< Day Day Up > |
The following alphabetical summary of GDB commands includes all those that are useful for day-to-day debugging. Esoteric commands, such as those used by GDB's maintainers, or to cross-debug remote systems connected via serial port or a network, have been omitted. Many of these commands may be abbreviated. The list of abbreviations is provided in the earlier section "Aliases for Other Commands."
add-symbol-file file addr [-readnow] add-symbol-file file [-s section address ...] Read additional symbol table information from file, which was dynamically loaded into the debuggee outside of GDB's knowledge. You must tell GDB the address at which it was loaded, since GDB cannot determine this on its own. The -readnow option is the same as for the file command; see file for more information. You may use -s to name the memory starting at address with the name section. You can provide multiple section/address pairs with multiple -s options.
advance bp-spec Continue executing until the program reaches bp-spec, which can have any value acceptable to the break command (see break for the details). This command is like the until command, but it does not skip recursive function calls, and the location doesn't have to be in the current frame.
apropos regex Search through the built-in documentation for commands that match the regular expression regex. Multiple words constitute a single regular expression. GDB uses Basic Regular Expressions (see Chapter 7); however, it also ignores case when matching.
attach pid Attach to the running process pid, and use it to obtain information about in-memory data. You must have appropriate permission in order to attach to a running process.
awatch expression Set a watchpoint to stop when expression is either read or written. (Compare rwatch and watch.)
backtrace [count] Print a full list of all stack frames. With a positive count, print only the innermost count stack frames. With a negative count, print only the outermost count stack frames. ExampleShow a backtrace upon hitting a breakpoint: ... Breakpoint 1, do_print (tree=0x924f9e0) at builtin.c:1573 1573 struct redirect *rp = NULL; (gdb) backtrace #0 do_print (tree=0x924f9e0) at builtin.c:1573 #1 0x08087bef in interpret (tree=0x924f9e0) at eval.c:784 #2 0x08086b68 in interpret (tree=0x924f980) at eval.c:453 #3 0x08072804 in main (argc=2, argv=0xbfe41bd4) at main.c:584
break [bp-spec] break bp-specif condition break bp-spec tHRead threadnum break bp-spec thread threadnum if condition Set a breakpoint. The first form sets an unconditional breakpoint; execution of the debuggee stops when the breakpoint is reached. The second form sets a conditional breakpoint: when the breakpoint is reached, GDB evaluates the condition. If the condition is true, execution stops. If it isn't, the program continues. In either case, bp-spec is one of the items given in the following section. The third and fourth forms are similar to the first and second ones respectively; however, they work on individual threads of control running within the debuggee. They specify that GDB should stop the program only when the given thread threadnum reaches the point specified by bp-spec. Breakpoint SpecificationsThe following list shows the different forms that the break command can take.
A breakpoint set at a line or statement stops when the first instruction in that statement is reached. ExampleSet a breakpoint in the main( ) function: $ gdb whizprog GNU gdb 6.3 ... (gdb) break main Breakpoint 1 at 0x80483c0: file whizprog.c, line 6.
call expression Call a function within the debuggee. expression is a function name and parameter list. Non-void results are printed and saved in the value history.
catch event Place a catchpoint. Execution stops when the specified event occurs. Catchpoint Events
cd dir Change GDB 's working directory to dir.
clear [bp-spec] Clear a breakpoint. The argument is the same as for the break command (see break).
commands [bp] ... commands ... end Supply GDB commands that should run when the program stops at a given breakpoint. With no bp, the list of commands is associated with the most recent breakpoint, watchpoint, or catchpoint that was set, not the one that was most recently executed. To clear a list of commands, supply the commands keyword and follow it immediately with end. Examplebreak myfunc if x > 42 Break myfunc if x > 42 commands List of commands silent Don't print GDB commands printf "x = %d\n", x Print variable value cont Continue execution end End of command list
complete prefix Show possible command completions for prefix. This is intended for Emacs when running GDB in an Emacs buffer.
condition bpcondition bp expression Add or remove a condition to a given breakpoint. The first syntax removes any condition associated with breakpoint number bp. The second form adds expression as a condition for breakpoint number bp, similar to the break ... if command. See also break.
continue [count] Resume execution after stopping at a breakpoint. If supplied, count is an ignore count; see the entry for ignore. ExampleSet a breakpoint in main( ). Once there, set another break point and then continue until the new breakpoint is reached. (gdb) break main Breakpoint 3 at 0x8071d2e: file main.c, line 209. (gdb) run ... Starting program: ... Breakpoint 3, main (argc=2, argv=0xbff59f04) at main.c:209 209 const char *optlist = "+F:f:v:W;m:D"; (gdb) break do_print Breakpoint 4 at 0x805b239: file builtin.c, line 1573. (gdb) continue Continuing. Breakpoint 4, do_print (tree=0x91589e0) at builtin.c:1573 1573 struct redirect *rp = NULL;
core-file [filename] With no argument, indicate that there is no separate core file. Otherwise, treat filename as the file to use as a core file; that is, a file containing a dump of memory from an executing program.
define commandname... commands ... end Create a user-defined command named commandname. The series of commands makes up the definition of commandname. Whenever you type commandname, GDB executes the commands. This is similar to functions or procedures in regular programming languages. See also document. HooksIf commandname has the form hook-command, where command is a built-in GDB command, when you enter command GDB runs commandname before it runs command. Similarly, if commandname has the form hookpost-command, then GDB runs the provided sequence of commands after command finishes. You thus have available both pre- and post-execution hook facilities. Finally, for the purposes of providing hooks, GDB recognizes a pseudo-command named stop that "executes" every time the debuggee stops. This allows you to define a hook of the form hook-stop in order to execute a sequence of commands every time the program stops.
delete [breakpoints] [range ...] delete display dnums ... delete mem mnums ... For the first syntax, remove the given range of breakpoints, watchpoints, or catchpoints. With no arguments, delete all breakpoints. (GDB may prompt for confirmation depending upon the setting of set confirm.) The second syntax removes items from the automatic display list (created with display); see display for more information. The third syntax removes defined memory regions created with mem; see mem for more information.
detach Detach the debugger from the running process previously attached to with attach.
directory [dirname ...] Add dirname to the list of directories that GDB searches when attempting to find source files. The directory is added to the front of the search path. With no argument, clear the directory search path.
disable [breakpoints] [range ...] disable display dnums ... disable mem mnums ... With the first syntax, disable the breakpoints in range, or all breakpoints if these are not supplied. GDB remembers disabled breakpoints, but they do not affect execution of the debuggee. The second syntax disables item(s) dnums in the automatic display list; see display for more information. The third syntax disables item(s) mnums in the list of defined memory regions; see mem for more information.
disassemble disassemble pc-valdisassemble start end Print a range of memory addresses as assembly code instructions. With no argument, print the entire current function. One argument is assumed to be a program counter value; the function containing this value is dumped. Two arguments specify a range of addresses to dump, from (and including) start up to (but not including) end.
display display/format expression Add expression (usually a variable or address) to the list of values that GDB automatically displays every time the debuggee stops. The format is one of the format letters accepted by the x command; see x for the full list. The trailing "/" and format immediately follow the display command. With no arguments, print the current values of the expressions on the display list.
document commandname ... text ...end Provide documentation for the user-defined command commandname. The documentation consists of the lines provided in text. After executing this command, help commandname displays text. See also define.
dont-repeat This command is designed for use inside user-defined commands (see define). It indicates that the user-defined command should not be repeated if the user presses ENTER.
down count Move down count stack frames. Positive values for count move towards more recent stack frames. See also frame and up.
down-silently count Same as the down command, but don't print any messages. This is intended mainly for use in GDB scripts.
echo strings ... Print strings. You may use the standard C escape sequences to generate nonprinting characters. In particular, you should use \n for newline. Note: unlike the shell-level echo command, GDB 's echo does not automatically supply a newline. You must explicitly request one if you want it.
edit [line-spec] Edit the lines in the source file as specified by line-spec. See list for values for line-spec. With no argument, edit the file containing the most recently listed line. This uses the value of $EDITOR as the editor, or ex if that environment variable is not set.
else Provide an alternate list of commands to execute if the expression in an if is false. Terminate the commands with end. See if.
enable [breakpoints] [range ...] enable [breakpoints] delete range ... enable [breakpoints] once range ... enable display dnums ... enable mem mnums ... The first syntax enables breakpoints; either all breakpoints if no range is supplied, or just the given breakpoints. The second syntax enables the specified breakpoints so that they stop the program when they're encountered, but are then deleted. The third syntax enables the specified breakpoints so that they stop the program when encountered, but then become disabled. The fourth syntax enables items in the automatic display list that were previously disabled with disable; for more information see display. The fifth syntax enables items in the list of defined memory regions; for more information, see mem.
end Terminate a list of commands provided with keywords commands, define, document, else, if, or while.
exec-file [filename] With no argument, discard all information about the executable file. Otherwise, treat filename as the file to execute. This command searches $PATH to find the file if necessary.
fg [count] An alias for continue; see continue.
file file filename [-readnow] The first syntax causes GDB to discard all its information on both the symbol file and the executable file. The second syntax treats filename as the file to be debugged; it is used both for symbol table information and as the program to run for the run command. The -readnow option forces GDB to load symbol table information immediately instead of waiting until information is needed.
finish Continue execution until the current stack frame (function) is about to return. This is most useful when you accidentally step into a function (using step) that does not have debugging information in it (such as a library function).
focus window Change the focus to TUI window window. Acceptable values for window are next, prev, src, asm, regs, and cmd.
forward-search regex Search forward from the current line for a line that matches the regular expression regex, and print it.
frame frame frame-numframe address Select or print information about the current stack frame (function invocation). Frame zero is the innermost (most recent) stack frame. With no arguments, print the current stack frame. With a frame-num, move to that frame. This is the most common kind of argument. An address argument may be used to select the frame at the given address. This is necessary if the chaining of stack frames has been damaged by a bug. Some architectures may require more than one address. ExampleMove up the call stack toward an older function: (gdb) where #0 do_print (tree=0x83579e0) at builtin.c:1573 #1 0x08087bef in interpret (tree=0x83579e0) at eval.c:784 #2 0x08086b68 in interpret (tree=0x8357980) at eval.c:453 #3 0x08072804 in main (argc=2, argv=0xbfeb8584) at main.c:584 (gdb) frame 2 #2 0x08086b68 in interpret (tree=0x8357980) at eval.c:453 453 (void) interpret(tree->rnode);
generate-core-file [file] Generate a core file from the state of the debuggee. With file, send the core dump to file. Otherwise, use a file named core.PID.
handle signal keywords ... Set GDB up to handle one or more signals. The signal may be a signal number, a signal name (with or without the SIG prefix), a range of the form low-high, or the keyword all. The keywords are one or more of the following:
hbreak bp-spec Set a hardware-assisted breakpoint. The argument is the same as for the break command (see break, earlier in this list). This command is intended for EEPROM/ROM code debugging; it allows you to set a breakpoint at a location without changing the location. However, not all systems have the necessary hardware for this.
help [command] With no arguments, print a list of subtopics for which help is available. With command, provide help on the given GDB command or group of commands.
if expression ... commands1 ...[ else ... commands2 ... ] end Conditionally execute a series of commands. If expression is true, execute commands1. If an else is present and the expression is false, execute commands2.
ignore bp count Set the ignore count on breakpoint, watchpoint, or catchpoint bp to count. GDB does not check conditions as long as the ignore count is positive.
inspect print-expressions An obsolete alias for the print command. See print for more information.
info [feature] Display information about feature, which concerns the state of the debuggee. With no arguments, provide a list of features about which information is available. Full details are provided in the section "Summary of the info Command," earlier in this chapter.
jump location Continue execution at location, which is either a line-spec as for the list command (see list), or a hexadecimal address preceded by a *. The continue command resumes execution where it stopped, while jump moves to a different place. If the location is not within the current frame, GDB asks for confirmation since GDB will not change the current setup of the machine registers (stack pointer, frame pointer, etc.).
kill Kill the process running the debuggee. This is most useful to force the production of a core dump for later debugging.
layout layout Change the layout of the TUI windows to layout. Acceptable values for layout are:
The command window is always displayed.
list functionlist line-spec List lines of source code, starting at the beginning of function function (first form), or centered around the line defined by line-spec (second form). Pressing the ENTER key repeats the last command; for list, this shows successive lines of source text. A line-spec can take one of the forms shown below. Line Specifications
macro expand expressionmacro expand-once expressionmacro define macro bodymacro define macro(args) bodymacro undefine macro Work with C preprocessor macros. As of GDB 6.3, not all of these are implemented.
make [args] Run the make program, passing it args. Equivalent to the shell make args command. This is useful for rebuilding your program while remaining within GDB.
mem start-addr end-addr attributes ... Define a memory region, i.e., a portion of the address space starting at start-addr and ending at end-addr that has particular attributes. Memory Access Attributes
next [count] Run the next statement. Unlike step, a function call is treated as a simple statement; single-stepping does not continue inside the called function. With a count, run the next count statements. In any case, execution stops upon reaching a breakpoint or receipt of a signal. See also step.
nexti [count] Run the next machine instruction. Otherwise, this is similar to the next command in that single-stepping continues past a called function instead of into it.
nosharedlibrary Unload all shared libraries from the debuggee.
output expressionoutput/format expression Print expression, completely unadorned. No newlines are added, nor is the value preceded by the usual $n =. Neither is the value added to the value history. With "/" and format, output the expression using format, which is the same as for the print command; see print.
path dir Add directory dir to the front of the PATH environment variable. print [/format] [expression] Print the value of expression. If the first argument is "/" and format, use the format to print the expression. Omitting expression prints the previous expression, allowing you to use a different format to see the same value. The allowed format values are a subset of the format items for the x command; see also x, later in this section. Print Formats
ExamplePrint a wide character value as a regular character: (gdb) print tmp->sub.val.wsp $2 = (wchar_t *) 0x99f0910 (gdb) print/c *$2 $3 = 97 'a'
print-object object Cause the Objective C object object to print information about itself. This command may only work with Objective C libraries that define the hook function _NSPrintForDebugger( ).
printf format-string, expressions ... Print expressions under control of the format-string, as for the C library printf(3) function. GDB allows only the simple, single-letter escape sequences (such as \t and \n) to appear in format-string.
ptype ptype expressionptype type-name Print the full definition of a type. This differs from whatis, in that whatis only prints type names, while ptype gives a full description. With no argument (the first syntax), print the type of the last value in the value history. This is equivalent to ptype $. With expression (the second syntax), print the type of expression. Note that the expression is not evaluated. No operators with side effects (such as ++, or a function call) execute. The third syntax prints the type of type-name, which is either the name of a type or one of the keywords class, enum, struct, or union, followed by a tag. See also whatis.
pwd Print GDB 's current working directory.
quit Exit GDB.
rbreak regexp Set breakpoints on all functions matching the regular expression regexp. The regular expression syntax used is that of grep (i.e., Basic Regular Expressions, see Chapter 7). This is useful for overloaded functions in C++.
refresh Redraw and refresh the screen for the TUI. See the earlier section "The GDB Text User Interface" for more information.
return [expression] Cause the current stack frame to return to its caller. If provided, expression is used at the return value. GDB pops the current stack frame and any below it (functions it called) from the execution stack, causing the returning frame's caller to become the current frame. Execution does not resume; the program remains stopped until you issue a continue command.
reverse-search regex Search backwards from the current line for a line that matches the regular expression regex, and print it.
run [arguments] Run the debuggee, optionally passing it arguments as the command-line arguments. GDB also supports simple I/O redirections (<, >, >>); pipes are not supported. GDB remembers the last-used arguments; thus a plain run command restarts the program with these same arguments. (Use set args to clear or change the argument list.) The debuggee receives the arguments you give to the run command, the environment as inherited by GDB and modified by set environment, the current working directory, and the current standard input, standard output, and standard error (unless redirected).
rwatch expression Set a watchpoint to stop when expression is read. (Compare awatch and watch.)
search regex An alias for forward-search. See forward-search for more information.
section sectname address Change the base address of sectname to address. This is a last-ditch command, used when the executable file format doesn't contain data on section addresses or if the data in the file is wrong.
select-frame select-frame frame-numselect-frame address Same as the frame command, except that it does not print any messages. See frame for more information.
set [variable] Change the setting either of GDB variables or variables in the debuggee. See the earlier section "Summary of set and show Commands" for more information.
sharedlibrary [regexp] With no argument, load all the shared libraries required by the program or core file. Otherwise, load only those files whose names match regexp.
shell [command args] Run the shell command command with arguments args without leaving GDB. With no arguments, start an interactive subshell. ExampleRun grep to find the definition of a macro: 510 return tmp_number((AWKNUM) len); (gdb) shell grep tmp_number *.h whizprog.h:#define tmp_number(x) mk_number((x), TEMP) (gdb)
show [variable] Show the setting of internal GDB variables. See the earlier section "Summary of set and show Commands" for more information.
signal sig Continue the program running, and immediately send it signal sig. sig may be either a signal number or a signal name. The signal number 0 is special: if the program stops due to receipt of a signal, sending signal 0 resumes it without delivering the original signal.
silent Don't print breakpoint-reached messages. Use this command inside a commands list; see commands.
source file Read and execute the commands in file. The commands are not printed as they are read, and an error in any one command terminates execution of the file. When executing a command file, commands that normally ask for confirmation do not do so, and many commands that would otherwise print messages are silent.
step [count] Run the next statement. This differs from the next command in that if the next statement is a function call, step steps into it and continues single-stepping in the called function. However, next calls the function without stepping into it. With a count, step through count statements. In any case, execution stops upon reaching a breakpoint or receipt of a signal. See also next.
stepi [count] Run the next machine instruction. Otherwise, this is similar to the step command in that single-stepping continues into a called function. With a count, step through count instructions.
symbol-file symbol-file filename [-readnow] With no argument, discard all symbol table information. Otherwise, treat filename as the file to get symbol table information from, and as the file to execute. This command searches $PATH to find the file if necessary. The -readnow option has the same meaning as for the file command; see file for more information.
tbreak bp-spec Set a temporary breakpoint. The argument is the same as for the break command (see break, earlier in this list). The difference is that once the breakpoint is reached, it is removed.
tcatch event Set a temporary catchpoint. The argument is the same as for the catch command (see catch, earlier in this list). The difference is that once the catchpoint is reached, it is removed.
thbreak bp-spec Set a temporary hardware-assisted breakpoint. The argument is the same as for the hbreak command (see hbreak, earlier in this list).
thread threadnumtHRead apply [threadnum | all] command The first form makes threadnum the current thread, i.e., the one that GDB works with. The second form lets you apply command to either the specific thread threadnum or to all threads.
tty device Set the debuggee's input and output to device (typically the device file for a terminal).
tui reg regkind For the TUI, update the register window to display the register set regkind. Register SetsThe following are the acceptable values for regkind.
undisplay dnums ... Remove display items dnums from the automatic display list. See display for more information.
unset environment variable Remove environment variable variable from the environment passed to the debuggee.
until [location] Continue execution until it reaches the next source line after the current line. This is most useful for reaching the line after the end of a loop body. Without a location, until uses single-stepping to reach the next source line. With a location, it uses an internal breakpoint to reach the next source line; this is much faster. The location may be any form acceptable to the break command; see break for more information. ExampleUse until to skip through the entire execution of a loop: $ nl -ba foo.c Show source file 1 #include <stdio.h> 2 3 int main(void) 4 { 5 int i; 6 7 for (i = 1; i <= 10; i++) 8 printf("i = %d\n", i); 9 10 printf("all done: i = %d\n", i); 11 } $ gcc -g foo.c -o foo Compile it $ gdb foo Run GDB GNU gdb 6.3 ... (gdb) break main Set breakpoint Breakpoint 1 at 0x8048358: file foo.c, line 7. (gdb) run Start it running Starting program: /tmp/foo Breakpoint 1, main ( ) at foo.c:7 7 for (i = 1; i <= 10; i++) (gdb) next Next statement 8 printf("i = %d\n", i); (gdb) ENTER repeats 'next' i = 1 7 for (i = 1; i <= 10; i++) (gdb) Same 8 printf("i = %d\n", i); (gdb) Same i = 2 7 for (i = 1; i <= 10; i++) (gdb) until 9 Finish up the loop i = 3 i = 4 i = 5 i = 6 i = 7 i = 8 i = 9 i = 10 main ( ) at foo.c:10 10 printf("all done: i = %d\n", i); (gdb) continue Finish program Continuing. all done: i = 11 Program exited with code 021. (gdb) quit
up count Move up count stack frames. Positive values for count move towards less recent stack frames. See also frame and down.
up-silently count Same as the up command, but don't print any messages. Intended mainly for use in GDB scripts.
update For the TUI, update the source window and the current execution point.
watch expression Set a watchpoint to stop when expression is written. (Compare awatch and rwatch.)
whatis [expression] With no argument, print the type of the last value in the value history. This is equivalent to whatis $. With expression, print the type of expression. Note that the expression is not evaluated. No operators with side effects (such as ++, or a function call) execute. See also ptype.
where [count] Identical to the backtrace command; see backtrace for more information.
while expression... commands ... end Repeatedly execute a series of commands. As long as expression is true, execute commands.
winheight win ±amount For the TUI, change the height of window win by amount. Using + increases the height; using - decreases it. The window name win may be one of asm, cmd, regs, or src.
x [[/NFU] addr] Examine the data at address. Subsequent x commands without an address move forward in memory according to the values for N, F, and U. The N value is a repeat count, for example, to examine a given number of instructions. The F value is a format, indicating how to print the data. The U value is the unit size in bytes of the items to be displayed. GDB stores the address printed by the x command in the $_ convenience variable. It stores the contents of the address in the $_ _ convenience variable. Format Values
Unit Size Values
|
< Day Day Up > |