share/man/man9/vnfileops.9

   1 .\"     $NetBSD: vnfileops.9,v 1.14 2008/04/30 13:10:59 martin 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 April 9, 2008
  31 .Dt VNFILEOPS 9
  32 .Os
  33 .Sh NAME
  34 .Nm vnfileops ,
  35 .Nm vn_closefile ,
  36 .Nm vn_fcntl ,
  37 .Nm vn_ioctl ,
  38 .Nm vn_read ,
  39 .Nm vn_poll ,
  40 .Nm vn_statfile ,
  41 .Nm vn_write
  42 .Nd vnode file descriptor operations
  43 .Sh SYNOPSIS
  44 .In sys/param.h
  45 .In sys/file.h
  46 .In sys/vnode.h
  47 .Ft int
  48 .Fn vn_closefile "file_t *fp"
  49 .Ft int
  50 .Fn vn_fcntl "file_t *fp" "u_int com" "void *data"
  51 .Ft int
  52 .Fn vn_ioctl "file_t *fp" "u_long com" "void *data"
  53 .Ft int
  54 .Fn vn_read "file_t *fp" "off_t *offset" "struct uio *uio" "kauth_cred_t cred" "int flags"
  55 .Ft int
  56 .Fn vn_poll "file_t *fp" "int events"
  57 .Ft int
  58 .Fn vn_statfile "file_t *fp" "struct stat *sb"
  59 .Ft int
  60 .Fn vn_write "file_t *fp" "off_t *offset" "struct uio *uio" "kauth_cred_t cred" "int flags"
  61 .Sh DESCRIPTION
  62 The functions described in this page are the vnode-specific file
  63 descriptor operations.
  64 They should only be accessed through the opaque function pointers
  65 in the file entries (see
  66 .Xr file 9 ) .
  67 They are described here only for completeness.
  68 .Sh FUNCTIONS
  69 .Bl -tag -width compact
  70 .It Fn vn_closefile "fp" "l"
  71 Common code for a file table vnode close operation.
  72 The file is described by
  73 .Fa fp
  74 and
  75 .Fa l
  76 is the calling lwp.
  77 .Fn vn_closefile
  78 simply calls
  79 .Xr vn_close 9
  80 with the appropriate arguments.
  81 .It Fn vn_fcntl "fp" "com" "data" "l"
  82 Common code for a file table vnode
  83 .Xr fcntl 2
  84 operation.
  85 The file is specified by
  86 .Fa fp .
  87 The argument
  88 .Fa l
  89 is the calling lwp.
  90 .Fn vn_fcntl
  91 simply locks the vnode and invokes the vnode operation
  92 .Xr VOP_FCNTL 9
  93 with the command
  94 .Fa com
  95 and buffer
  96 .Fa data .
  97 The vnode is unlocked on return.
  98 If the operation is successful zero is returned, otherwise an
  99 appropriate error is returned.
 100 .It Fn vn_ioctl "fp" "com" "data" "l"
 101 Common code for a file table vnode ioctl operation.
 102 The file is specified by
 103 .Fa fp .
 104 The argument
 105 .Fa l
 106 is the calling lwp
 107 .Fn vn_ioctl
 108 simply locks the vnode and invokes the vnode operation
 109 .Xr VOP_IOCTL 9
 110 with the command
 111 .Fa com
 112 and buffer
 113 .Fa data .
 114 The vnode is unlocked on return.
 115 If the operation is successful zero is returned, otherwise an
 116 appropriate error is returned.
 117 .It Fn vn_read "fp" "offset" "uio" "cred" "flags"
 118 Common code for a file table vnode read.
 119 The argument
 120 .Fa fp
 121 is the file structure,  The argument
 122 .Fa offset
 123 is the offset into the file.
 124 The argument
 125 .Fa uio
 126 is the uio structure describing the memory to read into.
 127 The caller's credentials are specified in
 128 .Fa cred .
 129 The
 130 .Fa flags
 131 argument can define FOF_UPDATE_OFFSET to update the read position in
 132 the file.
 133 If the operation is successful zero is returned, otherwise an
 134 appropriate error is returned.
 135 .It Fn vn_poll "fp" "events" "l"
 136 Common code for a file table vnode poll operation.
 137 .Fn vn_poll
 138 simply calls
 139 .Xr VOP_POLL 9
 140 with the events
 141 .Fa events
 142 and the calling lwp
 143 .Fa l .
 144 The function returns a bitmask of available events.
 145 .It Fn vn_statfile "fp" "sb" "l"
 146 Common code for a stat operation.
 147 The file descriptor is specified by the argument
 148 .Fa fp
 149 and
 150 .Fa sb
 151 is the buffer to return the stat information.
 152 The argument
 153 .Fa l
 154 is the calling lwp.
 155 .Fn vn_statfile
 156 basically calls the vnode operation
 157 .Xr VOP_GETATTR 9
 158 and transfer the contents of a vattr structure into a struct stat.
 159 If the operation is successful zero is returned, otherwise an
 160 appropriate error code is returned.
 161 .It Fn vn_write "fp" "offset" "uio" "cred" "flags"
 162 Common code for a file table vnode write.
 163 The argument
 164 .Fa fp
 165 is the file structure,  The argument
 166 .Fa offset
 167 is the offset into the file.
 168 The argument
 169 .Fa uio
 170 is the uio structure describing the memory to read from.
 171 The caller's credentials are specified in
 172 .Fa cred .
 173 The
 174 .Fa flags
 175 argument can define FOF_UPDATE_OFFSET to update the read position in
 176 the file.
 177 If the operation is successful zero is returned, otherwise an
 178 appropriate error is returned.
 179 .El
 180 .Sh CODE REFERENCES
 181 This section describes places within the
 182 .Nx
 183 source tree where actual code implementing or using the vnode
 184 framework can be found.
 185 All pathnames are relative to
 186 .Pa /usr/src .
 187 .Pp
 188 The high-level convenience functions are implemented within the file
 189 .Pa sys/kern/vfs_vnops.c .
 190 .Sh SEE ALSO
 191 .Xr file 9 ,
 192 .Xr intro 9 ,
 193 .Xr vnode 9 ,
 194 .Xr vnodeops 9 ,
 195 .Xr vnsubr 9