unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-4.1.3)
Page:
Section:
Apropos / Subsearch:
optional field

READ(2V)                                                              READ(2V)



NAME
       read, readv - read input

SYNOPSIS
       int read(fd, buf, nbyte)
       int fd;
       char *buf;
       int nbyte;

       #include <&lt;sys/types.h>&gt;
       #include <&lt;sys/uio.h>&gt;

       int readv(fd, iov, iovcnt)
       int fd;
       struct iovec *iov;
       int iovcnt;

DESCRIPTION
       read()  attempts to read nbyte bytes of data from the object referenced
       by the descriptor fd into the buffer pointed to by buf.   readv()  per-
       forms  the  same action as read(), but scatters the input data into the
       iovcnt  buffers  specified  by  the   members   of   the   iov   array:
       iov[0],iov[1], ..., iov[iovcnt-1].

       If  nbyte is zero, read() takes no action and returns 0.  readv(), how-
       ever, returns -1 and sets the global variable errno (see ERRORS below).

       For readv(), the iovec structure is defined as

              struct iovec {
                   caddr_t   iov_base;
                   int  iov_len;
              };

       Each iovec entry specifies the base address and length of  an  area  in
       memory  where  data should be placed.  readv() will always fill an area
       completely before proceeding to the next.

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

       Objects  that  are  not capable of seeking always read from the current
       position.  The value of the pointer associated with such an  object  is
       undefined.

       Upon  successful  completion,  read()  and readv() 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 nor-
       mal file which has that many bytes left before the EOF (end  of  file),
       but in no other case.

       If  the  process calling read() or readv() receives a signal before any
       data are read, the system call is restarted unless the process  explic-
       itly set the signal to interrupt the call using sigvec() or sigaction()
       (see the discussions of SV_INTERRUPT on sigvec(2) and  SA_INTERRUPT  on
       sigaction(3V)).   If read() or readv() is interrupted by a signal after
       successfully reading some data, it returns the number of bytes read.

       If nbyte is not zero and read() returns 0, then EOF has  been  reached.
       If readv() returns 0, then EOF has been reached.

       A  read()  or readv() from a STREAMS file (see intro(2)) can operate in
       three different modes: "byte-stream" mode,  "message-nondiscard"  mode,
       and "message-discard" mode.  The default is byte-stream mode.  This can
       be changed using the I_SRDOPT ioctl(2) request (see  streamio(4)),  and
       can  be tested with the I_GRDOPT ioctl() request.  In byte-stream mode,
       read() and readv() will retrieve data from the  stream  until  as  many
       bytes as were requested are transferred, or until there is no more data
       to be retrieved.  Byte-stream mode ignores message boundaries.

       In STREAMS message-nondiscard mode, read() and  readv()  will  retrieve
       data  until as many bytes as were requested are transferred, or until a
       message boundary is  reached.   If  the  read()  or  readv()  does  not
       retrieve  all the data in a message, the remaining data are left on the
       stream, and can be retrieved by the next read(), readv(), or  getmsg(2)
       call.   Message-discard mode also retrieves data until as many bytes as
       were requested are transferred, or a message boundary is reached.  How-
       ever,  unread  data  remaining in a message after the read() or readv()
       returns are discarded, and are not available for a  subsequent  read(),
       readv(), or getmsg().

       When  attempting  to  read  from  a descriptor associated with an empty
       pipe, socket, FIFO, or stream:

       o  If the object the  descriptor  is  associated  with  is  marked  for
          4.2BSD-style non-blocking I/O (with the FIONBIO ioctl() request or a
          call to fcntl(2V) using the FNDELAY flag from  <&lt;sys/file.h>&gt;  or  the
          O_NDELAY  flag  from  <&lt;fcntl.h>&gt; in the 4.2BSD environment), the read
          will return -1 and errno will be set to EWOULDBLOCK.

       o  If the descriptor is marked  for  System  V-style  non-blocking  I/O
          (using fcntl() with the FNBIO flag from <&lt;sys/file.h>&gt; or the O_NDELAY
          flag from <&lt;fcntl.h>&gt; in the System V environment), and does not refer
          to  a  stream, the read will return 0.  Note: this is indistinguish-
          able from EOF.

       o  If the descriptor is marked for POSIX-style non-blocking I/O  (using
          fcntl()  with  the  O_NONBLOCK  flag from <&lt;fcntl.h>&gt;) and refers to a
          stream, the read will return -1 and errno will be set to EAGAIN.

       o  If neither the descriptor nor the object it refers to are marked for
          non-blocking  I/O, the read will block until data is available to be
          read or the object has been "disconnected".  A pipe or FIFO is "dis-
          connected" when no process has the object open for writing; a socket
          that was connected is "disconnected" when the connection is  broken;
          a  stream  is  "disconnected"  when  a  hangup condition occurs (for
          instance, when carrier drops on a terminal).

       If the descriptor or the object is marked  for  non-blocking  I/O,  and
       less  data  are  available than are requested by the read() or readv(),
       only the data that are available are returned, and the count  indicates
       how many bytes of data were actually read.

       When  reading  from  a  STREAMS file, handling of zero-byte messages is
       determined by the current read  mode  setting.   In  byte-stream  mode,
       read()  and  readv()  accept data until as many bytes as were requested
       are transferred, or until there is no more data to  read,  or  until  a
       zero-byte message block is encountered.  read() and readv() then return
       the number of bytes read, and places the zero-byte message back on  the
       stream  to  be  retrieved by the next read(), readv(), or getmsg().  In
       the two other modes, a zero-byte message returns a value of 0  and  the
       message  is  removed from the stream.  When a zero-byte message is read
       as the first message on a stream, a value of 0 is  returned  regardless
       of the read mode.

       A read() or readv() from a STREAMS file can only process data messages.
       It cannot process any type of protocol message and will fail if a  pro-
       tocol message is encountered at the streamhead.

       Upon  successful  completion,  read()  and  readv() mark for update the
       st_atime field of the file.

