(libc.info.gz) Scatter-Gather

Info Catalog

(libc.info.gz) Stream/Descriptor Precautions

(libc.info.gz) Low-Level I/O

(libc.info.gz) Memory-mapped I/O

 
 13.6 Fast Scatter-Gather I/O
 ============================
 
 Some applications may need to read or write data to multiple buffers,
 which are separated in memory.  Although this can be done easily enough
 with multiple calls to `read' and `write', it is inefficient 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.
 

Info Catalog

(libc.info.gz) Stream/Descriptor Precautions

(libc.info.gz) Low-Level I/O

(libc.info.gz) Memory-mapped I/O