Subversion Repositories or1k

This is ./gdb.info, produced by makeinfo version 4.0 from gdb.texinfo.

INFO-DIR-SECTION Programming & development tools.
START-INFO-DIR-ENTRY
* Gdb: (gdb).                     The GNU debugger.
END-INFO-DIR-ENTRY

   This file documents the GNU debugger GDB.

   This is the Eighth Edition, March 2000, of `Debugging with GDB: the
GNU Source-Level Debugger' for GDB Version 5.0.

   Copyright (C) 1988-2000 Free Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the entire resulting derived work is distributed under the terms
of a permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions.


File: gdb.info,  Node: Top,  Next: Summary,  Prev: (dir),  Up: (dir)

Debugging with GDB
******************

   This file describes GDB, the GNU symbolic debugger.

   This is the Eighth Edition, March 2000, for GDB Version 5.0.

   Copyright (C) 1988-2000 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
* Configurations::              Configuration-specific information
* Controlling GDB::             Controlling GDB
* Sequences::                   Canned sequences of commands
* Emacs::                       Using GDB under GNU Emacs
* Annotations::                 GDB's annotation interface.
* GDB/MI::                      GDB's Machine Interface.

* 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


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 and C++.  For more
information, see *Note Supported languages: Support.  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.  For information on Chill, see
*Note Chill::.

   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
may be necessary to refer to some variables with a trailing underscore.

* Menu:

* Free Software::               Freely redistributable software
* Contributors::                Contributors to GDB


File: gdb.info,  Node: Free Software,  Next: Contributors,  Up: Summary

Free software
=============

   GDB is "free software", protected by the GNU General Public License
(GPL).  The GPL gives you the freedom to copy or adapt a licensed
program--but every person getting a copy also gets with it the freedom
to modify that copy (which means that they must get access to the
source code), and the freedom to distribute further copies.  Typical
software companies use copyrights to limit your freedoms; the Free
Software Foundation uses the GPL to preserve these freedoms.

   Fundamentally, the General Public License is a license which says
that you have these freedoms and that you cannot take these freedoms
away from anyone else.


File: gdb.info,  Node: Contributors,  Prev: Free Software,  Up: Summary

Contributors to GDB
===================

   Richard Stallman was the original author of GDB, and of many other
GNU programs.  Many others have contributed to its development.  This
section attempts to credit major contributors.  One of the virtues of
free software is that everyone is free to contribute to it; with
regret, we cannot actually acknowledge everyone here.  The file
`ChangeLog' in the GDB distribution approximates a blow-by-blow account.

   Changes much prior to version 2.0 are lost in the mists of time.

     _Plea:_ Additions to this section are particularly welcome.  If you
     or your friends (or enemies, to be evenhanded) have been unfairly
     omitted from this list, we would like to add your names!

   So that they may not regard their many labors as thankless, we
particularly thank those who shepherded GDB through major releases:
Andrew Cagney (release 5.0); 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, Kevin
Buettner, Edith Epstein, Chris Faylor, Fred Fish, Martin Hunt, Jim
Ingham, John Gilmore, Stu Grossman, Kung Hsu, Jim Kingdon, John Metzler,
Fernando Nasser, Geoffrey Noer, Dawn Perchik, Rich Pixley, Zdenek
Radouch, Keith Seitz, Stan Shebs, David Taylor, and Elena Zannoni.  In
addition, Dave Brolley, Ian Carmichael, Steve Chamberlain, Nick Clifton,
JT Conklin, Stan Cox, DJ Delorie, Ulrich Drepper, Frank Eigler, Doug
Evans, Sean Fagan, David Henkel-Wallace, Richard Henderson, Jeff
Holcomb, Jeff Law, Jim Lemke, Tom Lord, Bob Manson, Michael Meissner,
Jason Merrill, Catherine Moore, Drew Moseley, Ken Raeburn, Gavin
Romig-Koch, Rob Savoye, Jamie Smith, Mike Stump, Ian Taylor, Angela
Thomas, Michael Tiemann, Tom Tromey, Ron Unrau, Jim Wilson, and David
Zuhn have made contributions both large and small.


File: gdb.info,  Node: Sample Session,  Next: Invocation,  Prev: Summary,  Up: Top

