share/man/man9/namei.9

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