*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->OpenBSD man pages -> read (2)              



NAME    [Toc]    [Back]

     read, readv, pread, preadv - read input

SYNOPSIS    [Toc]    [Back]

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

     read(int d, void *buf, size_t nbytes);

     pread(int d, void *buf, size_t nbytes, off_t offset);

     #include <sys/types.h>
     #include <sys/uio.h>
     #include <unistd.h>

     readv(int d, const struct iovec *iov, int iovcnt);

     preadv(int d, const struct iovec  *iov,  int  iovcnt,  off_t

DESCRIPTION    [Toc]    [Back]

     read()  attempts to read nbytes of data from the object referenced by the
     descriptor d into the buffer pointed  to  by  buf.   readv()
performs the
     same  action,  but  scatters  the input data into the iovcnt
buffers specified
 by the members of the iov array: iov[0],  iov[1],  ...,
     pread()  and  preadv()  perform the same functions, but read
from the specified
 position in the file without modifying the file  pointer.

     For readv() and preadv(), the iovec structure is defined as:

           struct iovec {
                   void *iov_base;
                   size_t 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 d (see lseek(2)).  Upon return
from read(),
     the pointer is incremented by the number of  bytes  actually

     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(), readv(), pread(), and
preadv() 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
     but in no other case.

     Note  that  readv()  and  preadv() will fail if the value of
iovcnt exceeds
     the constant IOV_MAX.

RETURN VALUES    [Toc]    [Back]

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

ERRORS    [Toc]    [Back]

     read(), readv(), pread(), and preadv() will succeed unless:

     [EBADF]       d is not a valid  file  or  socket  descriptor
open for reading.

     [EFAULT]       buf  points  outside  the  allocated  address

     [EIO]         An I/O error occurred while reading  from  the
file system,
                   or  the  process  is  a member of a background
process attempting
 to read from its controlling terminal, the
process is
                   ignoring or blocking the SIGTTIN signal or the
                   group is orphaned.

     [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, read() and pread() may return the following error:

     [EINVAL]      nbytes was larger than SSIZE_MAX.

     Also,  readv()  and preadv() may return one of the following

     [EINVAL]      iovcnt was less than or equal to 0, or greater

     [EINVAL]      The sum of the iov_len values in the iov array
                   an ssize_t.

     [EFAULT]      Part of the iov points outside  the  process's
allocated address

SEE ALSO    [Toc]    [Back]

     dup(2),  fcntl(2),  open(2),  pipe(2),  poll(2),  select(2),

STANDARDS    [Toc]    [Back]

     The  read()  function  conforms  to  IEEE  Std   1003.1-1990
(``POSIX'').  The
     readv()  and pread() functions conform to X/Open Portability
Guide Issue
     4.2 (``XPG4.2'').

HISTORY    [Toc]    [Back]

     The preadv() function first appeared in  OpenBSD  2.7.   The
pread() function
 appeared in AT&T System V.4 UNIX.  The readv() function
call appeared
 in 4.2BSD.  The read() function call appeared in Version 2 AT&T

CAVEATS    [Toc]    [Back]

     Error checks should explicitly test for -1.  Code such as

             while ((nr = read(fd, buf, sizeof(buf))) > 0)

     is  not  maximally  portable,  as  some  platforms allow for
nbytes to range
     between SSIZE_MAX and SIZE_MAX - 2, in which case the return
value of an
     error-free  read()  may appear as a negative number distinct
from -1.
     Proper loops should use

             while ((nr = read(fd, buf, sizeof(buf))) != -1 && nr
!= 0)

OpenBSD      3.6                           July      28,     1998
[ Back ]
 Similar pages
Name OS Title
read HP-UX read a line from standard input
read IRIX read a line from standard input
line HP-UX read one line from user input
getwchar Linux read a wide character from standard input
tee Linux read from standard input and write to standard output and files
XmImUnsetFocus HP-UX An input manager function that notifies an input method that a widget has lost input focus
XmImSetFocusValues HP-UX An input manager function that notifies an input manager that a widget has received input focus and updates th
XmImVaSetFocusValues HP-UX An input manager function that notifies an input manager that a widget has received input focus and updates th
tis_read_unlock Tru64 Unlocks a read-write lock that was acquired for read access
tis_read_lock Tru64 Acquires a read-write lock for read access
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service