llio.texi

一个C源代码分析器

systems.  This is when the stream is doing input from a file that is not
random-access.  Such streams typically read ahead, and when the file is
not random access, there is no way to give back the excess data already
read.  When an input stream reads from a random-access file,
@code{fflush} does clean the stream, but leaves the file pointer at an
unpredictable place; you must set the file pointer before doing any
further I/O.  On the GNU system, using @code{fclean} avoids both of
these problems.

Closing an output-only stream also does @code{fflush}, so this is a
valid way of cleaning an output stream.  On the GNU system, closing an
input stream does @code{fclean}.

You need not clean a stream before using its descriptor for control
operations such as setting terminal modes; these operations don't affect
the file position and are not affected by it.  You can use any
descriptor for these operations, and all channels are affected
simultaneously.  However, text already ``output'' to a stream but still
buffered by the stream will be subject to the new terminal modes when
subsequently flushed.  To make sure ``past'' output is covered by the
terminal settings that were in effect at the time, flush the output
streams for that terminal before setting the modes.  @xref{Terminal
Modes}.

@node Waiting for I/O
@section Waiting for Input or Output
@cindex waiting for input or output
@cindex multiplexing input
@cindex input from multiple files

Sometimes a program needs to accept input on multiple input channels
whenever input arrives.  For example, some workstations may have devices
such as a digitizing tablet, function button box, or dial box that are
connected via normal asynchronous serial interfaces; good user interface
style requires responding immediately to input on any device.  Another
example is a program that acts as a server to several other processes
via pipes or sockets.

You cannot normally use @code{read} for this purpose, because this
blocks the program until input is available on one particular file
descriptor; input on other channels won't wake it up.  You could set
nonblocking mode and poll each file descriptor in turn, but this is very
inefficient.

A better solution is to use the @code{select} function.  This blocks the
program until input or output is ready on a specified set of file
descriptors, or until a timer expires, whichever comes first.  This
facility is declared in the header file @file{sys/types.h}.
@pindex sys/types.h

In the case of a server socket (@pxref{Listening}), we say that
``input'' is available when there are pending connections that could be
accepted (@pxref{Accepting Connections}).  @code{accept} for server
sockets blocks and interacts with @code{select} just as @code{read} does
for normal input.

@cindex file descriptor sets, for @code{select}
The file descriptor sets for the @code{select} function are specified
as @code{fd_set} objects.  Here is the description of the data type
and some macros for manipulating these objects.

@comment sys/types.h
@comment BSD
@deftp {Data Type} fd_set
The @code{fd_set} data type represents file descriptor sets for the
@code{select} function.  It is actually a bit array.
@end deftp

@comment sys/types.h
@comment BSD
@deftypevr Macro int FD_SETSIZE
The value of this macro is the maximum number of file descriptors that a
@code{fd_set} object can hold information about.  On systems with a
fixed maximum number, @code{FD_SETSIZE} is at least that number.  On
some systems, including GNU, there is no absolute limit on the number of
descriptors open, but this macro still has a constant value which
controls the number of bits in an @code{fd_set}.
@end deftypevr

@comment sys/types.h
@comment BSD
@deftypefn Macro void FD_ZERO (fd_set *@var{set})
This macro initializes the file descriptor set @var{set} to be the
empty set.
@end deftypefn

@comment sys/types.h
@comment BSD
@deftypefn Macro void FD_SET (int @var{filedes}, fd_set *@var{set})
This macro adds @var{filedes} to the file descriptor set @var{set}.
@end deftypefn

@comment sys/types.h
@comment BSD
@deftypefn Macro void FD_CLR (int @var{filedes}, fd_set *@var{set})
This macro removes @var{filedes} from the file descriptor set @var{set}.
@end deftypefn

@comment sys/types.h
@comment BSD
@deftypefn Macro int FD_ISSET (int @var{filedes}, fd_set *@var{set})
This macro returns a nonzero value (true) if @var{filedes} is a member
of the the file descriptor set @var{set}, and zero (false) otherwise.
@end deftypefn

Next, here is the description of the @code{select} function itself.

@comment sys/types.h
@comment BSD
@deftypefun int select (int @var{nfds}, fd_set *@var{read-fds}, fd_set *@var{write-fds}, fd_set *@var{except-fds}, struct timeval *@var{timeout})
The @code{select} function blocks the calling process until there is
activity on any of the specified sets of file descriptors, or until the
timeout period has expired.

