Copyright (c) 2002, 2005, 2006 The NetBSD Foundation, Inc.
All rights reserved.
This code is derived from software contributed to The NetBSD Foundation
by Gregory McGarry.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
.Dd April 8, 2019 .Dt FILEDESC 9 .Os .Sh NAME .Nm filedesc , .Nm fd_alloc , .Nm fd_checkstd , .Nm fd_clone , .Nm fd_closeexec , .Nm fd_copy , .Nm fd_dup , .Nm fd_dup2 , .Nm fd_dupopen , .Nm fd_free , .Nm fd_init , .Nm fd_getfile , .Nm fd_share , .Nm fd_tryexpand .Nd file descriptor tables and operations .Sh SYNOPSIS n sys/file.h n sys/filedesc.h .Ft int .Fn fd_alloc "proc_t *p" "int want" "int *result" .Ft int .Fn fd_checkstd "void" .Ft int .Fn fd_clone "file_t *fp" "int fd" "int flag" "const struct fileops *fops" "void *data" .Ft filedesc_t * .Fn fd_copy "void" .Ft void .Fn fd_closeexec "void" .Ft int .Fn fd_dup "file_t *fp" "int minfd" "int *newp" "bool exclose" .Ft int .Fn fd_dup2 "file_t *fp" "unsigned newfd" "int flags" .Ft int .Fn fd_dupopen "int old" "int *newp" "int error" .Ft void .Fn fd_free "void" .Ft filedesc_t * .Fn fd_init "filedesc_t *fdp" .Ft file_t * .Fn fd_getfile "unsigned fd" .Ft void .Fn fd_share "proc_t *p" .Ft void .Fn fd_tryexpand "proc_t *p" .Sh DESCRIPTION For user processes, all I/O is done through file descriptors. These file descriptors represent underlying objects supported by the kernel and are created by system calls specific to the type of object. In .Nx , six types of objects can be represented by file descriptors: data files, pipes, sockets, event queues, crypto, and miscellaneous.
p The kernel maintains a descriptor table for each process which is used to translate the external representation of a file descriptor into an internal representation. The file descriptor is merely an index into this table. The table maintains the following information:
p l -bullet -compact t the number of descriptors allocated in the file descriptor table; t approximate next free descriptor; t a reference count on the file descriptor table; and t an array of open file entries. .El
p On creation of the file descriptor table, a fixed number of file entries are created. It is the responsibility of the file descriptor operations to expand the available number of entries if more are required. Each file entry in the descriptor table contains the information needed to access the underlying object and to maintain common information. See .Xr file 9 for details of operations on the file entries.
p New file descriptors are generally allocated by .Fn fd_alloc and freed by .Fn fd_free . File entries are extracted from the file descriptor table by .Fn fd_getfile . Most of the remaining functions in the interface are purpose-specific and perform lower-level file descriptor operations. .Sh FUNCTIONS The following functions are high-level interface routines to access the file descriptor table for a process and its file entries. l -tag -width compact t Fn fd_alloc "p" "want" "*result" Create a new open file entry in the file descriptor table and allocate a file descriptor for the process .Fa p . The credential on the file entry are inherited from process .Fa p . Calling the .Fn fd_alloc function expands the file descriptor table when necessary.
p The index of the file entry is returned in .Fa *result . The .Fn fd_alloc function returns zero on success, or an appropriate error value otherwise. t Fn fd_getfile "fd" Get the file entry for file descriptor . .Fa fd The file entry is returned if it is valid and usable, otherwise .Dv NULL is returned. t Fn fd_dup "fp" "minfd" "*newp" "exclose" Duplicate file descriptor .Fa fp for the current process. The fd picked will be at least .Fa minfd . The resulting descriptor is given in .Fa newp . t Fn fd_dup2 "fp" "newfd" "flags" Duplicate file descriptor .Fa fp in fd number .Fa newfd . If newfd is already in use by an open file, close it (See .Xr dup2 2 ) . t Fn fd_dupopen "old" "*newp" "error" Duplicate file descriptor specified in .Fa old for the current lwp. .El
p The following functions operate on the file descriptor table for a process. l -tag -width compact t Fn fd_alloc "p" "want" "*result" Allocate a file descriptor .Fa want for process .Fa p . The resultant file descriptor is returned in .Fa *result . The .Fn fd_alloc function returns zero on success, otherwise an appropriate error is returned. t Fn fd_clone "fp" "fd" "flag" "fops" "data" This function is meant to be used by devices which allocate a file entry upon open. .Fn fd_clone fills .Fa fp with the given parameters. It always returns the in-kernel errno .Er EMOVEFD . This special return value is interpreted by the caller of the device open routine. t Fn fd_closeexec "void" Close any files for the current process that are marked .Dq close on exec . This operation is performed by invoking .Fn fd_close on the appropriate file descriptor. t Fn fd_copy "void" Copy the file descriptor table from the current process and return a pointer to the copy. The returned file descriptor is guaranteed to have a reference count of one. All file descriptor state is maintained. The reference counts on each file entry referenced by the file descriptor table is incremented accordingly. t Fn fd_tryexpand "p" Expand the file descriptor table for process .Fa p by allocating memory for additional file descriptors. t Fn fd_free "void" Decrement the reference count on the file descriptor table for the current lwp and release the file descriptor table if the reference count drops to zero. t Fn fd_share "p" Make process .Fa p share the current process's filedesc structure. t Fn fd_checkstd "l" Check the standard file descriptors 0, 1, and 2 and ensure they are referencing valid file descriptors. If they are not, create references to
a /dev/null . This is done to setuid/setgid executables, as file descriptors 0, 1, 2 are implicitly used by the Standard C Library. t Fn fd_init "fdp" Create a file descriptor table using the same current and root directories of the current process. The returned file descriptor table is guaranteed to have a reference count of one. .El .Sh RETURN VALUES Successful operations return zero. A failed operation will return a non-zero value. Possible values include: l -tag -width Er t Bq Er EBADF Bad file descriptor specified. t Bq Er EMFILE Cannot exceed file descriptor limit. t Bq Er ENOSPC No space left in file descriptor table. .El .Sh CODE REFERENCES The framework for file descriptor handling is implemented within the file
a sys/kern/kern_descrip.c . .Sh SEE ALSO .Xr file 9
Indexes created Sat Sep 20 22:09:52 GMT 2025