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 6, 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. 125This is a full lock of the vnode; the 126.Xr VOP_UNLOCK 9 127should be used 128to release the lock (or 129.Xr vput 9 130which is equivalent to calling 131.Xr VOP_UNLOCK 9 132followed by 133.Xr vrele 9 , 134all in one). 135.It Dv LOCKPARENT 136This flag lets the 137.Fn namei 138function return the parent (directory) vnode, 139.Va ni_dvp 140in locked state, unless it is identical to 141.Va ni_vp , 142in which case 143.Va ni_dvp 144is not locked per se (but may be locked due to 145.Dv LOCKLEAF ) . 146If a lock is enforced, it should be released using 147.Xr vput 9 148or 149.Xr VOP_UNLOCK 9 150and 151.Xr vrele 9 . 152.It Dv WANTPARENT 153This flag allows the 154.Fn namei 155function to return the parent (directory) vnode in an unlocked state. 156The parent vnode must be released separately by using 157.Xr vrele 9 . 158.It Dv NOCACHE 159Avoid 160.Fn namei 161creating this entry in the namecache if it is not 162already present. 163Normally, 164.Fn namei 165will add entries to the name cache 166if they are not already there. 167.It Dv FOLLOW 168With this flag, 169.Fn namei 170will follow the symbolic link if the last part 171of the path supplied is a symbolic link (i.e., it will return a vnode 172for whatever the link points at, instead for the link itself). 173.It Dv NOFOLLOW 174Do not follow symbolic links (pseudo). 175This flag is not looked for by the actual code, which looks for 176.Dv FOLLOW . 177.Dv NOFOLLOW 178is used to indicate to the source code reader that symlinks 179are intentionally not followed. 180.It Dv SAVENAME 181Do not free the pathname buffer at the end of the 182.Fn namei 183invocation; instead, free it later in 184.Fn NDFREE 185so that the caller may access the pathname buffer. 186See below for details. 187.It Dv SAVESTART 188Retain an additional reference to the parent directory; do not free 189the pathname buffer. 190See below for details. 191.El 192.Sh ALLOCATED ELEMENTS 193The 194.Vt nameidata 195structure is composed of the following fields: 196.Bl -tag -width ".Va ni_cnd.cn_pnbuf" 197.It Va ni_startdir 198In the normal case, this is either the current directory or the root. 199It is the current directory if the name passed in does not start with 200.Ql / 201and we have not gone through any symlinks with an absolute path, and 202the root otherwise. 203.Pp 204In this case, it is only used by 205.Fn lookup , 206and should not be 207considered valid after a call to 208.Fn namei . 209If 210.Dv SAVESTART 211is set, this is set to the same as 212.Va ni_dvp , 213with an extra 214.Xr vref 9 . 215To block 216.Fn NDFREE 217from releasing 218.Va ni_startdir , 219the 220.Dv NDF_NO_STARTDIR_RELE 221can be set. 222.It Va ni_dvp 223Vnode pointer to directory of the object on which lookup is performed. 224This is available on successful return if 225.Dv LOCKPARENT 226or 227.Dv WANTPARENT 228is set. 229It is locked if 230.Dv LOCKPARENT 231is set. 232Freeing this in 233.Fn NDFREE 234can be inhibited by 235.Dv NDF_NO_DVP_RELE , NDF_NO_DVP_PUT , 236or 237.Dv NDF_NO_DVP_UNLOCK 238(with the obvious effects). 239.It Va ni_vp 240Vnode pointer to the resulting object, 241.Dv NULL 242otherwise. 243The 244.Va v_usecount 245field of this vnode is incremented. 246If 247.Dv LOCKLEAF 248is set, it is also locked. 249.Pp 250Freeing this in 251.Fn NDFREE 252can be inhibited by 253.Dv NDF_NO_VP_RELE , NDF_NO_VP_PUT , 254or 255.Dv NDF_NO_VP_UNLOCK 256(with the obvious effects). 257.It Va ni_cnd.cn_pnbuf 258The pathname buffer contains the location of the file or directory 259that will be used by the 260.Nm 261operations. 262It is managed by the 263.Xr uma 9 264zone allocation interface. 265If the 266.Dv SAVESTART 267or 268.Dv SAVENAME 269flag is set, then the pathname buffer is available 270after calling the 271.Fn namei 272function. 273.Pp 274To only deallocate resources used by the pathname buffer, 275.Va ni_cnd.cn_pnbuf , 276then 277.Dv NDF_ONLY_PNBUF 278flag can be passed to the 279.Fn NDFREE 280function. 281To keep the pathname buffer intact, 282the 283.Dv NDF_NO_FREE_PNBUF 284flag can be passed to the 285.Fn NDFREE 286function. 287.El 288.Sh RETURN VALUES 289If successful, 290.Fn namei 291will return 0, otherwise it will return an error. 292.Sh FILES 293.Bl -tag -width Pa 294.It Pa src/sys/kern/vfs_lookup.c 295.El 296.Sh ERRORS 297Errors which 298.Fn namei 299may return: 300.Bl -tag -width Er 301.It Bq Er ENOTDIR 302A component of the specified pathname is not a directory when a directory is 303expected. 304.It Bq Er ENAMETOOLONG 305A component of a pathname exceeded 255 characters, 306or an entire pathname exceeded 1023 characters. 307.It Bq Er ENOENT 308A component of the specified pathname does not exist, 309or the pathname is an empty string. 310.It Bq Er EACCES 311An attempt is made to access a file in a way forbidden by its file access 312permissions. 313.It Bq Er ELOOP 314Too many symbolic links were encountered in translating the pathname. 315.It Bq Er EISDIR 316An attempt is made to open a directory with write mode specified. 317.It Bq Er EINVAL 318The last component of the pathname specified for a 319.Dv DELETE 320or 321.Dv RENAME 322operation is 323.Ql \&. . 324.It Bq Er EROFS 325An attempt is made to modify a file or directory on a read-only file system. 326.El 327.Sh SEE ALSO 328.Xr uio 9 , 329.Xr uma 9 , 330.Xr VFS 9 , 331.Xr vnode 9 , 332.Xr vput 9 , 333.Xr vref 9 334.Sh AUTHORS 335.An -nosplit 336This manual page was written by 337.An Eivind Eklund Aq Mt eivind@FreeBSD.org 338and later significantly revised by 339.An Hiten M. Pandya Aq Mt hmp@FreeBSD.org . 340.Sh BUGS 341The 342.Dv LOCKPARENT 343flag does not always result in the parent vnode being locked. 344This results in complications when the 345.Dv LOCKPARENT 346is used. 347In order to solve this for the cases where both 348.Dv LOCKPARENT 349and 350.Dv LOCKLEAF 351are used, it is necessary to resort to recursive locking. 352