BSD 4_4_Lite2 release

[unix-history] / usr / src / share / doc / psd / 05.sysman / 1.5.t

diff --git a/usr/src/share/doc/psd/05.sysman/1.5.t b/usr/src/share/doc/psd/05.sysman/1.5.t
index 02c4d22..d125ce7 100644 (file)
--- a/usr/src/share/doc/psd/05.sysman/1.5.t
+++ b/usr/src/share/doc/psd/05.sysman/1.5.t
@@ -1,101 +1,143 @@
-.\" Copyright (c) 1983 The Regents of the University of California.
-.\" All rights reserved.
+.\" Copyright (c) 1983, 1993, 1994
+.\"    The Regents of the University of California.  All rights reserved.

 .\"
 .\"

-.\" %sccs.include.redist.roff%
+.\" 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 University of
+.\"    California, Berkeley and its contributors.
+.\" 4. Neither the name of the University nor the names of its contributors
+.\"    may be used to endorse or promote products derived from this software
+.\"    without specific prior written permission.

 .\"
 .\"

-.\"    @(#)1.5.t       6.4 (Berkeley) %G%
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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.

 .\"
 .\"

-.sh Descriptors
-.PP
-.NH 3
-The reference table
+.\"    @(#)1.5.t       8.6 (Berkeley) 5/29/94
+.\"
+.Sh 2 Descriptors
+.Sh 3 "The reference table

 .PP
 Each process has access to resources through
 \fIdescriptors\fP.  Each descriptor is a handle allowing
 .PP
 Each process has access to resources through
 \fIdescriptors\fP.  Each descriptor is a handle allowing

-the process to reference objects such as files, devices
+processes to reference objects such as files, devices

 and communications links.
 .PP
 Rather than allowing processes direct access to descriptors, the system
 introduces a level of indirection, so that descriptors may be shared
 between processes.  Each process has a \fIdescriptor reference table\fP,
 and communications links.
 .PP
 Rather than allowing processes direct access to descriptors, the system
 introduces a level of indirection, so that descriptors may be shared
 between processes.  Each process has a \fIdescriptor reference table\fP,

-containing pointers to the actual descriptors.  The descriptors
-themselves thus have multiple references, and are reference counted by the
-system.
+containing pointers to the actual descriptors.
+The descriptors themselves therefore may have multiple references,
+and are reference counted by the system.

 .PP
 .PP

-Each process has a fixed size descriptor reference table, where
-the size is returned by the \fIgetdtablesize\fP call:
+Each process has a limited size descriptor reference table, where
+the current size is returned by the
+.Fn getdtablesize
+call:

 .DS
 .DS

+.Fd getdtablesize 0 "get descriptor table size

 nds = getdtablesize();
 result int nds;
 .DE
 nds = getdtablesize();
 result int nds;
 .DE

-and guaranteed to be at least 20.  The entries in the descriptor reference
+and guaranteed to be at least 64.
+The maximum number of descriptors is a resource limit (see section
+.Xr 1.6.3 ).
+The entries in the descriptor reference

 table are referred to by small integers; for example if there
 table are referred to by small integers; for example if there

-are 20 slots they are numbered 0 to 19.
-.NH 3
-Descriptor properties
+are 64 slots they are numbered 0 to 63.
+.Sh 3 "Descriptor properties

 .PP
 Each descriptor has a logical set of properties maintained
 by the system and defined by its \fItype\fP.
 Each type supports a set of operations;
 some operations, such as reading and writing, are common to several
 abstractions, while others are unique.
 .PP
 Each descriptor has a logical set of properties maintained
 by the system and defined by its \fItype\fP.
 Each type supports a set of operations;
 some operations, such as reading and writing, are common to several
 abstractions, while others are unique.

+For those types that support random access, the current file offset
+is stored in the descriptor.

 The generic operations applying to many of these types are described
 The generic operations applying to many of these types are described

