<P>
<A NAME="IDX653"></A>
<U>Function:</U> FILE * <B>fdopen</B> <I>(int <VAR>filedes</VAR>, const char *<VAR>opentype</VAR>)</I><P>
The <CODE>fdopen</CODE> function returns a new stream for the file descriptor
<VAR>filedes</VAR>.
<P>
The <VAR>opentype</VAR> argument is interpreted in the same way as for the
<CODE>fopen</CODE> function (see section <A HREF="library_11.html#SEC120" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_11.html#SEC120">Opening Streams</A>), except that
the <SAMP>`b'</SAMP> option is not permitted; this is because GNU makes no
distinction between text and binary files.  Also, <CODE>"w"</CODE> and
<CODE>"w+"</CODE> do not cause truncation of the file; these have affect only
when opening a file, and in this case the file has already been opened.
You must make sure that the <VAR>opentype</VAR> argument matches the actual
mode of the open file descriptor.
<P>
The return value is the new stream.  If the stream cannot be created
(for example, if the modes for the file indicated by the file descriptor
do not permit the access specified by the <VAR>opentype</VAR> argument), a
null pointer is returned instead.
<P>
For an example showing the use of the <CODE>fdopen</CODE> function,
see section <A HREF="library_14.html#SEC212" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_14.html#SEC212">Creating a Pipe</A>.
<P>
<A NAME="IDX654"></A>
<U>Function:</U> int <B>fileno</B> <I>(FILE *<VAR>stream</VAR>)</I><P>
This function returns the file descriptor associated with the stream
<VAR>stream</VAR>.  If an error is detected (for example, if the <VAR>stream</VAR>
is not valid) or if <VAR>stream</VAR> does not do I/O to a file,
<CODE>fileno</CODE> returns <CODE>-1</CODE>.
<P>
<A NAME="IDX655"></A>
<A NAME="IDX656"></A>
<P>
There are also symbolic constants defined in <TT>`unistd.h'</TT> for the
file descriptors belonging to the standard streams <CODE>stdin</CODE>,
<CODE>stdout</CODE>, and <CODE>stderr</CODE>; see section <A HREF="library_11.html#SEC119" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_11.html#SEC119">Standard Streams</A>.
<A NAME="IDX657"></A>
<P>
<DL COMPACT>
<A NAME="IDX658"></A>
<DT><CODE>STDIN_FILENO</CODE>
<DD>This macro has value <CODE>0</CODE>, which is the file descriptor for
standard input.
<A NAME="IDX659"></A>
<P>
<A NAME="IDX660"></A>
<DT><CODE>STDOUT_FILENO</CODE>
<DD>This macro has value <CODE>1</CODE>, which is the file descriptor for
standard output.
<A NAME="IDX661"></A>
<P>
<A NAME="IDX662"></A>
<DT><CODE>STDERR_FILENO</CODE>
<DD>This macro has value <CODE>2</CODE>, which is the file descriptor for
standard error output.
<A NAME="IDX663"></A>
</DL>
<P>
<A NAME="IDX664"></A>
<A NAME="IDX665"></A>
<A NAME="IDX666"></A>
<A NAME="IDX667"></A>
<H2><A NAME="SEC176" HREF="library_toc.html#SEC176" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC176">Precautions for Mixing Streams and Descriptors</A></H2>
<P>
You can have multiple file descriptors and streams (let's call both
streams and descriptors "channels" for short) connected to the same
file, but you must take care to avoid confusion between channels.  There
are two cases to consider: <DFN>linked</DFN> channels that share a single
file position value, and <DFN>independent</DFN> channels that have their own
file positions.
<P>
It's best to use just one channel in your program for actual data
transfer to any given file, except when all the access is for input.
For example, if you open a pipe (something you can only do at the file
descriptor level), either do all I/O with the descriptor, or construct a
stream from the descriptor with <CODE>fdopen</CODE> and then do all I/O with
the stream.
<P>
<A NAME="IDX668"></A>
<H3><A NAME="SEC177" HREF="library_toc.html#SEC177" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC177">Linked Channels</A></H3>
<P>
Channels that come from a single opening share the same file position;
we call them <DFN>linked</DFN> channels.  Linked channels result when you
make a stream from a descriptor using <CODE>fdopen</CODE>, when you get a
descriptor from a stream with <CODE>fileno</CODE>, and when you copy a
descriptor with <CODE>dup</CODE> or <CODE>dup2</CODE>.  For files that don't support
random access, such as terminals and pipes, <EM>all</EM> channels are
effectively linked.  On random-access files, all append-type output
streams are effectively linked to each other.
<A NAME="IDX669"></A>
<P>
If you have been using a stream for I/O, and you want to do I/O using
another channel (either a stream or a descriptor) that is linked to it,
you must first <DFN>clean up</DFN> the stream that you have been using.
See section <A HREF="library_12.html#SEC179" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_12.html#SEC179">Cleaning Streams</A>.
<P>
Terminating a process, or executing a new program in the process,
destroys all the streams in the process.  If descriptors linked to these
streams persist in other processes, their file positions become
undefined as a result.  To prevent this, you must clean up the streams
before destroying them.
<P>
<A NAME="IDX670"></A>
<H3><A NAME="SEC178" HREF="library_toc.html#SEC178" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC178">Independent Channels</A></H3>
<P>
When you open channels (streams or descriptors) separately on a seekable
file, each channel has its own file position.  These are called
<DFN>independent channels</DFN>.
<P>
The system handles each channel independently.  Most of the time, this
is quite predictable and natural (especially for input): each channel
can read or write sequentially at its own place in the file.
The precautions you should take are these:
<P>
<UL>
<LI>
You should clean an output stream after use, before doing anything else
that might read or write from the same part of the file.
<P>
<LI>
You should clean an input stream before reading data that may have been
modified using an independent channel.  Otherwise, you might read
obsolete data that had been in the stream's buffer.
</UL>
<P>
If you do output to one channel at the end of the file, this will
certainly leave the other independent channels positioned somewhere
before the new end.  If you want them to output at the end, you must set
their file positions to end of file, first.  (This is not necessary if
you use an append-type descriptor or stream; they always output at the
current end of the file.)  In order to make the end-of-file position
accurate, you must clean the output channel you were using, if it is a
stream.  (This is necessary even if you plan to use an append-type
channel next.)
<P>
It's impossible for two channels to have separate file pointers for a
file that doesn't support random access.  Thus, channels for reading or
writing such files are always linked, never independent.  Append-type
channels are also always linked.  For these channels, follow the rules
for linked channels; see section <A HREF="library_12.html#SEC177" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_12.html#SEC177">Linked Channels</A>.
<P>
<H3><A NAME="SEC179" HREF="library_toc.html#SEC179" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC179">Cleaning Streams</A></H3>
<P>
On the GNU system, you can clean up any stream with <CODE>fclean</CODE>:
<P>
<A NAME="IDX671"></A>
<U>Function:</U> int <B>fclean</B> <I>(<VAR>stream</VAR>)</I><P>
Clean up the stream <VAR>stream</VAR> so that its buffer is empty.  If
<VAR>stream</VAR> is doing output, force it out.  If <VAR>stream</VAR> is doing
input, give the data in the buffer back to the system, arranging to
reread it.
<P>
On other systems, you can use <CODE>fflush</CODE> to clean a stream in most
cases.
<P>
You can skip the <CODE>fclean</CODE> or <CODE>fflush</CODE> if you know the stream
is already clean.  A stream is clean whenever its buffer is empty.  For
example, an unbuffered stream is always clean.  An input stream that is
at end-of-file is clean.  A line-buffered stream is clean when the last
character output was a newline.
<P>
There is one case in which cleaning a stream is impossible on most
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</CODE> 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</CODE> avoids both of
these problems.
<P>
Closing an output-only stream also does <CODE>fflush</CODE>, so this is a
valid way of cleaning an output stream.  On the GNU system, closing an
input stream does <CODE>fclean</CODE>.
<P>
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.  See section <A HREF="library_16.html#SEC272" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_16.html#SEC272">Terminal Modes</A>.
<P>
<A NAME="IDX672"></A>
<A NAME="IDX673"></A>
<A NAME="IDX674"></A>
<H2><A NAME="SEC180" HREF="library_toc.html#SEC180" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC180">Waiting for Input or Output</A></H2>
<P>
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.
<P>
You cannot normally use <CODE>read</CODE> 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.
<P>
A better solution is to use the <CODE>select</CODE> function.  This blocks the
program until input or output is ready on a specified set of file
descriptors, or until timer expires, whichever comes first.  This
facility is declared in the header file <TT>`sys/types.h'</TT>.
<A NAME="IDX675"></A>
<A NAME="IDX676"></A>
<P>
The file descriptor sets for the <CODE>select</CODE> function are specified
as <CODE>fd_set</CODE> objects.  Here is the description of the data type
and some macros for manipulating these objects.
<P>
<A NAME="IDX677"></A>
<U>Data Type:</U> <B>fd_set</B><P>
The <CODE>fd_set</CODE> data type represents file descriptor sets for the
<CODE>select</CODE> function.  It is actually a bit array.
<P>
<A NAME="IDX678"></A>
<U>Macro:</U> int <B>FD_SETSIZE</B><P>
The value of this macro is the maximum number of file descriptors that a
<CODE>fd_set</CODE> object can hold information about.  On systems with a
fixed maximum number, <CODE>FD_SETSIZE</CODE> 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</CODE>.
<P>
<A NAME="IDX679"></A>
<U>Macro:</U> void <B>FD_ZERO</B> <I>(fd_set *<VAR>set</VAR>)</I><P>
This macro initializes the file descriptor set <VAR>set</VAR> to be the
empty set.
<P>
<A NAME="IDX680"></A>
<U>Macro:</U> void <B>FD_SET</B> <I>(int <VAR>filedes</VAR>, fd_set *<VAR>set</VAR>)</I><P>
This macro adds <VAR>filedes</VAR> to the file descriptor set <VAR>set</VAR>.
<P>
<A NAME="IDX681"></A>
<U>Macro:</U> void <B>FD_CLR</B> <I>(int <VAR>filedes</VAR>, fd_set *<VAR>set</VAR>)</I><P>
This macro removes <VAR>filedes</VAR> from the file descriptor set <VAR>set</VAR>.
<P>
<A NAME="IDX682"></A>
<U>Macro:</U> int <B>FD_ISSET</B> <I>(int <VAR>filedes</VAR>, fd_set *<VAR>set</VAR>)</I><P>
This macro returns a nonzero value (true) if <VAR>filedes</VAR> is a member
of the the file descriptor set <VAR>set</VAR>, and zero (false) otherwise.
<P>
Next, here is the description of the <CODE>select</CODE> function itself.
<P>
<A NAME="IDX683"></A>
<U>Function:</U> int <B>select</B> <I>(int <VAR>nfds</VAR>, fd_set *<VAR>read_fds</VAR>, fd_set *<VAR>write_fds</VAR>, fd_set *<VAR>except_fds</VAR>, struct timeval *<VAR>timeout</VAR>)</I><P>
The <CODE>select</CODE> 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.
<P>
The file descriptors specified by the <VAR>read_fds</VAR> argument are
checked to see if they are ready for reading; the <VAR>write_fds</VAR> file
descriptors are checked to see if they are ready for writing; and the
<VAR>except_fds</VAR> 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.
<P>
"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.  (See section <A HREF="library_15.html#SEC216" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_15.html#SEC216">Sockets</A>,
for information on urgent messages.)
<P>