Provided by: manpages-pl-dev_0.5-1_all bug

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.