NAME

       readv, writev - legge o scrive dati in buffer multipli

SINTASSI

       #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);

DESCRIZIONE

       La funzione readv() legge i buffer iovcnt dal file associato al descrittore di file fd nei
       buffer descritti da iov ("scatter input").

       La funzione writev() scrive i buffer di dati iovcnt descritti da iov nel file associato al
       descrittore di file fd ("gather output").

       Il puntatore iov punta a una matrice di iovec strutture, definite in <sys/uio.h> come:

         struct iovec {
             void  *iov_base;    /* Starting address */
             size_t iov_len;     /* Number of bytes to transfer */
         };

       La  funzione  readv()  funzione  esattamente come read(2) tranne per il fatto che i buffer
       multipli sono riempiti.

       La funzione writev() funzione esattamente come write(2) tranne per il fatto che  i  buffer
       multipli sono svuotati.

       I  buffer  sono  processati  in  ordine  matriciale  Ciò  significa  che  readv()  riempie
       completamente iov[0] prima  di  procedere  a  iov[1],  e  così  via.   (Se  ci  sono  dati
       insufficienti  allora  non  tutti  i  buffer  puntati  da  iov  possono  essere  riempiti)
       Similarmente, writev() estrae l'intero contenuto di iov[0] prima di procedere a iov[1],  e
       così via.

       I  trasferimenti  di  dati eseguiti da readv() e writev() sono atomici: il dato scritto da
       writev() è scritto come un blocco singolo mescolato con output provenienti da scritture in
       altri  processi  (tuttavia  si  veda  pipe(7)  per  un'eccezione); analogamente, readv() è
       garantito che  legga  un  blocco  contiguo  di  dati  dal  file,  indipendentemente  dalle
       operazioni  di  lettura  eseguite in altri thread o processi che hanno descrittori di file
       che fanno riferimento alla stessa descrizione di file aperto (si veda open(2)).

VALORE RESTITUITO

       In caso di successo la funzione readv() restituisce il numero di byte letti;  la  funzione
       writev()  restituisce il numero di byte scritti.  In caso di erroreviene restituito -1 , e
       errno è impostato appropriatamente.

ERRORI

       Gli errori sono gli stessi di read(2) e write(2).  Inoltre è definito il seguente errore:

       EINVAL La somma dei valori  iov_len  supera  un  valore  ssize_t  .   Oppure,  il  vettore
              conteggio iovcnt è meno di zero o maggiore del massimo permesso.

CONFORME A

       4.4BSD  (le  funzioni  readv()  e  writev()  sono  apparse  per la prima volta in 4.2BSD),
       POSIX.1-2001.  Linux libc5 usava size_t come tipo per il parametro iovcnt  ,  e  int  come
       tipo restituito per queste funzioni.

NOTE LINUX

       POSIX.1-2001  permette  un'implementazione  per  porre un limite al numero di elementi che
       possono essere passati  in  iov.   Un'implementazione  può  pubblicizzare  i  suoi  limiti
       impostando  IOV_MAX  in  <limits.h>  o  in  run  time  attraverso  il valore restituito da
       sysconf(_SC_IOV_MAX).  Su Linux, il limite pubblicizzato per questo meccanismo è 1024, che
       è  il limite reale del kernel.  Tuttavia, le funzioni wrapper glibc fanno del lavoro extra
       se rilevano che la chiamata di sistema del kernel sottostante ha  fallito  perché  i  suoi
       limiti  sono  stati  superati.   Nel  caso di readv() la funzione wrapper alloca un buffer
       temporaneo abbastanza grande per tutti gli  elementi  specificati  da  iov,  passa  questo
       buffer  in  una  chiamata a read(), copia i dati dal buffer alle locazioni specificate dai
       campi iov_base degli elementi di iov, e infine libera il buffer.  La funzione wrapper  per
       writev() esegue la task analoga usando un buffer temporaneo e una chiamata a write().

BUG

       Non è consigliabile mischiare chiamate a funzioni come readv() o writev(), che operano sui
       descrittori dei file,  con  le  funzioni  della  libreria  stdio;  i  risultati  sarebbero
       indefiniti e probabilmente on ciò che si vuole.

ESEMPIO

       Il seguente codice di esempio mostra l'uso di writev():

            char *str0 = "hello ";
            char *str1 = "world\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);

VEDERE ANCHE

       read(2), write(2)

                                            2002-10-17                                   READV(2)