readv

NAZWA

readv, writev, preadv, pwritev, preadv2, pwritev2 - czytanie lub zapisywanie danych do wielu buforów

BIBLIOTEKA

Standardowa biblioteka C ( libc, -lc)

SKŁADNIA

#include <sys/uio.h>

ssize_t readv(int fd, const struct iovec *iov, int iovcnt);
ssize_t writev(int fd, const struct iovec *iov, int iovcnt);

ssize_t preadv(int fd, const struct iovec *iov, int iovcnt,
                off_t offset);
ssize_t pwritev(int fd, const struct iovec *iov, int iovcnt,
                off_t offset);

ssize_t preadv2(int fd, const struct iovec *iov, int iovcnt,
                off_t offset, int flags);
ssize_t pwritev2(int fd, const struct iovec *iov, int iovcnt,
                off_t offset, int flags);

preadv(), pwritev():

    Od glibc 2.19:
        _DEFAULT_SOURCE
    glibc 2.19 i wcześniejsze:
        _BSD_SOURCE

OPIS

Wywołanie systemowe readv() czyta liczbę iovcnt bloków z pliku skojarzonego z deskryptorem pliku fd do wielu buforów opisanych przez iov ("rozrzucone wejście"). Funkcja writev() zapisuje co najwyżej iovcnt bloków opisanych przez iov do pliku skojarzonego z deskryptorem pliku fd ("zgromadzone wyjście"). The pointer iov points to an array of iovec structures, described in iovec(3type). Wywołanie systemowe readv() działa tak samo jak read(2), z tą różnicą że wypełnianych jest wiele buforów. Wywołanie systemowe writev() działa tak samo jak write(2), z tą różnicą że zapisywane dane pochodzą z wielu buforów. Bufory są przetwarzane w porządku, w którym zostały wymienione w tablicy. Oznacza to, że readv() całkowicie zapełni iov[0] zanim przejdzie do iov[1] itd. (jeśli jest za mało danych, to nie wszystkie bufory w iov zostaną wypełnione). Podobnie writev zapisuje całkowicie zawartość iov[0], zanim przejdzie do iov[1], itd. The data transfers performed by readv() and writev() are atomic: the data written by writev() is written as a single block that is not intermingled with output from writes in other processes; analogously, readv() is guaranteed to read a contiguous block of data from the file, regardless of read operations performed in other threads or processes that have file descriptors referring to the same open file description (see open(2)).

preadv() i pwritev()

Wywołanie systemowe preadv() łączy w sobie funkcjonalności dostarczane przez readv() i przez pread(2). Wykonuje to samo zadanie, co readv(), ale dodaje czwarty argument, offset, określający miejsce w pliku, w którym zostanie przeprowadzona operacja wejściowa. Wywołanie systemowe pwritev() łączy w sobie funkcjonalności dostarczane przez writev() i przez pwrite(2). Wykonuje to samo zadanie, co writev, ale dodaje czwarty argument, offset, określający miejsce w pliku, w którym zostanie przeprowadzona operacja wyjściowa. Opisywane wywołania systemowe nie zmieniają pozycji przesunięcia w pliku. Pliki wskazywane przez fd muszą pozwalać na swobodny dostęp (przeszukiwanie).

preadv2() i pwritev2()

Te wywołania systemowe są podobne do wywołań preadv() i pwritev(), lecz dodają piąty argument flags, modyfikujący zachowanie w zależności od wywołania. W przeciwieństwie do preadv() i pwritev(), jeśli argument offset wynosi -1, to używane i aktualizowane jest przesunięcie bieżącego pliku. Argument flags zawiera bitowe LUB z jednej lub więcej z następujących flag:

RWF_DSYNC (od Linuksa 4.7)

Provide a per-write equivalent of the O_DSYNC open(2) flag. This flag is meaningful only for pwritev2(), and its effect applies only to the data range written by the system call.

RWF_HIPRI (od Linuksa 4.6)

Odczyt/zapis o wysokim priorytecie. Pozwala blokowym systemom plików na odpytywanie urządzenia, co zapewnia niższe opóźnienia, lecz może wymagać dodatkowych zasobów (obecnie ta funkcja nadaje się do użycia wyłącznie, jeśli deskryptor pliku otwarto z flagą O_DIRECT).

RWF_SYNC (od Linuksa 4.7)

Provide a per-write equivalent of the O_SYNC open(2) flag. This flag is meaningful only for pwritev2(), and its effect applies only to the data range written by the system call.

RWF_NOWAIT (od Linuksa 4.14)

Do not wait for data which is not immediately available. If this flag is specified, the preadv2() system call will return instantly if it would have to read data from the backing storage or wait for a lock. If some data was successfully read, it will return the number of bytes read. If no bytes were read, it will return -1 and set errno to EAGAIN (but see BUGS). Currently, this flag is meaningful only for preadv2().

RWF_APPEND (od Linuksa 4.16)

