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