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