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