Fonction ReadFile (fileapi.h)

Article
08/23/2023

Lit les données du fichier ou du périphérique d’entrée/sortie (E/S) spécifié. Les lectures ont lieu à la position spécifiée par le pointeur de fichier si le dispositif le permet.

Cette fonction est conçue pour les opérations synchrones et asynchrones. Pour une fonction similaire conçue uniquement pour une opération asynchrone, consultez ReadFileEx.

Syntaxe

BOOL ReadFile(
  [in]                HANDLE       hFile,
  [out]               LPVOID       lpBuffer,
  [in]                DWORD        nNumberOfBytesToRead,
  [out, optional]     LPDWORD      lpNumberOfBytesRead,
  [in, out, optional] LPOVERLAPPED lpOverlapped
);

Paramètres

[in] hFile

Handle pour l’appareil (par exemple, un fichier, un flux de fichiers, un disque physique, un volume, une mémoire tampon de console, un lecteur de bande, un socket, une ressource de communication, un maillot ou un canal).

Le paramètre hFile doit avoir été créé avec un accès en lecture. Pour plus d’informations, consultez Droits d’accès génériques et Sécurité des fichiers et droits d’accès.

Pour les opérations de lecture asynchrones, hFile peut être n’importe quel handle ouvert avec l’indicateur FILE_FLAG_OVERLAPPED par la fonction CreateFile , ou un handle de socket retourné par la fonction socket ou accept .

[out] lpBuffer

Pointeur vers la mémoire tampon qui reçoit les données lues à partir d’un fichier ou d’un appareil.

Cette mémoire tampon doit rester valide pendant toute la durée de l’opération de lecture. L’appelant ne doit pas utiliser cette mémoire tampon tant que l’opération de lecture n’est pas terminée.

[in] nNumberOfBytesToRead

Nombre maximal d'octets à lire.

[out, optional] lpNumberOfBytesRead

Pointeur vers la variable qui reçoit le nombre d’octets lus lors de l’utilisation d’un paramètre hFile synchrone. ReadFile définit cette valeur sur zéro avant d’effectuer un travail ou une vérification des erreurs. Utilisez NULL pour ce paramètre s’il s’agit d’une opération asynchrone pour éviter des résultats potentiellement erronés.

Ce paramètre ne peut être NULL que lorsque le paramètre lpOverlapped n’est pas NULL.

Windows 7 : Ce paramètre ne peut pas être NULL.

Pour plus d'informations, consultez la section Notes.

[in, out, optional] lpOverlapped

Un pointeur vers une structure CHEVAUCHEMENT EST requis si le paramètre hFile a été ouvert avec FILE_FLAG_OVERLAPPED, sinon il peut être NULL.

Si hFile est ouvert avec FILE_FLAG_OVERLAPPED, le paramètre lpOverlapped doit pointer vers une structure chevauchement valide et unique, sinon la fonction peut signaler à tort que l’opération de lecture est terminée.

Pour un fichier hFile qui prend en charge les décalages d’octets, si vous utilisez ce paramètre, vous devez spécifier un décalage d’octet à partir duquel commencer la lecture à partir du fichier ou de l’appareil. Ce décalage est spécifié en définissant les membres Offset et OffsetHigh de la structure OVERLAPPED . Pour un hFile qui ne prend pas en charge les décalages d’octets, Offset et OffsetHigh sont ignorés.

Pour plus d’informations sur les différentes combinaisons de lpOverlapped et de FILE_FLAG_OVERLAPPED, consultez la section Remarques et la section Synchronisation et position du fichier .

Valeur retournée

Si la fonction réussit, la valeur de retour est différente de zéro (TRUE).

Si la fonction échoue ou se termine de manière asynchrone, la valeur de retour est zéro (FALSE). Pour obtenir des informations détaillées sur l’erreur, appelez la fonction GetLastError.

Note Le code GetLastErrorERROR_IO_PENDING n’est pas un échec ; il indique que l’opération de lecture est en attente d’achèvement de manière asynchrone. Pour plus d'informations, consultez la section Notes.

Notes

La fonction ReadFile retourne lorsque l’une des conditions suivantes se produit :

Le nombre d’octets demandés est lu.
Une opération d’écriture se termine à l’extrémité d’écriture du canal.
Un handle asynchrone est utilisé et la lecture se produit de manière asynchrone.
Une erreur se produit.

La fonction ReadFile peut échouer avec ERROR_INVALID_USER_BUFFER ou ERROR_NOT_ENOUGH_MEMORY chaque fois qu’il y a trop de demandes d’E/S asynchrones en attente.

