4.4BSD/usr/share/man/cat2/read.0

READ(2)                     BSD Programmer's Manual                    READ(2)

NNAAMMEE
     rreeaadd, rreeaaddvv - read input

SSYYNNOOPPSSIISS
     ##iinncclluuddee <<uunniissttdd..hh>>
     ##iinncclluuddee <<ssyyss//ttyyppeess..hh>>
     ##iinncclluuddee <<ssyyss//uuiioo..hh>>

     _s_s_i_z_e___t
     rreeaadd(_i_n_t _d, _v_o_i_d _*_b_u_f, _s_i_z_e___t _n_b_y_t_e_s);

     _i_n_t
     rreeaaddvv(_i_n_t _d, _s_t_r_u_c_t _i_o_v_e_c _*_i_o_v, _i_n_t _i_o_v_c_n_t);

DDEESSCCRRIIPPTTIIOONN
     RReeaadd() attempts to read _n_b_y_t_e_s of data from the object referenced by the
     descriptor _d into the buffer pointed to by _b_u_f. RReeaaddvv() performs the same
     action, but scatters the input data into the _i_o_v_c_n_t buffers specified by
     the members of the _i_o_v array: iov[0], iov[1], ..., iov[iovcnt-1].

     For rreeaaddvv(), the _i_o_v_e_c structure is defined as
           struct iovec {
                   void *iov_base;
                   int iov_len;
           };

     Each _i_o_v_e_c entry specifies the base address and length of an area in mem-
     ory where data should be placed.  RReeaaddvv() will always fill an area com-
     pletely before proceeding to the next.

     On objects capable of seeking, the rreeaadd() starts at a position given by
     the pointer associated with _d (see lseek(2)).  Upon return from rreeaadd(),
     the pointer is incremented by the number of bytes actually read.

     Objects that are not capable of seeking always read from the current po-
     sition.  The value of the pointer associated with such an object is unde-
     fined.

     Upon successful completion, rreeaadd() and rreeaaddvv() return the number of bytes
     actually read and placed in the buffer.  The system guarantees to read
     the number of bytes requested if the descriptor references a normal file
     that has that many bytes left before the end-of-file, but in no other
     case.

RREETTUURRNN VVAALLUUEESS
     If successful, the number of bytes actually read is returned. Upon read-
     ing end-of-file, zero is returned.  Otherwise, a -1 is returned and the
     global variable _e_r_r_n_o is set to indicate the error.

EERRRROORRSS
     RReeaadd() and rreeaaddvv() will succeed unless:

     [EBADF]       _D is not a valid file or socket descriptor open for read-
                   ing.

     [EFAULT]      _B_u_f points outside the allocated address space.

     [EIO]         An I/O error occurred while reading from the file system.

     [EINTR]       A read from a slow device was interrupted before any data
                   arrived by the delivery of a signal.


     [EINVAL]      The pointer associated with _d was negative.

     [EAGAIN]      The file was marked for non-blocking I/O, and no data were
                   ready to be read.

     In addition, rreeaaddvv() may return one of the following errors:

     [EINVAL]      _I_o_v_c_n_t was less than or equal to 0, or greater than 16.

     [EINVAL]      One of the _i_o_v___l_e_n values in the _i_o_v array was negative.

     [EINVAL]      The sum of the _i_o_v___l_e_n values in the _i_o_v array overflowed a
                   32-bit integer.

     [EFAULT]      Part of the _i_o_v points outside the process's allocated ad-
                   dress space.

SSEEEE AALLSSOO
     dup(2),  fcntl(2),  open(2),  pipe(2),  select(2),  socket(2),  socket-
     pair(2)

SSTTAANNDDAARRDDSS
     RReeaadd() is expected to conform to IEEE Std 1003.1-1988 (``POSIX'').

HHIISSTTOORRYY
     The rreeaaddvv() function call appeared in 4.2BSD. A rreeaadd function call ap-
     peared in Version 6 AT&T UNIX.

4th Berkeley Distribution        June 4, 1993                                2