This is Info file libc.info, produced by Makeinfo version 1.68 from the
input file libc.texinfo.

INFO-DIR-SECTION GNU libraries
START-INFO-DIR-ENTRY
* Libc: (libc).                 C library.
END-INFO-DIR-ENTRY

   This file documents the GNU C library.

   This is Edition 0.08 DRAFT, last updated 11 Jan 1999, of `The GNU C
Library Reference Manual', for Version 2.1 Beta.

   Copyright (C) 1993, '94, '95, '96, '97, '98, '99 Free Software
Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the section entitled "GNU Library General Public License" is
included exactly as in the original, and provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that the text of the translation of the section
entitled "GNU Library General Public License" must be approved for
accuracy by the Foundation.


File: libc.info,  Node: I/O Primitives,  Next: File Position Primitive,  Prev: Truncating Files,  Up: Low-Level I/O

Input and Output Primitives
===========================

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

 - 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 `size_t',
     but must be a signed type.

 - Function: ssize_t read (int FILEDES, void *BUFFER, size_t SIZE)
     The `read' function reads up to SIZE bytes from the file with
     descriptor FILEDES, storing the results in the BUFFER.  (This is
     not necessarily a character string and there is no terminating
     null character added.)

     The return value is the number of bytes actually read.  This might
     be less than 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 SIZE bytes is not an error.

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

     If `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, `read' returns -1.  The following `errno'
     error conditions are defined for this function:

    `EAGAIN'
          Normally, when no input is immediately available, `read'
          waits for some input.  But if the `O_NONBLOCK' flag is set
          for the file (*note File Status Flags::.), `read' returns
          immediately without reading any data, and reports this error.

          *Compatibility Note:* Most versions of BSD Unix use a
          different error code for this: `EWOULDBLOCK'.  In the GNU
          library, `EWOULDBLOCK' is an alias for `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 `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.  This problem never happens in the
          GNU system.

          Any condition that could result in `EAGAIN' can instead
          result in a successful `read' which returns fewer bytes than
          requested.  Calling `read' again immediately would result in
          `EAGAIN'.

    `EBADF'
          The FILEDES argument is not a valid file descriptor, or is
          not open for reading.

    `EINTR'
          `read' was interrupted by a signal while it was waiting for
          input.  *Note Interrupted Primitives::.  A signal will not
          necessary cause `read' to return `EINTR'; it may instead
          result in a successful `read' which returns fewer bytes than
          requested.

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

          `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 `SIGTTIN' signal isn't
          working.  This might happen if signal is being blocked or
          ignored, or because the process group is orphaned.  *Note Job
          Control::, for more information about job control, and *Note
          Signal Handling::, for information about signals.

     Please note that there is no function named `read64'.  This is not
     necessary since this function does not directly modify or handle
     the possibly wide file offset.  Since the kernel handles this state
     internally the `read' function can be used for all cases.

     This function is a cancelation point in multi-threaded programs.
     This is a problem if the thread allocates some resources (like
     memory, file descriptors, semaphores or whatever) at the time
     `read' is called.  If the thread gets canceled these resources
     stay allocated until the program ends.  To avoid this calls to
     `read' should be protected using cancelation handlers.

     The `read' function is the underlying primitive for all of the
     functions that read from streams, such as `fgetc'.

 - Function: ssize_t pread (int FILEDES, void *BUFFER, size_t SIZE,
          off_t OFFSET)
     The `pread' function is similar to the `read' function.  The first
     three arguments are identical and also the return values and error
     codes correspond.

     The difference is the fourth argument and its handling.  The data
     block is not read from the current position of the file descriptor
     `filedes'.  Instead the data is read from the file starting at
     position OFFSET.  The position of the file descriptor itself is
     not effected by the operation.  The value is the same as before
     the call.

     When the source file is compiled with `_FILE_OFFSET_BITS == 64' the
     `pread' function is in fact `pread64' and the type `off_t' has 64
     bits which makes it possible to handle files up to 2^63 bytes in
     length.

     The return value of `pread' describes the number of bytes read.
     In the error case it returns -1 like `read' does and the error
     codes are also the same.  Only there are a few more error codes:
    `EINVAL'
          The value given for OFFSET is negative and therefore illegal.

    `ESPIPE'
          The file descriptor FILEDES is associate with a pipe or a
          FIFO and this device does not allow positioning of the file
          pointer.

     The function is an extension defined in the Unix Single
     Specification version 2.

 - Function: ssize_t pread64 (int FILEDES, void *BUFFER, size_t SIZE,
          off64_t OFFSET)
     This function is similar to the `pread' function.  The difference
     is that the OFFSET parameter is of type `off64_t' instead of
     `off_t' which makes it possible on 32 bits machines to address
     files larger than 2^31 bytes and up to 2^63 bytes.  The file
     descriptor `filedes' must be opened using `open64' since otherwise
     the large offsets possible with `off64_t' will lead to errors with
     a descriptor in small file mode.

     When the source file is compiled with `_FILE_OFFSET_BITS == 64' on
     a 32 bits machine this function is actually available under the
     name `pread' and so transparently replaces the 32 bits interface.

 - Function: ssize_t write (int FILEDES, const void *BUFFER, size_t
          SIZE)
     The `write' function writes up to SIZE bytes from BUFFER to the
     file with descriptor FILEDES.  The data in 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
     may be SIZE, but can always be smaller.  Your program should
     always call `write' in a loop, iterating until all the data is
     written.

     Once `write' returns, the data is enqueued to be written and can be
     read back right away, but it is not necessarily written out to
     permanent storage immediately.  You can use `fsync' when you need
     to be sure your data has been permanently stored before
     continuing.  (It is more efficient for the system to batch up
     consecutive writes and do them all at once when convenient.
     Normally they will always be written to disk within a minute or
     less.)  Modern systems provide another function `fdatasync' which
     guarantees integrity only for the file data and is therefore
     faster.  You can use the `O_FSYNC' open mode to make `write' always
     store the data to disk before returning; *note Operating Modes::..

     In the case of an error, `write' returns -1.  The following
     `errno' error conditions are defined for this function:

    `EAGAIN'
          Normally, `write' blocks until the write operation is
          complete.  But if the `O_NONBLOCK' flag is set for the file
          (*note 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.

          *Compatibility Note:* Most versions of BSD Unix use a
          different error code for this: `EWOULDBLOCK'.  In the GNU
          library, `EWOULDBLOCK' is an alias for `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 `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.  This problem does not arise in the
          GNU system.

    `EBADF'
          The FILEDES argument is not a valid file descriptor, or is
          not open for writing.

    `EFBIG'
          The size of the file would become larger than the
          implementation can support.

    `EINTR'
          The `write' operation was interrupted by a signal while it was
          blocked waiting for completion.  A signal will not necessary
          cause `write' to return `EINTR'; it may instead result in a
          successful `write' which writes fewer bytes than requested.
          *Note Interrupted Primitives::.

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

    `ENOSPC'
          The device containing the file is full.

    `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 `SIGPIPE' signal is also sent to the process; see
          *Note Signal Handling::.

     Unless you have arranged to prevent `EINTR' failures, you should
     check `errno' after each failing call to `write', and if the error
     was `EINTR', you should simply repeat the call.  *Note Interrupted
     Primitives::.  The easy way to do this is with the macro
     `TEMP_FAILURE_RETRY', as follows:

          nbytes = TEMP_FAILURE_RETRY (write (desc, buffer, count));

     Please note that there is no function named `write64'.  This is not
     necessary since this function does not directly modify or handle
     the possibly wide file offset.  Since the kernel handles this state
     internally the `write' function can be used for all cases.

     This function is a cancelation point in multi-threaded programs.
     This is a problem if the thread allocates some resources (like
     memory, file descriptors, semaphores or whatever) at the time
     `write' is called.  If the thread gets canceled these resources
     stay allocated until the program ends.  To avoid this calls to
     `write' should be protected using cancelation handlers.

     The `write' function is the underlying primitive for all of the
     functions that write to streams, such as `fputc'.

 - Function: ssize_t pwrite (int FILEDES, const void *BUFFER, size_t
          SIZE, off_t OFFSET)
     The `pwrite' function is similar to the `write' function.  The
     first three arguments are identical and also the return values and
     error codes correspond.

     The difference is the fourth argument and its handling.  The data
     block is not written to the current position of the file descriptor
     `filedes'.  Instead the data is written to the file starting at
     position OFFSET.  The position of the file descriptor itself is
     not effected by the operation.  The value is the same as before
     the call.

     When the source file is compiled with `_FILE_OFFSET_BITS == 64' the
     `pwrite' function is in fact `pwrite64' and the type `off_t' has
     64 bits which makes it possible to handle files up to 2^63 bytes
     in length.

     The return value of `pwrite' describes the number of written bytes.
     In the error case it returns -1 like `write' does and the error
     codes are also the same.  Only there are a few more error codes:
    `EINVAL'
          The value given for OFFSET is negative and therefore illegal.

    `ESPIPE'
          The file descriptor FILEDES is associate with a pipe or a
          FIFO and this device does not allow positioning of the file
          pointer.

     The function is an extension defined in the Unix Single
     Specification version 2.

 - Function: ssize_t pwrite64 (int FILEDES, const void *BUFFER, size_t
          SIZE, off64_t OFFSET)
     This function is similar to the `pwrite' function.  The difference
     is that the OFFSET parameter is of type `off64_t' instead of
     `off_t' which makes it possible on 32 bits machines to address
     files larger than 2^31 bytes and up to 2^63 bytes.  The file
     descriptor `filedes' must be opened using `open64' since otherwise
     the large offsets possible with `off64_t' will lead to errors with
     a descriptor in small file mode.

     When the source file is compiled using `_FILE_OFFSET_BITS == 64'
     on a 32 bits machine this function is actually available under the
     name `pwrite' and so transparently replaces the 32 bits interface.


File: libc.info,  Node: File Position Primitive,  Next: Descriptors and Streams,  Prev: I/O Primitives,  Up: Low-Level I/O

Setting the File Position of a Descriptor
=========================================

   Just as you can set the file position of a stream with `fseek', you
