llio.texi

一个C源代码分析器

@node Low-Level I/O, File System Interface, I/O on Streams, Top
@chapter Low-Level Input/Output

This chapter describes functions for performing low-level input/output
operations on file descriptors.  These functions include the primitives
for the higher-level I/O functions described in @ref{I/O on Streams}, as
well as functions for performing low-level control operations for which
there are no equivalents on streams.

Stream-level I/O is more flexible and usually more convenient;
therefore, programmers generally use the descriptor-level functions only
when necessary.  These are some of the usual reasons:

@itemize @bullet
@item
For reading binary files in large chunks.

@item
For reading an entire file into core before parsing it.

@item
To perform operations other than data transfer, which can only be done
with a descriptor.  (You can use @code{fileno} to get the descriptor
corresponding to a stream.)

@item
To pass descriptors to a child process.  (The child can create its own
stream to use a descriptor that it inherits, but cannot inherit a stream
directly.)
@end itemize

@menu
* Opening and Closing Files::           How to open and close file
                                         descriptors. 
* I/O Primitives::                      Reading and writing data.
* File Position Primitive::             Setting a descriptor's file
                                         position. 
* Descriptors and Streams::             Converting descriptor to stream
                                         or vice-versa.
* Stream/Descriptor Precautions::       Precautions needed if you use both
                                         descriptors and streams.
* Waiting for I/O::                     How to check for input or output
					 on multiple file descriptors.
* Control Operations::                  Various other operations on file
					 descriptors.
* Duplicating Descriptors::             Fcntl commands for duplicating
                                         file descriptors.
* Descriptor Flags::                    Fcntl commands for manipulating
                                         flags associated with file
                                         descriptors. 
* File Status Flags::                   Fcntl commands for manipulating
                                         flags associated with open files.
* File Locks::                          Fcntl commands for implementing
                                         file locking.
* Interrupt Input::                     Getting an asynchronous signal when
                                         input arrives.
@end menu


@node Opening and Closing Files
@section Opening and Closing Files

@cindex opening a file descriptor
@cindex closing a file descriptor
This section describes the primitives for opening and closing files
using file descriptors.  The @code{open} and @code{creat} functions are
declared in the header file @file{fcntl.h}, while @code{close} is
declared in @file{unistd.h}.
@pindex unistd.h
@pindex fcntl.h

@comment fcntl.h
@comment POSIX.1
@deftypefun int open (const char *@var{filename}, int @var{flags}[, mode_t @var{mode}])
The @code{open} function creates and returns a new file descriptor
for the file named by @var{filename}.  Initially, the file position
indicator for the file is at the beginning of the file.  The argument
@var{mode} is used only when a file is created, but it doesn't hurt
to supply the argument in any case.

The @var{flags} argument controls how the file is to be opened.  This is
a bit mask; you create the value by the bitwise OR of the appropriate
parameters (using the @samp{|} operator in C).
@xref{File Status Flags}, for the parameters available.

The normal return value from @code{open} is a non-negative integer file
descriptor.  In the case of an error, a value of @code{-1} is returned
instead.  In addition to the usual file name syntax errors (@pxref{File
Name Errors}), the following @code{errno} error conditions are defined
for this function:

@table @code
@item EACCES
The file exists but is not readable/writable as requested by the @var{flags}
argument.

@item EEXIST
Both @code{O_CREAT} and @code{O_EXCL} are set, and the named file already
exists.

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

@item EISDIR
The @var{flags} argument specified write access, and the file is a directory.

@item EMFILE
The process has too many files open.

@item ENFILE
The entire system, or perhaps the file system which contains the
directory, cannot support any additional open files at the moment.
(This problem cannot happen on the GNU system.)

@item ENOENT
The named file does not exist, and @code{O_CREAT} is not specified.

@item ENOSPC
The directory or file system that would contain the new file cannot be
extended, because there is no disk space left.

@item ENXIO
@code{O_NONBLOCK} and @code{O_WRONLY} are both set in the @var{flags}
argument, the file named by @var{filename} is a FIFO (@pxref{Pipes and
FIFOs}), and no process has the file open for reading.

@item EROFS
The file resides on a read-only file system and any of @code{O_WRONLY},
@code{O_RDWR}, and @code{O_TRUNC} are set in the @var{flags} argument,
or @code{O_CREAT} is set and the file does not already exist.
@end table

The @code{open} function is the underlying primitive for the @code{fopen}
and @code{freopen} functions, that create streams.
@end deftypefun

@comment fcntl.h
@comment POSIX.1
@deftypefn {Obsolete function} int creat (const char *@var{filename}, mode_t @var{mode})
This function is obsolete.  The call:

@smallexample
creat (@var{filename}, @var{mode})
@end smallexample

@noindent
is equivalent to:

@smallexample
open (@var{filename}, O_WRONLY | O_CREAT | O_TRUNC, @var{mode})
@end smallexample
@end deftypefn

@comment unistd.h
@comment POSIX.1
@deftypefun int close (int @var{filedes})
The function @code{close} closes the file descriptor @var{filedes}.
Closing a file has the following consequences:

@itemize @bullet
@item 
The file descriptor is deallocated.

@item
Any record locks owned by the process on the file are unlocked.

@item
When all file descriptors associated with a pipe or FIFO have been closed,
any unread data is discarded.
@end itemize

The normal return value from @code{close} is @code{0}; a value of @code{-1}
is returned in case of failure.  The following @code{errno} error
conditions are defined for this function:

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

@item EINTR
The @code{close} call was interrupted by a signal.
@xref{Interrupted Primitives}.
Here is an example of how to handle @code{EINTR} properly:

@smallexample
TEMP_FAILURE_RETRY (close (desc));
@end smallexample
@end table
@end deftypefun

