llio.texi

一个C源代码分析器

macro @code{TEMP_FAILURE_RETRY}, as follows:

@smallexample
nbytes = TEMP_FAILURE_RETRY (write (desc, buffer, count));
@end smallexample

The @code{write} function is the underlying primitive for all of the
functions that write to streams, such as @code{fputc}.
@end deftypefun

@node File Position Primitive
@section Setting the File Position of a Descriptor

Just as you can set the file position of a stream with @code{fseek}, you
can set the file position of a descriptor with @code{lseek}.  This
specifies the position in the file for the next @code{read} or
@code{write} operation.  @xref{File Positioning}, for more information
on the file position and what it means.

To read the current file position value from a descriptor, use
@code{lseek (@var{desc}, 0, SEEK_CUR)}.

@cindex file positioning on a file descriptor
@cindex positioning a file descriptor
@cindex seeking on a file descriptor
@comment unistd.h
@comment POSIX.1
@deftypefun off_t lseek (int @var{filedes}, off_t @var{offset}, int @var{whence})
The @code{lseek} function is used to change the file position of the
file with descriptor @var{filedes}.

The @var{whence} argument specifies how the @var{offset} should be
interpreted in the same way as for the @code{fseek} function, and can be
one of the symbolic constants @code{SEEK_SET}, @code{SEEK_CUR}, or
@code{SEEK_END}.

@table @code
@item SEEK_SET
Specifies that @var{whence} is a count of characters from the beginning
of the file.

@item SEEK_CUR
Specifies that @var{whence} is a count of characters from the current
file position.  This count may be positive or negative.

@item SEEK_END
Specifies that @var{whence} is a count of characters from the end of
the file.  A negative count specifies a position within the current
extent of the file; a positive count specifies a position past the
current end.  If you set the position past the current end, and 
actually write data, you will extend the file with zeros up to that
position.
@end table

The return value from @code{lseek} is normally the resulting file
position, measured in bytes from the beginning of the file.
You can use this feature together with @code{SEEK_CUR} to read the
current file position.

You can set the file position past the current end of the file.  This
does not by itself make the file longer; @code{lseek} never changes the
file.  But subsequent output at that position will extend the file.
Characters between the previous end of file and the new position
are filled with zeros.

If the file position cannot be changed, or the operation is in some way
invalid, @code{lseek} returns a value of @code{-1}.  The following
@code{errno} error conditions are defined for this function:

@table @code
@item EBADF
The @var{filedes} is not a valid file descriptor.

@item EINVAL
The @var{whence} argument value is not valid, or the resulting
file offset is not valid.

@item ESPIPE
The @var{filedes} corresponds to a pipe or FIFO, which cannot be positioned.
(There may be other kinds of files that cannot be positioned either, but
the behavior is not specified in those cases.)
@end table

The @code{lseek} function is the underlying primitive for the
@code{fseek}, @code{ftell} and @code{rewind} functions, which operate on
streams instead of file descriptors.
@end deftypefun

You can have multiple descriptors for the same file if you open the file
more than once, or if you duplicate a descriptor with @code{dup}.  
Descriptors that come from separate calls to @code{open} have independent
file positions; using @code{lseek} on one descriptor has no effect on the
other.  For example, 

@smallexample
@group
@{
  int d1, d2;
  char buf[4];
  d1 = open ("foo", O_RDONLY);
  d2 = open ("foo", O_RDONLY);
  lseek (d1, 1024, SEEK_SET);
  read (d2, buf, 4);
@}
@end group
@end smallexample

@noindent
will read the first four characters of the file @file{foo}.  (The
error-checking code necessary for a real program has been omitted here
for brevity.)

By contrast, descriptors made by duplication share a common file
position with the original descriptor that was duplicated.  Anything
which alters the file position of one of the duplicates, including
reading or writing data, affects all of them alike.  Thus, for example,

@smallexample
@{
  int d1, d2, d3;
  char buf1[4], buf2[4];
  d1 = open ("foo", O_RDONLY);
  d2 = dup (d1);
  d3 = dup (d2);
  lseek (d3, 1024, SEEK_SET);
  read (d1, buf1, 4);
  read (d2, buf2, 4);
@}
@end smallexample

@noindent
will read four characters starting with the 1024'th character of
@file{foo}, and then four more characters starting with the 1028'th
character.

@comment sys/types.h
@comment POSIX.1
@deftp {Data Type} off_t
This is an arithmetic data type used to represent file sizes.
In the GNU system, this is equivalent to @code{fpos_t} or @code{long int}.
@end deftp

These aliases for the @samp{SEEK_@dots{}} constants exist for the sake
of compatibility with older BSD systems.  They are defined in two
different header files: @file{fcntl.h} and @file{sys/file.h}.