can set the file position of a descriptor with `lseek'.  This specifies
the position in the file for the next `read' or `write' operation.
*Note File Positioning::, for more information on the file position and
what it means.

   To read the current file position value from a descriptor, use
`lseek (DESC, 0, SEEK_CUR)'.

 - Function: off_t lseek (int FILEDES, off_t OFFSET, int WHENCE)
     The `lseek' function is used to change the file position of the
     file with descriptor FILEDES.

     The WHENCE argument specifies how the OFFSET should be interpreted
     in the same way as for the `fseek' function, and must be one of
     the symbolic constants `SEEK_SET', `SEEK_CUR', or `SEEK_END'.

    `SEEK_SET'
          Specifies that WHENCE is a count of characters from the
          beginning of the file.

    `SEEK_CUR'
          Specifies that WHENCE is a count of characters from the
          current file position.  This count may be positive or
          negative.

    `SEEK_END'
          Specifies that 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.

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

     If you want to append to the file, setting the file position to the
     current end of file with `SEEK_END' is not sufficient.  Another
     process may write more data after you seek but before you write,
     extending the file so the position you write onto clobbers their
     data.  Instead, use the `O_APPEND' operating mode; *note Operating
     Modes::..

     You can set the file position past the current end of the file.
     This does not by itself make the file longer; `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.  Extending the file in
     this way can create a "hole": the blocks of zeros are not actually
     allocated on disk, so the file takes up less space than it appears
     so; it is then called a "sparse file".

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

    `EBADF'
          The FILEDES is not a valid file descriptor.

    `EINVAL'
          The WHENCE argument value is not valid, or the resulting file
          offset is not valid.  A file offset is invalid.

    `ESPIPE'
          The FILEDES corresponds to an object that cannot be
          positioned, such as a pipe, FIFO or terminal device.
          (POSIX.1 specifies this error only for pipes and FIFOs, but
          in the GNU system, you always get `ESPIPE' if the object is
          not seekable.)

     When the source file is compiled with `_FILE_OFFSET_BITS == 64' the
     `lseek' function is in fact `lseek64' and the type `off_t' has 64
     bits which makes it possible to handle files up to 2^63 bytes in
     length.

     This function is a cancelation point in multi-threaded programs.
     This is a problem if the thread allocates some resources (like
     memory, file descriptors, semaphores or whatever) at the time
     `lseek' is called.  If the thread gets canceled these resources
     stay allocated until the program ends.  To avoid this calls to
     `lseek' should be protected using cancelation handlers.

     The `lseek' function is the underlying primitive for the `fseek',
     `fseeko', `ftell', `ftello' and `rewind' functions, which operate
     on streams instead of file descriptors.

 - Function: off64_t lseek64 (int FILEDES, off64_t OFFSET, int WHENCE)
     This function is similar to the `lseek' function.  The difference
     is that the OFFSET parameter is of type `off64_t' instead of
     `off_t' which makes it possible on 32 bits machines to address
     files larger than 2^31 bytes and up to 2^63 bytes.  The file
     descriptor `filedes' must be opened using `open64' since otherwise
     the large offsets possible with `off64_t' will lead to errors with
     a descriptor in small file mode.

     When the source file is compiled with `_FILE_OFFSET_BITS == 64' on
     a 32 bits machine this function is actually available under the
     name `lseek' and so transparently replaces the 32 bits interface.

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

     {
       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);
     }

will read the first four characters of the 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,

     {
       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);
     }

will read four characters starting with the 1024'th character of `foo',
and then four more characters starting with the 1028'th character.

 - Data Type: off_t
     This is an arithmetic data type used to represent file sizes.  In
     the GNU system, this is equivalent to `fpos_t' or `long int'.

     If the source is compiled with `_FILE_OFFSET_BITS == 64' this type
     is transparently replaced by `off64_t'.

 - Data Type: off64_t
     This type is used similar to `off_t'.  The difference is that even
     on 32 bits machines, where the `off_t' type would have 32 bits,
     `off64_t' has 64 bits and so is able to address files up to 2^63
     bytes in length.

     When compiling with `_FILE_OFFSET_BITS == 64' this type is
     available under the name `off_t'.

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

`L_SET'
     An alias for `SEEK_SET'.

`L_INCR'
     An alias for `SEEK_CUR'.

`L_XTND'
     An alias for `SEEK_END'.


File: libc.info,  Node: Descriptors and Streams,  Next: Stream/Descriptor Precautions,  Prev: File Position Primitive,  Up: Low-Level I/O

Descriptors and Streams
=======================

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

 - Function: FILE * fdopen (int FILEDES, const char *OPENTYPE)
     The `fdopen' function returns a new stream for the file descriptor
     FILEDES.

     The OPENTYPE argument is interpreted in the same way as for the
     `fopen' function (*note Opening Streams::.), except that the `b'
     option is not permitted; this is because GNU makes no distinction
     between text and binary files.  Also, `"w"' and `"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 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 OPENTYPE
     argument), a null pointer is returned instead.

     In some other systems, `fdopen' may fail to detect that the modes
     for file descriptor do not permit the access specified by
     `opentype'.  The GNU C library always checks for this.

   For an example showing the use of the `fdopen' function, see *Note
Creating a Pipe::.

 - Function: int fileno (FILE *STREAM)
     This function returns the file descriptor associated with the
     stream STREAM.  If an error is detected (for example, if the STREAM
     is not valid) or if STREAM does not do I/O to a file, `fileno'
     returns -1.

   There are also symbolic constants defined in `unistd.h' for the file
descriptors belonging to the standard streams `stdin', `stdout', and
`stderr'; see *Note Standard Streams::.

`STDIN_FILENO'
     This macro has value `0', which is the file descriptor for
     standard input.

`STDOUT_FILENO'
     This macro has value `1', which is the file descriptor for
     standard output.

`STDERR_FILENO'
     This macro has value `2', which is the file descriptor for
     standard error output.


File: libc.info,  Node: Stream/Descriptor Precautions,  Next: Scatter-Gather,  Prev: Descriptors and Streams,  Up: Low-Level I/O

Dangers of Mixing Streams and Descriptors
=========================================

   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: "linked" channels that share a single file
position value, and "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 `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.