Pour annuler toutes les opérations d’E/S asynchrones en attente, utilisez l’une des fonctions suivantes :

CancelIo : cette fonction annule uniquement les opérations émises par le thread appelant pour le descripteur de fichier spécifié.
CancelIoEx : cette fonction annule toutes les opérations émises par les threads pour le descripteur de fichier spécifié.

Utilisez CancelSynchronousIo pour annuler les opérations d’E/S synchrones en attente.

Les opérations d’E/S annulées sont terminées avec l’erreur ERROR_OPERATION_ABORTED.

La fonction ReadFile peut échouer avec ERROR_NOT_ENOUGH_QUOTA, ce qui signifie que la mémoire tampon du processus appelant n’a pas pu être verrouillée sur la page. Pour plus d’informations, consultez SetProcessWorkingSetSize.

Si une partie d’un fichier est verrouillée par un autre processus et que l’opération de lecture chevauche la partie verrouillée, cette fonction échoue.

L’accès à la mémoire tampon d’entrée lorsqu’une opération de lecture utilise la mémoire tampon peut entraîner une altération des données lues dans cette mémoire tampon. Les applications ne doivent pas lire à partir de, écrire dans, réallouer ou libérer la mémoire tampon d’entrée qu’une opération de lecture utilise tant que l’opération de lecture n’est pas terminée. Cela peut être particulièrement problématique lors de l’utilisation d’un handle de fichier asynchrone. Vous trouverez des informations supplémentaires sur les handles de fichiers synchrones et asynchrones dans la section Synchronisation et position du fichier et dans la rubrique de référence CreateFile .

Les caractères peuvent être lus à partir de la mémoire tampon d’entrée de console à l’aide de ReadFile avec un handle vers l’entrée de console. Le mode console détermine le comportement exact de la fonction ReadFile . Par défaut, le mode console est ENABLE_LINE_INPUT, ce qui indique que ReadFile doit lire jusqu’à ce qu’il atteigne un retour chariot. Si vous appuyez sur Ctrl+C, l’appel réussit, mais GetLastError retourne ERROR_OPERATION_ABORTED. Pour plus d’informations, consultez CreateFile.

Lors de la lecture à partir d’un appareil de communication, le comportement de ReadFile est déterminé par le délai de communication actuel défini et récupéré à l’aide des fonctions SetCommTimeouts et GetCommTimeouts . Des résultats imprévisibles peuvent se produire si vous ne parvenez pas à définir les valeurs de délai d’attente. Pour plus d’informations sur les délais de communication, consultez COMMTIMEOUTS.

Si ReadFile tente de lire à partir d’un maillot dont la mémoire tampon est trop petite, la fonction retourne FALSE et GetLastError retourne ERROR_INSUFFICIENT_BUFFER.

Il existe des exigences strictes pour utiliser correctement les fichiers ouverts avec CreateFile à l’aide de l’indicateur FILE_FLAG_NO_BUFFERING . Pour plus d’informations, consultez Mise en mémoire tampon de fichiers.

Si hFile a été ouvert avec FILE_FLAG_OVERLAPPED, les conditions suivantes sont en vigueur :

Le paramètre lpOverlapped doit pointer vers une structure chevauchement valide et unique, sinon, la fonction peut signaler à tort que l’opération de lecture est terminée.
Le paramètre lpNumberOfBytesRead doit avoir la valeur NULL. Utilisez la fonction GetOverlappedResult pour obtenir le nombre réel d’octets lus. Si le paramètre hFile est associé à un port d’achèvement d’E/S, vous pouvez également obtenir le nombre d’octets lus en appelant la fonction GetQueuedCompletionStatus .

Synchronisation et position du fichier

Si hFile est ouvert avec FILE_FLAG_OVERLAPPED, il s’agit d’un handle de fichier asynchrone ; sinon, il est synchrone. Comme indiqué précédemment, les règles d’utilisation de la structure CHEVAUCHEMENT SONT légèrement différentes pour chacune d’elles.

Note Si un fichier ou un appareil est ouvert pour les E/S asynchrones, les appels ultérieurs à des fonctions telles que ReadFile à l’aide de ce handle retournent généralement immédiatement, mais peuvent également se comporter de manière synchrone en ce qui concerne l’exécution bloquée. Pour plus d'informations, consultez http://support.microsoft.com/kb/156932.

Considérations relatives à l’utilisation des handles de fichiers asynchrones :

