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 パラメーターは、読み取りアクセス権を使用して作成されている必要があります。 詳細については、「 汎用アクセス権 」および「 ファイル セキュリティとアクセス権」を参照してください。
非同期読み取り操作の場合、hFile には、CreateFile 関数によってFILE_FLAG_OVERLAPPED フラグで開かれた任意のハンドル、またはソケットまたは accept 関数によって返されるソケット ハンドルを指定できます。
[out] lpBuffer
ファイルまたはデバイスから読み取られたデータを受信するバッファーへのポインター。
このバッファーは、読み取り操作の間は有効なままである必要があります。 読み取り操作が完了するまで、呼び出し元はこのバッファーを使用しないでください。
[in] nNumberOfBytesToRead
読み取る最大バイト数です。
[out, optional] lpNumberOfBytesRead
同期 hFile パラメーターを使用するときに読み取られたバイト数を受け取る変数へのポインター。 ReadFile は 、作業またはエラー チェックを行う前に、この値を 0 に設定します。 このパラメーターが非同期操作の場合は NULL を 使用して、誤った結果を回避します。
このパラメーターは、lpOverlapped パラメーターが NULL でない場合にのみ NULL にすることができます。
Windows 7: このパラメーターを NULL にすることはできません。
詳細については、「解説」を参照してください。
[in, out, optional] lpOverlapped
hFile パラメーターが FILE_FLAG_OVERLAPPED で開かれた場合は、OVERLAPPED 構造体へのポインターが必要です。それ以外の場合は NULL にすることができます。
hFile がFILE_FLAG_OVERLAPPEDで開かれている場合、lpOverlapped パラメーターは有効で一意の OVERLAPPED 構造体を指す必要があります。そうしないと、関数が読み取り操作が完了したことを誤って報告する可能性があります。
バイト オフセットをサポートする hFile の場合、このパラメーターを使用する場合は、ファイルまたはデバイスからの読み取りを開始するバイト オフセットを指定する必要があります。 このオフセットは、OVERLAPPED 構造体の Offset メンバーと OffsetHigh メンバーを設定することによって指定されます。 バイト オフセットをサポートしない hFile の場合、 Offset と OffsetHigh は無視されます。
lpOverlapped とFILE_FLAG_OVERLAPPEDのさまざまな組み合わせの詳細については、「解説」セクションと「同期とファイルの位置」セクションを参照してください。
戻り値
関数が成功した場合、戻り値は 0 以外 (TRUE) になります。
関数が失敗した場合、または非同期的に完了している場合、戻り値は 0 (FALSE) です。 エラーの詳細情報を得るには、GetLastError 関数を呼び出します。
解説
ReadFile 関数は、次のいずれかの条件が発生すると を返します。
- 要求されたバイト数が読み取られます。
- パイプの書き込み終了時に書き込み操作が完了します。
- 非同期ハンドルが使用されており、読み取りが非同期的に実行されています。
- エラーが発生しました。
readFile 関数は、未処理の非同期 I/O 要求が多すぎる場合は常に、ERROR_INVALID_USER_BUFFERまたはERROR_NOT_ENOUGH_MEMORYで失敗する可能性があります。
保留中のすべての非同期 I/O 操作を取り消すには、次のいずれかを使用します。
- CancelIo — この関数は、指定されたファイル ハンドルに対して呼び出し元スレッドによって発行された操作のみを取り消します。
- CancelIoEx — この関数は、指定されたファイル ハンドルに対してスレッドによって発行されたすべての操作を取り消します。
保留中の同期 I/O 操作を取り消すには、CancelSynchronousIo を使用します。
取り消された I/O 操作は、エラー ERROR_OPERATION_ABORTEDで完了します。
ReadFile 関数は、ERROR_NOT_ENOUGH_QUOTAで失敗する可能性があります。つまり、呼び出し元のプロセスのバッファーをページ ロックできませんでした。 詳細については、「 SetProcessWorkingSetSize」を参照してください。
ファイルの一部が別のプロセスによってロックされていて、読み取り操作がロックされた部分と重複している場合、この関数は失敗します。
読み取り操作でバッファーを使用しているときに入力バッファーにアクセスすると、そのバッファーに読み取られたデータが破損する可能性があります。 アプリケーションは、読み取り操作が完了するまで、読み取り操作で使用されている入力バッファーの読み取り、書き込み、再割り当て、または解放を行う必要はありません。 これは、非同期ファイル ハンドルを使用する場合に特に問題になる可能性があります。 同期と非同期のファイル ハンドルに関する追加情報については、「 同期とファイルの位置 」セクションと「 CreateFile リファレンス」トピックを参照してください。
コンソール入力へのハンドルを持つ ReadFile を使用して、コンソール入力バッファーから文字を読み取ることができます。 コンソール モードは 、ReadFile 関数の正確な動作を決定します。 既定では、コンソール モードは ENABLE_LINE_INPUTです。これは、復帰に達するまで ReadFile を読み取る必要があることを示します。 Ctrl キーを押しながら C キーを押すと、呼び出しは成功しますが、GetLastError はERROR_OPERATION_ABORTEDを返します。 詳細については、CreateFile のページを参照してください。
通信デバイスから読み取る場合、ReadFile の動作は、SetCommTimeouts 関数と GetCommTimeouts 関数を使用して設定および取得される現在の通信タイムアウトによって決定されます。 タイムアウト値の設定に失敗すると、予期しない結果が発生する可能性があります。 通信タイムアウトの詳細については、「 COMMTIMEOUTS」を参照してください。
ReadFile がバッファーが小さすぎる mailslot から読み取ろうとすると、関数は FALSE を返し、GetLastError はERROR_INSUFFICIENT_BUFFERを返します。
FILE_FLAG_NO_BUFFERING フラグを使用して CreateFile で開かれたファイルを正常に操作するための厳密な要件があります。 詳細については、「 ファイルバッファリング」を参照してください。
hFile が FILE_FLAG_OVERLAPPED で開かれた場合、次の条件が有効になります。
- lpOverlapped パラメーターは、有効で一意の OVERLAPPED 構造体を指す必要があります。それ以外の場合、関数は読み取り操作が完了したことを誤って報告する可能性があります。
- lpNumberOfBytesRead パラメーターは NULL に設定する必要があります。 GetOverlappedResult 関数を使用して、読み取られた実際のバイト数を取得します。 hFile パラメーターが I/O 入力候補ポートに関連付けられている場合は、GetQueuedCompletionStatus 関数を呼び出すことによって読み取られたバイト数を取得することもできます。
同期とファイルの位置
hFile を FILE_FLAG_OVERLAPPED で開くと、非同期ファイル ハンドルになります。それ以外の場合は同期です。 OVERLAPPED 構造体を使用する規則は、前に説明したように、それぞれについて若干異なります。- 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 オフセットとファイル ポインターを更新します。
- lpOverlapped が NULL の場合、同期読み取り操作がファイルの末尾に達すると、ReadFile は TRUE を返し、0 に設定します
*lpNumberOfBytesRead。 - lpOverlapped が NULL でない場合、同期読み取り操作がファイルの末尾に達すると、ReadFile は FALSE を返し、GetLastError はERROR_HANDLE_EOFを返します。
パイプ
匿名パイプが使用されていて、書き込みハンドルが閉じられている場合、ReadFile がパイプの対応する読み取りハンドルを使用して読み取りを試みると、関数は FALSE を返し、GetLastError はERROR_BROKEN_PIPEを返します。名前付きパイプがメッセージ モードで読み取られ、次のメッセージが nNumberOfBytesToRead パラメーターで指定したよりも長い場合、ReadFile は FALSE を返し、GetLastError はERROR_MORE_DATAを返します。 メッセージの残りの部分は、 ReadFile または PeekNamedPipe 関数の後続の呼び出しで読み取ることができます。
パイプで ReadFile が TRUE を返したときに lpNumberOfBytesRead パラメーターが 0 の場合、パイプのもう一方の末尾は、nNumberOfBytesToWrite が 0 に設定された WriteFile 関数と呼ばれます。
パイプの詳細については、「 パイプ」を参照してください。
Transacted Operations
ファイル ハンドルにバインドされたトランザクションがある場合、関数はファイルのトランザクション処理対象ビューからデータを返します。 トランザクション処理対象の読み取りハンドルは、ハンドルの存続期間中、ファイルの同じビューを表示することが保証されます。 詳細については、「 トランザクション NTFS について」を参照してください。Windows 8 と Windows Server 2012 では、この関数は、次のテクノロジによってサポートされています。
| テクノロジ | サポートされています |
|---|---|
| サーバー メッセージ ブロック (SMB) 3.0 プロトコル | はい |
| SMB 3.0 Transparent Failover (TFO) | はい |
| スケールアウト ファイル共有 (SO) を使う SMB 3.0 | はい |
| クラスターの共有ボリューム ファイル システム (CsvFS) | はい |
| Resilient File System (ReFS) | はい |
例
ファイルの終わりをテストする方法を示すコード例については、「ファイルの 終わりのテスト」を参照してください。 その他の例については、「 一時ファイルの作成と使用」および 「 読み取りまたは書き込み用にファイルを開く」を参照してください。
要件
| サポートされている最小のクライアント | Windows XP [デスクトップ アプリ | UWP アプリ] |
| サポートされている最小のサーバー | Windows Server 2003 [デスクトップ アプリのみ | UWP アプリ] |
| 対象プラットフォーム | Windows |
| ヘッダー | fileapi.h (Windows.h を含む) |
| Library | Kernel32.lib |
| [DLL] | Kernel32.dll |