To close a stream, call @code{fclose} (@pxref{Closing Streams}) instead
of trying to close its underlying file descriptor with @code{close}.
This flushes any buffered output and updates the stream object to
indicate that it is closed.

@node I/O Primitives
@section Input and Output Primitives

This section describes the functions for performing primitive input and
output operations on file descriptors: @code{read}, @code{write}, and
@code{lseek}.  These functions are declared in the header file
@file{unistd.h}.
@pindex unistd.h

@comment unistd.h
@comment POSIX.1
@deftp {Data Type} ssize_t
This data type is used to represent the sizes of blocks that can be
read or written in a single operation.  It is similar to @code{size_t},
but must be a signed type.
@end deftp

@cindex reading from a file descriptor
@comment unistd.h
@comment POSIX.1
@deftypefun ssize_t read (int @var{filedes}, void *@var{buffer}, size_t @var{size})
The @code{read} function reads up to @var{size} bytes from the file
with descriptor @var{filedes}, storing the results in the @var{buffer}.
(This is not necessarily a character string and there is no terminating
null character added.)

@cindex end-of-file, on a file descriptor
The return value is the number of bytes actually read.  This might be
less than @var{size}; for example, if there aren't that many bytes left
in the file or if there aren't that many bytes immediately available.
The exact behavior depends on what kind of file it is.  Note that
reading less than @var{size} bytes is not an error.

A value of zero indicates end-of-file (except if the value of the
@var{size} argument is also zero).  This is not considered an error.
If you keep calling @code{read} while at end-of-file, it will keep
returning zero and doing nothing else.

If @code{read} returns at least one character, there is no way you can
tell whether end-of-file was reached.  But if you did reach the end, the
next read will return zero.

In case of an error, @code{read} returns @code{-1}.  The following
@code{errno} error conditions are defined for this function:

@table @code
@item EAGAIN
Normally, when no input is immediately available, @code{read} waits for
some input.  But if the @code{O_NONBLOCK} flag is set for the file
(@pxref{File Status Flags}), @code{read} returns immediately without
reading any data, and reports this error.

@strong{Compatibility Note:} Most versions of BSD Unix use a different
error code for this: @code{EWOULDBLOCK}.  In the GNU library,
@code{EWOULDBLOCK} is an alias for @code{EAGAIN}, so it doesn't matter
which name you use.

On some systems, reading a large amount of data from a character special
file can also fail with @code{EAGAIN} if the kernel cannot find enough
physical memory to lock down the user's pages.  This is limited to
devices that transfer with direct memory access into the user's memory,
which means it does not include terminals, since they always use
separate buffers inside the kernel.

Any condition that could result in @code{EAGAIN} can instead result in a
successful @code{read} which returns fewer bytes than requested.
Calling @code{read} again immediately would result in @code{EAGAIN}.

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

@item EINTR
@code{read} was interrupted by a signal while it was waiting for input.
@xref{Interrupted Primitives}.

@item EIO
For many devices, and for disk files, this error code indicates
a hardware error.

@code{EIO} also occurs when a background process tries to read from the
controlling terminal, and the normal action of stopping the process by
sending it a @code{SIGTTIN} signal isn't working.  This might happen if
signal is being blocked or ignored, or because the process group is
orphaned.  @xref{Job Control}, for more information about job control,
and @ref{Signal Handling}, for information about signals.
@end table

The @code{read} function is the underlying primitive for all of the
functions that read from streams, such as @code{fgetc}.
@end deftypefun

@cindex writing to a file descriptor
@comment unistd.h
@comment POSIX.1
@deftypefun ssize_t write (int @var{filedes}, const void *@var{buffer}, size_t @var{size})
The @code{write} function writes up to @var{size} bytes from
@var{buffer} to the file with descriptor @var{filedes}.  The data in
@var{buffer} is not necessarily a character string and a null character is
output like any other character.

The return value is the number of bytes actually written.  This is
normally the same as @var{size}, but might be less (for example, if the
physical media being written to fills up).

In the case of an error, @code{write} returns @code{-1}.  The following
@code{errno} error conditions are defined for this function:

@table @code
@item EAGAIN
Normally, @code{write} blocks until the write operation is complete.
But if the @code{O_NONBLOCK} flag is set for the file (@pxref{Control
Operations}), it returns immediately without writing any data, and
reports this error.  An example of a situation that might cause the
process to block on output is writing to a terminal device that supports
flow control, where output has been suspended by receipt of a STOP
character.

@strong{Compatibility Note:} Most versions of BSD Unix use a different
error code for this: @code{EWOULDBLOCK}.  In the GNU library,
@code{EWOULDBLOCK} is an alias for @code{EAGAIN}, so it doesn't matter
which name you use.

On some systems, writing a large amount of data from a character special
file can also fail with @code{EAGAIN} if the kernel cannot find enough
physical memory to lock down the user's pages.  This is limited to
devices that transfer with direct memory access into the user's memory,
which means it does not include terminals, since they always use
separate buffers inside the kernel.

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

@item EFBIG
The size of the file is larger than the implementation can support.

@item EINTR
The @code{write} operation was interrupted by a signal while it was
blocked waiting for completion.  @xref{Interrupted Primitives}.

@item EIO
For many devices, and for disk files, this error code indicates
a hardware error.

@item ENOSPC
The device is full.

@item EPIPE
This error is returned when you try to write to a pipe or FIFO that
isn't open for reading by any process.  When this happens, a @code{SIGPIPE}
signal is also sent to the process; see @ref{Signal Handling}.
@end table

Unless you have arranged to prevent @code{EINTR} failures, you should
check @code{errno} after each failing call to @code{write}, and if the
error was @code{EINTR}, you should simply repeat the call.
@xref{Interrupted Primitives}.  The easy way to do this is with the