1.\" $NetBSD: namei.9,v 1.34 2015/04/21 10:00:30 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 April 21, 2015 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 ISDOTDOT 168current pathname component is .. 169.It Dv MAKEENTRY 170add entry to the name cache 171.It Dv ISLASTCN 172this is last component of pathname 173.It Dv ISWHITEOUT 174found whiteout 175.It Dv DOWHITEOUT 176do whiteouts 177.It Dv REQUIREDIR 178must be a directory 179.It Dv CREATEDIR 180trailing slashes are ok 181.It Dv PARAMASK 182mask of parameter descriptors 183.El 184.Pp 185All access to the 186.Nm 187interface must be in process context. 188Pathname lookups cannot be done in interrupt context. 189.Sh FUNCTIONS 190.Bl -tag -width compact 191.It Fn namei "ndp" 192Convert a pathname into a pointer to a vnode. 193The nameidata structure pointed to by 194.Fa ndp 195should be initialized with the 196.Fn NDINIT 197macro. 198Direct initialization of members of struct nameidata is 199.Em not 200supported and may break silently in the future. 201.Pp 202The vnode for the pathname is returned in 203.Em ndp-\*[Gt]ni_vp . 204The parent directory is returned locked in 205.Em ndp-\*[Gt]ni_dvp 206iff 207.Dv LOCKPARENT 208is specified. 209.Pp 210If 211.Em ndp-\*[Gt]ni_cnd.cn_flags 212has the 213.Dv FOLLOW 214flag set then symbolic links are followed when they 215occur at the end of the name translation process. 216Symbolic links are always followed for all other pathname components 217other than the last. 218.Pp 219Historically 220.Nm 221had a sub-function called 222.Fn lookup . 223This function processed a pathname until either running out of 224material or encountering a symbolic link. 225.Nm 226worked by first setting up the start directory 227.Em ndp-\*[Gt]ni_startdir 228and then calling 229.Fn lookup 230repeatedly. 231.Pp 232The semantics of 233.Nm 234are altered by the operation specified by 235.Em ndp-\*[Gt]ni_cnd.cn_nameiop . 236When 237.Dv CREATE , 238.Dv RENAME , 239or 240.Dv DELETE 241is specified, information usable in 242creating, renaming, or deleting a directory entry may be calculated. 243.Pp 244If the target of the pathname exists and LOCKLEAF is set, the target 245is returned locked in 246.Em ndp-\*[Gt]ni_vp , 247otherwise it is returned unlocked. 248.Pp 249As of this writing the internal function 250.Fn do_lookup 251is comparable to the historic 252.Fn lookup 253but this code is slated for refactoring. 254.It Fn lookup_for_nfsd "ndp" "startdir" "neverfollow" 255This is a private entry point into 256.Nm 257used by the NFS server code. 258It looks up a path starting from 259.Fa startdir . 260If 261.Fa neverfollow 262is set, 263.Em any 264symbolic link (not just at the end of the path) will cause an error. 265Otherwise, it follows symlinks normally. 266Its semantics are similar to a symlink-following loop around the historic 267.Fn lookup 268function described above. 269It should not be used by new code. 270.It Fn lookup_for_nfsd_index "ndp" 271This is a (second) private entry point into 272.Nm 273used by the NFS server code. 274Its semantics are similar to the historic 275.Fn lookup 276function described above. 277It should not be used by new code. 278.It Fn relookup "dvp" "vpp" "cnp" 279Reacquire a path name component is a directory. 280This is a quicker way to lookup a pathname component when the parent 281directory is known. 282The locked parent directory vnode is specified by 283.Fa dvp 284and the pathname component by 285.Fa cnp . 286The vnode of the pathname is returned in the address specified by 287.Fa vpp . 288.It Fn NDINIT "ndp" "op" "flags" "pathbuf" 289Initialise a nameidata structure pointed to by 290.Fa ndp 291for use by the 292.Nm 293interface. 294The operation and flags are specified by 295.Fa op 296and 297.Fa flags 298respectively. 299The pathname is passed as a pathbuf structure, which should be 300initialized using one of the 301.Xr pathbuf 9 302operations. 303Destroying the pathbuf is the responsibility of the caller; this must 304not be done until the caller is finished with all of the 305.Nm 306results and all of the nameidata contents except for the result vnode. 307.Pp 308This routine stores the credentials of the calling thread 309.Va ( curlwp ) 310in 311.Fa ndp . 312In the rare case that another set of credentials is required for the 313namei operation, 314.Em ndp-\*[Gt]ni_cnd.cn_cred 315must be set manually. 316.Pp 317The following fields of 318.Fa ndp 319are set: 320.Bl -tag -width compact 321.It Fa ni_cnd.cn_nameiop 322is set to 323.Fa op . 324.It Fa ni_cnd.cn_flags 325is set to 326.Fa flags . 327.It Fa ni_startdir 328is set to 329.Dv NULL . 330.It Fa ni_pathbuf 331is set to 332.Fa pathbuf . 333.It Fa ni_cnd.cn_cred 334is set using 335.Xr kauth_cred_get 9 . 336.El 337Other fields of struct nameidata are not 338.Pq normally 339initialized before 340.Nm 341is called. 342Direct assignment of these or other fields other than by using 343.Fn NDINIT 344or 345.Fn NDAT , 346except as specifically described above, is not supported and may break 347silently in the future. 348.It Fn NDAT "ndp" "dvp" 349This macro is used after 350.Fn NDINIT 351to set the starting directory. 352This supersedes the current process's current working directory as the 353initial point of departure for looking up relative paths. 354This mechanism is used by 355.Xr openat 2 356and related calls. 357.It Fn namei_simple_kernel "path" "sflags" "ret" 358Look up the path 359.Fa path 360and translate it to a vnode, returned in 361.Fa ret . 362The 363.Fa path 364argument must be a kernel 365.Pq Dv UIO_SYSSPACE 366pointer. 367The 368.Fa sflags 369argument chooses the precise behavior. 370It may be set to one of the following symbols: 371.Bl -tag -offset indent -width NSM_NOFOLLOW_TRYEMULROOT -compact 372.It Dv NSM_NOFOLLOW_NOEMULROOT 373.It Dv NSM_NOFOLLOW_TRYEMULROOT 374.It Dv NSM_FOLLOW_NOEMULROOT 375.It Dv NSM_FOLLOW_TRYEMULROOT 376.El 377These select (or not) the 378.Dv FOLLOW/NOFOLLOW 379and 380.Dv TRYEMULROOT 381flags. 382Other flags are not available through this interface, which is 383nonetheless sufficient for more than half the 384.Fn namei 385usage in the kernel. 386Note that the encoding of 387.Fa sflags 388has deliberately been arranged to be type-incompatible with anything 389else. 390This prevents various possible accidents while the 391.Fn namei 392interface is being rototilled. 393.It Fn namei_simple_user "path" "sflags" "ret" 394This function is the same as 395.Fn namei_simple_kernel 396except that the 397.Fa path 398argument shall be a user pointer 399.Pq Dv UIO_USERSPACE 400rather than a kernel pointer. 401.El 402.Sh CODE REFERENCES 403The name lookup subsystem is implemented within the file 404.Pa sys/kern/vfs_lookup.c . 405.Sh SEE ALSO 406.Xr intro 9 , 407.Xr namecache 9 , 408.Xr vfs 9 , 409.Xr vnode 9 , 410.Xr vnodeops 9 411.Sh BUGS 412It is unfortunate that much of the 413.Nm 414interface makes assumptions on the underlying vnode operations. 415These assumptions are an artefact of the introduction of the vfs 416interface to split a file system interface which was historically 417designed as a tightly coupled module. 418