[src/trunk]: src/share/man/man9 Update to reference the newer (committed long...

[maya <maya%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/69972a43d259
branches:  trunk
changeset: 455633:69972a43d259
user:      maya <maya%NetBSD.org@localhost>
date:      Mon Apr 08 13:04:54 2019 +0000

description:
Update to reference the newer (committed long ago) API.

With comments from Rocky Hotas on netbsd-docs, thanks.

diffstat:

 share/man/man9/filedesc.9 |  248 ++++++++++++++++++---------------------------
 1 files changed, 98 insertions(+), 150 deletions(-)

diffs (truncated from 359 to 300 lines):

diff -r 2a2c30be9e50 -r 69972a43d259 share/man/man9/filedesc.9
--- a/share/man/man9/filedesc.9 Mon Apr 08 11:32:49 2019 +0000
+++ b/share/man/man9/filedesc.9 Mon Apr 08 13:04:54 2019 +0000
@@ -1,4 +1,4 @@
-.\"     $NetBSD: filedesc.9,v 1.16 2010/12/02 12:54:13 wiz Exp $
+.\"     $NetBSD: filedesc.9,v 1.17 2019/04/08 13:04:54 maya Exp $
 .\"
 .\" Copyright (c) 2002, 2005, 2006 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -27,63 +27,54 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd July 24, 2006
+.Dd April 8, 2019
 .Dt FILEDESC 9
 .Os
 .Sh NAME
 .Nm filedesc ,
-.Nm dupfdopen ,
-.Nm falloc ,
+.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 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
+.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 falloc "struct lwp *l" "struct file **resultfp" "int *resultfd"
-.Ft struct file *
-.Fn fd_getfile "struct filedesc *fdp" "int fd"
+.Fn fd_alloc "proc_t *p" "int want" "int *result"
 .Ft int
-.Fn dupfdopen "struct lwp *l" "int indx" "int dfd" "int mode" "int error"
+.Fn fd_checkstd "void"
 .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"
+.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 fdcloseexec "struct lwp *l"
-.Ft struct filedesc *
-.Fn fdcopy "struct proc *p"
-.Ft void
-.Fn fdexpand "struct proc *p"
+.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 fdfree "struct lwp *l"
-.Ft struct filedesc *
-.Fn fdinit "struct proc *p"
-.Ft int
-.Fn fdrelease "struct lwp *l" "int fd"
+.Fn fd_free "void"
+.Ft filedesc_t *
+.Fn fd_init "filedesc_t *fdp"
+.Ft file_t *
+.Fn fd_getfile "unsigned fd"
 .Ft void
-.Fn fdremove "struct filedesc *fdp" "int fd"
+.Fn fd_share "proc_t *p"
 .Ft void
-.Fn fdshare "struct proc *p1" "struct proc *p2"
-.Ft void
-.Fn fdunshare "struct lwp *l"
+.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
@@ -97,7 +88,7 @@
 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:
+The table maintains the following information:
 .Pp
 .Bl -bullet -compact
 .It
@@ -114,67 +105,72 @@
 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
+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 falloc
+.Fn fd_alloc
 and freed by
-.Fn fdrelease .
+.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
+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
+.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 .
-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
+The caller to the
+.Fn fd_alloc
 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 index of the file entry is returned in
+.Fa *result .
 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
+.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
-in the file descriptor table
-.Fa fdp .
-The file entry is returned if it is valid and useable, otherwise
+The file entry is returned if it is valid and usable, otherwise
 .Dv NULL
 is returned.
-.It Fn dupfdopen "l" "indx" "dfd" "mode" "error"
+.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 dfd
-for lwp
-.Fa l .
+.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.
-.Pp
 .Bl -tag -width compact
-.It Fn fdalloc "p" "want" "*result"
+.It Fn fd_alloc "p" "want" "*result"
 Allocate a file descriptor
 .Fa want
 for process
@@ -182,112 +178,64 @@
 The resultant file descriptor is returned in
 .Fa *result .
 The
-.Fn fdalloc
+.Fn fd_alloc
 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"
+.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 fdclone
+.Fn fd_clone
 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.
+It always returns the in-kernel errno
+.Er EMOVEFD .
+This special value 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
+.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 fdunshare
-for the process and invoking
-.Fn fdrelease
+.Fn fd_close
 on the appropriate file descriptor.
-.It Fn fdcopy "p"
-Copy the file descriptor table from process
-.Fa p
+.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 fdexpand "p"
+.It Fn fd_tryexpand "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
+.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 fdinit "p"
+.It Fn fd_share "p"