Differential D56112 Diff 174387 share/man/man9/filedesc.9

Changeset View

Standalone View

share/man/man9/filedesc.9

This file was added.

				.\"
				.\" Copyright (c) 2026 Raghav Narayan.
				.\"
				.\" SPDX-License-Identifier: BSD-2-Clause
				.\"
				.Dd March 25, 2026
				.Dt Filedesc 9
				.Sh NAME
				.Nm filedesc ,
				.Nm fget ,
				.Nm fget_noref ,
				.Nm fdalloc ,
				.Nm falloc_caps ,
				.Nm fdinit ,
				.Nm fdcopy ,
				.Nm dupfdopen ,
				.Nm fdfree ,
				.Nm fdshare ,
				.Nm fdunshare ,
				.Nm fdcloseexec
				.Nd file descriptor table and operations
				.Sh SYNOPSIS
				.In sys/file.h
				.In sys/filedesc.h
				.Ft int
				.Fn fget "struct thread td" "int fd" "const cap_rights_t rightsp" "struct file **fpp"
				.Ft struct file *
				.Fn fget_noref "struct filedesc *fdp" "int fd"
				.Ft int
				.Fn fdalloc "struct thread td" "int minfd" "int result"
				.Ft int
				.Fn falloc_caps "struct thread td" "struct file resultfp" "int resultfd" "int flags" "struct filecaps *fcaps"
				.Ft struct filedesc *
				.Fn fdinit "void"
				.Ft struct filedesc *
				.Fn fdcopy "struct filedesc fdp" "struct proc p1"
				.Ft int
				.Fn dupfdopen "struct thread td" "struct filedesc fdp" "int dfd" "int mode" "int openerror" "int *indxp"
				.Ft void
				.Fn fdfree "struct file *fdp" "int fd"
				.Ft struct filedesc *
				.Fn fdshare "struct filedesc *fdp"
				.Ft void
				.Fn fdunshare "struct thread *td"
				.Ft void
				.Fn fdcloseexec "struct thread *td"
				.Sh DESCRIPTION
				User processes perform I/O operations through file descriptors, which are non-negative integers used to reference objects which are managed by the kernel. These objects can include files, sockets, pipes, queues and other kernel objects.
				.Pp
				The kernel maintains a file descriptor table for each process represented by a
				.Vt struct filedesc .
				File descriptors are only an index into this table which maintains the following:
				.Pp
				.Bl -bullet -compact
				.It
				File descriptor entries for open files.
				.It
				State used to manage allocation and reuse of file descriptors.
				.It
				Reference count on the file descriptor table.
				.It
				Reference to the
				.Vt struct file
				associated with each descriptor.
				.El
				.Pp
				The file descriptor table is dynamically managed and can grow as additional file descriptors are allocated. Common operations include allocation, release, and retrieving. Functions such as
				.Fn fdalloc ,
				.Fn fdfree ,
				.Fn fget ,
				etc are provided to manage file descriptors and access the associated file structures.
				.Pp
				File descriptor tables may be shared between processes and hence are reference counted to ensure proper lifetime management.
				.Pp
				In
				.Fx ,
				Capability rights may restrict operations on file descriptor.
				.Sh FUNCTIONS
				.Bl -tag -width compact
				.It Fn fdalloc "struct thread td" "int minfd" "int result"
				Allocates a file descriptor for the process. The file descriptor table is expanded if necessary. The allocated descriptor is returned in
				.Fa result .
				The
				.Fn fdalloc
				fucntion returns zero on success, or an appropriate error value otherwise.
				.It Fn falloc_caps "struct thread td" "struct file resultfp" "int resultfd" "int flags" "struct filecaps *fcaps"
				The
				.Fn falloc_caps
				function allocates a new file structure and associates it with a newly allocated file descriptor for the process associated with
				.Fa td .
				The file structure is returned in
				.Fa *resultfp
				and the file descriptor is retuned in
				.Fa *resultfd .
				.It Fn fget "struct thread td" "int fd" "const cap_rights_t rightsp" "struct file **fpp"
				The
				.Fn fget
				function retrieves the file pointer associated with the file descriptor
				.Fa fd .
				On success, a referenced pointer to the file is stored in
				.Fa *fpp
				and a zero is returned. On failure, an appropriate error value is returned and
				.Fa *fpp
				is set to
				.Dv NULL .
				.It Fn fget_noref "struct filedesc *fdp" "int fd"
				The
				.Fn fget_noref
				fucntion returns the pointer to the file associated with the file descriptor
				.Fa fd
				without any increment to the reference counter. On failure
				.Dv NULL
				is returned.
				.It Fn dupfdopen "struct thread td" "struct filedesc fdp" "int dfd" "int mode" "int openerror" "int *indxp"
				The
				.Fn dupfdopen
				fucntion either duplicates a file descriptor to a new descriptor or transfers the file object from the original file descriptor to a new file descriptor based on the value of
				.Fa openerror .
				If the file descriptor was transfered then the original file descriptor becomes invalid.
				The duplicated file descriptor is returned in
				.Fa indxp .
				On success zero is returned or an appropriate error value otherwise.
				.El
				.Pp
				The following function operates on the file descriptor table for a process.
				.Bl -tag -width compact
				.It Fn fdcopy "struct filedesc fdp" "struct proc p1"
				The
				.Fn fdcopy
				fucntion creates a copy of the file descriptor structure
				.Fa fdp
				and a pointer to the new structure is returned.
				.It Fn fdshare "struct filedesc *fpd"
				The
				.Fn fdshare
				function increments the reference counter of the file descriptor table
				.Fa fdp
				and returns a pointer to it.
				.It Fn fdunshare "struct thread *td"
				The
				.Fn fdunshare
				function makes sure that the file descriptor structure of the process associated with
				.Fa td
				is not shared. if the file descriptor structure is shared then a new copy is assigned to the process.
				.It Fn fdfree "struct file *fdp" "int fd"
				The
				.Fn fdfree
				function removes the file descriptor entry associated with
				.Fa fd
				and marks the descriptor as free.
				.It Fn fdcloseexec "struct thread *td"
				The
				.Fn fdcloseexec
				function closes file descriptors associated with
				.Fa td
				that are marked "close on exec".
				.It Fn fdinit "void"
				The
				.Fn fdinit
				function allocates and initializes a new table with a reference count of one. A pointer to the new table is returned.
				d.
				.El
				.Sh RETURN VALUES
				Successful operations return zero. A failed operation returns a non-zero value. Possible values include:
				.Bl -tag -width Er
				.It Bq Er EBADF
				Bad file descriptor specified.
				.It Bq Er EACCES
				The requested operation is not permitted.
				.It Bq Er EMFILE
				Cannot exceed the file descriptor limit.
				.El
				.Sh CODE REFERENCES
				The file descriptor handling framework is implemented in
				.Pa sys/kern/kern_descrip.c
				and defined in
				.Pa sys/sys/filedesc.h .