PsCreateSystemThread

PsCreateSystemThread creates a system thread that executes in kernel mode and returns a handle for the thread.

NTSTATUS 
  PsCreateSystemThread(
    OUT PHANDLE  ThreadHandle,
    IN ULONG  DesiredAccess,
    IN POBJECT_ATTRIBUTES  ObjectAttributes  OPTIONAL,
    IN HANDLE  ProcessHandle  OPTIONAL,
    OUT PCLIENT_ID  ClientId  OPTIONAL,
    IN PKSTART_ROUTINE  StartRoutine,
    IN PVOID  StartContext
    );

Parameters

ThreadHandle

Points to a variable that will receive the handle. The driver must close the handle with ZwClose once the handle is no longer in use.

DesiredAccess

Specifies the ACCESS_MASK value that represents the requested types of access to the created thread. This value can be THREAD_ALL_ACCESS or (ACCESS_MASK) 0L for a driver-created thread.

ObjectAttributes

Points to a structure that specifies the object’s attributes. OBJ_PERMANENT, OBJ_EXCLUSIVE, and OBJ_OPENIF are not valid attributes for a thread object. On Windows XP and later operating systems, if the caller is not running in the system process context, it must set the OBJ_KERNEL_HANDLE attribute for ObjectAttributes. Drivers for Windows 2000 and Windows 98/Me must only call PsCreateSystemThread from the system process context.

ProcessHandle

Specifies an open handle for the process in whose address space the thread is to be run. The caller’s thread must have PROCESS_CREATE_THREAD access to this process. If this parameter is not supplied, the thread will be created in the initial system process. This value should be NULL for a driver-created thread. Use the NtCurrentProcess macro to specify the current process.

ClientId

Points to a structure that receives the client identifier of the new thread. This value should be NULL for a driver-created thread.

StartRoutine

Is the entry point for a driver thread.

StartContext

Supplies a single argument passed to the thread when it begins execution.

Return Value

PsCreateSystemThread returns STATUS_SUCCESS if the thread was created.

Headers

Declared in wdm.h and ntddk.h. Include wdm.h or ntddk.h.

Comments

Drivers that create device-dedicated threads call this routine, either when they initialize or when I/O requests begin to come in to such a driver’s Dispatch routines. For example, a driver might create such a thread when it receives an asynchronous device control request.

PsCreateSystemThread creates a kernel-mode thread that begins a separate thread of execution within the system. Such a system thread has no TEB or user-mode context and runs only in kernel mode.

If the input ProcessHandle 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 terminates itself by calling PsTerminateSystemThread.

On Windows XP and later operating systems, 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 PsCreateSystemThread. This restricts the use of the handle returned by PsCreateSystemThread to processes running in kernel mode. Otherwise, the thread handle can be accessed by the process in whose context the driver is running. Drivers can set the OBJ_KERNEL_HANDLE attribute as follows.

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

Drivers for Windows 2000 and Windows 98/Me must only call PsCreateSystemThread from the system process context.

Callers of this routine must be running at IRQL PASSIVE_LEVEL.

See Also

InitializeObjectAttributes, KeSetBasePriorityThread, KeSetPriorityThread, PsTerminateSystemThread, ZwSetInformationThread