File: libc.info,  Node: Linked Channels,  Next: Independent Channels,  Up: Stream/Descriptor Precautions

Linked Channels
---------------

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

   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 "clean up" the stream that you have been using.  *Note
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.


File: libc.info,  Node: Independent Channels,  Next: Cleaning Streams,  Prev: Linked Channels,  Up: Stream/Descriptor Precautions

Independent Channels
--------------------

   When you open channels (streams or descriptors) separately on a
seekable file, each channel has its own file position.  These are called
"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:

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

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

   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.  You cannot reliably set their file positions to the
new end of file before writing, because the file can always be extended
by another process between when you set the file position and when you
write the data.  Instead, 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.

   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 *Note Linked Channels::.


File: libc.info,  Node: Cleaning Streams,  Prev: Independent Channels,  Up: Stream/Descriptor Precautions

Cleaning Streams
----------------

   On the GNU system, you can clean up any stream with `fclean':

 - Function: int fclean (FILE *STREAM)
     Clean up the stream STREAM so that its buffer is empty.  If STREAM
     is doing output, force it out.  If STREAM is doing input, give the
     data in the buffer back to the system, arranging to reread it.

   On other systems, you can use `fflush' to clean a stream in most
cases.

   You can skip the `fclean' or `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
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, `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 `fclean' avoids both of these problems.

   Closing an output-only stream also does `fflush', so this is a valid
way of cleaning an output stream.  On the GNU system, closing an input
stream does `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.  *Note Terminal
Modes::.


