readv(2) System Calls Manual readv(2) NOME readv, writev, preadv, pwritev, preadv2, pwritev2 - leggono o scrivono dati in buffer multipli LIBRERIA Libreria C standard (libc, -lc) SINTASSI #include 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 funzionalita 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"). Il puntatore iov punta a un array di strutture iovec, descritte 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. Cio significa che readv() riempie completamente iov[0] prima di procedere a iov[1], e cosi 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 cosi via. I trasferimenti di dati eseguiti da readv() e writev() sono atomici: il dato scritto da writev() e scritto come un blocco singolo che non e mescolato con output provenienti da scritture in altri processi ; analogamente, readv() e 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 funzionalita 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 funzionalita 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 e -1, viene usato e aggiornato l'offset del file corrente. L'argomento flags contiene un OR binario di zero o piu 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 e 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 priorita. 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 puo implicare il consumo di ulteriori risorse. (Attualmente, questa funzionalita e 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 e 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 e 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 e stato letto con successo, restituisce il numero di byte letti. Se non e stato letto nessun byte, restituisce -1 e imposta errno a EAGAIN (pero si veda BUGS). Attualmente, questo flag e 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 e 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 e -1, si usa e si aggiorna il file all'offset corrente. RWF_NOAPPEND (da Linux 6.9) Ignora il flag O_APPEND passato ad open(2). Questo flag ha significato solo per pwritev2(). Storicamente Linux ha utilizzato il flag O_APPEND se impostato, ignorando l'argomento offset, che e un bug. In pwritev2() l'offset e gestito correttamente quando il flag RWF_NOAPPEND e impostato, esattamente come se il flag O_APPEND non fosse impostato. RWF_ATOMIC (da Linux 6.11) Richiede che le scrittura su file normali che si trovano su filesystem a blocchi, siano fatte con la protezione "torn-write", vale a dire che se mancasse la corrente o ci fosse un guasto hardware, tutti i dati sono scritti in un colpo solo, senza che la scrittura sia parziale. Questo flag ha significato solo per pwritev2(), e il suo effetto si applica solo all'intervallo di dati scritti dalla chiamata di sistema. La dimensione totale della scrittura deve essere una potenza di 2 e deve stare nell'intervallo [stx_atomic_write_unit_min, stx_atomic_write_unit_max]. La scrittura deve partire da un'offset che sia allineato naturalmente in rapporto alla dimensione totale della scrittura. Per esempio: una scrittura di lunghezza 32KiB dall'offste 32KiB e permessa, ma una di 32KiB dall'offset 48KiB non lo e. Il limite superiore di iovcnt per pwritev2() e dato dal valore in stx_atomic_write_segments_max. La protezione "torn-write" funziona solo col flag O_DIRECT, vale a dire che le scrittura bufferizzate non sono supportate. Per garantire la consistenza con la scrittura dello stato interno del file e il device di archiviazione, deve essere specificato O_SYNC o O_DSYNC durante la open(2). Le stesse I/O sincronizzate garantite come descritto in open(2) sono fornite quando questi flag o i loro equivalenti e le chiamate di sistema sono usate (ad esempio se RWF_SYNC e specificato in pwritev2()). RWF_DONTCACHE (da Linux 6.14) Le letture e scritture da/su file normali scarteranno il contenuto dalle pagine della cache appena l'operazione termina. Questo e diverso dal normale I/O bufferizzato nel quale i dati normalmente rimangono in cache fino al momento che le pagine siano richieste per altri motivi. Se alcune parti di queste I/O in lettura o scrittura fossero gia nella cache prima della lettura o scrittura, queste non verranno scartate al completamente dell'operazione. Inoltre, ogni intervallo di dati sporcato dall'operazione di scrittura con RWF_DONTCACHE impostato, sara avviato al "writeback". Questo e analogo a chiamare sync_file_range(2) con SYNC_FILE_RANGE_WRITE per avviare il "writeback" su un certo intervallo di dati. RWF_DONTCACHE e una richiesta da eseguire al meglio, senza pero una garanzia sullo stato della cache una volta completata l'operazione. Se utilizzato su un file system o un device a blocchi che non la supporta, restituisce -1 e imposta errno a EOPNOTSUPP. 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 e 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 e impostato per indicare l'errore. ERRORI Gli errori sono gli stessi di read(2) e write(2). Per di piu, 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 Se e stato indicato RWF_ATOMIC, la somma dei valori di iov_len e di offset non soddisfa le regole per la lunghezza e l'offset indicate dalla protezione "torn-write". EINVAL Il vettore contatore, iovcnt, e inferiore a zero o maggiore nel massimo permesso. Se e stato indicato RWF_ATOMIC, il massimo e dato dal valore di stx_atomic_write_segments_max in statx. EOPNOTSUPP Se e stato impostato RWF_DONTCACHE tra i flag e il file non lo supporta. EOPNOTSUPP Un flag sconosciuto e specificato in flags. VERSIONI 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, e 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 piu significativi di offset. CONFORME A readv() writev() POSIX.1-2024. preadv() pwritev() BSD. preadv2() pwritev2() Linux. STORIA readv() writev() POSIX.1-2001, 4.4BSD (apparse per la prima volta in 4.2BSD). preadv(), pwritev(): Linux 2.6.30, glibc 2.10. preadv2(), pwritev2(): Linux 4.6, glibc 2.26. Precedenti differenze tra la libreria C e il kernel Per affrontare il fatto che IOV_MAX era cosi 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 perche 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'attivita analoga usando un buffer temporaneo e una chiamata a write(2). La necessita di questo sforzo aggiuntivo nelle funzioni wrappr glibc venne meno con le versioni di Linux 2.2 e superiori. Comunque, glibc continuo con questo comportamento fino alla versione 2.10. A partire da glibc versione 2.9, le funzioni wrapper prevedono questo comportamento solo se la libreria rileva che il sistema sta eseguendo un kernel Linux piu vecchio della versione 2.6.18 (una versione del kernel scelta arbitrariamente). E da glibc 2.20 (che richiede una versione del kernel Linux superiore alla 2.6.32), le funzioni wrapper di glibc invocano sempre direttamente le chiamate di sistema. NOTE POSIX.1 permette un'implementazione per porre un limite al numero di elementi che possono essere passati in iov. Un'implementazione puo pubblicizzare i suoi limiti definendo IOV_MAX in o in run time attraverso il valore restituito da sysconf(_SC_IOV_MAX). Sui sistemi Linux moderni, il limite e 1024, prima di Linux 2.0 questo limite era 16. BUG Linux 5.9 and 5.10 hanno un bug dove preadv2() col flag RWF_NOWAIT puo restituire 0 anche se non e alla fine del file. ESEMPI Il seguente codice di esempio mostra l'uso di writev(): char *str0 = "salve "; char *str1 = "mondo\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 e stata creata da Giulio Daprela , Marco Curreli e Giuseppe Sacco Questa traduzione e documentazione libera; leggere la GNU General Public License Versione 3 o successiva per le condizioni di copyright. Non ci assumiamo alcuna responsabilita. Per segnalare errori nella traduzione di questa pagina di manuale inviare un messaggio a . Linux man-pages 6.17 8 febbraio 2026 readv(2)