read - read bytes from file

Syntax	#include <unistd.h> ssize_t read(int fildes, void *buf, size_t nbyte);
Description	read() reads nbyte bytes from the file associated with the open file descriptor, fildes, into the buffer pointed to by buf. fildes is a file descriptor returned by a call to creat(), open(), dup(), fcntl() or pipe(). If nbyte is 0, read() will return only the value 0 and buf. On files that support seeking (for example, a regular file), read() starts at a position in the file given by the file offset associated with fildes. The file offset is incremented by the number of bytes actually read. Files that do not support seeking, for example, terminals, always read from the current position. The value of a file offset associated with such a file is undefined. No data transfer will occur past the current end-of-file. If the starting position is at or after the end-of-file, 0 will be returned. The following occurs when attempting to read from an empty pipe or FIFO: If no process has the pipe open for writing, read() will return 0 to indicate end-of-file. If a process has the pipe open for writing and O_NONBLOCK is set, read() will return -1 and set errno to EAGAIN. If a process has the pipe open for writing and O_NONBLOCK is clear, read() will block until some data is written or the pipe is closed by all processes that had the pipe open for writing. The following occurs when attempting to read a file (other than a pipe or FIFO) that supports non-blocking reads and has no data currently available: If O_NONBLOCK is set, read() will return a -1 and set errno to EAGAIN. If O_NONBLOCK is clear, read() will block until some data becomes available. The use of the O_NONBLOCK flag has no effect if there is some data available. The read() function reads data previously written to a file. If any portion of a regular file prior to the end-of-file has not been written, read() returns null bytes. For example, lseek() allows the file offset to be set beyond the end of existing data in the file. If data is later written at this point, subsequent reads in the gap between the previous end of data and the newly written data will return null bytes until data is written into the gap. Upon successful completion, where nbyte is greater than 0, read() will mark for update the st_atime structure component of the file (see sys/stat.h), and return the number of bytes read. This number will never be greater than nbyte. The value returned may be less than nbyte if the number of bytes left in the file is less than nbyte, if the read() request was interrupted by a signal, or if the file is a pipe or FIFO or special file and has fewer than nbyte bytes immediately available for reading. For example, a read() from a file associated with a terminal may return one typed line of data. If a read() is interrupted by a signal before it reads any data, it will return -1 with errno set to EINTR. If a read() is interrupted by a signal after it has successfully read some data, it will return the number of bytes read. If threads are used, then the function affects the process or a thread in the following manner: When an attempt is made to read from an empty pipe or FIFO, the following occurs: If a process has opened the pipe for writing and O_NONBLOCK is not set, read() blocks the calling process until data is written or until the pipe is closed by all processes that have opened it for reading. When an attempt is made to read from a file that is not a pipe or a FIFO that supports non-blocking reads and for which there is no data currently available, the following occurs: If O_NONBLOCK is not set, read() blocks the calling process until data becomes available.
Return val.	Number of bytes actually read
		upon successful completion.
	0	at end-of-file.
	-1	if an error occurs. The contents of the buffer to which buf points are undefined. errno is set to indicate the error.
Errors	read() will fail if:
	EAGAIN	The O_NONBLOCK flag is set for the file descriptor, and the process would be delayed by the read operation.
	Extension
	EAGAIN	The currently available amount of system memory for "raw" I/O is insufficient or there is no data in a terminal device file waiting to be read, and O_NONBLOCK is set or there is no message in a stream waiting to be read, and O_NONBLOCK is set. (End)
	EBADF	fildes is not a valid file descriptor open for reading.
	EFAULT	buf points outside the allocated address space of the process.
	EINTR	The read operation was terminated due to the receipt of a signal, and no data was transferred.
	EINVAL	An attempt was made to read from a stream linked with a multiplexer.
	EIO	A physical I/O error has occurred 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 process group is orphaned.
	ENXIO	A request was made for a non-existent device or the request exceeded the capabilities of the device.
Notes	The number of bytes actually read may be less than the value specified in nbytes if the end of the line is reached first (only for text files) and at end-of-file or the occurrence of an error. The sizeof() function should be used to ensure that the number of bytes does not exceed the capacity of the buffer. BS2000 The following applies in the case of text files with SAM access mode and variable record length for which a maximum record length is also specified: When the specification O_NOSPLIT was entered for open, records of maximum record length are not concatenated with the subsequent record when they are read. By default (i.e. without the specification O_NOSPLIT), when a record with maximum record length is read, it is assumed that the following record is the continuation of this record and the records are concatenated. (End) The program environment determines whether read() is executed for a BS2000 or POSIX file.
See also	fcntl(), lseek(), open(), pipe(), unistd.h, and section “General terminalinterface”.