xref: /dragonfly/share/man/man9/nlookup.9 (revision 9f3fc534) 
1.\"
2.\" Copyright (c) 2005 The DragonFly Project.  All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\"
8.\" 1. Redistributions of source code must retain the above copyright
9.\"    notice, this list of conditions and the following disclaimer.
10.\" 2. Redistributions in binary form must reproduce the above copyright
11.\"    notice, this list of conditions and the following disclaimer in
12.\"    the documentation and/or other materials provided with the
13.\"    distribution.
14.\" 3. Neither the name of The DragonFly Project nor the names of its
15.\"    contributors may be used to endorse or promote products derived
16.\"    from this software without specific, prior written permission.
17.\"
18.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
20.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
21.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
22.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
23.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
24.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
25.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
26.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
27.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
28.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29.\" SUCH DAMAGE.
30.\"
31.\" $DragonFly: src/share/man/man9/nlookup.9,v 1.11 2008/02/09 09:45:03 swildner Exp $
32.\"
33.Dd May 26, 2009
34.Os
35.Dt NLOOKUP 9
36.Sh NAME
37.Nm nlookup ,
38.Nm nlookup_init ,
39.Nm nlookup_init_raw ,
40.Nm nlookup_set_cred ,
41.Nm nlookup_zero ,
42.Nm nlookup_done ,
43.Nm nlookup_simple ,
44.Nm nlookup_mp ,
45.Nm nreadsymlink ,
46.Nm naccess ,
47.Nm naccess_va
48.Nd namecache API
49.Sh SYNOPSIS
50.In sys/types.h
51.In sys/nlookup.h
52.Ft int
53.Fn nlookup "struct nlookupdata *nd"
54.Ft int
55.Fn nlookup_init "struct nlookupdata *nd" "const char *path" "enum uio_seg seg" "int flags"
56.Ft int
57.Fn nlookup_init_raw "struct nlookupdata *nd" "const char *path" "enum uio_seg seg" "int flags" "struct ucred *cred" "struct namecache *ncstart"
58.Ft void
59.Fn nlookup_set_cred "struct nlookupdata *nd" "struct ucred *cred"
60.Ft void
61.Fn nlookup_zero "struct nlookupdata *nd"
62.Ft void
63.Fn nlookup_done "struct nlookupdata *nd"
64.Ft "struct namecache *"
65.Fn nlookup_simple "const char *str" "enum uio_seg seg" "int niflags" "int *error"
66.Ft int
67.Fn nlookup_mp "struct mount *mp" "struct namecache **ncpp"
68.Ft int
69.Fn nreadsymlink "struct nlookupdata *nd" "struct namecache *ncp" "struct nlcomponent *nlc"
70.Ft int
71.Fn naccess "struct namecache *ncp" "int vmode" "struct ucred *cred"
72.Ft int
73.Fn naccess_va "struct vattr *va" "int vmode" "struct ucred *cred"
74.Sh DESCRIPTION
75.Fn nlookup
76does a generic namecache lookup.
77Note that the passed
78.Fa "struct nlookupdata"
79is not
80.Fn nlookup_done Ap d
81on return, even if an error occurs.
82If no error occurs the returned nl_ncp
83is always referenced and locked, otherwise it may or may not be.
84Intermediate directory elements, including the current directory,
85require execute (search) permission.
86.Fn nlookup
87does not examine the access permissions on the returned element.
88If
89.Dv NLC_CREATE
90or
91.Dv NLC_DELETE
92is set the last directory must allow
93node creation
94.Po
95.Dv VCREATE Ns / Ns Dv VDELETE
96.Pc ,
97and an error code of 0
98will be returned for a non-existent target.
99Otherwise a non-existent target will cause
100.Er ENOENT
101to be returned.
102.Pp
103.Fn nlookup_init
104initializes a
105.Fa "struct nlookupdata" ,
106and does an early error
107return for copyin faults or a degenerate empty string (which is
108not allowed).
109The first process proc0's
110credentials are used if the calling
111thread is not associated with a process context.
112.Pp
113.Fn nlookup_init_raw
114works similarly to
115.Fn nlookup_init
116but does not assume a process context.
117rootncp is always chosen for the root directory and the
118.Fa cred
119and starting directory are supplied in the arguments.
120.Pp
121.Fn nlookup_set_cred
122sets a different credential; this credential will be used by
123future operations performed on nd.nl_open_vp
124and the
125.Fa nlookupdata
126structure.
127.Pp
128.Fn nlookup_zero
129zeroes a given
130.Fa "struct nlookupdata" .
131.Pp
132.Fn nlookup_done
133cleans up an
134.Fa nlookupdata
135structure after we are through with
136it.
137This function may be called on any nlookupdata structure
138initialized with
139.Fn nlookup_init .
140Calling
141.Fn nlookup_done
142is mandatory in all cases except where
143.Fn nlookup_init
144returns an error, even if as a consumer you believe you
145have taken all dynamic elements out of the
146.Fa nlookupdata
147structure.
148.Pp
149.Fn nlookup_simple
150is a simple all-in-one
151.Fn nlookup .
152It returns a locked namecache structure or NULL if an error
153occurred.
154Note that the returned ncp
155is not checked for permissions,
156though
157.Dv VEXEC
158is checked on the directory path leading up to
159the result.
160The caller must call
161.Fn naccess
162to check the permissions of the returned leaf.
163.Pp
164.Fn nlookup_mp
165is used to resolve a mount point's glue ncp.
166It creates the illusion of continuity in the namecache tree
167by connecting the ncp related to the vnode under the mount
168to the ncp related to the mount's root vnode.
169If no error occurred a locked, ref'd ncp is stored in
170.Fa *ncpp .
171.Pp
172.Fn nreadsymlink
173reads the contents of a symlink, allocates a path buffer out
174of the namei_zone and initialize the supplied nlcomponent
175with the result.
176If an error occurs no buffer will be allocated or returned
177in the nlc.
178.Pp
179.Fn naccess
180generally checks the V* access bits from
181.In sys/vnode.h .
182All specified bits must pass for this function to return 0.
183If
184.Dv VCREATE
185is specified and the target ncp represents a
186non-existent file or dir, or if
187.Dv VDELETE
188is specified and the
189target exists, the parent directory is checked for
190.Dv VWRITE .
191If
192.Dv VEXCL
193is specified and the target ncp represents a positive
194hit, an error is returned.
195If
196.Dv VCREATE
197is not specified and the target does not exist
198(negative hit),
199.Er ENOENT
200is returned.
201Note that
202.Fn nlookup
203does not (and should not) return
204.Er ENOENT
205for non-existent leafs.
206The passed ncp may or may not be locked.
207The caller should use a locked ncp on leaf lookups, especially
208for
209.Dv VCREATE ,
210.Dv VDELETE ,
211and
212.Dv VEXCL
213checks.
214.Pp
215.Fn naccess_va
216checks the requested access against the given
217.Fa vattr
218using
219.Fa cred .
220.Sh FILES
221.Pa sys/kern/vfs_nlookup.c
222.Sh SEE ALSO
223.Xr VFS 9 ,
224.Xr vnode 9
225.Sh AUTHORS
226This man page was written by
227.An Sascha Wildner .
228