The <CODE>select</CODE> function checks only the first <VAR>nfds</VAR> file
descriptors.  The usual thing is to pass <CODE>FD_SETSIZE</CODE> as the value
of this argument.
<P>
The <VAR>timeout</VAR> 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</CODE> format; see section <A HREF="library_19.html#SEC315" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_19.html#SEC315">High-Resolution Calendar</A>.  Specify zero as the time (a <CODE>struct timeval</CODE> containing
all zeros) if you want to find out which descriptors are ready without
waiting if none are ready.
<P>
The normal return value from <CODE>select</CODE> 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</VAR> has input,
use <CODE>FD_ISSET (<VAR>desc</VAR>, <VAR>read_fds</VAR>)</CODE> after <CODE>select</CODE> returns.
<P>
If <CODE>select</CODE> returns because the timeout period expires, it returns
a value of zero.
<P>
Any signal will cause <CODE>select</CODE> to return immediately.  So if your
program uses signals, you can't rely on <CODE>select</CODE> 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</CODE> and repeat
the <CODE>select</CODE> with a newly calculated timeout based on the current
time.  See the example below.  See also section <A HREF="library_21.html#SEC362" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_21.html#SEC362">Primitives Interrupted by Signals</A>.
<P>
If an error occurs, <CODE>select</CODE> returns <CODE>-1</CODE> and does not modify
the argument file descriptor sets.  The following <CODE>errno</CODE> error 
conditions are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EBADF</CODE>
<DD>One of the file descriptor sets specified an invalid file descriptor.
<P>
<DT><CODE>EINTR</CODE>
<DD>The operation was interrupted by a signal.  See section <A HREF="library_21.html#SEC362" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_21.html#SEC362">Primitives Interrupted by Signals</A>.
<P>
<DT><CODE>EINVAL</CODE>
<DD>The <VAR>timeout</VAR> argument is invalid; one of the components is negative
or too large.
</DL>
<P>
<STRONG>Portability Note:</STRONG>  The <CODE>select</CODE> function is a BSD Unix
feature.
<P>
Here is an example showing how you can use <CODE>select</CODE> to establish a
timeout period for reading from a file descriptor.  The <CODE>input_timeout</CODE>
function blocks the calling process until input is available on the
file descriptor, or until the timeout period expires.
<P>
<PRE>
#include &#60;stdio.h&#62;
#include &#60;unistd.h&#62;
#include &#60;sys/types.h&#62;
#include &#60;sys/time.h&#62;