File: libc.info,  Node: Scatter-Gather,  Next: Memory-mapped I/O,  Prev: Stream/Descriptor Precautions,  Up: Low-Level I/O

Fast Scatter-Gather I/O
=======================

   Some applications may need to read or write data to multiple buffers,
which are seperated in memory.  Although this can be done easily enough
with multiple calls to `read' and `write', it is inefficent because
there is overhead associated with each kernel call.

   Instead, many platforms provide special high-speed primitives to
perform these "scatter-gather" operations in a single kernel call.  The
GNU C library will provide an emulation on any system that lacks these
primitives, so they are not a portability threat.  They are defined in
`sys/uio.h'.

   These functions are controlled with arrays of `iovec' structures,
which describe the location and size of each buffer.

 - Data Type: struct iovec
     The `iovec' structure describes a buffer. It contains two fields:

    `void *iov_base'
          Contains the address of a buffer.

    `size_t iov_len'
          Contains the length of the buffer.


 - Function: ssize_t readv (int FILEDES, const struct iovec *VECTOR,
          int COUNT)
     The `readv' function reads data from FILEDES and scatters it into
     the buffers described in VECTOR, which is taken to be COUNT
     structures long.  As each buffer is filled, data is sent to the
     next.

     Note that `readv' is not guaranteed to fill all the buffers.  It
     may stop at any point, for the same reasons `read' would.

     The return value is a count of bytes (*not* buffers) read, 0
     indicating end-of-file, or -1 indicating an error.  The possible
     errors are the same as in `read'.


 - Function: ssize_t writev (int FILEDES, const struct iovec *VECTOR,
          int COUNT)
     The `writev' function gathers data from the buffers described in
     VECTOR, which is taken to be COUNT structures long, and writes
     them to `filedes'.  As each buffer is written, it moves on to the
     next.

     Like `readv', `writev' may stop midstream under the same
     conditions `write' would.

     The return value is a count of bytes written, or -1 indicating an
     error.  The possible errors are the same as in `write'.


   Note that if the buffers are small (under about 1kB), high-level
