1.\" $NetBSD: namei.9,v 1.16 2007/06/30 18:55:19 pooka Exp $ 2.\" 3.\" Copyright (c) 2001, 2005, 2006 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 June 30, 2007 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.In sys/namei.h 48.In sys/lwp.h 49.In sys/uio.h 50.In sys/vnode.h 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 nameidata *ndp" "u_long op" "u_long flags" \ 60"enum uio_seg segflg" "const char *namep" "struct lwp *l" 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 encapsulated 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 { 105 /* 106 * Arguments to lookup. 107 */ 108 u_long cn_nameiop; /* namei operation */ 109 u_long cn_flags; /* flags to namei */ 110 struct lwp *cn_lwp; /* lwp requesting lookup */ 111 kauth_cred_t cn_cred; /* credentials */ 112 /* 113 * Shared between lookup and commit routines. 114 */ 115 char *cn_pnbuf; /* pathname buffer */ 116 const char *cn_nameptr; /* pointer to looked up name */ 117 long cn_namelen; /* length of looked up component */ 118 u_long cn_hash; /* hash value of looked up name */ 119 long cn_consume; /* chars to consume in lookup() */ 120 } ni_cnd; 121}; 122.Ed 123.Pp 124The 125.Nm 126interface accesses vnode operations by passing arguments in the 127partially initialised 128.Em componentname 129structure 130.Em ni_cnd . 131This structure describes the subset of information from the nameidata 132structure that is passed through to the vnode operations. 133See 134.Xr vnodeops 9 135for more information. 136The details of the componentname structure are not absolutely necessary 137since the members are initialised by the helper macro 138.Fn NDINIT . 139It is useful to know the operations and flags as specified in 140.Xr vnodeops 9 . 141.Pp 142The 143.Nm 144interface overloads 145.Em ni_cnd.cn_flags 146with some additional flags. 147These flags should be specific to the 148.Nm 149interface and ignored by vnode operations. 150However, due to the historic close relationship between the 151.Nm 152interface and the vnode operations, these flags are sometimes used 153(and set) by vnode operations, particularly 154.Fn VOP_LOOKUP . 155The additional flags are: 156.Pp 157.Bl -tag -offset indent -width NOCROSSMOUNT -compact 158.It NOCROSSMOUNT 159do not cross mount points 160.It RDONLY 161lookup with read-only semantics 162.It HASBUF 163caller has allocated pathname buffer 164.Em ni_cnd.cn_pnbuf 165.It SAVENAME 166save pathname buffer 167.It SAVESTART 168save starting directory 169.It ISDOTDOT 170current pathname component is .. 171.It MAKEENTRY 172add entry to the name cache 173.It ISLASTCN 174this is last component of pathname 175.It ISSYMLINK 176symlink needs interpretation 177.It ISWHITEOUT 178found whiteout 179.It DOWHITEOUT 180do whiteouts 181.It REQUIREDIR 182must be a directory 183.It CREATEDIR 184trailing slashes are ok 185.It PARAMASK 186mask of parameter descriptors 187.El 188.Pp 189If the caller of 190.Fn namei 191sets the SAVENAME flag, then it must free the buffer. 192If 193.Fn VOP_LOOKUP 194sets the flag, then the buffer must be freed by either the commit 195routine or the 196.Fn VOP_ABORT 197routine. 198The SAVESTART flag is set only by the callers of 199.Fn namei . 200It implies SAVENAME plus the addition of saving the parent directory 201that contains the name in 202.Em ni_startdir . 203It allows repeated calls to 204.Fn lookup 205for the name being sought. 206The caller is responsible for releasing the buffer and for invoking 207.Fn vrele 208on 209.Em ni_startdir . 210.Pp 211All access to the 212.Nm 213interface must be in process context. 214Pathname lookups cannot be done in interrupt context. 215.Sh FUNCTIONS 216.Bl -tag -width compact 217.It Fn namei "ndp" 218Convert a pathname into a pointer to a vnode. 219The pathname is specified by 220.Em ndp-\*[Gt]ni_dirp 221and is of length 222.Em ndp-\*[Gt]ni_pathlen . 223The 224.Em ndp-\*[Gt]segflg 225flags defines whether the name in 226.Em ndp-\*[Gt]ni_dirp 227is an address in kernel space (UIO_SYSSPACE) or an address in user 228space (UIO_USERSPACE). 229.Pp 230The vnode for the pathname is returned in 231.Em ndp-\*[Gt]ni_vp . 232The parent directory is returned locked in 233.Em ndp-\*[Gt]ni_dvp 234iff LOCKPARENT is specified. 235.Pp 236If 237.Em ndp-\*[Gt]ni_cnd.cn_flags 238has the FOLLOW flag set then symbolic links are followed when they 239occur at the end of the name translation process. 240Symbolic links are always followed for all other pathname components 241other than the last. 242.It Fn lookup "ndp" 243Search for a pathname. 244This is a very central and rather complicated routine. 245.Pp 246The pathname is specified by 247.Em ndp-\*[Gt]ni_dirp 248and is of length 249.Em ndp-\*[Gt]ni_pathlen . 250The starting directory is taken from 251.Em ndp-\*[Gt]ni_startdir . 252The pathname is descended until done, or a symbolic link is 253encountered. 254.Pp 255The semantics of 256.Fn lookup 257are altered by the operation specified by 258.Em ndp-\*[Gt]ni_cnd.cn_nameiop . 259When CREATE, RENAME, or DELETE is specified, information usable in 260creating, renaming, or deleting a directory entry may be calculated. 261.Pp 262If the target of the pathname exists and LOCKLEAF is set, the target 263is returned locked in 264.Em ndp-\*[Gt]ni_vp , 265otherwise it is returned unlocked. 266.It Fn relookup "dvp" "vpp" "cnp" 267Reacquire a path name component is a directory. 268This is a quicker way to lookup a pathname component when the parent 269directory is known. 270The locked parent directory vnode is specified by 271.Fa dvp 272and the pathname component by 273.Fa cnp . 274The vnode of the pathname is returned in the address specified by 275.Fa vpp . 276.It Fn NDINIT "ndp" "op" "flags" "segflg" "namep" "l" 277Initialise a nameidata structure pointed to by 278.Fa ndp 279for use by the 280.Nm 281interface. 282It saves having to deal with the componentname structure inside 283.Fa ndp . 284The operation and flags are specified by 285.Fa op 286and 287.Fa flags 288respectively. 289These are the values to which 290.Em ndp-\*[Gt]ni_cnd.cn_nameiop 291and 292.Em ndp-\*[Gt]ni_cnd.cn_flags 293are respectively set. 294The segment flags which defines whether the pathname is in kernel 295address space or user address space is specified by 296.Fa segflag . 297The argument 298.Fa namep 299is a pointer to the pathname that 300.Em ndp-\*[Gt]ni_dirp 301is set to and 302.Fa l 303is the calling lwp. 304.El 305.Sh CODE REFERENCES 306This section describes places within the 307.Nx 308source tree where actual code implementing or using the name 309lookup subsystem can be found. 310All pathnames are relative to 311.Pa /usr/src . 312.Pp 313The name lookup subsystem is implemented within the file 314.Pa sys/kern/vfs_lookup.c . 315.Sh SEE ALSO 316.Xr intro 9 , 317.Xr namecache 9 , 318.Xr vfs 9 , 319.Xr vnode 9 , 320.Xr vnodeops 9 321.Sh BUGS 322It is unfortunate that much of the 323.Nm 324interface makes assumptions on the underlying vnode operations. 325These assumptions are an artefact of the introduction of the vfs 326interface to split a file system interface which was historically 327designed as a tightly coupled module. 328