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