ReadFile 関数 (fileapi.h)
指定したファイルまたは入出力 (I/O) デバイスからデータを読み取ります。 デバイスでサポートされている場合、読み取りはファイル ポインターで指定された位置で行われます。
この関数は、同期操作と非同期操作の両方を対象に設計されています。 非同期操作専用に設計された同様の関数については、「ReadFileEx
構文
BOOL ReadFile(
[in] HANDLE hFile,
[out] LPVOID lpBuffer,
[in] DWORD nNumberOfBytesToRead,
[out, optional] LPDWORD lpNumberOfBytesRead,
[in, out, optional] LPOVERLAPPED lpOverlapped
);
パラメーター
[in] hFile
デバイスへのハンドル (ファイル、ファイル ストリーム、物理ディスク、ボリューム、コンソール バッファー、テープ ドライブ、ソケット、通信リソース、mailslot、パイプなど)。
hFile パラメーターは、読み取りアクセス権で作成されている必要があります。 詳細については、「一般的なアクセス権
非同期読み取り操作の場合、
[out] lpBuffer
ファイルまたはデバイスから読み取られたデータを受け取るバッファーへのポインター。
このバッファーは、読み取り操作の期間中有効なままである必要があります。 呼び出し元は、読み取り操作が完了するまで、このバッファーを使用しないでください。
[in] nNumberOfBytesToRead
読み取る最大バイト数。
[out, optional] lpNumberOfBytesRead
同期 hFile パラメーターを使用するときに読み取られたバイト数を受け取る変数へのポインター。 ReadFile は、作業またはエラー チェックを実行する前に、この値を 0 に設定します。 このパラメーター NULL を使用すると、誤った結果を回避する非同期操作になります。
このパラメーターは、
詳細については、「解説」セクションを参照してください。
[in, out, optional] lpOverlapped
hFile
バイト オフセットをサポートする hFile の場合、このパラメーターを使用する場合は、ファイルまたはデバイスからの読み取りを開始するバイト オフセットを指定する必要があります。 このオフセットは、
lpOverlapped と
戻り値
関数が成功した場合、戻り値は 0 以外 (true
関数が失敗した場合、または非同期的に完了している場合、戻り値は 0 (FALSE
手記
GetLastError コード ERROR_IO_PENDING は失敗ではありません。読み取り操作が非同期的に完了待ちであることを指定します。 詳細については、「解説」を参照してください。
備考
ReadFile 関数は、次のいずれかの条件が発生すると返されます。
- 要求されたバイト数が読み取られます。
- パイプの書き込み終了時に書き込み操作が完了します。
- 非同期ハンドルが使用されており、読み取りが非同期的に発生しています。
- エラーが発生します。
ReadFile 関数は、未処理の非同期 I/O 要求が多すぎると、ERROR_INVALID_USER_BUFFER または ERROR_NOT_ENOUGH_MEMORY で失敗する可能性があります。
保留中のすべての非同期 I/O 操作を取り消すには、次のいずれかを使用します。
- CancelIo: この関数は、指定されたファイル ハンドルの呼び出し元スレッドによって発行された操作のみを取り消します。
- CancelIoEx: この関数は、指定されたファイル ハンドルに対してスレッドによって発行されたすべての操作を取り消します。
CancelSynchronousIo を使用して、保留中の同期 I/O 操作を取り消します。
取り消された I/O 操作は、エラー ERROR_OPERATION_ABORTEDで完了します。
ReadFile 関数は、ERROR_NOT_ENOUGH_QUOTAで失敗する可能性があります。つまり、呼び出し元のプロセスのバッファーをページ ロックできませんでした。 詳細については、「SetProcessWorkingSetSize
ファイルの一部が別のプロセスによってロックされていて、読み取り操作がロックされた部分と重複している場合、この関数は失敗します。
読み取り操作でバッファーを使用しているときに入力バッファーにアクセスすると、そのバッファーに読み込まれるデータが破損する可能性があります。 アプリケーションは、読み取り操作が完了するまで、読み取り操作で使用されている入力バッファーの読み取り、書き込み、再割り当て、または解放を行う必要はありません。 これは、非同期ファイル ハンドルを使用する場合に特に問題になる可能性があります。 同期ファイル ハンドルと非同期ファイル ハンドルの詳細については、「同期とファイル位置の」セクションと「CreateFile リファレンス トピック」を参照してください。
ReadFile とコンソール入力のハンドルを使用して、コンソール入力バッファーから文字を読み取ることができます。 コンソール モードは、ReadFile 関数の正確な動作を決定します。 既定では、コンソール モードは ENABLE_LINE_INPUTです。これは、ReadFile が復帰に達するまで読み取る必要があることを示します。 Ctrl キーを押しながら C キーを押すと呼び出しは成功しますが、GetLastError
通信デバイスから読み取る場合、
FILE_FLAG_NO_BUFFERING フラグを使用して CreateFile で開かれたファイルを正常に操作するための厳密な要件があります。 詳細については、「ファイル バッファリングの」を参照してください。
hFile が FILE_FLAG_OVERLAPPEDで開かれた場合、次の条件が有効になります。
- lpOverlapped パラメーターは、有効で一意の OVERLAPPED 構造体を指している必要があります。それ以外の場合、関数は読み取り操作が完了したことを誤って報告する可能性があります。
lpNumberOfBytesRead パラメーターを NULL設定する必要があります。 GetOverlappedResult 関数を使用して、読み取られた実際のバイト数を取得します。 hFile パラメーターが I/O 完了ポートに関連付けられている場合は、GetQueuedCompletionStatus 関数を呼び出すことによって読み取られたバイト数を取得することもできます。
同期とファイルの位置
FILE_FLAG_OVERLAPPEDhFile を開くと、非同期ファイル ハンドルになります。それ以外の場合は同期です。 前述のように、OVERLAPPED 構造体を使用する規則はそれぞれ若干異なります。
手記
非同期 I/O 用にファイルまたはデバイスを開いた場合、そのハンドルを使用、
非同期ファイル ハンドルの操作に関する考慮事項:
-
ReadFile は、読み取り操作が完了する前に返される場合があります。 このシナリオでは、
ReadFile は FALSE返し、 GetLastError 関数はERROR_IO_PENDING を返します。これにより、システムが読み取り操作を完了している間も呼び出しプロセスを続行できます。 lpOverlapped パラメーターは NULLすることはできません。また、次の点を念頭に置いて使用してください。 - OVERLAPPED 構造体で指定されたイベントはシステムによって自動的に設定およびリセットされますが、OVERLAPPED 構造体で指定されたオフセットは自動的に更新されません。
- ReadFile は、I/O 操作の開始時にイベントを非署名状態にリセットします。
- OVERLAPPED 構造体で指定されたイベントは、読み取り操作が完了するとシグナル状態に設定されます。その時点まで、読み取り操作は保留中と見なされます。
- 読み取り操作は、OVERLAPPED 構造体で指定されたオフセットから開始され、システム レベルの読み取り操作が完了する前に readFile が戻る可能性があるため (読み取り保留中)、オフセットも構造体の他の部分も、イベントが通知されるまでアプリケーションによって変更、解放、または再利用される必要はありません (つまり、 読み取りが完了しました)。
- 非同期操作中にファイルの終わり (EOF) が検出された場合、その操作の GetOverlappedResult
呼び出しは FALSE 返し、GetLastError は ERROR_HANDLE_EOF を返します。
同期ファイル ハンドルの操作に関する考慮事項:
- lpOverlapped が NULL
場合、読み取り操作は現在のファイル位置から開始され、 ReadFile は操作が完了するまで戻らず、システムは ReadFile を返す前にファイル ポインター更新します。 - lpOverlapped が NULL
場合、読み取り操作は、 OVERLAPPED 構造体で指定されたオフセットから開始され、読み取り操作が完了するまで ReadFile戻りません。 システムは、OVERLAPPED オフセットとファイル ポインター ReadFile が返される前に更新します。 - lpOverlapped
NULL 場合、同期読み取り操作がファイルの末尾に到達すると、 ReadFile は TRUE返し、 を 0 に設定します。 - lpOverlapped
NULL でない場合、同期読み取り操作がファイルの末尾に達すると、 ReadFile は FALSE返し、GetLastError は ERROR_HANDLE_EOF を返します。
詳細については、「CreateFile と同期および非同期 I/O
パイプ
匿名パイプが使用されていて、書き込みハンドルが閉じられている場合、readFile
名前付きパイプがメッセージ モードで読み取られ、次のメッセージが nNumberOfBytesToRead パラメーターで指定
パイプで
パイプの詳細については、「パイプを
トランザクション操作
ファイル ハンドルにバインドされたトランザクションがある場合、関数はファイルのトランザクション ビューからデータを返します。 トランザクション読み取りハンドルは、ハンドルの期間中、ファイルの同じビューを表示することが保証されます。 詳細については、「トランザクション NTFSについて」を参照してください。
Windows 8 および Windows Server 2012 では、この関数は次のテクノロジでサポートされています。
| テクノロジー | サポート |
|---|---|
| サーバー メッセージ ブロック (SMB) 3.0 プロトコル | はい |
| SMB 3.0 透過的フェールオーバー (TFO) | はい |
| SMB 3.0 とスケールアウト ファイル共有 (SO) | はい |
| クラスター共有ボリューム ファイル システム (CsvFS) | はい |
| 回復性のあるファイル システム (ReFS) | はい |
例
ファイルの終わりをテストする方法を示すコード例については、「ファイルの末尾のテスト を参照してください。 その他の例については、「
必要条件
| 要件 | 価値 |
|---|---|
| サポートされる最小クライアント | Windows XP [デスクトップ アプリ |UWP アプリ] |
| サポートされる最小サーバー | Windows Server 2003 [デスクトップ アプリ |UWP アプリ] |
| ターゲット プラットフォーム の |
ウィンドウズ |
| ヘッダー | fileapi.h (Windows.h を含む) |
| ライブラリ | Kernel32.lib |
| DLL | Kernel32.dll |
関連項目
CancelIo を
CancelIoEx を
CancelSynchronousIo の
CreateFile の
GetCommTimeouts の
GetOverlappedResult の
GetQueuedCompletionStatus を
重複する を
PeekNamedPipe の
ReadFileEx の
SetCommTimeouts の
SetErrorMode の
WriteFile の