1 files changed, 250 insertions, 0 deletions
diff --git a/static/netbsd/man9/filedesc.9 b/static/netbsd/man9/filedesc.9
new file mode 100644
index 00000000..26a02e02
--- /dev/null
+++ b/static/netbsd/man9/filedesc.9
@@ -0,0 +1,250 @@
+.\"     $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