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.\" 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 July 24, 2006 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 fdcheckstd , 47.Nm fdclear , 48.Nm fdclone , 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 lwp *l" "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 lwp *l" "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 fdcheckstd "struct lwp *l" 72.Ft void 73.Fn fdclear "struct lwp *l" 74.Ft int 75.Fn fdclone "struct lwp *l" "struct file *fp" "int fd" "int flag" "const struct fileops *fops" "void *data" 76.Ft void 77.Fn fdcloseexec "struct lwp *l" 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 lwp *l" 84.Ft struct filedesc * 85.Fn fdinit "struct proc *p" 86.Ft int 87.Fn fdrelease "struct lwp *l" "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 lwp *l" 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 , 100six types of objects can be represented by file descriptors: data 101files, pipes, sockets, event queues, crypto, and miscellaneous. 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 "l" "indx" "dfd" "mode" "error" 174Duplicate file descriptor 175.Fa dfd 176for lwp 177.Fa l . 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 187for 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 fdcheckstd "l" 196Check the standard file descriptors 0, 1, and 2 and ensure they are 197referencing valid file descriptors. 198If they are not, create references to 199.Pa /dev/null . 200This operation is necessary as these file descriptors are given implicit 201significance in the Standard C Library and it is unsafe for 202.Xr setuid 2 203and 204.Xr setgid 2 205processes to be started with these file descriptors closed. 206.It Fn fdclear "l" 207Clear the descriptor table for lwp 208.Fa l . 209This operation is performed by invoking 210.Fn fdinit 211to initialise a new file descriptor table to replace the old file 212descriptor table and invoking 213.Fn fdfree 214to release the old one. 215.It Fn fdclone "l" "fp" "fd" "flag" "fops" "data" 216This function is meant to be used by devices which allocate a file 217entry upon open. 218.Fn fdclone 219fills 220.Fa fp 221with the given parameters. 222It always returns the in-kernel errno value 223.Er EMOVEFD , 224which is meant to be returned from the device open routine. 225This special return value is interpreted by the caller of the device 226open routine. 227.It Fn fdcloseexec "l" 228Close any files for process 229.Fa p 230that are marked 231.Dq close on exec . 232This operation is performed by invoking 233.Fn fdunshare 234for the process and invoking 235.Fn fdrelease 236on the appropriate file descriptor. 237.It Fn fdcopy "p" 238Copy the file descriptor table from process 239.Fa p 240and return a pointer to the copy. 241The returned file descriptor is guaranteed to have a reference count of one. 242All file descriptor state is maintained. 243The reference counts on each file entry referenced by the file 244descriptor table is incremented accordingly. 245.It Fn fdexpand "p" 246Expand the file descriptor table for process 247.Fa p 248by allocating memory for additional file descriptors. 249.It Fn fdfree "l" 250Decrement the reference count on the file descriptor table for lwp 251.Fa l 252and release the file descriptor table if the reference count drops to 253zero. 254.It Fn fdinit "p" 255Create a file descriptor table using the same current and root 256directories of process 257.Fa p . 258The returned file descriptor table is guaranteed to have a reference 259count of one. 260.It Fn fdrelease "l" "fd" 261Remove file descriptor 262.Fa fd 263from the file descriptor table of lwp 264.Fa l . 265The operation is performed by invoking 266.Fn closef . 267.It Fn fdremove "fdp" "fd" 268Unconditionally remove the file descriptor 269.Fa fd 270from file descriptor table 271.Fa fdp . 272.It Fn fdshare "p1" "p2" 273Share the file descriptor table belonging to process 274.Fa p1 275with process 276.Fa p2 . 277Process 278.Fa p2 279is assumed not to have a file descriptor table already allocated. 280The reference count on the file descriptor table is incremented. 281This function is used by 282.Xr fork1 9 . 283.It Fn fdunshare "l" 284Ensure that lwp 285.Fa l 286does not share its file descriptor table. 287If its file descriptor table has more than one reference, the file 288descriptor table is copied by invoking 289.Fn fdcopy . 290The reference count on the original file descriptor table is 291decremented. 292.El 293.Sh RETURN VALUES 294Successful operations return zero. 295A failed operation will return a non-zero return value. 296Possible values include: 297.Pp 298.Bl -tag -width Er 299.It Bq Er EBADF 300Bad file descriptor specified. 301.It Bq Er EMFILE 302Cannot exceed file descriptor limit. 303.It Bq Er ENOSPC 304No space left in file descriptor table. 305.El 306.Sh CODE REFERENCES 307This section describes places within the 308.Nx 309source tree where actual code implementing or using file 310descriptors can be found. 311All pathnames are relative to 312.Pa /usr/src . 313.Pp 314The framework for file descriptor handling is implemented within the 315file 316.Pa sys/kern/kern_descrip.c . 317.Sh SEE ALSO 318.Xr file 9 319