DBG_C_SStep

Debug Command 9 - Single Step Command

Parameters

Pid= Process ID of debuggee
Tid= Thread ID of thread to single-step
Cmd= DBG_C_SStep

If Tid is zero, all threads will be marked to single-step at once, and the first thread to be scheduled to execute user-space code will single-step. No other threads will single-step.

Returns

Usually, the DBG_N_Exception notification is returned, but any notification may be returned. See DosDebug Notifications for more information.

Callgates that result in a privilege level transition to ring 0 will appear to single-step as a single instruction, with the single-step occurring just after the function completes. This hides ring 0 execution from debuggers.

Attempting to single-step any thread that is frozen results in an error.

Restrictions

The DBG_C_SStep command has two modes of operation, as follows:

If Tid is zero, the current thread is single-stepped while allowing all other threads to execute.
If Tid is nonzero, a specific thread is selected for single-stepping. Only that thread is executed, even if it is single-stepping a kernel function that can potentially cause a deadlock condition.

The single-step exception (XCPT_SINGLE_STEP) is not lost if the single-step operation causes a notification to be sent to DosDebug. In this case, the single-step exception is queued.

The single-step operation is not lost if other notifications were queued before the DBG_C_SStep command was issued. The Debug DBG_C_Continue command will clear the notifications one at a time until DosDebug has been completely notified. On the last DBG_C_Continue command, the single-step operation will take place as originally requested.

When a single-step operation is interrupted by an exception, the EIP (instruction pointer) should be moved to the next RING3 instruction. This may be in ring 3 system code. The single-step notification will be issued at this time.

The DBG_C_SStep command correctly single-steps most instructions. Single-stepping some REP instructions may not work correctly due to errors in the 80386 processor.