Provide a per-write equivalent of the O_APPEND open(2) flag. This flag is meaningful only for pwritev2(), and its effect applies only to the data range written by the system call. The offset argument does not affect the write operation; the data is always appended to the end of the file. However, if the offset argument is -1, the current file offset is updated.

WARTOŚĆ ZWRACANA

Gdy się powiodą, funkcje readv(), preadv() i preadv2() zwracają liczbę przeczytanych bajtów, a funkcje writev(), pwritev() i pwritev2() zwracają liczbę bajtów zapisanych. Proszę zauważyć, że nie jest błędem przesłanie mniejszej liczby bajtów niż żądano przez poprawne wywołanie (zob. read(2) i write(2)). On error, -1 is returned, and errno is set to indicate the error.

BŁĘDY

Zwracane błędy są takie same, jak w przypadku funkcji read(2) i write(2). Ponadto preadv(), preadv2(), pwritev() i pwritev2() mogą także zwrócić błędy takie jak w przypadku lseek(2). Dodatkowo zdefiniowane są następujące błędy:

EINVAL

Suma wartości iov_len przekracza rozmiar ssize_t.

EINVAL

Liczba iovcnt wektorów jest mniejsza niż zero lub większa niż dopuszczalne maksimum.

EOPNOTSUPP

Jako flags podano nieznaną flagę.

WERSJE

preadv() i pwritev() po raz pierwszy pojawiły się w Linuksie 2.6.30; wsparcie biblioteczne tych wywołań pojawiło się w glibc 2.10. preadv2() i pwritev2() po raz pierwszy pojawiły się w Linuksie 4.6; wsparcie biblioteczne tych wywołań pojawiło się w glibc 2.26.

STANDARDY

readv(), writev(): POSIX.1-2001, POSIX.1-2008, 4.4BSD (wywołania te początkowo pojawiły się w BSD 4.2). preadv(), pwritev(): niestandardowe, ale obecne także w nowoczesnych systemach BSD. preadv2(), pwritev2(): niestandardowe rozszerzenie systemu Linux.

UWAGI

POSIX.1 pozwala w implementacji umieścić ograniczenie liczby argumentów, które mogą być przekazane w iov. Implementacja może rozgłosić ten limit definiując IOV_MAX w <limits.h> lub w czasie uruchomienia, zwracaną wartością z sysconf(_SC_IOV_MAX). Na współczesnych systemach Linux limit ten wynosi 1024. W czasach Linuksa 2.0 wynosił 16.

Różnice biblioteki C/jądra

Surowe wywołania systemowe preadv() i pwritev() mają sygnatury wywołań różniące się subtelnie od odpowiadających im w funkcji opakowującej biblioteki GNU C pokazanych w SKŁADNI. Ostatni argument offset, jest rozpakowany przez funkcję opakowującą na dwa argumenty wywołania systemowego: unsigned long pos_l, unsigned long pos Argumenty te zawierają 32 bitowy offset w kolejności odpowiednio, od najmniej i od najbardziej znaczącego bitu.

Historyczne różnice biblioteki C/jądra

Aby rozwiązać sytuację, gdy IOV_MAX było tak niskie we wczesnych wersjach Linuksa, funkcje opakowujące readv() i writev() wykonywały pewne dodatkowe działania po wykryciu, że odpowiednie wywołanie systemowe zakończyło się błędem z powodu przekroczenia limitu. W takim wypadku funkcja readv() biblioteki glibc przydzielała tymczasowy bufor, wystarczająco duży, by pomieścić wszystkie elementy określone przez iov, przekazywała ten bufor wywołaniu systemowemu read(2), kopiowała dane z bufora tymczasowego do lokalizacji określonych przez iov, a następnie zwalniała pamięć bufora. Funkcja glibc dla writev() wykonywała analogiczne zadanie, używając bufora tymczasowego i wywołania funkcji write(2). The need for this extra effort in the glibc wrapper functions went away with Linux 2.2 and later. However, glibc continued to provide this behavior until glibc 2.10. Starting with glibc 2.9, the wrapper functions provide this behavior only if the library detects that the system is running a Linux kernel older than Linux 2.6.18 (an arbitrarily selected kernel version). And since glibc 2.20 (which requires a minimum of Linux 2.6.32), the glibc wrapper functions always just directly invoke the system calls.

BŁĘDY

Linux 5.9 and Linux 5.10 have a bug where preadv2() with the RWF_NOWAIT flag may return 0 even when not at end of file.

PRZYKŁADY

Następujący przykładowy kod pokazuje użycie funkcji writev():

char          *str0 = "hello ";
char          *str1 = "world\n";
ssize_t       nwritten;
struct iovec  iov[2];

iov[0].iov_base = str0;
iov[0].iov_len = strlen(str0);
iov[1].iov_base = str1;
iov[1].iov_len = strlen(str1);

nwritten = writev(STDOUT_FILENO, iov, 2);

ZOBACZ TAKŻE

pread(2), read(2), write(2)

TŁUMACZENIE

Autorami polskiego tłumaczenia niniejszej strony podręcznika są: Robert Luberda <[email protected]> i Michał Kułach <[email protected]> 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 [email protected]