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 関数を呼び出します。
Remarks
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 は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 プロトコル | Yes |
| SMB 3.0 Transparent Failover (TFO) | Yes |
| SMB 3.0 とスケールアウト ファイル共有 (SO) | Yes |
| クラスター共有ボリューム ファイル システム (CsvFS) | はい |
| Resilient File System (ReFS) | はい |
例
ファイルの終わりをテストする方法を示すコード例については、「ファイルの 終わりのテスト」を参照してください。 その他の例については、「 一時ファイルの作成と使用」および 「 読み取りまたは書き込みのためにファイルを開く」を参照してください。
要件
| サポートされている最小のクライアント | Windows XP [デスクトップ アプリの|UWP アプリ] |
| サポートされている最小のサーバー | Windows Server 2003 [デスクトップ アプリ |UWP アプリ] |
| 対象プラットフォーム | Windows |
| ヘッダー | fileapi.h (Windows.h を含む) |
| Library | Kernel32.lib |
| [DLL] | Kernel32.dll |