READ |
Lecture |
|---|---|
| C pour Unix | unistd.h |
Syntaxe
| ssize_t read(int fildes, void *buf, size_t nbyte); |
Paramètres
| Nom | Description |
|---|---|
| fildes | Ce paramètre permet d'indiquer un descripteur de fichier à partir duquel les données doivent être lues. Ce descripteur peut être obtenu à partir d'opérations comme open, pipe, socket, ou d'autres appels système renvoyant un descripteur de fichier valide. |
| buf | Ce paramètre permet d'indiquer un pointeur vers un tampon où les données lues seront entreposées. Ce tampon doit être suffisamment grand pour contenir les données que l'on souhaite lire (déterminées par nbyte). |
| nbyte | Ce paramètre permet d'indiquer un nombre maximum d'octets à lire à partir du descripteur de fichier. La fonction lira au maximum nbyte octets, mais il est possible que le nombre réel d'octets lus soit inférieur, en fonction des données disponibles. |
Retour
En cas de réussite, ces fonctions renvoient un entier non négatif indiquant le nombre d'octets réellement lus. Sinon, elles renvoient -1 et définissent errno pour indiquer l'erreur.
Description
Cette fonction permet d'effectuer la lecture d'un fichier.
Remarques
- La fonction read() doit tenter de lire nbyte octets du fichier associé au descripteur de fichier ouvert, fildes, dans le tampon pointé par buf. Le comportement de plusieurs lectures simultanées sur le même tube, FIFO ou terminal n'est pas spécifié.
- Avant toute action décrite ci-dessous, et si nbyte est nul, la fonction read() peut détecter et renvoyer des erreurs comme décrit ci-dessous. En l'absence d'erreur, ou si la détection d'erreur n'est pas effectuée, la fonction read() doit renvoyer zéro et ne produire aucun autre résultat.
- Sur les fichiers prenant en charge la recherche (par exemple, un fichier standard), la fonction read() doit commencer à une position du fichier donnée par le déplacement associé à fildes. Le déplacement est incrémenté du nombre d'octets réellement lus.
- Les fichiers ne prennant pas en charge la recherche (par exemple, les terminaux) lisent toujours à partir de la position actuelle. La valeur du déplacement associé à un tel fichier est indéfinie.
- Aucun transfert de données ne doit avoir lieu au-delà de la fin du fichier actuel. Si la position de départ se situe à la fin du fichier ou après, la valeur 0 est renvoyée. Si le fichier fait référence à un fichier spécial de périphérique, le résultat des requêtes read() suivantes est défini par l'implémentation.
- Si la valeur de nbyte est supérieure à {SSIZE_MAX}, le résultat est défini par l'implémentation.
- Lors d'une tentative de lecture depuis un tube ou une FIFO vide :
- Si aucun processus n'a ouvert le tube en écriture, read() renvoie 0 pour indiquer la fin du fichier.
- Si un processus a ouvert le tube en écriture et que O_NONBLOCK est défini, read() renvoie -1 et définit errno sur EAGAIN.
- Si un processus a ouvert le tube en écriture et que O_NONBLOCK est désactivé, read() bloque le processus léger appelant jusqu'à ce que des données soient écrites ou que le tube soit fermé par tous les processus qui l'avaient ouvert en écriture.
- Lors de la tentative de lecture d'un fichier (autre qu'un tube ou une FIFO) prenant en charge les lectures non bloquantes et ne contenant aucune donnée actuellement disponible :
- Si O_NONBLOCK est défini, read() doit renvoyer -1 et définir errno sur EAGAIN.
- Si O_NONBLOCK est désactivé, read() doit bloquer le processus léger appelant jusqu'à ce que des données soient disponibles.
- L'utilisation de l'indicateur O_NONBLOCK est sans effet si des données sont disponibles.
- La fonction read() lit les données précédemment écrites dans un fichier. Si une partie d'un fichier standard avant la fin du fichier n'a pas été écrite, read() renvoie des octets de valeur 0. Par exemple, lseek() permet de définir l'offset du fichier au-delà de la fin des données existantes. Si des données sont écrites ultérieurement à ce stade, les lectures ultérieures dans l'intervalle entre la fin des données précédentes et les nouvelles données écrites renvoient des octets de valeur 0 jusqu'à ce que des données soient écrites dans cet intervalle.
- En cas de réussite, lorsque nbyte est supérieur à 0, read() marque pour mise à jour l'horodatage du dernier accès aux données du fichier et renvoie le nombre d'octets lus. Ce nombre ne doit jamais être supérieur à nbyte. La valeur renvoyée peut être inférieure à nbyte si le nombre d'octets restants dans le fichier est inférieur à nbyte, si la requête read() a été interrompue par un signal, ou si le fichier est un tube, une FIFO ou un fichier spécial et qu'il contient moins de nbyte d'octets immédiatement disponibles en lecture. Par exemple, une fonction read() d'un fichier associé à un terminal peut renvoyer une ligne de données typée.
- Si une fonction read() est interrompue par un signal avant la lecture des données, elle renvoie -1 avec errno défini sur EINTR.
- Si une fonction read() est interrompue par un signal après avoir lu des données, elle renvoie le nombre d'octets lus.
- Pour les fichiers normaux, aucun transfert de données ne doit avoir lieu au-delà du décalage maximal défini dans la description du fichier ouvert associée à fildes.
- Si fildes fait référence à un socket, read() est équivalent à recv() sans indicateur défini.
- Si les bits O_DSYNC et O_RSYNC sont définis, les opérations d'entrées/sorties de lecture sur le descripteur de fichier doivent se terminer conformément à la procédure de traitement de l'intégrité des données des entrées/sorties synchronisées. Si les bits O_SYNC et O_RSYNC sont définis, les opérations d'entrées/sorties de lecture sur le descripteur de fichier doivent se terminer conformément à la procédure de traitement de l'intégrité des données des entrées/sorties synchronisées.
- Si fildes fait référence à un objet mémoire partagé, le résultat de la fonction read() n'est pas spécifié.
- Si fildes fait référence à un objet mémoire typé, le résultat de la fonction read() n'est pas spécifié.
- Une fonction read() d'un fichier STREAMS peut lire des données selon trois modes différents : flux d'octets, message non supprimé et message supprimé. Le mode par défaut est le flux d'octets. Il peut être modifié à l'aide de la requête ioctl() I_SRDOPT et testé avec la requête ioctl() I_GRDOPT. En mode flux d'octets, read() récupère les données du STREAM jusqu'à ce que le nombre d'octets demandé soit transféré, ou jusqu'à épuisement des données. Le mode flux d'octets ignore les limites des messages.
- En mode STREAMS sans suppression de messages, read() récupère les données jusqu'à ce que le nombre d'octets demandé soit transféré, ou jusqu'à ce qu'une limite de message soit atteinte. Si read() ne récupère pas toutes les données d'un message, les données restantes sont conservées dans le STREAM et peuvent être récupérées lors du prochain appel read(). Le mode suppression de messages récupère également les données jusqu'à ce que le nombre d'octets demandé soit transféré, ou jusqu'à ce qu'une limite de message soit atteinte. Cependant, les données non lues restant dans un message après le retour de read() seront supprimées et ne seront pas disponibles pour un appel read(), getmsg() ou getpmsg() ultérieur.
- La manière dont read() gère les messages STREAMS de zéro octet dépend du mode de lecture actuel. En mode flux d'octets, read() accepte les données jusqu'à ce qu'il ait lu n octets, qu'il n'y ait plus de données à lire ou qu'un bloc de message de zéro octet soit rencontré. La fonction read() renvoie alors le nombre d'octets lus et replace le message de zéro octet dans le STREAM pour qu'il soit récupéré par la prochaine fonction read(), getmsg() ou getpmsg(). En mode message-non-discard ou message-discard, un message de zéro octet renvoie 0 et est supprimé du STREAM. Lorsqu'un message de zéro octet est lu comme premier message d'un STREAM, il est supprimé du STREAM et renvoie 0, quel que soit le mode de lecture.
- Une fonction read() depuis un fichier STREAMS doit renvoyer les données du message en tête de la file de lecture du STREAM, quelle que soit la bande de priorité du message.
- Par défaut, les STREAMS sont en mode contrôle normal, ce qui signifie qu'une fonction read() depuis un fichier STREAMS ne peut traiter que les messages contenant une partie données, mais pas de partie contrôle. La fonction read() échoue si un message contenant une partie contrôle est détecté en tête du STREAM. Cette action par défaut peut être modifiée en plaçant le STREAM en mode contrôle données ou en mode contrôle-abandon avec la commande ioctl() I_SRDOPT. En mode contrôle données, read() convertit toute partie contrôle en données et la transmet à l'application avant de transmettre toute partie données initialement présente dans le même message. En mode control-discard, read() ignore les parties contrôle du message, mais renvoie au processus toute partie données du message.
- De plus, read() échoue si la tête du STREAM a traité une erreur désynchronisée avant l'appel. Dans ce cas, la valeur de errno ne reflète pas le résultat de read(), mais l'erreur précédente. En cas de blocage du STREAM en cours de lecture, read() continue de fonctionner normalement jusqu'à ce que la file d'attente de lecture du STREAM soit vide. Ensuite, la valeur renvoyée est 0.
- La fonction pread() est équivalente à read(), à la différence qu'elle lit à partir d'une position donnée du fichier sans modifier le déplacement. Les trois premiers paramètres de pread() sont identiques à ceux de read(), avec en plus un quatrième paramètre, offset, pour la position souhaitée dans le fichier. Toute tentative d'exécution de pread() sur un fichier incapable de rechercher entraînera une erreur.
Erreurs
| Constante | Description |
|---|---|
| EAGAIN | Le fichier n'est ni un tube, ni une FIFO, ni un socket, l'indicateur O_NONBLOCK est activé pour le descripteur de fichier et le thread serait retardé dans l'opération de lecture. |
| EBADF | Le paramètre fildes n'est pas un descripteur de fichier valide ouvert en lecture. |
| EBADMSG | Le fichier est un fichier STREAM configuré en mode contrôle normal et le message en attente de lecture inclut une partie contrôle. |
| EINTR | L'opération de lecture a été interrompue suite à la réception d'un signal et aucune donnée n'a été transférée. |
| INVAL | Le STREAM ou le multiplexeur référencé par fildes est lié (directement ou indirectement) en aval d'un multiplexeur. |
| EIO | Le processus est membre d'un groupe de processus d'arrière-plan et tente de lire depuis son terminal de contrôle. Soit le processus léger appelant bloque SIGTTIN, soit le processus l'ignore, soit le groupe de processus du processus est orphelin. Cette erreur peut également être générée pour des raisons d'implémentation. |
| EISDIR | Le paramètre fildes fait référence à un répertoire, et l'implémentation n'autorise pas la lecture du répertoire via read() ou pread(). La fonction readdir() doit être utilisée à la place. |
| EOVERFLOW | Le fichier est un fichier standard, nbyte est supérieur à 0, la position de départ est avant la fin du fichier et la position de départ est supérieure ou égale au décalage maximal défini dans la description du fichier ouvert associée à fildes. |
| EAGAIN | Le fichier est un tube ou une FIFO, l'indicateur O_NONBLOCK est activé pour le descripteur de fichier et le processus léger serait retardé dans l'opération de lecture. |
| EAGAIN ou EWOULDBLOCK | Le fichier est un socket, l'indicateur O_NONBLOCK est activé pour le descripteur de fichier et le processus léger serait retardé dans l'opération de lecture. |
| ECONNRESET | Une tentative de lecture a été effectuée sur un socket et la connexion a été fermée de force par son homologue. |
| ENOTCONN | Une tentative de lecture a été effectuée sur un socket non connecté. |
| ETIMEDOUT | Une tentative de lecture a été effectuée sur un socket et un dépassement de délai de transmission s'est produit. |
| EIO | Une erreur d'entrée/sortie physique s'est produite. |
| ENOBUFS | Les ressources système disponibles étaient insuffisantes pour effectuer l'opération. |
| ENOMEM | La mémoire disponible était insuffisante pour répondre à la requête. |
| ENXIO | Une requête a été effectuée sur un périphérique inexistant, ou la requête dépassait les capacités du périphérique. |
Exemple
L'exemple suivant lit les données du fichier associé au descripteur de fichier fd dans le tampon pointé par buf :
- #include <sys/types.h>
- #include <unistd.h>
- ...
- char buf[20];
- size_t nbytes;
- ssize_t bytes_read;
- int fd;
- ...
- nbytes = sizeof(buf);
- bytes_read = read(fd, buf, nbytes);
- ...
Dernière mise à jour : Vendredi, le 5 Juin 2020