.step_filter (Set Step Filter)

The .step_filter command creates a list of functions that are skipped (stepped over) when tracing. This allows you to trace through code and skip only certain functions. It can also be used in source mode to control stepping when there are multiple function calls on one line.

.step_filter "FilterList" 
.step_filter /c 
.step_filter 

Parameters

"FilterList"
Specifies the symbols associated with functions to be stepped over. FilterList can contain any number of text patterns separated by semicolons. Each of these patterns may contain a variety of wildcards and specifiers; see String Wildcard Syntax for details. A function whose symbol matches at least one of these patterns will be stepped over during tracing. Each time "FilterList" is used, any previous filter list is discarded and completely replaced with the new list.

/c
Clears the filter list.

Environment

Item	Description
Modes	User mode, kernel mode
Targets	Live, crash dump
Platforms	All

Remarks

Without any parameters, .step_filter displays the current filter list.

Typically, a trace command (for example, t or the windbg debug | step into] traces into a function call. However, if the symbol associated with the function being called matches a pattern specified by FilterList, the function will be stepped over -- as if a step command (for example, p) had been used.

If the instruction pointer is located within code that is listed in the filter list, any trace or step commands will step out of this function, like the gu command or the WinDbg Step Out button. Of course, this filter would prevent such code from having been traced into in the first place, so this will only happen if you have changed the filter or hit a breakpoint.

For example, the following command will cause trace commands to skip over all CRT calls:

.step_filter "msvcrt!*" 

The .step_filter command is most useful when you are debugging in source mode, because there can be multiple function calls on a single source line. The p and t commands cannot be used to separate these function calls.

For example, in the following line, the t command will step into both GetTickCount and printf, while the p command will step over both function calls:

printf( "%x\n", GetTickCount() );

The .step_filter command allows you to filter out one of these calls while still tracing into the other.

Because the functions are identified by symbol, a single filter can include an entire module. This lets you filter out framework functions -- for example, Microsoft Foundation Classes (MFC) or Active Template Library (ATL) calls.

When debugging in assembly mode, each call is on a different line, so you can choose whether to step or trace line-by-line. So .step_filter is not very useful in assembly mode.