312 lines
9.2 KiB
Groff
312 lines
9.2 KiB
Groff
.\" $NetBSD: filedesc.9,v 1.15 2008/04/30 13:10:58 martin 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 July 24, 2006
|
|
.Dt FILEDESC 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm filedesc ,
|
|
.Nm dupfdopen ,
|
|
.Nm falloc ,
|
|
.Nm fd_getfile ,
|
|
.Nm fdalloc ,
|
|
.Nm fdcheckstd ,
|
|
.Nm fdclear ,
|
|
.Nm fdclone ,
|
|
.Nm fdcloseexec ,
|
|
.Nm fdcopy ,
|
|
.Nm fdexpand ,
|
|
.Nm fdfree ,
|
|
.Nm fdinit ,
|
|
.Nm fdrelease ,
|
|
.Nm fdremove ,
|
|
.Nm fdshare ,
|
|
.Nm fdunshare
|
|
.Nd file descriptor tables and operations
|
|
.Sh SYNOPSIS
|
|
.In sys/file.h
|
|
.In sys/filedesc.h
|
|
.Ft int
|
|
.Fn falloc "struct lwp *l" "struct file **resultfp" "int *resultfd"
|
|
.Ft struct file *
|
|
.Fn fd_getfile "struct filedesc *fdp" "int fd"
|
|
.Ft int
|
|
.Fn dupfdopen "struct lwp *l" "int indx" "int dfd" "int mode" "int error"
|
|
.Ft int
|
|
.Fn fdalloc "struct proc *p" "int want" "int *result"
|
|
.Ft int
|
|
.Fn fdcheckstd "struct lwp *l"
|
|
.Ft void
|
|
.Fn fdclear "struct lwp *l"
|
|
.Ft int
|
|
.Fn fdclone "struct lwp *l" "struct file *fp" "int fd" "int flag" "const struct fileops *fops" "void *data"
|
|
.Ft void
|
|
.Fn fdcloseexec "struct lwp *l"
|
|
.Ft struct filedesc *
|
|
.Fn fdcopy "struct proc *p"
|
|
.Ft void
|
|
.Fn fdexpand "struct proc *p"
|
|
.Ft void
|
|
.Fn fdfree "struct lwp *l"
|
|
.Ft struct filedesc *
|
|
.Fn fdinit "struct proc *p"
|
|
.Ft int
|
|
.Fn fdrelease "struct lwp *l" "int fd"
|
|
.Ft void
|
|
.Fn fdremove "struct filedesc *fdp" "int fd"
|
|
.Ft void
|
|
.Fn fdshare "struct proc *p1" "struct proc *p2"
|
|
.Ft void
|
|
.Fn fdunshare "struct lwp *l"
|
|
.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 file descriptor 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 necessary
|
|
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 falloc
|
|
and freed by
|
|
.Fn fdrelease .
|
|
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.
|
|
.Pp
|
|
.Bl -tag -width compact
|
|
.It Fn falloc "p" "*resultfp" "*resultfd"
|
|
Create a new open file entry and allocate a file descriptor for
|
|
process
|
|
.Fa p .
|
|
This operation is performed by invoking
|
|
.Fn fdalloc
|
|
to allocate the new file descriptor.
|
|
The credential on the file entry are inherited from process
|
|
.Fa p .
|
|
The
|
|
.Fn falloc
|
|
function is responsible for expanding the file descriptor table when
|
|
necessary.
|
|
.Pp
|
|
A pointer to the file entry is returned in
|
|
.Fa *resultfp
|
|
and the file descriptor is returned in
|
|
.Fa *resultfd .
|
|
The
|
|
.Fn falloc
|
|
function returns zero on success, otherwise an appropriate error is
|
|
returned.
|
|
.It Fn fd_getfile "fdp" "fd"
|
|
Get the file entry for file descriptor
|
|
.Fa fd
|
|
in the file descriptor table
|
|
.Fa fdp .
|
|
The file entry is returned if it is valid and useable, otherwise
|
|
.Dv NULL
|
|
is returned.
|
|
.It Fn dupfdopen "l" "indx" "dfd" "mode" "error"
|
|
Duplicate file descriptor
|
|
.Fa dfd
|
|
for lwp
|
|
.Fa l .
|
|
.El
|
|
.Pp
|
|
The following functions operate on the file descriptor table for a
|
|
process.
|
|
.Pp
|
|
.Bl -tag -width compact
|
|
.It Fn fdalloc "p" "want" "*result"
|
|
Allocate a file descriptor
|
|
.Fa want
|
|
for process
|
|
.Fa p .
|
|
The resultant file descriptor is returned in
|
|
.Fa *result .
|
|
The
|
|
.Fn fdalloc
|
|
function returns zero on success, otherwise an appropriate error is
|
|
returned.
|
|
.It Fn fdcheckstd "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 operation is necessary as these file descriptors are given implicit
|
|
significance in the Standard C Library and it is unsafe for
|
|
.Xr setuid 2
|
|
and
|
|
.Xr setgid 2
|
|
processes to be started with these file descriptors closed.
|
|
.It Fn fdclear "l"
|
|
Clear the descriptor table for lwp
|
|
.Fa l .
|
|
This operation is performed by invoking
|
|
.Fn fdinit
|
|
to initialise a new file descriptor table to replace the old file
|
|
descriptor table and invoking
|
|
.Fn fdfree
|
|
to release the old one.
|
|
.It Fn fdclone "l" "fp" "fd" "flag" "fops" "data"
|
|
This function is meant to be used by devices which allocate a file
|
|
entry upon open.
|
|
.Fn fdclone
|
|
fills
|
|
.Fa fp
|
|
with the given parameters.
|
|
It always returns the in-kernel errno value
|
|
.Er EMOVEFD ,
|
|
which is meant to be returned from the device open routine.
|
|
This special return value is interpreted by the caller of the device
|
|
open routine.
|
|
.It Fn fdcloseexec "l"
|
|
Close any files for process
|
|
.Fa p
|
|
that are marked
|
|
.Dq close on exec .
|
|
This operation is performed by invoking
|
|
.Fn fdunshare
|
|
for the process and invoking
|
|
.Fn fdrelease
|
|
on the appropriate file descriptor.
|
|
.It Fn fdcopy "p"
|
|
Copy the file descriptor table from process
|
|
.Fa p
|
|
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 fdexpand "p"
|
|
Expand the file descriptor table for process
|
|
.Fa p
|
|
by allocating memory for additional file descriptors.
|
|
.It Fn fdfree "l"
|
|
Decrement the reference count on the file descriptor table for lwp
|
|
.Fa l
|
|
and release the file descriptor table if the reference count drops to
|
|
zero.
|
|
.It Fn fdinit "p"
|
|
Create a file descriptor table using the same current and root
|
|
directories of process
|
|
.Fa p .
|
|
The returned file descriptor table is guaranteed to have a reference
|
|
count of one.
|
|
.It Fn fdrelease "l" "fd"
|
|
Remove file descriptor
|
|
.Fa fd
|
|
from the file descriptor table of lwp
|
|
.Fa l .
|
|
The operation is performed by invoking
|
|
.Fn closef .
|
|
.It Fn fdremove "fdp" "fd"
|
|
Unconditionally remove the file descriptor
|
|
.Fa fd
|
|
from file descriptor table
|
|
.Fa fdp .
|
|
.It Fn fdshare "p1" "p2"
|
|
Share the file descriptor table belonging to process
|
|
.Fa p1
|
|
with process
|
|
.Fa p2 .
|
|
Process
|
|
.Fa p2
|
|
is assumed not to have a file descriptor table already allocated.
|
|
The reference count on the file descriptor table is incremented.
|
|
This function is used by
|
|
.Xr fork1 9 .
|
|
.It Fn fdunshare "l"
|
|
Ensure that lwp
|
|
.Fa l
|
|
does not share its file descriptor table.
|
|
If its file descriptor table has more than one reference, the file
|
|
descriptor table is copied by invoking
|
|
.Fn fdcopy .
|
|
The reference count on the original file descriptor table is
|
|
decremented.
|
|
.El
|
|
.Sh RETURN VALUES
|
|
Successful operations return zero.
|
|
A failed operation will return a non-zero return value.
|
|
Possible values include:
|
|
.Pp
|
|
.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
|
|
This section describes places within the
|
|
.Nx
|
|
source tree where actual code implementing or using file
|
|
descriptors can be found.
|
|
All pathnames are relative to
|
|
.Pa /usr/src .
|
|
.Pp
|
|
The framework for file descriptor handling is implemented within the
|
|
file
|
|
.Pa sys/kern/kern_descrip.c .
|
|
.Sh SEE ALSO
|
|
.Xr file 9
|