filedesc(9) rewrite, please review

[coypu%sdf.org@localhost]

hi,

attached is the generated output of a filedesc(9) rewrite.
The source to generate it is less important, but also available here:
http://coypu.sdf.org/filedesc.9

Most of the changes were rewriting the functions to describe the new API
names and signatures.
I tried to add some more functions for completeness, but it is still not
all.

Please review.

FILEDESC(9)		   Kernel Developer's Manual		   FILEDESC(9)

NAME
     filedesc, fd_alloc, fd_checkstd, fd_clone, fd_closeexec, fd_copy, fd_dup,
     fd_dup2, fd_dupopen, fd_free, fd_init, fd_getfile, fd_share,
     fd_tryexpand,  file descriptor tables and operations

SYNOPSIS
     #include <sys/file.h>
     #include <sys/filedesc.h>

     int
     fd_alloc(proc_t *p, int want, int *result);

     int
     fd_checkstd(void);

     int
     fd_clone(file_t *fp, int fd, int flag, const struct fileops *fops,
	 void *data);

     filedesc_t *
     fd_copy(void);

     void
     fd_closeexec(void);

     int
     fd_dup(file_t *fp, int minfd, int *newp, bool exclose);

     int
     fd_dup2(file_t *fp, unsigned newfd, int flags);

     int
     fd_dupopen(int old, int *newp, int error);

     void
     fd_free(void);

     filedesc_t *
     fd_init(filedesc_t *fdp);

     file_t *
     fd_getfile(unsigned fd);

     void
     fd_share(proc_t *p);

     void
     fd_tryexpand(proc_t *p);

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 NetBSD, six
     types of objects can be represented by file descriptors: data files,
     pipes, sockets, event queues, crypto, and miscellaneous.

     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:

       the number of descriptors allocated in the file descriptor table;
       approximate next free descriptor;
       a reference count on the file descriptor table; and
       an array of open file entries.

     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
     file(9) for details of operations on the file entries.

     New file descriptors are generally allocated by fd_alloc() and freed by
     fd_free().	 File entries are extracted from the file descriptor table by
     fd_getfile().  Most of the remaining functions in the interface are
     purpose specific and perform lower-level file descriptor operations.

FUNCTIONS
     The following functions are high-level interface routines to access the
     file descriptor table for a process and its file entries.

     fd_alloc(p, want, *result)
	      Create a new open file entry and allocate a file descriptor for
	      the process p.  This operation is performed by invoking
	      fd_alloc() to allocate the new file descriptor.  The credential
	      on the file entry are inherited from process p.  The caller to
	      the fd_alloc() function is responsible for expanding the file
	      descriptor table when necessary.

	      The index of the file entry is returned in *result.  The
	      fd_alloc() function returns zero on success, otherwise an
	      appropriate error is returned.

     fd_getfile(fd)
	      Get the file entry for file descriptor fd The file entry is
	      returned if it is valid and usable, otherwise NULL is returned.

     fd_dup(fp, minfd, *newp, exclose)
	      Duplicate file descriptor fp for the current process.  The fd
	      picked will be at least minfd.  The resulting descriptor is
	      given in newp.

     fd_dup2(fp, newfd, flags)
	      Duplicate file descriptor fp in fd number newfd.	If there is
	      already an open file, close it (See dup2(2)).

     fd_dupopen(old, *newp, error)
	      Duplicate file descriptor specified in old for the current lwp.

     The following functions operate on the file descriptor table for a
     process.

     fd_alloc(p, want, *result)
	      Allocate a file descriptor want for process p.  The resultant
	      file descriptor is returned in *result.  The fd_alloc() function
	      returns zero on success, otherwise an appropriate error is
	      returned.

     fd_clone(fp, fd, flag, fops, data)
	      This function is meant to be used by devices which allocate a
	      file entry upon open.  fd_clone() fills fp with the given
	      parameters.  It always returns the in-kernel errno value
	      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.

     fd_closeexec(void)
	      Close any files for the current process that are marked close
	      on exec.	This operation is performed by invoking fd_close() on
	      the appropriate file descriptor.

     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.

     fd_tryexpand(p)
	      Expand the file descriptor table for process p by allocating
	      memory for additional file descriptors.

     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.

     fd_share(p)
	      Make process p share the current process's filedesc structure.

     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 /dev/null.	This operation is necessary as these
	      file descriptors are given implicit significance in the Standard
	      C Library and it is unsafe for setuid(2) and setgid(2) processes
	      to be started with these file descriptors closed.

     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.

RETURN VALUES
     Successful operations return zero.	 A failed operation will return a non-
     zero return value.	 Possible values include:

     [EBADF]		Bad file descriptor specified.

     [EMFILE]		Cannot exceed file descriptor limit.

     [ENOSPC]		No space left in file descriptor table.

CODE REFERENCES
     The framework for file descriptor handling is implemented within the file
     sys/kern/kern_descrip.c.

SEE ALSO
     file(9)

NetBSD 8.99.25			 July 24, 2006			NetBSD 8.99.25