-in section 2.1.  Naming contexts, files and directories are described in
-section 2.2.  Section 2.3 describes communications domains and sockets.
-Terminals and (structured and unstructured) devices are described
-in section 2.4.
-.NH 3
-Managing descriptor references
-.PP
-A duplicate of a descriptor reference may be made by doing
+in section
+.Xr 2.1 .
+Naming contexts, files and directories are described in section
+.Xr 2.2 .
+Section
+.Xr 2.3
+describes communications domains and sockets.
+Terminals and (structured and unstructured) devices are described in section
+.Xr 2.4 .
+.Sh 3 "Managing descriptor references
+.LP
+A duplicate of a descriptor reference may be made by doing:

 .DS
 .DS

+.Fd dup 1 "duplicate an existing file descriptor

 new = dup(old);
 result int new; int old;
 .DE
 new = dup(old);
 result int new; int old;
 .DE

-returning a copy of descriptor reference \fIold\fP indistinguishable from
-the original.  The \fInew\fP chosen by the system will be the
+returning a copy of descriptor reference \fIold\fP which is
+indistinguishable from the original.
+The value of \fInew\fP chosen by the system will be the

 smallest unused descriptor reference slot.
 A copy of a descriptor reference may be made in a specific slot
 smallest unused descriptor reference slot.
 A copy of a descriptor reference may be made in a specific slot

-by doing
+by doing:

 .DS
 .DS

+.Fd dup2 2 "duplicate an existing file descriptor

 dup2(old, new);
 int old, new;
 .DE
 dup2(old, new);
 int old, new;
 .DE

-The \fIdup2\fP call causes the system to deallocate the descriptor reference
+The
+.Fn dup2
+call causes the system to deallocate the descriptor reference

 current occupying slot \fInew\fP, if any, replacing it with a reference
 to the same descriptor as old.
 current occupying slot \fInew\fP, if any, replacing it with a reference
 to the same descriptor as old.

-This deallocation is also performed by:
+.LP
+Descriptors are deallocated by:

 .DS
 .DS

+.Fd close 1 "delete a descriptor

 close(old);
 int old;
 .DE
 close(old);
 int old;
 .DE

-.NH 3
-Multiplexing requests
+.Sh 3 "Multiplexing requests

 .PP
 The system provides a
 standard way to do
 synchronous and asynchronous multiplexing of operations.
 .PP
 The system provides a
 standard way to do
 synchronous and asynchronous multiplexing of operations.

-.PP
-Synchronous multiplexing is performed by using the \fIselect\fP call
-to examine the state of multiple descriptors simultaneously,
+Synchronous multiplexing is performed by using the
+.Fn select
+call to examine the state of multiple descriptors simultaneously,

 and to wait for state changes on those descriptors.
 Sets of descriptors of interest are specified as bit masks,
 as follows:
 .DS
 and to wait for state changes on those descriptors.
 Sets of descriptors of interest are specified as bit masks,
 as follows:
 .DS

-#include <sys/types.h>
-
+.Fd select 5 "synchronous I/O multiplexing

 nds = select(nd, in, out, except, tvp);
 result int nds; int nd; result fd_set *in, *out, *except;
 struct timeval *tvp;
 
 nds = select(nd, in, out, except, tvp);
 result int nds; int nd; result fd_set *in, *out, *except;
 struct timeval *tvp;
 

-FD_ZERO(&fdset);
-FD_SET(fd, &fdset);

 FD_CLR(fd, &fdset);
 FD_CLR(fd, &fdset);

+FD_COPY(&fdset, &fdset2);

 FD_ISSET(fd, &fdset);
 FD_ISSET(fd, &fdset);

-int fs; fs_set fdset;
+FD_SET(fd, &fdset);
+FD_ZERO(&fdset);
+int fd; fs_set fdset, fdset2;

 .DE
 .DE

