1.\" $NetBSD: namei.9,v 1.24 2009/09/27 21:05:55 wiz 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 September 27, 2009 31.Dt NAMEI 9 32.Os 33.Sh NAME 34.Nm namei , 35.Nm lookup_for_nfsd , 36.Nm lookup_for_nfsd_index , 37.Nm relookup , 38.Nm NDINIT , 39.Nm namei_simple_kernel , 40.Nm namei_simple_user 41.Nd pathname lookup 42.Sh SYNOPSIS 43.In sys/namei.h 44.In sys/uio.h 45.In sys/vnode.h 46.Ft int 47.Fn namei "struct nameidata *ndp" 48.Ft int 49.Fn lookup_for_nfsd "struct nameidata *ndp" "struct vnode *startdir" \ 50"int neverfollow" 51.Ft int 52.Fn lookup_for_nfsd_index "struct nameidata *ndp" 53.Ft int 54.Fn relookup "struct vnode *dvp" "struct vnode **vpp" \ 55"struct componentname *cnp" 56.Ft void 57.Fn NDINIT "struct nameidata *ndp" "u_long op" "u_long flags" \ 58"enum uio_seg segflg" "const char *namep" 59.Ft int 60.Fn namei_simple_kernel "const char *path" "namei_simple_flags_t sflags" \ 61"struct vnode **ret" 62.Ft int 63.Fn namei_simple_user "const char *path" "namei_simple_flags_t sflags" \ 64"struct vnode **ret" 65.Sh DESCRIPTION 66The 67.Nm 68interface is used to convert pathnames to file system vnodes. 69The 70name of the interface is actually a contraction of the words 71.Em name 72and 73.Em inode 74for name-to-inode conversion, in the days before the 75.Xr vfs 9 76interface was implemented. 77.Pp 78Except for the simple forms, the arguments passed to the functions are 79encapsulated in the 80.Em nameidata 81structure. 82It has the following structure: 83.Bd -literal 84struct nameidata { 85 /* 86 * Arguments to namei/lookup. 87 */ 88 const char *ni_dirp; /* pathname pointer */ 89 enum uio_seg ni_segflg; /* location of pathname */ 90 /* 91 * Arguments to lookup. 92 */ 93 struct vnode *ni_startdir; /* starting directory */ 94 struct vnode *ni_rootdir; /* logical root directory */ 95 /* 96 * Results: returned from/manipulated by lookup 97 */ 98 struct vnode *ni_vp; /* vnode of result */ 99 struct vnode *ni_dvp; /* vnode of intermediate dir */ 100 /* 101 * Shared between namei and lookup/commit routines. 102 */ 103 size_t ni_pathlen; /* remaining chars in path */ 104 const char *ni_next; /* next location in pathname */ 105 u_long ni_loopcnt; /* count of symlinks encountered */ 106 /* 107 * Lookup parameters 108 */ 109 struct componentname { 110 /* 111 * Arguments to lookup. 112 */ 113 u_long cn_nameiop; /* namei operation */ 114 u_long cn_flags; /* flags to namei */ 115 kauth_cred_t cn_cred; /* credentials */ 116 /* 117 * Shared between lookup and commit routines. 118 */ 119 char *cn_pnbuf; /* pathname buffer */ 120 const char *cn_nameptr; /* pointer to looked up name */ 121 long cn_namelen; /* length of looked up component */ 122 u_long cn_hash; /* hash value of looked up name */ 123 long cn_consume; /* chars to consume in lookup() */ 124 } ni_cnd; 125}; 126.Ed 127.Pp 128The 129.Nm 130interface accesses vnode operations by passing arguments in the 131partially initialised 132.Em componentname 133structure 134.Em ni_cnd . 135This structure describes the subset of information from the nameidata 136structure that is passed through to the vnode operations. 137See 138.Xr vnodeops 9 139for more information. 140The details of the componentname structure are not absolutely necessary 141since the members are initialised by the helper macro 142.Fn NDINIT . 143It is useful to know the operations and flags as specified in 144.Xr vnodeops 9 . 145.Pp 146The 147.Nm 148interface overloads 149.Em ni_cnd.cn_flags 150with some additional flags. 151These flags should be specific to the 152.Nm 153interface and ignored by vnode operations. 154However, due to the historic close relationship between the 155.Nm 156interface and the vnode operations, these flags are sometimes used 157(and set) by vnode operations, particularly 158.Fn VOP_LOOKUP . 159The additional flags are: 160.Pp 161.Bl -tag -offset indent -width NOCROSSMOUNT -compact 162.It Dv NOCROSSMOUNT 163do not cross mount points 164.It Dv RDONLY 165lookup with read-only semantics 166.It Dv HASBUF 167caller has allocated pathname buffer 168.Em ni_cnd.cn_pnbuf 169.It Dv SAVENAME 170save pathname buffer 171.It Dv SAVESTART 172save starting directory 173.It Dv ISDOTDOT 174current pathname component is .. 175.It Dv MAKEENTRY 176add entry to the name cache 177.It Dv ISLASTCN 178this is last component of pathname 179.It Dv ISSYMLINK 180symlink needs interpretation 181.It Dv ISWHITEOUT 182found whiteout 183.It Dv DOWHITEOUT 184do whiteouts 185.It Dv REQUIREDIR 186must be a directory 187.It Dv CREATEDIR 188trailing slashes are ok 189.It Dv PARAMASK 190mask of parameter descriptors 191.El 192.Pp 193If the caller of 194.Fn namei 195sets the SAVENAME flag, then it must free the buffer. 196If 197.Fn VOP_LOOKUP 198sets the flag, then the buffer must be freed by either the commit 199routine or the 200.Fn VOP_ABORT 201routine. 202The 203.Dv SAVESTART 204flag is set only by the callers of 205.Fn namei . 206It implies 207.Dv SAVENAME 208plus the addition of saving the parent directory 209that contains the name in 210.Em ni_startdir . 211It allows repeated calls to 212.Fn lookup 213for the name being sought. 214The caller is responsible for releasing the buffer and for invoking 215.Fn vrele 216on 217.Em ni_startdir . 218.Pp 219All access to the 220.Nm 221interface must be in process context. 222Pathname lookups cannot be done in interrupt context. 223.Sh FUNCTIONS 224.Bl -tag -width compact 225.It Fn namei "ndp" 226Convert a pathname into a pointer to a vnode. 227The pathname is specified by 228.Em ndp-\*[Gt]ni_dirp 229and is of length 230.Em ndp-\*[Gt]ni_pathlen . 231The 232.Em ndp-\*[Gt]segflg 233flags defines whether the name in 234.Em ndp-\*[Gt]ni_dirp 235is an address in kernel space 236.Pq Dv UIO_SYSSPACE 237or an address in user space 238.Pq Dv UIO_USERSPACE . 239.Pp 240The vnode for the pathname is returned in 241.Em ndp-\*[Gt]ni_vp . 242The parent directory is returned locked in 243.Em ndp-\*[Gt]ni_dvp 244iff 245.Dv LOCKPARENT 246is specified. 247.Pp 248If 249.Em ndp-\*[Gt]ni_cnd.cn_flags 250has the 251.Dv FOLLOW 252flag set then symbolic links are followed when they 253occur at the end of the name translation process. 254Symbolic links are always followed for all other pathname components 255other than the last. 256.Pp 257Historically 258.Nm 259had a sub-function called 260.Fn lookup . 261This function processed a pathname until either running out of 262material or encountering a symbolic link. 263.Nm 264worked by first setting up the start directory 265.Em ndp-\*[Gt]ni_startdir 266and then calling 267.Fn lookup 268repeatedly. 269.Pp 270The semantics of 271.Nm 272are altered by the operation specified by 273.Em ndp-\*[Gt]ni_cnd.cn_nameiop . 274When 275.Dv CREATE , 276.Dv RENAME , 277or 278.Dv DELETE 279is specified, information usable in 280creating, renaming, or deleting a directory entry may be calculated. 281.Pp 282If the target of the pathname exists and LOCKLEAF is set, the target 283is returned locked in 284.Em ndp-\*[Gt]ni_vp , 285otherwise it is returned unlocked. 286.Pp 287As of this writing the internal function 288.Fn do_lookup 289is comparable to the historic 290.Fn lookup 291but this code is slated for refactoring. 292.It Fn lookup_for_nfsd "ndp" "startdir" "neverfollow" 293This is a private entry point into 294.Nm 295used by the NFS server code. 296It looks up a path starting from 297.Fa startdir . 298If 299.Fa neverfollow 300is set, 301.Em any 302symbolic link (not just at the end of the path) will cause an error. 303Otherwise, it follows symlinks normally. 304Its semantics are similar to a symlink-following loop around the historic 305.Fn lookup 306function described above. 307It should not be used by new code. 308.It Fn lookup_for_nfsd_index "ndp" 309This is a (second) private entry point into 310.Nm 311used by the NFS server code. 312Its semantics are similar to the historic 313.Fn lookup 314function described above. 315It should not be used by new code. 316.It Fn relookup "dvp" "vpp" "cnp" 317Reacquire a path name component is a directory. 318This is a quicker way to lookup a pathname component when the parent 319directory is known. 320The locked parent directory vnode is specified by 321.Fa dvp 322and the pathname component by 323.Fa cnp . 324The vnode of the pathname is returned in the address specified by 325.Fa vpp . 326.It Fn NDINIT "ndp" "op" "flags" "segflg" "namep" 327Initialise a nameidata structure pointed to by 328.Fa ndp 329for use by the 330.Nm 331interface. 332It saves having to deal with the componentname structure inside 333.Fa ndp . 334The operation and flags are specified by 335.Fa op 336and 337.Fa flags 338respectively. 339These are the values to which 340.Em ndp-\*[Gt]ni_cnd.cn_nameiop 341and 342.Em ndp-\*[Gt]ni_cnd.cn_flags 343are respectively set. 344The segment flags which defines whether the pathname is in kernel 345address space or user address space is specified by 346.Fa segflag . 347The argument 348.Fa namep 349is a pointer to the pathname that 350.Em ndp-\*[Gt]ni_dirp 351is set to. 352.Pp 353This routine stores the credentials of the calling thread 354.Va ( curlwp ) 355in 356.Fa ndp . 357In the rare case that another set of credentials is required for the 358namei operation, 359.Em ndp-\*[Gt]ni_cnd.cn_cred 360must be set manually. 361.It Fn namei_simple_kernel "path" "sflags" "ret" 362Look up the path 363.Fa path 364and translate it to a vnode, returned in 365.Fa ret . 366The 367.Fa path 368argument must be a kernel 369.Pq Dv UIO_SYSSPACE 370pointer. 371The 372.Fa sflags 373argument chooses the precise behavior. 374It may be set to one of the following symbols: 375.Bl -tag -offset indent -width NSM_NOFOLLOW_TRYEMULROOT -compact 376.It Dv NSM_NOFOLLOW_NOEMULROOT 377.It Dv NSM_NOFOLLOW_TRYEMULROOT 378.It Dv NSM_FOLLOW_NOEMULROOT 379.It Dv NSM_FOLLOW_TRYEMULROOT 380.El 381These select (or not) the 382.Dv FOLLOW/NOFOLLOW 383and 384.Dv TRYEMULROOT 385flags. 386Other flags are not available through this interface, which is 387nonetheless sufficient for more than half the 388.Fn namei 389usage in the kernel. 390Note that the encoding of 391.Fa sflags 392has deliberately been arranged to be type-incompatible with anything 393else. 394This prevents various possible accidents while the 395.Fn namei 396interface is being rototilled. 397.It Fn namei_simple_user "path" "sflags" "ret" 398This function is the same as 399.Fn namei_simple_kernel 400except that the 401.Fa path 402argument shall be a user pointer 403.Pq Dv UIO_USERSPACE 404rather than a kernel pointer. 405.El 406.Sh CODE REFERENCES 407This section describes places within the 408.Nx 409source tree where actual code implementing or using the name 410lookup subsystem can be found. 411All pathnames are relative to 412.Pa /usr/src . 413.Pp 414The name lookup subsystem is implemented within the file 415.Pa sys/kern/vfs_lookup.c . 416.Sh SEE ALSO 417.Xr intro 9 , 418.Xr namecache 9 , 419.Xr vfs 9 , 420.Xr vnode 9 , 421.Xr vnodeops 9 422.Sh BUGS 423It is unfortunate that much of the 424.Nm 425interface makes assumptions on the underlying vnode operations. 426These assumptions are an artefact of the introduction of the vfs 427interface to split a file system interface which was historically 428designed as a tightly coupled module. 429