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 May 16, 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 WANTPARENT 210This flag allows the 211.Fn namei 212function to return the parent (directory) vnode in an unlocked state. 213The parent vnode must be released separately by using 214.Xr vrele 9 . 215.It Dv FAILIFEXISTS 216Makes the 217.Nm 218operation fail if the target exists. 219It requires that the 220.Dv LOCKPARENT 221flag is set and 222.Dv LOCKLEAF 223is not. 224.It Dv FOLLOW 225With this flag, 226.Fn namei 227will follow the symbolic link if the last part 228of the path supplied is a symbolic link (i.e., it will return a vnode 229for whatever the link points at, instead for the link itself). 230.It Dv EMPTYPATH 231For 232.Nm 233call initialized with 234.Fn NDINIT_AT , 235allow the 236.Fa namep 237path to be empty. 238In this case, the 239.Fa dirfd 240file descriptor may reference a file of arbitrary type, not 241necessary a directory, and lookup returns the vnode for this file. 242.It Dv LOCKSHARED 243Lock vnode on return with 244.Dv LK_SHARED , 245if permitted by the file system that owns the vnode. 246The file system must explicitly permit this by setting 247.Dv MNTK_LOOKUP_SHARED 248in 249.Dv mp->mnt_kern_flag 250during mount and by calling 251.Fn VN_LOCK_ASHARE 252when allocating the vnode. 253If 254.Dv LOCKLEAF 255is specified but shared locking is not permitted, then the vnode will be 256returned with 257.Dv LK_EXCLUSIVE . 258.Xr VOP_UNLOCK 9 259should be used 260to release the lock (or 261.Xr vput 9 262which is equivalent to calling 263.Xr VOP_UNLOCK 9 264followed by 265.Xr vrele 9 , 266all in one). 267.It Dv NOFOLLOW 268Do not follow symbolic links (pseudo). 269This flag is not looked for by the actual code, which looks for 270.Dv FOLLOW . 271.Dv NOFOLLOW 272is used to indicate to the source code reader that symlinks 273are intentionally not followed. 274.It Dv RBENEATH 275Requires that 276.Nm 277did not cross the 278.Fa dirfd 279directory. 280The flag is used to implement 281.Dv O_RESOLVE_BENEATH 282flag for 283.Xr openat 2 . 284.It Dv NAMEILOOKUP 285The component is embedded in a 286.Nm 287lookup structure, and the 288.Fn vfs_lookup_nameidata 289function can be used to obtain that structure. 290This can be useful in 291.Xr VOP_LOOKUP 9 292implementations which need to obtain extra lookup metadata. 293.El 294.Sh PARAMETERS DESCRIPTORS FLAGS 295These flags are used for several purposes. 296Some of them affects the global 297.Nm 298operation, some provide information for processing of the specific 299path element, for instance, by the 300.Dv VOP_LOOKUP 301implementation of the involved filesystem. 302.Bl -tag -width IGNOREWHITEOUT 303.It Dv RDONLY 304Specifies that the lookup should act as if the final node is located on 305read-only mount. 306The flag is typically used by file servers, e.g. NFS, 307to handle read-only exports. 308.It Dv ISRESTARTED 309The 310.Nm 311was restarted with 312.Fn NDRESTART . 313This is used internally for double-root lookups used by ABI subsystems, 314after the lookup with native root failed. 315The components are reset to the original values, and lookup is repeated 316with different root, once. 317.It Dv IGNOREWHITEOUT 318Ignore whiteouts, e.g. when checking if a directory is empty. 319.It Dv ISWHITEOUT 320The result of lookup is whiteout. 321.It Dv DOWHITEOUT 322Handle whiteouts, the instruction for the 323.Fn VOP_LOOKUP 324filesystem methods. 325.It Dv WILLBEDIR 326The lookup is done for creating a new entry that will be directory. 327It allows the trailing slash in the path string. 328.It Dv ISOPEN 329The caller is the code that opens a file. 330This allows to weaken the lock mode of the return vnode, if the 331mount point indicates extended shared lock support. 332.It Dv NOCROSSMOUNT 333Do not cross mount points during lookup. 334.Pp 335For 336.Dq .. 337lookup leading to mount root, returns the root vnode of 338the mount instead of the covered vnode of the filesystem where 339the mount was placed. 340.Pp 341For other lookups passing over mount, do not jump into the mounted 342filesystem. 343This allows to descend into the file hierarchy otherwise shadowed 344by the mount point. 345.It Dv NOMACCHECK 346Do not perform MAC checks during lookup. 347.It Dv AUDITVNODE1 348Audit the looked up vnode information, use the first slot for audit information. 349.It Dv AUDITVNODE2 350Same as 351.Dv AUDITVNODE1 352but use the second slot. 353.It Dv NOCAPCHECK 354Do not perform capability checks. 355If the calling process is in capability mode, lookup is denied outright. 356.It Dv OPENREAD 357The lookup was for open and file will be opened for read. 358.It Dv OPENWRITE 359The lookup was for open and file will be opened for write. 360.It Dv WANTIOCTLCAPS 361Leave ioctl caps for the caller. 362See the description of 363.Nm 364results. 365.It Dv OPENNAMED 366Opening a named attribute (directory). 367.It Dv NOEXECCHECK 368Do not perform check for allowed execution on the starting directory. 369It is used to implement the POSIX-required semantic for 370.Xr openat 2 371lookups that must use the permissions from time the directory was 372opened, and not when used for lookup. 373.It Dv MAKEENTRY 374Looked-up entry is to be added to name cache. 375.It Dv ISSYMLINK 376Current component is symlink, and it needs the interpretation 377according to the 378.Dv FOLLOW 379or 380.Dv NOFOLLOW 381flags. 382.It Dv ISLASTCN 383This is last component of pathname. 384It is handled specially, many flags augment its processing. 385.It Dv ISDOTDOT 386Current component name is 387.Dq .. . 388Usually implies a need to specially handle the vnode locking 389for instantiation of the target vnode. 390The generic 391.Fn vn_vget_ino_gen 392function and its more specialized variant 393.Fn vn_vget_ino 394might be useful. 395.It Dv TRAILINGSLASH 396Path ended in a slash. 397.It Dv CREATENAMED 398Create a named attribute dir. 399.El 400.Sh ALLOCATED ELEMENTS 401The 402.Vt nameidata 403structure is composed of the following fields: 404.Bl -tag -width ".Va ni_cnd.cn_pnbuf" 405.It Va ni_startdir 406In the normal case, this is either the current directory or the root. 407It is the current directory if the name passed in does not start with 408.Ql / 409and we have not gone through any symlinks with an absolute path, and 410the root otherwise. 411.Pp 412In this case, it is only used by 413.Fn vfs_lookup , 414and should not be 415considered valid after a call to 416.Fn namei . 417.It Va ni_dvp 418Vnode pointer to directory of the object on which lookup is performed. 419This is available on successful return if 420.Dv LOCKPARENT 421or 422.Dv WANTPARENT 423is set. 424It is locked if 425.Dv LOCKPARENT 426is set. 427.It Va ni_vp 428Vnode pointer to the resulting object, 429.Dv NULL 430otherwise. 431The 432.Va v_usecount 433field of this vnode is incremented. 434If 435.Dv LOCKLEAF 436is set, it is also locked. 437.Pp 438.It Va ni_cnd.cn_pnbuf 439The pathname buffer contains the location of the file or directory 440that will be used by the 441.Nm 442operations. 443It is managed by the 444.Xr uma 9 445zone allocation interface. 446.El 447.Sh RESULTS 448The 449.Vt struct namei 450member 451.Dv ni_resflags 452returns the following flags giving some details of the succesfull operation: 453.Bl -tag -width NIRES_EMPTYPATH 454.It Dv NIRES_ABS 455The path passed was absolute. 456.It Dv NIRES_STRICTREL 457Restricted lookup result. 458Only relative lookups were done to resolve the path to vnode. 459.It Dv NIRES_EMPTYPATH 460The 461.Dv EMPTYPATH 462flag was provided and used. 463In particular, the passed path was empty. 464.El 465.Pp 466If the 467.Dv WANTIOCTLCAPS 468flag was specified, on return the 469.Va ni_filecaps 470member of the 471.Vt struct namei 472contains the capabilities of the file descriptor used as 473the lookup starting point 474.Pq Va dirfd . 475.Sh RETURN VALUES 476If successful, 477.Fn namei 478will return 0, otherwise it will return an error. 479.Sh FILES 480.Bl -tag -width Pa 481.It Pa src/sys/kern/vfs_lookup.c 482.El 483.Sh EXAMPLES 484Assuming the 485.Dv path 486variable contains a pointer to userspace path string, the following 487example looks up the file named by it, and performs required error 488and resource handling: 489.Bd -literal 490 char *path; 491 struct nameidata nd; 492 int error; 493 494 NDINIT(&nd, LOOKUP, FOLLOW | LOCKLEAF | AUDITVNODE1, UIO_USERSPACE, 495 path); 496 if ((error = namei(&nd)) != 0) 497 return (error); 498 NDFREE_PNBUF(&nd); 499 ... use nd.ni_vp vnode 500.Ed 501.Sh ERRORS 502Errors which 503.Fn namei 504may return: 505.Bl -tag -width Er 506.It Bq Er ENOTDIR 507A component of the specified pathname is not a directory when a directory is 508expected. 509.It Bq Er ENAMETOOLONG 510A component of a pathname exceeded 255 characters, 511or an entire pathname exceeded 1023 characters. 512.It Bq Er ENOENT 513A component of the specified pathname does not exist, 514or the pathname is an empty string. 515.It Bq Er EACCES 516An attempt is made to access a file in a way forbidden by its file access 517permissions. 518.It Bq Er ELOOP 519Too many symbolic links were encountered in translating the pathname. 520.It Bq Er EISDIR 521An attempt is made to open a directory with write mode specified. 522.It Bq Er EINVAL 523The last component of the pathname specified for a 524.Dv DELETE 525or 526.Dv RENAME 527operation is 528.Ql \&. . 529.It Bq Er EROFS 530An attempt is made to modify a file or directory on a read-only file system. 531.El 532.Sh SEE ALSO 533.Xr uio 9 , 534.Xr uma 9 , 535.Xr VFS 9 , 536.Xr vnode 9 , 537.Xr vput 9 , 538.Xr vref 9 , 539.Xr vrele 9 540.Sh AUTHORS 541.An -nosplit 542This manual page was written by 543.An Eivind Eklund Aq Mt eivind@FreeBSD.org 544and later significantly revised by 545.An Hiten M. Pandya Aq Mt hmp@FreeBSD.org . 546.Sh BUGS 547The 548.Dv LOCKPARENT 549flag does not always result in the parent vnode being locked. 550This results in complications when the 551.Dv LOCKPARENT 552is used. 553In order to solve this for the cases where both 554.Dv LOCKPARENT 555and 556.Dv LOCKLEAF 557are used, it is necessary to resort to recursive locking. 558