.\"     $NetBSD: filedesc.9,v 1.5 2003/04/16 13:35:28 wiz Exp $
.\"
.\" Copyright (c) 2002 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.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"        This product includes software developed by the NetBSD
.\"        Foundation, Inc. and its contributors.
.\" 4. Neither the name of The NetBSD Foundation nor the names of its
.\"    contributors may be used to endorse or promote products derived
.\"    from this software without specific prior written permission.
.\"
.\" 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 October 12, 2002
.Dt FILEDESC 9
.Os
.Sh NAME
.Nm filedesc ,
.Nm dupfdopen ,
.Nm falloc ,
.Nm fd_getfile ,
.Nm fdalloc ,
.Nm fdavail ,
.Nm fdcheckstd ,
.Nm fdclear ,
.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 proc *p" "struct file **resultfp" "int *resultfd"
.Ft struct file *
.Fn fd_getfile "struct filedesc *fdp" "int fd"
.Ft int
.Fn dupfdopen "struct proc *p" "int indx" "int dfd" "int mode" "int error"
.Ft int
.Fn fdalloc "struct proc *p" "int want" "int *result"
.Ft int
.Fn fdavail "struct proc *p" "int n"
.Ft int
.Fn fdcheckstd "struct proc *p"
.Ft void
.Fn fdclear "struct proc *p"
.Ft void
.Fn fdcloseexec "struct proc *p"
.Ft struct filedesc *
.Fn fdcopy "struct proc *p"
.Ft void
.Fn fdexpand "struct proc *p"
.Ft void
.Fn fdfree "struct proc *p"
.Ft struct filedesc *
.Fn fdinit "struct proc *p"
.Ft int
.Fn fdrelease "struct proc *p" "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 proc *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 ,
three type of objects can be represented by file descriptors: data
files, pipes, and sockets.
.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 "p" "indx" "dfd" "mode" "error"
Duplicate file descriptor
.Fa dfd
for process
.Fa p .
.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 fdavail "p" "n"
Check to see whether
.Fa n
file descriptors are available to process
.Fa p .
Returns zero on success, or 1 on failure.
.It Fn fdcheckstd "p"
Check the standard file descriptors 0, 1, 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 "p"
Clear the descriptor table for process
.Fa p .
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 fdcloseexec "p"
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 "p"
Decrement the reference count on the file descriptor table for process
.Fa p
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 "p" "fd"
Remove file descriptor
.Fa fd
from the file descriptor table of process
.Fa p .
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 "p"
Ensure that process
.Fa p
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