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.Dd September 30, 2025 35.Dt NAMEI 9 36.Os 37.Sh NAME 38.Nm namei , 39.Nm NDINIT , 40.Nm NDINIT_AT , 41.Nm NDFREE_PNBUF 42.Nd pathname translation and lookup operations 43.Sh SYNOPSIS 44.In sys/param.h 45.In sys/fcntl.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" "enum nameiop op" "u_int64_t flags" 52.Fa "enum uio_seg segflg" "const char *namep" 53.Fc 54.Ft void 55.Fo NDINIT_AT 56.Fa "struct nameidata *ndp" "enum nameiop op" "u_int64_t flags" 57.Fa "enum uio_seg segflg" "const char *namep" "int dirfd" 58.Fc 59.Ft void 60.Fn NDFREE_PNBUF "struct nameidata *ndp" 61.Sh DESCRIPTION 62The 63.Nm 64facility allows the client to perform pathname translation and lookup 65operations. 66The 67.Nm 68functions will increment the reference count for the vnode in question. 69The reference count has to be decremented after use of the vnode, by 70using either 71.Xr vrele 9 72or 73.Xr vput 9 , 74depending on whether the 75.Dv LOCKLEAF 76flag was specified or not. 77.Pp 78The 79.Fn NDINIT 80macro is used to initialize 81.Nm 82components. 83It takes the following arguments: 84.Bl -tag -width ".Fa segflg" 85.It Fa ndp 86A pointer to the 87.Vt "struct nameidata" 88to initialize. 89.It Fa op 90The operation which 91.Fn namei 92will perform. 93The following operations are valid: 94.Dv LOOKUP , CREATE , DELETE , 95and 96.Dv RENAME . 97The latter three are just setup for those 98effects; just calling 99.Fn namei 100will not result in 101.Fn VOP_RENAME 102being called. 103.It Fa flags 104Operation flags, described in the next section. 105Several of these can be effective at the same time. 106.It Fa segflg 107UIO segment indicator. 108This indicates if the name of the object is in userspace 109.Pq Dv UIO_USERSPACE 110or in the kernel address space 111.Pq Dv UIO_SYSSPACE . 112.It Fa namep 113Pointer to the component's pathname buffer 114(the file or directory name that will be looked up). 115.El 116.Pp 117The 118.Fn NDINIT_AT 119macro is similar to 120.Fn NDINIT , 121but takes one extra argument: 122.Bl -tag -width ".Fa segflg" 123.It Fa dirfd 124File descriptor referencing a directory, or the special value 125.Dv AT_FDCWD 126meaning the calling thread's current working directory. 127Lookups will be performed relative to this directory. 128.El 129.Pp 130The 131.Fn NDFREE_PNBUF 132macro is used to free the pathname buffer. 133It must be called exactly once for each successful 134.Fn namei 135call. 136It takes the following argument: 137.Bl -tag -width ".Fa segflg" 138.It Fa ndp 139A pointer to a 140.Vt "struct nameidata" 141that was used in a successful 142.Fn namei 143call. 144.El 145.Sh NAMEI OPERATION FLAGS 146The 147.Fn namei 148function takes the following set of 149.Dq "operation flags" 150that influence its operation: 151.Bl -tag -width NC_KEEPPOSENTRY 152.It Dv NC_NOMAKEENTRY 153An alias for 154.Dv NOCACHE . 155.It Dv NC_KEEPPOSENTRY 156Keep the positive-caching entry in cache. 157This flag is typically combined with 158.Dv NOCACHE 159to not cache a new entry, 160but keep existing one, or with 161.Dv MAKEENTRY . 162.It Dv NOCACHE 163Avoid 164.Fn namei 165creating this entry in the namecache if it is not 166already present. 167Normally, 168.Fn namei 169will add entries to the name cache 170if they are not already there. 171.It Dv LOCKLEAF 172Lock vnode on return with 173.Dv LK_EXCLUSIVE 174unless 175.Dv LOCKSHARED 176is also set. 177.Xr VOP_UNLOCK 9 178should be used 179to release the lock (or 180.Xr vput 9 181which is equivalent to calling 182.Xr VOP_UNLOCK 9 183followed by 184.Xr vrele 9 , 185all in one). 186.It Dv LOCKPARENT 187This flag lets the 188.Fn namei 189function return the parent (directory) vnode, 190.Va ni_dvp 191in locked state, unless it is identical to 192.Va ni_vp , 193in which case 194.Va ni_dvp 195is not locked per se (but may be locked due to 196.Dv LOCKLEAF ) . 197If a lock is enforced, it should be released using 198.Xr vput 9 199or 200.Xr VOP_UNLOCK 9 201and 202.Xr vrele 9 . 203.It Dv WANTPARENT 204This flag allows the 205.Fn namei 206function to return the parent (directory) vnode in an unlocked state. 207The parent vnode must be released separately by using 208.Xr vrele 9 . 209.It Dv FAILIFEXISTS 210Makes the 211.Nm 212operation fail if the target exists. 213It requires that the 214.Dv LOCKPARENT 215flag is set and 216.Dv LOCKLEAF 217is not. 218.It Dv FOLLOW 219With this flag, 220.Fn namei 221will follow the symbolic link if the last part 222of the path supplied is a symbolic link (i.e., it will return a vnode 223for whatever the link points at, instead for the link itself). 224.It Dv EMPTYPATH 225For 226.Nm 227call initialized with 228.Fn NDINIT_AT , 229allow the 230.Fa namep 231path to be empty. 232In this case, the 233.Fa dirfd 234file descriptor may reference a file of arbitrary type, not 235necessary a directory, and lookup returns the vnode for this file. 236.It Dv LOCKSHARED 237Lock vnode on return with 238.Dv LK_SHARED , 239if permitted by the file system that owns the vnode. 240The file system must explicitly permit this by setting 241.Dv MNTK_LOOKUP_SHARED 242in 243.Dv mp->mnt_kern_flag 244during mount and by calling 245.Fn VN_LOCK_ASHARE 246when allocating the vnode. 247If 248.Dv LOCKLEAF 249is specified but shared locking is not permitted, then the vnode will be 250returned with 251.Dv LK_EXCLUSIVE . 252.Xr VOP_UNLOCK 9 253should be used 254to release the lock (or 255.Xr vput 9 256which is equivalent to calling 257.Xr VOP_UNLOCK 9 258followed by 259.Xr vrele 9 , 260all in one). 261.It Dv NOFOLLOW 262Do not follow symbolic links (pseudo). 263This flag is not looked for by the actual code, which looks for 264.Dv FOLLOW . 265.Dv NOFOLLOW 266is used to indicate to the source code reader that symlinks 267are intentionally not followed. 268.It Dv RBENEATH 269Requires that 270.Nm 271did not cross the 272.Fa dirfd 273directory. 274The flag is used to implement 275.Dv O_RESOLVE_BENEATH 276flag for 277.Xr openat 2 . 278.It Dv NAMEILOOKUP 279The component is embedded in a 280.Nm 281lookup structure, and the 282.Fn vfs_lookup_nameidata 283function can be used to obtain that structure. 284This can be useful in 285.Xr VOP_LOOKUP 9 286implementations which need to obtain extra lookup metadata. 287.El 288.Sh PARAMETERS DESCRIPTORS FLAGS 289These flags are used for several purposes. 290Some of them affects the global 291.Nm 292operation, some provide information for processing of the specific 293path element, for instance, by the 294.Dv VOP_LOOKUP 295implementation of the involved filesystem. 296.Bl -tag -width IGNOREWHITEOUT 297.It Dv RDONLY 298Specifies that the lookup should act as if the final node is located on 299read-only mount. 300The flag is typically used by file servers, e.g. NFS, 301to handle read-only exports. 302.It Dv ISRESTARTED 303The 304.Nm 305was restarted with 306.Fn NDRESTART . 307This is used internally for double-root lookups used by ABI subsystems, 308after the lookup with native root failed. 309The components are reset to the original values, and lookup is repeated 310with different root, once. 311.It Dv IGNOREWHITEOUT 312Ignore whiteouts, e.g. when checking if a directory is empty. 313.It Dv ISWHITEOUT 314The result of lookup is whiteout. 315.It Dv DOWHITEOUT 316Handle whiteouts, the instruction for the 317.Fn VOP_LOOKUP 318filesystem methods. 319.It Dv WILLBEDIR 320The lookup is done for creating a new entry that will be directory. 321It allows the trailing slash in the path string. 322.It Dv ISOPEN 323The caller is the code that opens a file. 324This allows to weaken the lock mode of the return vnode, if the 325mount point indicates extended shared lock support. 326.It Dv NOCROSSMOUNT 327Do not cross mount points during lookup. 328.Pp 329For 330.Dq .. 331lookup leading to mount root, returns the root vnode of 332the mount instead of the covered vnode of the filesystem where 333the mount was placed. 334.Pp 335For other lookups passing over mount, do not jump into the mounted 336filesystem. 337This allows to descend into the file hierarchy otherwise shadowed 338by the mount point. 339.It Dv NOMACCHECK 340Do not perform MAC checks during lookup. 341.It Dv AUDITVNODE1 342Audit the looked up vnode information, use the first slot for audit information. 343.It Dv AUDITVNODE2 344Same as 345.Dv AUDITVNODE1 346but use the second slot. 347.It Dv NOCAPCHECK 348Do not perform capability checks. 349If the calling process is in capability mode, lookup is denied outright. 350.It Dv OPENREAD 351The lookup was for open and file will be opened for read. 352.It Dv OPENWRITE 353The lookup was for open and file will be opened for write. 354.It Dv WANTIOCTLCAPS 355Leave ioctl caps for the caller. 356See the description of 357.Nm 358results. 359.It Dv OPENNAMED 360Opening a named attribute (directory). 361.It Dv NOEXECCHECK 362Do not perform check for allowed execution on the starting directory. 363It is used to implement the POSIX-required semantic for 364.Xr openat 2 365lookups that must use the permissions from time the directory was 366opened, and not when used for lookup. 367.It Dv MAKEENTRY 368Looked-up entry is to be added to name cache. 369.It Dv ISSYMLINK 370Current component is symlink, and it needs the interpretation 371according to the 372.Dv FOLLOW 373or 374.Dv NOFOLLOW 375flags. 376.It Dv ISLASTCN 377This is last component of pathname. 378It is handled specially, many flags augment its processing. 379.It Dv ISDOTDOT 380Current component name is 381.Dq .. . 382Usually implies a need to specially handle the vnode locking 383for instantiation of the target vnode. 384The generic 385.Fn vn_vget_ino_gen 386function and its more specialized variant 387.Fn vn_vget_ino 388might be useful. 389.It Dv TRAILINGSLASH 390Path ended in a slash. 391.It Dv CREATENAMED 392Create a named attribute dir. 393.El 394.Sh ALLOCATED ELEMENTS 395The 396.Vt nameidata 397structure is composed of the following fields: 398.Bl -tag -width ".Va ni_cnd.cn_pnbuf" 399.It Va ni_startdir 400In the normal case, this is either the current directory or the root. 401It is the current directory if the name passed in does not start with 402.Ql / 403and we have not gone through any symlinks with an absolute path, and 404the root otherwise. 405.Pp 406In this case, it is only used by 407.Fn vfs_lookup , 408and should not be 409considered valid after a call to 410.Fn namei . 411.It Va ni_dvp 412Vnode pointer to directory of the object on which lookup is performed. 413This is available on successful return if 414.Dv LOCKPARENT 415or 416.Dv WANTPARENT 417is set. 418It is locked if 419.Dv LOCKPARENT 420is set. 421.It Va ni_vp 422Vnode pointer to the resulting object, 423.Dv NULL 424otherwise. 425The 426.Va v_usecount 427field of this vnode is incremented. 428If 429.Dv LOCKLEAF 430is set, it is also locked. 431.Pp 432.It Va ni_cnd.cn_pnbuf 433The pathname buffer contains the location of the file or directory 434that will be used by the 435.Nm 436operations. 437It is managed by the 438.Xr uma 9 439zone allocation interface. 440.El 441.Sh RESULTS 442The 443.Vt struct namei 444member 445.Dv ni_resflags 446returns the following flags giving some details of the succesfull operation: 447.Bl -tag -width NIRES_EMPTYPATH 448.It Dv NIRES_ABS 449The path passed was absolute. 450.It Dv NIRES_STRICTREL 451Restricted lookup result. 452Only relative lookups were done to resolve the path to vnode. 453.It Dv NIRES_EMPTYPATH 454The 455.Dv EMPTYPATH 456flag was provided and used. 457In particular, the passed path was empty. 458.El 459.Pp 460If the 461.Dv WANTIOCTLCAPS 462flag was specified, on return the 463.Va ni_filecaps 464member of the 465.Vt struct namei 466contains the capabilities of the file descriptor used as 467the lookup starting point 468.Pq Va dirfd . 469.Sh RETURN VALUES 470If successful, 471.Fn namei 472will return 0, otherwise it will return an error. 473.Sh FILES 474.Bl -tag -width Pa 475.It Pa src/sys/kern/vfs_lookup.c 476.El 477.Sh EXAMPLES 478Assuming the 479.Dv path 480variable contains a pointer to userspace path string, the following 481example looks up the file named by it, and performs required error 482and resource handling: 483.Bd -literal 484 char *path; 485 struct nameidata nd; 486 int error; 487 488 NDINIT(&nd, LOOKUP, FOLLOW | LOCKLEAF | AUDITVNODE1, UIO_USERSPACE, 489 path); 490 if ((error = namei(&nd)) != 0) 491 return (error); 492 NDFREE_PNBUF(&nd); 493 ... use nd.ni_vp vnode 494.Ed 495.Sh ERRORS 496Errors which 497.Fn namei 498may return: 499.Bl -tag -width Er 500.It Bq Er ENOTDIR 501A component of the specified pathname is not a directory when a directory is 502expected. 503.It Bq Er ENAMETOOLONG 504A component of a pathname exceeded 255 characters, 505or an entire pathname exceeded 1023 characters. 506.It Bq Er ENOENT 507A component of the specified pathname does not exist, 508or the pathname is an empty string. 509.It Bq Er EACCES 510An attempt is made to access a file in a way forbidden by its file access 511permissions. 512.It Bq Er ELOOP 513Too many symbolic links were encountered in translating the pathname. 514.It Bq Er EISDIR 515An attempt is made to open a directory with write mode specified. 516.It Bq Er EINVAL 517The last component of the pathname specified for a 518.Dv DELETE 519or 520.Dv RENAME 521operation is 522.Ql \&. . 523.It Bq Er EROFS 524An attempt is made to modify a file or directory on a read-only file system. 525.El 526.Sh SEE ALSO 527.Xr uio 9 , 528.Xr uma 9 , 529.Xr VFS 9 , 530.Xr vnode 9 , 531.Xr vput 9 , 532.Xr vref 9 , 533.Xr vrele 9 534.Sh AUTHORS 535.An -nosplit 536This manual page was written by 537.An Eivind Eklund Aq Mt eivind@FreeBSD.org 538and later significantly revised by 539.An Hiten M. Pandya Aq Mt hmp@FreeBSD.org . 540.Sh BUGS 541The 542.Dv LOCKPARENT 543flag does not always result in the parent vnode being locked. 544This results in complications when the 545.Dv LOCKPARENT 546is used. 547In order to solve this for the cases where both 548.Dv LOCKPARENT 549and 550.Dv LOCKLEAF 551are used, it is necessary to resort to recursive locking. 552