streams may be easier to use than these functions.  However, `readv' and
`writev' are more efficient when the individual buffers themselves (as
opposed to the total output), are large.  In that case, a high-level
stream would not be able to cache the data effectively.


File: libc.info,  Node: Memory-mapped I/O,  Next: Waiting for I/O,  Prev: Scatter-Gather,  Up: Low-Level I/O

Memory-mapped I/O
=================

   On modern operating systems, it is possible to "mmap" (pronounced
"em-map") a file to a region of memory.  When this is done, the file can
be accessed just like an array in the program.

   This is more efficent than `read' or `write', as only regions of the
file a program actually accesses are loaded.  Accesses to
not-yet-loaded parts of the mmapped region are handled in the same way
as swapped out pages.

   Since mmapped pages can be stored back to their file when physical
memory is low, it is possible to mmap files orders of magnitude larger
than both the physical memory *and* swap space.  The only limit is
address space.  The theoretical limit is 4GB on a 32-bit machine -
however, the actual limit will be smaller since some areas will be
reserved for other purposes.

   Memory mapping only works on entire pages of memory.  Thus, addresses
for mapping must be page-aligned, and length values will be rounded up.
To determine the size of a page the machine uses one should use

     size_t page_size = (size_t) sysconf (_SC_PAGESIZE);

   These functions are declared in `sys/mman.h'.

 - Function: void * mmap (void *ADDRESS, size_t LENGTH,int PROTECT, int
          FLAGS, int FILEDES, off_t OFFSET)
     The `mmap' function creates a new mapping, connected to bytes
     (OFFSET) to (OFFSET + LENGTH) in the file open on FILEDES.

     ADDRESS gives a preferred starting address for the mapping.
     `NULL' expresses no preference. Any previous mapping at that
     address is automatically removed. The address you give may still be
     changed, unless you use the `MAP_FIXED' flag.

     PROTECT contains flags that control what kind of access is
     permitted.  They include `PROT_READ', `PROT_WRITE', and
     `PROT_EXEC', which permit reading, writing, and execution,
     respectively.  Inappropriate access will cause a segfault (*note
     Program Error Signals::.).

     Note that most hardware designs cannot support write permission
     without read permission, and many do not distinguish read and
     execute permission.  Thus, you may recieve wider permissions than
     you ask for, and mappings of write-only files may be denied even
     if you do not use `PROT_READ'.

     FLAGS contains flags that control the nature of the map.  One of
     `MAP_SHARED' or `MAP_PRIVATE' must be specified.

     They include:

    `MAP_PRIVATE'
          This specifies that writes to the region should never be
          written back to the attached file.  Instead, a copy is made
          for the process, and the region will be swapped normally if
          memory runs low.  No other process will see the changes.

          Since private mappings effectively revert to ordinary memory
          when written to, you must have enough virtual memory for a
          copy of the entire mmapped region if you use this mode with
          `PROT_WRITE'.

    `MAP_SHARED'
          This specifies that writes to the region will be written back
          to the file.  Changes made will be shared immediately with
          other processes mmaping the same file.

          Note that actual writing may take place at any time.  You
          need to use `msync', described below, if it is important that
          other processes using conventional I/O get a consistent view
          of the file.

    `MAP_FIXED'
          This forces the system to use the exact mapping address
          specified in ADDRESS and fail if it can't.

    `MAP_ANONYMOUS'
    `MAP_ANON'
          This flag tells the system to create an anonymous mapping,
          not connected to a file.  FILEDES and OFF are ignored, and
          the region is initialized with zeros.

          Anonymous maps are used as the basic primitive to extend the
          heap on some systems.  They are also useful to share data
          between multiple tasks without creating a file.

          On some systems using private anonymous mmaps is more
          efficent than using `malloc' for large blocks.  This is not
          an issue with the GNU C library, as the included `malloc'
          automatically uses `mmap' where appropriate.

     `mmap' returns the address of the new mapping, or -1 for an error.

     Possible errors include:

    `EINVAL'
          Either ADDRESS was unusable, or inconsistent FLAGS were given.

    `EACCES'
          FILEDES was not open for the type of access specified in
          PROTECT.

    `ENOMEM'
          Either there is not enough memory for the operation, or the
          process is out of address space.

    `ENODEV'
          This file is of a type that doesn't support mapping.

    `ENOEXEC'
          The file is on a filesystem that doesn't support mapping.


 - Function: int munmap (void *ADDR, size_t LENGTH)
     `munmap' removes any memory maps from (ADDR) to (ADDR + LENGTH).
     LENGTH should be the length of the mapping.

     It is safe to un-map multiple mappings in one command, or include
     unmapped space in the range.  It is also possible to unmap only
     part of an existing mapping, however only entire pages can be
     removed.  If LENGTH is not an even number of pages, it will be
     rounded up.

     It returns 0 for success and -1 for an error.

     One error is possible:

    `EINVAL'
          The memory range given was outside the user mmap range, or
          wasn't page aligned.


 - Function: int msync (void *ADDRESS, size_t LENGTH, int FLAGS)
     When using shared mappings, the kernel can write the file at any
     time before the mapping is removed.  To be certain data has
     actually been written to the file and will be accessable to
     non-memory-mapped I/O, it is neccessary to use this function.

     It operates on the region ADDRESS to (ADDRESS + LENGTH).  It may
     be used on part of a mapping or multiple mappings, however the
     region given should not contain any unmapped space.

     FLAGS can contain some options:

    `MS_SYNC'
          This flag makes sure the data is actually written *to disk*.
          Normally `msync' only makes sure that accesses to a file with
          conventional I/O reflect the recent changes.

    `MS_ASYNC'
          This tells `msync' to begin the synchronization, but not to
          wait for it to complete.

     `msync' returns 0 for success and -1 for error.  Errors include:

    `EINVAL'
          An invalid region was given, or the FLAGS were invalid.

    `EFAULT'
          There is no existing mapping in at least part of the given
          region.


 - Function: void * mremap (void *ADDRESS, size_t LENGTH, size_t
          NEW_LENGTH, int FLAG)
     This function can be used to change the size of an existing memory
     area. ADDRESS and LENGTH must cover a region entirely mapped in
     the same `mmap' statement. A new mapping with the same
     characteristics will be returned, but a with the length NEW_LENGTH
     instead.

     One option is possible, `MREMAP_MAYMOVE'. If it is given in FLAGS,
     the system may remove the existing mapping and create a new one of
     the desired length in another location.

     The address of the resulting mapping is returned, or -1. Possible
     error codes include:

     This function is only available on a few systems.  Except for
     performing optional optimizations one should not rely on this
     function.
    `EFAULT'
          There is no existing mapping in at least part of the original
          region, or the region covers two or more distinct mappings.

    `EINVAL'
          The address given is misaligned or inappropriate.

    `EAGAIN'
          The region has pages locked, and if extended it would exceed
          the process's resource limit for locked pages.  *Note Limits
          on Resources::.

    `ENOMEM'
          The region is private writable, and insufficent virtual
          memory is available to extend it.  Also, this error will
          occur if `MREMAP_MAYMOVE' is not given and the extension
          would collide with another mapped region.


   Not all file descriptors may be mapped.  Sockets, pipes, and most
