![[Previous]](prev.gif) |
![[Contents]](contents.gif) |
![[Index]](keyword_index.gif) |
![[Next]](next.gif) |
|
|
|
|
The Neutrino implementation of GDB includes some extensions:
To debug an application, do the following:
gdb
file my_application
target qnx com_port_specifier | host:port | pty
upload my_application /tmp/my_application
set break main
run
This section includes:
You can abbreviate a GDB command to the first few letters of the command name, if that abbreviation is unambiguous; and you can repeat certain GDB commands by typing just Enter. You can also use the Tab key to get GDB to fill out the rest of a word in a command (or to show you the alternatives available, if there's more than one possibility).
You may also place GDB commands in an initialization file and these commands will be run before any that have been entered via the command line. For more information, see:
A GDB command is a single line of input. There's no limit on how long it can be. It starts with a command name, which is followed by arguments whose meaning depends on the command name. For example, the command step accepts an argument that is the number of times to step, as in step 5. You can also use the step command with no arguments. Some command names don't allow any arguments.
GDB command names may always be truncated if that abbreviation is unambiguous. Other possible command abbreviations are listed in the documentation for individual commands. In some cases, even ambiguous abbreviations are allowed; for example, s is specifically defined as equivalent to step even though there are other commands whose names start with s. You can test abbreviations by using them as arguments to the help command.
A blank line as input to GDB (typing just Enter) means to repeat the previous command. Certain commands (for example, run) don't repeat this way; these are commands whose unintentional repetition might cause trouble and which you're unlikely to want to repeat.
When you repeat the list and x commands with Enter, they construct new arguments rather than repeat exactly as typed. This permits easy scanning of source or memory.
GDB can also use Enter in another way: to partition lengthy output, in a way similar to the common utility more. Since it's easy to press one Enter too many in this situation, GDB disables command repetition after any command that generates this sort of display.
Any text from a # to the end of the line is a comment. This is useful mainly in command files.
GDB can fill in the rest of a word in a command for you if there's only one possibility; it can also show you what the valid possibilities are for the next word in a command, at any time. This works for GDB commands, GDB subcommands, and the names of symbols in your program.
Press the Tab key whenever you want GDB to fill out the rest of a word. If there's only one possibility, GDB fills in the word, and waits for you to finish the command (or press Enter to enter it). For example, if you type:
(gdb) info bre Tab
GDB fills in the rest of the word breakpoints, since that is the only info subcommand beginning with bre:
(gdb) info breakpoints
You can either press Enter at this point, to run the info breakpoints command, or backspace and enter something else, if breakpoints doesn't look like the command you expected. (If you were sure you wanted info breakpoints in the first place, you might as well just type Enter immediately after info bre, to exploit command abbreviations rather than command completion).
If there's more than one possibility for the next word when you press Tab, GDB sounds a bell. You can either supply more characters and try again, or just press Tab a second time; GDB displays all the possible completions for that word. For example, you might want to set a breakpoint on a subroutine whose name begins with make_, but when you type:
b make_Tab
GDB just sounds the bell. Typing Tab again displays all the function names in your program that begin with those characters, for example:
make_a_section_from_file make_environ make_abs_section make_function_type make_blockvector make_pointer_type make_cleanup make_reference_type make_command make_symbol_completion_list (gdb) b make_
After displaying the available possibilities, GDB copies your partial input (b make_ in the example) so you can finish the command.
If you just want to see the list of alternatives in the first place, you can press Esc followed by ? (rather than press Tab twice).
Sometimes the string you need, while logically a “word”, may contain parentheses or other characters that GDB normally excludes from its notion of a word. To permit word completion to work in this situation, you may enclose words in ' (single quote marks) in GDB commands.
The most likely situation where you might need this is in typing the name of a C++ function. This is because C++ allows function overloading (multiple definitions of the same function, distinguished by argument type). For example, when you want to set a breakpoint you may need to distinguish whether you mean the version of name that takes an int parameter, name(int), or the version that takes a float parameter, name(float). To use the word-completion facilities in this situation, type a single quote ' at the beginning of the function name. This alerts GDB that it may need to consider more information than usual when you press Tab, or Esc followed by ?, to request word completion:
(gdb) b 'bubble(Esc? bubble(double,double) bubble(int,int) (gdb) b 'bubble(
In some cases, GDB can tell that completing a name requires using quotes. When this happens, GDB inserts the quote for you (while completing as much as it can) if you don't type the quote in the first place:
(gdb) b bub Tab
GDB alters your input line to the following, and rings a bell:
(gdb) b 'bubble(
In general, GDB can tell that a quote is needed (and inserts it) if you haven't yet started typing the argument list when you ask for completion on an overloaded symbol.
You can always ask GDB itself for information on its commands, using the command help.
(gdb) help List of classes of commands: running -- Running the program stack -- Examining the stack data -- Examining data breakpoints -- Making program stop at certain points files -- Specifying and examining files status -- Status inquiries support -- Support facilities user-defined -- User-defined commands aliases -- Aliases of other commands obscure -- Obscure features Type "help" followed by a class name for a list of commands in that class. Type "help" followed by command name for full documentation. Command name abbreviations are allowed if unambiguous. (gdb)
(gdb) help status Status inquiries. List of commands: show -- Generic command for showing things set with "set" info -- Generic command for printing status Type "help" followed by command name for full documentation. Command name abbreviations are allowed if unambiguous. (gdb)
complete iresults in:
info inspect ignoreThis is intended for use by GNU Emacs.
In addition to help, you can use the GDB commands info and show to inquire about the state of your program, or the state of GDB itself. Each command supports many topics of inquiry; this manual introduces each of them in the appropriate context. The listings under info and show in the index point to all the sub-commands.
To display all the settable parameters and their current values, you can use show with no arguments; you may also use info set. Both commands produce the same display.
Here are three miscellaneous show subcommands, all of which are exceptional in lacking corresponding set commands:
This section includes:
To run a program under GDB, you must first generate debugging information when you compile it. You may start GDB with its arguments, if any, in an environment of your choice. You may redirect your program's input and output, debug an already running process, or kill the process being debugged.
Debugging information is stored in the object file; it describes the data type of each variable or function and the correspondence between source line numbers and addresses in the executable code.
To request debugging information, specify the -g option when you run the compiler.
GCC, the GNU C compiler, supports -g with or without -O, making it possible to debug optimized code. We recommend that you always use -g whenever you compile a program. You may think your program is correct, but there's no sense in pushing your luck.
When you debug a program compiled with -g -O, remember that the optimizer is rearranging your code; the debugger shows you what is really there. Don't be too surprised when the execution path doesn't exactly match your source file! An extreme example: if you define a variable, but never use it, GDB never sees that variable—because the compiler optimizes it out of existence.
Some things don't work as well with -g -O as with just -g, particularly on machines with instruction scheduling. If in doubt, recompile with -g alone, and if this fixes the problem, please report it to us — and include a test case.
If you're debugging locally, you don't need to specify the target (or you can specify target procfs).
If you're debugging remotely, you need to specify the target to use:
target qnx com_port_specifier | host:port | pty
The pty option spawns a pdebug server on the local machine and connects via a pty.
 |
The devc-pty manager must be running on the machine that's running pdebug, and a ptyp/ttyp pair must be available. |
The run creates an inferior process and makes that process run your program.
The execution of a program is affected by certain information it receives from its superior. GDB provides ways to specify this information, which you must do before starting your program. (You can change it after starting your program, but such changes affect your program the next time you start it.) This information may be divided into the following categories:
|
While input and output redirection work, you can't use pipes to pass the output of the program you're debugging to another program; if you attempt this, GDB is likely to wind up debugging the wrong program. |
If the modification time of your symbol file has changed since the last time GDB read its symbols, GDB discards its symbol table and reads it again. When it does this, GDB tries to retain your current breakpoints.
Here's an example of starting a program for local debugging:
(gdb) file /tmp/helloworld
Reading symbols from /tmp/helloworld...done.
(gdb) b main
Breakpoint 1 at 0x804860c: file ./main.c, line 5.
(gdb) r
Starting program:
Remote: /tmp/helloworld
Breakpoint 1, main () at ./main.c:5
5 {
(gdb)
Here's an example of starting the program for remote debugging:
(gdb) target qnx mytst:8000
Remote debugging using mytst:8000
Remote target is little-endian
(gdb) file /tmp/helloworld
Reading symbols from /tmp/helloworld...done.
(gdb) upload /tmp/helloworld /tmp/helloworld
(gdb) b main
Breakpoint 1 at 0x804860c: file ./main.c, line 5.
(gdb) r
Starting program:
Remote: /tmp/helloworld
Breakpoint 1, main () at ./main.c:5
5 {
(gdb)
If your communication line is slow, you might need to set the timeout for remote reads:
set nto-timeout time
where time is the timeout, in seconds. The default is 10 seconds.
The arguments to your program can be specified by the arguments of the run command.
A run command with no arguments uses the same arguments used by the previous run, or those set by the set args command.
The environment consists of a set of environment variables and their values. Environment variables conventionally record such things as your user name, your home directory, your terminal type, and your search path for programs to run. Usually you set up environment variables with the shell and they're inherited by all the other programs you run. When debugging, it can be useful to try running your program with a modified environment without having to start GDB over again.
You can use the string $cwd to refer to the current working directory at the time GDB searches the path. A period (.) refers to the directory where you executed the path command. GDB replaces the period in the directory argument by the current path before adding directory to the search path.
For example, this command:
set env USER=footells a Unix program, when subsequently run, that its user is named foo.
By default, the program you run under GDB does input and output to the same terminal that GDB uses. GDB switches the terminal to its own terminal modes to interact with you, but it records the terminal modes your program was using and switches back to them when you continue running your program.
You can redirect your program's input and/or output using shell redirection with the run command. For example,
run > outfile
starts your program, diverting its output to the file outfile.
The attach command doesn't repeat if you press Enter a second time after executing the command.
To use attach, you must have permission to send the process a signal.
When using attach, you should first use the file command to specify the program running in the process and load its symbol table.
The first thing GDB does after arranging to debug the specified process is to stop it. You can examine and modify an attached process with all the GDB commands that are ordinarily available when you start processes with run. You can insert breakpoints; you can step and continue; you can modify storage. If you want the process to continue running, use the continue command after attaching GDB to the process.
If you exit GDB or use the run command while you have an attached process, you kill that process. By default, GDB asks for confirmation if you try to do either of these things; you can control whether or not you need to confirm by using the set confirm command.
This command is useful if you wish to debug a core dump instead of a running process. GDB ignores any core dump file while your program is running.
The kill command is also useful if you wish to recompile and relink your program. With Neutrino, it's possible to modify an executable file while it's running in a process. If you want to run the new version, kill the current process; when you next type run, GDB notices that the file has changed, and reads the symbol table again (while trying to preserve your current breakpoint settings).
In Neutrino, a single program may have more than one thread of execution. Each thread has its own registers and execution stack, and perhaps private memory.
GDB provides these facilities for debugging multithreaded programs:
The GDB thread debugging facility lets you observe all threads while your program runs—but whenever GDB takes control, one thread in particular is always the focus of debugging. This thread is called the current thread. Debugging commands show program information from the perspective of the current thread.
GDB associates its own thread number—always a single integer—with each thread in your program.
An asterisk * to the left of the GDB thread number indicates the current thread. For example:
(gdb) info threads
3 process 35 thread 27 0x34e5 in sigpause ()
2 process 35 thread 23 0x34e5 in sigpause ()
* 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8)
at threadtest.c:68
(gdb) thread 2 [Switching to process 35 thread 23] 0x34e5 in sigpause ()
Whenever GDB stops your program because of a breakpoint or a signal, it automatically selects the thread where that breakpoint or signal happened. GDB alerts you to the context switch with a message of the form [Switching to systag] to identify the thread.
See “Stopping and starting multithreaded programs” for more information about how GDB behaves when you stop and start programs with multiple threads.
See “Setting watchpoints” for information about watchpoints in programs with multiple threads.
GDB has no special support for debugging programs that create additional processes using the fork() function. When a program forks, GDB continues to debug the parent process, and the child process runs unimpeded. If you've set a breakpoint in any code that the child then executes, the child gets a SIGTRAP signal, which (unless it catches the signal) causes it to terminate.
However, if you want to debug the child process, there's a workaround that isn't too painful:
This section includes:
Inside GDB, your program may stop for any of several reasons, such as a signal, a breakpoint, or reaching a new line after a GDB command such as step. You may then examine and change variables, set new breakpoints or remove old ones, and then continue execution. Usually, the messages shown by GDB provide ample explanation of the status of your program—but you can also explicitly request this information at any time.
This section includes:
A breakpoint makes your program stop whenever a certain point in the program is reached. For each breakpoint, you can add conditions to control in finer detail whether your program stops. You can set breakpoints with the break command and its variants (see “Setting breakpoints”) to specify the place where your program should stop by line number, function name or exact address in the program. In languages with exception handling (such as GNU C++), you can also set breakpoints where an exception is raised (see “Breakpoints and exceptions”).
A watchpoint is a special breakpoint that stops your program when the value of an expression changes. You must use a different command to set watchpoints (see “Setting watchpoints”), but aside from that, you can manage a watchpoint like any other breakpoint: you enable, disable, and delete both breakpoints and watchpoints using the same commands.
You can arrange to have values from your program displayed automatically whenever GDB stops at a breakpoint. See “Automatic display.”
GDB assigns a number to each breakpoint or watchpoint when you create it; these numbers are successive integers starting with 1. In many of the commands for controlling various features of breakpoints you use the breakpoint number to say which breakpoint you want to change. Each breakpoint may be enabled or disabled; if disabled, it has no effect on your program until you enable it again.
Use the break (b) command to set breakpoints. The debugger convenience variable $bpnum records the number of the breakpoints you've set most recently; see “Convenience variables” for a discussion of what you can do with convenience variables.
You have several ways to say where the breakpoint should go:
GDB normally ignores breakpoints when it resumes execution, until at least one instruction has been executed. If it didn't do this, you wouldn't be able to proceed past a breakpoint without first disabling the breakpoint. This rule applies whether or not the breakpoint already existed when your program stopped.
There are several variations on the break command, all using the same syntax as above:
The main purpose of this is EPROM/ROM code debugging, so you can set a breakpoint at an instruction without changing the instruction.
When debugging C++ programs, rbreak is useful for setting breakpoints on overloaded functions that aren't members of any special classes.
The following commands display information about breakpoints and watchpoints:
If a breakpoint is conditional, info break shows the condition on the line following the affected breakpoint; breakpoint commands, if any, are listed after that.
An info break command with a breakpoint number n as argument lists only that breakpoint. The convenience variable $_ and the default examining-address for the x command are set to the address of the last breakpoint listed (see “Examining memory”).
The info break command displays the number of times the breakpoint has been hit. This is especially useful in conjunction with the ignore command. You can ignore a large number of breakpoint hits, look at the breakpoint information to see how many times the breakpoint was hit, and then run again, ignoring one less than that number. This gets you quickly to the last hit of that breakpoint.
GDB lets you set any number of breakpoints at the same place in your program. There's nothing silly or meaningless about this. When the breakpoints are conditional, this is even useful (see “Break conditions”).
GDB itself sometimes sets breakpoints in your program for special purposes, such as proper handling of longjmp (in C programs). These internal breakpoints are assigned negative numbers, starting with -1; info breakpoints doesn't display them.
You can see these breakpoints with the GDB maintenance command, maint info breakpoints.
You can use a watchpoint to stop execution whenever the value of an expression changes, without having to predict a particular place where this may happen.
Although watchpoints currently execute two orders of magnitude more slowly than other breakpoints, they can help catch errors where in cases where you have no clue what part of your program is the culprit.
|
In multithreaded programs, watchpoints have only limited usefulness. With the current watchpoint implementation, GDB can watch the value of an expression in a single thread only. If you're confident that the expression can change due only to the current thread's activity (and if you're also confident that no other thread can become current), then you can use watchpoints as usual. However, GDB may not notice when a noncurrent thread's activity changes the expression. |
Some languages, such as GNU C++, implement exception handling. You can use GDB to examine what caused your program to raise an exception and to list the exceptions your program is prepared to handle at a given point in time.
You can use info catch to list active exception handlers. See “Information about a frame.”
There are currently some limitations to exception handling in GDB:
Sometimes catch isn't the best way to debug exception handling: if you need to know exactly where an exception is raised, it's better to stop before the exception handler is called, since that way you can see the stack before any unwinding takes place. If you set a breakpoint in an exception handler instead, it may not be easy to find out where the exception was raised.
To stop just before an exception handler is called, you need some knowledge of the implementation. In the case of GNU C++, exceptions are raised by calling a library function named __raise_exception(), which has the following ANSI C interface:
void __raise_exception (void **addr, void *id); /* addr is where the exception identifier is stored. id is the exception identifier. */
To make the debugger catch all exceptions before any stack unwinding takes place, set a breakpoint on __raise_exception(). See “Breakpoints, watchpoints, and exceptions.”
With a conditional breakpoint (see “Break conditions”) that depends on the value of id, you can stop your program when a specific exception is raised. You can use multiple conditional breakpoints to stop your program when any of a number of exceptions are raised.
You often need to eliminate a breakpoint or watchpoint once it's done its job and you no longer want your program to stop there. This is called deleting the breakpoint. A breakpoint that has been deleted no longer exists and is forgotten.
With the clear command you can delete breakpoints according to where they are in your program. With the delete command you can delete individual breakpoints or watchpoints by specifying their breakpoint numbers.
You don't have to delete a breakpoint to proceed past it. GDB automatically ignores breakpoints on the first instruction to be executed when you continue execution without changing the execution address.
Rather than delete a breakpoint or watchpoint, you might prefer to disable it. This makes the breakpoint inoperative as if it had been deleted, but remembers the information on the breakpoint so that you can enable it again later.
You disable and enable breakpoints and watchpoints with the enable and disable commands, optionally specifying one or more breakpoint numbers as arguments. Use info break or info watch to print a list of breakpoints or watchpoints if you don't know which numbers to use.
A breakpoint or watchpoint can have any of the following states:
You can use the following commands to enable or disable breakpoints and watchpoints:
Except for a breakpoint set with tbreak (see “Setting breakpoints”), breakpoints that you set are initially enabled; subsequently, they become disabled or enabled only when you use one of the commands above. (The command until can set and delete a breakpoint of its own, but it doesn't change the state of your other breakpoints; see “Continuing and stepping.”)
The simplest sort of breakpoint breaks every time your program reaches a specified place. You can also specify a condition for a breakpoint. A condition is just a Boolean expression in your programming language (see “Expressions”). A breakpoint with a condition evaluates the expression each time your program reaches it, and your program stops only if the condition is true.
This is the converse of using assertions for program validation; in that situation, you want to stop when the assertion is violated—that is, when the condition is false. In C, if you want to test an assertion expressed by the condition assert, you should set the condition ! assert on the appropriate breakpoint.
Conditions are also accepted for watchpoints; you may not need them, since a watchpoint is inspecting the value of an expression anyhow—but it might be simpler, say, to just set a watchpoint on a variable name, and specify a condition that tests whether the new value is an interesting one.
Break conditions can have side effects, and may even call functions in your program. This can be useful, for example, to activate functions that log program progress, or to use your own print functions to format special data structures. The effects are completely predictable unless there's another enabled breakpoint at the same address. (In that case, GDB might see the other breakpoint first and stop your program without checking the condition of this one.) Note that breakpoint commands are usually more convenient and flexible for the purpose of performing side effects when a breakpoint is reached (see “Breakpoint command lists”).
Break conditions can be specified when a breakpoint is set, by using if in the arguments to the break command. See “Setting breakpoints.” They can also be changed at any time with the condition command. The watch command doesn't recognize the if keyword; condition is the only way to impose a further condition on a watchpoint.
A special case of a breakpoint condition is to stop only when the breakpoint has been reached a certain number of times. This is so useful that there's a special way to do it, using the ignore count of the breakpoint. Every breakpoint has an ignore count, which is an integer. Most of the time, the ignore count is zero, and therefore has no effect. But if your program reaches a breakpoint whose ignore count is positive, then instead of stopping, it just decrements the ignore count by one and continues. As a result, if the ignore count value is n, the breakpoint doesn't stop the next n times your program reaches it.
To make the breakpoint stop the next time it's reached, specify a count of zero.
When you use continue to resume execution of your program from a breakpoint, you can specify an ignore count directly as an argument to continue, rather than use ignore. See “Continuing and stepping.”
If a breakpoint has a positive ignore count and a condition, the condition isn't checked. Once the ignore count reaches zero, GDB resumes checking the condition.
You could achieve the effect of the ignore count with a condition such as $foo-- <= 0 using a debugger convenience variable that's decremented each time. See “Convenience variables.”
You can give any breakpoint (or watchpoint) a series of commands to execute when your program stops due to that breakpoint. For example, you might want to print the values of certain expressions, or enable other breakpoints.
To remove all commands from a breakpoint, type commands and follow it immediately with end; that is, give no commands.
With no bnum argument, commands refers to the last breakpoint or watchpoint set (not to the breakpoint most recently encountered).
Pressing Enter as a means of repeating the last GDB command is disabled within a command-list.
You can use breakpoint commands to start your program up again. Just use the continue command, or step, or any other command that resumes execution.
Commands in command-list that follow a command that resumes execution are ignored. This is because any time you resume execution (even with a simple next or step), you may encounter another breakpoint—which could have its own command list, leading to ambiguities about which list to execute.
If the first command you specify in a command list is silent, the usual message about stopping at a breakpoint isn't printed. This may be desirable for breakpoints that are to print a specific message and then continue. If none of the remaining commands print anything, you see no sign that the breakpoint was reached. The silent command is meaningful only at the beginning of a breakpoint command list.
The commands echo, output, and printf allow you to print precisely controlled output, and are often useful in silent breakpoints.
For example, here's how you could use breakpoint commands to print the value of x at entry to foo() whenever x is positive:
break foo if x>0 commands silent printf "x is %d\n",x cont end
One application for breakpoint commands is to compensate for one bug so you can test for another. Put a breakpoint just after the erroneous line of code, give it a condition to detect the case in which something erroneous has been done, and give it commands to assign correct values to any variables that need them. End with the continue command so that your program doesn't stop, and start with the silent command so that no output is produced. Here's an example:
break 403 commands silent set x = y + 4 cont end
Some programming languages (notably C++) permit a single function name to be defined several times, for application in different contexts. This is called overloading. When a function name is overloaded, break function isn't enough to tell GDB where you want a breakpoint.
If you realize this is a problem, you can use something like break function(types) to specify which particular version of the function you want. Otherwise, GDB offers you a menu of numbered choices for different possible breakpoints, and waits for your selection with the prompt >. The first two options are always [0] cancel and [1] all. Typing 1 sets a breakpoint at each definition of function, and typing 0 aborts the break command without setting any new breakpoints.
For example, the following session excerpt shows an attempt to set a breakpoint at the overloaded symbol String::after(). We choose three particular definitions of that function name:
(gdb) b String::after [0] cancel [1] all [2] file:String.cc; line number:867 [3] file:String.cc; line number:860 [4] file:String.cc; line number:875 [5] file:String.cc; line number:853 [6] file:String.cc; line number:846 [7] file:String.cc; line number:735 > 2 4 6 Breakpoint 1 at 0xb26c: file String.cc, line 867. Breakpoint 2 at 0xb344: file String.cc, line 875. Breakpoint 3 at 0xafcc: file String.cc, line 846. Multiple breakpoints were set. Use the "delete" command to delete unwanted breakpoints. (gdb)
Continuing means resuming program execution until your program completes normally. In contrast, stepping means executing just one more “step” of your program, where “step” may mean either one line of source code, or one machine instruction (depending on what particular command you use). Either when continuing or when stepping, your program may stop even sooner, due to a breakpoint or a signal. (If due to a signal, you may want to use handle, or use signal 0 to resume execution. See “Signals.”)
The argument ignore-count is meaningful only when your program stopped due to a breakpoint. At other times, the argument to continue is ignored.
The synonyms c and fg are provided purely for convenience, and have exactly the same behavior as continue.
To resume execution at a different place, you can use return (see “Returning from a function”) to go back to the calling function; or jump (see “Continuing at a different address”) to go to an arbitrary location in your program.
A typical technique for using stepping is to set a breakpoint (see “Breakpoints, watchpoints, and exceptions”) at the beginning of the function or the section of your program where a problem is believed to lie, run your program until it stops at that breakpoint, and then step through the suspect area, examining the variables that are interesting, until you see the problem happen.
|
If you use the step command while control is within a function that was compiled without debugging information, execution proceeds until control reaches a function that does have debugging information. Likewise, it doesn't step into a function that is compiled without debugging information. To step through functions without debugging information, use the stepi command, described below. |
The step command stops only at the first instruction of a source line. This prevents multiple stops in switch statements, for loops, etc. The step command stops if a function that has debugging information is called within the line.
Also, the step command enters a subroutine only if there's line number information for the subroutine. Otherwise it acts like the next command. This avoids problems when using cc -gl on MIPS machines.
The count argument is a repeat count, as for step.
The next command stops only at the first instruction of a source line. This prevents the multiple stops in switch statements, for loops, etc.
Contrast this with the return command (see “Returning from a function”).
This means that when you reach the end of a loop after single-stepping though it, until makes your program continue execution until it exits the loop. In contrast, a next command at the end of a loop simply steps back to the beginning of the loop, which forces you to step through the next iteration.
The until command always stops your program if it attempts to exit the current stack frame.
The until command may produce somewhat counterintuitive results if the order of machine code doesn't match the order of the source lines. For example, in the following excerpt from a debugging session, the f (frame) command shows that execution is stopped at line 206; yet when we use until, we get to line 195:
(gdb) f
#0 main (argc=4, argv=0xf7fffae8) at m4.c:206
206 expand_input();
(gdb) until
195 for ( ; argc > 0; NEXTARG) {
This happened because, for execution efficiency, the compiler had generated code for the loop closure test at the end, rather than the start, of the loop—even though the test in a C for-loop is written before the body of the loop. The until command appeared to step back to the beginning of the loop when it advanced to this expression; however, it hasn't really gone to an earlier statement—not in terms of the actual machine code.
An until command with no argument works by means of single instruction stepping, and hence is slower than until with an argument.
It's often useful to do display/i $pc when stepping by machine instructions. This makes GDB automatically display the next instruction to be executed, each time your program stops. See “Automatic display.”
The count argument is a repeat count, as in step.
The count argument is a repeat count, as in next.
A signal is an asynchronous event that can happen in a program. The operating system defines the possible kinds of signals, and gives each kind a name and a number. The table below gives several examples of signals:
| Signal: | Received when: |
|---|---|
| SIGINT | You type an interrupt, Ctrl-C |
| SIGSEGV | The program references a place in memory far away from all the areas in use. |
| SIGALRM | The alarm clock timer goes off (which happens only if your program has requested an alarm). |
Some signals, including SIGALRM, are a normal part of the functioning of your program. Others, such as SIGSEGV, indicate errors; these signals are fatal (killing your program immediately) if the program hasn't specified in advance some other way to handle the signal. SIGINT doesn't indicate an error in your program, but it's normally fatal so it can carry out the purpose of the interrupt: to kill the program.
GDB has the ability to detect any occurrence of a signal in your program. You can tell GDB in advance what to do for each kind of signal. Normally, it's set up to:
You can change these settings with the handle command.
The keywords allowed by the handle command can be abbreviated. Their full names are:
When a signal stops your program, the signal isn't visible until you continue. Your program sees the signal then, if pass is in effect for the signal in question at that time. In other words, after GDB reports a signal, you can use the handle command with pass or nopass to control whether your program sees that signal when you continue.
You can also use the signal command to prevent your program from seeing a signal, or cause it to see a signal it normally doesn't see, or to give it any signal at any time. For example, if your program stopped due to some sort of memory reference error, you might store correct values into the erroneous variables and continue, hoping to see more execution; but your program would probably terminate immediately as a result of the fatal signal once it saw the signal. To prevent this, you can continue with signal 0. See “Giving your program a signal.”
When your program has multiple threads (see “Debugging programs with multiple threads”), you can choose whether to set breakpoints on all threads, or on a particular thread.
Use the qualifier thread threadno with a breakpoint command to specify that you want GDB to stop the program only when a particular thread reaches this breakpoint. The threadno is one of the numeric thread identifiers assigned by GDB, shown in the first column of the info threads display.
If you don't specify thread threadno when you set a breakpoint, the breakpoint applies to all threads of your program.
You can use the thread qualifier on conditional breakpoints as well; in this case, place thread threadno before the breakpoint condition, like this:
(gdb) break frik.c:13 thread 28 if bartab > lim
Whenever your program stops under GDB for any reason, all threads of execution stop, not just the current thread. This lets you examine the overall state of the program, including switching between threads, without worrying that things may change underfoot.
Conversely, whenever you restart the program, all threads start executing. This is true even when single-stepping with commands like step or next.
In particular, GDB can't single-step all threads in lockstep. Since thread scheduling is up to the Neutrino microkernel (not controlled by GDB), other threads may execute more than one statement while the current thread completes a single step. Moreover, in general, other threads stop in the middle of a statement, rather than at a clean statement boundary, when the program stops.
You might even find your program stopped in another thread after continuing or even single-stepping. This happens whenever some other thread runs into a breakpoint, a signal, or an exception before the first thread completes whatever you requested.
This section includes:
When your program has stopped, the first thing you need to know is where it stopped and how it got there.
Each time your program performs a function call, information about the call is generated. That information includes the location of the call in your program, the arguments of the call, and the local variables of the function being called. The information is saved in a block of data called a stack frame. The stack frames are allocated in a region of memory called the call stack.
When your program stops, the GDB commands for examining the stack allow you to see all of this information.
One of the stack frames is selected by GDB, and many GDB commands refer implicitly to the selected frame. In particular, whenever you ask GDB for the value of a variable in your program, the value is found in the selected frame. There are special GDB commands to select whichever frame you're interested in. See “Selecting a frame.”
When your program stops, GDB automatically selects the currently executing frame and describes it briefly, similar to the frame command (see “Information about a frame”).
The call stack is divided up into contiguous pieces called stack frames, or frames for short; each frame is the data associated with one call to one function. The frame contains the arguments given to the function, the function's local variables, and the address at which the function is executing.
When your program is started, the stack has only one frame, that of the function main(). This is called the initial frame or the outermost frame. Each time a function is called, a new frame is made. Each time a function returns, the frame for that function invocation is eliminated. If a function is recursive, there can be many frames for the same function. The frame for the function in which execution is actually occurring is called the innermost frame. This is the most recently created of all the stack frames that still exist.
Inside your program, stack frames are identified by their addresses. A stack frame consists of many bytes, each of which has its own address; each kind of computer has a convention for choosing one byte whose address serves as the address of the frame. Usually this address is kept in a register called the frame pointer register while execution is going on in that frame.
GDB assigns numbers to all existing stack frames, starting with 0 for the innermost frame, 1 for the frame that called it, and so on upward. These numbers don't really exist in your program; they're assigned by GDB to give you a way of designating stack frames in GDB commands.
Some compilers provide a way to compile functions so that they operate without stack frames. (For example, the gcc option -fomit-frame-pointer generates functions without a frame.) This is occasionally done with heavily used library functions to reduce the time required to set up the frame. GDB has limited facilities for dealing with these function invocations. If the innermost function invocation has no stack frame, GDB nevertheless regards it as though it had a separate frame, which is numbered 0 as usual, allowing correct tracing of the function call chain. However, GDB has no provision for frameless functions elsewhere in the stack.
A backtrace is a summary of how your program got where it is. It shows one line per frame, for many frames, starting with the currently executing frame (frame 0), followed by its caller (frame 1), and on up the stack.
You can stop the backtrace at any time by typing the system interrupt character, normally Ctrl-C.
The names where and info stack ( info s) are additional aliases for backtrace.
Each line in the backtrace shows the frame number and the function name. The program counter value is also shown—unless you use set print address off. The backtrace also shows the source filename and line number, as well as the arguments to the function. The program counter value is omitted if it's at the beginning of the code for that line number.
Here's an example of a backtrace. It was made with the command bt 3, so it shows the innermost three frames:
#0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8)
at builtin.c:993
#1 0x6e38 in expand_macro (sym=0x2b600) at macro.c:242
#2 0x6840 in expand_token (obs=0x0, t=177664, td=0xf7fffb08)
at macro.c:71
(More stack frames follow...)
The display for frame 0 doesn't begin with a program counter value, indicating that your program has stopped at the beginning of the code for line 993 of builtin.c.
Most commands for examining the stack and other data in your program work on whichever stack frame is selected at the moment. Here are the commands for selecting a stack frame; all of them finish by printing a brief description of the stack frame just selected.
On the MIPS architecture, frame needs two addresses: a stack pointer and a program counter.
All of these commands end by printing two lines of output describing the frame. The first line shows the frame number, the function name, the arguments, and the source file and line number of execution in that frame. The second line shows the text of that source line.
For example:
(gdb) up
#1 0x22f0 in main (argc=1, argv=0xf7fffbf4, env=0xf7fffbfc)
at env.c:10
10 read_input_file (argv[i]);
After such a printout, the list command with no arguments prints ten lines centered on the point of execution in the frame. See “Printing source lines.”
There are several other commands to print information about the selected stack frame:
The verbose description is useful when something has gone wrong that has made the stack format fail to fit the usual conventions.
MIPS-based computers use an unusual stack frame, which sometimes requires GDB to search backward in the object code to find the beginning of a function.
To improve response time — especially for embedded applications, where GDB may be restricted to a slow serial line for this search — you may want to limit the size of this search, using one of these commands:
These commands are available only when GDB is configured for debugging programs on MIPS processors.
This section includes:
GDB can print parts of your program's source, since the debugging information recorded in the program tells GDB what source files were used to build it. When your program stops, GDB spontaneously prints the line where it stopped. Likewise, when you select a stack frame (see “Selecting a frame”), GDB prints the line where execution in that frame has stopped. You can print other portions of source files by explicit command.
To print lines from a source file, use the list (l) command. By default, ten lines are printed. There are several ways to specify what part of the file you want to print. Here are the forms of the list command most commonly used:
By default, GDB prints ten source lines with any of these forms of the list command. You can change this using set listsize:
Repeating a list command with Enter discards the argument, so it's equivalent to typing just list. This is more useful than listing the same lines again. An exception is made for an argument of -; that argument is preserved in repetition so that each repetition moves up in the source file.
In general, the list command expects you to supply zero, one or two linespecs. Linespecs specify source lines; there are several ways of writing them but the effect is always to specify some source line. Here's a complete description of the possible arguments for list:
Here are the ways of specifying a single source line—all the kinds of linespec:
The commands for searching through the current source file for a regular expression are:
Executable programs sometimes don't record the directories of the source files from which they were compiled, just the names. Even when they do, the directories could be moved between the compilation and your debugging session. GDB has a list of directories to search for source files; this is called the source path. Each time GDB wants a source file, it tries all the directories in the list, in the order they're present in the list, until it finds a file with the desired name.
|
The executable search path isn't used for this purpose. Neither is the current working directory, unless it happens to be in the source path. |
If GDB can't find a source file in the source path, and the object program records a directory, GDB tries that directory too. If the source path is empty, and there's no record of the compilation directory, GDB looks in the current directory as a last resort.
Whenever you reset or rearrange the source path, GDB clears out any information it has cached about where source files are found and where each line is in the file.
When you start GDB, its source path is empty. To add other directories, use the directory command.
You can use the string $cdir to refer to the compilation directory (if one is recorded), and $cwd to refer to the current working directory. Note that $cwd isn't the same as a period (.); the former tracks the current working directory as it changes during your GDB session, while the latter is immediately expanded to the current directory at the time you add an entry to the source path.
If your source path is cluttered with directories that are no longer of interest, GDB may sometimes cause confusion by finding the wrong versions of source. You can correct the situation as follows:
You can use the command info line to map source lines to program addresses (and vice versa), and the command disassemble to display a range of addresses as machine instructions. When run under GNU Emacs mode, the info line command causes the arrow to point to the line specified. Also, info line prints addresses in symbolic form as well as hex.
For example, we can use info line to discover the location of the object code for the first line of function m4_changequote:
(gdb) info line m4_changecom Line 895 of "builtin.c" starts at pc 0x634c and ends at 0x6350.
We can also inquire (using *addr as the form for linespec) what source line covers a particular address:
(gdb) info line *0x63ff Line 926 of "builtin.c" starts at pc 0x63e4 and ends at 0x6404.
After info line, the default address for the x command is changed to the starting address of the line, so that x/i is sufficient to begin examining the machine code (see “Examining memory”). Also, this address is saved as the value of the convenience variable $_ (see “Convenience variables”).
We can use disassemble to inspect the object code range shown in the last info line example (the example shows SPARC machine instructions):
(gdb) disas 0x63e4 0x6404 Dump of assembler code from 0x63e4 to 0x6404: 0x63e4 <builtin_init+5340>: ble 0x63f8 <builtin_init+5360> 0x63e8 <builtin_init+5344>: sethi %hi(0x4c00), %o0 0x63ec <builtin_init+5348>: ld [%i1+4], %o0 0x63f0 <builtin_init+5352>: b 0x63fc <builtin_init+5364> 0x63f4 <builtin_init+5356>: ld [%o0+4], %o0 0x63f8 <builtin_init+5360>: or %o0, 0x1a4, %o0 0x63fc <builtin_init+5364>: call 0x9288 <path_search> 0x6400 <builtin_init+5368>: nop End of assembler dump.
Currently it's defined only for the Intel x86 family. You can set instruction-set to either i386 or i8086. The default is i386.
You can use the following commands when working with shared libraries:
The following parameters apply to shared libraries:
You can query the settings of these parameters with the show solib-search-path, show solib-absolute-prefix, and show auto-solib-add commands.
This section includes:
The usual way to examine data in your program is with the print (p) command or its synonym inspect. It evaluates and prints the value of an expression of the language your program is written in.
A lower-level way of examining data is with the x command. It examines data in memory at a specified address and prints it in a specified format. See “Examining memory.”
If you're interested in information about types, or about how the fields of a structure or class are declared, use the ptype exp command rather than print. See “Examining the symbol table.”
The print command and many other GDB commands accept an expression and compute its value. Any kind of constant, variable or operator defined by the programming language you're using is valid in an expression in GDB. This includes conditional expressions, function calls, casts and string constants. It unfortunately doesn't include symbols defined by preprocessor #define commands.
GDB supports array constants in expressions input by the user. The syntax is {element, element...}. For example, you can use the command print {1, 2, 3} to build up an array in memory that is malloc'd in the target program.
Because C is so widespread, most of the expressions shown in examples in this manual are in C. In this section, we discuss operators that you can use in GDB expressions regardless of your programming language.
Casts are supported in all languages, not just in C, because it's useful to cast a number into a pointer in order to examine a structure at that address in memory.
GDB supports these operators, in addition to those common to programming languages:
The most common kind of expression to use is the name of a variable in your program.
Variables in expressions are understood in the selected stack frame (see “Selecting a frame”); they must be either:
Or:
This means that in the function:
foo (a)
int a;
{
bar (a);
{
int b = test ();
bar (b);
}
}
you can examine and use the variable a whenever your program is executing within the function foo(), but you can use or examine the variable b only while your program is executing inside the block where b is declared.
There's an exception: you can refer to a variable or function whose scope is a single source file even if the current execution point isn't in this file. But it's possible to have more than one such variable or function with the same name (in different source files). If that happens, referring to that name has unpredictable effects. If you wish, you can specify a static variable in a particular function or file, using the colon-colon notation:
file::variable function::variable
Here file or function is the name of the context for the static variable. In the case of filenames, you can use quotes to make sure GDB parses the filename as a single word. For example, to print a global value of x defined in f2.c:
(gdb) p 'f2.c'::x
This use of :: is very rarely in conflict with the very similar use of the same notation in C++. GDB also supports use of the C++ scope resolution operator in GDB expressions.
|
Occasionally, a local variable may appear to have the
wrong value at certain points in a function, such as just after entry to a new
scope, and just before exit.
You may see this problem when you're stepping by machine instructions. This is because, on most machines, it takes more than one instruction to set up a stack frame (including local variable definitions); if you're stepping by machine instructions, variables may appear to have the wrong values until the stack frame is completely built. On exit, it usually also takes more than one machine instruction to destroy a stack frame; after you begin stepping through that group of instructions, local variable definitions may be gone. |
It's often useful to print out several successive objects of the same type in memory; a section of an array, or an array of dynamically determined size for which only a pointer exists in the program.
You can do this by referring to a contiguous span of memory as an artificial array, using the binary operator @. The left operand of @ should be the first element of the desired array and be an individual object. The right operand should be the desired length of the array. The result is an array value whose elements are all of the type of the left operand. The first element is actually the left operand; the second element comes from bytes of memory immediately following those that hold the first element, and so on. For example, if a program says:
int *array = (int *) malloc (len * sizeof (int));
you can print the contents of array with:
p *array@len
The left operand of @ must reside in memory. Array values made with @ in this way behave just like other arrays in terms of subscripting, and are coerced to pointers when used in expressions. Artificial arrays most often appear in expressions via the value history (see “Value history”), after printing one out.
Another way to create an artificial array is to use a cast. This reinterprets a value as if it were an array. The value need not be in memory:
(gdb) p/x (short[2])0x12345678
$1 = {0x1234, 0x5678}
As a convenience, if you leave the array length out — as in (type[])value — gdb calculates the size to fill the value as sizeof(value)/sizeof(type). For example:
(gdb) p/x (short[])0x12345678
$2 = {0x1234, 0x5678}
Sometimes the artificial array mechanism isn't quite enough; in moderately complex data structures, the elements of interest may not actually be adjacent—for example, if you're interested in the values of pointers in an array. One useful workaround in this situation is to use a convenience variable (see “Convenience variables”) as a counter in an expression that prints the first interesting value, and then repeat that expression via Enter. For instance, suppose you have an array dtab of pointers to structures, and you're interested in the values of a field fv in each structure. Here's an example of what you might type:
set $i = 0 p dtab[$i++]->fv Enter Enter ...
By default, GDB prints a value according to its data type. Sometimes this isn't what you want. For example, you might want to print a number in hex, or a pointer in decimal. Or you might want to view data in memory at a certain address as a character string or as an instruction. To do these things, specify an output format when you print a value.
The simplest use of output formats is to say how to print a value already computed. This is done by starting the arguments of the print command with a slash and a format letter. The format letters supported are:
(gdb) p/a 0x54320 $3 = 0x54320 <_initialize_vx+396>
For example, to print the program counter in hex (see “Registers”), type:
p/x $pc
|
No space is required before the slash; this is because command names in GDB can't contain a slash. |
To reprint the last value in the value history with a different format, you can use the print command with just a format and no expression. For example, p/x reprints the last value in hex.
You can use the command x (for “examine”) to examine memory in any of several formats, independently of your program's data types.
The n, f, and u are all optional parameters that specify how much memory to display and how to format it; addr is an expression giving the address where you want to start displaying memory. If you use defaults for nfu, you need not type the slash /. Several commands set convenient defaults for addr.
Each time you specify a unit size with x, that size becomes the default unit the next time you use x. (For the s and i formats, the unit size is ignored and isn't normally written.)
For example, x/3uh 0x54320 is a request to display three halfwords (h) of memory, formatted as unsigned decimal integers (u), starting at address 0x54320. The x/4xw $sp command prints the four words (w) of memory above the stack pointer (here, $sp; see “Registers”) in hexadecimal (x).
Since the letters indicating unit sizes are all distinct from the letters specifying output formats, you don't have to remember whether unit size or format comes first; either order works. The output specifications 4xw and 4wx mean exactly the same thing. (However, the count n must come first; wx4 doesn't work.)
Even though the unit size u is ignored for the formats s and i, you might still want to use a count n; for example, 3i specifies that you want to see three machine instructions, including any operands. The command disassemble gives an alternative way of inspecting machine instructions; see “Source and machine code.”
All the defaults for the arguments to x are designed to make it easy to continue scanning memory with minimal specifications each time you use x. For example, after you've inspected three machine instructions with x/3i addr, you can inspect the next seven with just x/7. If you use Enter to repeat the x command, the repeat count n is used again; the other arguments default as for successive uses of x.
The addresses and contents printed by the x command aren't saved in the value history because there's often too much of them and they would get in the way. Instead, GDB makes these values available for subsequent use in expressions as values of the convenience variables $_ and $__. After an x command, the last address examined is available for use in expressions in the convenience variable $_. The contents of that address, as examined, are available in the convenience variable $__.
If the x command has a repeat count, the address and contents saved are from the last memory unit printed; this isn't the same as the last address printed if several units were printed on the last line of output.
If you find that you want to print the value of an expression frequently (to see how it changes), you might want to add it to the automatic display list so that GDB prints its value each time your program stops. Each expression added to the list is given a number to identify it; to remove an expression from the list, you specify that number. The automatic display looks like this:
2: foo = 38 3: bar[5] = (struct hack *) 0x3804
This display shows item numbers, expressions and their current values. As with displays you request manually using x or print, you can specify the output format you prefer; in fact, display decides whether to use print or x depending on how elaborate your format specification is—it uses x if you specify a unit size, or one of the two formats (i and s) that are supported only by x; otherwise it uses print.
For example, display/i $pc can be helpful, to see the machine instruction about to be executed each time execution stops ($pc is a common name for the program counter; see “Registers”).
The undisplay command doesn't repeat if you press Enter after using it. (Otherwise you'd just get the error No display number ....)
If a display expression refers to local variables, it doesn't make sense outside the lexical context for which it was set up. Such an expression is disabled when execution enters a context where one of its variables isn't defined.
For example, if you give the command display last_char while inside a function with an argument last_char, GDB displays this argument while your program continues to stop inside that function. When it stops where there's no variable last_char, the display is disabled automatically. The next time your program stops where last_char is meaningful, you can enable the display expression once again.
GDB provides the following ways to control how arrays, structures, and symbols are printed.
These settings are useful for debugging programs in any language:
(gdb) f
#0 set_quotes (lq=0x34c78 "<<", rq=0x34c88 ">>")
at input.c:530
530 if (lquote != def_lquote)
(gdb) set print addr off (gdb) f #0 set_quotes (lq="<<", rq=">>") at input.c:530 530 if (lquote != def_lquote)You can use set print address off to eliminate all machine-dependent displays from the GDB interface. For example, with print address off, you should get the same text for backtraces on all machines—whether or not they involve pointer arguments.
When GDB prints a symbolic address, it normally prints the closest earlier symbol plus an offset. If that symbol doesn't uniquely identify the address (for example, it's a name whose scope is a single source file), you may need to clarify. One way to do this is with info line, for example info line *0x4537. Alternately, you can set GDB to print the source file and line number when it prints a symbolic address:
Another situation where it's helpful to show symbol filenames and line numbers is when disassembling code; GDB shows you the line number and source file that correspond to each instruction.
Also, you may wish to see the symbolic form only if the address being printed is reasonably close to the closest earlier symbol:
If you have a pointer and you aren't sure where it points, try set print symbol-filename on. Then you can determine the name and source file location of the variable where it points, using p/a pointer. This interprets the address in symbolic form. For example, here GDB shows that a variable ptt points at another variable t, defined in hi2.c:
(gdb) set print symbol-filename on (gdb) p/a ptt $4 = 0xe008 <t in hi2.c>
|
For pointers that point to a local variable, p/a doesn't show the symbol name and filename of the referent, even with the appropriate set print options turned on. |
Other settings control how different kinds of objects are printed:
$1 = {
next = 0x0,
flags = {
sweet = 1,
sour = 1
},
meat = 0x54 "Pork"
}
$1 = {next = 0x0, flags = {sweet = 1, sour = 1}, \
meat = 0x54 "Pork"}
This is the default format.
typedef enum {Tree, Bug} Species;
typedef enum {Big_tree, Acorn, Seedling} Tree_forms;
typedef enum {Caterpillar, Cocoon, Butterfly}
Bug_forms;
struct thing {
Species it;
union {
Tree_forms tree;
Bug_forms bug;
} form;
};
struct thing foo = {Tree, {Acorn}};
with set print union on in effect, p foo prints:
$1 = {it = Tree, form = {tree = Acorn, bug = Cocoon}}
and with set print union off in effect, it prints:
$1 = {it = Tree, form = {...}}
These settings are of interest when debugging C++ programs:
This setting alone isn't sufficient to allow debugging cfront-generated executables. GDB would require further enhancement to permit that.
Values printed by the print command are saved in the GDB value history. This lets you refer to them in other expressions. Values are kept until the symbol table is reread or discarded (for example with the file or symbol-file commands). When the symbol table changes, the value history is discarded, since the values may contain pointers back to the types defined in the symbol table.
The values printed are given history numbers, which you can use to refer to them. These are successive integers starting with 1. The print command shows you the history number assigned to a value by printing $num = before the value; here num is the history number.
To refer to any previous value, use $ followed by the value's history number. The way print labels its output is designed to remind you of this. Just $ refers to the most recent value in the history, and $$ refers to the value before that. $$n refers to the nth value from the end; $$2 is the value just prior to $$, $$1 is equivalent to $$, and $$0 is equivalent to $.
For example, suppose you have just printed a pointer to a structure and want to see the contents of the structure. It suffices to type:
p *$
If you have a chain of structures where the component next points to the next one, you can print the contents of the next one with this:
p *$.next
You can print successive links in the chain by repeating this command—which you can do by just typing Enter.
|
The history records values, not expressions. If the value of
x is 4 and you type these commands:
print x set x=5 then the value recorded in the value history by the print command remains 4 even though the value of x has changed. |
Pressing Enter to repeat show values n has exactly the same effect as show values +.
GDB provides convenience variables that you can use within GDB to hold on to a value and refer to it later. These variables exist entirely within GDB; they aren't part of your program, and setting a convenience variable has no direct effect on further execution of your program. That's why you can use them freely.
Convenience variables are prefixed with $. Any name preceded by $ can be used for a convenience variable, unless it's one of the predefined machine-specific register names (see “Registers”). Value history references, in contrast, are numbers preceded by $. See “Value history.”
You can save a value in a convenience variable with an assignment expression, just as you'd set a variable in your program. For example:
set $foo = *object_ptr
saves in $foo the value contained in the object pointed to by object_ptr.
Using a convenience variable for the first time creates it, but its value is void until you assign a new value. You can alter the value with another assignment at any time.
Convenience variables have no fixed types. You can assign to a convenience variable any type of value, including structures and arrays, even if that variable already has a value of a different type. The convenience variable, when used as an expression, has the type of its current value.
One of the ways to use a convenience variable is as a counter to be incremented or a pointer to be advanced. For example, to print a field from successive elements of an array of structures:
set $i = 0 print bar[$i++]->contents
Repeat that command by pressing Enter.
Some convenience variables are created automatically by GDB and given values likely to be useful:
You can refer to machine register contents, in expressions, as variables with names starting with $. The names of registers are different for each machine; use info registers to see the names used on your machine.
GDB has four “standard” register names that are available (in expressions) on most machines—whenever they don't conflict with an architecture's canonical mnemonics for registers:
For example, you could print the program counter in hex with:
p/x $pc
or print the instruction to be executed next with:
x/i $pc
or add four to the stack pointer with:
set $sp += 4
|
This is a way of removing one word from the stack, on machines where stacks grow downward in memory (most machines, nowadays). This assumes that the innermost stack frame is selected; setting $sp isn't allowed when other stack frames are selected. To pop entire frames off the stack, regardless of machine architecture, use the Enter key. |
Whenever possible, these four standard register names are available on your machine even though the machine has different canonical mnemonics, so long as there's no conflict. The info registers command shows the canonical names.
GDB always considers the contents of an ordinary register as an integer when the register is examined in this way. Some machines have special registers that can hold nothing but floating point; these registers are considered to have floating point values. There's no way to refer to the contents of an ordinary register as floating point value (although you can print it as a floating point value with print/f $regname).
Some registers have distinct “raw” and “virtual” data formats. This means that the data format in which the register contents are saved by the operating system isn't the same one that your program normally sees. For example, the registers of the 68881 floating point coprocessor are always saved in “extended” (raw) format, but all C programs expect to work with “double” (virtual) format. In such cases, GDB normally works with the virtual format only (the format that makes sense for your program), but the info registers command prints the data in both formats.
Normally, register values are relative to the selected stack frame (see “Selecting a frame”). This means that you get the value that the register would contain if all stack frames farther in were exited and their saved registers restored. In order to see the true contents of hardware registers, you must select the innermost frame (with frame 0).
However, GDB must deduce where registers are saved, from the machine code generated by your compiler. If some registers aren't saved, or if GDB is unable to locate the saved registers, the selected stack frame makes no difference.
Depending on the configuration, GDB may be able to give you more information about the status of the floating point hardware.
The commands described in this section allow you to inquire about the symbols (names of variables, functions and types) defined in your program. This information is inherent in the text of your program and doesn't change as your program executes. GDB finds it in your program's symbol table, in the file indicated when you started GDB (see the description of the gdb utility).
Occasionally, you may need to refer to symbols that contain unusual characters, which GDB ordinarily treats as word delimiters. The most frequent case is in referring to static variables in other source files (see “Program variables”). Filenames are recorded in object files as debugging symbols, but GDB ordinarily parses a typical filename, like foo.c, as the three words foo, ., and c. To allow GDB to recognize foo.c as a single symbol, enclose it in single quotes. For example:
p 'foo.c'::x
looks up the value of x in the scope of the file foo.c.
Note the contrast with print &symbol, which doesn't work at all for a register variable, and for a stack local variable prints the exact address of the current instantiation of the variable.
struct complex {double real; double imag;} v;
the two commands give this output:
(gdb) whatis v
type = struct complex
(gdb) ptype v
type = struct complex {
double real;
double imag;
}
As with whatis, using ptype without an argument refers to the type of $, the last value in the value history.
This command differs from ptype in two ways: first, like whatis, it doesn't print a detailed description; second, it lists all source files where a type is defined.
Some systems allow individual object files that make up your program to be replaced without stopping and restarting your program. If you're running on one of these systems, you can allow GDB to reload the symbols for automatically relinked modules:
This section includes:
Once you think you've found an error in your program, you might want to find out for certain whether correcting the apparent error would lead to correct results in the rest of the run. You can find the answer by experimenting, using the GDB features for altering execution of the program.
For example, you can store new values in variables or memory locations, give your program a signal, restart it at a different address, or even return prematurely from a function.
To alter the value of a variable, evaluate an assignment expression. See “Expressions”. For example,
print x=4
stores the value 4 in the variable x and then prints the value of the assignment expression (which is 4).
If you aren't interested in seeing the value of the assignment, use the set command instead of the print command. The set command is really the same as print except that the expression's value isn't printed and isn't put in the value history (see “Value history”). The expression is evaluated only for its effects.
If the beginning of the argument string of the set command appears identical to a set subcommand, use the set variable command instead of just set. This command is identical to set except for its lack of subcommands. For example, if your program has a variable width, you get an error if you try to set a new value with just set width=13, because GDB has the command set width:
(gdb) whatis width type = double (gdb) p width $4 = 13 (gdb) set width=47 Invalid syntax in expression.
The invalid expression, of course, is =47. In order to actually set the program's variable width, use:
(gdb) set var width=47
GDB allows more implicit conversions in assignments than C; you can freely store an integer value into a pointer variable or vice versa, and you can convert any structure to any other structure that is the same length or shorter.
To store values into arbitrary places in memory, use the {...} construct to generate a value of specified type at a specified address (see “Expressions”). For example, {int}0x83040 refers to memory location 0x83040 as an integer (which implies a certain size and representation in memory), and:
set {int}0x83040 = 4
stores the value 4 in that memory location.
Ordinarily, when you continue your program, you do so at the place where it stopped, with the continue command. You can instead continue at an address of your own choosing, with the following commands:
The jump command doesn't change the current stack frame, or the stack pointer, or the contents of any memory location or any register other than the program counter. If line linespec is in a different function from the one currently executing, the results may be bizarre if the two functions expect different patterns of arguments or of local variables. For this reason, the jump command requests confirmation if the specified line isn't in the function currently executing. However, even bizarre results are predictable if you're well acquainted with the machine-language code of your program.
You can get much the same effect as the jump command by storing a new value in the register $pc. The difference is that this doesn't start your program running; it only changes the address of where it will run when you continue. For example:
set $pc = 0x485
makes the next continue command or stepping command execute at address 0x485, rather than at the address where your program stopped. See “Continuing and stepping.”
The most common occasion to use the jump command is to back up — perhaps with more breakpoints set — over a portion of a program that has already executed, in order to examine its execution in more detail.
Alternatively, if signal is zero, continue execution without giving a signal. This is useful when your program stopped on account of a signal and would ordinary see the signal when resumed with the continue command; signal 0 causes it to resume without a signal.
The signal command doesn't repeat when you press Enter a second time after executing the command.
Invoking the signal command isn't the same as invoking the kill utility from the shell. Sending a signal with kill causes GDB to decide what to do with the signal depending on the signal handling tables (see “Signals”). The signal command passes the signal directly to your program.
When you use return, GDB discards the selected stack frame (and all frames within it). You can think of this as making the discarded frame return prematurely. If you wish to specify a value to be returned, give that value as the argument to return.
This pops the selected stack frame (see “Selecting a frame”) and any other frames inside it, leaving its caller as the innermost remaining frame. That frame becomes selected. The specified value is stored in the registers used for returning values of functions.
The return command doesn't resume execution; it leaves the program stopped in the state that would exist if the function had just returned. In contrast, the finish command (see “Continuing and stepping”) resumes execution until the selected stack frame returns naturally.
You can use this variant of the print command if you want to execute a function from your program, but without cluttering the output with void returned values. If the result isn't void, it's printed and saved in the value history.
A user-controlled variable, call_scratch_address, specifies the location of a scratch area to be used when GDB calls a function in the target. This is necessary because the usual method of putting the scratch area on the stack doesn't work in systems that have separate instruction and data spaces.
By default, GDB opens the file containing your program's executable code (or the core file) read-only. This prevents accidental alterations to machine code; but it also prevents you from intentionally patching your program's binary.
If you'd like to be able to patch the binary, you can specify that explicitly with the set write command. For example, you might want to turn on internal debugging flags, or even to make emergency repairs.
If you've already loaded a file, you must load it again (using the exec-file or core-file command) after changing set write for your new setting to take effect.
|
|
|
|