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