NAZWA

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

BIBLIOTEKA

       Standardowa biblioteka C (libc, -lc)

SKŁADNIA

       #include <unistd.h>

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

OPIS

       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:

       SEEK_SET
              Przesunięcie pliku jest ustawiane na offset bajtów.

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

       SEEK_END
              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.

   Szukanie danych i dziur w pliku
       Od Linuksa 3.1, Linux obsługuje następujące dodatkowe wartości whence:

       SEEK_DATA
              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.

       SEEK_HOLE
              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)

WARTOŚĆ ZWRACANA

       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.

BŁĘDY

       EBADF  fd nie jest deskryptorem otwartego pliku.

       EINVAL whence jest nieprawidłowe. Albo:  wynikowe  przesunięcie  pliku  byłoby  ujemne  lub  poza  końcem
              przeszukiwalnego urządzenia.

       ENXIO  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.

       EOVERFLOW
              Wynikowego przesunięcia pliku nie da się przedstawić w off_t.

       ESPIPE fd jest związany z potokiem, gniazdem, lub FIFO.

WERSJE

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

STANDARDY

       POSIX.1-2008.

HISTORIA

       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).

UWAGI

       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().

ZOBACZ TAKŻE

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

TŁUMACZENIE

       Tłumaczenie niniejszej strony podręcznika: 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.

Linux man-pages 6.9.1                          15 czerwca 2024 r.                                       lseek(2)