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