ReadFile-Funktion (fileapi.h)

Artikel
11/08/2024

Liest Daten aus der angegebenen Datei oder Eingabe/Ausgabe (E/A)-Gerät. Lesevorgänge erfolgen an der durch den Dateizeiger angegebenen Position, wenn sie vom Gerät unterstützt wird.

Diese Funktion ist sowohl für synchrone als auch für asynchrone Vorgänge ausgelegt. Eine ähnliche Funktion, die ausschließlich für asynchronen Vorgang entwickelt wurde, finden Sie unter ReadFileEx.

Syntax

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

Parameter

[in] hFile

Ein Handle für das Gerät (z. B. datei, Dateidatenstrom, physischer Datenträger, Volume, Konsolenpuffer, Bandlaufwerk, Socket, Kommunikationsressource, Maillot oder Pipe).

Der hFile Parameter muss mit Lesezugriff erstellt worden sein. Weitere Informationen finden Sie unter Generic Access Rights und File Security and Access Rights.

Bei asynchronen Lesevorgängen kann hFile- ein beliebiges Handle sein, das mit dem FILE_FLAG_OVERLAPPED Flag durch die CreateFile--Funktion geöffnet wird, oder ein Sockethandle, das vom Socket- oder Funktion zurückgegeben wird.

[out] lpBuffer

Ein Zeiger auf den Puffer, der die aus einer Datei oder einem Gerät gelesenen Daten empfängt.

Dieser Puffer muss für die Dauer des Lesevorgangs gültig bleiben. Der Aufrufer darf diesen Puffer erst verwenden, wenn der Lesevorgang abgeschlossen ist.

[in] nNumberOfBytesToRead

Die maximale Anzahl von Bytes, die gelesen werden sollen.

[out, optional] lpNumberOfBytesRead

Ein Zeiger auf die Variable, die die Anzahl der gelesenen Bytes empfängt, wenn ein synchroner hFile--Parameter verwendet wird. ReadFile- legt diesen Wert vor der Arbeit oder Fehlerüberprüfung auf Null fest. Verwenden Sie NULL- für diesen Parameter, wenn es sich um einen asynchronen Vorgang handelt, um potenziell fehlerhafte Ergebnisse zu vermeiden.

Dieser Parameter kann nur NULL- werden, wenn der parameter lpOverlap ped nicht NULL-ist.

Windows 7: Dieser Parameter kann nicht NULL-werden.

Weitere Informationen finden Sie im Abschnitt "Hinweise".

[in, out, optional] lpOverlapped

Ein Zeiger auf eine OVERLAPPED-Struktur ist erforderlich, wenn der hFile-Parameter mit FILE_FLAG_OVERLAPPEDgeöffnet wurde, andernfalls kann es NULL-sein.

Wenn hFile- mit FILE_FLAG_OVERLAPPEDgeöffnet wird, muss der parameter lpOverlap ped auf eine gültige und eindeutige OVERLAPPED struktur verweisen, andernfalls kann die Funktion fälschlicherweise melden, dass der Lesevorgang abgeschlossen ist.

Bei einer hFile-, die Byte-Offsets unterstützt, müssen Sie bei Verwendung dieses Parameters einen Byte-Offset angeben, mit dem das Lesen aus der Datei oder dem Gerät gestartet werden soll. Dieser Offset wird durch Festlegen des Offset- und OffsetHigh Member der OVERLAPPED-Struktur angegeben. Bei einer hFile-, die Byteoffsets nicht unterstützt, werden Offset- und OffsetHigh- ignoriert.

Weitere Informationen zu verschiedenen Kombinationen von lpOverlapped und FILE_FLAG_OVERLAPPEDfinden Sie im Abschnitt "Hinweise" und im Abschnitt Synchronisierung und Dateiposition.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null (TRUE).

