read(2) — Linux man page
On files that support seeking, the read operation commences at the current file offset, and the file offset is incremented by the number of bytes read. If the current file offset is at or past the end of file, no bytes are read, and read() returns zero.
If count is zero, read() may detect the errors described below. In the absence of any errors, or if read() does not check for errors, a read() with a count of 0 returns zero and has no other effects.
If count is greater than SSIZE_MAX, the result is unspecified.
Return Value
On success, the number of bytes read is returned (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 read() was interrupted by a signal. On error, -1 is returned, and errno is set appropriately. In this case it is left unspecified whether the file position (if any) changes.
Errors
EAGAIN The file descriptor fd refers to a file other than a socket and has been marked nonblocking (O_NONBLOCK), and the read would block. EAGAIN or EWOULDBLOCK The file descriptor fd refers to a socket and has been marked nonblocking (O_NONBLOCK), and the read would block. POSIX.1-2001 allows either error to be returned for this case, and does not require these constants to have the same value, so a portable application should check for both possibilities. EBADF fd is not a valid file descriptor or is not open for reading. EFAULT buf is outside your accessible address space. EINTR The call was interrupted by a signal before any data was read; see signal(7). EINVAL fd is attached to an object which is unsuitable for reading; or the file was opened with the O_DIRECT flag, and either the address specified in buf, the value specified in count, or the current file offset is not suitably aligned. EINVAL fd was created via a call to timerfd_create(2) and the wrong size buffer was given to read(); see timerfd_create(2) for further information. EIO I/O error. This will happen for example when the process is in a background process group, tries to read from its controlling terminal, and either it is ignoring or blocking SIGTTIN or its process group is orphaned. It may also occur when there is a low-level I/O error while reading from a disk or tape. EISDIR fd refers to a directory.
Other errors may occur, depending on the object connected to fd. POSIX allows a read() that is interrupted after reading some data to return -1 (with errno set to EINTR) or to return the number of bytes already read.
Conforming to
Notes
On NFS file systems, reading small amounts of data will only update the timestamp the first time, subsequent calls may not do so. This is caused by client side attribute caching, because most if not all NFS clients leave st_atime (last file access time) updates to the server and client side reads satisfied from the client’s cache will not cause st_atime updates on the server as there are no server side reads. UNIX semantics can be obtained by disabling client side attribute caching, but in most situations this will substantially increase server load and decrease performance.
See Also
close(2), fcntl(2), ioctl(2), lseek(2), open(2), pread(2), readdir(2), readlink(2), readv(2), select(2), write(2), fread(3)
Linux system calls read
#include
#include
#include
ssize_t read (int d void *buf size_t nbytes);
ssize_t pread (int d void *buf size_t nbytes off_t offset);
ssize_t readv (int d const struct iovec *iov int iovcnt);
ssize_t preadv (int d const struct iovec *iov int iovcnt off_t offset);
DESCRIPTION
The read ();
system call attempts to read Fa nbytes of data from the object referenced by the descriptor Fa d into the buffer pointed to by Fa buf . The readv ();
system call performs the same action, but scatters the input data into the Fa iovcnt buffers specified by the members of the Fa iov array: iov[0], iov[1], . iov[iovcnt-1]. The pread ();
and preadv ();
system calls perform the same functions, but read from the specified position in the file without modifying the file pointer.
For readv ();
and preadv (,);
the Fa iovec structure is defined as:
Each Fa iovec entry specifies the base address and length of an area in memory where data should be placed. The readv ();
system call 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 Fa d (see lseek(2)). Upon return from read (,);
the pointer is incremented by the number of bytes actually read.
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 end-of-file, but in no other case.
RETURN VALUES
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
Bq Er EBADF The Fa d argument is not a valid file or socket descriptor open for reading. Bq Er ECONNRESET The Fa d argument refers to a socket, and the remote socket end is forcibly closed. Bq Er EFAULT The Fa buf argument points outside the allocated address space. Bq Er EIO An I/O error occurred while reading from the file system. Bq Er EINTR A read from a slow device (i.e. one that might block for an arbitrary amount of time) was interrupted by the delivery of a signal before any data arrived. Bq Er EINVAL The pointer associated with Fa d was negative. Bq Er EAGAIN The file was marked for non-blocking I/O, and no data were ready to be read. Bq Er EISDIR The file descriptor is associated with a directory residing on a file system that does not allow regular read operations on directories (e.g. NFS). Bq Er EOPNOTSUPP The file descriptor is associated with a file system and file type that do not allow regular read operations on it. Bq Er EOVERFLOW The file descriptor is associated with a regular file, Fa nbytes is greater than 0, Fa offset is before the end-of-file, and Fa offset is greater than or equal to the offset maximum established for this file system. Bq Er EINVAL The value Fa nbytes is greater than INT_MAX
In addition, readv ();
and preadv ();
may return one of the following errors:
Bq Er EINVAL The Fa iovcnt argument was less than or equal to 0, or greater than IOV_MAX Bq Er EINVAL One of the Fa iov_len values in the Fa iov array was negative. Bq Er EINVAL The sum of the Fa iov_len values in the Fa iov array overflowed a 32-bit integer. Bq Er EFAULT Part of the Fa iov array points outside the process’s allocated address space.
The pread ();
and preadv ();
system calls may also return the following errors:
Bq Er EINVAL The Fa offset value was negative. Bq Er ESPIPE The file descriptor is associated with a pipe, socket, or FIFO.
SEE ALSO
STANDARDS
The read ();
system call is expected to conform to St -p1003.1-90 . The readv ();
and pread ();
system calls are expected to conform to St -xpg4.2 .
HISTORY
The preadv ();
system call appeared in Fx 6.0 . The pread ();
function appeared in AT&T System V.4 . The readv ();
system call appeared in BSD 4.2 The read ();
function appeared in AT&T System v6 .
Linux system calls read
read () пытается записать count байтов файлового описателя fd в буфер, адрес которого начинается с buf .
Если количество count равно нулю, то read () возвращает это нулевое значение и завершает свою работу. Если count больше, чем SSIZE_MAX , то результат не может быть определен.
ВОЗВРАЩАЕМЫЕ ЗНАЧЕНИЯ
При успешном завершении вызова возвращается количество байтов, которые были считаны (нулевое значение означает конец файла), а позиция файла увеличивается на это значение. Если количество прочитанных байтов меньше, чем количество запрошенных, то это не считается ошибкой: например, данные могли быть почти в конце файла, в канале, на терминале, или read () был прерван сигналом. В случае ошибки возвращаемое значение равно -1, а переменной errno присваивается номер ошибки. В этом случае позиция файла не определена.
НАЙДЕННЫЕ ОШИБКИ
EINTR Системный вызов был прерван сигналом до того, как был прочитан хотя бы один байт. EAGAIN При помощи O_NONBLOCK был выбран неблокирующий (non-blocking) ввод-вывод, и нет данных, доступных для чтения в данный момент. EIO Ошибка ввода-вывода. Это может произойти, например, если процесс, находящийся в группе фоновых процессов, пытается читать данные на контрольном терминале, игнорирует или блокирует сигнал SIGTTIN , или же его группа осталась без родителя. Это может также случиться, если произошла низкоуровневая ошибка ввода-вывода при считывании данных с диска или ленты. EISDIR fd указывает на каталог. EBADF fd является неверным файловым описателем или не открыт для чтения. EINVAL fd связан с объектом, не предназначенным для чтения. EFAULT buf указывает на каталог за пределами доступного адресного пространства.
Могут также возникнуть другие ошибки (в зависимости от объекта, связанного с fd ). POSIX позволяет системному вызову read , который был прерван после чтения первого блока запрошенных данных, вернуть значение -1 (устанавливая значение переменной errno равным EINTR) или количество уже прочитанных байтов.
СООТВЕТСТВИЕ СТАНДАРТАМ
НАЙДЕННЫЕ ОШИБКИ И ОГРАНИЧЕНИЯ
В файловых системах NFS чтение небольших порций данных обновляет значение временного штампа только в первый раз. Это вызвано кэшированием атрибутов со стороны клиента: большинство клиентов NFS (если не все) предоставляют серверу право обновлять время доступа, а запросы на чтение, которые удовлетворяются из клиентского кэша, не вызывают обновления времени доступа, потому что данные не считываются с сервера. Семантика UNIX может быть получена путем запрета кэширования атрибутов, но в большинстве случаев это увеличит нагрузку на сервер и уменьшит производительность.
Много файловых систем и дисков создавались достаточно быстрыми для того, чтобы в использовании O_NONBLOCK не было необходимости. Поэтому иногда O_NONBLOCK может быть недоступно на некоторых файлах и/или дисках.