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