READV(2)

NOM
readv, writev - Lire ou écrire dans plusieurs tampons

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

DESCRIPTION
La fonction readv() lit iovcnt tampons depuis le descripteur de fichier fd dans les tampons décrits par iov (« entrée de diffusion »).

La fonction writev() écrit iovcnt tampons de donnés décrits par iov dans le fichier associé au descripteur fd (« tampon de collecte »).

iov pointe sur un tableau de structures iovec définies dans <sys/uio.h> ainsi :

struct iovec {
    void  *iov_base;   /* Adresse de début */
    size_t iov_len;    /* Nombre d'octets  */
};

La fonction readv() travaille comme read(2) sauf que plusieurs tampons sont remplis.

La fonction writev() travaille comme write(2) sauf que plusieurs tampons sont écrits.

Les tampons sont traités dans l'ordre indiqué. Cela signifie que readv() remplit complètement iov[0] avant de traiter iov[1], et ainsi de suite. (S'il n'y a pas suffisamment de données, tous les tampons pointés par iov peuvent ne pas être remplis.) De la même manière, writev() écrit tout le contenu de iov[0] avant de traiter iov[1], et ainsi de suite.

Les transferts de données effectués par readv() et writev() sont atomiques : les données écrites avec writev() le sont d'un seul bloc qui n'est pas interrompu par des écritures issues d'autres processus (mais voir pipe(7) pour pour une exeception) ; de manière analogue, readv() est garantie de lire un bloc contigu de données depuis le fichier, quelles que soient les opérations de lecture effectuées par d'autres threads ou processus qui ont des descripteurs de fichiers faisant référence à la même description de fichier ouvert (voir open(2)).

VALEUR RENVOYÉE
S'ils réussissent readv() renvoie le nombre d'octets lus et writev() renvoie le nombre d'octets écrits. En cas d'échec -1 est renvoyé, et errno contient le code d'erreur.

ERREURS
Les erreurs indiquées pour read(2) et write(2) sont susceptibles de se produire. De plus, il peut survenir :

EINVAL
    La somme des iov_len valeurs déborde du type ssize_t, ou le nombre iovcnt de vecteurs est nul ou supérieur à MAX_IOVEC.

CONFORMITÉ
BSD 4.4 (les fonctions readv() et writev() sont apparues dans BSD 4.2), POSIX.1-2001. La libc5 de Linux utilisait les types size_t pour le paramètre iovcnt et int en retour de ces fonctions.

NOTES

  Notes Linux
POSIX.1-2001 permet à une implémentation de placer une limite sur le nombre d'éléments qui peuvent être passés dans iov. Une implémentation peut annoncer cette limite en définissant IOV_MAX dans <limits.h> ou en cours d'exécution via la valeur de retour de sysconf(_SC_IOV_MAX). Sous Linux, la limite annoncée par ces mécanismes est 1024, qui est la vraie limite du noyau. Toutefois, les fonctions enveloppes de la glibc effectuent un travail supplémentaire si elles détectent que l'appel système du noyau sous-jacent échoue parce que la limite a été dépassée.
 Dans le cas de readv(), la fonction enveloppe alloue un grand tampon temporaire pour tous les éléments spécifiés dans iov, passe ce tampon dans un appel à read(2), copie les données du tampon aux endroits spécifiés par les champs iov_base des éléments de iov, puis libère le tampon. La fonction enveloppe de writev() effectue une tâche analogue en utilisant un tampon temporaire et un appel à write(2).

BOGUES
Il est déconseillé de mélanger les appels readv() ou writev() qui agissent sur les descripteurs avec les fonctions de la bibliothèque stdio ; les résultats sont indéfinis et probablement différents de ce que l'on attend.

EXEMPLE
L'exemple de code suivant montre l'utilisation de 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);

VOIR AUSSI
read(2), write(2)

TRADUCTION

Ce document est une traduction réalisée par Christophe Blaess <http://www.blaess.fr/christophe/> le 14 octobre 1996 et révisée le 22 décembre 2007.

L'équipe de traduction a fait le maximum pour réaliser une adaptation française de qualité. La version anglaise la plus à jour de ce document est toujours consultable via la commande : « LANG=C man 2 readv ». N'hésitez pas à signaler à l'auteur ou au traducteur, selon le cas, toute erreur dans cette page de manuel.