.\" -*- coding: UTF-8 -*- .\" Copyright (C) 2007, 2010 Michael Kerrisk .\" and Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) .\" .\" %%%LICENSE_START(VERBATIM) .\" Permission is granted to make and distribute verbatim copies of this .\" manual provided the copyright notice and this permission notice are .\" preserved on all copies. .\" .\" Permission is granted to copy and distribute modified versions of this .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. .\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from .\" the use of the information contained herein. The author(s) may not .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. .\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" %%%LICENSE_END .\" .\" Modified Sat Jul 24 18:34:44 1993 by Rik Faith (faith@cs.unc.edu) .\" Merged readv.[23], 2002-10-17, aeb .\" 2007-04-30 mtk, A fairly major rewrite to fix errors and .\" add more details. .\" 2010-11-16, mtk, Added documentation of preadv() and pwritev() .\" .\"******************************************************************* .\" .\" This file was generated with po4a. Translate the source file. .\" .\"******************************************************************* .TH READV 2 "21 dicembre 2020" Linux "Manuale del programmatore di Linux" .SH NOME readv, writev, preadv, pwritev, preadv2, pwritev2 \- leggono o scrivono dati in buffer multipli .SH SINTASSI .nf \fB#include \fP .PP \fBssize_t readv(int \fP\fIfd\fP\fB, const struct iovec *\fP\fIiov\fP\fB, int \fP\fIiovcnt\fP\fB);\fP .PP \fBssize_t writev(int \fP\fIfd\fP\fB, const struct iovec *\fP\fIiov\fP\fB, int \fP\fIiovcnt\fP\fB);\fP .PP \fBssize_t preadv(int \fP\fIfd\fP\fB, const struct iovec *\fP\fIiov\fP\fB, int \fP\fIiovcnt\fP\fB,\fP \fB off_t \fP\fIoffset\fP\fB);\fP .PP \fBssize_t pwritev(int \fP\fIfd\fP\fB, const struct iovec *\fP\fIiov\fP\fB, int \fP\fIiovcnt\fP\fB,\fP \fB off_t \fP\fIoffset\fP\fB);\fP .PP \fBssize_t preadv2(int \fP\fIfd\fP\fB, const struct iovec *\fP\fIiov\fP\fB, int \fP\fIiovcnt\fP\fB,\fP \fB off_t \fP\fIoffset\fP\fB, int \fP\fIflags\fP\fB);\fP .PP \fBssize_t pwritev2(int \fP\fIfd\fP\fB, const struct iovec *\fP\fIiov\fP\fB, int \fP\fIiovcnt\fP\fB,\fP \fB off_t \fP\fIoffset\fP\fB, int \fP\fIflags\fP\fB);\fP .fi .PP .RS -4 Macro per test di funzionalità per glibc (vedere \fBfeature_test_macros\fP(7)): .RE .PP \fBpreadv\fP(), \fBpwritev\fP(): a partire da glibc 2.19: _DEFAULT_SOURCE Glibc 2.19 e precedenti: _BSD_SOURCE .SH DESCRIZIONE La chiamata di sistema \fBreadv\fP() legge i buffer \fIiovcnt\fP dal file associato al descrittore di file \fIfd\fP nei buffer descritti da \fIiov\fP ("scatter input"). .PP La chiamata di sistema \fBwritev\fP() scrive i buffer di dati \fIiovcnt\fP descritti da \fIiov\fP nel file associato al descrittore di file \fIfd\fP ("gather output"). .PP Il puntatore \fIiov\fP punta a un array di strutture \fIiovec\fP, definite in \fI\fP come: .PP .in +4n .EX struct iovec { void *iov_base; /* Indirizzo di partenza */ size_t iov_len; /* Numero di byte da trasferire */ }; .EE .in .PP La chiamata di sistema \fBreadv\fP() funziona esattamente come \fBread\fP(2) tranne per il fatto che i buffer multipli sono riempiti. .PP La chiamata di sistema \fBwritev\fP() funziona esattamente come \fBwrite\fP(2) tranne per il fatto che i buffer multipli sono svuotati. .PP I buffer sono elaborati in ordine di array. Ciò significa che \fBreadv\fP() riempie completamente \fIiov[0]\fP prima di procedere a \fIiov[1]\fP, e così via. (Se ci sono dati insufficienti allora non tutti i buffer puntati da \fIiov\fP possono essere riempiti) Similarmente, \fBwritev\fP() estrae l'intero contenuto di \fIiov[0]\fP prima di procedere a \fIiov[1]\fP, e così via. .PP .\" Regarding atomicity, see https://bugzilla.kernel.org/show_bug.cgi?id=10596 I trasferimenti di dati eseguiti da \fBreadv\fP() e \fBwritev\fP() sono atomici: il dato scritto da \fBwritev\fP() è scritto come un blocco singolo che non è mescolato con output provenienti da scritture in altri processi (tuttavia si veda \fBpipe\fP(7) per un'eccezione); analogamente, \fBreadv\fP() è 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 \fBopen\fP(2)). .SS "preadv() e pwritev()" La chiamata di sistema \fBpreadv\fP() combina le funzionalità di \fBreadv\fP() e di \fBpread\fP(2). Realizza lo stesso compito di \fBreadv\fP(), ma aggiunge un quarto argomento, \fIoffset\fP, che specifica la posizione nel file (offset) alla quale dev'essere effettuata l'operazione di input. .PP La chiamata di sistema \fBpwritev\fP() combina le funzionalità di \fBwritev\fP() e di \fBpwrite\fP(2). Realizza lo stesso compito di \fBwritev\fP(), ma aggiunge un quarto argomento, \fIoffset\fP, che specifica la posizione nel file (offset) alla quale dev'essere effettuata l'operazione di input. .PP L'offset nel file non viene modificato da queste chiamate di sistema. Il file al quale fa riferimento \fIfd\fP deve poter permettere il posizionamento a un offset. .SS "preadv2() e pwritev2()" Queste chiamate di sistema sono simili alle chiamate \fBpreadv\fP() e \fBpwritev\fP(), ma aggiungono un quinto argomento, \fIflags\fP, che modifica il comportamento a seconda del tipo di chiamata. .PP A differenza di \fBpreadv\fP() e \fBpwritev\fP(), se l'argomento \fIoffset\fP è \-1, viene usato e aggiornato l'offset del file corrente. .PP L'argomento \fIflags\fP contiene un OR binario di zero o più dei seguenti flag: .TP \fBRWF_DSYNC\fP (da Linux 4.7) .\" commit e864f39569f4092c2b2bc72c773b6e486c7e3bd9 Equivale a richiedere a livello di una singola scrittura la funzione richiesta dal flag \fBO_DSYNC\fP di \fBopen\fP(2). Questo flag è significativo solo per \fBpwritev2\fP(), e il suo risultato si applica solo all'intervallo di dati scritto dalla chiamata di sistema. .TP \fBRWF_HIPRI\fP (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 \fBO_DIRECT\fP.) .TP \fBRWF_SYNC\fP (da Linux 4.7) .\" commit e864f39569f4092c2b2bc72c773b6e486c7e3bd9 Costituisce un equivalente per ogni singola scrittura (per\-write) del flag \fBO_SYNC\fP di \fBopen\fP(2). Questo flag è significativo solo per \fBpwritev2\fP(), e il suo risultato si applica solo all'intervallo di dati scritto dalla chiamata di sistema. .TP \fBRWF_NOWAIT\fP (da Linux 4.14) .\" commit 3239d834847627b6634a4139cf1dc58f6f137a46 .\" commit 91f9943e1c7b6638f27312d03fe71fcc67b23571 Non attende i dati che non sono immediatamente disponibili. Se è stato specificato questo flag, la chiamata di sistema \fBpreadv2\fP() 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 \fIerrno\fP a \fBEAGAIN\fP. Attualmente, questo flag è significativo solo per \fBpreadv2\fP(). .TP \fBRWF_APPEND\fP (da Linux 4.16) .\" commit e1fc742e14e01d84d9693c4aca4ab23da65811fb Costituisce un equivalente per ogni singola scrittura (per\-write) del flag \fBO_APPEND\fP \fBopen\fP(2) flag. Questo flag è significativo solo per \fBpwritev2\fP(), e il suo risultato si applica solo all'intervallo di dati scritto dalla chiamata di sistema. L'argomento \fIoffset\fP non influisce sull'operazione di scrittura; i dati sono sempre accodati alla fine del file. Comunque, se l'argomento \fIoffset\fP è \-1, si usa e si aggiorna il file all'offset corrente. .SH "VALORE RESTITUITO" In caso di successo, \fBreadv\fP(), \fBpreadv\fP() e \fBpreadv2\fP() restituiscono il numero di byte letti; \fBwritev\fP(), \fBpwritev\fP() e \fBpwritev2\fP() restituiscono il numero di byte scritti. .PP Si noti che non è un errore per una chiamata andata a buon fine trasferire meno byte di quelli richiesti (si veda \fBread\fP(2) e \fBwrite\fP(2)). .PP In caso di errore viene restituito \-1 , e \fIerrno\fP è impostato appropriatamente. .SH ERRORI Gli errori sono gli stessi di \fBread\fP(2) e \fBwrite\fP(2). Per di più, \fBpreadv\fP(), \fBpreadv2\fP(), \fBpwritev\fP(), e \fBpwritev2\fP() possono anche non andare a buon fine per le stesse ragioni di \fBlseek\fP(2). Inoltre sono definiti i seguenti errori: .TP \fBEINVAL\fP La somma dei valori \fIiov_len\fP supera un valore \fIssize_t\fP. .TP \fBEINVAL\fP Il vettore conteggio, \fIiovcnt\fP, è minore di zero o maggiore del massimo permesso. .TP \fBEOPNOTSUPP\fP Un flag sconosciuto è specificato in \fIflags\fP. .SH VERSIONI \fBpreadv\fP() e \fBpwritev\fP() sono apparse per la prima volta in Linux 2.6.30; il supporto alla libreria è stato aggiunto in glibc 2.10. .PP \fBpreadv2\fP() e \fBpwritev2\fP() sono apparse per la prima volta in Linux 4.6. Il supporto alla libreria è stato aggiunto in glibc 2.26. .SH "CONFORME A" .\" Linux libc5 used \fIsize_t\fP as the type of the \fIiovcnt\fP argument, .\" and \fIint\fP as the return type. .\" The readv/writev system calls were buggy before Linux 1.3.40. .\" (Says release.libc.) \fBreadv\fP(), \fBwritev\fP(): POSIX.1\-2001, POSIX.1\-2008, 4.4BSD (queste chiamate di sistema sono apparse per la prima volta in 4.2BSD). .PP \fBpreadv\fP(), \fBpwritev\fP(): non standard, però presente anche nei sistemi BSD moderni. .PP \fBpreadv2\fP(), \fBpwritev2\fP(): Estensione Linux non standard. .SH NOTE .\" .\" POSIX.1 permette un'implementazione per porre un limite al numero di elementi che possono essere passati in \fIiov\fP. Un'implementazione può pubblicizzare i suoi limiti definendo \fBIOV_MAX\fP in \fI\fP o in run time attraverso il valore restituito da \fIsysconf(_SC_IOV_MAX)\fP. Sui sistemi Linux moderni, il limite è 1024, prima di Linux 2.0 questo limite era 16. .SS "Differenze tra la libreria C e il kernel" Le chiamate di sistema dirette \fBpreadv\fP() e \fBpwritev\fP() hanno firme che differiscono leggermente da quelle delle corrispondenti funzioni wrapper della libreria GNU C viste nella SINTASSI. L'argomento finale, \fIoffset\fP, è spacchettato dalle funzioni wrapper in due argomenti nelle chiamate di sistema: .PP \fB unsigned long \fP\fIpos_l\fP\fB, unsigned long \fP\fIpos\fP .PP Questi argomenti contengono, rispettivamente, i 32 bit meno significativi e i 32 bit più significativi di \fIoffset\fP. .SS "Precedenti differenze tra la libreria C e il kernel" Per affrontare il fatto che \fBIOV_MAX\fP era così basso nelle prime versioni di Linux, le funzioni wrapper di glibc per \fBreadv\fP() e \fBwritev\fP() facevano un lavoro aggiuntivo se rilevavano che la sottostante chiamata di sistema al kernel falliva perché era stato superato questo limite. Nel caso di \fBreadv\fP() la funzione wrapper allocava un buffer temporaneo abbastanza grande per tutti gli elementi specificati da \fIiov\fP, passava questo buffer in una chiamata a \fBread\fP(2), copiava i dati dal buffer alle posizioni specificate dai campi \fIiov_base\fP degli elementi di \fIiov\fP, e infine liberava il buffer. La funzione wrapper per \fBwritev\fP() eseguiva l'attività analoga usando un buffer temporaneo e una chiamata a \fBwrite\fP(2). .PP La necessità di questo sforzo aggiuntivo nelle funzioni wrappr glibc si rilevò con le versioni di Linux 2.2 e superiori. Comunque, glibc continuò 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 più vecchio della versione 2.6.18 (unna 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 le chiamate di sistema direttamente. .SH ESEMPI Il seguente codice di esempio mostra l'uso di \fBwritev\fP(): .PP .in +4n .EX char *str0 = "hello "; char *str1 = "world\en"; 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); .EE .in .SH "VEDERE ANCHE" \fBpread\fP(2), \fBread\fP(2), \fBwrite\fP(2) .SH COLOPHON Questa pagina fa parte del rilascio 5.10 del progetto Linux \fIman\-pages\fP. Una descrizione del progetto, le istruzioni per la segnalazione degli errori, e l'ultima versione di questa pagina si trovano su \%https://www.kernel.org/doc/man\-pages/. .SH TRADUZIONE La traduzione italiana di questa pagina di manuale è stata creata da Giulio Daprelà e Marco Curreli . Questa traduzione è documentazione libera; leggere la .UR https://www.gnu.org/licenses/gpl-3.0.html GNU General Public License Versione 3 .UE 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 .MT pluto-ildp@lists.pluto.it .ME .