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