share/man/man9/file.9

   1 .\"     $NetBSD: file.9,v 1.12 2009/05/10 14:33:54 elad Exp $
   2 .\"
   3 .\" Copyright (c) 2002, 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 May 17, 2009
  31 .Dt FILE 9
  32 .Os
  33 .Sh NAME
  34 .Nm file ,
  35 .Nm closef ,
  36 .Nm ffree ,
  37 .Nm FILE_IS_USABLE ,
  38 .Nm FILE_USE ,
  39 .Nm FILE_UNUSE ,
  40 .Nm FILE_SET_MATURE
  41 .Nd operations on file entries
  42 .Sh SYNOPSIS
  43 .In sys/file.h
  44 .Ft int
  45 .Fn closef "struct file *fp" "struct lwp *l"
  46 .Ft void
  47 .Fn ffree "struct file *fp"
  48 .Ft int
  49 .Fn FILE_IS_USABLE "struct file *fp"
  50 .Ft void
  51 .Fn FILE_USE "struct file *fp"
  52 .Ft void
  53 .Fn FILE_UNUSE "struct file *fp" "struct lwp *l"
  54 .Ft void
  55 .Fn FILE_SET_MATURE "struct file *fp"
  56 .Sh DESCRIPTION
  57 The file descriptor table of a process references a file entry for
  58 each file used by the kernel.
  59 See
  60 .Xr filedesc 9
  61 for details of the file descriptor table.
  62 Each file entry is given by:
  63 .Pp
  64 .Bd -literal
  65 struct file {
  66         LIST_ENTRY(file) f_list;        /* list of active files */
  67         int             f_flag;
  68         int             f_iflags;       /* internal flags */
  69         int             f_type;         /* descriptor type */
  70         u_int           f_count;        /* reference count */
  71         u_int           f_msgcount;     /* message queue references */
  72         int             f_usecount;     /* number active users */
  73         kauth_cred_t    f_cred;         /* creds associated with descriptor */
  74         struct fileops {
  75                 int (*fo_read)(struct file *fp, off_t *offset,
  76                         struct uio *uio, kauth_cred_t cred, int flags);
  77                 int (*fo_write)(struct file *fp, off_t *offset,
  78                         struct uio *uio, kauth_cred_t cred, int flags);
  79                 int (*fo_ioctl)(struct file *fp, u_long com, void *data,
  80                         struct lwp *l);
  81                 int (*fo_fcntl)(struct file *fp, u_int com, void *data,
  82                         struct lwp *l);
  83                 int (*fo_poll)(struct file *fp, int events,
  84                         struct lwp *l);
  85                 int (*fo_stat)(struct file *fp, struct stat *sp,
  86                         struct lwp *l);
  87                 int (*fo_close)(struct file *fp, struct lwp *l);
  88         } *f_ops;
  89         off_t           f_offset;
  90         void         *f_data;         /* descriptor data */
  91 };
  92 .Ed
  93 .Pp
  94 .Nx
  95 treats file entries in an object-oriented fashion after they are created.
  96 Each entry specifies the object type,
  97 .Em f_type ,
  98 which can have the values
  99 .Dv DTYPE_VNODE ,
 100 .Dv DTYPE_SOCKET ,
 101 .Dv DTYPE_PIPE
 102 and
 103 .Dv DTYPE_MISC .
 104 The file entry also has a pointer to a data structure,
 105 .Em f_data ,
 106 that contains information specific to the instance of the underlying object.
 107 The data structure is opaque to the routines that manipulate the file entry.
 108 Each entry also contains an array of function pointers,
 109 .Em f_ops ,
 110 that translate the generic operations on a file descriptor into the
 111 specific action associated with its type.
 112 A reference to the data structure is passed as the first parameter to a
 113 function that implements a file operation.
 114 The operations that must be implemented for each descriptor type are
 115 read, write, ioctl, fcntl, poll, stat, and close.
 116 See
 117 .Xr vnfileops 9
 118 for an overview of the vnode file operations.
 119 All state associated with an instance of an object must be stored in
 120 that instance's data structure; the underlying objects are not permitted
 121 to manipulate the file entry themselves.
 122 .Pp
 123 For data files, the file entry points to a
 124 .Xr vnode 9
 125 structure.
 126 Pipes and sockets do not have data blocks allocated on the disk and
 127 are handled by the special-device filesystem that calls appropriate
 128 drivers to handle I/O for them.
 129 For pipes, the file entry points to a system block that is used during
 130 data transfer.
 131 For sockets, the file entry points to a system block that is used in
 132 doing interprocess communications.
 133 .Pp
 134 The descriptor table of a process (and thus access to the objects to
 135 which the descriptors refer) is inherited from its parent, so several
 136 different processes may reference the same file entry.
 137 Thus, each file entry has a reference count,
 138 .Em f_count .
 139 Each time a new reference is created, the reference count is incremented.
 140 When a descriptor is closed, the reference count is decremented.
 141 When the reference count drops to zero, the file entry is freed.
 142 .Pp
 143 Some file descriptor semantics can be altered through the
 144 .Ar flags
 145 argument to the
 146 .Xr open 2
 147 system call.
 148 These flags are recorded in
 149 .Em f_flags
 150 member of the file entry.
 151 For example, the flags record whether the descriptor is open for
 152 reading, writing, or both reading and writing.
 153 The following flags and their corresponding
 154 .Xr open 2
 155 flags are:
 156 .Pp
 157 .Bl -tag -offset indent -width FNONBLOCK -compact
 158 .It FAPPEND
 159 .Dv O_APPEND
 160 .It FASYNC
 161 .Dv O_ASYNC
 162 .It O_FSYNC
 163 .Dv O_SYNC
 164 .It FNDELAY
 165 .Dv O_NONBLOCK
 166 .It O_NDELAY
 167 .Dv O_NONBLOCK
 168 .It FNONBLOCK
 169 .Dv O_NONBLOCK
 170 .It FFSYNC
 171 .Dv O_SYNC
 172 .It FDSYNC
 173 .Dv O_DSYNC
 174 .It FRSYNC
 175 .Dv O_RSYNC
 176 .It FALTIO
 177 .Dv O_ALT_IO
 178 .El
 179 .Pp
 180 Some additional state-specific flags are recorded in the
 181 .Em f_iflags
 182 member.
 183 Valid values include:
 184 .Pp
 185 .Bl -tag -offset indent -width FIF_WANTCLOSE -compact
 186 .It FIF_WANTCLOSE
 187 If set, then the reference count on the file is zero, but there were
 188 multiple users of the file.
 189 This can happen if a file descriptor table is shared by multiple processes.
 190 This flag notifies potential users that the file is closing and will
 191 prevent them from adding additional uses to the file.
 192 .It FIF_LARVAL
 193 The file entry is not fully constructed (mature) and should not be used.
 194 .El
 195 .Pp
 196 The
 197 .Xr read 2
 198 and
 199 .Xr write 2
 200 system calls do not take an offset in the file as an argument.
 201 Instead, each read or write updates the current file offset,
 202 .Em f_offset
 203 in the file according to the number of bytes transferred.
 204 Since more than one process may open the same file and each needs its
 205 own offset in the file, the offset cannot be stored in the per-object
 206 data structure.
 207 .Sh FUNCTIONS
 208 .Bl -tag -width compact
 209 .It Fn closef "fp" "l"
 210 The internal form of
 211 .Xr close 2
 212 which decrements the reference count on file entry
 213 .Fa fp .
 214 The
 215 .Fn closef
 216 function  release all locks on the file owned by lwp
 217 .Fa l ,
 218 decrements the reference count on the file entry, and invokes
 219 .Fn ffree
 220 to free the file entry.
 221 .It Fn ffree "struct file *fp"
 222 Free file entry
 223 .Fa fp .
 224 The file entry was created in
 225 .Xr falloc 9 .
 226 .It Fn FILE_IS_USABLE "fp"
 227 Ensure that the file entry is useable by ensuring that neither the
 228 FIF_WANTCLOSE and FIF_LARVAL flags are not set in
 229 .Em f_iflags .
 230 .It Fn FILE_USE "fp"
 231 Increment the reference count on file entry
 232 .Fa fp .
 233 .It Fn FILE_UNUSE "fp" "l"
 234 Decrement the reference count on file entry
 235 .Fa fp .
 236 If the FIF_WANTCLOSE
 237 flag is set in
 238 .Em f_iflags ,
 239 the file entry is freed.
 240 .It Fn FILE_SET_MATURE "fp"
 241 Mark the file entry as being fully constructed (mature) by clearing
 242 the FIF_LARVAL flag in
 243 .Em f_iflags .
 244 .El
 245 .Sh CODE REFERENCES
 246 This section describes places within the
 247 .Nx
 248 source tree where actual code implementing or using file entries
 249 can be found.
 250 All pathnames are relative to
 251 .Pa /usr/src .
 252 .Pp
 253 The framework for file entry handling is implemented within the file
 254 .Pa sys/kern/kern_descrip.c .
 255 .Sh SEE ALSO
 256 .Xr dofileread 9 ,
 257 .Xr filedesc 9 ,
 258 .Xr vnfileops 9 ,
 259 .Xr vnode 9