share/man/man9/filedesc.9

   1 .\"     $NetBSD: filedesc.9,v 1.14 2006/07/25 05:15:56 riz 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 July 24, 2006
  31 .Dt FILEDESC 9
  32 .Os
  33 .Sh NAME
  34 .Nm filedesc ,
  35 .Nm dupfdopen ,
  36 .Nm falloc ,
  37 .Nm fd_getfile ,
  38 .Nm fdalloc ,
  39 .Nm fdcheckstd ,
  40 .Nm fdclear ,
  41 .Nm fdclone ,
  42 .Nm fdcloseexec ,
  43 .Nm fdcopy ,
  44 .Nm fdexpand ,
  45 .Nm fdfree ,
  46 .Nm fdinit ,
  47 .Nm fdrelease ,
  48 .Nm fdremove ,
  49 .Nm fdshare ,
  50 .Nm fdunshare
  51 .Nd file descriptor tables and operations
  52 .Sh SYNOPSIS
  53 .In sys/file.h
  54 .In sys/filedesc.h
  55 .Ft int
  56 .Fn falloc "struct lwp *l" "struct file **resultfp" "int *resultfd"
  57 .Ft struct file *
  58 .Fn fd_getfile "struct filedesc *fdp" "int fd"
  59 .Ft int
  60 .Fn dupfdopen "struct lwp *l" "int indx" "int dfd" "int mode" "int error"
  61 .Ft int
  62 .Fn fdalloc "struct proc *p" "int want" "int *result"
  63 .Ft int
  64 .Fn fdcheckstd "struct lwp *l"
  65 .Ft void
  66 .Fn fdclear "struct lwp *l"
  67 .Ft int
  68 .Fn fdclone "struct lwp *l" "struct file *fp" "int fd" "int flag" "const struct fileops *fops" "void *data"
  69 .Ft void
  70 .Fn fdcloseexec "struct lwp *l"
  71 .Ft struct filedesc *
  72 .Fn fdcopy "struct proc *p"
  73 .Ft void
  74 .Fn fdexpand "struct proc *p"
  75 .Ft void
  76 .Fn fdfree "struct lwp *l"
  77 .Ft struct filedesc *
  78 .Fn fdinit "struct proc *p"
  79 .Ft int
  80 .Fn fdrelease "struct lwp *l" "int fd"
  81 .Ft void
  82 .Fn fdremove "struct filedesc *fdp" "int fd"
  83 .Ft void
  84 .Fn fdshare "struct proc *p1" "struct proc *p2"
  85 .Ft void
  86 .Fn fdunshare "struct lwp *l"
  87 .Sh DESCRIPTION
  88 For user processes, all I/O is done through file descriptors.
  89 These file descriptors represent underlying objects supported by the kernel
  90 and are created by system calls specific to the type of object.
  91 In
  92 .Nx ,
  93 six types of objects can be represented by file descriptors: data
  94 files, pipes, sockets, event queues, crypto, and miscellaneous.
  95 .Pp
  96 The kernel maintains a descriptor table for each process which is used
  97 to translate the external representation of a file descriptor into an
  98 internal representation.
  99 The file descriptor is merely an index into this table.
 100 The file descriptor table maintains the following information:
 101 .Pp
 102 .Bl -bullet -compact
 103 .It
 104 the number of descriptors allocated in the file descriptor table;
 105 .It
 106 approximate next free descriptor;
 107 .It
 108 a reference count on the file descriptor table; and
 109 .It
 110 an array of open file entries.
 111 .El
 112 .Pp
 113 On creation of the file descriptor table, a fixed number of file
 114 entries are created.
 115 It is the responsibility of the file descriptor operations to expand the
 116 available number of entries if more are required.
 117 Each file entry in the descriptor table contains the information necessary
 118 to access the underlying object and to maintain common information.
 119 See
 120 .Xr file 9
 121 for details of operations on the file entries.
 122 .Pp
 123 New file descriptors are generally allocated by
 124 .Fn falloc
 125 and freed by
 126 .Fn fdrelease .
 127 File entries are extracted from the file descriptor table by
 128 .Fn fd_getfile .
 129 Most of the remaining functions in the interface are purpose specific
 130 and perform lower-level file descriptor operations.
 131 .Sh FUNCTIONS
 132 The following functions are high-level interface routines to access
 133 the file descriptor table for a process and its file entries.
 134 .Pp
 135 .Bl -tag -width compact
 136 .It Fn falloc "p" "*resultfp" "*resultfd"
 137 Create a new open file entry and allocate a file descriptor for
 138 process
 139 .Fa p .
 140 This operation is performed by invoking
 141 .Fn fdalloc
 142 to allocate the new file descriptor.
 143 The credential on the file entry are inherited from process
 144 .Fa p .
 145 The
 146 .Fn falloc
 147 function is responsible for expanding the file descriptor table when
 148 necessary.
 149 .Pp
 150 A pointer to the file entry is returned in
 151 .Fa *resultfp
 152 and the file descriptor is returned in
 153 .Fa *resultfd .
 154 The
 155 .Fn falloc
 156 function returns zero on success, otherwise an appropriate error is
 157 returned.
 158 .It Fn fd_getfile "fdp" "fd"
 159 Get the file entry for file descriptor
 160 .Fa fd
 161 in the file descriptor table
 162 .Fa fdp .
 163 The file entry is returned if it is valid and useable, otherwise
 164 .Dv NULL
 165 is returned.
 166 .It Fn dupfdopen "l" "indx" "dfd" "mode" "error"
 167 Duplicate file descriptor
 168 .Fa dfd
 169 for lwp
 170 .Fa l .
 171 .El
 172 .Pp
 173 The following functions operate on the file descriptor table for a
 174 process.
 175 .Pp
 176 .Bl -tag -width compact
 177 .It Fn fdalloc "p" "want" "*result"
 178 Allocate a file descriptor
 179 .Fa want
 180 for process
 181 .Fa p .
 182 The resultant file descriptor is returned in
 183 .Fa *result .
 184 The
 185 .Fn fdalloc
 186 function returns zero on success, otherwise an appropriate error is
 187 returned.
 188 .It Fn fdcheckstd "l"
 189 Check the standard file descriptors 0, 1, and 2 and ensure they are
 190 referencing valid file descriptors.
 191 If they are not, create references to
 192 .Pa /dev/null .
 193 This operation is necessary as these file descriptors are given implicit
 194 significance in the Standard C Library and it is unsafe for
 195 .Xr setuid 2
 196 and
 197 .Xr setgid 2
 198 processes to be started with these file descriptors closed.
 199 .It Fn fdclear "l"
 200 Clear the descriptor table for lwp
 201 .Fa l .
 202 This operation is performed by invoking
 203 .Fn fdinit
 204 to initialise a new file descriptor table to replace the old file
 205 descriptor table and invoking
 206 .Fn fdfree
 207 to release the old one.
 208 .It Fn fdclone "l" "fp" "fd" "flag" "fops" "data"
 209 This function is meant to be used by devices which allocate a file
 210 entry upon open.
 211 .Fn fdclone
 212 fills
 213 .Fa fp
 214 with the given parameters.
 215 It always returns the in-kernel errno value
 216 .Er EMOVEFD ,
 217 which is meant to be returned from the device open routine.
 218 This special return value is interpreted by the caller of the device
 219 open routine.
 220 .It Fn fdcloseexec "l"
 221 Close any files for process
 222 .Fa p
 223 that are marked
 224 .Dq close on exec .
 225 This operation is performed by invoking
 226 .Fn fdunshare
 227 for the process and invoking
 228 .Fn fdrelease
 229 on the appropriate file descriptor.
 230 .It Fn fdcopy "p"
 231 Copy the file descriptor table from process
 232 .Fa p
 233 and return a pointer to the copy.
 234 The returned file descriptor is guaranteed to have a reference count of one.
 235 All file descriptor state is maintained.
 236 The reference counts on each file entry referenced by the file
 237 descriptor table is incremented accordingly.
 238 .It Fn fdexpand "p"
 239 Expand the file descriptor table for process
 240 .Fa p
 241 by allocating memory for additional file descriptors.
 242 .It Fn fdfree "l"
 243 Decrement the reference count on the file descriptor table for lwp
 244 .Fa l
 245 and release the file descriptor table if the reference count drops to
 246 zero.
 247 .It Fn fdinit "p"
 248 Create a file descriptor table using the same current and root
 249 directories of process
 250 .Fa p .
 251 The returned file descriptor table is guaranteed to have a reference
 252 count of one.
 253 .It Fn fdrelease "l" "fd"
 254 Remove file descriptor
 255 .Fa fd
 256 from the file descriptor table of lwp
 257 .Fa l .
 258 The operation is performed by invoking
 259 .Fn closef .
 260 .It Fn fdremove "fdp" "fd"
 261 Unconditionally remove the file descriptor
 262 .Fa fd
 263 from file descriptor table
 264 .Fa fdp .
 265 .It Fn fdshare "p1" "p2"
 266 Share the file descriptor table belonging to process
 267 .Fa p1
 268 with process
 269 .Fa p2 .
 270 Process
 271 .Fa p2
 272 is assumed not to have a file descriptor table already allocated.
 273 The reference count on the file descriptor table is incremented.
 274 This function is used by
 275 .Xr fork1 9 .
 276 .It Fn fdunshare "l"
 277 Ensure that lwp
 278 .Fa l
 279 does not share its file descriptor table.
 280 If its file descriptor table has more than one reference, the file
 281 descriptor table is copied by invoking
 282 .Fn fdcopy .
 283 The reference count on the original file descriptor table is
 284 decremented.
 285 .El
 286 .Sh RETURN VALUES
 287 Successful operations return zero.
 288 A failed operation will return a non-zero return value.
 289 Possible values include:
 290 .Pp
 291 .Bl -tag -width Er
 292 .It Bq Er EBADF
 293 Bad file descriptor specified.
 294 .It Bq Er EMFILE
 295 Cannot exceed file descriptor limit.
 296 .It Bq Er ENOSPC
 297 No space left in file descriptor table.
 298 .El
 299 .Sh CODE REFERENCES
 300 This section describes places within the
 301 .Nx
 302 source tree where actual code implementing or using file
 303 descriptors can be found.
 304 All pathnames are relative to
 305 .Pa /usr/src .
 306 .Pp
 307 The framework for file descriptor handling is implemented within the
 308 file
 309 .Pa sys/kern/kern_descrip.c .
 310 .Sh SEE ALSO
 311 .Xr file 9