1.\" $NetBSD: namei.9,v 1.4 2002/10/14 13:43:27 wiz Exp $ 2.\" 3.\" Copyright (c) 2001 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Gregory McGarry. 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.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd October 13, 2001 38.Dt NAMEI 9 39.Os 40.Sh NAME 41.Nm namei , 42.Nm lookup , 43.Nm relookup , 44.Nm NDINIT 45.Nd pathname lookup 46.Sh SYNOPSIS 47.Fd #include \*[Lt]sys/namei.h\*[Gt] 48.Fd #include \*[Lt]sys/proc.h\*[Gt] 49.Fd #include \*[Lt]sys/uio.h\*[Gt] 50.Fd #include \*[Lt]sys/vnode.h\*[Gt] 51.Ft int 52.Fn namei "struct nameidata *ndp" 53.Ft int 54.Fn lookup "struct nameidata *ndp" 55.Ft int 56.Fn relookup "struct vnode *dvp" "struct vnode **vpp" \ 57"struct componentname *cnp" 58.Ft void 59.Fn NDINIT "struct namidata *ndp" "u_long op" "u_long flags" \ 60"enum uio_seg segflg" "const char *namep" "struct proc *p" 61.Sh DESCRIPTION 62The 63.Nm 64interface is used to convert pathnames to file system vnodes. 65The 66name of the interface is actually a contraction of the words 67.Em name 68and 69.Em inode 70for name-to-inode conversion, in the days before the 71.Xr vfs 9 72interface was implemented. 73.Pp 74The arguments passed to the functions are uncapsulated in the 75.Em nameidata 76structure. 77It has the following structure: 78.Bd -literal 79struct nameidata { 80 /* 81 * Arguments to namei/lookup. 82 */ 83 const char *ni_dirp; /* pathname pointer */ 84 enum uio_seg ni_segflg; /* location of pathname */ 85 /* 86 * Arguments to lookup. 87 */ 88 struct vnode *ni_startdir; /* starting directory */ 89 struct vnode *ni_rootdir; /* logical root directory */ 90 /* 91 * Results: returned from/manipulated by lookup 92 */ 93 struct vnode *ni_vp; /* vnode of result */ 94 struct vnode *ni_dvp; /* vnode of intermediate dir */ 95 /* 96 * Shared between namei and lookup/commit routines. 97 */ 98 size_t ni_pathlen; /* remaining chars in path */ 99 const char *ni_next; /* next location in pathname */ 100 u_long ni_loopcnt; /* count of symlinks encountered */ 101 /* 102 * Lookup parameters 103 */ 104 struct componentname ni_cnd; 105}; 106.Ed 107.Pp 108The 109.Nm 110interface accesses vnode operations by passing arguments in the 111partially initialised 112.Em componentname 113structure 114.Em ni_cnd . 115This structure describes the subset of information from the nameidata 116structure that is passed through to the vnode operations. 117See 118.Xr vnodeops 9 119for more information. 120The details of the componentname structure are not absolutely necessary 121since the members are initialised by the helper macro 122.Fn NDINIT . 123It is useful to know the operations and flags as specified in 124.Xr vnodeops 9 . 125.Pp 126The 127.Nm 128interface overloads 129.Em ni_cnd.cn_flags 130with some additional flags. 131These flags should be specific to the 132.Nm 133interface and ignored by vnode operations. 134However, due to the historic close relationship between the 135.Nm 136interface and the vnode operations, these flags are sometimes used 137(and set) by vnode operations, particularly 138.Fn VOP_LOOKUP . 139The additional flags are: 140.Pp 141.Bl -tag -offset indent -width NOCROSSMOUNT -compact 142.It NOCROSSMOUNT 143do not cross mount points 144.It RDONLY 145lookup with read-only semantics 146.It HASBUF 147caller has allocated pathname buffer 148.Em ni_cnd.cn_pnbuf 149.It SAVENAME 150save pathname buffer 151.It SAVESTART 152save starting directory 153.It ISDOTDOT 154current pathname component is .. 155.It MAKEENTRY 156add entry to the name cache 157.It ISLASTCN 158this is last component of pathname 159.It ISSYMLINK 160symlink needs interpretation 161.It ISWHITEOUT 162found whiteout 163.It DOWHITEOUT 164do whiteouts 165.It REQUIREDIR 166must be a directory 167.It PDIRUNLOCK 168vfs_lookup() unlocked parent dir 169.It PARAMASK 170mask of parameter descriptors 171.El 172.Pp 173If the caller of 174.Fn namei 175sets the SAVENAME flag, then it must free the buffer. 176If 177.Fn VOP_LOOKUP 178sets the flag, then the buffer must be freed by either the commit 179routine or the 180.Fn VOP_ABORT 181routine. 182The SAVESTART flag is set only by the callers of 183.Fn namei . 184It implies SAVENAME plus the addition of saving the parent directory 185that contains the name in 186.Em ni_startdir . 187It allows repeated calls to 188.Fn lookup 189for the name being sought. 190The caller is responsible for releasing the buffer and for invoking 191.Fn vrele 192on 193.Em ni_startdir . 194.Pp 195All access to the 196.Nm 197interface must be in process context. 198Pathname lookups cannot be done in interrupt context. 199.Sh FUNCTIONS 200.Bl -tag -width compact 201.It Fn namei "ndp" 202Convert a pathname into a pointer to a locked inode. 203The pathname is specified by 204.Em ndp-\*[Gt]ni_dirp 205and is of length 206.Em ndp-\*[Gt]ni_pathlen . 207The 208.Em ndp-\*[Gt]segflg 209flags defines whether the name in 210.Em ndp-\*[Gt]ni_dirp 211is an address in kernel space (UIO_SYSSPACE) or an address in user 212space (UIO_USERSPACE). 213The locked vnode for the pathname is returned in 214.Em ndp-\*[Gt]ni_vp . 215.Pp 216If 217.Em ndp-\*[Gt]ni_cnd.cn_flags 218has the FOLLOW flag set then symbolic links are followed when they 219occur at the end of the name translation process. 220Symbolic links are always followed for all other pathname components 221other than the last. 222.It Fn lookup "ndp" 223Search for a pathname. 224This is a very central and rather complicated routine. 225.Pp 226The pathname is specified by 227.Em ndp-\*[Gt]ni_dirp 228and is of length 229.Em ndp-\*[Gt]ni_pathlen . 230The starting directory is taken from 231.Em ndp-\*[Gt]ni_startdir . 232The pathname is descended until done, or a symbolic link is 233encountered. 234.Pp 235The semantics of 236.Fn lookup 237are altered by the operation specified by 238.Em ndp-\*[Gt]ni_cnd.cn_nameiop . 239When CREATE, RENAME, or DELETE is specified, information usable in 240creating, renaming, or deleting a directory entry may be calculated. 241.Pp 242If 243.Em ndp-\*[Gt]ci_cnd.cn_flags 244has LOCKPARENT set, the parent directory is returned locked in 245.Em ndp-\*[Gt]ni_dvp . 246If WANTPARENT is set, the parent directory is returned unlocked. 247Otherwise the parent directory is not returned. 248If the target of the pathname exists and LOCKLEAF is set, the target 249is returned locked in 250.Em ndp-\*[Gt]ni_vp , 251otherwise it is returned unlocked. 252.It Fn relookup "dvp" "vpp" "cnp" 253Reacquire a path name component is a directory. 254This is a quicker way to lookup a pathname component when the parent 255directory is known. 256The unlocked parent directory vnode is specified by 257.Fa dvp 258and the pathname component by 259.Fa cnp . 260The vnode of the pathname is returned in the address specified by 261.Fa vpp . 262.It Fn NDINIT "ndp" "op" "flags" "segflg" "namep" "p" 263Initialise a nameidata structure pointed to by 264.Fa ndp 265for use by the 266.Nm 267interface. 268It saves having to deal with the componentname structure inside 269.Fa ndp . 270The operation and flags are specified by 271.Fa op 272and 273.Fa flags 274respectively. 275These are the values 276.Em ndp-\*[Gt]ni_cnd.cn_nameiop 277and 278.Em ndp-\*[Gt]ni_cnd.cn_flags 279are respectively set to. 280The segment flags which defines whether the pathname is in kernel 281address space or user address space is specified by 282.Fa segflag . 283The argument 284.Fa namep 285is a pointer to the pathname that 286.Em ndp-\*[Gt]ni_dirp 287is set to and 288.Fa p 289is the calling process. 290.El 291.Sh CODE REFERENCES 292This section describes places within the 293.Nx 294source tree where actual code implementing or utilising the name 295lookup subsystem can be found. 296All pathnames are relative to 297.Pa /usr/src . 298.Pp 299The name lookup subsystem is implemented within the file 300.Pa sys/kern/vfs_lookup.c . 301.Sh SEE ALSO 302.Xr intro 9 , 303.Xr namecache 9 , 304.Xr vfs 9 , 305.Xr vnode 9 , 306.Xr vnodeops 9 307.Sh BUGS 308It is unfortunate that much of the 309.Nm 310interface makes assumptions on the underlying vnode operations. 311These assumptions are an artefact of the introduction of the vfs 312interface to split a file system interface which was historically 313designed as a tightly coupled module. 314