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