NtReadFile 関数 (ntifs.h)
NtReadFile ルーチンは、開いているファイルからデータを読み取ります。
構文
__kernel_entry NTSYSCALLAPI NTSTATUS NtReadFile(
[in] HANDLE FileHandle,
[in, optional] HANDLE Event,
[in, optional] PIO_APC_ROUTINE ApcRoutine,
[in, optional] PVOID ApcContext,
[out] PIO_STATUS_BLOCK IoStatusBlock,
[out] PVOID Buffer,
[in] ULONG Length,
[in, optional] PLARGE_INTEGER ByteOffset,
[in, optional] PULONG Key
);
パラメーター
[in] FileHandle
ファイル オブジェクトを処理します。 このハンドルは、 NtCreateFile または NtOpenFile を正常に呼び出すことによって作成 されます。
[in, optional] Event
必要に応じて、読み取り操作の完了後にシグナル状態に設定するイベント オブジェクトへのハンドル。 デバイスドライバーと中間ドライバーでは、このパラメーターを NULL に設定する必要があります。
[in, optional] ApcRoutine
このパラメーターは予約されています。 デバイスドライバーと中間ドライバーは、このポインターを NULL に設定する必要があります。
[in, optional] ApcContext
このパラメーターは予約されています。 デバイスドライバーと中間ドライバーは、このポインターを NULL に設定する必要があります。
[out] IoStatusBlock
最終的 な完了 状態と要求された読み取り操作に関する情報を受け取るIO_STATUS_BLOCK構造体へのポインター。 Information メンバーは、ファイルから実際に読み取られたバイト数を受け取ります。
[out] Buffer
ファイルから読み取られたデータを受信する呼び出し元によって割り当てられたバッファーへのポインター。
[in] Length
Buffer が指すバッファーのサイズ (バイト単位)。
[in, optional] ByteOffset
読み取り操作が開始されるファイル内の開始バイト オフセットを指定する変数へのポインター。 ファイルの末尾を超えて読み取ろうとすると、 NtReadFile はエラーを返します。
NtCreateFile の呼び出しで CreateOptions フラグがFILE_SYNCHRONOUS_IO_ALERTまたはFILE_SYNCHRONOUS_IO_NONALERTのいずれかに設定されている場合、I/O マネージャーは現在のファイル位置を維持します。 その場合、 NtReadFile の呼び出し元は、明示的な ByteOffset 値の代わりに現在のファイル位置オフセットを使用するように指定できます。 この仕様は、次のいずれかの方法を使用して行うことができます。
- HighPart メンバーが -1 に設定され、LowPart メンバーがシステム定義値に設定されたLARGE_INTEGER値へのポインター FILE_USE_FILE_POINTER_POSITION指定します。
- ByteOffset に NULL ポインターを渡します。
NtReadFile は、I/O マネージャーによって管理されている現在のファイル位置を使用している場合に、読み取り操作が完了したときに読み取られたバイト数を追加することで、現在のファイル位置を更新します。
I/O マネージャーが現在のファイル位置を維持している場合でも、呼び出し元は明示的な ByteOffset 値を NtReadFile に渡すことによって、この位置をリセットできます。 これを行うと、現在のファイル位置がその ByteOffset 値に自動的に変更され、読み取り操作が実行され、実際に読み取られたバイト数に従って位置が更新されます。 この手法により、呼び出し元にアトミックな seek-and-read サービスが提供されます。
[in, optional] Key
デバイスドライバーと中間ドライバーは、このポインターを NULL に設定する必要があります。
戻り値
NtReadFile は 、STATUS_SUCCESSまたは適切な NTSTATUS エラー コードを返します。
注釈
NtReadFile の呼び出し元は、DesiredAccess パラメーターに設定されたFILE_READ_DATAまたはGENERIC_READ値を持つ NtCreateFile を既に呼び出している必要があります。
上記の NtCreateFile の呼び出しで CreateOptions パラメーターのFILE_NO_INTERMEDIATE_BUFFERING フラグを NtCreateFile に設定した場合、NtReadFile への Length パラメーターと ByteOffset パラメーターはセクター サイズの倍数である必要があります。
NtReadFile は 、指定された ByteOffset または現在のファイル位置から、指定された Buffer への読み取りを開始 します。 次のいずれかの条件で読み取り操作を終了します。
- Length パラメーターで指定されたバイト数が読み取られたため、バッファーがいっぱいです。 そのため、オーバーフローなしでは、これ以上データをバッファーに配置できません。
- 読み取り操作中にファイルの末尾に到達するため、ファイル内のデータをバッファーに転送する必要はありません。
呼び出し元が DesiredAccess に SYNCHRONIZE フラグを設定してファイルを開いた場合、呼び出し元のスレッドは、ファイル ハンドル FileHandle を待機することで、読み取り操作の完了に同期できます。 ハンドルは、ハンドルに対して発行された I/O 操作が完了するたびに通知されます。 ただし、呼び出し元は、同期ファイル アクセス (FILE_SYNCHRONOUS_IO_NONALERTまたはFILE_SYNCHRONOUS_IO_ALERT) のために開かれたハンドルを待機することはできません。 この場合、 NtReadFile は呼び出し元の代わりに待機し、読み取り操作が完了するまで戻りません。 呼び出し元は、次の 3 つの条件がすべて満たされた場合にのみ、ファイル ハンドルを安全に待機できます。
- 非同期アクセス用にハンドルが開かれた (つまり、どちらのFILE_SYNCHRONOUS_IO_XXX フラグも指定されませんでした)。
- ハンドルは、一度に 1 つの I/O 操作にのみ使用されています。
- NtReadFile がSTATUS_PENDING返されました。
次のいずれかの条件が存在する場合、ドライバーはシステム プロセスのコンテキストで NtReadFile を呼び出す必要があります。
- ドライバーは、 NtReadFile に渡すファイル ハンドルを作成しました。
- NtReadFile は、ドライバーが作成したイベントによって、I/O 完了をドライバーに通知します。
- NtReadFile は、ドライバーが NtReadFile に渡す APC コールバック ルーチンを使用して、I/O 完了をドライバーに通知します。
ファイル ハンドルとイベント ハンドルは、ハンドルが作成されるプロセス コンテキストでのみ有効です。 そのため、セキュリティホールを回避するために、ドライバーは、ドライバーが存在するプロセスのコンテキストではなく、システム プロセスのコンテキストで NtReadFile に渡す任意のファイルまたはイベント ハンドルを作成する必要があります。
同様に、APC を使用して I/O 完了をドライバーに通知する場合は、システム プロセスのコンテキストで NtReadFile を呼び出す必要があります。これは、APC は常に I/O 要求を発行するスレッドのコンテキストで発生するためです。 ドライバーがシステム 1 以外のプロセスのコンテキストで NtReadFile を呼び出すと、APC が無期限に遅延したり、まったく起動しない可能性があります。
ファイルの操作の詳細については、「 ドライバーでのファイルの使用」を参照してください。
NtReadFile の呼び出し元は、IRQL = PASSIVE_LEVELで実行され、特殊なカーネル APC が有効になっている必要があります。
この関数の呼び出しがユーザー モードで行われる場合は、"ZwReadFile" ではなく "NtReadFile" という名前を使用する必要があります。
カーネル モード ドライバーからの呼び出しの場合、Windows ネイティブ システム サービス ルーチンの NtXxx および ZwXxx バージョンは、入力パラメーターを処理および解釈する方法で動作が異なります。 ルーチンの NtXxx バージョンと ZwXxx バージョン間の関係の詳細については、「Using Nt and Zw Versions of the Native System Services Routines」を参照してください。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows 2000 |
| 対象プラットフォーム | ユニバーサル |
| Header | ntifs.h (Wdm.h、Ntddk.h、Ntifs.h を含みます) |
| Library | NtosKrnl.lib |
| [DLL] | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL (「解説」セクションを参照) |
| DDI コンプライアンス規則 | BufAfterReqCompletedIntIoctlA、BufAfterReqCompletedIoctlA、BufAfterReqCompletedReadA、BufAfterReqCompletedWriteA、HwStorPortProhibitedDDIs、PowerIrpDDis |