devices only allow sequential access and do not fit into the mapping
abstraction.  In addition, some regular files may not be mmapable, and
older kernels may not support mapping at all.  Thus, programs using
`mmap' should have a fallback method to use should it fail. *Note Mmap:
(standards)Mmap.


File: libc.info,  Node: Waiting for I/O,  Next: Synchronizing I/O,  Prev: Memory-mapped I/O,  Up: Low-Level I/O

Waiting for Input or Output
===========================

   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 `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 `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 `sys/types.h'.

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

   The file descriptor sets for the `select' function are specified as
`fd_set' objects.  Here is the description of the data type and some
macros for manipulating these objects.

 - Data Type: fd_set
     The `fd_set' data type represents file descriptor sets for the
     `select' function.  It is actually a bit array.

 - Macro: int FD_SETSIZE
     The value of this macro is the maximum number of file descriptors
     that a `fd_set' object can hold information about.  On systems
     with a fixed maximum number, `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 `fd_set'; if you get
     a file descriptor with a value as high as `FD_SETSIZE', you cannot
     put that descriptor into an `fd_set'.

 - Macro: void FD_ZERO (fd_set *SET)
     This macro initializes the file descriptor set SET to be the empty
     set.

 - Macro: void FD_SET (int FILEDES, fd_set *SET)
     This macro adds FILEDES to the file descriptor set SET.

 - Macro: void FD_CLR (int FILEDES, fd_set *SET)
     This macro removes FILEDES from the file descriptor set SET.

 - Macro: int FD_ISSET (int FILEDES, fd_set *SET)
     This macro returns a nonzero value (true) if FILEDES is a member
     of the file descriptor set SET, and zero (false) otherwise.

   Next, here is the description of the `select' function itself.

 - Function: int select (int NFDS, fd_set *READ-FDS, fd_set *WRITE-FDS,
          fd_set *EXCEPT-FDS, struct timeval *TIMEOUT)
     The `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 READ-FDS argument are
     checked to see if they are ready for reading; the WRITE-FDS file
     descriptors are checked to see if they are ready for writing; and
     the 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.

     A file descriptor is considered ready for reading if it is not at
     end of file.  A server socket is considered ready for reading if
     there is a pending connection which can be accepted with `accept';
     *note Accepting Connections::..  A client socket is ready for
     writing when its connection is fully established; *note
     Connecting::..

     "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.
     (*Note Sockets::, for information on urgent messages.)

     The `select' function checks only the first NFDS file descriptors.
     The usual thing is to pass `FD_SETSIZE' as the value of this
     argument.

     The 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 `struct timeval' format; see *Note
     High-Resolution Calendar::.  Specify zero as the time (a `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 `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 DESC has input, use `FD_ISSET (DESC, READ-FDS)' after
     `select' returns.

     If `select' returns because the timeout period expires, it returns
     a value of zero.

     Any signal will cause `select' to return immediately.  So if your
     program uses signals, you can't rely on `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 `EINTR' and
     repeat the `select' with a newly calculated timeout based on the
     current time.  See the example below.  See also *Note Interrupted
     Primitives::.

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

    `EBADF'
          One of the file descriptor sets specified an invalid file
          descriptor.

    `EINTR'
          The operation was interrupted by a signal.  *Note Interrupted
          Primitives::.

    `EINVAL'
          The TIMEOUT argument is invalid; one of the components is
          negative or too large.

   *Portability Note:*  The `select' function is a BSD Unix feature.

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

     #include <stdio.h>
     #include <unistd.h>
     #include <sys/types.h>
     #include <sys/time.h>

     int
     input_timeout (int filedes, unsigned int seconds)
     {
       fd_set set;
       struct timeval timeout;
     
       /* Initialize the file descriptor set. */
       FD_ZERO (&set);
       FD_SET (filedes, &set);
     
       /* Initialize the timeout data structure. */
       timeout.tv_sec = seconds;
       timeout.tv_usec = 0;
     /* `select' returns 0 if timeout, 1 if input available, -1 if error. */
       return TEMP_FAILURE_RETRY (select (FD_SETSIZE,
                                          &set, NULL, NULL,
                                          &timeout));
     }

     int
     main (void)
     {
       fprintf (stderr, "select returned %d.\n",
                input_timeout (STDIN_FILENO, 5));
       return 0;
     }

   There is another example showing the use of `select' to multiplex
input from multiple sockets in *Note Server Example::.

