1.\" $NetBSD: namei.9,v 1.3 2002/02/13 08:18:47 ross 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. The 65name of the interface is actually a contraction of the words 66.Em name 67and 68.Em inode 69for name-to-inode conversion, in the days before the 70.Xr vfs 9 71interface was implemented. 72.Pp 73The arguments passed to the functions are uncapsulated in the 74.Em nameidata 75structure. It has the following structure: 76.Bd -literal 77struct nameidata { 78 /* 79 * Arguments to namei/lookup. 80 */ 81 const char *ni_dirp; /* pathname pointer */ 82 enum uio_seg ni_segflg; /* location of pathname */ 83 /* 84 * Arguments to lookup. 85 */ 86 struct vnode *ni_startdir; /* starting directory */ 87 struct vnode *ni_rootdir; /* logical root directory */ 88 /* 89 * Results: returned from/manipulated by lookup 90 */ 91 struct vnode *ni_vp; /* vnode of result */ 92 struct vnode *ni_dvp; /* vnode of intermediate dir */ 93 /* 94 * Shared between namei and lookup/commit routines. 95 */ 96 size_t ni_pathlen; /* remaining chars in path */ 97 const char *ni_next; /* next location in pathname */ 98 u_long ni_loopcnt; /* count of symlinks encountered */ 99 /* 100 * Lookup parameters 101 */ 102 struct componentname ni_cnd; 103}; 104.Ed 105.Pp 106The 107.Nm 108interface accesses vnode operations by passing arguments in the 109partially initialised 110.Em componentname 111structure 112.Em ni_cnd . 113This structure describes the subset of information from the nameidata 114structure that is passed through to the vnode operations. See 115.Xr vnodeops 9 116for more information. The details of the componentname structure are 117not absolutely necessary since the members are initialised by the 118helper macro 119.Fn NDINIT . 120It is useful to know the operations and flags as specified in 121.Xr vnodeops 9 . 122.Pp 123The 124.Nm 125interface overloads 126.Em ni_cnd.cn_flags 127with some additional flags. These flags should be specific to the 128.Nm 129interface and ignored by vnode operations. However, due to the 130historic close relationship between the 131.Nm 132interface and the vnode operations, these flags are sometimes used 133(and set) by vnode operations, particularly 134.Fn VOP_LOOKUP . 135The additional flags are: 136.Pp 137.Bl -tag -offset indent -width NOCROSSMOUNT -compact 138.It NOCROSSMOUNT 139do not cross mount points 140.It RDONLY 141lookup with read-only semantics 142.It HASBUF 143caller has allocated pathname buffer 144.Em ni_cnd.cn_pnbuf 145.It SAVENAME 146save pathname buffer 147.It SAVESTART 148save starting directory 149.It ISDOTDOT 150current pathname component is .. 151.It MAKEENTRY 152add entry to the name cache 153.It ISLASTCN 154this is last component of pathname 155.It ISSYMLINK 156symlink needs interpretation 157.It ISWHITEOUT 158found whiteout 159.It DOWHITEOUT 160do whiteouts 161.It REQUIREDIR 162must be a directory 163.It PDIRUNLOCK 164vfs_lookup() unlocked parent dir 165.It PARAMASK 166mask of parameter descriptors 167.El 168.Pp 169If the caller of 170.Fn namei 171sets the SAVENAME flag, then it must free the buffer. If 172.Fn VOP_LOOKUP 173sets the flag, then the buffer must be freed by either the commit 174routine or the 175.Fn VOP_ABORT 176routine. The SAVESTART flag is set only by the callers of 177.Fn namei . 178It implies SAVENAME plus the addition of saving the parent directory 179that contains the name in 180.Em ni_startdir . 181It allows repeated calls to 182.Fn lookup 183for the name being sought. The caller is responsible for releasing 184the buffer and for invoking 185.Fn vrele 186on 187.Em ni_startdir . 188.Pp 189All access to the 190.Nm 191interface must be in process context. Pathname lookups cannot be done 192in interrupt context. 193.Sh FUNCTIONS 194.Bl -tag -width compact 195.It Fn namei "ndp" 196Convert a pathname into a pointer to a locked inode. The pathname is 197specified by 198.Em ndp-\*[Gt]ni_dirp 199and is of length 200.Em ndp-\*[Gt]ni_pathlen . 201The 202.Em ndp-\*[Gt]segflg 203flags defines whether the name in 204.Em ndp-\*[Gt]ni_dirp 205is an address in kernel space (UIO_SYSSPACE) or an address in user 206space (UIO_USERSPACE). The locked vnode for the pathname is returned 207in 208.Em ndp-\*[Gt]ni_vp . 209.Pp 210If 211.Em ndp-\*[Gt]ni_cnd.cn_flags 212has the FOLLOW flag set then symbolic links are followed when they 213occur at the end of the name translation process. Symbolic links are 214always followed for all other pathname components other than the last. 215.It Fn lookup "ndp" 216Search for a pathname. This is a very central and rather complicated 217routine. 218.Pp 219The pathname is specified by 220.Em ndp-\*[Gt]ni_dirp 221and is of length 222.Em ndp-\*[Gt]ni_pathlen . 223The starting directory is taken from 224.Em ndp-\*[Gt]ni_startdir . 225The pathname is descended until done, or a symbolic link is 226encountered. 227.Pp 228The semantics of 229.Fn lookup 230are altered by the operation specified by 231.Em ndp-\*[Gt]ni_cnd.cn_nameiop . 232When CREATE, RENAME, or DELETE is specified, information usable in 233creating, renaming, or deleting a directory entry may be calculated. 234.Pp 235If 236.Em ndp-\*[Gt]ci_cnd.cn_flags 237has LOCKPARENT set, the parent directory is returned locked in 238.Em ndp-\*[Gt]ni_dvp . 239If WANTPARENT is set, the parent directory is returned unlocked. 240Otherwise the parent directory is not returned. If the target of the 241pathname exists and LOCKLEAF is set, the target is returned locked in 242.Em ndp-\*[Gt]ni_vp , 243otherwise it is returned unlocked. 244.It Fn relookup "dvp" "vpp" "cnp" 245Reacquire a path name component is a directory. This is a quicker way 246to lookup a pathname component when the parent directory is known. 247The unlocked parent directory vnode is specified by 248.Fa dvp 249and the pathname component by 250.Fa cnp . 251The vnode of the pathname is returned in the address specified by 252.Fa vpp . 253.It Fn NDINIT "ndp" "op" "flags" "segflg" "namep" "p" 254Initialise a nameidata structure pointed to by 255.Fa ndp 256for use by the 257.Nm 258interface. It saves having to deal with the componentname structure 259inside 260.Fa ndp . 261The operation and flags are specified by 262.Fa op 263and 264.Fa flags 265respectively. These are the values 266.Em ndp-\*[Gt]ni_cnd.cn_nameiop 267and 268.Em ndp-\*[Gt]ni_cnd.cn_flags 269are respectively set to. The segment flags which defines whether the 270pathname is in kernel address space or user address space is specified 271by 272.Fa segflag . 273The argument 274.Fa namep 275is a pointer to the pathname that 276.Em ndp-\*[Gt]ni_dirp 277is set to and 278.Fa p 279is the calling process. 280.El 281.Sh CODE REFERENCES 282This section describes places within the 283.Nx 284source tree where actual code implementing or utilising the name 285lookup subsystem can be found. All pathnames are relative to 286.Pa /usr/src . 287.Pp 288The name lookup subsystem is implemented within the file 289.Pa sys/kern/vfs_lookup.c . 290.Sh SEE ALSO 291.Xr intro 9 , 292.Xr namecache 9 , 293.Xr vfs 9 , 294.Xr vnode 9 , 295.Xr vnodeops 9 296.Sh BUGS 297It is unfortunate that much of the 298.Nm 299interface makes assumptions on the underlying vnode operations. These 300assumptions are an artefact of the introduction of the vfs interface 301to split a file system interface which was historically designed as a 302tightly coupled module. 303