Intel® Debugger (IDB) Manual

1.8.1 Looking at the Source Files

You can perform the following operations on source files:

• Tell the debugger where your sources are, if it cannot find them.
• Find out the name of the current source file.
• Switch to a different source file.
• List lines in a source file.
• Search within a source file.

(idb) file
x_list.cxx
(idb) list 180: 10
    180 main()
    181 {
    182     List<Node> nodeList;
    183
    184     // add entries to list
    185     //
>   186     IntNode* newNode = new IntNode(1);
    187     nodeList.append(newNode);
    188
    189     CompoundNode* cNode = new CompoundNode(12.345, 2);
(idb) /CompoundNode
    192     CompoundNode* cNode1 = new CompoundNode(3.1415, 7);

(idb) alias W 
W       list $curline - 10:20
(idb) W 
    176
    177
    178 //  The driver for this test
    179 //
    180 main()
    181 {
    182     List<Node> nodeList;
    183
    184     // add entries to list
    185     //
>   186     IntNode* newNode = new IntNode(1);
    187     nodeList.append(newNode);
    188
    189     CompoundNode* cNode = new CompoundNode(12.345, 2);
    190     nodeList.append(cNode);
    191
    192     nodeList.append(new IntNode(3));
    193
    194     IntNode* newNode2 = new IntNode(4);
    195     nodeList.append(newNode2);

(idb) info source
Current source file is x_list.cxx
(idb) list 180,10
180	main()
181	{
182	    List<Node> nodeList;
183
184	    // add entries to list
185	    //
186	    IntNode* newNode = new IntNode(1);
187	    nodeList.append(newNode);
188
189	    CompoundNode* cNode = new CompoundNode(12.345, 2);
(idb) forward-search CompoundNode
192	    CompoundNode* cNode1 = new CompoundNode(3.1415, 7);

1.8.2 Looking at the Threads

In a multithreaded application, you can obtain information about the thread that stopped or about all the threads, and you can then change the context to look more closely at a different thread. Note that a right bracket (>) marks the current thread. And the asterisk (*) marks the thread with return status.

(idb) thread
  Thread Name                      State           Substate    Policy       Pri
  ------ ------------------------- --------------- ----------- ------------ ---
>*     1 default thread            running VP 3                SCHED_OTHER  19

(idb) show thread
  Thread Name                      State           Substate    Policy       Pri
  ------ ------------------------- --------------- ----------- ------------ ---
>*     1 default thread            running VP 3                SCHED_OTHER  19
      -1 manager thread            blk SCS                     SCHED_RR     19
      -2 null thread for slot 0    running VP 1                null thread  -1
      -3 null thread for slot 1    ready VP 3                  null thread  -1
      -4 null thread for slot 2    new             new         null thread  -1
      -5 null thread for slot 3    new             new         null thread  -1
       2 threads(0x140000798)      blocked         cond 3      SCHED_OTHER  19
       3 threads+8(0x1400007a0)    blocked         cond 3      SCHED_OTHER  19
       4 threads+16(0x1400007a8)   blocked         cond 3      SCHED_OTHER  19
       5 threads+24(0x1400007b0)   blocked         cond 3      SCHED_OTHER  19
       6 threads+32(0x1400007b8)   blocked         cond 3      SCHED_OTHER  19

(idb) thread 2
  Thread Name                      State           Substate    Policy       Pri
  ------ ------------------------- --------------- ----------- ------------ ---
>      2 threads(0x140000798)      blocked         cond 3      SCHED_OTHER  19

(idb) info threads
  0 Thread 1024 (LWP 19513)  0x804f8f6 in __sigsuspend from /tmp/pthread_manythreads
  1 Thread 2049 (LWP 19514)  0x805a42a in __clone from /tmp/pthread_manythreads
* 2 Thread 1026 (LWP 19515)  0x804f8f6 in __sigsuspend from /tmp/pthread_manythreads
  3 Thread 2051 (LWP 19516)  0x804f8f6 in __sigsuspend from /tmp/pthread_manythreads
  4 Thread 3076 (LWP 19517)  0x804f8f6 in __sigsuspend from /tmp/pthread_manythreads
  5 Thread 4101 (LWP 19518)  0x8048288 in prime_search at pthread_manythreads.c:79

(idb) thread 2
* 2 Thread 1026 (LWP 19515)  0x804f8f6 in __sigsuspend from /tmp/pthread_manythreads

1.8.3 Looking at the Call Stack

You can examine the call stack of any thread. Even if you are not using threads explicitly, your process will have one thread running your code. You can move up and down the stack, and examine the source being executed at each call.

(idb) where 4
>0  0x804a519 in ((Node*)0x80c38f0)->Node::Node() "x_list.cxx":79
#1  0x804a568 in ((IntNode*)0x80c38f0)->IntNode::IntNode(data=2) "x_list.cxx":88
#2  0x804a61f in ((CompoundNode*)0x80c38f0)->CompoundNode::CompoundNode(fdata=12.3450003, idata=2) "x_list.cxx":103
#3  0x804a09e in main() "x_list.cxx":189
(idb) up 2
>2  0x804a61f in ((CompoundNode*)0x80c38f0)->CompoundNode::CompoundNode(fdata=12.3450003, idata=2) "x_list.cxx":103
    103     IntNode(idata),
(idb) list $curline - 10: 20
     93     cout << " type is integer, value is ";
     94     cout << _data << endl;
     95 }
     96
     97
     98 //=============================================================================
     99 // CompoundNode definition
    100 //
    101 CompoundNode::CompoundNode(float fdata, int idata)
    102   :
>   103     IntNode(idata),
    104     _fdata (fdata)
    105 {
    106 }
    107 void CompoundNode::printNodeData() const
    108 {
    109     cout << " type is compound, value is ";
    110     cout << _fdata << endl;
    111     cout << "       parent ";
    112     IntNode::printNodeData();
(idb) down 1
>1  0x804a568 in ((IntNode*)0x80c38f0)->IntNode::IntNode(data=2) "x_list.cxx":88
     88 IntNode::IntNode(int data) : _data(data)

(idb) backtrace 4
>0  0x804a519   in ((Node*)(class Node *) 0x80c38f0)->Node::Node(this=(class Node *) 0x80c38f0) "x_list.cxx":79
#1  0x804a568   in ((IntNode*)(class IntNode *) 0x80c38f0)->IntNode::IntNode(this=(class IntNode *) 0x80c38f0, data=2) "x_list.cxx":88
#2  0x804a61f   in ((CompoundNode*)(class CompoundNode *) 0x80c38f0)->CompoundNode::CompoundNode(this=(class CompoundNode *) 0x80c38f0, fdata=12.345, idata=2) "x_list.cxx":103
#3  0x804a09e   in main() "x_list.cxx":189
(idb) up 2
>2  0x804a61f   in ((CompoundNode*)(class CompoundNode *) 0x80c38f0)->CompoundNode::CompoundNode(this=(class CompoundNode *) 0x80c38f0, fdata=12.345, idata=2) "x_list.cxx":103
103	    IntNode(idata),
(idb) list 93,112
93	    cout << " type is integer, value is ";
94	    cout << _data << endl;
95	}
96
97
98	//=============================================================================
99	// CompoundNode definition
100	//
101	CompoundNode::CompoundNode(float fdata, int idata)
102	  :
103	    IntNode(idata),
104	    _fdata (fdata)
105	{
106	}
107	void CompoundNode::printNodeData() const
108	{
109	    cout << " type is compound, value is ";
110	    cout << _fdata << endl;
111	    cout << "       parent ";
112	    IntNode::printNodeData();
(idb) down 1
>1  0x804a568   in ((IntNode*)(class IntNode *) 0x80c38f0)->IntNode::IntNode(this=(class IntNode *) 0x80c38f0, data=2) "x_list.cxx":88
88	IntNode::IntNode(int data) : _data(data)

1.8.4 Looking at the Data

You can look at variables and evaluate expressions involving them by using the print command.

(idb) print fdata
12.3450003
(idb) print idata
2
(idb) print idata + 59
61
(idb) print this
0x80c3670
(idb) print *this
class CompoundNode {
  _fdata = 0;
  _data = 0;                      // class IntNode
  _nextNode = 0x0;                // class IntNode::Node
}

(idb) print fdata
$2 = 12.345
(idb) print idata
$3 = 2
(idb) print idata + 59
$4 = 61
(idb) print this
$5 = (class CompoundNode *) 0x80c3670
(idb) print *this
$6 = {<IntNode> = {<Node> = {_nextNode = 0x0}, _data = 0}, _fdata = 0}

1.8.5 Looking at the Signal State

The debugger shows you the signal that stopped the thread.

(idb) run
Thread received signal SEGV
stopped at [void buggy(char*, char*):13 0x8048b79]
     13         output[k] = input[k];

Information: idb allows you to restart the execution of your program
from saved positions. Enter "help snapshot" for details.

(idb) run
Starting program: /usr/examples/x_segv
Thread received signal SEGV
buggy (input=0xbffff2f1 "/usr/examples/x_segv", output=0x0) at x_segv.cxx:13
13	        output[k] = input[k];

Information: idb allows you to restart the execution of your program
from saved positions. Enter "help snapshot" for details.

1.8.6 Looking at the Generated Code

You can print memory as instructions or as data.

(idb) alias wi 
wi	($curpc - 20)/10 i
(idb) wi
CompoundNode::CompoundNode(float, int): x_list.cxx
 [line 105, 0x120002348]	cpys	$f17,$f17,$f0
 [line 105, 0x12000234c]	bis	r31, r18, r8
 [line 101, 0x120002350]	bis	r31, r19, r16
 [line 101, 0x120002354]	bis	r31, r8, r17
 [line 101, 0x120002358]	bsr	r26, IntNode::IntNode(int)
*[line 101, 0x12000235c]	ldq	r18, -32712(gp)
 [line 101, 0x120002360]	lda	r18, 48(r18)
 [line 101, 0x120002364]	stq	r18, 8(r19)
 [line 101, 0x120002368]	sts	$f0, 24(r19)
 [line 106, 0x12000236c]	bis	r31, r19, r0
(idb) $pc/10x 
0x12000235c: 0x8038 0xa65d 0x0030 0x2252 0x0008 0xb653 0x0018 0x9813
0x12000236c: 0x0400 0x47f3
(idb) $pc/6xx 
0x12000235c: 0xa65d8038 0x22520030 0xb6530008 0x98130018
0x12000236c: 0x47f30400 0x47f5041a
(idb) $pc/2X 
0x12000235c: 0x22520030a65d8038 0x98130018b6530008

(idb) x /10i $pc
Dump of assembler code for function CompoundNode::CompoundNode(class CompoundNode * const, float, int):
0x804a60e <_ZN12CompoundNodeC1Efi(...)+24>:         addl     $-8, %esp
0x804a611 <_ZN12CompoundNodeC1Efi(...)+27>:         movl     -12(%ebp), %eax
0x804a614 <_ZN12CompoundNodeC1Efi(...)+30>:         movl     %eax, (%esp)
0x804a617 <_ZN12CompoundNodeC1Efi(...)+33>:         movl     -4(%ebp), %eax
0x804a61a <_ZN12CompoundNodeC1Efi(...)+36>:         movl     %eax, 0x4(%esp)
0x804a61e <_ZN12CompoundNodeC1Efi(...)+40>:         call     0x804a54e <_ZN7IntNodeC1Ei(...)>
0x804a623 <_ZN12CompoundNodeC1Efi(...)+45>:         addl     $0x8, %esp
0x804a626 <_ZN12CompoundNodeC1Efi(...)+48>:         movl     -12(%ebp), %eax
0x804a629 <_ZN12CompoundNodeC1Efi(...)+51>:         movl     $0x8087834, (%eax)
0x804a62f <_ZN12CompoundNodeC1Efi(...)+57>:         movl     -12(%ebp), %eax
(idb) x /10x $pc
0x804a60e: 0xc483 0x8bf8 0xf445 0x0489 0x8b24 0xfc45 0x4489 0x0424
0x804a61e: 0x2be8 0xffff
(idb) x /6w $pc
0x804a60e: 0x8bf8c483 0x0489f445 0xfc458b24 0x04244489
0x804a61e: 0xffff2be8 0x08c483ff
(idb) x /2g $pc
0x804a60e: 0x000000008bf8c483 0x00000000fc458b24

To examine individual registers, use the print command with name of register prepended with the dollar sign ($). Commands showing all (or subset of) the registers, are specific for the mode, see examples below.

(idb) print $eax
134942544
(idb) printx $eax
0x80b0f50
(idb) printregs
$eax           0x80b0f50	134942544
$ecx           0xa1	161
$edx           0x0	0
$ebx           0x401ae9e4	1075505636
$esp [$sp]     0xbffff53c	-1073744580
$ebp           0xbffff55c	-1073744548
$esi           0x40016b64	1073834852
$edi           0xbffff6bc	-1073744196
$eip [$pc]     0x804a628	134522408
$eflags        0x287	647
$cs            0x23	35
$ss            0x2b	43
$ds            0x2b	43
$es            0x2b	43
$fs            0x0	0
$gs            0x0	0
$orig_eax      0xffffffff	-1
$fctrl         0x37f	895
$fstat         0x0	0
$ftag          0x0	0
$fiseg         0x23	35
$fioff         0x804a619	134522393
$foseg         0x2b	43
$fooff         0xbffff554	-1073744556
$fop           0x0	0
$f0            0x00000000000000000000000000000000 0
$f1            0x0000000000003ffdf13a8dc3008792a0 0.47115
$f2            0x00000000000000000000000000000000 0
$f3            0x00000000000000000000000000000000 0
$f4            0x00000000000000000000000000000000 0
$f5            0x00000000000000000000000000000000 0
$f6            0x0000000000003ffb9700000000000000 0.0737305
$f7            0x0000000000004002c5851f0000000000 12.345
$xmm0          0x00000000000000000000000000000000
$xmm1          0x00000000000000000000000000000000
$xmm2          0x00000000000000000000000000000000
$xmm3          0x00000000000000000000000000000000
$xmm4          0x00000000000000000000000000000000
$xmm5          0x00000000000000000000000000000000
$xmm6          0x00000000000000000000000000000000
$xmm7          0x00000000000000000000000000000000
$mxcsr         0x1f80	8064
$vfp           0xbffff55c	0xbffff55c

(idb) print $eax
$11 = 134942544
(idb) print $eax
$12 = 0x80b0f50
(idb) info registers
$eax           0x80b0f50	134942544
$ecx           0xa1	161
$edx           0x0	0
$ebx           0x401ae9e4	1075505636
$esp [$sp]     0xbffff53c	-1073744580
$ebp           0xbffff55c	-1073744548
$esi           0x40016b64	1073834852
$edi           0xbffff6bc	-1073744196
$eip [$pc]     0x804a628	134522408
$eflags        0x287	647
$cs            0x23	35
$ss            0x2b	43
$ds            0x2b	43
$es            0x2b	43
$fs            0x0	0
$gs            0x0	0
$orig_eax      0xffffffff	-1
$fctrl         0x37f	895
$fstat         0x0	0
$ftag          0x0	0
$fiseg         0x23	35
$fioff         0x804a619	134522393
$foseg         0x2b	43
$fooff         0xbffff554	-1073744556
$fop           0x0	0
$f0            0x00000000000000000000000000000000 0
$f1            0x0000000000003ffdf13a8dc3008792a0 0.47115
$f2            0x00000000000000000000000000000000 0
$f3            0x00000000000000000000000000000000 0
$f4            0x00000000000000000000000000000000 0
$f5            0x00000000000000000000000000000000 0
$f6            0x0000000000003ffcdcd8000000000000 0.215668
$f7            0x0000000000004002c5851f0000000000 12.345
$xmm0          0x00000000000000000000000000000000
$xmm1          0x00000000000000000000000000000000
$xmm2          0x00000000000000000000000000000000
$xmm3          0x00000000000000000000000000000000
$xmm4          0x00000000000000000000000000000000
$xmm5          0x00000000000000000000000000000000
$xmm6          0x00000000000000000000000000000000
$xmm7          0x00000000000000000000000000000000
$mxcsr         0x1f80	8064
$vfp           0xbffff55c	0xbffff55c

4.3.1 History Replacement of the Line

Leading spaces and tabs are removed from the assembled line.

For assembled lines that begin with an exclamation point (!), the following rules apply:

• If the second character is also an exclamation point (!), the assembled line is replaced by the most-recent entry from the history list. Any remaining characters after the digits or ! are appended to the assembled line.
• Otherwise, spaces and tabs are skipped, and one of the following actions occurs:
  • If the next character is a digit, then the digits are read as a decimal number, and the assembled line is replaced by that line from the history list, with 1 being the oldest entry.
  • If the next character is a hyphen (-), then the digits following it are read as a decimal number, and the assembled line is replaced by that line from the history list, with -1 being the most-recent entry.
  • Otherwise, the rest of the line is used to find the most-recent command that starts with those characters, and the assembled line is replaced by that line from the history list.
  In the first two cases, any remaining characters after the digits are appended to the assembled line.

For lines that begin with a caret (^), these rules apply:

• The line is analyzed to extract the following:
  1. The characters following the first caret but before a second caret, or until the end of line. These characters are the target string.
  2. If there is a second caret, the characters following it but before a third caret, or until the end of line. These characters are the replacement string.
  3. If there is a third caret, the characters following it to the end of the line. These characters are the append string.
• The most-recent entry from the history list is checked to see if it has an occurrence of the target string. If it does not, an error is reported.
• The assembled line is replaced by this most-recent entry, except that the first occurrence of the target string is replaced by the replacement string (possibly zero length), and the append string is appended to the assembled line.

The assembled line is now appended to the history list.

Exclamation points and carets cannot be used in command lists built with braces ({}); for example, {print3; !!3} will not parse. They may be used in scripts.

History in a command list is not limited by braces, but goes all the way back. For example:

(idb) print 1
1
(idb) stop in main { print 2; history 3}
[#1: stop in int main(void) { print 2; history 3} ]
(idb) run
2
11: print 1
12: stop in main {print 2; history 3}
13: run
[1] stopped at [int main(void):182 0x8049f70]
    182     List<Node> nodeList;

4.3.3 Environment Variable Expansion

The debugger expands environment variables and the leading tilde (~) in the following cases:

• As part of a command in which a file name or a directory is expected.
• In the arguments to run or rerun(dbx).

As in any shell, you can group an environment variable name using a pair of curly braces ({}), and quote a dollar sign ($) by preceding it with a backslash (\).

The following table shows how various environment variables expand. It assumes that the home directory is /usr/users/hercules and the environment variable BIN is /usr/users/hercules/bin.

4.4.1 Lexical Elements of Commands

For the debugger to parse the line, it must first turn the line into a sequence of tokens, a process called "tokenizing" or "lexical analysis". Tokenizing is done with a state machine.

As the debugger starts tokenizing a line into a command, it starts processing the characters using the lexical state LKEYWORD. It uses the rules for lexical tokens in this state, recognizing the longest sequence of characters that forms a lexical token.

After the lexical token is recognized, the debugger appends it to the tokenized form of the line, perhaps changes the state of the tokenizer, and starts on the next token.

For more detailed information on lexical elements, see Lexical Elements of Commands in Part III.

4.4.2 Grammar of Commands

Each command line must parse as one of the following:

input
        : command_list
        | comment

A command_list is a sequence of commands that are executed one after the other.

command_list
        : command ;...
        | command ;
        | command

A comment is a line that begins with a pound (#) character.

comment
        : #

Any text after an unquoted pound character is ignored by the debugger. If the first non-whitespace character on a line is a pound character, the whole line is ignored.

4.4.3 Categories of Commands

Commands usually start with, and often contain, keywords. These keywords must be lowercase.

command
        : alias_command
        | attach_command
        | braced_command_list
        | breakpoint_command
        | browse_source_command
        | call_stack_command
        | command_repetition_command
        | continue_command
        | detach_command
        | dbgvar_command
        | edit_file_command
        | environment_variable_command
        | execute_commands_from_file_command
        | execute_shell_command
        | guion_command
        | help_command
        | history_command
        | if_command
        | kill_command
        | load_command
        | look_around_command
        | machinecode_level_command
        | modifying_command
        | multiprocess_command
        | parallel_debugging_command
        | quit_command
        | record_command
        | run_command
        | snapshot_command
        | shared_library_command
        | thread_command
        | unload_command

4.4.4 Keywords Within Commands

If the identifiers thread, in, at, and if occur within the expression in the following commands, the debugger treats them as keywords unless they are enclosed within parentheses (()).

• where expression
• stopi expression
• trace expression
• tracei expression
• wheni expression

For example, if your program has thread defined as an integer, enter the following command to inspect the first thread levels of the stack.

For example:

(idb) where 3
>0  0x8049a6c in c() "x_whereAmbigParse.c":7
#1  0x8049a8f in b() "x_whereAmbigParse.c":12
#2  0x8049aa2 in a() "x_whereAmbigParse.c":13
(idb)
(idb)
(idb)
(idb) where three(3)
>0  0x8049a6c in c() "x_whereAmbigParse.c":7
#1  0x8049a8f in b() "x_whereAmbigParse.c":12
#2  0x8049aa2 in a() "x_whereAmbigParse.c":13
(idb)
(idb)
(idb)
(idb) where thread (1)
Stack trace for thread 1
>0  0x8049a6c in c() "x_whereAmbigParse.c":7
#1  0x8049a8f in b() "x_whereAmbigParse.c":12
#2  0x8049aa2 in a() "x_whereAmbigParse.c":13
#3  0x8049abe in main() "x_whereAmbigParse.c":17
#4  0x400dd177 in __libc_start_main(...) in /lib/i686/libc.so.6
#5  0x8049929 in _init(...) in /usr/examples/x_whereAmbigParse

(idb)
(idb)
(idb)
(idb) where three(3) thread (1)
Stack trace for thread 1
>0  0x8049a6c in c() "x_whereAmbigParse.c":7
#1  0x8049a8f in b() "x_whereAmbigParse.c":12
#2  0x8049aa2 in a() "x_whereAmbigParse.c":13

(idb)
(idb)
(idb)
(idb) where (thread(3))
>0  0x8049a6c in c() "x_whereAmbigParse.c":7
#1  0x8049a8f in b() "x_whereAmbigParse.c":12
#2  0x8049aa2 in a() "x_whereAmbigParse.c":13
(idb)
(idb)
(idb)

4.4.5 Using Braces to Make a Composite Command

It is possible to surround a command_list with braces to make it work like a single command. Some places require a braced_command_list just for readability, or to assist the debugger in understanding your input.

braced_command_list
        : { command_list }

4.4.6 Conditionalizing Command Execution

The debugger provides the if command, whose behavior depends on the value of an expression.

if_command
        : if expression braced_command_list [ else_clause ]

else_clause
        : else braced_command_list

In this command, the first braced_command_list is executed if expression evaluates to a non-zero value; otherwise, the braced_command_list in the else_clause is executed, if specified.

For example:

(idb) set $c = 1
(idb) assign pid = 0
(idb) if (pid < $c) { print "Greater" } else { print "Lesser" }
Greater

4.4.7 Debugger Variables

Debugger variables are pseudovariables that exist within the debugger instead of within your program. They have the following uses:

• Support some limited programming capabilities within the debugger command language
• Allow you to examine and change various debugger options
• Allow you to find out exactly what various debugger commands did

The following table lists the three different varieties of debugger variables:

For more information about debugger variables, see Appendix 1 — Debugger Variables.

The following commands deal specifically with debugger variables:

dbgvar_command
        : set dbgvar_name = expression
        | set dbgvar_name
        | set
        | unset dbgvar_name

The dbgvar_name should not exist anywhere in your program, or you may confuse yourself about which of the occurrences you are actually dealing with. The predefined debugger variables all start with a dollar sign ($), to help avoid this confusion. It is strongly recommended that you follow the same practice; in a future release, all debugger variables will be required to start with a dollar sign.

The first form creates the debugger variable if it does not already exist. It then sets the value of the debugger variable to the result of evaluating the expression. For example:

(idb) set $myLoopCounter = 0
(idb) print $myLoopCounter
0

The second form is equivalent to the command set dbgvar_name = 1. For example:

(idb) print $stoponattach
0
(idb) set $stoponattach
(idb) print $stoponattach
1

The set form shows all the debugger variables and their values:

(idb) set
$ascii = 0
$beep = 1
$catchexecs = 0
$catchforkinfork = 0
$catchforks = 0
$childprocess = 0
$cmdset = "idb"
$curevent = 0
$curfile = "x_list.cxx"
$curfilepath = "../src/x_list.cxx"
$curline = 182
$curpc = 0x8049f4c
$curprocess = 30078
$cursrcline = 182
$cursrcpc = 0x8049f4c
$curthread = 1
$dbxoutputformat = 0
$dbxuse = 0
$debuggerpid = 30076
$decints = 0
$disasm_shows_unwind = 0
$doverbosehelp = 1
$editline = 1
$eventecho = 1
$floatshrinking = 1
$framesearchlimit = 0
$funcsig = 1
$givedebughints = 1
$hasmeta = 0
$hexints = 0
$historylines = 20
$indent = 1
$lang = "C++"
$lasteventmade = 0
$lc_ctype = "en_US.ISO8859-1"
$listwindow = 20
$main = "\"x_list.cxx\"`main"
$maxarrlen = 1024
$maxstrlen = 128
$memorymatchall = 0
$myLoopCounter = 0
$octints = 0
$overloadmenu = 1
$page = 1
$pagewindow = 0
$parentprocess = 0
$pimode = 1
$prompt = "(idb) "
$readtextfile = 0
$regstyle = 1
$repeatmode = 1
$reportsotrans = 0
$showlineonstartup = 0
$showwelcomemsg = 1
$stackargs = 1
$statusargs = 1
$stepg0 = 0
$stoponattach = 1
$stopparentonfork = 0
$symbolsearchlimit = 100
$threadlevel = "native"
$usedynamictypes = 1
$verbose = 0

To see the value of just one debugger variable, print it. For example:

(idb) print $catchexecs
0

The unset form deletes the debugger variable. Some predefined debugger variables either cannot be deleted or are automatically recreated in the future when needed. For example:

(idb) unset $myLoopCounter
(idb) print $myLoopCounter
Symbol "$myLoopCounter" is not defined.
(idb) unset $catchforks
Warning: The debugger variable "$catchforks" was not unset because it is an idb predefined variable

4.5.1 Recording Input and Output

To help you make command files, as well as to help you see what has happened before, the debugger can write both its input and its output to files, as follows:

record_command
        : record io  [ filename ]
        | record input [ filename ]
        | record output [ filename ]
        | unrecord io
        | unrecord input
        | unrecord output

Use record input to save debugger commands to a file. The commands in the file can be executed using the source command or the playback input command.

If no file name is specified, the debugger creates a file with a random file name in /tmp as the record file. The debugger issues a message giving the name of that file.

To stop recording debugger input or output, redirect as shown in the following example, use the appropriate version of the unrecord command, or exit the debugger:

(idb) record input /dev/null
(idb) record output /dev/null

The following example shows how to use the record input command to record a series of debugger commands in a file named myscript:

(idb) record input myscript
(idb) stop in main
[#1: stop in int main(void) ]
(idb) run
[1] stopped at [int main(void):182 0x8049f48]
    182     List<Node> nodeList;
(idb) record input /dev/null

This example results in the following recorded input in myscript:

(idb) sh cat myscript
stop in main
run
record input /dev/null

The record output command saves the debugger output to a file. The output is simultaneously written to stdout (normal output) or stderr (error messages). For example:

(idb) record output myscript
(idb) stop in List<Node>::append
[#2: stop in void List<Node>::append(struct Node* const) ]
(idb) cont
[2] stopped at [void List<Node>::append(struct Node* const):148 0x8058026]
    148     if (!_firstNode)
(idb) next
stopped at [void List<Node>::append(struct Node* const):149 0x805802f]
    149         _firstNode = node;

After the above commands are executed, myscript contains the following:

(idb) sh cat myscript
[#2: stop in void List<Node>::append(struct Node* const) ]
[2] stopped at [void List<Node>::append(struct Node* const):148 0x8058026]
    148     if (!_firstNode)
stopped at [void List<Node>::append(struct Node* const):149 0x805802f]
    149         _firstNode = node;

The record io command saves both input to and output from the debugger. For example:

(idb) record io myscript
(idb) stop in main
[#1: stop in int main(void) ]
(idb) run
[1] stopped at [int main(void):12 0x120001130]
     12 int i;
(idb) quit
% cat myscript
(idb) stop in main
[#1: stop in int main(void) ]
(idb) run
[1] stopped at [int main(void):12 0x120001130]
     12 int i;
(idb) quit

If input or output is already being recorded, a new record input command will close the old file and record to a new one, rather than record simultaneously to two files. In that connection, note that record io is equivalent to the combination of record input and record output, and will cause any open recording files to be closed.

Note that the prompt itself is only recorded for record io.

4.5.2 Viewing the Command History

You can see all the commands you have already entered by using the history command. Use history_number to indicate how many commands to show, starting with the most recent. If you do not specify $historylines, the 20 previous commands are shown. See also History replacement of the line.

history_command
        : history [ integer_constant ]

For example:

(idb) history 6
18: stop in main
19: run
20: stop at 103
21: cont
22: print "history_EXAMPLE START"
23: history 6

7.1.1 Disposition

disposition
        : stop
        | when

The stop command specifies that when the event specified by the breakpoint occurs and all processing for that breakpoint has been completed, the debugger should prompt for further commands.

The when command specifies that when the event specified by the breakpoint occurs and all processing for that breakpoint has been completed, the debugger may resume execution of the program. See the section When Multiple Breakpoints Trigger at Once for an explanation of how the debugger determines when to resume execution.

7.1.2 The quiet Specifier

By default, when an event is detected and the debugger determines that the breakpoint actions should be performed, the debugger prints a line that identifies the breakpoint, for example:

(idb) when in main { stop }
[#1: when in int main(void) { stop } ]
(idb) run
[1] when [int main(void):182 0x8049f48]
[1] stopped at [int main(void):182 0x8049f48]
    182     List<Node> nodeList;

The optional quiet specifier tells the debugger to omit this information.

(idb) when quiet in main { stop }
[#11: when quiet in int main(void) { stop } ]
(idb) run
(idb) list $curline: 1
>   182     List<Node> nodeList;

7.1.3 Detectors

The debugger uses several kinds of detectors, each corresponding to a particular kind of event:

detector
        : place_detector
        | watch_detector
        | signal_detector
        | unaligned_detector

A place detector specifies a place or location in your program. It can refer to the beginning of a function, a particular line in one of your source files, a specific value of the PC (program counter), or certain sets of these.

A watch detector specifies a variable or other memory locations that should be monitored to detect certain kinds of access (read, write, and so on).

A signal detector specifies a set of signals to be monitored.

An unaligned access detector specifies any kind of memory access using an unaligned access.

This section describes each type of detector.

place_detector
        : in function_name
        | in all function_name
        | pc address_expression
        | at line_specifier
        | every proc entry
        | every procedure entry
        | every instruction
        | expression

(idb) stop in foo
Select from
----------------------------------------------------
     1 int C::foo(double*)
     2 void C::foo(float)
     3 void C::foo(int)
     4 void C::foo(void)
     5 None of the above
----------------------------------------------------
2
[#4: stop in void C::foo(float) ]

(idb) stop in all foo
[#3: stop in all foo ]

(idb) stop pc $pc + 8
[#7: stop PC == 0x804a539 ]

(idb) stop at 190
[#8: stop at "x_list.cxx":190 ]

(idb) stop every procedure entry
[#9: stop every procedure entry ]

(idb) stop every instruction
[#10: stop every instruction ]

watch_detector
        : basic_watch_detector watch_detector_modifiers

basic_watch_detector
        : variable expression
        | memory start_address_expression
        | memory start_address_expression , end_address_expression
        | memory start_address_expression : byte_count_expression

watch_detector_modifiers
        : [ access_modifier ] [ within_modifier ]

access_modifier
        : write
        | read
        | changed
        | any

within_modifier
        : within function_name

(idb) whatis _nextNode
struct Node* Node::_nextNode
(idb) print "sizeof(_nextNode) =", sizeof((_nextNode))
sizeof(_nextNode) = 4
(idb) stop variable _nextNode write
[#3: stop variable _nextNode write ]

(idb) whatis t
int t
(idb) stop variable t write within foo
[#2: stop variable t write within void C::foo(void) ]
(idb) cont
[2] Address 0x804bbfc was accessed at:
void C::foo(void): x_overload.cxx
 [line 22, 0x8048af3]	foo+0x6:              movl     $0x0, 0x804bbfc
	0x804bbfc: Old value = 0x0000000f
	0x804bbfc: New value = 0x00000000
[2] stopped at [void C::foo(void):22 0x8048afd]
     22 void C::foo()         { t = 0; state++; return; }

signal_detector
        : signal signal_id ,...

signal_id
        : integer_constant
        | signal_name

(idb) stop signal SEGV, 3, SIGINT
[#2: stop signal SEGV, 3, SIGINT ]

unaligned_detector
        : unaligned

Unaligned access pid=30231 <x_signals> va=0x11ffff791 pc=0x120001af4 ra=0x120001b84 inst=0xa0220000

(idb) stop unaligned access
[#1: stop unaligned access ]
(idb) run
Thread encountered Unaligned Access
[1] stopped at [int unalignedAccess(void):27 0x120001af8]
     27     return y;

7.1.4 Thread Filter

A thread filter determines whether a detected event should be further considered for breakpoint processing.

thread_filter
        : thread thread_id ,...

The thread_id expressions are evaluated at the time the breakpoint command is entered, and each must yield an integer value.

A detected event is retained for further consideration only if the thread in which the event occurs matches one of the given threads. If not, the detection is quietly ignored.

If the thread_filter does not indicate a match, then any related logical filter is not evaluated.

7.1.5 Logical Filter

A logical filter determines whether a detected event should be further considered for breakpoint processing:

logical_filter
        : if expression

A detected event is retained for further consideration only if the given expression evaluates to true. If not, the detection is quietly ignored.

The expression is checked syntactically in the context of the place where the breakpoint command is given: it must be syntactically valid according to the language rules that apply there. However, the expression is not evaluated and names that occur in the expression need not be visible. After the syntax check, the expression is remembered in an internal form and is not rechecked later when it is evaluated.

If an error occurs when the expression is evaluated, for example, because a name in the expression is not defined, then the error is reported and the value of the expression is assumed to be true.

An error in the expression does not change the disposition. If continuation was specified, then that is still what occurs. For example:

(idb) when in List<Node>::append if x
[#5: when in void List<Node>::append(struct Node* const) if x ]
(idb) cont
Symbol "x" is not defined.
[Error while evaluating breakpoint condition - taken as true]
[5] when [void List<Node>::append(struct Node* const):148 0x8058026]
Symbol "x" is not defined.
[Error while evaluating breakpoint condition - taken as true]
[5] when [void List<Node>::append(struct Node* const):148 0x8058026]
[4] stopped at [int main(void):195 0x804a1ad]
    195     nodeList.append(new IntNode(3));

It is valid for a logical filter expression to contain a call to another routine in your program. Such a call is evaluated in the same way as if it occurred in a call or print command. However, execution of the called routine might result in triggering a breakpoint; this is called a recursive breakpoint.

7.1.6 Breakpoint Actions

The action part of a breakpoint command specifies actions to be performed when the event part has triggered (including passing any thread and/or logical filters):

breakpoint_actions
        : { action_list }

action_list
        : command
        | command ;
        | command ;...

7.1.7 When Multiple Breakpoints Trigger at Once

It is possible for multiple breakpoints to specify the same event, or possibly overlapping events. Thus, more that one breakpoint detector may trigger at the same time.

When more than one breakpoint detector triggers, the thread filters and logical filters of all the breakpoints involved are processed before the action part of any breakpoint is performed.

After the set of breakpoints that trigger is determined, the action parts of each of them are performed in an undefined order.

After all action parts are performed, execution of the program is resumed only if all of the breakpoints so specify in their disposition. If any one of them specifies a break, the debugger prompts you for further commands.

7.1.8 Recursive Breakpoints

The following commands cause the debugger to resume execution of your program while in the midst of action list processing:

• call
• continue
• goto
• next
• return
• step
• Any command that contains an expression whose evaluation involves calling a function in your program

In all of these cases, the debugger temporarily suspends processing of the current breakpoint to start your program executing again and then waits for that execution to complete. As long as no new breakpoint is triggered during that execution, all will be fine. However, if a new breakpoint triggers, in particular one with the stop disposition, then you may be prompted for new command input for the recursive breakpoint even before the initial breakpoint has completed. Further, continuing execution may ultimately allow the original breakpoint to complete, at which time its disposition will come into play.

It is easy in such cases to lose track of just what state breakpoint processing is really in or where you really are in your program. Such confusion may mislead or misdirect your debugging effort. See the call command example, which locates suspended execution in nested function calls.

7.1.9 Breakpoints and C++

This section describes how to use breakpoints when debugging C++ programs.

(idb) list 3: 25
      3 class C {
      4 public:
      5     void foo();
      6     void foo(int);
      7     void foo(float);
      8     int  foo(double *);
      9 };
     10
     11 C  o;
     12 C* p = new C;
     13 int t     = 0;
     14 int state = 1;
     15
     16 main(){
     17     t++;
     18     o.foo();
     19
     20 }
     21
     22 void C::foo()         { t = 0; state++; return; }
     23 void C::foo(int i)    { state++; return;  }
     24 void C::foo(float f)  { state++; return;  }
     25 int  C::foo(double *) { return state;}

(idb) stop in main
[#1: stop in int main(void) ]
(idb) run
[1] stopped at [int main(void):17 0x8048ad3]
     17     t++;
(idb) stop in foo
Symbol "foo" is not defined.
foo has no valid breakpoint address
Warning: Breakpoint not set

(idb) stop in C::foo
Select from
----------------------------------------------------
     1 int C::foo(double*)
     2 void C::foo(float)
     3 void C::foo(int)
     4 void C::foo(void)
     5 None of the above
----------------------------------------------------
3
[#5: stop in void C::foo(int) ]
(idb) stop in o.foo
Select from
----------------------------------------------------
     1 int C::foo(double*)
     2 void C::foo(float)
     3 void C::foo(int)
     4 void C::foo(void)
     5 None of the above
----------------------------------------------------
1
[#6: stop in int C::foo(double*) ]
(idb) stop in p->foo
Select from
----------------------------------------------------
     1 int C::foo(double*)
     2 void C::foo(float)
     3 void C::foo(int)
     4 void C::foo(void)
     5 None of the above
----------------------------------------------------
4
[#7: stop in void C::foo(void) ]

(idb) stop in C::foo(void)
[#8: stop in void C::foo(void) ]
(idb) stop in C::foo(int)
[#9: stop in void C::foo(int) ]

(idb) list 144: 13
    144 template <class NODETYPE>
    145 void List<NODETYPE>::append(NODETYPE* const node)
    146 {
    147
    148     if (!_firstNode)
    149         _firstNode = node;
    150     else {
    151         Node* currentNode = _firstNode;
    152         while (currentNode->getNextNode())
    153             currentNode = currentNode->getNextNode();
    154 	currentNode->setNextNode(node);
    155     }
    156 }

(idb) whatis List<Node>::append
void List<Node>::append(class Node* const)
(idb) stop in List<Node>::append
[#1: stop in void List<Node>::append(class Node* const) ]
(idb) run
[1] stopped at [void List<Node>::append(class Node* const):148 0x120001d9c]
    148     if (!_firstNode)
(idb) where 2
>0  0x120001d9c in ((List<Node>*)0x11fffee68)->List<Node>::append(node=0x140002c00) "x_list.cxx":148
#1  0x1200024a4 in main() "x_list.cxx":187

(idb) list 30: 29
     30 // Throw an exception.  The "throw(int)" syntax tells the compiler that
     31 // only integer exceptions can escape this method.  This will result in
     32 // an unexpected exception from C++.
     33 //
     34 void throwAnException() throw(int)
     35 {
     36     throw "Bug";
     37 }
     38
     39 // Provide some depth to the stack, for demonstration purposes
     40 //
     41 void someOperation()
     42 {
     43     int z = unalignedAccess();  // Some tests ignore this exception
     44     throwAnException();
     45 }
     46
     47 main()
     48 {
     49     try {
     50         someOperation();
     51     }
     52     catch(char* str) {
     53         cout << "Caught exception [" << str << "]" << endl;
     54     }
     55     catch(...) {
     56         cout << "Caught something" << endl;
     57     }
     58 }

(idb) stop at 52
[#1: stop at "x_signals.cxx":52 ]
(idb) stop in all terminate
[#2: stop in all terminate ]
(idb) stop in all unexpected
[#3: stop in all unexpected ]
(idb) run
[3] stopped at [<opaque> unexpected(void) 0x3ff802a064c]

Information:  An <opaque> type was presented during execution of the previous command.  For complete type information on this symbol, recompilation of the program will be necessary.  Consult the compiler man pages for details on producing full symbol table information using the '-g' (and '-gall' for cxx) flags.

(idb) where
>0  0x3ff802a064c in unexpected(...) in /usr/lib/cmplrs/cxx/libcxx.so
#1  0x120001b38 in throwAnException() "x_signals.cxx":36
#2  0x120001b88 in someOperation() "x_signals.cxx":44
#3  0x120001bc4 in main() "x_signals.cxx":50
#4  0x1200019c8 in __start(...) in /usr/examples/x_signals
(idb) cont
[3] stopped at [<opaque> unexpected(...) 0x3ff80287704]
(idb) where
>0  0x3ff80287704 in unexpected(...) in /usr/lib/cmplrs/cxx/libcxx.so
#1  0x3ff802a064c in unexpected(...) in /usr/lib/cmplrs/cxx/libcxx.so
#2  0x120001b38 in throwAnException() "x_signals.cxx":36
#3  0x120001b88 in someOperation() "x_signals.cxx":44
#4  0x120001bc4 in main() "x_signals.cxx":50
#5  0x1200019c8 in __start(...) in /usr/examples/x_signals
(idb) cont
[2] stopped at [<opaque> terminate(...) 0x3ff802875cc]
(idb) where
>0  0x3ff802875cc in terminate(...) in /usr/lib/cmplrs/cxx/libcxx.so
#1  0x3ff80287750 in unexpected(...) in /usr/lib/cmplrs/cxx/libcxx.so
#2  0x3ff802a064c in unexpected(...) in /usr/lib/cmplrs/cxx/libcxx.so
#3  0x120001b38 in throwAnException() "x_signals.cxx":36
#4  0x120001b88 in someOperation() "x_signals.cxx":44
#5  0x120001bc4 in main() "x_signals.cxx":50
#6  0x1200019c8 in __start(...) in /usr/examples/x_signals
(idb) cont
Thread received signal ABRT
stopped at [<opaque> __kill(...) 0x3ff800e1578]

7.1.10 Special Signal Breakpoints

Signals are operating-system-defined events that can be handled by the debugger.

signal_command
        : catch_command
        | ignore_command

catch_command
        : catch [ signal_id ]

ignore_command
        : ignore [ signal_id ]

(idb) catch BUS

(idb) stop signal SIGBUS
[#1: stop signal SIGBUS ]

(idb) ignore BUS

(idb) catch
INT, QUIT, ILL, TRAP, ABRT, FPE, BUS, SEGV, SIGSYS, PIPE, TERM, URG, STOP, TTIN, TTOU, XCPU, XFSZ, PROF, USR1, USR2, VTALRM, RTMIN, RTMIN1, RTMIN2, RTMIN3, RTMIN4, RTMIN5, RTMIN6, RTMIN7, RTMAX, RTMAX7, RTMAX6, RTMAX5, RTMAX4, RTMAX3, RTMAX2, RTMAX1
(idb) ignore
HUP, KILL, ALRM, TSTP, CONT, CLD, WINCH, POLL

(idb) catch unaligned

(idb) ignore unaligned

7.1.11 Breakpoint Interactions with exec(), fork(), dlopen() and dlclose() System Calls

A process starts with a copy of its parent's memory as the result of a fork() system call; after running for a while within that memory, the process will often make an exec() system call to start a new executable file within that process.

The debugger keeps track of the exec() calls that occur so that it can keep track of various properties associated with each executable file. In particular, the breakpoint table is one of those properties. Thus, if you run or rerun your program, the same breakpoints can be re-established, even though a new process is initiated. Similarly, if you work with more than one process, each process has a distinct breakpoint table associated with it.

When a dlopen() system call occurs, the debugger reprocesses the current breakpoint table and automatically sets up the means to detect any events that apply to the newly loaded image.

When a dlclose() system call occurs, the debugger also reprocesses the breakpoint and de-activates any events that apply to the unloaded image.

7.2.1 Showing Breakpoint Status

Use the following commands to display the current breakpoint table:

show_all_breakpoints_command
        : status

show_all_breakpoints_command
        : info breakpoints [ expression ]
        | info watchpoints [ expression ]
        | info break       [ expression ]
        | info b           [ expression ]
        | i    breakpoints [ expression ]
        | i    watchpoints [ expression ]
        | i    break       [ expression ]
        | i    b           [ expression ]

Each entry in the current breakpoint table is displayed showing all of its properties. For example:

(idb) status
#1 PC==0x8049f48 in int main(void) "x_list.cxx":182 { stop }
#2 PC==0x8058026 in void List<Node>::append(struct Node* const) "x_list.cxx":148 { break }
#3 Access memory (write) 0xbffff0fc to 0xbffff0ff { stop }

(idb) info breakpoints
Num Type           Disp Enb Address    What
1   breakpoint     keep y   0x804a0a0  in main at x_list.cxx:182
2   breakpoint     keep y   0x804aa4a  in List<Node>::append(class List<Node> * const, class Node * const) at x_list.cxx:148
3   breakpoint     keep y   Access memory (changed) 0xbfffec9c  to 0xbfffec9f

When an entry in the current breakpoint table references a shared object that is not currently mapped, it's contribution to the What column indicates Not Currently Mapped.

When large or complex values are passed by value to the routine in the status line, the output can be voluminous. You can set the control variable $statusargs to 0 to suppress the output of argument type information in the status line.

7.2.2 Enabling, Disabling, and Deleting Breakpoints

When a breakpoint is defined, it is enabled by default. When the debugger starts or resumes process execution, it first adapts the process so that it can detect when the given events occur. A breakpoint can be disabled so it is not involved in determining when the process should next stop. A breakpoint that is no longer required can be deleted entirely.

disable_breakpoint_command
        : disable all
        | disable breakpoint_number_expression ,...

enable_breakpoint_command
        : enable all
        | enable breakpoint_number_expression ,...

delete_breakpoint_command
        : delete all
        | delete breakpoint_number_expression ,...

disable_breakpoint_command
        : disable [ breakpoints ] [ bpnums ]
        | dis     [ breakpoints ] [ bpnums ]

enable_breakpoint_command
        : enable [ breakpoints ] [ bpnums ]

delete_breakpoint_command
        : delete [ breakpoints ] [ bpnums ]
        | d      [ breakpoints ] [ bpnums ]

bpnums
        : bpnum ...

bpnum
        : integer

For example:

(idb) disable 1
(idb) status
#1 PC==0x8049f48 in int main(void) "x_list.cxx":182 { stop } Disabled
#2 PC==0x8058026 in void List<Node>::append(struct Node* const) "x_list.cxx":148 { break }
#3 Access memory (write) 0xbffff0fc to 0xbffff0ff { stop }
(idb) disable 10 - 8,1 + 1 + 1
(idb) status
#1 PC==0x8049f48 in int main(void) "x_list.cxx":182 { stop } Disabled
#2 PC==0x8058026 in void List<Node>::append(struct Node* const) "x_list.cxx":148 { break } Disabled
#3 Access memory (write) 0xbffff0fc to 0xbffff0ff { stop } Disabled
(idb) delete 1
(idb) status
#2 PC==0x8058026 in void List<Node>::append(struct Node* const) "x_list.cxx":148 { break } Disabled
#3 Access memory (write) 0xbffff0fc to 0xbffff0ff { stop } Disabled
(idb) enable all
(idb) status
#2 PC==0x8058026 in void List<Node>::append(struct Node* const) "x_list.cxx":148 { break }
#3 Access memory (write) 0xbffff0fc to 0xbffff0ff { stop }

(idb) disable 1
(idb) info breakpoints
Num Type           Disp Enb Address    What
1   breakpoint     keep n   0x804a0a0  in main at x_list.cxx:182
2   breakpoint     keep y   0x804aa4a  in List<Node>::append(class List<Node> * const, class Node * const) at x_list.cxx:148
3   breakpoint     keep y   Access memory (changed) 0xbfffec9c  to 0xbfffec9f
(idb) disable 2-3
(idb) info breakpoints
Num Type           Disp Enb Address    What
1   breakpoint     keep n   0x804a0a0  in main at x_list.cxx:182
2   breakpoint     keep n   0x804aa4a  in List<Node>::append(class List<Node> * const, class Node * const) at x_list.cxx:148
3   breakpoint     keep n   Access memory (changed) 0xbfffec9c  to 0xbfffec9f
(idb) delete 1
(idb) info breakpoints
Num Type           Disp Enb Address    What
2   breakpoint     keep n   0x804aa4a  in List<Node>::append(class List<Node> * const, class Node * const) at x_list.cxx:148
3   breakpoint     keep n   Access memory (changed) 0xbfffec9c  to 0xbfffec9f
(idb) enable
(idb) info breakpoints
Num Type           Disp Enb Address    What
2   breakpoint     keep y   0x804aa4a  in List<Node>::append(class List<Node> * const, class Node * const) at x_list.cxx:148
3   breakpoint     keep y   Access memory (changed) 0xbfffec9c  to 0xbfffec9f

8.1.1 How the Debugger Finds Source Files

The debugger searches for a source file (dir_name/base_name) using the following algorithm:

1. If dir_name is mapped to another source directory (mapped_dir_name), look for mapped_dir_name/base_name.
2. If Step 1 fails to find a readable file:
   Case 1: If dir_name is absolute, look for dir_name/base_name.
   Case 2: If dir_name is relative, for each entry use_dir in use_list, look for use_dir/dir_name/base_name. Note that the use_list entries are tried in the order they appear in the use_list.
3. If Step 2 fails, for each entry use_dir in use_list, look for use_dir/base_name. Just as in Step 2, the use_list entries are tried in the order they appear in the use_list.
4. If Step 3 fails, the debugger cannot find any source file.

The debugger uses the first-found readable file as the source file.

The debugger has source directory mapping commands that:

• Inform you in which directories the debugger is looking for the source files.
• Allow you to designate directories in which the debugger will look for the source files.

The following example shows how to use source directory mapping. Suppose you compile x_solarSystem as follows:

% pwd
/usr/users/debugger/sandbox/test/src/common/Examples
% ls -R
bin/ src/

./bin:
x_solarSystem*

./src:
solarSystemSrc/

./src/solarSystemSrc:
base_class_includes/    main/                   star.cxx
derived_class_includes/ orbit.cxx
heavenlyBody.cxx        planet.cxx

./src/solarSystemSrc/base_class_includes:
heavenlyBody.h  orbit.h

./src/solarSystemSrc/derived_class_includes:
planet.h  star.h

./src/solarSystemSrc/main:
solarSystem.cxx
% cd src
% cc -g -o ../bin/x_solarSystem \
  -IsolarSystemSrc/base_class_includes \
  -IsolarSystemSrc/derived_class_includes \
  main/solarSystem.cxx heavenlyBody.cxx orbit.cxx planet.cxx star.cxx

Then you move the directory solarSystemSrc elsewhere:

% mv solarSystemSrc movedSolarSystemSrc

Now debug x_solarSystem in /usr/users/debugger/sandbox/test/src/common/Examples/bin:

(idb) list $curline - 10: 20
Source file not found or not readable, tried...
    ./solarSystemSrc/main/solarSystem.cxx
    ../src/solarSystemSrc/main/solarSystem.cxx
    /usr/examples/solarSystemSrc/main/solarSystem.cxx
    ./solarSystem.cxx
    ../src/solarSystem.cxx
    /usr/examples/solarSystem.cxx

The debugger cannot find the file because it has been moved to another directory.

The following command displays a summary of the source directories in a.out. The ellipsis (...) here means that solarSystemSrc contains one or more source directories.

(idb) show source directory
.
solarSystemSrc
 ...

Information: You can further expand a '...' using the command

    show source directory <directory>
or
    show all source directory <directory>

where <directory> is the directory on the line above the '...'.
The first command displays only the children of <directory>, whereas
the second command displays all the descendants of <directory>.

The following command directs the debugger to look for source files originally in solarSystemSrc in movedSolarSystemSrc instead. This time, the debugger finds the source file.

(idb) map source directory solarSystemSrc ../src/movedSolarSystemSrc
(idb) list $curline - 10: 20
    104
    105     // Insert the new entry appropriately
    106     //
    107     if (iAmBiggerThan < biggestCount) {
    108         biggestMoons[iAmBiggerThan] = moon;
    109     }
    110 }
    111
    112 int main()
    113 {
>   114     unsigned int j = 1;    // for scoping examples
    115     for (unsigned int i = 0; i < biggestCount; i++)
    116         biggestMoons[i] = NULL;
    117
    118     Star *sun = new Star("Sol", G, 2);
    119     buildOurSolarSystem(sun);
    120     sun->printBodyAndItsSatellites(j);
    121     printBiggestMoons();
    122
    123     return 0;

The following command gives a complete list of source directories. As you can see, solarSystemSrc is mapped to movedSolarSystemSrc. As a side effect of mapping solarSystemSrc to movedSolarSystemSrc, the subdirectories in solarSystemSrc are mapped to their counterparts under movedSolarSystemSrc.

(idb) show all source directory
.
solarSystemSrc  *=>  ../src/movedSolarSystemSrc
 solarSystemSrc/base_class_includes  =>  ../src/movedSolarSystemSrc/base_class_includes
 solarSystemSrc/derived_class_includes  =>  ../src/movedSolarSystemSrc/derived_class_includes
 solarSystemSrc/main  =>  ../src/movedSolarSystemSrc/main

To summarize, the debugger provides the following four commands for checking and setting source directory mappings:

source_directory_mapping_command
        : show source directory [ directory_name ]
        | show all source directory [ directory_name ]
        | map source directory from_directory_name to_directory_name
        | unmap source directory  from_directory_name

Use the show source directory(dbx) command to display the directory mapping information of directory_name and its child directories (or immediate subdirectory). If directory_name is not specified, the mapping information of all the source directories whose parent is not a source directory is displayed.

The show all source directory(dbx) command is identical to the show source directory(dbx) command except that the mapping information of all the descendants of directory_name is displayed:

(idb) show source directory
.
solarSystemSrc  *=>  ../src/movedSolarSystemSrc
 ...
(idb) show all source directory
.
solarSystemSrc  *=>  ../src/movedSolarSystemSrc
 solarSystemSrc/base_class_includes  =>  ../src/movedSolarSystemSrc/base_class_includes
 solarSystemSrc/derived_class_includes  =>  ../src/movedSolarSystemSrc/derived_class_includes
 solarSystemSrc/main  =>  ../src/movedSolarSystemSrc/main

When you further expand ellipsis points (...) where directory is the directory on the line above the ellipsis points:

• The show source directory(dbx) command displays only the children of directory_name.
• The show all source directory(dbx) command displays all the descendants of directory_name.

Use the map source directory(dbx) command to tell the debugger that the source files in the directory from_directory_name can now be found in to_directory_name.

The unmap source directory(dbx) command maps from_directory_name back to itself; in other words, if from_directory_name has been mapped to some other directory, this command will restore its default mapping. For example:

(idb) show source directory
.
solarSystemSrc  *=>  ../src/movedSolarSystemSrc
 ...
(idb) show source directory solarSystemSrc
solarSystemSrc  *=>  ../src/movedSolarSystemSrc
 solarSystemSrc/base_class_includes  =>  ../src/movedSolarSystemSrc/base_class_includes
 solarSystemSrc/derived_class_includes  =>  ../src/movedSolarSystemSrc/derived_class_includes
 solarSystemSrc/main  =>  ../src/movedSolarSystemSrc/main

(idb) unmap source directory solarSystemSrc
(idb) show source directory solarSystemSrc
solarSystemSrc
 solarSystemSrc/base_class_includes
 solarSystemSrc/derived_class_includes
 solarSystemSrc/main

By default, the use_list is: (1) the current directory and (2) the directory containing the executable file. (dbx) Each process has its own use_list. You can also use the idb command -I option to specify search directories.

The following commands let you view and modify the use_list.

source_search_list_command
        : use_command
        | unuse_command

source_search_list_command
        : directory_command
        | show directories

Enter the use(dbx) without an argument or show directories(gdb) command to list the directories in which the debugger searches for source code files. Specify a directory argument to make source code files in that directory available to the debugger. You can also use the idb command -I option to specify search directories, which puts those directories in the use_list.

You can customize your debugger environment source code search paths by adding commands to your .dbxinit file that use the use command:

use_command
        : use [directory_name ...]

directory_command
        : directory [directory_name ...]

unuse_command
        : unuse [directory_name ...]
        | unuse *

8.1.2 How the Debugger Chooses Which Source File to List

The debugger has a concept of current source file, so you do not have to explicitly specify a source file in many commands. Whenever the process stops, the current source file is set to the source file for the code currently executing. The commands up, down, class(dbx), and file(dbx) also set the current source file.

select_source_file_command
        : file [ filename ]
        : fileexpr [ expression ]

(idb) run
[1] stopped at [int main(void):114 0x804c440]
    114     unsigned int j = 1;    // for scoping examples
(idb) file
solarSystemSrc/main/solarSystem.cxx
(idb) set $originalFile = "solarSystem.cxx"
(idb) list 24: 10
     24     Moon   *phobos    = new Moon("Phobos",       9,   11, mars);
     25     Moon   *deimos    = new Moon("Deimos",      23,    6, mars);
     26
     27     Planet *jupiter   = new Planet("Jupiter",     778330, sun);
     28     Moon   *io        = new Moon("Io",         422, 1815, jupiter);
     29     Moon   *europa    = new Moon("Europa",     671, 1569, jupiter);
     30     Moon   *ganymede  = new Moon("Ganymede",  1070, 2631, jupiter);
     31     Moon   *callisto  = new Moon("Callisto",  1883, 2400, jupiter);
     32     Moon   *amalthea  = new Moon("Amalthea",   181,   98, jupiter);
     33
(idb) file star.cxx
(idb) list 24: 10
     24 // Stars are simple objects
     25 //
     26 Star::Star(
     27     char*           name,
     28     StellarClass    classification,
     29     StellarSubclass subclassification)
     30         : HeavenlyBody(name),
     31           _classification(classification),
     32           _subclassification(subclassification)
     33 {
(idb) stop at 26
[#2: stop at "solarSystemSrc/star.cxx":26 ]
(idb) cont
[2] stopped at [Star::Star(char*, enum StellarClass, StellarSubclass):26 0x804d1f4]
     26 Star::Star(
(idb) file
solarSystemSrc/star.cxx
(idb) fileexpr $originalFile
(idb) file
solarSystemSrc/main/solarSystem.cxx
(idb) list 24: 10
     24     Moon   *phobos    = new Moon("Phobos",       9,   11, mars);
     25     Moon   *deimos    = new Moon("Deimos",      23,    6, mars);
     26
     27     Planet *jupiter   = new Planet("Jupiter",     778330, sun);
     28     Moon   *io        = new Moon("Io",         422, 1815, jupiter);
     29     Moon   *europa    = new Moon("Europa",     671, 1569, jupiter);
     30     Moon   *ganymede  = new Moon("Ganymede",  1070, 2631, jupiter);
     31     Moon   *callisto  = new Moon("Callisto",  1883, 2400, jupiter);
     32     Moon   *amalthea  = new Moon("Amalthea",   181,   98, jupiter);
     33

(idb) run
Starting program: /usr/examples/x_solarSystem

Breakpoint 1, main () at solarSystemSrc/main/solarSystem.cxx:114
114	    unsigned int j = 1;    // for scoping examples
(idb) info source
Current source file is solarSystemSrc/main/solarSystem.cxx
(idb)
(idb) list 24,+10
24	    Moon   *phobos    = new Moon("Phobos",       9,   11, mars);
25	    Moon   *deimos    = new Moon("Deimos",      23,    6, mars);
26
27	    Planet *jupiter   = new Planet("Jupiter",     778330, sun);
28	    Moon   *io        = new Moon("Io",         422, 1815, jupiter);
29	    Moon   *europa    = new Moon("Europa",     671, 1569, jupiter);
30	    Moon   *ganymede  = new Moon("Ganymede",  1070, 2631, jupiter);
31	    Moon   *callisto  = new Moon("Callisto",  1883, 2400, jupiter);
32	    Moon   *amalthea  = new Moon("Amalthea",   181,   98, jupiter);
33
34	    Planet *saturn    = new Planet("Saturn",     1426940, sun);
(idb) list star.cxx:26,+10
26	Star::Star(
27	    char*           name,
28	    StellarClass    classification,
29	    StellarSubclass subclassification)
30	        : HeavenlyBody(name),
31	          _classification(classification),
32	          _subclassification(subclassification)
33	{
34	}
35
36	void Star::print(unsigned int i) const
(idb) info source
Current source file is star.cxx
(idb) break 26
Breakpoint 2 at 0x805455c: file solarSystemSrc/star.cxx, line 26.
(idb) continue
Continuing.

Breakpoint 2, Star::Star (this=0x80d2c50, name=0x808e61c "Sol", classification=G, subclassification=2 '\002') at solarSystemSrc/star.cxx:26
26	Star::Star(
(idb) info source
Current source file is star.cxx
(idb) list solarSystem.cxx:24,+10
24	    Moon   *phobos    = new Moon("Phobos",       9,   11, mars);
25	    Moon   *deimos    = new Moon("Deimos",      23,    6, mars);
26
27	    Planet *jupiter   = new Planet("Jupiter",     778330, sun);
28	    Moon   *io        = new Moon("Io",         422, 1815, jupiter);
29	    Moon   *europa    = new Moon("Europa",     671, 1569, jupiter);
30	    Moon   *ganymede  = new Moon("Ganymede",  1070, 2631, jupiter);
31	    Moon   *callisto  = new Moon("Callisto",  1883, 2400, jupiter);
32	    Moon   *amalthea  = new Moon("Amalthea",   181,   98, jupiter);
33
34	    Planet *saturn    = new Planet("Saturn",     1426940, sun);
(idb) info source
Current source file is solarSystem.cxx

8.1.3 Listing Source Files

However, some primitive inspection capabilities are built into the debugger. The list command displays source lines, which can be defined by following way:

• The position of the program counter
• The last line listed, if multiple list commands are entered
• The line number specified as the arguments to the list command

list_source_file_command
        : list [ line_expression ]
        | list line_expression , line_expression
        | list line_expression : line_expression

line_expression
        : expression

list_source_file_command
        : list [ [+ | -] line_expression ] [ , [ [+ | -] line_expression ] ]
        | list function

For example, to list lines 16 through 20:

(idb) list 16, 20
     16
     17 class Node {
     18 public:
     19     Node ();
     20

(idb) list 16,20
16
17	class Node {
18	public:
19	    Node ();
20

For example, to list 6 lines, beginning with line 16:

(idb) list 16: 6
     16
     17 class Node {
     18 public:
     19     Node ();
     20
     21     virtual void printNodeData() const = 0;

(idb) list 16,+6
16
17	class Node {
18	public:
19	    Node ();
20
21	    virtual void printNodeData() const = 0;

8.1.4 Searching the Content of Source Files

The following search commands search through the current source file to help you find the lines to list:

search_source_file_command
        : / [ string ]
        | ? [ string ]

search_source_file_command
        : [forward-]search regular expression
        | reverse-search regular expression

When a match is found, the debugger lists the line number and the line. That line becomes the starting point for any further searches, or for a list command. For example:

1. To locate _firstNode:

   DBX Mode

   (idb) /_firstNode
        69     NODETYPE* _firstNode;
   

   GDB Mode

   (idb) forward-search _firstNode
   69	    NODETYPE* _firstNode;
   

2. Then to locate append before line 69:

   DBX Mode

   (idb) ?append
        65     void      append  (NODETYPE* const node);
   

   GDB Mode

   (idb) reverse-search append
   65	    void      append  (NODETYPE* const node);
   

3. Then to locate append after line 65:

   DBX Mode

   (idb) /append
       145 void List<NODETYPE>::append(NODETYPE* const node)
   

   GDB Mode

   (idb) forward-search append
   145	void List<NODETYPE>::append(NODETYPE* const node)
   

The debugger provides parameterized aliases and debugger variables of arbitrary types. You can use these to do list traversal (see the array navigation example).

8.2.1 Thread Levels

The debugger supports three levels of threads:

• decthreads (user spece threads), also known as POSIX threads on Tru64
• pthreads (kernel threads), also known as POSIX threads in Linux
• Kernel threads (operating system level threads), also known as native threads

To specify the thread level, set the $threadlevel debugger variable to one of the following strings:

• decthreads — for POSIX thread library debugging on Tru64
• pthreads — for POSIX thread library debugging on Intel® platforms in Linux
• native — for kernel thread debugging.

For example:

(idb) set $threadlevel = "decthreads"

For core file debugging, the $threadlevel is always set to "native".

8.2.2 Thread Manipulation Commands

You can use a variety of commands to manipulate the threads:

thread_command
        : show_thread_command
        | switch_thread_command
        | show_condition_variable_command
        | show_mutex_variable_command
        | pthread_command

thread_commands
        : info_thread_command
        | thread_command

8.2.3 Thread Display Commands

You can use the following commands to display threads:

show_thread_command
        : show thread [ thread_id_list ] [ thread-state-filter ]

thread_id_list
        : thread_id ,...
        | *

thread_id
        : expression

thread_state_filter
        : with state eq thread_state

eq
        : ==               (for C, and C++)
        | .eq.             (for Fortran)

thread_state
        : ready
        | running
        | terminated
        | blocked

(idb) print $threadlevel
"decthreads"
(idb) show thread
  Thread Name                      State           Substate    Policy       Pri
  ------ ------------------------- --------------- ----------- ------------ ---
*      1 default thread            running VP 3                SCHED_OTHER  19
      -1 manager thread            blk SCS                     SCHED_RR     19
      -2 null thread for slot 0    running VP 1                null thread  -1
      -3 null thread for slot 1    ready VP 3                  null thread  -1
      -4 null thread for slot 2    new             new         null thread  -1
      -5 null thread for slot 3    new             new         null thread  -1
>      2 threads(0x140000798)      blocked         cond 3      SCHED_OTHER  19
       3 threads+8(0x1400007a0)    blocked         cond 3      SCHED_OTHER  19
       4 threads+16(0x1400007a8)   blocked         cond 3      SCHED_OTHER  19
       5 threads+24(0x1400007b0)   blocked         cond 3      SCHED_OTHER  19
       6 threads+32(0x1400007b8)   blocked         cond 3      SCHED_OTHER  19
(idb) set $threadlevel = "native"
(idb) print $threadlevel
"native"
(idb) show thread
   Id                  State
*  0x9                 stopped
*  0x9                 unstarted
   0x3                 unstarted
   0x7                 unstarted

info_threads_command
        : info threads

thread
        : expression

(idb) info threads
  0 Thread 1024 (LWP 19513)  0x804f8f6 in __sigsuspend from /tmp/pthread_manythreads
  1 Thread 2049 (LWP 19514)  0x805a42a in __clone from /tmp/pthread_manythreads
* 2 Thread 1026 (LWP 19515)  0x804f8f6 in __sigsuspend from /tmp/pthread_manythreads
  3 Thread 2051 (LWP 19516)  0x804f8f6 in __sigsuspend from /tmp/pthread_manythreads
  4 Thread 3076 (LWP 19517)  0x804f8f6 in __sigsuspend from /tmp/pthread_manythreads
  5 Thread 4101 (LWP 19518)  0x8048288 in prime_search at pthread_manythreads.c:79

You can switch to a different thread as the current thread. The debugger variable $curthread contains the thread identifier of the current thread.

switch_thread_command
          : thread [ thread_id ]

The $curthread value is updated when program execution stops or completes. You can modify the current thread by assigning $curthread a valid thread identifier. This is equivalent to issuing the thread thread_id command. When there is no process or program, $curthread is set to 0.

Use the thread command without a thread identifier to identify the current thread. Supply a thread identifier to make another thread the current thread.

(idb) thread 2
* 2 Thread 1026 (LWP 19515)  0x804f8f6 in __sigsuspend from /tmp/pthread_manythreads

8.2.4 Mutex Queries

A mutex (mutual exclusion) semaphore is a programming flag that allows multiple pthreads to synchronize access to shared resources, to ensure the following:

• All threads see a clean and consistent view of the data, without allowing one thread to change something while another thread is reading it.
• Two threads do not change different parts of the data at the same time, possibly in inconsistent ways.

Use the show mutex command to list information about currently available pthread mutexes:

show_mutex_variable_command
        : show mutex [ mutex_id_list ] [ mutex_state_filter ]

mutex_id_list
        : mutex_id  ,...
        | (mutex_id ,...)

mutex_state_filter
        : with state eq mutex_state

eq
        : ==               (for C, and C++)
        | .eq.             (for Fortran)

mutex_state
        : locked

If you specify one or more mutex identifiers, the debugger displays information about only those mutexes specified, provided that the list matches the identifiers of currently available mutexes. If you omit the mutex identifier specification, the debugger displays information about all mutexes currently available.

Use the show mutex with state == locked command to display information exclusively for locked mutexes.

If $verbose is set to 1, the sequence numbers of the threads locking the mutexes are displayed.

The following example shows the output from a simple show mutex command:

(idb) show mutex
Mutex  Name                      State Owner  Pri Type     Waiters (+Count)
------ ------------------------- ----- ------ --- -------- --------------------
     1 malloc heap                                Normal
     2 malloc hash                                Normal
     3 malloc cache[0]                            Normal
     4 malloc cache[1]                            Normal
     5 malloc cache[2]                            Normal
     6 malloc cache[3]                            Normal
     7 malloc cache[4]                            Normal
     8 malloc cache[5]                            Normal
     9 malloc cache[6]                            Normal
    10 malloc cache[7]                            Normal
    11 malloc cache[8]                            Normal
    12 malloc cache[9]                            Normal
    13 malloc cache[10]                           Normal
    14 malloc cache[11]                           Normal
    15 malloc cache[12]                           Normal
    16 malloc cache[13]                           Normal
    17 malloc cache[14]                           Normal
    18 malloc cache[15]                           Normal
    19 malloc cache[16]                           Normal
    20 malloc cache[17]                           Normal
    21 malloc cache[18]                           Normal
    22 malloc cache[19]                           Normal
    23 malloc cache[20]                           Normal
    24 malloc cache[21]                           Normal
    25 malloc cache[22]                           Normal
    26 malloc cache[23]                           Normal
    27 malloc cache[24]                           Normal
    28 malloc cache[25]                           Normal
    29 malloc cache[26]                           Normal
    30 malloc cache[27]                           Normal
    31 malloc cache[28]                           Normal
    32 brk                                        Normal
    33 exc cr                                     Recurs
    34 exc read rwl                               Normal
    35 known mutex queue                          Normal
    36 known cond queue                           Normal
    37 known VP queue                             Normal
    38 known rwl queue                            Normal
    39 VM 0 lookaside                             Normal
    40 VM 1 lookaside                             Normal
    41 VM 2 lookaside                             Normal
    42 VM 0 cache                                 Normal
    43 VM 1 cache                                 Normal
    44 VM 2 cache                                 Normal
    45 debugger client registry                   Normal
    46 Global lock                                Recurs
    47 ldr                                        Recurs
    48 prime_list(0x140000660)                    Normal
    49 cond_mutex(0x1400006c0)                    Normal
    50 current_mutex(0x140000690                  Normal
    51 curr_worker_mutex(0x14000 Lock             Normal

If the application being debugged has no pthreads, or if the $threadlevel is set to native, an appropriate message is issued.

8.2.5 Condition Variable Queries

A condition variable is a pthread synchronization object used in conjunction with a mutex. A condition variable is used when a thread has locked a mutex to gain access to data and then finds it must wait for some other thread to change some aspect of the data before it can continue.

show_condition_variable_command
        : show condition [ condition_id_list ] [ condition_state_filter ]

condition_id_list
        : condition_id ,...
        | (condition_id ,...)

condition_id
        : integer_constant

condition_state_filter
        : with state eq condition_state

condition_state
        : wait

Use the show condition command to list information about currently available condition variables. If you supply one or more condition identifiers, the debugger displays information about the condition variables you specify, provided that the list matches the identities of currently available condition variables. If you omit the condition variable specification, the debugger displays information about all the condition variables currently available.

Use the show condition with state == wait command to display information only for condition variables that have one or more threads waiting. If $verbose is set to 1, the sequence numbers of the threads waiting on the condition are displayed.

The following example shows output from a simple show condition command:

(idb) show condition
Cond   Name                      Mutex  Type  Waiters (+Count)
------ ------------------------- ------ ----- ---------------------------------
     1 _exc_read_mutex+72(0x3ffc
     2 _exc_read_mutex+112(0x3ff
     3 cond_var(0x140000720)         49       2, 3, 4, 5, 6
     4 curr_worker(0x140000748)

If the application being debugged has no pthreads, or if the $threadlevel is set to native, an appropriate message is issued.

8.2.6 Other Thread Commmands

You can use the where command to display the stack trace of current threads. You can specify one or more threads or all threads.

The print command evaluates an optional expression in the context of the current thread and displays the result.

The call command evalutes an expression in the context of the current thread and makes the call in the context of the current thread.

The printregs command prints the registers for the current thread.

8.2.7 Undocumented pthread Support

You can pass an undocumented string directly into the undocumented pthread debugging support. This is an internal debugging aid, not intended for general use.

pthread_command
        : pthread string

8.3.1 Navigating the Call Stack

You can select one of the call frames as the starting point for examining variables. This call frame provides the current scope in the program for which variables exist, and tells the debugger which instance of those variables whose values you want to see.

change_stack_frame_command
        : up   [ expression ]
        | down [ expression ]
        | func [ loc ]

change_stack_frame_command
        : up            [ expression ]
        | up-silently   [ expression ]
        | down          [ expression ]
        | down-silently [ expression ]
        | frame         [ expression ]

Use the up command or the down command without the expression to change to the call frame located one level up or down the stack. Specify an expression that evaluates to an integer to change the call frame up or down the specified number of levels. If the number of levels exceeds the number of active calls on the stack in the specified direction, the debugger issues a warning message and the call frame does not change.

When the current call frame changes, the debugger displays the source line corresponding to the last instruction executed in the function executing the selected call frame.

In the following example, the current call frame is changed to one for method Planet::print so that a variable in that instance of print() can be displayed:

(idb) where 4
#0  0x804cd72 in ((Planet*)0x80e6008)->Planet::print(i=2) "solarSystemSrc/planet.cxx":19
#1  0x804c772 in ((HeavenlyBody*)0x80e6008)->HeavenlyBody::printBodyAndItsSatellites(i=2) "solarSystemSrc/heavenlyBody.cxx":62
>2  0x804c7a7 in ((HeavenlyBody*)0x80e5fb0)->HeavenlyBody::printBodyAndItsSatellites(i=1) "solarSystemSrc/heavenlyBody.cxx":68
#3  0x804c50a in main() "solarSystemSrc/main/solarSystem.cxx":120
(idb) list $curline - 5: 10
     63
     64     // Recursively deal with the satellites.  Redeclare i for scoping examples.
     65     //
     66     unsigned int j = 1;
     67     for (HeavenlyBody* i = _firstSatellite; i; i = i->_outerNeighbor) {
>    68     	i->printBodyAndItsSatellites(j++);
     69     }
     70 }
(idb) whatis i
struct HeavenlyBody* i
(idb) print i
0x80e6008
(idb) func Planet::print
virtual void Planet::print(unsigned int) in solarSystemSrc/planet.cxx line No. 19:
     19     std::cout << "(" << i
(idb) where 4
>0  0x804cd72 in ((Planet*)0x80e6008)->Planet::print(i=2) "solarSystemSrc/planet.cxx":19
#1  0x804c772 in ((HeavenlyBody*)0x80e6008)->HeavenlyBody::printBodyAndItsSatellites(i=2) "solarSystemSrc/heavenlyBody.cxx":62
#2  0x804c7a7 in ((HeavenlyBody*)0x80e5fb0)->HeavenlyBody::printBodyAndItsSatellites(i=1) "solarSystemSrc/heavenlyBody.cxx":68
#3  0x804c50a in main() "solarSystemSrc/main/solarSystem.cxx":120
(idb) list $curline - 5: 10
     14 {
     15 }
     16
     17 void Planet::print(unsigned int i) const
     18 {
>    19     std::cout << "(" << i
     20          << ") Planet [" << HeavenlyBody::name() << "]; ";
     21     printOrbitalParameters();
     22     std::cout << std::endl;
     23 }
(idb) whatis i
unsigned int i
(idb) print i
2

8.3.2 The pop Command

The pop command removes one or more call frames from the call stack:

pop_stack_frame_command
        : pop [ expression ]

pop_stack_frame_command
        : return [ expression ]

8.3.3 Call Frames and Optimized Code

When optimized machine code is generated by the compilers, the compiler generates code that maintains the call stack, but sometimes the function boundaries are changed in one of two ways:

• Inlining is when the compiler completely eliminates the call by instead generating the instructions for the called function at the call site, usually followed by merging those instructions with the other instructions surrounding the call site.
• Outlining is when the compiler creates a function where one did not exist explicitly in the source. For example, the compiler turns a loop body into a function, so that it can generate code that uses threads to execute the different iterations in parallel; or the compiler creates a single shared function to replace several sections of the source that are similar.

Depending on the information the compiler makes available to the debugger, inlined calls may or may not show up in the call stack display. Outlined calls will show up, and will be correlated to the code they came from. The compiler will probably have supplied the debugger with some invented name for the function.

8.3.4 Call Frames and Machine Code Correlation

On a RISC processor the following is the machine code typically generated for a call to a function:

• The machine code before the call performs the following operations:
  • Sets some context registers
  • Puts the parameters either in registers or memory
  • Loads the address of the function into a register
  • Loads the address to return to into a register
  • Branches to the function
• The machine code at the start of the called function performs the following operations:
  • Sets some context registers
  • Allocates stack space
  • Saves some registers in the stack space
  • Performs some setup of the local variables
• The machine code at the end of the called function performs the following operations:
  • Restores the saved registers from the stack space
  • Deallocates the stack space
  • Branches to the address to return to
• The machine code at the return address of the call frame sets some context registers.

When the thread is partway through the call frame creation or tear-down, the debugger will still show the call frame, but will not be able to show correct values for the variables or parameters.

8.3.5 Special C++ Issues

For nonstatic member functions, the implicit this pointer is displayed as the address on the stack trace along with the class type of the object, as shown in the following example:

(idb) stop in List<Node>::print
[#3: stop in void List<Node>::print(void) ]
(idb) cont
[3] stopped at [void List<Node>::print(void):162 0x804aad2]
    162     Node* currentNode = _firstNode;
(idb) where 2
>0  0x804aad2 in ((List<Node>*)0xbfffecfc)->List<Node>::print() "x_list.cxx":162
#1  0x804a53a in main() "x_list.cxx":203

() break List<Node>::print
Breakpoint 3 at 0x804aad2: file x_list.cxx, line 162.
(idb) continue
Continuing.

Breakpoint 3, List<Node>::print (this=0xbfffecec) at x_list.cxx:162
162	    Node* currentNode = _firstNode;
(idb) backtrace 2
>0  0x804aad2   in ((List<Node>*)(const class List<Node> *) 0xbfffecec)->List<Node>::print(this=(const class List<Node> *) 0xbfffecec) "x_list.cxx":162
#1  0x804a53a   in main() "x_list.cxx":203

8.4.1 The print Command

You can print the values of one or more expressions or all local variables. You can also use the print command to evaluate complex expressions involving typecasts, pointer dereferences, multiple variables, constants, and any legal operators allowed by the language of the program you are debugging:

print_command
        : print [ expression ,... ]
        | print rescoped_expression
        | print printable-type
        | printb [ expression ,... ]
        | printd [ expression ,... ]
        | printo [ expression ,... ]
        | printx [ expression ,... ]

rescoped_expression
        : filename ` qual_symbol
        | ` qual_symbol

qual_symbol
        : expression
        | qual_symbol ` expression

print_command
        : print [/format specifier][expression]

format specifier
        : x | d | u | o | t | a | c | f

For an array, the debugger prints every cell in the array if you do not specify a specific cell.

Consider the following declarations in a C++ program:

(idb) list 59: 2
     59 const unsigned int biggestCount = 10;
     60 static Moon *biggestMoons[biggestCount];

(idb) list 59,+2
59	const unsigned int biggestCount = 10;
60	static Moon *biggestMoons[biggestCount];

The following example uses the print command to display a nonstring array:

(idb) print biggestMoons
[0] = 0x80cf928,[1] = 0x80cfc88,[2] = 0x80cf988,[3] = 0x80cf868,[4] = 0x80cf688,[5] = 0x80cf8c8,[6] = 0x80d0048,[7] = 0x80cff28,[8] = 0x80cfc28,[9] = 0x80cff88

(idb) print biggestMoons
$4 = {(class Moon *) 0x80d2708, (class Moon *) 0x80d2a68, (class Moon *) 0x80d2768, (class Moon *) 0x80d2648, (class Moon *) 0x80d2468, (class Moon *) 0x80d26a8, (class Moon *) 0x80d2e28, (class Moon *) 0x80d2d08, (class Moon *) 0x80d2a08, (class Moon *) 0x80d2d68}

The following example shows how to print individual values of an array:

(idb) print biggestMoons[3]
0x80cf868
(idb) print *biggestMoons[3]
struct Moon {
  _radius = 1815;
  _name = 0x808e47c="Io";         // class Planet::HeavenlyBody
  _innerNeighbor = 0x0;           // class Planet::HeavenlyBody
  _outerNeighbor = 0x80cf8c8;     // class Planet::HeavenlyBody
  _firstSatellite = 0x0;          // class Planet::HeavenlyBody
  _lastSatellite = 0x0;           // class Planet::HeavenlyBody
  _primary = 0x80cf808;           // class Planet::Orbit
  _distance = 422;                // class Planet::Orbit
  _name = 0x80cf900="Jupiter 1";  // class Planet::Orbit
}

(idb) print biggestMoons[3]
$7 = (class Moon *) 0x80d2648
(idb) print *biggestMoons[3]
$8 = {<Planet> = {<HeavenlyBody> = {_name = 0x808e17c "Io", _innerNeighbor = 0x0, _outerNeighbor = 0x80d26a8, _firstSatellite = 0x0, _lastSatellite = 0x0}, <Orbit> = {_primary = 0x80d25e8, _distance = 422, _name = 0x80d26e0 "Jupiter 1"}, }, _radius = 1815}

(idb) whatis newNode
class IntNode* newNode
(idb) print newNode
0x80b9740
(idb) print *newNode
class IntNode {
  _data = 1;
  _nextNode = 0x0;                // class Node
}

(idb) p $floatshrinking
1
(idb) p 1.1
1.1
(idb) set $floatshrinking = 0
(idb) p 1.1
1.10000000000000000000000000000000008

8.4.2 The printf Command

Use the printf command to format and display a complex structure. The first argument is a string expression of characters and conversion specifications using the same format specifiers as the printf C function. The printf command requires a running target program because it uses libc.

printf_command
        : printf [ format_string [ , expression  ,... ] ]

For example:

(idb) printf "The PC is 0x%x", $pc
The PC is 0x804a53a

8.4.3 The printi Command

The printi command takes one or more numerical expressions and interprets each one as an assembly instruction, printing out the instruction, and its arguments when applicable. This command is typically used by engineers performing machine-level debugging.

printi_command
	: printi [ expression  ,... ]

For example:

(idb) $curpc/1i
CompoundNode::CompoundNode(float, int): x_list.cxx
 [line 103, 0x804a60e]	_ZN12CompoundNodeC1Efi(...)+0x18:         addl     $-8, %esp
(idb) $curpc/1dd
0x804a60e:  -1946631037
(idb) printi $pc
_ZN12CompoundNodeC1Efi(...)+0x32:         hlt

8.4.4 The printregs Command

Use the printregs command to display the values of all the hardware registers. The list of registers displayed by the debugger is machine-dependent. By default, most values are displayed in decimal radix. To display the register values in hexadecimal radix, set the $hexints variable to 1.

print_registers_command
        : printregs

For example:

(idb) printregs
$eax           0x80b0c14	134941716
$ecx           0x40018000	1073840128
$edx           0x0	0
$ebx           0x401ae9e4	1075505636
$esp [$sp]     0xbffff58c	-1073744500
$ebp           0xbffff668	-1073744280
$esi           0x40016b64	1073834852
$edi           0xbffff6dc	-1073744164
$eip [$pc]     0x804a3e2	134521826
$eflags        0x286	646
$cs            0x23	35
$ss            0x2b	43
$ds            0x2b	43
$es            0x2b	43
$fs            0x0	0
$gs            0x0	0
$orig_eax      0xffffffff	-1
$fctrl         0x37f	895
$fstat         0x0	0
$ftag          0x0	0
$fiseg         0x23	35
$fioff         0x805badf	134593247
$foseg         0x2b	43
$fooff         0xbffff368	-1073745048
$fop           0x1bd	445
$f0            0x000000000000ffff0000000000000000 -inf
$f1            0x000000000000ffff0000000000000000 -inf
$f2            0x000000000000ffff0000000000000000 -inf
$f3            0x000000000000ffff0000000000000000 -inf
$f4            0x000000000000ffff0000000000000000 -inf
$f5            0x000000000000ffff0000000000000000 -inf
$f6            0x000000000000ffff0000000000000000 -inf
$f7            0x0000000000004002a1f7cf0000000000 10.123
$xmm0          0x00000000000000000000000000000000
$xmm1          0x00000000000000000000000000000000
$xmm2          0x00000000000000000000000000000000
$xmm3          0x00000000000000000000000000000000
$xmm4          0x00000000000000000000000000000000
$xmm5          0x00000000000000000000000000000000
$xmm6          0x00000000000000000000000000000000
$xmm7          0x00000000000000000000000000000000
$mxcsr         0x1f80	8064
$vfp           0xbffff668	0xbffff668

8.4.5 The printt Command

The printt command takes one or more numerical expressions and interprets each one as the number of seconds since the Epoch (00:00:00 UTC 1 Jan 1970; see ctime(3) for more information).

printt_command
        : printt [ expression  ,... ]

For example:

(idb) printt 0
(UTC) Thu Jan  1 00:00:00 1970
(idb) printt 978325200
(UTC) Mon Jan  1 05:00:00 2001

8.4.6 The dump Command

Use the dump command without an argument to list the parameters and local variables in the current function. To list the parameters and local variables in an active function, specify it as an argument.

Use the dump . command (include the dot) to list the parameters and local variables for all functions active on the stack:

dump_command
        : dump qual_symbol
        | dump .

For example:

(idb) dump
>0  0x804a53a in main() "x_list.cxx":203
cNode=0x80b9750
cNode1=0x80b9768
cNode2=0x80b97a0
newNode=0x80b9740
newNode2=0x80b9790
nodeList=class List<Node> { ... }

When large and complex values are passed by value to a routine on the stack, the output of the dump command can be voluminous. You can set the control variable $stackargs to 0 to suppress the output of argument values in the dump command.

8.4.7 The call Command

After a breakpoint or a signal suspends program execution, you can execute a single function in your program by using the call command, or by including a function call in the expression argument of a debugger command. Calling a function lets you test the function's operation with a specific set of parameters.

call_command
        : call call-expression

Specify the function as if you were calling it from within the program. If the function has no parameters, specify empty parentheses (()). For multithreaded applications, the call is made in the context of the current thread. For C++ applications, when you set the $overloadmenu debugger variable to 1 and call an overloaded function, the debugger lists the overloaded functions and calls the function you specify. When the function you call completes normally, the debugger restores the stack and the current context that existed before the function was called.

While the program counter is saved and restored, calling a function does not shield the program state from alteration if the function you call allocates memory or alters global variables. If the function affects global program variables, for instance, those variables will be changed permanently.

Functions compiled without the debugger option to include debugging information may lack important parameter information and are less likely to yield consistent results when called.

The call command executes the specified function with the parameters you supply and then returns control to you (at the debugger prompt) when the function returns. The call command discards the return value of the function. If you embed the function call in the expression argument of a print command, the debugger prints the return value after the function returns. The following example shows both methods of calling a function:

(idb) call earth->distance()
(idb) print earth->distance()
149600

In the previous example, the call command results in the return value being discarded while the embedded call passes the return value of the function to the print command, which in turn prints the value. You can also embed the call within a more involved expression, as shown in the following example:

(idb) print earth->distance() - 100000
49600
(idb) print mars->distance() - earth->distance()
78340
(idb) call io->print(3)
(3) Moon [Io], radius [1815] km; <Jupiter 1> orbits at 422 Megameters

All breakpoints or tracepoints defined and enabled during the session are active when a called function is executing. When program execution halts during function execution, you can examine program information, execute one line or instruction, continue execution of the function, or call another function.

When you call a function when execution is suspended in a called function, you are nesting function calls, as shown in the following example:

(idb) where 2
>0  0x804bb6b in buildOurSolarSystem(sun=0x80cf4d0) "solarSystemSrc/main/solarSystem.cxx":55
#1  0x804c4f2 in main() "solarSystemSrc/main/solarSystem.cxx":119
(idb) stop in Planet::print
[#2: stop in virtual void Planet::print(unsigned int) ]
(idb) call mars->print(1)
[2] stopped at [virtual void Planet::print(unsigned int):19 0x804cd72]
     19     std::cout << "(" << i
(idb) where
>0  0x804cd72 in ((Planet*)0x80cf6e8)->Planet::print(i=1) "solarSystemSrc/planet.cxx":19
#1  0x4004b1a4 in __do_global_ctors_aux(...) in /lib/i686/libm.so.6
#2  0x80cf6e8
(idb) next
stopped at [virtual void Planet::print(unsigned int):20 0x804cdc6]
     20          << ") Planet [" << HeavenlyBody::name() << "]; ";
(idb) stop in Orbit::distance
[#3: stop in Megameters Orbit::distance(void) ]
(idb) print distance()
[3] stopped at [Megameters Orbit::distance(void):41 0x804cac7]
     41     return _distance;
(idb) where
>0  0x804cac7 in ((Orbit*)0x80cf700)->Orbit::distance() "solarSystemSrc/orbit.cxx":41
#1  0x4004b1a4 in __do_global_ctors_aux(...) in /lib/i686/libm.so.6
#2  0x80cf700
(idb) disable 3
(idb) cont
Called Procedure Returned
stopped at [virtual void Planet::print(unsigned int):20 0x804cdc6]
     20          << ") Planet [" << HeavenlyBody::name() << "]; ";
(idb) where
>0  0x804cdc6 in ((Planet*)0x80cf6e8)->Planet::print(i=1) "solarSystemSrc/planet.cxx":20
#1  0x4004b1a4 in __do_global_ctors_aux(...) in /lib/i686/libm.so.6
#2  0x80cf6e8
(idb) cont
(1) Planet [Mars]; <Sol 4> orbits at 227940 Megameters
Called Procedure Returned
stopped at [void buildOurSolarSystem(struct Star*):55 0x804bb6b]
     55     Planet *pluto     = new Planet("Pluto",      5913520, sun);

8.4.8 The whatis Command

You can print information about the basic nature of a whatis_expression. The expression can be a normal language expression or the name of a type, function, or other language entity. The debugger shows you information about the entity rather than evaluating it. However, it will evaluate any contained expressions, such as pointers, needed to determine the entity to which you are referring.

whatis_command
        : whatis whatis_expression

The following example uses the whatis command to determine the storage representation for the data member _classification:

(idb) whatis sun->_classification
const enum StellarClass Star::_classification
(idb) whatis StellarClass
enum StellarClass {O, B, A, F, G, K, M, R, N, S}
(idb) print sun->_classification
G

8.4.9 The whereis Command

The whereis command lists all declarations of a variable and each declaration's fully qualified scope information.

The scope information of a variable usually consists of the name of the source file that contains the function in which the variable is declared, the name of that function, and the name of the variable. The components of the scope information are separated by back-quotes (`).

whereis_command
        : whereis whereis_name
        | whereis whereis_string

whereis_name
        : identifier_or_typedef_name
        | ( identifier_or_typedef_name )

whereis_string
	: string

You can use the whereis command with the whereis_name to obtain information needed to differentiate overloaded identifiers that are in different units, or within different routines in the same unit. The following example shows how to set breakpoints in two C++ methods, both named print:

(idb) whereis print
"solarSystemSrc/derived_class_includes/planet.h"`Planet::print(unsigned int)
"solarSystemSrc/derived_class_includes/planet.h"`Moon::print(unsigned int)
"solarSystemSrc/base_class_includes/heavenlyBody.h"`HeavenlyBody::print(unsigned int)
"solarSystemSrc/derived_class_includes/star.h"`Star::print(unsigned int)
(idb) stop in "solarSystemSrc/derived_class_includes/planet.h"`Planet::print
Select from
----------------------------------------------------
     1 planet.h containing Moon
     2 planet.h containing Moon
     3 planet.h containing __dt__6PlanetXv
     4 None of the above
----------------------------------------------------
1
[#2: stop in virtual void Planet::print(unsigned int) ]
(idb) stop in "solarSystemSrc/derived_class_includes/star.h"`Star::print
Select from
----------------------------------------------------
     1 star.h containing O
     2 star.h containing O
     3 None of the above
----------------------------------------------------
1
[#3: stop in virtual void Star::print(unsigned int) ]

See also the which command for another example of the whereis command.

If you are not sure how to spell a symbol, you can use the whereis command with the whereis_string to search the symbol table for the regular expression represented by the quoted string. All symbols that match the rules of the regular expression are displayed in ascending order. For example:

(idb) whereis planet
Symbol not found
(idb) whereis "[Pp]lanet"
"solarSystemSrc/derived_class_includes/planet.h"`Moon::Moon(char*, Megameters, Kilometers, class Planet*)
"solarSystemSrc/derived_class_includes/planet.h"`Planet
"solarSystemSrc/derived_class_includes/planet.h"`Planet
"solarSystemSrc/derived_class_includes/planet.h"`Planet
"solarSystemSrc/derived_class_includes/planet.h"`Planet::Planet(char*, Megameters, class HeavenlyBody*)
"solarSystemSrc/derived_class_includes/planet.h"`Planet::Planet(char*, Megameters, class HeavenlyBody*)
"solarSystemSrc/derived_class_includes/planet.h"`Planet::print(unsigned int)
"solarSystemSrc/derived_class_includes/planet.h"`__INTER__Moon_Moon_Orbit_Planet_Xv
"solarSystemSrc/derived_class_includes/planet.h"`__INTER__Planet_Planet_Orbit_Xv
"solarSystemSrc/derived_class_includes/planet.h"`__dt__6PlanetXv
__T_6Planet
__cxxexsig6Planet
__vtbl_5Orbit6Planet
__vtbl_5Orbit6Planet4Moon
__vtbl_6Planet
solarSystemSrc/derived_class_includes/planet.h
solarSystemSrc/derived_class_includes/planet.h
solarSystemSrc/derived_class_includes/planet.h
solarSystemSrc/planet.cxx
(idb) whereis "^Planet$"
"solarSystemSrc/derived_class_includes/planet.h"`Planet
"solarSystemSrc/derived_class_includes/planet.h"`Planet
"solarSystemSrc/derived_class_includes/planet.h"`Planet
"solarSystemSrc/derived_class_includes/planet.h"`Planet::Planet(char*, Megameters, class HeavenlyBody*)
(idb) whereis Planet
"solarSystemSrc/derived_class_includes/planet.h"`Planet
"solarSystemSrc/derived_class_includes/planet.h"`Planet
"solarSystemSrc/derived_class_includes/planet.h"`Planet
"solarSystemSrc/derived_class_includes/planet.h"`Planet::Planet(char*, Megameters, class HeavenlyBody*)
(idb) which Planet
"solarSystemSrc/derived_class_includes/planet.h"`Planet
(idb) whatis Planet
class Planet : HeavenlyBody, Orbit {
  Planet(char*, Megameters, class HeavenlyBody*);
  virtual void print(unsigned int);
}

You can use the $symbolsearchlimit debugger variable to specify the maximum number of symbols that will be returned by the whereis command for a regular expression search. The default value for the $symbolsearchlimit variable is 100; a value of 0 indicates no limit.

8.4.10 The which Command

Use the which command to determine which declaration an identifier resolves to. The which command shows the fully qualified scope information for the instance of the specified expression visible from the current scope.

The scope information of a variable usually consists of the name of the source file that contains the function in which the variable is declared, the name of that function, and the name of the variable. The components of the scope information are separated by back-quotes (`).

which_command
        : which which_name

which_name
        : identifier_or_typedef_name
        | ( identifier_or_typedef_name )

The following example shows how to use the whereis and which commands to determine a variable's scope:

(idb) where 4
>0  0x804cd72 in ((Planet*)0x80e6008)->Planet::print(i=2) "solarSystemSrc/planet.cxx":19
#1  0x804c772 in ((HeavenlyBody*)0x80e6008)->HeavenlyBody::printBodyAndItsSatellites(i=2) "solarSystemSrc/heavenlyBody.cxx":62
#2  0x804c7a7 in ((HeavenlyBody*)0x80e5fb0)->HeavenlyBody::printBodyAndItsSatellites(i=1) "solarSystemSrc/heavenlyBody.cxx":68
#3  0x804c50a in main() "solarSystemSrc/main/solarSystem.cxx":120
(idb) which i
"solarSystemSrc/planet.cxx"`Planet::print(unsigned int)`i
(idb) assign i = 10
(idb) print i
10
(idb) whereis i
"solarSystemSrc/heavenlyBody.cxx"`HeavenlyBody::printBodyAndItsSatellites(unsigned int)`i
"solarSystemSrc/heavenlyBody.cxx"`HeavenlyBody::printBodyAndItsSatellites(unsigned int)`i
"solarSystemSrc/heavenlyBody.cxx"`HeavenlyBody::satelliteNumber(struct HeavenlyBody*)`i
"solarSystemSrc/main/solarSystem.cxx"`main`i
"solarSystemSrc/main/solarSystem.cxx"`printBiggestMoons`i
"solarSystemSrc/main/solarSystem.cxx"`trackBiggestMoons(struct Moon*)`i
"solarSystemSrc/planet.cxx"`Moon::print(unsigned int)`i
"solarSystemSrc/planet.cxx"`Planet::print(unsigned int)`i
"solarSystemSrc/star.cxx"`Star::print(unsigned int)`i
(idb) func HeavenlyBody::printBodyAndItsSatellites
Error: no value for symbol this
Evaluating 'HeavenlyBody::printBodyAndItsSatellites' failed!
The scope HeavenlyBody does not have a field named 'printBodyAndItsSatellites'!
(idb) which i
Symbol not found in current scope
(idb) print i
Symbol "i" is not defined.

8.4.11 Notes on C++ Debugging

The following sections describe the debugger commands specific to debugging C++ programs.

c++_look_around_command
        : class [ class_name ]

(idb) stop in append
Symbol "append" is not defined.
append has no valid breakpoint address
Warning: Breakpoint not set
(idb) class List<Node>
struct List<Node> {
  struct Node* _firstNode;
  List(void);
  void append(struct Node* const);
  void print(void);
  ~List(void);
}
(idb) stop in append
[#1: stop in void List<Node>::append(struct Node* const) ]

(idb) list 43: 12
     43 // Compound Node - contains integer and float data items
     44 //
     45 class CompoundNode : public IntNode {
     46 public:
     47     CompoundNode (float fdata, int idata);
     48
     49     void printNodeData() const;
     50
     51 private:
     52     float _fdata;
     53 };
     54
(idb) whatis CompoundNode
struct CompoundNode : IntNode {
  float _fdata;
  CompoundNode(float, int);
  virtual void printNodeData(void);
}
(idb) whatis CompoundNode::CompoundNode
CompoundNode::CompoundNode(float, int)
(idb) stop in CompoundNode::printNodeData
[#1: stop in virtual void CompoundNode::printNodeData(void) ]
(idb) run
The list is:
Node 1 type is integer, value is 1
[1] stopped at [virtual void CompoundNode::printNodeData(void):109 0x804a654]
    109     cout << " type is compound, value is ";
(idb) print _fdata
12.3450003

(idb) whatis this
const struct CompoundNode* const this
(idb) whatis *this
struct CompoundNode : IntNode {
  float _fdata;
  CompoundNode(float, int);
  virtual void printNodeData(void);
}
(idb) print *this
struct CompoundNode {
  _fdata = 12.3450003;
  _data = 2;                      // class IntNode
  _nextNode = 0x80b0f68;          // class IntNode::Node
}
(idb) print _fdata, _data
12.3450003 2
(idb) print this->_fdata, this->_data
12.3450003 2

(idb) print $usedynamictypes
0
(idb) whatis *this
struct HeavenlyBody {
  const char* const _name;
  struct HeavenlyBody* _innerNeighbor;
  struct HeavenlyBody* _outerNeighbor;
  struct HeavenlyBody* _firstSatellite;
  struct HeavenlyBody* _lastSatellite;
  HeavenlyBody(char*);
  void addSatellite(struct HeavenlyBody*);
  const char* name(void);
  virtual void print(unsigned int);
  void printBodyAndItsSatellites(unsigned int);
  unsigned int satelliteNumber(struct HeavenlyBody*);
}
(idb) print *this
struct HeavenlyBody {
  _name = 0x808e4a0="Moon";
  _innerNeighbor = 0x0;
  _outerNeighbor = 0x0;
  _firstSatellite = 0x0;
  _lastSatellite = 0x0;
}

(idb) print $usedynamictypes
1
(idb) whatis *this
struct HeavenlyBody {
  const char* const _name;
  struct HeavenlyBody* _innerNeighbor;
  struct HeavenlyBody* _outerNeighbor;
  struct HeavenlyBody* _firstSatellite;
  struct HeavenlyBody* _lastSatellite;
  HeavenlyBody(char*);
  void addSatellite(struct HeavenlyBody*);
  const char* name(void);
  virtual void print(unsigned int);
  void printBodyAndItsSatellites(unsigned int);
  unsigned int satelliteNumber(struct HeavenlyBody*);
}
(idb) print *this
struct HeavenlyBody {
  _name = 0x808e4a0="Moon";
  _innerNeighbor = 0x0;
  _outerNeighbor = 0x0;
  _firstSatellite = 0x0;
  _lastSatellite = 0x0;
}

(idb) where 3
>0  0x804a628 in ((CompoundNode*)<bad value>)->CompoundNode::CompoundNode(=<no value>, =<no value>) "x_list.cxx":103
#1  0x804a0ae in main() "x_list.cxx":189
#2  0x400a2507 in __libc_start_main(...) in /lib/i686/libc.so.6
(idb) whatis *this
Symbol "this" is not defined.
(idb) print *this
Symbol "this" is not defined.
(idb) up 1
>1  0x804a0ae in main() "x_list.cxx":189
    189     CompoundNode* cNode = new CompoundNode(12.345, 2);
(idb) whatis *this
Symbol "this" is not defined.
(idb) print *this
Symbol "this" is not defined.
(idb) up 1
>2  0x400a2507 in __libc_start_main(...) in /lib/i686/libc.so.6
(idb) whatis *this
Symbol "this" is not defined.
(idb) print *this
Symbol "this" is not defined.

object.class::member

object->class::member

(idb) print *jupiter
struct Planet {
  _name = 0x808e480="Jupiter";    // class HeavenlyBody
  _innerNeighbor = 0x80cf6e8;     // class HeavenlyBody
  _outerNeighbor = 0x80cfa48;     // class HeavenlyBody
  _firstSatellite = 0x80cf868;    // class HeavenlyBody
  _lastSatellite = 0x80cf9e8;     // class HeavenlyBody
  _primary = 0x80cf4d0;           // class Orbit
  _distance = 778330;             // class Orbit
  _name = 0x80cf8a0="Sol 5";      // class Orbit
}
(idb) print jupiter->_name
Overloaded Values
0x80cf8a0="Sol 5"
0x808e480="Jupiter"
(idb) print jupiter->HeavenlyBody::_name
0x808e480="Jupiter"
(idb) print jupiter->Orbit::_name
0x80cf8a0="Sol 5"

Name is overloaded.

Member function has been inlined.

line: 41 Unable to parse input as legal command or C expression.

(idb) set $verbose = 0
(idb) whatis CompoundNode
struct CompoundNode : IntNode {
  float _fdata;
  CompoundNode(struct CompoundNode*, float, int);
  virtual void printNodeData(const struct CompoundNode* const);
}
(idb) set $verbose = 1
(idb) whatis CompoundNode
struct CompoundNode : IntNode {
  float _fdata;
  CompoundNode(struct CompoundNode*, float, int);
  virtual void printNodeData(const struct CompoundNode* const);
}

8.5.1 Memory Display and Search Commands

You can use the following commands to read arbitrary memory locations in your program:

machinecode_level_command
     : examine_command
     : search_command

examine_command
     : address_expression / [ count ] [ mode ]
     | address_expression ? [ count ] [ mode ]
     | address_expression , address_expression / [ mode ]

search_command
     : address_expression / [ count ] search_mode   value  mask
     | address_expression ? [ count ]  search_mode  value  mask
     | address_expression , address_expression /  search_mode  value  mask

count
     : integer_constant

mode
     : d 	Print a short word in decimal
     | dd      	Print a 32-bit (4-byte) decimal display
     | D      	Print a long word in decimal
     | u	Print a short word in unsigned decimal
     | uu	Print a 32-bit (4-byte) unsigned decimal display
     | U	Print a long word in unsigned decimal
     | o	Print a short word in octal
     | oo	Print a 32-bit (4-byte) octal display
     | O	Print a long word in octal
     | x	Print a short word in hexadecimal
     | xx	Print a 32-bit (4-byte) hexadecimal display
     | X       	Print a long word in hexadecimal
     | b       	Print a byte in hex
     | c       	Print a byte as a character
     | s       	Print a string of characters (a C-style string ending in null)
     | C       	Print a wide character as a character
     | S       	Print a null terminated string of wide characters
     | f       	Print a single precision real number
     | g       	Print a double precision real number
     | L       	Print a long double precision real number
     | i       	Disassemble machine instructions

search_mode
     : m   	32-bit search mode
     | M       	64-bit search mode

value
     : integer_constant

mask
     : integer_constant

The first examine_command displays the count number of memory values in the requested format, starting at address_expression. If count is not specified, 1 is assumed. The count value must be a positive value.

If you wish to see memory values leading up to the address_expression, use the second examine_command. The second examine_command displays count number of memory values in the requested format ending at the address_expression. If count is not specified, 1 is assumed. The count value must be a positive value.

The third examine_command displays memory values in the requested format starting at the smaller of the two address_expressions and ending at the larger address_expression.

You can display stored values in the following formats by specifying mode. If mode is not specified, the mode used in the previous / command is assumed. If no previous / command exists, X is assumed.

When disassembling machine instructions, use the $regstyle variable to customize how the registers are displayed.

The search_commands allow you to search memory. Use the address_expression and count to determine the range of memory to search. Use the search_mode to specify whether you want to search 32 or 64-bit chunks. The debugger will start at the specified starting address and read a chunk of memory (either 32 or 64 bits in size) and apply the mask and comparison on that chunk of memory. For example, if you want to search memory for a particular instruction or search an array of either integer or floating-point values, the 32-bit search would be efficient because machine instructions and integer and floating-point data types are 32 bits in length. Use the value to specify the memory value to seek. Use the mask to specify those bits that must match the same bits in the specified value. To ensure that a possible match will be found, the debugger applies the mask to the input value prior to starting the search, to remove any bits that could prevent a match from occurring. Then, for each memory location searched, the debugger applies the mask to the memory value and then compares it with this new input value. If a match is found, then the address and memory value are displayed.

For example, suppose the user wishes to check an array of 100 integers in memory to see if any values are NULL (0):

(idb) array,&(array[99])/m 0x0 0xfffffff
0x1400005d0:  0x00000000

Suppose the user wishes to search for the trapb instruction:

(idb) printi 0x63ff0000
trapb
(idb) main/1000m 0x63ff0000 0xfffffff
0x12561314: 0x63ff0000

Use the debugger variable $memorymatchall to cause the debugger to output all matches in the specified range. Suppose you want to search a long integer array of 100 values for the first value over 80, and then want to find all values in the array over 80:

(idb) printx 80
0x50
(idb) longarray/100M 0x50 0x50
0x140002680: 0x0000000000000050
(idb) set $memorymatchall
(idb) longarray/100M 0x50 0x50
0x140002680: 0x0000000000000050
0x140002688: 0x0000000000000051
0x140002690: 0x0000000000000052
0x140002698: 0x0000000000000053
0x1400026a0: 0x0000000000000054
0x1400026a8: 0x0000000000000055
0x1400026b0: 0x0000000000000056
0x1400026b8: 0x0000000000000057
0x1400026c0: 0x0000000000000058
0x1400026c8: 0x0000000000000059
0x1400026d0: 0x000000000000005a
0x1400026d8: 0x000000000000005b
0x1400026e0: 0x000000000000005c
0x1400026e8: 0x000000000000005d
0x1400026f0: 0x000000000000005e
0x1400026f8: 0x000000000000005f
(idb)

8.5.2 Machine-Level Debugging

The debugger lets you debug your programs at the machine-code level as well as at the source-code level. Using debugger commands, you can examine and edit values in memory, print the values of all machine registers, and step through program execution one machine instruction at a time.

Only those users familiar with machine-language programming and executable file code structure will find low-level debugging useful.

For more information on machine-level debugging, see Machine-Level Debugging in Part III.

9.1.1 The assign and the set variable Commands in Machine-Level Debugging

You can use the assign(dbx) and the set variable(gdb) commands to alter the contents of memory specified by an address as shown in the following example:

(idb) set $address = &(node->_data)
(idb) print $address
0x80c0ff8
(idb) print *(int *)($address)
-32
(idb) assign *(int *)($address) = 1024
(idb) print *(int *)($address)
1024

(idb) set $address = &(node->_data)
(idb) print $address
$11 = (int *) 0x80b98f8
(idb) print *(int *)($address)
$12 = 32
(idb) set *(int *)($address) = 1024
(idb) print *(int *)($address)
$13 = 1024

See Machine-Level Debugging for more information.

13.2.1 Limitations on Procedure Invocations

Following are the limitations on Fortran procedure invocations:

• The debugger does not support invocations of user-defined procedures unless they have been compiled with debug information.
• The debugger does not support complex or real*16 procedure return values.
• The debugger does not support real*16 or complex*32 procedure arguments.
• Of the Fortran intrinsic procedures, the debugger currently supports only:
  • the mathematical functions (for example, ACOS, ACOSD, SIN, SQRT, and so on)
  • the kind type functions (KIND, SELECTED_INT_KIND, SELECTED_REAL_KIND)

15.1.1 Lexical States

The debugger starts processing each line according to the rules of the LKEYWORD lexical state. It recognizes the longest lexeme it can, according to these rules. After recognizing the lexeme, it may stay in the same state, or it may change to a different lexical state with different rules.

The debugger moves between the following lexical states as it recognizes the lexemes:

The rules that each lexical state uses are described in the following sections, in a format known as a lex regular expression. Rather than repeating some of descriptions, a set of common subrules is described first. After the common subrules, we describe the initial state, the rules, and for each recognized token, the next lexical state.

15.1.2 Identifiers

All languages have a concept of an identifier, composed of letters, digits, and other special characters. The debugger also uses keywords composed of letters; therefore, rules are required to determine which identifiers are actually debugger keywords.

All debugger commands, except examine, begin with leading keywords. Because the examine command begins with an expression, all identifiers must be recognized as such from both the LKEYWORD state that starts commands and the LNORM state that the debugger uses for processing expressions.

Some debugger commands have keywords embedded in them following expressions, and the ends of expressions are hard to recognize. You can use identifiers that have the same spelling as an embedded keyword simply by enclosing the whole expression in parentheses (()). For more information on using keywords within commands, see Section 4.4.4.

Furthermore, the C and C++ grammars need to know whether an identifier is a typedef or struct/class identifier. The debugger currently makes the determination at the time the whole command is parsed, rather than deferring the determination to when the expression itself is being evaluated. This can result in a misidentification of the identifier.