1.\" -*- nroff -*- 2.\" 3.\" Copyright (c) 1998 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 September 26th, 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" "int operation" "int operflags" "int segflag" "const char *path" "struct proc *proc" 49 50.Sh DESCRIPTION 51 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 ndp->dvp), 114in locked state. Remember to release it (using 115.Xr vput 9 116or 117.Xr VOP_UNLOCK 9 118and 119.Xr vrele 9 .) 120.It Dv WANTPARENT 121Make 122.Fn namei 123also return the parent (directory) vnode, in unlocked 124state. Remember to release it (using 125.Xr vrele 9 .) 126.It Dv NOCACHE 127Avoid 128.Fn namei 129creating this entry in the namecache if it is not 130already present. Normally 131.Fn namei 132will add entries to the name cache 133if they're not already there. 134.It Dv FOLLOW 135With this flag, 136.Fn namei 137will follow the symbolic link if the last part 138of the path supplied is a symbolic link (i.e., it will return a vnode 139for whatever the link points at, instead for the link itself). 140.It Dv NOOBJ 141Do not call 142.Fn vfs_object_create 143for the returned vnode even if it is 144just a VREG and we're able to (ie, it is locked). 145.It Dv NOFOLLOW 146Do not follow symbolic links (pseudo). This flag does not seem to be 147honoured by the actual code. 148.El 149.Sh BUGS 150.Fn namei 151calls 152.Fn lookup 153for each component in the pathname, instead of 154handing the actual names onwards to the stacking layers. This hinders 155the implementation of stacking layers that do full namespace escapes. 156.Sh SEE ALSO 157.Xr VFS 9 , 158.Xr vnode 9 , 159.Pa src/sys/kern/vfs_lookup.c 160.Sh AUTHORS 161This man page was written by 162.An Eivind Eklund . 163