NAME

read – read from file

SYNOPSIS

#include <unistd.h>

ssize_t read( int fildes , void *buf , size_t nbyte );

DESCRIPTION

read() attempts to read nbyte bytes from the file associated with fildes into the buffer pointed to by buf. If nbyte is zero, read() returns zero and has no other results. fildes is an open file descriptor.

On devices capable of seeking, the read() starts at a position in the file given by the file pointer associated with fildes. On return from read() , , the file pointer is incremented by the number of bytes actually read.

Devices that are incapable of seeking always read from the current position. The value of a file pointer associated with such a file is undefined.

On success, read() returns the number of bytes actually read and placed in the buffer; this number may be less than nbyte if the file is associated with a communication line or if the number of bytes left in the file is less than nbyte, or if the file is a pipe or a special file. A value of 0 is returned when an end-of-file has been reached.

read() reads data previously written to a file. If any portion of an ordinary file prior to the end of file has not been written, read() returns the number of bytes read as 0. For example, the lseek() routine allows the file pointer to be set beyond the end of existing data in the file. If additional data is written at this point, subsequent reads in the gap between the previous end of data and newly written data return bytes with a value of 0 until data is written into the gap.

When attempting to read from a regular file with mandatory file/record locking set and there is a write lock owned by another thread on the segment of the file to be read: If O_NDELAY or O_NONBLOCK is set, read() returns -1 and sets errno to EAGAIN. If O_NDELAY and O_NONBLOCK are clear, read() sleeps until the blocking record lock is removed.

When attempting to read from an empty pipe or FIFO: If no thread has the pipe open for writing, read() returns 0 to indicate end-of-file. If some thread has the pipe open for writing and O_NDELAY is set, read() returns 0. If some thread has the pipe open for writing and O_NONBLOCK is set, read() returns -1 and sets errno to EAGAIN. If O_NDELAY and O_NONBLOCK are clear, read() blocks until data is written to the pipe or the pipe is closed by all processes that had opened the pipe for writing.

When attempting to read a file associated with a terminal that has no data currently available: If O_NDELAY is set, read() returns 0. If O_NONBLOCK is set, read() returns -1 and sets errno to EAGAIN. If O_NDELAY and O_NONBLOCK are clear, read() blocks until data become available.

RETURN VALUES

On success a non-negative integer is returned indicating the number of bytes actually read. Otherwise, a -1 is returned and errnorminal that has no data is set to indicate the error.

ERRORS

This function is a member of Unison’s IOLIB family of functions. IOLIB is implemented as a message passing and generalized interface layer. Each Unison I/O server is responsible for its own error reporting.

For an exact list of error codes returned by a particular server, refer to that server’s documentation in the Unison Programmer’s Guide for each specific platform.

Servers may implement these errors codes in response to this function.

read() fails if one or more of the following are true:

EAGAIN

Mandatory file/record locking was set, O_NDELAY or O_NONBLOCK was set, and there was a blocking record lock.

EAGAIN

Total amount of system memory available when reading using raw I/O is temporarily insufficient.

EAGAIN or EWOULDBLOCK

No data is waiting to be read on a file associated with a socket or tty device and O_NONBLOCK was set.

EBADF

fildes is not a valid file descriptor open for reading.

EFAULT

buf points to an illegal address.

SEE ALSO

ioctl(), open(), lseek()