.\" -*- 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 décembre 2020" Linux "Manuel du programmeur Linux" .SH NOM readv, writev, preadv, pwritev, preadv2, pwritev2 \- Lire ou écrire des données dans plusieurs tampons .SH SYNOPSIS .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 Exigences de macros de test de fonctionnalités pour la glibc (consulter \fBfeature_test_macros\fP(7))\ : .RE .PP \fBpreadv\fP(), \fBpwritev\fP(): Depuis la glibc 2.19 : _DEFAULT_SOURCE Glibc 2.19 et antérieures : _BSD_SOURCE .SH DESCRIPTION L'appel système \fBreadv\fP() lit \fIiovcnt\fP tampons depuis le fichier associé au descripteur de fichier \fIfd\fP dans les tampons décrits par \fIiov\fP.(«\ scatter input\ ») .PP L'appel système \fBwritev\fP() écrit au plus \fIiovcnt\fP tampons de données décrits par \fIiov\fP dans le fichier associé au descripteur \fIfd\fP («\ gather output\ »). .PP Le pointeur \fIiov\fP pointe vers un tableau de structures \fIiovec\fP définies dans \fI\fP\ : .PP .in +4n .EX struct iovec { void *iov_base; /* Adresse de début */ size_t iov_len; /* Nombre d'octets à transférer */ }; .EE .in .PP L'appel système \fBreadv\fP() travaille comme \fBread\fP(2) sauf que plusieurs tampons sont remplis. .PP L'appel système \fBwritev\fP() travaille comme \fBwrite\fP(2) sauf que plusieurs tampons sont écrits. .PP Les tampons sont considérés dans l'ordre du tableau. Cela signifie que \fBreadv\fP() remplit \fIiov\fP[0] complètement avant d'en arriver à \fIiov\fP[1], et ainsi de suite. (S'il n'y a pas assez de données, tous les tampons pointés par \fIiov\fP ne seront pas forcément remplis.) De même, \fBwritev\fP() écrit tout le contenu de \fIiov\fP[0] avant de considérer \fIiov\fP[1] et ainsi de suite. .PP .\" Regarding atomicity, see https://bugzilla.kernel.org/show_bug.cgi?id=10596 Les transferts de données effectués par \fBreadv\fP() et \fBwritev\fP() sont atomiques\ : les données écrites par \fBwritev\fP() sont écrites d'un bloc qui n'est pas interrompu par des écritures venant d'autres processus (mais voir \fBpipe\fP(7) pour une exception)\ ; de façon similaire, \fBreadv\fP() a la 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 correspondant à la même description de fichier ouvert (consultez \fBopen\fP(2)). .SS "preadv() et pwritev()" L'appel système \fBpreadv\fP() combine les fonctionnalités de \fBreadv\fP() et \fBpread\fP(2). Il effectue la même tâche que \fBreadv\fP(), mais ajoute un quatrième paramètre, \fIoffset\fP, qui indique la position dans le fichier à partir de laquelle l'opération d'entrée doit être effectuée. .PP L'appel système \fBpwritev\fP() combine les fonctionnalités de \fBwritev\fP() et \fBpwrite\fP(2). Il effectue la même tâche que \fBwritev\fP(), mais ajoute un quatrième paramètre, \fIoffset\fP, qui indique la position dans le fichier à partir de laquelle l'opération de sortie doit être effectuée. .PP La position dans le fichier n'est pas modifiée par ces appels système. Le fichier décrit par \fIfd\fP doit permettre le positionnement. .SS "preadv2() et pwritev2()" Ces appels système sont identiques aux appels \fBpreadv\fP() et \fBpwritev\fP() mais ils ajoutent un cinquième paramètre (\fIflags\fP) qui change le comportement sur la base de chaque appel. .PP Contrairement à \fBpreadv\fP() et \fBpwritev\fP(), si le paramètre \fIoffset\fP est \fB\-1\fP, la tête de lecture du fichier actuel est utilisée et mise à jour. .PP L'argument \fIflags\fP est un opérateur OU binaire contenant zéro ou plusieurs des attributs suivants\ : .TP \fBRWF_DSYNC\fP (depuis Linux 4.7) .\" commit e864f39569f4092c2b2bc72c773b6e486c7e3bd9 Fournir un équivalent par écriture à l'attribut \fBO_DSYNC\fP d'\fBopen\fP(2). Cet attribut n'a de sens que pour \fBpwritev2\fP() et son effet ne vaut que pour la plage de données écrite par l'appel système. .TP \fBRWF_HIPRI\fP (depuis Linux 4.6) Lecture/écriture haute priorité. Cela permet à des systèmes de fichiers fondés sur les blocs d'utiliser la scrutation du périphérique, ce qui donne moins de latence mais peut coûter plus de ressources (actuellement, cette fonctionnalité n'est utilisable que sur un descripteur de fichier ouvert avec l'attribut \fBO_DIRECT\fP). .TP \fBRWF_SYNC\fP (depuis Linux 4.7) .\" commit e864f39569f4092c2b2bc72c773b6e486c7e3bd9 Fournir un équivalent par écriture de l'attribut \fBO_SYNC\fP d'\fBopen\fP(2). Cet attribut n'a de sens que pour \fBpwritev2\fP() et ses effets ne valent que pour la plage de données écrite avec cet appel système. .TP \fBRWF_NOWAIT\fP (depuis Linux 4.14) .\" commit 3239d834847627b6634a4139cf1dc58f6f137a46 .\" commit 91f9943e1c7b6638f27312d03fe71fcc67b23571 Ne pas attendre les données qui ne sont pas immédiatement disponibles. Si cet attribut est indiqué, l'appel système \fBpreadv2\fP() renverra quelque chose instantanément s'il doit lire des données provenant d'un stockage de cache ou attendre un verrou. Si des données ont été lues avec succès, il renverra le nombre d'octets lus. Si aucun octet n'est lu, il renverra \fB\-1\fP et positionnera \fIerrno\fP sur \fBEAGAIN\fP. Actuellement, cet attribut n'a de sens que pour \fBpreadv2\fP(). .TP \fBRWF_APPEND\fP (depuis Linux 4.16) .\" commit e1fc742e14e01d84d9693c4aca4ab23da65811fb Fournir un équivalent par écriture de l'attribut \fBO_APPEND\fP d'\fBopen\fP(2). Cet attribut n'a de sens que pour \fBpwritev2\fP et ses effets ne valent que pour la plage de données écrite par cet appel système. Le paramètre \fIoffset\fP n’affecte pas l'opération d'écriture\ ; les données vont toujours à la fin du fichier. Cependant, si le paramètre \fIoffset\fP est \fB\-1\fP, la tête de lecture du fichier actuel est mise à jour. .SH "VALEUR RENVOYÉE" S'ils réussissent, \fBreadv\fP(), \fBpreadv\fP() et \fBpreadv2\fP() renvoient le nombre d'octets lus\ ; \fBwritev\fP, \fBpwritev\fP() et \fBpwritev2\fP() renvoient le nombre d'octets écrits. .PP Remarquez que le fait de transférer moins d'octets que deux demandés (voir \fBread\fP(2) et \fBwrite\fP(2)) ne constitue pas une erreur empêchant le succès de l'appel. .PP En cas d'erreur, la valeur de retour est \fB\-1\fP, et \fIerrno\fP est défini de façon appropriée. .SH ERREURS Les erreurs sont comme celles indiquées pour \fBread\fP(2) et \fBwrite\fP(2). En outre, \fBpreadv\fP(), \fBpreadv2\fP() et \fBpwritev\fP() peuvent aussi échouer pour les mêmes raisons que \fBlseek\fP(2). De plus, les erreurs suivantes peuvent survenir\ : .TP \fBEINVAL\fP La somme des valeurs \fIiov_len\fP déborde une valeur \fIssize_t\fP. .TP \fBEINVAL\fP Le nombre de vecteurs \fIiovcnt\fP est inférieur à zéro ou supérieur au maximum autorisé. .TP \fBEOPNOTSUPP\fP Un drapeau inconnu est indiqué dans \fIflags\fP. .SH VERSIONS \fBpreadv\fP() et \fBpwritev\fP() sont apparus dans Linux\ 2.6.30\ ; la glibc les gère depuis la version\ 2.10. .PP \fBpreadv\fP() et \fBpwritev\fP() sont apparus dans Linux\ 4.6. La prise en charge a été ajoutée à la glibc\ 2.26. .SH CONFORMITÉ .\" 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 (ces appels système sont apparus pour la première fois dans\ 4.2BSD). .PP \fBpreadv\fP(), \fBpwritev\fP()\ : non standard, mais sont aussi présents sur les BSD modernes. .PP \fBpreadv2\fP(), \fBpwritev2\fP()\ : extension Linux non standard. .SH NOTES .\" .\" POSIX.1 autorise une implémentation à poser une limite au nombre d'éléments qui peuvent être placés dans \fIiov\fP. Une implémentation peut indiquer cette limite en définissant \fBIOV_MAX\fP dans \fI\fP ou pendant l'exécution à l'aide d'un code de retour issu de \fIsysconf(_SC_IOV_MAX)\fP. Sur les systèmes Linux modernes, la limite est de 1024. À l'époque de Linux\ 2.0, la limite était de\ 16. .SS "différences entre bibliothèque C et noyau" Les appels système \fBpreadv\fP() et \fBpwritev\fP() bruts ont une signature d'appel différant légèrement de celle des fonctions d'enveloppe de la bibliothèque\ C présentées dans le SYNOPSIS. Le paramètre \fIoffset\fP final est dépaqueté par les fonctions d'enveloppe sous la forme de deux paramètres des appels système\ : .PP \fB unsigned long \fP\fIpos_l\fP\fB, unsigned long \fP\fIpos\fP .PP Ces paramètres contiennent respectivement les 32\ bits d'ordre bas et haut de l'\fIoffset\fP. .SS "Différence historique entre la bibliothèque C et le noyau" Pour gérer le fait que \fBIOV_MAX\fP était trop bas sur les premières versions de Linux, les fonctions d'enveloppe de la glibc pour \fBreadv\fP() et \fBwritev\fP() effectuaient un travail supplémentaire si elles détectaient que les appels système du noyau sous\-jacents échouaient à cause d'un dépassement de la limite. Pour \fBreadv\fP(), la fonction d'enveloppe allouait un tampon temporaire assez grand pour tous les éléments de \fIiov\fP, passait ce tampon dans un appel \fBread\fP(2), copiait les données du tampon vers les emplacements indiqués par le champ \fIiov_base\fP des éléments de \fIiov\fP, puis libérait le tampon. La fonction d'enveloppe de \fBwritev\fP() faisait la même chose avec un tampon temporaire et un appel à \fBwrite\fP(2). .PP La nécessité d'un tel effort supplémentaire par les fonctions d'enveloppe de la glibc a disparu avec Linux\ 2.2 et ultérieurs. Cependant la glibc a continué à fournir ce comportement jusqu'à la version\ 2.10. À partir de la version\ 2.9, les fonctions d'enveloppe ne fournissent ce comportement que si la bibliothèque détecte que le système a un noyau Linux plus ancien que la version\ 2.6.18 (une version du noyau sélectionnée à votre guise). Depuis la glibc\ 2.20 (qui nécessite une version au moins\ 2.6.32 du noyau Linux), les fonctions d'enveloppe de la glibc appellent simplement les appels système dans tous les cas. .SH EXEMPLES Le segment de code suivant donne un exemple d'utilisation de \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 "VOIR AUSSI" \fBpread\fP(2), \fBread\fP(2), \fBwrite\fP(2) .SH COLOPHON Cette page fait partie de la publication\ 5.10 du projet \fIman\-pages\fP Linux. Une description du projet et des instructions pour signaler des anomalies et la dernière version de cette page peuvent être trouvées à l'adresse \%https://www.kernel.org/doc/man\-pages/. .PP .SH TRADUCTION La traduction française de cette page de manuel a été créée par Christophe Blaess , Stéphan Rafin , Thierry Vignaud , François Micaux, Alain Portal , Jean-Philippe Guérard , Jean-Luc Coulon (f5ibh) , Julien Cristau , Thomas Huriaux , Nicolas François , Florentin Duneau , Simon Paillard , Denis Barbier , David Prévot , Frédéric Hantrais et Jean-Philippe MENGUAL . .PP Cette traduction est une documentation libre ; veuillez vous reporter à la .UR https://www.gnu.org/licenses/gpl-3.0.html GNU General Public License version 3 .UE concernant les conditions de copie et de distribution. Il n'y a aucune RESPONSABILITÉ LÉGALE. .PP Si vous découvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un message à .MT debian-l10n-french@lists.debian.org .ME .