IoCreateSystemThread 関数 (wdm.h)

[アーティクル]
2025/02/07

IoCreateSystemThread ルーチンは、カーネルモードで実行されるシステムスレッドを作成し、スレッドのハンドルを提供します。

構文

C++

NTSTATUS IoCreateSystemThread(
  [in, out]       PVOID              IoObject,
  [out]           PHANDLE            ThreadHandle,
  [in]            ULONG              DesiredAccess,
  [in, optional]  POBJECT_ATTRIBUTES ObjectAttributes,
  [in, optional]  HANDLE             ProcessHandle,
  [out, optional] PCLIENT_ID         ClientId,
  [in]            PKSTART_ROUTINE    StartRoutine,
  [in, optional]  PVOID              StartContext
);

パラメーター

[in, out] IoObject

作成されたスレッドに関連付ける DEVICE_OBJECT または DRIVER_OBJECT へのポインター。 IoCreateSystemThread は、このオブジェクトへのカウントされた参照を受け取ります。 I/O マネージャーは、後でスレッドが終了したときにこの参照を解放します。詳細については、「解説」を参照してください。

[out] ThreadHandle

ルーチンが作成されたスレッドのカーネルハンドルを書き込む変数へのポインター。ハンドルが不要になったら、ドライバーは、ZwClose ルーチンを呼び出すことによってハンドルを閉じる必要があります。

[in] DesiredAccess

作成されたスレッドに対する呼び出し元要求のアクセスの種類を表す ACCESS_MASK 値。

[in, optional] ObjectAttributes

スレッドオブジェクトの属性を指定する OBJECT_ATTRIBUTES 構造体へのポインター。 OBJ_PERMANENT、OBJ_EXCLUSIVE、およびOBJ_OPENIF属性は、スレッドオブジェクトの有効な属性ではありません。呼び出し元がシステムプロセスコンテキストで実行されていない場合は、OBJECT_ATTRIBUTES 構造体でOBJ_KERNEL_HANDLE属性を設定する必要があります。

[in, optional] ProcessHandle

作成されたスレッドが実行されるアドレス空間を持つプロセスのオープンハンドル。呼び出し元のスレッドは、このプロセスPROCESS_CREATE_THREADアクセスできる必要があります。このパラメーターが NULL 場合、スレッドは初期システムプロセスで作成されます。このパラメーターは、ドライバーによって作成されたスレッドの NULL する必要があります。 Wdm.h ヘッダーファイルで定義されている NtCurrentProcess マクロを使用して、現在のプロセスを指定します。

[out, optional] ClientId

ルーチンが作成されたスレッドのクライアント識別子を書き込む構造体へのポインター。このパラメーターは、ドライバーによって作成されたスレッドの NULL する必要があります。

[in] StartRoutine

作成されたスレッドのエントリポイントである ThreadStart ルーチンへのポインター。

[in, optional] StartContext

作成されたスレッドの実行を開始するときに、StartContext パラメーターとして ThreadStart ルーチンに渡されるコンテキストポインター。

戻り値

IoCreateSystemThread は、新しいスレッドが正常に作成された場合にSTATUS_SUCCESSを返します。可能な戻り値には、次のエラー状態コードが含まれます。

リターンコード	形容
STATUS_INVALID_HANDLE	ProcessHandle は有効なプロセスハンドルではありません。
STATUS_PROCESS_IS_TERMINATING	ProcessHandle で指定されたプロセスが終了しています。
STATUS_INSUFFICIENT_RESOURCES	要求された操作を実行するために使用できるシステムリソースが不足しています。

備考

Windows 8 以降、ドライバーは IoCreateSystemThread 呼び出して、デバイス専用スレッドを作成できます。このルーチンは、スレッド環境ブロック (TEB) またはユーザーモードコンテキストを持たない新しいシステムスレッドを作成し、カーネルモードでのみ実行します。

通常、ドライバーは、デバイスを起動するとき、またはドライバーの DispatchXxx ルーチンが I/O 要求の受信を開始するときに、IoCreateSystemThread を呼び出します。たとえば、ドライバーはこのルーチンを呼び出して、ディスパッチXxx ルーチンが非同期デバイス制御要求を受け取ったときにスレッドを作成する場合があります。

ProcessHandle パラメーターが NULL 場合、作成されたスレッドはシステムプロセスに関連付けられます。このようなスレッドは、システムがシャットダウンされるか、スレッドが終了するまで実行を続けます。

システムプロセス以外のプロセスコンテキストで実行されるドライバールーチンは、IoCreateSystemThread の ObjectAttributes パラメーターのOBJ_KERNEL_HANDLE属性設定する必要があります。この属性は、IoCreateSystemThread によって返されるハンドルの使用をカーネルモードで実行されているプロセスに制限します。それ以外の場合は、ドライバーが実行されているコンテキスト内のプロセスによってスレッドハンドルにアクセスできます。ドライバーは、次のコード例に示すように、InitializeObjectAttributes マクロを呼び出して、オブジェクト属性のOBJ_KERNEL_HANDLE属性を設定できます。

C++

OBJECT_ATTRIBUTES ObjectAttributes;

InitializeObjectAttributes(&ObjectAttributes, NULL, OBJ_KERNEL_HANDLE, NULL, NULL);

IoCreateSystemThread は、PsCreateSystemThread ルーチンに似ていますが、呼び出し元のドライバーオブジェクトまたはデバイスオブジェクトへのポインターである IoObject 追加のパラメーターがあります。 IoCreateSystemThread は、このパラメーターを使用して、作成されたスレッドが存在する間、ドライバーがアンロードできないようにします。 StartRoutine をこのスレッドで実行するようにスケジュールする前に、IoCreateSystemThread は、IoObject オブジェクトへのカウントされた参照を受け取ります。 I/O マネージャーは、作成されたスレッドが終了した後、この参照を解放します。したがって、このオブジェクトは、作成されたスレッドの有効期間中保持されます。

PsCreateSystemThread ルーチンによって作成されたシステムスレッドとは異なり、IoCreateSystemThread によって作成されたスレッドは、PsTerminateSystemThread ルーチンを呼び出して自身を終了しません。代わりに、I/O マネージャーは、スレッドが終了したときに、作成されたスレッドの代わりに PsTerminateSystemThread を呼び出します。

必要条件

要件	価値
サポートされる最小クライアント	Windows 8 以降で使用できます。
ターゲットプラットフォームの	万国
ヘッダー	wdm.h (Wdm.h、Ntddk.h、Ntifs.h を含む)
ライブラリ	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL

次の方法で共有

IoCreateSystemThread 関数 (wdm.h)

構文

パラメーター

戻り値

備考

必要条件

関連項目

フィードバック

その他のリソース