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