1.\" -*- nroff -*- 2.\" 3.\" Copyright (c) 1998, 1999 Eivind Eklund 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 December 16, 1998 36.Os 37.Dt NAMEI 9 38.Sh NAME 39.Nm namei , 40.Nm NDINIT 41.Nd convert pathname to a pointer to a locked vnode 42.Sh SYNOPSIS 43.In sys/param.h 44.In sys/proc.h 45.In sys/namei.h 46.Ft int 47.Fn namei "struct nameidata *ndp" 48.Ft void 49.Fn NDINIT "struct nameidata *ndp" "u_long operation" "u_long operflags" "enum uio_seg segflag" "const char *path" "struct thread *td" 50.Ft void 51.Fn NDFREE "struct nameidata *ndp" "u_int operflags" 52.Sh DESCRIPTION 53.Fn namei 54is used to get from a pathname to a vnode for the object. 55This is a necessity to start doing VFS operations. The vnode 56returned will have its reference count increased; when you're through 57with it, you have to release it using either 58.Xr vrele 9 59or 60.Xr vput 9 , 61depending on whether you specified the LOCKLEAF flag or not. 62.Pp 63To initialize the nameidata struct, you usually use 64.Fn NDINIT . 65It takes the following arguments: 66.Pp 67.Bl -tag -width nameidatap 68.It Ar nameidatap 69pointer to the struct nameidata to initialize 70.It Ar operation 71The operation to have 72.Fn namei 73do. The relevant operations are 74.Dv LOOKUP , 75.Dv CREATE , 76.Dv DELETE , 77and 78.Dv RENAME . 79The latter three are just setup for those 80effects; just calling 81.Fn namei 82will not result in 83.Fn VOP_RENAME 84being called. 85.It Ar operflags 86Operation flags. Several of these can be effective at the same time. 87.It Ar segflag 88Segment indicator. This tells if the name of the object is in 89userspace (UIO_USERSPACE) or in the kernel address space (UIO_SYSSPACE). 90.It Ar path 91Pointer to pathname buffer (the file or directory name that will be 92looked up) 93.It Ar td 94Which thread context to use for the 95.Fn namei 96locks. 97.El 98.Sh NAMEI OPERATION FLAGS 99.Fn namei 100takes the following set of 'operation flags' that influence 101how it operates: 102.Bl -tag -width WANTPARENT 103.It Dv LOCKLEAF 104Lock vnode on return. This is a full lock of the vnode; you'll have to use 105.Xr VOP_UNLOCK 9 106to release the lock (or use 107.Xr vput 9 108to release the lock and do a 109.Xr vrele 9 , 110all in one). 111.It Dv LOCKPARENT 112Make 113.Fn namei 114also return the parent (directory) vnode (in nd.ni_dvp), 115in locked state, unless the dvp is identical to the vp, in which case the dvp 116is not locked per se (but may be locked due to LOCKLEAF). 117If you get a lock, remember to release the lock (using 118.Xr vput 9 119or 120.Xr VOP_UNLOCK 9 121and 122.Xr vrele 9 . ) 123.It Dv WANTPARENT 124Make 125.Fn namei 126also return the parent (directory) vnode, in unlocked 127state. Remember to release it (using 128.Xr vrele 9 . ) 129.It Dv NOCACHE 130Avoid 131.Fn namei 132creating this entry in the namecache if it is not 133already present. Normally 134.Fn namei 135will add entries to the name cache 136if they're not already there. 137.It Dv FOLLOW 138With this flag, 139.Fn namei 140will follow the symbolic link if the last part 141of the path supplied is a symbolic link (i.e., it will return a vnode 142for whatever the link points at, instead for the link itself). 143.It Dv NOOBJ 144Do not call 145.Fn vfs_object_create 146for the returned vnode even if it is 147just a VREG and we're able to (ie, it is locked). 148.It Dv NOFOLLOW 149Do not follow symbolic links (pseudo). 150This flag is not looked for by the actual code, which looks for 151FOLLOW. 152NOFOLLOW is used to indicate to the source code reader that symlinks 153are intentionally not followed. 154.It Dv SAVENAME 155Do not free the name buffer at the end of the 156.Fn namei 157invocation, instead free it later in 158.Fn NDFREE 159so that the caller may access the name buffer. 160See below for details. 161.It Dv SAVESTART 162Retain an additional reference to the parent directory; do not free 163the name buffer. 164See below for details. 165.El 166.Sh ALLOCATED ELEMENTS 167.Bl -tag -width WANTPARENT 168.It Dv ni_startdir 169Where we did lookup relative to. 170In the normal case, this is either the current directory or the root. 171It is the current directory if the name passed in doesn't start with / 172and we have not gone through any symlinks with an absolute path, and 173the root otherwise. 174.Pp 175In this case, it is only used by 176.Fn lookup , 177and should not be 178considered valid after a call to 179.Fn namei . 180.Pp 181If SAVESTART is set, this is set to the same as ni_dvp, with an extra 182.Fn VREF . 183.Pp 184To block NDFREE from releasing ni_startdir when it is set, use the 185flag NDF_NO_STARTDIR_RELE. 186.It Dv ni_dvp 187The directory vp for the directory the object we're looking up is in. 188This is available on successful return if LOCKPARENT or WANTPARENT is 189set. It is locked if LOCKPARENT is set. Freeing this in NDFREE can 190be inhibited by NDF_NO_DVP_RELE, NDF_NO_DVP_PUT, or NDF_NO_DVP_UNLOCK 191(with the obvious effects). 192.It Dv ni_vp 193The vp for the target of the of the pathname exists, NULL otherwise. 194The vp is returned with increased reference count (VREF'ed). If 195LOCKLEAF is set, it is also locked. 196.Pp 197Freeing this in NDFREE can be inhibited by NDF_NO_VP_RELE, 198NDF_NO_VP_PUT, or NDF_NO_VP_UNLOCK (with the obvious effects). 199.It Dv ni_cnd.cn_pnbuf 200Path name buffer. This is allocated through zalloc(namei_zone) 201and freed through zfree(namei_zone, ...). 202.Pp 203This is available to the caller (who must free it using 204.Xr NDFREE 9 ) 205if SAVESTART or SAVENAME is set. 206To free only the ni_cnd.cn_pnbuf, there is a special flags NDF_ONLY_PNBUF. 207To not free the cnd, use the flag ND_NO_FREE_PNBUF. 208.El 209.Sh BUGS 210LOCKPARENT does not always result in parent vp being locked (see details in 211description). 212This results in complications everywhere LOCKPARENT is used. 213In order to solve this for the cases that include both LOCKPARENT and LOCKLEAF, 214it will be necessary to go to recursive locking. 215.Sh SEE ALSO 216.Xr VFS 9 , 217.Xr vnode 9 218.Pp 219.Pa src/sys/kern/vfs_lookup.c 220.Sh AUTHORS 221This man page was written by 222.An Eivind Eklund . 223