2 .\" Copyright (c) 1998, 1999 Eivind Eklund
3 .\" Copyright (c) 2003 Hiten M. Pandya
4 .\" Copyright (c) 2005 Robert N. M. Watson
6 .\" All rights reserved.
8 .\" This program is free software.
10 .\" Redistribution and use in source and binary forms, with or without
11 .\" modification, are permitted provided that the following conditions
13 .\" 1. Redistributions of source code must retain the above copyright
14 .\" notice, this list of conditions and the following disclaimer.
15 .\" 2. Redistributions in binary form must reproduce the above copyright
16 .\" notice, this list of conditions and the following disclaimer in the
17 .\" documentation and/or other materials provided with the distribution.
19 .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
20 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
21 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
22 .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
23 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
24 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
25 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
26 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
28 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 .\" If you integrate this manpage in another OS, I'd appreciate a note
32 .\" - eivind@FreeBSD.org
36 .Dd September 21, 2005
44 .Nd pathname translation and lookup operations
50 .Fn namei "struct nameidata *ndp"
53 .Fa "struct nameidata *ndp" "u_long op" "u_long flags"
54 .Fa "enum uio_seg segflg" "const char *namep" "struct thread *td"
57 .Fn NDFREE "struct nameidata *ndp" "const uint flags"
59 .Fn NDHASGIANT "struct nameidata *ndp"
63 facility allows the client to perform pathname translation and lookup
67 functions will increment the reference count for the vnode in question.
68 The reference count has to be decremented after use of the vnode, by
73 depending on whether the
75 flag was specified or not.
80 will acquire it if the caller indicates it is
82 in which case the caller must later release
84 based on the results of
89 function is used to initialize
92 It takes the following arguments:
93 .Bl -tag -width ".Fa segflg"
96 .Vt "struct nameidata"
102 The following operations are valid:
103 .Dv LOOKUP , CREATE , DELETE ,
106 The latter three are just setup for those
107 effects; just calling
114 Several of these can be effective at the same time.
116 UIO segment indicator.
117 This indicates if the name of the object is in userspace
119 or in the kernel address space
120 .Pq Dv UIO_SYSSPACE .
122 Pointer to the component's pathname buffer
123 (the file or directory name that will be looked up).
125 The thread context to use for
127 operations and locks.
129 .Sh NAMEI OPERATION FLAGS
132 function takes the following set of
133 .Dq "operation flags"
134 that influence its operation:
135 .Bl -tag -width ".Dv WANTPARENT"
137 Lock vnode on return.
138 This is a full lock of the vnode; the
141 to release the lock (or
143 which is equivalent to calling
151 function return the parent (directory) vnode,
153 in locked state, unless it is identical to
157 is not locked per se (but may be locked due to
159 If a lock is enforced, it should be released using
168 function to return the parent (directory) vnode in an unlocked state.
169 The parent vnode must be released separately by using
174 will conditionally acquire
176 if it is required by a traversed file system.
177 MPSAFE callers should pass the results of
181 in order to conditionally release
187 creating this entry in the namecache if it is not
191 will add entries to the name cache
192 if they are not already there.
196 will follow the symbolic link if the last part
197 of the path supplied is a symbolic link (i.e., it will return a vnode
198 for whatever the link points at, instead for the link itself).
201 .Fn vfs_object_create
202 for the returned vnode, even though it meets required criteria for VM support.
204 Do not follow symbolic links (pseudo).
205 This flag is not looked for by the actual code, which looks for
208 is used to indicate to the source code reader that symlinks
209 are intentionally not followed.
211 Do not free the pathname buffer at the end of the
213 invocation; instead, free it later in
215 so that the caller may access the pathname buffer.
216 See below for details.
218 Retain an additional reference to the parent directory; do not free
220 See below for details.
222 .Sh ALLOCATED ELEMENTS
225 structure is composed of the following fields:
226 .Bl -tag -width ".Va ni_cnd.cn_pnbuf"
228 In the normal case, this is either the current directory or the root.
229 It is the current directory if the name passed in does not start with
231 and we have not gone through any symlinks with an absolute path, and
234 In this case, it is only used by
237 considered valid after a call to
241 is set, this is set to the same as
250 .Dv NDF_NO_STARTDIR_RELE
253 Vnode pointer to directory of the object on which lookup is performed.
254 This is available on successful return if
265 .Dv NDF_NO_DVP_RELE , NDF_NO_DVP_PUT ,
267 .Dv NDF_NO_DVP_UNLOCK
268 (with the obvious effects).
270 Vnode pointer to the resulting object,
275 field of this vnode is incremented.
278 is set, it is also locked.
283 .Dv NDF_NO_VP_RELE , NDF_NO_VP_PUT ,
286 (with the obvious effects).
287 .It Va ni_cnd.cn_pnbuf
288 The pathname buffer contains the location of the file or directory
289 that will be used by the
294 zone allocation interface.
299 flag is set, then the pathname buffer is available
304 To only deallocate resources used by the pathname buffer,
305 .Va ni_cnd.cn_pnbuf ,
308 flag can be passed to the
311 To keep the pathname buffer intact,
313 .Dv NDF_NO_FREE_PNBUF
314 flag can be passed to the
321 will return 0, otherwise it will return an error.
324 .It Pa src/sys/kern/vfs_lookup.c
332 A component of the specified pathname is not a directory when a directory is
334 .It Bq Er ENAMETOOLONG
335 A component of a pathname exceeded 255 characters,
336 or an entire pathname exceeded 1023 characters.
338 A component of the specified pathname does not exist,
339 or the pathname is an empty string.
341 An attempt is made to access a file in a way forbidden by its file access
344 Too many symbolic links were encountered in translating the pathname.
346 An attempt is made to open a directory with write mode specified.
348 An attempt is made to modify a file or directory on a read-only file system.
354 .Xr VFS_UNLOCK_GIANT 9 ,
360 This manual page was written by
361 .An Eivind Eklund Aq eivind@FreeBSD.org
362 and later significantly revised by
363 .An Hiten M. Pandya Aq hmp@FreeBSD.org .
367 flag does not always result in the parent vnode being locked.
368 This results in complications when the
371 In order to solve this for the cases where both
375 are used, it is necessary to resort to recursive locking.
377 Non-MPSAFE file systems exist, requiring callers to conditionally unlock