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.