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 à transférer */
};

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 du tableau. 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 ne seront pas forcément 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 une exception) ; 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 fichier 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 valeurs iov_len déborde du type ssize_t, ou le nombre iovcnt de vecteurs est nul ou supérieur au maximum autorisé.

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 à l'implémentation de limiter le nombre d'éléments qui peuvent être passés dans iov. Une implémentation peut annoncer sa limite en définissant IOV_MAX dans <limits.h> ou à l'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 véritable 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 en raison de cette limite. Dans le cas de readv(), la fonction enveloppe alloue un tampon temporaire assez grand pour tous les éléments spécifiés dans iov, passe ce tampon à 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
Le morceau de code suivant donne un exemple de 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 24 juin 2008.

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.