This file documents the GNU debugger GDB.

Copyright (C) 1988, 1989, 1990, 1991 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 section entitled ``GNU General Public License'' is included exactly as in the original, and provided 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, except that the section entitled ``GNU General Public License'' may be included in a translation approved by the Free Software Foundation instead of in the original English.

This file describes version 4.0 of GDB, the GNU symbolic debugger.

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.

GDB can be used to debug programs written in C and C++.  Pascal support is being implemented, and Fortran support will be added when a GNU Fortran compiler is ready.

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 can't take these freedoms away from anyone else.

For full details, see Copying.

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; let's be evenhanded) have been unfairly omitted from this list, we would like to add your names!

So that they may not regard their long labor as thankless, we particularly thank those who shepherded GDB through major releases: John Gilmore (release 4.0); Jim Kingdon (releases 3.9, 3.5, 3.4, 3.3); and Randy Smith (releases 3.2, 3.1, 3.0).  As major maintainer of GDB for some period, each contributed significantly to the structure, stability, and capabilities of the entire debugger.

Richard Stallman, assisted at various times by Pete 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.0 uses the BFD subroutine library to examine multiple object-file formats; BFD was a joint project of V. Gumby 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.

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. Keith Packard contributed NS32K support.  Doug Rabson contributed Acorn Risc Machine support.  Chris Smith contributed Convex support (and Fortran debugging).  Jonathan Stone contributed Pyramid support. Michael Tiemann contributed SPARC support.  Tim Tucker contributed support for the Gould NP1 and Gould Powernode.  Pace Willison contributed Intel 386 support.  Jay Vosburgh contributed Symmetry support.

Rich Schaefer 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 and Wind River Systems contributed remote debugging modules for their products.

Brian Fox is the author of the readline libraries providing command-line editing and command history.

New Features since GDB version 3.5
**********************************

Targets
     Using the new command target, you can select at runtime whether you are debugging local files, local processes, standalone systems over a serial port, realtime systems over a TCP/IP connection, etc. Internally, GDB now uses a function vector to mediate access to different targets; if you need to add your own support for a remote protocol, this makes it much easier.

Watchpoints
     GDB now sports watchpoints as well as breakpoints.  You can use a watchpoint to stop execution whenever the value of an expression changes, without having to predict a particular place in your program where this may happen.

Object Code Formats
     GDB uses a new scheme called the Binary File Descriptor (BFD) Library to permit it to switch dynamically, without reconfiguration or recompilation, between different object-file formats.  Formats currently supported are COFF, a.out, and the Intel 960 b.out; files may be read as .o's, archive libraries, or core dumps.  BFD is available as a subroutine library so that other programs may take advantage of it, and the other GNU binary utilities are being converted to use it.

Configuration
     Compile-time configuration (to select a particular architecture and operating system) is much easier.  The script configure now allows you to configure GDB as either a native debugger or a cross-debugger.

Interaction
     The user interface to GDB's control variables has been simplified and consolidated in two commands, set and show.  Output lines are now broken at readable places, rather than overflowing onto the next line.  You can suppress output of machine-level addresses, displaying only source language information.

Source Language
     GDB now has limited support for C++ exception handling: GDB can break when an exception is raised, before the stack is peeled back to the exception handler's context.

Command Rationalization
     Many GDB commands have been renamed to make them easier to remember and use.  In particular, the subcommands of info and show/set are grouped to make the former refer to the state of your program, and the latter refer to the state of GDB itself. See Renamed Commands, for details on what commands were renamed.

Ports
     GDB has been ported to the following new architectures: AT&T 3b1, Acorn RISC machine, HP300 running HPUX, big- and little-endian MIPS machines, Motorola 88k, Sun 386i, and Sun 3 running SunOS 4.  In addition, the following are supported as targets only: AMD 29k, Intel 960, and Wind River's VxWorks.

Shared Libraries
     GDB 4.0 supports SunOS shared libraries.

Work in Progress
     Kernel debugging for BSD and Mach systems; Tahoe and HPPA architecture support.

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 these 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's definition in another stop working.  In the following short m4 session, we define a macro foo which expands to 0000; we then use the m4 builtin 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 /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's use GDB to try to see what's going on.

     $ gdb m4
     Reading symbol data from m4...done.
     (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 then tell GDB to use a narrower display width than usual, so that examples will fit in this manual.

     (gdb) set width 70

Let's see how the m4 builtin changequote works. Having looked at the source, we know the relevant subroutine is m4_changequote, so we set a breakpoint there with GDB's 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//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 summary display showing the subroutine where m4 is now suspended (and its arguments) is called a stack frame display.  We can use the backtrace command (which can also be spelled bt), to see where we are in the stack: it 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

Let's 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; let's examine the variables lquote and rquote to see if they are in fact the new left and right quotes we specified.  We can 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. Let's 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's 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.  Let's try setting them to better values. We can use the p command for this, since it'll 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

Let's see if that fixes 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'll let 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

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

Starting GDB
============

GDB is invoked with the shell command gdb.  Once started, it reads commands from the terminal until you tell it to exit.

You can run gdb with no arguments or options; but the most usual way to start GDB is with one argument or two, specifying an executable program as the argument:

     gdb program

You can also start with both an executable program and a core file specified:

     gdb program core

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

     gdb -help

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

Choosing Files
--------------

As shown above, any arguments other than options specify an executable file and core file; that is, the first argument encountered with no associated option flag is equivalent to a -se option, and the second, if any, is equivalent to a -c option.  Many options have both long and short forms; both are shown here.  The long forms are also recognized 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.

-command=FILE
-x FILE
     Execute GDB commands from file FILE.  See Command Files.

-directory=DIRECTORY
-d DIRECTORY
     Add DIRECTORY to the path to search for source files.

Choosing Modes
--------------

-nx
-n
     Do not execute commands from any .gdbinit initialization files. Normally, the commands in these files are executed after all the command options and arguments have been processed.  See Command Files.

-quiet
-q
     ``Quiet''.  Do not print the introductory and copyright messages.  These messages are also suppressed in batch mode, or if an executable file name is specified on the GDB command line.

-batch
     Run in batch mode.  Exit with status 0 after processing all the command files specified with -x (and .gdbinit, if not inhibited). 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
     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 the 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.