1.\" 2.\" Copyright (c) 1998, 1999 Eivind Eklund 3.\" Copyright (c) 2003 Hiten M. Pandya 4.\" 5.\" All rights reserved. 6.\" 7.\" This program is free software. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR 19.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 20.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 21.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, 22.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 23.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 24.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 25.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 26.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 27.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 28.\" 29.\" 30.\" If you integrate this manpage in another OS, I'd appreciate a note 31.\" - eivind@FreeBSD.org 32.\" 33.\" $FreeBSD$ 34.\" 35.Dd May 27, 2003 36.Os 37.Dt NAMEI 9 38.Sh NAME 39.Nm namei , 40.Nm NDINIT , 41.Nm NDFREE 42.Nd pathname translation and lookup operations 43.Sh SYNOPSIS 44.In sys/param.h 45.In sys/proc.h 46.In sys/namei.h 47.Ft int 48.Fn namei "struct nameidata *ndp" 49.Ft void 50.Fo NDINIT 51.Fa "struct nameidata *ndp" "u_long op" "u_long flags" 52.Fa "enum uio_seg segflg" "const char *namep" "struct thread *td" 53.Fc 54.Ft void 55.Fn NDFREE "struct nameidata *ndp" "const uint flags" 56.Sh DESCRIPTION 57The 58.Nm 59facility allows the client to perform pathname translation and lookup 60operations. 61The 62.Nm 63functions will increment the reference count for the vnode in question. 64The reference count has to be decremented after use of the vnode, by 65using either 66.Xr vrele 9 67or 68.Xr vput 9 , 69depending on whether the 70.Dv LOCKLEAF 71flag was specified or not. 72.Pp 73The 74.Fn NDINIT 75function is used to initialize 76.Nm 77components. 78It takes the following arguments: 79.Bl -tag -width ".Fa segflg" 80.It Fa ndp 81The 82.Vt "struct nameidata" 83to initialize. 84.It Fa op 85The operation which 86.Fn namei 87will perform. 88The following operations are valid: 89.Dv LOOKUP , CREATE , DELETE , 90and 91.Dv RENAME . 92The latter three are just setup for those 93effects; just calling 94.Fn namei 95will not result in 96.Fn VOP_RENAME 97being called. 98.It Fa flags 99Operation flags. 100Several of these can be effective at the same time. 101.It Fa segflg 102UIO segment indicator. 103This indicates if the name of the object is in userspace 104.Pq Dv UIO_USERSPACE 105or in the kernel address space 106.Pq Dv UIO_SYSSPACE . 107.It Fa namep 108Pointer to the component's pathname buffer 109(the file or directory name that will be looked up). 110.It Fa td 111The thread context to use for 112.Nm 113operations and locks. 114.El 115.Sh NAMEI OPERATION FLAGS 116The 117.Fn namei 118function takes the following set of 119.Dq "operation flags" 120that influence its operation: 121.Bl -tag -width ".Dv WANTPARENT" 122.It Dv LOCKLEAF 123Lock vnode on return. 124This is a full lock of the vnode; the 125.Xr VOP_UNLOCK 9 126should be used 127to release the lock (or 128.Xr vput 9 129which is equivalent to calling 130.Xr VOP_UNLOCK 9 131followed by 132.Xr vrele 9 , 133all in one). 134.It Dv LOCKPARENT 135This flag lets the 136.Fn namei 137function return the parent (directory) vnode, 138.Va ni_dvp 139in locked state, unless it is identical to 140.Va ni_vp , 141in which case 142.Va ni_dvp 143is not locked per se (but may be locked due to 144.Dv LOCKLEAF ) . 145If a lock is enforced, it should be released using 146.Xr vput 9 147or 148.Xr VOP_UNLOCK 9 149and 150.Xr vrele 9 . 151.It Dv WANTPARENT 152This flag allows the 153.Fn namei 154function to return the parent (directory) vnode in an unlocked state. 155The parent vnode must be released separately by using 156.Xr vrele 9 . 157.It Dv NOCACHE 158Avoid 159.Fn namei 160creating this entry in the namecache if it is not 161already present. 162Normally, 163.Fn namei 164will add entries to the name cache 165if they are not already there. 166.It Dv FOLLOW 167With this flag, 168.Fn namei 169will follow the symbolic link if the last part 170of the path supplied is a symbolic link (i.e., it will return a vnode 171for whatever the link points at, instead for the link itself). 172.It Dv NOOBJ 173Do not call 174.Fn vfs_object_create 175for the returned vnode, even though it meets required criteria for VM support. 176.It Dv NOFOLLOW 177Do not follow symbolic links (pseudo). 178This flag is not looked for by the actual code, which looks for 179.Dv FOLLOW . 180.Dv NOFOLLOW 181is used to indicate to the source code reader that symlinks 182are intentionally not followed. 183.It Dv SAVENAME 184Do not free the pathname buffer at the end of the 185.Fn namei 186invocation; instead, free it later in 187.Fn NDFREE 188so that the caller may access the pathname buffer. 189See below for details. 190.It Dv SAVESTART 191Retain an additional reference to the parent directory; do not free 192the pathname buffer. 193See below for details. 194.El 195.Sh ALLOCATED ELEMENTS 196The 197.Vt nameidata 198structure is composed of the following fields: 199.Bl -tag -width ".Va ni_cnd.cn_pnbuf" 200.It Va ni_startdir 201In the normal case, this is either the current directory or the root. 202It is the current directory if the name passed in does not start with 203.Ql / 204and we have not gone through any symlinks with an absolute path, and 205the root otherwise. 206.Pp 207In this case, it is only used by 208.Fn lookup , 209and should not be 210considered valid after a call to 211.Fn namei . 212If 213.Dv SAVESTART 214is set, this is set to the same as 215.Va ni_dvp , 216with an extra 217.Xr vref 9 . 218To block 219.Fn NDFREE 220from releasing 221.Va ni_startdir , 222the 223.Dv NDF_NO_STARTDIR_RELE 224can be set. 225.It Va ni_dvp 226Vnode pointer to directory of the object on which lookup is performed. 227This is available on successful return if 228.Dv LOCKPARENT 229or 230.Dv WANTPARENT 231is set. 232It is locked if 233.Dv LOCKPARENT 234is set. 235Freeing this in 236.Fn NDFREE 237can be inhibited by 238.Dv NDF_NO_DVP_RELE , NDF_NO_DVP_PUT , 239or 240.Dv NDF_NO_DVP_UNLOCK 241(with the obvious effects). 242.It Va ni_vp 243Vnode pointer to the resulting object, 244.Dv NULL 245otherwise. 246The 247.Va v_usecount 248field of this vnode is incremented. 249If 250.Dv LOCKLEAF 251is set, it is also locked. 252.Pp 253Freeing this in 254.Fn NDFREE 255can be inhibited by 256.Dv NDF_NO_VP_RELE , NDF_NO_VP_PUT , 257or 258.Dv NDF_NO_VP_UNLOCK 259(with the obvious effects). 260.It Va ni_cnd.cn_pnbuf 261The pathname buffer contains the location of the file or directory 262that will be used by the 263.Nm 264operations. 265It is managed by the 266.Xr uma 9 267zone allocation interface. 268If the 269.Dv SAVESTART 270or 271.Dv SAVENAME 272flag is set, then the pathname buffer is available 273after calling the 274.Fn namei 275function. 276.Pp 277To only deallocate resources used by the pathname buffer, 278.Va ni_cnd.cn_pnbuf , 279then 280.Dv NDF_ONLY_PNBUF 281flag can be passed to the 282.Fn NDFREE 283function. 284To keep the pathname buffer intact, 285the 286.Dv ND_NO_FREE_PNBUF 287flag can be passed to the 288.Fn NDFREE 289function. 290.El 291.Sh FILES 292.Bl -tag 293.It Pa src/sys/kern/vfs_lookup.c 294.El 295.Sh SEE ALSO 296.Xr uio 9 , 297.Xr uma 9 , 298.Xr VFS 9 , 299.Xr vnode 9 , 300.Xr vput 9 , 301.Xr vref 9 302.Sh AUTHORS 303.An -nosplit 304This manual page was written by 305.An Eivind Eklund Aq eivind@FreeBSD.org 306and later significantly revised by 307.An Hiten M. Pandya Aq hmp@FreeBSD.org . 308.Sh BUGS 309The 310.Dv LOCKPARENT 311flag does not always result in the parent vnode being locked. 312This results in complications when the 313.Dv LOCKPARENT 314is used. 315In order to solve this for the cases where both 316.Dv LOCKPARENT 317and 318.Dv LOCKLEAF 319are used, it is necessary to resort to recursive locking. 320