+++ /dev/null
-This is Info file ./gdb.info, produced by Makeinfo version 1.68 from
-the input file gdb.texinfo.
-
-START-INFO-DIR-ENTRY
-* Gdb: (gdb). The GNU debugger.
-END-INFO-DIR-ENTRY
- This file documents the GNU debugger GDB.
-
- This is the Seventh Edition, February 1999, of `Debugging with GDB:
-the GNU Source-Level Debugger' for GDB Version 4.18.
-
- Copyright (C) 1988-1999 Free Software Foundation, Inc.
-
- Permission is granted to make and distribute verbatim copies of this
-manual provided the copyright notice and this permission notice are
-preserved on all copies.
-
- Permission is granted to copy and distribute modified versions of
-this manual under the conditions for verbatim copying, provided also
-that the entire resulting derived work is distributed under the terms
-of a permission notice identical to this one.
-
- Permission is granted to copy and distribute translations of this
-manual into another language, under the above conditions for modified
-versions.
-
-\1f
-Indirect:
-gdb.info-1: 991
-gdb.info-2: 48295
-gdb.info-3: 96814
-gdb.info-4: 145217
-gdb.info-5: 193677
-gdb.info-6: 235496
-gdb.info-7: 284239
-gdb.info-8: 332485
-gdb.info-9: 381855
-gdb.info-10: 404259
-\1f
-Tag Table:
-(Indirect)
-Node: Top\7f991
-Node: Summary\7f9590
-Node: Free Software\7f11196
-Node: Contributors\7f11950
-Node: Sample Session\7f17994
-Node: Invocation\7f24864
-Node: Invoking GDB\7f25337
-Node: File Options\7f27232
-Node: Mode Options\7f30398
-Node: Quitting GDB\7f32594
-Node: Shell Commands\7f33460
-Node: Commands\7f34202
-Node: Command Syntax\7f34839
-Node: Completion\7f36719
-Node: Help\7f41039
-Node: Running\7f45347
-Node: Compilation\7f46483
-Node: Starting\7f48295
-Node: Arguments\7f51468
-Node: Environment\7f52472
-Node: Working Directory\7f55568
-Node: Input/Output\7f56308
-Node: Attach\7f57913
-Node: Kill Process\7f60341
-Node: Process Information\7f61311
-Node: Threads\7f62643
-Node: Processes\7f67288
-Node: Stopping\7f68520
-Node: Breakpoints\7f69669
-Node: Set Breaks\7f72514
-Node: Set Watchpoints\7f81021
-Node: Set Catchpoints\7f84382
-Node: Delete Breaks\7f87850
-Node: Disabling\7f89517
-Node: Conditions\7f92204
-Node: Break Commands\7f96814
-Node: Breakpoint Menus\7f99690
-Node: Continuing and Stepping\7f101366
-Node: Signals\7f108708
-Node: Thread Stops\7f112376
-Node: Stack\7f115697
-Node: Frames\7f117250
-Node: Backtrace\7f119981
-Node: Selection\7f121713
-Node: Frame Info\7f124449
-Node: Alpha/MIPS Stack\7f126745
-Node: Source\7f127800
-Node: List\7f128749
-Node: Search\7f132289
-Node: Source Path\7f133092
-Node: Machine Code\7f135773
-Node: Data\7f138692
-Node: Expressions\7f140567
-Node: Variables\7f142512
-Node: Arrays\7f145217
-Node: Output Formats\7f147742
-Node: Memory\7f149813
-Node: Auto Display\7f154077
-Node: Print Settings\7f157832
-Node: Value History\7f167759
-Node: Convenience Vars\7f170170
-Node: Registers\7f172953
-Node: Floating Point Hardware\7f177655
-Node: Languages\7f178158
-Node: Setting\7f179262
-Node: Filenames\7f180870
-Node: Manually\7f181624
-Node: Automatically\7f182822
-Node: Show\7f183873
-Node: Checks\7f185171
-Node: Type Checking\7f186527
-Node: Range Checking\7f189239
-Node: Support\7f191580
-Node: C\7f192520
-Node: C Operators\7f193677
-Node: C Constants\7f197758
-Node: Cplus expressions\7f199745
-Node: C Defaults\7f202223
-Node: C Checks\7f202885
-Node: Debugging C\7f203602
-Node: Debugging C plus plus\7f204107
-Node: Modula-2\7f206105
-Node: M2 Operators\7f206992
-Node: Built-In Func/Proc\7f210005
-Node: M2 Constants\7f212744
-Node: M2 Defaults\7f214333
-Node: Deviations\7f214928
-Node: M2 Checks\7f216015
-Node: M2 Scope\7f216815
-Node: GDB/M2\7f217824
-Node: Symbols\7f218763
-Node: Altering\7f225625
-Node: Assignment\7f226593
-Node: Jumping\7f228720
-Node: Signaling\7f230853
-Node: Returning\7f231975
-Node: Calling\7f233167
-Node: Patching\7f233961
-Node: GDB Files\7f235031
-Node: Files\7f235496
-Node: Symbol Errors\7f245168
-Node: Targets\7f248747
-Node: Active Targets\7f249697
-Node: Target Commands\7f251285
-Node: Byte Order\7f259363
-Node: Remote\7f260347
-Node: Remote Serial\7f261803
-Node: Stub Contents\7f264411
-Node: Bootstrapping\7f266512
-Node: Debug Session\7f270308
-Node: Protocol\7f273453
-Node: Server\7f276726
-Node: NetWare\7f280772
-Node: i960-Nindy Remote\7f282734
-Node: Nindy Startup\7f283554
-Node: Nindy Options\7f284239
-Node: Nindy Reset\7f285853
-Node: UDI29K Remote\7f286237
-Node: EB29K Remote\7f287142
-Node: Comms (EB29K)\7f287960
-Node: gdb-EB29K\7f291139
-Node: Remote Log\7f292505
-Node: ST2000 Remote\7f292980
-Node: VxWorks Remote\7f294448
-Node: VxWorks Connection\7f296408
-Node: VxWorks Download\7f297334
-Node: VxWorks Attach\7f299063
-Node: Sparclet Remote\7f299453
-Node: Sparclet File\7f300901
-Node: Sparclet Connection\7f301773
-Node: Sparclet Download\7f302243
-Node: Sparclet Execution\7f303281
-Node: Hitachi Remote\7f303864
-Node: Hitachi Boards\7f304792
-Node: Hitachi ICE\7f305855
-Node: Hitachi Special\7f306643
-Node: MIPS Remote\7f307369
-Node: Simulator\7f311666
-Node: Controlling GDB\7f313222
-Node: Prompt\7f313833
-Node: Editing\7f314631
-Node: History\7f315400
-Node: Screen Size\7f318099
-Node: Numbers\7f319497
-Node: Messages/Warnings\7f320899
-Node: Sequences\7f322907
-Node: Define\7f323487
-Node: Hooks\7f326671
-Node: Command Files\7f328069
-Node: Output\7f330078
-Node: Emacs\7f332485
-Node: GDB Bugs\7f338431
-Node: Bug Criteria\7f339153
-Node: Bug Reporting\7f340040
-Node: Command Line Editing\7f347326
-Node: Introduction and Notation\7f347991
-Node: Readline Interaction\7f349025
-Node: Readline Bare Essentials\7f350213
-Node: Readline Movement Commands\7f351749
-Node: Readline Killing Commands\7f352710
-Node: Readline Arguments\7f354421
-Node: Searching\7f355391
-Node: Readline Init File\7f356969
-Node: Readline Init File Syntax\7f358011
-Node: Conditional Init Constructs\7f366872
-Node: Sample Init File\7f369306
-Node: Bindable Readline Commands\7f372471
-Node: Commands For Moving\7f373217
-Node: Commands For History\7f374060
-Node: Commands For Text\7f376807
-Node: Commands For Killing\7f378588
-Node: Numeric Arguments\7f380733
-Node: Commands For Completion\7f381855
-Node: Keyboard Macros\7f383336
-Node: Miscellaneous Commands\7f383890
-Node: Readline vi Mode\7f386689
-Node: Using History Interactively\7f387532
-Node: History Interaction\7f387887
-Node: Event Designators\7f388839
-Node: Word Designators\7f389484
-Node: Modifiers\7f390392
-Node: Formatting Documentation\7f391062
-Node: Installing GDB\7f394433
-Node: Separate Objdir\7f397915
-Node: Config Names\7f400485
-Node: Configure Options\7f401927
-Node: Index\7f404259
-\1f
-End Tag Table
+++ /dev/null
-This is Info file ./gdb.info, produced by Makeinfo version 1.68 from
-the input file gdb.texinfo.
-
-START-INFO-DIR-ENTRY
-* Gdb: (gdb). The GNU debugger.
-END-INFO-DIR-ENTRY
- This file documents the GNU debugger GDB.
-
- This is the Seventh Edition, February 1999, of `Debugging with GDB:
-the GNU Source-Level Debugger' for GDB Version 4.18.
-
- Copyright (C) 1988-1999 Free Software Foundation, Inc.
-
- Permission is granted to make and distribute verbatim copies of this
-manual provided the copyright notice and this permission notice are
-preserved on all copies.
-
- Permission is granted to copy and distribute modified versions of
-this manual under the conditions for verbatim copying, provided also
-that the entire resulting derived work is distributed under the terms
-of a permission notice identical to this one.
-
- Permission is granted to copy and distribute translations of this
-manual into another language, under the above conditions for modified
-versions.
-
-\1f
-File: gdb.info, Node: Top, Next: Summary, Prev: (dir), Up: (dir)
-
-Debugging with GDB
-******************
-
- This file describes GDB, the GNU symbolic debugger.
-
- This is the Seventh Edition, February 1999, for GDB Version 4.18.
-
- Copyright (C) 1988-1999 Free Software Foundation, Inc.
-
-* Menu:
-
-* Summary:: Summary of GDB
-
-* Sample Session:: A sample GDB session
-
-* Invocation:: Getting in and out of GDB
-* Commands:: GDB commands
-* Running:: Running programs under GDB
-* Stopping:: Stopping and continuing
-* Stack:: Examining the stack
-* Source:: Examining source files
-* Data:: Examining data
-
-* Languages:: Using GDB with different languages
-
-
-* Symbols:: Examining the symbol table
-* Altering:: Altering execution
-* GDB Files:: GDB files
-* Targets:: Specifying a debugging target
-* Controlling GDB:: Controlling GDB
-* Sequences:: Canned sequences of commands
-
-* Emacs:: Using GDB under GNU Emacs
-
-* GDB Bugs:: Reporting bugs in GDB
-
-
-
-* Formatting Documentation:: How to format and print GDB documentation
-
-
-* Command Line Editing:: Command Line Editing
-* Using History Interactively:: Using History Interactively
-* Installing GDB:: Installing GDB
-* Index:: Index
-
- -- The Detailed Node Listing --
-
-Summary of GDB
-
-* Free Software:: Freely redistributable software
-* Contributors:: Contributors to GDB
-
-Getting In and Out of GDB
-
-* Invoking GDB:: How to start GDB
-* Quitting GDB:: How to quit GDB
-* Shell Commands:: How to use shell commands inside GDB
-
-Invoking GDB
-
-* File Options:: Choosing files
-* Mode Options:: Choosing modes
-
-GDB Commands
-
-* Command Syntax:: How to give commands to GDB
-* Completion:: Command completion
-* Help:: How to ask GDB for help
-
-Running Programs Under GDB
-
-* Compilation:: Compiling for debugging
-* Starting:: Starting your program
-
-* Arguments:: Your program's arguments
-* Environment:: Your program's environment
-
-* Working Directory:: Your program's working directory
-* Input/Output:: Your program's input and output
-* Attach:: Debugging an already-running process
-* Kill Process:: Killing the child process
-
-* Process Information:: Additional process information
-
-* Threads:: Debugging programs with multiple threads
-* Processes:: Debugging programs with multiple processes
-
-Stopping and Continuing
-
-* Breakpoints:: Breakpoints, watchpoints, and catchpoints
-* Continuing and Stepping:: Resuming execution
-
-* Signals:: Signals
-
-* Thread Stops:: Stopping and starting multi-thread programs
-
-Breakpoints and watchpoints
-
-* Set Breaks:: Setting breakpoints
-* Set Watchpoints:: Setting watchpoints
-* Set Catchpoints:: Setting catchpoints
-* Delete Breaks:: Deleting breakpoints
-* Disabling:: Disabling breakpoints
-* Conditions:: Break conditions
-* Break Commands:: Breakpoint command lists
-
-* Breakpoint Menus:: Breakpoint menus
-
-Examining the Stack
-
-* Frames:: Stack frames
-* Backtrace:: Backtraces
-* Selection:: Selecting a frame
-* Frame Info:: Information on a frame
-* Alpha/MIPS Stack:: Alpha and MIPS machines and the function stack
-
-Examining Source Files
-
-* List:: Printing source lines
-
-* Search:: Searching source files
-* Source Path:: Specifying source directories
-* Machine Code:: Source and machine code
-
-Examining Data
-
-* Expressions:: Expressions
-* Variables:: Program variables
-* Arrays:: Artificial arrays
-* Output Formats:: Output formats
-* Memory:: Examining memory
-* Auto Display:: Automatic display
-* Print Settings:: Print settings
-* Value History:: Value history
-* Convenience Vars:: Convenience variables
-* Registers:: Registers
-
-* Floating Point Hardware:: Floating point hardware
-
-Using GDB with Different Languages
-
-* Setting:: Switching between source languages
-* Show:: Displaying the language
-
-* Checks:: Type and range checks
-
-* Support:: Supported languages
-
-Switching between source languages
-
-* Filenames:: Filename extensions and languages.
-* Manually:: Setting the working language manually
-* Automatically:: Having GDB infer the source language
-
-
-Type and range checking
-
-* Type Checking:: An overview of type checking
-* Range Checking:: An overview of range checking
-
-Supported languages
-
-
-* C:: C and C++
-
-C Language Support
-
-* C Operators:: C operators
-
-C Language Support
-
-* C Operators:: C and C++ operators
-* C Constants:: C and C++ constants
-* Cplus expressions:: C++ expressions
-* C Defaults:: Default settings for C and C++
-
-* C Checks:: C and C++ type and range checks
-* Debugging C:: GDB and C
-* Debugging C plus plus:: GDB features for C++
-
-
-Modula-2
-
-* M2 Operators:: Built-in operators
-* Built-In Func/Proc:: Built-in functions and procedures
-* M2 Constants:: Modula-2 constants
-* M2 Defaults:: Default settings for Modula-2
-* Deviations:: Deviations from standard Modula-2
-* M2 Checks:: Modula-2 type and range checks
-* M2 Scope:: The scope operators `::' and `.'
-* GDB/M2:: GDB and Modula-2
-
-Altering Execution
-
-* Assignment:: Assignment to variables
-* Jumping:: Continuing at a different address
-
-* Signaling:: Giving your program a signal
-* Returning:: Returning from a function
-* Calling:: Calling your program's functions
-* Patching:: Patching your program
-
-GDB Files
-
-* Files:: Commands to specify files
-* Symbol Errors:: Errors reading symbol files
-
-Specifying a Debugging Target
-
-* Active Targets:: Active targets
-* Target Commands:: Commands for managing targets
-
-* Byte Order:: Choosing target byte order
-* Remote:: Remote debugging
-
-Remote debugging
-
-
-* Remote Serial:: GDB remote serial protocol
-
-
-* i960-Nindy Remote:: GDB with a remote i960 (Nindy)
-
-
-* UDI29K Remote:: The UDI protocol for AMD29K
-* EB29K Remote:: The EBMON protocol for AMD29K
-
-
-* VxWorks Remote:: GDB and VxWorks
-
-
-* ST2000 Remote:: GDB with a Tandem ST2000
-
-
-* Hitachi Remote:: GDB and Hitachi Microprocessors
-
-
-* MIPS Remote:: GDB and MIPS boards
-
-
-* Simulator:: Simulated CPU target
-
-Controlling GDB
-
-* Prompt:: Prompt
-* Editing:: Command editing
-* History:: Command history
-* Screen Size:: Screen size
-* Numbers:: Numbers
-* Messages/Warnings:: Optional warnings and messages
-
-Canned Sequences of Commands
-
-* Define:: User-defined commands
-* Hooks:: User-defined command hooks
-* Command Files:: Command files
-* Output:: Commands for controlled output
-
-Reporting Bugs in GDB
-
-* Bug Criteria:: Have you found a bug?
-* Bug Reporting:: How to report bugs
-
-Installing GDB
-
-* Separate Objdir:: Compiling GDB in another directory
-* Config Names:: Specifying names for hosts and targets
-* Configure Options:: Summary of options for configure
-
-\1f
-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
-
-\1f
-File: gdb.info, Node: Free Software, Next: Contributors, Prev: Summary, Up: Summary
-
-Free software
-=============
-
- GDB is "free software", protected by the GNU General Public License
-(GPL). The GPL gives you the freedom to copy or adapt a licensed
-program--but every person getting a copy also gets with it the freedom
-to modify that copy (which means that they must get access to the
-source code), and the freedom to distribute further copies. Typical
-software companies use copyrights to limit your freedoms; the Free
-Software Foundation uses the GPL to preserve these freedoms.
-
- Fundamentally, the General Public License is a license which says
-that you have these freedoms and that you cannot take these freedoms
-away from anyone else.
-
-\1f
-File: gdb.info, Node: Contributors, Prev: Free Software, Up: Summary
-
-Contributors to GDB
-===================
-
- Richard Stallman was the original author of GDB, and of many other
-GNU programs. Many others have contributed to its development. This
-section attempts to credit major contributors. One of the virtues of
-free software is that everyone is free to contribute to it; with
-regret, we cannot actually acknowledge everyone here. The file
-`ChangeLog' in the GDB distribution approximates a blow-by-blow account.
-
- Changes much prior to version 2.0 are lost in the mists of time.
-
- *Plea:* Additions to this section are particularly welcome. If you
- or your friends (or enemies, to be evenhanded) have been unfairly
- omitted from this list, we would like to add your names!
-
- So that they may not regard their many labors as thankless, we
-particularly thank those who shepherded GDB through major releases: Jim
-Blandy (release 4.18); Jason Molenda (release 4.17); Stan Shebs
-(release 4.14); Fred Fish (releases 4.16, 4.15, 4.13, 4.12, 4.11, 4.10,
-and 4.9); Stu Grossman and John Gilmore (releases 4.8, 4.7, 4.6, 4.5,
-and 4.4); John Gilmore (releases 4.3, 4.2, 4.1, 4.0, and 3.9); Jim
-Kingdon (releases 3.5, 3.4, and 3.3); and Randy Smith (releases 3.2,
-3.1, and 3.0).
-
- Richard Stallman, assisted at various times by Peter TerMaat, Chris
-Hanson, and Richard Mlynarik, handled releases through 2.8.
-
- Michael Tiemann is the author of most of the GNU C++ support in GDB,
-with significant additional contributions from Per Bothner. James
-Clark wrote the GNU C++ demangler. Early work on C++ was by Peter
-TerMaat (who also did much general update work leading to release 3.0).
-
- GDB 4 uses the BFD subroutine library to examine multiple
-object-file formats; BFD was a joint project of David V.
-Henkel-Wallace, Rich Pixley, Steve Chamberlain, and John Gilmore.
-
- David Johnson wrote the original COFF support; Pace Willison did the
-original support for encapsulated COFF.
-
- Brent Benson of Harris Computer Systems contributed DWARF 2 support.
-
- Adam de Boor and Bradley Davis contributed the ISI Optimum V support.
-Per Bothner, Noboyuki Hikichi, and Alessandro Forin contributed MIPS
-support. Jean-Daniel Fekete contributed Sun 386i support. Chris
-Hanson improved the HP9000 support. Noboyuki Hikichi and Tomoyuki
-Hasei contributed Sony/News OS 3 support. David Johnson contributed
-Encore Umax support. Jyrki Kuoppala contributed Altos 3068 support.
-Jeff Law contributed HP PA and SOM support. Keith Packard contributed
-NS32K support. Doug Rabson contributed Acorn Risc Machine support.
-Bob Rusk contributed Harris Nighthawk CX-UX support. Chris Smith
-contributed Convex support (and Fortran debugging). Jonathan Stone
-contributed Pyramid support. Michael Tiemann contributed SPARC support.
-Tim Tucker contributed support for the Gould NP1 and Gould Powernode.
-Pace Willison contributed Intel 386 support. Jay Vosburgh contributed
-Symmetry support.
-
- Andreas Schwab contributed M68K Linux support.
-
- Rich Schaefer and Peter Schauer helped with support of SunOS shared
-libraries.
-
- Jay Fenlason and Roland McGrath ensured that GDB and GAS agree about
-several machine instruction sets.
-
- Patrick Duval, Ted Goldstein, Vikram Koka and Glenn Engel helped
-develop remote debugging. Intel Corporation, Wind River Systems, AMD,
-and ARM contributed remote debugging modules for the i960, VxWorks,
-A29K UDI, and RDI targets, respectively.
-
- Brian Fox is the author of the readline libraries providing
-command-line editing and command history.
-
- Andrew Beers of SUNY Buffalo wrote the language-switching code, the
-Modula-2 support, and contributed the Languages chapter of this manual.
-
- Fred Fish wrote most of the support for Unix System Vr4. He also
-enhanced the command-completion support to cover C++ overloaded symbols.
-
- Hitachi America, Ltd. sponsored the support for H8/300, H8/500, and
-Super-H processors.
-
- NEC sponsored the support for the v850, Vr4xxx, and Vr5xxx
-processors.
-
- Mitsubishi sponsored the support for D10V, D30V, and M32R/D
-processors.
-
- Toshiba sponsored the support for the TX39 Mips processor.
-
- Matsushita sponsored the support for the MN10200 and MN10300
-processors.
-
- Fujitsu sponsored the support for SPARClite and FR30 processors
-
- Kung Hsu, Jeff Law, and Rick Sladkey added support for hardware
-watchpoints.
-
- Michael Snyder added support for tracepoints.
-
- Stu Grossman wrote gdbserver.
-
- Jim Kingdon, Peter Schauer, Ian Taylor, and Stu Grossman made nearly
-innumerable bug fixes and cleanups throughout GDB.
-
- The following people at the Hewlett-Packard Company contributed
-support for the PA-RISC 2.0 architecture, HP-UX 10.20, 10.30, and 11.0
-(narrow mode), HP's implementation of kernel threads, HP's aC++
-compiler, and the terminal user interface: Ben Krepp, Richard Title,
-John Bishop, Susan Macchia, Kathy Mann, Satish Pai, India Paul, Steve
-Rehrauer, and Elena Zannoni. Kim Haase provided HP-specific
-information in this manual.
-
- Cygnus Solutions has sponsored GDB maintenance and much of its
-development since 1991. Cygnus engineers who have worked on GDB
-fulltime include Mark Alexander, Jim Blandy, Per Bothner, Edith Epstein,
-Chris Faylor, Fred Fish, Martin Hunt, Jim Ingham, John Gilmore, Stu
-Grossman, Kung Hsu, Jim Kingdon, John Metzler, Fernando Nasser, Geoffrey
-Noer, Dawn Perchik, Rich Pixley, Zdenek Radouch, Keith Seitz, Stan
-Shebs, David Taylor, and Elena Zannoni. In addition, Dave Brolley, Ian
-Carmichael, Steve Chamberlain, Nick Clifton, JT Conklin, Stan Cox, DJ
-Delorie, Ulrich Drepper, Frank Eigler, Doug Evans, Sean Fagan, David
-Henkel-Wallace, Richard Henderson, Jeff Holcomb, Jeff Law, Jim Lemke,
-Tom Lord, Bob Manson, Michael Meissner, Jason Merrill, Catherine Moore,
-Drew Moseley, Ken Raeburn, Gavin Romig-Koch, Rob Savoye, Jamie Smith,
-Mike Stump, Ian Taylor, Angela Thomas, Michael Tiemann, Tom Tromey, Ron
-Unrau, Jim Wilson, and David Zuhn have made contributions both large
-and small.
-
-\1f
-File: gdb.info, Node: Sample Session, Next: Invocation, Prev: Summary, Up: Top
-
-A Sample GDB Session
-********************
-
- You can use this manual at your leisure to read all about GDB.
-However, a handful of commands are enough to get started using the
-debugger. This chapter illustrates those commands.
-
- One of the preliminary versions of GNU `m4' (a generic macro
-processor) exhibits the following bug: sometimes, when we change its
-quote strings from the default, the commands used to capture one macro
-definition within another stop working. In the following short `m4'
-session, we define a macro `foo' which expands to `0000'; we then use
-the `m4' built-in `defn' to define `bar' as the same thing. However,
-when we change the open quote string to `<QUOTE>' and the close quote
-string to `<UNQUOTE>', the same procedure fails to define a new synonym
-`baz':
-
- $ cd gnu/m4
- $ ./m4
- define(foo,0000)
-
- foo
- 0000
- define(bar,defn(`foo'))
-
- bar
- 0000
- changequote(<QUOTE>,<UNQUOTE>)
-
- define(baz,defn(<QUOTE>foo<UNQUOTE>))
- baz
- C-d
- m4: End of input: 0: fatal error: EOF in string
-
-Let us use GDB to try to see what is going on.
-
- $ gdb m4
- GDB is free software and you are welcome to distribute copies
- of it under certain conditions; type "show copying" to see
- the conditions.
- There is absolutely no warranty for GDB; type "show warranty"
- for details.
-
- GDB 4.18, Copyright 1999 Free Software Foundation, Inc...
- (gdb)
-
-GDB reads only enough symbol data to know where to find the rest when
-needed; as a result, the first prompt comes up very quickly. We now
-tell GDB to use a narrower display width than usual, so that examples
-fit in this manual.
-
- (gdb) set width 70
-
-We need to see how the `m4' built-in `changequote' works. Having
-looked at the source, we know the relevant subroutine is
-`m4_changequote', so we set a breakpoint there with the GDB `break'
-command.
-
- (gdb) break m4_changequote
- Breakpoint 1 at 0x62f4: file builtin.c, line 879.
-
-Using the `run' command, we start `m4' running under GDB control; as
-long as control does not reach the `m4_changequote' subroutine, the
-program runs as usual:
-
- (gdb) run
- Starting program: /work/Editorial/gdb/gnu/m4/m4
- define(foo,0000)
-
- foo
- 0000
-
-To trigger the breakpoint, we call `changequote'. GDB suspends
-execution of `m4', displaying information about the context where it
-stops.
-
- changequote(<QUOTE>,<UNQUOTE>)
-
- Breakpoint 1, m4_changequote (argc=3, argv=0x33c70)
- at builtin.c:879
- 879 if (bad_argc(TOKEN_DATA_TEXT(argv[0]),argc,1,3))
-
-Now we use the command `n' (`next') to advance execution to the next
-line of the current function.
-
- (gdb) n
- 882 set_quotes((argc >= 2) ? TOKEN_DATA_TEXT(argv[1])\
- : nil,
-
-`set_quotes' looks like a promising subroutine. We can go into it by
-using the command `s' (`step') instead of `next'. `step' goes to the
-next line to be executed in *any* subroutine, so it steps into
-`set_quotes'.
-
- (gdb) s
- set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>")
- at input.c:530
- 530 if (lquote != def_lquote)
-
-The display that shows the subroutine where `m4' is now suspended (and
-its arguments) is called a stack frame display. It shows a summary of
-the stack. We can use the `backtrace' command (which can also be
-spelled `bt'), to see where we are in the stack as a whole: the
-`backtrace' command displays a stack frame for each active subroutine.
-
- (gdb) bt
- #0 set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>")
- at input.c:530
- #1 0x6344 in m4_changequote (argc=3, argv=0x33c70)
- at builtin.c:882
- #2 0x8174 in expand_macro (sym=0x33320) at macro.c:242
- #3 0x7a88 in expand_token (obs=0x0, t=209696, td=0xf7fffa30)
- at macro.c:71
- #4 0x79dc in expand_input () at macro.c:40
- #5 0x2930 in main (argc=0, argv=0xf7fffb20) at m4.c:195
-
-We step through a few more lines to see what happens. The first two
-times, we can use `s'; the next two times we use `n' to avoid falling
-into the `xstrdup' subroutine.
-
- (gdb) s
- 0x3b5c 532 if (rquote != def_rquote)
- (gdb) s
- 0x3b80 535 lquote = (lq == nil || *lq == '\0') ? \
- def_lquote : xstrdup(lq);
- (gdb) n
- 536 rquote = (rq == nil || *rq == '\0') ? def_rquote\
- : xstrdup(rq);
- (gdb) n
- 538 len_lquote = strlen(rquote);
-
-The last line displayed looks a little odd; we can examine the variables
-`lquote' and `rquote' to see if they are in fact the new left and right
-quotes we specified. We use the command `p' (`print') to see their
-values.
-
- (gdb) p lquote
- $1 = 0x35d40 "<QUOTE>"
- (gdb) p rquote
- $2 = 0x35d50 "<UNQUOTE>"
-
-`lquote' and `rquote' are indeed the new left and right quotes. To
-look at some context, we can display ten lines of source surrounding
-the current line with the `l' (`list') command.
-
- (gdb) l
- 533 xfree(rquote);
- 534
- 535 lquote = (lq == nil || *lq == '\0') ? def_lquote\
- : xstrdup (lq);
- 536 rquote = (rq == nil || *rq == '\0') ? def_rquote\
- : xstrdup (rq);
- 537
- 538 len_lquote = strlen(rquote);
- 539 len_rquote = strlen(lquote);
- 540 }
- 541
- 542 void
-
-Let us step past the two lines that set `len_lquote' and `len_rquote',
-and then examine the values of those variables.
-
- (gdb) n
- 539 len_rquote = strlen(lquote);
- (gdb) n
- 540 }
- (gdb) p len_lquote
- $3 = 9
- (gdb) p len_rquote
- $4 = 7
-
-That certainly looks wrong, assuming `len_lquote' and `len_rquote' are
-meant to be the lengths of `lquote' and `rquote' respectively. We can
-set them to better values using the `p' command, since it can print the
-value of any expression--and that expression can include subroutine
-calls and assignments.
-
- (gdb) p len_lquote=strlen(lquote)
- $5 = 7
- (gdb) p len_rquote=strlen(rquote)
- $6 = 9
-
-Is that enough to fix the problem of using the new quotes with the `m4'
-built-in `defn'? We can allow `m4' to continue executing with the `c'
-(`continue') command, and then try the example that caused trouble
-initially:
-
- (gdb) c
- Continuing.
-
- define(baz,defn(<QUOTE>foo<UNQUOTE>))
-
- baz
- 0000
-
-Success! The new quotes now work just as well as the default ones. The
-problem seems to have been just the two typos defining the wrong
-lengths. We allow `m4' exit by giving it an EOF as input:
-
- C-d
- Program exited normally.
-
-The message `Program exited normally.' is from GDB; it indicates `m4'
-has finished executing. We can end our GDB session with the GDB `quit'
-command.
-
- (gdb) quit
-
-\1f
-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
-
-\1f
-File: gdb.info, Node: Invoking GDB, Next: Quitting GDB, Prev: Invocation, Up: Invocation
-
-Invoking GDB
-============
-
- Invoke GDB by running the program `gdb'. Once started, GDB reads
-commands from the terminal until you tell it to exit.
-
- You can also run `gdb' with a variety of arguments and options, to
-specify more of your debugging environment at the outset.
-
- The command-line options described here are designed to cover a
-variety of situations; in some environments, some of these options may
-effectively be unavailable.
-
- The most usual way to start GDB is with one argument, specifying an
-executable program:
-
- gdb PROGRAM
-
-You can also start with both an executable program and a core file
-specified:
-
- gdb PROGRAM CORE
-
- You can, instead, specify a process ID as a second argument, if you
-want to debug a running process:
-
- gdb PROGRAM 1234
-
-would attach GDB to process `1234' (unless you also have a file named
-`1234'; GDB does check for a core file first).
-
- Taking advantage of the second command-line argument requires a
-fairly complete operating system; when you use GDB as a remote debugger
-attached to a bare board, there may not be any notion of "process", and
-there is often no way to get a core dump.
-
- You can run `gdb' without printing the front material, which
-describes GDB's non-warranty, by specifying `-silent':
-
- gdb -silent
-
-You can further control how GDB starts up by using command-line
-options. GDB itself can remind you of the options available.
-
-Type
-
- gdb -help
-
-to display all available options and briefly describe their use (`gdb
--h' is a shorter equivalent).
-
- All options and command line arguments you give are processed in
-sequential order. The order makes a difference when the `-x' option is
-used.
-
-* Menu:
-
-
-* File Options:: Choosing files
-* Mode Options:: Choosing modes
-
-\1f
-File: gdb.info, Node: File Options, Next: Mode Options, Up: Invoking GDB
-
-Choosing files
---------------
-
- When GDB starts, it reads any arguments other than options as
-specifying an executable file and core file (or process ID). This is
-the same as if the arguments were specified by the `-se' and `-c'
-options respectively. (GDB reads the first argument that does not have
-an associated option flag as equivalent to the `-se' option followed by
-that argument; and the second argument that does not have an associated
-option flag, if any, as equivalent to the `-c' option followed by that
-argument.)
-
- Many options have both long and short forms; both are shown in the
-following list. GDB also recognizes the long forms if you truncate
-them, so long as enough of the option is present to be unambiguous.
-(If you prefer, you can flag option arguments with `--' rather than
-`-', though we illustrate the more usual convention.)
-
-`-symbols FILE'
-`-s FILE'
- Read symbol table from file FILE.
-
-`-exec FILE'
-`-e FILE'
- Use file FILE as the executable file to execute when appropriate,
- and for examining pure data in conjunction with a core dump.
-
-`-se FILE'
- Read symbol table from file FILE and use it as the executable file.
-
-`-core FILE'
-`-c FILE'
- Use file FILE as a core dump to examine.
-
-`-c NUMBER'
- Connect to process ID NUMBER, as with the `attach' command (unless
- there is a file in core-dump format named NUMBER, in which case
- `-c' specifies that file as a core dump to read).
-
-`-command FILE'
-`-x FILE'
- Execute GDB commands from file FILE. *Note Command files: Command
- Files.
-
-`-directory DIRECTORY'
-`-d DIRECTORY'
- Add DIRECTORY to the path to search for source files.
-
-`-m'
-`-mapped'
- *Warning: this option depends on operating system facilities that
- are not supported on all systems.*
- If memory-mapped files are available on your system through the
- `mmap' system call, you can use this option to have GDB write the
- symbols from your program into a reusable file in the current
- directory. If the program you are debugging is called
- `/tmp/fred', the mapped symbol file is `./fred.syms'. Future GDB
- debugging sessions notice the presence of this file, and can
- quickly map in symbol information from it, rather than reading the
- symbol table from the executable program.
-
- The `.syms' file is specific to the host machine where GDB is run.
- It holds an exact image of the internal GDB symbol table. It
- cannot be shared across multiple host platforms.
-
-`-r'
-`-readnow'
- Read each symbol file's entire symbol table immediately, rather
- than the default, which is to read it incrementally as it is
- needed. This makes startup slower, but makes future operations
- faster.
-
- The `-mapped' and `-readnow' options are typically combined in order
-to build a `.syms' file that contains complete symbol information.
-(*Note Commands to specify files: Files, for information on `.syms'
-files.) A simple GDB invocation to do nothing but build a `.syms' file
-for future use is:
-
- gdb -batch -nx -mapped -readnow programname
-
-\1f
-File: gdb.info, Node: Mode Options, Prev: File Options, Up: Invoking GDB
-
-Choosing modes
---------------
-
- You can run GDB in various alternative modes--for example, in batch
-mode or quiet mode.
-
-`-nx'
-`-n'
- Do not execute commands from any initialization files (normally
- called `.gdbinit', or `gdb.ini' on PCs). Normally, the commands in
- these files are executed after all the command options and
- arguments have been processed. *Note Command files: Command Files.
-
-`-quiet'
-`-q'
- "Quiet". Do not print the introductory and copyright messages.
- These messages are also suppressed in batch mode.
-
-`-batch'
- Run in batch mode. Exit with status `0' after processing all the
- command files specified with `-x' (and all commands from
- initialization files, if not inhibited with `-n'). Exit with
- nonzero status if an error occurs in executing the GDB commands in
- the command files.
-
- Batch mode may be useful for running GDB as a filter, for example
- to download and run a program on another computer; in order to
- make this more useful, the message
-
- Program exited normally.
-
- (which is ordinarily issued whenever a program running under GDB
- control terminates) is not issued when running in batch mode.
-
-`-cd DIRECTORY'
- Run GDB using DIRECTORY as its working directory, instead of the
- current directory.
-
-`-fullname'
-`-f'
- GNU Emacs sets this option when it runs GDB as a subprocess. It
- tells GDB to output the full file name and line number in a
- standard, recognizable fashion each time a stack frame is
- displayed (which includes each time your program stops). This
- recognizable format looks like two `\032' characters, followed by
- the file name, line number and character position separated by
- colons, and a newline. The Emacs-to-GDB interface program uses
- the two `\032' characters as a signal to display the source code
- for the frame.
-
-`-b BPS'
- Set the line speed (baud rate or bits per second) of any serial
- interface used by GDB for remote debugging.
-
-`-tty DEVICE'
- Run using DEVICE for your program's standard input and output.
-
-\1f
-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.).
-
-\1f
-File: gdb.info, Node: Shell Commands, Prev: Quitting GDB, Up: Invocation
-
-Shell commands
-==============
-
- If you need to execute occasional shell commands during your
-debugging session, there is no need to leave or suspend GDB; you can
-just use the `shell' command.
-
-`shell COMMAND STRING'
- Invoke a standard shell to execute COMMAND STRING. If it exists,
- the environment variable `SHELL' determines which shell to run.
- Otherwise GDB uses `/bin/sh'.
-
- The utility `make' is often needed in development environments. You
-do not have to use the `shell' command for this purpose in GDB:
-
-`make MAKE-ARGS'
- Execute the `make' program with the specified arguments. This is
- equivalent to `shell make MAKE-ARGS'.
-
-\1f
-File: gdb.info, Node: Commands, Next: Running, Prev: Invocation, Up: Top
-
-GDB Commands
-************
-
- You can abbreviate a GDB command to the first few letters of the
-command name, if that abbreviation is unambiguous; and you can repeat
-certain GDB commands by typing just <RET>. You can also use the <TAB>
-key to get GDB to fill out the rest of a word in a command (or to show
-you the alternatives available, if there is more than one possibility).
-
-* Menu:
-
-* Command Syntax:: How to give commands to GDB
-* Completion:: Command completion
-* Help:: How to ask GDB for help
-
-\1f
-File: gdb.info, Node: Command Syntax, Next: Completion, Prev: Commands, Up: Commands
-
-Command syntax
-==============
-
- A GDB command is a single line of input. There is no limit on how
-long it can be. It starts with a command name, which is followed by
-arguments whose meaning depends on the command name. For example, the
-command `step' accepts an argument which is the number of times to
-step, as in `step 5'. You can also use the `step' command with no
-arguments. Some command names do not allow any arguments.
-
- GDB command names may always be truncated if that abbreviation is
-unambiguous. Other possible command abbreviations are listed in the
-documentation for individual commands. In some cases, even ambiguous
-abbreviations are allowed; for example, `s' is specially defined as
-equivalent to `step' even though there are other commands whose names
-start with `s'. You can test abbreviations by using them as arguments
-to the `help' command.
-
- A blank line as input to GDB (typing just <RET>) means to repeat the
-previous command. Certain commands (for example, `run') will not repeat
-this way; these are commands whose unintentional repetition might cause
-trouble and which you are unlikely to want to repeat.
-
- The `list' and `x' commands, when you repeat them with <RET>,
-construct new arguments rather than repeating exactly as typed. This
-permits easy scanning of source or memory.
-
- GDB can also use <RET> in another way: to partition lengthy output,
-in a way similar to the common utility `more' (*note Screen size:
-Screen Size.). Since it is easy to press one <RET> too many in this
-situation, GDB disables command repetition after any command that
-generates this sort of display.
-
- Any text from a `#' to the end of the line is a comment; it does
-nothing. This is useful mainly in command files (*note Command files:
-Command Files.).
-
-\1f
-File: gdb.info, Node: Completion, Next: Help, Prev: Command Syntax, Up: Commands
-
-Command completion
-==================
-
- GDB can fill in the rest of a word in a command for you, if there is
-only one possibility; it can also show you what the valid possibilities
-are for the next word in a command, at any time. This works for GDB
-commands, GDB subcommands, and the names of symbols in your program.
-
- Press the <TAB> key whenever you want GDB to fill out the rest of a
-word. If there is only one possibility, GDB fills in the word, and
-waits for you to finish the command (or press <RET> to enter it). For
-example, if you type
-
- (gdb) info bre <TAB>
-
-GDB fills in the rest of the word `breakpoints', since that is the only
-`info' subcommand beginning with `bre':
-
- (gdb) info breakpoints
-
-You can either press <RET> at this point, to run the `info breakpoints'
-command, or backspace and enter something else, if `breakpoints' does
-not look like the command you expected. (If you were sure you wanted
-`info breakpoints' in the first place, you might as well just type
-<RET> immediately after `info bre', to exploit command abbreviations
-rather than command completion).
-
- If there is more than one possibility for the next word when you
-press <TAB>, GDB sounds a bell. You can either supply more characters
-and try again, or just press <TAB> a second time; GDB displays all the
-possible completions for that word. For example, you might want to set
-a breakpoint on a subroutine whose name begins with `make_', but when
-you type `b make_<TAB>' GDB just sounds the bell. Typing <TAB> again
-displays all the function names in your program that begin with those
-characters, for example:
-
- (gdb) b make_ <TAB>
-GDB sounds bell; press <TAB> again, to see:
- make_a_section_from_file make_environ
- make_abs_section make_function_type
- make_blockvector make_pointer_type
- make_cleanup make_reference_type
- make_command make_symbol_completion_list
- (gdb) b make_
-
-After displaying the available possibilities, GDB copies your partial
-input (`b make_' in the example) so you can finish the command.
-
- If you just want to see the list of alternatives in the first place,
-you can press `M-?' rather than pressing <TAB> twice. `M-?' means
-`<META> ?'. You can type this either by holding down a key designated
-as the <META> shift on your keyboard (if there is one) while typing
-`?', or as <ESC> followed by `?'.
-
- Sometimes the string you need, while logically a "word", may contain
-parentheses or other characters that GDB normally excludes from its
-notion of a word. To permit word completion to work in this situation,
-you may enclose words in `'' (single quote marks) in GDB commands.
-
- The most likely situation where you might need this is in typing the
-name of a C++ function. This is because C++ allows function overloading
-(multiple definitions of the same function, distinguished by argument
-type). For example, when you want to set a breakpoint you may need to
-distinguish whether you mean the version of `name' that takes an `int'
-parameter, `name(int)', or the version that takes a `float' parameter,
-`name(float)'. To use the word-completion facilities in this
-situation, type a single quote `'' at the beginning of the function
-name. This alerts GDB that it may need to consider more information
-than usual when you press <TAB> or `M-?' to request word completion:
-
- (gdb) b 'bubble( <M-?>
- bubble(double,double) bubble(int,int)
- (gdb) b 'bubble(
-
- In some cases, GDB can tell that completing a name requires using
-quotes. When this happens, GDB inserts the quote for you (while
-completing as much as it can) if you do not type the quote in the first
-place:
-
- (gdb) b bub <TAB>
-GDB alters your input line to the following, and rings a bell:
- (gdb) b 'bubble(
-
-In general, GDB can tell that a quote is needed (and inserts it) if you
-have not yet started typing the argument list when you ask for
-completion on an overloaded symbol.
-
- For more information about overloaded functions, *note C++
-expressions: Cplus expressions.. You can use the command `set
-overload-resolution off' to disable overload resolution; *note GDB
-features for C++: Debugging C plus plus..
-
-\1f
-File: gdb.info, Node: Help, Prev: Completion, Up: Commands
-
-Getting help
-============
-
- You can always ask GDB itself for information on its commands, using
-the command `help'.
-
-`help'
-`h'
- You can use `help' (abbreviated `h') with no arguments to display
- a short list of named classes of commands:
-
- (gdb) help
- List of classes of commands:
-
- running -- Running the program
- stack -- Examining the stack
- data -- Examining data
- breakpoints -- Making program stop at certain points
- files -- Specifying and examining files
- status -- Status inquiries
- support -- Support facilities
- user-defined -- User-defined commands
- aliases -- Aliases of other commands
- obscure -- Obscure features
-
- Type "help" followed by a class name for a list of
- commands in that class.
- Type "help" followed by command name for full
- documentation.
- Command name abbreviations are allowed if unambiguous.
- (gdb)
-
-`help CLASS'
- Using one of the general help classes as an argument, you can get a
- list of the individual commands in that class. For example, here
- is the help display for the class `status':
-
- (gdb) help status
- Status inquiries.
-
- List of commands:
-
- show -- Generic command for showing things set
- with "set"
- info -- Generic command for printing status
-
- Type "help" followed by command name for full
- documentation.
- Command name abbreviations are allowed if unambiguous.
- (gdb)
-
-`help COMMAND'
- With a command name as `help' argument, GDB displays a short
- paragraph on how to use that command.
-
-`complete ARGS'
- The `complete ARGS' command lists all the possible completions for
- the beginning of a command. Use ARGS to specify the beginning of
- the command you want completed. For example:
-
- complete i
-
- results in:
-
- info
- inspect
- ignore
-
- This is intended for use by GNU Emacs.
-
- In addition to `help', you can use the GDB commands `info' and
-`show' to inquire about the state of your program, or the state of GDB
-itself. Each command supports many topics of inquiry; this manual
-introduces each of them in the appropriate context. The listings under
-`info' and under `show' in the Index point to all the sub-commands.
-*Note Index::.
-
-`info'
- This command (abbreviated `i') is for describing the state of your
- program. For example, you can list the arguments given to your
- program with `info args', list the registers currently in use with
- `info registers', or list the breakpoints you have set with `info
- breakpoints'. You can get a complete list of the `info'
- sub-commands with `help info'.
-
-`set'
- You can assign the result of an expression to an environment
- variable with `set'. For example, you can set the GDB prompt to a
- $-sign with `set prompt $'.
-
-`show'
- In contrast to `info', `show' is for describing the state of GDB
- itself. You can change most of the things you can `show', by
- using the related command `set'; for example, you can control what
- number system is used for displays with `set radix', or simply
- inquire which is currently in use with `show radix'.
-
- To display all the settable parameters and their current values,
- you can use `show' with no arguments; you may also use `info set'.
- Both commands produce the same display.
-
- Here are three miscellaneous `show' subcommands, all of which are
-exceptional in lacking corresponding `set' commands:
-
-`show version'
- Show what version of GDB is running. You should include this
- information in GDB bug-reports. If multiple versions of GDB are in
- use at your site, you may occasionally want to determine which
- version of GDB you are running; as GDB evolves, new commands are
- introduced, and old ones may wither away. The version number is
- also announced when you start GDB.
-
-`show copying'
- Display information about permission for copying GDB.
-
-`show warranty'
- Display the GNU "NO WARRANTY" statement.
-
-\1f
-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
-
-\1f
-File: gdb.info, Node: Compilation, Next: Starting, Prev: Running, Up: Running
-
-Compiling for debugging
-=======================
-
- In order to debug a program effectively, you need to generate
-debugging information when you compile it. This debugging information
-is stored in the object file; it describes the data type of each
-variable or function and the correspondence between source line numbers
-and addresses in the executable code.
-
- To request debugging information, specify the `-g' option when you
-run the compiler.
-
- Many C compilers are unable to handle the `-g' and `-O' options
-together. Using those compilers, you cannot generate optimized
-executables containing debugging information.
-
- GCC, the GNU C compiler, supports `-g' with or without `-O', making
-it possible to debug optimized code. We recommend that you *always*
-use `-g' whenever you compile a program. You may think your program is
-correct, but there is no sense in pushing your luck.
-
- When you debug a program compiled with `-g -O', remember that the
-optimizer is rearranging your code; the debugger shows you what is
-really there. Do not be too surprised when the execution path does not
-exactly match your source file! An extreme example: if you define a
-variable, but never use it, GDB never sees that variable--because the
-compiler optimizes it out of existence.
-
- Some things do not work as well with `-g -O' as with just `-g',
-particularly on machines with instruction scheduling. If in doubt,
-recompile with `-g' alone, and if this fixes the problem, please report
-it to us as a bug (including a test case!).
-
- Older versions of the GNU C compiler permitted a variant option
-`-gg' for debugging information. GDB no longer supports this format;
-if your GNU C compiler has this option, do not use it.
-
+++ /dev/null
-This is Info file ./gdb.info, produced by Makeinfo version 1.68 from
-the input file gdb.texinfo.
-
-START-INFO-DIR-ENTRY
-* Gdb: (gdb). The GNU debugger.
-END-INFO-DIR-ENTRY
- This file documents the GNU debugger GDB.
-
- This is the Seventh Edition, February 1999, of `Debugging with GDB:
-the GNU Source-Level Debugger' for GDB Version 4.18.
-
- Copyright (C) 1988-1999 Free Software Foundation, Inc.
-
- Permission is granted to make and distribute verbatim copies of this
-manual provided the copyright notice and this permission notice are
-preserved on all copies.
-
- Permission is granted to copy and distribute modified versions of
-this manual under the conditions for verbatim copying, provided also
-that the entire resulting derived work is distributed under the terms
-of a permission notice identical to this one.
-
- Permission is granted to copy and distribute translations of this
-manual into another language, under the above conditions for modified
-versions.
-
-\1f
-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.
-* Alpha stack: Alpha/MIPS Stack.
-* 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.
-* backtraces: Backtrace.
-* bell-style: Readline Init File Syntax.
-* 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 events: 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 Constants.
-* 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: Set Catchpoints.
-* catch catch: Set Catchpoints.
-* catch exceptions: Frame Info.
-* catch exec: Set Catchpoints.
-* catch fork: Set Catchpoints.
-* catch load: Set Catchpoints.
-* catch throw: Set Catchpoints.
-* catch unload: Set Catchpoints.
-* catch vfork: Set Catchpoints.
-* catchpoints <1>: Set Catchpoints.
-* catchpoints: Breakpoints.
-* cd: Working Directory.
-* cdir: Source Path.
-* checks, range: Type Checking.
-* checks, type: Checks.
-* checksum, for GDB remote: Protocol.
-* choosing target byte order: Byte Order.
-* clear: Delete Breaks.
-* clearing breakpoints, watchpoints, catchpoints: Delete Breaks.
-* COFF versus C++: Cplus expressions.
-* colon, doubled as scope operator: M2 Scope.
-* colon-colon <1>: Variables.
-* colon-colon: M2 Scope.
-* command editing: Readline Bare Essentials.
-* command files <1>: Hooks.
-* command files: Command Files.
-* command line editing: Editing.
-* commands: Break Commands.
-* commands for C++: Debugging C plus plus.
-* commands to STDBUG (ST2000): ST2000 Remote.
-* comment: Command Syntax.
-* comment-begin: Readline Init File Syntax.
-* compilation directory: Source Path.
-* Compiling: Sparclet Remote.
-* complete: Help.
-* completion: Completion.
-* completion of quoted strings: Completion.
-* completion-query-items: Readline Init File Syntax.
-* 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.
-* convert-meta: Readline Init File Syntax.
-* 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, catchpoints: 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.
-* disable-completion: Readline Init File Syntax.
-* 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: Target Commands.
-* download to Hitachi SH: Target Commands.
-* download to Nindy-960: Target Commands.
-* 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 command lines: Readline Bare Essentials.
-* editing-mode: Readline Init File 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.
-* enable-keypad: Readline Init File Syntax.
-* end: Break Commands.
-* entering numbers: Numbers.
-* environment (of your program): Environment.
-* error on valid input: Bug Criteria.
-* event designators: Event Designators.
-* event handling: Set Catchpoints.
-* examining data: Data.
-* examining memory: Memory.
-* exception handlers <1>: Frame Info.
-* exception handlers: Set Catchpoints.
-* exceptionHandler: Bootstrapping.
-* exec-file: Files.
-* executable file: Files.
-* exiting GDB: Quitting GDB.
-* expand-tilde: Readline Init File Syntax.
-* 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: Target Commands.
-* H8/300 or H8/500 simulator: Simulator.
-* handle: Signals.
-* handle_exception: Stub Contents.
-* handling signals: Signals.
-* hardware watchpoints: Set Watchpoints.
-* hbreak: Set Breaks.
-* help: Help.
-* help target: Target Commands.
-* help user-defined: Define.
-* heuristic-fence-post (Alpha,MIPS): Alpha/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: Target Commands.
-* Hitachi SH simulator: Simulator.
-* horizontal-scroll-mode: Readline Init File 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 extensions: Show.
-* info f: Frame Info.
-* info files: Files.
-* info float: Floating Point Hardware.
-* info frame <1>: Frame Info.
-* info frame: Show.
-* 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.
-* initialization file, readline: Readline Init File.
-* innermost frame: Frames.
-* input-meta: Readline Init File Syntax.
-* 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.
-* keymap: Readline Init File Syntax.
-* kill: Kill Process.
-* kill ring: Readline Killing Commands.
-* killing text: Readline Killing Commands.
-* l: List.
-* languages: Languages.
-* latest breakpoint: Set Breaks.
-* leaving GDB: Quitting GDB.
-* linespec: List.
-* list: List.
-* listing machine instructions: Machine Code.
-* load FILENAME: Target Commands.
-* 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 File 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.
-* meta-flag: Readline Init File Syntax.
-* MIPS boards: MIPS Remote.
-* MIPS remote floating point: MIPS Remote.
-* MIPS remotedebug protocol: MIPS Remote.
-* MIPS stack: Alpha/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.
-* notation, readline: Readline Bare Essentials.
-* 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.
-* output-meta: Readline Init File Syntax.
-* 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.
-* 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: Set Catchpoints.
-* 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: Alpha/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: Starting.
-* Running: Sparclet Remote.
-* 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>: Type Checking.
-* set check: Range 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: Byte Order.
-* set endian big: Byte Order.
-* set endian little: Byte Order.
-* set environment: Environment.
-* set extension-language: Show.
-* 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>: Protocol.
-* set remotedebug: MIPS Remote.
-* 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: Byte Order.
-* 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.
-* show-all-if-ambiguous: Readline Init File Syntax.
-* 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.
-* software watchpoints: Set Watchpoints.
-* 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 Alpha: Alpha/MIPS Stack.
-* stack on MIPS: Alpha/MIPS Stack.
-* stack traces: Backtrace.
-* 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 abug: Target Commands.
-* target adapt: Target Commands.
-* target amd-eb: Target Commands.
-* target array: Target Commands.
-* target bug: Target Commands.
-* target byte order: Byte Order.
-* target core: Target Commands.
-* target cpu32bug: Target Commands.
-* target dbug: Target Commands.
-* target ddb: Target Commands.
-* target ddb PORT: MIPS Remote.
-* target dink32: Target Commands.
-* target e7000 <1>: Hitachi ICE.
-* target e7000: Target Commands.
-* target es1800: Target Commands.
-* target est: Target Commands.
-* target exec: Target Commands.
-* target hms: Target Commands.
-* target lsi: Target Commands.
-* target lsi PORT: MIPS Remote.
-* target m32r: Target Commands.
-* target mips: Target Commands.
-* target mips PORT: MIPS Remote.
-* target mon960: Target Commands.
-* target nindy: Target Commands.
-* target nrom: Target Commands.
-* target op50n: Target Commands.
-* target pmon: Target Commands.
-* target pmon PORT: MIPS Remote.
-* target ppcbug: Target Commands.
-* target ppcbug1: Target Commands.
-* target r3900: Target Commands.
-* target rdi: Target Commands.
-* target rdp: Target Commands.
-* target remote: Target Commands.
-* target rom68k: Target Commands.
-* target rombug: Target Commands.
-* target sds: Target Commands.
-* target sh3: Target Commands.
-* target sh3e: Target Commands.
-* target sim <1>: Target Commands.
-* target sim: Simulator.
-* 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.
-* tracebacks: Backtrace.
-* 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.
-* visible-stats: Readline Init File Syntax.
-* 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.
-* yanking text: Readline Killing Commands.
-* Z8000 simulator: Simulator.
-* {TYPE}: Expressions.
-
-
+++ /dev/null
-This is Info file ./gdb.info, produced by Makeinfo version 1.68 from
-the input file gdb.texinfo.
-
-START-INFO-DIR-ENTRY
-* Gdb: (gdb). The GNU debugger.
-END-INFO-DIR-ENTRY
- This file documents the GNU debugger GDB.
-
- This is the Seventh Edition, February 1999, of `Debugging with GDB:
-the GNU Source-Level Debugger' for GDB Version 4.18.
-
- Copyright (C) 1988-1999 Free Software Foundation, Inc.
-
- Permission is granted to make and distribute verbatim copies of this
-manual provided the copyright notice and this permission notice are
-preserved on all copies.
-
- Permission is granted to copy and distribute modified versions of
-this manual under the conditions for verbatim copying, provided also
-that the entire resulting derived work is distributed under the terms
-of a permission notice identical to this one.
-
- Permission is granted to copy and distribute translations of this
-manual into another language, under the above conditions for modified
-versions.
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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'.
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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 <RET> 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 you use `attach', the debugger finds the program running in the
-process first by looking in the current working directory, then (if the
-program is not found) by using the source file search path (*note
-Specifying source directories: Source Path.). You can also use the
-`file' command to load the program. *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 <RET> 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.).
-
-\1f
-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).
-
-\1f
-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.
-
-\1f
-File: gdb.info, Node: Threads, Next: Processes, Prev: Process Information, Up: Running
-
-Debugging programs with multiple threads
-========================================
-
- In some operating systems, such as HP-UX and Solaris, 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.
-
-\1f
-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.
-
-\1f
-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 catchpoints
-* Continuing and Stepping:: Resuming execution
-
-* Signals:: Signals
-
-
-* Thread Stops:: Stopping and starting multi-thread programs
-
-\1f
-File: gdb.info, Node: Breakpoints, Next: Continuing and Stepping, Prev: Stopping, Up: Stopping
-
-Breakpoints, watchpoints, and catchpoints
-=========================================
-
- 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 HP-UX, SunOS 4.x, SVR4, and Alpha OSF/1 configurations, you can
-set breakpoints in shared libraries before the executable is run.
-There is a minor limitation on HP-UX systems: you must wait until the
-executable is run in order to set breakpoints in shared library
-routines that are not called directly by the program (for example,
-routines that are arguments in a `pthread_create' call).
-
- 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.
-
- A "catchpoint" is another special breakpoint that stops your program
-when a certain kind of event occurs, such as the throwing of a C++
-exception or the loading of a library. As with watchpoints, you use a
-different command to set a catchpoint (*note Setting catchpoints: Set
-Catchpoints.), but aside from that, you can manage a catchpoint like any
-other breakpoint. (To stop when your program receives a signal, use the
-`handle' command; *note Signals: Signals..)
-
- GDB assigns a number to each breakpoint, watchpoint, or catchpoint
-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
-* Set Catchpoints:: Setting catchpoints
-* Delete Breaks:: Deleting breakpoints
-* Disabling:: Disabling breakpoints
-* Conditions:: Break conditions
-* Break Commands:: Breakpoint command lists
-
-* Breakpoint Menus:: Breakpoint menus
-
-\1f
-File: gdb.info, Node: Set Breaks, Next: Set Watchpoints, Prev: Breakpoints, 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 data 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 unused 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, watchpoints, and catchpoints set
- and not deleted, with the following columns for each breakpoint:
-
- *Breakpoint Numbers*
-
- *Type*
- Breakpoint, watchpoint, or catchpoint.
-
- *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' 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.
-
-\1f
-File: gdb.info, Node: Set Watchpoints, Next: Set Catchpoints, 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.
-
- Depending on your system, watchpoints may be implemented in software
-or hardware. GDB does software watchpointing by single-stepping your
-program and testing the variable's value each time, which is hundreds of
-times slower than normal execution. (But this may still be worth it, to
-catch errors where you have no clue what part of your program is the
-culprit.)
-
- On some systems, such as HP-UX and Linux, GDB includes support for
-hardware watchpoints, which do not slow down the running of your
-program.
-
-`watch EXPR'
- Set a watchpoint for an expression. GDB will break when EXPR is
- written into by the program and its value changes.
-
-`rwatch EXPR'
- Set a watchpoint that will break when watch EXPR 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, breakpoints, and
- catchpoints; it is the same as `info break'.
-
- GDB sets a "hardware watchpoint" if possible. Hardware watchpoints
-execute very quickly, and the debugger reports a change in value at the
-exact instruction where the change occurs. If GDB cannot set a
-hardware watchpoint, it sets a software watchpoint, which executes more
-slowly and reports the change in value at the next statement, not the
-instruction, after the change occurs.
-
- When you issue the `watch' command, GDB reports
-
- Hardware watchpoint NUM: EXPR
-
-if it was able to set a hardware watchpoint.
-
- The SPARClite DSU will generate traps when a program accesses some
-data 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. GDB will reject the
-command if you try to mix watchpoints. Delete or disable unused
-watchpoint commands before setting new ones.
-
- If you call a function interactively using `print' or `call', any
-watchpoints you have set will be inactive until GDB reaches another
-kind of breakpoint or the call completes.
-
- *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.
-
-\1f
-File: gdb.info, Node: Set Catchpoints, Next: Delete Breaks, Prev: Set Watchpoints, Up: Breakpoints
-
-Setting catchpoints
--------------------
-
- You can use "catchpoints" to cause the debugger to stop for certain
-kinds of program events, such as C++ exceptions or the loading of a
-shared library. Use the `catch' command to set a catchpoint.
-
-`catch EVENT'
- Stop when EVENT occurs. EVENT can be any of the following:
- `throw'
- The throwing of a C++ exception.
-
- `catch'
- The catching of a C++ exception.
-
- `exec'
- A call to `exec'. This is currently only available for HP-UX.
-
- `fork'
- A call to `fork'. This is currently only available for HP-UX.
-
- `vfork'
- A call to `vfork'. This is currently only available for
- HP-UX.
-
- `load'
- `load LIBNAME'
- The dynamic loading of any shared library, or the loading of
- the library LIBNAME. This is currently only available for
- HP-UX.
-
- `unload'
- `unload LIBNAME'
- The unloading of any dynamically loaded shared library, or
- the unloading of the library LIBNAME. This is currently only
- available for HP-UX.
-
-`tcatch EVENT'
- Set a catchpoint that is enabled only for one stop. The
- catchpoint is automatically deleted after the first time the event
- is caught.
-
- Use the `info break' command to list the current catchpoints.
-
- There are currently some limitations to C++ exception handling
-(`catch throw' and `catch catch') 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 either to abort
- or to simply continue running until it hits a breakpoint, catches
- a signal that GDB is listening for, or exits. This is the case
- even if you set a catchpoint for the exception; catchpoints on
- exceptions are disabled within interactive calls.
-
- * 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.
-
-\1f
-File: gdb.info, Node: Delete Breaks, Next: Disabling, Prev: Set Catchpoints, Up: Breakpoints
-
-Deleting breakpoints
---------------------
-
- It is often necessary to eliminate a breakpoint, watchpoint, or
-catchpoint 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, watchpoints, or catchpoints 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, watchpoints, or catchpoints 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'.
-
-\1f
-File: gdb.info, Node: Disabling, Next: Conditions, Prev: Delete Breaks, Up: Breakpoints
-
-Disabling breakpoints
----------------------
-
- Rather than deleting a breakpoint, watchpoint, or catchpoint, 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, watchpoints, and catchpoints 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, watchpoints, and catchpoints if you do not
-know which numbers to use.
-
- A breakpoint, watchpoint, or catchpoint 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,
-watchpoints, and catchpoints:
-
-`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.)
-
-\1f
-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,
- watchpoint, or catchpoint 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.
-
- Ignore counts apply to breakpoints, watchpoints, and catchpoints.
-
+++ /dev/null
-This is Info file ./gdb.info, produced by Makeinfo version 1.68 from
-the input file gdb.texinfo.
-
-START-INFO-DIR-ENTRY
-* Gdb: (gdb). The GNU debugger.
-END-INFO-DIR-ENTRY
- This file documents the GNU debugger GDB.
-
- This is the Seventh Edition, February 1999, of `Debugging with GDB:
-the GNU Source-Level Debugger' for GDB Version 4.18.
-
- Copyright (C) 1988-1999 Free Software Foundation, Inc.
-
- Permission is granted to make and distribute verbatim copies of this
-manual provided the copyright notice and this permission notice are
-preserved on all copies.
-
- Permission is granted to copy and distribute modified versions of
-this manual under the conditions for verbatim copying, provided also
-that the entire resulting derived work is distributed under the terms
-of a permission notice identical to this one.
-
- Permission is granted to copy and distribute translations of this
-manual into another language, under the above conditions for modified
-versions.
-
-\1f
-File: gdb.info, Node: Break Commands, Next: Breakpoint Menus, Prev: Conditions, Up: Breakpoints
-
-Breakpoint command lists
-------------------------
-
- You can give any breakpoint (or watchpoint or catchpoint) 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,
- watchpoint, or catchpoint set (not to the breakpoint most recently
- encountered).
-
- Pressing <RET> 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
-
-\1f
-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)
-
-\1f
-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 catchpoints: 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 switch 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.).
-
-`until'
-`u'
- 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'.
-
-\1f
-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.
-
-\1f
-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.
-
- On some OSes, you can lock the OS scheduler and thus allow only a
-single thread to run.
-
-`set scheduler-locking MODE'
- Set the scheduler locking mode. If it is `off', then there is no
- locking and any thread may run at any time. If `on', then only the
- current thread may run when the inferior is resumed. The `step'
- mode optimizes for single-stepping. It stops other threads from
- "seizing the prompt" by preempting the current thread while you are
- stepping. Other threads will only rarely (or never) get a chance
- to run when you step. They are more likely to run when you "next"
- over a function call, and they are completely free to run when you
- use commands like "continue", "until", or "finish". However,
- unless another thread hits a breakpoint during its timeslice, they
- will never steal the GDB prompt away from the thread that you are
- debugging.
-
-`show scheduler-locking'
- Display the current scheduler locking mode.
-
-\1f
-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
-* Alpha/MIPS Stack:: Alpha and MIPS machines and the function stack
-
-\1f
-File: gdb.info, Node: Frames, Next: Backtrace, Prev: Stack, 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'.
-
-\1f
-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'.
-
-\1f
-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.
-
-\1f
-File: gdb.info, Node: Frame Info, Next: Alpha/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
- Setting catchpoints: Set Catchpoints.
-
-\1f
-File: gdb.info, Node: Alpha/MIPS Stack, Prev: Frame Info, Up: Stack
-
-MIPS/Alpha machines and the function stack
-==========================================
-
- Alpha- and 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 Alpha or MIPS processors.
-
-\1f
-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
-
-\1f
-File: gdb.info, Node: List, Next: Search, Prev: Source, 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 <RET> 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.
-
-\1f
-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'.
-
-\1f
-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.
-
-\1f
-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.
-
- The following example shows the disassembly of a range of addresses
-of HP PA-RISC 2.0 code:
-
- (gdb) disas 0x32c4 0x32e4
- Dump of assembler code from 0x32c4 to 0x32e4:
- 0x32c4 <main+204>: addil 0,dp
- 0x32c8 <main+208>: ldw 0x22c(sr0,r1),r26
- 0x32cc <main+212>: ldil 0x3000,r31
- 0x32d0 <main+216>: ble 0x3f8(sr4,r31)
- 0x32d4 <main+220>: ldo 0(r31),rp
- 0x32d8 <main+224>: addil -0x800,dp
- 0x32dc <main+228>: ldo 0x588(r1),r26
- 0x32e0 <main+232>: ldil 0x3000,r31
- End of assembler dump.
-
- Some architectures have more than one commonly-used set of
-instruction mnemonics or other syntax.
-
-`set assembly-language INSTRUCTION-SET'
- Select the instruction set to use when disassembling the program
- via the `disassemble' or `x/i' commands.
-
- Currently this command is only defined for the Intel x86 family.
- You can set INSTRUCTION-SET to either `i386' or `i8086'. The
- default is `i386'.
-
-\1f
-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
-
-\1f
-File: gdb.info, Node: Expressions, Next: Variables, Prev: Data, 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.
-
-\1f
-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 file-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.
-
- This may also happen when the compiler does significant
-optimizations. To be sure of always seeing accurate values, turn off
-all optimization when compiling.
-
+++ /dev/null
-This is Info file ./gdb.info, produced by Makeinfo version 1.68 from
-the input file gdb.texinfo.
-
-START-INFO-DIR-ENTRY
-* Gdb: (gdb). The GNU debugger.
-END-INFO-DIR-ENTRY
- This file documents the GNU debugger GDB.
-
- This is the Seventh Edition, February 1999, of `Debugging with GDB:
-the GNU Source-Level Debugger' for GDB Version 4.18.
-
- Copyright (C) 1988-1999 Free Software Foundation, Inc.
-
- Permission is granted to make and distribute verbatim copies of this
-manual provided the copyright notice and this permission notice are
-preserved on all copies.
-
- Permission is granted to copy and distribute modified versions of
-this manual under the conditions for verbatim copying, provided also
-that the entire resulting derived work is distributed under the terms
-of a permission notice identical to this one.
-
- Permission is granted to copy and distribute translations of this
-manual into another language, under the above conditions for modified
-versions.
-
-\1f
-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 <RET>. 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
- <RET>
- <RET>
- ...
-
-\1f
-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..
-
-\1f
-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 <RET> 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.
-
-\1f
-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 <RET> 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 <RET> 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.
-
-\1f
-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 <t in hi2.c>
-
- *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.
-
- `hp'
- Decode based on the HP ANSI C++ (`aCC') encoding algorithm.
-
- `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.
-
- If you omit STYLE, you will see a list of possible 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.
-
-\1f
-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 <RET>.
-
- 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 <RET> to repeat `show values N' has exactly the same effect
-as `show values +'.
-
-\1f
-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 <RET>.
-
- 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.
-
-\1f
-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..
-
-\1f
-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.
-
-\1f
-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
-
-\1f
-File: gdb.info, Node: Setting, Next: Show, Prev: Languages, 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
-
-\1f
-File: gdb.info, Node: Filenames, Next: Manually, Prev: Setting, 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.
-
-`.c'
- C source file
-
-`.C'
-`.cc'
-`.cp'
-`.cpp'
-`.cxx'
-`.c++'
- C++ source file
-
-`.f'
-`.F'
- Fortran source file
-
-`.ch'
-`.c186'
-`.c286'
- CHILL source file.
-
-`.mod'
- Modula-2 source file
-
-`.s'
-`.S'
- Assembler source file. This actually behaves almost like C, but
- GDB does not skip over function prologues when stepping.
-
- In addition, you may set the language associated with a filename
-extension. *Note Displaying the language: Show.
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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.
-
- In unusual circumstances, you may have source files with extensions
-not in the standard list. You can then set the extension associated
-with a language explicitly:
-
-`set extension-language .EXT LANGUAGE'
- Set source files with extension .EXT to be assumed to be in the
- source language LANGUAGE.
-
-`info extensions'
- List all the filename extensions and the associated languages.
-
-\1f
-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
-
-\1f
-File: gdb.info, Node: Type Checking, Next: Range Checking, Prev: Checks, 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.
-
-\1f
-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.
-
-\1f
-File: gdb.info, Node: Support, Prev: Checks, Up: Languages
-
-Supported languages
-===================
-
- GDB supports C, C++, Fortran, Chill, assembly, 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
-
-\1f
-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 C++
-compiler and GDB. Therefore, to debug your C++ code effectively, you
-must compile your C++ programs with a supported C++ compiler, such as
-GNU `g++', or the HP ANSI C++ compiler (`aCC').
-
- For best results when using GNU C++, 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:: GDB features for C++
-
+++ /dev/null
-This is Info file ./gdb.info, produced by Makeinfo version 1.68 from
-the input file gdb.texinfo.
-
-START-INFO-DIR-ENTRY
-* Gdb: (gdb). The GNU debugger.
-END-INFO-DIR-ENTRY
- This file documents the GNU debugger GDB.
-
- This is the Seventh Edition, February 1999, of `Debugging with GDB:
-the GNU Source-Level Debugger' for GDB Version 4.18.
-
- Copyright (C) 1988-1999 Free Software Foundation, Inc.
-
- Permission is granted to make and distribute verbatim copies of this
-manual provided the copyright notice and this permission notice are
-preserved on all copies.
-
- Permission is granted to copy and distribute modified versions of
-this manual under the conditions for verbatim copying, provided also
-that the entire resulting derived work is distributed under the terms
-of a permission notice identical to this one.
-
- Permission is granted to copy and distribute translations of this
-manual into another language, under the above conditions for modified
-versions.
-
-\1f
-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.
-
-* Menu:
-
-* C Constants::
-
-\1f
-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.
-
-* Menu:
-
-* Cplus expressions::
-* C Defaults::
-
-* C Checks::
-
-* Debugging C::
-
-\1f
-File: gdb.info, Node: Cplus expressions, Next: C Defaults, Prev: C Constants, Up: C
-
-C++ expressions
-...............
-
- GDB expression handling can interpret most C++ expressions.
-
- *Warning:* GDB can only debug C++ code if you use the proper
- compiler. Typically, C++ debugging depends on the use of
- additional debugging information in the symbol table, and thus
- requires special support. 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.).
-
-\1f
-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', etc, 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.
-
-\1f
-File: gdb.info, Node: C Checks, Next: Debugging C, Prev: C Defaults, Up: C Constants
-
-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.
-
-\1f
-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.
-
-* Menu:
-
-* Debugging C plus plus::
-
-\1f
-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 throw'
-`catch catch'
- Debug C++ exception handling using these commands. *Note Setting
- catchpoints: Set Catchpoints.
-
-`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.
-
-\1f
-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
-
-\1f
-File: gdb.info, Node: M2 Operators, Next: Built-In Func/Proc, Prev: Modula-2, 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.
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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').
-
-\1f
-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
-
-\1f
-File: gdb.info, Node: Assignment, Next: Jumping, Prev: Altering, 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.
-
-\1f
-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.
- It is common practice to use the `tbreak' command in conjunction
- with `jump'. *Note Setting breakpoints: Set Breaks.
-
- 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.
-
-\1f
-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 <RET> 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.
-
-\1f
-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.
-
-\1f
-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.
-
- For the A29K, a user-controlled variable `call_scratch_address',
-specifies the location of a scratch area to be used when GDB calls a
-function in the target. This is necessary because the usual method of
-putting the scratch area on the stack does not work in systems that
-have separate instruction and data spaces.
-
-\1f
-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.
-
-\1f
-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
-
+++ /dev/null
-This is Info file ./gdb.info, produced by Makeinfo version 1.68 from
-the input file gdb.texinfo.
-
-START-INFO-DIR-ENTRY
-* Gdb: (gdb). The GNU debugger.
-END-INFO-DIR-ENTRY
- This file documents the GNU debugger GDB.
-
- This is the Seventh Edition, February 1999, of `Debugging with GDB:
-the GNU Source-Level Debugger' for GDB Version 4.18.
-
- Copyright (C) 1988-1999 Free Software Foundation, Inc.
-
- Permission is granted to make and distribute verbatim copies of this
-manual provided the copyright notice and this permission notice are
-preserved on all copies.
-
- Permission is granted to copy and distribute modified versions of
-this manual under the conditions for verbatim copying, provided also
-that the entire resulting derived work is distributed under the terms
-of a permission notice identical to this one.
-
- Permission is granted to copy and distribute translations of this
-manual into another language, under the above conditions for modified
-versions.
-
-\1f
-File: gdb.info, Node: Files, Next: Symbol Errors, Prev: GDB Files, 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 <RET> 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.
-
- For most kinds of object files, with the exception of old SVR3
- systems using COFF, 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. Note that "stabs-in-COFF"
- still does the two-stage strategy, since the debug info is actually
- in stabs format.
-
-`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.).
-
-`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 <RET> 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 HP-UX, 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.
-
-\1f
-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.
-
-\1f
-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
-
-* Byte Order:: Choosing target byte order
-* Remote:: Remote debugging
-
-\1f
-File: gdb.info, Node: Active Targets, Next: Target Commands, Prev: Targets, 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.).
-
-\1f
-File: gdb.info, Node: Target Commands, Next: Byte Order, 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 <RET> 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'
- GDB uses 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.
-
- The following targets are all CPU-specific, and only available for
-specific configurations.
-
-`target abug DEV'
- ABug ROM monitor for M68K.
-
-`target adapt DEV'
- Adapt monitor for A29K.
-
-`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 array DEV'
- Array Tech LSI33K RAID controller board.
-
-`target bug DEV'
- BUG monitor, running on a MVME187 (m88k) board.
-
-`target cpu32bug DEV'
- CPU32BUG monitor, running on a CPU32 (M68K) board.
-
-`target dbug DEV'
- dBUG ROM monitor for Motorola ColdFire.
-
-`target ddb DEV'
- NEC's DDB monitor for Mips Vr4300.
-
-`target dink32 DEV'
- DINK32 ROM monitor for PowerPC.
-
-`target e7000 DEV'
- E7000 emulator for Hitachi H8 and SH.
-
-`target es1800 DEV'
- ES-1800 emulator for M68K.
-
-`target est DEV'
- EST-300 ICE monitor, running on a CPU32 (M68K) board.
-
-`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 lsi DEV'
- LSI ROM monitor for Mips.
-
-`target m32r DEV'
- Mitsubishi M32R/D ROM monitor.
-
-`target mips DEV'
- IDT/SIM ROM monitor for Mips.
-
-`target mon960 DEV'
- MON960 monitor for Intel i960.
-
-`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 nrom DEV'
- NetROM ROM emulator. This target only supports downloading.
-
-`target op50n DEV'
- OP50N monitor, running on an OKI HPPA board.
-
-`target pmon DEV'
- PMON ROM monitor for Mips.
-
-`target ppcbug DEV'
-
-`target ppcbug1 DEV'
- PPCBUG ROM monitor for PowerPC.
-
-`target r3900 DEV'
- Densan DVE-R3900 ROM monitor for Toshiba R3900 Mips.
-
-`target rdi DEV'
- ARM Angel monitor, via RDI library interface.
-
-`target rdp DEV'
- ARM Demon monitor.
-
-`target rom68k DEV'
- ROM 68K monitor, running on an M68K IDP board.
-
-`target rombug DEV'
- ROMBUG ROM monitor for OS/9000.
-
-`target sds DEV'
- SDS monitor, running on a PowerPC board (such as Motorola's ADS).
-
-`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.
-
-`target sh3 DEV'
-
-`target sh3e DEV'
- Hitachi SH-3 and SH-3E target systems.
-
-`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 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 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 w89k DEV'
- W89K monitor, running on a Winbond HPPA board.
-
- Different targets are available on different configurations of GDB;
-your configuration may have more or fewer targets.
-
- Many remote targets require you to download the executable's code
-once you've successfully established a connection.
-
-`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 <RET> again after using it.
-
-\1f
-File: gdb.info, Node: Byte Order, Next: Remote, Prev: Target Commands, Up: Targets
-
-Choosing target byte order
-==========================
-
- Some types of processors, such as the MIPS, PowerPC, and Hitachi SH,
-offer the ability to run either big-endian or little-endian byte
-orders. Usually the executable or symbol will include a bit to
-designate the endian-ness, and you will not need to worry about which
-to use. However, you may still find it useful to adjust GDB's idea of
-processor endian-ness manually.
-
-`set endian big'
- Instruct GDB to assume the target is big-endian.
-
-`set endian little'
- Instruct GDB to assume the target is little-endian.
-
-`set endian auto'
- Instruct GDB to use the byte order associated with the executable.
-
-`show endian'
- Display GDB's current idea of the target byte order.
-
- Note that these commands merely adjust interpretation of symbolic
-data on the host, and that they have absolutely no effect on the target
-system.
-
-\1f
-File: gdb.info, Node: Remote, Prev: Byte Order, 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
-
-\1f
-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
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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 <C-C>), 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.
-
-\1f
-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.
-
- GDB now implements a write-through cache for registers and 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.
-
-\1f
-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.
-
-\1f
-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'.
-
-\1f
-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
-
-\1f
-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.).
-
+++ /dev/null
-This is Info file ./gdb.info, produced by Makeinfo version 1.68 from
-the input file gdb.texinfo.
-
-START-INFO-DIR-ENTRY
-* Gdb: (gdb). The GNU debugger.
-END-INFO-DIR-ENTRY
- This file documents the GNU debugger GDB.
-
- This is the Seventh Edition, February 1999, of `Debugging with GDB:
-the GNU Source-Level Debugger' for GDB Version 4.18.
-
- Copyright (C) 1988-1999 Free Software Foundation, Inc.
-
- Permission is granted to make and distribute verbatim copies of this
-manual provided the copyright notice and this permission notice are
-preserved on all copies.
-
- Permission is granted to copy and distribute modified versions of
-this manual under the conditions for verbatim copying, provided also
-that the entire resulting derived work is distributed under the terms
-of a permission notice identical to this one.
-
- Permission is granted to copy and distribute translations of this
-manual into another language, under the above conditions for modified
-versions.
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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
-
-\1f
-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.
-
-\1f
-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'.
-
-\1f
-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.
-
-\1f
-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:
- `<RET>~.' (Return, followed by tilde and period) or `<RET>~<C-d>'
- (Return, followed by tilde and control-D).
-
-\1f
-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
-
-\1f
-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.
-
-\1f
-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.)
-
-\1f
-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.
-
-\1f
-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
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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)
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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'.
-
-\1f
-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 {No Value For
- "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.
-
-\1f
-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,
-simulators are available for ARM, D10V, D30V, FR30, H8/300, H8/500,
-i960, M32R, MIPS, MN10200, MN10300, PowerPC, SH, Sparc, V850, W65, and
-Z8000.
-
- 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 ARGS'
- Debug programs on a simulated CPU. If the simulator supports setup
- options, specify them via ARGS.
-
-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'), the Z8000 simulator 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.
-
-\1f
-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
-
-\1f
-File: gdb.info, Node: Prompt, Next: Editing, Prev: Controlling GDB, 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'
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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 <RET> 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.
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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
-
-\1f
-File: gdb.info, Node: Define, Next: Hooks, Prev: Sequences, 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.
-
-\1f
-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.
-
-\1f
-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' on Unix, or `gdb.ini'
-on DOS/Windows. 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.
-
-\1f
-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.
-
+++ /dev/null
-This is Info file ./gdb.info, produced by Makeinfo version 1.68 from
-the input file gdb.texinfo.
-
-START-INFO-DIR-ENTRY
-* Gdb: (gdb). The GNU debugger.
-END-INFO-DIR-ENTRY
- This file documents the GNU debugger GDB.
-
- This is the Seventh Edition, February 1999, of `Debugging with GDB:
-the GNU Source-Level Debugger' for GDB Version 4.18.
-
- Copyright (C) 1988-1999 Free Software Foundation, Inc.
-
- Permission is granted to make and distribute verbatim copies of this
-manual provided the copyright notice and this permission notice are
-preserved on all copies.
-
- Permission is granted to copy and distribute modified versions of
-this manual under the conditions for verbatim copying, provided also
-that the entire resulting derived work is distributed under the terms
-of a permission notice identical to this one.
-
- Permission is granted to copy and distribute translations of this
-manual into another language, under the above conditions for modified
-versions.
-
-\1f
-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.
-
-\1f
-File: gdb.info, Node: GDB Bugs, Next: Formatting Documentation, 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
-
-\1f
-File: gdb.info, Node: Bug Criteria, Next: Bug Reporting, Prev: GDB Bugs, 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.
- (Note that if you're cross debugging, the problem may also be
- somewhere in the connection to the target.)
-
- * 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.
-
-\1f
-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
-this addresses:
-
- bug-gdb@prep.ai.mit.edu
-
- *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. It may be that the bug has been reported previously, but
-neither you nor we can know that unless your bug report is complete and
-self-contained.
-
- 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.
-
- 1. What compiler (and its version) was used to compile GDB--e.g.
- "gcc-2.8.1".
-
- * What compiler (and its version) was used to compile the program
- you are debugging--e.g. "gcc-2.8.1", or "HP92453-01 A.10.32.03 HP
- C Compiler". For GCC, you can say `gcc --version' to get this
- information; for other compilers, see the documentation for those
- compilers.
-
- * 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.
-
- 2. 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.
-
-\1f
-File: gdb.info, Node: Command Line Editing, Next: Using History Interactively, Prev: Formatting Documentation, Up: Top
-
-Command Line Editing
-********************
-
- This chapter describes the basic features of the GNU 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.
-* Bindable Readline Commands:: A description of most of the Readline commands
- available for binding
-* Readline vi Mode:: A short description of how to make Readline
- behave like the vi editor.
-
-\1f
-File: gdb.info, Node: Introduction and Notation, Next: Readline Interaction, Up: Command Line Editing
-
-Introduction to Line Editing
-============================
-
- The following paragraphs describe the notation used to represent
-keystrokes.
-
- The text <C-k> is read as `Control-K' and describes the character
-produced when the <k> key is pressed while the Control key is depressed.
-
- The text <M-k> is read as `Meta-K' and describes the character
-produced when the meta key (if you have one) is depressed, and the <k>
-key is pressed. If you do not have a meta key, the identical keystroke
-can be generated by typing <ESC> first, and then typing <k>. Either
-process is known as "metafying" the <k> key.
-
- The text <M-C-k> is read as `Meta-Control-k' and describes the
-character produced by "metafying" <C-k>.
-
- In addition, several keys have their own names. Specifically,
-<DEL>, <ESC>, <LFD>, <SPC>, <RET>, and <TAB> all stand for themselves
-when seen in this text, or in an init file (*note Readline Init
-File::.).
-
-\1f
-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 <RETURN>. You do not have to be at the end
-of the line to press <RETURN>; 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.
-* Searching:: Searching through previous lines.
-
-\1f
-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 your
-erase character 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 <C-b> to move the cursor to the
-left, and then correct your mistake. Afterwards, you can move the
-cursor to the right with <C-f>.
-
- When you add text in the middle of a line, you will notice that
-characters to the right of the cursor are `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 are `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.
-
-<C-b>
- Move back one character.
-
-<C-f>
- Move forward one character.
-
-<DEL>
- Delete the character to the left of the cursor.
-
-<C-d>
- Delete the character underneath the cursor.
-
-Printing characters
- Insert the character into the line at the cursor.
-
-<C-_>
- Undo the last editing command. You can undo all the way back to an
- empty line.
-
-\1f
-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 <C-b>,
-<C-f>, <C-d>, and <DEL>. Here are some commands for moving more rapidly
-about the line.
-
-<C-a>
- Move to the start of the line.
-
-<C-e>
- Move to the end of the line.
-
-<M-f>
- Move forward a word, where a word is composed of letters and
- digits.
-
-<M-b>
- Move backward a word.
-
-<C-l>
- Clear the screen, reprinting the current line at the top.
-
- Notice how <C-f> moves forward a character, while <M-f> moves
-forward a word. It is a loose convention that control keystrokes
-operate on characters while meta keystrokes operate on words.
-
-\1f
-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" (re-inserting) 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.
-
- 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 all. 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.
-
- Here is the list of commands for killing text.
-
-<C-k>
- Kill the text from the current cursor position to the end of the
- line.
-
-<M-d>
- Kill from the cursor to the end of the current word, or if between
- words, to the end of the next word.
-
-<M-DEL>
- Kill from the cursor the start of the previous word, or if between
- words, to the start of the previous word.
-
-<C-w>
- Kill from the cursor to the previous whitespace. This is
- different than <M-DEL> because the word boundaries differ.
-
- Here is how to "yank" the text back into the line. Yanking means to
-copy the most-recently-killed text from the kill buffer.
-
-<C-y>
- Yank the most recently killed text back into the buffer at the
- cursor.
-
-<M-y>
- Rotate the kill-ring, and yank the new top. You can only do this
- if the prior command is <C-y> or <M-y>.
-
-\1f
-File: gdb.info, Node: Readline Arguments, Next: Searching, 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 `M-- C-k'.
-
- The general way to pass numeric arguments to a command is to type
-meta digits before the command. If the first `digit' typed 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 <C-d> command an argument of 10, you could type `M-1 0 C-d'.
-
-\1f
-File: gdb.info, Node: Searching, Prev: Readline Arguments, Up: Readline Interaction
-
-Searching for Commands in the History
--------------------------------------
-
- Readline provides commands for searching through the command history
-for lines containing a specified string. There are two search modes:
-INCREMENTAL and NON-INCREMENTAL.
-
- Incremental searches begin before the user has finished typing the
-search string. As each character of the search string is typed,
-Readline displays the next entry from the history matching the string
-typed so far. An incremental search requires only as many characters
-as needed to find the desired history entry. The <ESC> character is
-used to terminate an incremental search. <C-j> will also terminate the
-search. <C-g> will abort an incremental search and restore the
-original line. When the search is terminated, the history entry
-containing the search string becomes the current line. To find other
-matching entries in the history list, type <C-s> or <C-r> as
-appropriate. This will search backward or forward in the history for
-the next entry matching the search string typed so far. Any other key
-sequence bound to a Readline command will terminate the search and
-execute that command. For instance, a <RET> will terminate the search
-and accept the line, thereby executing the command from the history
-list.
-
- Non-incremental searches read the entire search string before
-starting to search for matching history lines. The search string may be
-typed by the user or be part of the contents of the current line.
-
-\1f
-File: gdb.info, Node: Readline Init File, Next: Bindable Readline Commands, Prev: Readline Interaction, Up: Command Line Editing
-
-Readline Init File
-==================
-
- Although the Readline library comes with a set of `emacs'-like
-keybindings installed by default, it is possible to use a different set
-of keybindings. Any user can customize programs that use Readline by
-putting commands in an "inputrc" file in his home directory. The name
-of this file is taken from the value of the environment variable
-`INPUTRC'. If that variable is unset, the default is `~/.inputrc'.
-
- When a program which uses the Readline library starts up, the init
-file is read, and the key bindings are set.
-
- In addition, the `C-x C-r' command re-reads this init file, thus
-incorporating any changes that you might have made to it.
-
-* Menu:
-
-* Readline Init File Syntax:: Syntax for the commands in the inputrc file.
-
-* Conditional Init Constructs:: Conditional key bindings in the inputrc file.
-
-* Sample Init File:: An example inputrc file.
-
-\1f
-File: gdb.info, Node: Readline Init File Syntax, Next: Conditional Init Constructs, Up: Readline Init File
-
-Readline Init File Syntax
--------------------------
-
- There are only a few basic constructs allowed in the Readline init
-file. Blank lines are ignored. Lines beginning with a `#' are
-comments. Lines beginning with a `$' indicate conditional constructs
-(*note Conditional Init Constructs::.). Other lines denote variable
-settings and key bindings.
-
-Variable Settings
- You can modify the run-time behavior of Readline by altering the
- values of variables in Readline using the `set' command within the
- init file. Here is how to change from the default Emacs-like key
- binding to use `vi' line editing commands:
-
- set editing-mode vi
-
- A great deal of run-time behavior is changeable with the following
- variables.
-
- `bell-style'
- Controls what happens when Readline wants to ring the
- terminal bell. If set to `none', Readline never rings the
- bell. If set to `visible', Readline uses a visible bell if
- one is available. If set to `audible' (the default),
- Readline attempts to ring the terminal's bell.
-
- `comment-begin'
- The string to insert at the beginning of the line when the
- `insert-comment' command is executed. The default value is
- `"#"'.
-
- `completion-ignore-case'
- If set to `on', Readline performs filename matching and
- completion in a case-insensitive fashion. The default value
- is `off'.
-
- `completion-query-items'
- The number of possible completions that determines when the
- user is asked whether he wants to see the list of
- possibilities. If the number of possible completions is
- greater than this value, Readline will ask the user whether
- or not he wishes to view them; otherwise, they are simply
- listed. The default limit is `100'.
-
- `convert-meta'
- If set to `on', Readline will convert characters with the
- eighth bit set to an ASCII key sequence by stripping the
- eighth bit and prepending an <ESC> character, converting them
- to a meta-prefixed key sequence. The default value is `on'.
-
- `disable-completion'
- If set to `On', Readline will inhibit word completion.
- Completion characters will be inserted into the line as if
- they had been mapped to `self-insert'. The default is `off'.
-
- `editing-mode'
- The `editing-mode' variable controls which default set of key
- bindings is used. By default, Readline starts up in Emacs
- editing mode, where the keystrokes are most similar to Emacs.
- This variable can be set to either `emacs' or `vi'.
-
- `enable-keypad'
- When set to `on', Readline will try to enable the application
- keypad when it is called. Some systems need this to enable
- the arrow keys. The default is `off'.
-
- `expand-tilde'
- If set to `on', tilde expansion is performed when Readline
- attempts word completion. The default is `off'.
-
- `horizontal-scroll-mode'
- This variable can be set to either `on' or `off'. Setting it
- to `on' means that the text of the lines being edited will
- scroll horizontally on a single screen line when they are
- longer than the width of the screen, instead of wrapping onto
- a new screen line. By default, this variable is set to `off'.
-
- `keymap'
- Sets Readline's idea of the current keymap for key binding
- commands. Acceptable `keymap' names are `emacs',
- `emacs-standard', `emacs-meta', `emacs-ctlx', `vi',
- `vi-command', and `vi-insert'. `vi' is equivalent to
- `vi-command'; `emacs' is equivalent to `emacs-standard'. The
- default value is `emacs'. The value of the `editing-mode'
- variable also affects the default keymap.
-
- `mark-directories'
- If set to `on', completed directory names have a slash
- appended. The default is `on'.
-
- `mark-modified-lines'
- This variable, when set to `on', causes Readline to display an
- asterisk (`*') at the start of history lines which have been
- modified. This variable is `off' by default.
-
- `input-meta'
- If set to `on', Readline will enable eight-bit input (it will
- not strip the eighth bit from the characters it reads),
- regardless of what the terminal claims it can support. The
- default value is `off'. The name `meta-flag' is a synonym
- for this variable.
-
- `output-meta'
- If set to `on', Readline will display characters with the
- eighth bit set directly rather than as a meta-prefixed escape
- sequence. The default is `off'.
-
- `print-completions-horizontally'
- If set to `on', Readline will display completions with matches
- sorted horizontally in alphabetical order, rather than down
- the screen. The default is `off'.
-
- `show-all-if-ambiguous'
- This alters the default behavior of the completion functions.
- If set to `on', words which have more than one possible
- completion cause the matches to be listed immediately instead
- of ringing the bell. The default value is `off'.
-
- `visible-stats'
- If set to `on', a character denoting a file's type is
- appended to the filename when listing possible completions.
- The default is `off'.
-
-Key Bindings
- The syntax for controlling key bindings in the init file is
- simple. First you have to know the name of the command that you
- want to change. The following sections contain tables of the
- command name, the default keybinding, if any, 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 init 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, <C-u> is bound to the function
- `universal-argument', and <C-o> 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, by placing the key
- sequence in double quotes. Some GNU Emacs style key escapes
- can be used, as in the following example, but the special
- character names are not recognized.
-
- "\C-u": universal-argument
- "\C-x\C-r": re-read-init-file
- "\e[11~": "Function Key 1"
-
- In the above example, <C-u> is bound to the function
- `universal-argument' (just as it was in the first example),
- `<C-x> <C-r>' is bound to the function `re-read-init-file',
- and `<ESC> <[> <1> <1> <~>' is bound to insert the text
- `Function Key 1'.
-
- The following GNU Emacs style escape sequences are available when
- specifying key sequences:
-
- `\C-'
- control prefix
-
- `\M-'
- meta prefix
-
- `\e'
- an escape character
-
- `\\'
- backslash
-
- `\"'
- <">
-
- `\''
- <'>
-
- In addition to the GNU Emacs style escape sequences, a second set
- of backslash escapes is available:
-
- `\a'
- alert (bell)
-
- `\b'
- backspace
-
- `\d'
- delete
-
- `\f'
- form feed
-
- `\n'
- newline
-
- `\r'
- carriage return
-
- `\t'
- horizontal tab
-
- `\v'
- vertical tab
-
- `\NNN'
- the character whose ASCII code is the octal value NNN (one to
- three digits)
-
- `\xNNN'
- the character whose ASCII code is the hexadecimal value NNN
- (one to three digits)
-
- When entering the text of a macro, single or double quotes must be
- used to indicate a macro definition. Unquoted text is assumed to
- be a function name. In the macro body, the backslash escapes
- described above are expanded. Backslash will quote any other
- character in the macro text, including `"' and `''. For example,
- the following binding will make `C-x \' insert a single `\' into
- the line:
- "\C-x\\": "\\"
-
-\1f
-File: gdb.info, Node: Conditional Init Constructs, Next: Sample Init File, Prev: Readline Init File Syntax, Up: Readline Init File
-
-Conditional Init Constructs
----------------------------
-
- Readline implements a facility similar in spirit to the conditional
-compilation features of the C preprocessor which allows key bindings
-and variable settings to be performed as the result of tests. There
-are four parser directives used.
-
-`$if'
- The `$if' construct allows bindings to be made based on the
- editing mode, the terminal being used, or the application using
- Readline. The text of the test extends to the end of the line; no
- characters are required to isolate it.
-
- `mode'
- The `mode=' form of the `$if' directive is used to test
- whether Readline is in `emacs' or `vi' mode. This may be
- used in conjunction with the `set keymap' command, for
- instance, to set bindings in the `emacs-standard' and
- `emacs-ctlx' keymaps only if Readline is starting out in
- `emacs' mode.
-
- `term'
- The `term=' form may be used to include terminal-specific key
- bindings, perhaps to bind the key sequences output by the
- terminal's function keys. The word on the right side of the
- `=' is tested against both the full name of the terminal and
- the portion of the terminal name before the first `-'. This
- allows `sun' to match both `sun' and `sun-cmd', for instance.
-
- `application'
- The APPLICATION construct is used to include
- application-specific settings. Each program using the
- Readline library sets the APPLICATION NAME, and you can test
- for it. This could be used to bind key sequences to
- functions useful for a specific program. For instance, the
- following command adds a key sequence that quotes the current
- or previous word in Bash:
- $if Bash
- # Quote the current or previous word
- "\C-xq": "\eb\"\ef\""
- $endif
-
-`$endif'
- This command, as seen in the previous example, terminates an `$if'
- command.
-
-`$else'
- Commands in this branch of the `$if' directive are executed if the
- test fails.
-
-`$include'
- This directive takes a single filename as an argument and reads
- commands and bindings from that file.
- $include /etc/inputrc
-
-\1f
-File: gdb.info, Node: Sample Init File, Prev: Conditional Init Constructs, Up: Readline Init File
-
-Sample Init File
-----------------
-
- Here is an example of an inputrc file. This illustrates key
-binding, variable assignment, and conditional syntax.
-
-
- # This file controls the behaviour of line input editing for
- # programs that use the Gnu Readline library. Existing programs
- # include FTP, Bash, and Gdb.
- #
- # You can re-read the inputrc file with C-x C-r.
- # Lines beginning with '#' are comments.
- #
- # First, include any systemwide bindings and variable assignments from
- # /etc/Inputrc
- $include /etc/Inputrc
-
- #
- # Set various bindings for emacs mode.
-
- set editing-mode emacs
-
- $if mode=emacs
-
- Meta-Control-h: backward-kill-word Text after the function name is ignored
-
- #
- # Arrow keys in keypad mode
- #
- #"\M-OD": backward-char
- #"\M-OC": forward-char
- #"\M-OA": previous-history
- #"\M-OB": next-history
- #
- # Arrow keys in ANSI mode
- #
- "\M-[D": backward-char
- "\M-[C": forward-char
- "\M-[A": previous-history
- "\M-[B": next-history
- #
- # Arrow keys in 8 bit keypad mode
- #
- #"\M-\C-OD": backward-char
- #"\M-\C-OC": forward-char
- #"\M-\C-OA": previous-history
- #"\M-\C-OB": next-history
- #
- # Arrow keys in 8 bit ANSI mode
- #
- #"\M-\C-[D": backward-char
- #"\M-\C-[C": forward-char
- #"\M-\C-[A": previous-history
- #"\M-\C-[B": next-history
-
- C-q: quoted-insert
-
- $endif
-
- # An old-style binding. This happens to be the default.
- TAB: complete
-
- # Macros that are convenient for shell interaction
- $if Bash
- # edit the path
- "\C-xp": "PATH=${PATH}\e\C-e\C-a\ef\C-f"
- # prepare to type a quoted word -- insert open and close double quotes
- # and move to just after the open quote
- "\C-x\"": "\"\"\C-b"
- # insert a backslash (testing backslash escapes in sequences and macros)
- "\C-x\\": "\\"
- # Quote the current or previous word
- "\C-xq": "\eb\"\ef\""
- # Add a binding to refresh the line, which is unbound
- "\C-xr": redraw-current-line
- # Edit variable on current line.
- "\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y="
- $endif
-
- # use a visible bell if one is available
- set bell-style visible
-
- # don't strip characters to 7 bits when reading
- set input-meta on
-
- # allow iso-latin1 characters to be inserted rather than converted to
- # prefix-meta sequences
- set convert-meta off
-
- # display characters with the eighth bit set directly rather than
- # as meta-prefixed characters
- set output-meta on
-
- # if there are more than 150 possible completions for a word, ask the
- # user if he wants to see all of them
- set completion-query-items 150
-
- # For FTP
- $if Ftp
- "\C-xg": "get \M-?"
- "\C-xt": "put \M-?"
- "\M-.": yank-last-arg
- $endif
-
-\1f
-File: gdb.info, Node: Bindable Readline Commands, Next: Readline vi Mode, Prev: Readline Init File, Up: Command Line Editing
-
-Bindable Readline Commands
-==========================
-
-* 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.
-* Keyboard Macros:: Saving and re-executing typed characters
-* Miscellaneous Commands:: Other miscellaneous commands.
-
- This section describes Readline commands that may be bound to key
-sequences.
-
-\1f
-File: gdb.info, Node: Commands For Moving, Next: Commands For History, Up: Bindable Readline Commands
-
-Commands For Moving
--------------------
-
-`beginning-of-line (C-a)'
- Move to the start of the current line.
-
-`end-of-line (C-e)'
- Move to the end of the line.
-
-`forward-char (C-f)'
- Move forward a character.
-
-`backward-char (C-b)'
- Move back a character.
-
-`forward-word (M-f)'
- Move forward to the end of the next word. Words are composed of
- letters and digits.
-
-`backward-word (M-b)'
- Move back to the start of this, or the previous, word. Words are
- composed of letters and digits.
-
-`clear-screen (C-l)'
- Clear the screen and redraw the current line, leaving the current
- line at the top of the screen.
-
-`redraw-current-line ()'
- Refresh the current line. By default, this is unbound.
-
-\1f
-File: gdb.info, Node: Commands For History, Next: Commands For Text, Prev: Commands For Moving, Up: Bindable Readline Commands
-
-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 (C-p)'
- Move `up' through the history list.
-
-`next-history (C-n)'
- Move `down' through the history list.
-
-`beginning-of-history (M-<)'
- Move to the first line in the history.
-
-`end-of-history (M->)'
- Move to the end of the input history, i.e., the line currently
- being entered.
-
-`reverse-search-history (C-r)'
- Search backward starting at the current line and moving `up'
- through the history as necessary. This is an incremental search.
-
-`forward-search-history (C-s)'
- Search forward starting at the current line and moving `down'
- through the the history as necessary. This is an incremental
- search.
-
-`non-incremental-reverse-search-history (M-p)'
- Search backward starting at the current line and moving `up'
- through the history as necessary using a non-incremental search
- for a string supplied by the user.
-
-`non-incremental-forward-search-history (M-n)'
- Search forward starting at the current line and moving `down'
- through the the history as necessary using a non-incremental search
- for a string supplied by the user.
-
-`history-search-forward ()'
- Search forward through the history for the string of characters
- between the start of the current line and the current cursor
- position (the POINT). This is a non-incremental search. By
- default, this command is unbound.
-
-`history-search-backward ()'
- Search backward through the history for the string of characters
- between the start of the current line and the point. This is a
- non-incremental search. By default, this command is unbound.
-
-`yank-nth-arg (M-C-y)'
- Insert the first argument to the previous command (usually the
- second word on the previous line). With an argument N, insert the
- Nth word from the previous command (the words in the previous
- command begin with word 0). A negative argument inserts the Nth
- word from the end of the previous command.
-
-`yank-last-arg (M-., M-_)'
- Insert last argument to the previous command (the last word of the
- previous history entry). With an argument, behave exactly like
- `yank-nth-arg'. Successive calls to `yank-last-arg' move back
- through the history list, inserting the last argument of each line
- in turn.
-
-\1f
-File: gdb.info, Node: Commands For Text, Next: Commands For Killing, Prev: Commands For History, Up: Bindable Readline Commands
-
-Commands For Changing Text
---------------------------
-
-`delete-char (C-d)'
- Delete the character under the cursor. If the cursor is at the
- beginning of the line, there are no characters in the line, and
- the last character typed was not bound to `delete-char', then
- return `EOF'.
-
-`backward-delete-char (Rubout)'
- Delete the character behind the cursor. A numeric argument means
- to kill the characters instead of deleting them.
-
-`quoted-insert (C-q, C-v)'
- Add the next character typed to the line verbatim. This is how to
- insert key sequences like <C-q>, for example.
-
-`tab-insert (M-TAB)'
- Insert a tab character.
-
-`self-insert (a, b, A, 1, !, ...)'
- Insert yourself.
-
-`transpose-chars (C-t)'
- Drag the character before the cursor forward over the character at
- the cursor, moving the cursor forward as well. If the insertion
- point is at the end of the line, then this transposes the last two
- characters of the line. Negative arguments don't work.
-
-`transpose-words (M-t)'
- Drag the word behind the cursor past the word in front of the
- cursor moving the cursor over that word as well.
-
-`upcase-word (M-u)'
- Uppercase the current (or following) word. With a negative
- argument, uppercase the previous word, but do not move the cursor.
-
-`downcase-word (M-l)'
- Lowercase the current (or following) word. With a negative
- argument, lowercase the previous word, but do not move the cursor.
-
-`capitalize-word (M-c)'
- Capitalize the current (or following) word. With a negative
- argument, capitalize the previous word, but do not move the cursor.
-
-\1f
-File: gdb.info, Node: Commands For Killing, Next: Numeric Arguments, Prev: Commands For Text, Up: Bindable Readline Commands
-
-Killing And Yanking
--------------------
-
-`kill-line (C-k)'
- Kill the text from the current cursor position to the end of the
- line.
-
-`backward-kill-line (C-x Rubout)'
- Kill backward to the beginning of the line.
-
-`unix-line-discard (C-u)'
- Kill backward from the cursor to the beginning of the current line.
- The killed text is saved on the kill-ring.
-
-`kill-whole-line ()'
- Kill all characters on the current line, no matter where the
- cursor is. By default, this is unbound.
-
-`kill-word (M-d)'
- Kill from the cursor to the end of the current word, or if between
- words, to the end of the next word. Word boundaries are the same
- as `forward-word'.
-
-`backward-kill-word (M-DEL)'
- Kill the word behind the cursor. Word boundaries are the same as
- `backward-word'.
-
-`unix-word-rubout (C-w)'
- Kill the word behind the cursor, using white space as a word
- boundary. The killed text is saved on the kill-ring.
-
-`delete-horizontal-space ()'
- Delete all spaces and tabs around point. By default, this is
- unbound.
-
-`kill-region ()'
- Kill the text between the point and the *mark* (saved cursor
- position). This text is referred to as the REGION. By default,
- this command is unbound.
-
-`copy-region-as-kill ()'
- Copy the text in the region to the kill buffer, so it can be yanked
- right away. By default, this command is unbound.
-
-`copy-backward-word ()'
- Copy the word before point to the kill buffer. The word
- boundaries are the same as `backward-word'. By default, this
- command is unbound.
-
-`copy-forward-word ()'
- Copy the word following point to the kill buffer. The word
- boundaries are the same as `forward-word'. By default, this
- command is unbound.
-
-`yank (C-y)'
- Yank the top of the kill ring into the buffer at the current
- cursor position.
-
-`yank-pop (M-y)'
- Rotate the kill-ring, and yank the new top. You can only do this
- if the prior command is yank or yank-pop.
-
-\1f
-File: gdb.info, Node: Numeric Arguments, Next: Commands For Completion, Prev: Commands For Killing, Up: Bindable Readline Commands
-
-Specifying Numeric Arguments
-----------------------------
-
-`digit-argument (M-0, M-1, ... M--)'
- Add this digit to the argument already accumulating, or start a new
- argument. <M-> starts a negative argument.
-
-`universal-argument ()'
- This is another way to specify an argument. If this command is
- followed by one or more digits, optionally with a leading minus
- sign, those digits define the argument. If the command is
- followed by digits, executing `universal-argument' again ends the
- numeric argument, but is otherwise ignored. As a special case, if
- this command is immediately followed by a character that is
- neither a digit or minus sign, the argument count for the next
- command is multiplied by four. The argument count is initially
- one, so executing this function the first time makes the argument
- count four, a second time makes the argument count sixteen, and so
- on. By default, this is not bound to a key.
-
+++ /dev/null
-This is Info file ./gdb.info, produced by Makeinfo version 1.68 from
-the input file gdb.texinfo.
-
-START-INFO-DIR-ENTRY
-* Gdb: (gdb). The GNU debugger.
-END-INFO-DIR-ENTRY
- This file documents the GNU debugger GDB.
-
- This is the Seventh Edition, February 1999, of `Debugging with GDB:
-the GNU Source-Level Debugger' for GDB Version 4.18.
-
- Copyright (C) 1988-1999 Free Software Foundation, Inc.
-
- Permission is granted to make and distribute verbatim copies of this
-manual provided the copyright notice and this permission notice are
-preserved on all copies.
-
- Permission is granted to copy and distribute modified versions of
-this manual under the conditions for verbatim copying, provided also
-that the entire resulting derived work is distributed under the terms
-of a permission notice identical to this one.
-
- Permission is granted to copy and distribute translations of this
-manual into another language, under the above conditions for modified
-versions.
-
-\1f
-File: gdb.info, Node: Commands For Completion, Next: Keyboard Macros, Prev: Numeric Arguments, Up: Bindable Readline Commands
-
-Letting Readline Type For You
------------------------------
-
-`complete (TAB)'
- Attempt to do completion on the text before the cursor. This is
- application-specific. 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,
- and so on.
-
-`possible-completions (M-?)'
- List the possible completions of the text before the cursor.
-
-`insert-completions (M-*)'
- Insert all completions of the text before point that would have
- been generated by `possible-completions'.
-
-`menu-complete ()'
- Similar to `complete', but replaces the word to be completed with
- a single match from the list of possible completions. Repeated
- execution of `menu-complete' steps through the list of possible
- completions, inserting each match in turn. At the end of the list
- of completions, the bell is rung and the original text is restored.
- An argument of N moves N positions forward in the list of matches;
- a negative argument may be used to move backward through the list.
- This command is intended to be bound to `TAB', but is unbound by
- default.
-
-\1f
-File: gdb.info, Node: Keyboard Macros, Next: Miscellaneous Commands, Prev: Commands For Completion, Up: Bindable Readline Commands
-
-Keyboard Macros
----------------
-
-`start-kbd-macro (C-x ()'
- Begin saving the characters typed into the current keyboard macro.
-
-`end-kbd-macro (C-x ))'
- Stop saving the characters typed into the current keyboard macro
- and save the definition.
-
-`call-last-kbd-macro (C-x e)'
- Re-execute the last keyboard macro defined, by making the
- characters in the macro appear as if typed at the keyboard.
-
-\1f
-File: gdb.info, Node: Miscellaneous Commands, Prev: Keyboard Macros, Up: Bindable Readline Commands
-
-Some Miscellaneous Commands
----------------------------
-
-`re-read-init-file (C-x C-r)'
- Read in the contents of the inputrc file, and incorporate any
- bindings or variable assignments found there.
-
-`abort (C-g)'
- Abort the current editing command and ring the terminal's bell
- (subject to the setting of `bell-style').
-
-`do-uppercase-version (M-a, M-b, M-X, ...)'
- If the metafied character X is lowercase, run the command that is
- bound to the corresponding uppercase character.
-
-`prefix-meta (ESC)'
- Make the next character typed be metafied. This is for keyboards
- without a meta key. Typing `ESC f' is equivalent to typing `M-f'.
-
-`undo (C-_, C-x C-u)'
- Incremental undo, separately remembered for each line.
-
-`revert-line (M-r)'
- Undo all changes made to this line. This is like executing the
- `undo' command enough times to get back to the beginning.
-
-`tilde-expand (M-~)'
- Perform tilde expansion on the current word.
-
-`set-mark (C-@)'
- Set the mark to the current point. If a numeric argument is
- supplied, the mark is set to that position.
-
-`exchange-point-and-mark (C-x C-x)'
- Swap the point with the mark. The current cursor position is set
- to the saved position, and the old cursor position is saved as the
- mark.
-
-`character-search (C-])'
- A character is read and point is moved to the next occurrence of
- that character. A negative count searches for previous
- occurrences.
-
-`character-search-backward (M-C-])'
- A character is read and point is moved to the previous occurrence
- of that character. A negative count searches for subsequent
- occurrences.
-
-`insert-comment (M-#)'
- The value of the `comment-begin' variable is inserted at the
- beginning of the current line, and the line is accepted as if a
- newline had been typed.
-
-`dump-functions ()'
- Print all of the functions and their key bindings to the Readline
- output stream. If a numeric argument is supplied, the output is
- formatted in such a way that it can be made part of an INPUTRC
- file. This command is unbound by default.
-
-`dump-variables ()'
- Print all of the settable variables and their values to the
- Readline output stream. If a numeric argument is supplied, the
- output is formatted in such a way that it can be made part of an
- INPUTRC file. This command is unbound by default.
-
-`dump-macros ()'
- Print all of the Readline key sequences bound to macros and the
- strings they ouput. If a numeric argument is supplied, the output
- is formatted in such a way that it can be made part of an INPUTRC
- file. This command is unbound by default.
-
-\1f
-File: gdb.info, Node: Readline vi Mode, Prev: Bindable Readline Commands, Up: Command Line Editing
-
-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.
-The Readline `vi' mode behaves as specified in the POSIX 1003.2
-standard.
-
- In order to switch interactively between `emacs' and `vi' editing
-modes, use the command M-C-j (toggle-editing-mode). The Readline
-default is `emacs' mode.
-
- When you enter a line in `vi' mode, you are already placed in
-`insertion' mode, as if you had typed an `i'. Pressing <ESC> switches
-you into `command' mode, where you can edit the text of the line with
-the standard `vi' movement keys, move to previous history lines with
-`k' and subsequent lines with `j', and so forth.
-
-\1f
-File: gdb.info, Node: Using History Interactively, Next: Installing GDB, 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.
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-File: gdb.info, Node: Formatting Documentation, Next: Command Line Editing, Prev: GDB Bugs, 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-4.18/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-4.18', in the case of version 4.18), 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-4.18/gdb') and type:
-
- make gdb.dvi
-
- Then give `gdb.dvi' to your DVI printing program.
-
- ---------- Footnotes ----------
-
- (1) In `gdb-4.18/gdb/refcard.ps' of the version 4.18 release.
-
-\1f
-File: gdb.info, Node: Installing GDB, Next: Index, Prev: Using History Interactively, 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 4.18 distribution is in the `gdb-4.18'
-directory. That directory contains:
-
-`gdb-4.18/configure (and supporting files)'
- script for configuring GDB and all its supporting libraries
-
-`gdb-4.18/gdb'
- the source specific to GDB itself
-
-`gdb-4.18/bfd'
- source for the Binary File Descriptor library
-
-`gdb-4.18/include'
- GNU include files
-
-`gdb-4.18/libiberty'
- source for the `-liberty' free software library
-
-`gdb-4.18/opcodes'
- source for the library of opcode tables and disassemblers
-
-`gdb-4.18/readline'
- source for the GNU command-line interface
-
-`gdb-4.18/glob'
- source for the GNU filename pattern-matching subroutine
-
-`gdb-4.18/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-4.18' 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-4.18
- ./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-4.18'
-source directory for version 4.18, `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 4.18, type the following to configure only
-the `bfd' subdirectory:
-
- cd gdb-4.18/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
-
-\1f
-File: gdb.info, Node: Separate Objdir, Next: Config Names, Prev: Installing GDB, 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 4.18, you can build GDB in a separate
-directory for a Sun 4 like this:
-
- cd gdb-4.18
- mkdir ../gdb-sun4
- cd ../gdb-sun4
- ../gdb-4.18/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-4.18' (or in a separate configured directory configured with
-`--srcdir=DIRNAME/gdb-4.18'), 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.
-
-\1f
-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 i386-linux
- i386-pc-linux-gnu
- % sh config.sub alpha-linux
- alpha-unknown-linux-gnu
- % sh config.sub hp9k700
- hppa1.1-hp-hpux
- % sh config.sub sun4
- sparc-sun-sunos4.1.1
- % sh config.sub sun3
- m68k-sun-sunos4.1.1
- % sh config.sub i986v
- Invalid configuration `i986v': machine `i986v' not recognized
-
-`config.sub' is also distributed in the GDB source directory
-(`gdb-4.18', for version 4.18).
-
-\1f
-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]
- [--exec-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'.
-
-`--exec-prefix=DIR'
- Configure the source to install programs 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.
-
-`--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.
-
- There are many other options available as well, but they are
-generally needed for special purposes only.
-
OSDN Git Service