The file descriptors specified by the @var{read-fds} argument are
checked to see if they are ready for reading (or if a server socket, for
accepting a connection); the @var{write-fds} file descriptors are
checked to see if they are ready for writing; and the @var{except-fds}
file descriptors are checked for exceptional conditions.  You can pass a
null pointer for any of these arguments if you are not interested in
checking for that kind of condition.
``Exceptional conditions'' does not mean errors---errors are reported
immediately when an erroneous system call is executed, and do not
constitute a state of the descriptor.  Rather, they include conditions
such as the presence of an urgent message on a socket.  (@xref{Sockets},
for information on urgent messages.)

The @code{select} function checks only the first @var{nfds} file
descriptors.  The usual thing is to pass @code{FD_SETSIZE} as the value
of this argument.

The @var{timeout} specifies the maximum time to wait.  If you pass a
null pointer for this argument, it means to block indefinitely until one
of the file descriptors is ready.  Otherwise, you should provide the
time in @code{struct timeval} format; see @ref{High-Resolution
Calendar}.  Specify zero as the time (a @code{struct timeval} containing
all zeros) if you want to find out which descriptors are ready without
waiting if none are ready.

The normal return value from @code{select} is the total number of ready file
descriptors in all of the sets.  Each of the argument sets is overwritten
with information about the descriptors that are ready for the corresponding
operation.  Thus, to see if a particular descriptor @var{desc} has input,
use @code{FD_ISSET (@var{desc}, @var{read-fds})} after @code{select} returns.

If @code{select} returns because the timeout period expires, it returns
a value of zero.

Any signal will cause @code{select} to return immediately.  So if your
program uses signals, you can't rely on @code{select} to keep waiting
for the full time specified.  If you want to be sure of waiting for a
particular amount of time, you must check for @code{EINTR} and repeat
the @code{select} with a newly calculated timeout based on the current
time.  See the example below.  See also @ref{Interrupted Primitives}.

If an error occurs, @code{select} returns @code{-1} and does not modify
the argument file descriptor sets.  The following @code{errno} error 
conditions are defined for this function:

@table @code
@item EBADF
One of the file descriptor sets specified an invalid file descriptor.

@item EINTR
The operation was interrupted by a signal.  @xref{Interrupted Primitives}.

@item EINVAL
The @var{timeout} argument is invalid; one of the components is negative
or too large.
@end table
@end deftypefun

@strong{Portability Note:}  The @code{select} function is a BSD Unix
feature.

Here is an example showing how you can use @code{select} to establish a
timeout period for reading from a file descriptor.  The @code{input_timeout}
function blocks the calling process until input is available on the
file descriptor, or until the timeout period expires.

@smallexample
@include select.c.texi
@end smallexample

There is another example showing the use of @code{select} to multiplex
input from multiple sockets in @ref{Server Example}.


@node Control Operations
@section Control Operations on Files

@cindex control operations on files
@cindex @code{fcntl} function
This section describes how you can perform various other operations on
file descriptors, such as inquiring about or setting flags describing
the status of the file descriptor, manipulating record locks, and the
like.  All of these operations are performed by the function @code{fcntl}.

The second argument to the @code{fcntl} function is a command that
specifies which operation to perform.  The function and macros that name
various flags that are used with it are declared in the header file
@file{fcntl.h}.  (Many of these flags are also used by the @code{open}
function; see @ref{Opening and Closing Files}.)
@pindex fcntl.h

@comment fcntl.h
@comment POSIX.1
@deftypefun int fcntl (int @var{filedes}, int @var{command}, @dots{})
The @code{fcntl} function performs the operation specified by
@var{command} on the file descriptor @var{filedes}.  Some commands
require additional arguments to be supplied.  These additional arguments
and the return value and error conditions are given in the detailed
descriptions of the individual commands.

Briefly, here is a list of what the various commands are.

@table @code
@item F_DUPFD
Duplicate the file descriptor (return another file descriptor pointing
to the same open file).  @xref{Duplicating Descriptors}.

@item F_GETFD
Get flags associated with the file descriptor.  @xref{Descriptor Flags}.