int 
input_timeout (int filedes, unsigned int seconds)
{
  fd_set set;
  struct timeval timeout;

  /* Initialize the file descriptor set.  */
  FD_ZERO (&#38;set);
  FD_SET (filedes, &#38;set);

  /* Initialize the timeout data structure.  */
  timeout.tv_sec = seconds;
  timeout.tv_usec = 0;

  /* <CODE>select</CODE> returns 0 if timeout, 1 if input available, -1 if error.  */
  return TEMP_FAILURE_RETRY (select (FD_SETSIZE, &#38;set, NULL, NULL, &#38;timeout));
}

int
main (void)
{
  fprintf (stderr, "select returned %d.\n", input_timeout (STDIN_FILENO, 5));
  return 0;
}
</PRE>
<P>
There is another example showing the use of <CODE>select</CODE> to multiplex
input from multiple sockets in section <A HREF="library_15.html#SEC254" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_15.html#SEC254">Byte Stream Connection Server Example</A>.
<P>
<H2><A NAME="SEC181" HREF="library_toc.html#SEC181" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC181">Control Operations on Files</A></H2>
<A NAME="IDX684"></A>
<A NAME="IDX685"></A>
<P>
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</CODE>.
<P>
The second argument to the <CODE>fcntl</CODE> 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
<TT>`fcntl.h'</TT>.  (Many of these flags are also used by the <CODE>open</CODE>
function; see section <A HREF="library_12.html#SEC172" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_12.html#SEC172">Opening and Closing Files</A>.)
<A NAME="IDX686"></A>
<P>
<A NAME="IDX687"></A>
<U>Function:</U> int <B>fcntl</B> <I>(int <VAR>filedes</VAR>, int <VAR>command</VAR>, ...)</I><P>
The <CODE>fcntl</CODE> function performs the operation specified by
<VAR>command</VAR> on the file descriptor <VAR>filedes</VAR>.  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.
<P>
Briefly, here is a list of what the various commands are.
<P>
<DL COMPACT>
<DT><CODE>F_DUPFD</CODE>
<DD>Duplicate the file descriptor (return another file descriptor pointing
to the same open file).  See section <A HREF="library_12.html#SEC182" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_12.html#SEC182">Duplicating Descriptors</A>.
<P>
<DT><CODE>F_GETFD</CODE>
<DD>Get flags associated with the file descriptor.  See section <A HREF="library_12.html#SEC183" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_12.html#SEC183">File Descriptor Flags</A>.
<P>
<DT><CODE>F_SETFD</CODE>
<DD>Set flags associated with the file descriptor.  See section <A HREF="library_12.html#SEC183" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_12.html#SEC183">File Descriptor Flags</A>.
<P>
<DT><CODE>F_GETFL</CODE>
<DD>Get flags associated with the open file.  See section <A HREF="library_12.html#SEC184" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_12.html#SEC184">File Status Flags</A>.
<P>
<DT><CODE>F_SETFL</CODE>
<DD>Set flags associated with the open file.  See section <A HREF="library_12.html#SEC184" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_12.html#SEC184">File Status Flags</A>.
<P>
<DT><CODE>F_GETLK</CODE>
<DD>Get a file lock.  See section <A HREF="library_12.html#SEC185" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_12.html#SEC185">File Locks</A>.
<P>
<DT><CODE>F_SETLK</CODE>
<DD>Set or clear a file lock.  See section <A HREF="library_12.html#SEC185" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_12.html#SEC185">File Locks</A>.
<P>
<DT><CODE>F_SETLKW</CODE>
<DD>Like <CODE>F_SETLK</CODE>, but wait for completion.  See section <A HREF="library_12.html#SEC185" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_12.html#SEC185">File Locks</A>.
<P>
<DT><CODE>F_GETOWN</CODE>
<DD>Get process or process group ID to receive <CODE>SIGIO</CODE> signals.
See section <A HREF="library_12.html#SEC186" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_12.html#SEC186">Interrupt-Driven Input</A>.
<P>
<DT><CODE>F_SETOWN</CODE>
<DD>Set process or process group ID to receive <CODE>SIGIO</CODE> signals.
See section <A HREF="library_12.html#SEC186" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_12.html#SEC186">Interrupt-Driven Input</A>.
</DL>
<P>
<H2><A NAME="SEC182" HREF="library_toc.html#SEC182" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC182">Duplicating Descriptors</A></H2>
<A NAME="IDX688"></A>
<A NAME="IDX689"></A>
<P>
You can <DFN>duplicate</DFN> 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
(see section <A HREF="library_12.html#SEC184" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_12.html#SEC184">File Status Flags</A>), but each has its own set of file descriptor
flags (see section <A HREF="library_12.html#SEC183" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_12.html#SEC183">File Descriptor Flags</A>).
<P>
The major use of duplicating a file descriptor is to implement
<DFN>redirection</DFN> of input or output:  that is, to change the
file or pipe that a particular file descriptor corresponds to.
<P>
You can perform this operation using the <CODE>fcntl</CODE> function with the
<CODE>F_DUPFD</CODE> command, but there are also convenient functions
<CODE>dup</CODE> and <CODE>dup2</CODE> for duplicating descriptors.
<A NAME="IDX690"></A>
<A NAME="IDX691"></A>
<P>
The <CODE>fcntl</CODE> function and flags are declared in <TT>`fcntl.h'</TT>,
while prototypes for <CODE>dup</CODE> and <CODE>dup2</CODE> are in the header file
<TT>`unistd.h'</TT>.
<P>
<A NAME="IDX692"></A>
<U>Function:</U> int <B>dup</B> <I>(int <VAR>old</VAR>)</I><P>
This function copies descriptor <VAR>old</VAR> to the first available
descriptor number (the first number not currently open).  It is
equivalent to <CODE>fcntl (<VAR>old</VAR>, F_DUPFD, 0)</CODE>.
<P>
<A NAME="IDX693"></A>
<U>Function:</U> int <B>dup2</B> <I>(int <VAR>old</VAR>, int <VAR>new</VAR>)</I><P>
This function copies the descriptor <VAR>old</VAR> to descriptor number
<VAR>new</VAR>.
<P>
If <VAR>old</VAR> is an invalid descriptor, then <CODE>dup2</CODE> does nothing; it
does not close <VAR>new</VAR>.  Otherwise, the new duplicate of <VAR>old</VAR>
replaces any previous meaning of descriptor <VAR>new</VAR>, as if <VAR>new</VAR>
were closed first.
<P>
If <VAR>old</VAR> and <VAR>new</VAR> are different numbers, and <VAR>old</VAR> is a
valid descriptor number, then <CODE>dup2</CODE> is equivalent to:
<P>
<PRE>
close (<VAR>new</VAR>);
fcntl (<VAR>old</VAR>, F_DUPFD, <VAR>new</VAR>)
</PRE>
<P>
However, <CODE>dup2</CODE> does this atomically; there is no instant in the
middle of calling <CODE>dup2</CODE> at which <VAR>new</VAR> is closed and not yet a
duplicate of <VAR>old</VAR>.
<P>
<A NAME="IDX694"></A>
<U>Macro:</U> int <B>F_DUPFD</B><P>
This macro is used as the <VAR>command</VAR> argument to <CODE>fcntl</CODE>, to
copy the file descriptor given as the first argument.
<P>
The form of the call in this case is:
<P>
<PRE>
fcntl (<VAR>old</VAR>, F_DUPFD, <VAR>next_filedes</VAR>)
</PRE>
<P>
The <VAR>next_filedes</VAR> argument is of type <CODE>int</CODE> and specifies that
the file descriptor returned should be the next available one greater
than or equal to this value.
<P>
The return value from <CODE>fcntl</CODE> with this command is normally the value
of the new file descriptor.  A return value of <CODE>-1</CODE> indicates an
error.  The following <CODE>errno</CODE> error conditions are defined for
this command:
<P>
<DL COMPACT>
<DT><CODE>EBADF</CODE>
<DD>The <VAR>old</VAR> argument is invalid.
<P>
<DT><CODE>EINVAL</CODE>
<DD>The <VAR>next_filedes</VAR> argument is invalid.
<P>
<DT><CODE>EMFILE</CODE>
<DD>There are no more file descriptors available--your program is already
using the maximum.
</DL>
<P>
<CODE>ENFILE</CODE> is not a possible error code for <CODE>dup2</CODE> because
<CODE>dup2</CODE> does not create a new opening of a file; duplicate
descriptors do not count toward the limit which <CODE>ENFILE</CODE>
indicates.  <CODE>EMFILE</CODE> is possible because it refers to the limit on
distinct descriptor numbers in use in one process.
<P>
Here is an example showing how to use <CODE>dup2</CODE> to do redirection.
Typically, redirection of the standard streams (like <CODE>stdin</CODE>) is
done by a shell or shell-like program before calling one of the
<CODE>exec</CODE> functions (see section <A HREF="library_23.html#SEC406" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_23.html#SEC406">Executing a File</A>) to execute a new
program in a child process.  When the new program is executed, it
creates and initializes the standard streams to point to the
corresponding file descriptors, before its <CODE>main</CODE> function is
invoked.
<P>
So, to redirect standard input to a file, the shell could do something
like:
<P>
<PRE>
pid = fork ();
if (pid == 0)
  {
    char *filename;
    char *program;
    int file;
    ...
    file = TEMP_FAILURE_RETRY (open (filename, O_RDONLY));
    dup2 (file, STDIN_FILENO);
    TEMP_FAILURE_RETRY (close (file));
    execv (program, NULL);
  }
</PRE>
<P>
There is also a more detailed example showing how to implement redirection
in the context of a pipeline of processes in section <A HREF="library_24.html#SEC420" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_24.html#SEC420">Launching Jobs</A>.
<P>
<A NAME="IDX695"></A>