251 lines
7.8 KiB
Groff
251 lines
7.8 KiB
Groff
.\" $NetBSD: filedesc.9,v 1.18 2019/04/08 13:30:46 wiz Exp $
|
|
.\"
|
|
.\" 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
|
|
.In sys/file.h
|
|
.In 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.
|
|
.Pp
|
|
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:
|
|
.Pp
|
|
.Bl -bullet -compact
|
|
.It
|
|
the number of descriptors allocated in the file descriptor table;
|
|
.It
|
|
approximate next free descriptor;
|
|
.It
|
|
a reference count on the file descriptor table; and
|
|
.It
|
|
an array of open file entries.
|
|
.El
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
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.
|
|
.Bl -tag -width compact
|
|
.It 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.
|
|
.Pp
|
|
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.
|
|
.It 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.
|
|
.It 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 .
|
|
.It 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 ) .
|
|
.It Fn fd_dupopen "old" "*newp" "error"
|
|
Duplicate file descriptor specified in
|
|
.Fa old
|
|
for the current lwp.
|
|
.El
|
|
.Pp
|
|
The following functions operate on the file descriptor table for a
|
|
process.
|
|
.Bl -tag -width compact
|
|
.It 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.
|
|
.It 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.
|
|
.It 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.
|
|
.It 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.
|
|
.It Fn fd_tryexpand "p"
|
|
Expand the file descriptor table for process
|
|
.Fa p
|
|
by allocating memory for additional file descriptors.
|
|
.It 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.
|
|
.It Fn fd_share "p"
|
|
Make process
|
|
.Fa p
|
|
share the current process's filedesc structure.
|
|
.It 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
|
|
.Pa /dev/null .
|
|
This is done to setuid/setgid executables, as file descriptors 0, 1, 2
|
|
are implicitly used by the Standard C Library.
|
|
.It 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:
|
|
.Bl -tag -width Er
|
|
.It Bq Er EBADF
|
|
Bad file descriptor specified.
|
|
.It Bq Er EMFILE
|
|
Cannot exceed file descriptor limit.
|
|
.It 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
|
|
.Pa sys/kern/kern_descrip.c .
|
|
.Sh SEE ALSO
|
|
.Xr file 9
|