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