lseek(2)

НАИМЕНОВАНИЕ
lseek - изменяет файловое смещение, используемое при чтении/записи

БИБЛИОТЕКА
Стандартная библиотека языка C (libc, -lc)

СИНТАКСИС
#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() allows the file offset to be set beyond the end of the file (but this does not change the size of the file). If data is later written at this point, subsequent reads of the data in the gap (a "hole") return null bytes ('\0') until data is actually written into the gap.

  Перемещения по данным файла и промежутки
Since Linux 3.1, Linux supports the following additional values for whence:

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

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

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

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

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

Чтобы получить определения SEEK_DATA и SEEK_HOLE из <unistd.h>, нужно задать макрос тестирования свойств _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)

•   GFS2 (начиная с Linux 4.15)

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
При успешном выполнении lseek() возвращает получившееся в результате смещение в байтах от начала файла. При ошибке возвращается значение (off_t) -1 и в errno записывается код ошибки.

ОШИБКИ

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

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

ENXIO
    whence is SEEK_DATA or SEEK_HOLE, and offset is beyond the end of the file, or whence is SEEK_DATA and offset is within a hole at the end of the file.

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

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

ВЕРСИИ
В Linux при использовании lseek() на устройствах терминалов возвращается ошибка ESPIPE.

СТАНДАРТЫ
POSIX.1-2024.

ИСТОРИЯ
4.3BSD, SVr4, POSIX.1-1988.

SEEK_DATA
SEEK_HOLE
    Solaris 10, FreeBSD 7.0, DragonFly BSD 2.3.1, POSIX.1-2024.

ПРИМЕЧАНИЯ
Описание взаимосвязи между файловыми дескрипторами, открытыми файловыми описаниями и файлами смотрите в open(2).

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

Некоторые устройства не могут выполнять смещения и в POSIX не указано какие устройства должны поддерживать lseek().

СМОТРИТЕ ТАКЖЕ
dup(2), fallocate(2), fork(2), open(2), fseek(3), lseek64(3), posix_fallocate(3)

ПЕРЕВОД
Русский перевод этой страницы руководства разработал(и) Artyom Kunyov <artkun@guitarplayer.ru>, Azamat Hackimov <azamat.hackimov@gmail.com>, Dmitry Bolkhovskikh <d20052005@yandex.ru>, Katrin Kutepova <blackkatelv@gmail.com>, Konstantin Shvaykovskiy <kot.shv@gmail.com>, Yuri Kozlov <yuray@komyakino.ru> и Иван Павлов <pavia00@gmail.com>

Этот перевод является свободной программной документацией; он распространяется на условиях общедоступной лицензии GNU (GNU General Public License - GPL, https://www.gnu.org/licenses/gpl-3.0.html версии 3 или более поздней) в отношении авторского права, но БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ.

Если вы обнаружите какие-либо ошибки в переводе этой страницы руководства, пожалуйста, сообщите об этом разработчику(ам) по его(их) адресу(ам) электронной почты или по адресу списка рассылки русских переводчиков (debian-l10n-russian@lists.debian.org).