ИМЯ

lseek - изменяет файловое смещение, используемое при чтении/записи

ОБЗОР

#include <sys/types.h>
#include <unistd.h>

off_t lseek(int fd, off_t offset, int whence);

ОПИСАНИЕ

Функция lseek() изменяет файловое смещение в описании открытого файла, связанного
с файловым дескрипторов fd, на значение аргумента offset в соответствии с
директивой whence, которая может принимать одно из следующих значений:

SEEK_SET
Установить файловое смещение равным offset (в байтах).

SEEK_CUR
Установить файловое смещение равным текущему положению плюс offset (в
байтах).

SEEK_END
Установить файловое смещение равным размеру файла плюс offset (в байтах).

Функция lseek() позволяет задавать смещение, которое будет находиться за
существующим концом файла (но это не изменяет размер файла). Если позднее по этому
смещению будут записаны данные, то последующее чтение в промежутке («дырке») от
конца файла до этого смещения, будет возвращать нулевые байты ('\0'), пока в этот
промежуток действительно не будут записаны данные.

Перемещения по данным файла и промежутки
Начиная с версии 3.1, в Linux поддерживаются следующие дополнительные значения
whence:

SEEK_DATA
Подогнать файловое смещение к следующему расположению, большему или равному
значению offset, по которому в файле есть данные. Если значение offset
указывает на данные, то файловое смещение устанавливается в offset.

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

В обоих, показанных выше, случаях, lseek() завершится с ошибкой, если offset
указывает за конец файла.

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

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

Операции SEEK_HOLE и SEEK_DATA поддерживаются следующими файловыми системами:

* Btrfs (начиная с Linux 3.1)

* OCFS (начиная с Linux 3.2)

* XFS (начиная с Linux 3.5)

* ext4 (начиная с Linux 3.8)

* tmpfs(5) (начиная с Linux 3.8)

* NFS (начиная с Linux 3.18)

* FUSE (начиная с Linux 4.5)

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ

При успешном выполнении lseek() возвращает получившееся в результате смещение в
байтах от начала файла. При ошибке возвращается значение (off_t) -1 и в errno
записывается код ошибки.

ОШИБКИ

EBADF fd не является открытым файловым дескриптором.

EINVAL Неправильное значение whence. Получается, что возвращаемое файловое
смещение стало бы отрицательным или указывало бы за конец поверхности
носителя.

ENXIO Значение whence равно SEEK_DATA или SEEK_HOLE, а файловое смещение
указывает за конец файла.

EOVERFLOW
Результирующие файловое смещение не может быть представлено типом off_t.

ESPIPE Значение fd связано с каналом, сокетом или FIFO.

СООТВЕТСТВИЕ СТАНДАРТАМ

POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD.

Значения SEEK_DATA и SEEK_HOLE являются нестандартными расширениями, которые также
есть в Solaris, FreeBSD и DragonFly BSD; их предложили включить в следующую
редакцию POSIX (выпуск 8).

ЗАМЕЧАНИЯ

Описание взаимосвязи между файловыми дескрипторами, открытыми файловыми описаниями
и файлами смотрите в open(2).

Если установлен флаг состояние файла O_APPEND в открытом файловом описании, то
write(2) всегда перемещает файловое смещение в конец файла, независимо от
использования lseek().

Тип данных off_t представляет собой знаковый целочисленный тип, определён в
POSIX.1.