READ

Syntaxe

Paramètres

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

Exemple

L'exemple suivant lit les données du fichier associé au descripteur de fichier fd dans le tampon pointé par buf :