diff --git a/gnu/dist/gdb/doc/gdb.info b/gnu/dist/gdb/doc/gdb.info deleted file mode 100644 index a9ebaab1f2ed..000000000000 --- a/gnu/dist/gdb/doc/gdb.info +++ /dev/null @@ -1,224 +0,0 @@ -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 Fifth Edition, April 1998, of `Debugging with GDB: the -GNU Source-Level Debugger' for GDB Version . - - Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, -1997, 1998 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. - - -Indirect: -gdb.info-1: 1037 -gdb.info-2: 50989 -gdb.info-3: 100293 -gdb.info-4: 144637 -gdb.info-5: 193017 -gdb.info-6: 238324 -gdb.info-7: 287491 -gdb.info-8: 337158 -gdb.info-9: 366713 - -Tag Table: -(Indirect) -Node: Top1037 -Node: Summary2501 -Node: Free Software4107 -Node: Contributors4845 -Node: Sample Session9212 -Node: Invocation16078 -Node: Invoking GDB16552 -Node: File Options18428 -Node: Mode Options21531 -Node: Quitting GDB23706 -Node: Shell Commands24572 -Node: Commands25319 -Node: Command Syntax25956 -Node: Completion27819 -Node: Help31904 -Node: Running36211 -Node: Compilation37326 -Node: Starting39122 -Node: Arguments42294 -Node: Environment43298 -Node: Working Directory46394 -Node: Input/Output47134 -Node: Attach48739 -Node: Kill Process50989 -Node: Process Information51959 -Node: Threads53291 -Node: Processes57909 -Node: Stopping59141 -Node: Breakpoints60276 -Node: Set Breaks62537 -Node: Set Watchpoints71001 -Node: Exception Handling73477 -Node: Delete Breaks75991 -Node: Disabling77619 -Node: Conditions80237 -Node: Break Commands84763 -Node: Breakpoint Menus87607 -Node: Continuing and Stepping89283 -Node: Signals96625 -Node: Thread Stops100293 -Node: Stack102619 -Node: Frames104163 -Node: Backtrace106880 -Node: Selection108612 -Node: Frame Info111348 -Node: MIPS Stack113648 -Node: Source114665 -Node: List115614 -Node: Search119139 -Node: Source Path119942 -Node: Machine Code122623 -Node: Data125678 -Node: Expressions127553 -Node: Variables129485 -Node: Arrays132022 -Node: Output Formats134547 -Node: Memory136618 -Node: Auto Display140882 -Node: Print Settings144637 -Node: Value History154465 -Node: Convenience Vars156876 -Node: Registers159659 -Node: Floating Point Hardware164361 -Node: Languages164864 -Node: Setting165968 -Node: Filenames167558 -Node: Manually168142 -Node: Automatically169340 -Node: Show170391 -Node: Checks171293 -Node: Type Checking172649 -Node: Range Checking175346 -Node: Support177687 -Node: C178603 -Node: C Operators179725 -Node: C Constants183780 -Node: Cplus expressions185689 -Node: C Defaults188284 -Node: C Checks188941 -Node: Debugging C189648 -Node: Debugging C plus plus190117 -Node: Modula-2192129 -Node: M2 Operators193017 -Node: Built-In Func/Proc196013 -Node: M2 Constants198752 -Node: M2 Defaults200341 -Node: Deviations200936 -Node: M2 Checks202023 -Node: M2 Scope202823 -Node: GDB/M2203832 -Node: Symbols204771 -Node: Altering211633 -Node: Assignment212601 -Node: Jumping214711 -Node: Signaling216715 -Node: Returning217837 -Node: Calling219029 -Node: Patching219812 -Node: GDB Files220882 -Node: Files221347 -Node: Symbol Errors232283 -Node: Targets235862 -Node: Active Targets236752 -Node: Target Commands238324 -Node: Remote243935 -Node: Remote Serial245396 -Node: Stub Contents248004 -Node: Bootstrapping250105 -Node: Debug Session253901 -Node: Protocol257046 -Node: Server260353 -Node: NetWare264399 -Node: i960-Nindy Remote266361 -Node: Nindy Startup267181 -Node: Nindy Options267866 -Node: Nindy Reset269480 -Node: UDI29K Remote269864 -Node: EB29K Remote270769 -Node: Comms (EB29K)271587 -Node: gdb-EB29K274766 -Node: Remote Log276132 -Node: ST2000 Remote276607 -Node: VxWorks Remote278075 -Node: VxWorks Connection280035 -Node: VxWorks Download280961 -Node: VxWorks Attach282690 -Node: Sparclet Remote283080 -Node: Sparclet File284528 -Node: Sparclet Connection285400 -Node: Sparclet Download285870 -Node: Sparclet Execution286908 -Node: Hitachi Remote287491 -Node: Hitachi Boards288419 -Node: Hitachi ICE289482 -Node: Hitachi Special290270 -Node: MIPS Remote290996 -Node: Simulator295275 -Node: Controlling GDB296765 -Node: Prompt297376 -Node: Editing298150 -Node: History298919 -Node: Screen Size301618 -Node: Numbers303016 -Node: Messages/Warnings304418 -Node: Sequences306426 -Node: Define306986 -Node: Hooks310152 -Node: Command Files311550 -Node: Output313522 -Node: Emacs315929 -Node: GDB Bugs321875 -Node: Bug Criteria322593 -Node: Bug Reporting323347 -Node: Command Line Editing330487 -Node: Introduction and Notation330908 -Node: Readline Interaction331955 -Node: Readline Bare Essentials333087 -Node: Readline Movement Commands334606 -Node: Readline Killing Commands335514 -Node: Readline Arguments337158 -Node: Readline Init File338114 -Node: Readline Init Syntax338941 -Node: Commands For Moving342885 -Node: Commands For History343519 -Node: Commands For Text344600 -Node: Commands For Killing346348 -Node: Numeric Arguments347509 -Node: Commands For Completion347961 -Node: Miscellaneous Commands348673 -Node: Readline vi Mode349439 -Node: Using History Interactively350166 -Node: History Interaction350531 -Node: Event Designators351483 -Node: Word Designators352128 -Node: Modifiers353036 -Node: Formatting Documentation353706 -Node: Installing GDB357031 -Node: Separate Objdir360442 -Node: Config Names362969 -Node: configure Options364389 -Node: Index366713 - -End Tag Table diff --git a/gnu/dist/gdb/doc/gdb.info-1 b/gnu/dist/gdb/doc/gdb.info-1 deleted file mode 100644 index 9f7255299510..000000000000 --- a/gnu/dist/gdb/doc/gdb.info-1 +++ /dev/null @@ -1,1322 +0,0 @@ -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 Fifth Edition, April 1998, of `Debugging with GDB: the -GNU Source-Level Debugger' for GDB Version . - - Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, -1997, 1998 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, Up: (dir) - -Debugging with GDB -****************** - - This file describes GDB, the GNU symbolic debugger. - - This is the Fifth Edition, April 1998, for GDB Version . - -* 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 -* Command Line Editing:: Facilities of the readline library -* Using History Interactively:: - -* Formatting Documentation:: How to format and print GDB documentation -* Installing GDB:: Installing GDB - -* Index:: Index - - -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, 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 long labor as thankless, we -particularly thank those who shepherded GDB through major releases: -Stan Shebs (release 4.14), Fred Fish (releases 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). As major maintainer of GDB for some period, each -contributed significantly to the structure, stability, and capabilities -of the entire debugger. - - 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. - - 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 Hitachi -microprocessors. - - 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. - - Cygnus Solutions has sponsored GDB maintenance and much of its -development since 1991. - - -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 `' and the close quote -string to `', 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(,) - - define(baz,defn(foo)) - 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 , Copyright 1995 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(,) - - 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 "", rq=0x34c88 "") - 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 "", rq=0x34c88 "") - 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 "" - (gdb) p rquote - $2 = 0x35d50 "" - -`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(foo)) - - 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, 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 - - 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'). 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 the 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 . You can also use the -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, 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 ) 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 , -construct new arguments rather than repeating exactly as typed. This -permits easy scanning of source or memory. - - GDB can also use 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 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 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 to enter it). For -example, if you type - - (gdb) info bre - -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 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 - 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 , GDB sounds a bell. You can either supply more characters -and try again, or just press 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_' GDB just sounds the bell. Typing again -displays all the function names in your program that begin with those -characters, for example: - - (gdb) b make_ -GDB sounds bell; press 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 twice. `M-?' means -` ?'. You can type this either by holding down a key designated -as the shift on your keyboard (if there is one) while typing -`?', or as 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 or `M-?' to request word completion: - - (gdb) b 'bubble( - 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 -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. - - -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 expresson 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, 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. - - -File: gdb.info, Node: Starting, Next: Arguments, Prev: Compilation, Up: Running - -Starting your program -===================== - -`run' -`r' - Use the `run' command to start your program under GDB. You must - first specify the program name (except on VxWorks) with an - argument to GDB (*note Getting In and Out of GDB: Invocation.), or - by using the `file' or `exec-file' command (*note Commands to - specify files: Files.). - - If you are running your program in an execution environment that -supports processes, `run' creates an inferior process and makes that -process run your program. (In environments without processes, `run' -jumps to the start of 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 only affect -your program the next time you start it.) This information may be -divided into four categories: - -The *arguments.* - Specify the arguments to give your program as the arguments of the - `run' command. If a shell is available on your target, the shell - is used to pass the arguments, so that you may use normal - conventions (such as wildcard expansion or variable substitution) - in describing the arguments. In Unix systems, you can control - which shell is used with the `SHELL' environment variable. *Note - Your program's arguments: Arguments. - -The *environment.* - Your program normally inherits its environment from GDB, but you - can use the GDB commands `set environment' and `unset environment' - to change parts of the environment that affect your program. - *Note Your program's environment: Environment. - -The *working directory.* - Your program inherits its working directory from GDB. You can set - the GDB working directory with the `cd' command in GDB. *Note - Your program's working directory: Working Directory. - -The *standard input and output.* - Your program normally uses the same device for standard input and - standard output as GDB is using. You can redirect input and output - in the `run' command line, or you can use the `tty' command to set - a different device for your program. *Note Your program's input - and output: Input/Output. - - *Warning:* While input and output redirection work, you cannot use - pipes to pass the output of the program you are debugging to - another program; if you attempt this, GDB is likely to wind up - debugging the wrong program. - - When you issue the `run' command, your program begins to execute -immediately. *Note Stopping and continuing: Stopping, for discussion -of how to arrange for your program to stop. Once your program has -stopped, you may call functions in your program, using the `print' or -`call' commands. *Note Examining Data: Data. - - 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. - - -File: gdb.info, Node: Arguments, Next: Environment, Prev: Starting, Up: Running - -Your program's arguments -======================== - - The arguments to your program can be specified by the arguments of -the `run' command. They are passed to a shell, which expands wildcard -characters and performs redirection of I/O, and thence to your program. -Your `SHELL' environment variable (if it exists) specifies what shell -GDB uses. If you do not define `SHELL', GDB uses `/bin/sh'. - - `run' with no arguments uses the same arguments used by the previous -`run', or those set by the `set args' command. - -`set args' - Specify the arguments to be used the next time your program is - run. If `set args' has no arguments, `run' executes your program - with no arguments. Once you have run your program with arguments, - using `set args' before the next `run' is the only way to run it - again without arguments. - -`show args' - Show the arguments to give your program when it is started. - - -File: gdb.info, Node: Environment, Next: Working Directory, Prev: Arguments, Up: Running - -Your program's environment -========================== - - 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 are 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. - -`path DIRECTORY' - Add DIRECTORY to the front of the `PATH' environment variable (the - search path for executables), for both GDB and your program. You - may specify several directory names, separated by `:' or - whitespace. If DIRECTORY is already in the path, it is moved to - the front, so it is searched sooner. - - You can use the string `$cwd' to refer to whatever is the current - working directory at the time GDB searches the path. If you use - `.' instead, it refers to the directory where you executed the - `path' command. GDB replaces `.' in the DIRECTORY argument (with - the current path) before adding DIRECTORY to the search path. - -`show paths' - Display the list of search paths for executables (the `PATH' - environment variable). - -`show environment [VARNAME]' - Print the value of environment variable VARNAME to be given to - your program when it starts. If you do not supply VARNAME, print - the names and values of all environment variables to be given to - your program. You can abbreviate `environment' as `env'. - -`set environment VARNAME [=] VALUE' - Set environment variable VARNAME to VALUE. The value changes for - your program only, not for GDB itself. VALUE may be any string; - the values of environment variables are just strings, and any - interpretation is supplied by your program itself. The VALUE - parameter is optional; if it is eliminated, the variable is set to - a null value. - - For example, this command: - - set env USER = foo - - tells a Unix program, when subsequently run, that its user is named - `foo'. (The spaces around `=' are used for clarity here; they are - not actually required.) - -`unset environment VARNAME' - Remove variable VARNAME from the environment to be passed to your - program. This is different from `set env VARNAME ='; `unset - environment' removes the variable from the environment, rather - than assigning it an empty value. - - *Warning:* GDB runs your program using the shell indicated by your -`SHELL' environment variable if it exists (or `/bin/sh' if not). If -your `SHELL' variable names a shell that runs an initialization -file--such as `.cshrc' for C-shell, or `.bashrc' for BASH--any -variables you set in that file affect your program. You may wish to -move setting of environment variables to files that are only run when -you sign on, such as `.login' or `.profile'. - - -File: gdb.info, Node: Working Directory, Next: Input/Output, Prev: Environment, Up: Running - -Your program's working directory -================================ - - Each time you start your program with `run', it inherits its working -directory from the current working directory of GDB. The GDB working -directory is initially whatever it inherited from its parent process -(typically the shell), but you can specify a new working directory in -GDB with the `cd' command. - - The GDB working directory also serves as a default for the commands -that specify files for GDB to operate on. *Note Commands to specify -files: Files. - -`cd DIRECTORY' - Set the GDB working directory to DIRECTORY. - -`pwd' - Print the GDB working directory. - - -File: gdb.info, Node: Input/Output, Next: Attach, Prev: Working Directory, Up: Running - -Your program's input and output -=============================== - - 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. - -`info terminal' - Displays information recorded by GDB about the terminal modes your - program is using. - - 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'. - - Another way to specify where your program should do input and output -is with the `tty' command. This command accepts a file name as -argument, and causes this file to be the default for future `run' -commands. It also resets the controlling terminal for the child -process, for future `run' commands. For example, - - tty /dev/ttyb - -directs that processes started with subsequent `run' commands default -to do input and output on the terminal `/dev/ttyb' and have that as -their controlling terminal. - - An explicit redirection in `run' overrides the `tty' command's -effect on the input/output device, but not its effect on the controlling -terminal. - - When you use the `tty' command or redirect input in the `run' -command, only the input *for your program* is affected. The input for -GDB still comes from your terminal. - - -File: gdb.info, Node: Attach, Next: Kill Process, Prev: Input/Output, Up: Running - -Debugging an already-running process -==================================== - -`attach PROCESS-ID' - This command attaches to a running process--one that was started - outside GDB. (`info files' shows your active targets.) The - command takes as argument a process ID. The usual way to find out - the process-id of a Unix process is with the `ps' utility, or with - the `jobs -l' shell command. - - `attach' does not repeat if you press a second time after - executing the command. - - To use `attach', your program must be running in an environment -which supports processes; for example, `attach' does not work for -programs on bare-board targets that lack an operating system. You must -also 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. -*Note Commands to Specify Files: Files. - - 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 would rather the process -continue running, you may use the `continue' command after attaching -GDB to the process. - -`detach' - When you have finished debugging the attached process, you can use - the `detach' command to release it from GDB control. Detaching - the process continues its execution. After the `detach' command, - that process and GDB become completely independent once more, and - you are ready to `attach' another process or start one with `run'. - `detach' does not repeat if you press again after executing - the command. - - 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 (*note Optional -warnings and messages: Messages/Warnings.). - diff --git a/gnu/dist/gdb/doc/gdb.info-2 b/gnu/dist/gdb/doc/gdb.info-2 deleted file mode 100644 index dee6fadc3b29..000000000000 --- a/gnu/dist/gdb/doc/gdb.info-2 +++ /dev/null @@ -1,1185 +0,0 @@ -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 Fifth Edition, April 1998, of `Debugging with GDB: the -GNU Source-Level Debugger' for GDB Version . - - Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, -1997, 1998 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: Kill Process, Next: Process Information, Prev: Attach, Up: Running - -Killing the child process -========================= - -`kill' - Kill the child process in which your program is running under GDB. - - 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. - - On some operating systems, a program cannot be executed outside GDB -while you have breakpoints set on it inside GDB. You can use the -`kill' command in this situation to permit running your program outside -the debugger. - - The `kill' command is also useful if you wish to recompile and -relink your program, since on many systems it is impossible to modify an -executable file while it is running in a process. In this case, 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). - - -File: gdb.info, Node: Process Information, Next: Threads, Prev: Kill Process, Up: Running - -Additional process information -============================== - - Some operating systems provide a facility called `/proc' that can be -used to examine the image of a running process using file-system -subroutines. If GDB is configured for an operating system with this -facility, the command `info proc' is available to report on several -kinds of information about the process running your program. `info -proc' works only on SVR4 systems that support `procfs'. - -`info proc' - Summarize available information about the process. - -`info proc mappings' - Report on the address ranges accessible in the program, with - information on whether your program may read, write, or execute - each range. - -`info proc times' - Starting time, user CPU time, and system CPU time for your program - and its children. - -`info proc id' - Report on the process IDs related to your program: its own process - ID, the ID of its parent, the process group ID, and the session ID. - -`info proc status' - General information on the state of the process. If the process is - stopped, this report includes the reason for stopping, and any - signal received. - -`info proc all' - Show all the above information about the process. - - -File: gdb.info, Node: Threads, Next: Processes, Prev: Process Information, Up: Running - -Debugging programs with multiple threads -======================================== - - In some operating systems, a single program may have more than one -"thread" of execution. The precise semantics of threads differ from -one operating system to another, but in general the threads of a single -program are akin to multiple processes--except that they share one -address space (that is, they can all examine and modify the same -variables). On the other hand, each thread has its own registers and -execution stack, and perhaps private memory. - - GDB provides these facilities for debugging multi-thread programs: - - * automatic notification of new threads - - * `thread THREADNO', a command to switch among threads - - * `info threads', a command to inquire about existing threads - - * `thread apply [THREADNO] [ALL] ARGS', a command to apply a command - to a list of threads - - * thread-specific breakpoints - - *Warning:* These facilities are not yet available on every GDB - configuration where the operating system supports threads. If - your GDB does not support threads, these commands have no effect. - For example, a system without thread support shows no output from - `info threads', and always rejects the `thread' command, like this: - - (gdb) info threads - (gdb) thread 1 - Thread ID 1 not known. Use the "info threads" command to - see the IDs of currently known threads. - - The GDB thread debugging facility allows you to 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. - - Whenever GDB detects a new thread in your program, it displays the -target system's identification for the thread with a message in the -form `[New SYSTAG]'. SYSTAG is a thread identifier whose form varies -depending on the particular system. For example, on LynxOS, you might -see - - [New process 35 thread 27] - -when GDB notices a new thread. In contrast, on an SGI system, the -SYSTAG is simply something like `process 368', with no further -qualifier. - - For debugging purposes, GDB associates its own thread number--always -a single integer--with each thread in your program. - -`info threads' - Display a summary of all threads currently in your program. GDB - displays for each thread (in this order): - - 1. the thread number assigned by GDB - - 2. the target system's thread identifier (SYSTAG) - - 3. the current stack frame summary for that thread - - 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 - -`thread THREADNO' - Make thread number THREADNO the current thread. The command - argument THREADNO is the internal GDB thread number, as shown in - the first field of the `info threads' display. GDB responds by - displaying the system identifier of the thread you selected, and - its current stack frame summary: - - (gdb) thread 2 - [Switching to process 35 thread 23] - 0x34e5 in sigpause () - - As with the `[New ...]' message, the form of the text after - `Switching to' depends on your system's conventions for identifying - threads. - -`thread apply [THREADNO] [ALL] ARGS' - The `thread apply' command allows you to apply a command to one or - more threads. Specify the numbers of the threads that you want - affected with the command argument THREADNO. THREADNO is the - internal GDB thread number, as shown in the first field of the - `info threads' display. To apply a command to all threads, use - `thread apply all' ARGS. - - Whenever GDB stops your program, due to 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. - - *Note Stopping and starting multi-thread programs: Thread Stops, for -more information about how GDB behaves when you stop and start programs -with multiple threads. - - *Note Setting watchpoints: Set Watchpoints, for information about -watchpoints in programs with multiple threads. - - -File: gdb.info, Node: Processes, Prev: Threads, Up: Running - -Debugging programs with multiple processes -========================================== - - GDB has no special support for debugging programs which create -additional processes using the `fork' function. When a program forks, -GDB will continue to debug the parent process and the child process -will run unimpeded. If you have set a breakpoint in any code which the -child then executes, the child will get a `SIGTRAP' signal which -(unless it catches the signal) will cause it to terminate. - - However, if you want to debug the child process there is a workaround -which isn't too painful. Put a call to `sleep' in the code which the -child process executes after the fork. It may be useful to sleep only -if a certain environment variable is set, or a certain file exists, so -that the delay need not occur when you don't want to run GDB on the -child. While the child is sleeping, use the `ps' program to get its -process ID. Then tell GDB (a new invocation of GDB if you are also -debugging the parent process) to attach to the child process (see *Note -Attach::). From that point on you can debug the child process just -like any other process which you attached to. - - -File: gdb.info, Node: Stopping, Next: Stack, Prev: Running, Up: Top - -Stopping and Continuing -*********************** - - The principal purposes of using a debugger are so that you can stop -your program before it terminates; or so that, if your program runs into -trouble, you can investigate and find out why. - - 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. - -`info program' - Display information about the status of your program: whether it is - running or not, what process it is, and why it stopped. - -* Menu: - - -* Breakpoints:: Breakpoints, watchpoints, and exceptions - -* Continuing and Stepping:: Resuming execution - -* Signals:: Signals - -* Thread Stops:: Stopping and starting multi-thread programs - - -File: gdb.info, Node: Breakpoints, Next: Continuing and Stepping, Up: Stopping - -Breakpoints, watchpoints, and exceptions -======================================== - - 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 (*note Setting -breakpoints: Set Breaks.), 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 (*note -Breakpoints and exceptions: Exception Handling.). - - In SunOS 4.x, SVR4, and Alpha OSF/1 configurations, you can now set -breakpoints in shared libraries before the executable is run. - - 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 (*note Setting watchpoints: Set 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. *Note Automatic -display: Auto Display. - - GDB assigns a number to each breakpoint or watchpoint when you -create it; these numbers are successive integers starting with one. 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. - -* Menu: - -* Set Breaks:: Setting breakpoints -* Set Watchpoints:: Setting watchpoints - -* Exception Handling:: Breakpoints and exceptions - -* Delete Breaks:: Deleting breakpoints -* Disabling:: Disabling breakpoints -* Conditions:: Break conditions -* Break Commands:: Breakpoint command lists - -* Breakpoint Menus:: Breakpoint menus - - -File: gdb.info, Node: Set Breaks, Next: Set Watchpoints, Up: Breakpoints - -Setting breakpoints -------------------- - - Breakpoints are set with the `break' command (abbreviated `b'). The -debugger convenience variable `$bpnum' records the number of the -breakpoints you've set most recently; see *Note Convenience variables: -Convenience Vars, for a discussion of what you can do with convenience -variables. - - You have several ways to say where the breakpoint should go. - -`break FUNCTION' - Set a breakpoint at entry to function FUNCTION. When using source - languages that permit overloading of symbols, such as C++, - FUNCTION may refer to more than one possible place to break. - *Note Breakpoint menus: Breakpoint Menus, for a discussion of that - situation. - -`break +OFFSET' -`break -OFFSET' - Set a breakpoint some number of lines forward or back from the - position at which execution stopped in the currently selected - frame. - -`break LINENUM' - Set a breakpoint at line LINENUM in the current source file. That - file is the last file whose source text was printed. This - breakpoint stops your program just before it executes any of the - code on that line. - -`break FILENAME:LINENUM' - Set a breakpoint at line LINENUM in source file FILENAME. - -`break FILENAME:FUNCTION' - Set a breakpoint at entry to function FUNCTION found in file - FILENAME. Specifying a file name as well as a function name is - superfluous except when multiple files contain similarly named - functions. - -`break *ADDRESS' - Set a breakpoint at address ADDRESS. You can use this to set - breakpoints in parts of your program which do not have debugging - information or source files. - -`break' - When called without any arguments, `break' sets a breakpoint at - the next instruction to be executed in the selected stack frame - (*note Examining the Stack: Stack.). In any selected frame but the - innermost, this makes your program stop as soon as control returns - to that frame. This is similar to the effect of a `finish' - command in the frame inside the selected frame--except that - `finish' does not leave an active breakpoint. If you use `break' - without an argument in the innermost frame, GDB stops the next - time it reaches the current location; this may be useful inside - loops. - - GDB normally ignores breakpoints when it resumes execution, until - at least one instruction has been executed. If it did not do - this, you would be unable to proceed past a breakpoint without - first disabling the breakpoint. This rule applies whether or not - the breakpoint already existed when your program stopped. - -`break ... if COND' - Set a breakpoint with condition COND; evaluate the expression COND - each time the breakpoint is reached, and stop only if the value is - nonzero--that is, if COND evaluates as true. `...' stands for one - of the possible arguments described above (or no argument) - specifying where to break. *Note Break conditions: Conditions, - for more information on breakpoint conditions. - -`tbreak ARGS' - Set a breakpoint enabled only for one stop. ARGS are the same as - for the `break' command, and the breakpoint is set in the same - way, but the breakpoint is automatically deleted after the first - time your program stops there. *Note Disabling breakpoints: - Disabling. - -`hbreak ARGS' - Set a hardware-assisted breakpoint. ARGS are the same as for the - `break' command and the breakpoint is set in the same way, but the - breakpoint requires hardware support and some target hardware may - not have this support. The main purpose of this is EPROM/ROM code - debugging, so you can set a breakpoint at an instruction without - changing the instruction. This can be used with the new - trap-generation provided by SPARClite DSU. DSU will generate - traps when a program accesses some date or instruction address - that is assigned to the debug registers. However the hardware - breakpoint registers can only take two data breakpoints, and GDB - will reject this command if more than two are used. Delete or - disable usused hardware breakpoints before setting new ones. - *Note Break conditions: Conditions. - -`thbreak ARGS' - Set a hardware-assisted breakpoint enabled only for one stop. ARGS - are the same as for the `hbreak' command and the breakpoint is set - in the same way. However, like the `tbreak' command, the - breakpoint is automatically deleted after the first time your - program stops there. Also, like the `hbreak' command, the - breakpoint requires hardware support and some target hardware may - not have this support. *Note Disabling breakpoints: Disabling. - Also *Note Break conditions: Conditions. - -`rbreak REGEX' - Set breakpoints on all functions matching the regular expression - REGEX. This command sets an unconditional breakpoint on all - matches, printing a list of all breakpoints it set. Once these - breakpoints are set, they are treated just like the breakpoints - set with the `break' command. You can delete them, disable them, - or make them conditional the same way as any other breakpoint. - - When debugging C++ programs, `rbreak' is useful for setting - breakpoints on overloaded functions that are not members of any - special classes. - -`info breakpoints [N]' -`info break [N]' -`info watchpoints [N]' - Print a table of all breakpoints and watchpoints set and not - deleted, with the following columns for each breakpoint: - - *Breakpoint Numbers* - - *Type* - Breakpoint or watchpoint. - - *Disposition* - Whether the breakpoint is marked to be disabled or deleted - when hit. - - *Enabled or Disabled* - Enabled breakpoints are marked with `y'. `n' marks - breakpoints that are not enabled. - - *Address* - Where the breakpoint is in your program, as a memory address - - *What* - Where the breakpoint is in the source for your program, as a - file and line number. - - 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. - - `info break' 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 (*note Examining memory: Memory.). - - `info break' now displays a count of 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 info to see how many times - the breakpoint was hit, and then run again, ignoring one less than - that number. This will get you quickly to the last hit of that - breakpoint. - - GDB allows you to set any number of breakpoints at the same place in -your program. There is nothing silly or meaningless about this. When -the breakpoints are conditional, this is even useful (*note Break -conditions: 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' does not display them. - - You can see these breakpoints with the GDB maintenance command -`maint info breakpoints'. - -`maint info breakpoints' - Using the same format as `info breakpoints', display both the - breakpoints you've set explicitly, and those GDB is using for - internal purposes. Internal breakpoints are shown with negative - breakpoint numbers. The type column identifies what kind of - breakpoint is shown: - - `breakpoint' - Normal, explicitly set breakpoint. - - `watchpoint' - Normal, explicitly set watchpoint. - - `longjmp' - Internal breakpoint, used to handle correctly stepping through - `longjmp' calls. - - `longjmp resume' - Internal breakpoint at the target of a `longjmp'. - - `until' - Temporary internal breakpoint used by the GDB `until' command. - - `finish' - Temporary internal breakpoint used by the GDB `finish' - command. - - -File: gdb.info, Node: Set Watchpoints, Next: Exception Handling, Prev: Set Breaks, Up: Breakpoints - -Setting watchpoints -------------------- - - 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. - - Watchpoints currently execute two orders of magnitude more slowly -than other breakpoints, but this can be well worth it to catch errors -where you have no clue what part of your program is the culprit. - -`watch EXPR' - Set a watchpoint for an expression. GDB will break when EXPR is - written into by the program and its value changes. This can be - used with the new trap-generation provided by SPARClite DSU. DSU - will generate traps when a program accesses some date or - instruction address that is assigned to the debug registers. For - the data addresses, DSU facilitates the `watch' command. However - the hardware breakpoint registers can only take two data - watchpoints, and both watchpoints must be the same kind. For - example, you can set two watchpoints with `watch' commands, two - with `rwatch' commands, *or* two with `awatch' commands, but you - cannot set one watchpoint with one command and the other with a - different command. {No Value For "GBDN"} will reject the command - if you try to mix watchpoints. Delete or disable unused - watchpoint commands before setting new ones. - -`rwatch EXPR' - Set a watchpoint that will break when watch ARGS is read by the - program. If you use both watchpoints, both must be set with the - `rwatch' command. - -`awatch EXPR' - Set a watchpoint that will break when ARGS is read and written into - by the program. If you use both watchpoints, both must be set - with the `awatch' command. - -`info watchpoints' - This command prints a list of watchpoints and breakpoints; it is - the same as `info break'. - - *Warning:* in multi-thread programs, watchpoints have only limited - usefulness. With the current watchpoint implementation, GDB can - only watch the value of an expression *in a single thread*. If - you are confident that the expression can only change due to the - current thread's activity (and if you are also confident that no - other thread can become current), then you can use watchpoints as - usual. However, GDB may not notice when a non-current thread's - activity changes the expression. - - -File: gdb.info, Node: Exception Handling, Next: Delete Breaks, Prev: Set Watchpoints, Up: Breakpoints - -Breakpoints and exceptions --------------------------- - - 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. - -`catch EXCEPTIONS' - You can set breakpoints at active exception handlers by using the - `catch' command. EXCEPTIONS is a list of names of exceptions to - catch. - - You can use `info catch' to list active exception handlers. *Note -Information about a frame: Frame Info. - - There are currently some limitations to exception handling in GDB: - - * If you call a function interactively, GDB normally returns control - to you when the function has finished executing. If the call - raises an exception, however, the call may bypass the mechanism - that returns control to you and cause your program to simply - continue running until it hits a breakpoint, catches a signal that - GDB is listening for, or exits. - - * You cannot raise an exception interactively. - - * You cannot install an exception handler interactively. - - Sometimes `catch' is not the best way to debug exception handling: -if you need to know exactly where an exception is raised, it is 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: - - /* ADDR is where the exception identifier is stored. - ID is the exception identifier. */ - void __raise_exception (void **ADDR, void *ID); - -To make the debugger catch all exceptions before any stack unwinding -takes place, set a breakpoint on `__raise_exception' (*note -Breakpoints; watchpoints; and exceptions: Breakpoints.). - - With a conditional breakpoint (*note Break conditions: 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. - - -File: gdb.info, Node: Delete Breaks, Next: Disabling, Prev: Exception Handling, Up: Breakpoints - -Deleting breakpoints --------------------- - - It is often necessary to eliminate a breakpoint or watchpoint once it -has 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; it 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. - - It is not necessary 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. - -`clear' - Delete any breakpoints at the next instruction to be executed in - the selected stack frame (*note Selecting a frame: Selection.). - When the innermost frame is selected, this is a good way to delete - a breakpoint where your program just stopped. - -`clear FUNCTION' -`clear FILENAME:FUNCTION' - Delete any breakpoints set at entry to the function FUNCTION. - -`clear LINENUM' -`clear FILENAME:LINENUM' - Delete any breakpoints set at or within the code of the specified - line. - -`delete [breakpoints] [BNUMS...]' - Delete the breakpoints or watchpoints of the numbers specified as - arguments. If no argument is specified, delete all breakpoints - (GDB asks confirmation, unless you have `set confirm off'). You - can abbreviate this command as `d'. - - -File: gdb.info, Node: Disabling, Next: Conditions, Prev: Delete Breaks, Up: Breakpoints - -Disabling breakpoints ---------------------- - - Rather than deleting 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 do not know which numbers to use. - - A breakpoint or watchpoint can have any of four different states of -enablement: - - * Enabled. The breakpoint stops your program. A breakpoint set - with the `break' command starts out in this state. - - * Disabled. The breakpoint has no effect on your program. - - * Enabled once. The breakpoint stops your program, but then becomes - disabled. A breakpoint set with the `tbreak' command starts out in - this state. - - * Enabled for deletion. The breakpoint stops your program, but - immediately after it does so it is deleted permanently. - - You can use the following commands to enable or disable breakpoints -and watchpoints: - -`disable [breakpoints] [BNUMS...]' - Disable the specified breakpoints--or all breakpoints, if none are - listed. A disabled breakpoint has no effect but is not forgotten. - All options such as ignore-counts, conditions and commands are - remembered in case the breakpoint is enabled again later. You may - abbreviate `disable' as `dis'. - -`enable [breakpoints] [BNUMS...]' - Enable the specified breakpoints (or all defined breakpoints). - They become effective once again in stopping your program. - -`enable [breakpoints] once BNUMS...' - Enable the specified breakpoints temporarily. GDB disables any of - these breakpoints immediately after stopping your program. - -`enable [breakpoints] delete BNUMS...' - Enable the specified breakpoints to work once, then die. GDB - deletes any of these breakpoints as soon as your program stops - there. - - Except for a breakpoint set with `tbreak' (*note Setting -breakpoints: Set Breaks.), 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 does not change the state of your other -breakpoints; see *Note Continuing and stepping: Continuing and -Stepping.) - - -File: gdb.info, Node: Conditions, Next: Break Commands, Prev: Disabling, Up: Breakpoints - -Break conditions ----------------- - - 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 (*note Expressions: 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 is 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 (*note Breakpoint -command lists: Break Commands.). - - Break conditions can be specified when a breakpoint is set, by using -`if' in the arguments to the `break' command. *Note Setting -breakpoints: Set Breaks. They can also be changed at any time with the -`condition' command. The `watch' command does not recognize the `if' -keyword; `condition' is the only way to impose a further condition on a -watchpoint. - -`condition BNUM EXPRESSION' - Specify EXPRESSION as the break condition for breakpoint or - watchpoint number BNUM. After you set a condition, breakpoint - BNUM stops your program only if the value of EXPRESSION is true - (nonzero, in C). When you use `condition', GDB checks EXPRESSION - immediately for syntactic correctness, and to determine whether - symbols in it have referents in the context of your breakpoint. - GDB does not actually evaluate EXPRESSION at the time the - `condition' command is given, however. *Note Expressions: - Expressions. - -`condition BNUM' - Remove the condition from breakpoint number BNUM. It becomes an - ordinary unconditional breakpoint. - - 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 is 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 does not stop the next N times your program reaches -it. - -`ignore BNUM COUNT' - Set the ignore count of breakpoint number BNUM to COUNT. The next - COUNT times the breakpoint is reached, your program's execution - does not stop; other than to decrement the ignore count, GDB takes - no action. - - To make the breakpoint stop the next time it is 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 using `ignore'. *Note - Continuing and stepping: Continuing and Stepping. - - If a breakpoint has a positive ignore count and a condition, the - condition is not 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 - is decremented each time. *Note Convenience variables: - Convenience Vars. - - -File: gdb.info, Node: Break Commands, Next: Breakpoint Menus, Prev: Conditions, Up: Breakpoints - -Breakpoint command lists ------------------------- - - 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. - -`commands [BNUM]' -`... COMMAND-LIST ...' -`end' - Specify a list of commands for breakpoint number BNUM. The - commands themselves appear on the following lines. Type a line - containing just `end' to terminate the commands. - - 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 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. -Simply use the `continue' command, or `step', or any other command that -resumes execution. - - Any other commands in the command list, after 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 is not 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. `silent' 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. *Note Commands for controlled output: Output. - - For example, here is 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 does not stop, and start with the `silent' command so -that no output is produced. Here is an example: - - break 403 - commands - silent - set x = y + 4 - cont - end - - -File: gdb.info, Node: Breakpoint Menus, Prev: Break Commands, Up: Breakpoints - -Breakpoint menus ----------------- - - 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' is not 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) - - -File: gdb.info, Node: Continuing and Stepping, Next: Signals, Prev: Breakpoints, Up: Stopping - -Continuing and stepping -======================= - - "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. *Note Signals: Signals.) - -`continue [IGNORE-COUNT]' -`c [IGNORE-COUNT]' -`fg [IGNORE-COUNT]' - Resume program execution, at the address where your program last - stopped; any breakpoints set at that address are bypassed. The - optional argument IGNORE-COUNT allows you to specify a further - number of times to ignore a breakpoint at this location; its - effect is like that of `ignore' (*note Break conditions: - Conditions.). - - 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' -(*note Returning from a function: Returning.) to go back to the calling -function; or `jump' (*note Continuing at a different address: Jumping.) -to go to an arbitrary location in your program. - - A typical technique for using stepping is to set a breakpoint (*note -Breakpoints; watchpoints; and exceptions: Breakpoints.) 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. - -`step' - Continue running your program until control reaches a different - source line, then stop it and return control to GDB. This command - is abbreviated `s'. - - *Warning:* 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 - will not step into a function which is compiled without - debugging information. To step through functions without - debugging information, use the `stepi' command, described - below. - - The `step' command now only stops at the first instruction of a - source line. This prevents the multiple stops that used to occur - in switch statements, for loops, etc. `step' continues to stop if - a function that has debugging information is called within the - line. - - Also, the `step' command now only enters a subroutine if there is - line number information for the subroutine. Otherwise it acts - like the `next' command. This avoids problems when using `cc -gl' - on MIPS machines. Previously, `step' entered subroutines if there - was any debugging information about the routine. - -`step COUNT' - Continue running as in `step', but do so COUNT times. If a - breakpoint is reached, or a signal not related to stepping occurs - before COUNT steps, stepping stops right away. - -`next [COUNT]' - Continue to the next source line in the current (innermost) stack - frame. This is similar to `step', but function calls that appear - within the line of code are executed without stopping. Execution - stops when control reaches a different line of code at the - original stack level that was executing when you gave the `next' - command. This command is abbreviated `n'. - - An argument COUNT is a repeat count, as for `step'. - - The `next' command now only stops at the first instruction of a - source line. This prevents the multiple stops that used to occur - in swtch statements, for loops, etc. - -`finish' - Continue running until just after function in the selected stack - frame returns. Print the returned value (if any). - - Contrast this with the `return' command (*note Returning from a - function: Returning.). - -`u' - -`until' - Continue running until a source line past the current line, in the - current stack frame, is reached. This command is used to avoid - single stepping through a loop more than once. It is like the - `next' command, except that when `until' encounters a jump, it - automatically continues execution until the program counter is - greater than the address of the jump. - - 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. - - `until' always stops your program if it attempts to exit the - current stack frame. - - `until' may produce somewhat counterintuitive results if the order - of machine code does not 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 has not really gone to an earlier - statement--not in terms of the actual machine code. - - `until' with no argument works by means of single instruction - stepping, and hence is slower than `until' with an argument. - -`until LOCATION' -`u LOCATION' - Continue running your program until either the specified location - is reached, or the current stack frame returns. LOCATION is any of - the forms of argument acceptable to `break' (*note Setting - breakpoints: Set Breaks.). This form of the command uses - breakpoints, and hence is quicker than `until' without an argument. - -`stepi' -`si' - Execute one machine instruction, then stop and return to the - debugger. - - It is 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. *Note - Automatic display: Auto Display. - - An argument is a repeat count, as in `step'. - -`nexti' -`ni' - Execute one machine instruction, but if it is a function call, - proceed until the function returns. - - An argument is a repeat count, as in `next'. - - -File: gdb.info, Node: Signals, Next: Thread Stops, Prev: Continuing and Stepping, Up: Stopping - -Signals -======= - - 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. For example, in Unix `SIGINT' is the signal -a program gets when you type an interrupt (often `C-c'); `SIGSEGV' is -the signal a program gets from referencing a place in memory far away -from all the areas in use; `SIGALRM' occurs when 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" (kill your program immediately) if the -program has not specified in advance some other way to handle the -signal. `SIGINT' does not indicate an error in your program, but it is -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, GDB is set up to ignore non-erroneous signals like -`SIGALRM' (so as not to interfere with their role in the functioning of -your program) but to stop your program immediately whenever an error -signal happens. You can change these settings with the `handle' -command. - -`info signals' - Print a table of all the kinds of signals and how GDB has been - told to handle each one. You can use this to see the signal - numbers of all the defined types of signals. - - `info handle' is the new alias for `info signals'. - -`handle SIGNAL KEYWORDS...' - Change the way GDB handles signal SIGNAL. SIGNAL can be the - number of a signal or its name (with or without the `SIG' at the - beginning). The KEYWORDS say what change to make. - - The keywords allowed by the `handle' command can be abbreviated. -Their full names are: - -`nostop' - GDB should not stop your program when this signal happens. It may - still print a message telling you that the signal has come in. - -`stop' - GDB should stop your program when this signal happens. This - implies the `print' keyword as well. - -`print' - GDB should print a message when this signal happens. - -`noprint' - GDB should not mention the occurrence of the signal at all. This - implies the `nostop' keyword as well. - -`pass' - GDB should allow your program to see this signal; your program can - handle the signal, or else it may terminate if the signal is fatal - and not handled. - -`nopass' - GDB should not allow your program to see this signal. - - When a signal stops your program, the signal is not 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 would not 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'. *Note Giving your program a signal: -Signaling. - diff --git a/gnu/dist/gdb/doc/gdb.info-3 b/gnu/dist/gdb/doc/gdb.info-3 deleted file mode 100644 index e857543bd734..000000000000 --- a/gnu/dist/gdb/doc/gdb.info-3 +++ /dev/null @@ -1,1149 +0,0 @@ -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 Fifth Edition, April 1998, of `Debugging with GDB: the -GNU Source-Level Debugger' for GDB Version . - - Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, -1997, 1998 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: Thread Stops, Prev: Signals, Up: Stopping - -Stopping and starting multi-thread programs -=========================================== - - When your program has multiple threads (*note Debugging programs -with multiple threads: Threads.), you can choose whether to set -breakpoints on all threads, or on a particular thread. - -`break LINESPEC thread THREADNO' -`break LINESPEC thread THREADNO if ...' - LINESPEC specifies source lines; there are several ways of writing - them, but the effect is always to specify some source line. - - Use the qualifier `thread THREADNO' with a breakpoint command to - specify that you only want GDB to stop the program when a - particular thread reaches this breakpoint. THREADNO is one of the - numeric thread identifiers assigned by GDB, shown in the first - column of the `info threads' display. - - If you do not 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 allows you to -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 cannot single-step all threads in lockstep. -Since thread scheduling is up to your debugging target's operating -system (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. - - -File: gdb.info, Node: Stack, Next: Source, Prev: Stopping, Up: Top - -Examining the Stack -******************* - - 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 are interested in. *Note Selecting a frame: -Selection. - - When your program stops, GDB automatically selects the currently -executing frame and describes it briefly, similar to the `frame' -command (*note Information about a frame: Frame Info.). - -* Menu: - -* Frames:: Stack frames -* Backtrace:: Backtraces -* Selection:: Selecting a frame -* Frame Info:: Information on a frame - -* MIPS Stack:: MIPS machines and the function stack - - -File: gdb.info, Node: Frames, Next: Backtrace, Up: Stack - -Stack frames -============ - - 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 zero -for the innermost frame, one for the frame that called it, and so on -upward. These numbers do not really exist in your program; they are -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 save the frame -setup time. 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 zero as usual, allowing correct tracing of the function call -chain. However, GDB has no provision for frameless functions elsewhere -in the stack. - -`frame ARGS' - The `frame' command allows you to move from one stack frame to - another, and to print the stack frame you select. ARGS may be - either the address of the frame or the stack frame number. - Without an argument, `frame' prints the current stack frame. - -`select-frame' - The `select-frame' command allows you to move from one stack frame - to another without printing the frame. This is the silent version - of `frame'. - - -File: gdb.info, Node: Backtrace, Next: Selection, Prev: Frames, Up: Stack - -Backtraces -========== - - 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 zero), followed by its caller (frame one), and -on up the stack. - -`backtrace' -`bt' - Print a backtrace of the entire stack: one line per frame for all - frames in the stack. - - You can stop the backtrace at any time by typing the system - interrupt character, normally `C-c'. - -`backtrace N' -`bt N' - Similar, but print only the innermost N frames. - -`backtrace -N' -`bt -N' - Similar, but print only the outermost N frames. - - The names `where' and `info stack' (abbreviated `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 file name and -line number, as well as the arguments to the function. The program -counter value is omitted if it is at the beginning of the code for that -line number. - - Here is 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 zero does not begin with a program counter value, -indicating that your program has stopped at the beginning of the code -for line `993' of `builtin.c'. - - -File: gdb.info, Node: Selection, Next: Frame Info, Prev: Backtrace, Up: Stack - -Selecting a frame -================= - - 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. - -`frame N' -`f N' - Select frame number N. Recall that frame zero is the innermost - (currently executing) frame, frame one is the frame that called the - innermost one, and so on. The highest-numbered frame is the one - for `main'. - -`frame ADDR' -`f ADDR' - Select the frame at address ADDR. This is useful mainly if the - chaining of stack frames has been damaged by a bug, making it - impossible for GDB to assign numbers properly to all frames. In - addition, this can be useful when your program has multiple stacks - and switches between them. - - On the SPARC architecture, `frame' needs two addresses to select - an arbitrary frame: a frame pointer and a stack pointer. - - On the MIPS and Alpha architecture, it needs two addresses: a stack - pointer and a program counter. - - On the 29k architecture, it needs three addresses: a register stack - pointer, a program counter, and a memory stack pointer. - -`up N' - Move N frames up the stack. For positive numbers N, this advances - toward the outermost frame, to higher frame numbers, to frames - that have existed longer. N defaults to one. - -`down N' - Move N frames down the stack. For positive numbers N, this - advances toward the innermost frame, to lower frame numbers, to - frames that were created more recently. N defaults to one. You - may abbreviate `down' as `do'. - - 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. *Note -Printing source lines: List. - -`up-silently N' -`down-silently N' - These two commands are variants of `up' and `down', respectively; - they differ in that they do their work silently, without causing - display of the new frame. They are intended primarily for use in - GDB command scripts, where the output might be unnecessary and - distracting. - - -File: gdb.info, Node: Frame Info, Next: MIPS Stack, Prev: Selection, Up: Stack - -Information about a frame -========================= - - There are several other commands to print information about the -selected stack frame. - -`frame' -`f' - When used without any argument, this command does not change which - frame is selected, but prints a brief description of the currently - selected stack frame. It can be abbreviated `f'. With an - argument, this command is used to select a stack frame. *Note - Selecting a frame: Selection. - -`info frame' -`info f' - This command prints a verbose description of the selected stack - frame, including: - - * the address of the frame - - * the address of the next frame down (called by this frame) - - * the address of the next frame up (caller of this frame) - - * the language in which the source code corresponding to this - frame is written - - * the address of the frame's arguments - - * the program counter saved in it (the address of execution in - the caller frame) - - * which registers were saved in the frame - - The verbose description is useful when something has gone wrong - that has made the stack format fail to fit the usual conventions. - -`info frame ADDR' -`info f ADDR' - Print a verbose description of the frame at address ADDR, without - selecting that frame. The selected frame remains unchanged by this - command. This requires the same kind of address (more than one - for some architectures) that you specify in the `frame' command. - *Note Selecting a frame: Selection. - -`info args' - Print the arguments of the selected frame, each on a separate line. - -`info locals' - Print the local variables of the selected frame, each on a separate - line. These are all variables (declared either static or - automatic) accessible at the point of execution of the selected - frame. - -`info catch' - Print a list of all the exception handlers that are active in the - current stack frame at the current point of execution. To see - other exception handlers, visit the associated frame (using the - `up', `down', or `frame' commands); then type `info catch'. *Note - Breakpoints and exceptions: Exception Handling. - - -File: gdb.info, Node: MIPS Stack, Prev: Frame Info, Up: Stack - -MIPS machines and the function stack -==================================== - - 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: - -`set heuristic-fence-post LIMIT' - Restrict GDB to examining at most LIMIT bytes in its search for - the beginning of a function. A value of 0 (the default) means - there is no limit. However, except for 0, the larger the limit - the more bytes `heuristic-fence-post' must search and therefore - the longer it takes to run. - -`show heuristic-fence-post' - Display the current limit. - -These commands are available *only* when GDB is configured for -debugging programs on MIPS processors. - - -File: gdb.info, Node: Source, Next: Data, Prev: Stack, Up: Top - -Examining Source Files -********************** - - 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 -(*note Selecting a frame: Selection.), GDB prints the line where -execution in that frame has stopped. You can print other portions of -source files by explicit command. - - If you use GDB through its GNU Emacs interface, you may prefer to use -Emacs facilities to view source; *note Using GDB under GNU Emacs: -Emacs.. - -* Menu: - -* List:: Printing source lines - -* Search:: Searching source files - -* Source Path:: Specifying source directories -* Machine Code:: Source and machine code - - -File: gdb.info, Node: List, Next: Search, Up: Source - -Printing source lines -===================== - - To print lines from a source file, use the `list' command -(abbreviated `l'). 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: - -`list LINENUM' - Print lines centered around line number LINENUM in the current - source file. - -`list FUNCTION' - Print lines centered around the beginning of function FUNCTION. - -`list' - Print more lines. If the last lines printed were printed with a - `list' command, this prints lines following the last lines - printed; however, if the last line printed was a solitary line - printed as part of displaying a stack frame (*note Examining the - Stack: Stack.), this prints lines centered around that line. - -`list -' - Print lines just before the lines last printed. - - By default, GDB prints ten source lines with any of these forms of -the `list' command. You can change this using `set listsize': - -`set listsize COUNT' - Make the `list' command display COUNT source lines (unless the - `list' argument explicitly specifies some other number). - -`show listsize' - Display the number of lines that `list' prints. - - Repeating a `list' command with discards the argument, so it -is 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 is a complete description of the possible arguments for `list': - -`list LINESPEC' - Print lines centered around the line specified by LINESPEC. - -`list FIRST,LAST' - Print lines from FIRST to LAST. Both arguments are linespecs. - -`list ,LAST' - Print lines ending with LAST. - -`list FIRST,' - Print lines starting with FIRST. - -`list +' - Print lines just after the lines last printed. - -`list -' - Print lines just before the lines last printed. - -`list' - As described in the preceding table. - - Here are the ways of specifying a single source line--all the kinds -of linespec. - -`NUMBER' - Specifies line NUMBER of the current source file. When a `list' - command has two linespecs, this refers to the same source file as - the first linespec. - -`+OFFSET' - Specifies the line OFFSET lines after the last line printed. When - used as the second linespec in a `list' command that has two, this - specifies the line OFFSET lines down from the first linespec. - -`-OFFSET' - Specifies the line OFFSET lines before the last line printed. - -`FILENAME:NUMBER' - Specifies line NUMBER in the source file FILENAME. - -`FUNCTION' - Specifies the line that begins the body of the function FUNCTION. - For example: in C, this is the line with the open brace. - -`FILENAME:FUNCTION' - Specifies the line of the open-brace that begins the body of the - function FUNCTION in the file FILENAME. You only need the file - name with a function name to avoid ambiguity when there are - identically named functions in different source files. - -`*ADDRESS' - Specifies the line containing the program address ADDRESS. - ADDRESS may be any expression. - - -File: gdb.info, Node: Search, Next: Source Path, Prev: List, Up: Source - -Searching source files -====================== - - There are two commands for searching through the current source file -for a regular expression. - -`forward-search REGEXP' -`search REGEXP' - The command `forward-search REGEXP' checks each line, starting - with the one following the last line listed, for a match for - REGEXP. It lists the line that is found. You can use the synonym - `search REGEXP' or abbreviate the command name as `fo'. - -`reverse-search REGEXP' - The command `reverse-search REGEXP' checks each line, starting - with the one before the last line listed and going backward, for a - match for REGEXP. It lists the line that is found. You can - abbreviate this command as `rev'. - - -File: gdb.info, Node: Source Path, Next: Machine Code, Prev: Search, Up: Source - -Specifying source directories -============================= - - Executable programs sometimes do not 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 are present in the list, until it finds a file with the desired -name. Note that the executable search path is *not* used for this -purpose. Neither is the current working directory, unless it happens -to be in the source path. - - If GDB cannot 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 is 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. - -`directory DIRNAME ...' - -`dir DIRNAME ...' - Add directory DIRNAME to the front of the source path. Several - directory names may be given to this command, separated by `:' or - whitespace. You may specify a directory that is already in the - source path; this moves it forward, so GDB searches it sooner. - - 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. `$cwd' is not the same as `.'--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. - -`directory' - Reset the source path to empty again. This requires confirmation. - -`show directories' - Print the source path: show which directories it contains. - - 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: - - 1. Use `directory' with no argument to reset the source path to empty. - - 2. Use `directory' with suitable arguments to reinstall the - directories you want in the source path. You can add all the - directories in one command. - - -File: gdb.info, Node: Machine Code, Prev: Source Path, Up: Source - -Source and machine code -======================= - - 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 now causes the arrow to point to the line -specified. Also, `info line' prints addresses in symbolic form as well -as hex. - -`info line LINESPEC' - Print the starting and ending addresses of the compiled code for - source line LINESPEC. You can specify source lines in any of the - ways understood by the `list' command (*note Printing source - lines: List.). - - 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 (*note Examining memory: -Memory.). Also, this address is saved as the value of the convenience -variable `$_' (*note Convenience variables: Convenience Vars.). - -`disassemble' - This specialized command dumps a range of memory as machine - instructions. The default memory range is the function - surrounding the program counter of the selected frame. A single - argument to this command is a program counter value; GDB dumps the - function surrounding this value. Two arguments specify a range of - addresses (first inclusive, second exclusive) to dump. - - 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 : ble 0x63f8 - 0x63e8 : sethi %hi(0x4c00), %o0 - 0x63ec : ld [%i1+4], %o0 - 0x63f0 : b 0x63fc - 0x63f4 : ld [%o0+4], %o0 - 0x63f8 : or %o0, 0x1a4, %o0 - 0x63fc : call 0x9288 - 0x6400 : nop - End of assembler dump. - -`set assembly-language INSTRUCTION-SET' - This command selects the instruction set to use when disassembling - the program via the `disassemble' or `x/i' commands. It is useful - for architectures that have more than one native instruction set. - - Currently it is only defined for the Intel x86 family. You can - set INSTRUCTION-SET to either `i386' or `i8086'. The default is - `i386'. - - -File: gdb.info, Node: Data, Next: Languages, Prev: Source, Up: Top - -Examining Data -************** - - The usual way to examine data in your program is with the `print' -command (abbreviated `p'), or its synonym `inspect'. It evaluates and -prints the value of an expression of the language your program is -written in (*note Using GDB with Different Languages: Languages.). - -`print EXP' -`print /F EXP' - EXP is an expression (in the source language). By default the - value of EXP is printed in a format appropriate to its data type; - you can choose a different format by specifying `/F', where F is a - letter specifying the format; *note Output formats: Output - Formats.. - -`print' -`print /F' - If you omit EXP, GDB displays the last value again (from the - "value history"; *note Value history: Value History.). This - allows you to conveniently inspect the same value in an - alternative format. - - A more low-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. *Note Examining memory: Memory. - - If you are interested in information about types, or about how the -fields of a struct or class are declared, use the `ptype EXP' command -rather than `print'. *Note Examining the Symbol Table: Symbols. - -* Menu: - -* 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 - - -File: gdb.info, Node: Expressions, Next: Variables, Up: Data - -Expressions -=========== - - `print' 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 are using is valid in an expression in GDB. -This includes conditional expressions, function calls, casts and string -constants. It unfortunately does not include symbols defined by -preprocessor `#define' commands. - - GDB now supports array constants in expressions input by the user. -The syntax is {ELEMENT, ELEMENT...}. For example, you can now 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. *Note Using GDB with Different -Languages: Languages, for information on how to use expressions in other -languages. - - 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 is so -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: - -`@' - `@' is a binary operator for treating parts of memory as arrays. - *Note Artificial arrays: Arrays, for more information. - -`::' - `::' allows you to specify a variable in terms of the file or - function where it is defined. *Note Program variables: Variables. - -`{TYPE} ADDR' - Refers to an object of type TYPE stored at address ADDR in memory. - ADDR may be any expression whose value is an integer or pointer - (but parentheses are required around binary operators, just as in - a cast). This construct is allowed regardless of what kind of - data is normally supposed to reside at ADDR. - - -File: gdb.info, Node: Variables, Next: Arrays, Prev: Expressions, Up: Data - -Program variables -================= - - 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 -(*note Selecting a frame: Selection.); they must be either: - - * global (or static) - -or - - * visible according to the scope rules of the programming language - from the point of execution in that frame - -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 only use or examine -the variable `b' while your program is executing inside the block where -`b' is declared. - - There is an exception: you can refer to a variable or function whose -scope is a single source file even if the current execution point is not -in this file. But it is 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 file names, you can use quotes to make sure -GDB parses the file name 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. - - *Warning:* Occasionally, a local variable may appear to have the - wrong value at certain points in a function--just after entry to a - new scope, and just before exit. - You may see this problem when you are 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 are 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. - - -File: gdb.info, Node: Arrays, Next: Output Formats, Prev: Variables, Up: Data - -Artificial arrays -================= - - It is 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 argument. The first element is actually the left -argument; the second element comes from bytes of memory immediately -following those that hold the first element, and so on. Here is an -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 -(*note Value history: Value History.), after printing one out. - - Another way to create an artificial array is to use a cast. This -re-interprets 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)': - (gdb) p/x (short[])0x12345678 - $2 = {0x1234, 0x5678} - - Sometimes the artificial array mechanism is not quite enough; in -moderately complex data structures, the elements of interest may not -actually be adjacent--for example, if you are interested in the values -of pointers in an array. One useful work-around in this situation is -to use a convenience variable (*note Convenience variables: Convenience -Vars.) as a counter in an expression that prints the first interesting -value, and then repeat that expression via . For instance, -suppose you have an array `dtab' of pointers to structures, and you are -interested in the values of a field `fv' in each structure. Here is an -example of what you might type: - - set $i = 0 - p dtab[$i++]->fv - - - ... - - -File: gdb.info, Node: Output Formats, Next: Memory, Prev: Arrays, Up: Data - -Output formats -============== - - By default, GDB prints a value according to its data type. Sometimes -this is not 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: - -`x' - Regard the bits of the value as an integer, and print the integer - in hexadecimal. - -`d' - Print as integer in signed decimal. - -`u' - Print as integer in unsigned decimal. - -`o' - Print as integer in octal. - -`t' - Print as integer in binary. The letter `t' stands for "two". (1) - -`a' - Print as an address, both absolute in hexadecimal and as an offset - from the nearest preceding symbol. You can use this format used - to discover where (in what function) an unknown address is located: - - (gdb) p/a 0x54320 - $3 = 0x54320 <_initialize_vx+396> - -`c' - Regard as an integer and print it as a character constant. - -`f' - Regard the bits of the value as a floating point number and print - using typical floating point syntax. - - For example, to print the program counter in hex (*note -Registers::.), type - - p/x $pc - -Note that no space is required before the slash; this is because command -names in GDB cannot 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. - - ---------- Footnotes ---------- - - (1) `b' cannot be used because these format letters are also used -with the `x' command, where `b' stands for "byte"; *note Examining -memory: Memory.. - - -File: gdb.info, Node: Memory, Next: Auto Display, Prev: Output Formats, Up: Data - -Examining memory -================ - - You can use the command `x' (for "examine") to examine memory in any -of several formats, independently of your program's data types. - -`x/NFU ADDR' -`x ADDR' -`x' - Use the `x' command to examine memory. - - 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. - -N, the repeat count - The repeat count is a decimal integer; the default is 1. It - specifies how much memory (counting by units U) to display. - -F, the display format - The display format is one of the formats used by `print', `s' - (null-terminated string), or `i' (machine instruction). The - default is `x' (hexadecimal) initially. The default changes each - time you use either `x' or `print'. - -U, the unit size - The unit size is any of - - `b' - Bytes. - - `h' - Halfwords (two bytes). - - `w' - Words (four bytes). This is the initial default. - - `g' - Giant words (eight bytes). - - 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 is normally not written.) - -ADDR, starting display address - ADDR is the address where you want GDB to begin displaying memory. - The expression need not have a pointer value (though it may); it - is always interpreted as an integer address of a byte of memory. - *Note Expressions: Expressions, for more information on - expressions. The default for ADDR is usually just after the last - address examined--but several other commands also set the default - address: `info breakpoints' (to the address of the last breakpoint - listed), `info line' (to the starting address of a line), and - `print' (if you use it to display a value from memory). - - 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'. `x/4xw $sp' prints the four words (`w') of -memory above the stack pointer (here, `$sp'; *note Registers::.) in -hexadecimal (`x'). - - Since the letters indicating unit sizes are all distinct from the -letters specifying output formats, you do not 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' does not 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; *note Source and machine code: 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 have inspected three machine -instructions with `x/3i ADDR', you can inspect the next seven with just -`x/7'. If you use 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 are not saved -in the value history because there is 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 is not the same as the last -address printed if several units were printed on the last line of -output. - - -File: gdb.info, Node: Auto Display, Next: Print Settings, Prev: Memory, Up: Data - -Automatic display -================= - - 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 only supported by `x'; otherwise it -uses `print'. - -`display EXP' - Add the expression EXP to the list of expressions to display each - time your program stops. *Note Expressions: Expressions. - - `display' does not repeat if you press again after using it. - -`display/FMT EXP' - For FMT specifying only a display format and not a size or count, - add the expression EXP to the auto-display list but arrange to - display it each time in the specified format FMT. *Note Output - formats: Output Formats. - -`display/FMT ADDR' - For FMT `i' or `s', or including a unit-size or a number of units, - add the expression ADDR as a memory address to be examined each - time your program stops. Examining means in effect doing `x/FMT - ADDR'. *Note Examining memory: Memory. - - 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; *note Registers::.). - -`undisplay DNUMS...' -`delete display DNUMS...' - Remove item numbers DNUMS from the list of expressions to display. - - `undisplay' does not repeat if you press after using it. - (Otherwise you would just get the error `No display number ...'.) - -`disable display DNUMS...' - Disable the display of item numbers DNUMS. A disabled display - item is not printed automatically, but is not forgotten. It may be - enabled again later. - -`enable display DNUMS...' - Enable display of item numbers DNUMS. It becomes effective once - again in auto display of its expression, until you specify - otherwise. - -`display' - Display the current values of the expressions on the list, just as - is done when your program stops. - -`info display' - Print the list of expressions previously set up to display - automatically, each one with its item number, but without showing - the values. This includes disabled expressions, which are marked - as such. It also includes expressions which would not be - displayed right now because they refer to automatic variables not - currently available. - - If a display expression refers to local variables, then it does not -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 is not 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 elsewhere--where there is 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. - diff --git a/gnu/dist/gdb/doc/gdb.info-4 b/gnu/dist/gdb/doc/gdb.info-4 deleted file mode 100644 index d78ee1255453..000000000000 --- a/gnu/dist/gdb/doc/gdb.info-4 +++ /dev/null @@ -1,1305 +0,0 @@ -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 Fifth Edition, April 1998, of `Debugging with GDB: the -GNU Source-Level Debugger' for GDB Version . - - Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, -1997, 1998 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: Print Settings, Next: Value History, Prev: Auto Display, Up: Data - -Print settings -============== - - GDB provides the following ways to control how arrays, structures, -and symbols are printed. - -These settings are useful for debugging programs in any language: - -`set print address' -`set print address on' - GDB prints memory addresses showing the location of stack traces, - structure values, pointer values, breakpoints, and so forth, even - when it also displays the contents of those addresses. The default - is `on'. For example, this is what a stack frame display looks - like with `set print address on': - - (gdb) f - #0 set_quotes (lq=0x34c78 "<<", rq=0x34c88 ">>") - at input.c:530 - 530 if (lquote != def_lquote) - -`set print address off' - Do not print addresses when displaying their contents. For - example, this is the same stack frame displayed with `set print - address off': - - (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. - -`show print address' - Show whether or not addresses are to be printed. - - When GDB prints a symbolic address, it normally prints the closest -earlier symbol plus an offset. If that symbol does not uniquely -identify the address (for example, it is 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: - -`set print symbol-filename on' - Tell GDB to print the source file name and line number of a symbol - in the symbolic form of an address. - -`set print symbol-filename off' - Do not print source file name and line number of a symbol. This - is the default. - -`show print symbol-filename' - Show whether or not GDB will print the source file name and line - number of a symbol in the symbolic form of an address. - - Another situation where it is helpful to show symbol filenames and -line numbers is when disassembling code; GDB shows you the line number -and source file that corresponds 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: - -`set print max-symbolic-offset MAX-OFFSET' - Tell GDB to only display the symbolic form of an address if the - offset between the closest earlier symbol and the address is less - than MAX-OFFSET. The default is 0, which tells GDB to always - print the symbolic form of an address if any symbol precedes it. - -`show print max-symbolic-offset' - Ask how large the maximum offset is that GDB prints in a symbolic - address. - - If you have a pointer and you are not 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 - - *Warning:* For pointers that point to a local variable, `p/a' does - not 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: - -`set print array' -`set print array on' - Pretty print arrays. This format is more convenient to read, but - uses more space. The default is off. - -`set print array off' - Return to compressed format for arrays. - -`show print array' - Show whether compressed or pretty format is selected for displaying - arrays. - -`set print elements NUMBER-OF-ELEMENTS' - Set a limit on how many elements of an array GDB will print. If - GDB is printing a large array, it stops printing after it has - printed the number of elements set by the `set print elements' - command. This limit also applies to the display of strings. - Setting NUMBER-OF-ELEMENTS to zero means that the printing is - unlimited. - -`show print elements' - Display the number of elements of a large array that GDB will - print. If the number is 0, then the printing is unlimited. - -`set print null-stop' - Cause GDB to stop printing the characters of an array when the - first NULL is encountered. This is useful when large arrays - actually contain only short strings. - -`set print pretty on' - Cause GDB to print structures in an indented format with one member - per line, like this: - - $1 = { - next = 0x0, - flags = { - sweet = 1, - sour = 1 - }, - meat = 0x54 "Pork" - } - -`set print pretty off' - Cause GDB to print structures in a compact format, like this: - - $1 = {next = 0x0, flags = {sweet = 1, sour = 1}, \ - meat = 0x54 "Pork"} - - This is the default format. - -`show print pretty' - Show which format GDB is using to print structures. - -`set print sevenbit-strings on' - Print using only seven-bit characters; if this option is set, GDB - displays any eight-bit characters (in strings or character values) - using the notation `\'NNN. This setting is best if you are - working in English (ASCII) and you use the high-order bit of - characters as a marker or "meta" bit. - -`set print sevenbit-strings off' - Print full eight-bit characters. This allows the use of more - international character sets, and is the default. - -`show print sevenbit-strings' - Show whether or not GDB is printing only seven-bit characters. - -`set print union on' - Tell GDB to print unions which are contained in structures. This - is the default setting. - -`set print union off' - Tell GDB not to print unions which are contained in structures. - -`show print union' - Ask GDB whether or not it will print unions which are contained in - structures. - - For example, given the declarations - - 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' would print - - $1 = {it = Tree, form = {tree = Acorn, bug = Cocoon}} - - and with `set print union off' in effect it would print - - $1 = {it = Tree, form = {...}} - -These settings are of interest when debugging C++ programs: - -`set print demangle' -`set print demangle on' - Print C++ names in their source form rather than in the encoded - ("mangled") form passed to the assembler and linker for type-safe - linkage. The default is `on'. - -`show print demangle' - Show whether C++ names are printed in mangled or demangled form. - -`set print asm-demangle' -`set print asm-demangle on' - Print C++ names in their source form rather than their mangled - form, even in assembler code printouts such as instruction - disassemblies. The default is off. - -`show print asm-demangle' - Show whether C++ names in assembly listings are printed in mangled - or demangled form. - -`set demangle-style STYLE' - Choose among several encoding schemes used by different compilers - to represent C++ names. The choices for STYLE are currently: - - `auto' - Allow GDB to choose a decoding style by inspecting your - program. - - `gnu' - Decode based on the GNU C++ compiler (`g++') encoding - algorithm. This is the default. - - `lucid' - Decode based on the Lucid C++ compiler (`lcc') encoding - algorithm. - - `arm' - Decode using the algorithm in the `C++ Annotated Reference - Manual'. *Warning:* this setting alone is not sufficient to - allow debugging `cfront'-generated executables. GDB would - require further enhancement to permit that. - - `foo' - Show the list of formats. - -`show demangle-style' - Display the encoding style currently in use for decoding C++ - symbols. - -`set print object' -`set print object on' - When displaying a pointer to an object, identify the *actual* - (derived) type of the object rather than the *declared* type, using - the virtual function table. - -`set print object off' - Display only the declared type of objects, without reference to the - virtual function table. This is the default setting. - -`show print object' - Show whether actual, or declared, object types are displayed. - -`set print static-members' -`set print static-members on' - Print static members when displaying a C++ object. The default is - on. - -`set print static-members off' - Do not print static members when displaying a C++ object. - -`show print static-members' - Show whether C++ static members are printed, or not. - -`set print vtbl' -`set print vtbl on' - Pretty print C++ virtual function tables. The default is off. - -`set print vtbl off' - Do not pretty print C++ virtual function tables. - -`show print vtbl' - Show whether C++ virtual function tables are pretty printed, or - not. - - -File: gdb.info, Node: Value History, Next: Convenience Vars, Prev: Print Settings, Up: Data - -Value history -============= - - Values printed by the `print' command are saved in the GDB "value -history". This allows you to refer to them in other expressions. -Values are kept until the symbol table is re-read 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" by which you can -refer to them. These are successive integers starting with one. -`print' 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 . - - Note that 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. - -`show values' - Print the last ten values in the value history, with their item - numbers. This is like `p $$9' repeated ten times, except that - `show values' does not change the history. - -`show values N' - Print ten history values centered on history item number N. - -`show values +' - Print ten history values just after the values last printed. If - no more values are available, `show values +' produces no display. - - Pressing to repeat `show values N' has exactly the same effect -as `show values +'. - - -File: gdb.info, Node: Convenience Vars, Next: Registers, Prev: Value History, Up: Data - -Convenience variables -===================== - - 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 are not part of your program, and setting a -convenience variable has no direct effect on further execution of your -program. That is why you can use them freely. - - Convenience variables are prefixed with `$'. Any name preceded by -`$' can be used for a convenience variable, unless it is one of the -predefined machine-specific register names (*note Registers::.). -(Value history references, in contrast, are *numbers* preceded by `$'. -*Note Value history: Value History.) - - You can save a value in a convenience variable with an assignment -expression, just as you would set a variable in your program. For -example: - - set $foo = *object_ptr - -would save 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 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. - -`show convenience' - Print a list of convenience variables used so far, and their - values. Abbreviated `show con'. - - 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 typing . - - Some convenience variables are created automatically by GDB and given -values likely to be useful. - -`$_' - The variable `$_' is automatically set by the `x' command to the - last address examined (*note Examining memory: Memory.). Other - commands which provide a default address for `x' to examine also - set `$_' to that address; these commands include `info line' and - `info breakpoint'. The type of `$_' is `void *' except when set - by the `x' command, in which case it is a pointer to the type of - `$__'. - -`$__' - The variable `$__' is automatically set by the `x' command to the - value found in the last address examined. Its type is chosen to - match the format in which the data was printed. - -`$_exitcode' - The variable `$_exitcode' is automatically set to the exit code - when the program being debugged terminates. - - -File: gdb.info, Node: Registers, Next: Floating Point Hardware, Prev: Convenience Vars, Up: Data - -Registers -========= - - 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. - -`info registers' - Print the names and values of all registers except floating-point - registers (in the selected stack frame). - -`info all-registers' - Print the names and values of all registers, including - floating-point registers. - -`info registers REGNAME ...' - Print the "relativized" value of each specified register REGNAME. - As discussed in detail below, register values are normally - relative to the selected stack frame. REGNAME may be any register - name valid on the machine you are using, with or without the - initial `$'. - - GDB has four "standard" register names that are available (in -expressions) on most machines--whenever they do not conflict with an -architecture's canonical mnemonics for registers. The register names -`$pc' and `$sp' are used for the program counter register and the stack -pointer. `$fp' is used for a register that contains a pointer to the -current stack frame, and `$ps' is used for a register that contains the -processor status. 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(1) with - - set $sp += 4 - - Whenever possible, these four standard register names are available -on your machine even though the machine has different canonical -mnemonics, so long as there is no conflict. The `info registers' -command shows the canonical names. For example, on the SPARC, `info -registers' displays the processor status register as `$psr' but you can -also refer to it as `$ps'. - - 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 which can hold nothing but floating point; these -registers are considered to have floating point values. There is 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 is not 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 -(*note Selecting a frame: Selection.). 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 are not saved, or if -GDB is unable to locate the saved registers, the selected stack frame -makes no difference. - -`set rstack_high_address ADDRESS' - On AMD 29000 family processors, registers are saved in a separate - "register stack". There is no way for GDB to determine the extent - of this stack. Normally, GDB just assumes that the stack is "large - enough". This may result in GDB referencing memory locations that - do not exist. If necessary, you can get around this problem by - specifying the ending address of the register stack with the `set - rstack_high_address' command. The argument should be an address, - which you probably want to precede with `0x' to specify in - hexadecimal. - -`show rstack_high_address' - Display the current limit of the register stack, on AMD 29000 - family processors. - - ---------- Footnotes ---------- - - (1) 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' is -not allowed when other stack frames are selected. To pop entire frames -off the stack, regardless of machine architecture, use `return'; *note -Returning from a function: Returning.. - - -File: gdb.info, Node: Floating Point Hardware, Prev: Registers, Up: Data - -Floating point hardware -======================= - - Depending on the configuration, GDB may be able to give you more -information about the status of the floating point hardware. - -`info float' - Display hardware-dependent information about the floating point - unit. The exact contents and layout vary depending on the - floating point chip. Currently, `info float' is supported on the - ARM and x86 machines. - - -File: gdb.info, Node: Languages, Next: Symbols, Prev: Data, Up: Top - -Using GDB with Different Languages -********************************** - - Although programming languages generally have common aspects, they -are rarely expressed in the same manner. For instance, in ANSI C, -dereferencing a pointer `p' is accomplished by `*p', but in Modula-2, -it is accomplished by `p^'. Values can also be represented (and -displayed) differently. Hex numbers in C appear as `0x1ae', while in -Modula-2 they appear as `1AEH'. - - Language-specific information is built into GDB for some languages, -allowing you to express operations like the above in your program's -native language, and allowing GDB to output values in a manner -consistent with the syntax of your program's native language. The -language you use to build expressions is called the "working language". - -* Menu: - -* Setting:: Switching between source languages -* Show:: Displaying the language - -* Checks:: Type and range checks - -* Support:: Supported languages - - -File: gdb.info, Node: Setting, Next: Show, Up: Languages - -Switching between source languages -================================== - - There are two ways to control the working language--either have GDB -set it automatically, or select it manually yourself. You can use the -`set language' command for either purpose. On startup, GDB defaults to -setting the language automatically. The working language is used to -determine how expressions you type are interpreted, how values are -printed, etc. - - In addition to the working language, every source file that GDB -knows about has its own working language. For some object file -formats, the compiler might indicate which language a particular source -file is in. However, most of the time GDB infers the language from the -name of the file. The language of a source file controls whether C++ -names are demangled--this way `backtrace' can show each frame -appropriately for its own language. There is no way to set the -language of a source file from within GDB. - - This is most commonly a problem when you use a program, such as -`cfront' or `f2c', that generates C but is written in another language. -In that case, make the program use `#line' directives in its C output; -that way GDB will know the correct language of the source code of the -original program, and will display that source code, not the generated -C code. - -* Menu: - -* Filenames:: Filename extensions and languages. -* Manually:: Setting the working language manually -* Automatically:: Having GDB infer the source language - - -File: gdb.info, Node: Filenames, Next: Manually, Up: Setting - -List of filename extensions and languages ------------------------------------------ - - If a source file name ends in one of the following extensions, then -GDB infers that its language is the one indicated. - -`.mod' - Modula-2 source file - -`.c' - C source file - -`.C' -`.cc' -`.cxx' -`.cpp' -`.cp' -`.c++' - C++ source file - -`.ch' -`.c186' -`.c286' - CHILL source file. - -`.s' -`.S' - Assembler source file. This actually behaves almost like C, but - GDB does not skip over function prologues when stepping. - - -File: gdb.info, Node: Manually, Next: Automatically, Prev: Filenames, Up: Setting - -Setting the working language ----------------------------- - - If you allow GDB to set the language automatically, expressions are -interpreted the same way in your debugging session and your program. - - If you wish, you may set the language manually. To do this, issue -the command `set language LANG', where LANG is the name of a language, -such as `c' or `modula-2'. For a list of the supported languages, type -`set language'. - - Setting the language manually prevents GDB from updating the working -language automatically. This can lead to confusion if you try to debug -a program when the working language is not the same as the source -language, when an expression is acceptable to both languages--but means -different things. For instance, if the current source file were -written in C, and GDB was parsing Modula-2, a command such as: - - print a = b + c - -might not have the effect you intended. In C, this means to add `b' -and `c' and place the result in `a'. The result printed would be the -value of `a'. In Modula-2, this means to compare `a' to the result of -`b+c', yielding a `BOOLEAN' value. - - -File: gdb.info, Node: Automatically, Prev: Manually, Up: Setting - -Having GDB infer the source language ------------------------------------- - - To have GDB set the working language automatically, use `set -language local' or `set language auto'. GDB then infers the working -language. That is, when your program stops in a frame (usually by -encountering a breakpoint), GDB sets the working language to the -language recorded for the function in that frame. If the language for -a frame is unknown (that is, if the function or block corresponding to -the frame was defined in a source file that does not have a recognized -extension), the current working language is not changed, and GDB issues -a warning. - - This may not seem necessary for most programs, which are written -entirely in one source language. However, program modules and libraries -written in one source language can be used by a main program written in -a different source language. Using `set language auto' in this case -frees you from having to set the working language manually. - - -File: gdb.info, Node: Show, Next: Checks, Prev: Setting, Up: Languages - -Displaying the language -======================= - - The following commands help you find out which language is the -working language, and also what language source files were written in. - -`show language' - Display the current working language. This is the language you - can use with commands such as `print' to build and compute - expressions that may involve variables in your program. - -`info frame' - Display the source language for this frame. This language becomes - the working language if you use an identifier from this frame. - *Note Information about a frame: Frame Info, to identify the other - information listed here. - -`info source' - Display the source language of this source file. *Note Examining - the Symbol Table: Symbols, to identify the other information - listed here. - - -File: gdb.info, Node: Checks, Next: Support, Prev: Show, Up: Languages - -Type and range checking -======================= - - *Warning:* In this release, the GDB commands for type and range - checking are included, but they do not yet have any effect. This - section documents the intended facilities. - - Some languages are designed to guard you against making seemingly -common errors through a series of compile- and run-time checks. These -include checking the type of arguments to functions and operators, and -making sure mathematical overflows are caught at run time. Checks such -as these help to ensure a program's correctness once it has been -compiled by eliminating type mismatches, and providing active checks -for range errors when your program is running. - - GDB can check for conditions like the above if you wish. Although -GDB does not check the statements in your program, it can check -expressions entered directly into GDB for evaluation via the `print' -command, for example. As with the working language, GDB can also -decide whether or not to check automatically based on your program's -source language. *Note Supported languages: Support, for the default -settings of supported languages. - -* Menu: - -* Type Checking:: An overview of type checking -* Range Checking:: An overview of range checking - - -File: gdb.info, Node: Type Checking, Next: Range Checking, Up: Checks - -An overview of type checking ----------------------------- - - Some languages, such as Modula-2, are strongly typed, meaning that -the arguments to operators and functions have to be of the correct type, -otherwise an error occurs. These checks prevent type mismatch errors -from ever causing any run-time problems. For example, - - 1 + 2 => 3 -but - error--> 1 + 2.3 - - The second example fails because the `CARDINAL' 1 is not -type-compatible with the `REAL' 2.3. - - For the expressions you use in GDB commands, you can tell the GDB -type checker to skip checking; to treat any mismatches as errors and -abandon the expression; or to only issue warnings when type mismatches -occur, but evaluate the expression anyway. When you choose the last of -these, GDB evaluates expressions like the second example above, but -also issues a warning. - - Even if you turn type checking off, there may be other reasons -related to type that prevent GDB from evaluating an expression. For -instance, GDB does not know how to add an `int' and a `struct foo'. -These particular type errors have nothing to do with the language in -use, and usually arise from expressions, such as the one described -above, which make little sense to evaluate anyway. - - Each language defines to what degree it is strict about type. For -instance, both Modula-2 and C require the arguments to arithmetical -operators to be numbers. In C, enumerated types and pointers can be -represented as numbers, so that they are valid arguments to mathematical -operators. *Note Supported languages: Support, for further details on -specific languages. - - GDB provides some additional commands for controlling the type -checker: - -`set check type auto' - Set type checking on or off based on the current working language. - *Note Supported languages: Support, for the default settings for - each language. - -`set check type on' -`set check type off' - Set type checking on or off, overriding the default setting for the - current working language. Issue a warning if the setting does not - match the language default. If any type mismatches occur in - evaluating an expression while typechecking is on, GDB prints a - message and aborts evaluation of the expression. - -`set check type warn' - Cause the type checker to issue warnings, but to always attempt to - evaluate the expression. Evaluating the expression may still be - impossible for other reasons. For example, GDB cannot add numbers - and structures. - -`show type' - Show the current setting of the type checker, and whether or not - GDB is setting it automatically. - - -File: gdb.info, Node: Range Checking, Prev: Type Checking, Up: Checks - -An overview of range checking ------------------------------ - - In some languages (such as Modula-2), it is an error to exceed the -bounds of a type; this is enforced with run-time checks. Such range -checking is meant to ensure program correctness by making sure -computations do not overflow, or indices on an array element access do -not exceed the bounds of the array. - - For expressions you use in GDB commands, you can tell GDB to treat -range errors in one of three ways: ignore them, always treat them as -errors and abandon the expression, or issue warnings but evaluate the -expression anyway. - - A range error can result from numerical overflow, from exceeding an -array index bound, or when you type a constant that is not a member of -any type. Some languages, however, do not treat overflows as an error. -In many implementations of C, mathematical overflow causes the result -to "wrap around" to lower values--for example, if M is the largest -integer value, and S is the smallest, then - - M + 1 => S - - This, too, is specific to individual languages, and in some cases -specific to individual compilers or machines. *Note Supported -languages: Support, for further details on specific languages. - - GDB provides some additional commands for controlling the range -checker: - -`set check range auto' - Set range checking on or off based on the current working language. - *Note Supported languages: Support, for the default settings for - each language. - -`set check range on' -`set check range off' - Set range checking on or off, overriding the default setting for - the current working language. A warning is issued if the setting - does not match the language default. If a range error occurs, - then a message is printed and evaluation of the expression is - aborted. - -`set check range warn' - Output messages when the GDB range checker detects a range error, - but attempt to evaluate the expression anyway. Evaluating the - expression may still be impossible for other reasons, such as - accessing memory that the process does not own (a typical example - from many Unix systems). - -`show range' - Show the current setting of the range checker, and whether or not - it is being set automatically by GDB. - - -File: gdb.info, Node: Support, Prev: Checks, Up: Languages - -Supported languages -=================== - - GDB 4 supports C, C++, and Modula-2. Some GDB features may be used -in expressions regardless of the language you use: the GDB `@' and `::' -operators, and the `{type}addr' construct (*note Expressions: -Expressions.) can be used with the constructs of any supported language. - - The following sections detail to what degree each source language is -supported by GDB. These sections are not meant to be language -tutorials or references, but serve only as a reference guide to what the -GDB expression parser accepts, and what input and output formats should -look like for different languages. There are many good books written -on each of these languages; please look to these for a language -reference or tutorial. - -* Menu: - -* C:: C and C++ -* Modula-2:: Modula-2 - - -File: gdb.info, Node: C, Next: Modula-2, Up: Support - -C and C++ ---------- - - Since C and C++ are so closely related, many features of GDB apply -to both languages. Whenever this is the case, we discuss those -languages together. - - The C++ debugging facilities are jointly implemented by the GNU C++ -compiler and GDB. Therefore, to debug your C++ code effectively, you -must compile your C++ programs with the GNU C++ compiler, `g++'. - - For best results when debugging C++ programs, use the stabs debugging -format. You can select that format explicitly with the `g++' -command-line options `-gstabs' or `-gstabs+'. See *Note Options for -Debugging Your Program or GNU CC: (gcc.info)Debugging Options, for more -information. - -* Menu: - -* 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:: Special features for C++ - - -File: gdb.info, Node: C Operators, Next: C Constants, Up: C - -C and C++ operators -................... - - Operators must be defined on values of specific types. For instance, -`+' is defined on numbers, but not on structures. Operators are often -defined on groups of types. - - For the purposes of C and C++, the following definitions hold: - - * *Integral types* include `int' with any of its storage-class - specifiers; `char'; and `enum'. - - * *Floating-point types* include `float' and `double'. - - * *Pointer types* include all types defined as `(TYPE *)'. - - * *Scalar types* include all of the above. - -The following operators are supported. They are listed here in order -of increasing precedence: - -`,' - The comma or sequencing operator. Expressions in a - comma-separated list are evaluated from left to right, with the - result of the entire expression being the last expression - evaluated. - -`=' - Assignment. The value of an assignment expression is the value - assigned. Defined on scalar types. - -`OP=' - Used in an expression of the form `A OP= B', and translated to - `A = A OP B'. `OP=' and `=' have the same precendence. OP is any - one of the operators `|', `^', `&', `<<', `>>', `+', `-', `*', - `/', `%'. - -`?:' - The ternary operator. `A ? B : C' can be thought of as: if A - then B else C. A should be of an integral type. - -`||' - Logical OR. Defined on integral types. - -`&&' - Logical AND. Defined on integral types. - -`|' - Bitwise OR. Defined on integral types. - -`^' - Bitwise exclusive-OR. Defined on integral types. - -`&' - Bitwise AND. Defined on integral types. - -`==, !=' - Equality and inequality. Defined on scalar types. The value of - these expressions is 0 for false and non-zero for true. - -`<, >, <=, >=' - Less than, greater than, less than or equal, greater than or equal. - Defined on scalar types. The value of these expressions is 0 for - false and non-zero for true. - -`<<, >>' - left shift, and right shift. Defined on integral types. - -`@' - The GDB "artificial array" operator (*note Expressions: - Expressions.). - -`+, -' - Addition and subtraction. Defined on integral types, - floating-point types and pointer types. - -`*, /, %' - Multiplication, division, and modulus. Multiplication and - division are defined on integral and floating-point types. - Modulus is defined on integral types. - -`++, --' - Increment and decrement. When appearing before a variable, the - operation is performed before the variable is used in an - expression; when appearing after it, the variable's value is used - before the operation takes place. - -`*' - Pointer dereferencing. Defined on pointer types. Same precedence - as `++'. - -`&' - Address operator. Defined on variables. Same precedence as `++'. - - For debugging C++, GDB implements a use of `&' beyond what is - allowed in the C++ language itself: you can use `&(&REF)' (or, if - you prefer, simply `&&REF') to examine the address where a C++ - reference variable (declared with `&REF') is stored. - -`-' - Negative. Defined on integral and floating-point types. Same - precedence as `++'. - -`!' - Logical negation. Defined on integral types. Same precedence as - `++'. - -`~' - Bitwise complement operator. Defined on integral types. Same - precedence as `++'. - -`., ->' - Structure member, and pointer-to-structure member. For - convenience, GDB regards the two as equivalent, choosing whether - to dereference a pointer based on the stored type information. - Defined on `struct' and `union' data. - -`[]' - Array indexing. `A[I]' is defined as `*(A+I)'. Same precedence - as `->'. - -`()' - Function parameter list. Same precedence as `->'. - -`::' - C++ scope resolution operator. Defined on `struct', `union', and - `class' types. - -`::' - Doubled colons also represent the GDB scope operator (*note - Expressions: Expressions.). Same precedence as `::', above. - - -File: gdb.info, Node: C Constants, Next: Cplus expressions, Prev: C Operators, Up: C - -C and C++ constants -................... - - GDB allows you to express the constants of C and C++ in the -following ways: - - * Integer constants are a sequence of digits. Octal constants are - specified by a leading `0' (i.e. zero), and hexadecimal constants - by a leading `0x' or `0X'. Constants may also end with a letter - `l', specifying that the constant should be treated as a `long' - value. - - * Floating point constants are a sequence of digits, followed by a - decimal point, followed by a sequence of digits, and optionally - followed by an exponent. An exponent is of the form: - `e[[+]|-]NNN', where NNN is another sequence of digits. The `+' - is optional for positive exponents. - - * Enumerated constants consist of enumerated identifiers, or their - integral equivalents. - - * Character constants are a single character surrounded by single - quotes (`''), or a number--the ordinal value of the corresponding - character (usually its ASCII value). Within quotes, the single - character may be represented by a letter or by "escape sequences", - which are of the form `\NNN', where NNN is the octal representation - of the character's ordinal value; or of the form `\X', where `X' - is a predefined special character--for example, `\n' for newline. - - * String constants are a sequence of character constants surrounded - by double quotes (`"'). - - * Pointer constants are an integral value. You can also write - pointers to constants using the C operator `&'. - - * Array constants are comma-separated lists surrounded by braces `{' - and `}'; for example, `{1,2,3}' is a three-element array of - integers, `{{1,2}, {3,4}, {5,6}}' is a three-by-two array, and - `{&"hi", &"there", &"fred"}' is a three-element array of pointers. - - -File: gdb.info, Node: Cplus expressions, Next: C Defaults, Prev: C Constants, Up: C - -C++ expressions -............... - - GDB expression handling has a number of extensions to interpret a -significant subset of C++ expressions. - - *Warning:* GDB can only debug C++ code if you compile with the GNU - C++ compiler. Moreover, C++ debugging depends on the use of - additional debugging information in the symbol table, and thus - requires special support. GDB has this support *only* with the - stabs debug format. In particular, if your compiler generates - a.out, MIPS ECOFF, RS/6000 XCOFF, or ELF with stabs extensions to - the symbol table, these facilities are all available. (With GNU - CC, you can use the `-gstabs' option to request stabs debugging - extensions explicitly.) Where the object code format is standard - COFF or DWARF in ELF, on the other hand, most of the C++ support - in GDB does *not* work. - - 1. Member function calls are allowed; you can use expressions like - - count = aml->GetOriginal(x, y) - - 2. While a member function is active (in the selected stack frame), - your expressions have the same namespace available as the member - function; that is, GDB allows implicit references to the class - instance pointer `this' following the same rules as C++. - - 3. You can call overloaded functions; GDB resolves the function call - to the right definition, with one restriction--you must use - arguments of the type required by the function that you want to - call. GDB does not perform conversions requiring constructors or - user-defined type operators. - - 4. GDB understands variables declared as C++ references; you can use - them in expressions just as you do in C++ source--they are - automatically dereferenced. - - In the parameter list shown when GDB displays a frame, the values - of reference variables are not displayed (unlike other variables); - this avoids clutter, since references are often used for large - structures. The *address* of a reference variable is always - shown, unless you have specified `set print address off'. - - 5. GDB supports the C++ name resolution operator `::'--your - expressions can use it just as expressions in your program do. - Since one scope may be defined in another, you can use `::' - repeatedly if necessary, for example in an expression like - `SCOPE1::SCOPE2::NAME'. GDB also allows resolving name scope by - reference to source files, in both C and C++ debugging (*note - Program variables: Variables.). - - -File: gdb.info, Node: C Defaults, Next: C Checks, Prev: Cplus expressions, Up: C - -C and C++ defaults -.................. - - If you allow GDB to set type and range checking automatically, they -both default to `off' whenever the working language changes to C or -C++. This happens regardless of whether you or GDB selects the working -language. - - If you allow GDB to set the language automatically, it recognizes -source files whose names end with `.c', `.C', or `.cc', and when GDB -enters code compiled from one of these files, it sets the working -language to C or C++. *Note Having GDB infer the source language: -Automatically, for further details. - - -File: gdb.info, Node: C Checks, Next: Debugging C, Prev: C Defaults, Up: C - -C and C++ type and range checks -............................... - - By default, when GDB parses C or C++ expressions, type checking is -not used. However, if you turn type checking on, GDB considers two -variables type equivalent if: - - * The two variables are structured and have the same structure, - union, or enumerated tag. - - * The two variables have the same type name, or types that have been - declared equivalent through `typedef'. - - Range checking, if turned on, is done on mathematical operations. -Array indices are not checked, since they are often used to index a -pointer that is not itself an array. - - -File: gdb.info, Node: Debugging C, Next: Debugging C plus plus, Prev: C Checks, Up: C - -GDB and C -......... - - The `set print union' and `show print union' commands apply to the -`union' type. When set to `on', any `union' that is inside a `struct' -or `class' is also printed. Otherwise, it appears as `{...}'. - - The `@' operator aids in the debugging of dynamic arrays, formed -with pointers and a memory allocation function. *Note Expressions: -Expressions. - - -File: gdb.info, Node: Debugging C plus plus, Prev: Debugging C, Up: C - -GDB features for C++ -.................... - - Some GDB commands are particularly useful with C++, and some are -designed specifically for use with C++. Here is a summary: - -`breakpoint menus' - When you want a breakpoint in a function whose name is overloaded, - GDB breakpoint menus help you specify which function definition - you want. *Note Breakpoint menus: Breakpoint Menus. - -`rbreak REGEX' - Setting breakpoints using regular expressions is helpful for - setting breakpoints on overloaded functions that are not members - of any special classes. *Note Setting breakpoints: Set Breaks. - -`catch EXCEPTIONS' -`info catch' - Debug C++ exception handling using these commands. *Note - Breakpoints and exceptions: Exception Handling. - -`ptype TYPENAME' - Print inheritance relationships as well as other information for - type TYPENAME. *Note Examining the Symbol Table: Symbols. - -`set print demangle' -`show print demangle' -`set print asm-demangle' -`show print asm-demangle' - Control whether C++ symbols display in their source form, both when - displaying code as C++ source and when displaying disassemblies. - *Note Print settings: Print Settings. - -`set print object' -`show print object' - Choose whether to print derived (actual) or declared types of - objects. *Note Print settings: Print Settings. - -`set print vtbl' -`show print vtbl' - Control the format for printing virtual function tables. *Note - Print settings: Print Settings. - -`Overloaded symbol names' - You can specify a particular definition of an overloaded symbol, - using the same notation that is used to declare such symbols in - C++: type `SYMBOL(TYPES)' rather than just SYMBOL. You can also - use the GDB command-line word completion facilities to list the - available choices, or to finish the type list for you. *Note - Command completion: Completion, for details on how to do this. - - -File: gdb.info, Node: Modula-2, Prev: C, Up: Support - -Modula-2 --------- - - The extensions made to GDB to support Modula-2 only support output -from the GNU Modula-2 compiler (which is currently being developed). -Other Modula-2 compilers are not currently supported, and attempting to -debug executables produced by them is most likely to give an error as -GDB reads in the executable's symbol table. - -* Menu: - -* 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 - diff --git a/gnu/dist/gdb/doc/gdb.info-5 b/gnu/dist/gdb/doc/gdb.info-5 deleted file mode 100644 index 450c32ad7f2d..000000000000 --- a/gnu/dist/gdb/doc/gdb.info-5 +++ /dev/null @@ -1,1173 +0,0 @@ -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 Fifth Edition, April 1998, of `Debugging with GDB: the -GNU Source-Level Debugger' for GDB Version . - - Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, -1997, 1998 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: M2 Operators, Next: Built-In Func/Proc, Up: Modula-2 - -Operators -......... - - Operators must be defined on values of specific types. For instance, -`+' is defined on numbers, but not on structures. Operators are often -defined on groups of types. For the purposes of Modula-2, the -following definitions hold: - - * *Integral types* consist of `INTEGER', `CARDINAL', and their - subranges. - - * *Character types* consist of `CHAR' and its subranges. - - * *Floating-point types* consist of `REAL'. - - * *Pointer types* consist of anything declared as `POINTER TO TYPE'. - - * *Scalar types* consist of all of the above. - - * *Set types* consist of `SET' and `BITSET' types. - - * *Boolean types* consist of `BOOLEAN'. - -The following operators are supported, and appear in order of -increasing precedence: - -`,' - Function argument or array index separator. - -`:=' - Assignment. The value of VAR `:=' VALUE is VALUE. - -`<, >' - Less than, greater than on integral, floating-point, or enumerated - types. - -`<=, >=' - Less than, greater than, less than or equal to, greater than or - equal to on integral, floating-point and enumerated types, or set - inclusion on set types. Same precedence as `<'. - -`=, <>, #' - Equality and two ways of expressing inequality, valid on scalar - types. Same precedence as `<'. In GDB scripts, only `<>' is - available for inequality, since `#' conflicts with the script - comment character. - -`IN' - Set membership. Defined on set types and the types of their - members. Same precedence as `<'. - -`OR' - Boolean disjunction. Defined on boolean types. - -`AND, &' - Boolean conjuction. Defined on boolean types. - -`@' - The GDB "artificial array" operator (*note Expressions: - Expressions.). - -`+, -' - Addition and subtraction on integral and floating-point types, or - union and difference on set types. - -`*' - Multiplication on integral and floating-point types, or set - intersection on set types. - -`/' - Division on floating-point types, or symmetric set difference on - set types. Same precedence as `*'. - -`DIV, MOD' - Integer division and remainder. Defined on integral types. Same - precedence as `*'. - -`-' - Negative. Defined on `INTEGER' and `REAL' data. - -`^' - Pointer dereferencing. Defined on pointer types. - -`NOT' - Boolean negation. Defined on boolean types. Same precedence as - `^'. - -`.' - `RECORD' field selector. Defined on `RECORD' data. Same - precedence as `^'. - -`[]' - Array indexing. Defined on `ARRAY' data. Same precedence as `^'. - -`()' - Procedure argument list. Defined on `PROCEDURE' objects. Same - precedence as `^'. - -`::, .' - GDB and Modula-2 scope operators. - - *Warning:* Sets and their operations are not yet supported, so GDB - treats the use of the operator `IN', or the use of operators `+', - `-', `*', `/', `=', , `<>', `#', `<=', and `>=' on sets as an - error. - - -File: gdb.info, Node: Built-In Func/Proc, Next: M2 Constants, Prev: M2 Operators, Up: Modula-2 - -Built-in functions and procedures -................................. - - Modula-2 also makes available several built-in procedures and -functions. In describing these, the following metavariables are used: - -A - represents an `ARRAY' variable. - -C - represents a `CHAR' constant or variable. - -I - represents a variable or constant of integral type. - -M - represents an identifier that belongs to a set. Generally used in - the same function with the metavariable S. The type of S should - be `SET OF MTYPE' (where MTYPE is the type of M). - -N - represents a variable or constant of integral or floating-point - type. - -R - represents a variable or constant of floating-point type. - -T - represents a type. - -V - represents a variable. - -X - represents a variable or constant of one of many types. See the - explanation of the function for details. - - All Modula-2 built-in procedures also return a result, described -below. - -`ABS(N)' - Returns the absolute value of N. - -`CAP(C)' - If C is a lower case letter, it returns its upper case equivalent, - otherwise it returns its argument - -`CHR(I)' - Returns the character whose ordinal value is I. - -`DEC(V)' - Decrements the value in the variable V. Returns the new value. - -`DEC(V,I)' - Decrements the value in the variable V by I. Returns the new - value. - -`EXCL(M,S)' - Removes the element M from the set S. Returns the new set. - -`FLOAT(I)' - Returns the floating point equivalent of the integer I. - -`HIGH(A)' - Returns the index of the last member of A. - -`INC(V)' - Increments the value in the variable V. Returns the new value. - -`INC(V,I)' - Increments the value in the variable V by I. Returns the new - value. - -`INCL(M,S)' - Adds the element M to the set S if it is not already there. - Returns the new set. - -`MAX(T)' - Returns the maximum value of the type T. - -`MIN(T)' - Returns the minimum value of the type T. - -`ODD(I)' - Returns boolean TRUE if I is an odd number. - -`ORD(X)' - Returns the ordinal value of its argument. For example, the - ordinal value of a character is its ASCII value (on machines - supporting the ASCII character set). X must be of an ordered - type, which include integral, character and enumerated types. - -`SIZE(X)' - Returns the size of its argument. X can be a variable or a type. - -`TRUNC(R)' - Returns the integral part of R. - -`VAL(T,I)' - Returns the member of the type T whose ordinal value is I. - - *Warning:* Sets and their operations are not yet supported, so - GDB treats the use of procedures `INCL' and `EXCL' as an error. - - -File: gdb.info, Node: M2 Constants, Next: M2 Defaults, Prev: Built-In Func/Proc, Up: Modula-2 - -Constants -......... - - GDB allows you to express the constants of Modula-2 in the following -ways: - - * Integer constants are simply a sequence of digits. When used in an - expression, a constant is interpreted to be type-compatible with - the rest of the expression. Hexadecimal integers are specified by - a trailing `H', and octal integers by a trailing `B'. - - * Floating point constants appear as a sequence of digits, followed - by a decimal point and another sequence of digits. An optional - exponent can then be specified, in the form `E[+|-]NNN', where - `[+|-]NNN' is the desired exponent. All of the digits of the - floating point constant must be valid decimal (base 10) digits. - - * Character constants consist of a single character enclosed by a - pair of like quotes, either single (`'') or double (`"'). They may - also be expressed by their ordinal value (their ASCII value, - usually) followed by a `C'. - - * String constants consist of a sequence of characters enclosed by a - pair of like quotes, either single (`'') or double (`"'). Escape - sequences in the style of C are also allowed. *Note C and C++ - constants: C Constants, for a brief explanation of escape - sequences. - - * Enumerated constants consist of an enumerated identifier. - - * Boolean constants consist of the identifiers `TRUE' and `FALSE'. - - * Pointer constants consist of integral values only. - - * Set constants are not yet supported. - - -File: gdb.info, Node: M2 Defaults, Next: Deviations, Prev: M2 Constants, Up: Modula-2 - -Modula-2 defaults -................. - - If type and range checking are set automatically by GDB, they both -default to `on' whenever the working language changes to Modula-2. -This happens regardless of whether you, or GDB, selected the working -language. - - If you allow GDB to set the language automatically, then entering -code compiled from a file whose name ends with `.mod' sets the working -language to Modula-2. *Note Having GDB set the language automatically: -Automatically, for further details. - - -File: gdb.info, Node: Deviations, Next: M2 Checks, Prev: M2 Defaults, Up: Modula-2 - -Deviations from standard Modula-2 -................................. - - A few changes have been made to make Modula-2 programs easier to -debug. This is done primarily via loosening its type strictness: - - * Unlike in standard Modula-2, pointer constants can be formed by - integers. This allows you to modify pointer variables during - debugging. (In standard Modula-2, the actual address contained in - a pointer variable is hidden from you; it can only be modified - through direct assignment to another pointer variable or - expression that returned a pointer.) - - * C escape sequences can be used in strings and characters to - represent non-printable characters. GDB prints out strings with - these escape sequences embedded. Single non-printable characters - are printed using the `CHR(NNN)' format. - - * The assignment operator (`:=') returns the value of its right-hand - argument. - - * All built-in procedures both modify *and* return their argument. - - -File: gdb.info, Node: M2 Checks, Next: M2 Scope, Prev: Deviations, Up: Modula-2 - -Modula-2 type and range checks -.............................. - - *Warning:* in this release, GDB does not yet perform type or range - checking. - - GDB considers two Modula-2 variables type equivalent if: - - * They are of types that have been declared equivalent via a `TYPE - T1 = T2' statement - - * They have been declared on the same line. (Note: This is true of - the GNU Modula-2 compiler, but it may not be true of other - compilers.) - - As long as type checking is enabled, any attempt to combine variables -whose types are not equivalent is an error. - - Range checking is done on all mathematical operations, assignment, -array index bounds, and all built-in functions and procedures. - - -File: gdb.info, Node: M2 Scope, Next: GDB/M2, Prev: M2 Checks, Up: Modula-2 - -The scope operators `::' and `.' -................................ - - There are a few subtle differences between the Modula-2 scope -operator (`.') and the GDB scope operator (`::'). The two have similar -syntax: - - - MODULE . ID - SCOPE :: ID - -where SCOPE is the name of a module or a procedure, MODULE the name of -a module, and ID is any declared identifier within your program, except -another module. - - Using the `::' operator makes GDB search the scope specified by -SCOPE for the identifier ID. If it is not found in the specified -scope, then GDB searches all scopes enclosing the one specified by -SCOPE. - - Using the `.' operator makes GDB search the current scope for the -identifier specified by ID that was imported from the definition module -specified by MODULE. With this operator, it is an error if the -identifier ID was not imported from definition module MODULE, or if ID -is not an identifier in MODULE. - - -File: gdb.info, Node: GDB/M2, Prev: M2 Scope, Up: Modula-2 - -GDB and Modula-2 -................ - - Some GDB commands have little use when debugging Modula-2 programs. -Five subcommands of `set print' and `show print' apply specifically to -C and C++: `vtbl', `demangle', `asm-demangle', `object', and `union'. -The first four apply to C++, and the last to the C `union' type, which -has no direct analogue in Modula-2. - - The `@' operator (*note Expressions: Expressions.), while available -while using any language, is not useful with Modula-2. Its intent is -to aid the debugging of "dynamic arrays", which cannot be created in -Modula-2 as they can in C or C++. However, because an address can be -specified by an integral constant, the construct `{TYPE}ADREXP' is -still useful. (*note Expressions: Expressions.) - - In GDB scripts, the Modula-2 inequality operator `#' is interpreted -as the beginning of a comment. Use `<>' instead. - - -File: gdb.info, Node: Symbols, Next: Altering, Prev: Languages, Up: Top - -Examining the Symbol Table -************************** - - 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 -does not change as your program executes. GDB finds it in your -program's symbol table, in the file indicated when you started GDB -(*note Choosing files: File Options.), or by one of the file-management -commands (*note Commands to specify files: Files.). - - 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 -(*note Program variables: Variables.). File names are recorded in -object files as debugging symbols, but GDB would ordinarily parse a -typical file name, like `foo.c', as the three words `foo' `.' `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'. - -`info address SYMBOL' - Describe where the data for SYMBOL is stored. For a register - variable, this says which register it is kept in. For a - non-register local variable, this prints the stack-frame offset at - which the variable is always stored. - - Note the contrast with `print &SYMBOL', which does not work at all - for a register variable, and for a stack local variable prints the - exact address of the current instantiation of the variable. - -`whatis EXP' - Print the data type of expression EXP. EXP is not actually - evaluated, and any side-effecting operations (such as assignments - or function calls) inside it do not take place. *Note - Expressions: Expressions. - -`whatis' - Print the data type of `$', the last value in the value history. - -`ptype TYPENAME' - Print a description of data type TYPENAME. TYPENAME may be the - name of a type, or for C code it may have the form `class - CLASS-NAME', `struct STRUCT-TAG', `union UNION-TAG' or `enum - ENUM-TAG'. - -`ptype EXP' -`ptype' - Print a description of the type of expression EXP. `ptype' - differs from `whatis' by printing a detailed description, instead - of just the name of the type. - - For example, for this variable declaration: - - 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. - -`info types REGEXP' -`info types' - Print a brief description of all types whose name matches REGEXP - (or all types in your program, if you supply no argument). Each - complete typename is matched as though it were a complete line; - thus, `i type value' gives information on all types in your - program whose name includes the string `value', but `i type - ^value$' gives information only on types whose complete name is - `value'. - - This command differs from `ptype' in two ways: first, like - `whatis', it does not print a detailed description; second, it - lists all source files where a type is defined. - -`info source' - Show the name of the current source file--that is, the source file - for the function containing the current point of execution--and - the language it was written in. - -`info sources' - Print the names of all source files in your program for which - there is debugging information, organized into two lists: files - whose symbols have already been read, and files whose symbols will - be read when needed. - -`info functions' - Print the names and data types of all defined functions. - -`info functions REGEXP' - Print the names and data types of all defined functions whose - names contain a match for regular expression REGEXP. Thus, `info - fun step' finds all functions whose names include `step'; `info - fun ^step' finds those whose names start with `step'. - -`info variables' - Print the names and data types of all variables that are declared - outside of functions (i.e., excluding local variables). - -`info variables REGEXP' - Print the names and data types of all variables (except for local - variables) whose names contain a match for regular expression - REGEXP. - - Some systems allow individual object files that make up your - program to be replaced without stopping and restarting your - program. For example, in VxWorks you can simply recompile a - defective object file and keep on running. If you are running on - one of these systems, you can allow GDB to reload the symbols for - automatically relinked modules: - - `set symbol-reloading on' - Replace symbol definitions for the corresponding source file - when an object file with a particular name is seen again. - - `set symbol-reloading off' - Do not replace symbol definitions when re-encountering object - files of the same name. This is the default state; if you - are not running on a system that permits automatically - relinking modules, you should leave `symbol-reloading' off, - since otherwise GDB may discard symbols when linking large - programs, that may contain several modules (from different - directories or libraries) with the same name. - - `show symbol-reloading' - Show the current `on' or `off' setting. - -`maint print symbols FILENAME' -`maint print psymbols FILENAME' -`maint print msymbols FILENAME' - Write a dump of debugging symbol data into the file FILENAME. - These commands are used to debug the GDB symbol-reading code. Only - symbols with debugging data are included. If you use `maint print - symbols', GDB includes all the symbols for which it has already - collected full details: that is, FILENAME reflects symbols for - only those files whose symbols GDB has read. You can use the - command `info sources' to find out which files these are. If you - use `maint print psymbols' instead, the dump shows information - about symbols that GDB only knows partially--that is, symbols - defined in files that GDB has skimmed, but not yet read - completely. Finally, `maint print msymbols' dumps just the - minimal symbol information required for each object file from - which GDB has read some symbols. *Note Commands to specify files: - Files, for a discussion of how GDB reads symbols (in the - description of `symbol-file'). - - -File: gdb.info, Node: Altering, Next: GDB Files, Prev: Symbols, Up: Top - -Altering Execution -****************** - - Once you think you have 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 experiment, using the GDB features for altering execution of -the program. - - For example, you can store new values into variables or memory -locations, give your program a signal, restart it at a different -address, or even return prematurely from a function. - -* Menu: - -* 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 - - -File: gdb.info, Node: Assignment, Next: Jumping, Up: Altering - -Assignment to variables -======================= - - To alter the value of a variable, evaluate an assignment expression. -*Note Expressions: Expressions. For example, - - print x=4 - -stores the value 4 into the variable `x', and then prints the value of -the assignment expression (which is 4). *Note Using GDB with Different -Languages: Languages, for more information on operators in supported -languages. - - If you are not interested in seeing the value of the assignment, use -the `set' command instead of the `print' command. `set' is really the -same as `print' except that the expression's value is not printed and -is not put in the value history (*note Value history: 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 -(*note Expressions: 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 into that memory location. - - -File: gdb.info, Node: Jumping, Next: Signaling, Prev: Assignment, Up: Altering - -Continuing at a different address -================================= - - 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: - -`jump LINESPEC' - Resume execution at line LINESPEC. Execution stops again - immediately if there is a breakpoint there. *Note Printing source - lines: List, for a description of the different forms of LINESPEC. - - The `jump' command does not 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 is not in the - function currently executing. However, even bizarre results are - predictable if you are well acquainted with the machine-language - code of your program. - -`jump *ADDRESS' - Resume execution at the instruction at address ADDRESS. - - You can get much the same effect as the `jump' command by storing a -new value into the register `$pc'. The difference is that this does -not 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. -*Note Continuing and stepping: 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. - - -File: gdb.info, Node: Signaling, Next: Returning, Prev: Jumping, Up: Altering - -Giving your program a signal -============================ - -`signal SIGNAL' - Resume execution where your program stopped, but immediately give - it the signal SIGNAL. SIGNAL can be the name or the number of a - signal. For example, on many systems `signal 2' and `signal - SIGINT' are both ways of sending an interrupt signal. - - 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. - - `signal' does not repeat when you press a second time after - executing the command. - - Invoking the `signal' command is not 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 (*note Signals::.). The `signal' command passes the signal -directly to your program. - - -File: gdb.info, Node: Returning, Next: Calling, Prev: Signaling, Up: Altering - -Returning from a function -========================= - -`return' -`return EXPRESSION' - You can cancel execution of a function call with the `return' - command. If you give an EXPRESSION argument, its value is used as - the function's return value. - - 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 (*note Selecting a frame: -Selection.), and any other frames inside of 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 does not resume execution; it leaves the -program stopped in the state that would exist if the function had just -returned. In contrast, the `finish' command (*note Continuing and -stepping: Continuing and Stepping.) resumes execution until the -selected stack frame returns naturally. - - -File: gdb.info, Node: Calling, Next: Patching, Prev: Returning, Up: Altering - -Calling program functions -========================= - -`call EXPR' - Evaluate the expression EXPR without displaying `void' returned - values. - - 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 is not void, it is printed -and saved in the value history. - - A new 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 does not work in systems that have separate -instruction and data spaces. - - -File: gdb.info, Node: Patching, Prev: Calling, Up: Altering - -Patching programs -================= - - By default, GDB opens the file containing your program's executable -code (or the corefile) 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. - -`set write on' -`set write off' - If you specify `set write on', GDB opens executable and core files - for both reading and writing; if you specify `set write off' (the - default), GDB opens them read-only. - - If you have 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. - -`show write' - Display whether executable files and core files are opened for - writing as well as reading. - - -File: gdb.info, Node: GDB Files, Next: Targets, Prev: Altering, Up: Top - -GDB Files -********* - - GDB needs to know the file name of the program to be debugged, both -in order to read its symbol table and in order to start your program. -To debug a core dump of a previous run, you must also tell GDB the name -of the core dump file. - -* Menu: - -* Files:: Commands to specify files -* Symbol Errors:: Errors reading symbol files - - -File: gdb.info, Node: Files, Next: Symbol Errors, Up: GDB Files - -Commands to specify files -========================= - - You may want to specify executable and core dump file names. The -usual way to do this is at start-up time, using the arguments to GDB's -start-up commands (*note Getting In and Out of GDB: Invocation.). - - Occasionally it is necessary to change to a different file during a -GDB session. Or you may run GDB and forget to specify a file you want -to use. In these situations the GDB commands to specify new files are -useful. - -`file FILENAME' - Use FILENAME as the program to be debugged. It is read for its - symbols and for the contents of pure memory. It is also the - program executed when you use the `run' command. If you do not - specify a directory and the file is not found in the GDB working - directory, GDB uses the environment variable `PATH' as a list of - directories to search, just as the shell does when looking for a - program to run. You can change the value of this variable, for - both GDB and your program, using the `path' command. - - On systems with memory-mapped files, an auxiliary file - `FILENAME.syms' may hold symbol table information for FILENAME. - If so, GDB maps in the symbol table from `FILENAME.syms', starting - up more quickly. See the descriptions of the file options - `-mapped' and `-readnow' (available on the command line, and with - the commands `file', `symbol-file', or `add-symbol-file', - described below), for more information. - -`file' - `file' with no argument makes GDB discard any information it has - on both executable file and the symbol table. - -`exec-file [ FILENAME ]' - Specify that the program to be run (but not the symbol table) is - found in FILENAME. GDB searches the environment variable `PATH' - if necessary to locate your program. Omitting FILENAME means to - discard information on the executable file. - -`symbol-file [ FILENAME ]' - Read symbol table information from file FILENAME. `PATH' is - searched when necessary. Use the `file' command to get both symbol - table and program to run from the same file. - - `symbol-file' with no argument clears out GDB information on your - program's symbol table. - - The `symbol-file' command causes GDB to forget the contents of its - convenience variables, the value history, and all breakpoints and - auto-display expressions. This is because they may contain - pointers to the internal data recording symbols and data types, - which are part of the old symbol table data being discarded inside - GDB. - - `symbol-file' does not repeat if you press again after - executing it once. - - When GDB is configured for a particular environment, it - understands debugging information in whatever format is the - standard generated for that environment; you may use either a GNU - compiler, or other compilers that adhere to the local conventions. - Best results are usually obtained from GNU compilers; for - example, using `gcc' you can generate debugging information for - optimized code. - - On some kinds of object files, the `symbol-file' command does not - normally read the symbol table in full right away. Instead, it - scans the symbol table quickly to find which source files and - which symbols are present. The details are read later, one source - file at a time, as they are needed. - - The purpose of this two-stage reading strategy is to make GDB - start up faster. For the most part, it is invisible except for - occasional pauses while the symbol table details for a particular - source file are being read. (The `set verbose' command can turn - these pauses into messages if desired. *Note Optional warnings - and messages: Messages/Warnings.) - - We have not implemented the two-stage strategy for COFF yet. When - the symbol table is stored in COFF format, `symbol-file' reads the - symbol table data in full right away. - -`symbol-file FILENAME [ -readnow ] [ -mapped ]' -`file FILENAME [ -readnow ] [ -mapped ]' - You can override the GDB two-stage strategy for reading symbol - tables by using the `-readnow' option with any of the commands that - load symbol table information, if you want to be sure GDB has the - entire symbol table available. - - If memory-mapped files are available on your system through the - `mmap' system call, you can use another option, `-mapped', to - cause GDB to write the symbols for your program into a reusable - file. Future GDB debugging sessions map in symbol information - from this auxiliary symbol file (if the program has not changed), - rather than spending time reading the symbol table from the - executable program. Using the `-mapped' option has the same - effect as starting GDB with the `-mapped' command-line option. - - You can use both options together, to make sure the auxiliary - symbol file has all the symbol information for your program. - - The auxiliary symbol file for a program called MYPROG is called - `MYPROG.syms'. Once this file exists (so long as it is newer than - the corresponding executable), GDB always attempts to use it when - you debug MYPROG; no special options or commands are needed. - - The `.syms' file is specific to the host machine where you run - GDB. It holds an exact image of the internal GDB symbol table. - It cannot be shared across multiple host platforms. - -`core-file [ FILENAME ]' - Specify the whereabouts of a core dump file to be used as the - "contents of memory". Traditionally, core files contain only some - parts of the address space of the process that generated them; GDB - can access the executable file itself for other parts. - - `core-file' with no argument specifies that no core file is to be - used. - - Note that the core file is ignored when your program is actually - running under GDB. So, if you have been running your program and - you wish to debug a core file instead, you must kill the - subprocess in which the program is running. To do this, use the - `kill' command (*note Killing the child process: Kill Process.). - -`load FILENAME' - Depending on what remote debugging facilities are configured into - GDB, the `load' command may be available. Where it exists, it is - meant to make FILENAME (an executable) available for debugging on - the remote system--by downloading, or dynamic linking, for example. - `load' also records the FILENAME symbol table in GDB, like the - `add-symbol-file' command. - - If your GDB does not have a `load' command, attempting to execute - it gets the error message "`You can't do that when your target is - ...'" - - The file is loaded at whatever address is specified in the - executable. For some object file formats, you can specify the - load address when you link the program; for other formats, like - a.out, the object file format specifies a fixed address. - - On VxWorks, `load' links FILENAME dynamically on the current - target system as well as adding its symbols in GDB. - - With the Nindy interface to an Intel 960 board, `load' downloads - FILENAME to the 960 as well as adding its symbols in GDB. - - When you select remote debugging to a Hitachi SH, H8/300, or - H8/500 board (*note GDB and Hitachi Microprocessors: Hitachi - Remote.), the `load' command downloads your program to the Hitachi - board and also opens it as the current executable target for GDB - on your host (like the `file' command). - - `load' does not repeat if you press again after using it. - -`add-symbol-file FILENAME ADDRESS' -`add-symbol-file FILENAME ADDRESS [ -readnow ] [ -mapped ]' - The `add-symbol-file' command reads additional symbol table - information from the file FILENAME. You would use this command - when FILENAME has been dynamically loaded (by some other means) - into the program that is running. ADDRESS should be the memory - address at which the file has been loaded; GDB cannot figure this - out for itself. You can specify ADDRESS as an expression. - - The symbol table of the file FILENAME is added to the symbol table - originally read with the `symbol-file' command. You can use the - `add-symbol-file' command any number of times; the new symbol data - thus read keeps adding to the old. To discard all old symbol data - instead, use the `symbol-file' command. - - `add-symbol-file' does not repeat if you press after using - it. - - You can use the `-mapped' and `-readnow' options just as with the - `symbol-file' command, to change how GDB manages the symbol table - information for FILENAME. - -`add-shared-symbol-file' - The `add-shared-symbol-file' command can be used only under - Harris' CXUX operating system for the Motorola 88k. GDB - automatically looks for shared libraries, however if GDB does not - find yours, you can run `add-shared-symbol-file'. It takes no - arguments. - -`section' - The `section' command changes the base address of section SECTION - of the exec file to ADDR. This can be used if the exec file does - not contain section addresses, (such as in the a.out format), or - when the addresses specified in the file itself are wrong. Each - section must be changed separately. The "info files" command - lists all the sections and their addresses. - -`info files' -`info target' - `info files' and `info target' are synonymous; both print the - current target (*note Specifying a Debugging Target: Targets.), - including the names of the executable and core dump files - currently in use by GDB, and the files from which symbols were - loaded. The command `help target' lists all possible targets - rather than current ones. - - All file-specifying commands allow both absolute and relative file -names as arguments. GDB always converts the file name to an absolute -file name and remembers it that way. - - GDB supports SunOS, SVr4, Irix 5, and IBM RS/6000 shared libraries. -GDB automatically loads symbol definitions from shared libraries when -you use the `run' command, or when you examine a core file. (Before -you issue the `run' command, GDB does not understand references to a -function in a shared library, however--unless you are debugging a core -file). - -`info share' -`info sharedlibrary' - Print the names of the shared libraries which are currently loaded. - -`sharedlibrary REGEX' -`share REGEX' - Load shared object library symbols for files matching a Unix - regular expression. As with files loaded automatically, it only - loads shared libraries required by your program for a core file or - after typing `run'. If REGEX is omitted all shared libraries - required by your program are loaded. - - -File: gdb.info, Node: Symbol Errors, Prev: Files, Up: GDB Files - -Errors reading symbol files -=========================== - - While reading a symbol file, GDB occasionally encounters problems, -such as symbol types it does not recognize, or known bugs in compiler -output. By default, GDB does not notify you of such problems, since -they are relatively common and primarily of interest to people -debugging compilers. If you are interested in seeing information about -ill-constructed symbol tables, you can either ask GDB to print only one -message about each such type of problem, no matter how many times the -problem occurs; or you can ask GDB to print more messages, to see how -many times the problems occur, with the `set complaints' command (*note -Optional warnings and messages: Messages/Warnings.). - - The messages currently printed, and their meanings, include: - -`inner block not inside outer block in SYMBOL' - The symbol information shows where symbol scopes begin and end - (such as at the start of a function or a block of statements). - This error indicates that an inner scope block is not fully - contained in its outer scope blocks. - - GDB circumvents the problem by treating the inner block as if it - had the same scope as the outer block. In the error message, - SYMBOL may be shown as "`(don't know)'" if the outer block is not a - function. - -`block at ADDRESS out of order' - The symbol information for symbol scope blocks should occur in - order of increasing addresses. This error indicates that it does - not do so. - - GDB does not circumvent this problem, and has trouble locating - symbols in the source file whose symbols it is reading. (You can - often determine what source file is affected by specifying `set - verbose on'. *Note Optional warnings and messages: - Messages/Warnings.) - -`bad block start address patched' - The symbol information for a symbol scope block has a start address - smaller than the address of the preceding source line. This is - known to occur in the SunOS 4.1.1 (and earlier) C compiler. - - GDB circumvents the problem by treating the symbol scope block as - starting on the previous source line. - -`bad string table offset in symbol N' - Symbol number N contains a pointer into the string table which is - larger than the size of the string table. - - GDB circumvents the problem by considering the symbol to have the - name `foo', which may cause other problems if many symbols end up - with this name. - -`unknown symbol type `0xNN'' - The symbol information contains new data types that GDB does not - yet know how to read. `0xNN' is the symbol type of the - misunderstood information, in hexadecimal. - - GDB circumvents the error by ignoring this symbol information. - This usually allows you to debug your program, though certain - symbols are not accessible. If you encounter such a problem and - feel like debugging it, you can debug `gdb' with itself, - breakpoint on `complain', then go up to the function - `read_dbx_symtab' and examine `*bufp' to see the symbol. - -`stub type has NULL name' - GDB could not find the full definition for a struct or class. - -`const/volatile indicator missing (ok if using g++ v1.x), got...' - The symbol information for a C++ member function is missing some - information that recent versions of the compiler should have output - for it. - -`info mismatch between compiler and debugger' - GDB could not parse a type specification output by the compiler. - - -File: gdb.info, Node: Targets, Next: Controlling GDB, Prev: GDB Files, Up: Top - -Specifying a Debugging Target -***************************** - - A "target" is the execution environment occupied by your program. -Often, GDB runs in the same host environment as your program; in that -case, the debugging target is specified as a side effect when you use -the `file' or `core' commands. When you need more flexibility--for -example, running GDB on a physically separate host, or controlling a -standalone system over a serial port or a realtime system over a TCP/IP -connection--you can use the `target' command to specify one of the -target types configured for GDB (*note Commands for managing targets: -Target Commands.). - -* Menu: - -* Active Targets:: Active targets -* Target Commands:: Commands for managing targets -* Remote:: Remote debugging - - -File: gdb.info, Node: Active Targets, Next: Target Commands, Up: Targets - -Active targets -============== - - There are three classes of targets: processes, core files, and -executable files. GDB can work concurrently on up to three active -targets, one in each class. This allows you to (for example) start a -process and inspect its activity without abandoning your work on a core -file. - - For example, if you execute `gdb a.out', then the executable file -`a.out' is the only active target. If you designate a core file as -well--presumably from a prior run that crashed and coredumped--then GDB -has two active targets and uses them in tandem, looking first in the -corefile target, then in the executable file, to satisfy requests for -memory addresses. (Typically, these two classes of target are -complementary, since core files contain only a program's read-write -memory--variables and so on--plus machine status, while executable -files contain only the program text and initialized data.) - - When you type `run', your executable file becomes an active process -target as well. When a process target is active, all GDB commands -requesting memory addresses refer to that target; addresses in an -active core file or executable file target are obscured while the -process target is active. - - Use the `core-file' and `exec-file' commands to select a new core -file or executable target (*note Commands to specify files: Files.). -To specify as a target a process that is already running, use the -`attach' command (*note Debugging an already-running process: Attach.). - diff --git a/gnu/dist/gdb/doc/gdb.info-6 b/gnu/dist/gdb/doc/gdb.info-6 deleted file mode 100644 index 6605bff72b5a..000000000000 --- a/gnu/dist/gdb/doc/gdb.info-6 +++ /dev/null @@ -1,1294 +0,0 @@ -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 Fifth Edition, April 1998, of `Debugging with GDB: the -GNU Source-Level Debugger' for GDB Version . - - Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, -1997, 1998 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: Target Commands, Next: Remote, Prev: Active Targets, Up: Targets - -Commands for managing targets -============================= - -`target TYPE PARAMETERS' - Connects the GDB host environment to a target machine or process. - A target is typically a protocol for talking to debugging - facilities. You use the argument TYPE to specify the type or - protocol of the target machine. - - Further PARAMETERS are interpreted by the target protocol, but - typically include things like device names or host names to connect - with, process numbers, and baud rates. - - The `target' command does not repeat if you press again - after executing the command. - -`help target' - Displays the names of all targets available. To display targets - currently selected, use either `info target' or `info files' - (*note Commands to specify files: Files.). - -`help target NAME' - Describe a particular target, including any parameters necessary to - select it. - -`set gnutarget ARGS' - GDBuses its own library BFD to read your files. GDB knows whether - it is reading an "executable", a "core", or a ".o" file, however - you can specify the file format with the `set gnutarget' command. - Unlike most `target' commands, with `gnutarget' the `target' - refers to a program, not a machine. - - *Warning:* To specify a file format with `set gnutarget', you must - know the actual BFD name. - - *Note Commands to specify files: Files. - -`show gnutarget' - Use the `show gnutarget' command to display what file format - `gnutarget' is set to read. If you have not set `gnutarget', GDB - will determine the file format for each file automatically and - `show gnutarget' displays `The current BDF target is "auto"'. - - Here are some common targets (available, or not, depending on the GDB -configuration): - -`target exec PROGRAM' - An executable file. `target exec PROGRAM' is the same as - `exec-file PROGRAM'. - -`target core FILENAME' - A core dump file. `target core FILENAME' is the same as - `core-file FILENAME'. - -`target remote DEV' - Remote serial target in GDB-specific protocol. The argument DEV - specifies what serial device to use for the connection (e.g. - `/dev/ttya'). *Note Remote debugging: Remote. `target remote' now - supports the `load' command. This is only useful if you have some - other way of getting the stub to the target system, and you can put - it somewhere in memory where it won't get clobbered by the - download. - -`target sim' - CPU simulator. *Note Simulated CPU Target: Simulator. - -`target udi KEYWORD' - Remote AMD29K target, using the AMD UDI protocol. The KEYWORD - argument specifies which 29K board or simulator to use. *Note The - UDI protocol for AMD29K: UDI29K Remote. - -`target amd-eb DEV SPEED PROG' - Remote PC-resident AMD EB29K board, attached over serial lines. - DEV is the serial device, as for `target remote'; SPEED allows you - to specify the linespeed; and PROG is the name of the program to - be debugged, as it appears to DOS on the PC. *Note The EBMON - protocol for AMD29K: EB29K Remote. - -`target hms DEV' - A Hitachi SH, H8/300, or H8/500 board, attached via serial line to - your host. Use special commands `device' and `speed' to control - the serial line and the communications speed used. *Note GDB and - Hitachi Microprocessors: Hitachi Remote. - -`target nindy DEVICENAME' - An Intel 960 board controlled by a Nindy Monitor. DEVICENAME is - the name of the serial device to use for the connection, e.g. - `/dev/ttya'. *Note GDB with a remote i960 (Nindy): i960-Nindy - Remote. - -`target st2000 DEV SPEED' - A Tandem ST2000 phone switch, running Tandem's STDBUG protocol. - DEV is the name of the device attached to the ST2000 serial line; - SPEED is the communication line speed. The arguments are not used - if GDB is configured to connect to the ST2000 using TCP or Telnet. - *Note GDB with a Tandem ST2000: ST2000 Remote. - -`target vxworks MACHINENAME' - A VxWorks system, attached via TCP/IP. The argument MACHINENAME - is the target system's machine name or IP address. *Note GDB and - VxWorks: VxWorks Remote. - -`target bug DEV' - BUG monitor, running on a MVME187 (m88k) board. - -`target cpu32bug DEV' - CPU32BUG monitor, running on a CPU32 (M68K) board. - -`target op50n DEV' - OP50N monitor, running on an OKI HPPA board. - -`target w89k DEV' - W89K monitor, running on a Winbond HPPA board. - -`target est DEV' - EST-300 ICE monitor, running on a CPU32 (M68K) board. - -`target rom68k DEV' - ROM 68K monitor, running on an IDP board. - -`target array DEV' - Array Tech LSI33K RAID controller board. - -`target sparclite DEV' - Fujitsu sparclite boards, used only for the purpose of loading. - You must use an additional command to debug the program. For - example: target remote DEV using GDB standard remote protocol. - - Different targets are available on different configurations of GDB; -your configuration may have more or fewer targets. - -Choosing target byte order -========================== - - You can now choose which byte order to use with a target system. -Use the `set endian big' and `set endian little' commands. Use the -`set endian auto' command to instruct GDB to use the byte order -associated with the executable. You can see the current setting for -byte order with the `show endian' command. - - *Warning:* Currently, only embedded MIPS configurations support -dynamic selection of target byte order. - - -File: gdb.info, Node: Remote, Prev: Target Commands, Up: Targets - -Remote debugging -================ - - If you are trying to debug a program running on a machine that -cannot run GDB in the usual way, it is often useful to use remote -debugging. For example, you might use remote debugging on an operating -system kernel, or on a small system which does not have a general -purpose operating system powerful enough to run a full-featured -debugger. - - Some configurations of GDB have special serial or TCP/IP interfaces -to make this work with particular debugging targets. In addition, GDB -comes with a generic serial protocol (specific to GDB, but not specific -to any particular target system) which you can use if you write the -remote stubs--the code that runs on the remote system to communicate -with GDB. - - Other remote targets may be available in your configuration of GDB; -use `help target' to list them. - -* Menu: - - -* 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 - -* Sparclet Remote:: GDB and Sparclet boards - -* Simulator:: Simulated CPU target - - -File: gdb.info, Node: Remote Serial, Next: i960-Nindy Remote, Up: Remote - -The GDB remote serial protocol ------------------------------- - - To debug a program running on another machine (the debugging -"target" machine), you must first arrange for all the usual -prerequisites for the program to run by itself. For example, for a C -program, you need: - - 1. A startup routine to set up the C runtime environment; these - usually have a name like `crt0'. The startup routine may be - supplied by your hardware supplier, or you may have to write your - own. - - 2. You probably need a C subroutine library to support your program's - subroutine calls, notably managing input and output. - - 3. A way of getting your program to the other machine--for example, a - download program. These are often supplied by the hardware - manufacturer, but you may have to write your own from hardware - documentation. - - The next step is to arrange for your program to use a serial port to -communicate with the machine where GDB is running (the "host" machine). -In general terms, the scheme looks like this: - -*On the host,* - GDB already understands how to use this protocol; when everything - else is set up, you can simply use the `target remote' command - (*note Specifying a Debugging Target: Targets.). - -*On the target,* - you must link with your program a few special-purpose subroutines - that implement the GDB remote serial protocol. The file - containing these subroutines is called a "debugging stub". - - On certain remote targets, you can use an auxiliary program - `gdbserver' instead of linking a stub into your program. *Note - Using the `gdbserver' program: Server, for details. - - The debugging stub is specific to the architecture of the remote -machine; for example, use `sparc-stub.c' to debug programs on SPARC -boards. - - These working remote stubs are distributed with GDB: - -`i386-stub.c' - For Intel 386 and compatible architectures. - -`m68k-stub.c' - For Motorola 680x0 architectures. - -`sh-stub.c' - For Hitachi SH architectures. - -`sparc-stub.c' - For SPARC architectures. - -`sparcl-stub.c' - For Fujitsu SPARCLITE architectures. - - The `README' file in the GDB distribution may list other recently -added stubs. - -* Menu: - -* Stub Contents:: What the stub can do for you -* Bootstrapping:: What you must do for the stub -* Debug Session:: Putting it all together -* Protocol:: Outline of the communication protocol - -* Server:: Using the `gdbserver' program - -* NetWare:: Using the `gdbserve.nlm' program - - -File: gdb.info, Node: Stub Contents, Next: Bootstrapping, Up: Remote Serial - -What the stub can do for you -............................ - - The debugging stub for your architecture supplies these three -subroutines: - -`set_debug_traps' - This routine arranges for `handle_exception' to run when your - program stops. You must call this subroutine explicitly near the - beginning of your program. - -`handle_exception' - This is the central workhorse, but your program never calls it - explicitly--the setup code arranges for `handle_exception' to run - when a trap is triggered. - - `handle_exception' takes control when your program stops during - execution (for example, on a breakpoint), and mediates - communications with GDB on the host machine. This is where the - communications protocol is implemented; `handle_exception' acts as - the GDB representative on the target machine; it begins by sending - summary information on the state of your program, then continues - to execute, retrieving and transmitting any information GDB needs, - until you execute a GDB command that makes your program resume; at - that point, `handle_exception' returns control to your own code on - the target machine. - -`breakpoint' - Use this auxiliary subroutine to make your program contain a - breakpoint. Depending on the particular situation, this may be - the only way for GDB to get control. For instance, if your target - machine has some sort of interrupt button, you won't need to call - this; pressing the interrupt button transfers control to - `handle_exception'--in effect, to GDB. On some machines, simply - receiving characters on the serial port may also trigger a trap; - again, in that situation, you don't need to call `breakpoint' from - your own program--simply running `target remote' from the host GDB - session gets control. - - Call `breakpoint' if none of these is true, or if you simply want - to make certain your program stops at a predetermined point for the - start of your debugging session. - - -File: gdb.info, Node: Bootstrapping, Next: Debug Session, Prev: Stub Contents, Up: Remote Serial - -What you must do for the stub -............................. - - The debugging stubs that come with GDB are set up for a particular -chip architecture, but they have no information about the rest of your -debugging target machine. - - First of all you need to tell the stub how to communicate with the -serial port. - -`int getDebugChar()' - Write this subroutine to read a single character from the serial - port. It may be identical to `getchar' for your target system; a - different name is used to allow you to distinguish the two if you - wish. - -`void putDebugChar(int)' - Write this subroutine to write a single character to the serial - port. It may be identical to `putchar' for your target system; a - different name is used to allow you to distinguish the two if you - wish. - - If you want GDB to be able to stop your program while it is running, -you need to use an interrupt-driven serial driver, and arrange for it -to stop when it receives a `^C' (`\003', the control-C character). -That is the character which GDB uses to tell the remote system to stop. - - Getting the debugging target to return the proper status to GDB -probably requires changes to the standard stub; one quick and dirty way -is to just execute a breakpoint instruction (the "dirty" part is that -GDB reports a `SIGTRAP' instead of a `SIGINT'). - - Other routines you need to supply are: - -`void exceptionHandler (int EXCEPTION_NUMBER, void *EXCEPTION_ADDRESS)' - Write this function to install EXCEPTION_ADDRESS in the exception - handling tables. You need to do this because the stub does not - have any way of knowing what the exception handling tables on your - target system are like (for example, the processor's table might - be in ROM, containing entries which point to a table in RAM). - EXCEPTION_NUMBER is the exception number which should be changed; - its meaning is architecture-dependent (for example, different - numbers might represent divide by zero, misaligned access, etc). - When this exception occurs, control should be transferred directly - to EXCEPTION_ADDRESS, and the processor state (stack, registers, - and so on) should be just as it is when a processor exception - occurs. So if you want to use a jump instruction to reach - EXCEPTION_ADDRESS, it should be a simple jump, not a jump to - subroutine. - - For the 386, EXCEPTION_ADDRESS should be installed as an interrupt - gate so that interrupts are masked while the handler runs. The - gate should be at privilege level 0 (the most privileged level). - The SPARC and 68k stubs are able to mask interrup themselves - without help from `exceptionHandler'. - -`void flush_i_cache()' - (sparc and sparclite only) Write this subroutine to flush the - instruction cache, if any, on your target machine. If there is no - instruction cache, this subroutine may be a no-op. - - On target machines that have instruction caches, GDB requires this - function to make certain that the state of your program is stable. - -You must also make sure this library routine is available: - -`void *memset(void *, int, int)' - This is the standard library function `memset' that sets an area of - memory to a known value. If you have one of the free versions of - `libc.a', `memset' can be found there; otherwise, you must either - obtain it from your hardware manufacturer, or write your own. - - If you do not use the GNU C compiler, you may need other standard -library subroutines as well; this varies from one stub to another, but -in general the stubs are likely to use any of the common library -subroutines which `gcc' generates as inline code. - - -File: gdb.info, Node: Debug Session, Next: Protocol, Prev: Bootstrapping, Up: Remote Serial - -Putting it all together -....................... - - In summary, when your program is ready to debug, you must follow -these steps. - - 1. Make sure you have the supporting low-level routines (*note What - you must do for the stub: Bootstrapping.): - `getDebugChar', `putDebugChar', - `flush_i_cache', `memset', `exceptionHandler'. - - 2. Insert these lines near the top of your program: - - set_debug_traps(); - breakpoint(); - - 3. For the 680x0 stub only, you need to provide a variable called - `exceptionHook'. Normally you just use: - - void (*exceptionHook)() = 0; - - but if before calling `set_debug_traps', you set it to point to a - function in your program, that function is called when `GDB' - continues after stopping on a trap (for example, bus error). The - function indicated by `exceptionHook' is called with one - parameter: an `int' which is the exception number. - - 4. Compile and link together: your program, the GDB debugging stub for - your target architecture, and the supporting subroutines. - - 5. Make sure you have a serial connection between your target machine - and the GDB host, and identify the serial port on the host. - - 6. Download your program to your target machine (or get it there by - whatever means the manufacturer provides), and start it. - - 7. To start remote debugging, run GDB on the host machine, and specify - as an executable file the program that is running in the remote - machine. This tells GDB how to find your program's symbols and - the contents of its pure text. - - Then establish communication using the `target remote' command. - Its argument specifies how to communicate with the target - machine--either via a devicename attached to a direct serial line, - or a TCP port (usually to a terminal server which in turn has a - serial line to the target). For example, to use a serial line - connected to the device named `/dev/ttyb': - - target remote /dev/ttyb - - To use a TCP connection, use an argument of the form `HOST:port'. - For example, to connect to port 2828 on a terminal server named - `manyfarms': - - target remote manyfarms:2828 - - Now you can use all the usual commands to examine and change data -and to step and continue the remote program. - - To resume the remote program and stop debugging it, use the `detach' -command. - - Whenever GDB is waiting for the remote program, if you type the -interrupt character (often ), GDB attempts to stop the program. -This may or may not succeed, depending in part on the hardware and the -serial drivers the remote system uses. If you type the interrupt -character once again, GDB displays this prompt: - - Interrupted while waiting for the program. - Give up (and stop debugging it)? (y or n) - - If you type `y', GDB abandons the remote debugging session. (If you -decide you want to try again later, you can use `target remote' again -to connect once more.) If you type `n', GDB goes back to waiting. - - -File: gdb.info, Node: Protocol, Next: Server, Prev: Debug Session, Up: Remote Serial - -Communication protocol -...................... - - The stub files provided with GDB implement the target side of the -communication protocol, and the GDB side is implemented in the GDB -source file `remote.c'. Normally, you can simply allow these -subroutines to communicate, and ignore the details. (If you're -implementing your own stub file, you can still ignore the details: start -with one of the existing stub files. `sparc-stub.c' is the best -organized, and therefore the easiest to read.) - - However, there may be occasions when you need to know something about -the protocol--for example, if there is only one serial port to your -target machine, you might want your program to do something special if -it recognizes a packet meant for GDB. - - All GDB commands and responses (other than acknowledgements, which -are single characters) are sent as a packet which includes a checksum. -A packet is introduced with the character `$', and ends with the -character `#' followed by a two-digit checksum: - - $PACKET INFO#CHECKSUM - -CHECKSUM is computed as the modulo 256 sum of the PACKET INFO -characters. - - When either the host or the target machine receives a packet, the -first response expected is an acknowledgement: a single character, -either `+' (to indicate the package was received correctly) or `-' (to -request retransmission). - - The host (GDB) sends commands, and the target (the debugging stub -incorporated in your program) sends data in response. The target also -sends data when your program stops. - - Command packets are distinguished by their first character, which -identifies the kind of command. - - These are some of the commands currently supported (for a complete -list of commands, look in `gdb/remote.c.'): - -`g' - Requests the values of CPU registers. - -`G' - Sets the values of CPU registers. - -`mADDR,COUNT' - Read COUNT bytes at location ADDR. - -`MADDR,COUNT:...' - Write COUNT bytes at location ADDR. - -`c' -`cADDR' - Resume execution at the current address (or at ADDR if supplied). - -`s' -`sADDR' - Step the target program for one instruction, from either the - current program counter or from ADDR if supplied. - -`k' - Kill the target program. - -`?' - Report the most recent signal. To allow you to take advantage of - the GDB signal handling commands, one of the functions of the - debugging stub is to report CPU traps as the corresponding POSIX - signal values. - -`T' - Allows the remote stub to send only the registers that GDB needs - to make a quick decision about single-stepping or conditional - breakpoints. This eliminates the need to fetch the entire - register set for each instruction being stepped through. - - The GDB remote serial protocol now implements a write-through - cache for registers. GDB only re-reads the registers if the - target has run. - - If you have trouble with the serial connection, you can use the -command `set remotedebug'. This makes GDB report on all packets sent -back and forth across the serial line to the remote machine. The -packet-debugging information is printed on the GDB standard output -stream. `set remotedebug off' turns it off, and `show remotedebug' -shows you its current state. - - -File: gdb.info, Node: Server, Next: NetWare, Prev: Protocol, Up: Remote Serial - -Using the `gdbserver' program -............................. - - `gdbserver' is a control program for Unix-like systems, which allows -you to connect your program with a remote GDB via `target remote'--but -without linking in the usual debugging stub. - - `gdbserver' is not a complete replacement for the debugging stubs, -because it requires essentially the same operating-system facilities -that GDB itself does. In fact, a system that can run `gdbserver' to -connect to a remote GDB could also run GDB locally! `gdbserver' is -sometimes useful nevertheless, because it is a much smaller program -than GDB itself. It is also easier to port than all of GDB, so you may -be able to get started more quickly on a new system by using -`gdbserver'. Finally, if you develop code for real-time systems, you -may find that the tradeoffs involved in real-time operation make it -more convenient to do as much development work as possible on another -system, for example by cross-compiling. You can use `gdbserver' to -make a similar choice for debugging. - - GDB and `gdbserver' communicate via either a serial line or a TCP -connection, using the standard GDB remote serial protocol. - -*On the target machine,* - you need to have a copy of the program you want to debug. - `gdbserver' does not need your program's symbol table, so you can - strip the program if necessary to save space. GDB on the host - system does all the symbol handling. - - To use the server, you must tell it how to communicate with GDB; - the name of your program; and the arguments for your program. The - syntax is: - - target> gdbserver COMM PROGRAM [ ARGS ... ] - - COMM is either a device name (to use a serial line) or a TCP - hostname and portnumber. For example, to debug Emacs with the - argument `foo.txt' and communicate with GDB over the serial port - `/dev/com1': - - target> gdbserver /dev/com1 emacs foo.txt - - `gdbserver' waits passively for the host GDB to communicate with - it. - - To use a TCP connection instead of a serial line: - - target> gdbserver host:2345 emacs foo.txt - - The only difference from the previous example is the first - argument, specifying that you are communicating with the host GDB - via TCP. The `host:2345' argument means that `gdbserver' is to - expect a TCP connection from machine `host' to local TCP port 2345. - (Currently, the `host' part is ignored.) You can choose any number - you want for the port number as long as it does not conflict with - any TCP ports already in use on the target system (for example, - `23' is reserved for `telnet').(1) You must use the same port - number with the host GDB `target remote' command. - -*On the GDB host machine,* - you need an unstripped copy of your program, since GDB needs - symbols and debugging information. Start up GDB as usual, using - the name of the local copy of your program as the first argument. - (You may also need the `--baud' option if the serial line is - running at anything other than 9600 bps.) After that, use `target - remote' to establish communications with `gdbserver'. Its argument - is either a device name (usually a serial device, like - `/dev/ttyb'), or a TCP port descriptor in the form `HOST:PORT'. - For example: - - (gdb) target remote /dev/ttyb - - communicates with the server via serial line `/dev/ttyb', and - - (gdb) target remote the-target:2345 - - communicates via a TCP connection to port 2345 on host - `the-target'. For TCP connections, you must start up `gdbserver' - prior to using the `target remote' command. Otherwise you may get - an error whose text depends on the host system, but which usually - looks something like `Connection refused'. - - ---------- Footnotes ---------- - - (1) If you choose a port number that conflicts with another service, -`gdbserver' prints an error message and exits. - - -File: gdb.info, Node: NetWare, Prev: Server, Up: Remote Serial - -Using the `gdbserve.nlm' program -................................ - - `gdbserve.nlm' is a control program for NetWare systems, which -allows you to connect your program with a remote GDB via `target -remote'. - - GDB and `gdbserve.nlm' communicate via a serial line, using the -standard GDB remote serial protocol. - -*On the target machine,* - you need to have a copy of the program you want to debug. - `gdbserve.nlm' does not need your program's symbol table, so you - can strip the program if necessary to save space. GDB on the host - system does all the symbol handling. - - To use the server, you must tell it how to communicate with GDB; - the name of your program; and the arguments for your program. The - syntax is: - - load gdbserve [ BOARD=BOARD ] [ PORT=PORT ] - [ BAUD=BAUD ] PROGRAM [ ARGS ... ] - - BOARD and PORT specify the serial line; BAUD specifies the baud - rate used by the connection. PORT and NODE default to 0, BAUD - defaults to 9600 bps. - - For example, to debug Emacs with the argument `foo.txt'and - communicate with GDB over serial port number 2 or board 1 using a - 19200 bps connection: - - load gdbserve BOARD=1 PORT=2 BAUD=19200 emacs foo.txt - -*On the GDB host machine,* - you need an unstripped copy of your program, since GDB needs - symbols and debugging information. Start up GDB as usual, using - the name of the local copy of your program as the first argument. - (You may also need the `--baud' option if the serial line is - running at anything other than 9600 bps. After that, use `target - remote' to establish communications with `gdbserve.nlm'. Its - argument is a device name (usually a serial device, like - `/dev/ttyb'). For example: - - (gdb) target remote /dev/ttyb - - communications with the server via serial line `/dev/ttyb'. - - -File: gdb.info, Node: i960-Nindy Remote, Next: UDI29K Remote, Prev: Remote Serial, Up: Remote - -GDB with a remote i960 (Nindy) ------------------------------- - - "Nindy" is a ROM Monitor program for Intel 960 target systems. When -GDB is configured to control a remote Intel 960 using Nindy, you can -tell GDB how to connect to the 960 in several ways: - - * Through command line options specifying serial port, version of the - Nindy protocol, and communications speed; - - * By responding to a prompt on startup; - - * By using the `target' command at any point during your GDB - session. *Note Commands for managing targets: Target Commands. - -* Menu: - -* Nindy Startup:: Startup with Nindy -* Nindy Options:: Options for Nindy -* Nindy Reset:: Nindy reset command - - -File: gdb.info, Node: Nindy Startup, Next: Nindy Options, Up: i960-Nindy Remote - -Startup with Nindy -.................. - - If you simply start `gdb' without using any command-line options, -you are prompted for what serial port to use, *before* you reach the -ordinary GDB prompt: - - Attach /dev/ttyNN -- specify NN, or "quit" to quit: - -Respond to the prompt with whatever suffix (after `/dev/tty') -identifies the serial port you want to use. You can, if you choose, -simply start up with no Nindy connection by responding to the prompt -with an empty line. If you do this and later wish to attach to Nindy, -use `target' (*note Commands for managing targets: Target Commands.). - - -File: gdb.info, Node: Nindy Options, Next: Nindy Reset, Prev: Nindy Startup, Up: i960-Nindy Remote - -Options for Nindy -................. - - These are the startup options for beginning your GDB session with a -Nindy-960 board attached: - -`-r PORT' - Specify the serial port name of a serial interface to be used to - connect to the target system. This option is only available when - GDB is configured for the Intel 960 target architecture. You may - specify PORT as any of: a full pathname (e.g. `-r /dev/ttya'), a - device name in `/dev' (e.g. `-r ttya'), or simply the unique - suffix for a specific `tty' (e.g. `-r a'). - -`-O' - (An uppercase letter "O", not a zero.) Specify that GDB should use - the "old" Nindy monitor protocol to connect to the target system. - This option is only available when GDB is configured for the Intel - 960 target architecture. - - *Warning:* if you specify `-O', but are actually trying to - connect to a target system that expects the newer protocol, - the connection fails, appearing to be a speed mismatch. GDB - repeatedly attempts to reconnect at several different line - speeds. You can abort this process with an interrupt. - -`-brk' - Specify that GDB should first send a `BREAK' signal to the target - system, in an attempt to reset it, before connecting to a Nindy - target. - - *Warning:* Many target systems do not have the hardware that - this requires; it only works with a few boards. - - The standard `-b' option controls the line speed used on the serial -port. - - -File: gdb.info, Node: Nindy Reset, Prev: Nindy Options, Up: i960-Nindy Remote - -Nindy reset command -................... - -`reset' - For a Nindy target, this command sends a "break" to the remote - target system; this is only useful if the target has been equipped - with a circuit to perform a hard reset (or some other interesting - action) when a break is detected. - - -File: gdb.info, Node: UDI29K Remote, Next: EB29K Remote, Prev: i960-Nindy Remote, Up: Remote - -The UDI protocol for AMD29K ---------------------------- - - GDB supports AMD's UDI ("Universal Debugger Interface") protocol for -debugging the a29k processor family. To use this configuration with -AMD targets running the MiniMON monitor, you need the program `MONTIP', -available from AMD at no charge. You can also use GDB with the -UDI-conformant a29k simulator program `ISSTIP', also available from AMD. - -`target udi KEYWORD' - Select the UDI interface to a remote a29k board or simulator, where - KEYWORD is an entry in the AMD configuration file `udi_soc'. This - file contains keyword entries which specify parameters used to - connect to a29k targets. If the `udi_soc' file is not in your - working directory, you must set the environment variable `UDICONF' - to its pathname. - - -File: gdb.info, Node: EB29K Remote, Next: VxWorks Remote, Prev: UDI29K Remote, Up: Remote - -The EBMON protocol for AMD29K ------------------------------ - - AMD distributes a 29K development board meant to fit in a PC, -together with a DOS-hosted monitor program called `EBMON'. As a -shorthand term, this development system is called the "EB29K". To use -GDB from a Unix system to run programs on the EB29K board, you must -first connect a serial cable between the PC (which hosts the EB29K -board) and a serial port on the Unix system. In the following, we -assume you've hooked the cable between the PC's `COM1' port and -`/dev/ttya' on the Unix system. - -* Menu: - -* Comms (EB29K):: Communications setup -* gdb-EB29K:: EB29K cross-debugging -* Remote Log:: Remote log - - -File: gdb.info, Node: Comms (EB29K), Next: gdb-EB29K, Up: EB29K Remote - -Communications setup -.................... - - The next step is to set up the PC's port, by doing something like -this in DOS on the PC: - - C:\> MODE com1:9600,n,8,1,none - -This example--run on an MS DOS 4.0 system--sets the PC port to 9600 -bps, no parity, eight data bits, one stop bit, and no "retry" action; -you must match the communications parameters when establishing the Unix -end of the connection as well. - - To give control of the PC to the Unix side of the serial line, type -the following at the DOS console: - - C:\> CTTY com1 - -(Later, if you wish to return control to the DOS console, you can use -the command `CTTY con'--but you must send it over the device that had -control, in our example over the `COM1' serial line). - - From the Unix host, use a communications program such as `tip' or -`cu' to communicate with the PC; for example, - - cu -s 9600 -l /dev/ttya - -The `cu' options shown specify, respectively, the linespeed and the -serial port to use. If you use `tip' instead, your command line may -look something like the following: - - tip -9600 /dev/ttya - -Your system may require a different name where we show `/dev/ttya' as -the argument to `tip'. The communications parameters, including which -port to use, are associated with the `tip' argument in the "remote" -descriptions file--normally the system table `/etc/remote'. - - Using the `tip' or `cu' connection, change the DOS working directory -to the directory containing a copy of your 29K program, then start the -PC program `EBMON' (an EB29K control program supplied with your board -by AMD). You should see an initial display from `EBMON' similar to the -one that follows, ending with the `EBMON' prompt `#'-- - - C:\> G: - - G:\> CD \usr\joe\work29k - - G:\USR\JOE\WORK29K> EBMON - Am29000 PC Coprocessor Board Monitor, version 3.0-18 - Copyright 1990 Advanced Micro Devices, Inc. - Written by Gibbons and Associates, Inc. - - Enter '?' or 'H' for help - - PC Coprocessor Type = EB29K - I/O Base = 0x208 - Memory Base = 0xd0000 - - Data Memory Size = 2048KB - Available I-RAM Range = 0x8000 to 0x1fffff - Available D-RAM Range = 0x80002000 to 0x801fffff - - PageSize = 0x400 - Register Stack Size = 0x800 - Memory Stack Size = 0x1800 - - CPU PRL = 0x3 - Am29027 Available = No - Byte Write Available = Yes - - # ~. - - Then exit the `cu' or `tip' program (done in the example by typing -`~.' at the `EBMON' prompt). `EBMON' keeps running, ready for GDB to -take over. - - For this example, we've assumed what is probably the most convenient -way to make sure the same 29K program is on both the PC and the Unix -system: a PC/NFS connection that establishes "drive `G:'" on the PC as -a file system on the Unix host. If you do not have PC/NFS or something -similar connecting the two systems, you must arrange some other -way--perhaps floppy-disk transfer--of getting the 29K program from the -Unix system to the PC; GDB does *not* download it over the serial line. - - -File: gdb.info, Node: gdb-EB29K, Next: Remote Log, Prev: Comms (EB29K), Up: EB29K Remote - -EB29K cross-debugging -..................... - - Finally, `cd' to the directory containing an image of your 29K -program on the Unix system, and start GDB--specifying as argument the -name of your 29K program: - - cd /usr/joe/work29k - gdb myfoo - - Now you can use the `target' command: - - target amd-eb /dev/ttya 9600 MYFOO - -In this example, we've assumed your program is in a file called -`myfoo'. Note that the filename given as the last argument to `target -amd-eb' should be the name of the program as it appears to DOS. In our -example this is simply `MYFOO', but in general it can include a DOS -path, and depending on your transfer mechanism may not resemble the -name on the Unix side. - - At this point, you can set any breakpoints you wish; when you are -ready to see your program run on the 29K board, use the GDB command -`run'. - - To stop debugging the remote program, use the GDB `detach' command. - - To return control of the PC to its console, use `tip' or `cu' once -again, after your GDB session has concluded, to attach to `EBMON'. You -can then type the command `q' to shut down `EBMON', returning control -to the DOS command-line interpreter. Type `CTTY con' to return command -input to the main DOS console, and type `~.' to leave `tip' or `cu'. - - -File: gdb.info, Node: Remote Log, Prev: gdb-EB29K, Up: EB29K Remote - -Remote log -.......... - - The `target amd-eb' command creates a file `eb.log' in the current -working directory, to help debug problems with the connection. -`eb.log' records all the output from `EBMON', including echoes of the -commands sent to it. Running `tail -f' on this file in another window -often helps to understand trouble with `EBMON', or unexpected events on -the PC side of the connection. - - -File: gdb.info, Node: ST2000 Remote, Next: Hitachi Remote, Prev: VxWorks Remote, Up: Remote - -GDB with a Tandem ST2000 ------------------------- - - To connect your ST2000 to the host system, see the manufacturer's -manual. Once the ST2000 is physically attached, you can run: - - target st2000 DEV SPEED - -to establish it as your debugging environment. DEV is normally the -name of a serial device, such as `/dev/ttya', connected to the ST2000 -via a serial line. You can instead specify DEV as a TCP connection -(for example, to a serial line attached via a terminal concentrator) -using the syntax `HOSTNAME:PORTNUMBER'. - - The `load' and `attach' commands are *not* defined for this target; -you must load your program into the ST2000 as you normally would for -standalone operation. GDB reads debugging information (such as -symbols) from a separate, debugging version of the program available on -your host computer. - - These auxiliary GDB commands are available to help you with the -ST2000 environment: - -`st2000 COMMAND' - Send a COMMAND to the STDBUG monitor. See the manufacturer's - manual for available commands. - -`connect' - Connect the controlling terminal to the STDBUG command monitor. - When you are done interacting with STDBUG, typing either of two - character sequences gets you back to the GDB command prompt: - `~.' (Return, followed by tilde and period) or `~' - (Return, followed by tilde and control-D). - - -File: gdb.info, Node: VxWorks Remote, Next: ST2000 Remote, Prev: EB29K Remote, Up: Remote - -GDB and VxWorks ---------------- - - GDB enables developers to spawn and debug tasks running on networked -VxWorks targets from a Unix host. Already-running tasks spawned from -the VxWorks shell can also be debugged. GDB uses code that runs on -both the Unix host and on the VxWorks target. The program `gdb' is -installed and executed on the Unix host. (It may be installed with the -name `vxgdb', to distinguish it from a GDB for debugging programs on -the host itself.) - -`VxWorks-timeout ARGS' - All VxWorks-based targets now support the option `vxworks-timeout'. - This option is set by the user, and ARGS represents the number of - seconds GDB waits for responses to rpc's. You might use this if - your VxWorks target is a slow software simulator or is on the far - side of a thin network line. - - The following information on connecting to VxWorks was current when -this manual was produced; newer releases of VxWorks may use revised -procedures. - - To use GDB with VxWorks, you must rebuild your VxWorks kernel to -include the remote debugging interface routines in the VxWorks library -`rdb.a'. To do this, define `INCLUDE_RDB' in the VxWorks configuration -file `configAll.h' and rebuild your VxWorks kernel. The resulting -kernel contains `rdb.a', and spawns the source debugging task -`tRdbTask' when VxWorks is booted. For more information on configuring -and remaking VxWorks, see the manufacturer's manual. - - Once you have included `rdb.a' in your VxWorks system image and set -your Unix execution search path to find GDB, you are ready to run GDB. -From your Unix host, run `gdb' (or `vxgdb', depending on your -installation). - - GDB comes up showing the prompt: - - (vxgdb) - -* Menu: - -* VxWorks Connection:: Connecting to VxWorks -* VxWorks Download:: VxWorks download -* VxWorks Attach:: Running tasks - - -File: gdb.info, Node: VxWorks Connection, Next: VxWorks Download, Up: VxWorks Remote - -Connecting to VxWorks -..................... - - The GDB command `target' lets you connect to a VxWorks target on the -network. To connect to a target whose host name is "`tt'", type: - - (vxgdb) target vxworks tt - - GDB displays messages like these: - - Attaching remote machine across net... - Connected to tt. - - GDB then attempts to read the symbol tables of any object modules -loaded into the VxWorks target since it was last booted. GDB locates -these files by searching the directories listed in the command search -path (*note Your program's environment: Environment.); if it fails to -find an object file, it displays a message such as: - - prog.o: No such file or directory. - - When this happens, add the appropriate directory to the search path -with the GDB command `path', and execute the `target' command again. - - -File: gdb.info, Node: VxWorks Download, Next: VxWorks Attach, Prev: VxWorks Connection, Up: VxWorks Remote - -VxWorks download -................ - - If you have connected to the VxWorks target and you want to debug an -object that has not yet been loaded, you can use the GDB `load' command -to download a file from Unix to VxWorks incrementally. The object file -given as an argument to the `load' command is actually opened twice: -first by the VxWorks target in order to download the code, then by GDB -in order to read the symbol table. This can lead to problems if the -current working directories on the two systems differ. If both systems -have NFS mounted the same filesystems, you can avoid these problems by -using absolute paths. Otherwise, it is simplest to set the working -directory on both systems to the directory in which the object file -resides, and then to reference the file by its name, without any path. -For instance, a program `prog.o' may reside in `VXPATH/vw/demo/rdb' in -VxWorks and in `HOSTPATH/vw/demo/rdb' on the host. To load this -program, type this on VxWorks: - - -> cd "VXPATH/vw/demo/rdb" - v Then, in GDB, type: - - (vxgdb) cd HOSTPATH/vw/demo/rdb - (vxgdb) load prog.o - - GDB displays a response similar to this: - - Reading symbol data from wherever/vw/demo/rdb/prog.o... done. - - You can also use the `load' command to reload an object module after -editing and recompiling the corresponding source file. Note that this -makes GDB delete all currently-defined breakpoints, auto-displays, and -convenience variables, and to clear the value history. (This is -necessary in order to preserve the integrity of debugger data -structures that reference the target system's symbol table.) - - -File: gdb.info, Node: VxWorks Attach, Prev: VxWorks Download, Up: VxWorks Remote - -Running tasks -............. - - You can also attach to an existing task using the `attach' command as -follows: - - (vxgdb) attach TASK - -where TASK is the VxWorks hexadecimal task ID. The task can be running -or suspended when you attach to it. Running tasks are suspended at the -time of attachment. - - -File: gdb.info, Node: Sparclet Remote, Next: Simulator, Prev: MIPS Remote, Up: Remote - -GDB and Sparclet ----------------- - - GDB enables developers to debug tasks running on Sparclet targets -from a Unix host. GDB uses code that runs on both the Unix host and on -the Sparclet target. The program `gdb' is installed and executed on -the Unix host. - -`timeout ARGS' - GDB now supports the option `remotetimeout'. This option is set - by the user, and ARGS represents the number of seconds GDB waits - for responses. - - When compiling for debugging, include the options "-g" to get debug -information and "-Ttext" to relocate the program to where you wish to -load it on the target. You may also want to add the options "-n" or -"-N" in order to reduce the size of the sections. - - sparclet-aout-gcc prog.c -Ttext 0x12010000 -g -o prog -N - - You can use objdump to verify that the addresses are what you -intended. - - sparclet-aout-objdump --headers --syms prog - - Once you have set your Unix execution search path to find GDB, you -are ready to run GDB. From your Unix host, run `gdb' (or -`sparclet-aout-gdb', depending on your installation). - - GDB comes up showing the prompt: - - (gdbslet) - -* Menu: - -* Sparclet File:: Setting the file to debug -* Sparclet Connection:: Connecting to Sparclet -* Sparclet Download:: Sparclet download -* Sparclet Execution:: Running and debugging - - -File: gdb.info, Node: Sparclet File, Next: Sparclet Connection, Up: Sparclet Remote - -Setting file to debug -..................... - - The GDB command `file' lets you choose with program to debug. - - (gdbslet) file prog - - GDB then attempts to read the symbol table of `prog'. GDB locates -the file by searching the directories listed in the command search path. -If the file was compiled with debug information (option "-g"), source -files will be searched as well. GDB locates the source files by -searching the directories listed in the directory search path (*note -Your program's environment: Environment.). If it fails to find a file, -it displays a message such as: - - prog: No such file or directory. - - When this happens, add the appropriate directories to the search -paths with the GDB commands `path' and `dir', and execute the `target' -command again. - - -File: gdb.info, Node: Sparclet Connection, Next: Sparclet Download, Prev: Sparclet File, Up: Sparclet Remote - -Connecting to Sparclet -...................... - - The GDB command `target' lets you connect to a Sparclet target. To -connect to a target on serial port "`ttya'", type: - - (gdbslet) target sparclet /dev/ttya - Remote target sparclet connected to /dev/ttya - main () at ../prog.c:3 - - GDB displays messages like these: - - Connected to ttya. - - -File: gdb.info, Node: Sparclet Download, Next: Sparclet Execution, Prev: Sparclet Connection, Up: Sparclet Remote - -Sparclet download -................. - - Once connected to the Sparclet target, you can use the GDB `load' -command to download the file from the host to the target. The file -name and load offset should be given as arguments to the `load' command. -Since the file format is aout, the program must be loaded to the -starting address. You can use objdump to find out what this value is. -The load offset is an offset which is added to the VMA (virtual memory -address) of each of the file's sections. For instance, if the program -`prog' was linked to text address 0x1201000, with data at 0x12010160 -and bss at 0x12010170, in GDB, type: - - (gdbslet) load prog 0x12010000 - Loading section .text, size 0xdb0 vma 0x12010000 - - If the code is loaded at a different address then what the program -was linked to, you may need to use the `section' and `add-symbol-file' -commands to tell GDB where to map the symbol table. - - -File: gdb.info, Node: Sparclet Execution, Prev: Sparclet Download, Up: Sparclet Remote - -Running and debugging -..................... - - You can now begin debugging the task using GDB's execution control -commands, `b', `step', `run', etc. See the GDB manual for the list of -commands. - - (gdbslet) b main - Breakpoint 1 at 0x12010000: file prog.c, line 3. - (gdbslet) run - Starting program: prog - Breakpoint 1, main (argc=1, argv=0xeffff21c) at prog.c:3 - 3 char *symarg = 0; - (gdbslet) step - 4 char *execarg = "hello!"; - (gdbslet) - diff --git a/gnu/dist/gdb/doc/gdb.info-7 b/gnu/dist/gdb/doc/gdb.info-7 deleted file mode 100644 index e623e060444c..000000000000 --- a/gnu/dist/gdb/doc/gdb.info-7 +++ /dev/null @@ -1,1314 +0,0 @@ -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 Fifth Edition, April 1998, of `Debugging with GDB: the -GNU Source-Level Debugger' for GDB Version . - - Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, -1997, 1998 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: Hitachi Remote, Next: MIPS Remote, Prev: ST2000 Remote, Up: Remote - -GDB and Hitachi microprocessors -------------------------------- - - GDB needs to know these things to talk to your Hitachi SH, H8/300, -or H8/500: - - 1. that you want to use `target hms', the remote debugging interface - for Hitachi microprocessors, or `target e7000', the in-circuit - emulator for the Hitachi SH and the Hitachi 300H. (`target hms' is - the default when GDB is configured specifically for the Hitachi SH, - H8/300, or H8/500.) - - 2. what serial device connects your host to your Hitachi board (the - first serial device available on your host is the default). - - 3. what speed to use over the serial device. - -* Menu: - -* Hitachi Boards:: Connecting to Hitachi boards. -* Hitachi ICE:: Using the E7000 In-Circuit Emulator. -* Hitachi Special:: Special GDB commands for Hitachi micros. - - -File: gdb.info, Node: Hitachi Boards, Next: Hitachi ICE, Up: Hitachi Remote - -Connecting to Hitachi boards -............................ - - Use the special `gdb' command `device PORT' if you need to -explicitly set the serial device. The default PORT is the first -available port on your host. This is only necessary on Unix hosts, -where it is typically something like `/dev/ttya'. - - `gdb' has another special command to set the communications speed: -`speed BPS'. This command also is only used from Unix hosts; on DOS -hosts, set the line speed as usual from outside GDB with the DOS `mode' -command (for instance, `mode com2:9600,n,8,1,p' for a 9600 bps -connection). - - The `device' and `speed' commands are available only when you use a -Unix host to debug your Hitachi microprocessor programs. If you use a -DOS host, GDB depends on an auxiliary terminate-and-stay-resident -program called `asynctsr' to communicate with the development board -through a PC serial port. You must also use the DOS `mode' command to -set up the serial port on the DOS side. - - -File: gdb.info, Node: Hitachi ICE, Next: Hitachi Special, Prev: Hitachi Boards, Up: Hitachi Remote - -Using the E7000 in-circuit emulator -................................... - - You can use the E7000 in-circuit emulator to develop code for either -the Hitachi SH or the H8/300H. Use one of these forms of the `target -e7000' command to connect GDB to your E7000: - -`target e7000 PORT SPEED' - Use this form if your E7000 is connected to a serial port. The - PORT argument identifies what serial port to use (for example, - `com2'). The third argument is the line speed in bits per second - (for example, `9600'). - -`target e7000 HOSTNAME' - If your E7000 is installed as a host on a TCP/IP network, you can - just specify its hostname; GDB uses `telnet' to connect. - - -File: gdb.info, Node: Hitachi Special, Prev: Hitachi ICE, Up: Hitachi Remote - -Special GDB commands for Hitachi micros -....................................... - - Some GDB commands are available only on the H8/300 or the H8/500 -configurations: - -`set machine h8300' -`set machine h8300h' - Condition GDB for one of the two variants of the H8/300 - architecture with `set machine'. You can use `show machine' to - check which variant is currently in effect. - -`set memory MOD' -`show memory' - Specify which H8/500 memory model (MOD) you are using with `set - memory'; check which memory model is in effect with `show memory'. - The accepted values for MOD are `small', `big', `medium', and - `compact'. - - -File: gdb.info, Node: MIPS Remote, Next: Sparclet Remote, Prev: Hitachi Remote, Up: Remote - -GDB and remote MIPS boards --------------------------- - - GDB can use the MIPS remote debugging protocol to talk to a MIPS -board attached to a serial line. This is available when you configure -GDB with `--target=mips-idt-ecoff'. - - Use these GDB commands to specify the connection to your target -board: - -`target mips PORT' - To run a program on the board, start up `gdb' with the name of - your program as the argument. To connect to the board, use the - command `target mips PORT', where PORT is the name of the serial - port connected to the board. If the program has not already been - downloaded to the board, you may use the `load' command to - download it. You can then use all the usual GDB commands. - - For example, this sequence connects to the target board through a - serial port, and loads and runs a program called PROG through the - debugger: - - host$ gdb PROG - GDB is free software and ... - (gdb) target mips /dev/ttyb - (gdb) load PROG - (gdb) run - -`target mips HOSTNAME:PORTNUMBER' - On some GDB host configurations, you can specify a TCP connection - (for instance, to a serial line managed by a terminal - concentrator) instead of a serial port, using the syntax - `HOSTNAME:PORTNUMBER'. - -`target pmon PORT' - -`target ddb PORT' - -`target lsi PORT' -GDB also supports these special commands for MIPS targets: - -`set processor ARGS' -`show processor' - Use the `set processor' command to set the type of MIPS processor - when you want to access processor-type-specific registers. For - example, `set processor R3041' tells GDB to use the CPO registers - appropriate for the 3041 chip. Use the `show processor' command - to see what MIPS processor GDB is using. Use the `info reg' - command to see what registers GDB is using. - -`set mipsfpu double' -`set mipsfpu single' -`set mipsfpu none' -`show mipsfpu' - If your target board does not support the MIPS floating point - coprocessor, you should use the command `set mipsfpu none' (if you - need this, you may wish to put the command in your .gdbinit file). - This tells GDB how to find the return value of functions which - return floating point values. It also allows GDB to avoid saving - the floating point registers when calling functions on the board. - If you are using a floating point coprocessor with only single - precision floating point support, as on the R4650 processor, use - the command `set mipsfpu single'. The default double precision - floating point coprocessor may be selected using `set mipsfpu - double'. - - In previous versions the only choices were double precision or no - floating point, so `set mipsfpu on' will select double precision - and `set mipsfpu off' will select no floating point. - - As usual, you can inquire about the `mipsfpu' variable with `show - mipsfpu'. - -`set remotedebug N' -`show remotedebug' - You can see some debugging information about communications with - the board by setting the `remotedebug' variable. If you set it to - `1' using `set remotedebug 1', every packet is displayed. If you - set it to `2', every character is displayed. You can check the - current value at any time with the command `show remotedebug'. - -`set timeout SECONDS' -`set retransmit-timeout SECONDS' -`show timeout' -`show retransmit-timeout' - You can control the timeout used while waiting for a packet, in - the MIPS remote protocol, with the `set timeout SECONDS' command. - The default is 5 seconds. Similarly, you can control the timeout - used while waiting for an acknowledgement of a packet with the `set - retransmit-timeout SECONDS' command. The default is 3 seconds. - You can inspect both values with `show timeout' and `show - retransmit-timeout'. (These commands are *only* available when - GDB is configured for `--target=mips-idt-ecoff'.) - - The timeout set by `set timeout' does not apply when GDB is - waiting for your program to stop. In that case, GDB waits forever - because it has no way of knowing how long the program is going to - run before stopping. - - -File: gdb.info, Node: Simulator, Prev: Sparclet Remote, Up: Remote - -Simulated CPU target --------------------- - - For some configurations, GDB includes a CPU simulator that you can -use instead of a hardware CPU to debug your programs. Currently, a -simulator is available when GDB is configured to debug Zilog Z8000 or -Hitachi microprocessor targets. - - For the Z8000 family, `target sim' simulates either the Z8002 (the -unsegmented variant of the Z8000 architecture) or the Z8001 (the -segmented variant). The simulator recognizes which architecture is -appropriate by inspecting the object code. - -`target sim' - Debug programs on a simulated CPU (which CPU depends on the GDB - configuration) - -After specifying this target, you can debug programs for the simulated -CPU in the same style as programs for your host computer; use the -`file' command to load a new program image, the `run' command to run -your program, and so on. - - As well as making available all the usual machine registers (see -`info reg'), this debugging target provides three additional items of -information as specially named registers: - -`cycles' - Counts clock-ticks in the simulator. - -`insts' - Counts instructions run in the simulator. - -`time' - Execution time in 60ths of a second. - - You can refer to these values in GDB expressions with the usual -conventions; for example, `b fputc if $cycles>5000' sets a conditional -breakpoint that suspends only after at least 5000 simulated clock ticks. - - -File: gdb.info, Node: Controlling GDB, Next: Sequences, Prev: Targets, Up: Top - -Controlling GDB -*************** - - You can alter the way GDB interacts with you by using the `set' -command. For commands controlling how GDB displays data, *note Print -settings: Print Settings.; other settings are described here. - -* Menu: - -* Prompt:: Prompt -* Editing:: Command editing -* History:: Command history -* Screen Size:: Screen size -* Numbers:: Numbers -* Messages/Warnings:: Optional warnings and messages - - -File: gdb.info, Node: Prompt, Next: Editing, Up: Controlling GDB - -Prompt -====== - - GDB indicates its readiness to read a command by printing a string -called the "prompt". This string is normally `(gdb)'. You can change -the prompt string with the `set prompt' command. For instance, when -debugging GDB with GDB, it is useful to change the prompt in one of the -GDB sessions so that you can always tell which one you are talking to. - - *Note:* `set prompt' no longer adds a space for you after the -prompt you set. This allows you to set a prompt which ends in a space -or a prompt that does not. - -`set prompt NEWPROMPT' - Directs GDB to use NEWPROMPT as its prompt string henceforth. - -`show prompt' - Prints a line of the form: `Gdb's prompt is: YOUR-PROMPT' - - -File: gdb.info, Node: Editing, Next: History, Prev: Prompt, Up: Controlling GDB - -Command editing -=============== - - GDB reads its input commands via the "readline" interface. This GNU -library provides consistent behavior for programs which provide a -command line interface to the user. Advantages are GNU Emacs-style or -"vi"-style inline editing of commands, `csh'-like history substitution, -and a storage and recall of command history across debugging sessions. - - You may control the behavior of command line editing in GDB with the -command `set'. - -`set editing' -`set editing on' - Enable command line editing (enabled by default). - -`set editing off' - Disable command line editing. - -`show editing' - Show whether command line editing is enabled. - - -File: gdb.info, Node: History, Next: Screen Size, Prev: Editing, Up: Controlling GDB - -Command history -=============== - - GDB can keep track of the commands you type during your debugging -sessions, so that you can be certain of precisely what happened. Use -these commands to manage the GDB command history facility. - -`set history filename FNAME' - Set the name of the GDB command history file to FNAME. This is - the file where GDB reads an initial command history list, and - where it writes the command history from this session when it - exits. You can access this list through history expansion or - through the history command editing characters listed below. This - file defaults to the value of the environment variable - `GDBHISTFILE', or to `./.gdb_history' if this variable is not set. - -`set history save' -`set history save on' - Record command history in a file, whose name may be specified with - the `set history filename' command. By default, this option is - disabled. - -`set history save off' - Stop recording command history in a file. - -`set history size SIZE' - Set the number of commands which GDB keeps in its history list. - This defaults to the value of the environment variable `HISTSIZE', - or to 256 if this variable is not set. - - History expansion assigns special meaning to the character `!'. - - Since `!' is also the logical not operator in C, history expansion -is off by default. If you decide to enable history expansion with the -`set history expansion on' command, you may sometimes need to follow -`!' (when it is used as logical not, in an expression) with a space or -a tab to prevent it from being expanded. The readline history -facilities do not attempt substitution on the strings `!=' and `!(', -even when history expansion is enabled. - - The commands to control history expansion are: - -`set history expansion on' -`set history expansion' - Enable history expansion. History expansion is off by default. - -`set history expansion off' - Disable history expansion. - - The readline code comes with more complete documentation of - editing and history expansion features. Users unfamiliar with GNU - Emacs or `vi' may wish to read it. - -`show history' -`show history filename' -`show history save' -`show history size' -`show history expansion' - These commands display the state of the GDB history parameters. - `show history' by itself displays all four states. - -`show commands' - Display the last ten commands in the command history. - -`show commands N' - Print ten commands centered on command number N. - -`show commands +' - Print ten commands just after the commands last printed. - - -File: gdb.info, Node: Screen Size, Next: Numbers, Prev: History, Up: Controlling GDB - -Screen size -=========== - - Certain commands to GDB may produce large amounts of information -output to the screen. To help you read all of it, GDB pauses and asks -you for input at the end of each page of output. Type when you -want to continue the output, or `q' to discard the remaining output. -Also, the screen width setting determines when to wrap lines of output. -Depending on what is being printed, GDB tries to break the line at a -readable place, rather than simply letting it overflow onto the -following line. - - Normally GDB knows the size of the screen from the termcap data base -together with the value of the `TERM' environment variable and the -`stty rows' and `stty cols' settings. If this is not correct, you can -override it with the `set height' and `set width' commands: - -`set height LPP' -`show height' -`set width CPL' -`show width' - These `set' commands specify a screen height of LPP lines and a - screen width of CPL characters. The associated `show' commands - display the current settings. - - If you specify a height of zero lines, GDB does not pause during - output no matter how long the output is. This is useful if output - is to a file or to an editor buffer. - - Likewise, you can specify `set width 0' to prevent GDB from - wrapping its output. - - -File: gdb.info, Node: Numbers, Next: Messages/Warnings, Prev: Screen Size, Up: Controlling GDB - -Numbers -======= - - You can always enter numbers in octal, decimal, or hexadecimal in -GDB by the usual conventions: octal numbers begin with `0', decimal -numbers end with `.', and hexadecimal numbers begin with `0x'. Numbers -that begin with none of these are, by default, entered in base 10; -likewise, the default display for numbers--when no particular format is -specified--is base 10. You can change the default base for both input -and output with the `set radix' command. - -`set input-radix BASE' - Set the default base for numeric input. Supported choices for - BASE are decimal 8, 10, or 16. BASE must itself be specified - either unambiguously or using the current default radix; for - example, any of - - set radix 012 - set radix 10. - set radix 0xa - - sets the base to decimal. On the other hand, `set radix 10' - leaves the radix unchanged no matter what it was. - -`set output-radix BASE' - Set the default base for numeric display. Supported choices for - BASE are decimal 8, 10, or 16. BASE must itself be specified - either unambiguously or using the current default radix. - -`show input-radix' - Display the current default base for numeric input. - -`show output-radix' - Display the current default base for numeric display. - - -File: gdb.info, Node: Messages/Warnings, Prev: Numbers, Up: Controlling GDB - -Optional warnings and messages -============================== - - By default, GDB is silent about its inner workings. If you are -running on a slow machine, you may want to use the `set verbose' -command. This makes GDB tell you when it does a lengthy internal -operation, so you will not think it has crashed. - - Currently, the messages controlled by `set verbose' are those which -announce that the symbol table for a source file is being read; see -`symbol-file' in *Note Commands to specify files: Files. - -`set verbose on' - Enables GDB output of certain informational messages. - -`set verbose off' - Disables GDB output of certain informational messages. - -`show verbose' - Displays whether `set verbose' is on or off. - - By default, if GDB encounters bugs in the symbol table of an object -file, it is silent; but if you are debugging a compiler, you may find -this information useful (*note Errors reading symbol files: Symbol -Errors.). - -`set complaints LIMIT' - Permits GDB to output LIMIT complaints about each type of unusual - symbols before becoming silent about the problem. Set LIMIT to - zero to suppress all complaints; set it to a large number to - prevent complaints from being suppressed. - -`show complaints' - Displays how many symbol complaints GDB is permitted to produce. - - By default, GDB is cautious, and asks what sometimes seems to be a -lot of stupid questions to confirm certain commands. For example, if -you try to run a program which is already running: - - (gdb) run - The program being debugged has been started already. - Start it from the beginning? (y or n) - - If you are willing to unflinchingly face the consequences of your own -commands, you can disable this "feature": - -`set confirm off' - Disables confirmation requests. - -`set confirm on' - Enables confirmation requests (the default). - -`show confirm' - Displays state of confirmation requests. - - -File: gdb.info, Node: Sequences, Next: Emacs, Prev: Controlling GDB, Up: Top - -Canned Sequences of Commands -**************************** - - Aside from breakpoint commands (*note Breakpoint command lists: -Break Commands.), GDB provides two ways to store sequences of commands -for execution as a unit: user-defined commands and command files. - -* Menu: - -* Define:: User-defined commands -* Hooks:: User-defined command hooks -* Command Files:: Command files -* Output:: Commands for controlled output - - -File: gdb.info, Node: Define, Next: Hooks, Up: Sequences - -User-defined commands -===================== - - A "user-defined command" is a sequence of GDB commands to which you -assign a new name as a command. This is done with the `define' -command. User commands may accept up to 10 arguments separated by -whitespace. Arguments are accessed within the user command via -$ARG0...$ARG9. A trivial example: - - define adder - print $arg0 + $arg1 + $arg2 - -To execute the command use: - - adder 1 2 3 - -This defines the command `adder', which prints the sum of its three -arguments. Note the arguments are text substitutions, so they may -reference variables, use complex expressions, or even perform inferior -functions calls. - -`define COMMANDNAME' - Define a command named COMMANDNAME. If there is already a command - by that name, you are asked to confirm that you want to redefine - it. - - The definition of the command is made up of other GDB command - lines, which are given following the `define' command. The end of - these commands is marked by a line containing `end'. - -`if' - Takes a single argument, which is an expression to evaluate. It - is followed by a series of commands that are executed only if the - expression is true (nonzero). There can then optionally be a line - `else', followed by a series of commands that are only executed if - the expression was false. The end of the list is marked by a line - containing `end'. - -`while' - The syntax is similar to `if': the command takes a single argument, - which is an expression to evaluate, and must be followed by the - commands to execute, one per line, terminated by an `end'. The - commands are executed repeatedly as long as the expression - evaluates to true. - -`document COMMANDNAME' - Document the user-defined command COMMANDNAME, so that it can be - accessed by `help'. The command COMMANDNAME must already be - defined. This command reads lines of documentation just as - `define' reads the lines of the command definition, ending with - `end'. After the `document' command is finished, `help' on command - COMMANDNAME displays the documentation you have written. - - You may use the `document' command again to change the - documentation of a command. Redefining the command with `define' - does not change the documentation. - -`help user-defined' - List all user-defined commands, with the first line of the - documentation (if any) for each. - -`show user' -`show user COMMANDNAME' - Display the GDB commands used to define COMMANDNAME (but not its - documentation). If no COMMANDNAME is given, display the - definitions for all user-defined commands. - - When user-defined commands are executed, the commands of the -definition are not printed. An error in any command stops execution of -the user-defined command. - - If used interactively, commands that would ask for confirmation -proceed without asking when used inside a user-defined command. Many -GDB commands that normally print messages to say what they are doing -omit the messages when used in a user-defined command. - - -File: gdb.info, Node: Hooks, Next: Command Files, Prev: Define, Up: Sequences - -User-defined command hooks -========================== - - You may define *hooks*, which are a special kind of user-defined -command. Whenever you run the command `foo', if the user-defined -command `hook-foo' exists, it is executed (with no arguments) before -that command. - - In addition, a pseudo-command, `stop' exists. Defining -(`hook-stop') makes the associated commands execute every time -execution stops in your program: before breakpoint commands are run, -displays are printed, or the stack frame is printed. - - For example, to ignore `SIGALRM' signals while single-stepping, but -treat them normally during normal execution, you could define: - - define hook-stop - handle SIGALRM nopass - end - - define hook-run - handle SIGALRM pass - end - - define hook-continue - handle SIGLARM pass - end - - You can define a hook for any single-word command in GDB, but not -for command aliases; you should define a hook for the basic command -name, e.g. `backtrace' rather than `bt'. If an error occurs during -the execution of your hook, execution of GDB commands stops and GDB -issues a prompt (before the command that you actually typed had a -chance to run). - - If you try to define a hook which does not match any known command, -you get a warning from the `define' command. - - -File: gdb.info, Node: Command Files, Next: Output, Prev: Hooks, Up: Sequences - -Command files -============= - - A command file for GDB is a file of lines that are GDB commands. -Comments (lines starting with `#') may also be included. An empty line -in a command file does nothing; it does not mean to repeat the last -command, as it would from the terminal. - - When you start GDB, it automatically executes commands from its -"init files". These are files named `.gdbinit'. GDB reads the init -file (if any) in your home directory, then processes command line -options and operands, and then reads the init file (if any) in the -current working directory. This is so the init file in your home -directory can set options (such as `set complaints') which affect the -processing of the command line options and operands. The init files -are not executed if you use the `-nx' option; *note Choosing modes: -Mode Options.. - - On some configurations of GDB, the init file is known by a different -name (these are typically environments where a specialized form of GDB -may need to coexist with other forms, hence a different name for the -specialized version's init file). These are the environments with -special init file names: - - * VxWorks (Wind River Systems real-time OS): `.vxgdbinit' - - * OS68K (Enea Data Systems real-time OS): `.os68gdbinit' - - * ES-1800 (Ericsson Telecom AB M68000 emulator): `.esgdbinit' - - You can also request the execution of a command file with the -`source' command: - -`source FILENAME' - Execute the command file FILENAME. - - The lines in a command file are executed sequentially. They are not -printed as they are executed. An error in any command terminates -execution of the command file. - - Commands that would ask for confirmation if used interactively -proceed without asking when used in a command file. Many GDB commands -that normally print messages to say what they are doing omit the -messages when called from command files. - - -File: gdb.info, Node: Output, Prev: Command Files, Up: Sequences - -Commands for controlled output -============================== - - During the execution of a command file or a user-defined command, -normal GDB output is suppressed; the only output that appears is what is -explicitly printed by the commands in the definition. This section -describes three commands useful for generating exactly the output you -want. - -`echo TEXT' - Print TEXT. Nonprinting characters can be included in TEXT using - C escape sequences, such as `\n' to print a newline. *No newline - is printed unless you specify one.* In addition to the standard C - escape sequences, a backslash followed by a space stands for a - space. This is useful for displaying a string with spaces at the - beginning or the end, since leading and trailing spaces are - otherwise trimmed from all arguments. To print ` and foo = ', use - the command `echo \ and foo = \ '. - - A backslash at the end of TEXT can be used, as in C, to continue - the command onto subsequent lines. For example, - - echo This is some text\n\ - which is continued\n\ - onto several lines.\n - - produces the same output as - - echo This is some text\n - echo which is continued\n - echo onto several lines.\n - -`output EXPRESSION' - Print the value of EXPRESSION and nothing but that value: no - newlines, no `$NN = '. The value is not entered in the value - history either. *Note Expressions: Expressions, for more - information on expressions. - -`output/FMT EXPRESSION' - Print the value of EXPRESSION in format FMT. You can use the same - formats as for `print'. *Note Output formats: Output Formats, for - more information. - -`printf STRING, EXPRESSIONS...' - Print the values of the EXPRESSIONS under the control of STRING. - The EXPRESSIONS are separated by commas and may be either numbers - or pointers. Their values are printed as specified by STRING, - exactly as if your program were to execute the C subroutine - - printf (STRING, EXPRESSIONS...); - - For example, you can print two values in hex like this: - - printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo - - The only backslash-escape sequences that you can use in the format - string are the simple ones that consist of backslash followed by a - letter. - - -File: gdb.info, Node: Emacs, Next: GDB Bugs, Prev: Sequences, Up: Top - -Using GDB under GNU Emacs -************************* - - A special interface allows you to use GNU Emacs to view (and edit) -the source files for the program you are debugging with GDB. - - To use this interface, use the command `M-x gdb' in Emacs. Give the -executable file you want to debug as an argument. This command starts -GDB as a subprocess of Emacs, with input and output through a newly -created Emacs buffer. - - Using GDB under Emacs is just like using GDB normally except for two -things: - - * All "terminal" input and output goes through the Emacs buffer. - - This applies both to GDB commands and their output, and to the input -and output done by the program you are debugging. - - This is useful because it means that you can copy the text of -previous commands and input them again; you can even use parts of the -output in this way. - - All the facilities of Emacs' Shell mode are available for interacting -with your program. In particular, you can send signals the usual -way--for example, `C-c C-c' for an interrupt, `C-c C-z' for a stop. - - * GDB displays source code through Emacs. - - Each time GDB displays a stack frame, Emacs automatically finds the -source file for that frame and puts an arrow (`=>') at the left margin -of the current line. Emacs uses a separate buffer for source display, -and splits the screen to show both your GDB session and the source. - - Explicit GDB `list' or search commands still produce output as -usual, but you probably have no reason to use them from Emacs. - - *Warning:* If the directory where your program resides is not your - current directory, it can be easy to confuse Emacs about the - location of the source files, in which case the auxiliary display - buffer does not appear to show your source. GDB can find programs - by searching your environment's `PATH' variable, so the GDB input - and output session proceeds normally; but Emacs does not get - enough information back from GDB to locate the source files in - this situation. To avoid this problem, either start GDB mode from - the directory where your program resides, or specify an absolute - file name when prompted for the `M-x gdb' argument. - - A similar confusion can result if you use the GDB `file' command to - switch to debugging a program in some other location, from an - existing GDB buffer in Emacs. - - By default, `M-x gdb' calls the program called `gdb'. If you need -to call GDB by a different name (for example, if you keep several -configurations around, with different names) you can set the Emacs -variable `gdb-command-name'; for example, - - (setq gdb-command-name "mygdb") - -(preceded by `ESC ESC', or typed in the `*scratch*' buffer, or in your -`.emacs' file) makes Emacs call the program named "`mygdb'" instead. - - In the GDB I/O buffer, you can use these special Emacs commands in -addition to the standard Shell mode commands: - -`C-h m' - Describe the features of Emacs' GDB Mode. - -`M-s' - Execute to another source line, like the GDB `step' command; also - update the display window to show the current file and location. - -`M-n' - Execute to next source line in this function, skipping all function - calls, like the GDB `next' command. Then update the display window - to show the current file and location. - -`M-i' - Execute one instruction, like the GDB `stepi' command; update - display window accordingly. - -`M-x gdb-nexti' - Execute to next instruction, using the GDB `nexti' command; update - display window accordingly. - -`C-c C-f' - Execute until exit from the selected stack frame, like the GDB - `finish' command. - -`M-c' - Continue execution of your program, like the GDB `continue' - command. - - *Warning:* In Emacs v19, this command is `C-c C-p'. - -`M-u' - Go up the number of frames indicated by the numeric argument - (*note Numeric Arguments: (Emacs)Arguments.), like the GDB `up' - command. - - *Warning:* In Emacs v19, this command is `C-c C-u'. - -`M-d' - Go down the number of frames indicated by the numeric argument, - like the GDB `down' command. - - *Warning:* In Emacs v19, this command is `C-c C-d'. - -`C-x &' - Read the number where the cursor is positioned, and insert it at - the end of the GDB I/O buffer. For example, if you wish to - disassemble code around an address that was displayed earlier, - type `disassemble'; then move the cursor to the address display, - and pick up the argument for `disassemble' by typing `C-x &'. - - You can customize this further by defining elements of the list - `gdb-print-command'; once it is defined, you can format or - otherwise process numbers picked up by `C-x &' before they are - inserted. A numeric argument to `C-x &' indicates that you wish - special formatting, and also acts as an index to pick an element - of the list. If the list element is a string, the number to be - inserted is formatted using the Emacs function `format'; otherwise - the number is passed as an argument to the corresponding list - element. - - In any source file, the Emacs command `C-x SPC' (`gdb-break') tells -GDB to set a breakpoint on the source line point is on. - - If you accidentally delete the source-display buffer, an easy way to -get it back is to type the command `f' in the GDB buffer, to request a -frame display; when you run under Emacs, this recreates the source -buffer if necessary to show you the context of the current frame. - - The source files displayed in Emacs are in ordinary Emacs buffers -which are visiting the source files in the usual way. You can edit the -files with these buffers if you wish; but keep in mind that GDB -communicates with Emacs in terms of line numbers. If you add or delete -lines from the text, the line numbers that GDB knows cease to -correspond properly with the code. - - -File: gdb.info, Node: GDB Bugs, Next: Command Line Editing, Prev: Emacs, Up: Top - -Reporting Bugs in GDB -********************* - - Your bug reports play an essential role in making GDB reliable. - - Reporting a bug may help you by bringing a solution to your problem, -or it may not. But in any case the principal function of a bug report -is to help the entire community by making the next version of GDB work -better. Bug reports are your contribution to the maintenance of GDB. - - In order for a bug report to serve its purpose, you must include the -information that enables us to fix the bug. - -* Menu: - -* Bug Criteria:: Have you found a bug? -* Bug Reporting:: How to report bugs - - -File: gdb.info, Node: Bug Criteria, Next: Bug Reporting, Up: GDB Bugs - -Have you found a bug? -===================== - - If you are not sure whether you have found a bug, here are some -guidelines: - - * If the debugger gets a fatal signal, for any input whatever, that - is a GDB bug. Reliable debuggers never crash. - - * If GDB produces an error message for valid input, that is a bug. - - * If GDB does not produce an error message for invalid input, that - is a bug. However, you should note that your idea of "invalid - input" might be our idea of "an extension" or "support for - traditional practice". - - * If you are an experienced user of debugging tools, your suggestions - for improvement of GDB are welcome in any case. - - -File: gdb.info, Node: Bug Reporting, Prev: Bug Criteria, Up: GDB Bugs - -How to report bugs -================== - - A number of companies and individuals offer support for GNU products. -If you obtained GDB from a support organization, we recommend you -contact that organization first. - - You can find contact information for many support companies and -individuals in the file `etc/SERVICE' in the GNU Emacs distribution. - - In any event, we also recommend that you send bug reports for GDB to -one of these addresses: - - bug-gdb@prep.ai.mit.edu - {ucbvax|mit-eddie|uunet}!prep.ai.mit.edu!bug-gdb - - *Do not send bug reports to `info-gdb', or to `help-gdb', or to any -newsgroups.* Most users of GDB do not want to receive bug reports. -Those that do have arranged to receive `bug-gdb'. - - The mailing list `bug-gdb' has a newsgroup `gnu.gdb.bug' which -serves as a repeater. The mailing list and the newsgroup carry exactly -the same messages. Often people think of posting bug reports to the -newsgroup instead of mailing them. This appears to work, but it has one -problem which can be crucial: a newsgroup posting often lacks a mail -path back to the sender. Thus, if we need to ask for more information, -we may be unable to reach you. For this reason, it is better to send -bug reports to the mailing list. - - As a last resort, send bug reports on paper to: - - GNU Debugger Bugs - Free Software Foundation Inc. - 59 Temple Place - Suite 330 - Boston, MA 02111-1307 - USA - - The fundamental principle of reporting bugs usefully is this: -*report all the facts*. If you are not sure whether to state a fact or -leave it out, state it! - - Often people omit facts because they think they know what causes the -problem and assume that some details do not matter. Thus, you might -assume that the name of the variable you use in an example does not -matter. Well, probably it does not, but one cannot be sure. Perhaps -the bug is a stray memory reference which happens to fetch from the -location where that name is stored in memory; perhaps, if the name were -different, the contents of that location would fool the debugger into -doing the right thing despite the bug. Play it safe and give a -specific, complete example. That is the easiest thing for you to do, -and the most helpful. - - Keep in mind that the purpose of a bug report is to enable us to fix -the bug if it is new to us. Therefore, always write your bug reports on -the assumption that the bug has not been reported previously. - - Sometimes people give a few sketchy facts and ask, "Does this ring a -bell?" Those bug reports are useless, and we urge everyone to *refuse -to respond to them* except to chide the sender to report bugs properly. - - To enable us to fix the bug, you should include all these things: - - * The version of GDB. GDB announces it if you start with no - arguments; you can also print it at any time using `show version'. - - Without this, we will not know whether there is any point in - looking for the bug in the current version of GDB. - - * The type of machine you are using, and the operating system name - and version number. - - * What compiler (and its version) was used to compile GDB--e.g. - "gcc-2.0". - - * What compiler (and its version) was used to compile the program you - are debugging--e.g. "gcc-2.0". - - * The command arguments you gave the compiler to compile your - example and observe the bug. For example, did you use `-O'? To - guarantee you will not omit something important, list them all. A - copy of the Makefile (or the output from make) is sufficient. - - If we were to try to guess the arguments, we would probably guess - wrong and then we might not encounter the bug. - - * A complete input script, and all necessary source files, that will - reproduce the bug. - - * A description of what behavior you observe that you believe is - incorrect. For example, "It gets a fatal signal." - - Of course, if the bug is that GDB gets a fatal signal, then we will - certainly notice it. But if the bug is incorrect output, we might - not notice unless it is glaringly wrong. You might as well not - give us a chance to make a mistake. - - Even if the problem you experience is a fatal signal, you should - still say so explicitly. Suppose something strange is going on, - such as, your copy of GDB is out of synch, or you have encountered - a bug in the C library on your system. (This has happened!) Your - copy might crash and ours would not. If you told us to expect a - crash, then when ours fails to crash, we would know that the bug - was not happening for us. If you had not told us to expect a - crash, then we would not be able to draw any conclusion from our - observations. - - * If you wish to suggest changes to the GDB source, send us context - diffs. If you even discuss something in the GDB source, refer to - it by context, not by line number. - - The line numbers in our development sources will not match those - in your sources. Your line numbers would convey no useful - information to us. - - Here are some things that are not necessary: - - * A description of the envelope of the bug. - - Often people who encounter a bug spend a lot of time investigating - which changes to the input file will make the bug go away and which - changes will not affect it. - - This is often time consuming and not very useful, because the way - we will find the bug is by running a single example under the - debugger with breakpoints, not by pure deduction from a series of - examples. We recommend that you save your time for something else. - - Of course, if you can find a simpler example to report *instead* - of the original one, that is a convenience for us. Errors in the - output will be easier to spot, running under the debugger will take - less time, and so on. - - However, simplification is not vital; if you do not want to do - this, report the bug anyway and send us the entire test case you - used. - - * A patch for the bug. - - A patch for the bug does help us if it is a good one. But do not - omit the necessary information, such as the test case, on the - assumption that a patch is all we need. We might see problems - with your patch and decide to fix the problem another way, or we - might not understand it at all. - - Sometimes with a program as complicated as GDB it is very hard to - construct an example that will make the program follow a certain - path through the code. If you do not send us the example, we will - not be able to construct one, so we will not be able to verify - that the bug is fixed. - - And if we cannot understand what bug you are trying to fix, or why - your patch should be an improvement, we will not install it. A - test case will help us to understand. - - * A guess about what the bug is or what it depends on. - - Such guesses are usually wrong. Even we cannot guess right about - such things without first using the debugger to find the facts. - - -File: gdb.info, Node: Command Line Editing, Next: Using History Interactively, Prev: GDB Bugs, Up: Top - -Command Line Editing -******************** - - This text describes GNU's command line editing interface. - -* Menu: - -* Introduction and Notation:: Notation used in this text. -* Readline Interaction:: The minimum set of commands for editing a line. -* Readline Init File:: Customizing Readline from a user's view. - - -File: gdb.info, Node: Introduction and Notation, Next: Readline Interaction, Up: Command Line Editing - -Introduction to Line Editing -============================ - - The following paragraphs describe the notation we use to represent -keystrokes. - - The text is read as `Control-K' and describes the character -produced when the Control key is depressed and the key is struck. - - The text is read as `Meta-K' and describes the character -produced when the meta key (if you have one) is depressed, and the -key is struck. If you do not have a meta key, the identical keystroke -can be generated by typing first, and then typing . Either -process is known as "metafying" the key. - - The text is read as `Meta-Control-k' and describes the -character produced by "metafying" . - - In addition, several keys have their own names. Specifically, -, , , , , and all stand for themselves -when seen in this text, or in an init file (*note Readline Init -File::., for more info). - - -File: gdb.info, Node: Readline Interaction, Next: Readline Init File, Prev: Introduction and Notation, Up: Command Line Editing - -Readline Interaction -==================== - - Often during an interactive session you type in a long line of text, -only to notice that the first word on the line is misspelled. The -Readline library gives you a set of commands for manipulating the text -as you type it in, allowing you to just fix your typo, and not forcing -you to retype the majority of the line. Using these editing commands, -you move the cursor to the place that needs correction, and delete or -insert the text of the corrections. Then, when you are satisfied with -the line, you simply press . You do not have to be at the end of -the line to press ; the entire line is accepted regardless of the -location of the cursor within the line. - -* Menu: - -* Readline Bare Essentials:: The least you need to know about Readline. -* Readline Movement Commands:: Moving about the input line. -* Readline Killing Commands:: How to delete text, and how to get it back! -* Readline Arguments:: Giving numeric arguments to commands. - - -File: gdb.info, Node: Readline Bare Essentials, Next: Readline Movement Commands, Up: Readline Interaction - -Readline Bare Essentials ------------------------- - - In order to enter characters into the line, simply type them. The -typed character appears where the cursor was, and then the cursor moves -one space to the right. If you mistype a character, you can use -to back up, and delete the mistyped character. - - Sometimes you may miss typing a character that you wanted to type, -and not notice your error until you have typed several other -characters. In that case, you can type to move the cursor to the -left, and then correct your mistake. Aftwerwards, you can move the -cursor to the right with . - - When you add text in the middle of a line, you will notice that -characters to the right of the cursor get `pushed over' to make room -for the text that you have inserted. Likewise, when you delete text -behind the cursor, characters to the right of the cursor get `pulled -back' to fill in the blank space created by the removal of the text. A -list of the basic bare essentials for editing the text of an input line -follows. - - - Move back one character. - - - Move forward one character. - - - Delete the character to the left of the cursor. - - - Delete the character underneath the cursor. - -Printing characters - Insert itself into the line at the cursor. - - - Undo the last thing that you did. You can undo all the way back - to an empty line. - - -File: gdb.info, Node: Readline Movement Commands, Next: Readline Killing Commands, Prev: Readline Bare Essentials, Up: Readline Interaction - -Readline Movement Commands --------------------------- - - The above table describes the most basic possible keystrokes that -you need in order to do editing of the input line. For your -convenience, many other commands have been added in addition to , -, , and . Here are some commands for moving more rapidly -about the line. - - - Move to the start of the line. - - - Move to the end of the line. - - - Move forward a word. - - - Move backward a word. - - - Clear the screen, reprinting the current line at the top. - - Notice how moves forward a character, while moves -forward a word. It is a loose convention that control keystrokes -operate on characters while meta keystrokes operate on words. - - -File: gdb.info, Node: Readline Killing Commands, Next: Readline Arguments, Prev: Readline Movement Commands, Up: Readline Interaction - -Readline Killing Commands -------------------------- - - "Killing" text means to delete the text from the line, but to save -it away for later use, usually by "yanking" it back into the line. If -the description for a command says that it `kills' text, then you can -be sure that you can get the text back in a different (or the same) -place later. - - Here is the list of commands for killing text. - - - Kill the text from the current cursor position to the end of the - line. - - - Kill from the cursor to the end of the current word, or if between - words, to the end of the next word. - - - Kill from the cursor to the start of the previous word, or if - between words, to the start of the previous word. - - - Kill from the cursor to the previous whitespace. This is - different than because the word boundaries differ. - - And, here is how to "yank" the text back into the line. - - - Yank the most recently killed text back into the buffer at the - cursor. - - - Rotate the kill-ring, and yank the new top. You can only do this - if the prior command is or . - - When you use a kill command, the text is saved in a "kill-ring". -Any number of consecutive kills save all of the killed text together, so -that when you yank it back, you get it in one clean sweep. The kill -ring is not line specific; the text that you killed on a previously -typed line is available to be yanked back later, when you are typing -another line. - diff --git a/gnu/dist/gdb/doc/gdb.info-8 b/gnu/dist/gdb/doc/gdb.info-8 deleted file mode 100644 index 7797c44fa1e3..000000000000 --- a/gnu/dist/gdb/doc/gdb.info-8 +++ /dev/null @@ -1,844 +0,0 @@ -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 Fifth Edition, April 1998, of `Debugging with GDB: the -GNU Source-Level Debugger' for GDB Version . - - Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, -1997, 1998 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: Readline Arguments, Prev: Readline Killing Commands, Up: Readline Interaction - -Readline Arguments ------------------- - - You can pass numeric arguments to Readline commands. Sometimes the -argument acts as a repeat count, other times it is the sign of the -argument that is significant. If you pass a negative argument to a -command which normally acts in a forward direction, that command will -act in a backward direction. For example, to kill text back to the -start of the line, you might type . - - The general way to pass numeric arguments to a command is to type -meta digits before the command. If the first `digit' you type is a -minus sign (<->), then the sign of the argument will be negative. Once -you have typed one meta digit to get the argument started, you can type -the remainder of the digits, and then the command. For example, to give -the command an argument of 10, you could type . - - -File: gdb.info, Node: Readline Init File, Prev: Readline Interaction, Up: Command Line Editing - -Readline Init File -================== - - Although the Readline library comes with a set of GNU Emacs-like -keybindings, it is possible that you would like to use a different set -of keybindings. You can customize programs that use Readline by putting -commands in an "init" file in your home directory. The name of this -file is `~/.inputrc'. - - When a program which uses the Readline library starts up, the -`~/.inputrc' file is read, and the keybindings are set. - - In addition, the command re-reads this init file, thus -incorporating any changes that you might have made to it. - -* Menu: - -* Readline Init Syntax:: Syntax for the commands in `~/.inputrc'. -* Readline vi Mode:: Switching to `vi' mode in Readline. - - -File: gdb.info, Node: Readline Init Syntax, Next: Readline vi Mode, Up: Readline Init File - -Readline Init Syntax --------------------- - - There are only four constructs allowed in the `~/.inputrc' file: - -Variable Settings - You can change the state of a few variables in Readline. You do - this by using the `set' command within the init file. Here is how - you would specify that you wish to use `vi' line editing commands: - - set editing-mode vi - - Right now, there are only a few variables which can be set; so few - in fact, that we just iterate them here: - - `editing-mode' - The `editing-mode' variable controls which editing mode you - are using. By default, GNU Readline starts up in Emacs - editing mode, where the keystrokes are most similar to Emacs. - This variable can either be set to `emacs' or `vi'. - - `horizontal-scroll-mode' - This variable can either be set to `On' or `Off'. Setting it - to `On' means that the text of the lines that you edit will - scroll horizontally on a single screen line when they are - larger than the width of the screen, instead of wrapping onto - a new screen line. By default, this variable is set to `Off'. - - `mark-modified-lines' - This variable when set to `On', says to display an asterisk - (`*') at the starts of history lines which have been modified. - This variable is off by default. - - `prefer-visible-bell' - If this variable is set to `On' it means to use a visible - bell if one is available, rather than simply ringing the - terminal bell. By default, the value is `Off'. - -Key Bindings - The syntax for controlling keybindings in the `~/.inputrc' file is - simple. First you have to know the name of the command that you - want to change. The following pages contain tables of the command - name, the default keybinding, and a short description of what the - command does. - - Once you know the name of the command, simply place the name of - the key you wish to bind the command to, a colon, and then the - name of the command on a line in the `~/.inputrc' file. The name - of the key can be expressed in different ways, depending on which - is most comfortable for you. - - KEYNAME: FUNCTION-NAME or MACRO - KEYNAME is the name of a key spelled out in English. For - example: - Control-u: universal-argument - Meta-Rubout: backward-kill-word - Control-o: ">&output" - - In the above example, is bound to the function - `universal-argument', and is bound to run the macro - expressed on the right hand side (that is, to insert the text - `>&output' into the line). - - "KEYSEQ": FUNCTION-NAME or MACRO - KEYSEQ differs from KEYNAME above in that strings denoting an - entire key sequence can be specified. Simply place the key - sequence in double quotes. GNU Emacs style key escapes can - be used, as in the following example: - - "\C-u": universal-argument - "\C-x\C-r": re-read-init-file - "\e[11~": "Function Key 1" - - In the above example, is bound to the function - `universal-argument' (just as it was in the first example), - is bound to the function `re-read-init-file', and - is bound to insert the text `Function Key 1'. - -* Menu: - -* Commands For Moving:: Moving about the line. -* Commands For History:: Getting at previous lines. -* Commands For Text:: Commands for changing text. -* Commands For Killing:: Commands for killing and yanking. -* Numeric Arguments:: Specifying numeric arguments, repeat counts. -* Commands For Completion:: Getting Readline to do the typing for you. -* Miscellaneous Commands:: Other miscillaneous commands. - - -File: gdb.info, Node: Commands For Moving, Next: Commands For History, Up: Readline Init Syntax - -Commands For Moving -................... - -`beginning-of-line ()' - Move to the start of the current line. - -`end-of-line ()' - Move to the end of the line. - -`forward-char ()' - Move forward a character. - -`backward-char ()' - Move back a character. - -`forward-word ()' - Move forward to the end of the next word. - -`backward-word ()' - Move back to the start of this, or the previous, word. - -`clear-screen ()' - Clear the screen leaving the current line at the top of the screen. - - -File: gdb.info, Node: Commands For History, Next: Commands For Text, Prev: Commands For Moving, Up: Readline Init Syntax - -Commands For Manipulating The History -..................................... - -`accept-line (Newline, Return)' - Accept the line regardless of where the cursor is. If this line is - non-empty, add it to the history list. If this line was a history - line, then restore the history line to its original state. - -`previous-history ()' - Move `up' through the history list. - -`next-history ()' - Move `down' through the history list. - -`beginning-of-history ()' - Move to the first line in the history. - -`end-of-history (>)' - Move to the end of the input history, i.e., the line you are - entering. - -`reverse-search-history ()' - Search backward starting at the current line and moving `up' - through the history as necessary. This is an incremental search. - -`forward-search-history ()' - Search forward starting at the current line and moving `down' - through the the history as necessary. - - -File: gdb.info, Node: Commands For Text, Next: Commands For Killing, Prev: Commands For History, Up: Readline Init Syntax - -Commands For Changing Text -.......................... - -`delete-char ()' - Delete the character under the cursor. If the cursor is at the - beginning of the line, and there are no characters in the line, and - the last character typed was not , then return EOF. - -`backward-delete-char (Rubout)' - Delete the character behind the cursor. A numeric argument says - to kill the characters instead of deleting them. - -`quoted-insert (, )' - Add the next character that you type to the line verbatim. This is - how to insert things like for example. - -`tab-insert ()' - Insert a tab character. - -`self-insert (a, b, A, 1, !, ...)' - Insert yourself. - -`transpose-chars ()' - Drag the character before point forward over the character at - point. Point moves forward as well. If point is at the end of - the line, then transpose the two characters before point. - Negative arguments don't work. - -`transpose-words ()' - Drag the word behind the cursor past the word in front of the - cursor moving the cursor over that word as well. - -`upcase-word ()' - Uppercase all letters in the current (or following) word. With a - negative argument, do the previous word, but do not move point. - -`downcase-word ()' - Lowercase all letters in the current (or following) word. With a - negative argument, do the previous word, but do not move point. - -`capitalize-word ()' - Uppercase the first letter in the current (or following) word. - With a negative argument, do the previous word, but do not move - point. - - -File: gdb.info, Node: Commands For Killing, Next: Numeric Arguments, Prev: Commands For Text, Up: Readline Init Syntax - -Killing And Yanking -................... - -`kill-line ()' - Kill the text from the current cursor position to the end of the - line. - -`backward-kill-line ()' - Kill backward to the beginning of the line. This is normally - unbound. - -`kill-word ()' - Kill from the cursor to the end of the current word, or if between - words, to the end of the next word. - -`backward-kill-word ()' - Kill the word behind the cursor. - -`unix-line-discard ()' - Kill the whole line the way used to in Unix line input. The - killed text is saved on the kill-ring. - -`unix-word-rubout ()' - Kill the word the way used to in Unix line input. The - killed text is saved on the kill-ring. This is different than - backward-kill-word because the word boundaries differ. - -`yank ()' - Yank the top of the kill ring into the buffer at point. - -`yank-pop ()' - Rotate the kill-ring, and yank the new top. You can only do this - if the prior command is yank or yank-pop. - - -File: gdb.info, Node: Numeric Arguments, Next: Commands For Completion, Prev: Commands For Killing, Up: Readline Init Syntax - -Specifying Numeric Arguments -............................ - -`digit-argument (, , ... )' - Add this digit to the argument already accumulating, or start a new - argument. starts a negative argument. - -`universal-argument ()' - Do what does in GNU Emacs. By default, this is not bound. - - -File: gdb.info, Node: Commands For Completion, Next: Miscellaneous Commands, Prev: Numeric Arguments, Up: Readline Init Syntax - -Letting Readline Type For You -............................. - -`complete (TAB)' - Attempt to do completion on the text before point. This is - implementation defined. Generally, if you are typing a filename - argument, you can do filename completion; if you are typing a - command, you can do command completion, if you are typing in a - symbol to GDB, you can do symbol name completion, if you are - typing in a variable to Bash, you can do variable name completion. - -`possible-completions (M-?)' - List the possible completions of the text before point. - - -File: gdb.info, Node: Miscellaneous Commands, Prev: Commands For Completion, Up: Readline Init Syntax - -Some Miscellaneous Commands -........................... - -`re-read-init-file ( )' - Read in the contents of your `~/.inputrc' file, and incorporate - any bindings found there. - -`abort ()' - Stop running the current editing command. - -`prefix-meta (ESC)' - Make the next character that you type be metafied. This is for - people without a meta key. Typing is equivalent to typing - . - -`undo ()' - Incremental undo, separately remembered for each line. - -`revert-line ()' - Undo all changes made to this line. This is like typing the `undo' - command enough times to get back to the beginning. - - -File: gdb.info, Node: Readline vi Mode, Prev: Readline Init Syntax, Up: Readline Init File - -Readline `vi' Mode ------------------- - - While the Readline library does not have a full set of `vi' editing -functions, it does contain enough to allow simple editing of the line. - - In order to switch interactively between GNU Emacs and `vi' editing -modes, use the command (toggle-editing-mode). - - When you enter a line in `vi' mode, you are already placed in -`insertion' mode, as if you had typed an `i'. Pressing switches -you into `edit' mode, where you can edit the text of the line with the -standard `vi' movement keys, move to previous history lines with `k', -and following lines with `j', and so forth. - - -File: gdb.info, Node: Using History Interactively, Next: Formatting Documentation, Prev: Command Line Editing, Up: Top - -Using History Interactively -*************************** - - This chapter describes how to use the GNU History Library -interactively, from a user's standpoint. - -* Menu: - -* History Interaction:: What it feels like using History as a user. - - -File: gdb.info, Node: History Interaction, Up: Using History Interactively - -History Interaction -=================== - - The History library provides a history expansion feature similar to -the history expansion in `csh'. The following text describes the -syntax you use to manipulate history information. - - History expansion takes two parts. In the first part, determine -which line from the previous history will be used for substitution. -This line is called the "event". In the second part, select portions -of that line for inclusion into the current line. These portions are -called "words". GDB breaks the line into words in the same way that -the Bash shell does, so that several English (or Unix) words surrounded -by quotes are considered one word. - -* Menu: - -* Event Designators:: How to specify which history line to use. -* Word Designators:: Specifying which words are of interest. -* Modifiers:: Modifying the results of susbstitution. - - -File: gdb.info, Node: Event Designators, Next: Word Designators, Up: History Interaction - -Event Designators ------------------ - - An "event designator" is a reference to a command line entry in the -history list. - -`!' - Start a history subsititution, except when followed by a space, - tab, or the end of the line... <=> or <(>. - -`!!' - Refer to the previous command. This is a synonym for `!-1'. - -`!n' - Refer to command line N. - -`!-n' - Refer to the command line N lines back. - -`!string' - Refer to the most recent command starting with STRING. - -`!?string'[`?'] - Refer to the most recent command containing STRING. - - -File: gdb.info, Node: Word Designators, Next: Modifiers, Prev: Event Designators, Up: History Interaction - -Word Designators ----------------- - - A <:> separates the event designator from the "word designator". It -can be omitted if the word designator begins with a <^>, <$>, <*> or -<%>. Words are numbered from the beginning of the line, with the first -word being denoted by a 0 (zero). - -`0 (zero)' - The zero'th word. For many applications, this is the command word. - -`n' - The N'th word. - -`^' - The first argument. that is, word 1. - -`$' - The last argument. - -`%' - The word matched by the most recent `?string?' search. - -`x-y' - A range of words; `-Y' Abbreviates `0-Y'. - -`*' - All of the words, excepting the zero'th. This is a synonym for - `1-$'. It is not an error to use <*> if there is just one word in - the event. The empty string is returned in that case. - - -File: gdb.info, Node: Modifiers, Prev: Word Designators, Up: History Interaction - -Modifiers ---------- - - After the optional word designator, you can add a sequence of one or -more of the following "modifiers", each preceded by a <:>. - -`#' - The entire command line typed so far. This means the current - command, not the previous command. - -`h' - Remove a trailing pathname component, leaving only the head. - -`r' - Remove a trailing suffix of the form `.'SUFFIX, leaving the - basename. - -`e' - Remove all but the suffix. - -`t' - Remove all leading pathname components, leaving the tail. - -`p' - Print the new command but do not execute it. - - -File: gdb.info, Node: Formatting Documentation, Next: Installing GDB, Prev: Using History Interactively, Up: Top - -Formatting Documentation -************************ - - The GDB 4 release includes an already-formatted reference card, ready -for printing with PostScript or Ghostscript, in the `gdb' subdirectory -of the main source directory(1). If you can use PostScript or -Ghostscript with your printer, you can print the reference card -immediately with `refcard.ps'. - - The release also includes the source for the reference card. You -can format it, using TeX, by typing: - - make refcard.dvi - - The GDB reference card is designed to print in "landscape" mode on -US "letter" size paper; that is, on a sheet 11 inches wide by 8.5 inches -high. You will need to specify this form of printing as an option to -your DVI output program. - - All the documentation for GDB comes as part of the machine-readable -distribution. The documentation is written in Texinfo format, which is -a documentation system that uses a single source file to produce both -on-line information and a printed manual. You can use one of the Info -formatting commands to create the on-line version of the documentation -and TeX (or `texi2roff') to typeset the printed version. - - GDB includes an already formatted copy of the on-line Info version of -this manual in the `gdb' subdirectory. The main Info file is -`gdb-version-number/gdb/gdb.info', and it refers to subordinate files -matching `gdb.info*' in the same directory. If necessary, you can -print out these files, or read them with any editor; but they are -easier to read using the `info' subsystem in GNU Emacs or the -standalone `info' program, available as part of the GNU Texinfo -distribution. - - If you want to format these Info files yourself, you need one of the -Info formatting programs, such as `texinfo-format-buffer' or `makeinfo'. - - If you have `makeinfo' installed, and are in the top level GDB -source directory (`gdb-', in the case of version ), you can make the -Info file by typing: - - cd gdb - make gdb.info - - If you want to typeset and print copies of this manual, you need TeX, -a program to print its DVI output files, and `texinfo.tex', the Texinfo -definitions file. - - TeX is a typesetting program; it does not print files directly, but -produces output files called DVI files. To print a typeset document, -you need a program to print DVI files. If your system has TeX -installed, chances are it has such a program. The precise command to -use depends on your system; `lpr -d' is common; another (for PostScript -devices) is `dvips'. The DVI print command may require a file name -without any extension or a `.dvi' extension. - - TeX also requires a macro definitions file called `texinfo.tex'. -This file tells TeX how to typeset a document written in Texinfo -format. On its own, TeX cannot either read or typeset a Texinfo file. -`texinfo.tex' is distributed with GDB and is located in the -`gdb-VERSION-NUMBER/texinfo' directory. - - If you have TeX and a DVI printer program installed, you can typeset -and print this manual. First switch to the the `gdb' subdirectory of -the main source directory (for example, to `gdb-/gdb') and then type: - - make gdb.dvi - - ---------- Footnotes ---------- - - (1) In `gdb-/gdb/refcard.ps' of the version release. - - -File: gdb.info, Node: Installing GDB, Next: Index, Prev: Formatting Documentation, Up: Top - -Installing GDB -************** - - GDB comes with a `configure' script that automates the process of -preparing GDB for installation; you can then use `make' to build the -`gdb' program. - - The GDB distribution includes all the source code you need for GDB -in a single directory, whose name is usually composed by appending the -version number to `gdb'. - - For example, the GDB version distribution is in the `gdb-' -directory. That directory contains: - -`gdb-/configure (and supporting files)' - script for configuring GDB and all its supporting libraries - -`gdb-/gdb' - the source specific to GDB itself - -`gdb-/bfd' - source for the Binary File Descriptor library - -`gdb-/include' - GNU include files - -`gdb-/libiberty' - source for the `-liberty' free software library - -`gdb-/opcodes' - source for the library of opcode tables and disassemblers - -`gdb-/readline' - source for the GNU command-line interface - -`gdb-/glob' - source for the GNU filename pattern-matching subroutine - -`gdb-/mmalloc' - source for the GNU memory-mapped malloc package - - The simplest way to configure and build GDB is to run `configure' -from the `gdb-VERSION-NUMBER' source directory, which in this example -is the `gdb-' directory. - - First switch to the `gdb-VERSION-NUMBER' source directory if you are -not already in it; then run `configure'. Pass the identifier for the -platform on which GDB will run as an argument. - - For example: - - cd gdb- - ./configure HOST - make - -where HOST is an identifier such as `sun4' or `decstation', that -identifies the platform where GDB will run. (You can often leave off -HOST; `configure' tries to guess the correct value by examining your -system.) - - Running `configure HOST' and then running `make' builds the `bfd', -`readline', `mmalloc', and `libiberty' libraries, then `gdb' itself. -The configured source files, and the binaries, are left in the -corresponding source directories. - - `configure' is a Bourne-shell (`/bin/sh') script; if your system -does not recognize this automatically when you run a different shell, -you may need to run `sh' on it explicitly: - - sh configure HOST - - If you run `configure' from a directory that contains source -directories for multiple libraries or programs, such as the `gdb-' -source directory for version , `configure' creates configuration files -for every directory level underneath (unless you tell it not to, with -the `--norecursion' option). - - You can run the `configure' script from any of the subordinate -directories in the GDB distribution if you only want to configure that -subdirectory, but be sure to specify a path to it. - - For example, with version , type the following to configure only the -`bfd' subdirectory: - - cd gdb-/bfd - ../configure HOST - - You can install `gdb' anywhere; it has no hardwired paths. However, -you should make sure that the shell on your path (named by the `SHELL' -environment variable) is publicly readable. Remember that GDB uses the -shell to start your program--some systems refuse to let GDB debug child -processes whose programs are not readable. - -* Menu: - -* 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: Separate Objdir, Next: Config Names, Up: Installing GDB - -Compiling GDB in another directory -================================== - - If you want to run GDB versions for several host or target machines, -you need a different `gdb' compiled for each combination of host and -target. `configure' is designed to make this easy by allowing you to -generate each configuration in a separate subdirectory, rather than in -the source directory. If your `make' program handles the `VPATH' -feature (GNU `make' does), running `make' in each of these directories -builds the `gdb' program specified there. - - To build `gdb' in a separate directory, run `configure' with the -`--srcdir' option to specify where to find the source. (You also need -to specify a path to find `configure' itself from your working -directory. If the path to `configure' would be the same as the -argument to `--srcdir', you can leave out the `--srcdir' option; it is -assumed.) - - For example, with version , you can build GDB in a separate -directory for a Sun 4 like this: - - cd gdb- - mkdir ../gdb-sun4 - cd ../gdb-sun4 - ../gdb-/configure sun4 - make - - When `configure' builds a configuration using a remote source -directory, it creates a tree for the binaries with the same structure -(and using the same names) as the tree under the source directory. In -the example, you'd find the Sun 4 library `libiberty.a' in the -directory `gdb-sun4/libiberty', and GDB itself in `gdb-sun4/gdb'. - - One popular reason to build several GDB configurations in separate -directories is to configure GDB for cross-compiling (where GDB runs on -one machine--the "host"--while debugging programs that run on another -machine--the "target"). You specify a cross-debugging target by giving -the `--target=TARGET' option to `configure'. - - When you run `make' to build a program or library, you must run it -in a configured directory--whatever directory you were in when you -called `configure' (or one of its subdirectories). - - The `Makefile' that `configure' generates in each source directory -also runs recursively. If you type `make' in a source directory such -as `gdb-' (or in a separate configured directory configured with -`--srcdir=DIRNAME/gdb-'), you will build all the required libraries, -and then build GDB. - - When you have multiple hosts or targets configured in separate -directories, you can run `make' on them in parallel (for example, if -they are NFS-mounted on each of the hosts); they will not interfere -with each other. - - -File: gdb.info, Node: Config Names, Next: configure Options, Prev: Separate Objdir, Up: Installing GDB - -Specifying names for hosts and targets -====================================== - - The specifications used for hosts and targets in the `configure' -script are based on a three-part naming scheme, but some short -predefined aliases are also supported. The full naming scheme encodes -three pieces of information in the following pattern: - - ARCHITECTURE-VENDOR-OS - - For example, you can use the alias `sun4' as a HOST argument, or as -the value for TARGET in a `--target=TARGET' option. The equivalent -full name is `sparc-sun-sunos4'. - - The `configure' script accompanying GDB does not provide any query -facility to list all supported host and target names or aliases. -`configure' calls the Bourne shell script `config.sub' to map -abbreviations to full names; you can read the script, if you wish, or -you can use it to test your guesses on abbreviations--for example: - - % sh config.sub sun4 - sparc-sun-sunos4.1.1 - % sh config.sub sun3 - m68k-sun-sunos4.1.1 - % sh config.sub decstation - mips-dec-ultrix4.2 - % sh config.sub hp300bsd - m68k-hp-bsd - % sh config.sub i386v - i386-unknown-sysv - % sh config.sub i786v - Invalid configuration `i786v': machine `i786v' not recognized - -`config.sub' is also distributed in the GDB source directory (`gdb-', -for version ). - - -File: gdb.info, Node: configure Options, Prev: Config Names, Up: Installing GDB - -`configure' options -=================== - - Here is a summary of the `configure' options and arguments that are -most often useful for building GDB. `configure' also has several other -options not listed here. *note (configure.info)What Configure Does::, -for a full explanation of `configure'. - - configure [--help] - [--prefix=DIR] - [--srcdir=DIRNAME] - [--norecursion] [--rm] - [--target=TARGET] HOST - -You may introduce options with a single `-' rather than `--' if you -prefer; but you may abbreviate option names if you use `--'. - -`--help' - Display a quick summary of how to invoke `configure'. - -`-prefix=DIR' - Configure the source to install programs and files under directory - `DIR'. - -`--srcdir=DIRNAME' - *Warning: using this option requires GNU `make', or another `make' - that implements the `VPATH' feature.* - Use this option to make configurations in directories separate - from the GDB source directories. Among other things, you can use - this to build (or maintain) several configurations simultaneously, - in separate directories. `configure' writes configuration - specific files in the current directory, but arranges for them to - use the source in the directory DIRNAME. `configure' creates - directories under the working directory in parallel to the source - directories below DIRNAME. - -`--norecursion' - Configure only the directory level where `configure' is executed; - do not propagate configuration to subdirectories. - -`--rm' - *Remove* files otherwise built during configuration. - -`--target=TARGET' - Configure GDB for cross-debugging programs running on the specified - TARGET. Without this option, GDB is configured to debug programs - that run on the same machine (HOST) as GDB itself. - - There is no convenient way to generate a list of all available - targets. - -`HOST ...' - Configure GDB to run on the specified HOST. - - There is no convenient way to generate a list of all available - hosts. - -`configure' accepts other options, for compatibility with configuring -other GNU tools recursively; but these are the only options that affect -GDB or its supporting libraries. - diff --git a/gnu/dist/gdb/doc/gdb.info-9 b/gnu/dist/gdb/doc/gdb.info-9 deleted file mode 100644 index af64a524b94d..000000000000 --- a/gnu/dist/gdb/doc/gdb.info-9 +++ /dev/null @@ -1,717 +0,0 @@ -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 Fifth Edition, April 1998, of `Debugging with GDB: the -GNU Source-Level Debugger' for GDB Version . - - Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, -1997, 1998 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: Index, Prev: Installing GDB, Up: Top - -Index -***** - -* Menu: - -* #: Command Syntax. -* # in Modula-2: GDB/M2. -* $: Value History. -* $$: Value History. -* $_: Convenience Vars. -* $_ and info breakpoints: Set Breaks. -* $_ and info line: Machine Code. -* $_, $__, and value history: Memory. -* $__: Convenience Vars. -* $_exitcode: Convenience Vars. -* $bpnum: Set Breaks. -* $cdir: Source Path. -* $cwd: Source Path. -* .: M2 Scope. -* .esgdbinit: Command Files. -* .gdbinit: Command Files. -* .os68gdbinit: Command Files. -* .vxgdbinit: Command Files. -* /proc: Process Information. -* @: Arrays. -* a.out and C++: Cplus expressions. -* abbreviation: Command Syntax. -* active targets: Active Targets. -* add-shared-symbol-file: Files. -* add-symbol-file: Files. -* AMD 29K register stack: Registers. -* AMD EB29K: Target Commands. -* AMD29K via UDI: UDI29K Remote. -* arguments (to your program): Arguments. -* artificial array: Arrays. -* assembly instructions: Machine Code. -* assignment: Assignment. -* attach: Attach. -* automatic display: Auto Display. -* automatic thread selection: Threads. -* awatch: Set Watchpoints. -* b: Set Breaks. -* backtrace: Backtrace. -* break: Set Breaks. -* break ... thread THREADNO: Thread Stops. -* break in overloaded functions: Debugging C plus plus. -* breakpoint commands: Break Commands. -* breakpoint conditions: Conditions. -* breakpoint numbers: Breakpoints. -* breakpoint on memory address: Breakpoints. -* breakpoint on variable modification: Breakpoints. -* breakpoint subroutine, remote: Stub Contents. -* breakpoints: Breakpoints. -* breakpoints and threads: Thread Stops. -* bt: Backtrace. -* bug criteria: Bug Criteria. -* bug reports: Bug Reporting. -* bugs in GDB: GDB Bugs. -* c: Continuing and Stepping. -* C and C++: C. -* C and C++ checks: C Checks. -* C and C++ constants: C Operators. -* C and C++ defaults: C Defaults. -* C and C++ operators: C. -* C++: C. -* C++ and object formats: Cplus expressions. -* C++ exception handling: Debugging C plus plus. -* C++ scope resolution: Variables. -* C++ support, not in COFF: Cplus expressions. -* C++ symbol decoding style: Print Settings. -* C++ symbol display: Debugging C plus plus. -* call: Calling. -* call overloaded functions: Cplus expressions. -* call stack: Stack. -* calling functions: Calling. -* calling make: Shell Commands. -* casts, to view memory: Expressions. -* catch: Exception Handling. -* catch exceptions: Frame Info. -* cd: Working Directory. -* cdir: Source Path. -* checks, range: Type Checking. -* checks, type: Checks. -* checksum, for GDB remote: Protocol. -* choosing target byte order: Target Commands. -* clear: Delete Breaks. -* clearing breakpoints, watchpoints: Delete Breaks. -* COFF versus C++: Cplus expressions. -* colon, doubled as scope operator: M2 Scope. -* colon-colon <1>: M2 Scope. -* colon-colon: Variables. -* command files <1>: Command Files. -* command files: Hooks. -* command line editing: Editing. -* commands: Break Commands. -* commands for C++: Debugging C plus plus. -* commands to STDBUG (ST2000): ST2000 Remote. -* comment: Command Syntax. -* compilation directory: Source Path. -* Compiling: Sparclet Remote. -* complete: Help. -* completion: Completion. -* completion of quoted strings: Completion. -* condition: Conditions. -* conditional breakpoints: Conditions. -* configuring GDB: Installing GDB. -* confirmation: Messages/Warnings. -* connect (to STDBUG): ST2000 Remote. -* continue: Continuing and Stepping. -* continuing: Continuing and Stepping. -* continuing threads: Thread Stops. -* control C, and remote debugging: Bootstrapping. -* controlling terminal: Input/Output. -* convenience variables: Convenience Vars. -* core: Files. -* core dump file: Files. -* core-file: Files. -* CPU simulator: Simulator. -* crash of debugger: Bug Criteria. -* current directory: Source Path. -* current thread: Threads. -* cwd: Source Path. -* d: Delete Breaks. -* debugger crash: Bug Criteria. -* debugging optimized code: Compilation. -* debugging stub, example: Protocol. -* debugging target: Targets. -* define: Define. -* delete: Delete Breaks. -* delete breakpoints: Delete Breaks. -* delete display: Auto Display. -* deleting breakpoints, watchpoints: Delete Breaks. -* demangling: Print Settings. -* detach: Attach. -* device: Hitachi Boards. -* dir: Source Path. -* directories for source files: Source Path. -* directory: Source Path. -* directory, compilation: Source Path. -* directory, current: Source Path. -* dis: Disabling. -* disable: Disabling. -* disable breakpoints: Disabling. -* disable display: Auto Display. -* disassemble: Machine Code. -* display: Auto Display. -* display of expressions: Auto Display. -* do: Selection. -* document: Define. -* documentation: Formatting Documentation. -* down: Selection. -* down-silently: Selection. -* download to H8/300 or H8/500: Files. -* download to Hitachi SH: Files. -* download to Nindy-960: Files. -* download to Sparclet: Sparclet Download. -* download to VxWorks: VxWorks Download. -* dynamic linking: Files. -* eb.log: Remote Log. -* EB29K board: EB29K Remote. -* EBMON: Comms (EB29K). -* echo: Output. -* ECOFF and C++: Cplus expressions. -* editing: Editing. -* editing-mode: Readline Init Syntax. -* ELF/DWARF and C++: Cplus expressions. -* ELF/stabs and C++: Cplus expressions. -* else: Define. -* Emacs: Emacs. -* enable: Disabling. -* enable breakpoints: Disabling. -* enable display: Auto Display. -* end: Break Commands. -* entering numbers: Numbers. -* environment (of your program): Environment. -* error on valid input: Bug Criteria. -* event designators: Event Designators. -* examining data: Data. -* examining memory: Memory. -* exception handlers <1>: Frame Info. -* exception handlers: Exception Handling. -* exceptionHandler: Bootstrapping. -* exec-file: Files. -* executable file: Files. -* exiting GDB: Quitting GDB. -* expansion: History Interaction. -* expressions: Expressions. -* expressions in C or C++: C. -* expressions in C++: Cplus expressions. -* expressions in Modula-2: Modula-2. -* f: Selection. -* fatal signal: Bug Criteria. -* fatal signals: Signals. -* fg: Continuing and Stepping. -* file: Files. -* finish: Continuing and Stepping. -* flinching: Messages/Warnings. -* floating point: Floating Point Hardware. -* floating point registers: Registers. -* floating point, MIPS remote: MIPS Remote. -* flush_i_cache: Bootstrapping. -* focus of debugging: Threads. -* foo: Symbol Errors. -* fork, debugging programs which call: Processes. -* format options: Print Settings. -* formatted output: Output Formats. -* Fortran: Summary. -* forward-search: Search. -* frame <1>: Selection. -* frame: Frames. -* frame number: Frames. -* frame pointer: Frames. -* frameless execution: Frames. -* Fujitsu: Remote Serial. -* g++: C. -* GDB bugs, reporting: Bug Reporting. -* GDB reference card: Formatting Documentation. -* GDBHISTFILE: History. -* gdbserve.nlm: NetWare. -* gdbserver: Server. -* getDebugChar: Bootstrapping. -* GNU C++: C. -* GNU Emacs: Emacs. -* h: Help. -* H8/300 or H8/500 download: Files. -* H8/300 or H8/500 simulator: Simulator. -* handle: Signals. -* handle_exception: Stub Contents. -* handling signals: Signals. -* hbreak: Set Breaks. -* help: Help. -* help target: Target Commands. -* help user-defined: Define. -* heuristic-fence-post (MIPS): MIPS Stack. -* history expansion: History. -* history file: History. -* history number: Value History. -* history save: History. -* history size: History. -* history substitution: History. -* Hitachi: Remote Serial. -* Hitachi SH download: Files. -* Hitachi SH simulator: Simulator. -* horizontal-scroll-mode: Readline Init Syntax. -* i: Help. -* i/o: Input/Output. -* i386: Remote Serial. -* i386-stub.c: Remote Serial. -* i960: i960-Nindy Remote. -* if: Define. -* ignore: Conditions. -* ignore count (of breakpoint): Conditions. -* INCLUDE_RDB: VxWorks Remote. -* info: Help. -* info address: Symbols. -* info all-registers: Registers. -* info args: Frame Info. -* info breakpoints: Set Breaks. -* info catch: Frame Info. -* info display: Auto Display. -* info f: Frame Info. -* info files: Files. -* info float: Floating Point Hardware. -* info frame <1>: Show. -* info frame: Frame Info. -* info functions: Symbols. -* info line: Machine Code. -* info locals: Frame Info. -* info proc: Process Information. -* info proc id: Process Information. -* info proc mappings: Process Information. -* info proc status: Process Information. -* info proc times: Process Information. -* info program: Stopping. -* info registers: Registers. -* info s: Backtrace. -* info set: Help. -* info share: Files. -* info sharedlibrary: Files. -* info signals: Signals. -* info source <1>: Symbols. -* info source: Show. -* info sources: Symbols. -* info stack: Backtrace. -* info target: Files. -* info terminal: Input/Output. -* info threads: Threads. -* info types: Symbols. -* info variables: Symbols. -* info watchpoints: Set Watchpoints. -* inheritance: Debugging C plus plus. -* init file: Command Files. -* init file name: Command Files. -* initial frame: Frames. -* innermost frame: Frames. -* inspect: Data. -* installation: Installing GDB. -* instructions, assembly: Machine Code. -* Intel: Remote Serial. -* interaction, readline: Readline Interaction. -* internal GDB breakpoints: Set Breaks. -* interrupt: Quitting GDB. -* interrupting remote programs: Debug Session. -* interrupting remote targets: Bootstrapping. -* invalid input: Bug Criteria. -* jump: Jumping. -* kill: Kill Process. -* l: List. -* languages: Languages. -* latest breakpoint: Set Breaks. -* leaving GDB: Quitting GDB. -* linespec: List. -* list: List. -* listing machine instructions: Machine Code. -* load FILENAME: Files. -* log file for EB29K: Remote Log. -* m680x0: Remote Serial. -* m68k-stub.c: Remote Serial. -* machine instructions: Machine Code. -* maint info breakpoints: Set Breaks. -* maint print psymbols: Symbols. -* maint print symbols: Symbols. -* make: Shell Commands. -* mapped: Files. -* mark-modified-lines: Readline Init Syntax. -* member functions: Cplus expressions. -* memory models, H8/500: Hitachi Special. -* memory tracing: Breakpoints. -* memory, viewing as typed object: Expressions. -* memory-mapped symbol file: Files. -* memset: Bootstrapping. -* MIPS boards: MIPS Remote. -* MIPS remote floating point: MIPS Remote. -* MIPS remotedebug protocol: MIPS Remote. -* MIPS stack: MIPS Stack. -* Modula-2: Modula-2. -* Modula-2 built-ins: M2 Operators. -* Modula-2 checks: M2 Checks. -* Modula-2 constants: Built-In Func/Proc. -* Modula-2 defaults: M2 Defaults. -* Modula-2 operators: M2 Operators. -* Modula-2, deviations from: Deviations. -* Motorola 680x0: Remote Serial. -* multiple processes: Processes. -* multiple targets: Active Targets. -* multiple threads: Threads. -* n: Continuing and Stepping. -* names of symbols: Symbols. -* namespace in C++: Cplus expressions. -* negative breakpoint numbers: Set Breaks. -* New SYSTAG: Threads. -* next: Continuing and Stepping. -* nexti: Continuing and Stepping. -* ni: Continuing and Stepping. -* Nindy: i960-Nindy Remote. -* number representation: Numbers. -* numbers for breakpoints: Breakpoints. -* object formats and C++: Cplus expressions. -* online documentation: Help. -* optimized code, debugging: Compilation. -* outermost frame: Frames. -* output: Output. -* output formats: Output Formats. -* overloading: Breakpoint Menus. -* overloading in C++: Debugging C plus plus. -* packets, reporting on stdout: Protocol. -* partial symbol dump: Symbols. -* patching binaries: Patching. -* path: Environment. -* pauses in output: Screen Size. -* pipes: Starting. -* pointer, finding referent: Print Settings. -* prefer-visible-bell: Readline Init Syntax. -* print: Data. -* print settings: Print Settings. -* printf: Output. -* printing data: Data. -* process image: Process Information. -* processes, multiple: Processes. -* prompt: Prompt. -* protocol, GDB remote serial: Protocol. -* ptype: Symbols. -* putDebugChar: Bootstrapping. -* pwd: Working Directory. -* q: Quitting GDB. -* quit [EXPRESSION]: Quitting GDB. -* quotes in commands: Completion. -* quoting names: Symbols. -* raise exceptions: Exception Handling. -* range checking: Type Checking. -* rbreak: Set Breaks. -* reading symbols immediately: Files. -* readline: Editing. -* readnow: Files. -* redirection: Input/Output. -* reference card: Formatting Documentation. -* reference declarations: Cplus expressions. -* register stack, AMD29K: Registers. -* registers: Registers. -* regular expression: Set Breaks. -* reloading symbols: Symbols. -* remote connection without stubs: Server. -* remote debugging: Remote. -* remote programs, interrupting: Debug Session. -* remote serial debugging summary: Debug Session. -* remote serial debugging, overview: Remote Serial. -* remote serial protocol: Protocol. -* remote serial stub: Stub Contents. -* remote serial stub list: Remote Serial. -* remote serial stub, initialization: Stub Contents. -* remote serial stub, main routine: Stub Contents. -* remote stub, example: Protocol. -* remote stub, support routines: Bootstrapping. -* remotedebug, MIPS protocol: MIPS Remote. -* remotetimeout: Sparclet Remote. -* repeating commands: Command Syntax. -* reporting bugs in GDB: GDB Bugs. -* reset: Nindy Reset. -* response time, MIPS debugging: MIPS Stack. -* resuming execution: Continuing and Stepping. -* RET: Command Syntax. -* retransmit-timeout, MIPS protocol: MIPS Remote. -* return: Returning. -* returning from a function: Returning. -* reverse-search: Search. -* run: Starting. -* Running: Sparclet Remote. -* running: Starting. -* running 29K programs: EB29K Remote. -* running and debugging Sparclet programs: Sparclet Execution. -* running VxWorks tasks: VxWorks Attach. -* rwatch: Set Watchpoints. -* s: Continuing and Stepping. -* saving symbol table: Files. -* scope: M2 Scope. -* search: Search. -* searching: Search. -* section: Files. -* select-frame: Frames. -* selected frame: Stack. -* serial connections, debugging: Protocol. -* serial device, Hitachi micros: Hitachi Boards. -* serial line speed, Hitachi micros: Hitachi Boards. -* serial line, target remote: Debug Session. -* serial protocol, GDB remote: Protocol. -* set: Help. -* set args: Arguments. -* set assembly-language: Machine Code. -* set check <1>: Range Checking. -* set check: Type Checking. -* set check range: Range Checking. -* set check type: Type Checking. -* set complaints: Messages/Warnings. -* set confirm: Messages/Warnings. -* set demangle-style: Print Settings. -* set editing: Editing. -* set endian auto: Target Commands. -* set endian big: Target Commands. -* set endian little: Target Commands. -* set environment: Environment. -* set gnutarget: Target Commands. -* set height: Screen Size. -* set history expansion: History. -* set history filename: History. -* set history save: History. -* set history size: History. -* set input-radix: Numbers. -* set language: Manually. -* set listsize: List. -* set machine: Hitachi Special. -* set memory MOD: Hitachi Special. -* set mipsfpu: MIPS Remote. -* set output-radix: Numbers. -* set print address: Print Settings. -* set print array: Print Settings. -* set print asm-demangle: Print Settings. -* set print demangle: Print Settings. -* set print elements: Print Settings. -* set print max-symbolic-offset: Print Settings. -* set print null-stop: Print Settings. -* set print object: Print Settings. -* set print pretty: Print Settings. -* set print sevenbit-strings: Print Settings. -* set print static-members: Print Settings. -* set print symbol-filename: Print Settings. -* set print union: Print Settings. -* set print vtbl: Print Settings. -* set processor ARGS: MIPS Remote. -* set prompt: Prompt. -* set remotedebug <1>: MIPS Remote. -* set remotedebug: Protocol. -* set retransmit-timeout: MIPS Remote. -* set rstack_high_address: Registers. -* set symbol-reloading: Symbols. -* set timeout: MIPS Remote. -* set variable: Assignment. -* set verbose: Messages/Warnings. -* set width: Screen Size. -* set write: Patching. -* set_debug_traps: Stub Contents. -* setting variables: Assignment. -* setting watchpoints: Set Watchpoints. -* SH: Remote Serial. -* sh-stub.c: Remote Serial. -* share: Files. -* shared libraries: Files. -* sharedlibrary: Files. -* shell: Shell Commands. -* shell escape: Shell Commands. -* show: Help. -* show args: Arguments. -* show check range: Range Checking. -* show check type: Type Checking. -* show commands: History. -* show complaints: Messages/Warnings. -* show confirm: Messages/Warnings. -* show convenience: Convenience Vars. -* show copying: Help. -* show demangle-style: Print Settings. -* show directories: Source Path. -* show editing: Editing. -* show endian: Target Commands. -* show environment: Environment. -* show gnutarget: Target Commands. -* show height: Screen Size. -* show history: History. -* show input-radix: Numbers. -* show language: Show. -* show listsize: List. -* show machine: Hitachi Special. -* show mipsfpu: MIPS Remote. -* show output-radix: Numbers. -* show paths: Environment. -* show print address: Print Settings. -* show print array: Print Settings. -* show print asm-demangle: Print Settings. -* show print demangle: Print Settings. -* show print elements: Print Settings. -* show print max-symbolic-offset: Print Settings. -* show print object: Print Settings. -* show print pretty: Print Settings. -* show print sevenbit-strings: Print Settings. -* show print static-members: Print Settings. -* show print symbol-filename: Print Settings. -* show print union: Print Settings. -* show print vtbl: Print Settings. -* show processor: MIPS Remote. -* show prompt: Prompt. -* show remotedebug <1>: MIPS Remote. -* show remotedebug: Protocol. -* show retransmit-timeout: MIPS Remote. -* show rstack_high_address: Registers. -* show symbol-reloading: Symbols. -* show timeout: MIPS Remote. -* show user: Define. -* show values: Value History. -* show verbose: Messages/Warnings. -* show version: Help. -* show warranty: Help. -* show width: Screen Size. -* show write: Patching. -* si: Continuing and Stepping. -* signal: Signaling. -* signals: Signals. -* silent: Break Commands. -* sim: Simulator. -* simulator: Simulator. -* simulator, H8/300 or H8/500: Simulator. -* simulator, Hitachi SH: Simulator. -* simulator, Z8000: Simulator. -* size of screen: Screen Size. -* source: Command Files. -* source path: Source Path. -* Sparc: Remote Serial. -* sparc-stub.c: Remote Serial. -* sparcl-stub.c: Remote Serial. -* Sparclet: Sparclet Remote. -* SparcLite: Remote Serial. -* speed: Hitachi Boards. -* ST2000 auxiliary commands: ST2000 Remote. -* st2000 CMD: ST2000 Remote. -* stack frame: Frames. -* stack on MIPS: MIPS Stack. -* stacking targets: Active Targets. -* starting: Starting. -* STDBUG commands (ST2000): ST2000 Remote. -* step: Continuing and Stepping. -* stepi: Continuing and Stepping. -* stepping: Continuing and Stepping. -* stopped threads: Thread Stops. -* stub example, remote debugging: Protocol. -* stupid questions: Messages/Warnings. -* switching threads: Threads. -* switching threads automatically: Threads. -* symbol decoding style, C++: Print Settings. -* symbol dump: Symbols. -* symbol names: Symbols. -* symbol overloading: Breakpoint Menus. -* symbol table: Files. -* symbol-file: Files. -* symbols, reading immediately: Files. -* target: Targets. -* target amd-eb: Target Commands. -* target array: Target Commands. -* target bug: Target Commands. -* target byte order: Target Commands. -* target core: Target Commands. -* target cpu32bug: Target Commands. -* target ddb PORT: MIPS Remote. -* target e7000: Hitachi ICE. -* target est: Target Commands. -* target exec: Target Commands. -* target hms: Target Commands. -* target lsi PORT: MIPS Remote. -* target mips PORT: MIPS Remote. -* target nindy: Target Commands. -* target op50n: Target Commands. -* target pmon PORT: MIPS Remote. -* target remote: Target Commands. -* target rom68k: Target Commands. -* target sim <1>: Simulator. -* target sim: Target Commands. -* target sparclite: Target Commands. -* target st2000: Target Commands. -* target udi: Target Commands. -* target vxworks: Target Commands. -* target w89k: Target Commands. -* tbreak: Set Breaks. -* TCP port, target remote: Debug Session. -* terminal: Input/Output. -* thbreak: Set Breaks. -* this: Cplus expressions. -* thread apply: Threads. -* thread breakpoints: Thread Stops. -* thread identifier (GDB): Threads. -* thread identifier (system): Threads. -* thread number: Threads. -* thread THREADNO: Threads. -* threads and watchpoints: Set Watchpoints. -* threads of execution: Threads. -* threads, automatic switching: Threads. -* threads, continuing: Thread Stops. -* threads, stopped: Thread Stops. -* timeout, MIPS protocol: MIPS Remote. -* toggle-editing-mode: Readline vi Mode. -* tty: Input/Output. -* type casting memory: Expressions. -* type checking: Checks. -* type conversions in C++: Cplus expressions. -* u: Continuing and Stepping. -* udi: UDI29K Remote. -* UDI: UDI29K Remote. -* undisplay: Auto Display. -* unknown address, locating: Output Formats. -* unset environment: Environment. -* until: Continuing and Stepping. -* up: Selection. -* up-silently: Selection. -* user-defined command: Define. -* value history: Value History. -* variable name conflict: Variables. -* variable values, wrong: Variables. -* variables, setting: Assignment. -* version number: Help. -* vi style command editing: Readline vi Mode. -* VxWorks: VxWorks Remote. -* vxworks-timeout: VxWorks Remote. -* watch: Set Watchpoints. -* watchpoints: Breakpoints. -* watchpoints and threads: Set Watchpoints. -* whatis: Symbols. -* where: Backtrace. -* while: Define. -* wild pointer, interpreting: Print Settings. -* word completion: Completion. -* working directory: Source Path. -* working directory (of your program): Working Directory. -* working language: Languages. -* writing into corefiles: Patching. -* writing into executables: Patching. -* wrong values: Variables. -* x: Memory. -* XCOFF and C++: Cplus expressions. -* Z8000 simulator: Simulator. -* {TYPE}: Expressions. - - diff --git a/gnu/dist/gdb/doc/gdbint.info b/gnu/dist/gdb/doc/gdbint.info deleted file mode 100644 index e03939925dc9..000000000000 --- a/gnu/dist/gdb/doc/gdbint.info +++ /dev/null @@ -1,58 +0,0 @@ -This is Info file gdbint.info, produced by Makeinfo version 1.68 from -the input file ../../../devo/gdb/doc/gdbint.texinfo. - -START-INFO-DIR-ENTRY -* Gdb-Internals: (gdbint). The GNU debugger's internals. -END-INFO-DIR-ENTRY - - This file documents the internals of the GNU debugger GDB. - - Copyright 1990, 91, 92, 93, 94, 95, 96, 97, 1998 Free Software -Foundation, Inc. Contributed by Cygnus Support. Written by John -Gilmore. - - 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 or distribute modified versions of this -manual under the terms of the GPL (for which purpose this text may be -regarded as a program in the language TeX). - - -Indirect: -gdbint.info-1: 781 -gdbint.info-2: 49078 - -Tag Table: -(Indirect) -Node: Top781 -Node: README2852 -Node: Getting Started3085 -Node: Debugging GDB7758 -Node: New Architectures8933 -Node: Config12094 -Node: Host15218 -Node: Native18808 -Node: Target24139 -Node: Languages28075 -Node: Releases32842 -Node: Partial Symbol Tables34229 -Node: Types37887 -Node: BFD support for GDB39487 -Node: Symbol Reading40869 -Node: Cleanups44778 -Node: Wrapping46804 -Node: Frames48003 -Node: Remote Stubs49078 -Node: Longjmp Support50968 -Node: Coding Style51690 -Node: Clean Design53308 -Node: Submitting Patches59120 -Node: Host Conditionals63276 -Node: Target Conditionals72301 -Node: Native Conditionals89218 -Node: Obsolete Conditionals93665 -Node: XCOFF94768 - -End Tag Table diff --git a/gnu/dist/gdb/doc/gdbint.info-1 b/gnu/dist/gdb/doc/gdbint.info-1 deleted file mode 100644 index 7f09dc15dbea..000000000000 --- a/gnu/dist/gdb/doc/gdbint.info-1 +++ /dev/null @@ -1,1107 +0,0 @@ -This is Info file gdbint.info, produced by Makeinfo version 1.68 from -the input file ../../../devo/gdb/doc/gdbint.texinfo. - -START-INFO-DIR-ENTRY -* Gdb-Internals: (gdbint). The GNU debugger's internals. -END-INFO-DIR-ENTRY - - This file documents the internals of the GNU debugger GDB. - - Copyright 1990, 91, 92, 93, 94, 95, 96, 97, 1998 Free Software -Foundation, Inc. Contributed by Cygnus Support. Written by John -Gilmore. - - 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 or distribute modified versions of this -manual under the terms of the GPL (for which purpose this text may be -regarded as a program in the language TeX). - - -File: gdbint.info, Node: Top, Next: README, Up: (dir) - -Scope of this Document -********************** - - This document documents the internals of the GNU debugger, GDB. It -is intended to document aspects of GDB which apply across many different -parts of GDB (for example, *note Coding Style::.), or which are global -aspects of design (for example, what are the major modules and which -files document them in detail?). Information which pertains to specific -data structures, functions, variables, etc., should be put in comments -in the source code, not here. It is more likely to get noticed and kept -up to date there. Some of the information in this document should -probably be moved into comments. - -* Menu: - -* README:: The README File -* Getting Started:: Getting started working on GDB -* Debugging GDB:: Debugging GDB with itself -* New Architectures:: Defining a New Host or Target Architecture -* Config:: Adding a New Configuration -* Host:: Adding a New Host -* Native:: Adding a New Native Configuration -* Target:: Adding a New Target -* Languages:: Defining New Source Languages -* Releases:: Configuring GDB for Release -* Partial Symbol Tables:: How GDB reads symbols quickly at startup -* Types:: How GDB keeps track of types -* BFD support for GDB:: How BFD and GDB interface -* Symbol Reading:: Defining New Symbol Readers -* Cleanups:: Cleanups -* Wrapping:: Wrapping Output Lines -* Frames:: Keeping track of function calls -* Remote Stubs:: Code that runs in targets and talks to GDB -* Longjmp Support:: Stepping through longjmp's in the target -* Coding Style:: Strunk and White for GDB maintainers -* Clean Design:: Frank Lloyd Wright for GDB maintainers -* Submitting Patches:: How to get your changes into GDB releases -* Host Conditionals:: What features exist in the host -* Target Conditionals:: What features exist in the target -* Native Conditionals:: Conditionals for when host and target are same -* Obsolete Conditionals:: Conditionals that don't exist any more -* XCOFF:: The Object file format used on IBM's RS/6000 - - -File: gdbint.info, Node: README, Next: Getting Started, Prev: Top, Up: Top - -The `README' File -***************** - - Check the `README' file, it often has useful information that does -not appear anywhere else in the directory. - - -File: gdbint.info, Node: Getting Started, Next: Debugging GDB, Prev: README, Up: Top - -Getting Started Working on GDB -****************************** - - GDB is a large and complicated program, and if you first starting to -work on it, it can be hard to know where to start. Fortunately, if you -know how to go about it, there are ways to figure out what is going on: - - * This manual, the GDB Internals manual, has information which - applies generally to many parts of GDB. - - * Information about particular functions or data structures are - located in comments with those functions or data structures. If - you run across a function or a global variable which does not have - a comment correctly explaining what is does, this can be thought - of as a bug in GDB; feel free to submit a bug report, with a - suggested comment if you can figure out what the comment should - say (*note Submitting Patches::.). If you find a comment which is - actually wrong, be especially sure to report that. - - Comments explaining the function of macros defined in host, - target, or native dependent files can be in several places. - Sometimes they are repeated every place the macro is defined. - Sometimes they are where the macro is used. Sometimes there is a - header file which supplies a default definition of the macro, and - the comment is there. This manual also has a list of macros - (*note Host Conditionals::., *note Target Conditionals::., *note - Native Conditionals::., and *note Obsolete Conditionals::.) with - some documentation. - - * Start with the header files. Once you some idea of how GDB's - internal symbol tables are stored (see `symtab.h', `gdbtypes.h'), - you will find it much easier to understand the code which uses and - creates those symbol tables. - - * You may wish to process the information you are getting somehow, to - enhance your understanding of it. Summarize it, translate it to - another language, add some (perhaps trivial or non-useful) feature - to GDB, use the code to predict what a test case would do and - write the test case and verify your prediction, etc. If you are - reading code and your eyes are starting to glaze over, this is a - sign you need to use a more active approach. - - * Once you have a part of GDB to start with, you can find more - specifically the part you are looking for by stepping through each - function with the `next' command. Do not use `step' or you will - quickly get distracted; when the function you are stepping through - calls another function try only to get a big-picture understanding - (perhaps using the comment at the beginning of the function being - called) of what it does. This way you can identify which of the - functions being called by the function you are stepping through is - the one which you are interested in. You may need to examine the - data structures generated at each stage, with reference to the - comments in the header files explaining what the data structures - are supposed to look like. - - Of course, this same technique can be used if you are just reading - the code, rather than actually stepping through it. The same - general principle applies--when the code you are looking at calls - something else, just try to understand generally what the code - being called does, rather than worrying about all its details. - - * A good place to start when tracking down some particular area is - with a command which invokes that feature. Suppose you want to - know how single-stepping works. As a GDB user, you know that the - `step' command invokes single-stepping. The command is invoked - via command tables (see `command.h'); by convention the function - which actually performs the command is formed by taking the name - of the command and adding `_command', or in the case of an `info' - subcommand, `_info'. For example, the `step' command invokes the - `step_command' function and the `info display' command invokes - `display_info'. When this convention is not followed, you might - have to use `grep' or `M-x tags-search' in emacs, or run GDB on - itself and set a breakpoint in `execute_command'. - - * If all of the above fail, it may be appropriate to ask for - information on `bug-gdb'. But *never* post a generic question - like "I was wondering if anyone could give me some tips about - understanding GDB"--if we had some magic secret we would put it in - this manual. Suggestions for improving the manual are always - welcome, of course. - - Good luck! - - -File: gdbint.info, Node: Debugging GDB, Next: New Architectures, Prev: Getting Started, Up: Top - -Debugging GDB with itself -************************* - - If GDB is limping on your machine, this is the preferred way to get -it fully functional. Be warned that in some ancient Unix systems, like -Ultrix 4.2, a program can't be running in one process while it is being -debugged in another. Rather than typing the command `./gdb ./gdb', -which works on Suns and such, you can copy `gdb' to `gdb2' and then -type `./gdb ./gdb2'. - - When you run GDB in the GDB source directory, it will read a -`.gdbinit' file that sets up some simple things to make debugging gdb -easier. The `info' command, when executed without a subcommand in a -GDB being debugged by gdb, will pop you back up to the top level gdb. -See `.gdbinit' for details. - - If you use emacs, you will probably want to do a `make TAGS' after -you configure your distribution; this will put the machine dependent -routines for your local machine where they will be accessed first by -`M-.' - - Also, make sure that you've either compiled GDB with your local cc, -or have run `fixincludes' if you are compiling with gcc. - - -File: gdbint.info, Node: New Architectures, Next: Config, Prev: Debugging GDB, Up: Top - -Defining a New Host or Target Architecture -****************************************** - - When building support for a new host and/or target, much of the work -you need to do is handled by specifying configuration files; *note -Adding a New Configuration: Config.. Further work can be divided into -"host-dependent" (*note Adding a New Host: Host.) and -"target-dependent" (*note Adding a New Target: Target.). The following -discussion is meant to explain the difference between hosts and targets. - -What is considered "host-dependent" versus "target-dependent"? -============================================================== - - "Host" refers to attributes of the system where GDB runs. "Target" -refers to the system where the program being debugged executes. In -most cases they are the same machine, in which case a third type of -"Native" attributes come into play. - - Defines and include files needed to build on the host are host -support. Examples are tty support, system defined types, host byte -order, host float format. - - Defines and information needed to handle the target format are target -dependent. Examples are the stack frame format, instruction set, -breakpoint instruction, registers, and how to set up and tear down the -stack to call a function. - - Information that is only needed when the host and target are the -same, is native dependent. One example is Unix child process support; -if the host and target are not the same, doing a fork to start the -target process is a bad idea. The various macros needed for finding the -registers in the `upage', running `ptrace', and such are all in the -native-dependent files. - - Another example of native-dependent code is support for features -that are really part of the target environment, but which require -`#include' files that are only available on the host system. Core file -handling and `setjmp' handling are two common cases. - - When you want to make GDB work "native" on a particular machine, you -have to include all three kinds of information. - - The dependent information in GDB is organized into files by naming -conventions. - - Host-Dependent Files -`config/*/*.mh' - Sets Makefile parameters - -`config/*/xm-*.h' - Global #include's and #define's and definitions - -`*-xdep.c' - Global variables and functions - - Native-Dependent Files -`config/*/*.mh' - Sets Makefile parameters (for *both* host and native) - -`config/*/nm-*.h' - #include's and #define's and definitions. This file is only - included by the small number of modules that need it, so beware of - doing feature-test #define's from its macros. - -`*-nat.c' - global variables and functions - - Target-Dependent Files -`config/*/*.mt' - Sets Makefile parameters - -`config/*/tm-*.h' - Global #include's and #define's and definitions - -`*-tdep.c' - Global variables and functions - - At this writing, most supported hosts have had their host and native -dependencies sorted out properly. There are a few stragglers, which -can be recognized by the absence of NATDEPFILES lines in their -`config/*/*.mh'. - - -File: gdbint.info, Node: Config, Next: Host, Prev: New Architectures, Up: Top - -Adding a New Configuration -************************** - - Most of the work in making GDB compile on a new machine is in -specifying the configuration of the machine. This is done in a -dizzying variety of header files and configuration scripts, which we -hope to make more sensible soon. Let's say your new host is called an -XXX (e.g. `sun4'), and its full three-part configuration name is -`XARCH-XVEND-XOS' (e.g. `sparc-sun-sunos4'). In particular: - - In the top level directory, edit `config.sub' and add XARCH, XVEND, -and XOS to the lists of supported architectures, vendors, and operating -systems near the bottom of the file. Also, add XXX as an alias that -maps to `XARCH-XVEND-XOS'. You can test your changes by running - - ./config.sub XXX - -and - ./config.sub `XARCH-XVEND-XOS' - -which should both respond with `XARCH-XVEND-XOS' and no error messages. - - Now, go to the `bfd' directory and create a new file -`bfd/hosts/h-XXX.h'. Examine the other `h-*.h' files as templates, and -create one that brings in the right include files for your system, and -defines any host-specific macros needed by BFD, the Binutils, GNU LD, -or the Opcodes directories. (They all share the bfd `hosts' directory -and the `configure.host' file.) - - Then edit `bfd/configure.host'. Add a line to recognize your -`XARCH-XVEND-XOS' configuration, and set `my_host' to XXX when you -recognize it. This will cause your file `h-XXX.h' to be linked to -`sysdep.h' at configuration time. When creating the line that -recognizes your configuration, only match the fields that you really -need to match; e.g. don't match the architecture or manufacturer if the -OS is sufficient to distinguish the configuration that your `h-XXX.h' -file supports. Don't match the manufacturer name unless you really -need to. This should make future ports easier. - - Also, if this host requires any changes to the Makefile, create a -file `bfd/config/XXX.mh', which includes the required lines. - - It's possible that the `libiberty' and `readline' directories won't -need any changes for your configuration, but if they do, you can change -the `configure.in' file there to recognize your system and map to an -`mh-XXX' file. Then add `mh-XXX' to the `config/' subdirectory, to set -any makefile variables you need. The only current options in there are -things like `-DSYSV'. (This `mh-XXX' naming convention differs from -elsewhere in GDB, by historical accident. It should be cleaned up so -that all such files are called `XXX.mh'.) - - Aha! Now to configure GDB itself! Edit `gdb/configure.in' to -recognize your system and set `gdb_host' to XXX, and (unless your -desired target is already available) also set `gdb_target' to something -appropriate (for instance, XXX). To handle new hosts, modify the -segment after the comment `# per-host'; to handle new targets, modify -after `# per-target'. - - Finally, you'll need to specify and define GDB's host-, native-, and -target-dependent `.h' and `.c' files used for your configuration; the -next two chapters discuss those. - - -File: gdbint.info, Node: Host, Next: Native, Prev: Config, Up: Top - -Adding a New Host -***************** - - Once you have specified a new configuration for your host (*note -Adding a New Configuration: Config.), there are three remaining pieces -to making GDB work on a new machine. First, you have to make it host -on the new machine (compile there, handle that machine's terminals -properly, etc). If you will be cross-debugging to some other kind of -system that's already supported, you are done. - - If you want to use GDB to debug programs that run on the new machine, -you have to get it to understand the machine's object files, symbol -files, and interfaces to processes; *note Adding a New Target: Target. -and *note Adding a New Native Configuration: Native. - - Several files control GDB's configuration for host systems: - -`gdb/config/ARCH/XXX.mh' - Specifies Makefile fragments needed when hosting on machine XXX. - In particular, this lists the required machine-dependent object - files, by defining `XDEPFILES=...'. Also specifies the header - file which describes host XXX, by defining `XM_FILE= xm-XXX.h'. - You can also define `CC', `REGEX' and `REGEX1', `SYSV_DEFINE', - `XM_CFLAGS', `XM_ADD_FILES', `XM_CLIBS', `XM_CDEPS', etc.; see - `Makefile.in'. - -`gdb/config/ARCH/xm-XXX.h' - (`xm.h' is a link to this file, created by configure). Contains C - macro definitions describing the host system environment, such as - byte order, host C compiler and library, ptrace support, and core - file structure. Crib from existing `xm-*.h' files to create a new - one. - -`gdb/XXX-xdep.c' - Contains any miscellaneous C code required for this machine as a - host. On many machines it doesn't exist at all. If it does - exist, put `XXX-xdep.o' into the `XDEPFILES' line in - `gdb/config/mh-XXX'. - -Generic Host Support Files --------------------------- - - There are some "generic" versions of routines that can be used by -various systems. These can be customized in various ways by macros -defined in your `xm-XXX.h' file. If these routines work for the XXX -host, you can just include the generic file's name (with `.o', not -`.c') in `XDEPFILES'. - - Otherwise, if your machine needs custom support routines, you will -need to write routines that perform the same functions as the generic -file. Put them into `XXX-xdep.c', and put `XXX-xdep.o' into -`XDEPFILES'. - -`ser-bsd.c' - This contains serial line support for Berkeley-derived Unix - systems. - -`ser-go32.c' - This contains serial line support for 32-bit programs running - under DOS using the GO32 execution environment. - -`ser-termios.c' - This contains serial line support for System V-derived Unix - systems. - - Now, you are now ready to try configuring GDB to compile using your -system as its host. From the top level (above `bfd', `gdb', etc), do: - - ./configure XXX --target=vxworks960 - - This will configure your system to cross-compile for VxWorks on the -Intel 960, which is probably not what you really want, but it's a test -case that works at this stage. (You haven't set up to be able to debug -programs that run *on* XXX yet.) - - If this succeeds, you can try building it all with: - - make - - Repeat until the program configures, compiles, links, and runs. -When run, it won't be able to do much (unless you have a VxWorks/960 -board on your network) but you will know that the host support is -pretty well done. - - Good luck! Comments and suggestions about this section are -particularly welcome; send them to `bug-gdb@prep.ai.mit.edu'. - - -File: gdbint.info, Node: Native, Next: Target, Prev: Host, Up: Top - -Adding a New Native Configuration -********************************* - - If you are making GDB run native on the XXX machine, you have plenty -more work to do. Several files control GDB's configuration for native -support: - -`gdb/config/XARCH/XXX.mh' - Specifies Makefile fragments needed when hosting *or native* on - machine XXX. In particular, this lists the required - native-dependent object files, by defining `NATDEPFILES=...'. Also - specifies the header file which describes native support on XXX, - by defining `NAT_FILE= nm-XXX.h'. You can also define - `NAT_CFLAGS', `NAT_ADD_FILES', `NAT_CLIBS', `NAT_CDEPS', etc.; see - `Makefile.in'. - -`gdb/config/ARCH/nm-XXX.h' - (`nm.h' is a link to this file, created by configure). Contains C - macro definitions describing the native system environment, such - as child process control and core file support. Crib from - existing `nm-*.h' files to create a new one. - -`gdb/XXX-nat.c' - Contains any miscellaneous C code required for this native support - of this machine. On some machines it doesn't exist at all. - -Generic Native Support Files ----------------------------- - - There are some "generic" versions of routines that can be used by -various systems. These can be customized in various ways by macros -defined in your `nm-XXX.h' file. If these routines work for the XXX -host, you can just include the generic file's name (with `.o', not -`.c') in `NATDEPFILES'. - - Otherwise, if your machine needs custom support routines, you will -need to write routines that perform the same functions as the generic -file. Put them into `XXX-nat.c', and put `XXX-nat.o' into -`NATDEPFILES'. - -`inftarg.c' - This contains the *target_ops vector* that supports Unix child - processes on systems which use ptrace and wait to control the - child. - -`procfs.c' - This contains the *target_ops vector* that supports Unix child - processes on systems which use /proc to control the child. - -`fork-child.c' - This does the low-level grunge that uses Unix system calls to do a - "fork and exec" to start up a child process. - -`infptrace.c' - This is the low level interface to inferior processes for systems - using the Unix `ptrace' call in a vanilla way. - -`core-aout.c::fetch_core_registers()' - Support for reading registers out of a core file. This routine - calls `register_addr()', see below. Now that BFD is used to read - core files, virtually all machines should use `core-aout.c', and - should just provide `fetch_core_registers' in `XXX-nat.c' (or - `REGISTER_U_ADDR' in `nm-XXX.h'). - -`core-aout.c::register_addr()' - If your `nm-XXX.h' file defines the macro `REGISTER_U_ADDR(addr, - blockend, regno)', it should be defined to set `addr' to the - offset within the `user' struct of GDB register number `regno'. - `blockend' is the offset within the "upage" of `u.u_ar0'. If - `REGISTER_U_ADDR' is defined, `core-aout.c' will define the - `register_addr()' function and use the macro in it. If you do not - define `REGISTER_U_ADDR', but you are using the standard - `fetch_core_registers()', you will need to define your own version - of `register_addr()', put it into your `XXX-nat.c' file, and be - sure `XXX-nat.o' is in the `NATDEPFILES' list. If you have your - own `fetch_core_registers()', you may not need a separate - `register_addr()'. Many custom `fetch_core_registers()' - implementations simply locate the registers themselves. - - When making GDB run native on a new operating system, to make it -possible to debug core files, you will need to either write specific -code for parsing your OS's core files, or customize `bfd/trad-core.c'. -First, use whatever `#include' files your machine uses to define the -struct of registers that is accessible (possibly in the u-area) in a -core file (rather than `machine/reg.h'), and an include file that -defines whatever header exists on a core file (e.g. the u-area or a -`struct core'). Then modify `trad_unix_core_file_p()' to use these -values to set up the section information for the data segment, stack -segment, any other segments in the core file (perhaps shared library -contents or control information), "registers" segment, and if there are -two discontiguous sets of registers (e.g. integer and float), the -"reg2" segment. This section information basically delimits areas in -the core file in a standard way, which the section-reading routines in -BFD know how to seek around in. - - Then back in GDB, you need a matching routine called -`fetch_core_registers()'. If you can use the generic one, it's in -`core-aout.c'; if not, it's in your `XXX-nat.c' file. It will be -passed a char pointer to the entire "registers" segment, its length, -and a zero; or a char pointer to the entire "regs2" segment, its -length, and a 2. The routine should suck out the supplied register -values and install them into GDB's "registers" array. (*Note Defining -a New Host or Target Architecture: New Architectures, for more info -about this.) - - If your system uses `/proc' to control processes, and uses ELF -format core files, then you may be able to use the same routines for -reading the registers out of processes and out of core files. - - -File: gdbint.info, Node: Target, Next: Languages, Prev: Native, Up: Top - -Adding a New Target -******************* - - For a new target called TTT, first specify the configuration as -described in *Note Adding a New Configuration: Config. If your new -target is the same as your new host, you've probably already done that. - - A variety of files specify attributes of the GDB target environment: - -`gdb/config/ARCH/TTT.mt' - Contains a Makefile fragment specific to this target. Specifies - what object files are needed for target TTT, by defining - `TDEPFILES=...'. Also specifies the header file which describes - TTT, by defining `TM_FILE= tm-TTT.h'. You can also define - `TM_CFLAGS', `TM_CLIBS', `TM_CDEPS', and other Makefile variables - here; see `Makefile.in'. - -`gdb/config/ARCH/tm-TTT.h' - (`tm.h' is a link to this file, created by configure). Contains - macro definitions about the target machine's registers, stack - frame format and instructions. Crib from existing `tm-*.h' files - when building a new one. - -`gdb/TTT-tdep.c' - Contains any miscellaneous code required for this target machine. - On some machines it doesn't exist at all. Sometimes the macros in - `tm-TTT.h' become very complicated, so they are implemented as - functions here instead, and the macro is simply defined to call - the function. - -`gdb/exec.c' - Defines functions for accessing files that are executable on the - target system. These functions open and examine an exec file, - extract data from one, write data to one, print information about - one, etc. Now that executable files are handled with BFD, every - target should be able to use the generic exec.c rather than its - own custom code. - -`gdb/config/ARCH/tm-ARCH.h' - This often exists to describe the basic layout of the target - machine's processor chip (registers, stack, etc). If used, it is - included by `tm-XXX.h'. It can be shared among many targets that - use the same processor. - -`gdb/ARCH-tdep.c' - Similarly, there are often common subroutines that are shared by - all target machines that use this particular architecture. - - When adding support for a new target machine, there are various areas -of support that might need change, or might be OK. - - If you are using an existing object file format (a.out or COFF), -there is probably little to be done. See `bfd/doc/bfd.texinfo' for -more information on writing new a.out or COFF versions. - - If you need to add a new object file format, you must first add it to -BFD. This is beyond the scope of this document right now. Basically -you must build a transfer vector (of type `bfd_target'), which will -mean writing all the required routines, and add it to the list in -`bfd/targets.c'. - - You must then arrange for the BFD code to provide access to the -debugging symbols. Generally GDB will have to call swapping routines -from BFD and a few other BFD internal routines to locate the debugging -information. As much as possible, GDB should not depend on the BFD -internal data structures. - - For some targets (e.g., COFF), there is a special transfer vector -used to call swapping routines, since the external data structures on -various platforms have different sizes and layouts. Specialized -routines that will only ever be implemented by one object file format -may be called directly. This interface should be described in a file -`bfd/libxxx.h', which is included by GDB. - - If you are adding a new operating system for an existing CPU chip, -add a `tm-XOS.h' file that describes the operating system facilities -that are unusual (extra symbol table info; the breakpoint instruction -needed; etc). Then write a `tm-XARCH-XOS.h' that just `#include's -`tm-XARCH.h' and `tm-XOS.h'. (Now that we have three-part -configuration names, this will probably get revised to separate the XOS -configuration from the XARCH configuration.) - - -File: gdbint.info, Node: Languages, Next: Releases, Prev: Target, Up: Top - -Adding a Source Language to GDB -******************************* - - To add other languages to GDB's expression parser, follow the -following steps: - -*Create the expression parser.* - This should reside in a file `LANG-exp.y'. Routines for building - parsed expressions into a `union exp_element' list are in - `parse.c'. - - Since we can't depend upon everyone having Bison, and YACC produces - parsers that define a bunch of global names, the following lines - *must* be included at the top of the YACC parser, to prevent the - various parsers from defining the same global names: - - #define yyparse LANG_parse - #define yylex LANG_lex - #define yyerror LANG_error - #define yylval LANG_lval - #define yychar LANG_char - #define yydebug LANG_debug - #define yypact LANG_pact - #define yyr1 LANG_r1 - #define yyr2 LANG_r2 - #define yydef LANG_def - #define yychk LANG_chk - #define yypgo LANG_pgo - #define yyact LANG_act - #define yyexca LANG_exca - #define yyerrflag LANG_errflag - #define yynerrs LANG_nerrs - - At the bottom of your parser, define a `struct language_defn' and - initialize it with the right values for your language. Define an - `initialize_LANG' routine and have it call - `add_language(LANG_language_defn)' to tell the rest of GDB that - your language exists. You'll need some other supporting variables - and functions, which will be used via pointers from your - `LANG_language_defn'. See the declaration of `struct - language_defn' in `language.h', and the other `*-exp.y' files, for - more information. - -*Add any evaluation routines, if necessary* - If you need new opcodes (that represent the operations of the - language), add them to the enumerated type in `expression.h'. Add - support code for these operations in `eval.c:evaluate_subexp()'. - Add cases for new opcodes in two functions from `parse.c': - `prefixify_subexp()' and `length_of_subexp()'. These compute the - number of `exp_element's that a given operation takes up. - -*Update some existing code* - Add an enumerated identifier for your language to the enumerated - type `enum language' in `defs.h'. - - Update the routines in `language.c' so your language is included. - These routines include type predicates and such, which (in some - cases) are language dependent. If your language does not appear - in the switch statement, an error is reported. - - Also included in `language.c' is the code that updates the variable - `current_language', and the routines that translate the - `language_LANG' enumerated identifier into a printable string. - - Update the function `_initialize_language' to include your - language. This function picks the default language upon startup, - so is dependent upon which languages that GDB is built for. - - Update `allocate_symtab' in `symfile.c' and/or symbol-reading code - so that the language of each symtab (source file) is set properly. - This is used to determine the language to use at each stack frame - level. Currently, the language is set based upon the extension of - the source file. If the language can be better inferred from the - symbol information, please set the language of the symtab in the - symbol-reading code. - - Add helper code to `expprint.c:print_subexp()' to handle any new - expression opcodes you have added to `expression.h'. Also, add the - printed representations of your operators to `op_print_tab'. - -*Add a place of call* - Add a call to `LANG_parse()' and `LANG_error' in - `parse.c:parse_exp_1()'. - -*Use macros to trim code* - The user has the option of building GDB for some or all of the - languages. If the user decides to build GDB for the language - LANG, then every file dependent on `language.h' will have the - macro `_LANG_LANG' defined in it. Use `#ifdef's to leave out - large routines that the user won't need if he or she is not using - your language. - - Note that you do not need to do this in your YACC parser, since if - GDB is not build for LANG, then `LANG-exp.tab.o' (the compiled - form of your parser) is not linked into GDB at all. - - See the file `configure.in' for how GDB is configured for different - languages. - -*Edit `Makefile.in'* - Add dependencies in `Makefile.in'. Make sure you update the macro - variables such as `HFILES' and `OBJS', otherwise your code may not - get linked in, or, worse yet, it may not get `tar'red into the - distribution! - - -File: gdbint.info, Node: Releases, Next: Partial Symbol Tables, Prev: Languages, Up: Top - -Configuring GDB for Release -*************************** - - From the top level directory (containing `gdb', `bfd', `libiberty', -and so on): - make -f Makefile.in gdb.tar.gz - - This will properly configure, clean, rebuild any files that are -distributed pre-built (e.g. `c-exp.tab.c' or `refcard.ps'), and will -then make a tarfile. (If the top level directory has already been -configured, you can just do `make gdb.tar.gz' instead.) - - This procedure requires: - * symbolic links - - * `makeinfo' (texinfo2 level) - - * TeX - - * `dvips' - - * `yacc' or `bison' - -... and the usual slew of utilities (`sed', `tar', etc.). - -TEMPORARY RELEASE PROCEDURE FOR DOCUMENTATION ---------------------------------------------- - - `gdb.texinfo' is currently marked up using the texinfo-2 macros, -which are not yet a default for anything (but we have to start using -them sometime). - - For making paper, the only thing this implies is the right -generation of `texinfo.tex' needs to be included in the distribution. - - For making info files, however, rather than duplicating the texinfo2 -distribution, generate `gdb-all.texinfo' locally, and include the files -`gdb.info*' in the distribution. Note the plural; `makeinfo' will -split the document into one overall file and five or so included files. - - -File: gdbint.info, Node: Partial Symbol Tables, Next: Types, Prev: Releases, Up: Top - -Partial Symbol Tables -********************* - - GDB has three types of symbol tables. - - * full symbol tables (symtabs). These contain the main information - about symbols and addresses. - - * partial symbol tables (psymtabs). These contain enough - information to know when to read the corresponding part of the - full symbol table. - - * minimal symbol tables (msymtabs). These contain information - gleaned from non-debugging symbols. - - This section describes partial symbol tables. - - A psymtab is constructed by doing a very quick pass over an -executable file's debugging information. Small amounts of information -are extracted - enough to identify which parts of the symbol table will -need to be re-read and fully digested later, when the user needs the -information. The speed of this pass causes GDB to start up very -quickly. Later, as the detailed rereading occurs, it occurs in small -pieces, at various times, and the delay therefrom is mostly invisible to -the user. (*Note Symbol Reading::.) - - The symbols that show up in a file's psymtab should be, roughly, -those visible to the debugger's user when the program is not running -code from that file. These include external symbols and types, static -symbols and types, and enum values declared at file scope. - - The psymtab also contains the range of instruction addresses that the -full symbol table would represent. - - The idea is that there are only two ways for the user (or much of -the code in the debugger) to reference a symbol: - - * by its address (e.g. execution stops at some address which is - inside a function in this file). The address will be noticed to - be in the range of this psymtab, and the full symtab will be read - in. `find_pc_function', `find_pc_line', and other `find_pc_...' - functions handle this. - - * by its name (e.g. the user asks to print a variable, or set a - breakpoint on a function). Global names and file-scope names will - be found in the psymtab, which will cause the symtab to be pulled - in. Local names will have to be qualified by a global name, or a - file-scope name, in which case we will have already read in the - symtab as we evaluated the qualifier. Or, a local symbol can be - referenced when we are "in" a local scope, in which case the first - case applies. `lookup_symbol' does most of the work here. - - The only reason that psymtabs exist is to cause a symtab to be read -in at the right moment. Any symbol that can be elided from a psymtab, -while still causing that to happen, should not appear in it. Since -psymtabs don't have the idea of scope, you can't put local symbols in -them anyway. Psymtabs don't have the idea of the type of a symbol, -either, so types need not appear, unless they will be referenced by -name. - - It is a bug for GDB to behave one way when only a psymtab has been -read, and another way if the corresponding symtab has been read in. -Such bugs are typically caused by a psymtab that does not contain all -the visible symbols, or which has the wrong instruction address ranges. - - The psymtab for a particular section of a symbol-file (objfile) -could be thrown away after the symtab has been read in. The symtab -should always be searched before the psymtab, so the psymtab will never -be used (in a bug-free environment). Currently, psymtabs are allocated -on an obstack, and all the psymbols themselves are allocated in a pair -of large arrays on an obstack, so there is little to be gained by -trying to free them unless you want to do a lot more work. - - -File: gdbint.info, Node: Types, Next: BFD support for GDB, Prev: Partial Symbol Tables, Up: Top - -Types -***** - - Fundamental Types (e.g., FT_VOID, FT_BOOLEAN). - - These are the fundamental types that GDB uses internally. -Fundamental types from the various debugging formats (stabs, ELF, etc) -are mapped into one of these. They are basically a union of all -fundamental types that gdb knows about for all the languages that GDB -knows about. - - Type Codes (e.g., TYPE_CODE_PTR, TYPE_CODE_ARRAY). - - Each time GDB builds an internal type, it marks it with one of these -types. The type may be a fundamental type, such as TYPE_CODE_INT, or a -derived type, such as TYPE_CODE_PTR which is a pointer to another type. -Typically, several FT_* types map to one TYPE_CODE_* type, and are -distinguished by other members of the type struct, such as whether the -type is signed or unsigned, and how many bits it uses. - - Builtin Types (e.g., builtin_type_void, builtin_type_char). - - These are instances of type structs that roughly correspond to -fundamental types and are created as global types for GDB to use for -various ugly historical reasons. We eventually want to eliminate -these. Note for example that builtin_type_int initialized in -gdbtypes.c is basically the same as a TYPE_CODE_INT type that is -initialized in c-lang.c for an FT_INTEGER fundamental type. The -difference is that the builtin_type is not associated with any -particular objfile, and only one instance exists, while c-lang.c builds -as many TYPE_CODE_INT types as needed, with each one associated with -some particular objfile. - - -File: gdbint.info, Node: BFD support for GDB, Next: Symbol Reading, Prev: Types, Up: Top - -Binary File Descriptor Library Support for GDB -********************************************** - - BFD provides support for GDB in several ways: - -*identifying executable and core files* - BFD will identify a variety of file types, including a.out, coff, - and several variants thereof, as well as several kinds of core - files. - -*access to sections of files* - BFD parses the file headers to determine the names, virtual - addresses, sizes, and file locations of all the various named - sections in files (such as the text section or the data section). - GDB simply calls BFD to read or write section X at byte offset Y - for length Z. - -*specialized core file support* - BFD provides routines to determine the failing command name stored - in a core file, the signal with which the program failed, and - whether a core file matches (i.e. could be a core dump of) a - particular executable file. - -*locating the symbol information* - GDB uses an internal interface of BFD to determine where to find - the symbol information in an executable file or symbol-file. GDB - itself handles the reading of symbols, since BFD does not - "understand" debug symbols, but GDB uses BFD's cached information - to find the symbols, string table, etc. - - -File: gdbint.info, Node: Symbol Reading, Next: Cleanups, Prev: BFD support for GDB, Up: Top - -Symbol Reading -************** - - GDB reads symbols from "symbol files". The usual symbol file is the -file containing the program which GDB is debugging. GDB can be directed -to use a different file for symbols (with the "symbol-file" command), -and it can also read more symbols via the "add-file" and "load" -commands, or while reading symbols from shared libraries. - - Symbol files are initially opened by `symfile.c' using the BFD -library. BFD identifies the type of the file by examining its header. -`symfile_init' then uses this identification to locate a set of -symbol-reading functions. - - Symbol reading modules identify themselves to GDB by calling -`add_symtab_fns' during their module initialization. The argument to -`add_symtab_fns' is a `struct sym_fns' which contains the name (or name -prefix) of the symbol format, the length of the prefix, and pointers to -four functions. These functions are called at various times to process -symbol-files whose identification matches the specified prefix. - - The functions supplied by each module are: - -`XXX_symfile_init(struct sym_fns *sf)' - Called from `symbol_file_add' when we are about to read a new - symbol file. This function should clean up any internal state - (possibly resulting from half-read previous files, for example) - and prepare to read a new symbol file. Note that the symbol file - which we are reading might be a new "main" symbol file, or might - be a secondary symbol file whose symbols are being added to the - existing symbol table. - - The argument to `XXX_symfile_init' is a newly allocated `struct - sym_fns' whose `bfd' field contains the BFD for the new symbol - file being read. Its `private' field has been zeroed, and can be - modified as desired. Typically, a struct of private information - will be `malloc''d, and a pointer to it will be placed in the - `private' field. - - There is no result from `XXX_symfile_init', but it can call - `error' if it detects an unavoidable problem. - -`XXX_new_init()' - Called from `symbol_file_add' when discarding existing symbols. - This function need only handle the symbol-reading module's - internal state; the symbol table data structures visible to the - rest of GDB will be discarded by `symbol_file_add'. It has no - arguments and no result. It may be called after - `XXX_symfile_init', if a new symbol table is being read, or may be - called alone if all symbols are simply being discarded. - -`XXX_symfile_read(struct sym_fns *sf, CORE_ADDR addr, int mainline)' - Called from `symbol_file_add' to actually read the symbols from a - symbol-file into a set of psymtabs or symtabs. - - `sf' points to the struct sym_fns originally passed to - `XXX_sym_init' for possible initialization. `addr' is the offset - between the file's specified start address and its true address in - memory. `mainline' is 1 if this is the main symbol table being - read, and 0 if a secondary symbol file (e.g. shared library or - dynamically loaded file) is being read. - - In addition, if a symbol-reading module creates psymtabs when -XXX_symfile_read is called, these psymtabs will contain a pointer to a -function `XXX_psymtab_to_symtab', which can be called from any point in -the GDB symbol-handling code. - -`XXX_psymtab_to_symtab (struct partial_symtab *pst)' - Called from `psymtab_to_symtab' (or the PSYMTAB_TO_SYMTAB macro) - if the psymtab has not already been read in and had its - `pst->symtab' pointer set. The argument is the psymtab to be - fleshed-out into a symtab. Upon return, pst->readin should have - been set to 1, and pst->symtab should contain a pointer to the new - corresponding symtab, or zero if there were no symbols in that - part of the symbol file. - - -File: gdbint.info, Node: Cleanups, Next: Wrapping, Prev: Symbol Reading, Up: Top - -Cleanups -******** - - Cleanups are a structured way to deal with things that need to be -done later. When your code does something (like `malloc' some memory, -or open a file) that needs to be undone later (e.g. free the memory or -close the file), it can make a cleanup. The cleanup will be done at -some future point: when the command is finished, when an error occurs, -or when your code decides it's time to do cleanups. - - You can also discard cleanups, that is, throw them away without doing -what they say. This is only done if you ask that it be done. - - Syntax: - -`struct cleanup *OLD_CHAIN;' - Declare a variable which will hold a cleanup chain handle. - -`OLD_CHAIN = make_cleanup (FUNCTION, ARG);' - Make a cleanup which will cause FUNCTION to be called with ARG (a - `char *') later. The result, OLD_CHAIN, is a handle that can be - passed to `do_cleanups' or `discard_cleanups' later. Unless you - are going to call `do_cleanups' or `discard_cleanups' yourself, - you can ignore the result from `make_cleanup'. - -`do_cleanups (OLD_CHAIN);' - Perform all cleanups done since `make_cleanup' returned OLD_CHAIN. - E.g.: - make_cleanup (a, 0); - old = make_cleanup (b, 0); - do_cleanups (old); - - will call `b()' but will not call `a()'. The cleanup that calls - `a()' will remain in the cleanup chain, and will be done later - unless otherwise discarded. - -`discard_cleanups (OLD_CHAIN);' - Same as `do_cleanups' except that it just removes the cleanups - from the chain and does not call the specified functions. - - Some functions, e.g. `fputs_filtered()' or `error()', specify that -they "should not be called when cleanups are not in place". This means -that any actions you need to reverse in the case of an error or -interruption must be on the cleanup chain before you call these -functions, since they might never return to your code (they `longjmp' -instead). - - -File: gdbint.info, Node: Wrapping, Next: Frames, Prev: Cleanups, Up: Top - -Wrapping Output Lines -********************* - - Output that goes through `printf_filtered' or `fputs_filtered' or -`fputs_demangled' needs only to have calls to `wrap_here' added in -places that would be good breaking points. The utility routines will -take care of actually wrapping if the line width is exceeded. - - The argument to `wrap_here' is an indentation string which is printed -*only* if the line breaks there. This argument is saved away and used -later. It must remain valid until the next call to `wrap_here' or -until a newline has been printed through the `*_filtered' functions. -Don't pass in a local variable and then return! - - It is usually best to call `wrap_here()' after printing a comma or -space. If you call it before printing a space, make sure that your -indentation properly accounts for the leading space that will print if -the line wraps there. - - Any function or set of functions that produce filtered output must -finish by printing a newline, to flush the wrap buffer, before -switching to unfiltered ("`printf'") output. Symbol reading routines -that print warnings are a good example. - - -File: gdbint.info, Node: Frames, Next: Remote Stubs, Prev: Wrapping, Up: Top - -Frames -****** - - A frame is a construct that GDB uses to keep track of calling and -called functions. - -`FRAME_FP' - in the machine description has no meaning to the - machine-independent part of GDB, except that it is used when - setting up a new frame from scratch, as follows: - - create_new_frame (read_register (FP_REGNUM), read_pc ())); - - Other than that, all the meaning imparted to `FP_REGNUM' is - imparted by the machine-dependent code. So, `FP_REGNUM' can have - any value that is convenient for the code that creates new frames. - (`create_new_frame' calls `INIT_EXTRA_FRAME_INFO' if it is - defined; that is where you should use the `FP_REGNUM' value, if - your frames are nonstandard.) - -`FRAME_CHAIN' - Given a GDB frame, determine the address of the calling function's - frame. This will be used to create a new GDB frame struct, and - then `INIT_EXTRA_FRAME_INFO' and `INIT_FRAME_PC' will be called for - the new frame. - diff --git a/gnu/dist/gdb/doc/gdbint.info-2 b/gnu/dist/gdb/doc/gdbint.info-2 deleted file mode 100644 index 256cf24f90fd..000000000000 --- a/gnu/dist/gdb/doc/gdbint.info-2 +++ /dev/null @@ -1,1320 +0,0 @@ -This is Info file gdbint.info, produced by Makeinfo version 1.68 from -the input file ../../../devo/gdb/doc/gdbint.texinfo. - -START-INFO-DIR-ENTRY -* Gdb-Internals: (gdbint). The GNU debugger's internals. -END-INFO-DIR-ENTRY - - This file documents the internals of the GNU debugger GDB. - - Copyright 1990, 91, 92, 93, 94, 95, 96, 97, 1998 Free Software -Foundation, Inc. Contributed by Cygnus Support. Written by John -Gilmore. - - 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 or distribute modified versions of this -manual under the terms of the GPL (for which purpose this text may be -regarded as a program in the language TeX). - - -File: gdbint.info, Node: Remote Stubs, Next: Longjmp Support, Prev: Frames, Up: Top - -Remote Stubs -************ - - GDB's file `remote.c' talks a serial protocol to code that runs in -the target system. GDB provides several sample "stubs" that can be -integrated into target programs or operating systems for this purpose; -they are named `*-stub.c'. - - The GDB user's manual describes how to put such a stub into your -target code. What follows is a discussion of integrating the SPARC stub -into a complicated operating system (rather than a simple program), by -Stu Grossman, the author of this stub. - - The trap handling code in the stub assumes the following upon entry -to trap_low: - - 1. %l1 and %l2 contain pc and npc respectively at the time of the trap - - 2. traps are disabled - - 3. you are in the correct trap window - - As long as your trap handler can guarantee those conditions, then -there is no reason why you shouldn't be able to `share' traps with the -stub. The stub has no requirement that it be jumped to directly from -the hardware trap vector. That is why it calls `exceptionHandler()', -which is provided by the external environment. For instance, this -could setup the hardware traps to actually execute code which calls the -stub first, and then transfers to its own trap handler. - - For the most point, there probably won't be much of an issue with -`sharing' traps, as the traps we use are usually not used by the -kernel, and often indicate unrecoverable error conditions. Anyway, -this is all controlled by a table, and is trivial to modify. The most -important trap for us is for `ta 1'. Without that, we can't single -step or do breakpoints. Everything else is unnecessary for the proper -operation of the debugger/stub. - - From reading the stub, it's probably not obvious how breakpoints -work. They are simply done by deposit/examine operations from GDB. - - -File: gdbint.info, Node: Longjmp Support, Next: Coding Style, Prev: Remote Stubs, Up: Top - -Longjmp Support -*************** - - GDB has support for figuring out that the target is doing a -`longjmp' and for stopping at the target of the jump, if we are -stepping. This is done with a few specialized internal breakpoints, -which are visible in the `maint info breakpoint' command. - - To make this work, you need to define a macro called -`GET_LONGJMP_TARGET', which will examine the `jmp_buf' structure and -extract the longjmp target address. Since `jmp_buf' is target -specific, you will need to define it in the appropriate `tm-xxx.h' -file. Look in `tm-sun4os4.h' and `sparc-tdep.c' for examples of how to -do this. - - -File: gdbint.info, Node: Coding Style, Next: Clean Design, Prev: Longjmp Support, Up: Top - -Coding Style -************ - - GDB is generally written using the GNU coding standards, as -described in `standards.texi', which is available for anonymous FTP -from GNU archive sites. There are some additional considerations for -GDB maintainers that reflect the unique environment and style of GDB -maintenance. If you follow these guidelines, GDB will be more -consistent and easier to maintain. - - GDB's policy on the use of prototypes is that prototypes are used to -*declare* functions but never to *define* them. Simple macros are used -in the declarations, so that a non-ANSI compiler can compile GDB -without trouble. The simple macro calls are used like this: - - extern int - memory_remove_breakpoint PARAMS ((CORE_ADDR, char *)); - - Note the double parentheses around the parameter types. This allows -an arbitrary number of parameters to be described, without freaking out -the C preprocessor. When the function has no parameters, it should be -described like: - - void - noprocess PARAMS ((void)); - - The `PARAMS' macro expands to its argument in ANSI C, or to a simple -`()' in traditional C. - - All external functions should have a `PARAMS' declaration in a -header file that callers include. All static functions should have such -a declaration near the top of their source file. - - We don't have a gcc option that will properly check that these rules -have been followed, but it's GDB policy, and we periodically check it -using the tools available (plus manual labor), and clean up any -remnants. - - -File: gdbint.info, Node: Clean Design, Next: Submitting Patches, Prev: Coding Style, Up: Top - -Clean Design -************ - - In addition to getting the syntax right, there's the little question -of semantics. Some things are done in certain ways in GDB because long -experience has shown that the more obvious ways caused various kinds of -trouble. In particular: - -* - You can't assume the byte order of anything that comes from a - target (including VALUEs, object files, and instructions). Such - things must be byte-swapped using `SWAP_TARGET_AND_HOST' in GDB, - or one of the swap routines defined in `bfd.h', such as - `bfd_get_32'. - -* - You can't assume that you know what interface is being used to - talk to the target system. All references to the target must go - through the current `target_ops' vector. - -* - You can't assume that the host and target machines are the same - machine (except in the "native" support modules). In particular, - you can't assume that the target machine's header files will be - available on the host machine. Target code must bring along its - own header files - written from scratch or explicitly donated by - their owner, to avoid copyright problems. - -* - Insertion of new `#ifdef''s will be frowned upon. It's much better - to write the code portably than to conditionalize it for various - systems. - -* - New `#ifdef''s which test for specific compilers or manufacturers - or operating systems are unacceptable. All `#ifdef''s should test - for features. The information about which configurations contain - which features should be segregated into the configuration files. - Experience has proven far too often that a feature unique to one - particular system often creeps into other systems; and that a - conditional based on some predefined macro for your current system - will become worthless over time, as new versions of your system - come out that behave differently with regard to this feature. - -* - Adding code that handles specific architectures, operating - systems, target interfaces, or hosts, is not acceptable in generic - code. If a hook is needed at that point, invent a generic hook - and define it for your configuration, with something like: - - #ifdef WRANGLE_SIGNALS - WRANGLE_SIGNALS (signo); - #endif - - In your host, target, or native configuration file, as appropriate, - define `WRANGLE_SIGNALS' to do the machine-dependent thing. Take - a bit of care in defining the hook, so that it can be used by other - ports in the future, if they need a hook in the same place. - - If the hook is not defined, the code should do whatever "most" - machines want. Using `#ifdef', as above, is the preferred way to - do this, but sometimes that gets convoluted, in which case use - - #ifndef SPECIAL_FOO_HANDLING - #define SPECIAL_FOO_HANDLING(pc, sp) (0) - #endif - - where the macro is used or in an appropriate header file. - - Whether to include a "small" hook, a hook around the exact pieces - of code which are system-dependent, or whether to replace a whole - function with a hook depends on the case. A good example of this - dilemma can be found in `get_saved_register'. All machines that - GDB 2.8 ran on just needed the `FRAME_FIND_SAVED_REGS' hook to - find the saved registers. Then the SPARC and Pyramid came along, - and `HAVE_REGISTER_WINDOWS' and `REGISTER_IN_WINDOW_P' were - introduced. Then the 29k and 88k required the `GET_SAVED_REGISTER' - hook. The first three are examples of small hooks; the latter - replaces a whole function. In this specific case, it is useful to - have both kinds; it would be a bad idea to replace all the uses of - the small hooks with `GET_SAVED_REGISTER', since that would result - in much duplicated code. Other times, duplicating a few lines of - code here or there is much cleaner than introducing a large number - of small hooks. - - Another way to generalize GDB along a particular interface is with - an attribute struct. For example, GDB has been generalized to - handle multiple kinds of remote interfaces - not by #ifdef's - everywhere, but by defining the "target_ops" structure and having - a current target (as well as a stack of targets below it, for - memory references). Whenever something needs to be done that - depends on which remote interface we are using, a flag in the - current target_ops structure is tested (e.g. `target_has_stack'), - or a function is called through a pointer in the current - target_ops structure. In this way, when a new remote interface is - added, only one module needs to be touched - the one that actually - implements the new remote interface. Other examples of - attribute-structs are BFD access to multiple kinds of object file - formats, or GDB's access to multiple source languages. - - Please avoid duplicating code. For example, in GDB 3.x all the - code interfacing between `ptrace' and the rest of GDB was - duplicated in `*-dep.c', and so changing something was very - painful. In GDB 4.x, these have all been consolidated into - `infptrace.c'. `infptrace.c' can deal with variations between - systems the same way any system-independent file would (hooks, #if - defined, etc.), and machines which are radically different don't - need to use infptrace.c at all. - -* - *Do* write code that doesn't depend on the sizes of C data types, - the format of the host's floating point numbers, the alignment of - anything, or the order of evaluation of expressions. In short, - follow good programming practices for writing portable C code. - - -File: gdbint.info, Node: Submitting Patches, Next: Host Conditionals, Prev: Clean Design, Up: Top - -Submitting Patches -****************** - - Thanks for thinking of offering your changes back to the community of -GDB users. In general we like to get well designed enhancements. -Thanks also for checking in advance about the best way to transfer the -changes. - - The two main problems with getting your patches in are, - -* - The GDB maintainers will only install "cleanly designed" patches. - You may not always agree on what is clean design. *note Coding - Style::., *note Clean Design::.. - -* - If the maintainers don't have time to put the patch in when it - arrives, or if there is any question about a patch, it goes into a - large queue with everyone else's patches and bug reports. - - I don't know how to get past these problems except by continuing to -try. - - There are two issues here - technical and legal. - - The legal issue is that to incorporate substantial changes requires a -copyright assignment from you and/or your employer, granting ownership -of the changes to the Free Software Foundation. You can get the -standard document for doing this by sending mail to -`gnu@prep.ai.mit.edu' and asking for it. I recommend that people write -in "All programs owned by the Free Software Foundation" as "NAME OF -PROGRAM", so that changes in many programs (not just GDB, but GAS, -Emacs, GCC, etc) can be contributed with only one piece of legalese -pushed through the bureacracy and filed with the FSF. I can't start -merging changes until this paperwork is received by the FSF (their -rules, which I follow since I maintain it for them). - - Technically, the easiest way to receive changes is to receive each -feature as a small context diff or unidiff, suitable for "patch". Each -message sent to me should include the changes to C code and header -files for a single feature, plus ChangeLog entries for each directory -where files were modified, and diffs for any changes needed to the -manuals (gdb/doc/gdb.texi or gdb/doc/gdbint.texi). If there are a lot -of changes for a single feature, they can be split down into multiple -messages. - - In this way, if I read and like the feature, I can add it to the -sources with a single patch command, do some testing, and check it in. -If you leave out the ChangeLog, I have to write one. If you leave out -the doc, I have to puzzle out what needs documenting. Etc. - - The reason to send each change in a separate message is that I will -not install some of the changes. They'll be returned to you with -questions or comments. If I'm doing my job, my message back to you -will say what you have to fix in order to make the change acceptable. -The reason to have separate messages for separate features is so that -other changes (which I *am* willing to accept) can be installed while -one or more changes are being reworked. If multiple features are sent -in a single message, I tend to not put in the effort to sort out the -acceptable changes from the unacceptable, so none of the features get -installed until all are acceptable. - - If this sounds painful or authoritarian, well, it is. But I get a -lot of bug reports and a lot of patches, and most of them don't get -installed because I don't have the time to finish the job that the bug -reporter or the contributor could have done. Patches that arrive -complete, working, and well designed, tend to get installed on the day -they arrive. The others go into a queue and get installed if and when -I scan back over the queue - which can literally take months sometimes. -It's in both our interests to make patch installation easy - you get -your changes installed, and I make some forward progress on GDB in a -normal 12-hour day (instead of them having to wait until I have a -14-hour or 16-hour day to spend cleaning up patches before I can -install them). - - Please send patches to `bug-gdb@prep.ai.mit.edu', if they are less -than about 25,000 characters. If longer than that, either make them -available somehow (e.g. anonymous FTP), and announce it on `bug-gdb', -or send them directly to the GDB maintainers at -`gdb-patches@cygnus.com'. - - -File: gdbint.info, Node: Host Conditionals, Next: Target Conditionals, Prev: Submitting Patches, Up: Top - -Host Conditionals -***************** - - When GDB is configured and compiled, various macros are defined or -left undefined, to control compilation based on the attributes of the -host system. These macros and their meanings (or if the meaning is not -documented here, then one of the source files where they are used is -indicated) are: - -`GDBINIT_FILENAME' - The default name of GDB's initialization file (normally - `.gdbinit'). - -`MEM_FNS_DECLARED' - Your host config file defines this if it includes declarations of - `memcpy' and `memset'. Define this to avoid conflicts between the - native include files and the declarations in `defs.h'. - -`NO_SYS_FILE' - Define this if your system does not have a `'. - -`SIGWINCH_HANDLER' - If your host defines `SIGWINCH', you can define this to be the - name of a function to be called if `SIGWINCH' is received. - -`SIGWINCH_HANDLER_BODY' - Define this to expand into code that will define the function - named by the expansion of `SIGWINCH_HANDLER'. - -`ALIGN_STACK_ON_STARTUP' - Define this if your system is of a sort that will crash in - `tgetent' if the stack happens not to be longword-aligned when - `main' is called. This is a rare situation, but is known to occur - on several different types of systems. - -`CRLF_SOURCE_FILES' - Define this if host files use `\r\n' rather than `\n' as a line - terminator. This will cause source file listings to omit `\r' - characters when printing. It must be possible to open files in - binary mode using `O_BINARY' or, for fopen, `"rb"'. - -`DEFAULT_PROMPT' - The default value of the prompt string (normally `"(gdb) "'). - -`DEV_TTY' - The name of the generic TTY device, defaults to `"/dev/tty"'. - -`FCLOSE_PROVIDED' - Define this if the system declares `fclose' in the headers - included in `defs.h'. This isn't needed unless your compiler is - unusually anal. - -`FOPEN_RB' - Define this if binary files are opened the same way as text files. - -`GETENV_PROVIDED' - Define this if the system declares `getenv' in its headers - included in `defs.h'. This isn't needed unless your compiler is - unusually anal. - -`HAVE_MMAP' - In some cases, use the system call `mmap' for reading symbol - tables. For some machines this allows for sharing and quick - updates. - -`HAVE_SIGSETMASK' - Define this if the host system has job control, but does not - define `sigsetmask()'. Currently, this is only true of the - RS/6000. - -`HAVE_TERMIO' - Define this if the host system has `termio.h'. - -`HOST_BYTE_ORDER' - The ordering of bytes in the host. This must be defined to be - either `BIG_ENDIAN' or `LITTLE_ENDIAN'. - -`INT_MAX' - -`INT_MIN' - -`LONG_MAX' - -`UINT_MAX' - -`ULONG_MAX' - Values for host-side constants. - -`ISATTY' - Substitute for isatty, if not available. - -`KERNEL_U_ADDR' - Define this to the address of the `u' structure (the "user struct", - also known as the "u-page") in kernel virtual memory. GDB needs - to know this so that it can subtract this address from absolute - addresses in the upage, that are obtained via ptrace or from core - files. On systems that don't need this value, set it to zero. - -`KERNEL_U_ADDR_BSD' - Define this to cause GDB to determine the address of `u' at - runtime, by using Berkeley-style `nlist' on the kernel's image in - the root directory. - -`KERNEL_U_ADDR_HPUX' - Define this to cause GDB to determine the address of `u' at - runtime, by using HP-style `nlist' on the kernel's image in the - root directory. - -`LONGEST' - This is the longest integer type available on the host. If not - defined, it will default to `long long' or `long', depending on - `CC_HAS_LONG_LONG'. - -`CC_HAS_LONG_LONG' - Define this if the host C compiler supports "long long". This is - set by the configure script. - -`PRINTF_HAS_LONG_LONG' - Define this if the host can handle printing of long long integers - via the printf format directive "ll". This is set by the configure - script. - -`HAVE_LONG_DOUBLE' - Define this if the host C compiler supports "long double". This - is set by the configure script. - -`PRINTF_HAS_LONG_DOUBLE' - Define this if the host can handle printing of long double - float-point numbers via the printf format directive "Lg". This is - set by the configure script. - -`SCANF_HAS_LONG_DOUBLE' - Define this if the host can handle the parsing of long double - float-point numbers via the scanf format directive directive "Lg". - This is set by the configure script. - -`LSEEK_NOT_LINEAR' - Define this if `lseek (n)' does not necessarily move to byte number - `n' in the file. This is only used when reading source files. It - is normally faster to define `CRLF_SOURCE_FILES' when possible. - -`L_SET' - This macro is used as the argument to lseek (or, most commonly, - bfd_seek). FIXME, should be replaced by SEEK_SET instead, which - is the POSIX equivalent. - -`MAINTENANCE_CMDS' - If the value of this is 1, then a number of optional maintenance - commands are compiled in. - -`MALLOC_INCOMPATIBLE' - Define this if the system's prototype for `malloc' differs from the - ANSI definition. - -`MMAP_BASE_ADDRESS' - When using HAVE_MMAP, the first mapping should go at this address. - -`MMAP_INCREMENT' - when using HAVE_MMAP, this is the increment between mappings. - -`NEED_POSIX_SETPGID' - Define this to use the POSIX version of `setpgid' to determine - whether job control is available. - -`NORETURN' - If defined, this should be one or more tokens, such as `volatile', - that can be used in both the declaration and definition of - functions to indicate that they never return. The default is - already set correctly if compiling with GCC. This will almost - never need to be defined. - -`ATTR_NORETURN' - If defined, this should be one or more tokens, such as - `__attribute__ ((noreturn))', that can be used in the declarations - of functions to indicate that they never return. The default is - already set correctly if compiling with GCC. This will almost - never need to be defined. - -`USE_MMALLOC' - GDB will use the `mmalloc' library for memory allocation for symbol - reading if this symbol is defined. Be careful defining it since - there are systems on which `mmalloc' does not work for some - reason. One example is the DECstation, where its RPC library - can't cope with our redefinition of `malloc' to call `mmalloc'. - When defining `USE_MMALLOC', you will also have to set `MMALLOC' - in the Makefile, to point to the mmalloc library. This define is - set when you configure with -with-mmalloc. - -`NO_MMCHECK' - Define this if you are using `mmalloc', but don't want the overhead - of checking the heap with `mmcheck'. Note that on some systems, - the C runtime makes calls to malloc prior to calling `main', and if - `free' is ever called with these pointers after calling `mmcheck' - to enable checking, a memory corruption abort is certain to occur. - These systems can still use mmalloc, but must define NO_MMCHECK. - -`MMCHECK_FORCE' - Define this to 1 if the C runtime allocates memory prior to - `mmcheck' being called, but that memory is never freed so we don't - have to worry about it triggering a memory corruption abort. The - default is 0, which means that `mmcheck' will only install the - heap checking functions if there has not yet been any memory - allocation calls, and if it fails to install the functions, gdb - will issue a warning. This is currently defined if you configure - using -with-mmalloc. - -`NO_SIGINTERRUPT' - Define this to indicate that siginterrupt() is not available. - -`R_OK' - Define if this is not in a system .h file. - -`SEEK_CUR' - -`SEEK_SET' - Define these to appropriate value for the system lseek(), if not - already defined. - -`STOP_SIGNAL' - This is the signal for stopping GDB. Defaults to SIGTSTP. (Only - redefined for the Convex.) - -`USE_O_NOCTTY' - ??? - -`USG' - Means that System V (prior to SVR4) include files are in use. - (FIXME: This symbol is abused in `infrun.c', `regex.c', - `remote-nindy.c', and `utils.c' for other things, at the moment.) - -`lint' - Define this to help lint in some stupid way. - -`volatile' - Define this to override the defaults of `__volatile__' or `/**/'. - - Platform-specific host conditionals. - -`ALTOS_AS' - xm-altos.h - -`MOTOROLA' - xm-altos.h - -`NBPG' - altos-xdep.c - -`DELTA88' - m88k-xdep.c - -`DGUX' - m88k-xdep.c - -`F_OK' - xm-ultra3.h - -`UPAGES' - altos-xdep.c - - Regex conditionals. - -`C_ALLOCA' - regex.c - -`NFAILURES' - regex.c - -`RE_NREGS' - regex.h - -`SIGN_EXTEND_CHAR' - regex.c - -`SWITCH_ENUM_BUG' - regex.c - -`SYNTAX_TABLE' - regex.c - -`Sword' - regex.c - -`sparc' - regex.c - - -File: gdbint.info, Node: Target Conditionals, Next: Native Conditionals, Prev: Host Conditionals, Up: Top - -Target Conditionals -******************* - - When GDB is configured and compiled, various macros are defined or -left undefined, to control compilation based on the attributes of the -target system. These macros and their meanings are: - -`ADDITIONAL_OPTIONS' - -`ADDITIONAL_OPTION_CASES' - -`ADDITIONAL_OPTION_HANDLER' - -`ADDITIONAL_OPTION_HELP' - These are a set of macros that allow the addition of additional - command line options to GDB. They are currently used only for the - unsupported i960 Nindy target, and should not be used in any other - configuration. - -`ADDR_BITS_REMOVE (addr)' - If a raw machine address includes any bits that are not really part - of the address, then define this macro to expand into an expression - that zeros those bits in ADDR. For example, the two low-order - bits of a Motorola 88K address may be used by some kernels for - their own purposes, since addresses must always be 4-byte aligned, - and so are of no use for addressing. Those bits should be - filtered out with an expression such as `((addr) & ~3)'. - -`BEFORE_MAIN_LOOP_HOOK' - Define this to expand into any code that you want to execute before - the main loop starts. Although this is not, strictly speaking, a - target conditional, that is how it is currently being used. Note - that if a configuration were to define it one way for a host and a - different way for the target, GDB will probably not compile, let - alone run correctly. - -`BELIEVE_PCC_PROMOTION' - coffread.c - -`BELIEVE_PCC_PROMOTION_TYPE' - stabsread.c - -`BITS_BIG_ENDIAN' - Define this if the numbering of bits in the targets does *not* - match the endianness of the target byte order. A value of 1 means - that the bits are numbered in a big-endian order, 0 means - little-endian. - -`BREAKPOINT' - This is the character array initializer for the bit pattern to put - into memory where a breakpoint is set. Although it's common to - use a trap instruction for a breakpoint, it's not required; for - instance, the bit pattern could be an invalid instruction. The - breakpoint must be no longer than the shortest instruction of the - architecture. - -`BIG_BREAKPOINT' - -`LITTLE_BREAKPOINT' - Similar to BREAKPOINT, but used for bi-endian targets. - -`CALL_DUMMY' - valops.c - -`CALL_DUMMY_LOCATION' - inferior.h - -`CALL_DUMMY_STACK_ADJUST' - valops.c - -`CANNOT_FETCH_REGISTER (regno)' - A C expression that should be nonzero if REGNO cannot be fetched - from an inferior process. This is only relevant if - `FETCH_INFERIOR_REGISTERS' is not defined. - -`CANNOT_STORE_REGISTER (regno)' - A C expression that should be nonzero if REGNO should not be - written to the target. This is often the case for program - counters, status words, and other special registers. If this is - not defined, GDB will assume that all registers may be written. - -`CHILL_PRODUCER' - -`GCC_PRODUCER' - -`GPLUS_PRODUCER' - -`LCC_PRODUCER' - If defined, these are the producer strings in a DWARF 1 file. All - of these have reasonable defaults already. - -`DO_DEFERRED_STORES' - -`CLEAR_DEFERRED_STORES' - Define this to execute any deferred stores of registers into the - inferior, and to cancel any deferred stores. - - Currently only implemented correctly for native Sparc - configurations? - -`CPLUS_MARKER' - Define this to expand into the character that G++ uses to - distinguish compiler-generated identifiers from - programmer-specified identifiers. By default, this expands into - `'$''. Most System V targets should define this to `'.''. - -`DBX_PARM_SYMBOL_CLASS' - Hook for the `SYMBOL_CLASS' of a parameter when decoding DBX symbol - information. In the i960, parameters can be stored as locals or as - args, depending on the type of the debug record. - -`DECR_PC_AFTER_BREAK' - Define this to be the amount by which to decrement the PC after - the program encounters a breakpoint. This is often the number of - bytes in BREAKPOINT, though not always. For most targets this - value will be 0. - -`DECR_PC_AFTER_HW_BREAK' - Similarly, for hardware breakpoints. - -`DISABLE_UNSETTABLE_BREAK addr' - If defined, this should evaluate to 1 if ADDR is in a shared - library in which breakpoints cannot be set and so should be - disabled. - -`DO_REGISTERS_INFO' - If defined, use this to print the value of a register or all - registers. - -`END_OF_TEXT_DEFAULT' - This is an expression that should designate the end of the text - section (? FIXME ?) - -`EXTRACT_RETURN_VALUE' - tm-m68k.h - -`EXTRACT_STRUCT_VALUE_ADDRESS' - values.c - -`EXTRA_FRAME_INFO' - If defined, this must be a list of slots that may be inserted into - the `frame_info' structure defined in `frame.h'. - -`EXTRA_SYMTAB_INFO' - If defined, this must be a list of slots that may be inserted into - the `symtab' structure defined in `symtab.h'. - -`FLOAT_INFO' - If defined, then the `info float' command will print information - about the processor's floating point unit. - -`FP_REGNUM' - The number of the frame pointer register. - -`FRAMELESS_FUNCTION_INVOCATION' - blockframe.c - -`FRAME_ARGS_ADDRESS_CORRECT' - stack.c - -`FRAME_CHAIN' - Given FRAME, return a pointer to the calling frame. - -`FRAME_CHAIN_COMBINE' - blockframe.c - -`FRAME_CHAIN_VALID' - frame.h - -`FRAME_CHAIN_VALID_ALTERNATE' - frame.h - -`FRAME_FIND_SAVED_REGS' - stack.c - -`FRAME_NUM_ARGS (val, fi)' - For the frame described by fi, set val to the number of arguments - that are being passed. - -`FRAME_SPECIFICATION_DYADIC' - stack.c - -`FRAME_SAVED_PC' - Given FRAME, return the pc saved there. That is, the return - address. - -`FUNCTION_EPILOGUE_SIZE' - For some COFF targets, the `x_sym.x_misc.x_fsize' field of the - function end symbol is 0. For such targets, you must define - `FUNCTION_EPILOGUE_SIZE' to expand into the standard size of a - function's epilogue. - -`GCC_COMPILED_FLAG_SYMBOL' - -`GCC2_COMPILED_FLAG_SYMBOL' - If defined, these are the names of the symbols that GDB will look - for to detect that GCC compiled the file. The default symbols are - `gcc_compiled.' and `gcc2_compiled.', respectively. (Currently - only defined for the Delta 68.) - -`GDB_TARGET_IS_HPPA' - This determines whether horrible kludge code in dbxread.c and - partial-stab.h is used to mangle multiple-symbol-table files from - HPPA's. This should all be ripped out, and a scheme like - elfread.c used. - -`GDB_TARGET_IS_MACH386' - mach386-xdep.c - -`GDB_TARGET_IS_SUN3' - a68v-xdep.c - -`GDB_TARGET_IS_SUN386' - sun386-xdep.c - -`GET_LONGJMP_TARGET' - For most machines, this is a target-dependent parameter. On the - DECstation and the Iris, this is a native-dependent parameter, - since is needed to define it. - - This macro determines the target PC address that longjmp() will - jump to, assuming that we have just stopped at a longjmp - breakpoint. It takes a CORE_ADDR * as argument, and stores the - target PC value through this pointer. It examines the current - state of the machine as needed. - -`GET_SAVED_REGISTER' - Define this if you need to supply your own definition for the - function `get_saved_register'. Currently this is only done for - the a29k. - -`GR64_REGNUM' - Very a29k-specific. - -`HAVE_REGISTER_WINDOWS' - Define this if the target has register windows. - -`REGISTER_IN_WINDOW_P regnum' - Define this to be an expression that is 1 is the given register is - in the window. - -`IBM6000_TARGET' - Shows that we are configured for an IBM RS/6000 target. This - conditional should be eliminated (FIXME) and replaced by - feature-specific macros. It was introduced in haste and we are - repenting at leisure. - -`IEEE_FLOAT' - Define this if the target system uses IEEE-format floating point - numbers. - -`IGNORE_SYMBOL type' - This seems to be no longer used. - -`INIT_EXTRA_FRAME_INFO (fromleaf, fci)' - If defined, this should be a C expression or statement that fills - in the `EXTRA_FRAME_INFO' slots of the given frame FCI. - -`INIT_EXTRA_SYMTAB_INFO' - symfile.c - -`INIT_FRAME_PC (fromleaf, prev)' - This is a C statement that sets the pc of the frame pointed to by - PREV. [By default...] - -`INNER_THAN' - Define this to be either `<' if the target's stack grows downward - in memory, or `>' is the stack grows upwards. - -`IN_SIGTRAMP (pc name)' - Define this to return true if the given pc and/or name indicates - that the current function is a sigtramp. - -`SIGTRAMP_START (pc)' - -`SIGTRAMP_END (pc)' - Define these to be the start and end address of the sigtramp for - the given pc. On machines where the address is just a compile - time constant, the macro expansion will typically just ignore the - supplied pc. - -`IN_SOLIB_TRAMPOLINE pc name' - Define this to evaluate to nonzero if the program is stopped in - the trampoline that connects to a shared library. - -`IS_TRAPPED_INTERNALVAR name' - This is an ugly hook to allow the specification of special actions - that should occur as a side-effect of setting the value of a - variable internal to GDB. Currently only used by the h8500. Note - that this could be either a host or target conditional. - -`KERNEL_DEBUGGING' - tm-ultra3.h - -`MIPSEL' - mips-tdep.c - -`NEED_TEXT_START_END' - Define this if GDB should determine the start and end addresses of - the text section. (Seems dubious.) - -`KERNEL_DEBUGGING' - -`NO_HIF_SUPPORT' - (Specific to the a29k.) - -`NO_SINGLE_STEP' - Define this if the target does not support single-stepping. If - this is defined, you must supply, in `*-tdep.c', the function - `single_step', which takes a target_signal as argument and returns - nothing. It must insert breakpoints at each possible destinations - of the next instruction. See `sparc-tdep.c' and `rs6000-tdep.c' - for examples. - -`PCC_SOL_BROKEN' - (Used only in the Convex target.) - -`PC_IN_CALL_DUMMY' - inferior.h - -`PC_LOAD_SEGMENT' - If defined, print information about the load segment for the - program counter. (Defined only for the RS/6000.) - -`PC_REGNUM' - If the program counter is kept in a register, then define this - macro to be the number of that register. This need be defined - only if `TARGET_WRITE_PC' is not defined. - -`NPC_REGNUM' - The number of the "next program counter" register, if defined. - -`NNPC_REGNUM' - The number of the "next next program counter" register, if defined. - Currently, this is only defined for the Motorola 88K. - -`PRINT_REGISTER_HOOK (regno)' - If defined, this must be a function that prints the contents of the - given register to standard output. - -`PRINT_TYPELESS_INTEGER' - This is an obscure substitute for `print_longest' that seems to - have been defined for the Convex target. - -`PROCESS_LINENUMBER_HOOK' - A hook defined for XCOFF reading. - -`PROLOGUE_FIRSTLINE_OVERLAP' - (Only used in unsupported Convex configuration.) - -`PS_REGNUM' - If defined, this is the number of the processor status register. - (This definition is only used in generic code when parsing "$ps".) - -`POP_FRAME' - Used in `call_function_by_hand' to remove an artificial stack - frame. - -`PUSH_ARGUMENTS (nargs, args, sp, struct_return, struct_addr)' - Define this to push arguments onto the stack for inferior function - call. - -`PUSH_DUMMY_FRAME' - Used in `call_function_by_hand' to create an artificial stack - frame. - -`REGISTER_BYTES' - The total amount of space needed to store GDB's copy of the - machine's register state. - -`REGISTER_NAMES' - Define this to expand into an initializer of an array of strings. - Each string is the name of a register. [more detail] - -`REG_STRUCT_HAS_ADDR (gcc_p, type)' - Define this to return 1 if the given type will be passed by pointer - rather than directly. - -`SDB_REG_TO_REGNUM' - Define this to convert sdb register numbers into GDB regnums. If - not defined, no conversion will be done. - -`SHIFT_INST_REGS' - (Only used for m88k targets.) - -`SKIP_PROLOGUE' - A C statement that advances the PC across any function entry - prologue instructions so as to reach "real" code. - -`SKIP_PROLOGUE_FRAMELESS_P' - A C statement that should behave similarly, but that can stop as - soon as the function is known to have a frame. If not defined, - `SKIP_PROLOGUE' will be used instead. - -`SKIP_TRAMPOLINE_CODE (pc)' - If the target machine has trampoline code that sits between callers - and the functions being called, then define this macro to return a - new PC that is at the start of the real function. - -`SP_REGNUM' - Define this to be the number of the register that serves as the - stack pointer. - -`STAB_REG_TO_REGNUM' - Define this to convert stab register numbers (as gotten from `r' - declarations) into GDB regnums. If not defined, no conversion - will be done. - -`STACK_ALIGN (addr)' - Define this to adjust the address to the alignment required for the - processor's stack. - -`STEP_SKIPS_DELAY (addr)' - Define this to return true if the address is of an instruction - with a delay slot. If a breakpoint has been placed in the - instruction's delay slot, GDB will single-step over that - instruction before resuming normally. Currently only defined for - the Mips. - -`STORE_RETURN_VALUE (type, valbuf)' - A C expression that stores a function return value of type TYPE, - where VALBUF is the address of the value to be stored. - -`SUN_FIXED_LBRAC_BUG' - (Used only for Sun-3 and Sun-4 targets.) - -`SYMBOL_RELOADING_DEFAULT' - The default value of the `symbol-reloading' variable. (Never - defined in current sources.) - -`TARGET_BYTE_ORDER' - The ordering of bytes in the target. This must be defined to be - either `BIG_ENDIAN' or `LITTLE_ENDIAN'. - -`TARGET_CHAR_BIT' - Number of bits in a char; defaults to 8. - -`TARGET_COMPLEX_BIT' - Number of bits in a complex number; defaults to `2 * - TARGET_FLOAT_BIT'. - -`TARGET_DOUBLE_BIT' - Number of bits in a double float; defaults to `8 * - TARGET_CHAR_BIT'. - -`TARGET_DOUBLE_COMPLEX_BIT' - Number of bits in a double complex; defaults to `2 * - TARGET_DOUBLE_BIT'. - -`TARGET_FLOAT_BIT' - Number of bits in a float; defaults to `4 * TARGET_CHAR_BIT'. - -`TARGET_INT_BIT' - Number of bits in an integer; defaults to `4 * TARGET_CHAR_BIT'. - -`TARGET_LONG_BIT' - Number of bits in a long integer; defaults to `4 * - TARGET_CHAR_BIT'. - -`TARGET_LONG_DOUBLE_BIT' - Number of bits in a long double float; defaults to `2 * - TARGET_DOUBLE_BIT'. - -`TARGET_LONG_LONG_BIT' - Number of bits in a long long integer; defaults to `2 * - TARGET_LONG_BIT'. - -`TARGET_PTR_BIT' - Number of bits in a pointer; defaults to `TARGET_INT_BIT'. - -`TARGET_SHORT_BIT' - Number of bits in a short integer; defaults to `2 * - TARGET_CHAR_BIT'. - -`TARGET_READ_PC' - -`TARGET_WRITE_PC (val, pid)' - -`TARGET_READ_SP' - -`TARGET_WRITE_SP' - -`TARGET_READ_FP' - -`TARGET_WRITE_FP' - These change the behavior of `read_pc', `write_pc', `read_sp', - `write_sp', `read_fp' and `write_fp'. For most targets, these may - be left undefined. GDB will call the read and write register - functions with the relevant `_REGNUM' argument. - - These macros are useful when a target keeps one of these registers - in a hard to get at place; for example, part in a segment - register and part in an ordinary register. - -`USE_STRUCT_CONVENTION (gcc_p, type)' - If defined, this must be an expression that is nonzero if a value - of the given TYPE being returned from a function must have space - allocated for it on the stack. GCC_P is true if the function - being considered is known to have been compiled by GCC; this is - helpful for systems where GCC is known to use different calling - convention than other compilers. - -`VARIABLES_INSIDE_BLOCK (desc, gcc_p)' - For dbx-style debugging information, if the compiler puts variable - declarations inside LBRAC/RBRAC blocks, this should be defined to - be nonzero. DESC is the value of `n_desc' from the `N_RBRAC' - symbol, and GCC_P is true if GDB has noticed the presence of - either the `GCC_COMPILED_SYMBOL' or the `GCC2_COMPILED_SYMBOL'. - By default, this is 0. - -`OS9K_VARIABLES_INSIDE_BLOCK (desc, gcc_p)' - Similarly, for OS/9000. Defaults to 1. - -`WRS_ORIG' - remote-vx.c - -`test' - (Define this to enable testing code in regex.c.) - - Motorola M68K target conditionals. - -`BPT_VECTOR' - Define this to be the 4-bit location of the breakpoint trap vector. - If not defined, it will default to `0xf'. - -`REMOTE_BPT_VECTOR' - Defaults to `1'. - - -File: gdbint.info, Node: Native Conditionals, Next: Obsolete Conditionals, Prev: Target Conditionals, Up: Top - -Native Conditionals -******************* - - When GDB is configured and compiled, various macros are defined or -left undefined, to control compilation when the host and target systems -are the same. These macros should be defined (or left undefined) in -`nm-SYSTEM.h'. - -`ATTACH_DETACH' - If defined, then GDB will include support for the `attach' and - `detach' commands. - -`CHILD_PREPARE_TO_STORE' - If the machine stores all registers at once in the child process, - then define this to ensure that all values are correct. This - usually entails a read from the child. - - [Note that this is incorrectly defined in `xm-SYSTEM.h' files - currently.] - -`FETCH_INFERIOR_REGISTERS' - Define this if the native-dependent code will provide its own - routines `fetch_inferior_registers' and `store_inferior_registers' - in `HOST-nat.c'. If this symbol is *not* defined, and - `infptrace.c' is included in this configuration, the default - routines in `infptrace.c' are used for these functions. - -`FILES_INFO_HOOK' - (Only defined for Convex.) - -`FP0_REGNUM' - This macro is normally defined to be the number of the first - floating point register, if the machine has such registers. As - such, it would appear only in target-specific code. However, - /proc support uses this to decide whether floats are in use on - this target. - -`GET_LONGJMP_TARGET' - For most machines, this is a target-dependent parameter. On the - DECstation and the Iris, this is a native-dependent parameter, - since is needed to define it. - - This macro determines the target PC address that longjmp() will - jump to, assuming that we have just stopped at a longjmp - breakpoint. It takes a CORE_ADDR * as argument, and stores the - target PC value through this pointer. It examines the current - state of the machine as needed. - -`ONE_PROCESS_WRITETEXT' - Define this to be able to, when a breakpoint insertion fails, warn - the user that another process may be running with the same - executable. - -`PROC_NAME_FMT' - Defines the format for the name of a `/proc' device. Should be - defined in `nm.h' *only* in order to override the default - definition in `procfs.c'. - -`PTRACE_FP_BUG' - mach386-xdep.c - -`PTRACE_ARG3_TYPE' - The type of the third argument to the `ptrace' system call, if it - exists and is different from `int'. - -`REGISTER_U_ADDR' - Defines the offset of the registers in the "u area"; *note Host::.. - -`SHELL_COMMAND_CONCAT' - If defined, is a string to prefix on the shell command used to - start the inferior. - -`SHELL_FILE' - If defined, this is the name of the shell to use to run the - inferior. Defaults to `"/bin/sh"'. - -`SOLIB_ADD (filename, from_tty, targ)' - Define this to expand into an expression that will cause the - symbols in FILENAME to be added to GDB's symbol table. - -`SOLIB_CREATE_INFERIOR_HOOK' - Define this to expand into any shared-library-relocation code that - you want to be run just after the child process has been forked. - -`START_INFERIOR_TRAPS_EXPECTED' - When starting an inferior, GDB normally expects to trap twice; - once when the shell execs, and once when the program itself execs. - If the actual number of traps is something other than 2, then - define this macro to expand into the number expected. - -`SVR4_SHARED_LIBS' - Define this to indicate that SVR4-style shared libraries are in - use. - -`USE_PROC_FS' - This determines whether small routines in `*-tdep.c', which - translate register values between GDB's internal representation - and the /proc representation, are compiled. - -`U_REGS_OFFSET' - This is the offset of the registers in the upage. It need only be - defined if the generic ptrace register access routines in - `infptrace.c' are being used (that is, `infptrace.c' is configured - in, and `FETCH_INFERIOR_REGISTERS' is not defined). If the - default value from `infptrace.c' is good enough, leave it - undefined. - - The default value means that u.u_ar0 *points to* the location of - the registers. I'm guessing that `#define U_REGS_OFFSET 0' means - that u.u_ar0 *is* the location of the registers. - -`CLEAR_SOLIB' - objfiles.c - -`DEBUG_PTRACE' - Define this to debug ptrace calls. - - -File: gdbint.info, Node: Obsolete Conditionals, Next: XCOFF, Prev: Native Conditionals, Up: Top - -Obsolete Conditionals -********************* - - Fragments of old code in GDB sometimes reference or set the following -configuration macros. They should not be used by new code, and old -uses should be removed as those parts of the debugger are otherwise -touched. - -`STACK_END_ADDR' - This macro used to define where the end of the stack appeared, for - use in interpreting core file formats that don't record this - address in the core file itself. This information is now - configured in BFD, and GDB gets the info portably from there. The - values in GDB's configuration files should be moved into BFD - configuration files (if needed there), and deleted from all of - GDB's config files. - - Any `FOO-xdep.c' file that references STACK_END_ADDR is so old - that it has never been converted to use BFD. Now that's old! - -`PYRAMID_CONTROL_FRAME_DEBUGGING' - pyr-xdep.c - -`PYRAMID_CORE' - pyr-xdep.c - -`PYRAMID_PTRACE' - pyr-xdep.c - -`REG_STACK_SEGMENT' - exec.c - - -File: gdbint.info, Node: XCOFF, Prev: Obsolete Conditionals, Up: Top - -The XCOFF Object File Format -**************************** - - The IBM RS/6000 running AIX uses an object file format called xcoff. -The COFF sections, symbols, and line numbers are used, but debugging -symbols are dbx-style stabs whose strings are located in the `.debug' -section (rather than the string table). For more information, *Note -Top: (stabs)Top, and search for XCOFF. - - The shared library scheme has a nice clean interface for figuring out -what shared libraries are in use, but the catch is that everything which -refers to addresses (symbol tables and breakpoints at least) needs to be -relocated for both shared libraries and the main executable. At least -using the standard mechanism this can only be done once the program has -been run (or the core file has been read). - - diff --git a/gnu/dist/gdb/doc/stabs.info b/gnu/dist/gdb/doc/stabs.info deleted file mode 100644 index 2be706ee66fc..000000000000 --- a/gnu/dist/gdb/doc/stabs.info +++ /dev/null @@ -1,123 +0,0 @@ -This is Info file stabs.info, produced by Makeinfo version 1.68 from -the input file ../../../devo/gdb/doc/stabs.texinfo. - -START-INFO-DIR-ENTRY -* Stabs: (stabs). The "stabs" debugging information format. -END-INFO-DIR-ENTRY - - This document describes the stabs debugging symbol tables. - - Copyright 1992, 93, 94, 95, 1997 Free Software Foundation, Inc. -Contributed by Cygnus Support. Written by Julia Menapace, Jim Kingdon, -and David MacKenzie. - - 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 or distribute modified versions of this -manual under the terms of the GPL (for which purpose this text may be -regarded as a program in the language TeX). - - -Indirect: -stabs.info-1: 817 -stabs.info-2: 50524 -stabs.info-3: 99932 -stabs.info-4: 146210 - -Tag Table: -(Indirect) -Node: Top817 -Node: Overview1729 -Node: Flow3145 -Node: Stabs Format4666 -Node: String Field6223 -Node: C Example11486 -Node: Assembly Code12026 -Node: Program Structure13992 -Node: Main Program14717 -Node: Source Files15274 -Node: Include Files17099 -Node: Line Numbers19758 -Node: Procedures21289 -Node: Nested Procedures27177 -Node: Block Structure28348 -Node: Alternate Entry Points29750 -Node: Constants30478 -Node: Variables33591 -Node: Stack Variables34278 -Node: Global Variables35971 -Node: Register Variables37123 -Node: Common Blocks37940 -Node: Statics39190 -Node: Based Variables41766 -Node: Parameters43146 -Node: Register Parameters44753 -Node: Local Variable Parameters47006 -Node: Reference Parameters49913 -Node: Conformant Arrays50524 -Node: Types51232 -Node: Builtin Types52166 -Node: Traditional Builtin Types53306 -Node: Traditional Integer Types53699 -Node: Traditional Other Types55994 -Node: Builtin Type Descriptors56895 -Node: Negative Type Numbers60389 -Node: Miscellaneous Types66736 -Node: Cross-References68617 -Node: Subranges70289 -Node: Arrays71519 -Node: Strings74742 -Node: Enumerations75800 -Node: Structures78181 -Node: Typedefs80884 -Node: Unions82205 -Node: Function Types83774 -Node: Symbol Tables85350 -Node: Symbol Table Format85781 -Node: Transformations On Symbol Tables87224 -Node: Transformations On Static Variables88573 -Node: Transformations On Global Variables89300 -Node: Stab Section Transformations90534 -Node: Cplusplus91910 -Node: Class Names92489 -Node: Nested Symbols93230 -Node: Basic Cplusplus Types94072 -Node: Simple Classes95627 -Node: Class Instance99932 -Node: Methods100644 -Node: Method Type Descriptor102870 -Node: Member Type Descriptor103861 -Node: Protections104604 -Node: Method Modifiers107687 -Node: Virtual Methods109307 -Node: Inheritence113102 -Node: Virtual Base Classes116814 -Node: Static Members119051 -Node: Stab Types119514 -Node: Non-Stab Symbol Types120120 -Node: Stab Symbol Types121546 -Node: Symbol Descriptors125268 -Node: Type Descriptors128027 -Node: Expanded Reference131219 -Node: N_PC132618 -Node: N_NSYMS132987 -Node: N_NOMAP133219 -Node: N_M2C133516 -Node: N_BROWS133941 -Node: N_DEFD134215 -Node: N_EHDECL134663 -Node: N_MOD2134905 -Node: N_CATCH135134 -Node: N_SSYM135619 -Node: N_SCOPE135893 -Node: Gould136072 -Node: N_LENG137049 -Node: Questions137266 -Node: Stab Sections138886 -Node: Stab Section Basics139465 -Node: ELF Linker Relocation142803 -Node: Symbol Types Index146210 - -End Tag Table diff --git a/gnu/dist/gdb/doc/stabs.info-1 b/gnu/dist/gdb/doc/stabs.info-1 deleted file mode 100644 index e3d2f1c8d162..000000000000 --- a/gnu/dist/gdb/doc/stabs.info-1 +++ /dev/null @@ -1,1166 +0,0 @@ -This is Info file stabs.info, produced by Makeinfo version 1.68 from -the input file ../../../devo/gdb/doc/stabs.texinfo. - -START-INFO-DIR-ENTRY -* Stabs: (stabs). The "stabs" debugging information format. -END-INFO-DIR-ENTRY - - This document describes the stabs debugging symbol tables. - - Copyright 1992, 93, 94, 95, 1997 Free Software Foundation, Inc. -Contributed by Cygnus Support. Written by Julia Menapace, Jim Kingdon, -and David MacKenzie. - - 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 or distribute modified versions of this -manual under the terms of the GPL (for which purpose this text may be -regarded as a program in the language TeX). - - -File: stabs.info, Node: Top, Next: Overview, Up: (dir) - -The "stabs" representation of debugging information -*************************************************** - - This document describes the stabs debugging format. - -* Menu: - -* Overview:: Overview of stabs -* Program Structure:: Encoding of the structure of the program -* Constants:: Constants -* Variables:: -* Types:: Type definitions -* Symbol Tables:: Symbol information in symbol tables -* Cplusplus:: Stabs specific to C++ -* Stab Types:: Symbol types in a.out files -* Symbol Descriptors:: Table of symbol descriptors -* Type Descriptors:: Table of type descriptors -* Expanded Reference:: Reference information by stab type -* Questions:: Questions and anomolies -* Stab Sections:: In some object file formats, stabs are - in sections. -* Symbol Types Index:: Index of symbolic stab symbol type names. - - -File: stabs.info, Node: Overview, Next: Program Structure, Prev: Top, Up: Top - -Overview of Stabs -***************** - - "Stabs" refers to a format for information that describes a program -to a debugger. This format was apparently invented by Peter Kessler at -the University of California at Berkeley, for the `pdx' Pascal -debugger; the format has spread widely since then. - - This document is one of the few published sources of documentation on -stabs. It is believed to be comprehensive for stabs used by C. The -lists of symbol descriptors (*note Symbol Descriptors::.) and type -descriptors (*note Type Descriptors::.) are believed to be completely -comprehensive. Stabs for COBOL-specific features and for variant -records (used by Pascal and Modula-2) are poorly documented here. - - Other sources of information on stabs are `Dbx and Dbxtool -Interfaces', 2nd edition, by Sun, 1988, and `AIX Version 3.2 Files -Reference', Fourth Edition, September 1992, "dbx Stabstring Grammar" in -the a.out section, page 2-31. This document is believed to incorporate -the information from those two sources except where it explicitly -directs you to them for more information. - -* Menu: - -* Flow:: Overview of debugging information flow -* Stabs Format:: Overview of stab format -* String Field:: The string field -* C Example:: A simple example in C source -* Assembly Code:: The simple example at the assembly level - - -File: stabs.info, Node: Flow, Next: Stabs Format, Up: Overview - -Overview of Debugging Information Flow -====================================== - - The GNU C compiler compiles C source in a `.c' file into assembly -language in a `.s' file, which the assembler translates into a `.o' -file, which the linker combines with other `.o' files and libraries to -produce an executable file. - - With the `-g' option, GCC puts in the `.s' file additional debugging -information, which is slightly transformed by the assembler and linker, -and carried through into the final executable. This debugging -information describes features of the source file like line numbers, -the types and scopes of variables, and function names, parameters, and -scopes. - - For some object file formats, the debugging information is -encapsulated in assembler directives known collectively as "stab" -(symbol table) directives, which are interspersed with the generated -code. Stabs are the native format for debugging information in the -a.out and XCOFF object file formats. The GNU tools can also emit stabs -in the COFF and ECOFF object file formats. - - The assembler adds the information from stabs to the symbol -information it places by default in the symbol table and the string -table of the `.o' file it is building. The linker consolidates the `.o' -files into one executable file, with one symbol table and one string -table. Debuggers use the symbol and string tables in the executable as -a source of debugging information about the program. - - -File: stabs.info, Node: Stabs Format, Next: String Field, Prev: Flow, Up: Overview - -Overview of Stab Format -======================= - - There are three overall formats for stab assembler directives, -differentiated by the first word of the stab. The name of the directive -describes which combination of four possible data fields follows. It is -either `.stabs' (string), `.stabn' (number), or `.stabd' (dot). IBM's -XCOFF assembler uses `.stabx' (and some other directives such as -`.file' and `.bi') instead of `.stabs', `.stabn' or `.stabd'. - - The overall format of each class of stab is: - - .stabs "STRING",TYPE,OTHER,DESC,VALUE - .stabn TYPE,OTHER,DESC,VALUE - .stabd TYPE,OTHER,DESC - .stabx "STRING",VALUE,TYPE,SDB-TYPE - - For `.stabn' and `.stabd', there is no STRING (the `n_strx' field is -zero; see *Note Symbol Tables::). For `.stabd', the VALUE field is -implicit and has the value of the current file location. For `.stabx', -the SDB-TYPE field is unused for stabs and can always be set to zero. -The OTHER field is almost always unused and can be set to zero. - - The number in the TYPE field gives some basic information about -which type of stab this is (or whether it *is* a stab, as opposed to an -ordinary symbol). Each valid type number defines a different stab -type; further, the stab type defines the exact interpretation of, and -possible values for, any remaining STRING, DESC, or VALUE fields -present in the stab. *Note Stab Types::, for a list in numeric order -of the valid TYPE field values for stab directives. - - -File: stabs.info, Node: String Field, Next: C Example, Prev: Stabs Format, Up: Overview - -The String Field -================ - - For most stabs the string field holds the meat of the debugging -information. The flexible nature of this field is what makes stabs -extensible. For some stab types the string field contains only a name. -For other stab types the contents can be a great deal more complex. - - The overall format of the string field for most stab types is: - - "NAME:SYMBOL-DESCRIPTOR TYPE-INFORMATION" - - NAME is the name of the symbol represented by the stab; it can -contain a pair of colons (*note Nested Symbols::.). NAME can be -omitted, which means the stab represents an unnamed object. For -example, `:t10=*2' defines type 10 as a pointer to type 2, but does not -give the type a name. Omitting the NAME field is supported by AIX dbx -and GDB after about version 4.8, but not other debuggers. GCC -sometimes uses a single space as the name instead of omitting the name -altogether; apparently that is supported by most debuggers. - - The SYMBOL-DESCRIPTOR following the `:' is an alphabetic character -that tells more specifically what kind of symbol the stab represents. -If the SYMBOL-DESCRIPTOR is omitted, but type information follows, then -the stab represents a local variable. For a list of symbol -descriptors, see *Note Symbol Descriptors::. The `c' symbol descriptor -is an exception in that it is not followed by type information. *Note -Constants::. - - TYPE-INFORMATION is either a TYPE-NUMBER, or `TYPE-NUMBER='. A -TYPE-NUMBER alone is a type reference, referring directly to a type -that has already been defined. - - The `TYPE-NUMBER=' form is a type definition, where the number -represents a new type which is about to be defined. The type -definition may refer to other types by number, and those type numbers -may be followed by `=' and nested definitions. Also, the Lucid -compiler will repeat `TYPE-NUMBER=' more than once if it wants to -define several type numbers at once. - - In a type definition, if the character that follows the equals sign -is non-numeric then it is a TYPE-DESCRIPTOR, and tells what kind of -type is about to be defined. Any other values following the -TYPE-DESCRIPTOR vary, depending on the TYPE-DESCRIPTOR. *Note Type -Descriptors::, for a list of TYPE-DESCRIPTOR values. If a number -follows the `=' then the number is a TYPE-REFERENCE. For a full -description of types, *Note Types::. - - A TYPE-NUMBER is often a single number. The GNU and Sun tools -additionally permit a TYPE-NUMBER to be a pair -(FILE-NUMBER,FILETYPE-NUMBER) (the parentheses appear in the string, -and serve to distinguish the two cases). The FILE-NUMBER is a number -starting with 1 which is incremented for each seperate source file in -the compilation (e.g., in C, each header file gets a different number). -The FILETYPE-NUMBER is a number starting with 1 which is incremented -for each new type defined in the file. (Separating the file number and -the type number permits the `N_BINCL' optimization to succeed more -often; see *Note Include Files::). - - There is an AIX extension for type attributes. Following the `=' -are any number of type attributes. Each one starts with `@' and ends -with `;'. Debuggers, including AIX's dbx and GDB 4.10, skip any type -attributes they do not recognize. GDB 4.9 and other versions of dbx -may not do this. Because of a conflict with C++ (*note Cplusplus::.), -new attributes should not be defined which begin with a digit, `(', or -`-'; GDB may be unable to distinguish those from the C++ type -descriptor `@'. The attributes are: - -`aBOUNDARY' - BOUNDARY is an integer specifying the alignment. I assume it - applies to all variables of this type. - -`pINTEGER' - Pointer class (for checking). Not sure what this means, or how - INTEGER is interpreted. - -`P' - Indicate this is a packed type, meaning that structure fields or - array elements are placed more closely in memory, to save memory - at the expense of speed. - -`sSIZE' - Size in bits of a variable of this type. This is fully supported - by GDB 4.11 and later. - -`S' - Indicate that this type is a string instead of an array of - characters, or a bitstring instead of a set. It doesn't change - the layout of the data being represented, but does enable the - debugger to know which type it is. - - All of this can make the string field quite long. All versions of -GDB, and some versions of dbx, can handle arbitrarily long strings. -But many versions of dbx (or assemblers or linkers, I'm not sure which) -cretinously limit the strings to about 80 characters, so compilers which -must work with such systems need to split the `.stabs' directive into -several `.stabs' directives. Each stab duplicates every field except -the string field. The string field of every stab except the last is -marked as continued with a backslash at the end (in the assembly code -this may be written as a double backslash, depending on the assembler). -Removing the backslashes and concatenating the string fields of each -stab produces the original, long string. Just to be incompatible (or so -they don't have to worry about what the assembler does with -backslashes), AIX can use `?' instead of backslash. - - -File: stabs.info, Node: C Example, Next: Assembly Code, Prev: String Field, Up: Overview - -A Simple Example in C Source -============================ - - To get the flavor of how stabs describe source information for a C -program, let's look at the simple program: - - main() - { - printf("Hello world"); - } - - When compiled with `-g', the program above yields the following `.s' -file. Line numbers have been added to make it easier to refer to parts -of the `.s' file in the description of the stabs that follows. - - -File: stabs.info, Node: Assembly Code, Prev: C Example, Up: Overview - -The Simple Example at the Assembly Level -======================================== - - This simple "hello world" example demonstrates several of the stab -types used to describe C language source files. - - 1 gcc2_compiled.: - 2 .stabs "/cygint/s1/users/jcm/play/",100,0,0,Ltext0 - 3 .stabs "hello.c",100,0,0,Ltext0 - 4 .text - 5 Ltext0: - 6 .stabs "int:t1=r1;-2147483648;2147483647;",128,0,0,0 - 7 .stabs "char:t2=r2;0;127;",128,0,0,0 - 8 .stabs "long int:t3=r1;-2147483648;2147483647;",128,0,0,0 - 9 .stabs "unsigned int:t4=r1;0;-1;",128,0,0,0 - 10 .stabs "long unsigned int:t5=r1;0;-1;",128,0,0,0 - 11 .stabs "short int:t6=r1;-32768;32767;",128,0,0,0 - 12 .stabs "long long int:t7=r1;0;-1;",128,0,0,0 - 13 .stabs "short unsigned int:t8=r1;0;65535;",128,0,0,0 - 14 .stabs "long long unsigned int:t9=r1;0;-1;",128,0,0,0 - 15 .stabs "signed char:t10=r1;-128;127;",128,0,0,0 - 16 .stabs "unsigned char:t11=r1;0;255;",128,0,0,0 - 17 .stabs "float:t12=r1;4;0;",128,0,0,0 - 18 .stabs "double:t13=r1;8;0;",128,0,0,0 - 19 .stabs "long double:t14=r1;8;0;",128,0,0,0 - 20 .stabs "void:t15=15",128,0,0,0 - 21 .align 4 - 22 LC0: - 23 .ascii "Hello, world!\12\0" - 24 .align 4 - 25 .global _main - 26 .proc 1 - 27 _main: - 28 .stabn 68,0,4,LM1 - 29 LM1: - 30 !#PROLOGUE# 0 - 31 save %sp,-136,%sp - 32 !#PROLOGUE# 1 - 33 call ___main,0 - 34 nop - 35 .stabn 68,0,5,LM2 - 36 LM2: - 37 LBB2: - 38 sethi %hi(LC0),%o1 - 39 or %o1,%lo(LC0),%o0 - 40 call _printf,0 - 41 nop - 42 .stabn 68,0,6,LM3 - 43 LM3: - 44 LBE2: - 45 .stabn 68,0,6,LM4 - 46 LM4: - 47 L1: - 48 ret - 49 restore - 50 .stabs "main:F1",36,0,0,_main - 51 .stabn 192,0,0,LBB2 - 52 .stabn 224,0,0,LBE2 - - -File: stabs.info, Node: Program Structure, Next: Constants, Prev: Overview, Up: Top - -Encoding the Structure of the Program -************************************* - - The elements of the program structure that stabs encode include the -name of the main function, the names of the source and include files, -the line numbers, procedure names and types, and the beginnings and -ends of blocks of code. - -* Menu: - -* Main Program:: Indicate what the main program is -* Source Files:: The path and name of the source file -* Include Files:: Names of include files -* Line Numbers:: -* Procedures:: -* Nested Procedures:: -* Block Structure:: -* Alternate Entry Points:: Entering procedures except at the beginning. - - -File: stabs.info, Node: Main Program, Next: Source Files, Up: Program Structure - -Main Program -============ - - Most languages allow the main program to have any name. The -`N_MAIN' stab type tells the debugger the name that is used in this -program. Only the string field is significant; it is the name of a -function which is the main program. Most C compilers do not use this -stab (they expect the debugger to assume that the name is `main'), but -some C compilers emit an `N_MAIN' stab for the `main' function. I'm -not sure how XCOFF handles this. - - -File: stabs.info, Node: Source Files, Next: Include Files, Prev: Main Program, Up: Program Structure - -Paths and Names of the Source Files -=================================== - - Before any other stabs occur, there must be a stab specifying the -source file. This information is contained in a symbol of stab type -`N_SO'; the string field contains the name of the file. The value of -the symbol is the start address of the portion of the text section -corresponding to that file. - - With the Sun Solaris2 compiler, the desc field contains a -source-language code. - - Some compilers (for example, GCC2 and SunOS4 `/bin/cc') also include -the directory in which the source was compiled, in a second `N_SO' -symbol preceding the one containing the file name. This symbol can be -distinguished by the fact that it ends in a slash. Code from the -`cfront' C++ compiler can have additional `N_SO' symbols for -nonexistent source files after the `N_SO' for the real source file; -these are believed to contain no useful information. - - For example: - - .stabs "/cygint/s1/users/jcm/play/",100,0,0,Ltext0 # 100 is N_SO - .stabs "hello.c",100,0,0,Ltext0 - .text - Ltext0: - - Instead of `N_SO' symbols, XCOFF uses a `.file' assembler directive -which assembles to a `C_FILE' symbol; explaining this in detail is -outside the scope of this document. - - If it is useful to indicate the end of a source file, this is done -with an `N_SO' symbol with an empty string for the name. The value is -the address of the end of the text section for the file. For some -systems, there is no indication of the end of a source file, and you -just need to figure it ended when you see an `N_SO' for a different -source file, or a symbol ending in `.o' (which at least some linkers -insert to mark the start of a new `.o' file). - - -File: stabs.info, Node: Include Files, Next: Line Numbers, Prev: Source Files, Up: Program Structure - -Names of Include Files -====================== - - There are several schemes for dealing with include files: the -traditional `N_SOL' approach, Sun's `N_BINCL' approach, and the XCOFF -`C_BINCL' approach (which despite the similar name has little in common -with `N_BINCL'). - - An `N_SOL' symbol specifies which include file subsequent symbols -refer to. The string field is the name of the file and the value is the -text address corresponding to the end of the previous include file and -the start of this one. To specify the main source file again, use an -`N_SOL' symbol with the name of the main source file. - - The `N_BINCL' approach works as follows. An `N_BINCL' symbol -specifies the start of an include file. In an object file, only the -string is significant; the linker puts data into some of the other -fields. The end of the include file is marked by an `N_EINCL' symbol -(which has no string field). In an object file, there is no -significant data in the `N_EINCL' symbol. `N_BINCL' and `N_EINCL' can -be nested. - - If the linker detects that two source files have identical stabs -between an `N_BINCL' and `N_EINCL' pair (as will generally be the case -for a header file), then it only puts out the stabs once. Each -additional occurance is replaced by an `N_EXCL' symbol. I believe the -GNU linker and the Sun (both SunOS4 and Solaris) linker are the only -ones which supports this feature. - - A linker which supports this feature will set the value of a -`N_BINCL' symbol to the total of all the characters in the stabs -strings included in the header file, omitting any file numbers. The -value of an `N_EXCL' symbol is the same as the value of the `N_BINCL' -symbol it replaces. This information can be used to match up `N_EXCL' -and `N_BINCL' symbols which have the same filename. The `N_EINCL' -value, and the values of the other and description fields for all -three, appear to always be zero. - - For the start of an include file in XCOFF, use the `.bi' assembler -directive, which generates a `C_BINCL' symbol. A `.ei' directive, -which generates a `C_EINCL' symbol, denotes the end of the include -file. Both directives are followed by the name of the source file in -quotes, which becomes the string for the symbol. The value of each -symbol, produced automatically by the assembler and linker, is the -offset into the executable of the beginning (inclusive, as you'd -expect) or end (inclusive, as you would not expect) of the portion of -the COFF line table that corresponds to this include file. `C_BINCL' -and `C_EINCL' do not nest. - - -File: stabs.info, Node: Line Numbers, Next: Procedures, Prev: Include Files, Up: Program Structure - -Line Numbers -============ - - An `N_SLINE' symbol represents the start of a source line. The desc -field contains the line number and the value contains the code address -for the start of that source line. On most machines the address is -absolute; for stabs in sections (*note Stab Sections::.), it is -relative to the function in which the `N_SLINE' symbol occurs. - - GNU documents `N_DSLINE' and `N_BSLINE' symbols for line numbers in -the data or bss segments, respectively. They are identical to -`N_SLINE' but are relocated differently by the linker. They were -intended to be used to describe the source location of a variable -declaration, but I believe that GCC2 actually puts the line number in -the desc field of the stab for the variable itself. GDB has been -ignoring these symbols (unless they contain a string field) since at -least GDB 3.5. - - For single source lines that generate discontiguous code, such as -flow of control statements, there may be more than one line number -entry for the same source line. In this case there is a line number -entry at the start of each code range, each with the same line number. - - XCOFF does not use stabs for line numbers. Instead, it uses COFF -line numbers (which are outside the scope of this document). Standard -COFF line numbers cannot deal with include files, but in XCOFF this is -fixed with the `C_BINCL' method of marking include files (*note Include -Files::.). - - -File: stabs.info, Node: Procedures, Next: Nested Procedures, Prev: Line Numbers, Up: Program Structure - -Procedures -========== - - All of the following stabs normally use the `N_FUN' symbol type. -However, Sun's `acc' compiler on SunOS4 uses `N_GSYM' and `N_STSYM', -which means that the value of the stab for the function is useless and -the debugger must get the address of the function from the non-stab -symbols instead. On systems where non-stab symbols have leading -underscores, the stabs will lack underscores and the debugger needs to -know about the leading underscore to match up the stab and the non-stab -symbol. BSD Fortran is said to use `N_FNAME' with the same -restriction; the value of the symbol is not useful (I'm not sure it -really does use this, because GDB doesn't handle this and no one has -complained). - - A function is represented by an `F' symbol descriptor for a global -(extern) function, and `f' for a static (local) function. For a.out, -the value of the symbol is the address of the start of the function; it -is already relocated. For stabs in ELF, the SunPRO compiler version -2.0.1 and GCC put out an address which gets relocated by the linker. -In a future release SunPRO is planning to put out zero, in which case -the address can be found from the ELF (non-stab) symbol. Because -looking things up in the ELF symbols would probably be slow, I'm not -sure how to find which symbol of that name is the right one, and this -doesn't provide any way to deal with nested functions, it would -probably be better to make the value of the stab an address relative to -the start of the file, or just absolute. See *Note ELF Linker -Relocation:: for more information on linker relocation of stabs in ELF -files. For XCOFF, the stab uses the `C_FUN' storage class and the -value of the stab is meaningless; the address of the function can be -found from the csect symbol (XTY_LD/XMC_PR). - - The type information of the stab represents the return type of the -function; thus `foo:f5' means that foo is a function returning type 5. -There is no need to try to get the line number of the start of the -function from the stab for the function; it is in the next `N_SLINE' -symbol. - - Some compilers (such as Sun's Solaris compiler) support an extension -for specifying the types of the arguments. I suspect this extension is -not used for old (non-prototyped) function definitions in C. If the -extension is in use, the type information of the stab for the function -is followed by type information for each argument, with each argument -preceded by `;'. An argument type of 0 means that additional arguments -are being passed, whose types and number may vary (`...' in ANSI C). -GDB has tolerated this extension (parsed the syntax, if not necessarily -used the information) since at least version 4.8; I don't know whether -all versions of dbx tolerate it. The argument types given here are not -redundant with the symbols for the formal parameters (*note -Parameters::.); they are the types of the arguments as they are passed, -before any conversions might take place. For example, if a C function -which is declared without a prototype takes a `float' argument, the -value is passed as a `double' but then converted to a `float'. -Debuggers need to use the types given in the arguments when printing -values, but when calling the function they need to use the types given -in the symbol defining the function. - - If the return type and types of arguments of a function which is -defined in another source file are specified (i.e., a function -prototype in ANSI C), traditionally compilers emit no stab; the only -way for the debugger to find the information is if the source file -where the function is defined was also compiled with debugging symbols. -As an extension the Solaris compiler uses symbol descriptor `P' -followed by the return type of the function, followed by the arguments, -each preceded by `;', as in a stab with symbol descriptor `f' or `F'. -This use of symbol descriptor `P' can be distinguished from its use for -register parameters (*note Register Parameters::.) by the fact that it -has symbol type `N_FUN'. - - The AIX documentation also defines symbol descriptor `J' as an -internal function. I assume this means a function nested within another -function. It also says symbol descriptor `m' is a module in Modula-2 -or extended Pascal. - - Procedures (functions which do not return values) are represented as -functions returning the `void' type in C. I don't see why this couldn't -be used for all languages (inventing a `void' type for this purpose if -necessary), but the AIX documentation defines `I', `P', and `Q' for -internal, global, and static procedures, respectively. These symbol -descriptors are unusual in that they are not followed by type -information. - - The following example shows a stab for a function `main' which -returns type number `1'. The `_main' specified for the value is a -reference to an assembler label which is used to fill in the start -address of the function. - - .stabs "main:F1",36,0,0,_main # 36 is N_FUN - - The stab representing a procedure is located immediately following -the code of the procedure. This stab is in turn directly followed by a -group of other stabs describing elements of the procedure. These other -stabs describe the procedure's parameters, its block local variables, -and its block structure. - - If functions can appear in different sections, then the debugger may -not be able to find the end of a function. Recent versions of GCC will -mark the end of a function with an `N_FUN' symbol with an empty string -for the name. The value is the address of the end of the current -function. Without such a symbol, there is no indication of the address -of the end of a function, and you must assume that it ended at the -starting address of the next function or at the end of the text section -for the program. - - -File: stabs.info, Node: Nested Procedures, Next: Block Structure, Prev: Procedures, Up: Program Structure - -Nested Procedures -================= - - For any of the symbol descriptors representing procedures, after the -symbol descriptor and the type information is optionally a scope -specifier. This consists of a comma, the name of the procedure, another -comma, and the name of the enclosing procedure. The first name is local -to the scope specified, and seems to be redundant with the name of the -symbol (before the `:'). This feature is used by GCC, and presumably -Pascal, Modula-2, etc., compilers, for nested functions. - - If procedures are nested more than one level deep, only the -immediately containing scope is specified. For example, this code: - - int - foo (int x) - { - int bar (int y) - { - int baz (int z) - { - return x + y + z; - } - return baz (x + 2 * y); - } - return x + bar (3 * x); - } - -produces the stabs: - - .stabs "baz:f1,baz,bar",36,0,0,_baz.15 # 36 is N_FUN - .stabs "bar:f1,bar,foo",36,0,0,_bar.12 - .stabs "foo:F1",36,0,0,_foo - - -File: stabs.info, Node: Block Structure, Next: Alternate Entry Points, Prev: Nested Procedures, Up: Program Structure - -Block Structure -=============== - - The program's block structure is represented by the `N_LBRAC' (left -brace) and the `N_RBRAC' (right brace) stab types. The variables -defined inside a block precede the `N_LBRAC' symbol for most compilers, -including GCC. Other compilers, such as the Convex, Acorn RISC -machine, and Sun `acc' compilers, put the variables after the `N_LBRAC' -symbol. The values of the `N_LBRAC' and `N_RBRAC' symbols are the -start and end addresses of the code of the block, respectively. For -most machines, they are relative to the starting address of this source -file. For the Gould NP1, they are absolute. For stabs in sections -(*note Stab Sections::.), they are relative to the function in which -they occur. - - The `N_LBRAC' and `N_RBRAC' stabs that describe the block scope of a -procedure are located after the `N_FUN' stab that represents the -procedure itself. - - Sun documents the desc field of `N_LBRAC' and `N_RBRAC' symbols as -containing the nesting level of the block. However, dbx seems to not -care, and GCC always sets desc to zero. - - For XCOFF, block scope is indicated with `C_BLOCK' symbols. If the -name of the symbol is `.bb', then it is the beginning of the block; if -the name of the symbol is `.be'; it is the end of the block. - - -File: stabs.info, Node: Alternate Entry Points, Prev: Block Structure, Up: Program Structure - -Alternate Entry Points -====================== - - Some languages, like Fortran, have the ability to enter procedures at -some place other than the beginning. One can declare an alternate entry -point. The `N_ENTRY' stab is for this; however, the Sun FORTRAN -compiler doesn't use it. According to AIX documentation, only the name -of a `C_ENTRY' stab is significant; the address of the alternate entry -point comes from the corresponding external symbol. A previous -revision of this document said that the value of an `N_ENTRY' stab was -the address of the alternate entry point, but I don't know the source -for that information. - - -File: stabs.info, Node: Constants, Next: Variables, Prev: Program Structure, Up: Top - -Constants -********* - - The `c' symbol descriptor indicates that this stab represents a -constant. This symbol descriptor is an exception to the general rule -that symbol descriptors are followed by type information. Instead, it -is followed by `=' and one of the following: - -`b VALUE' - Boolean constant. VALUE is a numeric value; I assume it is 0 for - false or 1 for true. - -`c VALUE' - Character constant. VALUE is the numeric value of the constant. - -`e TYPE-INFORMATION , VALUE' - Constant whose value can be represented as integral. - TYPE-INFORMATION is the type of the constant, as it would appear - after a symbol descriptor (*note String Field::.). VALUE is the - numeric value of the constant. GDB 4.9 does not actually get the - right value if VALUE does not fit in a host `int', but it does not - do anything violent, and future debuggers could be extended to - accept integers of any size (whether unsigned or not). This - constant type is usually documented as being only for enumeration - constants, but GDB has never imposed that restriction; I don't - know about other debuggers. - -`i VALUE' - Integer constant. VALUE is the numeric value. The type is some - sort of generic integer type (for GDB, a host `int'); to specify - the type explicitly, use `e' instead. - -`r VALUE' - Real constant. VALUE is the real value, which can be `INF' - (optionally preceded by a sign) for infinity, `QNAN' for a quiet - NaN (not-a-number), or `SNAN' for a signalling NaN. If it is a - normal number the format is that accepted by the C library function - `atof'. - -`s STRING' - String constant. STRING is a string enclosed in either `'' (in - which case `'' characters within the string are represented as - `\'' or `"' (in which case `"' characters within the string are - represented as `\"'). - -`S TYPE-INFORMATION , ELEMENTS , BITS , PATTERN' - Set constant. TYPE-INFORMATION is the type of the constant, as it - would appear after a symbol descriptor (*note String Field::.). - ELEMENTS is the number of elements in the set (does this means how - many bits of PATTERN are actually used, which would be redundant - with the type, or perhaps the number of bits set in PATTERN? I - don't get it), BITS is the number of bits in the constant (meaning - it specifies the length of PATTERN, I think), and PATTERN is a - hexadecimal representation of the set. AIX documentation refers - to a limit of 32 bytes, but I see no reason why this limit should - exist. This form could probably be used for arbitrary constants, - not just sets; the only catch is that PATTERN should be understood - to be target, not host, byte order and format. - - The boolean, character, string, and set constants are not supported -by GDB 4.9, but it ignores them. GDB 4.8 and earlier gave an error -message and refused to read symbols from the file containing the -constants. - - The above information is followed by `;'. - - -File: stabs.info, Node: Variables, Next: Types, Prev: Constants, Up: Top - -Variables -********* - - Different types of stabs describe the various ways that variables -can be allocated: on the stack, globally, in registers, in common -blocks, statically, or as arguments to a function. - -* Menu: - -* Stack Variables:: Variables allocated on the stack. -* Global Variables:: Variables used by more than one source file. -* Register Variables:: Variables in registers. -* Common Blocks:: Variables statically allocated together. -* Statics:: Variables local to one source file. -* Based Variables:: Fortran pointer based variables. -* Parameters:: Variables for arguments to functions. - - -File: stabs.info, Node: Stack Variables, Next: Global Variables, Up: Variables - -Automatic Variables Allocated on the Stack -========================================== - - If a variable's scope is local to a function and its lifetime is -only as long as that function executes (C calls such variables -"automatic"), it can be allocated in a register (*note Register -Variables::.) or on the stack. - - Each variable allocated on the stack has a stab with the symbol -descriptor omitted. Since type information should begin with a digit, -`-', or `(', only those characters precluded from being used for symbol -descriptors. However, the Acorn RISC machine (ARM) is said to get this -wrong: it puts out a mere type definition here, without the preceding -`TYPE-NUMBER='. This is a bad idea; there is no guarantee that type -descriptors are distinct from symbol descriptors. Stabs for stack -variables use the `N_LSYM' stab type, or `C_LSYM' for XCOFF. - - The value of the stab is the offset of the variable within the local -variables. On most machines this is an offset from the frame pointer -and is negative. The location of the stab specifies which block it is -defined in; see *Note Block Structure::. - - For example, the following C code: - - int - main () - { - int x; - } - - produces the following stabs: - - .stabs "main:F1",36,0,0,_main # 36 is N_FUN - .stabs "x:1",128,0,0,-12 # 128 is N_LSYM - .stabn 192,0,0,LBB2 # 192 is N_LBRAC - .stabn 224,0,0,LBE2 # 224 is N_RBRAC - - *Note Procedures:: for more information on the `N_FUN' stab, and -*Note Block Structure:: for more information on the `N_LBRAC' and -`N_RBRAC' stabs. - - -File: stabs.info, Node: Global Variables, Next: Register Variables, Prev: Stack Variables, Up: Variables - -Global Variables -================ - - A variable whose scope is not specific to just one source file is -represented by the `G' symbol descriptor. These stabs use the `N_GSYM' -stab type (C_GSYM for XCOFF). The type information for the stab (*note -String Field::.) gives the type of the variable. - - For example, the following source code: - - char g_foo = 'c'; - -yields the following assembly code: - - .stabs "g_foo:G2",32,0,0,0 # 32 is N_GSYM - .global _g_foo - .data - _g_foo: - .byte 99 - - The address of the variable represented by the `N_GSYM' is not -contained in the `N_GSYM' stab. The debugger gets this information -from the external symbol for the global variable. In the example above, -the `.global _g_foo' and `_g_foo:' lines tell the assembler to produce -an external symbol. - - Some compilers, like GCC, output `N_GSYM' stabs only once, where the -variable is defined. Other compilers, like SunOS4 /bin/cc, output a -`N_GSYM' stab for each compilation unit which references the variable. - - -File: stabs.info, Node: Register Variables, Next: Common Blocks, Prev: Global Variables, Up: Variables - -Register Variables -================== - - Register variables have their own stab type, `N_RSYM' (`C_RSYM' for -XCOFF), and their own symbol descriptor, `r'. The stab's value is the -number of the register where the variable data will be stored. - - AIX defines a separate symbol descriptor `d' for floating point -registers. This seems unnecessary; why not just just give floating -point registers different register numbers? I have not verified whether -the compiler actually uses `d'. - - If the register is explicitly allocated to a global variable, but not -initialized, as in: - - register int g_bar asm ("%g5"); - -then the stab may be emitted at the end of the object file, with the -other bss symbols. - - -File: stabs.info, Node: Common Blocks, Next: Statics, Prev: Register Variables, Up: Variables - -Common Blocks -============= - - A common block is a statically allocated section of memory which can -be referred to by several source files. It may contain several -variables. I believe Fortran is the only language with this feature. - - A `N_BCOMM' stab begins a common block and an `N_ECOMM' stab ends -it. The only field that is significant in these two stabs is the -string, which names a normal (non-debugging) symbol that gives the -address of the common block. According to IBM documentation, only the -`N_BCOMM' has the name of the common block (even though their compiler -actually puts it both places). - - The stabs for the members of the common block are between the -`N_BCOMM' and the `N_ECOMM'; the value of each stab is the offset -within the common block of that variable. IBM uses the `C_ECOML' stab -type, and there is a corresponding `N_ECOML' stab type, but Sun's -Fortran compiler uses `N_GSYM' instead. The variables within a common -block use the `V' symbol descriptor (I believe this is true of all -Fortran variables). Other stabs (at least type declarations using -`C_DECL') can also be between the `N_BCOMM' and the `N_ECOMM'. - - -File: stabs.info, Node: Statics, Next: Based Variables, Prev: Common Blocks, Up: Variables - -Static Variables -================ - - Initialized static variables are represented by the `S' and `V' -symbol descriptors. `S' means file scope static, and `V' means -procedure scope static. One exception: in XCOFF, IBM's xlc compiler -always uses `V', and whether it is file scope or not is distinguished -by whether the stab is located within a function. - - In a.out files, `N_STSYM' means the data section, `N_FUN' means the -text section, and `N_LCSYM' means the bss section. For those systems -with a read-only data section separate from the text section (Solaris), -`N_ROSYM' means the read-only data section. - - For example, the source lines: - - static const int var_const = 5; - static int var_init = 2; - static int var_noinit; - -yield the following stabs: - - .stabs "var_const:S1",36,0,0,_var_const # 36 is N_FUN - ... - .stabs "var_init:S1",38,0,0,_var_init # 38 is N_STSYM - ... - .stabs "var_noinit:S1",40,0,0,_var_noinit # 40 is N_LCSYM - - In XCOFF files, the stab type need not indicate the section; -`C_STSYM' can be used for all statics. Also, each static variable is -enclosed in a static block. A `C_BSTAT' (emitted with a `.bs' -assembler directive) symbol begins the static block; its value is the -symbol number of the csect symbol whose value is the address of the -static block, its section is the section of the variables in that -static block, and its name is `.bs'. A `C_ESTAT' (emitted with a `.es' -assembler directive) symbol ends the static block; its name is `.es' -and its value and section are ignored. - - In ECOFF files, the storage class is used to specify the section, so -the stab type need not indicate the section. - - In ELF files, for the SunPRO compiler version 2.0.1, symbol -descriptor `S' means that the address is absolute (the linker relocates -it) and symbol descriptor `V' means that the address is relative to the -start of the relevant section for that compilation unit. SunPRO has -plans to have the linker stop relocating stabs; I suspect that their the -debugger gets the address from the corresponding ELF (not stab) symbol. -I'm not sure how to find which symbol of that name is the right one. -The clean way to do all this would be to have a the value of a symbol -descriptor `S' symbol be an offset relative to the start of the file, -just like everything else, but that introduces obvious compatibility -problems. For more information on linker stab relocation, *Note ELF -Linker Relocation::. - - -File: stabs.info, Node: Based Variables, Next: Parameters, Prev: Statics, Up: Variables - -Fortran Based Variables -======================= - - Fortran (at least, the Sun and SGI dialects of FORTRAN-77) has a -feature which allows allocating arrays with `malloc', but which avoids -blurring the line between arrays and pointers the way that C does. In -stabs such a variable uses the `b' symbol descriptor. - - For example, the Fortran declarations - - real foo, foo10(10), foo10_5(10,5) - pointer (foop, foo) - pointer (foo10p, foo10) - pointer (foo105p, foo10_5) - - produce the stabs - - foo:b6 - foo10:bar3;1;10;6 - foo10_5:bar3;1;5;ar3;1;10;6 - - In this example, `real' is type 6 and type 3 is an integral type -which is the type of the subscripts of the array (probably `integer'). - - The `b' symbol descriptor is like `V' in that it denotes a -statically allocated symbol whose scope is local to a function; see -*Note Statics::. The value of the symbol, instead of being the address -of the variable itself, is the address of a pointer to that variable. -So in the above example, the value of the `foo' stab is the address of -a pointer to a real, the value of the `foo10' stab is the address of a -pointer to a 10-element array of reals, and the value of the `foo10_5' -stab is the address of a pointer to a 5-element array of 10-element -arrays of reals. - - -File: stabs.info, Node: Parameters, Prev: Based Variables, Up: Variables - -Parameters -========== - - Formal parameters to a function are represented by a stab (or -sometimes two; see below) for each parameter. The stabs are in the -order in which the debugger should print the parameters (i.e., the -order in which the parameters are declared in the source file). The -exact form of the stab depends on how the parameter is being passed. - - Parameters passed on the stack use the symbol descriptor `p' and the -`N_PSYM' symbol type (or `C_PSYM' for XCOFF). The value of the symbol -is an offset used to locate the parameter on the stack; its exact -meaning is machine-dependent, but on most machines it is an offset from -the frame pointer. - - As a simple example, the code: - - main (argc, argv) - int argc; - char **argv; - - produces the stabs: - - .stabs "main:F1",36,0,0,_main # 36 is N_FUN - .stabs "argc:p1",160,0,0,68 # 160 is N_PSYM - .stabs "argv:p20=*21=*2",160,0,0,72 - - The type definition of `argv' is interesting because it contains -several type definitions. Type 21 is pointer to type 2 (char) and -`argv' (type 20) is pointer to type 21. - - The following symbol descriptors are also said to go with `N_PSYM'. -The value of the symbol is said to be an offset from the argument -pointer (I'm not sure whether this is true or not). - - pP (<>) - pF Fortran function parameter - X (function result variable) - -* Menu: - -* Register Parameters:: -* Local Variable Parameters:: -* Reference Parameters:: -* Conformant Arrays:: - - -File: stabs.info, Node: Register Parameters, Next: Local Variable Parameters, Up: Parameters - -Passing Parameters in Registers -------------------------------- - - If the parameter is passed in a register, then traditionally there -are two symbols for each argument: - - .stabs "arg:p1" . . . ; N_PSYM - .stabs "arg:r1" . . . ; N_RSYM - - Debuggers use the second one to find the value, and the first one to -know that it is an argument. - - Because that approach is kind of ugly, some compilers use symbol -descriptor `P' or `R' to indicate an argument which is in a register. -Symbol type `C_RPSYM' is used in XCOFF and `N_RSYM' is used otherwise. -The symbol's value is the register number. `P' and `R' mean the same -thing; the difference is that `P' is a GNU invention and `R' is an IBM -(XCOFF) invention. As of version 4.9, GDB should handle either one. - - There is at least one case where GCC uses a `p' and `r' pair rather -than `P'; this is where the argument is passed in the argument list and -then loaded into a register. - - According to the AIX documentation, symbol descriptor `D' is for a -parameter passed in a floating point register. This seems -unnecessary--why not just use `R' with a register number which -indicates that it's a floating point register? I haven't verified -whether the system actually does what the documentation indicates. - - On the sparc and hppa, for a `P' symbol whose type is a structure or -union, the register contains the address of the structure. On the -sparc, this is also true of a `p' and `r' pair (using Sun `cc') or a -`p' symbol. However, if a (small) structure is really in a register, -`r' is used. And, to top it all off, on the hppa it might be a -structure which was passed on the stack and loaded into a register and -for which there is a `p' and `r' pair! I believe that symbol -descriptor `i' is supposed to deal with this case (it is said to mean -"value parameter by reference, indirect access"; I don't know the -source for this information), but I don't know details or what -compilers or debuggers use it, if any (not GDB or GCC). It is not -clear to me whether this case needs to be dealt with differently than -parameters passed by reference (*note Reference Parameters::.). - - -File: stabs.info, Node: Local Variable Parameters, Next: Reference Parameters, Prev: Register Parameters, Up: Parameters - -Storing Parameters as Local Variables -------------------------------------- - - There is a case similar to an argument in a register, which is an -argument that is actually stored as a local variable. Sometimes this -happens when the argument was passed in a register and then the compiler -stores it as a local variable. If possible, the compiler should claim -that it's in a register, but this isn't always done. - - If a parameter is passed as one type and converted to a smaller type -by the prologue (for example, the parameter is declared as a `float', -but the calling conventions specify that it is passed as a `double'), -then GCC2 (sometimes) uses a pair of symbols. The first symbol uses -symbol descriptor `p' and the type which is passed. The second symbol -has the type and location which the parameter actually has after the -prologue. For example, suppose the following C code appears with no -prototypes involved: - - void - subr (f) - float f; - { - - if `f' is passed as a double at stack offset 8, and the prologue -converts it to a float in register number 0, then the stabs look like: - - .stabs "f:p13",160,0,3,8 # 160 is `N_PSYM', here 13 is `double' - .stabs "f:r12",64,0,3,0 # 64 is `N_RSYM', here 12 is `float' - - In both stabs 3 is the line number where `f' is declared (*note Line -Numbers::.). - - GCC, at least on the 960, has another solution to the same problem. -It uses a single `p' symbol descriptor for an argument which is stored -as a local variable but uses `N_LSYM' instead of `N_PSYM'. In this -case, the value of the symbol is an offset relative to the local -variables for that function, not relative to the arguments; on some -machines those are the same thing, but not on all. - - On the VAX or on other machines in which the calling convention -includes the number of words of arguments actually passed, the debugger -(GDB at least) uses the parameter symbols to keep track of whether it -needs to print nameless arguments in addition to the formal parameters -which it has printed because each one has a stab. For example, in - - extern int fprintf (FILE *stream, char *format, ...); - ... - fprintf (stdout, "%d\n", x); - - there are stabs for `stream' and `format'. On most machines, the -debugger can only print those two arguments (because it has no way of -knowing that additional arguments were passed), but on the VAX or other -machines with a calling convention which indicates the number of words -of arguments, the debugger can print all three arguments. To do so, -the parameter symbol (symbol descriptor `p') (not necessarily `r' or -symbol descriptor omitted symbols) needs to contain the actual type as -passed (for example, `double' not `float' if it is passed as a double -and converted to a float). - - -File: stabs.info, Node: Reference Parameters, Next: Conformant Arrays, Prev: Local Variable Parameters, Up: Parameters - -Passing Parameters by Reference -------------------------------- - - If the parameter is passed by reference (e.g., Pascal `VAR' -parameters), then the symbol descriptor is `v' if it is in the argument -list, or `a' if it in a register. Other than the fact that these -contain the address of the parameter rather than the parameter itself, -they are identical to `p' and `R', respectively. I believe `a' is an -AIX invention; `v' is supported by all stabs-using systems as far as I -know. - diff --git a/gnu/dist/gdb/doc/stabs.info-2 b/gnu/dist/gdb/doc/stabs.info-2 deleted file mode 100644 index a7b7136f1a6d..000000000000 --- a/gnu/dist/gdb/doc/stabs.info-2 +++ /dev/null @@ -1,1286 +0,0 @@ -This is Info file stabs.info, produced by Makeinfo version 1.68 from -the input file ../../../devo/gdb/doc/stabs.texinfo. - -START-INFO-DIR-ENTRY -* Stabs: (stabs). The "stabs" debugging information format. -END-INFO-DIR-ENTRY - - This document describes the stabs debugging symbol tables. - - Copyright 1992, 93, 94, 95, 1997 Free Software Foundation, Inc. -Contributed by Cygnus Support. Written by Julia Menapace, Jim Kingdon, -and David MacKenzie. - - 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 or distribute modified versions of this -manual under the terms of the GPL (for which purpose this text may be -regarded as a program in the language TeX). - - -File: stabs.info, Node: Conformant Arrays, Prev: Reference Parameters, Up: Parameters - -Passing Conformant Array Parameters ------------------------------------ - - Conformant arrays are a feature of Modula-2, and perhaps other -languages, in which the size of an array parameter is not known to the -called function until run-time. Such parameters have two stabs: a `x' -for the array itself, and a `C', which represents the size of the -array. The value of the `x' stab is the offset in the argument list -where the address of the array is stored (it this right? it is a -guess); the value of the `C' stab is the offset in the argument list -where the size of the array (in elements? in bytes?) is stored. - - -File: stabs.info, Node: Types, Next: Symbol Tables, Prev: Variables, Up: Top - -Defining Types -************** - - The examples so far have described types as references to previously -defined types, or defined in terms of subranges of or pointers to -previously defined types. This chapter describes the other type -descriptors that may follow the `=' in a type definition. - -* Menu: - -* Builtin Types:: Integers, floating point, void, etc. -* Miscellaneous Types:: Pointers, sets, files, etc. -* Cross-References:: Referring to a type not yet defined. -* Subranges:: A type with a specific range. -* Arrays:: An aggregate type of same-typed elements. -* Strings:: Like an array but also has a length. -* Enumerations:: Like an integer but the values have names. -* Structures:: An aggregate type of different-typed elements. -* Typedefs:: Giving a type a name. -* Unions:: Different types sharing storage. -* Function Types:: - - -File: stabs.info, Node: Builtin Types, Next: Miscellaneous Types, Up: Types - -Builtin Types -============= - - Certain types are built in (`int', `short', `void', `float', etc.); -the debugger recognizes these types and knows how to handle them. -Thus, don't be surprised if some of the following ways of specifying -builtin types do not specify everything that a debugger would need to -know about the type--in some cases they merely specify enough -information to distinguish the type from other types. - - The traditional way to define builtin types is convolunted, so new -ways have been invented to describe them. Sun's `acc' uses special -builtin type descriptors (`b' and `R'), and IBM uses negative type -numbers. GDB accepts all three ways, as of version 4.8; dbx just -accepts the traditional builtin types and perhaps one of the other two -formats. The following sections describe each of these formats. - -* Menu: - -* Traditional Builtin Types:: Put on your seatbelts and prepare for kludgery -* Builtin Type Descriptors:: Builtin types with special type descriptors -* Negative Type Numbers:: Builtin types using negative type numbers - - -File: stabs.info, Node: Traditional Builtin Types, Next: Builtin Type Descriptors, Up: Builtin Types - -Traditional Builtin Types -------------------------- - - This is the traditional, convoluted method for defining builtin -types. There are several classes of such type definitions: integer, -floating point, and `void'. - -* Menu: - -* Traditional Integer Types:: -* Traditional Other Types:: - - -File: stabs.info, Node: Traditional Integer Types, Next: Traditional Other Types, Up: Traditional Builtin Types - -Traditional Integer Types -......................... - - Often types are defined as subranges of themselves. If the bounding -values fit within an `int', then they are given normally. For example: - - .stabs "int:t1=r1;-2147483648;2147483647;",128,0,0,0 # 128 is N_LSYM - .stabs "char:t2=r2;0;127;",128,0,0,0 - - Builtin types can also be described as subranges of `int': - - .stabs "unsigned short:t6=r1;0;65535;",128,0,0,0 - - If the lower bound of a subrange is 0 and the upper bound is -1, the -type is an unsigned integral type whose bounds are too big to describe -in an `int'. Traditionally this is only used for `unsigned int' and -`unsigned long': - - .stabs "unsigned int:t4=r1;0;-1;",128,0,0,0 - - For larger types, GCC 2.4.5 puts out bounds in octal, with one or -more leading zeroes. In this case a negative bound consists of a number -which is a 1 bit (for the sign bit) followed by a 0 bit for each bit in -the number (except the sign bit), and a positive bound is one which is a -1 bit for each bit in the number (except possibly the sign bit). All -known versions of dbx and GDB version 4 accept this (at least in the -sense of not refusing to process the file), but GDB 3.5 refuses to read -the whole file containing such symbols. So GCC 2.3.3 did not output the -proper size for these types. As an example of octal bounds, the string -fields of the stabs for 64 bit integer types look like: - - long int:t3=r1;001000000000000000000000;000777777777777777777777; - long unsigned int:t5=r1;000000000000000000000000;001777777777777777777777; - - If the lower bound of a subrange is 0 and the upper bound is -negative, the type is an unsigned integral type whose size in bytes is -the absolute value of the upper bound. I believe this is a Convex -convention for `unsigned long long'. - - If the lower bound of a subrange is negative and the upper bound is -0, the type is a signed integral type whose size in bytes is the -absolute value of the lower bound. I believe this is a Convex -convention for `long long'. To distinguish this from a legitimate -subrange, the type should be a subrange of itself. I'm not sure whether -this is the case for Convex. - - -File: stabs.info, Node: Traditional Other Types, Prev: Traditional Integer Types, Up: Traditional Builtin Types - -Traditional Other Types -....................... - - If the upper bound of a subrange is 0 and the lower bound is -positive, the type is a floating point type, and the lower bound of the -subrange indicates the number of bytes in the type: - - .stabs "float:t12=r1;4;0;",128,0,0,0 - .stabs "double:t13=r1;8;0;",128,0,0,0 - - However, GCC writes `long double' the same way it writes `double', -so there is no way to distinguish. - - .stabs "long double:t14=r1;8;0;",128,0,0,0 - - Complex types are defined the same way as floating-point types; -there is no way to distinguish a single-precision complex from a -double-precision floating-point type. - - The C `void' type is defined as itself: - - .stabs "void:t15=15",128,0,0,0 - - I'm not sure how a boolean type is represented. - - -File: stabs.info, Node: Builtin Type Descriptors, Next: Negative Type Numbers, Prev: Traditional Builtin Types, Up: Builtin Types - -Defining Builtin Types Using Builtin Type Descriptors ------------------------------------------------------ - - This is the method used by Sun's `acc' for defining builtin types. -These are the type descriptors to define builtin types: - -`b SIGNED CHAR-FLAG WIDTH ; OFFSET ; NBITS ;' - Define an integral type. SIGNED is `u' for unsigned or `s' for - signed. CHAR-FLAG is `c' which indicates this is a character - type, or is omitted. I assume this is to distinguish an integral - type from a character type of the same size, for example it might - make sense to set it for the C type `wchar_t' so the debugger can - print such variables differently (Solaris does not do this). Sun - sets it on the C types `signed char' and `unsigned char' which - arguably is wrong. WIDTH and OFFSET appear to be for small - objects stored in larger ones, for example a `short' in an `int' - register. WIDTH is normally the number of bytes in the type. - OFFSET seems to always be zero. NBITS is the number of bits in - the type. - - Note that type descriptor `b' used for builtin types conflicts with - its use for Pascal space types (*note Miscellaneous Types::.); - they can be distinguished because the character following the type - descriptor will be a digit, `(', or `-' for a Pascal space type, or - `u' or `s' for a builtin type. - -`w' - Documented by AIX to define a wide character type, but their - compiler actually uses negative type numbers (*note Negative Type - Numbers::.). - -`R FP-TYPE ; BYTES ;' - Define a floating point type. FP-TYPE has one of the following - values: - - `1 (NF_SINGLE)' - IEEE 32-bit (single precision) floating point format. - - `2 (NF_DOUBLE)' - IEEE 64-bit (double precision) floating point format. - - `3 (NF_COMPLEX)' - - `4 (NF_COMPLEX16)' - - `5 (NF_COMPLEX32)' - These are for complex numbers. A comment in the GDB source - describes them as Fortran `complex', `double complex', and - `complex*16', respectively, but what does that mean? (i.e., - Single precision? Double precison?). - - `6 (NF_LDOUBLE)' - Long double. This should probably only be used for Sun format - `long double', and new codes should be used for other floating - point formats (`NF_DOUBLE' can be used if a `long double' is - really just an IEEE double, of course). - - BYTES is the number of bytes occupied by the type. This allows a - debugger to perform some operations with the type even if it - doesn't understand FP-TYPE. - -`g TYPE-INFORMATION ; NBITS' - Documented by AIX to define a floating type, but their compiler - actually uses negative type numbers (*note Negative Type - Numbers::.). - -`c TYPE-INFORMATION ; NBITS' - Documented by AIX to define a complex type, but their compiler - actually uses negative type numbers (*note Negative Type - Numbers::.). - - The C `void' type is defined as a signed integral type 0 bits long: - .stabs "void:t19=bs0;0;0",128,0,0,0 - The Solaris compiler seems to omit the trailing semicolon in this -case. Getting sloppy in this way is not a swift move because if a type -is embedded in a more complex expression it is necessary to be able to -tell where it ends. - - I'm not sure how a boolean type is represented. - - -File: stabs.info, Node: Negative Type Numbers, Prev: Builtin Type Descriptors, Up: Builtin Types - -Negative Type Numbers ---------------------- - - This is the method used in XCOFF for defining builtin types. Since -the debugger knows about the builtin types anyway, the idea of negative -type numbers is simply to give a special type number which indicates -the builtin type. There is no stab defining these types. - - There are several subtle issues with negative type numbers. - - One is the size of the type. A builtin type (for example the C types -`int' or `long') might have different sizes depending on compiler -options, the target architecture, the ABI, etc. This issue doesn't -come up for IBM tools since (so far) they just target the RS/6000; the -sizes indicated below for each size are what the IBM RS/6000 tools use. -To deal with differing sizes, either define separate negative type -numbers for each size (which works but requires changing the debugger, -and, unless you get both AIX dbx and GDB to accept the change, -introduces an incompatibility), or use a type attribute (*note String -Field::.) to define a new type with the appropriate size (which merely -requires a debugger which understands type attributes, like AIX dbx or -GDB). For example, - - .stabs "boolean:t10=@s8;-16",128,0,0,0 - - defines an 8-bit boolean type, and - - .stabs "boolean:t10=@s64;-16",128,0,0,0 - - defines a 64-bit boolean type. - - A similar issue is the format of the type. This comes up most often -for floating-point types, which could have various formats (particularly -extended doubles, which vary quite a bit even among IEEE systems). -Again, it is best to define a new negative type number for each -different format; changing the format based on the target system has -various problems. One such problem is that the Alpha has both VAX and -IEEE floating types. One can easily imagine one library using the VAX -types and another library in the same executable using the IEEE types. -Another example is that the interpretation of whether a boolean is true -or false can be based on the least significant bit, most significant -bit, whether it is zero, etc., and different compilers (or different -options to the same compiler) might provide different kinds of boolean. - - The last major issue is the names of the types. The name of a given -type depends *only* on the negative type number given; these do not -vary depending on the language, the target system, or anything else. -One can always define separate type numbers--in the following list you -will see for example separate `int' and `integer*4' types which are -identical except for the name. But compatibility can be maintained by -not inventing new negative type numbers and instead just defining a new -type with a new name. For example: - - .stabs "CARDINAL:t10=-8",128,0,0,0 - - Here is the list of negative type numbers. The phrase "integral -type" is used to mean twos-complement (I strongly suspect that all -machines which use stabs use twos-complement; most machines use -twos-complement these days). - -`-1' - `int', 32 bit signed integral type. - -`-2' - `char', 8 bit type holding a character. Both GDB and dbx on AIX - treat this as signed. GCC uses this type whether `char' is signed - or not, which seems like a bad idea. The AIX compiler (`xlc') - seems to avoid this type; it uses -5 instead for `char'. - -`-3' - `short', 16 bit signed integral type. - -`-4' - `long', 32 bit signed integral type. - -`-5' - `unsigned char', 8 bit unsigned integral type. - -`-6' - `signed char', 8 bit signed integral type. - -`-7' - `unsigned short', 16 bit unsigned integral type. - -`-8' - `unsigned int', 32 bit unsigned integral type. - -`-9' - `unsigned', 32 bit unsigned integral type. - -`-10' - `unsigned long', 32 bit unsigned integral type. - -`-11' - `void', type indicating the lack of a value. - -`-12' - `float', IEEE single precision. - -`-13' - `double', IEEE double precision. - -`-14' - `long double', IEEE double precision. The compiler claims the size - will increase in a future release, and for binary compatibility - you have to avoid using `long double'. I hope when they increase - it they use a new negative type number. - -`-15' - `integer'. 32 bit signed integral type. - -`-16' - `boolean'. 32 bit type. GDB and GCC assume that zero is false, - one is true, and other values have unspecified meaning. I hope - this agrees with how the IBM tools use the type. - -`-17' - `short real'. IEEE single precision. - -`-18' - `real'. IEEE double precision. - -`-19' - `stringptr'. *Note Strings::. - -`-20' - `character', 8 bit unsigned character type. - -`-21' - `logical*1', 8 bit type. This Fortran type has a split - personality in that it is used for boolean variables, but can also - be used for unsigned integers. 0 is false, 1 is true, and other - values are non-boolean. - -`-22' - `logical*2', 16 bit type. This Fortran type has a split - personality in that it is used for boolean variables, but can also - be used for unsigned integers. 0 is false, 1 is true, and other - values are non-boolean. - -`-23' - `logical*4', 32 bit type. This Fortran type has a split - personality in that it is used for boolean variables, but can also - be used for unsigned integers. 0 is false, 1 is true, and other - values are non-boolean. - -`-24' - `logical', 32 bit type. This Fortran type has a split personality - in that it is used for boolean variables, but can also be used for - unsigned integers. 0 is false, 1 is true, and other values are - non-boolean. - -`-25' - `complex'. A complex type consisting of two IEEE single-precision - floating point values. - -`-26' - `complex'. A complex type consisting of two IEEE double-precision - floating point values. - -`-27' - `integer*1', 8 bit signed integral type. - -`-28' - `integer*2', 16 bit signed integral type. - -`-29' - `integer*4', 32 bit signed integral type. - -`-30' - `wchar'. Wide character, 16 bits wide, unsigned (what format? - Unicode?). - -`-31' - `long long', 64 bit signed integral type. - -`-32' - `unsigned long long', 64 bit unsigned integral type. - -`-33' - `logical*8', 64 bit unsigned integral type. - -`-34' - `integer*8', 64 bit signed integral type. - - -File: stabs.info, Node: Miscellaneous Types, Next: Cross-References, Prev: Builtin Types, Up: Types - -Miscellaneous Types -=================== - -`b TYPE-INFORMATION ; BYTES' - Pascal space type. This is documented by IBM; what does it mean? - - This use of the `b' type descriptor can be distinguished from its - use for builtin integral types (*note Builtin Type Descriptors::.) - because the character following the type descriptor is always a - digit, `(', or `-'. - -`B TYPE-INFORMATION' - A volatile-qualified version of TYPE-INFORMATION. This is a Sun - extension. References and stores to a variable with a - volatile-qualified type must not be optimized or cached; they must - occur as the user specifies them. - -`d TYPE-INFORMATION' - File of type TYPE-INFORMATION. As far as I know this is only used - by Pascal. - -`k TYPE-INFORMATION' - A const-qualified version of TYPE-INFORMATION. This is a Sun - extension. A variable with a const-qualified type cannot be - modified. - -`M TYPE-INFORMATION ; LENGTH' - Multiple instance type. The type seems to composed of LENGTH - repetitions of TYPE-INFORMATION, for example `character*3' is - represented by `M-2;3', where `-2' is a reference to a character - type (*note Negative Type Numbers::.). I'm not sure how this - differs from an array. This appears to be a Fortran feature. - LENGTH is a bound, like those in range types; see *Note - Subranges::. - -`S TYPE-INFORMATION' - Pascal set type. TYPE-INFORMATION must be a small type such as an - enumeration or a subrange, and the type is a bitmask whose length - is specified by the number of elements in TYPE-INFORMATION. - - In CHILL, if it is a bitstring instead of a set, also use the `S' - type attribute (*note String Field::.). - -`* TYPE-INFORMATION' - Pointer to TYPE-INFORMATION. - - -File: stabs.info, Node: Cross-References, Next: Subranges, Prev: Miscellaneous Types, Up: Types - -Cross-References to Other Types -=============================== - - A type can be used before it is defined; one common way to deal with -that situation is just to use a type reference to a type which has not -yet been defined. - - Another way is with the `x' type descriptor, which is followed by -`s' for a structure tag, `u' for a union tag, or `e' for a enumerator -tag, followed by the name of the tag, followed by `:'. If the name -contains `::' between a `<' and `>' pair (for C++ templates), such a -`::' does not end the name--only a single `:' ends the name; see *Note -Nested Symbols::. - - For example, the following C declarations: - - struct foo; - struct foo *bar; - -produce: - - .stabs "bar:G16=*17=xsfoo:",32,0,0,0 - - Not all debuggers support the `x' type descriptor, so on some -machines GCC does not use it. I believe that for the above example it -would just emit a reference to type 17 and never define it, but I -haven't verified that. - - Modula-2 imported types, at least on AIX, use the `i' type -descriptor, which is followed by the name of the module from which the -type is imported, followed by `:', followed by the name of the type. -There is then optionally a comma followed by type information for the -type. This differs from merely naming the type (*note Typedefs::.) in -that it identifies the module; I don't understand whether the name of -the type given here is always just the same as the name we are giving -it, or whether this type descriptor is used with a nameless stab (*note -String Field::.), or what. The symbol ends with `;'. - - -File: stabs.info, Node: Subranges, Next: Arrays, Prev: Cross-References, Up: Types - -Subrange Types -============== - - The `r' type descriptor defines a type as a subrange of another -type. It is followed by type information for the type of which it is a -subrange, a semicolon, an integral lower bound, a semicolon, an -integral upper bound, and a semicolon. The AIX documentation does not -specify the trailing semicolon, in an effort to specify array indexes -more cleanly, but a subrange which is not an array index has always -included a trailing semicolon (*note Arrays::.). - - Instead of an integer, either bound can be one of the following: - -`A OFFSET' - The bound is passed by reference on the stack at offset OFFSET - from the argument list. *Note Parameters::, for more information - on such offsets. - -`T OFFSET' - The bound is passed by value on the stack at offset OFFSET from - the argument list. - -`a REGISTER-NUMBER' - The bound is pased by reference in register number REGISTER-NUMBER. - -`t REGISTER-NUMBER' - The bound is passed by value in register number REGISTER-NUMBER. - -`J' - There is no bound. - - Subranges are also used for builtin types; see *Note Traditional -Builtin Types::. - - -File: stabs.info, Node: Arrays, Next: Strings, Prev: Subranges, Up: Types - -Array Types -=========== - - Arrays use the `a' type descriptor. Following the type descriptor -is the type of the index and the type of the array elements. If the -index type is a range type, it ends in a semicolon; otherwise (for -example, if it is a type reference), there does not appear to be any -way to tell where the types are separated. In an effort to clean up -this mess, IBM documents the two types as being separated by a -semicolon, and a range type as not ending in a semicolon (but this is -not right for range types which are not array indexes, *note -Subranges::.). I think probably the best solution is to specify that a -semicolon ends a range type, and that the index type and element type -of an array are separated by a semicolon, but that if the index type is -a range type, the extra semicolon can be omitted. GDB (at least -through version 4.9) doesn't support any kind of index type other than a -range anyway; I'm not sure about dbx. - - It is well established, and widely used, that the type of the index, -unlike most types found in the stabs, is merely a type definition, not -type information (*note String Field::.) (that is, it need not start -with `TYPE-NUMBER=' if it is defining a new type). According to a -comment in GDB, this is also true of the type of the array elements; it -gives `ar1;1;10;ar1;1;10;4' as a legitimate way to express a two -dimensional array. According to AIX documentation, the element type -must be type information. GDB accepts either. - - The type of the index is often a range type, expressed as the type -descriptor `r' and some parameters. It defines the size of the array. -In the example below, the range `r1;0;2;' defines an index type which -is a subrange of type 1 (integer), with a lower bound of 0 and an upper -bound of 2. This defines the valid range of subscripts of a -three-element C array. - - For example, the definition: - - char char_vec[3] = {'a','b','c'}; - -produces the output: - - .stabs "char_vec:G19=ar1;0;2;2",32,0,0,0 - .global _char_vec - .align 4 - _char_vec: - .byte 97 - .byte 98 - .byte 99 - - If an array is "packed", the elements are spaced more closely than -normal, saving memory at the expense of speed. For example, an array -of 3-byte objects might, if unpacked, have each element aligned on a -4-byte boundary, but if packed, have no padding. One way to specify -that something is packed is with type attributes (*note String -Field::.). In the case of arrays, another is to use the `P' type -descriptor instead of `a'. Other than specifying a packed array, `P' -is identical to `a'. - - An open array is represented by the `A' type descriptor followed by -type information specifying the type of the array elements. - - An N-dimensional dynamic array is represented by - - D DIMENSIONS ; TYPE-INFORMATION - - DIMENSIONS is the number of dimensions; TYPE-INFORMATION specifies -the type of the array elements. - - A subarray of an N-dimensional array is represented by - - E DIMENSIONS ; TYPE-INFORMATION - - DIMENSIONS is the number of dimensions; TYPE-INFORMATION specifies -the type of the array elements. - - -File: stabs.info, Node: Strings, Next: Enumerations, Prev: Arrays, Up: Types - -Strings -======= - - Some languages, like C or the original Pascal, do not have string -types, they just have related things like arrays of characters. But -most Pascals and various other languages have string types, which are -indicated as follows: - -`n TYPE-INFORMATION ; BYTES' - BYTES is the maximum length. I'm not sure what TYPE-INFORMATION - is; I suspect that it means that this is a string of - TYPE-INFORMATION (thus allowing a string of integers, a string of - wide characters, etc., as well as a string of characters). Not - sure what the format of this type is. This is an AIX feature. - -`z TYPE-INFORMATION ; BYTES' - Just like `n' except that this is a gstring, not an ordinary - string. I don't know the difference. - -`N' - Pascal Stringptr. What is this? This is an AIX feature. - - Languages, such as CHILL which have a string type which is basically -just an array of characters use the `S' type attribute (*note String -Field::.). - - -File: stabs.info, Node: Enumerations, Next: Structures, Prev: Strings, Up: Types - -Enumerations -============ - - Enumerations are defined with the `e' type descriptor. - - The source line below declares an enumeration type at file scope. -The type definition is located after the `N_RBRAC' that marks the end of -the previous procedure's block scope, and before the `N_FUN' that marks -the beginning of the next procedure's block scope. Therefore it does -not describe a block local symbol, but a file local one. - - The source line: - - enum e_places {first,second=3,last}; - -generates the following stab: - - .stabs "e_places:T22=efirst:0,second:3,last:4,;",128,0,0,0 - - The symbol descriptor (`T') says that the stab describes a -structure, enumeration, or union tag. The type descriptor `e', -following the `22=' of the type definition narrows it down to an -enumeration type. Following the `e' is a list of the elements of the -enumeration. The format is `NAME:VALUE,'. The list of elements ends -with `;'. The fact that VALUE is specified as an integer can cause -problems if the value is large. GCC 2.5.2 tries to output it in octal -in that case with a leading zero, which is probably a good thing, -although GDB 4.11 supports octal only in cases where decimal is -perfectly good. Negative decimal values are supported by both GDB and -dbx. - - There is no standard way to specify the size of an enumeration type; -it is determined by the architecture (normally all enumerations types -are 32 bits). Type attributes can be used to specify an enumeration -type of another size for debuggers which support them; see *Note String -Field::. - - Enumeration types are unusual in that they define symbols for the -enumeration values (`first', `second', and `third' in the above -example), and even though these symbols are visible in the file as a -whole (rather than being in a more local namespace like structure -member names), they are defined in the type definition for the -enumeration type rather than each having their own symbol. In order to -be fast, GDB will only get symbols from such types (in its initial scan -of the stabs) if the type is the first thing defined after a `T' or `t' -symbol descriptor (the above example fulfills this requirement). If -the type does not have a name, the compiler should emit it in a -nameless stab (*note String Field::.); GCC does this. - - -File: stabs.info, Node: Structures, Next: Typedefs, Prev: Enumerations, Up: Types - -Structures -========== - - The encoding of structures in stabs can be shown with an example. - - The following source code declares a structure tag and defines an -instance of the structure in global scope. Then a `typedef' equates the -structure tag with a new type. Seperate stabs are generated for the -structure tag, the structure `typedef', and the structure instance. The -stabs for the tag and the `typedef' are emited when the definitions are -encountered. Since the structure elements are not initialized, the -stab and code for the structure variable itself is located at the end -of the program in the bss section. - - struct s_tag { - int s_int; - float s_float; - char s_char_vec[8]; - struct s_tag* s_next; - } g_an_s; - - typedef struct s_tag s_typedef; - - The structure tag has an `N_LSYM' stab type because, like the -enumeration, the symbol has file scope. Like the enumeration, the -symbol descriptor is `T', for enumeration, structure, or tag type. The -type descriptor `s' following the `16=' of the type definition narrows -the symbol type to structure. - - Following the `s' type descriptor is the number of bytes the -structure occupies, followed by a description of each structure element. -The structure element descriptions are of the form NAME:TYPE, BIT -OFFSET FROM THE START OF THE STRUCT, NUMBER OF BITS IN THE ELEMENT. - - # 128 is N_LSYM - .stabs "s_tag:T16=s20s_int:1,0,32;s_float:12,32,32; - s_char_vec:17=ar1;0;7;2,64,64;s_next:18=*16,128,32;;",128,0,0,0 - - In this example, the first two structure elements are previously -defined types. For these, the type following the `NAME:' part of the -element description is a simple type reference. The other two structure -elements are new types. In this case there is a type definition -embedded after the `NAME:'. The type definition for the array element -looks just like a type definition for a standalone array. The `s_next' -field is a pointer to the same kind of structure that the field is an -element of. So the definition of structure type 16 contains a type -definition for an element which is a pointer to type 16. - - If a field is a static member (this is a C++ feature in which a -single variable appears to be a field of every structure of a given -type) it still starts out with the field name, a colon, and the type, -but then instead of a comma, bit position, comma, and bit size, there -is a colon followed by the name of the variable which each such field -refers to. - - If the structure has methods (a C++ feature), they follow the -non-method fields; see *Note Cplusplus::. - - -File: stabs.info, Node: Typedefs, Next: Unions, Prev: Structures, Up: Types - -Giving a Type a Name -==================== - - To give a type a name, use the `t' symbol descriptor. The type is -specified by the type information (*note String Field::.) for the stab. -For example, - - .stabs "s_typedef:t16",128,0,0,0 # 128 is N_LSYM - - specifies that `s_typedef' refers to type number 16. Such stabs -have symbol type `N_LSYM' (or `C_DECL' for XCOFF). (The Sun -documentation mentions using `N_GSYM' in some cases). - - If you are specifying the tag name for a structure, union, or -enumeration, use the `T' symbol descriptor instead. I believe C is the -only language with this feature. - - If the type is an opaque type (I believe this is a Modula-2 feature), -AIX provides a type descriptor to specify it. The type descriptor is -`o' and is followed by a name. I don't know what the name means--is it -always the same as the name of the type, or is this type descriptor -used with a nameless stab (*note String Field::.)? There optionally -follows a comma followed by type information which defines the type of -this type. If omitted, a semicolon is used in place of the comma and -the type information, and the type is much like a generic pointer -type--it has a known size but little else about it is specified. - - -File: stabs.info, Node: Unions, Next: Function Types, Prev: Typedefs, Up: Types - -Unions -====== - - union u_tag { - int u_int; - float u_float; - char* u_char; - } an_u; - - This code generates a stab for a union tag and a stab for a union -variable. Both use the `N_LSYM' stab type. If a union variable is -scoped locally to the procedure in which it is defined, its stab is -located immediately preceding the `N_LBRAC' for the procedure's block -start. - - The stab for the union tag, however, is located preceding the code -for the procedure in which it is defined. The stab type is `N_LSYM'. -This would seem to imply that the union type is file scope, like the -struct type `s_tag'. This is not true. The contents and position of -the stab for `u_type' do not convey any infomation about its procedure -local scope. - - # 128 is N_LSYM - .stabs "u_tag:T23=u4u_int:1,0,32;u_float:12,0,32;u_char:21,0,32;;", - 128,0,0,0 - - The symbol descriptor `T', following the `name:' means that the stab -describes an enumeration, structure, or union tag. The type descriptor -`u', following the `23=' of the type definition, narrows it down to a -union type definition. Following the `u' is the number of bytes in the -union. After that is a list of union element descriptions. Their -format is NAME:TYPE, BIT OFFSET INTO THE UNION, NUMBER OF BYTES FOR THE -ELEMENT;. - - The stab for the union variable is: - - .stabs "an_u:23",128,0,0,-20 # 128 is N_LSYM - - `-20' specifies where the variable is stored (*note Stack -Variables::.). - - -File: stabs.info, Node: Function Types, Prev: Unions, Up: Types - -Function Types -============== - - Various types can be defined for function variables. These types are -not used in defining functions (*note Procedures::.); they are used for -things like pointers to functions. - - The simple, traditional, type is type descriptor `f' is followed by -type information for the return type of the function, followed by a -semicolon. - - This does not deal with functions for which the number and types of -the parameters are part of the type, as in Modula-2 or ANSI C. AIX -provides extensions to specify these, using the `f', `F', `p', and `R' -type descriptors. - - First comes the type descriptor. If it is `f' or `F', this type -involves a function rather than a procedure, and the type information -for the return type of the function follows, followed by a comma. Then -comes the number of parameters to the function and a semicolon. Then, -for each parameter, there is the name of the parameter followed by a -colon (this is only present for type descriptors `R' and `F' which -represent Pascal function or procedure parameters), type information -for the parameter, a comma, 0 if passed by reference or 1 if passed by -value, and a semicolon. The type definition ends with a semicolon. - - For example, this variable definition: - - int (*g_pf)(); - -generates the following code: - - .stabs "g_pf:G24=*25=f1",32,0,0,0 - .common _g_pf,4,"bss" - - The variable defines a new type, 24, which is a pointer to another -new type, 25, which is a function returning `int'. - - -File: stabs.info, Node: Symbol Tables, Next: Cplusplus, Prev: Types, Up: Top - -Symbol Information in Symbol Tables -*********************************** - - This chapter describes the format of symbol table entries and how -stab assembler directives map to them. It also describes the -transformations that the assembler and linker make on data from stabs. - -* Menu: - -* Symbol Table Format:: -* Transformations On Symbol Tables:: - - -File: stabs.info, Node: Symbol Table Format, Next: Transformations On Symbol Tables, Up: Symbol Tables - -Symbol Table Format -=================== - - Each time the assembler encounters a stab directive, it puts each -field of the stab into a corresponding field in a symbol table entry of -its output file. If the stab contains a string field, the symbol table -entry for that stab points to a string table entry containing the -string data from the stab. Assembler labels become relocatable -addresses. Symbol table entries in a.out have the format: - - struct internal_nlist { - unsigned long n_strx; /* index into string table of name */ - unsigned char n_type; /* type of symbol */ - unsigned char n_other; /* misc info (usually empty) */ - unsigned short n_desc; /* description field */ - bfd_vma n_value; /* value of symbol */ - }; - - If the stab has a string, the `n_strx' field holds the offset in -bytes of the string within the string table. The string is terminated -by a NUL character. If the stab lacks a string (for example, it was -produced by a `.stabn' or `.stabd' directive), the `n_strx' field is -zero. - - Symbol table entries with `n_type' field values greater than 0x1f -originated as stabs generated by the compiler (with one random -exception). The other entries were placed in the symbol table of the -executable by the assembler or the linker. - - -File: stabs.info, Node: Transformations On Symbol Tables, Prev: Symbol Table Format, Up: Symbol Tables - -Transformations on Symbol Tables -================================ - - The linker concatenates object files and does fixups of externally -defined symbols. - - You can see the transformations made on stab data by the assembler -and linker by examining the symbol table after each pass of the build. -To do this, use `nm -ap', which dumps the symbol table, including -debugging information, unsorted. For stab entries the columns are: -VALUE, OTHER, DESC, TYPE, STRING. For assembler and linker symbols, -the columns are: VALUE, TYPE, STRING. - - The low 5 bits of the stab type tell the linker how to relocate the -value of the stab. Thus for stab types like `N_RSYM' and `N_LSYM', -where the value is an offset or a register number, the low 5 bits are -`N_ABS', which tells the linker not to relocate the value. - - Where the value of a stab contains an assembly language label, it is -transformed by each build step. The assembler turns it into a -relocatable address and the linker turns it into an absolute address. - -* Menu: - -* Transformations On Static Variables:: -* Transformations On Global Variables:: -* Stab Section Transformations:: For some object file formats, - things are a bit different. - - -File: stabs.info, Node: Transformations On Static Variables, Next: Transformations On Global Variables, Up: Transformations On Symbol Tables - -Transformations on Static Variables ------------------------------------ - - This source line defines a static variable at file scope: - - static int s_g_repeat - -The following stab describes the symbol: - - .stabs "s_g_repeat:S1",38,0,0,_s_g_repeat - -The assembler transforms the stab into this symbol table entry in the -`.o' file. The location is expressed as a data segment offset. - - 00000084 - 00 0000 STSYM s_g_repeat:S1 - -In the symbol table entry from the executable, the linker has made the -relocatable address absolute. - - 0000e00c - 00 0000 STSYM s_g_repeat:S1 - - -File: stabs.info, Node: Transformations On Global Variables, Next: Stab Section Transformations, Prev: Transformations On Static Variables, Up: Transformations On Symbol Tables - -Transformations on Global Variables ------------------------------------ - - Stabs for global variables do not contain location information. In -this case, the debugger finds location information in the assembler or -linker symbol table entry describing the variable. The source line: - - char g_foo = 'c'; - -generates the stab: - - .stabs "g_foo:G2",32,0,0,0 - - The variable is represented by two symbol table entries in the object -file (see below). The first one originated as a stab. The second one -is an external symbol. The upper case `D' signifies that the `n_type' -field of the symbol table contains 7, `N_DATA' with local linkage. The -stab's value is zero since the value is not used for `N_GSYM' stabs. -The value of the linker symbol is the relocatable address corresponding -to the variable. - - 00000000 - 00 0000 GSYM g_foo:G2 - 00000080 D _g_foo - -These entries as transformed by the linker. The linker symbol table -entry now holds an absolute address: - - 00000000 - 00 0000 GSYM g_foo:G2 - ... - 0000e008 D _g_foo - - -File: stabs.info, Node: Stab Section Transformations, Prev: Transformations On Global Variables, Up: Transformations On Symbol Tables - -Transformations of Stabs in separate sections ---------------------------------------------- - - For object file formats using stabs in separate sections (*note Stab -Sections::.), use `objdump --stabs' instead of `nm' to show the stabs -in an object or executable file. `objdump' is a GNU utility; Sun does -not provide any equivalent. - - The following example is for a stab whose value is an address is -relative to the compilation unit (*note ELF Linker Relocation::.). For -example, if the source line - - static int ld = 5; - - appears within a function, then the assembly language output from the -compiler contains: - - .Ddata.data: - ... - .stabs "ld:V(0,3)",0x26,0,4,.L18-Ddata.data # 0x26 is N_STSYM - ... - .L18: - .align 4 - .word 0x5 - - Because the value is formed by subtracting one symbol from another, -the value is absolute, not relocatable, and so the object file contains - - Symnum n_type n_othr n_desc n_value n_strx String - 31 STSYM 0 4 00000004 680 ld:V(0,3) - - without any relocations, and the executable file also contains - - Symnum n_type n_othr n_desc n_value n_strx String - 31 STSYM 0 4 00000004 680 ld:V(0,3) - - -File: stabs.info, Node: Cplusplus, Next: Stab Types, Prev: Symbol Tables, Up: Top - -GNU C++ Stabs -************* - -* Menu: - -* Class Names:: C++ class names are both tags and typedefs. -* Nested Symbols:: C++ symbol names can be within other types. -* Basic Cplusplus Types:: -* Simple Classes:: -* Class Instance:: -* Methods:: Method definition -* Method Type Descriptor:: The `#' type descriptor -* Member Type Descriptor:: The `@' type descriptor -* Protections:: -* Method Modifiers:: -* Virtual Methods:: -* Inheritence:: -* Virtual Base Classes:: -* Static Members:: - - -File: stabs.info, Node: Class Names, Next: Nested Symbols, Up: Cplusplus - -C++ Class Names -=============== - - In C++, a class name which is declared with `class', `struct', or -`union', is not only a tag, as in C, but also a type name. Thus there -should be stabs with both `t' and `T' symbol descriptors (*note -Typedefs::.). - - To save space, there is a special abbreviation for this case. If the -`T' symbol descriptor is followed by `t', then the stab defines both a -type name and a tag. - - For example, the C++ code - - struct foo {int x;}; - - can be represented as either - - .stabs "foo:T19=s4x:1,0,32;;",128,0,0,0 # 128 is N_LSYM - .stabs "foo:t19",128,0,0,0 - - or - - .stabs "foo:Tt19=s4x:1,0,32;;",128,0,0,0 - - -File: stabs.info, Node: Nested Symbols, Next: Basic Cplusplus Types, Prev: Class Names, Up: Cplusplus - -Defining a Symbol Within Another Type -===================================== - - In C++, a symbol (such as a type name) can be defined within another -type. - - In stabs, this is sometimes represented by making the name of a -symbol which contains `::'. Such a pair of colons does not end the name -of the symbol, the way a single colon would (*note String Field::.). -I'm not sure how consistently used or well thought out this mechanism -is. So that a pair of colons in this position always has this meaning, -`:' cannot be used as a symbol descriptor. - - For example, if the string for a stab is `foo::bar::baz:t5=*6', then -`foo::bar::baz' is the name of the symbol, `t' is the symbol -descriptor, and `5=*6' is the type information. - - -File: stabs.info, Node: Basic Cplusplus Types, Next: Simple Classes, Prev: Nested Symbols, Up: Cplusplus - -Basic Types For C++ -=================== - - << the examples that follow are based on a01.C >> - - C++ adds two more builtin types to the set defined for C. These are -the unknown type and the vtable record type. The unknown type, type -16, is defined in terms of itself like the void type. - - The vtable record type, type 17, is defined as a structure type and -then as a structure tag. The structure has four fields: delta, index, -pfn, and delta2. pfn is the function pointer. - - << In boilerplate $vtbl_ptr_type, what are the fields delta, index, -and delta2 used for? >> - - This basic type is present in all C++ programs even if there are no -virtual methods defined. - - .stabs "struct_name:sym_desc(type)type_def(17)=type_desc(struct)struct_bytes(8) - elem_name(delta):type_ref(short int),bit_offset(0),field_bits(16); - elem_name(index):type_ref(short int),bit_offset(16),field_bits(16); - elem_name(pfn):type_def(18)=type_desc(ptr to)type_ref(void), - bit_offset(32),field_bits(32); - elem_name(delta2):type_def(short int);bit_offset(32),field_bits(16);;" - N_LSYM, NIL, NIL - - .stabs "$vtbl_ptr_type:t17=s8 - delta:6,0,16;index:6,16,16;pfn:18=*15,32,32;delta2:6,32,16;;" - ,128,0,0,0 - - .stabs "name:sym_dec(struct tag)type_ref($vtbl_ptr_type)",N_LSYM,NIL,NIL,NIL - - .stabs "$vtbl_ptr_type:T17",128,0,0,0 - - -File: stabs.info, Node: Simple Classes, Next: Class Instance, Prev: Basic Cplusplus Types, Up: Cplusplus - -Simple Class Definition -======================= - - The stabs describing C++ language features are an extension of the -stabs describing C. Stabs representing C++ class types elaborate -extensively on the stab format used to describe structure types in C. -Stabs representing class type variables look just like stabs -representing C language variables. - - Consider the following very simple class definition. - - class baseA { - public: - int Adat; - int Ameth(int in, char other); - }; - - The class `baseA' is represented by two stabs. The first stab -describes the class as a structure type. The second stab describes a -structure tag of the class type. Both stabs are of stab type `N_LSYM'. -Since the stab is not located between an `N_FUN' and an `N_LBRAC' stab -this indicates that the class is defined at file scope. If it were, -then the `N_LSYM' would signify a local variable. - - A stab describing a C++ class type is similar in format to a stab -describing a C struct, with each class member shown as a field in the -structure. The part of the struct format describing fields is expanded -to include extra information relevent to C++ class members. In -addition, if the class has multiple base classes or virtual functions -the struct format outside of the field parts is also augmented. - - In this simple example the field part of the C++ class stab -representing member data looks just like the field part of a C struct -stab. The section on protections describes how its format is sometimes -extended for member data. - - The field part of a C++ class stab representing a member function -differs substantially from the field part of a C struct stab. It still -begins with `name:' but then goes on to define a new type number for -the member function, describe its return type, its argument types, its -protection level, any qualifiers applied to the method definition, and -whether the method is virtual or not. If the method is virtual then -the method description goes on to give the vtable index of the method, -and the type number of the first base class defining the method. - - When the field name is a method name it is followed by two colons -rather than one. This is followed by a new type definition for the -method. This is a number followed by an equal sign and the type of the -method. Normally this will be a type declared using the `#' type -descriptor; see *Note Method Type Descriptor::; static member functions -are declared using the `f' type descriptor instead; see *Note Function -Types::. - - The format of an overloaded operator method name differs from that of -other methods. It is `op$::OPERATOR-NAME.' where OPERATOR-NAME is the -operator name such as `+' or `+='. The name ends with a period, and -any characters except the period can occur in the OPERATOR-NAME string. - - The next part of the method description represents the arguments to -the method, preceeded by a colon and ending with a semi-colon. The -types of the arguments are expressed in the same way argument types are -expressed in C++ name mangling. In this example an `int' and a `char' -map to `ic'. - - This is followed by a number, a letter, and an asterisk or period, -followed by another semicolon. The number indicates the protections -that apply to the member function. Here the 2 means public. The -letter encodes any qualifier applied to the method definition. In this -case, `A' means that it is a normal function definition. The dot shows -that the method is not virtual. The sections that follow elaborate -further on these fields and describe the additional information present -for virtual methods. - - .stabs "class_name:sym_desc(type)type_def(20)=type_desc(struct)struct_bytes(4) - field_name(Adat):type(int),bit_offset(0),field_bits(32); - - method_name(Ameth)::type_def(21)=type_desc(method)return_type(int); - :arg_types(int char); - protection(public)qualifier(normal)virtual(no);;" - N_LSYM,NIL,NIL,NIL - - .stabs "baseA:t20=s4Adat:1,0,32;Ameth::21=##1;:ic;2A.;;",128,0,0,0 - - .stabs "class_name:sym_desc(struct tag)",N_LSYM,NIL,NIL,NIL - - .stabs "baseA:T20",128,0,0,0 - diff --git a/gnu/dist/gdb/doc/stabs.info-3 b/gnu/dist/gdb/doc/stabs.info-3 deleted file mode 100644 index 3c99871f99c8..000000000000 --- a/gnu/dist/gdb/doc/stabs.info-3 +++ /dev/null @@ -1,1385 +0,0 @@ -This is Info file stabs.info, produced by Makeinfo version 1.68 from -the input file ../../../devo/gdb/doc/stabs.texinfo. - -START-INFO-DIR-ENTRY -* Stabs: (stabs). The "stabs" debugging information format. -END-INFO-DIR-ENTRY - - This document describes the stabs debugging symbol tables. - - Copyright 1992, 93, 94, 95, 1997 Free Software Foundation, Inc. -Contributed by Cygnus Support. Written by Julia Menapace, Jim Kingdon, -and David MacKenzie. - - 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 or distribute modified versions of this -manual under the terms of the GPL (for which purpose this text may be -regarded as a program in the language TeX). - - -File: stabs.info, Node: Class Instance, Next: Methods, Prev: Simple Classes, Up: Cplusplus - -Class Instance -============== - - As shown above, describing even a simple C++ class definition is -accomplished by massively extending the stab format used in C to -describe structure types. However, once the class is defined, C stabs -with no modifications can be used to describe class instances. The -following source: - - main () { - baseA AbaseA; - } - -yields the following stab describing the class instance. It looks no -different from a standard C stab describing a local variable. - - .stabs "name:type_ref(baseA)", N_LSYM, NIL, NIL, frame_ptr_offset - - .stabs "AbaseA:20",128,0,0,-20 - - -File: stabs.info, Node: Methods, Next: Method Type Descriptor, Prev: Class Instance, Up: Cplusplus - -Method Definition -================= - - The class definition shown above declares Ameth. The C++ source -below defines Ameth: - - int - baseA::Ameth(int in, char other) - { - return in; - }; - - This method definition yields three stabs following the code of the -method. One stab describes the method itself and following two describe -its parameters. Although there is only one formal argument all methods -have an implicit argument which is the `this' pointer. The `this' -pointer is a pointer to the object on which the method was called. Note -that the method name is mangled to encode the class name and argument -types. Name mangling is described in the ARM (`The Annotated C++ -Reference Manual', by Ellis and Stroustrup, ISBN 0-201-51459-1); -`gpcompare.texi' in Cygnus GCC distributions describes the differences -between GNU mangling and ARM mangling. - - .stabs "name:symbol_desriptor(global function)return_type(int)", - N_FUN, NIL, NIL, code_addr_of_method_start - - .stabs "Ameth__5baseAic:F1",36,0,0,_Ameth__5baseAic - - Here is the stab for the `this' pointer implicit argument. The name -of the `this' pointer is always `this'. Type 19, the `this' pointer is -defined as a pointer to type 20, `baseA', but a stab defining `baseA' -has not yet been emited. Since the compiler knows it will be emited -shortly, here it just outputs a cross reference to the undefined -symbol, by prefixing the symbol name with `xs'. - - .stabs "name:sym_desc(register param)type_def(19)= - type_desc(ptr to)type_ref(baseA)= - type_desc(cross-reference to)baseA:",N_RSYM,NIL,NIL,register_number - - .stabs "this:P19=*20=xsbaseA:",64,0,0,8 - - The stab for the explicit integer argument looks just like a -parameter to a C function. The last field of the stab is the offset -from the argument pointer, which in most systems is the same as the -frame pointer. - - .stabs "name:sym_desc(value parameter)type_ref(int)", - N_PSYM,NIL,NIL,offset_from_arg_ptr - - .stabs "in:p1",160,0,0,72 - - << The examples that follow are based on A1.C >> - - -File: stabs.info, Node: Method Type Descriptor, Next: Member Type Descriptor, Prev: Methods, Up: Cplusplus - -The `#' Type Descriptor -======================= - - This is like the `f' type descriptor for functions (*note Function -Types::.), except that a function which uses the `#' type descriptor -takes an extra argument as its first argument, for the `this' pointer. -The `#' type descriptor is optionally followed by the types of the -arguments, then another `#'. If the types of the arguments are -omitted, so that the second `#' immediately follows the `#' which is -the type descriptor, the arguments are being omitted (to save space) -and can be deduced from the mangled name of the method. After the -second `#' there is type information for the return type of the method -and a semicolon. - - Note that although such a type will normally be used to describe -fields in structures, unions, or classes, for at least some versions of -the compiler it can also be used in other contexts. - - -File: stabs.info, Node: Member Type Descriptor, Next: Protections, Prev: Method Type Descriptor, Up: Cplusplus - -The `@' Type Descriptor -======================= - - The `@' type descriptor is for a member (class and variable) type. -It is followed by type information for the offset basetype, a comma, and -type information for the type of the field being pointed to. (FIXME: -this is acknowledged to be gibberish. Can anyone say what really goes -here?). - - Note that there is a conflict between this and type attributes -(*note String Field::.); both use type descriptor `@'. Fortunately, -the `@' type descriptor used in this C++ sense always will be followed -by a digit, `(', or `-', and type attributes never start with those -things. - - -File: stabs.info, Node: Protections, Next: Method Modifiers, Prev: Member Type Descriptor, Up: Cplusplus - -Protections -=========== - - In the simple class definition shown above all member data and -functions were publicly accessable. The example that follows contrasts -public, protected and privately accessable fields and shows how these -protections are encoded in C++ stabs. - - If the character following the `FIELD-NAME:' part of the string is -`/', then the next character is the visibility. `0' means private, `1' -means protected, and `2' means public. Debuggers should ignore -visibility characters they do not recognize, and assume a reasonable -default (such as public) (GDB 4.11 does not, but this should be fixed -in the next GDB release). If no visibility is specified the field is -public. The visibility `9' means that the field has been optimized out -and is public (there is no way to specify an optimized out field with a -private or protected visibility). Visibility `9' is not supported by -GDB 4.11; this should be fixed in the next GDB release. - - The following C++ source: - - class vis { - private: - int priv; - protected: - char prot; - public: - float pub; - }; - -generates the following stab: - - # 128 is N_LSYM - .stabs "vis:T19=s12priv:/01,0,32;prot:/12,32,8;pub:12,64,32;;",128,0,0,0 - - `vis:T19=s12' indicates that type number 19 is a 12 byte structure -named `vis' The `priv' field has public visibility (`/0'), type int -(`1'), and offset and size `,0,32;'. The `prot' field has protected -visibility (`/1'), type char (`2') and offset and size `,32,8;'. The -`pub' field has type float (`12'), and offset and size `,64,32;'. - - Protections for member functions are signified by one digit embeded -in the field part of the stab describing the method. The digit is 0 if -private, 1 if protected and 2 if public. Consider the C++ class -definition below: - - class all_methods { - private: - int priv_meth(int in){return in;}; - protected: - char protMeth(char in){return in;}; - public: - float pubMeth(float in){return in;}; - }; - - It generates the following stab. The digit in question is to the -left of an `A' in each case. Notice also that in this case two symbol -descriptors apply to the class name struct tag and struct type. - - .stabs "class_name:sym_desc(struct tag&type)type_def(21)= - sym_desc(struct)struct_bytes(1) - meth_name::type_def(22)=sym_desc(method)returning(int); - :args(int);protection(private)modifier(normal)virtual(no); - meth_name::type_def(23)=sym_desc(method)returning(char); - :args(char);protection(protected)modifier(normal)virual(no); - meth_name::type_def(24)=sym_desc(method)returning(float); - :args(float);protection(public)modifier(normal)virtual(no);;", - N_LSYM,NIL,NIL,NIL - - .stabs "all_methods:Tt21=s1priv_meth::22=##1;:i;0A.;protMeth::23=##2;:c;1A.; - pubMeth::24=##12;:f;2A.;;",128,0,0,0 - - -File: stabs.info, Node: Method Modifiers, Next: Virtual Methods, Prev: Protections, Up: Cplusplus - -Method Modifiers (`const', `volatile', `const volatile') -======================================================== - - << based on a6.C >> - - In the class example described above all the methods have the normal -modifier. This method modifier information is located just after the -protection information for the method. This field has four possible -character values. Normal methods use `A', const methods use `B', -volatile methods use `C', and const volatile methods use `D'. Consider -the class definition below: - - class A { - public: - int ConstMeth (int arg) const { return arg; }; - char VolatileMeth (char arg) volatile { return arg; }; - float ConstVolMeth (float arg) const volatile {return arg; }; - }; - - This class is described by the following stab: - - .stabs "class(A):sym_desc(struct)type_def(20)=type_desc(struct)struct_bytes(1) - meth_name(ConstMeth)::type_def(21)sym_desc(method) - returning(int);:arg(int);protection(public)modifier(const)virtual(no); - meth_name(VolatileMeth)::type_def(22)=sym_desc(method) - returning(char);:arg(char);protection(public)modifier(volatile)virt(no) - meth_name(ConstVolMeth)::type_def(23)=sym_desc(method) - returning(float);:arg(float);protection(public)modifer(const volatile) - virtual(no);;", ... - - .stabs "A:T20=s1ConstMeth::21=##1;:i;2B.;VolatileMeth::22=##2;:c;2C.; - ConstVolMeth::23=##12;:f;2D.;;",128,0,0,0 - - -File: stabs.info, Node: Virtual Methods, Next: Inheritence, Prev: Method Modifiers, Up: Cplusplus - -Virtual Methods -=============== - - << The following examples are based on a4.C >> - - The presence of virtual methods in a class definition adds additional -data to the class description. The extra data is appended to the -description of the virtual method and to the end of the class -description. Consider the class definition below: - - class A { - public: - int Adat; - virtual int A_virt (int arg) { return arg; }; - }; - - This results in the stab below describing class A. It defines a new -type (20) which is an 8 byte structure. The first field of the class -struct is `Adat', an integer, starting at structure offset 0 and -occupying 32 bits. - - The second field in the class struct is not explicitly defined by the -C++ class definition but is implied by the fact that the class contains -a virtual method. This field is the vtable pointer. The name of the -vtable pointer field starts with `$vf' and continues with a type -reference to the class it is part of. In this example the type -reference for class A is 20 so the name of its vtable pointer field is -`$vf20', followed by the usual colon. - - Next there is a type definition for the vtable pointer type (21). -This is in turn defined as a pointer to another new type (22). - - Type 22 is the vtable itself, which is defined as an array, indexed -by a range of integers between 0 and 1, and whose elements are of type -17. Type 17 was the vtable record type defined by the boilerplate C++ -type definitions, as shown earlier. - - The bit offset of the vtable pointer field is 32. The number of bits -in the field are not specified when the field is a vtable pointer. - - Next is the method definition for the virtual member function -`A_virt'. Its description starts out using the same format as the -non-virtual member functions described above, except instead of a dot -after the `A' there is an asterisk, indicating that the function is -virtual. Since is is virtual some addition information is appended to -the end of the method description. - - The first number represents the vtable index of the method. This is -a 32 bit unsigned number with the high bit set, followed by a -semi-colon. - - The second number is a type reference to the first base class in the -inheritence hierarchy defining the virtual member function. In this -case the class stab describes a base class so the virtual function is -not overriding any other definition of the method. Therefore the -reference is to the type number of the class that the stab is -describing (20). - - This is followed by three semi-colons. One marks the end of the -current sub-section, one marks the end of the method field, and the -third marks the end of the struct definition. - - For classes containing virtual functions the very last section of the -string part of the stab holds a type reference to the first base class. -This is preceeded by `~%' and followed by a final semi-colon. - - .stabs "class_name(A):type_def(20)=sym_desc(struct)struct_bytes(8) - field_name(Adat):type_ref(int),bit_offset(0),field_bits(32); - field_name(A virt func ptr):type_def(21)=type_desc(ptr to)type_def(22)= - sym_desc(array)index_type_ref(range of int from 0 to 1); - elem_type_ref(vtbl elem type), - bit_offset(32); - meth_name(A_virt)::typedef(23)=sym_desc(method)returning(int); - :arg_type(int),protection(public)normal(yes)virtual(yes) - vtable_index(1);class_first_defining(A);;;~%first_base(A);", - N_LSYM,NIL,NIL,NIL - - .stabs "A:t20=s8Adat:1,0,32;$vf20:21=*22=ar1;0;1;17,32; - A_virt::23=##1;:i;2A*-2147483647;20;;;~%20;",128,0,0,0 - - -File: stabs.info, Node: Inheritence, Next: Virtual Base Classes, Prev: Virtual Methods, Up: Cplusplus - -Inheritence -=========== - - Stabs describing C++ derived classes include additional sections that -describe the inheritence hierarchy of the class. A derived class stab -also encodes the number of base classes. For each base class it tells -if the base class is virtual or not, and if the inheritence is private -or public. It also gives the offset into the object of the portion of -the object corresponding to each base class. - - This additional information is embeded in the class stab following -the number of bytes in the struct. First the number of base classes -appears bracketed by an exclamation point and a comma. - - Then for each base type there repeats a series: a virtual character, -a visibilty character, a number, a comma, another number, and a -semi-colon. - - The virtual character is `1' if the base class is virtual and `0' if -not. The visibility character is `2' if the derivation is public, `1' -if it is protected, and `0' if it is private. Debuggers should ignore -virtual or visibility characters they do not recognize, and assume a -reasonable default (such as public and non-virtual) (GDB 4.11 does not, -but this should be fixed in the next GDB release). - - The number following the virtual and visibility characters is the -offset from the start of the object to the part of the object -pertaining to the base class. - - After the comma, the second number is a type_descriptor for the base -type. Finally a semi-colon ends the series, which repeats for each -base class. - - The source below defines three base classes `A', `B', and `C' and -the derived class `D'. - - class A { - public: - int Adat; - virtual int A_virt (int arg) { return arg; }; - }; - - class B { - public: - int B_dat; - virtual int B_virt (int arg) {return arg; }; - }; - - class C { - public: - int Cdat; - virtual int C_virt (int arg) {return arg; }; - }; - - class D : A, virtual B, public C { - public: - int Ddat; - virtual int A_virt (int arg ) { return arg+1; }; - virtual int B_virt (int arg) { return arg+2; }; - virtual int C_virt (int arg) { return arg+3; }; - virtual int D_virt (int arg) { return arg; }; - }; - - Class stabs similar to the ones described earlier are generated for -each base class. - - .stabs "A:T20=s8Adat:1,0,32;$vf20:21=*22=ar1;0;1;17,32; - A_virt::23=##1;:i;2A*-2147483647;20;;;~%20;",128,0,0,0 - - .stabs "B:Tt25=s8Bdat:1,0,32;$vf25:21,32;B_virt::26=##1; - :i;2A*-2147483647;25;;;~%25;",128,0,0,0 - - .stabs "C:Tt28=s8Cdat:1,0,32;$vf28:21,32;C_virt::29=##1; - :i;2A*-2147483647;28;;;~%28;",128,0,0,0 - - In the stab describing derived class `D' below, the information about -the derivation of this class is encoded as follows. - - .stabs "derived_class_name:symbol_descriptors(struct tag&type)= - type_descriptor(struct)struct_bytes(32)!num_bases(3), - base_virtual(no)inheritence_public(no)base_offset(0), - base_class_type_ref(A); - base_virtual(yes)inheritence_public(no)base_offset(NIL), - base_class_type_ref(B); - base_virtual(no)inheritence_public(yes)base_offset(64), - base_class_type_ref(C); ... - - .stabs "D:Tt31=s32!3,000,20;100,25;0264,28;$vb25:24,128;Ddat: - 1,160,32;A_virt::32=##1;:i;2A*-2147483647;20;;B_virt: - :32:i;2A*-2147483647;25;;C_virt::32:i;2A*-2147483647; - 28;;D_virt::32:i;2A*-2147483646;31;;;~%20;",128,0,0,0 - - -File: stabs.info, Node: Virtual Base Classes, Next: Static Members, Prev: Inheritence, Up: Cplusplus - -Virtual Base Classes -==================== - - A derived class object consists of a concatination in memory of the -data areas defined by each base class, starting with the leftmost and -ending with the rightmost in the list of base classes. The exception -to this rule is for virtual inheritence. In the example above, class -`D' inherits virtually from base class `B'. This means that an -instance of a `D' object will not contain its own `B' part but merely a -pointer to a `B' part, known as a virtual base pointer. - - In a derived class stab, the base offset part of the derivation -information, described above, shows how the base class parts are -ordered. The base offset for a virtual base class is always given as 0. -Notice that the base offset for `B' is given as 0 even though `B' is -not the first base class. The first base class `A' starts at offset 0. - - The field information part of the stab for class `D' describes the -field which is the pointer to the virtual base class `B'. The vbase -pointer name is `$vb' followed by a type reference to the virtual base -class. Since the type id for `B' in this example is 25, the vbase -pointer name is `$vb25'. - - .stabs "D:Tt31=s32!3,000,20;100,25;0264,28;$vb25:24,128;Ddat:1, - 160,32;A_virt::32=##1;:i;2A*-2147483647;20;;B_virt::32:i; - 2A*-2147483647;25;;C_virt::32:i;2A*-2147483647;28;;D_virt: - :32:i;2A*-2147483646;31;;;~%20;",128,0,0,0 - - Following the name and a semicolon is a type reference describing the -type of the virtual base class pointer, in this case 24. Type 24 was -defined earlier as the type of the `B' class `this' pointer. The -`this' pointer for a class is a pointer to the class type. - - .stabs "this:P24=*25=xsB:",64,0,0,8 - - Finally the field offset part of the vbase pointer field description -shows that the vbase pointer is the first field in the `D' object, -before any data fields defined by the class. The layout of a `D' class -object is a follows, `Adat' at 0, the vtable pointer for `A' at 32, -`Cdat' at 64, the vtable pointer for C at 96, the virtual base pointer -for `B' at 128, and `Ddat' at 160. - - -File: stabs.info, Node: Static Members, Prev: Virtual Base Classes, Up: Cplusplus - -Static Members -============== - - The data area for a class is a concatenation of the space used by the -data members of the class. If the class has virtual methods, a vtable -pointer follows the class data. The field offset part of each field -description in the class stab shows this ordering. - - << How is this reflected in stabs? See Cygnus bug #677 for some -info. >> - - -File: stabs.info, Node: Stab Types, Next: Symbol Descriptors, Prev: Cplusplus, Up: Top - -Table of Stab Types -******************* - - The following are all the possible values for the stab type field, -for a.out files, in numeric order. This does not apply to XCOFF, but -it does apply to stabs in sections (*note Stab Sections::.). Stabs in -ECOFF use these values but add 0x8f300 to distinguish them from non-stab -symbols. - - The symbolic names are defined in the file `include/aout/stabs.def'. - -* Menu: - -* Non-Stab Symbol Types:: Types from 0 to 0x1f -* Stab Symbol Types:: Types from 0x20 to 0xff - - -File: stabs.info, Node: Non-Stab Symbol Types, Next: Stab Symbol Types, Up: Stab Types - -Non-Stab Symbol Types -===================== - - The following types are used by the linker and assembler, not by stab -directives. Since this document does not attempt to describe aspects of -object file format other than the debugging format, no details are -given. - -`0x0 N_UNDF' - Undefined symbol - -`0x2 N_ABS' - File scope absolute symbol - -`0x3 N_ABS | N_EXT' - External absolute symbol - -`0x4 N_TEXT' - File scope text symbol - -`0x5 N_TEXT | N_EXT' - External text symbol - -`0x6 N_DATA' - File scope data symbol - -`0x7 N_DATA | N_EXT' - External data symbol - -`0x8 N_BSS' - File scope BSS symbol - -`0x9 N_BSS | N_EXT' - External BSS symbol - -`0x0c N_FN_SEQ' - Same as `N_FN', for Sequent compilers - -`0x0a N_INDR' - Symbol is indirected to another symbol - -`0x12 N_COMM' - Common--visible after shared library dynamic link - -`0x14 N_SETA' -`0x15 N_SETA | N_EXT' - Absolute set element - -`0x16 N_SETT' -`0x17 N_SETT | N_EXT' - Text segment set element - -`0x18 N_SETD' -`0x19 N_SETD | N_EXT' - Data segment set element - -`0x1a N_SETB' -`0x1b N_SETB | N_EXT' - BSS segment set element - -`0x1c N_SETV' -`0x1d N_SETV | N_EXT' - Pointer to set vector - -`0x1e N_WARNING' - Print a warning message during linking - -`0x1f N_FN' - File name of a `.o' file - - -File: stabs.info, Node: Stab Symbol Types, Prev: Non-Stab Symbol Types, Up: Stab Types - -Stab Symbol Types -================= - - The following symbol types indicate that this is a stab. This is the -full list of stab numbers, including stab types that are used in -languages other than C. - -`0x20 N_GSYM' - Global symbol; see *Note Global Variables::. - -`0x22 N_FNAME' - Function name (for BSD Fortran); see *Note Procedures::. - -`0x24 N_FUN' - Function name (*note Procedures::.) or text segment variable - (*note Statics::.). - -`0x26 N_STSYM' - Data segment file-scope variable; see *Note Statics::. - -`0x28 N_LCSYM' - BSS segment file-scope variable; see *Note Statics::. - -`0x2a N_MAIN' - Name of main routine; see *Note Main Program::. - -`0x2c N_ROSYM' - Variable in `.rodata' section; see *Note Statics::. - -`0x30 N_PC' - Global symbol (for Pascal); see *Note N_PC::. - -`0x32 N_NSYMS' - Number of symbols (according to Ultrix V4.0); see *Note N_NSYMS::. - -`0x34 N_NOMAP' - No DST map; see *Note N_NOMAP::. - -`0x38 N_OBJ' - Object file (Solaris2). - -`0x3c N_OPT' - Debugger options (Solaris2). - -`0x40 N_RSYM' - Register variable; see *Note Register Variables::. - -`0x42 N_M2C' - Modula-2 compilation unit; see *Note N_M2C::. - -`0x44 N_SLINE' - Line number in text segment; see *Note Line Numbers::. - -`0x46 N_DSLINE' - Line number in data segment; see *Note Line Numbers::. - -`0x48 N_BSLINE' - Line number in bss segment; see *Note Line Numbers::. - -`0x48 N_BROWS' - Sun source code browser, path to `.cb' file; see *Note N_BROWS::. - -`0x4a N_DEFD' - GNU Modula2 definition module dependency; see *Note N_DEFD::. - -`0x4c N_FLINE' - Function start/body/end line numbers (Solaris2). - -`0x50 N_EHDECL' - GNU C++ exception variable; see *Note N_EHDECL::. - -`0x50 N_MOD2' - Modula2 info "for imc" (according to Ultrix V4.0); see *Note - N_MOD2::. - -`0x54 N_CATCH' - GNU C++ `catch' clause; see *Note N_CATCH::. - -`0x60 N_SSYM' - Structure of union element; see *Note N_SSYM::. - -`0x62 N_ENDM' - Last stab for module (Solaris2). - -`0x64 N_SO' - Path and name of source file; see *Note Source Files::. - -`0x80 N_LSYM' - Stack variable (*note Stack Variables::.) or type (*note - Typedefs::.). - -`0x82 N_BINCL' - Beginning of an include file (Sun only); see *Note Include Files::. - -`0x84 N_SOL' - Name of include file; see *Note Include Files::. - -`0xa0 N_PSYM' - Parameter variable; see *Note Parameters::. - -`0xa2 N_EINCL' - End of an include file; see *Note Include Files::. - -`0xa4 N_ENTRY' - Alternate entry point; see *Note Alternate Entry Points::. - -`0xc0 N_LBRAC' - Beginning of a lexical block; see *Note Block Structure::. - -`0xc2 N_EXCL' - Place holder for a deleted include file; see *Note Include Files::. - -`0xc4 N_SCOPE' - Modula2 scope information (Sun linker); see *Note N_SCOPE::. - -`0xe0 N_RBRAC' - End of a lexical block; see *Note Block Structure::. - -`0xe2 N_BCOMM' - Begin named common block; see *Note Common Blocks::. - -`0xe4 N_ECOMM' - End named common block; see *Note Common Blocks::. - -`0xe8 N_ECOML' - Member of a common block; see *Note Common Blocks::. - -`0xea N_WITH' - Pascal `with' statement: type,,0,0,offset (Solaris2). - -`0xf0 N_NBTEXT' - Gould non-base registers; see *Note Gould::. - -`0xf2 N_NBDATA' - Gould non-base registers; see *Note Gould::. - -`0xf4 N_NBBSS' - Gould non-base registers; see *Note Gould::. - -`0xf6 N_NBSTS' - Gould non-base registers; see *Note Gould::. - -`0xf8 N_NBLCS' - Gould non-base registers; see *Note Gould::. - - -File: stabs.info, Node: Symbol Descriptors, Next: Type Descriptors, Prev: Stab Types, Up: Top - -Table of Symbol Descriptors -*************************** - - The symbol descriptor is the character which follows the colon in -many stabs, and which tells what kind of stab it is. *Note String -Field::, for more information about their use. - -`DIGIT' -`(' -`-' - Variable on the stack; see *Note Stack Variables::. - -`:' - C++ nested symbol; see *Note Nested Symbols:: - -`a' - Parameter passed by reference in register; see *Note Reference - Parameters::. - -`b' - Based variable; see *Note Based Variables::. - -`c' - Constant; see *Note Constants::. - -`C' - Conformant array bound (Pascal, maybe other languages); *Note - Conformant Arrays::. Name of a caught exception (GNU C++). These - can be distinguished because the latter uses `N_CATCH' and the - former uses another symbol type. - -`d' - Floating point register variable; see *Note Register Variables::. - -`D' - Parameter in floating point register; see *Note Register - Parameters::. - -`f' - File scope function; see *Note Procedures::. - -`F' - Global function; see *Note Procedures::. - -`G' - Global variable; see *Note Global Variables::. - -`i' - *Note Register Parameters::. - -`I' - Internal (nested) procedure; see *Note Nested Procedures::. - -`J' - Internal (nested) function; see *Note Nested Procedures::. - -`L' - Label name (documented by AIX, no further information known). - -`m' - Module; see *Note Procedures::. - -`p' - Argument list parameter; see *Note Parameters::. - -`pP' - *Note Parameters::. - -`pF' - Fortran Function parameter; see *Note Parameters::. - -`P' - Unfortunately, three separate meanings have been independently - invented for this symbol descriptor. At least the GNU and Sun - uses can be distinguished by the symbol type. Global Procedure - (AIX) (symbol type used unknown); see *Note Procedures::. - Register parameter (GNU) (symbol type `N_PSYM'); see *Note - Parameters::. Prototype of function referenced by this file (Sun - `acc') (symbol type `N_FUN'). - -`Q' - Static Procedure; see *Note Procedures::. - -`R' - Register parameter; see *Note Register Parameters::. - -`r' - Register variable; see *Note Register Variables::. - -`S' - File scope variable; see *Note Statics::. - -`s' - Local variable (OS9000). - -`t' - Type name; see *Note Typedefs::. - -`T' - Enumeration, structure, or union tag; see *Note Typedefs::. - -`v' - Parameter passed by reference; see *Note Reference Parameters::. - -`V' - Procedure scope static variable; see *Note Statics::. - -`x' - Conformant array; see *Note Conformant Arrays::. - -`X' - Function return variable; see *Note Parameters::. - - -File: stabs.info, Node: Type Descriptors, Next: Expanded Reference, Prev: Symbol Descriptors, Up: Top - -Table of Type Descriptors -************************* - - The type descriptor is the character which follows the type number -and an equals sign. It specifies what kind of type is being defined. -*Note String Field::, for more information about their use. - -`DIGIT' -`(' - Type reference; see *Note String Field::. - -`-' - Reference to builtin type; see *Note Negative Type Numbers::. - -`#' - Method (C++); see *Note Method Type Descriptor::. - -`*' - Pointer; see *Note Miscellaneous Types::. - -`&' - Reference (C++). - -`@' - Type Attributes (AIX); see *Note String Field::. Member (class - and variable) type (GNU C++); see *Note Member Type Descriptor::. - -`a' - Array; see *Note Arrays::. - -`A' - Open array; see *Note Arrays::. - -`b' - Pascal space type (AIX); see *Note Miscellaneous Types::. Builtin - integer type (Sun); see *Note Builtin Type Descriptors::. Const - and volatile qualfied type (OS9000). - -`B' - Volatile-qualified type; see *Note Miscellaneous Types::. - -`c' - Complex builtin type (AIX); see *Note Builtin Type Descriptors::. - Const-qualified type (OS9000). - -`C' - COBOL Picture type. See AIX documentation for details. - -`d' - File type; see *Note Miscellaneous Types::. - -`D' - N-dimensional dynamic array; see *Note Arrays::. - -`e' - Enumeration type; see *Note Enumerations::. - -`E' - N-dimensional subarray; see *Note Arrays::. - -`f' - Function type; see *Note Function Types::. - -`F' - Pascal function parameter; see *Note Function Types:: - -`g' - Builtin floating point type; see *Note Builtin Type Descriptors::. - -`G' - COBOL Group. See AIX documentation for details. - -`i' - Imported type (AIX); see *Note Cross-References::. - Volatile-qualified type (OS9000). - -`k' - Const-qualified type; see *Note Miscellaneous Types::. - -`K' - COBOL File Descriptor. See AIX documentation for details. - -`M' - Multiple instance type; see *Note Miscellaneous Types::. - -`n' - String type; see *Note Strings::. - -`N' - Stringptr; see *Note Strings::. - -`o' - Opaque type; see *Note Typedefs::. - -`p' - Procedure; see *Note Function Types::. - -`P' - Packed array; see *Note Arrays::. - -`r' - Range type; see *Note Subranges::. - -`R' - Builtin floating type; see *Note Builtin Type Descriptors:: (Sun). - Pascal subroutine parameter; see *Note Function Types:: (AIX). - Detecting this conflict is possible with careful parsing (hint: a - Pascal subroutine parameter type will always contain a comma, and - a builtin type descriptor never will). - -`s' - Structure type; see *Note Structures::. - -`S' - Set type; see *Note Miscellaneous Types::. - -`u' - Union; see *Note Unions::. - -`v' - Variant record. This is a Pascal and Modula-2 feature which is - like a union within a struct in C. See AIX documentation for - details. - -`w' - Wide character; see *Note Builtin Type Descriptors::. - -`x' - Cross-reference; see *Note Cross-References::. - -`Y' - Used by IBM's xlC C++ compiler (for structures, I think). - -`z' - gstring; see *Note Strings::. - - -File: stabs.info, Node: Expanded Reference, Next: Questions, Prev: Type Descriptors, Up: Top - -Expanded Reference by Stab Type -******************************* - - For a full list of stab types, and cross-references to where they are -described, see *Note Stab Types::. This appendix just covers certain -stabs which are not yet described in the main body of this document; -eventually the information will all be in one place. - - Format of an entry: - - The first line is the symbol type (see `include/aout/stab.def'). - - The second line describes the language constructs the symbol type -represents. - - The third line is the stab format with the significant stab fields -named and the rest NIL. - - Subsequent lines expand upon the meaning and possible values for each -significant stab field. - - Finally, any further information. - -* Menu: - -* N_PC:: Pascal global symbol -* N_NSYMS:: Number of symbols -* N_NOMAP:: No DST map -* N_M2C:: Modula-2 compilation unit -* N_BROWS:: Path to .cb file for Sun source code browser -* N_DEFD:: GNU Modula2 definition module dependency -* N_EHDECL:: GNU C++ exception variable -* N_MOD2:: Modula2 information "for imc" -* N_CATCH:: GNU C++ "catch" clause -* N_SSYM:: Structure or union element -* N_SCOPE:: Modula2 scope information (Sun only) -* Gould:: non-base register symbols used on Gould systems -* N_LENG:: Length of preceding entry - - -File: stabs.info, Node: N_PC, Next: N_NSYMS, Up: Expanded Reference - -N_PC -==== - - - `.stabs': N_PC - Global symbol (for Pascal). - - "name" -> "symbol_name" <> - value -> supposedly the line number (stab.def is skeptical) - - `stabdump.c' says: - - global pascal symbol: name,,0,subtype,line - << subtype? >> - - -File: stabs.info, Node: N_NSYMS, Next: N_NOMAP, Prev: N_PC, Up: Expanded Reference - -N_NSYMS -======= - - - `.stabn': N_NSYMS - Number of symbols (according to Ultrix V4.0). - - 0, files,,funcs,lines (stab.def) - - -File: stabs.info, Node: N_NOMAP, Next: N_M2C, Prev: N_NSYMS, Up: Expanded Reference - -N_NOMAP -======= - - - `.stabs': N_NOMAP - No DST map for symbol (according to Ultrix V4.0). I think this - means a variable has been optimized out. - - name, ,0,type,ignored (stab.def) - - -File: stabs.info, Node: N_M2C, Next: N_BROWS, Prev: N_NOMAP, Up: Expanded Reference - -N_M2C -===== - - - `.stabs': N_M2C - Modula-2 compilation unit. - - "string" -> "unit_name,unit_time_stamp[,code_time_stamp]" - desc -> unit_number - value -> 0 (main unit) - 1 (any other unit) - - See `Dbx and Dbxtool Interfaces', 2nd edition, by Sun, 1988, for - more information. - - - -File: stabs.info, Node: N_BROWS, Next: N_DEFD, Prev: N_M2C, Up: Expanded Reference - -N_BROWS -======= - - - `.stabs': N_BROWS - Sun source code browser, path to `.cb' file - - <> "path to associated `.cb' file" - - Note: N_BROWS has the same value as N_BSLINE. - - -File: stabs.info, Node: N_DEFD, Next: N_EHDECL, Prev: N_BROWS, Up: Expanded Reference - -N_DEFD -====== - - - `.stabn': N_DEFD - GNU Modula2 definition module dependency. - - GNU Modula-2 definition module dependency. The value is the - modification time of the definition file. The other field is - non-zero if it is imported with the GNU M2 keyword `%INITIALIZE'. - Perhaps `N_M2C' can be used if there are enough empty fields? - - -File: stabs.info, Node: N_EHDECL, Next: N_MOD2, Prev: N_DEFD, Up: Expanded Reference - -N_EHDECL -======== - - - `.stabs': N_EHDECL - GNU C++ exception variable <>. - - "STRING is variable name" - - Note: conflicts with `N_MOD2'. - - -File: stabs.info, Node: N_MOD2, Next: N_CATCH, Prev: N_EHDECL, Up: Expanded Reference - -N_MOD2 -====== - - - `.stab?': N_MOD2 - Modula2 info "for imc" (according to Ultrix V4.0) - - Note: conflicts with `N_EHDECL' <> - - -File: stabs.info, Node: N_CATCH, Next: N_SSYM, Prev: N_MOD2, Up: Expanded Reference - -N_CATCH -======= - - - `.stabn': N_CATCH - GNU C++ `catch' clause - - GNU C++ `catch' clause. The value is its address. The desc field - is nonzero if this entry is immediately followed by a `CAUGHT' stab - saying what exception was caught. Multiple `CAUGHT' stabs means - that multiple exceptions can be caught here. If desc is 0, it - means all exceptions are caught here. - - -File: stabs.info, Node: N_SSYM, Next: N_SCOPE, Prev: N_CATCH, Up: Expanded Reference - -N_SSYM -====== - - - `.stabn': N_SSYM - Structure or union element. - - The value is the offset in the structure. - - <> - - -File: stabs.info, Node: N_SCOPE, Next: Gould, Prev: N_SSYM, Up: Expanded Reference - -N_SCOPE -======= - - - `.stab?': N_SCOPE - Modula2 scope information (Sun linker) <> - - -File: stabs.info, Node: Gould, Next: N_LENG, Prev: N_SCOPE, Up: Expanded Reference - -Non-base registers on Gould systems -=================================== - - - `.stab?': N_NBTEXT - - `.stab?': N_NBDATA - - `.stab?': N_NBBSS - - `.stab?': N_NBSTS - - `.stab?': N_NBLCS - These are used on Gould systems for non-base registers syms. - - However, the following values are not the values used by Gould; - they are the values which GNU has been documenting for these - values for a long time, without actually checking what Gould uses. - I include these values only because perhaps some someone actually - did something with the GNU information (I hope not, why GNU - knowingly assigned wrong values to these in the header file is a - complete mystery to me). - - 240 0xf0 N_NBTEXT ?? - 242 0xf2 N_NBDATA ?? - 244 0xf4 N_NBBSS ?? - 246 0xf6 N_NBSTS ?? - 248 0xf8 N_NBLCS ?? - - -File: stabs.info, Node: N_LENG, Prev: Gould, Up: Expanded Reference - -N_LENG -====== - - - `.stabn': N_LENG - Second symbol entry containing a length-value for the preceding - entry. The value is the length. - - -File: stabs.info, Node: Questions, Next: Stab Sections, Prev: Expanded Reference, Up: Top - -Questions and Anomalies -*********************** - - * For GNU C stabs defining local and global variables (`N_LSYM' and - `N_GSYM'), the desc field is supposed to contain the source line - number on which the variable is defined. In reality the desc - field is always 0. (This behavior is defined in `dbxout.c' and - putting a line number in desc is controlled by `#ifdef - WINNING_GDB', which defaults to false). GDB supposedly uses this - information if you say `list VAR'. In reality, VAR can be a - variable defined in the program and GDB says `function VAR not - defined'. - - * In GNU C stabs, there seems to be no way to differentiate tag - types: structures, unions, and enums (symbol descriptor `T') and - typedefs (symbol descriptor `t') defined at file scope from types - defined locally to a procedure or other more local scope. They - all use the `N_LSYM' stab type. Types defined at procedure scope - are emited after the `N_RBRAC' of the preceding function and - before the code of the procedure in which they are defined. This - is exactly the same as types defined in the source file between - the two procedure bodies. GDB overcompensates by placing all - types in block #1, the block for symbols of file scope. This is - true for default, `-ansi' and `-traditional' compiler options. - (Bugs gcc/1063, gdb/1066.) - - * What ends the procedure scope? Is it the proc block's `N_RBRAC' - or the next `N_FUN'? (I believe its the first.) - - -File: stabs.info, Node: Stab Sections, Next: Symbol Types Index, Prev: Questions, Up: Top - -Using Stabs in Their Own Sections -********************************* - - Many object file formats allow tools to create object files with -custom sections containing any arbitrary data. For any such object file -format, stabs can be embedded in special sections. This is how stabs -are used with ELF and SOM, and aside from ECOFF and XCOFF, is how stabs -are used with COFF. - -* Menu: - -* Stab Section Basics:: How to embed stabs in sections -* ELF Linker Relocation:: Sun ELF hacks - - -File: stabs.info, Node: Stab Section Basics, Next: ELF Linker Relocation, Up: Stab Sections - -How to Embed Stabs in Sections -============================== - - The assembler creates two custom sections, a section named `.stab' -which contains an array of fixed length structures, one struct per stab, -and a section named `.stabstr' containing all the variable length -strings that are referenced by stabs in the `.stab' section. The byte -order of the stabs binary data depends on the object file format. For -ELF, it matches the byte order of the ELF file itself, as determined -from the `EI_DATA' field in the `e_ident' member of the ELF header. -For SOM, it is always big-endian (is this true??? FIXME). For COFF, it -matches the byte order of the COFF headers. The meaning of the fields -is the same as for a.out (*note Symbol Table Format::.), except that -the `n_strx' field is relative to the strings for the current -compilation unit (which can be found using the synthetic N_UNDF stab -described below), rather than the entire string table. - - The first stab in the `.stab' section for each compilation unit is -synthetic, generated entirely by the assembler, with no corresponding -`.stab' directive as input to the assembler. This stab contains the -following fields: - -`n_strx' - Offset in the `.stabstr' section to the source filename. - -`n_type' - `N_UNDF'. - -`n_other' - Unused field, always zero. This may eventually be used to hold - overflows from the count in the `n_desc' field. - -`n_desc' - Count of upcoming symbols, i.e., the number of remaining stabs for - this source file. - -`n_value' - Size of the string table fragment associated with this source - file, in bytes. - - The `.stabstr' section always starts with a null byte (so that string -offsets of zero reference a null string), followed by random length -strings, each of which is null byte terminated. - - The ELF section header for the `.stab' section has its `sh_link' -member set to the section number of the `.stabstr' section, and the -`.stabstr' section has its ELF section header `sh_type' member set to -`SHT_STRTAB' to mark it as a string table. SOM and COFF have no way of -linking the sections together or marking them as string tables. - - For COFF, the `.stab' and `.stabstr' sections may be simply -concatenated by the linker. GDB then uses the `n_desc' fields to -figure out the extent of the original sections. Similarly, the -`n_value' fields of the header symbols are added together in order to -get the actual position of the strings in a desired `.stabstr' section. -Although this design obviates any need for the linker to relocate or -otherwise manipulate `.stab' and `.stabstr' sections, it also requires -some care to ensure that the offsets are calculated correctly. For -instance, if the linker were to pad in between the `.stabstr' sections -before concatenating, then the offsets to strings in the middle of the -executable's `.stabstr' section would be wrong. - - The GNU linker is able to optimize stabs information by merging -duplicate strings and removing duplicate header file information (*note -Include Files::.). When some versions of the GNU linker optimize stabs -in sections, they remove the leading `N_UNDF' symbol and arranges for -all the `n_strx' fields to be relative to the start of the `.stabstr' -section. - - -File: stabs.info, Node: ELF Linker Relocation, Prev: Stab Section Basics, Up: Stab Sections - -Having the Linker Relocate Stabs in ELF -======================================= - - This section describes some Sun hacks for Stabs in ELF; it does not -apply to COFF or SOM. - - To keep linking fast, you don't want the linker to have to relocate -very many stabs. Making sure this is done for `N_SLINE', `N_RBRAC', -and `N_LBRAC' stabs is the most important thing (see the descriptions -of those stabs for more information). But Sun's stabs in ELF has taken -this further, to make all addresses in the `n_value' field (functions -and static variables) relative to the source file. For the `N_SO' -symbol itself, Sun simply omits the address. To find the address of -each section corresponding to a given source file, the compiler puts -out symbols giving the address of each section for a given source file. -Since these are ELF (not stab) symbols, the linker relocates them -correctly without having to touch the stabs section. They are named -`Bbss.bss' for the bss section, `Ddata.data' for the data section, and -`Drodata.rodata' for the rodata section. For the text section, there -is no such symbol (but there should be, see below). For an example of -how these symbols work, *Note Stab Section Transformations::. GCC does -not provide these symbols; it instead relies on the stabs getting -relocated. Thus addresses which would normally be relative to -`Bbss.bss', etc., are already relocated. The Sun linker provided with -Solaris 2.2 and earlier relocates stabs using normal ELF relocation -information, as it would do for any section. Sun has been threatening -to kludge their linker to not do this (to speed up linking), even -though the correct way to avoid having the linker do these relocations -is to have the compiler no longer output relocatable values. Last I -heard they had been talked out of the linker kludge. See Sun point -patch 101052-01 and Sun bug 1142109. With the Sun compiler this -affects `S' symbol descriptor stabs (*note Statics::.) and functions -(*note Procedures::.). In the latter case, to adopt the clean solution -(making the value of the stab relative to the start of the compilation -unit), it would be necessary to invent a `Ttext.text' symbol, analogous -to the `Bbss.bss', etc., symbols. I recommend this rather than using a -zero value and getting the address from the ELF symbols. - - Finding the correct `Bbss.bss', etc., symbol is difficult, because -the linker simply concatenates the `.stab' sections from each `.o' file -without including any information about which part of a `.stab' section -comes from which `.o' file. The way GDB does this is to look for an -ELF `STT_FILE' symbol which has the same name as the last component of -the file name from the `N_SO' symbol in the stabs (for example, if the -file name is `../../gdb/main.c', it looks for an ELF `STT_FILE' symbol -named `main.c'). This loses if different files have the same name -(they could be in different directories, a library could have been -copied from one system to another, etc.). It would be much cleaner to -have the `Bbss.bss' symbols in the stabs themselves. Having the linker -relocate them there is no more work than having the linker relocate ELF -symbols, and it solves the problem of having to associate the ELF and -stab symbols. However, no one has yet designed or implemented such a -scheme. - diff --git a/gnu/dist/gdb/doc/stabs.info-4 b/gnu/dist/gdb/doc/stabs.info-4 deleted file mode 100644 index f5d2c220f51b..000000000000 --- a/gnu/dist/gdb/doc/stabs.info-4 +++ /dev/null @@ -1,98 +0,0 @@ -This is Info file stabs.info, produced by Makeinfo version 1.68 from -the input file ../../../devo/gdb/doc/stabs.texinfo. - -START-INFO-DIR-ENTRY -* Stabs: (stabs). The "stabs" debugging information format. -END-INFO-DIR-ENTRY - - This document describes the stabs debugging symbol tables. - - Copyright 1992, 93, 94, 95, 1997 Free Software Foundation, Inc. -Contributed by Cygnus Support. Written by Julia Menapace, Jim Kingdon, -and David MacKenzie. - - 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 or distribute modified versions of this -manual under the terms of the GPL (for which purpose this text may be -regarded as a program in the language TeX). - - -File: stabs.info, Node: Symbol Types Index, Prev: Stab Sections, Up: Top - -Symbol Types Index -****************** - -* Menu: - -* .bb: Block Structure. -* .be: Block Structure. -* C_BCOMM: Common Blocks. -* C_BINCL: Include Files. -* C_BLOCK: Block Structure. -* C_BSTAT: Statics. -* C_DECL, for types: Typedefs. -* C_ECOML: Common Blocks. -* C_ECOMM: Common Blocks. -* C_EINCL: Include Files. -* C_ENTRY: Alternate Entry Points. -* C_ESTAT: Statics. -* C_FILE: Source Files. -* C_FUN: Procedures. -* C_GSYM: Global Variables. -* C_LSYM: Stack Variables. -* C_PSYM: Parameters. -* C_RPSYM: Register Parameters. -* C_RSYM: Register Variables. -* C_STSYM: Statics. -* N_BCOMM: Common Blocks. -* N_BINCL: Include Files. -* N_BROWS: N_BROWS. -* N_BSLINE: Line Numbers. -* N_CATCH: N_CATCH. -* N_DEFD: N_DEFD. -* N_DSLINE: Line Numbers. -* N_ECOML: Common Blocks. -* N_ECOMM: Common Blocks. -* N_EHDECL: N_EHDECL. -* N_EINCL: Include Files. -* N_ENTRY: Alternate Entry Points. -* N_EXCL: Include Files. -* N_FNAME: Procedures. -* N_FUN, for functions: Procedures. -* N_FUN, for variables: Statics. -* N_GSYM: Global Variables. -* N_GSYM, for functions (Sun acc): Procedures. -* N_LBRAC: Block Structure. -* N_LCSYM: Statics. -* N_LENG: N_LENG. -* N_LSYM, for parameter: Local Variable Parameters. -* N_LSYM, for stack variables: Stack Variables. -* N_LSYM, for types: Typedefs. -* N_M2C: N_M2C. -* N_MAIN: Main Program. -* N_MOD2: N_MOD2. -* N_NBBSS: Gould. -* N_NBDATA: Gould. -* N_NBLCS: Gould. -* N_NBSTS: Gould. -* N_NBTEXT: Gould. -* N_NOMAP: N_NOMAP. -* N_NSYMS: N_NSYMS. -* N_PC: N_PC. -* N_PSYM: Parameters. -* N_RBRAC: Block Structure. -* N_ROSYM: Statics. -* N_RSYM: Register Variables. -* N_RSYM, for parameters: Register Parameters. -* N_SCOPE: N_SCOPE. -* N_SLINE: Line Numbers. -* N_SO: Source Files. -* N_SOL: Include Files. -* N_SSYM: N_SSYM. -* N_STSYM: Statics. -* N_STSYM, for functions (Sun acc): Procedures. - -