xref: /freebsd/share/man/man9/namei.9 (revision c98323078dede7579020518ec84cdcb478e5c142)
1.\"
2.\" Copyright (c) 1998, 1999 Eivind Eklund
3.\" Copyright (c) 2003 Hiten M. Pandya
4.\"
5.\" All rights reserved.
6.\"
7.\" This program is free software.
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 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.
28.\"
29.\"
30.\" If you integrate this manpage in another OS, I'd appreciate a note
31.\"	- eivind@FreeBSD.org
32.\"
33.\" $FreeBSD$
34.\"
35.Dd May 27, 2003
36.Os
37.Dt NAMEI 9
38.Sh NAME
39.Nm namei ,
40.Nm NDINIT ,
41.Nm NDFREE
42.Nd pathname translation and lookup operations
43.Sh SYNOPSIS
44.In sys/param.h
45.In sys/proc.h
46.In sys/namei.h
47.Ft int
48.Fn namei "struct nameidata *ndp"
49.Ft void
50.Fo NDINIT
51.Fa "struct nameidata *ndp" "u_long op" "u_long flags"
52.Fa "enum uio_seg segflg" "const char *namep" "struct thread *td"
53.Fc
54.Ft void
55.Fn NDFREE "struct nameidata *ndp" "const uint flags"
56.Sh DESCRIPTION
57The
58.Nm
59facility allows the client to perform pathname translation and lookup
60operations.
61The
62.Nm
63functions will increment the reference count for the vnode in question.
64The reference count has to be decremented after use of the vnode, by
65using either
66.Xr vrele 9
67or
68.Xr vput 9 ,
69depending on whether the
70.Dv LOCKLEAF
71flag was specified or not.
72.Pp
73The
74.Fn NDINIT
75function is used to initialize
76.Nm
77components.
78It takes the following arguments:
79.Bl -tag -width ".Fa segflg"
80.It Fa ndp
81The
82.Vt "struct nameidata"
83to initialize.
84.It Fa op
85The operation which
86.Fn namei
87will perform.
88The following operations are valid:
89.Dv LOOKUP , CREATE , DELETE ,
90and
91.Dv RENAME .
92The latter three are just setup for those
93effects; just calling
94.Fn namei
95will not result in
96.Fn VOP_RENAME
97being called.
98.It Fa flags
99Operation flags.
100Several of these can be effective at the same time.
101.It Fa segflg
102UIO segment indicator.
103This indicates if the name of the object is in userspace
104.Pq Dv UIO_USERSPACE
105or in the kernel address space
106.Pq Dv UIO_SYSSPACE .
107.It Fa namep
108Pointer to the component's pathname buffer
109(the file or directory name that will be looked up).
110.It Fa td
111The thread context to use for
112.Nm
113operations and locks.
114.El
115.Sh NAMEI OPERATION FLAGS
116The
117.Fn namei
118function takes the following set of
119.Dq "operation flags"
120that influence its operation:
121.Bl -tag -width ".Dv WANTPARENT"
122.It Dv LOCKLEAF
123Lock vnode on return.
124This is a full lock of the vnode; the
125.Xr VOP_UNLOCK 9
126should be used
127to release the lock (or
128.Xr vput 9
129which is equivalent to calling
130.Xr VOP_UNLOCK 9
131followed by
132.Xr vrele 9 ,
133all in one).
134.It Dv LOCKPARENT
135This flag lets the
136.Fn namei
137function return the parent (directory) vnode,
138.Va ni_dvp
139in locked state, unless it is identical to
140.Va ni_vp ,
141in which case
142.Va ni_dvp
143is not locked per se (but may be locked due to
144.Dv LOCKLEAF ) .
145If a lock is enforced, it should be released using
146.Xr vput 9
147or
148.Xr VOP_UNLOCK 9
149and
150.Xr vrele 9 .
151.It Dv WANTPARENT
152This flag allows the
153.Fn namei
154function to return the parent (directory) vnode in an unlocked state.
155The parent vnode must be released separately by using
156.Xr vrele 9 .
157.It Dv NOCACHE
158Avoid
159.Fn namei
160creating this entry in the namecache if it is not
161already present.
162Normally,
163.Fn namei
164will add entries to the name cache
165if they are not already there.
166.It Dv FOLLOW
167With this flag,
168.Fn namei
169will follow the symbolic link if the last part
170of the path supplied is a symbolic link (i.e., it will return a vnode
171for whatever the link points at, instead for the link itself).
172.It Dv NOOBJ
173Do not call
174.Fn vfs_object_create
175for the returned vnode, even though it meets required criteria for VM support.
176.It Dv NOFOLLOW
177Do not follow symbolic links (pseudo).
178This flag is not looked for by the actual code, which looks for
179.Dv FOLLOW .
180.Dv NOFOLLOW
181is used to indicate to the source code reader that symlinks
182are intentionally not followed.
183.It Dv SAVENAME
184Do not free the pathname buffer at the end of the
185.Fn namei
186invocation; instead, free it later in
187.Fn NDFREE
188so that the caller may access the pathname buffer.
189See below for details.
190.It Dv SAVESTART
191Retain an additional reference to the parent directory; do not free
192the pathname buffer.
193See below for details.
194.El
195.Sh ALLOCATED ELEMENTS
196The
197.Vt nameidata
198structure is composed of the following fields:
199.Bl -tag -width ".Va ni_cnd.cn_pnbuf"
200.It Va ni_startdir
201In the normal case, this is either the current directory or the root.
202It is the current directory if the name passed in does not start with
203.Ql /
204and we have not gone through any symlinks with an absolute path, and
205the root otherwise.
206.Pp
207In this case, it is only used by
208.Fn lookup ,
209and should not be
210considered valid after a call to
211.Fn namei .
212If
213.Dv SAVESTART
214is set, this is set to the same as
215.Va ni_dvp ,
216with an extra
217.Xr vref 9 .
218To block
219.Fn NDFREE
220from releasing
221.Va ni_startdir ,
222the
223.Dv NDF_NO_STARTDIR_RELE
224can be set.
225.It Va ni_dvp
226Vnode pointer to directory of the object on which lookup is performed.
227This is available on successful return if
228.Dv LOCKPARENT
229or
230.Dv WANTPARENT
231is set.
232It is locked if
233.Dv LOCKPARENT
234is set.
235Freeing this in
236.Fn NDFREE
237can be inhibited by
238.Dv NDF_NO_DVP_RELE , NDF_NO_DVP_PUT ,
239or
240.Dv NDF_NO_DVP_UNLOCK
241(with the obvious effects).
242.It Va ni_vp
243Vnode pointer to the resulting object,
244.Dv NULL
245otherwise.
246The
247.Va v_usecount
248field of this vnode is incremented.
249If
250.Dv LOCKLEAF
251is set, it is also locked.
252.Pp
253Freeing this in
254.Fn NDFREE
255can be inhibited by
256.Dv NDF_NO_VP_RELE , NDF_NO_VP_PUT ,
257or
258.Dv NDF_NO_VP_UNLOCK
259(with the obvious effects).
260.It Va ni_cnd.cn_pnbuf
261The pathname buffer contains the location of the file or directory
262that will be used by the
263.Nm
264operations.
265It is managed by the
266.Xr uma 9
267zone allocation interface.
268If the
269.Dv SAVESTART
270or
271.Dv SAVENAME
272flag is set, then the pathname buffer is available
273after calling the
274.Fn namei
275function.
276.Pp
277To only deallocate resources used by the pathname buffer,
278.Va ni_cnd.cn_pnbuf ,
279then
280.Dv NDF_ONLY_PNBUF
281flag can be passed to the
282.Fn NDFREE
283function.
284To keep the pathname buffer intact,
285the
286.Dv ND_NO_FREE_PNBUF
287flag can be passed to the
288.Fn NDFREE
289function.
290.El
291.Sh FILES
292.Bl -tag
293.It Pa src/sys/kern/vfs_lookup.c
294.El
295.Sh SEE ALSO
296.Xr uio 9 ,
297.Xr uma 9 ,
298.Xr VFS 9 ,
299.Xr vnode 9 ,
300.Xr vput 9 ,
301.Xr vref 9
302.Sh AUTHORS
303.An -nosplit
304This manual page was written by
305.An Eivind Eklund Aq eivind@FreeBSD.org
306and later significantly revised by
307.An Hiten M. Pandya Aq hmp@FreeBSD.org .
308.Sh BUGS
309The
310.Dv LOCKPARENT
311flag does not always result in the parent vnode being locked.
312This results in complications when the
313.Dv LOCKPARENT
314is used.
315In order to solve this for the cases where both
316.Dv LOCKPARENT
317and
318.Dv LOCKLEAF
319are used, it is necessary to resort to recursive locking.
320