1.\" $OpenBSD: namei.9,v 1.23 2023/07/15 23:01:25 kn 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: July 15 2023 $ 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 converts a pathname to a 61.Xr vnode 9 . 62It uses the following structure: 63.Bd -literal 64struct nameidata { 65 /* 66 * Arguments to namei/lookup. 67 */ 68 const char *ni_dirp; /* pathname pointer */ 69 int ni_dirfd; /* AT_FDCWD or fd of base of */ 70 /* relative paths */ 71 enum uio_seg ni_segflg; /* location of pathname */ 72 /* 73 * Arguments to lookup. 74 */ 75 struct vnode *ni_startdir; /* starting directory */ 76 struct vnode *ni_rootdir; /* logical root directory */ 77 uint64_t ni_pledge; /* expected pledge for namei */ 78 u_char ni_unveil; /* required unveil flags for namei */ 79 /* 80 * Results: returned from/manipulated by lookup 81 */ 82 struct vnode *ni_vp; /* vnode of result */ 83 struct vnode *ni_dvp; /* vnode of intermediate dir */ 84 /* 85 * Shared between namei and lookup/commit routines. 86 */ 87 size_t ni_pathlen; /* remaining chars in path */ 88 char *ni_next; /* next location in pathname */ 89 u_long ni_loopcnt; /* count of symlinks encountered */ 90 struct unveil *ni_unveil_match; /* last matching unveil component */ 91 /* 92 * Lookup parameters 93 */ 94 struct componentname ni_cnd; 95}; 96.Ed 97.Pp 98The 99.Fn namei 100function accesses vnode operations by passing arguments in the 101partially initialised 102.Em componentname 103structure 104.Em ni_cnd . 105This structure describes the subset of information from the nameidata 106structure that is passed through to the vnode operations. 107See 108.Xr VOP_LOOKUP 9 109for more information. 110The details of the componentname structure are not absolutely necessary 111since the members are initialised by the helper macros 112.Fn NDINIT 113and 114.Fn NDINITAT . 115It is useful to know the operations and flags as specified in 116.Xr VOP_LOOKUP 9 . 117.Pp 118The 119.Fn namei 120function overloads 121.Em ni_cnd.cn_flags 122with some additional flags. 123These flags should be specific to 124.Fn namei 125and ignored by vnode operations. 126However, due to the historic close relationship between 127.Fn namei 128and the vnode operations, these flags are sometimes used 129(and set) by vnode operations, particularly 130.Fn VOP_LOOKUP . 131The additional flags are: 132.Pp 133.Bl -tag -offset indent -width NOCROSSMOUNT -compact 134.It NOCROSSMOUNT 135do not cross mount points 136.It RDONLY 137lookup with read-only semantics 138.It HASBUF 139caller has allocated pathname buffer 140.Em ni_cnd.cn_pnbuf 141.It SAVENAME 142save pathname buffer 143.It SAVESTART 144save starting directory 145.It ISDOTDOT 146current pathname component is .. 147.It MAKEENTRY 148add entry to the name cache 149.It ISLASTCN 150this is last component of pathname 151.It ISSYMLINK 152symlink needs interpretation 153.It REALPATH 154save pathname buffer for realpath 155.It REQUIREDIR 156must be a directory 157.It STRIPSLASHES 158strip trailing slashes from the pathname 159.It PDIRUNLOCK 160.Fn VOP_LOOKUP 161unlocked parent dir 162.It BYPASSUNVEIL 163bypass pledge paths checks 164.It KERNELPATH 165access file as kernel, not process 166.El 167.Pp 168If the caller of 169.Fn namei 170sets the SAVENAME flag, then it must free the buffer. 171If 172.Fn VOP_LOOKUP 173sets the flag, then the buffer must be freed by either the commit 174routine or the 175.Fn VOP_ABORT 176routine. 177The SAVESTART flag is set only by the callers of 178.Fn namei . 179It implies SAVENAME plus the addition of saving the parent directory 180that contains the name in 181.Em ni_startdir . 182It allows repeated calls to 183.Fn vfs_lookup 184for the name being sought. 185The caller is responsible for releasing the buffer and for invoking 186.Fn vrele 187on 188.Em ni_startdir . 189.Pp 190All access to 191.Fn namei , 192.Fn vfs_lookup , 193and 194.Fn vfs_relookup 195must be in process context. 196Pathname lookups cannot be done in interrupt context. 197.Sh FUNCTIONS 198.Bl -tag -width compact 199.It Fn namei "ndp" 200Convert a pathname into a pointer to a vnode. 201The pathname is specified by 202.Em ndp-\*[Gt]ni_dirp 203and is of length 204.Em ndp-\*[Gt]ni_pathlen . 205The 206.Em ndp-\*[Gt]segflg 207flag defines whether the name in 208.Em ndp-\*[Gt]ni_dirp 209is an address in kernel space (UIO_SYSSPACE) or an address in user 210space (UIO_USERSPACE). 211The vnode for the pathname is referenced and returned in 212.Em ndp-\*[Gt]ni_vp . 213.Pp 214If 215.Em ndp-\*[Gt]ni_cnd.cn_flags 216has the FOLLOW flag set then symbolic links are followed when they 217occur at the end of the name translation process. 218Symbolic links are always followed for all other pathname components 219other than the last. 220.Pp 221If the LOCKLEAF flag is set, a locked vnode is returned. 222.It Fn vfs_lookup "ndp" 223Search for a pathname. 224This is a very central and rather complicated routine. 225.Pp 226The pathname is specified by 227.Em ndp-\*[Gt]ni_dirp 228and is of length 229.Em ndp-\*[Gt]ni_pathlen . 230The starting directory is taken from 231.Em ndp-\*[Gt]ni_startdir . 232The pathname is descended until done, or a symbolic link is 233encountered. 234.Pp 235The semantics of 236.Fn vfs_lookup 237are altered by the operation specified by 238.Em ndp-\*[Gt]ni_cnd.cn_nameiop . 239When CREATE, RENAME, or DELETE is specified, information usable in 240creating, renaming, or deleting a directory entry may be calculated. 241.Pp 242If 243.Em ndp-\*[Gt]ci_cnd.cn_flags 244has LOCKPARENT set, the parent directory is returned locked in 245.Em ndp-\*[Gt]ni_dvp . 246If WANTPARENT is set, the parent directory is returned unlocked. 247Otherwise the parent directory is not returned. 248If the target of the pathname exists and LOCKLEAF is set, the target 249is returned locked in 250.Em ndp-\*[Gt]ni_vp , 251otherwise it is returned unlocked. 252.It Fn vfs_relookup "dvp" "vpp" "cnp" 253Reacquire a path name component in a directory. 254This is a quicker way to lookup a pathname component when the parent 255directory is known. 256The unlocked parent directory vnode is specified by 257.Fa dvp 258and the pathname component by 259.Fa cnp . 260The vnode of the pathname is returned in the address specified by 261.Fa vpp . 262.It Fn NDINITAT "ndp" "op" "flags" "segflg" "dirfd" "namep" "p" 263Initialise a nameidata structure pointed to by 264.Fa ndp 265for use by the 266.Nm 267interfaces. 268It saves having to deal with the componentname structure inside 269.Fa ndp . 270The operation and flags are specified by 271.Fa op 272and 273.Fa flags 274respectively. 275These are the values to which 276.Em ndp-\*[Gt]ni_cnd.cn_nameiop 277and 278.Em ndp-\*[Gt]ni_cnd.cn_flags 279are respectively set. 280The segment flag, which defines whether the pathname is in kernel 281address space or user address space, is specified by 282.Fa segflg . 283The directory from which relative pathnames will be looked up is 284specified by 285.Fa dirfd , 286with 287.Dv AT_FDCWD 288specifying use of the current working directory of process 289.Fa p . 290The argument 291.Fa namep 292is a pointer to the pathname that 293.Em ndp-\*[Gt]ni_dirp 294is set to and 295.Fa p 296is the calling process. 297.It Fn NDINIT "ndp" "op" "flags" "segflg" "namep" "p" 298Same as 299.Fn NDINITAT "ndp" "op" "flags" "segflg" \fRAT_FDCWD\fP "namep" "p" . 300.El 301.Sh CODE REFERENCES 302The name lookup subsystem is implemented within the file 303.Pa sys/kern/vfs_lookup.c . 304.Sh SEE ALSO 305.Xr intro 9 , 306.\" .Xr namecache 9 , 307.Xr vfs 9 , 308.Xr vnode 9 , 309.Xr VOP_LOOKUP 9 310.Sh HISTORY 311The 312.Fn namei 313function first appeared in 314.At v4 . 315Its name is an abbreviation for the name-to-inode conversion 316which it performed before the appearance of 317.Xr vfs 9 318in 319.Bx 4.3 Reno . 320.Sh BUGS 321It is unfortunate that much of the 322.Nm 323interface makes assumptions on the underlying vnode operations. 324These assumptions are an artefact of the introduction of the vfs 325interface to split a file system interface which was historically 326designed as a tightly coupled module. 327