2 .\" Copyright (c) 1998, 1999 Eivind Eklund
3 .\" Copyright (c) 2003 Hiten M. Pandya
5 .\" All rights reserved.
7 .\" This program is free software.
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
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.
18 .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
19 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
20 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
21 .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
22 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
23 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
24 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
25 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
26 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
27 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30 .\" If you integrate this manpage in another OS, I'd appreciate a note
31 .\" - eivind@FreeBSD.org
42 .Nd pathname translation and lookup operations
48 .Fn namei "struct nameidata *ndp"
51 .Fa "struct nameidata *ndp" "u_long op" "u_long flags"
52 .Fa "enum uio_seg segflg" "const char *namep" "struct thread *td"
55 .Fn NDFREE "struct nameidata *ndp" "const uint flags"
59 facility allows the client to perform pathname translation and lookup
63 functions will increment the reference count for the vnode in question.
64 The reference count has to be decremented after use of the vnode, by
69 depending on whether the
71 flag was specified or not.
75 function is used to initialize
78 It takes the following arguments:
79 .Bl -tag -width ".Fa segflg"
82 .Vt "struct nameidata"
88 The following operations are valid:
89 .Dv LOOKUP , CREATE , DELETE ,
92 The latter three are just setup for those
100 Several of these can be effective at the same time.
102 UIO segment indicator.
103 This indicates if the name of the object is in userspace
105 or in the kernel address space
106 .Pq Dv UIO_SYSSPACE .
108 Pointer to the component's pathname buffer
109 (the file or directory name that will be looked up).
111 The thread context to use for
113 operations and locks.
115 .Sh NAMEI OPERATION FLAGS
118 function takes the following set of
119 .Dq "operation flags"
120 that influence its operation:
121 .Bl -tag -width ".Dv WANTPARENT"
123 Lock vnode on return.
124 This is a full lock of the vnode; the
127 to release the lock (or
129 which is equivalent to calling
137 function return the parent (directory) vnode,
139 in locked state, unless it is identical to
143 is not locked per se (but may be locked due to
145 If a lock is enforced, it should be released using
154 function to return the parent (directory) vnode in an unlocked state.
155 The parent vnode must be released separately by using
160 creating this entry in the namecache if it is not
164 will add entries to the name cache
165 if they are not already there.
169 will follow the symbolic link if the last part
170 of the path supplied is a symbolic link (i.e., it will return a vnode
171 for whatever the link points at, instead for the link itself).
174 .Fn vfs_object_create
175 for the returned vnode, even though it meets required criteria for VM support.
177 Do not follow symbolic links (pseudo).
178 This flag is not looked for by the actual code, which looks for
181 is used to indicate to the source code reader that symlinks
182 are intentionally not followed.
184 Do not free the pathname buffer at the end of the
186 invocation; instead, free it later in
188 so that the caller may access the pathname buffer.
189 See below for details.
191 Retain an additional reference to the parent directory; do not free
193 See below for details.
195 .Sh ALLOCATED ELEMENTS
198 structure is composed of the following fields:
199 .Bl -tag -width ".Va ni_cnd.cn_pnbuf"
201 In the normal case, this is either the current directory or the root.
202 It is the current directory if the name passed in does not start with
204 and we have not gone through any symlinks with an absolute path, and
207 In this case, it is only used by
210 considered valid after a call to
214 is set, this is set to the same as
223 .Dv NDF_NO_STARTDIR_RELE
226 Vnode pointer to directory of the object on which lookup is performed.
227 This is available on successful return if
238 .Dv NDF_NO_DVP_RELE , NDF_NO_DVP_PUT ,
240 .Dv NDF_NO_DVP_UNLOCK
241 (with the obvious effects).
243 Vnode pointer to the resulting object,
248 field of this vnode is incremented.
251 is set, it is also locked.
256 .Dv NDF_NO_VP_RELE , NDF_NO_VP_PUT ,
259 (with the obvious effects).
260 .It Va ni_cnd.cn_pnbuf
261 The pathname buffer contains the location of the file or directory
262 that will be used by the
267 zone allocation interface.
272 flag is set, then the pathname buffer is available
277 To only deallocate resources used by the pathname buffer,
278 .Va ni_cnd.cn_pnbuf ,
281 flag can be passed to the
284 To keep the pathname buffer intact,
287 flag can be passed to the
293 .It Pa src/sys/kern/vfs_lookup.c
304 This manual page was written by
305 .An Eivind Eklund Aq eivind@FreeBSD.org
306 and later significantly revised by
307 .An Hiten M. Pandya Aq hmp@FreeBSD.org .
311 flag does not always result in the parent vnode being locked.
312 This results in complications when the
315 In order to solve this for the cases where both
319 are used, it is necessary to resort to recursive locking.