READ(2)

НАЗВАНИЕ
read - чтение из файла

СИНТАКСИС


        int read (fildes, buf, nbyte)

        int fildes;

        char *buf;

        unsigned nbyte;

ОПИСАНИЕ
Аргумент fildes - это дескриптор файла, полученный после выполнения системных вызовов creat(2), open(2), dup(2), fcntl(2) или pipe(2).

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

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

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

При успешном завершении системного вызова read возвращается количество байт, реально прочитанных и помещенных в буфер; это количество может быть меньше значения аргумента nbyte, если файл ассоциирован с линией связи [см. ioctl(2) и termio(7)] или если количество байт, оставшихся в файле, меньше значения аргумента nbyte. Если текущая позиция совпадала с концом файла, результат будет равен 0.

Чтение с псевдоустройств [см. intro(2)] может выполняться в трех различных режимах: байтном, режиме сообщений без сброса и режиме сообщений со сбросом. Стандартным является байтный режим. С помощью системного вызова ioctl режим может быть изменен (опция I_SRDOPT [см. streamio(7)]) и опрошен (опция I_GRDOPT). В байтовом режиме системный вызов read выбирает данные из потока до тех пор, пока не получит nbyte байт или пока не выберет все данные потока. В этом режиме границы сообщений игнорируются.

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

При попытке чтения из обычного файла с установленным флагом учета блокировки [см. chmod(2)] и при наличии блокировки на запись (другим процессом) того сегмента файла, который должен быть прочитан, в зависимости от значения флага O_NDELAY системный вызов read ведет себя следующим образом:

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

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

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

При попытке чтения из файла, ассоциированного с терминалом, когда нет данных, предназначенных для чтения:

Если установлен флаг O_NDELAY, то возвращается значение 0.
Если не установлен флаг O_NDELAY, то читающий процесс откладывается до тех пор, пока данные не появятся.

При попытке чтения из файла, ассоциированного с потоком, в котором нет данных:

Если установлен флаг O_NDELAY, то возвращается значение -1, а переменной errno присваивается код ошибки EAGAIN.
Если не установлен флаг O_NDELAY, то читающий процесс откладывается до тех пор, пока данные не появятся.

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

При чтении с псевдоустройств системный вызов read может обрабатывать только сообщения с данными. Он не в состоянии обработать протокольное сообщение и завершается неудачей, если встретит подобное сообщение в истоке потока.

Если в потоке происходит освобождение линии, то системный вызов read будет нормально работать, пока очередь чтения в истоке не станет пустой. После этого read вернет значение 0.

Системный вызов read завершается неудачей, если выполнено хотя бы одно из следующих условий:

[EAGAIN]: Установлены флаги учета блокировки файла и O_NDELAY, и требуемый сегмент файла заблокирован.
[EAGAIN]: Общее количество системной памяти, предоставленной для бесструктурного ввода/вывода, временно оказалось недостаточным.
[EAGAIN]: При установленном флаге O_NDELAY в потоке нет сообщений, ожидающих чтения.
[EBADF]: Аргумент fildes не является корректным дескриптором файла, открытого на чтение.
[EBADMSG]: Сообщение, считываемое из потока, не является сообщением с данными.
[EDEADLK]: Попытка ожидания чтения приводит к тупику.
[EFAULT]: Аргумент buf указывает за пределы отведенного процессу адресного пространства.
[EINTR]: Во время выполнения системного вызова перехвачен сигнал.
[EINVAL]: Попытка чтения из потока, который мультиплексируется.
[ENOLCK]: Нет свободного места в системной таблице блокировок.
[ENOLINK]: Аргумент fildes является дескриптором файла на удаленном компьютере, связи с которым в данный момент нет.

Чтение с псевдоустройства также завершается неудачей, если в истоке потока получено сообщение об ошибке. В этом случае переменной errno присваивается значение, содержащееся в сообщении.

СМ. ТАКЖЕ
creat(2), dup(2), fcntl(2), ioctl(2), intro(2), open(2), pipe(2), getmsg(2). streamio(7), termio(7) в Справочнике администратора.

ДИАГНОСТИКА
При успешном завершении результат равен неотрицательному целому числу - количеству реально прочитанных байт; в случае ошибки возвращается -1, а переменной errno присваивается код ошибки.