PsLookupThreadByThreadId function (ntifs.h)

Article
10/21/2021

The PsLookupThreadByThreadId routine accepts the thread ID of a thread and returns a referenced pointer to the ETHREAD structure of the thread.

Syntax

NTSTATUS PsLookupThreadByThreadId(
  [in]  HANDLE   ThreadId,
  [out] PETHREAD *Thread
);

Parameters

[in] ThreadId

Specifies the thread ID of the thread.

[out] Thread

Returns a referenced pointer to the ETHREAD structure of thread specified by the ThreadId.

Return value

PsLookupThreadByThreadId returns STATUS_SUCCESS on success or an appropriate NTSTATUS value, such as:

Return code	Description
STATUS_INVALID_PARAMETER	The thread ID was not found.

Remarks

This routine is available on Windows 2000 and later versions.

If the call to PsLookupThreadByThreadId is successful, PsLookupThreadByThreadId increases the reference count on the object returned in the Thread parameter. Consequently, when a driver has completed using the Thread parameter, the driver must call ObDereferenceObject to dereference the Thread parameter received from the PsLookupThreadByThreadId routine.

The ETHREAD structure is an opaque data structure used internally by the operating system. This structure can be passed to other routines to access specific information in this structure.

A file system filter driver can enumerate active threads by calling PsLookupThreadByThreadId to convert a thread ID to an ETHREAD structure. The thread ID is available in the thread create routine. A file system filter driver can set a thread notification callback routine using PsSetCreateThreadNotifyRoutine. In the notification callback routine, the file system filter driver can use the passed in ThreadId parameter and call PsLookupThreadByThreadId to locate the ETHREAD structure.

The PsLookupThreadByThreadId routine contains pageable code.

Requirements

Requirement	Value
Target Platform	Universal
Header	ntifs.h (include Ntifs.h)
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL