1.\" $NetBSD: filedesc.9,v 1.5 2003/04/16 13:35:28 wiz Exp $ 2.\" 3.\" Copyright (c) 2002 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.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd October 12, 2002 38.Dt FILEDESC 9 39.Os 40.Sh NAME 41.Nm filedesc , 42.Nm dupfdopen , 43.Nm falloc , 44.Nm fd_getfile , 45.Nm fdalloc , 46.Nm fdavail , 47.Nm fdcheckstd , 48.Nm fdclear , 49.Nm fdcloseexec , 50.Nm fdcopy , 51.Nm fdexpand , 52.Nm fdfree , 53.Nm fdinit , 54.Nm fdrelease , 55.Nm fdremove , 56.Nm fdshare , 57.Nm fdunshare 58.Nd file descriptor tables and operations 59.Sh SYNOPSIS 60.In sys/file.h 61.In sys/filedesc.h 62.Ft int 63.Fn falloc "struct proc *p" "struct file **resultfp" "int *resultfd" 64.Ft struct file * 65.Fn fd_getfile "struct filedesc *fdp" "int fd" 66.Ft int 67.Fn dupfdopen "struct proc *p" "int indx" "int dfd" "int mode" "int error" 68.Ft int 69.Fn fdalloc "struct proc *p" "int want" "int *result" 70.Ft int 71.Fn fdavail "struct proc *p" "int n" 72.Ft int 73.Fn fdcheckstd "struct proc *p" 74.Ft void 75.Fn fdclear "struct proc *p" 76.Ft void 77.Fn fdcloseexec "struct proc *p" 78.Ft struct filedesc * 79.Fn fdcopy "struct proc *p" 80.Ft void 81.Fn fdexpand "struct proc *p" 82.Ft void 83.Fn fdfree "struct proc *p" 84.Ft struct filedesc * 85.Fn fdinit "struct proc *p" 86.Ft int 87.Fn fdrelease "struct proc *p" "int fd" 88.Ft void 89.Fn fdremove "struct filedesc *fdp" "int fd" 90.Ft void 91.Fn fdshare "struct proc *p1" "struct proc *p2" 92.Ft void 93.Fn fdunshare "struct proc *p" 94.Sh DESCRIPTION 95For user processes, all I/O is done through file descriptors. 96These file descriptors represent underlying objects supported by the kernel 97and are created by system calls specific to the type of object. 98In 99.Nx , 100three type of objects can be represented by file descriptors: data 101files, pipes, and sockets. 102.Pp 103The kernel maintains a descriptor table for each process which is used 104to translate the external representation of a file descriptor into an 105internal representation. 106The file descriptor is merely an index into this table. 107The file descriptor table maintains the following information: 108.Pp 109.Bl -bullet -compact 110.It 111the number of descriptors allocated in the file descriptor table; 112.It 113approximate next free descriptor; 114.It 115a reference count on the file descriptor table; and 116.It 117an array of open file entries. 118.El 119.Pp 120On creation of the file descriptor table, a fixed number of file 121entries are created. 122It is the responsibility of the file descriptor operations to expand the 123available number of entries if more are required. 124Each file entry in the descriptor table contains the information necessary 125to access the underlying object and to maintain common information. 126See 127.Xr file 9 128for details of operations on the file entries. 129.Pp 130New file descriptors are generally allocated by 131.Fn falloc 132and freed by 133.Fn fdrelease . 134File entries are extracted from the file descriptor table by 135.Fn fd_getfile . 136Most of the remaining functions in the interface are purpose specific 137and perform lower-level file descriptor operations. 138.Sh FUNCTIONS 139The following functions are high-level interface routines to access 140the file descriptor table for a process and its file entries. 141.Pp 142.Bl -tag -width compact 143.It Fn falloc "p" "*resultfp" "*resultfd" 144Create a new open file entry and allocate a file descriptor for 145process 146.Fa p . 147This operation is performed by invoking 148.Fn fdalloc 149to allocate the new file descriptor. 150The credential on the file entry are inherited from process 151.Fa p . 152The 153.Fn falloc 154function is responsible for expanding the file descriptor table when 155necessary. 156.Pp 157A pointer to the file entry is returned in 158.Fa *resultfp 159and the file descriptor is returned in 160.Fa *resultfd . 161The 162.Fn falloc 163function returns zero on success, otherwise an appropriate error is 164returned. 165.It Fn fd_getfile "fdp" "fd" 166Get the file entry for file descriptor 167.Fa fd 168in the file descriptor table 169.Fa fdp . 170The file entry is returned if it is valid and useable, otherwise 171.Dv NULL 172is returned. 173.It Fn dupfdopen "p" "indx" "dfd" "mode" "error" 174Duplicate file descriptor 175.Fa dfd 176for process 177.Fa p . 178.El 179.Pp 180The following functions operate on the file descriptor table for a 181process. 182.Pp 183.Bl -tag -width compact 184.It Fn fdalloc "p" "want" "*result" 185Allocate a file descriptor 186.Fa want 187 for process 188.Fa p . 189The resultant file descriptor is returned in 190.Fa *result . 191The 192.Fn fdalloc 193function returns zero on success, otherwise an appropriate error is 194returned. 195.It Fn fdavail "p" "n" 196Check to see whether 197.Fa n 198file descriptors are available to process 199.Fa p . 200Returns zero on success, or 1 on failure. 201.It Fn fdcheckstd "p" 202Check the standard file descriptors 0, 1, 2 and ensure they are 203referencing valid file descriptors. 204If they are not, create references to 205.Pa /dev/null . 206This operation is necessary as these file descriptors are given implicit 207significance in the Standard C Library and it is unsafe for 208.Xr setuid 2 209and 210.Xr setgid 2 211processes to be started with these file descriptors closed. 212.It Fn fdclear "p" 213Clear the descriptor table for process 214.Fa p . 215This operation is performed by invoking 216.Fn fdinit 217to initialise a new file descriptor table to replace the old file 218descriptor table and invoking 219.Fn fdfree 220to release the old one. 221.It Fn fdcloseexec "p" 222Close any files for process 223.Fa p 224that are marked 225.Dq close on exec . 226This operation is performed by invoking 227.Fn fdunshare 228for the process and invoking 229.Fn fdrelease 230on the appropriate file descriptor. 231.It Fn fdcopy "p" 232Copy the file descriptor table from process 233.Fa p 234and return a pointer to the copy. 235The returned file descriptor is guaranteed to have a reference count of one. 236All file descriptor state is maintained. 237The reference counts on each file entry referenced by the file 238descriptor table is incremented accordingly. 239.It Fn fdexpand "p" 240Expand the file descriptor table for process 241.Fa p 242by allocating memory for additional file descriptors. 243.It Fn fdfree "p" 244Decrement the reference count on the file descriptor table for process 245.Fa p 246and release the file descriptor table if the reference count drops to 247zero. 248.It Fn fdinit "p" 249Create a file descriptor table using the same current and root 250directories of process 251.Fa p . 252The returned file descriptor table is guaranteed to have a reference 253count of one. 254.It Fn fdrelease "p" "fd" 255Remove file descriptor 256.Fa fd 257from the file descriptor table of process 258.Fa p . 259The operation is performed by invoking 260.Fn closef . 261.It Fn fdremove "fdp" "fd" 262Unconditionally remove the file descriptor 263.Fa fd 264from file descriptor table 265.Fa fdp . 266.It Fn fdshare "p1" "p2" 267Share the file descriptor table belonging to process 268.Fa p1 269with process 270.Fa p2 . 271Process 272.Fa p2 273is assumed not to have a file descriptor table already allocated. 274The reference count on the file descriptor table is incremented. 275This function is used by 276.Xr fork1 9 . 277.It Fn fdunshare "p" 278Ensure that process 279.Fa p 280does not share its file descriptor table. 281If its file descriptor table has more than one reference, the file 282descriptor table is copied by invoking 283.Fn fdcopy . 284The reference count on the original file descriptor table is 285decremented. 286.El 287.Sh RETURN VALUES 288Successful operations return zero. 289A failed operation will return a non-zero return value. 290Possible values include: 291.Pp 292.Bl -tag -width Er 293.It Bq Er EBADF 294Bad file descriptor specified. 295.It Bq Er EMFILE 296Cannot exceed file descriptor limit. 297.It Bq Er ENOSPC 298No space left in file descriptor table. 299.El 300.Sh CODE REFERENCES 301This section describes places within the 302.Nx 303source tree where actual code implementing or using file 304descriptors can be found. 305All pathnames are relative to 306.Pa /usr/src . 307.Pp 308The framework for file descriptor handling is implemented within the 309file 310.Pa sys/kern/kern_descrip.c . 311.Sh SEE ALSO 312.Xr file 9 313