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.El 155.Sh ALLOCATED ELEMENTS 156.Bl -tag -width WANTPARENT 157.It Dv ni_startdir 158Where we did lookup relative to. 159In the normal case, this is either the current directory or the root. 160It is the current directory if the name passed in doesn't start with / 161and we have not gone through any symlinks with an absolute path, and 162the root otherwise. 163.Pp 164In this case, it is only used by 165.Fn lookup , 166and should not be 167considered valid after a call to 168.Fn namei . 169.Pp 170If SAVESTART is set, this is set to the same as ni_dvp, with an extra 171.Fn VREF . 172.Pp 173To block NDFREE from releasing ni_startdir when it is set, use the 174flag NDF_NO_STARTDIR_RELE. 175.It Dv ni_dvp 176The directory vp for the directory the object we're looking up is in. 177This is available on successful return if LOCKPARENT or WANTPARENT is 178set. It is locked if LOCKPARENT is set. Freeing this in NDFREE can 179be inhibited by NDF_NO_DVP_RELE, NDF_NO_DVP_PUT, or NDF_NO_DVP_UNLOCK 180(with the obvious effects). 181.It Dv ni_vp 182The vp for the target of the of the pathname exists, NULL otherwise. 183The vp is returned with increased reference count (VREF'ed). If 184LOCKLEAF is set, it is also locked. 185.Pp 186Freeing this in NDFREE can be inhibited by NDF_NO_VP_RELE, 187NDF_NO_VP_PUT, or NDF_NO_VP_UNLOCK (with the obvious effects). 188.It Dv ni_cnd.cn_pnbuf 189Path name buffer. This is allocated through zalloc(namei_zone) 190and freed through zfree(namei_zone, ...). 191.Pp 192This is available to the caller (who must free it using 193.Xr NDFREE 9 ) 194if SAVESTART or SAVENAME is set. 195To free only the ni_cnd.cn_pnbuf, there is a special flags NDF_ONLY_PNBUF. 196To not free the cnd, use the flag ND_NO_FREE_PNBUF. 197.El 198.Sh BUGS 199LOCKPARENT does not always result in parent vp being locked (see details in 200description). 201This results in complications everywhere LOCKPARENT is used. 202In order to solve this for the cases that include both LOCKPARENT and LOCKLEAF, 203it will be necessary to go to recursive locking. 204.Sh SEE ALSO 205.Xr VFS 9 , 206.Xr vnode 9 207.Pp 208.Pa src/sys/kern/vfs_lookup.c 209.Sh AUTHORS 210This man page was written by 211.An Eivind Eklund . 212