IoCreateSystemThread function (wdm.h)
The IoCreateSystemThread routine creates a system thread that executes in kernel mode, and supplies a handle for the thread.
Syntax
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
);
Parameters
[in, out] IoObject
A pointer to the DEVICE_OBJECT or DRIVER_OBJECT to associate with the created thread. IoCreateSystemThread takes a counted reference to this object. The I/O manager later releases this reference when the thread exits. For more information, see Remarks.
[out] ThreadHandle
A pointer to a variable to which the routine writes the kernel handle for the created thread. When the handle is no longer needed, the driver must close the handle by calling the ZwClose routine.
[in] DesiredAccess
The ACCESS_MASK value that represents the types of access the caller requests to the created thread.
[in, optional] ObjectAttributes
A pointer to an OBJECT_ATTRIBUTES structure that specifies the thread object's attributes. The OBJ_PERMANENT, OBJ_EXCLUSIVE, and OBJ_OPENIF attributes are not valid attributes for a thread object. If the caller is not running in the system process context, it must set the OBJ_KERNEL_HANDLE attribute in the OBJECT_ATTRIBUTES structure.
[in, optional] ProcessHandle
An open handle for the process in whose address space the created thread is to run. The caller's thread must have PROCESS_CREATE_THREAD access to this process. If this parameter is NULL, the thread will be created in the initial system process. This parameter should be NULL for a driver-created thread. Use the NtCurrentProcess macro, defined in the Wdm.h header file, to specify the current process.
[out, optional] ClientId
A pointer to a structure to which the routine writes the client identifier for the created thread. This parameter should be NULL for a driver-created thread.
[in] StartRoutine
A pointer to a ThreadStart routine that is the entry point for the created thread.
[in, optional] StartContext
A context pointer that is passed as the StartContext parameter to the ThreadStart routine when the created thread starts to run.
Return value
IoCreateSystemThread returns STATUS_SUCCESS if the new thread was successfully created. Possible return values include the following error status codes.
| Return code | Description |
|---|---|
| STATUS_INVALID_HANDLE | ProcessHandle is not a valid process handle. |
| STATUS_PROCESS_IS_TERMINATING | The process specified by ProcessHandle is terminating. |
| STATUS_INSUFFICIENT_RESOURCES | Insufficient system resources are available to perform the requested operation. |
Remarks
Starting with Windows 8, a driver can call IoCreateSystemThread to create a device-dedicated thread. This routine creates a new system thread that has no thread environment block (TEB) or user-mode context, and runs only in kernel mode.
Typically, the driver calls IoCreateSystemThread either when it starts the device, or when the driver's DispatchXxx routines start to receive I/O requests. For example, a driver might call this routine to create a thread when a DispatchXxx routine receives an asynchronous device control request.
If the ProcessHandle parameter is NULL, the created thread is associated with the system process. Such a thread continues running until either the system is shut down or the thread exits.
Driver routines that run in a process context other than that of the system process must set the OBJ_KERNEL_HANDLE attribute for the ObjectAttributes parameter of IoCreateSystemThread. This attribute restricts the use of the handle returned by IoCreateSystemThread to processes running in kernel mode. Otherwise, the thread handle could be accessed by the process in whose context the driver is running. Drivers can call the InitializeObjectAttributes macro to set the OBJ_KERNEL_HANDLE attribute in the object attributes, as shown in the following code example.
OBJECT_ATTRIBUTES ObjectAttributes;
InitializeObjectAttributes(&ObjectAttributes, NULL, OBJ_KERNEL_HANDLE, NULL, NULL);
IoCreateSystemThread is similar to the PsCreateSystemThread routine, but has an additional parameter, IoObject, which is a pointer to the caller's driver object or device object. IoCreateSystemThread uses this parameter to ensure that the driver cannot unload while the created thread exists. Before scheduling StartRoutine to run in this thread, IoCreateSystemThread takes a counted reference to the IoObject object. The I/O manager releases this reference after the created thread exits. Thus, this object persists for the lifetime of the created thread.
In contrast to a system thread that is created by the PsCreateSystemThread routine, a thread created by IoCreateSystemThread does not call the PsTerminateSystemThread routine to terminate itself. Instead, the I/O manager calls PsTerminateSystemThread on behalf of the created thread when the thread exits.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Available starting with Windows 8. |
| Target Platform | Universal |
| Header | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| Library | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |