Provided by: manpages-it-dev_4.19.0-7_all 
NOME
readv, writev, preadv, pwritev, preadv2, pwritev2 - leggono o scrivono dati in buffer
multipli
LIBRARY
Standard C library (libc, -lc)
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);
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);
Macro per test di funzionalità per glibc (vedere feature_test_macros(7)):
preadv(), pwritev():
A partire da glibc 2.19:
_DEFAULT_SOURCE
glibc 2.19 e precedenti:
_BSD_SOURCE
DESCRIZIONE
La chiamata di sistema readv() legge i buffer iovcnt dal file associato al descrittore di
file fd nei buffer descritti da iov ("scatter input").
La chiamata di sistema writev() scrive i buffer di dati iovcnt descritti da iov nel file
associato al descrittore di file fd ("gather output").
The pointer iov points to an array of iovec structures, described in iovec(3type).
La chiamata di sistema readv() funziona esattamente come read(2) tranne per il fatto che i
buffer multipli sono riempiti.
La chiamata di sistema writev() funziona esattamente come write(2) tranne per il fatto che
i buffer multipli sono svuotati.
I buffer sono elaborati in ordine di array. 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 che non è mescolato con output provenienti da
scritture in altri processi ; 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)).
preadv() e pwritev()
La chiamata di sistema preadv() combina le funzionalità di readv() e di pread(2). Realizza
lo stesso compito di readv(), ma aggiunge un quarto argomento, offset, che specifica la
posizione nel file (offset) alla quale dev'essere effettuata l'operazione di input.
La chiamata di sistema pwritev() combina le funzionalità di writev() e di pwrite(2).
Realizza lo stesso compito di writev(), ma aggiunge un quarto argomento, offset, che
specifica la posizione nel file (offset) alla quale dev'essere effettuata l'operazione di
input.
L'offset nel file non viene modificato da queste chiamate di sistema. Il file al quale fa
riferimento fd deve poter permettere il posizionamento a un offset.
preadv2() e pwritev2()
Queste chiamate di sistema sono simili alle chiamate preadv() e pwritev(), ma aggiungono
un quinto argomento, flags, che modifica il comportamento a seconda del tipo di chiamata.
A differenza di preadv() e pwritev(), se l'argomento offset è -1, viene usato e aggiornato
l'offset del file corrente.
L'argomento flags contiene un OR binario di zero o più dei seguenti flag:
RWF_DSYNC (da Linux 4.7)
Equivale a richiedere a livello di una singola scrittura la funzione richiesta dal
flag O_DSYNC di open(2). Questo flag è significativo solo per pwritev2(), e il suo
risultato si applica solo all'intervallo di dati scritto dalla chiamata di sistema.
RWF_HIPRI (da Linux 4.6)
Lettura/scrittura ad alta priorità. Permette ai filesystem basati su blocchi di
usare la funzione di polling (interrogazione periodica) del dispositivo, il che
permette di abbreviare il periodo di latenza, ma può implicare il consumo di
ulteriori risorse. (Attualmente, questa funzionalità è usabile solo su un
descrittore di fileaperto usando il flag O_DIRECT.)
RWF_SYNC (da Linux 4.7)
Costituisce un equivalente per ogni singola scrittura (per-write) del flag O_SYNC
di open(2). Questo flag è significativo solo per pwritev2(), e il suo risultato si
applica solo all'intervallo di dati scritto dalla chiamata di sistema.
RWF_NOWAIT (da Linux 4.14)
Non attende i dati che non sono immediatamente disponibili. Se è stato specificato
questo flag, la chiamata di sistema preadv2() torna al chiamante senza fare nulla
se i dati da leggere devono essere rintracciati da disco o se occorre attendere per
un lock Se qualche dato è stato letto con successo, restituisce il numero di byte
letti. Se non è stato letto nessun byte, restituisce -1 e imposta errno a EAGAIN
(però si veda BUGS). Attualmente, questo flag è significativo solo per preadv2().
RWF_APPEND (da Linux 4.16)
Costituisce un equivalente per ogni singola scrittura (per-write) del flag O_APPEND
open(2) flag. Questo flag è significativo solo per pwritev2(), e il suo risultato
si applica solo all'intervallo di dati scritto dalla chiamata di sistema.
L'argomento offset non influisce sull'operazione di scrittura; i dati sono sempre
accodati alla fine del file. Comunque, se l'argomento offset è -1, si usa e si
aggiorna il file all'offset corrente.
VALORE RESTITUITO
In caso di successo, readv(), preadv() e preadv2() restituiscono il numero di byte letti;
writev(), pwritev() e pwritev2() restituiscono il numero di byte scritti.
Si noti che non è un errore per una chiamata andata a buon fine trasferire meno byte di
quelli richiesti (si veda read(2) e write(2)).
In caso di errore viene restituito -1 , e errno è impostato per indicare l'errore.
ERRORI
Gli errori sono gli stessi di read(2) e write(2). Per di più, preadv(), preadv2(),
pwritev(), e pwritev2() possono anche non andare a buon fine per le stesse ragioni di
lseek(2). Inoltre sono definiti i seguenti errori:
EINVAL La somma dei valori iov_len supera un valore ssize_t.
EINVAL Il vettore conteggio, iovcnt, è minore di zero o maggiore del massimo permesso.
EOPNOTSUPP
Un flag sconosciuto è specificato in flags.
VERSIONI
preadv() e pwritev() sono apparse per la prima volta in Linux 2.6.30; il supporto alla
libreria è stato aggiunto in glibc 2.10.
preadv2() e pwritev2() sono apparse per la prima volta in Linux 4.6. Il supporto alla
libreria è stato aggiunto in glibc 2.26.
STANDARDS
readv(), writev(): POSIX.1-2001, POSIX.1-2008, 4.4BSD (queste chiamate di sistema sono
apparse per la prima volta in 4.2BSD).
preadv(), pwritev(): non standard, però presente anche nei sistemi BSD moderni.
preadv2(), pwritev2(): Estensione Linux non standard.
NOTE
POSIX.1 permette un'implementazione per porre un limite al numero di elementi che possono
essere passati in iov. Un'implementazione può pubblicizzare i suoi limiti definendo
IOV_MAX in <limits.h> o in run time attraverso il valore restituito da
sysconf(_SC_IOV_MAX). Sui sistemi Linux moderni, il limite è 1024, prima di Linux 2.0
questo limite era 16.
Differenze tra la libreria C e il kernel
Le chiamate di sistema dirette preadv() e pwritev() hanno firme che differiscono
leggermente da quelle delle corrispondenti funzioni wrapper della libreria GNU C viste
nella SINTASSI. L'argomento finale, offset, è spacchettato dalle funzioni wrapper in due
argomenti nelle chiamate di sistema:
unsigned long pos_l, unsigned long pos
Questi argomenti contengono, rispettivamente, i 32 bit meno significativi e i 32 bit più
significativi di offset.
Precedenti differenze tra la libreria C e il kernel
Per affrontare il fatto che IOV_MAX era così basso nelle prime versioni di Linux, le
funzioni wrapper di glibc per readv() e writev() facevano un lavoro aggiuntivo se
rilevavano che la sottostante chiamata di sistema al kernel falliva perché era stato
superato questo limite. Nel caso di readv() la funzione wrapper allocava un buffer
temporaneo abbastanza grande per tutti gli elementi specificati da iov, passava questo
buffer in una chiamata a read(2), copiava i dati dal buffer alle posizioni specificate dai
campi iov_base degli elementi di iov, e infine liberava il buffer. La funzione wrapper per
writev() eseguiva l'attività analoga usando un buffer temporaneo e una chiamata a
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.
BUG
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.
ESEMPI
Il seguente codice di esempio mostra l'uso di 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);
VEDERE ANCHE
pread(2), read(2), write(2)
TRADUZIONE
La traduzione italiana di questa pagina di manuale è stata creata da Giulio Daprelà
<giulio@pluto.it> e Marco Curreli <marcocurreli@tiscali.it>
Questa traduzione è documentazione libera; leggere la GNU General Public License Versione
3 ⟨https://www.gnu.org/licenses/gpl-3.0.html⟩ o successiva per le condizioni di copyright.
Non ci assumiamo alcuna responsabilità.
Per segnalare errori nella traduzione di questa pagina di manuale inviare un messaggio a
⟨pluto-ildp@lists.pluto.it⟩.