RETURN VALUES
       read() and readv() return the number of bytes actually read on success.
       On failure, they return -1 and set errno to indicate the error.

ERRORS
       EAGAIN              The descriptor referred to a stream, was marked for
                           System V-style non-blocking I/O, and no  data  were
                           ready to be read.

       EBADF               d is not a valid file descriptor open for reading.

       EBADMSG             The message waiting to be read on a stream is not a
                           data message.

       EFAULT              buf points outside the allocated address space.

       EINTR               The process performing a read from  a  slow  device
                           received  a signal before any data arrived, and the
                           signal was set to interrupt the system call.

       EINVAL              The stream is linked below a multiplexor.

                           The pointer associated with fd was negative.

       EIO                 An I/O error occurred while reading from or writing
                           to the file system.

                           The  calling  process  is  in  a background process
                           group and is attempting to read from  its  control-
                           ling terminal and the process is ignoring or block-
                           ing SIGTTIN.

                           The calling process  is  in  a  background  process
                           group  and  is attempting to read from its control-
                           ling terminal and the process is orphaned.

       EISDIR              fd refers to a directory which is on a file  system
                           mounted using the NFS.

       EWOULDBLOCK         The  file  was marked for 4.2BSD-style non-blocking
                           I/O, and no data were ready to be read.

       In addition to the above, readv() may set errno to:

       EFAULT              Part of iov points outside the process's  allocated
                           address space.

       EINVAL              iovcnt was less than or equal to 0, or greater than
                           16.

                           One of the iov_len values in the iov array was neg-
                           ative.

                           The  sum  of  the  iov_len  values in the iov array
                           overflowed a 32-bit integer.

       A read() or readv() from a STREAMS file will also fail if an error mes-
       sage is received at the stream head.  In this case, errno is set to the
       value returned in the error message.  If a hangup occurs on the  stream
       being  read,  read() will continue to operate normally until the stream
       head read queue is empty.  Thereafter, it will return 0.

SEE ALSO
       dup(2V), fcntl(2V), getmsg(2), intro(2), ioctl(2), lseek(2V), open(2V),
       pipe(2V), select(2), socket(2), socketpair(2), streamio(4), termio(4)



                                21 January 1990                       READ(2V)