NAZWA

       sendfile - przesyła dane pomiędzy deskryptorami plików

BIBLIOTEKA

       Standardowa biblioteka C (libc, -lc)

SKŁADNIA

       #include <sys/sendfile.h>

       ssize_t sendfile(int out_fd, int in_fd, off_t *_Nullable offset,
                        size_t count);

OPIS

       sendfile()  kopiuje  dane  pomiędzy  dwoma  deskryptorami  plików.  Kopiowanie odbywa się wewnątrz jądra,
       dlatego sendfile() jest wydajniejsze niż połączenie  read(2)  z  write(2),  które  wymagałoby  przesłania
       danych do i z przestrzeni użytkownika.

       in_fd powinien być deskryptorem pliku otwartym do odczytu, a out_fd powinien być deskryptorem otwartym do
       zapisu.

       Jeśli  offset  nie  wynosi  NULL,  to wskazuje on na zmienną przechowującą przesunięcie pliku, od którego
       sendfile() zacznie odczytywać dane z in_fd. Gdy sendfile() powróci,  zmienna  ta  zostanie  ustawiona  na
       przesunięcie  bajtu,  który  następuje  po  ostatnim  odczytanym bajcie. Jeśli offset nie wynosi NULL, to
       sendfile()  nie  modyfikuje  przesunięcia  pliku  in_fd;  w  innym  przypadku  przesunięcie  pliku   jest
       dostosowywane, aby uwzględnić liczbę bajtów odczytanych z in_fd.

       Jeśli offset wynosi NULL, to dane będą odczytane z in_fd, począwszy od przesunięcia pliku, a przesunięcie
       pliku zostanie zaktualizowane przez to wywołanie.

       count jest liczbą bajtów do skopiowania pomiędzy deskryptorami plików.

       Argument  in_fd  musi  odnosić  się  do  pliku  obsługującego  operacje w stylu mmap(2) (tj. nie może być
       gniazdem). Od Linuksa 5.12 nie  dotyczy  to  sytuacji,  gdy  out_fd  jest  potokiem;  wówczas  sendfile()
       upraszcza się do splice(2) i stosują się jego ograniczenia.

       Przed  Linuksem 2.6.33, out_fd musiał odnosić się do gniazda. Od Linuksa 2.6.33 może być to dowolny plik.
       Jeśli jest przewijalny, to sendfile() odpowiednio dostosowuje przesunięcie pliku.

WARTOŚĆ ZWRACANA

       Jeśli przesłanie się powiodło, zwracana jest liczba bajtów zapisanych  do  out_fd.  Proszę  zauważyć,  że
       pomyślne  wywołanie  do  sendfile()  może  zapisać  mniej  bajtów  niż  zażądano; wywołujący powinien być
       przygotowany na ponowienie wywołania, jeśli wystąpiły niewysłane bajty. Zob. też UWAGI.

       W razie wystąpienia błędu zwracane jest -1 i ustawiane errno wskazując błąd.

BŁĘDY

       EAGAIN Wybrano nieblokujące wejście/wyjście za pomocą O_NONBLOCK, a zapis zablokowałby.

       EBADF  Plik wejściowy nie został otwarty do odczytu lub plik wyjściowy nie został otwarty do zapisu.

       EFAULT Niepoprawny adres.

       EINVAL Deskryptor nie jest prawidłowy lub zablokowany; albo operacja w stylu mmap(2)  nie  jest  dostępna
              dla in_fd; albo count jest ujemne.

       EINVAL out_fd ma ustawiony znacznik O_APPEND. Obecnie nie jest to obsługiwane przez sendfile().

       EIO    Nieokreślony błąd przy odczycie z in_fd.

       ENOMEM Zabrakło pamięci do odczytu z in_fd.

       EOVERFLOW
              count jest zbyt duże, operacja spowodowałaby przekroczenie maksymalnego rozmiaru pliku wejściowego
              lub pliku wyjściowego.

       ESPIPE offset nie wynosi NULL, lecz plik wejściowy nie jest przewijalny.

WERSJE

       Inne  systemy  uniksowe  implementują  sendfile() z różnym zachowaniem i prototypami. Nie należy stosować
       tego wywołania w przenośnym programach.

STANDARDY

       Brak.

HISTORIA

       Linux 2.2, glibc 2.1.

       W Linuksie 2.4 i wcześniejszych, out_fd mógł odnosić się także do zwykłego pliku; ta możliwość zniknęła w
       serii jąder Linux 2.6.x, lecz przywrócono ją w Linuksie 2.6.33.

       Pierwotne, linuksowe wywołanie systemowe sendfile() nie było zaprojektowane do obsługi dużych  przesunięć
       plików.  Z  tego  względu  w Linuksie 2.4 dodano sendfile64(), z szerszym typem argumentu offset. Funkcja
       opakowująca sendfile() z glibc radzi sobie z różnicami w jądrze w sposób transparentny.

UWAGI

       sendfile() dokona transferu co  najwyżej  0x7ffff000  (2 147 479 552)  bajtów,  zwracając  liczbę  bajtów
       faktycznie przesłanych (jest to prawdziwe zarówno dla systemów 32 jak i 64-bitowych).

       Jeśli  planuje  się  używać  sendfile()  do wysyłania plików do gniazda TCP, lecz przed zawartością pliku
       trzeba dołączyć jakieś  dane  nagłówka,  przydatne  będzie  korzystanie  z  opcji  TCP_CORK,  opisanej  w
       podręczniku tcp(7), w celu ograniczenia liczby pakietów i poprawienia wydajności.

       Aplikacje  mogą  uznać za stosowne awaryjnie korzystanie z read(2) i write(2) w przypadku, gdy sendfile()
       zawiedzie z błędem EINVAL lub ENOSYS.

       Jeśli out_fd odnosi się do gniazda lub potoku z obsługą  zero-copy,  wywołujący  muszą  upewnić  się,  że
       przesyłane części pliku, do których odnosi się in_fd, pozostaną niezmodyfikowane do momentu skonsumowania
       przesłanych danych przez odczytującego na drugim końcu out_fd.

       Typowo  linuksowe wywołanie splice(2) obsługuje przesyłanie danych pomiędzy dwoma dowolnymi deskryptorami
       plików, pod warunkiem, że jeden (lub obydwa) z nich jest potokiem.

ZOBACZ TAKŻE

       copy_file_range(2), mmap(2), open(2), socket(2), splice(2)

TŁUMACZENIE

       Tłumaczenie niniejszej strony podręcznika: 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                            2 maja 2024 r.                                      sendfile(2)