NtWriteFile 関数 (ntifs.h)

ZwWriteFile ルーチンは、開いているファイルにデータを書き込みます。

構文

__kernel_entry NTSYSCALLAPI NTSTATUS NtWriteFile(
  [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

ファイルオブジェクトへのハンドル。このハンドルは、 NtCreateFile または NtOpenFile を正常に呼び出すことによって作成 されます。

[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 が現在のファイルの末尾のマークを超えて書き込み操作を指定した場合、NtWriteFile は自動的にファイルを拡張し、ファイルの末尾のマークを更新します。このような古いファイルの終わりと新しいファイルの終わりのマークの間に明示的に書き込まれていないバイトはすべて、ゼロとして定義されます。

NtCreateFile の呼び出しで DesiredAccess フラグFILE_APPEND_DATAのみが設定されている場合、ByteOffset は無視されます。指定された Buffer 内のデータ ( Length バイト) は、ファイルの現在の末尾から書き込まれます。

NtCreateFile の呼び出しが CreateOptions フラグ、FILE_SYNCHRONOUS_IO_ALERT、またはFILE_SYNCHRONOUS_IO_NONALERTのいずれかを設定した場合、I/O マネージャーは現在のファイル位置を維持します。その場合、 NtWriteFile の呼び出し元は、明示的な ByteOffset 値の代わりに現在のファイル位置オフセットを使用するように指定できます。この仕様は、次のいずれかの方法を使用して行うことができます。

HighPart メンバーが -1 に設定され、LowPart メンバーがシステム定義値に設定されているLARGE_INTEGER値へのポインター FILE_USE_FILE_POINTER_POSITION指定します。
ByteOffset に NULL ポインターを渡します。

NtWriteFile は、I/O マネージャーによって保持されている現在のファイル位置を使用している場合、書き込み操作の完了時に書き込まれたバイト数を追加することで、現在のファイル位置を更新します。

I/O マネージャーが現在のファイル位置を維持している場合でも、呼び出し元は明示的な ByteOffset 値を NtWriteFile に渡すことによって、この位置をリセットできます。これにより、現在のファイル位置がその ByteOffset 値に自動的に変更され、書き込み操作が実行され、実際に書き込まれたバイト数に従って位置が更新されます。この手法により、呼び出し元にアトミックなシークアンドライトサービスが提供されます。

また、HighPart を -1 に設定し、LowPart を FILE_WRITE_TO_END_OF_FILE に設定したLARGE_INTEGER値へのポインターを ByteOffset に指定することで、書き込み操作をファイルの現在の末尾から開始することもできます。これは、I/O マネージャーが現在のファイル位置を維持しているかどうかに関係なく機能します。

[in, optional] Key

デバイスドライバーと中間ドライバーは、このポインターを NULL に設定する必要があります。

戻り値

NtWriteFile は、成功した場合はSTATUS_SUCCESSを返し、失敗した場合は適切な NTSTATUS エラーコードを返します。

注釈

NtWriteFile の呼び出し元は、DesiredAccess パラメーターに設定されたFILE_WRITE_DATA、FILE_APPEND_DATA、またはGENERIC_WRITE フラグを使用して NtCreateFile を既に呼び出している必要があります。ファイルにFILE_APPEND_DATAアクセスするだけでは、呼び出し元は現在のファイルの末尾を除き、ファイル内の任意の場所に書き込むことはありませんが、ファイルにFILE_WRITE_DATAアクセスしても、呼び出し元がファイルの末尾との間で書き込みを妨げることはありません。

上記の NtCreateFile の呼び出しで CreateOptions フラグがFILE_NO_INTERMEDIATE_BUFFERING設定されている場合、Length パラメーターと ByteOffset パラメーターを NtWriteFile に設定するには、セクターサイズの整数を指定する必要があります。詳細については、「 NtCreateFile」を参照してください。

NtWriteFile は、 ByteOffset、現在のファイル位置、またはファイルの末尾にあるファイルへの書き込み操作を開始します。 Buffer から Length バイトを書き込むと、書き込み操作が終了 します。必要に応じて、ファイルの長さを拡張し、ファイルの末尾のマークをリセットします。

呼び出し元 が DesiredAccess SYNCHRONIZE フラグを設定してファイルを開いた場合、呼び出し元は、このルーチンが指定された FileHandle を シグナル状態に設定するのを待機できます。

ドライバーは、次の 3 つの場合に、システムプロセスのコンテキストで NtWriteFile を呼び出す必要があります。

ドライバーは、 NtWriteFile に渡すファイルハンドルを作成します。
NtWriteFile は、ドライバーによって作成されたイベントを使用して、I/O 完了をドライバーに通知します。
NtWriteFile は、ドライバーが NtWriteFile に渡す APC コールバックルーチンを使用して、I/O 完了をドライバーに通知します。

ファイルハンドルとイベントハンドルは、ハンドルが作成されるプロセスコンテキストでのみ有効です。そのため、セキュリティホールを回避するために、ドライバーは、ドライバーが存在するプロセスコンテキストではなく、システムプロセスのコンテキストで NtWriteFile に渡す任意のファイルまたはイベントハンドルを作成する必要があります。

同様に、APC を使用して I/O 完了をドライバーに通知する場合は、システムプロセスのコンテキストで NtWriteFile を呼び出す必要があります。これは、APC が I/O 要求を発行するスレッドのコンテキストで常に発生するためです。ドライバーがシステムプロセス以外のプロセスのコンテキストで NtWriteFile を 呼び出した場合、APC が無期限に遅延する可能性があります。または、発生元のスレッドがアラート可能な待機状態に入らない可能性があるため、まったく起動しない可能性があります。

ファイルの操作の詳細については、「ドライバーでのファイルの使用」を参照してください。

NtWriteFile の呼び出し元は、IRQL = PASSIVE_LEVELで実行され、特殊なカーネル API が有効になっている必要があります。

この関数の呼び出しがユーザーモードで発生する場合は、"ZwWriteFile" ではなく "NtWriteFile" という名前を使用する必要があります。

カーネルモードドライバーからの呼び出しの場合、Windows ネイティブシステムサービスルーチンの NtXxx および ZwXxx バージョンは、入力パラメーターを処理および解釈する方法で動作が異なる場合があります。ルーチンの NtXxx と ZwXxx バージョンの間の関係の詳細については、「ネイティブシステムサービスルーチンの Nt および Zw バージョンの使用を参照してください。

Requirements

Requirement	価値
サポートされる最小クライアント	Windows 2000
ターゲットプラットフォームの	万国
Header	ntifs.h (Wdm.h、Ntddk.h、Ntifs.h を含む)
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (「解説」セクションを参照)
DDI コンプライアンス規則をする	HwStorPortProhibitedDIs、PowerIrpDDis