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