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 NOCACHE
 172 Avoid
 173 .Fn namei
 174 creating this entry in the namecache if it is not
 175 already present.
 176 Normally,
 177 .Fn namei
 178 will add entries to the name cache
 179 if they are not already there.
 180 .It Dv FOLLOW
 181 With this flag,
 182 .Fn namei
 183 will follow the symbolic link if the last part
 184 of the path supplied is a symbolic link (i.e., it will return a vnode
 185 for whatever the link points at, instead for the link itself).
 186 .It Dv NOFOLLOW
 187 Do not follow symbolic links (pseudo).
 188 This flag is not looked for by the actual code, which looks for
 189 .Dv FOLLOW .
 190 .Dv NOFOLLOW
 191 is used to indicate to the source code reader that symlinks
 192 are intentionally not followed.
 193 .It Dv SAVENAME
 194 Do not free the pathname buffer at the end of the
 195 .Fn namei
 196 invocation; instead, free it later in
 197 .Fn NDFREE
 198 so that the caller may access the pathname buffer.
 199 See below for details.
 200 .It Dv SAVESTART
 201 Retain an additional reference to the parent directory; do not free
 202 the pathname buffer.
 203 See below for details.
 204 .El
 205 .Sh ALLOCATED ELEMENTS
 206 The
 207 .Vt nameidata
 208 structure is composed of the following fields:
 209 .Bl -tag -width ".Va ni_cnd.cn_pnbuf"
 210 .It Va ni_startdir
 211 In the normal case, this is either the current directory or the root.
 212 It is the current directory if the name passed in does not start with
 213 .Ql /
 214 and we have not gone through any symlinks with an absolute path, and
 215 the root otherwise.
 216 .Pp
 217 In this case, it is only used by
 218 .Fn lookup ,
 219 and should not be
 220 considered valid after a call to
 221 .Fn namei .
 222 If
 223 .Dv SAVESTART
 224 is set, this is set to the same as
 225 .Va ni_dvp ,
 226 with an extra
 227 .Xr vref 9 .
 228 To block
 229 .Fn NDFREE
 230 from releasing
 231 .Va ni_startdir ,
 232 the
 233 .Dv NDF_NO_STARTDIR_RELE
 234 can be set.
 235 .It Va ni_dvp
 236 Vnode pointer to directory of the object on which lookup is performed.
 237 This is available on successful return if
 238 .Dv LOCKPARENT
 239 or
 240 .Dv WANTPARENT
 241 is set.
 242 It is locked if
 243 .Dv LOCKPARENT
 244 is set.
 245 Freeing this in
 246 .Fn NDFREE
 247 can be inhibited by
 248 .Dv NDF_NO_DVP_RELE , NDF_NO_DVP_PUT ,
 249 or
 250 .Dv NDF_NO_DVP_UNLOCK
 251 (with the obvious effects).
 252 .It Va ni_vp
 253 Vnode pointer to the resulting object,
 254 .Dv NULL
 255 otherwise.
 256 The
 257 .Va v_usecount
 258 field of this vnode is incremented.
 259 If
 260 .Dv LOCKLEAF
 261 is set, it is also locked.
 262 .Pp
 263 Freeing this in
 264 .Fn NDFREE
 265 can be inhibited by
 266 .Dv NDF_NO_VP_RELE , NDF_NO_VP_PUT ,
 267 or
 268 .Dv NDF_NO_VP_UNLOCK
 269 (with the obvious effects).
 270 .It Va ni_cnd.cn_pnbuf
 271 The pathname buffer contains the location of the file or directory
 272 that will be used by the
 273 .Nm
 274 operations.
 275 It is managed by the
 276 .Xr uma 9
 277 zone allocation interface.
 278 If the
 279 .Dv SAVESTART
 280 or
 281 .Dv SAVENAME
 282 flag is set, then the pathname buffer is available
 283 after calling the
 284 .Fn namei
 285 function.
 286 .Pp
 287 To only deallocate resources used by the pathname buffer,
 288 .Va ni_cnd.cn_pnbuf ,
 289 then
 290 .Dv NDF_ONLY_PNBUF
 291 flag can be passed to the
 292 .Fn NDFREE
 293 function.
 294 To keep the pathname buffer intact,
 295 the
 296 .Dv NDF_NO_FREE_PNBUF
 297 flag can be passed to the
 298 .Fn NDFREE
 299 function.
 300 .El
 301 .Sh RETURN VALUES
 302 If successful,
 303 .Fn namei
 304 will return 0, otherwise it will return an error.
 305 .Sh FILES
 306 .Bl -tag -width Pa
 307 .It Pa src/sys/kern/vfs_lookup.c
 308 .El
 309 .Sh ERRORS
 310 Errors which
 311 .Fn namei
 312 may return:
 313 .Bl -tag -width Er
 314 .It Bq Er ENOTDIR
 315 A component of the specified pathname is not a directory when a directory is
 316 expected.
 317 .It Bq Er ENAMETOOLONG
 318 A component of a pathname exceeded 255 characters,
 319 or an entire pathname exceeded 1023 characters.
 320 .It Bq Er ENOENT
 321 A component of the specified pathname does not exist,
 322 or the pathname is an empty string.
 323 .It Bq Er EACCES
 324 An attempt is made to access a file in a way forbidden by its file access
 325 permissions.
 326 .It Bq Er ELOOP
 327 Too many symbolic links were encountered in translating the pathname.
 328 .It Bq Er EISDIR
 329 An attempt is made to open a directory with write mode specified.
 330 .It Bq Er EINVAL
 331 The last component of the pathname specified for a
 332 .Dv DELETE
 333 or
 334 .Dv RENAME
 335 operation is
 336 .Ql \&. .
 337 .It Bq Er EROFS
 338 An attempt is made to modify a file or directory on a read-only file system.
 339 .El
 340 .Sh SEE ALSO
 341 .Xr uio 9 ,
 342 .Xr uma 9 ,
 343 .Xr VFS 9 ,
 344 .Xr vnode 9 ,
 345 .Xr vput 9 ,
 346 .Xr vref 9
 347 .Sh AUTHORS
 348 .An -nosplit
 349 This manual page was written by
 350 .An Eivind Eklund Aq eivind@FreeBSD.org
 351 and later significantly revised by
 352 .An Hiten M. Pandya Aq hmp@FreeBSD.org .
 353 .Sh BUGS
 354 The
 355 .Dv LOCKPARENT
 356 flag does not always result in the parent vnode being locked.
 357 This results in complications when the
 358 .Dv LOCKPARENT
 359 is used.
 360 In order to solve this for the cases where both
 361 .Dv LOCKPARENT
 362 and
 363 .Dv LOCKLEAF
 364 are used, it is necessary to resort to recursive locking.
 365 .Pp
 366 Non-MPSAFE file systems exist, requiring callers to conditionally unlock
 367 .Va Giant .