Provided by: manpages-pl-dev_4.27.0-1_all 
NAZWA
splice - przenosi dane do/z potoku
BIBLIOTEKA
Standardowa biblioteka C (libc, -lc)
SKŁADNIA
#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);
OPIS
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:
SPLICE_F_MOVE
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.
SPLICE_F_NONBLOCK
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).
SPLICE_F_MORE
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)).
SPLICE_F_GIFT
Nieużywane w splice(); zob. vmsplice(2).
WARTOŚĆ ZWRACANA
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.
BŁĘDY
EAGAIN We flags podano SPLICE_F_NONBLOCK lub jeden z deskryptorów plików oznaczono jako nieblokujący
(O_NONBLOCK), natomiast operacja spowodowałaby blokowanie.
EBADF Jeden lub więcej deskryptorów plików nie jest prawidłowych lub nie mają prawidłowego trybu do
odczytu i zapisu.
EINVAL Docelowy system plików nie obsługuje operacji splice.
EINVAL Docelowy plik jest otwarty w trybie dopisywania.
EINVAL Żaden z deskryptorów plików nie odnosi się do potoku.
EINVAL Podano przesunięcie dla urządzenia, które nie jest przewijalne (np. potok).
EINVAL fd_in i fd_out odnoszą się do tego samego potoku.
ENOMEM Brak pamięci.
ESPIPE off_in albo off_out nie miały wartości NULL, a odpowiadający deskryptor pliku odnosił się do
potoku.
STANDARDY
Linux.
HISTORIA
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.
UWAGI
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:
splice()
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.
PRZYKŁADY
Zob. tee(2).
ZOBACZ TAKŻE
copy_file_range(2), sendfile(2), tee(2), vmsplice(2), pipe(7)
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. splice(2)