DOKK / manpages / debian 13 / manpages-pl-dev / splice.2.pl
splice(2) System Calls Manual splice(2)

splice - przenosi dane do/z potoku

Standardowa biblioteka C (libc, -lc)

#define _GNU_SOURCE         /* Zob. feature_test_macros(7) */
#define _FILE_OFFSET_BITS 64
#include <fcntl.h>
ssize_t splice(int fd_in, off_t *_Nullable off_in,
               int fd_out, off_t *_Nullable off_out,
               size_t len, unsigned int flags);

splice() przenosi dane pomiędzy dwoma deskryptorami plików, bez kopiowania pomiędzy przestrzenią adresową jądra i przestrzenią adresową użytkownika. Transferuje maksymalnie len bajtów z deskryptora pliku fd_in do deskryptora pliku fd_out, przy czym jeden z deskryptorów plików musi odnosić się do potoku.

fd_in i off_in są objęte następującą semantyką:

•
Jeśli fd_in odnosi się do potoku, to off_in musi wynosić NULL.
•
Jeśli fd_in nie odnosi się do potoku, a off_in wynosi NULL, to bajty są odczytywane z fd_in począwszy od przesunięcia pliku, a przesunięcie pliku jest odpowiednio dostosowywane.
•
Jeśli fd_in nie odnosi się do potoku, a off_in nie wynosi NULL, to off_in musi wskazywać na bufor określający początkowe przesunięcie, z którego zostaną odczytane bajty w fd_in; w tym przypadku przesunięcie pliku w fd_in nie ulega zmianie.

Analogiczne stwierdzenia stosują się do fd_out i off_out.

Argument flags jest maską bitową tworzoną jako suma logiczna (OR) zera lub większej liczby następujących wartości:

Próbuje przesunąć strony zamiast je kopiować. Jest to tylko wskazówka dla jądra: strony wciąż mogą być skopiowane, jeśli jądro nie może przesunąć stron z potoku lub jeśli bufory potoku nie odnoszą się do pełnych stron. Pierwotna implementacja tego znacznika była nieprawidłowa: z tego względu począwszy od Linuksa 2.6.21 nie odnosi on skutku (jednak wciąż jest dozwolony w wywołaniu do splice()); w przyszłości może być przywrócona poprawna implementacja.
Nie blokuje wejścia/wyjścia. Operacje splice na potoku będą nieblokujące, jednak splice() wciąż może zablokować, ponieważ deskryptory plików do/z których następuje splice mogą blokować (chyba, że mają one ustawiony znacznik O_NONBLOCK).
W kolejnym splice nadejdzie więcej danych. Jest to przydatna wskazówka, gdy fd_out odnosi się do gniazda (zob. też opis MSG_MORE w send(2) oraz opis TCP_CORK w tcp(7)).
Nieużywane w splice(); zob. vmsplice(2).

Po pomyślnym zakończeniu splice() zwraca liczbę bajtów przeniesionych do lub z potoku.

Zwracana wartość 0 oznacza koniec wejścia. Jeśli fd_in odnosi się do potoku, oznacza to, że nie było danych do transferu, zatem blokowanie nie miało sensu, ponieważ nie było zapisujących do końca do zapisu potoku.

W razie wystąpienia błędu splice zwraca -1 i ustawia errno, wskazując błąd.

We flags podano SPLICE_F_NONBLOCK lub jeden z deskryptorów plików oznaczono jako nieblokujący (O_NONBLOCK), natomiast operacja spowodowałaby blokowanie.
Jeden lub więcej deskryptorów plików nie jest prawidłowych lub nie mają prawidłowego trybu do odczytu i zapisu.
Docelowy system plików nie obsługuje operacji splice.
Docelowy plik jest otwarty w trybie dopisywania.
Żaden z deskryptorów plików nie odnosi się do potoku.
Podano przesunięcie dla urządzenia, które nie jest przewijalne (np. potok).
fd_in i fd_out odnoszą się do tego samego potoku.
Brak pamięci.
off_in albo off_out nie miały wartości NULL, a odpowiadający deskryptor pliku odnosił się do potoku.

Linux.

Linux 2.6.17, glibc 2.5.

W Linuksie 2.6.30 i wcześniejszych, dokładnie jeden z argumentów fd_in i fd_out musiał być potokiem. Od Linuksa 2.6.31 oba argumenty mogą odnosić się do potoków.

Trzy wywołania systemowe: splice(), vmsplice(2) i tee(2) zapewniają programom w przestrzeni użytkownika pełną kontrolę nad pewnym buforem jądra, zaimplementowanym w jądrze używając tego samego typu bufora, jaki jest używany dla potoku. Ogólnie, te wywołania systemowe spełniają następujące role:

przenosi dane z bufora do dowolnego deskryptora pliku lub na odwrót, lub z jednego bufora do innego.
tee(2)
„kopiuje” dane z jednego bufora do drugiego.
vmsplice(2)
„kopiuje” dane z przestrzeni użytkownika do bufora.

Choć mowa tu o kopiowaniu, generalnie unika się faktycznego kopiowania. Jądro dokonuje tego implementując bufor potoku jako zbiór wskaźników, z licznikami odniesień, do stron pamięci jądra. Jądro tworzy „kopie” stron w buforze, tworząc nowe wskaźniki (dla bufora wyjściowego) odnoszące się do stron oraz zwiększając liczniki odniesień do stron: kopiowane są tylko wskaźniki, a nie strony bufora.

_FILE_OFFSET_BITS powinno być zdefiniowane jako 64 w kodzie, który używa wartości off_in lub off_out innych niż null lub takim, który przyjmuje adres splice, jeśli kod ma być przenośny na tradycyjne, 32-bitowe platformy x86 i ARM, w których szerokość off_t domyślnie wynosi 32 bity.

Zob. tee(2).

copy_file_range(2), sendfile(2), tee(2), vmsplice(2), pipe(7)

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.

2 maja 2024 r. Linux man-pages 6.9.1