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