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 September 21, 2005 37.Os 38.Dt NAMEI 9 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/proc.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 NOOBJ 200Do not call 201.Fn vfs_object_create 202for the returned vnode, even though it meets required criteria for VM support. 203.It Dv NOFOLLOW 204Do not follow symbolic links (pseudo). 205This flag is not looked for by the actual code, which looks for 206.Dv FOLLOW . 207.Dv NOFOLLOW 208is used to indicate to the source code reader that symlinks 209are intentionally not followed. 210.It Dv SAVENAME 211Do not free the pathname buffer at the end of the 212.Fn namei 213invocation; instead, free it later in 214.Fn NDFREE 215so that the caller may access the pathname buffer. 216See below for details. 217.It Dv SAVESTART 218Retain an additional reference to the parent directory; do not free 219the pathname buffer. 220See below for details. 221.El 222.Sh ALLOCATED ELEMENTS 223The 224.Vt nameidata 225structure is composed of the following fields: 226.Bl -tag -width ".Va ni_cnd.cn_pnbuf" 227.It Va ni_startdir 228In the normal case, this is either the current directory or the root. 229It is the current directory if the name passed in does not start with 230.Ql / 231and we have not gone through any symlinks with an absolute path, and 232the root otherwise. 233.Pp 234In this case, it is only used by 235.Fn lookup , 236and should not be 237considered valid after a call to 238.Fn namei . 239If 240.Dv SAVESTART 241is set, this is set to the same as 242.Va ni_dvp , 243with an extra 244.Xr vref 9 . 245To block 246.Fn NDFREE 247from releasing 248.Va ni_startdir , 249the 250.Dv NDF_NO_STARTDIR_RELE 251can be set. 252.It Va ni_dvp 253Vnode pointer to directory of the object on which lookup is performed. 254This is available on successful return if 255.Dv LOCKPARENT 256or 257.Dv WANTPARENT 258is set. 259It is locked if 260.Dv LOCKPARENT 261is set. 262Freeing this in 263.Fn NDFREE 264can be inhibited by 265.Dv NDF_NO_DVP_RELE , NDF_NO_DVP_PUT , 266or 267.Dv NDF_NO_DVP_UNLOCK 268(with the obvious effects). 269.It Va ni_vp 270Vnode pointer to the resulting object, 271.Dv NULL 272otherwise. 273The 274.Va v_usecount 275field of this vnode is incremented. 276If 277.Dv LOCKLEAF 278is set, it is also locked. 279.Pp 280Freeing this in 281.Fn NDFREE 282can be inhibited by 283.Dv NDF_NO_VP_RELE , NDF_NO_VP_PUT , 284or 285.Dv NDF_NO_VP_UNLOCK 286(with the obvious effects). 287.It Va ni_cnd.cn_pnbuf 288The pathname buffer contains the location of the file or directory 289that will be used by the 290.Nm 291operations. 292It is managed by the 293.Xr uma 9 294zone allocation interface. 295If the 296.Dv SAVESTART 297or 298.Dv SAVENAME 299flag is set, then the pathname buffer is available 300after calling the 301.Fn namei 302function. 303.Pp 304To only deallocate resources used by the pathname buffer, 305.Va ni_cnd.cn_pnbuf , 306then 307.Dv NDF_ONLY_PNBUF 308flag can be passed to the 309.Fn NDFREE 310function. 311To keep the pathname buffer intact, 312the 313.Dv NDF_NO_FREE_PNBUF 314flag can be passed to the 315.Fn NDFREE 316function. 317.El 318.Sh FILES 319.Bl -tag 320.It Pa src/sys/kern/vfs_lookup.c 321.El 322.Sh SEE ALSO 323.Xr uio 9 , 324.Xr uma 9 , 325.Xr VFS 9 , 326.Xr VFS_UNLOCK_GIANT 9 , 327.Xr vnode 9 , 328.Xr vput 9 , 329.Xr vref 9 330.Sh AUTHORS 331.An -nosplit 332This manual page was written by 333.An Eivind Eklund Aq eivind@FreeBSD.org 334and later significantly revised by 335.An Hiten M. Pandya Aq hmp@FreeBSD.org . 336.Sh BUGS 337The 338.Dv LOCKPARENT 339flag does not always result in the parent vnode being locked. 340This results in complications when the 341.Dv LOCKPARENT 342is used. 343In order to solve this for the cases where both 344.Dv LOCKPARENT 345and 346.Dv LOCKLEAF 347are used, it is necessary to resort to recursive locking. 348.Pp 349Non-MPSAFE file systems exist, requiring callers to conditionally unlock 350.Va Giant . 351