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 .\" $FreeBSD$
  35 .\"
  36 .Dd May 23, 2015
  37 .Dt NAMEI 9
  38 .Os
  39 .Sh NAME
  40 .Nm namei ,
  41 .Nm NDINIT ,
  42 .Nm NDFREE ,
  43 .Nd pathname translation and lookup operations
  44 .Sh SYNOPSIS
  45 .In sys/param.h
  46 .In sys/fcntl.h
  47 .In sys/namei.h
  48 .Ft int
  49 .Fn namei "struct nameidata *ndp"
  50 .Ft void
  51 .Fo NDINIT
  52 .Fa "struct nameidata *ndp" "u_long op" "u_long flags"
  53 .Fa "enum uio_seg segflg" "const char *namep" "struct thread *td"
  54 .Fc
  55 .Ft void
  56 .Fn NDFREE "struct nameidata *ndp" "const uint flags"
  57 .Sh DESCRIPTION
  58 The
  59 .Nm
  60 facility allows the client to perform pathname translation and lookup
  61 operations.
  62 The
  63 .Nm
  64 functions will increment the reference count for the vnode in question.
  65 The reference count has to be decremented after use of the vnode, by
  66 using either
  67 .Xr vrele 9
  68 or
  69 .Xr vput 9 ,
  70 depending on whether the
  71 .Dv LOCKLEAF
  72 flag was specified or not.
  73 .Pp
  74 The
  75 .Fn NDINIT
  76 function is used to initialize
  77 .Nm
  78 components.
  79 It takes the following arguments:
  80 .Bl -tag -width ".Fa segflg"
  81 .It Fa ndp
  82 The
  83 .Vt "struct nameidata"
  84 to initialize.
  85 .It Fa op
  86 The operation which
  87 .Fn namei
  88 will perform.
  89 The following operations are valid:
  90 .Dv LOOKUP , CREATE , DELETE ,
  91 and
  92 .Dv RENAME .
  93 The latter three are just setup for those
  94 effects; just calling
  95 .Fn namei
  96 will not result in
  97 .Fn VOP_RENAME
  98 being called.
  99 .It Fa flags
 100 Operation flags.
 101 Several of these can be effective at the same time.
 102 .It Fa segflg
 103 UIO segment indicator.
 104 This indicates if the name of the object is in userspace
 105 .Pq Dv UIO_USERSPACE
 106 or in the kernel address space
 107 .Pq Dv UIO_SYSSPACE .
 108 .It Fa namep
 109 Pointer to the component's pathname buffer
 110 (the file or directory name that will be looked up).
 111 .It Fa td
 112 The thread context to use for
 113 .Nm
 114 operations and locks.
 115 .El
 116 .Sh NAMEI OPERATION FLAGS
 117 The
 118 .Fn namei
 119 function takes the following set of
 120 .Dq "operation flags"
 121 that influence its operation:
 122 .Bl -tag -width ".Dv WANTPARENT"
 123 .It Dv LOCKLEAF
 124 Lock vnode on return with
 125 .Dv LK_EXCLUSIVE
 126 unless
 127 .Dv LOCKSHARED
 128 is also set.
 129 The
 130 .Xr VOP_UNLOCK 9
 131 should be used
 132 to release the lock (or
 133 .Xr vput 9
 134 which is equivalent to calling
 135 .Xr VOP_UNLOCK 9
 136 followed by
 137 .Xr vrele 9 ,
 138 all in one).
 139 .It Dv LOCKPARENT
 140 This flag lets the
 141 .Fn namei
 142 function return the parent (directory) vnode,
 143 .Va ni_dvp
 144 in locked state, unless it is identical to
 145 .Va ni_vp ,
 146 in which case
 147 .Va ni_dvp
 148 is not locked per se (but may be locked due to
 149 .Dv LOCKLEAF ) .
 150 If a lock is enforced, it should be released using
 151 .Xr vput 9
 152 or
 153 .Xr VOP_UNLOCK 9
 154 and
 155 .Xr vrele 9 .
 156 .It Dv LOCKSHARED
 157 Lock vnode on return with
 158 .Dv LK_SHARED .
 159 The
 160 .Xr VOP_UNLOCK 9
 161 should be used
 162 to release the lock (or
 163 .Xr vput 9
 164 which is equivalent to calling
 165 .Xr VOP_UNLOCK 9
 166 followed by
 167 .Xr vrele 9 ,
 168 all in one).
 169 .It Dv WANTPARENT
 170 This flag allows the
 171 .Fn namei
 172 function to return the parent (directory) vnode in an unlocked state.
 173 The parent vnode must be released separately by using
 174 .Xr vrele 9 .
 175 .It Dv NOCACHE
 176 Avoid
 177 .Fn namei
 178 creating this entry in the namecache if it is not
 179 already present.
 180 Normally,
 181 .Fn namei
 182 will add entries to the name cache
 183 if they are not already there.
 184 .It Dv FOLLOW
 185 With this flag,
 186 .Fn namei
 187 will follow the symbolic link if the last part
 188 of the path supplied is a symbolic link (i.e., it will return a vnode
 189 for whatever the link points at, instead for the link itself).
 190 .It Dv NOFOLLOW
 191 Do not follow symbolic links (pseudo).
 192 This flag is not looked for by the actual code, which looks for
 193 .Dv FOLLOW .
 194 .Dv NOFOLLOW
 195 is used to indicate to the source code reader that symlinks
 196 are intentionally not followed.
 197 .It Dv SAVENAME
 198 Do not free the pathname buffer at the end of the
 199 .Fn namei
 200 invocation; instead, free it later in
 201 .Fn NDFREE
 202 so that the caller may access the pathname buffer.
 203 See below for details.
 204 .It Dv SAVESTART
 205 Retain an additional reference to the parent directory; do not free
 206 the pathname buffer.
 207 See below for details.
 208 .El
 209 .Sh ALLOCATED ELEMENTS
 210 The
 211 .Vt nameidata
 212 structure is composed of the following fields:
 213 .Bl -tag -width ".Va ni_cnd.cn_pnbuf"
 214 .It Va ni_startdir
 215 In the normal case, this is either the current directory or the root.
 216 It is the current directory if the name passed in does not start with
 217 .Ql /
 218 and we have not gone through any symlinks with an absolute path, and
 219 the root otherwise.
 220 .Pp
 221 In this case, it is only used by
 222 .Fn lookup ,
 223 and should not be
 224 considered valid after a call to
 225 .Fn namei .
 226 If
 227 .Dv SAVESTART
 228 is set, this is set to the same as
 229 .Va ni_dvp ,
 230 with an extra
 231 .Xr vref 9 .
 232 To block
 233 .Fn NDFREE
 234 from releasing
 235 .Va ni_startdir ,
 236 the
 237 .Dv NDF_NO_STARTDIR_RELE
 238 can be set.
 239 .It Va ni_dvp
 240 Vnode pointer to directory of the object on which lookup is performed.
 241 This is available on successful return if
 242 .Dv LOCKPARENT
 243 or
 244 .Dv WANTPARENT
 245 is set.
 246 It is locked if
 247 .Dv LOCKPARENT
 248 is set.
 249 Freeing this in
 250 .Fn NDFREE
 251 can be inhibited by
 252 .Dv NDF_NO_DVP_RELE , NDF_NO_DVP_PUT ,
 253 or
 254 .Dv NDF_NO_DVP_UNLOCK
 255 (with the obvious effects).
 256 .It Va ni_vp
 257 Vnode pointer to the resulting object,
 258 .Dv NULL
 259 otherwise.
 260 The
 261 .Va v_usecount
 262 field of this vnode is incremented.
 263 If
 264 .Dv LOCKLEAF
 265 is set, it is also locked.
 266 .Pp
 267 Freeing this in
 268 .Fn NDFREE
 269 can be inhibited by
 270 .Dv NDF_NO_VP_RELE , NDF_NO_VP_PUT ,
 271 or
 272 .Dv NDF_NO_VP_UNLOCK
 273 (with the obvious effects).
 274 .It Va ni_cnd.cn_pnbuf
 275 The pathname buffer contains the location of the file or directory
 276 that will be used by the
 277 .Nm
 278 operations.
 279 It is managed by the
 280 .Xr uma 9
 281 zone allocation interface.
 282 If the
 283 .Dv SAVESTART
 284 or
 285 .Dv SAVENAME
 286 flag is set, then the pathname buffer is available
 287 after calling the
 288 .Fn namei
 289 function.
 290 .Pp
 291 To only deallocate resources used by the pathname buffer,
 292 .Va ni_cnd.cn_pnbuf ,
 293 then
 294 .Dv NDF_ONLY_PNBUF
 295 flag can be passed to the
 296 .Fn NDFREE
 297 function.
 298 To keep the pathname buffer intact,
 299 the
 300 .Dv NDF_NO_FREE_PNBUF
 301 flag can be passed to the
 302 .Fn NDFREE
 303 function.
 304 .El
 305 .Sh RETURN VALUES
 306 If successful,
 307 .Fn namei
 308 will return 0, otherwise it will return an error.
 309 .Sh FILES
 310 .Bl -tag -width Pa
 311 .It Pa src/sys/kern/vfs_lookup.c
 312 .El
 313 .Sh ERRORS
 314 Errors which
 315 .Fn namei
 316 may return:
 317 .Bl -tag -width Er
 318 .It Bq Er ENOTDIR
 319 A component of the specified pathname is not a directory when a directory is
 320 expected.
 321 .It Bq Er ENAMETOOLONG
 322 A component of a pathname exceeded 255 characters,
 323 or an entire pathname exceeded 1023 characters.
 324 .It Bq Er ENOENT
 325 A component of the specified pathname does not exist,
 326 or the pathname is an empty string.
 327 .It Bq Er EACCES
 328 An attempt is made to access a file in a way forbidden by its file access
 329 permissions.
 330 .It Bq Er ELOOP
 331 Too many symbolic links were encountered in translating the pathname.
 332 .It Bq Er EISDIR
 333 An attempt is made to open a directory with write mode specified.
 334 .It Bq Er EINVAL
 335 The last component of the pathname specified for a
 336 .Dv DELETE
 337 or
 338 .Dv RENAME
 339 operation is
 340 .Ql \&. .
 341 .It Bq Er EROFS
 342 An attempt is made to modify a file or directory on a read-only file system.
 343 .El
 344 .Sh SEE ALSO
 345 .Xr uio 9 ,
 346 .Xr uma 9 ,
 347 .Xr VFS 9 ,
 348 .Xr vnode 9 ,
 349 .Xr vput 9 ,
 350 .Xr vref 9
 351 .Sh AUTHORS
 352 .An -nosplit
 353 This manual page was written by
 354 .An Eivind Eklund Aq Mt eivind@FreeBSD.org
 355 and later significantly revised by
 356 .An Hiten M. Pandya Aq Mt hmp@FreeBSD.org .
 357 .Sh BUGS
 358 The
 359 .Dv LOCKPARENT
 360 flag does not always result in the parent vnode being locked.
 361 This results in complications when the
 362 .Dv LOCKPARENT
 363 is used.
 364 In order to solve this for the cases where both
 365 .Dv LOCKPARENT
 366 and
 367 .Dv LOCKLEAF
 368 are used, it is necessary to resort to recursive locking.