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