@item F_SETFD
Set flags associated with the file descriptor.  @xref{Descriptor Flags}.

@item F_GETFL
Get flags associated with the open file.  @xref{File Status Flags}.

@item F_SETFL
Set flags associated with the open file.  @xref{File Status Flags}.

@item F_GETLK
Get a file lock.  @xref{File Locks}.

@item F_SETLK
Set or clear a file lock.  @xref{File Locks}.

@item F_SETLKW
Like @code{F_SETLK}, but wait for completion.  @xref{File Locks}.

@item F_GETOWN
Get process or process group ID to receive @code{SIGIO} signals.
@xref{Interrupt Input}.

@item F_SETOWN
Set process or process group ID to receive @code{SIGIO} signals.
@xref{Interrupt Input}.
@end table
@end deftypefun


@node Duplicating Descriptors
@section Duplicating Descriptors

@cindex duplicating file descriptors
@cindex redirecting input and output

You can @dfn{duplicate} a file descriptor, or allocate another file
descriptor that refers to the same open file as the original.  Duplicate
descriptors share one file position and one set of file status flags
(@pxref{File Status Flags}), but each has its own set of file descriptor
flags (@pxref{Descriptor Flags}).

The major use of duplicating a file descriptor is to implement
@dfn{redirection} of input or output:  that is, to change the
file or pipe that a particular file descriptor corresponds to.

You can perform this operation using the @code{fcntl} function with the
@code{F_DUPFD} command, but there are also convenient functions
@code{dup} and @code{dup2} for duplicating descriptors.

@pindex unistd.h
@pindex fcntl.h
The @code{fcntl} function and flags are declared in @file{fcntl.h},
while prototypes for @code{dup} and @code{dup2} are in the header file
@file{unistd.h}.

@comment unistd.h
@comment POSIX.1
@deftypefun int dup (int @var{old})
This function copies descriptor @var{old} to the first available
descriptor number (the first number not currently open).  It is
equivalent to @code{fcntl (@var{old}, F_DUPFD, 0)}.
@end deftypefun

@comment unistd.h
@comment POSIX.1
@deftypefun int dup2 (int @var{old}, int @var{new})
This function copies the descriptor @var{old} to descriptor number
@var{new}.

If @var{old} is an invalid descriptor, then @code{dup2} does nothing; it
does not close @var{new}.  Otherwise, the new duplicate of @var{old}
replaces any previous meaning of descriptor @var{new}, as if @var{new}
were closed first.

If @var{old} and @var{new} are different numbers, and @var{old} is a
valid descriptor number, then @code{dup2} is equivalent to:

@smallexample
close (@var{new});
fcntl (@var{old}, F_DUPFD, @var{new})
@end smallexample

However, @code{dup2} does this atomically; there is no instant in the
middle of calling @code{dup2} at which @var{new} is closed and not yet a
duplicate of @var{old}.
@end deftypefun

@comment fcntl.h
@comment POSIX.1
@deftypevr Macro int F_DUPFD
This macro is used as the @var{command} argument to @code{fcntl}, to
copy the file descriptor given as the first argument.

The form of the call in this case is:

@smallexample
fcntl (@var{old}, F_DUPFD, @var{next-filedes})
@end smallexample

The @var{next-filedes} argument is of type @code{int} and specifies that
the file descriptor returned should be the next available one greater
than or equal to this value.

The return value from @code{fcntl} with this command is normally the value
of the new file descriptor.  A return value of @code{-1} indicates an
error.  The following @code{errno} error conditions are defined for
this command:

@table @code
@item EBADF
The @var{old} argument is invalid.

@item EINVAL
The @var{next-filedes} argument is invalid.

@item EMFILE
There are no more file descriptors available---your program is already
using the maximum.  In BSD and GNU, the maximum is controlled by a
resource limit that can be changed; @pxref{Limits on Resources}, for
more information about the @code{RLIMIT_NOFILE} limit.
@end table

@code{ENFILE} is not a possible error code for @code{dup2} because
@code{dup2} does not create a new opening of a file; duplicate
descriptors do not count toward the limit which @code{ENFILE}
indicates.  @code{EMFILE} is possible because it refers to the limit on
distinct descriptor numbers in use in one process.
@end deftypevr