@table @code
@item L_SET
An alias for @code{SEEK_SET}.

@item L_INCR
An alias for @code{SEEK_CUR}.

@item L_XTND
An alias for @code{SEEK_END}.
@end table

@node Descriptors and Streams
@section Descriptors and Streams
@cindex streams, and file descriptors
@cindex converting file descriptor to stream
@cindex extracting file descriptor from stream

Given an open file descriptor, you can create a stream for it with the
@code{fdopen} function.  You can get the underlying file descriptor for
an existing stream with the @code{fileno} function.  These functions are
declared in the header file @file{stdio.h}.
@pindex stdio.h

@comment stdio.h
@comment POSIX.1
@deftypefun {FILE *} fdopen (int @var{filedes}, const char *@var{opentype})
The @code{fdopen} function returns a new stream for the file descriptor
@var{filedes}.

The @var{opentype} argument is interpreted in the same way as for the
@code{fopen} function (@pxref{Opening Streams}), except that
the @samp{b} option is not permitted; this is because GNU makes no
distinction between text and binary files.  Also, @code{"w"} and
@code{"w+"} 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} argument matches the actual
mode of the open file descriptor.

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} argument), a
null pointer is returned instead.
@end deftypefun

For an example showing the use of the @code{fdopen} function,
see @ref{Creating a Pipe}.

@comment stdio.h
@comment POSIX.1
@deftypefun int fileno (FILE *@var{stream})
This function returns the file descriptor associated with the stream
@var{stream}.  If an error is detected (for example, if the @var{stream}
is not valid) or if @var{stream} does not do I/O to a file,
@code{fileno} returns @code{-1}.
@end deftypefun

@cindex standard file descriptors
@cindex file descriptors, standard
There are also symbolic constants defined in @file{unistd.h} for the
file descriptors belonging to the standard streams @code{stdin},
@code{stdout}, and @code{stderr}; see @ref{Standard Streams}.
@pindex unistd.h

@comment unistd.h
@comment POSIX.1
@table @code
@item STDIN_FILENO
@vindex STDIN_FILENO
This macro has value @code{0}, which is the file descriptor for
standard input.
@cindex standard input file descriptor

@comment unistd.h
@comment POSIX.1
@item STDOUT_FILENO
@vindex STDOUT_FILENO
This macro has value @code{1}, which is the file descriptor for
standard output.
@cindex standard output file descriptor

@comment unistd.h
@comment POSIX.1
@item STDERR_FILENO
@vindex STDERR_FILENO
This macro has value @code{2}, which is the file descriptor for
standard error output.
@end table
@cindex standard error file descriptor

@node Stream/Descriptor Precautions
@section Dangers of Mixing Streams and Descriptors
@cindex channels
@cindex streams and descriptors
@cindex descriptors and streams
@cindex mixing descriptors and streams

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} channels that share a single
file position value, and @dfn{independent} channels that have their own
file positions.

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} and then do all I/O with
the stream.

@menu
* Linked Channels::	   Dealing with channels sharing a file position.
* Independent Channels::   Dealing with separately opened, unlinked channels.
* Cleaning Streams::	   Cleaning a stream makes it safe to use 
                            another channel.
@end menu

@node Linked Channels
@subsection Linked Channels
@cindex linked channels

Channels that come from a single opening share the same file position;
we call them @dfn{linked} channels.  Linked channels result when you
make a stream from a descriptor using @code{fdopen}, when you get a
descriptor from a stream with @code{fileno}, and when you copy a
descriptor with @code{dup} or @code{dup2}.  For files that don't support
random access, such as terminals and pipes, @emph{all} channels are
effectively linked.  On random-access files, all append-type output
streams are effectively linked to each other.

@cindex cleaning up a stream
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} the stream that you have been using.
@xref{Cleaning Streams}.

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.

@node Independent Channels
@subsection Independent Channels
@cindex independent channels

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}.

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.  However,
if some of the channels are streams, you must take these precautions:

@itemize @bullet
@item
You should clean an output stream after use, before doing anything else
that might read or write from the same part of the file.

@item
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.
@end itemize

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.)

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 @ref{Linked Channels}.

@node Cleaning Streams
@subsection Cleaning Streams

On the GNU system, you can clean up any stream with @code{fclean}:

@comment stdio.h
@comment GNU
@deftypefun int fclean (FILE *@var{stream})
Clean up the stream @var{stream} so that its buffer is empty.  If
@var{stream} is doing output, force it out.  If @var{stream} is doing
input, give the data in the buffer back to the system, arranging to
reread it.
@end deftypefun

On other systems, you can use @code{fflush} to clean a stream in most
cases.

You can skip the @code{fclean} or @code{fflush} 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.

There is one case in which cleaning a stream is impossible on most