READ

Manuel du programmeur Linux (2)
4 mai 2014

NOM

read - Lire depuis un descripteur de fichier

SYNOPSIS

#include <unistd.h>

ssize_t read(int fd, void *buf, size_t count);

DESCRIPTION

read() lit jusqu'à count octets depuis le descripteur de fichier fd dans le tampon pointé par buf.

Sur les fichiers permettant le positionnement, l'opération de lecture a lieu à la position actuelle dans le fichier et elle est déplacée du nombre d'octets lus. Si la position actuelle dans le fichier est à la fin du fichier ou après, aucun octet n'est lu et read() renvoie zéro.

Si count vaut zéro, read() pourrait détecter les erreurs décrites ci-dessous. En absence d'erreur, ou si read() ne vérifie pas les erreurs, un read() avec un count de 0 renvoie zéro et n'a pas d'autres effets.

Si count est supérieur à SSIZE_MAX, le résultat est indéfini.

VALEUR RENVOYÉE

read() renvoie -1 s'il échoue, auquel cas errno contient le code d'erreur, et la position de la tête de lecture est indéfinie. Sinon, read renvoie le nombre d'octets lus (0 en fin de fichier), et avance la tête de lecture de ce nombre. Le fait que le nombre renvoyé soit plus petit que le nombre demandé n'est pas une erreur. Ceci se produit à la fin du fichier, ou si on lit depuis un tube ou un terminal, ou encore si read() a été interrompu par un signal.

ERREURS

EAGAIN: Le descripteur de fichier fd fait référence à un fichier autre qu'une socket et a été marqué comme non bloquant (O_NONBLOCK), et la lecture devrait bloquer.
EAGAIN ou EWOULDBLOCK: Le descripteur de fichier fd fait référence à un fichier autre qu'une socket et a été marqué comme non bloquant (O_NONBLOCK), et la lecture devrait bloquer. POSIX.1-2001 permet de renvoyer l'une ou l'autre des erreurs dans ce cas et n'exige pas que ces constantes aient la même valeur. Une application portable devrait donc tester les deux possibilités.
EBADF: fd n'est pas un descripteur de fichier valable ou n'est pas ouvert en lecture.
EFAULT: buf pointe en dehors de l'espace d'adressage accessible.
EINTR: read() a été interrompu par un signal avant d'avoir eu le temps de lire quoi que ce soit ; consultez signal(7).
EINVAL: Le descripteur fd correspond à un objet sur lequel il est impossible de lire. Ou bien le fichier a été ouvert avec l'attribut O_DIRECT, et l'adresse de buf, la valeur de count ou la position actuelle de la tête de lecture ne sont pas alignées correctement.
EINVAL: fd a été créé par un appel à timerfd_create(2) et une mauvaise taille de tampon a été donnée à read() ; consultez timerfd_create(2) pour plus d'informations.
EIO: Erreur d'entrée-sortie. Ceci arrive si un processus est dans un groupe en arrière-plan et tente de lire depuis le terminal (tty). Il reçoit un signal SIGTTIN mais il l'ignore ou le bloque. Ceci se produit également si une erreur d'entrée-sortie bas niveau s'est produite pendant la lecture d'un disque ou d'une bande.
EISDIR: fd est un répertoire.

D'autres erreurs peuvent se produire, suivant le type d'objet associé à fd. POSIX permet à un read() interrompu par un signal de renvoyer soit le nombre d'octets lus à ce point, soit -1, et de placer errno à EINTR.

CONFORMITÉ

SVr4, BSD 4.3, POSIX.1-2001.

NOTES

Sur un système de fichiers NFS, la lecture de petites quantités de données ne mettra à jour l'horodatage du fichier que lors de la première lecture. Les lectures suivantes ne modifieront pas cette heure. En effet la plupart, si ce n'est tous les clients NFS disposent d'un cache des attributs de fichiers et n'effectuent pas la mise à jour du champ « st_atime » du côté serveur. La véritable sémantique UNIX peut être obtenue en désactivant le cache des attributs du côté client, mais généralement ceci augmente sensiblement la charge du serveur, et dégrade ses performances.

BOGUES

Selon POSIX.1-2008/SUSv4, Section XSI 2.9.7 ("Thread Interactions with Regular File Operations") :

: Toutes les fonctions suivantes doivent être atomiques et ne pas se perturber mutuellement pour ce qui concerne les effets spécifiés dans POSIX.1-2008 lorsqu'elles opèrent sur les fichiers réguliers ou sur les liens symboliques : ...

read() et readv(2) figurent parmi les API listées par la suite. En outre, la mise à jour du décalage de fichier fait partie des effets qui doivent être atomiques pour les threads (et pour les processus). Cependant, dans les versions de Linux antérieures à 3.14, cela n'était pas le cas : si deux processus partageant un même descripteur de fichier (consultez open(2)) effectuaient une action read() (ou readv(2)) simultanément, alors les opération E/S n'étaient pas atomiques pour ce qui concernait la mise à jour du décalage de fichier. En conséquence, les lectures effectuées par les deux processus pouvaient se chevaucher au niveau des blocs de données récupérés (de façon incorrecte). Ce problème a été résolu dans Linux 3.14.

VOIR AUSSI

close(2), fcntl(2), ioctl(2), lseek(2), open(2), pread(2), readdir(2), readlink(2), readv(2), select(2), write(2), fread(3)

COLOPHON

Cette page fait partie de la publication 3.66 du projet man-pages Linux. Une description du projet et des instructions pour signaler des anomalies peuvent être trouvées à l'adresse http://www.kernel.org/doc/man-pages/.

TRADUCTION

Depuis 2010, cette traduction est maintenue à l'aide de l'outil po4a <http://po4a.alioth.debian.org/> par l'équipe de traduction francophone au sein du projet perkamon <http://perkamon.alioth.debian.org/>.

Christophe Blaess <http://www.blaess.fr/christophe/> (1996-2003), Alain Portal <http://manpagesfr.free.fr/> (2003-2006). Julien Cristau et l'équipe francophone de traduction de Debian (2006-2009).

Veuillez signaler toute erreur de traduction en écrivant à <perkamon-fr@traduc.org>.

Vous pouvez toujours avoir accès à la version anglaise de ce document en utilisant la commande « LC_ALL=C man <section> <page_de_man> ».

This document was created by man2html, using the manual pages.
Time: 21:52:35 GMT, July 12, 2014