1.\" $NetBSD: namei.9,v 1.21 2009/06/29 06:02:09 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 June 29, 2009 31.Dt NAMEI 9 32.Os 33.Sh NAME 34.Nm namei , 35.Nm lookup , 36.Nm relookup , 37.Nm NDINIT , 38.Nm namei_simple_kernel , 39.Nm namei_simple_user 40.Nd pathname lookup 41.Sh SYNOPSIS 42.In sys/namei.h 43.In sys/uio.h 44.In sys/vnode.h 45.Ft int 46.Fn namei "struct nameidata *ndp" 47.Ft int 48.Fn lookup "struct nameidata *ndp" 49.Ft int 50.Fn relookup "struct vnode *dvp" "struct vnode **vpp" \ 51"struct componentname *cnp" 52.Ft void 53.Fn NDINIT "struct nameidata *ndp" "u_long op" "u_long flags" \ 54"enum uio_seg segflg" "const char *namep" 55.Ft int 56.Fn namei_simple_kernel "const char *path" "namei_simple_flags_t sflags" \ 57"struct vnode **ret" 58.Ft int 59.Fn namei_simple_user "const char *path" "namei_simple_flags_t sflags" \ 60"struct vnode **ret" 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 74Except for the simple forms, the arguments passed to the functions are 75encapsulated in the 76.Em nameidata 77structure. 78It has the following structure: 79.Bd -literal 80struct nameidata { 81 /* 82 * Arguments to namei/lookup. 83 */ 84 const char *ni_dirp; /* pathname pointer */ 85 enum uio_seg ni_segflg; /* location of pathname */ 86 /* 87 * Arguments to lookup. 88 */ 89 struct vnode *ni_startdir; /* starting directory */ 90 struct vnode *ni_rootdir; /* logical root directory */ 91 /* 92 * Results: returned from/manipulated by lookup 93 */ 94 struct vnode *ni_vp; /* vnode of result */ 95 struct vnode *ni_dvp; /* vnode of intermediate dir */ 96 /* 97 * Shared between namei and lookup/commit routines. 98 */ 99 size_t ni_pathlen; /* remaining chars in path */ 100 const char *ni_next; /* next location in pathname */ 101 u_long ni_loopcnt; /* count of symlinks encountered */ 102 /* 103 * Lookup parameters 104 */ 105 struct componentname { 106 /* 107 * Arguments to lookup. 108 */ 109 u_long cn_nameiop; /* namei operation */ 110 u_long cn_flags; /* flags to namei */ 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 Dv NOCROSSMOUNT 159do not cross mount points 160.It Dv RDONLY 161lookup with read-only semantics 162.It Dv HASBUF 163caller has allocated pathname buffer 164.Em ni_cnd.cn_pnbuf 165.It Dv SAVENAME 166save pathname buffer 167.It Dv SAVESTART 168save starting directory 169.It Dv ISDOTDOT 170current pathname component is .. 171.It Dv MAKEENTRY 172add entry to the name cache 173.It Dv ISLASTCN 174this is last component of pathname 175.It Dv ISSYMLINK 176symlink needs interpretation 177.It Dv ISWHITEOUT 178found whiteout 179.It Dv DOWHITEOUT 180do whiteouts 181.It Dv REQUIREDIR 182must be a directory 183.It Dv CREATEDIR 184trailing slashes are ok 185.It Dv 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 199.Dv SAVESTART 200flag is set only by the callers of 201.Fn namei . 202It implies 203.Dv SAVENAME 204plus the addition of saving the parent directory 205that contains the name in 206.Em ni_startdir . 207It allows repeated calls to 208.Fn lookup 209for the name being sought. 210The caller is responsible for releasing the buffer and for invoking 211.Fn vrele 212on 213.Em ni_startdir . 214.Pp 215All access to the 216.Nm 217interface must be in process context. 218Pathname lookups cannot be done in interrupt context. 219.Sh FUNCTIONS 220.Bl -tag -width compact 221.It Fn namei "ndp" 222Convert a pathname into a pointer to a vnode. 223The pathname is specified by 224.Em ndp-\*[Gt]ni_dirp 225and is of length 226.Em ndp-\*[Gt]ni_pathlen . 227The 228.Em ndp-\*[Gt]segflg 229flags defines whether the name in 230.Em ndp-\*[Gt]ni_dirp 231is an address in kernel space 232.Pq Dv UIO_SYSSPACE 233or an address in user space 234.Pq Dv UIO_USERSPACE . 235.Pp 236The vnode for the pathname is returned in 237.Em ndp-\*[Gt]ni_vp . 238The parent directory is returned locked in 239.Em ndp-\*[Gt]ni_dvp 240iff 241.Dv LOCKPARENT 242is specified. 243.Pp 244If 245.Em ndp-\*[Gt]ni_cnd.cn_flags 246has the 247.Dv FOLLOW 248flag set then symbolic links are followed when they 249occur at the end of the name translation process. 250Symbolic links are always followed for all other pathname components 251other than the last. 252.It Fn lookup "ndp" 253Search for a pathname. 254This is a very central and rather complicated routine. 255.Pp 256The pathname is specified by 257.Em ndp-\*[Gt]ni_dirp 258and is of length 259.Em ndp-\*[Gt]ni_pathlen . 260The starting directory is taken from 261.Em ndp-\*[Gt]ni_startdir . 262The pathname is descended until done, or a symbolic link is 263encountered. 264.Pp 265The semantics of 266.Fn lookup 267are altered by the operation specified by 268.Em ndp-\*[Gt]ni_cnd.cn_nameiop . 269When 270.Dv CREATE , 271.Dv RENAME , 272or 273.Dv DELETE 274is specified, information usable in 275creating, renaming, or deleting a directory entry may be calculated. 276.Pp 277If the target of the pathname exists and LOCKLEAF is set, the target 278is returned locked in 279.Em ndp-\*[Gt]ni_vp , 280otherwise it is returned unlocked. 281.It Fn relookup "dvp" "vpp" "cnp" 282Reacquire a path name component is a directory. 283This is a quicker way to lookup a pathname component when the parent 284directory is known. 285The locked parent directory vnode is specified by 286.Fa dvp 287and the pathname component by 288.Fa cnp . 289The vnode of the pathname is returned in the address specified by 290.Fa vpp . 291.It Fn NDINIT "ndp" "op" "flags" "segflg" "namep" 292Initialise a nameidata structure pointed to by 293.Fa ndp 294for use by the 295.Nm 296interface. 297It saves having to deal with the componentname structure inside 298.Fa ndp . 299The operation and flags are specified by 300.Fa op 301and 302.Fa flags 303respectively. 304These are the values to which 305.Em ndp-\*[Gt]ni_cnd.cn_nameiop 306and 307.Em ndp-\*[Gt]ni_cnd.cn_flags 308are respectively set. 309The segment flags which defines whether the pathname is in kernel 310address space or user address space is specified by 311.Fa segflag . 312The argument 313.Fa namep 314is a pointer to the pathname that 315.Em ndp-\*[Gt]ni_dirp 316is set to. 317.Pp 318This routine stores the credentials of the calling thread 319.Va ( curlwp ) 320in 321.Fa ndp . 322In the rare case that another set of credentials is required for the 323namei operation, 324.Em ndp-\*[Gt]ni_cnd.cn_cred 325must be set manually. 326.It Fn namei_simple_kernel "path" "sflags" "ret" 327Look up the path 328.Fa path 329and translate it to a vnode, returned in 330.Fa ret . 331The 332.Fa path 333argument must be a kernel 334.Pq Dv UIO_SYSSPACE 335pointer. 336The 337.Fa sflags 338argument chooses the precise behavior. 339It may be set to one of the following symbols: 340.Bl -tag -offset indent -width NSM_NOFOLLOW_TRYEMULROOT -compact 341.It Dv NSM_NOFOLLOW_NOEMULROOT 342.It Dv NSM_NOFOLLOW_TRYEMULROOT 343.It Dv NSM_FOLLOW_NOEMULROOT 344.It Dv NSM_FOLLOW_TRYEMULROOT 345.El 346These select (or not) the 347.Dv FOLLOW/NOFOLLOW 348and 349.Dv TRYEMULROOT 350flags. 351Other flags are not available through this interface, which is 352nonetheless sufficient for more than half the 353.Fn namei 354usage in the kernel. 355Note that the encoding of 356.Fa sflags 357has deliberately been arranged to be type-incompatible with anything 358else. 359This prevents various possible accidents while the 360.Fn namei 361interface is being rototilled. 362.It Fn namei_simple_user "path" "sflags" "ret" 363This function is the same as 364.Fn namei_simple_kernel 365except that the 366.Fa path 367argument shall be a user pointer 368.Pq Dv UIO_USERSPACE 369rather than a kernel pointer. 370.El 371.Sh CODE REFERENCES 372This section describes places within the 373.Nx 374source tree where actual code implementing or using the name 375lookup subsystem can be found. 376All pathnames are relative to 377.Pa /usr/src . 378.Pp 379The name lookup subsystem is implemented within the file 380.Pa sys/kern/vfs_lookup.c . 381.Sh SEE ALSO 382.Xr intro 9 , 383.Xr namecache 9 , 384.Xr vfs 9 , 385.Xr vnode 9 , 386.Xr vnodeops 9 387.Sh BUGS 388It is unfortunate that much of the 389.Nm 390interface makes assumptions on the underlying vnode operations. 391These assumptions are an artefact of the introduction of the vfs 392interface to split a file system interface which was historically 393designed as a tightly coupled module. 394