ReadFile peut retourner avant la fin de l’opération de lecture. Dans ce scénario, ReadFile retourne FALSE et la fonction GetLastError retourne ERROR_IO_PENDING, ce qui permet au processus d’appel de continuer pendant que le système termine l’opération de lecture.
Le paramètre lpOverlapped ne doit pas être NULL et doit être utilisé avec les faits suivants à l’esprit :
- Bien que l’événement spécifié dans la structure OVERLAPPED soit défini et réinitialisé automatiquement par le système, le décalage spécifié dans la structure OVERLAPPED n’est pas automatiquement mis à jour.
- ReadFile réinitialise l’événement à un état non signé lorsqu’il commence l’opération d’E/S.
- L’événement spécifié dans la structure OVERLAPPED est défini sur un état signalé lorsque l’opération de lecture est terminée ; jusqu’à ce moment- là, l’opération de lecture est considérée comme en attente.
- Étant donné que l’opération de lecture commence au décalage spécifié dans la structure OVERLAPPED et que ReadFile peut retourner avant la fin de l’opération de lecture au niveau du système (lecture en attente), ni le décalage ni toute autre partie de la structure ne doivent être modifiés, libérés ou réutilisés par l’application jusqu’à ce que l’événement soit signalé (autrement dit, la lecture se termine).
- Si la fin du fichier (EOF) est détectée pendant les opérations asynchrones, l’appel à GetOverlappedResult pour cette opération retourne FALSE et GetLastError retourne ERROR_HANDLE_EOF.

Considérations relatives à l’utilisation des handles de fichiers synchrones :

Si lpOverlapped a la valeur NULL, l’opération de lecture commence à la position de fichier actuelle et ReadFile ne retourne pas tant que l’opération n’est pas terminée, et le système met à jour le pointeur de fichier avant le retour de ReadFile .
Si lpOverlapped n’a pas la valeur NULL, l’opération de lecture commence au décalage spécifié dans la structure chevauchement et ReadFile ne retourne pas tant que l’opération de lecture n’est pas terminée. Le système met à jour le décalage chevauchement et le pointeur de fichier avant que ReadFile ne retourne.
Si lpOverlapped a la valeur NULL, quand une opération de lecture synchrone atteint la fin d’un fichier, ReadFile retourne TRUE et définit *lpNumberOfBytesRead sur zéro.
Si lpOverlapped n’a pas la valeur NULL, lorsqu’une opération de lecture synchrone atteint la fin d’un fichier, ReadFile retourne FALSE et GetLastError retourne ERROR_HANDLE_EOF.

Pour plus d’informations, consultez CreateFile et E/S synchrones et asynchrones.

Tuyaux

Si un canal anonyme est utilisé et que le handle d’écriture a été fermé, lorsque ReadFile tente de lire à l’aide du handle de lecture correspondant du canal, la fonction retourne FALSE et GetLastError retourne ERROR_BROKEN_PIPE.

Si un canal nommé est lu en mode message et que le message suivant est plus long que le paramètre nNumberOfBytesToRead spécifié, ReadFile retourne FALSE et GetLastError retourne ERROR_MORE_DATA. Le reste du message peut être lu par un appel suivant à la fonction ReadFile ou PeekNamedPipe .

Si le paramètre lpNumberOfBytesRead est égal à zéro lorsque ReadFile retourne TRUE sur un canal, l’autre extrémité du canal a appelé la fonction WriteFile avec nNumberOfBytesToWrite défini sur zéro.

Pour plus d’informations sur les canaux, consultez Canaux.

Opérations traitées

S’il existe une transaction liée au descripteur de fichier, la fonction retourne les données de la vue traitée du fichier. Un descripteur de lecture traité affiche nécessairement la même vue d’un fichier pendant toute la durée du descripteur. Pour plus d’informations, consultez À propos de NTFS transactionnel.

Dans Windows 8 et Windows Server 2012, cette fonction est prise en charge par les technologies suivantes.

Technologie	Prise en charge
Protocole Server Message Block (SMB) 3.0	Oui
Basculement transparent SMB 3.0 (TFO)	Oui
SMB 3.0 avec partages de fichiers avec montée en puissance parallèle (SO)	Oui
Système de fichiers du volume partagé de cluster (CsvFS)	Oui
Système de fichiers résilient (ReFS)	Oui

Exemples

Pour obtenir un exemple de code qui vous montre comment tester la fin d’un fichier, consultez Test de la fin d’un fichier. Pour obtenir d’autres exemples, consultez Création et utilisation d’un fichier temporaire et Ouverture d’un fichier pour la lecture ou l’écriture.

Spécifications


Client minimal pris en charge	Windows XP [applications de bureau \| applications UWP]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau \| applications UWP]
Plateforme cible	Windows
En-tête	fileapi.h (inclure Windows.h)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll