Synopsis

cordbg [program [program-arguments]] [!command ...]

Description

This is a general source-level, command-line debug utility for MSIL programs. It's a very useful tool for C# source debugging (make sure you compiled your program with /debug). Source for cordbg is available in the \Tool Developers Guide directory. You can start cordbg with the name of a program and the arguments to pass to that program. You can also supply one or more commands (prefixed with !) on the command line.

After you launch cordbg, you are greeted by the (cordbg) prompt, where you can type commands until you exit cordbg with the quit command.

Sample Sessions

Set a breakpoint, start the program, and step through a few lines of code:

c:\home>cordbg Tester.exe
Microsoft (R) Common Language Runtime Test Debugger Shell 
Version 1.1.4322.573
Copyright (C) Microsoft Corporation 1998-2002. All rights reserved.
  
(cordbg) run Tester.exe
Process 2024/0x7e8 created.
Warning: couldn't load symbols for 
c:\windows\microsoft.net\framework\v1.0.3617\mscorlib.dll
[thread 0xee8] Thread created.
  
004:     for (int i = 0; i < 3; i++) {
(cordbg) show
001: using System;
002: class Tester {
003:   public static void Main( ) {
004:*    for (int i = 0; i < 3; i++) {
005:       object o = i;
006:       Console.Write(i + " ");
007:     }
008:     Console.Write("\n");
009:   }
(cordbg) b 6
Breakpoint #1 has bound to c:\home\Tester.exe.
#1      c:\home\Tester.cs:6  Main+0xb(il) [active]
(cordbg) go
break at #1     c:\home\Tester.cs:6  Main+0xb(il) [active]
  
006:       Console.Write(i + " ");
(cordbg) next
0
004:     for (int i = 0; i < 3; i++) {
(cordbg) step
  
005:       object o = i;
(cordbg) step
break at #1     c:\home\Tester.cs:6  Main+0xb(il) [active]

Swap two string variables by changing the addresses they refer to:

017:     string a = "A";
(cordbg) step
  
018:     string b = "B";
(cordbg) step
  
019:     Console.WriteLine(a + ", " + b);
(cordbg) print a
a=(0x00c51abc) "A"
(cordbg) print b
b=(0x00c51ad0) "B"
(cordbg) set a 0x00c51ad0
a=(0x00c51ad0) "B"
(cordbg) set b 0x00c51abc
b=(0x00c51abc) "A"
(cordbg) next
B, A

Invoke a static and instance method using funceval:

014:     TestClass my_instance = new TestClass( );
(cordbg) next
  
015:     return;
(cordbg) funceval TestClass::MyStaticMethod
In MyStaticMethod( )
Function evaluation complete.
$result=0x0000002a
015:     return;
(cordbg) funceval TestClass::MyInstanceMethod my_instance
In MyInstanceMethod( )
Function evaluation complete.
$result=0x00000017
015:     return;
(cordbg) print $result
$result=0x00000017

Commands

? [ command] , h[elp] [ command]

Displays general help. If command is specified, displays help for that command.

> [ file]

Writes all subsequent commands to a file. If file is not specified, this command stops writing commands to that file.

< file

Read and execute commands from a file.

ap[pdomainenum] [ option]

Lists all the AppDomains inside the current process. Valid choices for option are attach (list all AppDomains and prompt for which appdomain to attach to), detach (list all AppDomains and prompt for which AppDomain to detach from), 0 (list the AppDomains), or 1 (AppDomains and assemblies; the default list).

as[sociatesource] (s | b breakpoint) filename

Associate the specified source file with the current stackframe (s) or an existing breakpoint (b breakpoint).

a[ttach] pid

Attach to a managed process (use pro[cessenum] to get a list of pids).

b[reak] ([ file:] line | [ class::] function[ :offset])

Set a breakpoint at a given line number or function. With no arguments, lists all breakpoints.

ca[tch] [ event]

Specify an event type to suspend execution when that event occurs. Valid types are e[xceptions] [exception-type] (an exception is thrown), u[nhandled] (an exception is thrown that is not handled by the program), c[lass] (a class is loaded), m[odule] (a module is loaded), or t[hread] (a thread is started). With no arguments, catch displays a list of event types with the current catch/ignore settings.

cont [ count] , g[o]

Continues until the next breakpoint or until the program terminates, whichever comes first. Use count to continue over breakpoints multiple times.

del[ete] [ breakpoint ...] , rem[ove] [ breakpoint ...]

Delete the specified breakpoint(s). Use the breakpoint IDs as listed by the break command. If you don't specify a breakpoint, all breakpoints are deleted.

de[tach]

Detach from the current process and let it run to completion.

dis[assemble] [0x address] [{+|-} delta] [ lines]

Displays native code disassembly for the current instruction pointer (IP) or address. By default, five lines of surrounding context before and after the IP are shown (use the lines argument to change this).

d[own] [ count]

Move the stack pointer down one stack frame or the specified number of stack frames. This does not affect the instruction pointer, but it does affect the output of subsequent show commands.

du[mp] address [ count]

Dump memory at the specified address. The optional count argument specifies how many bytes to dump.

f[unceval] [ class::] function [ args]

Execute a function. For instance, with methods, you must supply an instance of the class as the first argument (see Sample Sessions for an example). The return value is stored in the variable $result, which you can inspect with the p[rint] command.

ig[nore]

Specify an event type to ignore when that event occurs (use catch to suspend execution whenever that event occurs). See catch for a list and description of valid events. With no arguments, ignore displays a list of event types with the current catch/ignore settings.

k[ill]

Stops the current process, but does not exit the debugger.

l[ist] option

Lists the loaded modules (option=mod), classes (option=cl), or global functions (option=fu).

m[ode] option (0 | 1)

Sets debugger modes. Type help mode for a list of valid modes and their descriptions. With no arguments, mode displays current mode settings.

newo[bj] type

Creates a new object, stored in the variable $result.

newobjnc type

Creates a new object without calling the constructor. The new object is stored in the variable $result.

news[tr] "string"

Creates a new string, stored in the variable $result.

ns[ingle] [ count]

Step to the next native instruction, stepping over function calls. If count is specified, steps the next count instructions.

o[ut] [ count]

Steps out of the current function. If count is specified, steps out of count functions.

pa[th] [ path]

Sets or (with no argument) displays the path used to search for source code files.

p[rint] [ variable]

Prints a list of all local variables and their values, or if variable is specified, prints the value of that variable.

pro[cessenum]

Displays a list of each managed process along with its process id (pid).

q[uit], ex[it]

Terminates the current process and exits the debugger.

ref[reshsource] file

Reloads the source code for the specified file.

reg[isters]

Displays the CPU registers and their contents for the current thread.

re[sume] [~] tid

With tid, resumes the specified thread ID. With ~, resumes all threads except the specified thread ID. See the t[hreads] command.

r[un] [ program [ program-arguments]]

With no arguments, kills and restarts the current process. With arguments, starts a new program with the specified program arguments.

set variable value

Set a variable to a given value. You can set the address of a reference type to a valid address for that type (see Sample Sessions). The C# or JIT compiler may perform optimizations that make certain variables unavailable, in which case you see the message "Variable variable is in scope but unavailable."

setip line

Set the instruction pointer to the specified line number.

sh[ow] [ number-of-lines]

Displays source code. The current line is shown with an asterisk (*).

si [ count] , s[tep] [ count] , i[n] [ count]

Steps to the next line of code, stepping into functions. If count is specified, steps the next count lines of code.

so [ count] , n[ext]

Steps to the next line of source code, stepping over functions. If count is specified, steps the next count lines of code.

ss[ingle] [ count]

Step to the next native instruction, stepping into function calls. If count is specified, steps the next count instructions.

stop

See break.

su[spend] [~] tid

With tid, suspends the specified thread ID. With ~, suspends all threads except the specified thread ID. See the t[hreads] command.

t[hreads] [ tid]

With no arguments, lists all threads and their IDs. With the tid argument, sets the current thread.

uc[lear] tid

Clears the current unmanaged exception for the thread ID specified by tid.

u[p] [ count]

Move the stack pointer up one stack frame or the specified number of stack frames. This does not affect the instruction pointer, but it does affect the output of subsequent show commands.

ut[hreads] [ tid]

With no arguments, lists all unmanaged threads and their IDs. With the tid argument, sets the current unmanaged thread.

uw[here]

Displays an unmanaged stack trace.

w[here] [ count]

Displays a stack trace for the currently executing thread. This displays up to 10 (or count) stack frames.

wr[itememory] addresscountbyte1 [ byte2 ...]

Writes count bytes to the specified memory address.

wt

Steps through the program, one native instruction at a time, and prints a call tree containing a count of instructions in each function.

x pattern

Displays symbols matching pattern. Use * as a wild card character (trailing characters are ignored). The symbol format is module!symbol.

IL Debugging

If you'd like to step through the MSIL instead of the C# source code, you can use ILDasm to disassemble your program and then use ILasm to assemble it into an executable (don't forget the /debug switch). Then, run that executable under cordbg:

C:\home>csc Tester.cs
Microsoft (R) Visual C# .NET Compiler version 7.10.3052.4
for Microsoft (R) .NET Framework version 1.1.4322
Copyright (C) Microsoft Corporation 2001-2002. All rights reserved.
  
C:\home>ILDasm /text Tester.exe > TesterIL.il
  
C:\home>ILasm /debug TesterIL.il
  
Microsoft (R) .NET Framework IL Assembler.  Version 1.1.4322.573
Copyright (C) Microsoft Corporation 1998-2002. All rights reserved.
Assembling 'TesterIL.il' , no listing file, to EXE --> 'TesterIL.EXE'
Source file is ANSI
  
Assembled method Tester::Main
Assembled method Tester::.ctor
Creating PE file
  
Emitting members:
Global
Class 1 Methods: 2;
Writing PE file
Operation completed successfully
  
C:\home>cordbg TesterIL.exe
Microsoft (R) Common Language Runtime Test Debugger Shell
Version 1.1.4322.573
Copyright (C) Microsoft Corporation 1998-2002. All rights reserved.
  
(cordbg) run TesterIL.exe
Process 1004/0x3ec created.
Warning: couldn't load symbols for 
c:\windows\microsoft.net\framework\v1.0.3617\mscorlib.dll
[thread 0x61c] Thread created.
  
057:     IL_0000:  ldc.i4.0
(cordbg) show
052:     .entrypoint
053:     // Code size       51 (0x33)
054:     .maxstack  2
055:     .locals init (int32 V_0,
056:              object V_1)
057:*    IL_0000:  ldc.i4.0
058:     IL_0001:  stloc.0
059:     IL_0002:  br.s       IL_0024
060:
061:     IL_0004:  ldloc.0
062:     IL_0005:  box        [mscorlib]System.Int32
(cordbg)

See Also

Csc.exe, ILAsm.exe, ILDasm.exe