269 lines
9.1 KiB
Perl
269 lines
9.1 KiB
Perl
.\" $NetBSD: 1.5.t,v 1.2 1998/01/09 06:54:44 perry Exp $
|
|
.\"
|
|
.\" Copyright (c) 1983, 1993, 1994
|
|
.\" The Regents of the University of California. All rights reserved.
|
|
.\"
|
|
.\" 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.
|
|
.\"
|
|
.\" 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.
|
|
.\"
|
|
.\" @(#)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
|
|
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,
|
|
containing pointers to the actual descriptors.
|
|
The descriptors themselves therefore may have multiple references,
|
|
and are reference counted by the system.
|
|
.PP
|
|
Each process has a limited size descriptor reference table, where
|
|
the current size is returned by the
|
|
.Fn getdtablesize
|
|
call:
|
|
.DS
|
|
.Fd getdtablesize 0 "get descriptor table size
|
|
nds = getdtablesize();
|
|
result int nds;
|
|
.DE
|
|
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
|
|
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.
|
|
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
|
|
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
|
|
.Fd dup 1 "duplicate an existing file descriptor
|
|
new = dup(old);
|
|
result int new; int old;
|
|
.DE
|
|
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
|
|
by doing:
|
|
.DS
|
|
.Fd dup2 2 "duplicate an existing file descriptor
|
|
dup2(old, new);
|
|
int old, new;
|
|
.DE
|
|
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.
|
|
.LP
|
|
Descriptors are deallocated by:
|
|
.DS
|
|
.Fd close 1 "delete a descriptor
|
|
close(old);
|
|
int old;
|
|
.DE
|
|
.Sh 3 "Multiplexing requests
|
|
.PP
|
|
The system provides a
|
|
standard way to do
|
|
synchronous and asynchronous multiplexing of operations.
|
|
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
|
|
.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;
|
|
|
|
FD_CLR(fd, &fdset);
|
|
FD_COPY(&fdset, &fdset2);
|
|
FD_ISSET(fd, &fdset);
|
|
FD_SET(fd, &fdset);
|
|
FD_ZERO(&fdset);
|
|
int fd; fs_set fdset, fdset2;
|
|
.DE
|
|
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
|
|
indicates the number of file descriptors specified by the bit masks).
|
|
If any descriptors meet the following criteria,
|
|
then the number of such descriptors is returned in \fInds\fP and the
|
|
bit masks are updated.
|
|
.if n .ds bu *
|
|
.if t .ds bu \(bu
|
|
.IP \*(bu
|
|
A descriptor selects for input if an input oriented operation
|
|
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
|
|
such as
|
|
.Fn write
|
|
or
|
|
.Fn send
|
|
is possible, or if an operation
|
|
that was ``in progress'', such as connection establishment,
|
|
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
|
|
that would cause a SIGURG signal to be generated exists (see section
|
|
.Xr 1.3.2 ),
|
|
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 \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
|
|
.Fd fcntl 3 "file control
|
|
dopt = fcntl(d, cmd, arg);
|
|
result int dopt; int d, cmd, arg;
|
|
.DE
|
|
.DS
|
|
.TS
|
|
l s
|
|
l l.
|
|
/* command values */
|
|
|
|
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
|
|
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
|
|
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.
|
|
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,
|
|
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.
|
|
A descriptor which has signalling enabled will cause the specified process
|
|
and/or process group
|
|
be signaled, with a SIGIO for input, output, or in-progress
|
|
operation complete, or
|
|
a SIGURG for exceptional conditions.
|
|
.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,
|
|
then return.
|
|
When making a connection on a \fIsocket\fP, the operation may
|
|
return indicating that the connection establishment is ``in progress''.
|
|
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.
|