-The \fIselect\fP call examines the descriptors
-specified by the
+The
+.Fn select
+call examines the descriptors specified by the

 sets \fIin\fP, \fIout\fP and \fIexcept\fP, replacing
 the specified bit masks by the subsets that select true for input,
 output, and exceptional conditions respectively (\fInd\fP
 sets \fIin\fP, \fIout\fP and \fIexcept\fP, replacing
 the specified bit masks by the subsets that select true for input,
 output, and exceptional conditions respectively (\fInd\fP


@@ -107,45 +149,101 @@ bit masks are updated.
 .if t .ds bu \(bu
 .IP \*(bu
 A descriptor selects for input if an input oriented operation
 .if t .ds bu \(bu
 .IP \*(bu
 A descriptor selects for input if an input oriented operation

-such as \fIread\fP or \fIreceive\fP is possible, or if a
-connection request may be accepted (see section 2.3.1.4).
+such as
+.Fn read
+or
+.Fn receive
+is possible, or if a connection request may be accepted (see sections
+.Xr 2.1.3
+and
+.Xr 2.3.1.4 ).

 .IP \*(bu
 A descriptor selects for output if an output oriented operation
 .IP \*(bu
 A descriptor selects for output if an output oriented operation

-such as \fIwrite\fP or \fIsend\fP is possible, or if an operation
+such as
+.Fn write
+or
+.Fn send
+is possible, or if an operation

 that was ``in progress'', such as connection establishment,
 that was ``in progress'', such as connection establishment,

-has completed (see section 2.1.3).
+has completed (see sections
+.Xr 2.1.3
+and
+.Xr 2.3.1.5 ).

 .IP \*(bu
 A descriptor selects for an exceptional condition if a condition
 .IP \*(bu
 A descriptor selects for an exceptional condition if a condition

-that would cause a SIGURG signal to be generated exists (see section 1.3.2),
+that would cause a SIGURG signal to be generated exists (see section
+.Xr 1.3.2 ),

 or other device-specific events have occurred.
 .LP
 or other device-specific events have occurred.
 .LP

+For these tests, an operation is considered to be possible if a call
+to the operation would return without blocking (even if the O_NONBLOCK
+flag were not set).
+For example, a descriptor would test as ready for reading if a read
+call would return immediately with data, an end-of-file indication,
+or an error other than EWOULDBLOCK.
+.LP

 If none of the specified conditions is true, the operation
 waits for one of the conditions to arise,
 blocking at most the amount of time specified by \fItvp\fP.
 If none of the specified conditions is true, the operation
 waits for one of the conditions to arise,
 blocking at most the amount of time specified by \fItvp\fP.

-If \fItvp\fP is given as 0, the \fIselect\fP waits indefinitely.
-.PP
+If \fItvp\fP is given as NULL, the
+.Fn select
+waits indefinitely.
+.LP

 Options affecting I/O on a descriptor
 may be read and set by the call:
 .DS
 Options affecting I/O on a descriptor
 may be read and set by the call:
 .DS

-._d
-dopt = fcntl(d, cmd, arg)
+.Fd fcntl 3 "file control
+dopt = fcntl(d, cmd, arg);

 result int dopt; int d, cmd, arg;
 result int dopt; int d, cmd, arg;

+.DE
+.DS
+.TS
+l s
+l l.
+/* command values */

 
 

-/* interesting values for cmd */
-#define        F_SETFL 3       /* set descriptor options */
-#define        F_GETFL 4       /* get descriptor options */
-#define        F_SETOWN        5       /* set descriptor owner (pid/pgrp) */
-#define        F_GETOWN        6       /* get descriptor owner (pid/pgrp) */
+F_DUPFD        /* return a new descriptor */
+F_GETFD        /* get file descriptor flags */
+F_SETFD        /* set file descriptor flags */
+F_GETFL        /* get file status flags */
+F_SETFL        /* set file status flags */
+F_GETOWN       /* get SIGIO/SIGURG proc/pgrp */
+F_SETOWN       /* set SIGIO/SIGURG proc/pgrp */
+F_GETLK        /* get blocking lock */
+F_SETLK        /* set or clear lock */
+F_SETLKW       /* set lock with wait */
+.TE

 .DE
 .DE

+The F_DUPFD \fIcmd\fP provides identical functionality to
+.Fn dup2 ;
+it is provided solely for POSIX compatibility.
+The F_SETFD \fIcmd\fP can be used to set the close-on-exec
+flag for a file descriptor.

 The F_SETFL \fIcmd\fP may be used to set a descriptor in 
 The F_SETFL \fIcmd\fP may be used to set a descriptor in 

-non-blocking I/O mode and/or enable signaling when I/O is
-possible.  F_SETOWN may be used to specify a process or process
+non-blocking I/O mode and/or enable signaling when I/O is possible.
+F_SETOWN may be used to specify a process or process

 group to be signaled when using the latter mode of operation
 or when urgent indications arise.
 group to be signaled when using the latter mode of operation
 or when urgent indications arise.

+The
+.Fn fcntl
+system call also provides POSIX-compliant byte-range locking on files.
+However the semantics of unlocking on every 
+.Fn close
+rather than last close makes them useless.
+Much better semantics and faster locking are provided by the
+.Fn flock
+system call (see section
+.Xr 2.2.7 ).
+The
+.Fn fcntl
+and
+.Fn flock
+locks can be used concurrently;
+they will serialize against each other properly.

 .PP
 Operations on non-blocking descriptors will
 either complete immediately,
 .PP
 Operations on non-blocking descriptors will
 either complete immediately,

-note an error EWOULDBLOCK,
+return the error EWOULDBLOCK,

 partially complete an input or output operation returning a partial count,
 or return an error EINPROGRESS noting that the requested operation is
 in progress.
 partially complete an input or output operation returning a partial count,
 or return an error EINPROGRESS noting that the requested operation is
 in progress.


@@ -157,43 +255,12 @@ a SIGURG for exceptional conditions.
 .PP
 For example, when writing to a terminal
 using non-blocking output,
 .PP
 For example, when writing to a terminal
 using non-blocking output,

-the system will accept only as much data as there is buffer space for
-and return; when making a connection on a \fIsocket\fP, the operation may
+the system will accept only as much data as there is buffer space,
+then return.
+When making a connection on a \fIsocket\fP, the operation may

 return indicating that the connection establishment is ``in progress''.
 return indicating that the connection establishment is ``in progress''.

-The \fIselect\fP facility can be used to determine when further
+The
+.Fn select
+facility can be used to determine when further

 output is possible on the terminal, or when the connection establishment
 attempt is complete.
 output is possible on the terminal, or when the connection establishment
 attempt is complete.

-.NH 3
-Descriptor wrapping.\(dg
-.PP
-.FS
-\(dg The facilities described in this section are not included
-in 4.3BSD.
-.FE
-A user process may build descriptors of a specified type by
-\fIwrapping\fP a communications channel with a system supplied protocol
-translator:
-.DS
-new = wrap(old, proto)
-result int new; int old; struct dprop *proto;
-.DE
-Operations on the descriptor \fIold\fP are then translated by the
-system provided protocol translator into requests on the underlying
-object \fIold\fP in a way defined by the protocol.
-The protocols supported by the kernel may vary from system to system
-and are described in the programmers manual.
-.PP
-Protocols may be based on communications multiplexing or a rights-passing
-style of handling multiple requests made on the same object.  For instance,
-a protocol for implementing a file abstraction may or may not include
-locally generated ``read-ahead'' requests.  A protocol that provides for
-read-ahead may provide higher performance but have a more difficult
-implementation.
-.PP
-Another example is the terminal driving facilities.  Normally a terminal
-is associated with a communications line, and the terminal type
-and standard terminal access protocol are wrapped around a synchronous
-communications line and given to the user.  If a virtual terminal
-is required, the terminal driver can be wrapped around a communications
-link, the other end of which is held by a virtual terminal protocol
-interpreter.