Module Name: src Committed By: maya Date: Mon Apr 8 13:04:54 UTC 2019
Modified Files: src/share/man/man9: filedesc.9 Log Message: Update to reference the newer (committed long ago) API. With comments from Rocky Hotas on netbsd-docs, thanks. To generate a diff of this commit: cvs rdiff -u -r1.16 -r1.17 src/share/man/man9/filedesc.9 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
Modified files: Index: src/share/man/man9/filedesc.9 diff -u src/share/man/man9/filedesc.9:1.16 src/share/man/man9/filedesc.9:1.17 --- src/share/man/man9/filedesc.9:1.16 Thu Dec 2 12:54:13 2010 +++ src/share/man/man9/filedesc.9 Mon Apr 8 13:04:54 2019 @@ -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" +.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 fdclear "struct lwp *l" +.Fn fd_closeexec "void" .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" +.Fn fd_dup "file_t *fp" "int minfd" "int *newp" "bool exclose" .Ft int -.Fn fdrelease "struct lwp *l" "int fd" +.Fn fd_dup2 "file_t *fp" "unsigned newfd" "int flags" +.Ft int +.Fn fd_dupopen "int old" "int *newp" "int error" .Ft void -.Fn fdremove "struct filedesc *fdp" "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 fdshare "struct proc *p1" "struct proc *p2" +.Fn fd_share "proc_t *p" .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 @@ The kernel maintains a descriptor table 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 @@ On creation of the file descriptor table 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 @@ for process 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" +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 process -.Fa p . +directories of the current process. 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. +A failed operation will return a non-zero value. Possible values include: -.Pp .Bl -tag -width Er .It Bq Er EBADF Bad file descriptor specified.