share/man/man9/vnsubr.9

   1 .\"     $NetBSD: vnsubr.9,v 1.37 2009/05/28 09:32:17 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 2001, 2005, 2006 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Gregory McGarry.
   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 NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd June 2, 2009
  31 .Dt VNSUBR 9
  32 .Os
  33 .Sh NAME
  34 .Nm vnsubr ,
  35 .Nm vn_bwrite ,
  36 .Nm vn_close ,
  37 .Nm vn_default_error ,
  38 .Nm vn_isunder ,
  39 .Nm vn_lock ,
  40 .Nm vn_markexec ,
  41 .Nm vn_marktext ,
  42 .Nm vn_rdwr ,
  43 .Nm vn_restorerecurse ,
  44 .Nm vn_setrecurse ,
  45 .Nm vn_open ,
  46 .Nm vn_stat ,
  47 .Nm vn_writechk
  48 .Nd high-level convenience functions for vnode operations
  49 .Sh SYNOPSIS
  50 .In sys/param.h
  51 .In sys/lock.h
  52 .In sys/vnode.h
  53 .Ft int
  54 .Fn vn_bwrite "void *ap"
  55 .Ft int
  56 .Fn vn_close "struct vnode *vp" "int flags" "kauth_cred_t cred"
  57 .Ft int
  58 .Fn vn_default_error "void *v"
  59 .Ft int
  60 .Fn vn_isunder "struct vnode *dvp" "struct vnode *rvp" "struct lwp *l"
  61 .Ft int
  62 .Fn vn_lock "struct vnode *vp" "int flags"
  63 .Ft void
  64 .Fn vn_markexec "struct vnode *vp"
  65 .Ft void
  66 .Fn vn_marktext "struct vnode *vp"
  67 .Ft u_int
  68 .Fn vn_setrecurse "struct vnode *vp"
  69 .Ft void
  70 .Fn vn_restorerecurse "struct vnode *vp" "u_int flags"
  71 .Ft int
  72 .Fn vn_open "struct nameidata *ndp" "int fmode" "int cmode"
  73 .Ft int
  74 .Fo vn_rdwr
  75 .Fa "enum uio_rw rw" "struct vnode *vp" "void *base"
  76 .Fa "int len" "off_t offset" "enum uio_seg segflg" "int ioflg"
  77 .Fa "kauth_cred_t cred" "size_t *aresid" "struct lwp *l"
  78 .Fc
  79 .Ft int
  80 .Fn vn_readdir "file_t *fp" "char *buf" "int segflg" "u_int count" "int *done" "struct lwp *l" "off_t **cookies" "int *ncookies"
  81 .Ft int
  82 .Fn vn_stat "struct vnode *vp" "struct stat *sb"
  83 .Ft int
  84 .Fn vn_writechk "struct vnode *vp"
  85 .Sh DESCRIPTION
  86 The high-level functions described in this page are convenience
  87 functions for simplified access to the vnode operations described in
  88 .Xr vnodeops 9 .
  89 .Sh FUNCTIONS
  90 .Bl -tag -width compact
  91 .It Fn vn_bwrite "ap"
  92 Common code for block write operations.
  93 .It Fn vn_close "vp" "flags" "cred"
  94 Common code for a vnode close.
  95 The argument
  96 .Fa vp
  97 is the unlocked vnode of the vnode to close.
  98 .Fn vn_close
  99 simply locks the vnode, invokes the vnode operation
 100 .Xr VOP_CLOSE 9
 101 and calls
 102 .Fn vput
 103 to return the vnode to the freelist or holdlist.
 104 Note that
 105 .Fn vn_close
 106 expects an unlocked, referenced vnode and will dereference the vnode
 107 prior to returning.
 108 If the operation is successful zero is returned,
 109 otherwise an appropriate error is returned.
 110 .It Fn vn_default_error "v"
 111 A generic "default" routine that just returns error.
 112 It is used by a file system to specify unsupported operations in
 113 the vnode operations vector.
 114 .It Fn vn_isunder "dvp" "rvp" "l"
 115 Common code to check if one directory specified by the vnode
 116 .Fa rvp
 117 can be found inside the directory specified by the vnode
 118 .Fa dvp .
 119 The argument
 120 .Fa l
 121 is the calling process.
 122 .Fn vn_isunder
 123 is intended to be used in
 124 .Xr chroot 2 ,
 125 .Xr chdir 2 ,
 126 .Xr fchdir 2 ,
 127 etc., to ensure that
 128 .Xr chroot 2
 129 actually means something.
 130 If the operation is successful zero is returned, otherwise 1 is returned.
 131 .It Fn vn_lock "vp" "flags"
 132 Common code to acquire the lock for vnode
 133 .Fa vp .
 134 The argument
 135 .Fa flags
 136 specifies the
 137 .Xr lockmgr 9
 138 flags used to lock the vnode.
 139 If the operation is successful zero is returned, otherwise an
 140 appropriate error code is returned.
 141 The vnode interlock
 142 .Em v_interlock
 143 is released on return.
 144 .Pp
 145 .Fn vn_lock
 146 must not be called when the vnode's reference count is zero.
 147 Instead,
 148 .Xr vget 9
 149 should be used.
 150 .It Fn vn_markexec "vp"
 151 Common code to mark the vnode
 152 .Fa vp
 153 as containing executable code of a running process.
 154 .It Fn vn_marktext "vp"
 155 Common code to mark the vnode
 156 .Fa vp
 157 as being the text of a running process.
 158 .It Fn vn_setrecurse "vp"
 159 Common code to enable
 160 .Dv LK_CANRECURSE
 161 on the vnode lock for vnode
 162 .Fa vp .
 163 .Fn vn_setrecurse
 164 returns the new
 165 .Xr lockmgr 9
 166 flags after the update.
 167 .It Fn vn_restorerecurse "vp" "flags"
 168 Common code to restore the vnode lock flags for the vnode
 169 .Fa vp .
 170 It is called when done with
 171 .Fn vn_setrecurse .
 172 .It Fn vn_open "ndp" "fmode" "cmode"
 173 Common code for vnode open operations.
 174 The pathname is described in the nameidata pointer (see
 175 .Xr namei 9 ) .
 176 The arguments
 177 .Fa fmode
 178 and
 179 .Fa cmode
 180 specify the
 181 .Xr open 2
 182 file mode and the access permissions for creation.
 183 .Fn vn_open
 184 checks  permissions and invokes the
 185 .Xr VOP_OPEN 9
 186 or
 187 .Xr VOP_CREATE 9
 188 vnode operations.
 189 If the operation is successful zero is returned and the vnode is locked,
 190 otherwise an appropriate error code is returned.
 191 .It Fn vn_rdwr "rw" "vp" "base" "len" "offset" "segflg" "ioflg" "cred" "aresid" "l"
 192 Common code to package up an I/O request on a vnode into a uio and
 193 then perform the I/O.
 194 The argument
 195 .Fa rw
 196 specifies whether the I/O is a read
 197 .Pq Dv UIO_READ
 198 or write
 199 .Pq Dv UIO_WRITE
 200 operation.
 201 The vnode is specified by
 202 .Fa vp .
 203 The arguments
 204 .Fa l
 205 and
 206 .Fa cred
 207 are the calling lwp and its credentials.
 208 If
 209 .Fa ioflg
 210 contains
 211 .Dv IO_NODELOCKED ,
 212 it is expected that the vnode is locked.
 213 .Fa ioflg
 214 will be passed to
 215 .Fn VOP_READ Ns No / Ns Fn VOP_WRITE .
 216 The remaining arguments specify the uio parameters.
 217 For further information on these parameters see
 218 .Xr uiomove 9 .
 219 .It Fn vn_readdir "fp" "buf" "segflg" "count" "done" "l" "cookies" "ncookies"
 220 Common code for reading the contents of a directory.
 221 The argument
 222 .Fa fp
 223 is the file structure,
 224 .Fa buf
 225 is the buffer for placing the struct dirent structures.
 226 The arguments
 227 .Fa cookies
 228 and
 229 .Fa ncookies
 230 specify the addresses for the list and number of directory seek
 231 cookies generated for NFS.
 232 Both
 233 .Fa cookies
 234 and
 235 .Fa ncookies
 236 should be
 237 .Dv NULL
 238 if they aren't required to be returned by
 239 .Fn vn_readdir .
 240 If the operation is successful zero is returned, otherwise an
 241 appropriate error code is returned.
 242 .It Fn vn_stat "vp" "sb"
 243 Common code for a vnode stat operation.
 244 The vnode is specified by the argument
 245 .Fa vp ,
 246 and
 247 .Fa sb
 248 is the buffer to return the stat information.
 249 .Fn vn_stat
 250 basically calls the vnode operation
 251 .Xr VOP_GETATTR 9
 252 and transfers the contents of a vattr structure into a struct stat.
 253 If the operation is successful zero is returned, otherwise an
 254 appropriate error code is returned.
 255 .It Fn vn_writechk "vp"
 256 Common code to check for write permission on the vnode
 257 .Fa vp .
 258 A vnode is read-only if it is in use as a process's text image.
 259 If the vnode is read-only ETEXTBSY is returned, otherwise zero is
 260 returned to indicate that the vnode can be written to.
 261 .El
 262 .Sh ERRORS
 263 .Bl -tag -width Er
 264 .It Bq Er EBUSY
 265 The LK_NOWAIT flag was set and
 266 .Fn vn_lock
 267 would have slept.
 268 .It Bq Er ENOENT
 269 The vnode has been reclaimed and is dead.
 270 This error is only returned if the LK_RETRY flag is not passed to
 271 .Fn vn_lock .
 272 .It Bq Er ETXTBSY
 273 Cannot write to a vnode since is a process's text image.
 274 .El
 275 .Sh CODE REFERENCES
 276 This section describes places within the
 277 .Nx
 278 source tree where actual code implementing or using the vnode
 279 framework can be found.
 280 All pathnames are relative to
 281 .Pa /usr/src .
 282 .Pp
 283 The high-level convenience functions are implemented within the files
 284 .Pa sys/kern/vfs_vnops.c
 285 and
 286 .Pa sys/sys/vnode.h .
 287 .Sh SEE ALSO
 288 .Xr file 9 ,
 289 .Xr intro 9 ,
 290 .Xr lock 9 ,
 291 .Xr namei 9 ,
 292 .Xr vattr 9 ,
 293 .Xr vfs 9 ,
 294 .Xr vnode 9 ,
 295 .Xr vnodeops 9