[Previous]
[Contents]
[Next]

read(), readv()

read bytes from a file

Synopsis:

#include <unistd.h>
#include <sys/uio.h>
ssize_t read( int fildes,
              void *buf,
              size_t nbyte );

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

Description:

The read() function attempts to read nbyte bytes from the file associated with the open file descriptor, fildes, into the buffer pointed to by buf.

If nbyte is zero, read() returns zero and has no other effect.

On a regular file or other file capable of seeking, read() starts at a position in the file given by the file offset associated with fildes. Before successfully returning from read(), the file offset is incremented by the number of bytes actually read.

The readv() function performs the same action as read(), but places the data into the iovcnt buffers specified by the members of the iov array: iov[0], iov[1], ..., iov[iovcnt-1].

For readv(), the iovec structure contains the following members:

iov_base
The base address of a memory area where data should be placed.
iov_len
The length of the memory area.

readv() always fills one buffer completely before proceeding to the next. The maximum number of entries in the iov array is UIO_MAXIOV.


Note: The read() call ignores advisory locks that may have been set by the fcntl(), lock(), or locking() functions.

On a file not capable of seeking, read() starts at the current position.

When read() returns successfully, its return value is the number of bytes actually read and placed in the buffer. This number will never be greater than nbyte, although it may be less than nbyte for one of the following reasons:

If read() is interrupted by a signal before it reads any data, it returns -1, and errno is set to EINTR. However, if read() is interrupted by a signal after it has successfully read some data, it will return the number of bytes read.

No data is transferred past the current end-of-file. If the starting position is at or after the end-of-file, read() returns zero. If the file is a device special file, the result of subsequent calls to read() will work, based on the then current state of the device (that is, the end of file is transitory).

If the value of nbyte is greater than INT_MAX, read() returns -1, and sets errno to EINVAL. See <limits.h>.

When attempting to read from an empty pipe or FIFO:

  1. If no process has the pipe open for writing, read() returns 0 to indicate end-of-file.
  2. If a process has the pipe open for writing, and O_NONBLOCK is set, read() returns -1 and errno is set to EAGAIN.
  3. If a process has the pipe open for writing and O_NONBLOCK is clear, read() blocks until some data is written, or the pipe is closed by all processes that had opened it for writing.

When attempting to read from a file (other than a pipe or FIFO) that support nonblocking reads and has no data currently available:

  1. If O_NONBLOCK is set, read() returns -1 and errno is set to EAGAIN.
  2. If O_NONBLOCK is clear, read blocks until some data is available.
  3. The O_NONBLOCK flag has no effect if some data is available.

If read() is called on a portion of a file prior to the end-of-file that hasn't been written, it returns bytes with the value zero.

If read() succeeds, the st_atime field of the file is marked for update.

When read() is called and the O_CACHE flag (a QNX extension) is set, internal file system caching behavior may be modified. See the open() documentation for a discussion of the effect of O_CACHE on I/O calls.

Returns:

The number of bytes actually read. If not successful, -1 is returned, errno is set to indicate the error, and the content of the buffer pointed to by buf is indeterminate.

Errors:

If any of the following conditions occurs, the read() function returns -1 and sets errno to the corresponding value:

EAGAIN
The O_NONBLOCK flag is set for the file descriptor and the process would be delayed in the read operation.
EBADF
The file descriptor, fildes, isn't a valid file descriptor open for reading.
EINTR
The read operation was interrupted by a signal, and either no data was transferred, or the resource manager responsible for that file doesn't report partial transfers.
EINVAL
iovcnt was less than or equal to 0, or greater than UIO_MAXIOV.
EIO
A physical I/O error occurred (for example, a bad block on a disk). The precise meaning is device-dependent.

Examples:

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

void main()
  {
    int  fd;
    int  size_read;
    char buffer[80];

    /* Open a file for input                  */
    fd = open( "myfile.dat", O_RDONLY );

    /* Read the text                          */
    size_read = read( fd, buffer,
                      sizeof( buffer ) );

    /* Test for error                          */
    if( size_read == -1 ) {
      perror( "Error reading myfile.dat" );
    }

    /* Close the file                          */
    close( fd );
  }

Classification:

POSIX 1003.1

Safety:
Interrupt handler No
Signal handler Yes, but modifies errno
Thread Yes

See also:

block_read(), close(), creat(), dup(), dup2(), errno, fcntl(), lseek(), open(), pipe(), select(), write(), writev()


[Previous]
[Contents]
[Next]