A Sample GDB Session
********************

   You can use this manual at your leisure to read all about GDB.
However, a handful of commands are enough to get started using the
debugger.  This chapter illustrates those commands.

   One of the preliminary versions of GNU `m4' (a generic macro
processor) exhibits the following bug: sometimes, when we change its
quote strings from the default, the commands used to capture one macro
definition within another stop working.  In the following short `m4'
session, we define a macro `foo' which expands to `0000'; we then use
the `m4' built-in `defn' to define `bar' as the same thing.  However,
when we change the open quote string to `<QUOTE>' and the close quote
string to `<UNQUOTE>', the same procedure fails to define a new synonym
`baz':

     $ cd gnu/m4
     $ ./m4
     define(foo,0000)
     
     foo
     0000
     define(bar,defn(`foo'))
     
     bar
     0000
     changequote(<QUOTE>,<UNQUOTE>)
     
     define(baz,defn(<QUOTE>foo<UNQUOTE>))
     baz
     C-d
     m4: End of input: 0: fatal error: EOF in string

Let us use GDB to try to see what is going on.

     $ gdb m4
     GDB is free software and you are welcome to distribute copies
      of it under certain conditions; type "show copying" to see
      the conditions.
     There is absolutely no warranty for GDB; type "show warranty"
      for details.
     
     GDB 5.0, Copyright 1999 Free Software Foundation, Inc...
     (gdb)

GDB reads only enough symbol data to know where to find the rest when
needed; as a result, the first prompt comes up very quickly.  We now
tell GDB to use a narrower display width than usual, so that examples
fit in this manual.

     (gdb) set width 70

We need to see how the `m4' built-in `changequote' works.  Having
looked at the source, we know the relevant subroutine is
`m4_changequote', so we set a breakpoint there with the GDB `break'
command.

     (gdb) break m4_changequote
     Breakpoint 1 at 0x62f4: file builtin.c, line 879.

Using the `run' command, we start `m4' running under GDB control; as
long as control does not reach the `m4_changequote' subroutine, the
program runs as usual:

     (gdb) run
     Starting program: /work/Editorial/gdb/gnu/m4/m4
     define(foo,0000)
     
     foo
     0000

To trigger the breakpoint, we call `changequote'.  GDB suspends
execution of `m4', displaying information about the context where it
stops.

     changequote(<QUOTE>,<UNQUOTE>)
     
     Breakpoint 1, m4_changequote (argc=3, argv=0x33c70)
         at builtin.c:879
     879         if (bad_argc(TOKEN_DATA_TEXT(argv[0]),argc,1,3))

Now we use the command `n' (`next') to advance execution to the next
line of the current function.

     (gdb) n
     882         set_quotes((argc >= 2) ? TOKEN_DATA_TEXT(argv[1])\
      : nil,

`set_quotes' looks like a promising subroutine.  We can go into it by
using the command `s' (`step') instead of `next'.  `step' goes to the
next line to be executed in _any_ subroutine, so it steps into
`set_quotes'.

     (gdb) s
     set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>")
         at input.c:530
     530         if (lquote != def_lquote)

The display that shows the subroutine where `m4' is now suspended (and
its arguments) is called a stack frame display.  It shows a summary of
the stack.  We can use the `backtrace' command (which can also be
spelled `bt'), to see where we are in the stack as a whole: the
`backtrace' command displays a stack frame for each active subroutine.

     (gdb) bt
     #0  set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>")
         at input.c:530
     #1  0x6344 in m4_changequote (argc=3, argv=0x33c70)
         at builtin.c:882
     #2  0x8174 in expand_macro (sym=0x33320) at macro.c:242
     #3  0x7a88 in expand_token (obs=0x0, t=209696, td=0xf7fffa30)
         at macro.c:71
     #4  0x79dc in expand_input () at macro.c:40
     #5  0x2930 in main (argc=0, argv=0xf7fffb20) at m4.c:195

We step through a few more lines to see what happens.  The first two
times, we can use `s'; the next two times we use `n' to avoid falling
into the `xstrdup' subroutine.

     (gdb) s
     0x3b5c  532         if (rquote != def_rquote)
     (gdb) s
     0x3b80  535         lquote = (lq == nil || *lq == '\0') ?  \
     def_lquote : xstrdup(lq);
     (gdb) n
     536         rquote = (rq == nil || *rq == '\0') ? def_rquote\
      : xstrdup(rq);
     (gdb) n
     538         len_lquote = strlen(rquote);

The last line displayed looks a little odd; we can examine the variables
`lquote' and `rquote' to see if they are in fact the new left and right
quotes we specified.  We use the command `p' (`print') to see their
values.

     (gdb) p lquote
     $1 = 0x35d40 "<QUOTE>"
     (gdb) p rquote
     $2 = 0x35d50 "<UNQUOTE>"