Wenn die Funktion fehlschlägt oder asynchron abgeschlossen wird, ist der Rückgabewert null (FALSE). Rufen Sie zum Abrufen erweiterter Fehlerinformationen die GetLastError--Funktion auf.

Anmerkung

Der GetLastError- Code ERROR_IO_PENDING ist kein Fehler; er legt fest, dass der Lesevorgang asynchron abgeschlossen ist. Weitere Informationen finden Sie in den Hinweisen.

Bemerkungen

Die ReadFile--Funktion gibt zurück, wenn eine der folgenden Bedingungen auftritt:

Die Anzahl der angeforderten Bytes wird gelesen.
Ein Schreibvorgang wird am Ende der Pfeife abgeschlossen.
Es wird ein asynchrones Handle verwendet, und der Lesevorgang erfolgt asynchron.
Ein Fehler tritt auf.

Die ReadFile--Funktion schlägt möglicherweise mit ERROR_INVALID_USER_BUFFER oder ERROR_NOT_ENOUGH_MEMORY fehl, wenn zu viele asynchrone E/A-Anforderungen vorhanden sind.

Um alle ausstehenden asynchronen E/A-Vorgänge abzubrechen, verwenden Sie eine der folgenden Aktionen:

CancelIo: Diese Funktion bricht nur Vorgänge ab, die vom aufrufenden Thread für das angegebene Dateihandle ausgegeben werden.
CancelIoEx-: Mit dieser Funktion werden alle Vorgänge abgebrochen, die von den Threads für das angegebene Dateihandle ausgegeben werden.

Verwenden Sie CancelSynchronousIo-, um ausstehende synchrone E/A-Vorgänge abzubrechen.

E/A-Vorgänge, die mit dem Fehler ERROR_OPERATION_ABORTEDabgebrochen werden.

Die ReadFile--Funktion kann mit ERROR_NOT_ENOUGH_QUOTAfehlschlagen, was bedeutet, dass der Puffer des aufrufenden Prozesses nicht seitensperrt sein konnte. Weitere Informationen finden Sie unter SetProcessWorkingSetSize.

Wenn ein Teil einer Datei durch einen anderen Prozess gesperrt ist und der Lesevorgang den gesperrten Teil überlappt, schlägt diese Funktion fehl.

Der Zugriff auf den Eingabepuffer, während ein Lesevorgang den Puffer verwendet, kann zu Einer Beschädigung der in diesen Puffer gelesenen Daten führen. Anwendungen dürfen den Von einem Lesevorgang verwendeten Eingabepuffer nicht lesen, in diesen schreiben, neu zuweisen oder freigeben, bis der Lesevorgang abgeschlossen ist. Dies kann besonders problematisch sein, wenn sie ein asynchrones Dateihandle verwenden. Weitere Informationen zu synchronen und asynchronen Dateihandles finden Sie im Abschnitt Synchronisierung und Dateiposition und im Referenzthema CreateFile.

Zeichen können aus dem Konsoleneingabepuffer gelesen werden, indem ReadFile- mit einem Handle für konsoleneingaben verwendet werden. Der Konsolenmodus bestimmt das genaue Verhalten der funktion ReadFile. Der Konsolenmodus ist standardmäßig ENABLE_LINE_INPUT, was angibt, dass ReadFile- lesen sollte, bis er eine Wagenrücklauf erreicht. Wenn Sie STRG+C drücken, wird der Aufruf erfolgreich ausgeführt, aber GetLastError- gibt ERROR_OPERATION_ABORTEDzurück. Weitere Informationen finden Sie unter CreateFile-.

Beim Lesen von einem Kommunikationsgerät wird das Verhalten von ReadFile- durch das aktuelle Kommunikationstimeout bestimmt und mithilfe der SetCommTimeouts- und GetCommTimeouts--Funktionen abgerufen. Unvorhersehbare Ergebnisse können auftreten, wenn Sie die Timeoutwerte nicht festlegen. Weitere Informationen zu Kommunikationstimeouts finden Sie unter COMMTIMEOUTS.

