home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 8 / FreshFishVol8-CD1.bin / gnu / man / cat2 / read.0 < prev    next >
Text File  |  1993-12-07  |  4KB  |  133 lines
  1.  
  2. READ(2)                    UNIX Programmer's Manual                    READ(2)
  3.  
  4. NNAAMMEE
  5.      rreeaadd, rreeaaddvv - read input
  6.  
  7. SSYYNNOOPPSSIISS
  8.      ##iinncclluuddee <<uunniissttdd..hh>>
  9.      ##iinncclluuddee <<ssyyss//ttyyppeess..hh>>
  10.      ##iinncclluuddee <<ssyyss//uuiioo..hh>>
  11.  
  12.      _s_s_i_z_e___t
  13.      rreeaadd(_i_n_t _d, _c_h_a_r _*_b_u_f, _s_i_z_e___t _n_b_y_t_e_s)
  14.  
  15.      _i_n_t
  16.      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)
  17.  
  18. DDEESSCCRRIIPPTTIIOONN
  19.      RReeaadd() attempts to read _n_b_y_t_e_s of data from the object referenced by the
  20.      descriptor _d into the buffer pointed to by _b_u_f. RReeaaddvv() performs the same
  21.      action, but scatters the input data into the _i_o_v_c_n_t buffers specified by
  22.      the members of the _i_o_v array: iov[0], iov[1], ..., iov[iovcnt-1].
  23.  
  24.      For rreeaaddvv(), the _i_o_v_e_c structure is defined as
  25.            struct iovec {
  26.                    caddr_t iov_base;
  27.                    int     iov_len;
  28.            };
  29.  
  30.      Each _i_o_v_e_c entry specifies the base address and length of an area in mem­
  31.      ory where data should be placed.  RReeaaddvv() will always fill an area com­
  32.      pletely before proceeding to the next.
  33.  
  34.      On objects capable of seeking, the rreeaadd() starts at a position given by
  35.      the pointer associated with _d (see lseek(2)).  Upon return from rreeaadd(),
  36.      the pointer is incremented by the number of bytes actually read.
  37.  
  38.      Objects that are not capable of seeking always read from the current po­
  39.      sition.  The value of the pointer associated with such an object is unde­
  40.      fined.
  41.  
  42.      Upon successful completion, rreeaadd() and rreeaaddvv() return the number of bytes
  43.      actually read and placed in the buffer.  The system guarantees to read
  44.      the number of bytes requested if the descriptor references a normal file
  45.      that has that many bytes left before the end­of­file, but in no other
  46.      case.
  47.  
  48. RREETTUURRNN VVAALLUUEESS
  49.      If successful, the number of bytes actually read is returned. Upon read­
  50.      ing end­of­file, zero is returned.  Otherwise, a ­1 is returned and the
  51.      global variable _e_r_r_n_o is set to indicate the error.
  52.  
  53. EERRRROORRSS
  54.      RReeaadd() and rreeaaddvv() will succeed unless:
  55.  
  56.      [EBADF]       _D is not a valid file or socket descriptor open for read­
  57.                    ing.
  58.  
  59.      [EFAULT]      _B_u_f points outside the allocated address space.
  60.  
  61.      [EIO]         An I/O error occurred while reading from the file system.
  62.  
  63.      [EINTR]       A read from a slow device was interrupted before any data
  64.  
  65.  
  66.                    arrived by the delivery of a signal.
  67.  
  68.      [EINVAL]      The pointer associated with _d was negative.
  69.  
  70.      [EWOULDBLOCK]
  71.                    The file was marked for non­blocking I/O, and no data were
  72.                    ready to be read.
  73.  
  74.      In addition, rreeaaddvv() may return one of the following errors:
  75.  
  76.      [EINVAL]      _I_o_v_c_n_t was less than or equal to 0, or greater than 16.
  77.  
  78.      [EINVAL]      One of the _i_o_v___l_e_n values in the _i_o_v array was negative.
  79.  
  80.      [EINVAL]      The sum of the _i_o_v___l_e_n values in the _i_o_v array overflowed a
  81.                    32­bit integer.
  82.  
  83.      [EFAULT]      Part of the _i_o_v points outside the process's allocated ad­
  84.                    dress space.
  85.  
  86. SSEEEE AALLSSOO
  87.      dup(2),  fcntl(2),  open(2),  pipe(2),  select(2),  socket(2),  socket­
  88.      pair(2)
  89.  
  90. SSTTAANNDDAARRDDSS
  91.      RReeaadd() is expected to conform to IEEE Std 1003.1­1988 (``POSIX'').
  92.  
  93. HHIISSTTOORRYY
  94.      The rreeaaddvv() function call appeared in 4.2BSD. A rreeaadd function call ap­
  95.      peared in Version 6 AT&T UNIX.
  96.  
  97. 4th Berkeley Distribution       March 10, 1991                               2
  98.  
  99.  
  100.  
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.