ReadFile-Funktion (fileapi.h)
Liest Daten aus der angegebenen Datei oder dem angegebenen Eingabe-/Ausgabegerät (E/A). Lesevorgänge erfolgen an der vom Dateizeiger angegebenen Position, wenn dies vom Gerät unterstützt wird.
Diese Funktion ist sowohl für synchrone als auch für asynchrone Vorgänge konzipiert. Eine ähnliche Funktion, die ausschließlich für asynchrone Vorgänge 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. eine Datei, ein Dateistream, ein physischer Datenträger, ein Volume, ein Konsolenpuffer, ein Bandlaufwerk, ein Socket, eine Kommunikationsressource, ein Maillot oder eine Pipe).
Der hFile-Parameter muss mit Lesezugriff erstellt worden sein. Weitere Informationen finden Sie unter Generische Zugriffsrechte und Dateisicherheit und Zugriffsrechte.
Bei asynchronen Lesevorgängen kann hFile ein beliebiges Handle sein, das mit dem FILE_FLAG_OVERLAPPED-Flag von der CreateFile-Funktion geöffnet wird, oder ein Sockethandle, das von der Socket- oder Accept-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 der zu lesenden Bytes.
[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 sein, wenn der lpOverlapped-Parameter nicht NULL ist.
Windows 7: Dieser Parameter kann nicht NULL sein.
Weitere Informationen finden Sie im Abschnitt mit Hinweisen.
[in, out, optional] lpOverlapped
Ein Zeiger auf eine OVERLAPPED-Struktur ist erforderlich, wenn der hFile-Parameter mit FILE_FLAG_OVERLAPPED geöffnet wurde, andernfalls kann er NULL sein.
Wenn hFile mit FILE_FLAG_OVERLAPPED geöffnet wird, muss der lpOverlapped-Parameter auf eine gültige und eindeutige OVERLAPPED-Struktur verweisen. Andernfalls kann die Funktion fälschlicherweise melden, dass der Lesevorgang abgeschlossen ist.
Bei einer hFile-Datei , die Byteoffsets unterstützt, müssen Sie bei Verwendung dieses Parameters einen Byteoffset angeben, bei dem das Lesen aus der Datei oder dem Gerät gestartet werden soll. Dieser Offset wird durch Festlegen der Offset - und OffsetHigh-Elemente der OVERLAPPED-Struktur angegeben. Bei einer hFile-Datei , die Byteoffsets nicht unterstützt, werden Offset und OffsetHigh ignoriert.
Weitere Informationen zu verschiedenen Kombinationen von lpOverlapped und FILE_FLAG_OVERLAPPED finden Sie im Abschnitt Hinweise und im Abschnitt Synchronisierung und Dateiposition .
Rückgabewert
Wenn die Funktion erfolgreich ist, ist der Rückgabewert nonzero (TRUE).
Wenn die Funktion fehlschlägt oder asynchron abgeschlossen wird, ist der Rückgabewert 0 (FALSE). Um erweiterte Fehlerinformationen zu erhalten, rufen Sie die GetLastError-Funktion auf.
Hinweise
Die ReadFile-Funktion gibt zurück, wenn eine der folgenden Bedingungen auftritt:
- Die Anzahl der angeforderten Bytes wird gelesen.
- Am Schreibende der Pipe wird ein Schreibvorgang 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 ausstehen.
Verwenden Sie eine der folgenden Optionen, um alle ausstehenden asynchronen E/A-Vorgänge abzubrechen:
- CancelIo: Diese Funktion bricht nur Vorgänge ab, die vom aufrufenden Thread für das angegebene Dateihandle ausgegeben wurden.
- CancelIoEx: Diese Funktion bricht alle Vorgänge ab, die von den Threads für das angegebene Dateihandle ausgegeben wurden.
Verwenden Sie CancelSynchronousIo, um ausstehende synchrone E/A-Vorgänge abzubrechen.
E/A-Vorgänge, die mit dem fehler ERROR_OPERATION_ABORTED abgebrochen werden.
Die ReadFile-Funktion schlägt möglicherweise mit ERROR_NOT_ENOUGH_QUOTA fehl, was bedeutet, dass der Puffer des aufrufenden Prozesses nicht seitengesperrt 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 überschneidet, 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 Eingabepuffer, den ein Lesevorgang verwendet, erst nach Abschluss des Lesevorgangs lesen, schreiben, neu zuweisen oder freigeben. Dies kann besonders problematisch sein, wenn ein asynchrones Dateihandle verwendet wird. 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 wird. Der Konsolenmodus bestimmt das genaue Verhalten der ReadFile-Funktion . Standardmäßig ist der Konsolenmodus ENABLE_LINE_INPUT, was angibt, dass ReadFile gelesen werden soll, bis ein Wagenrücklauf erreicht wird. Wenn Sie STRG+C drücken, ist der Aufruf erfolgreich, aber GetLastError gibt ERROR_OPERATION_ABORTED zurück. Weitere Informationen finden Sie unter CreateFile.
Beim Lesen von einem Kommunikationsgerät wird das Verhalten von ReadFile durch das aktuelle Kommunikationstimeout bestimmt, das festgelegt und mithilfe der Funktionen SetCommTimeouts und GetCommTimeouts abgerufen wird. Unvorhersehbare Ergebnisse können auftreten, wenn Sie die Timeoutwerte nicht festlegen können. Weitere Informationen zu Kommunikationstimeouts finden Sie unter COMMTIMEOUTS.
Wenn ReadFile versucht, aus einem Maillot zu lesen, das über einen zu kleinen Puffer verfügt, gibt die Funktion FALSE und GetLastErrorERROR_INSUFFICIENT_BUFFER zurück.
Es gibt strenge Anforderungen für die erfolgreiche Arbeit mit Dateien, die mit CreateFile mithilfe des flags FILE_FLAG_NO_BUFFERING geöffnet wurden. Ausführliche Informationen finden Sie unter Dateipufferung.
Wenn hFile mit FILE_FLAG_OVERLAPPED geöffnet wurde, gelten die folgenden Bedingungen:
- Der lpOverlapped-Parameter muss auf eine gültige und eindeutige OVERLAPPED-Struktur verweisen, andernfalls kann die Funktion fälschlicherweise melden, dass der Lesevorgang abgeschlossen ist.
- Der lpNumberOfBytesRead-Parameter sollte auf NULL festgelegt werden. Verwenden Sie die GetOverlappedResult-Funktion , um die tatsächliche Anzahl gelesener 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_OVERLAPPED geöffnet wird, handelt es sich um ein asynchrones Dateihandle. andernfalls ist es synchron. Wie bereits erwähnt, unterscheiden sich die Regeln für die Verwendung der OVERLAPPED-Struktur geringfügig.- ReadFile kann zurückgegeben werden, bevor der Lesevorgang abgeschlossen ist. In diesem Szenario gibt ReadFileFALSE zurück, und die GetLastError-Funktion gibt ERROR_IO_PENDING zurück, sodass der aufrufende Prozess fortgesetzt werden kann, während das System den Lesevorgang abgeschlossen hat.
- Der lpOverlapped-Parameter darf nicht NULL sein und sollte unter Berücksichtigung der folgenden Fakten verwendet werden:
- Obwohl das in der OVERLAPPED-Struktur angegebene Ereignis vom System automatisch festgelegt und zurückgesetzt wird, wird der in der OVERLAPPED-Struktur angegebene Offset nicht automatisch aktualisiert.
- ReadFile setzt das Ereignis auf einen nicht signalierten Zustand zurück, wenn es mit dem E/A-Vorgang beginnt.
- Das in der OVERLAPPED-Struktur angegebene Ereignis wird auf einen Signalzustand 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 möglicherweise zurückgegeben wird, bevor der Lesevorgang auf Systemebene abgeschlossen ist (Lesevorgang aussteht), sollte weder der Offset noch ein anderer Teil der Struktur von der Anwendung geändert, freigegeben oder wiederverwendet werden, bis das Ereignis signalisiert wird (d. h. der Lesevorgang ist abgeschlossen).
- Wenn das Dateiende (End-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_EOF zurück.
- Wenn lpOverlappedNULL ist, wird der Lesevorgang an der aktuellen Dateiposition gestartet, und ReadFile wird erst zurückgegeben, wenn der Vorgang abgeschlossen ist, und das System aktualisiert den Dateizeiger, bevor ReadFile zurückgibt.
- Wenn lpOverlapped nicht NULL ist, beginnt der Lesevorgang mit dem Offset, der in der OVERLAPPED-Struktur angegeben ist, und ReadFile wird erst zurückgegeben, wenn der Lesevorgang abgeschlossen ist. Das System aktualisiert den OVERLAPPED-Offset und den Dateizeiger, bevor ReadFile zurückgegeben wird.
- Wenn lpOverlappedNULL ist, gibt ReadFiletrue zurück und legt auf 0 fest
*lpNumberOfBytesRead, wenn ein synchroner Lesevorgang das Ende einer Datei erreicht. - Wenn lpOverlapped nicht NULL ist, gibt ReadFilefalse undGetLastErrorERROR_HANDLE_EOF zurück, wenn ein synchroner Lesevorgang das Ende einer Datei erreicht.
Rohre
Wenn eine anonyme Pipe verwendet wird und das Schreibhandle geschlossen wurde, gibt die Funktion false und GetLastErrorERROR_BROKEN_PIPE zurück, wenn ReadFile versucht, mithilfe des entsprechenden Lesehandles der Pipe zu lesen.Wenn eine benannte Pipe im Nachrichtenmodus gelesen wird und die nächste Nachricht länger ist als der nNumberOfBytesToRead-Parameter angibt, gibt ReadFileFALSE und GetLastErrorERROR_MORE_DATA zurück. Der Rest der Nachricht kann durch einen nachfolgenden Aufruf der Funktion ReadFile oder PeekNamedPipe gelesen werden.
Wenn der lpNumberOfBytesRead-Parameter 0 ist, wenn ReadFileTRUE für eine Pipe zurückgibt, wird am anderen Ende der Pipe die WriteFile-Funktion aufgerufen, wobei nNumberOfBytesToWrite auf Null festgelegt ist.
Weitere Informationen zu Pipes finden Sie unter Pipes.
Transaktionen
Ist an das Dateihandle eine Transaktion gebunden, gibt die Funktion Daten aus der transaktiven Dateiansicht zurück. Ein transaktives Lesehandle zeigt für die Dauer des Handles garantiert die gleiche Dateiansicht an. Weitere Informationen finden Sie unter Informationen zu Transaktions-NTFS.Unter Windows 8 und Windows Server 2012 wird diese Funktion von den folgenden Technologien unterstützt.
| Technologie | Unterstützt |
|---|---|
| SMB 3.0-Protokoll (Server Message Block) | Ja |
| SMB 3.0 Transparent Failover (TFO) | Ja |
| SMB 3.0 mit Dateifreigaben mit horizontaler Skalierung (SO) | Ja |
| Dateisystem mit freigegebenen Clustervolumes (CsvFS) | Ja |
| Robustes Dateisystem (Resilient File System, ReFS) | Ja |
Beispiele
Ein Codebeispiel, das zeigt, wie Sie auf Dateiende 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.
Anforderungen
| Unterstützte Mindestversion (Client) | Windows XP [Desktop-Apps | UWP-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2003 [Desktop-Apps | UWP-Apps] |
| Zielplattform | Windows |
| Kopfzeile | fileapi.h (Einschließen von Windows.h) |
| Bibliothek | Kernel32.lib |
| DLL | Kernel32.dll |