share/man/man9/namei.9

   1 .\"
   2 .\" Copyright (c) 1998, 1999 Eivind Eklund
   3 .\" Copyright (c) 2003 Hiten M. Pandya
   4 .\" Copyright (c) 2005 Robert N. M. Watson
   5 .\"
   6 .\" All rights reserved.
   7 .\"
   8 .\" This program is free software.
   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 DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
  20 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  21 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  22 .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
  23 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  24 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  25 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  26 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  27 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  28 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .\"
  31 .\" If you integrate this manpage in another OS, I'd appreciate a note
  32 .\"     - eivind@FreeBSD.org
  33 .\"
  34 .Dd July 8, 2023
  35 .Dt NAMEI 9
  36 .Os
  37 .Sh NAME
  38 .Nm namei ,
  39 .Nm NDINIT ,
  40 .Nm NDFREE
  41 .Nd pathname translation and lookup operations
  42 .Sh SYNOPSIS
  43 .In sys/param.h
  44 .In sys/fcntl.h
  45 .In sys/namei.h
  46 .Ft int
  47 .Fn namei "struct nameidata *ndp"
  48 .Ft void
  49 .Fo NDINIT
  50 .Fa "struct nameidata *ndp" "u_long op" "u_long flags"
  51 .Fa "enum uio_seg segflg" "const char *namep" "struct thread *td"
  52 .Fc
  53 .Ft void
  54 .Fn NDFREE "struct nameidata *ndp" "const uint flags"
  55 .Sh DESCRIPTION
  56 The
  57 .Nm
  58 facility allows the client to perform pathname translation and lookup
  59 operations.
  60 The
  61 .Nm
  62 functions will increment the reference count for the vnode in question.
  63 The reference count has to be decremented after use of the vnode, by
  64 using either
  65 .Xr vrele 9
  66 or
  67 .Xr vput 9 ,
  68 depending on whether the
  69 .Dv LOCKLEAF
  70 flag was specified or not.
  71 .Pp
  72 The
  73 .Fn NDINIT
  74 function is used to initialize
  75 .Nm
  76 components.
  77 It takes the following arguments:
  78 .Bl -tag -width ".Fa segflg"
  79 .It Fa ndp
  80 The
  81 .Vt "struct nameidata"
  82 to initialize.
  83 .It Fa op
  84 The operation which
  85 .Fn namei
  86 will perform.
  87 The following operations are valid:
  88 .Dv LOOKUP , CREATE , DELETE ,
  89 and
  90 .Dv RENAME .
  91 The latter three are just setup for those
  92 effects; just calling
  93 .Fn namei
  94 will not result in
  95 .Fn VOP_RENAME
  96 being called.
  97 .It Fa flags
  98 Operation flags.
  99 Several of these can be effective at the same time.
 100 .It Fa segflg
 101 UIO segment indicator.
 102 This indicates if the name of the object is in userspace
 103 .Pq Dv UIO_USERSPACE
 104 or in the kernel address space
 105 .Pq Dv UIO_SYSSPACE .
 106 .It Fa namep
 107 Pointer to the component's pathname buffer
 108 (the file or directory name that will be looked up).
 109 .It Fa td
 110 The thread context to use for
 111 .Nm
 112 operations and locks.
 113 .El
 114 .Sh NAMEI OPERATION FLAGS
 115 The
 116 .Fn namei
 117 function takes the following set of
 118 .Dq "operation flags"
 119 that influence its operation:
 120 .Bl -tag -width ".Dv WANTPARENT"
 121 .It Dv LOCKLEAF
 122 Lock vnode on return with
 123 .Dv LK_EXCLUSIVE
 124 unless
 125 .Dv LOCKSHARED
 126 is also set.
 127 The
 128 .Xr VOP_UNLOCK 9
 129 should be used
 130 to release the lock (or
 131 .Xr vput 9
 132 which is equivalent to calling
 133 .Xr VOP_UNLOCK 9
 134 followed by
 135 .Xr vrele 9 ,
 136 all in one).
 137 .It Dv LOCKPARENT
 138 This flag lets the
 139 .Fn namei
 140 function return the parent (directory) vnode,
 141 .Va ni_dvp
 142 in locked state, unless it is identical to
 143 .Va ni_vp ,
 144 in which case
 145 .Va ni_dvp
 146 is not locked per se (but may be locked due to
 147 .Dv LOCKLEAF ) .
 148 If a lock is enforced, it should be released using
 149 .Xr vput 9
 150 or
 151 .Xr VOP_UNLOCK 9
 152 and
 153 .Xr vrele 9 .
 154 .It Dv LOCKSHARED
 155 Lock vnode on return with
 156 .Dv LK_SHARED .
 157 The
 158 .Xr VOP_UNLOCK 9
 159 should be used
 160 to release the lock (or
 161 .Xr vput 9
 162 which is equivalent to calling
 163 .Xr VOP_UNLOCK 9
 164 followed by
 165 .Xr vrele 9 ,
 166 all in one).
 167 .It Dv WANTPARENT
 168 This flag allows the
 169 .Fn namei
 170 function to return the parent (directory) vnode in an unlocked state.
 171 The parent vnode must be released separately by using
 172 .Xr vrele 9 .
 173 .It Dv NOCACHE
 174 Avoid
 175 .Fn namei
 176 creating this entry in the namecache if it is not
 177 already present.
 178 Normally,
 179 .Fn namei
 180 will add entries to the name cache
 181 if they are not already there.
 182 .It Dv FOLLOW
 183 With this flag,
 184 .Fn namei
 185 will follow the symbolic link if the last part
 186 of the path supplied is a symbolic link (i.e., it will return a vnode
 187 for whatever the link points at, instead for the link itself).
 188 .It Dv NOFOLLOW
 189 Do not follow symbolic links (pseudo).
 190 This flag is not looked for by the actual code, which looks for
 191 .Dv FOLLOW .
 192 .Dv NOFOLLOW
 193 is used to indicate to the source code reader that symlinks
 194 are intentionally not followed.
 195 .It Dv SAVENAME
 196 Do not free the pathname buffer at the end of the
 197 .Fn namei
 198 invocation; instead, free it later in
 199 .Fn NDFREE
 200 so that the caller may access the pathname buffer.
 201 See below for details.
 202 .It Dv SAVESTART
 203 Retain an additional reference to the parent directory; do not free
 204 the pathname buffer.
 205 See below for details.
 206 .El
 207 .Sh ALLOCATED ELEMENTS
 208 The
 209 .Vt nameidata
 210 structure is composed of the following fields:
 211 .Bl -tag -width ".Va ni_cnd.cn_pnbuf"
 212 .It Va ni_startdir
 213 In the normal case, this is either the current directory or the root.
 214 It is the current directory if the name passed in does not start with
 215 .Ql /
 216 and we have not gone through any symlinks with an absolute path, and
 217 the root otherwise.
 218 .Pp
 219 In this case, it is only used by
 220 .Fn vfs_lookup ,
 221 and should not be
 222 considered valid after a call to
 223 .Fn namei .
 224 .It Va ni_dvp
 225 Vnode pointer to directory of the object on which lookup is performed.
 226 This is available on successful return if
 227 .Dv LOCKPARENT
 228 or
 229 .Dv WANTPARENT
 230 is set.
 231 It is locked if
 232 .Dv LOCKPARENT
 233 is set.
 234 .It Va ni_vp
 235 Vnode pointer to the resulting object,
 236 .Dv NULL
 237 otherwise.
 238 The
 239 .Va v_usecount
 240 field of this vnode is incremented.
 241 If
 242 .Dv LOCKLEAF
 243 is set, it is also locked.
 244 .Pp
 245 .It Va ni_cnd.cn_pnbuf
 246 The pathname buffer contains the location of the file or directory
 247 that will be used by the
 248 .Nm
 249 operations.
 250 It is managed by the
 251 .Xr uma 9
 252 zone allocation interface.
 253 .El
 254 .Sh RETURN VALUES
 255 If successful,
 256 .Fn namei
 257 will return 0, otherwise it will return an error.
 258 .Sh FILES
 259 .Bl -tag -width Pa
 260 .It Pa src/sys/kern/vfs_lookup.c
 261 .El
 262 .Sh ERRORS
 263 Errors which
 264 .Fn namei
 265 may return:
 266 .Bl -tag -width Er
 267 .It Bq Er ENOTDIR
 268 A component of the specified pathname is not a directory when a directory is
 269 expected.
 270 .It Bq Er ENAMETOOLONG
 271 A component of a pathname exceeded 255 characters,
 272 or an entire pathname exceeded 1023 characters.
 273 .It Bq Er ENOENT
 274 A component of the specified pathname does not exist,
 275 or the pathname is an empty string.
 276 .It Bq Er EACCES
 277 An attempt is made to access a file in a way forbidden by its file access
 278 permissions.
 279 .It Bq Er ELOOP
 280 Too many symbolic links were encountered in translating the pathname.
 281 .It Bq Er EISDIR
 282 An attempt is made to open a directory with write mode specified.
 283 .It Bq Er EINVAL
 284 The last component of the pathname specified for a
 285 .Dv DELETE
 286 or
 287 .Dv RENAME
 288 operation is
 289 .Ql \&. .
 290 .It Bq Er EROFS
 291 An attempt is made to modify a file or directory on a read-only file system.
 292 .El
 293 .Sh SEE ALSO
 294 .Xr uio 9 ,
 295 .Xr uma 9 ,
 296 .Xr VFS 9 ,
 297 .Xr vnode 9 ,
 298 .Xr vput 9 ,
 299 .Xr vref 9
 300 .Sh AUTHORS
 301 .An -nosplit
 302 This manual page was written by
 303 .An Eivind Eklund Aq Mt eivind@FreeBSD.org
 304 and later significantly revised by
 305 .An Hiten M. Pandya Aq Mt hmp@FreeBSD.org .
 306 .Sh BUGS
 307 The
 308 .Dv LOCKPARENT
 309 flag does not always result in the parent vnode being locked.
 310 This results in complications when the
 311 .Dv LOCKPARENT
 312 is used.
 313 In order to solve this for the cases where both
 314 .Dv LOCKPARENT
 315 and
 316 .Dv LOCKLEAF
 317 are used, it is necessary to resort to recursive locking.