1.\" $NetBSD: filedesc.9,v 1.18 2019/04/08 13:30:46 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 April 8, 2019 31.Dt FILEDESC 9 32.Os 33.Sh NAME 34.Nm filedesc , 35.Nm fd_alloc , 36.Nm fd_checkstd , 37.Nm fd_clone , 38.Nm fd_closeexec , 39.Nm fd_copy , 40.Nm fd_dup , 41.Nm fd_dup2 , 42.Nm fd_dupopen , 43.Nm fd_free , 44.Nm fd_init , 45.Nm fd_getfile , 46.Nm fd_share , 47.Nm fd_tryexpand 48.Nd file descriptor tables and operations 49.Sh SYNOPSIS 50.In sys/file.h 51.In sys/filedesc.h 52.Ft int 53.Fn fd_alloc "proc_t *p" "int want" "int *result" 54.Ft int 55.Fn fd_checkstd "void" 56.Ft int 57.Fn fd_clone "file_t *fp" "int fd" "int flag" "const struct fileops *fops" "void *data" 58.Ft filedesc_t * 59.Fn fd_copy "void" 60.Ft void 61.Fn fd_closeexec "void" 62.Ft int 63.Fn fd_dup "file_t *fp" "int minfd" "int *newp" "bool exclose" 64.Ft int 65.Fn fd_dup2 "file_t *fp" "unsigned newfd" "int flags" 66.Ft int 67.Fn fd_dupopen "int old" "int *newp" "int error" 68.Ft void 69.Fn fd_free "void" 70.Ft filedesc_t * 71.Fn fd_init "filedesc_t *fdp" 72.Ft file_t * 73.Fn fd_getfile "unsigned fd" 74.Ft void 75.Fn fd_share "proc_t *p" 76.Ft void 77.Fn fd_tryexpand "proc_t *p" 78.Sh DESCRIPTION 79For user processes, all I/O is done through file descriptors. 80These file descriptors represent underlying objects supported by the kernel 81and are created by system calls specific to the type of object. 82In 83.Nx , 84six types of objects can be represented by file descriptors: data 85files, pipes, sockets, event queues, crypto, and miscellaneous. 86.Pp 87The kernel maintains a descriptor table for each process which is used 88to translate the external representation of a file descriptor into an 89internal representation. 90The file descriptor is merely an index into this table. 91The table maintains the following information: 92.Pp 93.Bl -bullet -compact 94.It 95the number of descriptors allocated in the file descriptor table; 96.It 97approximate next free descriptor; 98.It 99a reference count on the file descriptor table; and 100.It 101an array of open file entries. 102.El 103.Pp 104On creation of the file descriptor table, a fixed number of file 105entries are created. 106It is the responsibility of the file descriptor operations to expand the 107available number of entries if more are required. 108Each file entry in the descriptor table contains the information needed 109to access the underlying object and to maintain common information. 110See 111.Xr file 9 112for details of operations on the file entries. 113.Pp 114New file descriptors are generally allocated by 115.Fn fd_alloc 116and freed by 117.Fn fd_free . 118File entries are extracted from the file descriptor table by 119.Fn fd_getfile . 120Most of the remaining functions in the interface are purpose-specific 121and perform lower-level file descriptor operations. 122.Sh FUNCTIONS 123The following functions are high-level interface routines to access 124the file descriptor table for a process and its file entries. 125.Bl -tag -width compact 126.It Fn fd_alloc "p" "want" "*result" 127Create a new open file entry in the file descriptor table and 128allocate a file descriptor for the process 129.Fa p . 130The credential on the file entry are inherited from process 131.Fa p . 132Calling the 133.Fn fd_alloc 134function expands the file descriptor table when necessary. 135.Pp 136The index of the file entry is returned in 137.Fa *result . 138The 139.Fn fd_alloc 140function returns zero on success, or an appropriate error value 141otherwise. 142.It Fn fd_getfile "fd" 143Get the file entry for file descriptor . 144.Fa fd 145The file entry is returned if it is valid and usable, otherwise 146.Dv NULL 147is returned. 148.It Fn fd_dup "fp" "minfd" "*newp" "exclose" 149Duplicate file descriptor 150.Fa fp 151for the current process. 152The fd picked will be at least 153.Fa minfd . 154The resulting descriptor is given in 155.Fa newp . 156.It Fn fd_dup2 "fp" "newfd" "flags" 157Duplicate file descriptor 158.Fa fp 159in fd number 160.Fa newfd . 161If newfd is already in use by an open file, close it (See 162.Xr dup2 2 ) . 163.It Fn fd_dupopen "old" "*newp" "error" 164Duplicate file descriptor specified in 165.Fa old 166for the current lwp. 167.El 168.Pp 169The following functions operate on the file descriptor table for a 170process. 171.Bl -tag -width compact 172.It Fn fd_alloc "p" "want" "*result" 173Allocate a file descriptor 174.Fa want 175for process 176.Fa p . 177The resultant file descriptor is returned in 178.Fa *result . 179The 180.Fn fd_alloc 181function returns zero on success, otherwise an appropriate error is 182returned. 183.It Fn fd_clone "fp" "fd" "flag" "fops" "data" 184This function is meant to be used by devices which allocate a file 185entry upon open. 186.Fn fd_clone 187fills 188.Fa fp 189with the given parameters. 190It always returns the in-kernel errno 191.Er EMOVEFD . 192This special return value is interpreted by the caller of the device 193open routine. 194.It Fn fd_closeexec "void" 195Close any files for the current process 196that are marked 197.Dq close on exec . 198This operation is performed by invoking 199.Fn fd_close 200on the appropriate file descriptor. 201.It Fn fd_copy "void" 202Copy the file descriptor table from the current process 203and return a pointer to the copy. 204The returned file descriptor is guaranteed to have a reference count of one. 205All file descriptor state is maintained. 206The reference counts on each file entry referenced by the file 207descriptor table is incremented accordingly. 208.It Fn fd_tryexpand "p" 209Expand the file descriptor table for process 210.Fa p 211by allocating memory for additional file descriptors. 212.It Fn fd_free "void" 213Decrement the reference count on the file descriptor table for the current lwp 214and release the file descriptor table if the reference count drops to 215zero. 216.It Fn fd_share "p" 217Make process 218.Fa p 219share the current process's filedesc structure. 220.It Fn fd_checkstd "l" 221Check the standard file descriptors 0, 1, and 2 and ensure they are 222referencing valid file descriptors. 223If they are not, create references to 224.Pa /dev/null . 225This is done to setuid/setgid executables, as file descriptors 0, 1, 2 226are implicitly used by the Standard C Library. 227.It Fn fd_init "fdp" 228Create a file descriptor table using the same current and root 229directories of the current process. 230The returned file descriptor table is guaranteed to have a reference 231count of one. 232.El 233.Sh RETURN VALUES 234Successful operations return zero. 235A failed operation will return a non-zero value. 236Possible values include: 237.Bl -tag -width Er 238.It Bq Er EBADF 239Bad file descriptor specified. 240.It Bq Er EMFILE 241Cannot exceed file descriptor limit. 242.It Bq Er ENOSPC 243No space left in file descriptor table. 244.El 245.Sh CODE REFERENCES 246The framework for file descriptor handling is implemented within the 247file 248.Pa sys/kern/kern_descrip.c . 249.Sh SEE ALSO 250.Xr file 9 251