NtStopProfile

This function stops the profiling that has been configured for a given profile object.

Declaration

NTSTATUS NtStopProfile (HANDLE ProfileHandle);

Parameters

The ProfileHandle argument is a handle to an executive profile object, such as created by NtCreateProfile or NtCreateProfileEx.

Return Value

The function returns STATUS_SUCCESS if successful, else a negative error code.

Availability

The NtStopProfile function and its alias ZwStopProfile are exported by name from NTDLL in version 3.10 and higher. In kernel mode, where ZwStopProfile is a stub and NtStopProfile is the implementation, neither is exported.

Documentation Status

Neither NtStopProfile nor its alias is documented. As ZwStopProfile, it is declared in the ZWAPI.H file in the Windows Driver Kit (WDK) for Windows 10.

Unusually for native API functions, no repackaging of NtStopProfile, documented or not, is known in any higher-level user-mode module that is distributed as standard with Windows.

Behaviour

The following implementation notes are from inspection of the kernel from the original release of Windows 10 only. They may some day get revised to account for earlier versions. Meanwhile, where anything is added about earlier versions, take it not as an attempt at comprehensiveness but as a bonus from my being unable to resist a trip down memory lane or at least a quick look into the history.

Parameter Validation

The function fails unless the given handle references an executive profile object (rather than any other type of object) and has whatever permission is represented by the access mask 0x00000001. Microsoft’s name for this one permission that is defined for profile objects is not known.

The profile object retains parameters that were supplied on some earlier call to NtCreateProfile or NtCreateProfileEx. Among these is the address of a buffer that is to receive the ULONG counters of times that execution is discovered in successive buckets that span a profiled region of address space. Because the counters will be incremented while handling a hardware interrupt this buffer—well, that part of it that will be needed for the counters—must be locked into physical memory and mapped into system address space at all times that profiling is started but not yet stopped. This mapped address for the buffer is also kept with the profile object. If it’s not present, then there is no profiling to stop, and the function returns STATUS_PROFILING_NOT_STARTED.

WORK IN PROGRESS