| blob | 2e5a480231214d671294223701ab4659aa35344d |
1 .\" $NetBSD: namei.9,v 1.23 2009/09/27 17:23:53 dholland Exp $
2 .\"
3 .\" Copyright (c) 2001, 2005, 2006 The NetBSD Foundation, Inc.
4 .\" All rights reserved.
5 .\"
6 .\" This code is derived from software contributed to The NetBSD Foundation
7 .\" by Gregory McGarry.
8 .\"
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
11 .\" are met:
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\" notice, this list of conditions and the following disclaimer.
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\" notice, this list of conditions and the following disclaimer in the
16 .\" documentation and/or other materials provided with the distribution.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28 .\" POSSIBILITY OF SUCH DAMAGE.
29 .\"
30 .Dd September 27, 2009
31 .Dt NAMEI 9
32 .Os
33 .Sh NAME
34 .Nm namei ,
35 .Nm lookup_for_nfsd ,
36 .Nm lookup_for_nfsd_index ,
37 .Nm relookup ,
38 .Nm NDINIT ,
39 .Nm namei_simple_kernel ,
40 .Nm namei_simple_user
41 .Nd pathname lookup
42 .Sh SYNOPSIS
43 .In sys/namei.h
44 .In sys/uio.h
45 .In sys/vnode.h
46 .Ft int
47 .Fn namei "struct nameidata *ndp"
48 .Ft int
49 .Fn lookup_for_nfsd "struct nameidata *ndp" "struct vnode *startdir" \
50 "int neverfollow"
51 .Ft int
52 .Fn lookup_for_nfsd_index "struct nameidata *ndp"
53 .Ft int
54 .Fn relookup "struct vnode *dvp" "struct vnode **vpp" \
55 "struct componentname *cnp"
56 .Ft void
57 .Fn NDINIT "struct nameidata *ndp" "u_long op" "u_long flags" \
58 "enum uio_seg segflg" "const char *namep"
59 .Ft int
60 .Fn namei_simple_kernel "const char *path" "namei_simple_flags_t sflags" \
61 "struct vnode **ret"
62 .Ft int
63 .Fn namei_simple_user "const char *path" "namei_simple_flags_t sflags" \
64 "struct vnode **ret"
65 .Sh DESCRIPTION
66 The
67 .Nm
68 interface is used to convert pathnames to file system vnodes.
69 The
70 name of the interface is actually a contraction of the words
71 .Em name
72 and
73 .Em inode
74 for name-to-inode conversion, in the days before the
75 .Xr vfs 9
76 interface was implemented.
77 .Pp
78 Except for the simple forms, the arguments passed to the functions are
79 encapsulated in the
80 .Em nameidata
81 structure.
82 It has the following structure:
83 .Bd -literal
84 struct nameidata {
85 /*
86 * Arguments to namei/lookup.
87 */
88 const char *ni_dirp; /* pathname pointer */
89 enum uio_seg ni_segflg; /* location of pathname */
90 /*
91 * Arguments to lookup.
92 */
93 struct vnode *ni_startdir; /* starting directory */
94 struct vnode *ni_rootdir; /* logical root directory */
95 /*
96 * Results: returned from/manipulated by lookup
97 */
98 struct vnode *ni_vp; /* vnode of result */
99 struct vnode *ni_dvp; /* vnode of intermediate dir */
100 /*
101 * Shared between namei and lookup/commit routines.
102 */
103 size_t ni_pathlen; /* remaining chars in path */
104 const char *ni_next; /* next location in pathname */
105 u_long ni_loopcnt; /* count of symlinks encountered */
106 /*
107 * Lookup parameters
108 */
109 struct componentname {
110 /*
111 * Arguments to lookup.
112 */
113 u_long cn_nameiop; /* namei operation */
114 u_long cn_flags; /* flags to namei */
115 kauth_cred_t cn_cred; /* credentials */
116 /*
117 * Shared between lookup and commit routines.
118 */
119 char *cn_pnbuf; /* pathname buffer */
120 const char *cn_nameptr; /* pointer to looked up name */
121 long cn_namelen; /* length of looked up component */
122 u_long cn_hash; /* hash value of looked up name */
123 long cn_consume; /* chars to consume in lookup() */
124 } ni_cnd;
125 };
126 .Ed
127 .Pp
128 The
129 .Nm
130 interface accesses vnode operations by passing arguments in the
131 partially initialised
132 .Em componentname
133 structure
134 .Em ni_cnd .
135 This structure describes the subset of information from the nameidata
136 structure that is passed through to the vnode operations.
137 See
138 .Xr vnodeops 9
139 for more information.
140 The details of the componentname structure are not absolutely necessary
141 since the members are initialised by the helper macro
142 .Fn NDINIT .
143 It is useful to know the operations and flags as specified in
144 .Xr vnodeops 9 .
145 .Pp
146 The
147 .Nm
148 interface overloads
149 .Em ni_cnd.cn_flags
150 with some additional flags.
151 These flags should be specific to the
152 .Nm
153 interface and ignored by vnode operations.
154 However, due to the historic close relationship between the
155 .Nm
156 interface and the vnode operations, these flags are sometimes used
157 (and set) by vnode operations, particularly
158 .Fn VOP_LOOKUP .
159 The additional flags are:
160 .Pp
161 .Bl -tag -offset indent -width NOCROSSMOUNT -compact
162 .It Dv NOCROSSMOUNT
163 do not cross mount points
164 .It Dv RDONLY
165 lookup with read-only semantics
166 .It Dv HASBUF
167 caller has allocated pathname buffer
168 .Em ni_cnd.cn_pnbuf
169 .It Dv SAVENAME
170 save pathname buffer
171 .It Dv SAVESTART
172 save starting directory
173 .It Dv ISDOTDOT
174 current pathname component is ..
175 .It Dv MAKEENTRY
176 add entry to the name cache
177 .It Dv ISLASTCN
178 this is last component of pathname
179 .It Dv ISSYMLINK
180 symlink needs interpretation
181 .It Dv ISWHITEOUT
182 found whiteout
183 .It Dv DOWHITEOUT
184 do whiteouts
185 .It Dv REQUIREDIR
186 must be a directory
187 .It Dv CREATEDIR
188 trailing slashes are ok
189 .It Dv PARAMASK
190 mask of parameter descriptors
191 .El
192 .Pp
193 If the caller of
194 .Fn namei
195 sets the SAVENAME flag, then it must free the buffer.
196 If
197 .Fn VOP_LOOKUP
198 sets the flag, then the buffer must be freed by either the commit
199 routine or the
200 .Fn VOP_ABORT
201 routine.
202 The
203 .Dv SAVESTART
204 flag is set only by the callers of
205 .Fn namei .
206 It implies
207 .Dv SAVENAME
208 plus the addition of saving the parent directory
209 that contains the name in
210 .Em ni_startdir .
211 It allows repeated calls to
212 .Fn lookup
213 for the name being sought.
214 The caller is responsible for releasing the buffer and for invoking
215 .Fn vrele
216 on
217 .Em ni_startdir .
218 .Pp
219 All access to the
220 .Nm
221 interface must be in process context.
222 Pathname lookups cannot be done in interrupt context.
223 .Sh FUNCTIONS
224 .Bl -tag -width compact
225 .It Fn namei "ndp"
226 Convert a pathname into a pointer to a vnode.
227 The pathname is specified by
228 .Em ndp-\*[Gt]ni_dirp
229 and is of length
230 .Em ndp-\*[Gt]ni_pathlen .
231 The
232 .Em ndp-\*[Gt]segflg
233 flags defines whether the name in
234 .Em ndp-\*[Gt]ni_dirp
235 is an address in kernel space
236 .Pq Dv UIO_SYSSPACE
237 or an address in user space
238 .Pq Dv UIO_USERSPACE .
239 .Pp
240 The vnode for the pathname is returned in
241 .Em ndp-\*[Gt]ni_vp .
242 The parent directory is returned locked in
243 .Em ndp-\*[Gt]ni_dvp
244 iff
245 .Dv LOCKPARENT
246 is specified.
247 .Pp
248 If
249 .Em ndp-\*[Gt]ni_cnd.cn_flags
250 has the
251 .Dv FOLLOW
252 flag set then symbolic links are followed when they
253 occur at the end of the name translation process.
254 Symbolic links are always followed for all other pathname components
255 other than the last.
256 .Pp
257 Historically
258 .Nm
259 had a sub-function called
260 .Fn lookup .
261 This function processed a pathname until either running out of
262 material or encountering a symbolic link.
263 .Nm
264 worked by first setting up the start directory
265 .Em ndp-\*[Gt]ni_startdir
266 and then calling
267 .Fn lookup
268 repeatedly.
269 .Pp
270 The semantics of
271 .Nm
272 are altered by the operation specified by
273 .Em ndp-\*[Gt]ni_cnd.cn_nameiop .
274 When
275 .Dv CREATE ,
276 .Dv RENAME ,
277 or
278 .Dv DELETE
279 is specified, information usable in
280 creating, renaming, or deleting a directory entry may be calculated.
281 .Pp
282 If the target of the pathname exists and LOCKLEAF is set, the target
283 is returned locked in
284 .Em ndp-\*[Gt]ni_vp ,
285 otherwise it is returned unlocked.
286 .Pp
287 As of this writing the internal function
288 .Fn do_lookup
289 is comparable to the historic
290 .Fn lookup
291 but this code is slated for refactoring.
292 .It Fn lookup_for_nfsd "ndp" "startdir" "neverfollow"
293 This is a private entry point into
294 .Nm
295 used by the NFS server code.
296 It looks up a path starting from
297 .Fa startdir .
298 If
299 .Fa neverfollow
300 is set,
301 .Em any
302 symbolic link (not just at the end of the path) will cause an error.
303 Otherwise, it follows symlinks normally.
304 Its semantics are similar to a symlink-following loop around the historic
305 .Fn lookup
306 function described above.
307 It should not be used by new code.
308 .It Fn lookup_for_nfsd_index "ndp"
309 This is a (second) private entry point into
310 .Nm
311 used by the NFS server code.
312 Its semantics are similar to the historic
313 .Fn lookup
314 function described above.
315 It should not be used by new code.
316 .It Fn relookup "dvp" "vpp" "cnp"
317 Reacquire a path name component is a directory.
318 This is a quicker way to lookup a pathname component when the parent
319 directory is known.
320 The locked parent directory vnode is specified by
321 .Fa dvp
322 and the pathname component by
323 .Fa cnp .
324 The vnode of the pathname is returned in the address specified by
325 .Fa vpp .
326 .It Fn NDINIT "ndp" "op" "flags" "segflg" "namep"
327 Initialise a nameidata structure pointed to by
328 .Fa ndp
329 for use by the
330 .Nm
331 interface.
332 It saves having to deal with the componentname structure inside
333 .Fa ndp .
334 The operation and flags are specified by
335 .Fa op
336 and
337 .Fa flags
338 respectively.
339 These are the values to which
340 .Em ndp-\*[Gt]ni_cnd.cn_nameiop
341 and
342 .Em ndp-\*[Gt]ni_cnd.cn_flags
343 are respectively set.
344 The segment flags which defines whether the pathname is in kernel
345 address space or user address space is specified by
346 .Fa segflag .
347 The argument
348 .Fa namep
349 is a pointer to the pathname that
350 .Em ndp-\*[Gt]ni_dirp
351 is set to.
352 .Pp
353 This routine stores the credentials of the calling thread
354 .Va ( curlwp )
355 in
356 .Fa ndp .
357 In the rare case that another set of credentials is required for the
358 namei operation,
359 .Em ndp-\*[Gt]ni_cnd.cn_cred
360 must be set manually.
361 .It Fn namei_simple_kernel "path" "sflags" "ret"
362 Look up the path
363 .Fa path
364 and translate it to a vnode, returned in
365 .Fa ret .
366 The
367 .Fa path
368 argument must be a kernel
369 .Pq Dv UIO_SYSSPACE
370 pointer.
371 The
372 .Fa sflags
373 argument chooses the precise behavior.
374 It may be set to one of the following symbols:
375 .Bl -tag -offset indent -width NSM_NOFOLLOW_TRYEMULROOT -compact
376 .It Dv NSM_NOFOLLOW_NOEMULROOT
377 .It Dv NSM_NOFOLLOW_TRYEMULROOT
378 .It Dv NSM_FOLLOW_NOEMULROOT
379 .It Dv NSM_FOLLOW_TRYEMULROOT
380 .El
381 These select (or not) the
382 .Dv FOLLOW/NOFOLLOW
383 and
384 .Dv TRYEMULROOT
385 flags.
386 Other flags are not available through this interface, which is
387 nonetheless sufficient for more than half the
388 .Fn namei
389 usage in the kernel.
390 Note that the encoding of
391 .Fa sflags
392 has deliberately been arranged to be type-incompatible with anything
393 else.
394 This prevents various possible accidents while the
395 .Fn namei
396 interface is being rototilled.
397 .It Fn namei_simple_user "path" "sflags" "ret"
398 This function is the same as
399 .Fn namei_simple_kernel
400 except that the
401 .Fa path
402 argument shall be a user pointer
403 .Pq Dv UIO_USERSPACE
404 rather than a kernel pointer.
405 .El
406 .Sh CODE REFERENCES
407 This section describes places within the
408 .Nx
409 source tree where actual code implementing or using the name
410 lookup subsystem can be found.
411 All pathnames are relative to
412 .Pa /usr/src .
413 .Pp
414 The name lookup subsystem is implemented within the file
415 .Pa sys/kern/vfs_lookup.c .
416 .Sh SEE ALSO
417 .Xr intro 9 ,
418 .Xr namecache 9 ,
419 .Xr vfs 9 ,
420 .Xr vnode 9 ,
421 .Xr vnodeops 9
422 .Sh BUGS
423 It is unfortunate that much of the
424 .Nm
425 interface makes assumptions on the underlying vnode operations.
426 These assumptions are an artefact of the introduction of the vfs
427 interface to split a file system interface which was historically
428 designed as a tightly coupled module.