.\" 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() .\" .\" Traduzione da man-pages-2.16 di Giulio Daprelà .\" dicembre 2005 .\" Aggiornamento a man-pages-2.38 di Giulio Daprelà - agosto 2006 .\" Aggiornamento a man-pages-2.49 di Giulio Daprelà - giugno 2007 .\" Aggiornamento a man-pages-3.53 di Marco Curreli .\" agosto 2013 .\" Aggiornamento a man-pages-3.72 di Marco Curreli - settembre 2014 .\" .TH READV 2 2014-08-19 "Linux" "Linux Programmer's Manual" .SH NOME readv, writev, preadv, pwritev \- leggono o scrivono dati in buffer multipli .SH SINTASSI .nf .B #include .sp .BI "ssize_t readv(int " fd ", const struct iovec *" iov ", int " iovcnt ); .sp .BI "ssize_t writev(int " fd ", const struct iovec *" iov ", int " iovcnt ); .sp .BI "ssize_t preadv(int " fd ", const struct iovec *" iov ", int " iovcnt , .BI " off_t " offset ); .sp .BI "ssize_t pwritev(int " fd ", const struct iovec *" iov ", int " iovcnt , .BI " off_t " offset ); .fi .sp .in -4n Macro per test di funzionalità richieste per glibc (si veda .BR feature_test_macros (7)): .in .sp .BR preadv (), .BR pwritev (): _BSD_SOURCE .SH DESCRIZIONE La chiamata di sistema .BR readv () legge i buffer .I iovcnt dal file associato al descrittore di file .I fd nei buffer descritti da .I iov ("scatter input"). .PP La chiamata di sistema .BR writev () scrive i buffer di dati .I iovcnt descritti da .I iov nel file associato al descrittore di file .I fd ("gather output"). .PP Il puntatore .I iov punta a un array di strutture .I iovec , definite in .I come: .PP .br .in +4n .nf struct iovec { void *iov_base; /* Starting address */ size_t iov_len; /* Number of bytes to transfer */ }; .fi .in .PP La chiamata di sistema .BR readv () funzione esattamente come .BR read (2) tranne per il fatto che i buffer multipli sono riempiti. .PP La chiamata di sistema .BR writev () funzione esattamente come .BR write (2) tranne per il fatto che i buffer multipli sono svuotati. .PP I buffer sono elaborati in ordine di array Ciò significa che .BR readv () riempie completamente .IR iov [0] prima di procedere a .IR iov [1], e così via. (Se ci sono dati insufficienti allora non tutti i buffer puntati da .I iov possono essere riempiti) Similarmente, .BR writev () estrae l'intero contenuto di .IR iov [0] prima di procedere a .IR iov [1], e così via. .PP I trasferimenti di dati eseguiti da .BR readv () e .BR writev () sono atomici: il dato scritto da .BR writev () è scritto come un blocco singolo che non è mescolato con output provenienti da scritture in altri processi (tuttavia si veda .BR pipe (7) per un'eccezione); analogamente, .BR 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 .BR open (2)). .SS preadv() e pwritev() La chiamata di sistema .BR preadv () combina le funzionalità di .BR readv () e di .BR pread (2). Realizza lo stesso compito di .BR readv (), ma aggiunge un quarto argomento, .IR offset , che specifica la posizione nel file (offset) alla quale dev'essere effettuata l'operazione di input. La chiamata d sistema .BR pwritev () combina le funzionalità di .BR writev () e di .BR pwrite (2). Realizza lo stesso compito di .BR writev (), ma aggiunge un quarto argomento, .IR 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 .I fd deve deve poter permettere il posizionamento a un offset. .SH VALORE RESTITUITO In caso di successo, .BR readv () e .BR preadv () restituiscono il numero di byte letti; .BR writev () e .BR pwritev () restituiscono il numero di byte scritti. In caso di errore viene restituito \-1 , e \fIerrno\fP è impostato appropriatamente. .SH ERRORI Gli errori sono gli stessi di .BR read (2) e .BR write (2). Per di più, .BR preadv () e .BR pwritev () possono anche non andare a buon fine per le stesse ragioni di .BR lseek (2). Inoltre è definito il seguente errore: .TP .B EINVAL La somma dei valori .I iov_len supera un valore .I ssize_t . Oppure, il vettore conteggio \fIiovcnt\fP è minore di zero o maggiore del massimo permesso. .SH VERSIONI .BR preadv () e .BR pwritev () sono apparse per la prima volta in Linux 2.6.30; il supporto alla libreria è stato aggiunto in glibc 2.10. .SH CONFORME A .BR readv (), .BR writev (): 4.4BSD (queste chiamate di sistema sono apparse per la prima volta in 4.2BSD), POSIX.1-2001. .\" Linux libc5 usava \fIsize_t\fP come tipo per l'argomento \fIiovcnt\fP, .\" e \fIint\fP come tipo restituito. .\" The readv/writev system calls were buggy before Linux 1.3.40. .\" (Says release.libc.) .BR preadv (), .BR pwritev (): non standard, però presente anche nei sistemi BSD moderni. .SH NOTE .SS Differenze tra le ABI della libreria C e del kernel POSIX.1-2001 permette un'implementazione per porre un limite al numero di elementi che possono essere passati in .IR iov . Un'implementazione può pubblicizzare i suoi limiti definendo .B IOV_MAX in .I o in run time attraverso il valore restituito da .IR 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 .BR readv () la funzione wrapper alloca un buffer temporaneo abbastanza grande per tutti gli elementi specificati da .IR iov , passa questo buffer in una chiamata a .BR read (2), copia i dati dal buffer alle posizioni specificate dai campi .I iov_base degli elementi di .IR iov , e infine libera il buffer. La funzione wrapper per .BR writev () esegue l'attività analoga usando un buffer temporaneo e una chiamata a .BR write (2). .SH BUG Non è consigliabile mischiare chiamate a .BR readv () o .BR writev (), che operano sui descrittori dei file, con le funzioni della libreria stdio; i risultati sarebbero indefiniti e probabilmente non ciò che si vuole. .SH ESEMPIO Il seguente codice di esempio mostra l'uso di .BR writev (): .in +4n .nf 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); .fi .in .SH VEDERE ANCHE .BR pread (2), .BR read (2), .BR write (2) .SH COLOPHON Questa pagina fa parte del rilascio 3.73 del progetto Linux .IR man-pages . Una descrizione del progetto, le istruzioni per la segnalazione degli errori, e l'ultima versione di questa pagina si trova su \%http://www.kernel.org/doc/man\-pages/. La versione italiana fa parte del pacchetto .I man-pages-it v. 3.73, a cura di: ILDP "Italian Linux Documentation Project" \%http://www.pluto.it/ildp .br Per la traduzione in italiano si pu\(`o fare riferimento a http://www.pluto.it/ildp/collaborare/ .br Segnalare eventuali errori di traduzione a .IR ildp@pluto.it