read()

Считать последовательность байт из файла

Прототип:

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

Аргументы:

fildes

Дескриптор файла, из которого требуется считать информацию.

buf

Указатель на буфер, в котором функция может хранить считываемые данные.

nbyte

Количество байт, которые требуется прочитать.

Библиотека:

libc

Описание:

Функция read() пытается прочитать nbyte байт из файла, связанного с дескриптором открытого файла fildes, в буфер, на который указывает buf.

Если nbyte равен нулю, read() возвращает нуль, и не имеет никакого другого эффекта.

В обычном файле или другом файле, в котором возможен поиск, read() начинается с позиции в файле, заданной смещением файла, связанным с fildes. Перед успешным возвратом из read() смещение файла увеличивается на количество фактически прочитанных байт.

---

Вызов read() игнорирует рекомендательные блокировки, которые вы могли установить с помощью fcntl().

---

В файле, в котором невозможен поиск, read() начинает с текущей позиции.

Когда функция read() успешно завершается, ее возвращаемое значение - это количество байт, фактически прочитанных и помещенных в буфер. Это число никогда не будет больше nbyte, хотя оно может быть меньше nbyte по одной из следующих причин:

• Количество байт, оставшихся в файле, меньше nbyte.
• Запрос read() был прерван сигналом.
• Файл представляет собой канал (или FIFO) или специальный файл, в котором для чтения доступно менее nbyte байт. Например, чтение из файла, связанного с терминалом, может вернуть одну типизированную строку данных.

Если read() прерывается сигналом до того, как она считает какие-либо данные, она возвращает значение -1 и устанавливает errno в EINTR. Однако, если read() перврвана сигналом после того, как она успешно прочитала некоторые данные, она возвращает количество прочитанных байт.

Никакие данные не считываются после достижения конца текущего файла. Если начальная позиция находится в конце файла или после него, read() возвращает ноль. Если файл является специальным файлом устройства, результат последующих вызовов read() будет работать в зависимости от текущего состояния устройства (то есть конец файла является временным).

Если значение nbyte больше, чем INT_MAX, read() возвращает -1 и устанавливает errno в значение EINVAL. См. <limits.h>.

При попытке чтения из пустого канала или FIFO:

1. Если ни у одного процесса нет канала, открытого для записи, read() возвращает 0, чтобы сообщить о достижении конца файла.
2. Если у процесса канал открыт для записи и установлен O_NONBLOCK, read() возвращает -1, и errno устанавливается в EAGAIN.
3. Если у процесса есть канал, открытый для записи, и O_NONBLOCK очищен, read() блокируется до тех пор, пока данные записываются, или канал будет закрыт всеми процессами, открывшими его для записи.

При попытке чтения из файла (кроме канала или FIFO), который поддерживает неблокирующее чтение и не имеет в данный момент никаких данных:

1. Если установлено O_NONBLOCK, read() возвращает -1, и errno устанавливается в EAGAIN.
2. Если O_NONBLOCK равен нулю, read() блокируется до тех пор, пока не появятся данные.
3. Флаг O_NONBLOCK не действует, если часть данных доступна.

Если вы вызываете read() для некоторой части файла до конца файла, которая еще не была записана, то она возвращает байты с нулевым значением.

Если read() завершается успешно, поле st_atime файла помечается для обновления.

Возвращаемое значение:

Фактически прочитанное количество байт.

Если возникла ошибка функция возвращает -1, код ошибки записывается в errno.

Коды ошибок:

EAGAIN

Флаг O_NONBLOCK установлен для дескриптора файла, и процесс будет задержан в операции чтения.

EBADF

Файловый дескриптор fildes, не является допустимым файловым дескриптором, открытым для чтения.

EINTR

Операция чтения была прервана сигналом, и либо данные не были переданы, либо менеджер ресурсов, ответственный за этот файл, не сообщает о частичной передаче.

EIO

Одно из двух:

• Произошла физическая ошибка ввода/вывода (например, битый блок на диске). Точное значение зависит от устройства.
• Файловая система находится на съемном носителе, и этот носитель был принудительно удален.

ENOSYS

Функция read() не реализована для файловой системы, указанной в filedes.

EOVERFLOW

Файл является обычным файлом, и производится попытка чтения с максимальным смещением, связанным с файлом, или за его пределами.

Примеры:

#include <sys/types.h>
#include <fcntl.h>
#include <unistd.h>
#include <stdlib.h>
#include <stdio.h>
                                       
int main( void )
{
    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" );
        return (EXIT_FAILURE);
    }
                                       
    /* Close the file */
    close( fd );
        
    return (EXIT_SUCCESS);
}

Классификация:

POSIX 1003.1 X/Open Systems Interfaces Extension

Безопасность использования

Точка остановки потока

Да

Обработчик прерываний

Нет

Обработчик сигналов

Да

В потоке

Да

Тематические ссылки:

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

Предыдущий раздел: Описание API системной библиотеки