`lquote' and `rquote' are indeed the new left and right quotes.  To
look at some context, we can display ten lines of source surrounding
the current line with the `l' (`list') command.

     (gdb) l
     533             xfree(rquote);
     534
     535         lquote = (lq == nil || *lq == '\0') ? def_lquote\
      : xstrdup (lq);
     536         rquote = (rq == nil || *rq == '\0') ? def_rquote\
      : xstrdup (rq);
     537
     538         len_lquote = strlen(rquote);
     539         len_rquote = strlen(lquote);
     540     }
     541
     542     void

Let us step past the two lines that set `len_lquote' and `len_rquote',
and then examine the values of those variables.

     (gdb) n
     539         len_rquote = strlen(lquote);
     (gdb) n
     540     }
     (gdb) p len_lquote
     $3 = 9
     (gdb) p len_rquote
     $4 = 7

That certainly looks wrong, assuming `len_lquote' and `len_rquote' are
meant to be the lengths of `lquote' and `rquote' respectively.  We can
set them to better values using the `p' command, since it can print the
value of any expression--and that expression can include subroutine
calls and assignments.

     (gdb) p len_lquote=strlen(lquote)
     $5 = 7
     (gdb) p len_rquote=strlen(rquote)
     $6 = 9

Is that enough to fix the problem of using the new quotes with the `m4'
built-in `defn'?  We can allow `m4' to continue executing with the `c'
(`continue') command, and then try the example that caused trouble
initially:

     (gdb) c
     Continuing.
     
     define(baz,defn(<QUOTE>foo<UNQUOTE>))
     
     baz
     0000

Success!  The new quotes now work just as well as the default ones.  The
problem seems to have been just the two typos defining the wrong
lengths.  We allow `m4' exit by giving it an EOF as input:

     C-d
     Program exited normally.

The message `Program exited normally.' is from GDB; it indicates `m4'
has finished executing.  We can end our GDB session with the GDB `quit'
command.

     (gdb) quit


File: gdb.info,  Node: Invocation,  Next: Commands,  Prev: Sample Session,  Up: Top

Getting In and Out of GDB
*************************

   This chapter discusses how to start GDB, and how to get out of it.
The essentials are:
   * type `gdb' to start GDB.

   * type `quit' or `C-d' to exit.

* Menu:

* Invoking GDB::                How to start GDB
* Quitting GDB::                How to quit GDB
* Shell Commands::              How to use shell commands inside GDB


File: gdb.info,  Node: Invoking GDB,  Next: Quitting GDB,  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.  GDB will warn you if it is
unable to attach or to read core dumps.

   You can run `gdb' without printing the front material, which
describes GDB's non-warranty, by specifying `-silent':

     gdb -silent

You can further control how GDB starts up by using command-line
options.  GDB itself can remind you of the options available.

Type

     gdb -help

to display all available options and briefly describe their use (`gdb
-h' is a shorter equivalent).

   All options and command line arguments you give are processed in
sequential order.  The order makes a difference when the `-x' option is
used.

* Menu:

* File Options::                Choosing files
* Mode Options::                Choosing modes


File: gdb.info,  Node: File Options,  Next: Mode Options,  Up: Invoking GDB

Choosing files
--------------

   When GDB starts, it reads any arguments other than options as
specifying an executable file and core file (or process ID).  This is
the same as if the arguments were specified by the `-se' and `-c'
options respectively.  (GDB reads the first argument that does not have
an associated option flag as equivalent to the `-se' option followed by
that argument; and the second argument that does not have an associated
option flag, if any, as equivalent to the `-c' option followed by that
argument.)

   If GDB has not been configured to included core file support, such
as for most embedded targets, then it will complain about a second
argument and ignore it.

   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 `/tmp/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.

   You typically combine the `-mapped' and `-readnow' options in order
to build a `.syms' file that contains complete symbol information.
(*Note Commands to specify files: Files, for information on `.syms'
files.)  A simple GDB invocation to do nothing but build a `.syms' file
for future use is:

     gdb -batch -nx -mapped -readnow programname


File: gdb.info,  Node: Mode Options,  Prev: File Options,  Up: Invoking GDB

Choosing modes
--------------

   You can run GDB in various alternative modes--for example, in batch
mode or quiet mode.

`-nx'
`-n'
     Do not execute commands found in any initialization files (normally
     called `.gdbinit', or `gdb.ini' on PCs).  Normally, GDB executes
     the commands in these files after all the command options and
     arguments have been processed.  *Note Command files: Command Files.

