write()

Записать последовательность байт в файл

Прототип:

#include <unistd.h>
                                       
ssize_t write( int fildes,
               const void *buf,
               size_t nbytes );

Аргументы:

fildes
Дескриптор файла, в который должна быть произведена запись.
buf
Указатель на область памяти, которая содержит данные для записи.
nbytes
Количество байт для записи.

Библиотека:

libc

Описание:

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

Если nbytes равен нулю, write() возвращает ноль, и не выполняет других действий.

В обычном файле (или любом другом файле, в котором возможен поиск с последовательным смещением отступа от начала), если не установлен флаг O_APPEND, write() начинает работу с позиции, которую определяет отступ, соответствующий дескриптору fildes. Если флаг O_APPEND установлен, отступ установлен в конце файла до начала операции записии. До успешного возврата из write() отступ файла увеличивается на число байт, которые были записаны. В обычном файле, если новый полученный отступ больше, чем длина файла, длина файла преобразуется к значению отступа.

Note: Обратите внимание, что вызов write() игнорирует рекомендованные блокировки, которые могли быть установлены функцией fcntl().

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

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

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

Если write() прервана сигналом до записи любого количества байт, она возвращает -1, а переменной errno устанавливается значение EINTR. Однако, если a write() была прервана сигналом после того, как какая-то часть данных была записана, она возвращает количество записанных байт. Если значение nbytes выше чем INT_MAX, write() возвращает -1 и устанавливает переменной errno значение EINVAL (см. <limits.h>).

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

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

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

Если write() завершилась с успехом, поля файла st_ctime и st_mtime помечаются для обновления.

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

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

Коды ошибок:

EAGAIN
Флаг O_NONBLOCK установлен для файлового дескриптора, процесс будет задержан при операции записи.
EBADF
Файловый дескриптор fildes не является допустимом файловым дескриптором, который позволяет производить запись.
ECONNRESET
Попытка записи по неподключенному сокету.
EFBIG
Произошло одно из следующих событий:
EINTR
Операции записи была прервана сигналом, данные либо не были записаны, либо ресурс менеджер, отвественный за этот файл, не сообщил об успешной передаче части информации.
EIO
Произошло одно из следующих событий:
ENETDOWN
Попытка записи была выполнена в сокет или интерфейс локальной сети, который недоступен.
ENETUNREACH
Попытка записи в сокет, к которому не существует маршрута в сети.
ENOSPC
Нет свободного места на устройстве, которое содержит файл.
ENOSYS
Функция write() не реализована для файловой системы, указанной в filedes.
ENXIO
Произошло одно из следующих событий:
EPIPE
Произошло одно из следующих событий:
ERANGE
Запрошенный размер для записи за границей диапазона, который поддерживает поток файловый системы для файла, указанного в fildes.

Примеры:

#include <stdio.h>
#include <fcntl.h>
#include <unistd.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <stdlib.h>
                                       
char buffer[] = { "A text record to be written" };
                                       
int main( void )
{
    int  fd;
    int  size_written;
                                       
    /* open a file for output          */
    /* replace existing file if it exists */
    fd = creat( "myfile.dat", S_IRUSR | S_IWUSR );
                                       
    /* write the text              */
    size_written = write( fd, buffer, sizeof( buffer ) );
                                       
    /* test for error              */
    if ( size_written != sizeof( buffer ) )
    {
        perror( "Error writing 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(), read(), readv(), select(), writev()




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