Wenn ReadFile- versucht, aus einem Maillot zu lesen, der einen zu kleinen Puffer enthält, gibt die Funktion FALSE- zurück und GetLastError- gibt ERROR_INSUFFICIENT_BUFFERzurück.

Es gibt strenge Anforderungen für das erfolgreiche Arbeiten mit Dateien, die mit CreateFile- mithilfe des FILE_FLAG_NO_BUFFERING-Flags geöffnet wurden. Ausführliche Informationen finden Sie unter Dateipufferung.

Wenn hFile- mit FILE_FLAG_OVERLAPPEDgeöffnet wurde, sind die folgenden Bedingungen wirksam:

Der parameter lpOverlapped muss auf eine gültige und eindeutige OVERLAPPED struktur verweisen, andernfalls kann die Funktion fälschlicherweise melden, dass der Lesevorgang abgeschlossen ist.
Der parameter lpNumberOfBytesRead sollte auf NULL-festgelegt werden. Verwenden Sie die GetOverlappedResult--Funktion, um die tatsächliche Anzahl der gelesenen Bytes abzurufen. Wenn der hFile- Parameter einem E/A-Vervollständigungsport zugeordnet ist, können Sie auch die Anzahl der gelesenen Bytes abrufen, indem Sie die GetQueuedCompletionStatus--Funktion aufrufen.

Synchronisierung und Dateiposition

Wenn hFile- mit FILE_FLAG_OVERLAPPEDgeöffnet wird, handelt es sich um ein asynchrones Dateihandle; andernfalls ist sie synchron. Die Regeln für die Verwendung der OVERLAPPED Struktur unterscheiden sich geringfügig für jede Struktur, wie bereits erwähnt.

Anmerkung

Wenn eine Datei oder ein Gerät für asynchrone E/A geöffnet wird, können nachfolgende Aufrufe von Funktionen wie ReadFile-, die dieses Handle im Allgemeinen sofort zurückgeben, sich aber auch synchron in Bezug auf die blockierte Ausführung verhalten. Weitere Informationen finden Sie unter Asynchrone Datenträger-E/A unter Windowsals synchron angezeigt wird.

Überlegungen zum Arbeiten mit asynchronen Dateihandles:

ReadFile- kann vor Abschluss des Lesevorgangs zurückgegeben werden. In diesem Szenario gibt ReadFile-FALSE- zurück, und die GetLastError-Funktion gibt ERROR_IO_PENDINGzurück, wodurch der Aufrufvorgang fortgesetzt werden kann, während das System den Lesevorgang abgeschlossen hat.
Der parameter lpOverlapped darf nicht NULL- sein und sollte unter Berücksichtigung der folgenden Fakten verwendet werden:
- Obwohl das in der OVERLAPPED Struktur angegebene Ereignis vom System festgelegt und automatisch zurückgesetzt wird, wird der Offset, der in der OVERLAPPED Struktur angegeben ist, nicht automatisch aktualisiert.
- ReadFile setzt das Ereignis auf einen nicht signalfreien Zustand zurück, wenn der E/A-Vorgang beginnt.
- Das in der OVERLAPPED Struktur angegebene Ereignis wird auf einen signalisierten Zustand festgelegt, wenn der Lesevorgang abgeschlossen ist; bis zu diesem Zeitpunkt gilt der Lesevorgang als ausstehend.
- Da der Lesevorgang mit dem Offset beginnt, der in der OVERLAPPED-Struktur angegeben ist, und ReadFile- kann zurückgeben, bevor der Lesevorgang auf Systemebene abgeschlossen ist (ausstehend), sollten weder der Offset noch ein anderer Teil der Struktur geändert, freigegeben oder wiederverwendet werden, bis das Ereignis signalisiert wird (d. h. der Lesevorgang abgeschlossen ist).
- Wenn ende-of-file (EOF) während asynchroner Vorgänge erkannt wird, gibt der Aufruf von GetOverlappedResult- für diesen Vorgang FALSE- zurück und GetLastError- gibt ERROR_HANDLE_EOFzurück.

