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 March 1, 2012 37.Dt NAMEI 9 38.Os 39.Sh NAME 40.Nm namei , 41.Nm NDINIT , 42.Nm NDFREE , 43.Nm NDHASGIANT 44.Nd pathname translation and lookup operations 45.Sh SYNOPSIS 46.In sys/param.h 47.In sys/fcntl.h 48.In sys/namei.h 49.Ft int 50.Fn namei "struct nameidata *ndp" 51.Ft void 52.Fo NDINIT 53.Fa "struct nameidata *ndp" "u_long op" "u_long flags" 54.Fa "enum uio_seg segflg" "const char *namep" "struct thread *td" 55.Fc 56.Ft void 57.Fn NDFREE "struct nameidata *ndp" "const uint flags" 58.Ft int 59.Fn NDHASGIANT "struct nameidata *ndp" 60.Sh DESCRIPTION 61The 62.Nm 63facility allows the client to perform pathname translation and lookup 64operations. 65The 66.Nm 67functions will increment the reference count for the vnode in question. 68The reference count has to be decremented after use of the vnode, by 69using either 70.Xr vrele 9 71or 72.Xr vput 9 , 73depending on whether the 74.Dv LOCKLEAF 75flag was specified or not. 76If the 77.Va Giant 78lock is required, 79.Nm 80will acquire it if the caller indicates it is 81.Dv MPSAFE , 82in which case the caller must later release 83.Va Giant 84based on the results of 85.Fn NDHASGIANT . 86.Pp 87The 88.Fn NDINIT 89function is used to initialize 90.Nm 91components. 92It takes the following arguments: 93.Bl -tag -width ".Fa segflg" 94.It Fa ndp 95The 96.Vt "struct nameidata" 97to initialize. 98.It Fa op 99The operation which 100.Fn namei 101will perform. 102The following operations are valid: 103.Dv LOOKUP , CREATE , DELETE , 104and 105.Dv RENAME . 106The latter three are just setup for those 107effects; just calling 108.Fn namei 109will not result in 110.Fn VOP_RENAME 111being called. 112.It Fa flags 113Operation flags. 114Several of these can be effective at the same time. 115.It Fa segflg 116UIO segment indicator. 117This indicates if the name of the object is in userspace 118.Pq Dv UIO_USERSPACE 119or in the kernel address space 120.Pq Dv UIO_SYSSPACE . 121.It Fa namep 122Pointer to the component's pathname buffer 123(the file or directory name that will be looked up). 124.It Fa td 125The thread context to use for 126.Nm 127operations and locks. 128.El 129.Sh NAMEI OPERATION FLAGS 130The 131.Fn namei 132function takes the following set of 133.Dq "operation flags" 134that influence its operation: 135.Bl -tag -width ".Dv WANTPARENT" 136.It Dv LOCKLEAF 137Lock vnode on return. 138This is a full lock of the vnode; the 139.Xr VOP_UNLOCK 9 140should be used 141to release the lock (or 142.Xr vput 9 143which is equivalent to calling 144.Xr VOP_UNLOCK 9 145followed by 146.Xr vrele 9 , 147all in one). 148.It Dv LOCKPARENT 149This flag lets the 150.Fn namei 151function return the parent (directory) vnode, 152.Va ni_dvp 153in locked state, unless it is identical to 154.Va ni_vp , 155in which case 156.Va ni_dvp 157is not locked per se (but may be locked due to 158.Dv LOCKLEAF ) . 159If a lock is enforced, it should be released using 160.Xr vput 9 161or 162.Xr VOP_UNLOCK 9 163and 164.Xr vrele 9 . 165.It Dv WANTPARENT 166This flag allows the 167.Fn namei 168function to return the parent (directory) vnode in an unlocked state. 169The parent vnode must be released separately by using 170.Xr vrele 9 . 171.It Dv NOCACHE 172Avoid 173.Fn namei 174creating this entry in the namecache if it is not 175already present. 176Normally, 177.Fn namei 178will add entries to the name cache 179if they are not already there. 180.It Dv FOLLOW 181With this flag, 182.Fn namei 183will follow the symbolic link if the last part 184of the path supplied is a symbolic link (i.e., it will return a vnode 185for whatever the link points at, instead for the link itself). 186.It Dv NOFOLLOW 187Do not follow symbolic links (pseudo). 188This flag is not looked for by the actual code, which looks for 189.Dv FOLLOW . 190.Dv NOFOLLOW 191is used to indicate to the source code reader that symlinks 192are intentionally not followed. 193.It Dv SAVENAME 194Do not free the pathname buffer at the end of the 195.Fn namei 196invocation; instead, free it later in 197.Fn NDFREE 198so that the caller may access the pathname buffer. 199See below for details. 200.It Dv SAVESTART 201Retain an additional reference to the parent directory; do not free 202the pathname buffer. 203See below for details. 204.El 205.Sh ALLOCATED ELEMENTS 206The 207.Vt nameidata 208structure is composed of the following fields: 209.Bl -tag -width ".Va ni_cnd.cn_pnbuf" 210.It Va ni_startdir 211In the normal case, this is either the current directory or the root. 212It is the current directory if the name passed in does not start with 213.Ql / 214and we have not gone through any symlinks with an absolute path, and 215the root otherwise. 216.Pp 217In this case, it is only used by 218.Fn lookup , 219and should not be 220considered valid after a call to 221.Fn namei . 222If 223.Dv SAVESTART 224is set, this is set to the same as 225.Va ni_dvp , 226with an extra 227.Xr vref 9 . 228To block 229.Fn NDFREE 230from releasing 231.Va ni_startdir , 232the 233.Dv NDF_NO_STARTDIR_RELE 234can be set. 235.It Va ni_dvp 236Vnode pointer to directory of the object on which lookup is performed. 237This is available on successful return if 238.Dv LOCKPARENT 239or 240.Dv WANTPARENT 241is set. 242It is locked if 243.Dv LOCKPARENT 244is set. 245Freeing this in 246.Fn NDFREE 247can be inhibited by 248.Dv NDF_NO_DVP_RELE , NDF_NO_DVP_PUT , 249or 250.Dv NDF_NO_DVP_UNLOCK 251(with the obvious effects). 252.It Va ni_vp 253Vnode pointer to the resulting object, 254.Dv NULL 255otherwise. 256The 257.Va v_usecount 258field of this vnode is incremented. 259If 260.Dv LOCKLEAF 261is set, it is also locked. 262.Pp 263Freeing this in 264.Fn NDFREE 265can be inhibited by 266.Dv NDF_NO_VP_RELE , NDF_NO_VP_PUT , 267or 268.Dv NDF_NO_VP_UNLOCK 269(with the obvious effects). 270.It Va ni_cnd.cn_pnbuf 271The pathname buffer contains the location of the file or directory 272that will be used by the 273.Nm 274operations. 275It is managed by the 276.Xr uma 9 277zone allocation interface. 278If the 279.Dv SAVESTART 280or 281.Dv SAVENAME 282flag is set, then the pathname buffer is available 283after calling the 284.Fn namei 285function. 286.Pp 287To only deallocate resources used by the pathname buffer, 288.Va ni_cnd.cn_pnbuf , 289then 290.Dv NDF_ONLY_PNBUF 291flag can be passed to the 292.Fn NDFREE 293function. 294To keep the pathname buffer intact, 295the 296.Dv NDF_NO_FREE_PNBUF 297flag can be passed to the 298.Fn NDFREE 299function. 300.El 301.Sh RETURN VALUES 302If successful, 303.Fn namei 304will return 0, otherwise it will return an error. 305.Sh FILES 306.Bl -tag -width Pa 307.It Pa src/sys/kern/vfs_lookup.c 308.El 309.Sh ERRORS 310Errors which 311.Fn namei 312may return: 313.Bl -tag -width Er 314.It Bq Er ENOTDIR 315A component of the specified pathname is not a directory when a directory is 316expected. 317.It Bq Er ENAMETOOLONG 318A component of a pathname exceeded 255 characters, 319or an entire pathname exceeded 1023 characters. 320.It Bq Er ENOENT 321A component of the specified pathname does not exist, 322or the pathname is an empty string. 323.It Bq Er EACCES 324An attempt is made to access a file in a way forbidden by its file access 325permissions. 326.It Bq Er ELOOP 327Too many symbolic links were encountered in translating the pathname. 328.It Bq Er EISDIR 329An attempt is made to open a directory with write mode specified. 330.It Bq Er EINVAL 331The last component of the pathname specified for a 332.Dv DELETE 333or 334.Dv RENAME 335operation is 336.Ql \&. . 337.It Bq Er EROFS 338An attempt is made to modify a file or directory on a read-only file system. 339.El 340.Sh SEE ALSO 341.Xr uio 9 , 342.Xr uma 9 , 343.Xr VFS 9 , 344.Xr vnode 9 , 345.Xr vput 9 , 346.Xr vref 9 347.Sh AUTHORS 348.An -nosplit 349This manual page was written by 350.An Eivind Eklund Aq Mt eivind@FreeBSD.org 351and later significantly revised by 352.An Hiten M. Pandya Aq Mt hmp@FreeBSD.org . 353.Sh BUGS 354The 355.Dv LOCKPARENT 356flag does not always result in the parent vnode being locked. 357This results in complications when the 358.Dv LOCKPARENT 359is used. 360In order to solve this for the cases where both 361.Dv LOCKPARENT 362and 363.Dv LOCKLEAF 364are used, it is necessary to resort to recursive locking. 365.Pp 366Non-MPSAFE file systems exist, requiring callers to conditionally unlock 367.Va Giant . 368