share/man/man9/namei.9

   1 .\" Copyright (c) 1998, 1999 Eivind Eklund
   2 .\"
   3 .\" All rights reserved.
   4 .\"
   5 .\" This program is free software.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
  17 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  18 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  19 .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
  20 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  21 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  22 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  23 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  24 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  25 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  26 .\"
  27 .\"
  28 .\" If you integrate this manpage in another OS, I'd appreciate a note
  29 .\"     - eivind@FreeBSD.org
  30 .\"
  31 .\" $FreeBSD: src/share/man/man9/namei.9,v 1.8.2.8 2001/12/17 11:30:18 ru Exp $
  32 .\" $DragonFly: src/share/man/man9/Attic/namei.9,v 1.3 2004/06/01 11:36:53 hmp Exp $
  33 .\"
  34 .Dd December 16, 1998
  35 .Os
  36 .Dt NAMEI 9
  37 .Sh NAME
  38 .Nm namei ,
  39 .Nm NDINIT
  40 .Nd convert pathname to a pointer to a locked vnode
  41 .Sh SYNOPSIS
  42 .In sys/types.h
  43 .In sys/namei.h
  44 .Ft int
  45 .Fn namei "struct nameidata *ndp"
  46 .Ft void
  47 .Fn NDINIT "struct nameidata *ndp" "u_long operation" "u_long operflags" "enum uio_seg segflag" "const char *path" "struct proc *proc"
  48 .Ft void
  49 .Fn NDFREE "struct nameidata *ndp" "u_int operflags"
  50 .Sh DESCRIPTION
  51 .Fn namei
  52 is used to get from a pathname to a vnode for the object.
  53 This is a necessity to start doing VFS operations.  The vnode
  54 returned will have its reference count increased; when you're through
  55 with it, you have to release it using either
  56 .Xr vrele 9
  57 or
  58 .Xr vput 9 ,
  59 depending on whether you specified the LOCKLEAF flag or not.
  60 .Pp
  61 To initialize the nameidata struct, you usually use
  62 .Fn NDINIT .
  63 It takes the following arguments:
  64 .Pp
  65 .Bl -tag -width nameidatap
  66 .It Ar nameidatap
  67 pointer to the struct nameidata to initialize
  68 .It Ar operation
  69 The operation to have
  70 .Fn namei
  71 do.  The relevant operations are
  72 .Dv LOOKUP ,
  73 .Dv CREATE ,
  74 .Dv DELETE ,
  75 and
  76 .Dv RENAME .
  77 The latter three are just setup for those
  78 effects; just calling
  79 .Fn namei
  80 will not result in
  81 .Fn VOP_RENAME
  82 being called.
  83 .It Ar operflags
  84 Operation flags.  Several of these can be effective at the same time.
  85 .It Ar segflag
  86 Segment indicator.  This tells if the name of the object is in
  87 userspace (UIO_USERSPACE) or in the kernel address space (UIO_SYSSPACE).
  88 .It Ar path
  89 Pointer to pathname buffer (the file or directory name that will be
  90 looked up)
  91 .It Ar proc
  92 Which process context to use for the
  93 .Fn namei
  94 locks.
  95 .El
  96 .Sh NAMEI OPERATION FLAGS
  97 .Fn namei
  98 takes the following set of 'operation flags' that influence
  99 how it operates:
 100 .Bl -tag -width WANTPARENT
 101 .It Dv LOCKLEAF
 102 Lock vnode on return.  This is a full lock of the vnode; you'll have to use
 103 .Xr VOP_UNLOCK 9
 104 to release the lock (or use
 105 .Xr vput 9
 106 to release the lock and do a
 107 .Xr vrele 9 ,
 108 all in one).
 109 .It Dv LOCKPARENT
 110 Make
 111 .Fn namei
 112 also return the parent (directory) vnode (in nd.ni_dvp),
 113 in locked state, unless the dvp is identical to the vp, in which case the dvp
 114 is not locked per se (but may be locked due to LOCKLEAF).
 115 If you get a lock, remember to release the lock (using
 116 .Xr vput 9
 117 or
 118 .Xr VOP_UNLOCK 9
 119 and
 120 .Xr vrele 9 . )
 121 .It Dv WANTPARENT
 122 Make
 123 .Fn namei
 124 also return the parent (directory) vnode, in unlocked
 125 state.  Remember to release it (using
 126 .Xr vrele 9 . )
 127 .It Dv NOCACHE
 128 Avoid
 129 .Fn namei
 130 creating this entry in the namecache if it is not
 131 already present.  Normally
 132 .Fn namei
 133 will add entries to the name cache
 134 if they're not already there.
 135 .It Dv FOLLOW
 136 With this flag,
 137 .Fn namei
 138 will follow the symbolic link if the last part
 139 of the path supplied is a symbolic link (i.e., it will return a vnode
 140 for whatever the link points at, instead for the link itself).
 141 .It Dv NOOBJ
 142 Do not call
 143 .Fn vfs_object_create
 144 for the returned vnode even if it is
 145 just a VREG and we're able to (ie, it is locked).
 146 .It Dv NOFOLLOW
 147 Do not follow symbolic links (pseudo).
 148 This flag is not looked for by the actual code, which looks for
 149 FOLLOW.
 150 NOFOLLOW is used to indicate to the source code reader that symlinks
 151 are intentionally not followed.
 152 .El
 153 .Sh ALLOCATED ELEMENTS
 154 .Bl -tag -width WANTPARENT
 155 .It Dv ni_startdir
 156 Where we did lookup relative to.
 157 In the normal case, this is either the current directory or the root.
 158 It is the current directory if the name passed in doesn't start with /
 159 and we have not gone through any symlinks with an absolute path, and
 160 the root otherwise.
 161 .Pp
 162 In this case, it is only used by
 163 .Fn lookup ,
 164 and should not be
 165 considered valid after a call to
 166 .Fn namei .
 167 .Pp
 168 If SAVESTART is set, this is set to the same as ni_dvp, with an extra
 169 .Fn VREF .
 170 .Pp
 171 To block NDFREE from releasing ni_startdir when it is set, use the
 172 flag NDF_NO_STARTDIR_RELE.
 173 .It Dv ni_dvp
 174 The directory vp for the directory the object we're looking up is in.
 175 This is available on successful return if LOCKPARENT or WANTPARENT is
 176 set.  It is locked if LOCKPARENT is set.  Freeing this in NDFREE can
 177 be inhibited by NDF_NO_DVP_RELE, NDF_NO_DVP_PUT, or NDF_NO_DVP_UNLOCK
 178 (with the obvious effects).
 179 .It Dv ni_vp
 180 The vp for the target of the of the pathname exists, NULL otherwise.
 181 The vp is returned with increased reference count (VREF'ed).  If
 182 LOCKLEAF is set, it is also locked.
 183 .Pp
 184 Freeing this in NDFREE can be inhibited by NDF_NO_VP_RELE,
 185 NDF_NO_VP_PUT, or NDF_NO_VP_UNLOCK (with the obvious effects).
 186 .It Dv ni_cnd.cn_pnbuf
 187 Path name buffer.  This is allocated through zalloc(namei_zone)
 188 and freed through zfree(namei_zone, ...).
 189 .Pp
 190 This is available to the caller (who must free it using
 191 .Xr NDFREE 9 )
 192 if SAVESTART or SAVENAME is set.
 193 To free only the ni_cnd.cn_pnbuf, there is a special flags NDF_ONLY_PNBUF.
 194 To not free the cnd, use the flag ND_NO_FREE_PNBUF.
 195 .El
 196 .Sh BUGS
 197 LOCKPARENT does not always result in parent vp being locked (see details in
 198 description).
 199 This results in complications everywhere LOCKPARENT is used.
 200 In order to solve this for the cases that include both LOCKPARENT and LOCKLEAF,
 201 it will be necessary to go to recursive locking.
 202 .Sh SEE ALSO
 203 .Xr VFS 9 ,
 204 .Xr vnode 9
 205 .Pp
 206 .Pa src/sys/kern/vfs_lookup.c
 207 .Sh AUTHORS
 208 This man page was written by
 209 .An Eivind Eklund .