xref: /freebsd/share/man/man9/namei.9 (revision 22bb70a6b3bb7799276ab480e40665b7d6e4ce25)
1c78f3f0dSEivind Eklund.\"
29a8fa3c1SEivind Eklund.\" Copyright (c) 1998, 1999 Eivind Eklund
309f84dd1SRuslan Ermilov.\" Copyright (c) 2003 Hiten M. Pandya
46b8a3687SRobert Watson.\" Copyright (c) 2005 Robert N. M. Watson
5c78f3f0dSEivind Eklund.\"
6c78f3f0dSEivind Eklund.\" All rights reserved.
7c78f3f0dSEivind Eklund.\"
8c78f3f0dSEivind Eklund.\" This program is free software.
9c78f3f0dSEivind Eklund.\"
10c78f3f0dSEivind Eklund.\" Redistribution and use in source and binary forms, with or without
11c78f3f0dSEivind Eklund.\" modification, are permitted provided that the following conditions
12c78f3f0dSEivind Eklund.\" are met:
13c78f3f0dSEivind Eklund.\" 1. Redistributions of source code must retain the above copyright
14c78f3f0dSEivind Eklund.\"    notice, this list of conditions and the following disclaimer.
15c78f3f0dSEivind Eklund.\" 2. Redistributions in binary form must reproduce the above copyright
16c78f3f0dSEivind Eklund.\"    notice, this list of conditions and the following disclaimer in the
17c78f3f0dSEivind Eklund.\"    documentation and/or other materials provided with the distribution.
18c78f3f0dSEivind Eklund.\"
19c78f3f0dSEivind Eklund.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
20c78f3f0dSEivind Eklund.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
21c78f3f0dSEivind Eklund.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
22c78f3f0dSEivind Eklund.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
23c78f3f0dSEivind Eklund.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
24c78f3f0dSEivind Eklund.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
25c78f3f0dSEivind Eklund.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
26c78f3f0dSEivind Eklund.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27c78f3f0dSEivind Eklund.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
28c78f3f0dSEivind Eklund.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29c78f3f0dSEivind Eklund.\"
30c78f3f0dSEivind Eklund.\"
31c78f3f0dSEivind Eklund.\" If you integrate this manpage in another OS, I'd appreciate a note
32e87b9f28SJeroen Ruigrok van der Werven.\"	- eivind@FreeBSD.org
33c78f3f0dSEivind Eklund.\"
34*22bb70a6SAlan Somers.Dd December 17, 2024
35def37e7cSMike Pritchard.Dt NAMEI 9
36aa12cea2SUlrich Spörlein.Os
37c78f3f0dSEivind Eklund.Sh NAME
38c78f3f0dSEivind Eklund.Nm namei ,
3915c3fb05SHiten Pandya.Nm NDINIT ,
4032068667SChristian Brueffer.Nm NDFREE
4115c3fb05SHiten Pandya.Nd pathname translation and lookup operations
42c78f3f0dSEivind Eklund.Sh SYNOPSIS
43f16b3c0dSChad David.In sys/param.h
4494fa222aSJohn Baldwin.In sys/fcntl.h
4532eef9aeSRuslan Ermilov.In sys/namei.h
46c78f3f0dSEivind Eklund.Ft int
47c78f3f0dSEivind Eklund.Fn namei "struct nameidata *ndp"
48c78f3f0dSEivind Eklund.Ft void
4909f84dd1SRuslan Ermilov.Fo NDINIT
5009f84dd1SRuslan Ermilov.Fa "struct nameidata *ndp" "u_long op" "u_long flags"
5109f84dd1SRuslan Ermilov.Fa "enum uio_seg segflg" "const char *namep" "struct thread *td"
5209f84dd1SRuslan Ermilov.Fc
53eac993bcSBruce Evans.Ft void
5415c3fb05SHiten Pandya.Fn NDFREE "struct nameidata *ndp" "const uint flags"
55c78f3f0dSEivind Eklund.Sh DESCRIPTION
5660dca836SPhilippe CharnierThe
5715c3fb05SHiten Pandya.Nm
5815c3fb05SHiten Pandyafacility allows the client to perform pathname translation and lookup
5915c3fb05SHiten Pandyaoperations.
6015c3fb05SHiten PandyaThe
6115c3fb05SHiten Pandya.Nm
6215c3fb05SHiten Pandyafunctions will increment the reference count for the vnode in question.
6315c3fb05SHiten PandyaThe reference count has to be decremented after use of the vnode, by
6415c3fb05SHiten Pandyausing either
65c78f3f0dSEivind Eklund.Xr vrele 9
66c78f3f0dSEivind Eklundor
67c78f3f0dSEivind Eklund.Xr vput 9 ,
6809f84dd1SRuslan Ermilovdepending on whether the
6915c3fb05SHiten Pandya.Dv LOCKLEAF
7009f84dd1SRuslan Ermilovflag was specified or not.
71c78f3f0dSEivind Eklund.Pp
7215c3fb05SHiten PandyaThe
7315c3fb05SHiten Pandya.Fn NDINIT
7415c3fb05SHiten Pandyafunction is used to initialize
7515c3fb05SHiten Pandya.Nm
7615c3fb05SHiten Pandyacomponents.
77c78f3f0dSEivind EklundIt takes the following arguments:
7809f84dd1SRuslan Ermilov.Bl -tag -width ".Fa segflg"
7915c3fb05SHiten Pandya.It Fa ndp
8015c3fb05SHiten PandyaThe
8115c3fb05SHiten Pandya.Vt "struct nameidata"
8215c3fb05SHiten Pandyato initialize.
8315c3fb05SHiten Pandya.It Fa op
8415c3fb05SHiten PandyaThe operation which
85c78f3f0dSEivind Eklund.Fn namei
8615c3fb05SHiten Pandyawill perform.
8715c3fb05SHiten PandyaThe following operations are valid:
8809f84dd1SRuslan Ermilov.Dv LOOKUP , CREATE , DELETE ,
89c78f3f0dSEivind Eklundand
90c78f3f0dSEivind Eklund.Dv RENAME .
91c78f3f0dSEivind EklundThe latter three are just setup for those
92c78f3f0dSEivind Eklundeffects; just calling
93c78f3f0dSEivind Eklund.Fn namei
94c78f3f0dSEivind Eklundwill not result in
95c78f3f0dSEivind Eklund.Fn VOP_RENAME
96c78f3f0dSEivind Eklundbeing called.
9715c3fb05SHiten Pandya.It Fa flags
9815c3fb05SHiten PandyaOperation flags.
9915c3fb05SHiten PandyaSeveral of these can be effective at the same time.
10015c3fb05SHiten Pandya.It Fa segflg
10115c3fb05SHiten PandyaUIO segment indicator.
10215c3fb05SHiten PandyaThis indicates if the name of the object is in userspace
10315c3fb05SHiten Pandya.Pq Dv UIO_USERSPACE
10415c3fb05SHiten Pandyaor in the kernel address space
10515c3fb05SHiten Pandya.Pq Dv UIO_SYSSPACE .
10615c3fb05SHiten Pandya.It Fa namep
10715c3fb05SHiten PandyaPointer to the component's pathname buffer
10809f84dd1SRuslan Ermilov(the file or directory name that will be looked up).
10915c3fb05SHiten Pandya.It Fa td
11015c3fb05SHiten PandyaThe thread context to use for
11115c3fb05SHiten Pandya.Nm
11215c3fb05SHiten Pandyaoperations and locks.
113c78f3f0dSEivind Eklund.El
114c78f3f0dSEivind Eklund.Sh NAMEI OPERATION FLAGS
11560dca836SPhilippe CharnierThe
116c78f3f0dSEivind Eklund.Fn namei
11715c3fb05SHiten Pandyafunction takes the following set of
11809f84dd1SRuslan Ermilov.Dq "operation flags"
11915c3fb05SHiten Pandyathat influence its operation:
12009f84dd1SRuslan Ermilov.Bl -tag -width ".Dv WANTPARENT"
121c78f3f0dSEivind Eklund.It Dv LOCKLEAF
122f0c619b2SBryan DreweryLock vnode on return with
123f0c619b2SBryan Drewery.Dv LK_EXCLUSIVE
124f0c619b2SBryan Dreweryunless
125f0c619b2SBryan Drewery.Dv LOCKSHARED
126f0c619b2SBryan Dreweryis also set.
127c78f3f0dSEivind Eklund.Xr VOP_UNLOCK 9
12809f84dd1SRuslan Ermilovshould be used
12909f84dd1SRuslan Ermilovto release the lock (or
130c78f3f0dSEivind Eklund.Xr vput 9
13109f84dd1SRuslan Ermilovwhich is equivalent to calling
13209f84dd1SRuslan Ermilov.Xr VOP_UNLOCK 9
13309f84dd1SRuslan Ermilovfollowed by
134c78f3f0dSEivind Eklund.Xr vrele 9 ,
135c78f3f0dSEivind Eklundall in one).
136c78f3f0dSEivind Eklund.It Dv LOCKPARENT
13715c3fb05SHiten PandyaThis flag lets the
138c78f3f0dSEivind Eklund.Fn namei
13915c3fb05SHiten Pandyafunction return the parent (directory) vnode,
14015c3fb05SHiten Pandya.Va ni_dvp
14115c3fb05SHiten Pandyain locked state, unless it is identical to
14215c3fb05SHiten Pandya.Va ni_vp ,
14315c3fb05SHiten Pandyain which case
14415c3fb05SHiten Pandya.Va ni_dvp
14515c3fb05SHiten Pandyais not locked per se (but may be locked due to
14615c3fb05SHiten Pandya.Dv LOCKLEAF ) .
14715c3fb05SHiten PandyaIf a lock is enforced, it should be released using
148c78f3f0dSEivind Eklund.Xr vput 9
149c78f3f0dSEivind Eklundor
150c78f3f0dSEivind Eklund.Xr VOP_UNLOCK 9
151c78f3f0dSEivind Eklundand
15215c3fb05SHiten Pandya.Xr vrele 9 .
153f0c619b2SBryan Drewery.It Dv LOCKSHARED
154f0c619b2SBryan DreweryLock vnode on return with
155*22bb70a6SAlan Somers.Dv LK_SHARED ,
156*22bb70a6SAlan Somersif permitted by the file system that owns the vnode.
157*22bb70a6SAlan SomersThe file system must explicitly permit this by setting
158*22bb70a6SAlan Somers.Dv MNTK_LOOKUP_SHARED
159*22bb70a6SAlan Somersin
160*22bb70a6SAlan Somers.Dv mp->mnt_kern_flag
161*22bb70a6SAlan Somersduring mount and by calling
162*22bb70a6SAlan Somers.Fn VN_LOCK_ASHARE
163*22bb70a6SAlan Somerswhen allocating the vnode.
164*22bb70a6SAlan SomersIf
165*22bb70a6SAlan Somers.Dv LOCKLEAF
166*22bb70a6SAlan Somersis specified but shared locking is not permitted, then the vnode will be
167*22bb70a6SAlan Somersreturned with
168*22bb70a6SAlan Somers.Dv LK_EXCLUSIVE .
169f0c619b2SBryan Drewery.Xr VOP_UNLOCK 9
170f0c619b2SBryan Dreweryshould be used
171f0c619b2SBryan Dreweryto release the lock (or
172f0c619b2SBryan Drewery.Xr vput 9
173f0c619b2SBryan Drewerywhich is equivalent to calling
174f0c619b2SBryan Drewery.Xr VOP_UNLOCK 9
175f0c619b2SBryan Dreweryfollowed by
176f0c619b2SBryan Drewery.Xr vrele 9 ,
177f0c619b2SBryan Dreweryall in one).
178c78f3f0dSEivind Eklund.It Dv WANTPARENT
17915c3fb05SHiten PandyaThis flag allows the
180c78f3f0dSEivind Eklund.Fn namei
18115c3fb05SHiten Pandyafunction to return the parent (directory) vnode in an unlocked state.
18215c3fb05SHiten PandyaThe parent vnode must be released separately by using
18315c3fb05SHiten Pandya.Xr vrele 9 .
184c78f3f0dSEivind Eklund.It Dv NOCACHE
185c78f3f0dSEivind EklundAvoid
186c78f3f0dSEivind Eklund.Fn namei
187c78f3f0dSEivind Eklundcreating this entry in the namecache if it is not
18809f84dd1SRuslan Ermilovalready present.
18909f84dd1SRuslan ErmilovNormally,
190c78f3f0dSEivind Eklund.Fn namei
191c78f3f0dSEivind Eklundwill add entries to the name cache
19209f84dd1SRuslan Ermilovif they are not already there.
193c78f3f0dSEivind Eklund.It Dv FOLLOW
194c78f3f0dSEivind EklundWith this flag,
195c78f3f0dSEivind Eklund.Fn namei
196c78f3f0dSEivind Eklundwill follow the symbolic link if the last part
197c78f3f0dSEivind Eklundof the path supplied is a symbolic link (i.e., it will return a vnode
198c78f3f0dSEivind Eklundfor whatever the link points at, instead for the link itself).
199c78f3f0dSEivind Eklund.It Dv NOFOLLOW
2009a8fa3c1SEivind EklundDo not follow symbolic links (pseudo).
2019a8fa3c1SEivind EklundThis flag is not looked for by the actual code, which looks for
20215c3fb05SHiten Pandya.Dv FOLLOW .
20315c3fb05SHiten Pandya.Dv NOFOLLOW
20415c3fb05SHiten Pandyais used to indicate to the source code reader that symlinks
2059a8fa3c1SEivind Eklundare intentionally not followed.
206060c42c3SRobert Watson.It Dv SAVENAME
20715c3fb05SHiten PandyaDo not free the pathname buffer at the end of the
208060c42c3SRobert Watson.Fn namei
20909f84dd1SRuslan Ermilovinvocation; instead, free it later in
210060c42c3SRobert Watson.Fn NDFREE
21115c3fb05SHiten Pandyaso that the caller may access the pathname buffer.
212060c42c3SRobert WatsonSee below for details.
213060c42c3SRobert Watson.It Dv SAVESTART
214060c42c3SRobert WatsonRetain an additional reference to the parent directory; do not free
21515c3fb05SHiten Pandyathe pathname buffer.
216060c42c3SRobert WatsonSee below for details.
217c78f3f0dSEivind Eklund.El
2189a8fa3c1SEivind Eklund.Sh ALLOCATED ELEMENTS
21915c3fb05SHiten PandyaThe
22015c3fb05SHiten Pandya.Vt nameidata
22115c3fb05SHiten Pandyastructure is composed of the following fields:
22209f84dd1SRuslan Ermilov.Bl -tag -width ".Va ni_cnd.cn_pnbuf"
22315c3fb05SHiten Pandya.It Va ni_startdir
2249a8fa3c1SEivind EklundIn the normal case, this is either the current directory or the root.
22509f84dd1SRuslan ErmilovIt is the current directory if the name passed in does not start with
22609f84dd1SRuslan Ermilov.Ql /
2279a8fa3c1SEivind Eklundand we have not gone through any symlinks with an absolute path, and
2289a8fa3c1SEivind Eklundthe root otherwise.
2293136363fSRuslan Ermilov.Pp
2309e28aca5SDima DorfmanIn this case, it is only used by
23170c00442SMateusz Guzik.Fn vfs_lookup ,
2329e28aca5SDima Dorfmanand should not be
2339e28aca5SDima Dorfmanconsidered valid after a call to
2349e28aca5SDima Dorfman.Fn namei .
23515c3fb05SHiten Pandya.It Va ni_dvp
23615c3fb05SHiten PandyaVnode pointer to directory of the object on which lookup is performed.
23715c3fb05SHiten PandyaThis is available on successful return if
23815c3fb05SHiten Pandya.Dv LOCKPARENT
23915c3fb05SHiten Pandyaor
24015c3fb05SHiten Pandya.Dv WANTPARENT
24115c3fb05SHiten Pandyais set.
24215c3fb05SHiten PandyaIt is locked if
24315c3fb05SHiten Pandya.Dv LOCKPARENT
24415c3fb05SHiten Pandyais set.
24515c3fb05SHiten Pandya.It Va ni_vp
24615c3fb05SHiten PandyaVnode pointer to the resulting object,
24715c3fb05SHiten Pandya.Dv NULL
24815c3fb05SHiten Pandyaotherwise.
24915c3fb05SHiten PandyaThe
25015c3fb05SHiten Pandya.Va v_usecount
25115c3fb05SHiten Pandyafield of this vnode is incremented.
25215c3fb05SHiten PandyaIf
25315c3fb05SHiten Pandya.Dv LOCKLEAF
25415c3fb05SHiten Pandyais set, it is also locked.
2553136363fSRuslan Ermilov.Pp
25615c3fb05SHiten Pandya.It Va ni_cnd.cn_pnbuf
25715c3fb05SHiten PandyaThe pathname buffer contains the location of the file or directory
25815c3fb05SHiten Pandyathat will be used by the
25915c3fb05SHiten Pandya.Nm
26015c3fb05SHiten Pandyaoperations.
26115c3fb05SHiten PandyaIt is managed by the
26215c3fb05SHiten Pandya.Xr uma 9
26315c3fb05SHiten Pandyazone allocation interface.
2643136363fSRuslan Ermilov.El
26594fa222aSJohn Baldwin.Sh RETURN VALUES
26694fa222aSJohn BaldwinIf successful,
26794fa222aSJohn Baldwin.Fn namei
26894fa222aSJohn Baldwinwill return 0, otherwise it will return an error.
2690b31f1f7SUlrich Spörlein.Sh FILES
270e5254989SGlen Barber.Bl -tag -width Pa
2710b31f1f7SUlrich Spörlein.It Pa src/sys/kern/vfs_lookup.c
2720b31f1f7SUlrich Spörlein.El
27394fa222aSJohn Baldwin.Sh ERRORS
27494fa222aSJohn BaldwinErrors which
27594fa222aSJohn Baldwin.Fn namei
27694fa222aSJohn Baldwinmay return:
27794fa222aSJohn Baldwin.Bl -tag -width Er
27894fa222aSJohn Baldwin.It Bq Er ENOTDIR
27994fa222aSJohn BaldwinA component of the specified pathname is not a directory when a directory is
28094fa222aSJohn Baldwinexpected.
28194fa222aSJohn Baldwin.It Bq Er ENAMETOOLONG
28294fa222aSJohn BaldwinA component of a pathname exceeded 255 characters,
28394fa222aSJohn Baldwinor an entire pathname exceeded 1023 characters.
28494fa222aSJohn Baldwin.It Bq Er ENOENT
28594fa222aSJohn BaldwinA component of the specified pathname does not exist,
28694fa222aSJohn Baldwinor the pathname is an empty string.
2871d800a67SJohn Baldwin.It Bq Er EACCES
28894fa222aSJohn BaldwinAn attempt is made to access a file in a way forbidden by its file access
28994fa222aSJohn Baldwinpermissions.
29094fa222aSJohn Baldwin.It Bq Er ELOOP
29194fa222aSJohn BaldwinToo many symbolic links were encountered in translating the pathname.
29294fa222aSJohn Baldwin.It Bq Er EISDIR
29394fa222aSJohn BaldwinAn attempt is made to open a directory with write mode specified.
2948bffca5eSJaakko Heinonen.It Bq Er EINVAL
2958bffca5eSJaakko HeinonenThe last component of the pathname specified for a
2968bffca5eSJaakko Heinonen.Dv DELETE
2978bffca5eSJaakko Heinonenor
2988bffca5eSJaakko Heinonen.Dv RENAME
2998bffca5eSJaakko Heinonenoperation is
3008bffca5eSJaakko Heinonen.Ql \&. .
30194fa222aSJohn Baldwin.It Bq Er EROFS
30294fa222aSJohn BaldwinAn attempt is made to modify a file or directory on a read-only file system.
30394fa222aSJohn Baldwin.El
30415c3fb05SHiten Pandya.Sh SEE ALSO
30515c3fb05SHiten Pandya.Xr uio 9 ,
30615c3fb05SHiten Pandya.Xr uma 9 ,
30715c3fb05SHiten Pandya.Xr VFS 9 ,
30815c3fb05SHiten Pandya.Xr vnode 9 ,
30915c3fb05SHiten Pandya.Xr vput 9 ,
31015c3fb05SHiten Pandya.Xr vref 9
311c78f3f0dSEivind Eklund.Sh AUTHORS
31209f84dd1SRuslan Ermilov.An -nosplit
31315c3fb05SHiten PandyaThis manual page was written by
3148a7314fcSBaptiste Daroussin.An Eivind Eklund Aq Mt eivind@FreeBSD.org
31515c3fb05SHiten Pandyaand later significantly revised by
3168a7314fcSBaptiste Daroussin.An Hiten M. Pandya Aq Mt hmp@FreeBSD.org .
31715c3fb05SHiten Pandya.Sh BUGS
31815c3fb05SHiten PandyaThe
31915c3fb05SHiten Pandya.Dv LOCKPARENT
32015c3fb05SHiten Pandyaflag does not always result in the parent vnode being locked.
32115c3fb05SHiten PandyaThis results in complications when the
32215c3fb05SHiten Pandya.Dv LOCKPARENT
32315c3fb05SHiten Pandyais used.
32415c3fb05SHiten PandyaIn order to solve this for the cases where both
32515c3fb05SHiten Pandya.Dv LOCKPARENT
32615c3fb05SHiten Pandyaand
32715c3fb05SHiten Pandya.Dv LOCKLEAF
32815c3fb05SHiten Pandyaare used, it is necessary to resort to recursive locking.
329