`-quiet'
`-silent'
`-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.

`-nowindows'
`-nw'
     "No windows".  If GDB comes with a graphical user interface (GUI)
     built in, then this option tells GDB to only use the command-line
     interface.  If no GUI is available, this option has no effect.

`-windows'
`-w'
     If GDB includes a GUI, then this option requires it to be used if
     possible.

`-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.

`-epoch'
     The Epoch Emacs-GDB interface sets this option when it runs GDB as
     a subprocess.  It tells GDB to modify its print routines so as to
     allow Epoch to display values of expressions in a separate window.

`-annotate LEVEL'
     This option sets the "annotation level" inside GDB.  Its effect is
     identical to using `set annotate LEVEL' (*note Annotations::).
     Annotation level controls how much information does GDB print
     together with its prompt, values of expressions, source lines, and
     other types of output.  Level 0 is the normal, level 1 is for use
     when GDB is run as a subprocess of GNU Emacs, level 2 is the
     maximum annotation suitable for programs that control GDB.

`-async'
     Use the asynchronous event loop for the command-line interface.
     GDB processes all events, such as user keyboard input, via a
     special event loop.  This allows GDB to accept and process user
     commands in parallel with the debugged process being run(1), so
     you don't need to wait for control to return to GDB before you
     type the next command.  (_Note:_ as of version 5.0, the target
     side of the asynchronous operation is not yet in place, so
     `-async' does not work fully yet.)

     When the standard input is connected to a terminal device, GDB
     uses the asynchronous event loop by default, unless disabled by the
     `-noasync' option.

`-noasync'
     Disable the asynchronous event loop for the command-line interface.

`-baud BPS'
`-b BPS'
     Set the line speed (baud rate or bits per second) of any serial
     interface used by GDB for remote debugging.

`-tty DEVICE'
`-t DEVICE'
     Run using DEVICE for your program's standard input and output.

`-interpreter INTERP'
     Use the interpreter INTERP for interface with the controlling
     program or device.  This option is meant to be set by programs
     which communicate with GDB using it as a back end.  For example,
     `--interpreter=mi' causes GDB to use the "gdbmi interface" (*note
     The GDB/MI Interface: GDB/MI.).

`-write'
     Open the executable and core files for both reading and writing.
     This is equivalent to the `set write on' command inside GDB (*note
     Patching::).

`-statistics'
     This option causes GDB to print statistics about time and memory
     usage after it completes each command and returns to the prompt.

`-version'
     This option causes GDB to print its version number and no-warranty
     blurb, and exit.

   ---------- Footnotes ----------

   (1) GDB built with DJGPP tools for MS-DOS/MS-Windows supports this
mode of operation, but the event loop is suspended when the debuggee
runs.


File: gdb.info,  Node: Quitting GDB,  Next: Shell Commands,  Prev: Invoking GDB,  Up: Invocation

Quitting GDB
============

`quit [EXPRESSION]'
`q'
     To exit GDB, use the `quit' command (abbreviated `q'), or type an
     end-of-file character (usually `C-d').  If you do not supply
     EXPRESSION, GDB will terminate normally; otherwise it will
     terminate using the result of EXPRESSION as the error code.

   An interrupt (often `C-c') does not exit from GDB, but rather
terminates the action of any GDB command that is in progress and
returns to GDB command level.  It is safe to type the interrupt
character at any time because GDB does not allow it to take effect
until a time when it is safe.

   If you have been using GDB to control an attached process or device,
you can release it with the `detach' command (*note Debugging an
already-running process: Attach.).


File: gdb.info,  Node: Shell Commands,  Prev: Quitting GDB,  Up: Invocation

Shell commands
==============

   If you need to execute occasional shell commands during your
debugging session, there is no need to leave or suspend GDB; you can
just use the `shell' command.

`shell COMMAND STRING'
     Invoke a standard shell to execute COMMAND STRING.  If it exists,
     the environment variable `SHELL' determines which shell to run.
     Otherwise GDB uses the default shell (`/bin/sh' on Unix systems,
     `COMMAND.COM' on MS-DOS, etc.).

   The utility `make' is often needed in development environments.  You
do not have to use the `shell' command for this purpose in GDB:

`make MAKE-ARGS'
     Execute the `make' program with the specified arguments.  This is
     equivalent to `shell make MAKE-ARGS'.


File: gdb.info,  Node: Commands,  Next: Running,  Prev: Invocation,  Up: Top

GDB Commands
************

   You can abbreviate a GDB command to the first few letters of the
command name, if that abbreviation is unambiguous; and you can repeat
certain GDB commands by typing just <RET>.  You can also use the <TAB>
key to get GDB to fill out the rest of a word in a command (or to show
you the alternatives available, if there is more than one possibility).

* Menu:

* Command Syntax::              How to give commands to GDB
* Completion::                  Command completion
* Help::                        How to ask GDB for help


File: gdb.info,  Node: Command Syntax,  Next: Completion,  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 commands do not allow any arguments.

   GDB command names may always be truncated if that abbreviation is
unambiguous.  Other possible command abbreviations are listed in the
documentation for individual commands.  In some cases, even ambiguous
abbreviations are allowed; for example, `s' is specially defined as
equivalent to `step' even though there are other commands whose names
start with `s'.  You can test abbreviations by using them as arguments
to the `help' command.

   A blank line as input to GDB (typing just <RET>) means to repeat the
previous command.  Certain commands (for example, `run') will not
repeat this way; these are commands whose unintentional repetition
might cause trouble and which you are unlikely to want to repeat.

   The `list' and `x' commands, when you repeat them with <RET>,
construct new arguments rather than repeating exactly as typed.  This
permits easy scanning of source or memory.

   GDB can also use <RET> in another way: to partition lengthy output,
in a way similar to the common utility `more' (*note Screen size:
Screen Size.).  Since it is easy to press one <RET> too many in this
situation, GDB disables command repetition after any command that
generates this sort of display.

   Any text from a `#' to the end of the line is a comment; it does
nothing.  This is useful mainly in command files (*note Command files:
Command Files.).


File: gdb.info,  Node: Completion,  Next: Help,  Prev: Command Syntax,  Up: Commands

Command completion
==================

   GDB can fill in the rest of a word in a command for you, if there is
only one possibility; it can also show you what the valid possibilities
are for the next word in a command, at any time.  This works for GDB
commands, GDB subcommands, and the names of symbols in your program.

   Press the <TAB> key whenever you want GDB to fill out the rest of a
word.  If there is only one possibility, GDB fills in the word, and
waits for you to finish the command (or press <RET> to enter it).  For
example, if you type

     (gdb) info bre <TAB>

GDB fills in the rest of the word `breakpoints', since that is the only
`info' subcommand beginning with `bre':

     (gdb) info breakpoints

You can either press <RET> at this point, to run the `info breakpoints'
command, or backspace and enter something else, if `breakpoints' does
not look like the command you expected.  (If you were sure you wanted
`info breakpoints' in the first place, you might as well just type
<RET> immediately after `info bre', to exploit command abbreviations
rather than command completion).

   If there is more than one possibility for the next word when you
press <TAB>, GDB sounds a bell.  You can either supply more characters
and try again, or just press <TAB> a second time; GDB displays all the
possible completions for that word.  For example, you might want to set
a breakpoint on a subroutine whose name begins with `make_', but when
you type `b make_<TAB>' GDB just sounds the bell.  Typing <TAB> again
displays all the function names in your program that begin with those
characters, for example:

     (gdb) b make_ <TAB>
GDB sounds bell; press <TAB> again, to see:
     make_a_section_from_file     make_environ
     make_abs_section             make_function_type
     make_blockvector             make_pointer_type
     make_cleanup                 make_reference_type
     make_command                 make_symbol_completion_list
     (gdb) b make_

After displaying the available possibilities, GDB copies your partial
input (`b make_' in the example) so you can finish the command.

   If you just want to see the list of alternatives in the first place,
you can press `M-?' rather than pressing <TAB> twice. `M-?' means
`<META> ?'.  You can type this either by holding down a key designated
as the <META> shift on your keyboard (if there is one) while typing
`?', or as <ESC> followed by `?'.

   Sometimes the string you need, while logically a "word", may contain
parentheses or other characters that GDB normally excludes from its
notion of a word.  To permit word completion to work in this situation,
you may enclose words in `'' (single quote marks) in GDB commands.

   The most likely situation where you might need this is in typing the
name of a C++ function.  This is because C++ allows function overloading
(multiple definitions of the same function, distinguished by argument
type).  For example, when you want to set a breakpoint you may need to
distinguish whether you mean the version of `name' that takes an `int'
parameter, `name(int)', or the version that takes a `float' parameter,
`name(float)'.  To use the word-completion facilities in this
situation, type a single quote `'' at the beginning of the function
name.  This alerts GDB that it may need to consider more information
than usual when you press <TAB> or `M-?' to request word completion:

     (gdb) b 'bubble( M-?
     bubble(double,double)    bubble(int,int)
     (gdb) b 'bubble(

   In some cases, GDB can tell that completing a name requires using
quotes.  When this happens, GDB inserts the quote for you (while
completing as much as it can) if you do not type the quote in the first
place:

     (gdb) b bub <TAB>
GDB alters your input line to the following, and rings a bell:
     (gdb) b 'bubble(

In general, GDB can tell that a quote is needed (and inserts it) if you
have not yet started typing the argument list when you ask for
completion on an overloaded symbol.

   For more information about overloaded functions, see *Note C++
expressions: C plus plus expressions.  You can use the command `set
overload-resolution off' to disable overload resolution; see *Note GDB
features for C++: Debugging C plus plus.


File: gdb.info,  Node: Help,  Prev: Completion,  Up: Commands

Getting help
============

   You can always ask GDB itself for information on its commands, using
the command `help'.

`help'
`h'
     You can use `help' (abbreviated `h') with no arguments to display
     a short list of named classes of commands:

          (gdb) help
          List of classes of commands:
          
          aliases -- Aliases of other commands
          breakpoints -- Making program stop at certain points
          data -- Examining data
          files -- Specifying and examining files
          internals -- Maintenance commands
          obscure -- Obscure features
          running -- Running the program
          stack -- Examining the stack
          status -- Status inquiries
          support -- Support facilities
          tracepoints -- Tracing of program execution without

          stopping the program
          user-defined -- User-defined commands
          
          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:
          
          info -- Generic command for showing things
           about the program being debugged
          show -- Generic command for showing things
           about the debugger
          
          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.

`apropos ARGS'
     The `apropos ARGS' command searches through all of the GDB
     commands, and their documentation, for the regular expression
     specified in ARGS. It prints out all matches found. For example:

          apropos reload

     results in:

          set symbol-reloading -- Set dynamic symbol table reloading
                                           multiple times in one run
          show symbol-reloading -- Show dynamic symbol table reloading
                                           multiple times in one run

`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:

          if
          ignore
          info
          inspect

     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 need to determine which version of
     GDB you are running; as GDB evolves, new commands are introduced,
     and old ones may wither away.  Also, many system vendors ship
     variant versions of GDB, and there are variant versions of GDB in
     GNU/Linux distributions as well.  The version number is the same
     as the one announced when you start GDB.

`show copying'
     Display information about permission for copying GDB.

`show warranty'
     Display the GNU "NO WARRANTY" statement, or a warranty, if your
     version of GDB comes with one.


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.  If you are doing native debugging, 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

* Threads::                     Debugging programs with multiple threads
* Processes::                   Debugging programs with multiple processes


File: gdb.info,  Node: Compilation,  Next: Starting,  Up: Running

Compiling for debugging
=======================

   In order to debug a program effectively, you need to generate
debugging information when you compile it.  This debugging information
is stored in the object file; it describes the data type of each
variable or function and the correspondence between source line numbers
and addresses in the executable code.

   To request debugging information, specify the `-g' option when you
run the compiler.

   Many C compilers are unable to handle the `-g' and `-O' options
together.  Using those compilers, you cannot generate optimized
executables containing debugging information.

   GCC, the GNU C compiler, supports `-g' with or without `-O', making
it possible to debug optimized code.  We recommend that you _always_
use `-g' whenever you compile a program.  You may think your program is
correct, but there is no sense in pushing your luck.

   When you debug a program compiled with `-g -O', remember that the
optimizer is rearranging your code; the debugger shows you what is
really there.  Do not be too surprised when the execution path does not
exactly match your source file!  An extreme example: if you define a
variable, but never use it, GDB never sees that variable--because the
compiler optimizes it out of existence.

   Some things do not work as well with `-g -O' as with just `-g',
particularly on machines with instruction scheduling.  If in doubt,
recompile with `-g' alone, and if this fixes the problem, please report
it to us as a bug (including a test case!).

   Older versions of the GNU C compiler permitted a variant option
`-gg' for debugging information.  GDB no longer supports this format;
if your GNU C compiler has this option, do not use it.


File: gdb.info,  Node: Starting,  Next: Arguments,  Prev: Compilation,  Up: Running

Starting your program
=====================

`run'
`r'
     Use the `run' command to start your program under GDB.  You must
     first specify the program name (except on VxWorks) with an
     argument to GDB (*note Getting In and Out of GDB: Invocation.), or
     by using the `file' or `exec-file' command (*note Commands to
     specify files: Files.).

   If you are running your program in an execution environment that
supports processes, `run' creates an inferior process and makes that
process run your program.  (In environments without processes, `run'
jumps to the start of your program.)

   The execution of a program is affected by certain information it
receives from its superior.  GDB provides ways to specify this
information, which you must do _before_ starting your program.  (You
can change it after starting your program, but such changes only affect
your program the next time you start it.)  This information may be
divided into four categories:

The _arguments._
     Specify the arguments to give your program as the arguments of the
     `run' command.  If a shell is available on your target, the shell
     is used to pass the arguments, so that you may use normal
     conventions (such as wildcard expansion or variable substitution)
     in describing the arguments.  In Unix systems, you can control
     which shell is used with the `SHELL' environment variable.  *Note
     Your program's arguments: Arguments.

The _environment._
     Your program normally inherits its environment from GDB, but you
     can use the GDB commands `set environment' and `unset environment'
     to change parts of the environment that affect your program.
     *Note Your program's environment: Environment.

The _working directory._
     Your program inherits its working directory from GDB.  You can set
     the GDB working directory with the `cd' command in GDB.  *Note
     Your program's working directory: Working Directory.

The _standard input and output._
     Your program normally uses the same device for standard input and
     standard output as GDB is using.  You can redirect input and output
     in the `run' command line, or you can use the `tty' command to set
     a different device for your program.  *Note Your program's input
     and output: Input/Output.

     _Warning:_ While input and output redirection work, you cannot use
     pipes to pass the output of the program you are debugging to
     another program; if you attempt this, GDB is likely to wind up
     debugging the wrong program.

   When you issue the `run' command, your program begins to execute
immediately.  *Note Stopping and continuing: Stopping, for discussion
of how to arrange for your program to stop.  Once your program has
stopped, you may call functions in your program, using the `print' or
`call' commands.  *Note Examining Data: Data.

   If the modification time of your symbol file has changed since the
last time GDB read its symbols, GDB discards its symbol table, and
reads it again.  When it does this, GDB tries to retain your current
breakpoints.


File: gdb.info,  Node: Arguments,  Next: Environment,  Prev: Starting,  Up: Running

Your program's arguments
========================

   The arguments to your program can be specified by the arguments of
the `run' command.  They are passed to a shell, which expands wildcard
characters and performs redirection of I/O, and thence to your program.
Your `SHELL' environment variable (if it exists) specifies what shell
GDB uses.  If you do not define `SHELL', GDB uses the default shell
(`/bin/sh' on Unix).

   On non-Unix systems, the program is usually invoked directly by GDB,
which emulates I/O redirection via the appropriate system calls, and
the wildcard characters are expanded by the startup code of the
program, not by the shell.

   `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.