C Programming/POSIX Reference/unistd.h/read

In most modern operating systems, a program that needs to access data from a file stored in a filesystem uses the read system call. The file is identified by the file descriptor that is obtained from a previous call to open. This system call reads data, in bytes as specified by the caller, from the file and stores then into a buffer supplied by the calling process.

The read system call can take three arguments:


 * 1) The file descriptor of the file,
 * 2) the buffer where the read data is to be stored and
 * 3) the number of bytes to be read from the file.

POSIX usage
The read system call interface is standardized by the POSIX specification. Data from a file is read by calling the read function:

The value returned is the number of bytes read (zero indicates end of file) and the file position is advanced by this number. It is not an error if this number is smaller than the number of bytes requested; this may happen for example because fewer bytes are actually available right now (maybe because we were close to end-of-file, or because we are reading from a pipe, or from a terminal), or because the system call was interrupted by a signal.

Alternatively. -1 is returned when an error occurs, in such a case errno is set appropriately and it is left unspecified whether the file position (if any) changes.