Provided by: manpages-pl-dev_0.5-1_all 
NAZWA
readv, writev, preadv, pwritev - czytanie lub zapisywanie danych do wielu buforów
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);
Wymagane ustawienia makr biblioteki glibc (patrz feature_test_macros(7)):
preadv(), pwritev(): _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").
Wskaźnik iov prowadzi do struktury iovec zdefiniowanej w pliku <sys/uio.h> następująco:
struct iovec {
void *iov_base; /* Adres początkowy */
size_t iov_len; /* Liczba bajtów do przeniesienia */
};
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.
Transfery danych przeprowadzane przez readv() i writev() są atomowe: dane zapisywane przez
writev() są zapisywane jako pojedynczy blok danych, niekolidujący z danymi zapisywanymi
przez inne procesy (z jednym wyjątkiem, patrz pipe(7)). Analogicznie readv() gwarantuje
przeczytanie sąsiadujących bloków danych, niezależnie od operacji odczytu przeprowadzanych
przez inne wątki lub procesy mające deskryptory plików odnoszące się do tego samego
otwartego pliku (patrz 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).
WARTOŚĆ ZWRACANA
Gdy się powiodą, funkcje readv() i preadv() zwracają liczbę przeczytanych bajtów, a
funkcje writev() i pwritev() zwracają liczbę bajtów zapisanych. W przypadku błędu zwracane
jest -1 i odpowiednio jest ustawiana zmienna errno.
BŁĘDY
Zwracane błędy są takie same, jak w przypadku funkcji read(2) i write(2). Ponadto preadv()
i pwritev() mogą także zwrócić błędy takie jak w przypadku lseek(2). Dodatkowo
zdefiniowany jest następujący błąd:
EINVAL Suma wartości iov_len przekracza rozmiar ssize_t albo liczba iovcnt wektorów jest
mniejsza niż zero lub większa niż dopuszczalne maksimum.
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.
ZGODNE Z
readv(), writev(): BSD 4.4 (wywołania te początkowo pojawiły się w BSD 4.2), POSIX.1-2001.
libc5 w Linuksie używała size_t jako typu parametru iovcnt oraz int jako typu wartości
zwracanej.
preadv(), pwritev(): niestandardowe, ale obecne także w nowoczesnych systemach BSD.
UWAGI
Uwagi linuksowe
Standard POSIX.1-2001 dopuszcza, aby implementacja wprowadziła ograniczenia na liczbę
rekordów przekazywanych w parametrze iov. Limit ten jest określony jako wartość IOV_MAX w
<limits.h>, a w czasie działania programu - jako wartość zwracana przez wywołanie
sysconf(_SC_IOV_MAX). Pod Linuksem limit określony przez te mechanizmy wynosi 1024, co
jest prawdziwym ograniczeniem jądra Linuksa. Jednakże funkcje glibc wykonują 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 tymczasowy bufor, wystarczająco duży, by pomieścić wszystkie elementy określone
przez iov, przekazuje ten bufor wywołaniu systemowemu read(2), kopiuje dane z bufora
tymczasowego do lokalizacji określonych przez iov, a następnie zwalnia pamięć bufora.
Funkcja glibc dla writev() wykonuje analogiczne zadanie, używając bufora tymczasowego i
wywołania funkcji write(2).
BŁĘDY
Nie jest zalecane mieszanie wywołań funkcji operujących na deskryptorach plików, takich
jak readv() czy writev(), z funkcjami biblioteki stdio; rezultaty takiego mieszania nie są
określone i najprawdopodobniej nie będą zgodne z oczekiwaniami.
PRZYKŁAD
Następujący przykładowy kod pokazuje użycie funkcji writev():
char *str0 = "witaj ";
char *str1 = "świecie\n";
struct iovec iov[2];
ssize_t nwritten;
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)
O STRONIE
Angielska wersja tej strony pochodzi z wydania 3.52 projektu Linux man-pages. Opis
projektu oraz informacje dotyczące zgłaszania błędów można znaleźć pod adresem
http://www.kernel.org/doc/man-pages/.
TŁUMACZENIE
Autorami polskiego tłumaczenia niniejszej strony podręcznika man są: Robert Luberda
<robert@debian.org> i Michał Kułach <michal.kulach@gmail.com>.
Polskie tłumaczenie jest częścią projektu manpages-pl; uwagi, pomoc, zgłaszanie błędów na
stronie http://sourceforge.net/projects/manpages-pl/. Jest zgodne z wersją 3.52
oryginału.