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