Überlegungen zum Arbeiten mit synchronen Dateihandles:

Wenn lpOverlapped-NULL-ist, beginnt der Lesevorgang an der aktuellen Dateiposition und ReadFile- wird erst zurückgegeben, wenn der Vorgang abgeschlossen ist, und das System aktualisiert den Dateizeiger vor ReadFile- zurück.
Wenn lpOverlapped- nicht NULL-ist, beginnt der Lesevorgang beim Offset, der in der struktur OVERLAPPED angegeben ist, und ReadFile- erst zurückgegeben wird, wenn der Lesevorgang abgeschlossen ist. Das System aktualisiert den OVERLAPPED Offset und den Dateizeiger, bevor ReadFile- zurückgegeben wird.
Wenn lpOverlapped-NULL-ist, wird beim synchronen Lesevorgang das Ende einer Datei erreicht, ReadFile- gibt TRUE zurück und legt *lpNumberOfBytesRead auf Null fest.
Wenn lpOverlapped- nicht NULL-ist, gibt ReadFileFALSE zurück und GetLastError gibt ERROR_HANDLE_EOFzurück.

Weitere Informationen finden Sie unter CreateFile- und synchrone und asynchrone E/A-.

Dudelsack

Wenn eine anonyme Pipe verwendet wird und der Schreibhandle geschlossen wurde, wenn ReadFile- versucht, mit dem entsprechenden Lesekästchen der Pipe zu lesen, gibt die Funktion FALSE zurück und GetLastError gibt ERROR_BROKEN_PIPEzurück.

Wenn eine benannte Pipe im Nachrichtenmodus gelesen wird und die nächste Nachricht länger ist als die nNumberOfBytesToRead Parameter angibt, gibt ReadFile-FALSE- zurück und GetLastError gibt ERROR_MORE_DATAzurück. Der Rest der Nachricht kann durch einen nachfolgenden Aufruf des ReadFile- oder PeekNamedPipe--Funktion gelesen werden.

Wenn der parameter lpNumberOfBytesRead null ist, wenn ReadFile-TRUE- für eine Pipe zurückgibt, wird das andere Ende der Pipe, die WriteFile--Funktion mit nNumberOfBytesToWrite- auf Null festgelegt.

Weitere Informationen zu Rohren finden Sie unter Pipes.

Transacted Operations

Wenn eine Transaktion an das Dateihandle gebunden ist, gibt die Funktion Daten aus der transaktionsgebundenen Ansicht der Datei zurück. Ein transacted Read Handle wird garantiert die gleiche Ansicht einer Datei für die Dauer des Handles anzeigen. Weitere Informationen finden Sie unter About Transactional NTFS.

In Windows 8 und Windows Server 2012 wird diese Funktion von den folgenden Technologien unterstützt.

Technologie	Abgestützt
Server Message Block (SMB) 3.0-Protokoll	Ja
SMB 3.0 Transparent Failover (TFO)	Ja
SMB 3.0 mit Skalierungsdateifreigaben (SO)	Ja
Freigegebenes Clustervolumedateisystem (CsvFS)	Ja
Resilient File System (ReFS)	Ja

Beispiele

Ein Codebeispiel, das zeigt, wie Sie das Ende der Datei testen, finden Sie unter Testen für das Ende einer Datei. Weitere Beispiele finden Sie unter Erstellen und Verwenden einer temporären Datei und Öffnen einer Datei zum Lesen oder Schreiben von.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows XP [Desktop-Apps \| UWP-Apps]
mindestens unterstützte Server-	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform-	Fenster
Header-	fileapi.h (include Windows.h)
Library	Kernel32.lib
DLL-	Kernel32.dll