- wt (Trace and Watch Data)
- Parameters
- Environment
- Additional Information
- Remarks
- OpenTraceA function (evntrace.h)
- Syntax
- Parameters
- Return value
- Remarks
- Examples
- ProcessTrace function (evntrace.h)
- Syntax
- Parameters
- Return value
- Remarks
- Viewing the Call Stack in WinDbg
- Debugger Command Window
- Calls Window
- Additional Information
wt (Trace and Watch Data)
The wt command runs through the whole function and then displays statistics, when you execute this command at the beginning of a function call.
Parameters
WatchOptions
Specifies how to modify the display. You can use any of the following options.
| Option | Effect |
|---|---|
Additional Information
For more information about issuing the wt command and an overview of related commands, see Controlling the Target.
Remarks
The wt command is useful if you want information about the behavior of a specific function, but you do not want to step through the function. Instead, go to the beginning of that function and then issue the wt command.
If the program counter is at a point that corresponds to a symbol (such as the beginning of a function or entry point into a module), the wt command traces until it reaches the current return address. If the program counter is on a call instruction, the wt command traces until it returns to the current location. This tracing is profiled in the Debugger Command window together with output that describes the various calls that the command encounters.
If the wt command is issued somewhere other than the beginning of a function, the command behaves like the p (Step) command. However, if you specify EndAddress, execution continues until that address is reached, even if this execution involves many program steps and function calls.
When you are debugging in source mode, you should trace into the function only to the point where you see the opening bracket of the function body. Then, you can use the wt command. (It is typically easier to insert a breakpoint at the first line of the function, or use Debug | Run to Cursor, and then use the wt command.)
Because the output from wt can be long, you might want to use a log file to record your output.
The following example shows a typical log file.
In the listing of the trace, the first number specifies the number of instructions that were executed, the second number specifies the number of instructions executed by child processes of the function, and the third number (in brackets) specifies the depth of the function in the stack (taking the initial function as zero). The indentation of the function name shows the call depth.
In the preceding example, MyModule!myFunction executes 105 instructions before it calls several subroutines, including printf and fgets, and then executes 54545 additional instructions after calling those functions, but before issuing a few more calls. However, in the final count, the display shows that myFunction executes 112,379 instructions, because this count includes all of the instructions that myFunction and its children execute. (The children of myFunction are functions that are called from myFunction, either directly or indirectly.)
In the preceding example, note also that ILT+1440 (__isatty) is called 21 times. In the final count, the summary of this function’s behavior shows the number of times that it was called, the smallest number of instructions in any single execution, the largest number of instructions in any single execution, and the average number of instructions per execution.
If any system calls are made, they appear in the counter and are listed again at the end of the command output.
OpenTraceA function (evntrace.h)
The OpenTrace function opens a real-time trace session or log file for consuming.
Syntax
Parameters
Pointer to an EVENT_TRACE_LOGFILE structure. The structure specifies the source from which to consume events (from a log file or the session in real time) and specifies the callbacks the consumer wants to use to receive the events.
Return value
If the function succeeds, it returns a handle to the trace.
If the function fails, it returns INVALID_PROCESSTRACE_HANDLE.
If your code base supports WindowsВ 7 and WindowsВ Vista, and also supports earlier operating systems such as WindowsВ XP and Windows ServerВ 2003, do not use the constants described above. Instead, determine the operating system on which you are running and compare the return value to the following values.
| Operating system | Application | Return value to compare |
|---|---|---|
| WindowsВ 7 and WindowsВ Vista | 32-bit | 0x00000000FFFFFFFF |
| WindowsВ 7 and WindowsВ Vista | 64-bit | 0XFFFFFFFFFFFFFFFF |
| WindowsВ XP and Windows ServerВ 2003 | 32- or 64-bit | 0XFFFFFFFFFFFFFFFF |
В
If the function returns INVALID_PROCESSTRACE_HANDLE, you can use the GetLastError function to obtain extended error information. The following table lists some common errors and their causes.
| Return code | Description | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ERROR_INVALID_PARAMETER | The Logfile parameter is NULL. | ||||||||||||||||||
| ERROR_BAD_PATHNAME | If you did not specify the LoggerName member of EVENT_TRACE_LOGFILE, you must specify a valid log file name. | ||||||||||||||||||
| ERROR_ACCESS_DENIED | Only users with administrative privileges, users in the Performance Log Users group, and services running as LocalSystem, LocalService, NetworkService can consume events in real time. To grant a restricted user the ability to consume events in real time, add them to the Performance Log Users group. WindowsВ XP and WindowsВ 2000:В В Anyone can consume real time events. RemarksConsumers call this function. After calling OpenTrace, call the ProcessTrace function to process the events. When you have finished processing events, call the CloseTrace function. Note that you can process events from only one real-time session. WindowsВ Vista and earlier: If the function fails it will returns INVALID_HANDLE_VALUE. To avoid compile-time errors, cast INVALID_HANDLE_VALUE to TRACEHANDLE as follows: (TRACEHANDLE)INVALID_HANDLE_VALUE . ExamplesThe evntrace.h header defines OpenTrace as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes. ProcessTrace function (evntrace.h)The ProcessTrace function delivers events from one or more event tracing sessions to the consumer. SyntaxParametersPointer to an array of trace handles obtained from earlier calls to the OpenTrace function. The number of handles that you can specify is limited to 64. The array can contain the handles to multiple log files, but only one real-time trace session. Number of elements in HandleArray. Pointer to an optional FILETIME structure that specifies the beginning time period for which you want to receive events. The function does not deliver events recorded prior to StartTime. Pointer to an optional FILETIME structure that specifies the ending time period for which you want to receive events. The function does not deliver events recorded after EndTime. Windows ServerВ 2003:В В This value is ignored for real-time event delivery. Return valueIf the function succeeds, the return value is ERROR_SUCCESS. If the function fails, the return value is one of the system error codes. The following table includes some common errors and their causes.
RemarksConsumers call this function. You must call the OpenTrace function prior to calling ProcessTrace. The ProcessTrace function delivers the events to the consumer’s BufferCallback, EventCallback, and EventClassCallback callback functions. The ProcessTrace function sorts the events chronologically and delivers all events generated between StartTime and EndTime. Note that events can appear out of order if the session specifies system time as the clock (low resolution) and the volume of events is high. In this case, it is possible for multiple events to contain the same time stamp. If multiple events contain the same time stamp, ETW cannot guarantee the order of those events. The ProcessTrace function blocks the thread until it delivers all events, the BufferCallback function returns FALSE, or you call CloseTrace. If the consumer is consuming events in real time, the ProcessTrace function returns after the controller stops the trace session. (Note that there may be a several-second delay before the function returns.) Windows ServerВ 2003:В В You can call CloseTrace only after ProcessTrace returns. Viewing the Call Stack in WinDbgThe call stack is the chain of function calls that have led to the current location of the program counter. The top function on the call stack is the current function, the next function is the function that called the current function, and so on. The call stack that is displayed is based on the current program counter, unless you change the register context. For more information about how to change the register context, see Changing Contexts. In WinDbg, you can view the call stack by entering commands or by using the Calls window. Debugger Command WindowYou can view the call stack by entering one of the k (Display Stack Backtrace) commands in the Debugger Command window. Calls WindowAs an alternative to the k command, you can view the call stack in the Calls window. To open the Calls window, choose Call Stack from the View menu. The following screen shot shows an example of a Calls window.
Buttons in the Calls window enable you to customize the view of the call stack. To move to the corresponding call location in the Source window or Disassembly window, double-click a line of the call stack, or select a line and press ENTER. This action also changes the local context to the selected stack frame. For more information about running to or from this point, see Controlling the Target. In user mode, the stack trace is based on the stack of the current thread. For more information about the stack of the current thread, see Controlling Processes and Threads. In kernel mode, the stack trace is based on the current register context. You can set the register context to match a specific thread, context record, or trap frame. For more information about setting the register context, see Register Context. The Calls window has a toolbar that contains several buttons and has a shortcut menu with additional commands. To access this menu, select and hold (or right-click) the title bar or select the icon near the upper-right corner of the window ( Raw args displays the first three parameters that are passed to the function. On an x86-based processor, this display includes the first three parameters that are passed to the function («Args to Child»). Func info displays Frame Pointer Omission (FPO) data and other internal information about the function. This command is available only on an x86-based processor. Source displays source module names and line numbers after the function names (if the debugger has this information). Addrs displays various frame-related addresses. On an x86-based processor, this display includes the base pointer for the stack frame («ChildEBP») and the return address («RetAddr»). Frame nums displays frame numbers. Frames are always numbered consecutively, beginning with zero. Arg types displays detailed information about the arguments that are expected and received by the functions in the stack. Always floating causes the window to remain undocked even if it is dragged to a docking location. Move with frame causes the window to move when the WinDbg frame is moved, even if the window is undocked. For more information about docked, tabbed, and floating windows, see Positioning the Windows. Additional InformationFor more information about the register context and the local context, see Changing Contexts. |
). The toolbar and menu contain the following buttons and commands:
