lseek(2) System Calls Manual lseek(2)

lseek - zmienia pozycję przesunięcia pliku do odczytu/zapisu

Standardowa biblioteka C (libc, -lc)

#include <unistd.h>
off_t lseek(int fd, off_t offset, int whence);

lseek zmienia przesunięcie opisu otwartego pliku (OFD), powiązanego z deskryptorem pliku fd na wartość podaną w argumencie offset, zgodnie z dyrektywą whence w następujący sposób:

Przesunięcie pliku jest ustawiane na offset bajtów.
Przesunięcie pliku jest ustawiane na aktualną pozycję plus offset bajtów.
Przesunięcie pliku jest ustawiane na rozmiar pliku plus offset bajtów.

lseek umożliwia ustawienie przesunięcia w pliku poza istniejący plik (jednak nie zmienia to rozmiaru pliku). Jeśli później w tym miejscu zostaną zapisane jakieś dane, to kolejne odczyty danych z luki (dziury) zwrócą bajty null („\0”), aż do czasu, gdy dane zostaną rzeczywiście w tej luce zapisane.

Od Linuksa 3.1, Linux obsługuje następujące dodatkowe wartości whence:

Dopasowuje przesunięcie pliku do następnego położenia w pliku, większego lub równego przesunięciu offset, które zawiera dane. Jeśli offset wskazuje na dane, to przesunięcie pliku jest ustawiane na offset.
Dopasowuje przesunięcie pliku do następnej dziury w pliku, większej lub równej przesunięciu offset. Jeśli offset wskazuje wewnątrz dziury, to przesunięcie pliku jest ustawiane na offset. Jeśli po offset nie występuje dziura, to przesunięcie pliku jest dopasowane do końca pliku (tj. występuje domniemana dziura na końcu każdego pliku).

W obu powyższych przypadkach lseek() zawiedzie, jeśli offset wskazuje poza koniec pliku.

Opisywane operacje pozwalają aplikacjom na lokalizowanie dziur w rzadko (elastycznie) alokowanych plikach. Może okazać się przydatne w aplikacjach takich jak narzędzia kopii zapasowej, które mogą zaoszczędzić miejsce przy tworzeniu kopii zapasowej, przy zachowaniu dziur, jeśli posiadają mechanizm do ich odkrywania.

Do celów tych operacji, za dziurę uważa się sekwencję zer, która (normalnie) nie byłaby przydzielona w przedmiotowym nośniku pliku. Jednak system plików nie ma obowiązku informowania o dziurach, tak więc operacje te nie są pewnym mechanizmem wyszukiwania przestrzeni rzeczywiście przydzielonej plikowi (co więcej, sekwencja zer, która rzeczywiście została zapisana na przedmiotowym nośniku może nie zostać zgłoszona jako dziura). W najprostszej implementacji, system plików może obsługiwać te operacje w ten sposób, że SEEK_HOLE zawsze zwróci przesunięcie końca pliku, a SEEK_DATA zawsze zwróci offset (tj. nawet gdy położenie, do którego odnosi się offset jest dziurą, może być rozważane jako składające się z danych będących sekwencją zer).

Konieczne jest zdefiniowana makra _GNU_SOURCE, aby pozyskać definicje SEEK_DATA i SEEK_HOLE z <unistd.h>.

Operacje SEEK_HOLE i SEEK_DATA są obsługiwane w następujących systemach plików:

•
Btrfs (od Linuksa 3.1)
•
OCFS (od Linuksa 3.2)
•
XFS (od Linuksa 3.5)
•
ext4 (od Linusa 3.8)
•
tmpfs(5) (od Linuksa 3.8)
•
NFS (od Linuksa 3.18)
•
FUSE (od Linuksa 4.5)
•
GFS2 (od Linuksa 4.15)

Po pomyślnym zakończeniu lseek() zwraca ustawione przesunięcie, liczone w bajtach od początku pliku. W razie wystąpienia błędu, zwracana jest wartość (off_t) -1 oraz ustawiane jest errno w sposób wskazujący rodzaj błędu.

fd nie jest deskryptorem otwartego pliku.
whence jest nieprawidłowe. Albo: wynikowe przesunięcie pliku byłoby ujemne lub poza końcem przeszukiwalnego urządzenia.
whence wynosi SEEK_DATA lub SEEK_HOLE, a offset jest poza końcem pliku albo whence wynosi SEEK_DATA, a offset jest w dziurze na końcu pliku.
Wynikowego przesunięcia pliku nie da się przedstawić w off_t.
fd jest związany z potokiem, gniazdem, lub FIFO.

W Linuksie, użycie lseek() na urządzeniu terminala zawiedzie z błędem ESPIPE.

POSIX.1-2008.

POSIX.1-2001, SVr4, 4.3BSD.

SEEK_DATA i SEEK_HOLE są niestandardowymi rozszerzeniami obecnymi również w Solarisie, FreeBSD i DragonFly BSD; proponuje się włączenie ich do następnej rewizji POSIX (Issue 8).

W podręczniku open(2) opisano relacje pomiędzy deskryptorami pliku, opisami otwartego pliku (OFD) i plikami.

Jeśli znacznik statusu O_APPEND jest ustawiony na opisie otwartego pliku (OFD), to write(2) zawsze przenosi przesunięcie pliku na koniec pliku, niezależnie od użycia lseek().

Niektóre urządzenia nie obsługują tego typu operacji, a POSIX nie opisuje, które urządzenie muszą obsługiwać lseek().

dup(2), fallocate(2), fork(2), open(2), fseek(3), lseek64(3), posix_fallocate(3)

Autorami polskiego tłumaczenia niniejszej strony podręcznika są: Przemek Borys <pborys@dione.ids.pl>, Andrzej Krzysztofowicz <ankry@green.mf.pg.gda.pl> i Michał Kułach <michal.kulach@gmail.com>

Niniejsze tłumaczenie jest wolną dokumentacją. Bliższe informacje o warunkach licencji można uzyskać zapoznając się z GNU General Public License w wersji 3 lub nowszej. Nie przyjmuje się ŻADNEJ ODPOWIEDZIALNOŚCI.

Błędy w tłumaczeniu strony podręcznika prosimy zgłaszać na adres listy dyskusyjnej manpages-pl-list@lists.sourceforge.net.

2 maja 2024 r. Linux man-pages 6.8