diff options
Diffstat (limited to 'gdb/doc/gdb.info-1')
| -rw-r--r-- | gdb/doc/gdb.info-1 | 1319 |
1 files changed, 1319 insertions, 0 deletions
diff --git a/gdb/doc/gdb.info-1 b/gdb/doc/gdb.info-1 new file mode 100644 index 0000000..b016705 --- /dev/null +++ b/gdb/doc/gdb.info-1 @@ -0,0 +1,1319 @@ +This is Info file ./gdb.info, produced by Makeinfo version 1.68 from +the input file gdb.texinfo. + +START-INFO-DIR-ENTRY +* Gdb: (gdb). The GNU debugger. +END-INFO-DIR-ENTRY + This file documents the GNU debugger GDB. + + This is the Seventh Edition, February 1999, of `Debugging with GDB: +the GNU Source-Level Debugger' for GDB Version 4.18. + + Copyright (C) 1988-1999 Free Software Foundation, Inc. + + Permission is granted to make and distribute verbatim copies of this +manual provided the copyright notice and this permission notice are +preserved on all copies. + + Permission is granted to copy and distribute modified versions of +this manual under the conditions for verbatim copying, provided also +that the entire resulting derived work is distributed under the terms +of a permission notice identical to this one. + + Permission is granted to copy and distribute translations of this +manual into another language, under the above conditions for modified +versions. + + +File: gdb.info, Node: Top, Next: Summary, Prev: (dir), Up: (dir) + +Debugging with GDB +****************** + + This file describes GDB, the GNU symbolic debugger. + + This is the Seventh Edition, February 1999, for GDB Version 4.18. + + Copyright (C) 1988-1999 Free Software Foundation, Inc. + +* Menu: + +* Summary:: Summary of GDB + +* Sample Session:: A sample GDB session + +* Invocation:: Getting in and out of GDB +* Commands:: GDB commands +* Running:: Running programs under GDB +* Stopping:: Stopping and continuing +* Stack:: Examining the stack +* Source:: Examining source files +* Data:: Examining data + +* Languages:: Using GDB with different languages + + +* Symbols:: Examining the symbol table +* Altering:: Altering execution +* GDB Files:: GDB files +* Targets:: Specifying a debugging target +* Controlling GDB:: Controlling GDB +* Sequences:: Canned sequences of commands + +* Emacs:: Using GDB under GNU Emacs + +* GDB Bugs:: Reporting bugs in GDB + + + +* Formatting Documentation:: How to format and print GDB documentation + + +* Command Line Editing:: Command Line Editing +* Using History Interactively:: Using History Interactively +* Installing GDB:: Installing GDB +* Index:: Index + + -- The Detailed Node Listing -- + +Summary of GDB + +* Free Software:: Freely redistributable software +* Contributors:: Contributors to GDB + +Getting In and Out of GDB + +* Invoking GDB:: How to start GDB +* Quitting GDB:: How to quit GDB +* Shell Commands:: How to use shell commands inside GDB + +Invoking GDB + +* File Options:: Choosing files +* Mode Options:: Choosing modes + +GDB Commands + +* Command Syntax:: How to give commands to GDB +* Completion:: Command completion +* Help:: How to ask GDB for help + +Running Programs Under GDB + +* Compilation:: Compiling for debugging +* Starting:: Starting your program + +* Arguments:: Your program's arguments +* Environment:: Your program's environment + +* Working Directory:: Your program's working directory +* Input/Output:: Your program's input and output +* Attach:: Debugging an already-running process +* Kill Process:: Killing the child process + +* Process Information:: Additional process information + +* Threads:: Debugging programs with multiple threads +* Processes:: Debugging programs with multiple processes + +Stopping and Continuing + +* Breakpoints:: Breakpoints, watchpoints, and catchpoints +* Continuing and Stepping:: Resuming execution + +* Signals:: Signals + +* Thread Stops:: Stopping and starting multi-thread programs + +Breakpoints and watchpoints + +* Set Breaks:: Setting breakpoints +* Set Watchpoints:: Setting watchpoints +* Set Catchpoints:: Setting catchpoints +* Delete Breaks:: Deleting breakpoints +* Disabling:: Disabling breakpoints +* Conditions:: Break conditions +* Break Commands:: Breakpoint command lists + +* Breakpoint Menus:: Breakpoint menus + +Examining the Stack + +* Frames:: Stack frames +* Backtrace:: Backtraces +* Selection:: Selecting a frame +* Frame Info:: Information on a frame +* Alpha/MIPS Stack:: Alpha and MIPS machines and the function stack + +Examining Source Files + +* List:: Printing source lines + +* Search:: Searching source files +* Source Path:: Specifying source directories +* Machine Code:: Source and machine code + +Examining Data + +* Expressions:: Expressions +* Variables:: Program variables +* Arrays:: Artificial arrays +* Output Formats:: Output formats +* Memory:: Examining memory +* Auto Display:: Automatic display +* Print Settings:: Print settings +* Value History:: Value history +* Convenience Vars:: Convenience variables +* Registers:: Registers + +* Floating Point Hardware:: Floating point hardware + +Using GDB with Different Languages + +* Setting:: Switching between source languages +* Show:: Displaying the language + +* Checks:: Type and range checks + +* Support:: Supported languages + +Switching between source languages + +* Filenames:: Filename extensions and languages. +* Manually:: Setting the working language manually +* Automatically:: Having GDB infer the source language + + +Type and range checking + +* Type Checking:: An overview of type checking +* Range Checking:: An overview of range checking + +Supported languages + + +* C:: C and C++ + +C Language Support + +* C Operators:: C operators + +C Language Support + +* C Operators:: C and C++ operators +* C Constants:: C and C++ constants +* Cplus expressions:: C++ expressions +* C Defaults:: Default settings for C and C++ + +* C Checks:: C and C++ type and range checks +* Debugging C:: GDB and C +* Debugging C plus plus:: GDB features for C++ + + +Modula-2 + +* M2 Operators:: Built-in operators +* Built-In Func/Proc:: Built-in functions and procedures +* M2 Constants:: Modula-2 constants +* M2 Defaults:: Default settings for Modula-2 +* Deviations:: Deviations from standard Modula-2 +* M2 Checks:: Modula-2 type and range checks +* M2 Scope:: The scope operators `::' and `.' +* GDB/M2:: GDB and Modula-2 + +Altering Execution + +* Assignment:: Assignment to variables +* Jumping:: Continuing at a different address + +* Signaling:: Giving your program a signal +* Returning:: Returning from a function +* Calling:: Calling your program's functions +* Patching:: Patching your program + +GDB Files + +* Files:: Commands to specify files +* Symbol Errors:: Errors reading symbol files + +Specifying a Debugging Target + +* Active Targets:: Active targets +* Target Commands:: Commands for managing targets + +* Byte Order:: Choosing target byte order +* Remote:: Remote debugging + +Remote debugging + + +* Remote Serial:: GDB remote serial protocol + + +* i960-Nindy Remote:: GDB with a remote i960 (Nindy) + + +* UDI29K Remote:: The UDI protocol for AMD29K +* EB29K Remote:: The EBMON protocol for AMD29K + + +* VxWorks Remote:: GDB and VxWorks + + +* ST2000 Remote:: GDB with a Tandem ST2000 + + +* Hitachi Remote:: GDB and Hitachi Microprocessors + + +* MIPS Remote:: GDB and MIPS boards + + +* Simulator:: Simulated CPU target + +Controlling GDB + +* Prompt:: Prompt +* Editing:: Command editing +* History:: Command history +* Screen Size:: Screen size +* Numbers:: Numbers +* Messages/Warnings:: Optional warnings and messages + +Canned Sequences of Commands + +* Define:: User-defined commands +* Hooks:: User-defined command hooks +* Command Files:: Command files +* Output:: Commands for controlled output + +Reporting Bugs in GDB + +* Bug Criteria:: Have you found a bug? +* Bug Reporting:: How to report bugs + +Installing GDB + +* Separate Objdir:: Compiling GDB in another directory +* Config Names:: Specifying names for hosts and targets +* Configure Options:: Summary of options for configure + + +File: gdb.info, Node: Summary, Next: Sample Session, Prev: Top, Up: Top + +Summary of GDB +************** + + The purpose of a debugger such as GDB is to allow you to see what is +going on "inside" another program while it executes--or what another +program was doing at the moment it crashed. + + GDB can do four main kinds of things (plus other things in support of +these) to help you catch bugs in the act: + + * Start your program, specifying anything that might affect its + behavior. + + * Make your program stop on specified conditions. + + * Examine what has happened, when your program has stopped. + + * Change things in your program, so you can experiment with + correcting the effects of one bug and go on to learn about another. + + You can use GDB to debug programs written in C or C++. For more +information, see *Note C and C++: C. + + Support for Modula-2 and Chill is partial. For information on +Modula-2, see *Note Modula-2: Modula-2. There is no further +documentation on Chill yet. + + Debugging Pascal programs which use sets, subranges, file variables, +or nested functions does not currently work. GDB does not support +entering expressions, printing values, or similar features using Pascal +syntax. + + GDB can be used to debug programs written in Fortran, although it +does not yet support entering expressions, printing values, or similar +features using Fortran syntax. It may be necessary to refer to some +variables with a trailing underscore. + +* Menu: + +* Free Software:: Freely redistributable software +* Contributors:: Contributors to GDB + + +File: gdb.info, Node: Free Software, Next: Contributors, Prev: Summary, Up: Summary + +Free software +============= + + GDB is "free software", protected by the GNU General Public License +(GPL). The GPL gives you the freedom to copy or adapt a licensed +program--but every person getting a copy also gets with it the freedom +to modify that copy (which means that they must get access to the +source code), and the freedom to distribute further copies. Typical +software companies use copyrights to limit your freedoms; the Free +Software Foundation uses the GPL to preserve these freedoms. + + Fundamentally, the General Public License is a license which says +that you have these freedoms and that you cannot take these freedoms +away from anyone else. + + +File: gdb.info, Node: Contributors, Prev: Free Software, Up: Summary + +Contributors to GDB +=================== + + Richard Stallman was the original author of GDB, and of many other +GNU programs. Many others have contributed to its development. This +section attempts to credit major contributors. One of the virtues of +free software is that everyone is free to contribute to it; with +regret, we cannot actually acknowledge everyone here. The file +`ChangeLog' in the GDB distribution approximates a blow-by-blow account. + + Changes much prior to version 2.0 are lost in the mists of time. + + *Plea:* Additions to this section are particularly welcome. If you + or your friends (or enemies, to be evenhanded) have been unfairly + omitted from this list, we would like to add your names! + + So that they may not regard their many labors as thankless, we +particularly thank those who shepherded GDB through major releases: Jim +Blandy (release 4.18); Jason Molenda (release 4.17); Stan Shebs +(release 4.14); Fred Fish (releases 4.16, 4.15, 4.13, 4.12, 4.11, 4.10, +and 4.9); Stu Grossman and John Gilmore (releases 4.8, 4.7, 4.6, 4.5, +and 4.4); John Gilmore (releases 4.3, 4.2, 4.1, 4.0, and 3.9); Jim +Kingdon (releases 3.5, 3.4, and 3.3); and Randy Smith (releases 3.2, +3.1, and 3.0). + + Richard Stallman, assisted at various times by Peter TerMaat, Chris +Hanson, and Richard Mlynarik, handled releases through 2.8. + + Michael Tiemann is the author of most of the GNU C++ support in GDB, +with significant additional contributions from Per Bothner. James +Clark wrote the GNU C++ demangler. Early work on C++ was by Peter +TerMaat (who also did much general update work leading to release 3.0). + + GDB 4 uses the BFD subroutine library to examine multiple +object-file formats; BFD was a joint project of David V. +Henkel-Wallace, Rich Pixley, Steve Chamberlain, and John Gilmore. + + David Johnson wrote the original COFF support; Pace Willison did the +original support for encapsulated COFF. + + Brent Benson of Harris Computer Systems contributed DWARF 2 support. + + Adam de Boor and Bradley Davis contributed the ISI Optimum V support. +Per Bothner, Noboyuki Hikichi, and Alessandro Forin contributed MIPS +support. Jean-Daniel Fekete contributed Sun 386i support. Chris +Hanson improved the HP9000 support. Noboyuki Hikichi and Tomoyuki +Hasei contributed Sony/News OS 3 support. David Johnson contributed +Encore Umax support. Jyrki Kuoppala contributed Altos 3068 support. +Jeff Law contributed HP PA and SOM support. Keith Packard contributed +NS32K support. Doug Rabson contributed Acorn Risc Machine support. +Bob Rusk contributed Harris Nighthawk CX-UX support. Chris Smith +contributed Convex support (and Fortran debugging). Jonathan Stone +contributed Pyramid support. Michael Tiemann contributed SPARC support. +Tim Tucker contributed support for the Gould NP1 and Gould Powernode. +Pace Willison contributed Intel 386 support. Jay Vosburgh contributed +Symmetry support. + + Andreas Schwab contributed M68K Linux support. + + Rich Schaefer and Peter Schauer helped with support of SunOS shared +libraries. + + Jay Fenlason and Roland McGrath ensured that GDB and GAS agree about +several machine instruction sets. + + Patrick Duval, Ted Goldstein, Vikram Koka and Glenn Engel helped +develop remote debugging. Intel Corporation, Wind River Systems, AMD, +and ARM contributed remote debugging modules for the i960, VxWorks, +A29K UDI, and RDI targets, respectively. + + Brian Fox is the author of the readline libraries providing +command-line editing and command history. + + Andrew Beers of SUNY Buffalo wrote the language-switching code, the +Modula-2 support, and contributed the Languages chapter of this manual. + + Fred Fish wrote most of the support for Unix System Vr4. He also +enhanced the command-completion support to cover C++ overloaded symbols. + + Hitachi America, Ltd. sponsored the support for H8/300, H8/500, and +Super-H processors. + + NEC sponsored the support for the v850, Vr4xxx, and Vr5xxx +processors. + + Mitsubishi sponsored the support for D10V, D30V, and M32R/D +processors. + + Toshiba sponsored the support for the TX39 Mips processor. + + Matsushita sponsored the support for the MN10200 and MN10300 +processors. + + Fujitsu sponsored the support for SPARClite and FR30 processors + + Kung Hsu, Jeff Law, and Rick Sladkey added support for hardware +watchpoints. + + Michael Snyder added support for tracepoints. + + Stu Grossman wrote gdbserver. + + Jim Kingdon, Peter Schauer, Ian Taylor, and Stu Grossman made nearly +innumerable bug fixes and cleanups throughout GDB. + + The following people at the Hewlett-Packard Company contributed +support for the PA-RISC 2.0 architecture, HP-UX 10.20, 10.30, and 11.0 +(narrow mode), HP's implementation of kernel threads, HP's aC++ +compiler, and the terminal user interface: Ben Krepp, Richard Title, +John Bishop, Susan Macchia, Kathy Mann, Satish Pai, India Paul, Steve +Rehrauer, and Elena Zannoni. Kim Haase provided HP-specific +information in this manual. + + Cygnus Solutions has sponsored GDB maintenance and much of its +development since 1991. Cygnus engineers who have worked on GDB +fulltime include Mark Alexander, Jim Blandy, Per Bothner, Edith Epstein, +Chris Faylor, Fred Fish, Martin Hunt, Jim Ingham, John Gilmore, Stu +Grossman, Kung Hsu, Jim Kingdon, John Metzler, Fernando Nasser, Geoffrey +Noer, Dawn Perchik, Rich Pixley, Zdenek Radouch, Keith Seitz, Stan +Shebs, David Taylor, and Elena Zannoni. In addition, Dave Brolley, Ian +Carmichael, Steve Chamberlain, Nick Clifton, JT Conklin, Stan Cox, DJ +Delorie, Ulrich Drepper, Frank Eigler, Doug Evans, Sean Fagan, David +Henkel-Wallace, Richard Henderson, Jeff Holcomb, Jeff Law, Jim Lemke, +Tom Lord, Bob Manson, Michael Meissner, Jason Merrill, Catherine Moore, +Drew Moseley, Ken Raeburn, Gavin Romig-Koch, Rob Savoye, Jamie Smith, +Mike Stump, Ian Taylor, Angela Thomas, Michael Tiemann, Tom Tromey, Ron +Unrau, Jim Wilson, and David Zuhn have made contributions both large +and small. + + +File: gdb.info, Node: Sample Session, Next: Invocation, Prev: Summary, Up: Top + +A Sample GDB Session +******************** + + You can use this manual at your leisure to read all about GDB. +However, a handful of commands are enough to get started using the +debugger. This chapter illustrates those commands. + + One of the preliminary versions of GNU `m4' (a generic macro +processor) exhibits the following bug: sometimes, when we change its +quote strings from the default, the commands used to capture one macro +definition within another stop working. In the following short `m4' +session, we define a macro `foo' which expands to `0000'; we then use +the `m4' built-in `defn' to define `bar' as the same thing. However, +when we change the open quote string to `<QUOTE>' and the close quote +string to `<UNQUOTE>', the same procedure fails to define a new synonym +`baz': + + $ cd gnu/m4 + $ ./m4 + define(foo,0000) + + foo + 0000 + define(bar,defn(`foo')) + + bar + 0000 + changequote(<QUOTE>,<UNQUOTE>) + + define(baz,defn(<QUOTE>foo<UNQUOTE>)) + baz + C-d + m4: End of input: 0: fatal error: EOF in string + +Let us use GDB to try to see what is going on. + + $ gdb m4 + GDB is free software and you are welcome to distribute copies + of it under certain conditions; type "show copying" to see + the conditions. + There is absolutely no warranty for GDB; type "show warranty" + for details. + + GDB 4.18, Copyright 1999 Free Software Foundation, Inc... + (gdb) + +GDB reads only enough symbol data to know where to find the rest when +needed; as a result, the first prompt comes up very quickly. We now +tell GDB to use a narrower display width than usual, so that examples +fit in this manual. + + (gdb) set width 70 + +We need to see how the `m4' built-in `changequote' works. Having +looked at the source, we know the relevant subroutine is +`m4_changequote', so we set a breakpoint there with the GDB `break' +command. + + (gdb) break m4_changequote + Breakpoint 1 at 0x62f4: file builtin.c, line 879. + +Using the `run' command, we start `m4' running under GDB control; as +long as control does not reach the `m4_changequote' subroutine, the +program runs as usual: + + (gdb) run + Starting program: /work/Editorial/gdb/gnu/m4/m4 + define(foo,0000) + + foo + 0000 + +To trigger the breakpoint, we call `changequote'. GDB suspends +execution of `m4', displaying information about the context where it +stops. + + changequote(<QUOTE>,<UNQUOTE>) + + Breakpoint 1, m4_changequote (argc=3, argv=0x33c70) + at builtin.c:879 + 879 if (bad_argc(TOKEN_DATA_TEXT(argv[0]),argc,1,3)) + +Now we use the command `n' (`next') to advance execution to the next +line of the current function. + + (gdb) n + 882 set_quotes((argc >= 2) ? TOKEN_DATA_TEXT(argv[1])\ + : nil, + +`set_quotes' looks like a promising subroutine. We can go into it by +using the command `s' (`step') instead of `next'. `step' goes to the +next line to be executed in *any* subroutine, so it steps into +`set_quotes'. + + (gdb) s + set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>") + at input.c:530 + 530 if (lquote != def_lquote) + +The display that shows the subroutine where `m4' is now suspended (and +its arguments) is called a stack frame display. It shows a summary of +the stack. We can use the `backtrace' command (which can also be +spelled `bt'), to see where we are in the stack as a whole: the +`backtrace' command displays a stack frame for each active subroutine. + + (gdb) bt + #0 set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>") + at input.c:530 + #1 0x6344 in m4_changequote (argc=3, argv=0x33c70) + at builtin.c:882 + #2 0x8174 in expand_macro (sym=0x33320) at macro.c:242 + #3 0x7a88 in expand_token (obs=0x0, t=209696, td=0xf7fffa30) + at macro.c:71 + #4 0x79dc in expand_input () at macro.c:40 + #5 0x2930 in main (argc=0, argv=0xf7fffb20) at m4.c:195 + +We step through a few more lines to see what happens. The first two +times, we can use `s'; the next two times we use `n' to avoid falling +into the `xstrdup' subroutine. + + (gdb) s + 0x3b5c 532 if (rquote != def_rquote) + (gdb) s + 0x3b80 535 lquote = (lq == nil || *lq == '\0') ? \ + def_lquote : xstrdup(lq); + (gdb) n + 536 rquote = (rq == nil || *rq == '\0') ? def_rquote\ + : xstrdup(rq); + (gdb) n + 538 len_lquote = strlen(rquote); + +The last line displayed looks a little odd; we can examine the variables +`lquote' and `rquote' to see if they are in fact the new left and right +quotes we specified. We use the command `p' (`print') to see their +values. + + (gdb) p lquote + $1 = 0x35d40 "<QUOTE>" + (gdb) p rquote + $2 = 0x35d50 "<UNQUOTE>" + +`lquote' and `rquote' are indeed the new left and right quotes. To +look at some context, we can display ten lines of source surrounding +the current line with the `l' (`list') command. + + (gdb) l + 533 xfree(rquote); + 534 + 535 lquote = (lq == nil || *lq == '\0') ? def_lquote\ + : xstrdup (lq); + 536 rquote = (rq == nil || *rq == '\0') ? def_rquote\ + : xstrdup (rq); + 537 + 538 len_lquote = strlen(rquote); + 539 len_rquote = strlen(lquote); + 540 } + 541 + 542 void + +Let us step past the two lines that set `len_lquote' and `len_rquote', +and then examine the values of those variables. + + (gdb) n + 539 len_rquote = strlen(lquote); + (gdb) n + 540 } + (gdb) p len_lquote + $3 = 9 + (gdb) p len_rquote + $4 = 7 + +That certainly looks wrong, assuming `len_lquote' and `len_rquote' are +meant to be the lengths of `lquote' and `rquote' respectively. We can +set them to better values using the `p' command, since it can print the +value of any expression--and that expression can include subroutine +calls and assignments. + + (gdb) p len_lquote=strlen(lquote) + $5 = 7 + (gdb) p len_rquote=strlen(rquote) + $6 = 9 + +Is that enough to fix the problem of using the new quotes with the `m4' +built-in `defn'? We can allow `m4' to continue executing with the `c' +(`continue') command, and then try the example that caused trouble +initially: + + (gdb) c + Continuing. + + define(baz,defn(<QUOTE>foo<UNQUOTE>)) + + baz + 0000 + +Success! The new quotes now work just as well as the default ones. The +problem seems to have been just the two typos defining the wrong +lengths. We allow `m4' exit by giving it an EOF as input: + + C-d + Program exited normally. + +The message `Program exited normally.' is from GDB; it indicates `m4' +has finished executing. We can end our GDB session with the GDB `quit' +command. + + (gdb) quit + + +File: gdb.info, Node: Invocation, Next: Commands, Prev: Sample Session, Up: Top + +Getting In and Out of GDB +************************* + + This chapter discusses how to start GDB, and how to get out of it. +The essentials are: + * type `gdb' to start GDB. + + * type `quit' or `C-d' to exit. + +* Menu: + +* Invoking GDB:: How to start GDB +* Quitting GDB:: How to quit GDB +* Shell Commands:: How to use shell commands inside GDB + + +File: gdb.info, Node: Invoking GDB, Next: Quitting GDB, Prev: Invocation, Up: Invocation + +Invoking GDB +============ + + Invoke GDB by running the program `gdb'. Once started, GDB reads +commands from the terminal until you tell it to exit. + + You can also run `gdb' with a variety of arguments and options, to +specify more of your debugging environment at the outset. + + The command-line options described here are designed to cover a +variety of situations; in some environments, some of these options may +effectively be unavailable. + + The most usual way to start GDB is with one argument, specifying an +executable program: + + gdb PROGRAM + +You can also start with both an executable program and a core file +specified: + + gdb PROGRAM CORE + + You can, instead, specify a process ID as a second argument, if you +want to debug a running process: + + gdb PROGRAM 1234 + +would attach GDB to process `1234' (unless you also have a file named +`1234'; GDB does check for a core file first). + + Taking advantage of the second command-line argument requires a +fairly complete operating system; when you use GDB as a remote debugger +attached to a bare board, there may not be any notion of "process", and +there is often no way to get a core dump. + + You can run `gdb' without printing the front material, which +describes GDB's non-warranty, by specifying `-silent': + + gdb -silent + +You can further control how GDB starts up by using command-line +options. GDB itself can remind you of the options available. + +Type + + gdb -help + +to display all available options and briefly describe their use (`gdb +-h' is a shorter equivalent). + + All options and command line arguments you give are processed in +sequential order. The order makes a difference when the `-x' option is +used. + +* Menu: + + +* File Options:: Choosing files +* Mode Options:: Choosing modes + + +File: gdb.info, Node: File Options, Next: Mode Options, Up: Invoking GDB + +Choosing files +-------------- + + When GDB starts, it reads any arguments other than options as +specifying an executable file and core file (or process ID). This is +the same as if the arguments were specified by the `-se' and `-c' +options respectively. (GDB reads the first argument that does not have +an associated option flag as equivalent to the `-se' option followed by +that argument; and the second argument that does not have an associated +option flag, if any, as equivalent to the `-c' option followed by that +argument.) + + Many options have both long and short forms; both are shown in the +following list. GDB also recognizes the long forms if you truncate +them, so long as enough of the option is present to be unambiguous. +(If you prefer, you can flag option arguments with `--' rather than +`-', though we illustrate the more usual convention.) + +`-symbols FILE' +`-s FILE' + Read symbol table from file FILE. + +`-exec FILE' +`-e FILE' + Use file FILE as the executable file to execute when appropriate, + and for examining pure data in conjunction with a core dump. + +`-se FILE' + Read symbol table from file FILE and use it as the executable file. + +`-core FILE' +`-c FILE' + Use file FILE as a core dump to examine. + +`-c NUMBER' + Connect to process ID NUMBER, as with the `attach' command (unless + there is a file in core-dump format named NUMBER, in which case + `-c' specifies that file as a core dump to read). + +`-command FILE' +`-x FILE' + Execute GDB commands from file FILE. *Note Command files: Command + Files. + +`-directory DIRECTORY' +`-d DIRECTORY' + Add DIRECTORY to the path to search for source files. + +`-m' +`-mapped' + *Warning: this option depends on operating system facilities that + are not supported on all systems.* + If memory-mapped files are available on your system through the + `mmap' system call, you can use this option to have GDB write the + symbols from your program into a reusable file in the current + directory. If the program you are debugging is called + `/tmp/fred', the mapped symbol file is `./fred.syms'. Future GDB + debugging sessions notice the presence of this file, and can + quickly map in symbol information from it, rather than reading the + symbol table from the executable program. + + The `.syms' file is specific to the host machine where GDB is run. + It holds an exact image of the internal GDB symbol table. It + cannot be shared across multiple host platforms. + +`-r' +`-readnow' + Read each symbol file's entire symbol table immediately, rather + than the default, which is to read it incrementally as it is + needed. This makes startup slower, but makes future operations + faster. + + The `-mapped' and `-readnow' options are typically combined in order +to build a `.syms' file that contains complete symbol information. +(*Note Commands to specify files: Files, for information on `.syms' +files.) A simple GDB invocation to do nothing but build a `.syms' file +for future use is: + + gdb -batch -nx -mapped -readnow programname + + +File: gdb.info, Node: Mode Options, Prev: File Options, Up: Invoking GDB + +Choosing modes +-------------- + + You can run GDB in various alternative modes--for example, in batch +mode or quiet mode. + +`-nx' +`-n' + Do not execute commands from any initialization files (normally + called `.gdbinit', or `gdb.ini' on PCs). Normally, the commands in + these files are executed after all the command options and + arguments have been processed. *Note Command files: Command Files. + +`-quiet' +`-q' + "Quiet". Do not print the introductory and copyright messages. + These messages are also suppressed in batch mode. + +`-batch' + Run in batch mode. Exit with status `0' after processing all the + command files specified with `-x' (and all commands from + initialization files, if not inhibited with `-n'). Exit with + nonzero status if an error occurs in executing the GDB commands in + the command files. + + Batch mode may be useful for running GDB as a filter, for example + to download and run a program on another computer; in order to + make this more useful, the message + + Program exited normally. + + (which is ordinarily issued whenever a program running under GDB + control terminates) is not issued when running in batch mode. + +`-cd DIRECTORY' + Run GDB using DIRECTORY as its working directory, instead of the + current directory. + +`-fullname' +`-f' + GNU Emacs sets this option when it runs GDB as a subprocess. It + tells GDB to output the full file name and line number in a + standard, recognizable fashion each time a stack frame is + displayed (which includes each time your program stops). This + recognizable format looks like two `\032' characters, followed by + the file name, line number and character position separated by + colons, and a newline. The Emacs-to-GDB interface program uses + the two `\032' characters as a signal to display the source code + for the frame. + +`-b BPS' + Set the line speed (baud rate or bits per second) of any serial + interface used by GDB for remote debugging. + +`-tty DEVICE' + Run using DEVICE for your program's standard input and output. + + +File: gdb.info, Node: Quitting GDB, Next: Shell Commands, Prev: Invoking GDB, Up: Invocation + +Quitting GDB +============ + +`quit' + To exit GDB, use the `quit' command (abbreviated `q'), or type an + end-of-file character (usually `C-d'). If you do not supply + EXPRESSION, GDB will terminate normally; otherwise it will + terminate using the result of EXPRESSION as the error code. + + An interrupt (often `C-c') does not exit from GDB, but rather +terminates the action of any GDB command that is in progress and +returns to GDB command level. It is safe to type the interrupt +character at any time because GDB does not allow it to take effect +until a time when it is safe. + + If you have been using GDB to control an attached process or device, +you can release it with the `detach' command (*note Debugging an +already-running process: Attach.). + + +File: gdb.info, Node: Shell Commands, Prev: Quitting GDB, Up: Invocation + +Shell commands +============== + + If you need to execute occasional shell commands during your +debugging session, there is no need to leave or suspend GDB; you can +just use the `shell' command. + +`shell COMMAND STRING' + Invoke a standard shell to execute COMMAND STRING. If it exists, + the environment variable `SHELL' determines which shell to run. + Otherwise GDB uses `/bin/sh'. + + The utility `make' is often needed in development environments. You +do not have to use the `shell' command for this purpose in GDB: + +`make MAKE-ARGS' + Execute the `make' program with the specified arguments. This is + equivalent to `shell make MAKE-ARGS'. + + +File: gdb.info, Node: Commands, Next: Running, Prev: Invocation, Up: Top + +GDB Commands +************ + + 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 <RET>. 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 is more than one possibility). + +* Menu: + +* Command Syntax:: How to give commands to GDB +* Completion:: Command completion +* Help:: How to ask GDB for help + + +File: gdb.info, Node: Command Syntax, Next: Completion, Prev: Commands, Up: Commands + +Command syntax +============== + + A GDB command is a single line of input. There is 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 which is the number of times to +step, as in `step 5'. You can also use the `step' command with no +arguments. Some command names do not 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 specially 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 <RET>) means to repeat the +previous command. Certain commands (for example, `run') will not repeat +this way; these are commands whose unintentional repetition might cause +trouble and which you are unlikely to want to repeat. + + The `list' and `x' commands, when you repeat them with <RET>, +construct new arguments rather than repeating exactly as typed. This +permits easy scanning of source or memory. + + GDB can also use <RET> in another way: to partition lengthy output, +in a way similar to the common utility `more' (*note Screen size: +Screen Size.). Since it is easy to press one <RET> 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; it does +nothing. This is useful mainly in command files (*note Command files: +Command Files.). + + +File: gdb.info, Node: Completion, Next: Help, Prev: Command Syntax, Up: Commands + +Command completion +================== + + GDB can fill in the rest of a word in a command for you, if there is +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 is only one possibility, GDB fills in the word, and +waits for you to finish the command (or press <RET> 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 <RET> at this point, to run the `info breakpoints' +command, or backspace and enter something else, if `breakpoints' does +not look like the command you expected. (If you were sure you wanted +`info breakpoints' in the first place, you might as well just type +<RET> immediately after `info bre', to exploit command abbreviations +rather than command completion). + + If there is 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: + + (gdb) b make_ <TAB> +GDB sounds bell; press <TAB> again, to see: + 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 `M-?' rather than pressing <TAB> twice. `M-?' means +`<META> ?'. You can type this either by holding down a key designated +as the <META> shift on your keyboard (if there is one) while typing +`?', or as <ESC> followed by `?'. + + 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 `M-?' to request word completion: + + (gdb) b 'bubble( <M-?> + 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 do not 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 +have not yet started typing the argument list when you ask for +completion on an overloaded symbol. + + For more information about overloaded functions, *note C++ +expressions: Cplus expressions.. You can use the command `set +overload-resolution off' to disable overload resolution; *note GDB +features for C++: Debugging C plus plus.. + + +File: gdb.info, Node: Help, Prev: Completion, Up: Commands + +Getting help +============ + + You can always ask GDB itself for information on its commands, using +the command `help'. + +`help' +`h' + You can use `help' (abbreviated `h') with no arguments to display + a short list of named classes of commands: + + (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) + +`help CLASS' + Using one of the general help classes as an argument, you can get a + list of the individual commands in that class. For example, here + is the help display for the class `status': + + (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) + +`help COMMAND' + With a command name as `help' argument, GDB displays a short + paragraph on how to use that command. + +`complete ARGS' + The `complete ARGS' command lists all the possible completions for + the beginning of a command. Use ARGS to specify the beginning of + the command you want completed. For example: + + complete i + + results in: + + info + inspect + ignore + + This 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 under `show' in the Index point to all the sub-commands. +*Note Index::. + +`info' + This command (abbreviated `i') is for describing the state of your + program. For example, you can list the arguments given to your + program with `info args', list the registers currently in use with + `info registers', or list the breakpoints you have set with `info + breakpoints'. You can get a complete list of the `info' + sub-commands with `help info'. + +`set' + You can assign the result of an expression to an environment + variable with `set'. For example, you can set the GDB prompt to a + $-sign with `set prompt $'. + +`show' + In contrast to `info', `show' is for describing the state of GDB + itself. You can change most of the things you can `show', by + using the related command `set'; for example, you can control what + number system is used for displays with `set radix', or simply + inquire which is currently in use with `show radix'. + + 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: + +`show version' + Show what version of GDB is running. You should include this + information in GDB bug-reports. If multiple versions of GDB are in + use at your site, you may occasionally want to determine which + version of GDB you are running; as GDB evolves, new commands are + introduced, and old ones may wither away. The version number is + also announced when you start GDB. + +`show copying' + Display information about permission for copying GDB. + +`show warranty' + Display the GNU "NO WARRANTY" statement. + + +File: gdb.info, Node: Running, Next: Stopping, Prev: Commands, Up: Top + +Running Programs Under GDB +************************** + + When you 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 a +child process. + +* Menu: + +* Compilation:: Compiling for debugging +* Starting:: Starting your program + +* Arguments:: Your program's arguments +* Environment:: Your program's environment + +* Working Directory:: Your program's working directory +* Input/Output:: Your program's input and output +* Attach:: Debugging an already-running process +* Kill Process:: Killing the child process + +* Process Information:: Additional process information + +* Threads:: Debugging programs with multiple threads +* Processes:: Debugging programs with multiple processes + + +File: gdb.info, Node: Compilation, Next: Starting, Prev: Running, Up: Running + +Compiling for debugging +======================= + + In order to debug a program effectively, you need to generate +debugging information when you compile it. This 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. + + Many C compilers are unable to handle the `-g' and `-O' options +together. Using those compilers, you cannot generate optimized +executables containing debugging information. + + 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 is 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. Do not be too surprised when the execution path does not +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 do not 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 as a bug (including a test case!). + + Older versions of the GNU C compiler permitted a variant option +`-gg' for debugging information. GDB no longer supports this format; +if your GNU C compiler has this option, do not use it. + |