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