Runtime Debugger (Cordbg.exe)

Article
11/16/2012

The Runtime Debugger helps tools vendors and application developers find and fix bugs in programs that target the .NET Framework common language runtime. This tool uses the runtime Debug API to provide debugging services. The source code for Cordbg.exe is being shipped as a sample application. Developers can examine the code to learn how to use the debugging services. Currently, you can only use Cordbg.exe to debug managed code; there is no support for debugging unmanaged code.

Use the first line of syntax below to start a Cordbg.exe session. Use the second line at the (cordbg) prompt inside a Cordbg.exe session.

cordbg [ProgramName[Program arguments]][optional arguments ]
command [command arguments]

Parameters

Command	Description
ap[pdomainenum] [option]	Enumerates all application domains, assemblies, and modules in the current process. If you do not specify the option argument, the command lists all application domains, assemblies, and modules in the current process. After detaching or attaching, you must specify the go command to resume execution. The option argument can be one of the following: attach Lists the application domains in the process and prompts the user to select the domain to attach to. detach Lists the application domains in the process and prompts the user to select the domain to detach from. 0 Lists the application domains in the process. 1 Lists the application domains and assemblies in the process.
as[sociatesource] {s\|b breakpoint id} filename	Associates the given file name with the current stack frame pointer (option s) or the specified breakpoint (option b).
a[ttach] pid	Attaches the debugger to a running process. Cordbg.exe kills the program that it is currently debugging (if there is one), and attempts to attach to the process specified by the pid argument. The process identification number pid can be in decimal or hexadecimal format.
b[reak] [[file:] line number] \| [[ class::] function [:offset]]	Sets or displays breakpoints. If you do not specify any arguments, the tool displays a list of current breakpoints; otherwise, it sets a breakpoint at the specified location. You can set a breakpoint at a line number in the current source file, a line number in a fully qualified source file, or in a method qualified by a class and optional offset. Breakpoints persist across runs in a session. You can use the stop command the same way you use break. Cordbg.exe displays breakpoints as "unbound" if the specified breakpoint location cannot be bound to code. When a breakpoint is unbound, it means that the underlying code for the breakpoint location has not been loaded yet. This can happen for a number of valid reasons, such as a misspelled file or class name (they are case-sensitive). Also, breakpoints will be unbound if you set them before running an application. Breakpoints become bound when the real code is loaded. The debugger tries to automatically rebind every unbound breakpoint when it loads a module.
ca[tch] [event]	Displays a list of event types, or causes the specified event type to stop the debugger. If you do not specify an argument, the tool displays a list of event types, where event types that stop the debugger are marked "on," and event types that are ignored are marked "off." If you specify an argument, the debugger stops when events of the specified type occur. By default, the debugger only stops on unhandled exception events (that is, second chance exceptions). Event types that stop the debugger persist across runs in a session. To cause the debugger to ignore a particular type of event, use the ignore command. The event argument can be one of the following: e[ xceptions] [exception type] The tool adds the exception type to a list of first chance exceptions to catch. If you do not specify an exception type, the tool catches all first chance exceptions. The exception type is case sensitive, for example, System.ArgumentException. u[ nhandled] Unhandled exceptions c[ lass] Class load events m[ odule] Module load events t[ hread] Thread start events
cont [count]	Continues the program. If you do not specify an argument, the program continues once. If you do specify an argument, the program continues the specified number of times. This command is useful for continuing a program when a class load event, exception, or breakpoint stops the debugger. You can use the go command the same way you use cont.
del[ete] [breakpoint id, ...]	Deletes breakpoints. If you do not specify any arguments, the tool deletes all current breakpoints. If you specify one or more breakpoint id arguments, the tool deletes the specified breakpoints. You can obtain breakpoint identifiers by using the break or stop commands. You can use the remove command the same way you use delete.
de[tach]	Detaches the debugger from the current process. The process automatically continues and runs as if a debugger is not attached to it.
dis[assemble] [0xaddress][{+\|-} delta] [line count]	Displays native disassembled instructions for the current instruction pointer or address, if specified. The default number of instructions displayed is five. If you specify a line count argument, the tool displays the specified number of extra instructions before and after the current instruction pointer or address. The last line count used becomes the default for the current session. If you specify a delta, the number specified will be added to the current instruction pointer or specified address to begin disassembling.
d[own] [count]	Moves the stack frame pointer down the stack toward frames called by the current frame for inspection purposes. If you do not specify an argument, the stack frame pointer moves down one frame. If you specify an argument, the stack frame pointer moves down by the specified number of frames. If source level information is available, the tool displays the source line for the frame. This command is frequently used in conjunction with the up command.
du[mp] address [count]	Dumps a block of memory, with the output in hexadecimal or decimal format depending on the debugger's mode (see mode). The address argument is the address of the block of memory. The count argument is the number of bytes to dump.
ex[it]	Stops the current process and exits the debugger. You can use the quit command in the same way you use exit.
f[unceval] [class::] function [ arg0 arg1 ...argn]	Evaluates the specified function on the current thread. The tool stores the new object in the variable $result and can use it for subsequent evaluations. Valid arguments are limited to other variables, 4-byte integers, and the constants Null, True, and False. Note For a member function, the first argument should be an object of the class or derived class to which the member function belongs.
g[o] [count]	See cont.
h[elp] [command ...]	Displays descriptions for the specified commands. If you do not specify any arguments, Cordbg.exe displays a list of debugger commands. You can use the ? command the same way you use help.
ig[nore] [event]	Displays a list of event types or causes the specified event type to be ignored by the debugger. If you do not specify an event argument, the tool displays a list of event types, where event types that are ignored are marked "off" and event types that stop the debugger are marked "on." If you specify an argument, the tool ignores events of the specified type. To set an event type to stop the debugger, use the catch command. The event argument can be one of the following event types: e[ xceptions] [exception type] The tool adds the exception type to a list of first chance exceptions to ignore. If you do not specify an exception type, the tool ignores all first chance exceptions. The exception type is case sensitive, for example, System.ArgumentException. u[ nhandled] Unhandled exceptions c[ lass] Class load events m[ odule] Module load events t[ hread] Thread start events
i[n] [count]	See step.
k[ill]	Stops the current process. The debugger remains active to process further commands.
l[ist] option	Displays a list of loaded modules, classes, or global functions. The option argument can be one of the following: mod Lists the loaded modules in the process. cl Lists the loaded classes in the process. fu Lists global functions for each module in the process.
m[ode] [[mode name {0\|1} ]	Sets and displays debugger modes for various debugger features. To set a value, specify the mode name and a 1 for "on" or 0 for "off." If you do not specify an argument, the tool displays a list of current mode settings. The modes are persisted in the Windows registry between runs of Cordbg.exe. For more information, see the table of debugger mode arguments.
newo[bj] class	Creates a new object using the current thread. The tool stores the new object in the variable $result and can use it for subsequent evaluations.
newobjnc class	Creates a new object using the current thread without running a constructor on the object. The new object is initialized to zero. The tool stores the new object in the variable $result and can use it for subsequent evaluations.
news[tr] string	Creates a new string using the current thread. The tool stores the new object in the variable $result and can use it for subsequent evaluations.
n[ext] [count]	Steps the program to the next source line, stepping over function calls. If you do not specify an argument, the tool steps one source line. If you specify an argument, the tool steps the specified number of lines. You can use the so command the same way you use next.
ns[ingle] [count]	Steps the program one or more instructions, skipping over function calls. If you do not specify an argument, the tool steps one instruction. If you specify a count argument, the tool steps the specified number of instructions.
o[ut] [count]	Steps the program out of the current function. If you do not specify an argument, the tool performs a step out once for the current function. If you specify an argument, the tool performs a step out the specified number of times.
pa[th] [new path]	Displays or sets the path used to search for source files and debugging symbols. If you do not specify an argument, the tool displays the current path. If you specify a new path argument, it becomes the new path used to search for source files and debugging symbols. This path persists between sessions in the Windows registry.
p[rint] [variable name]	Displays one or more local variables along with their values. If you do not specify an argument, the tool displays all local variables and their values. If you specify an argument, the tool displays the value of only the specified local variable. For details, see Using the print command in the Examples section.
pro[cessenum]	Enumerates all managed processes and the application domains in each process.
q[uit]	See exit.
ref[reshsource] [source file]	Reloads the source code for a given source file. The source file to be reloaded must be part of the currently executing program. After setting a source file path with the path command, you can use the refreshsource command to bring in missing source code.
regd[efault] [force]	Sets the default just-in-time (JIT) debugger to Cordbg.exe. The command does nothing if another debugger is already registered. Use the force argument to overwrite the registered JIT debugger.
reg[isters]	Displays the contents of the registers for the current thread.
rem[ove] [breakpoint id, ...]	See delete.
re[sume] [~] [tid]	Resumes the thread specified by the tid argument when the debugger continues. If you use the ~ syntax, the tool resumes all threads except the specified thread. If you do not specify an argument, the command has no effect.
r[un] [executable [args]]	Kills the current process (if there is one) and starts a new one. If you do not specify an executable argument, this command runs the program that was previously executed with the run command. If you specify an executable argument, the tool runs the specified program using the optionally supplied args. If Cordbg.exe is ignoring class load, module load, and thread start events (as it is by default), the program stops on the first executable instruction of the main thread.
set variable value	Sets the value of the specified variable to the specified value. The value can be a literal or another variable. For details, see Using the set command. in the Examples section.
setip line number	Sets the next statement to execute to the specified line number.
sh[ow] [count]	Displays source code lines. If you do not specify an argument, the tool displays the five source code lines before and after the current source code line. If you specify an argument, the tool displays the specified number of lines before and after the current line. The last count specified becomes the default for the current session.
si [<count>]	See step.
so [<count>]	See next.
ss[ingle] [count]	Steps the program one or more instructions, stepping into function calls. If you do not specify an argument, the tool steps into only one instruction. If you specify an argument, the tool performs the specified number of steps.
s[tep] [count]	Steps the program to the next source line, stepping into function calls. If you do not specify an argument, the program steps to the next line. If you specify an argument, the program steps the specified number of lines. You can use the si command or the in command the same way you use step.
stop [[file:] line number] \| [[class::] function[:offset]] \| [=0xaddress]	See break.
su[spend] [~] [tid]	Suspends the thread specified by the tid argument when the debugger continues. If you use the ~ syntax, the tool suspends all threads except the specified thread. If you do not specify an argument, the command has no effect.
t[hreads] [tid]	Displays a list of threads, or sets the current thread. If you do not specify an argument, the tool displays the list of all threads that are still alive and that have run managed code. If you specify an argument, the tool sets the current thread to the specified thread.
up [count]	Moves the stack frame pointer up the stack toward frames that called the current frame for inspection purposes. If you do not specify an argument, the stack frame pointer moves up one frame. If you specify an argument, the stack frame pointer moves up by the specified number of stack frames. If source level information is available, the tool displays the source line for the frame.
w[here] [count]	Displays a stack trace for the current thread. If you do not specify an argument, the tool displays a complete stack trace. If you specify an argument, the tool displays the specified number of stack frames.
wr[itememory] address count byte, ...	Writes the specified bytes to the target process. The address argument specifies the location in which to write the bytes. The count argument specifies the number of bytes to write. The byte arguments specify what to write to the process. If the number of bytes in the list is less than the count argument, the tool wraps the byte list and copies it again. If the number of bytes in the list is more than the count argument, the tool ignores the extra bytes.
wt	Steps the application by native instructions, starting from the current instruction and printing the call tree as it goes. The tool prints the number of native instructions executed in each function with the call trace. Tracing stops when the tool reaches the return instruction for the function in which the command was originally executed. At the end of the trace, the tool prints the total number of instructions executed. This command mimics the NT Symbolic Debugger wt command, and you can use it for basic performance analysis. Currently, the tool only counts managed code.
x modulename ! string_to_look_for	Displays symbols in the specified module that match the pattern specified by the string_to_look_for argument. You can use the asterisk () character in the string_to_look_for* argument to indicate to the tool to match anything. The tool ignores any characters after the * character.
? [command ...]	See help.
>filename	Writes all executed commands to the specified filename. If you do not specify filename, the command stops writing commands to the file.
<filename	Reads and executes commands from the specified filename.

Note

Cordbg.exe commands are case-sensitive. In addition, several commands have synonyms, meaning that you can use any one of several commands to produce the same result. For example, you can use either the break or the stop command to set breakpoints.

Mode Arguments

You can specify mode arguments using the fewest number of characters necessary to make the mode unique. For example, "mode m 1" is equivalent to "mode moduleloads 1".

Argument	Description
AppDomainLoads	Displays application domain and assembly load events.
ClassLoads	Displays class load events.
DumpMemoryInBytes	Displays memory contents as bytes or DWORDS.
EmbededCLR	Sets the debugger to target .NET Compact Framework applications running on smart devices. To control this setting, specify 1 for on or 0 for off.
EnhanceDiag	Displays enhanced diagnostic information.
HexDisplay	Displays numbers in hexadecimal or decimal format.
ILNatPrint	Displays offsets in Microsoft intermediate language (MSIL) or native-relative language, or both.
ISAll	Steps through all interceptors.
ISClinit	Steps through class initializers.
ISExceptF	Steps through exception filters.
ISInt	Steps through user interceptors.
ISPolicy	Steps through context policies.
ISSec	Steps through security interceptors.
JitOptimizations	Specifies whether JIT compilation generates code that is easier to debug.
LoggingMessages	Displays managed code log messages.
ModuleLoads	Displays module load events.
SeparateConsole	Specifies whether the process being debugged gets its own console.
ShowArgs	Displays method arguments in the stack trace.
ShowModules	Displays module names in the stack trace.
ShowStaticsOnPrint	Displays static fields for objects.
ShowSuperClassOnPrint	Displays contents of base class for objects.
USAll	Steps through all unmapped stop locations.
USEpi	Steps through method epilogs.
USPro	Steps through method prologs.
USUnmanaged	Steps through unmanaged code.

Remarks

You should compile the application to debug using compiler-specific flags, which cause your compiler to generate debugging symbols. Refer to your compiler's documentation for more information about these flags. You can still debug optimized applications, but some debugging information will be missing. For example, many local variables will not be visible, and source lines will be inaccurate.

After you compile the application, type cordbg at the command prompt to start a debugging session, as shown in the following example.

D:\Program Files\FrameworkSDK\Bin>cordbg
Microsoft (R) Common Language Runtime Test Debugger Shell. Version 2000.14.2100.0, Copyright (c) Microsoft Corp. 1998-2000
(cordbg)

The (cordbg) prompt indicates that you are in the debugger.

Once you are in the debugger, use the commands and appropriate arguments to invoke the required functionality.

When you start a debugging session from the command line, you can also provide the name of the application you want to debug, program arguments, and optional arguments. The Cordbg.exe optional arguments are the same commands that you would use while in Cordbg.exe but you must prefix them with the exclamation point (!) character. You can use the ! character as a literal in a string by prefixing it with the backslash (\) character. This is necessary when using the x command.

If a numeric argument to a command begins with the prefix 0x, Cordbg.exe assumes the argument is in hexadecimal format. Otherwise, it assumes the argument is in decimal format.

Most commands in Cordbg.exe can be prefixed with an asterisk (*), which causes the command to execute once for each managed thread in the process. The command is executed in the context of each thread. The most useful command to prefix with an asterisk is the w[here] command. For example, *w will cause the stack trace of every managed thread to be printed.

For more information about the runtime's debugging services, see the Enabling Profiling and Debugging specification. In addition, tools developers should see the Debug Overview and Debug Reference specifications located in the Tools Developers Guide folder that ships with the Windows Software Development Kit (SDK).

Examples

Starting a Cordbg.exe session

The following command starts a Cordbg.exe session for the application MyApplication.exe with the program arguments a and 2 and the following optional commands: set a breakpoint in MyApplication.cs at line 42; continue the application; display symbols in MyApplication.exe matching the string 'SomeString'.

cordbg MyApplication.exe a 2 !b MyApplication.cs:42 !g !x MyApplication.exe\!SomeString

Running an executable inside a Cordbg.exe session

The following command entered from within a Cordbg.exe session (at the (cordbg) prompt) runs the executable MyApplication.exe with the program arguments a and 2.

run MyApplication.exe a 2

Using the print command

The following commands demonstrate that you can use dot notation with the print command to specify variables within objects.

print obj.var1
print obj1.obj2.var1

If a class extends another class, the print command shows both the specified class's fields and the base class's fields. For example, if class m1 has fields a, b, and c and class m2 extends m1 and has fields d, e, and f, then an instance myInstance of m2 prints as follows.

myInstance = <addr> <m2>
      a = 1
      b = 2
      c = 3
      m2::d = 4
      m2::e = 5
      m2::f = 6

You can specify class static variables by prefixing the variable name with the class name, as follows.

print MyClass::StaticVar1
print System::Boolean::True

Array indexes must be simple expressions. The following array indexes are valid for use with the print command.

print arr[1]
print arr[i]
print arr1[arr2[1]]
print md[1][5][myObject.a]

The following array indexes are not valid for use with the print command, because the array index is not a simple expression.

print arr[i + 1]
print arr[i + 2]

Using the set command

When using the set command, the value being assigned to the specified variable can be a literal or another variable. The following are valid uses of the set command.

set int1 0x2a
set float1 3.1415
set char1 'a'
set bool1 true
set obj1 0x12345678
set obj1 obj2
set obj1.m_length[obj1.m_height] obj3.m_length[2]

Share via