Subversion Repositories openrisc_me

\input texinfo      @c -*-texinfo-*-

@c Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998,

@c 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006

@c Free Software Foundation, Inc.

@c

@c %**start of header

@c makeinfo ignores cmds prev to setfilename, so its arg cannot make use

@c of @set vars.  However, you can override filename with makeinfo -o.

@setfilename gdb.info

@c

@include gdb-cfg.texi

@c

@settitle Debugging with @value{GDBN}

@setchapternewpage odd

@c %**end of header

@iftex

@c @smallbook

@c @cropmarks

@end iftex

@finalout

@syncodeindex ky cp

@c readline appendices use @vindex, @findex and @ftable,

@c annotate.texi and gdbmi use @findex.

@syncodeindex vr cp

@syncodeindex fn cp

@c !!set GDB manual's edition---not the same as GDB version!

@c This is updated by GNU Press.

@set EDITION Ninth

@c !!set GDB edit command default editor

@set EDITOR /bin/ex

@c THIS MANUAL REQUIRES TEXINFO 4.0 OR LATER.

@c This is a dir.info fragment to support semi-automated addition of

@c manuals to an info tree.

@dircategory Software development

@direntry

* Gdb: (gdb).                     The GNU debugger.

@end direntry

@ifinfo

This file documents the @sc{gnu} debugger @value{GDBN}.

This is the @value{EDITION} Edition, of @cite{Debugging with

@value{GDBN}: the @sc{gnu} Source-Level Debugger} for @value{GDBN}

Version @value{GDBVN}.

Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998,@*

              1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006@*

              Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document

under the terms of the GNU Free Documentation License, Version 1.1 or

any later version published by the Free Software Foundation; with the

Invariant Sections being ``Free Software'' and ``Free Software Needs

Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,''

and with the Back-Cover Texts as in (a) below.

(a) The FSF's Back-Cover Text is: ``You are free to copy and modify

this GNU Manual.  Buying copies from GNU Press supports the FSF in

developing GNU and promoting software freedom.''

@end ifinfo

@titlepage

@title Debugging with @value{GDBN}

@subtitle The @sc{gnu} Source-Level Debugger

@sp 1

@subtitle @value{EDITION} Edition, for @value{GDBN} version @value{GDBVN}

@author Richard Stallman, Roland Pesch, Stan Shebs, et al.

@page

@tex

{\parskip=0pt

\hfill (Send bugs and comments on @value{GDBN} to bug-gdb\@gnu.org.)\par

\hfill {\it Debugging with @value{GDBN}}\par

\hfill \TeX{}info \texinfoversion\par

}

@end tex

@vskip 0pt plus 1filll

Copyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995,

1996, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2006

Free Software Foundation, Inc.

@sp 2

Published by the Free Software Foundation @*

51 Franklin Street, Fifth Floor,

Boston, MA 02110-1301, USA@*

ISBN 1-882114-77-9 @*

Permission is granted to copy, distribute and/or modify this document

under the terms of the GNU Free Documentation License, Version 1.1 or

any later version published by the Free Software Foundation; with the

Invariant Sections being ``Free Software'' and ``Free Software Needs

Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,''

and with the Back-Cover Texts as in (a) below.

(a) The FSF's Back-Cover Text is: ``You are free to copy and modify

this GNU Manual.  Buying copies from GNU Press supports the FSF in

developing GNU and promoting software freedom.''

@page

This edition of the GDB manual is dedicated to the memory of Fred

Fish.  Fred was a long-standing contributor to GDB and to Free

software in general.  We will miss him.

@end titlepage

@page

@ifnottex

@node Top, Summary, (dir), (dir)

@top Debugging with @value{GDBN}

This file describes @value{GDBN}, the @sc{gnu} symbolic debugger.

This is the @value{EDITION} Edition, for @value{GDBN} Version

@value{GDBVN}.

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

This edition of the GDB manual is dedicated to the memory of Fred

Fish.  Fred was a long-standing contributor to GDB and to Free

software in general.  We will miss him.

@menu

* Summary::                     Summary of @value{GDBN}

* Sample Session::              A sample @value{GDBN} session

* Invocation::                  Getting in and out of @value{GDBN}

* Commands::                    @value{GDBN} commands

* Running::                     Running programs under @value{GDBN}

* Stopping::                    Stopping and continuing

* Stack::                       Examining the stack

* Source::                      Examining source files

* Data::                        Examining data

* Macros::                      Preprocessor Macros

* Tracepoints::                 Debugging remote targets non-intrusively

* Overlays::                    Debugging programs that use overlays

* Languages::                   Using @value{GDBN} with different languages

* Symbols::                     Examining the symbol table

* Altering::                    Altering execution

* GDB Files::                   @value{GDBN} files

* Targets::                     Specifying a debugging target

* Remote Debugging::            Debugging remote programs

* Configurations::              Configuration-specific information

* Controlling GDB::             Controlling @value{GDBN}

* Sequences::                   Canned sequences of commands

* Interpreters::                Command Interpreters

* TUI::                         @value{GDBN} Text User Interface

* Emacs::                       Using @value{GDBN} under @sc{gnu} Emacs

* GDB/MI::                      @value{GDBN}'s Machine Interface.

* Annotations::                 @value{GDBN}'s annotation interface.

* GDB Bugs::                    Reporting bugs in @value{GDBN}

* Command Line Editing::        Command Line Editing

* Using History Interactively:: Using History Interactively

* Formatting Documentation::    How to format and print @value{GDBN} documentation

* Installing GDB::              Installing GDB

* Maintenance Commands::        Maintenance Commands

* Remote Protocol::             GDB Remote Serial Protocol

* Agent Expressions::           The GDB Agent Expression Mechanism

* Target Descriptions::         How targets can describe themselves to

                                @value{GDBN}

* Copying::                     GNU General Public License says

                                how you can copy and share GDB

* GNU Free Documentation License::  The license for this documentation

* Index::                       Index

@end menu

@end ifnottex

@contents

@node Summary

@unnumbered Summary of @value{GDBN}

The purpose of a debugger such as @value{GDBN} 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.

@value{GDBN} can do four main kinds of things (plus other things in support of

these) to help you catch bugs in the act:

@itemize @bullet

@item

Start your program, specifying anything that might affect its behavior.

@item

Make your program stop on specified conditions.

@item

Examine what has happened, when your program has stopped.

@item

Change things in your program, so you can experiment with correcting the

effects of one bug and go on to learn about another.

@end itemize

You can use @value{GDBN} to debug programs written in C and C@t{++}.

For more information, see @ref{Supported Languages,,Supported Languages}.

For more information, see @ref{C,,C and C++}.

@cindex Modula-2

Support for Modula-2 is partial.  For information on Modula-2, see

@ref{Modula-2,,Modula-2}.

@cindex Pascal

Debugging Pascal programs which use sets, subranges, file variables, or

nested functions does not currently work.  @value{GDBN} does not support

entering expressions, printing values, or similar features using Pascal

syntax.

@cindex Fortran

@value{GDBN} can be used to debug programs written in Fortran, although

it may be necessary to refer to some variables with a trailing

underscore.

@value{GDBN} can be used to debug programs written in Objective-C,

using either the Apple/NeXT or the GNU Objective-C runtime.

@menu

* Free Software::               Freely redistributable software

* Contributors::                Contributors to GDB

@end menu

@node Free Software

@unnumberedsec Free Software

@value{GDBN} is @dfn{free software}, protected by the @sc{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.

@unnumberedsec Free Software Needs Free Documentation

The biggest deficiency in the free software community today is not in

the software---it is the lack of good free documentation that we can

include with the free software.  Many of our most important

programs do not come with free reference manuals and free introductory

texts.  Documentation is an essential part of any software package;

when an important free software package does not come with a free

manual and a free tutorial, that is a major gap.  We have many such

gaps today.

Consider Perl, for instance.  The tutorial manuals that people

normally use are non-free.  How did this come about?  Because the

authors of those manuals published them with restrictive terms---no

copying, no modification, source files not available---which exclude

them from the free software world.

That wasn't the first time this sort of thing happened, and it was far

from the last.  Many times we have heard a GNU user eagerly describe a

manual that he is writing, his intended contribution to the community,

only to learn that he had ruined everything by signing a publication

contract to make it non-free.

Free documentation, like free software, is a matter of freedom, not

price.  The problem with the non-free manual is not that publishers

charge a price for printed copies---that in itself is fine.  (The Free

Software Foundation sells printed copies of manuals, too.)  The

problem is the restrictions on the use of the manual.  Free manuals

are available in source code form, and give you permission to copy and

modify.  Non-free manuals do not allow this.

The criteria of freedom for a free manual are roughly the same as for

free software.  Redistribution (including the normal kinds of

commercial redistribution) must be permitted, so that the manual can

accompany every copy of the program, both on-line and on paper.

Permission for modification of the technical content is crucial too.

When people modify the software, adding or changing features, if they

are conscientious they will change the manual too---so they can

provide accurate and clear documentation for the modified program.  A

manual that leaves you no choice but to write a new manual to document

a changed version of the program is not really available to our

community.

Some kinds of limits on the way modification is handled are

acceptable.  For example, requirements to preserve the original

author's copyright notice, the distribution terms, or the list of

authors, are ok.  It is also no problem to require modified versions

to include notice that they were modified.  Even entire sections that

may not be deleted or changed are acceptable, as long as they deal

with nontechnical topics (like this one).  These kinds of restrictions

are acceptable because they don't obstruct the community's normal use

of the manual.

However, it must be possible to modify all the @emph{technical}

content of the manual, and then distribute the result in all the usual

media, through all the usual channels.  Otherwise, the restrictions

obstruct the use of the manual, it is not free, and we need another

manual to replace it.

Please spread the word about this issue.  Our community continues to

lose manuals to proprietary publishing.  If we spread the word that

free software needs free reference manuals and free tutorials, perhaps

the next person who wants to contribute by writing documentation will

realize, before it is too late, that only free manuals contribute to

the free software community.

If you are writing documentation, please insist on publishing it under

the GNU Free Documentation License or another free documentation

license.  Remember that this decision requires your approval---you

don't have to let the publisher decide.  Some commercial publishers

will use a free license if you insist, but they will not propose the

option; it is up to you to raise the issue and say firmly that this is

what you want.  If the publisher you are dealing with refuses, please

try other publishers.  If you're not sure whether a proposed license

is free, write to @email{licensing@@gnu.org}.

You can encourage commercial publishers to sell more free, copylefted

manuals and tutorials by buying them, and particularly by buying

copies from the publishers that paid for their writing or for major

improvements.  Meanwhile, try to avoid buying non-free documentation

at all.  Check the distribution terms of a manual before you buy it,

and insist that whoever seeks your business must respect your freedom.

Check the history of the book, and try to reward the publishers that

have paid or pay the authors to work on it.

The Free Software Foundation maintains a list of free documentation

published by other publishers, at

@url{http://www.fsf.org/doc/other-free-books.html}.

@node Contributors

@unnumberedsec Contributors to @value{GDBN}

Richard Stallman was the original author of @value{GDBN}, and of many

other @sc{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 @file{ChangeLog} in the @value{GDBN} distribution approximates a

blow-by-blow account.

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

@quotation

@emph{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!

@end quotation

So that they may not regard their many labors as thankless, we

particularly thank those who shepherded @value{GDBN} through major

releases:

Andrew Cagney (releases 6.3, 6.2, 6.1, 6.0, 5.3, 5.2, 5.1 and 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 @sc{gnu} C@t{++} support

in @value{GDBN}, with significant additional contributions from Per

Bothner and Daniel Berlin.  James Clark wrote the @sc{gnu} C@t{++}

demangler.  Early work on C@t{++} was by Peter TerMaat (who also did

much general update work leading to release 3.0).

@value{GDBN} 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.

Marko Mlinar, Ivan Guzvinec, Johan Rydverg, Alessandro Forin, Per

Bothner, Chris Ziomkowski and Jeremy Bennett contributed OpenRISC 1000 support.

Andreas Schwab contributed M68K @sc{gnu}/Linux support.

Rich Schaefer and Peter Schauer helped with support of SunOS shared

libraries.

Jay Fenlason and Roland McGrath ensured that @value{GDBN} 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@t{++} overloaded

symbols.

Hitachi America (now Renesas 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 (now Renesas) 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 @value{GDBN}.

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@t{++}

compiler, and the Text User Interface (nee 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.

DJ Delorie ported @value{GDBN} to MS-DOS, for the DJGPP project.

Robert Hoehne made significant contributions to the DJGPP port.

Cygnus Solutions has sponsored @value{GDBN} maintenance and much of its

development since 1991.  Cygnus engineers who have worked on @value{GDBN}

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.

Andrew Cagney, Fernando Nasser, and Elena Zannoni, while working for

Cygnus Solutions, implemented the original @sc{gdb/mi} interface.

Jim Blandy added support for preprocessor macros, while working for Red

Hat.

Andrew Cagney designed @value{GDBN}'s architecture vector.  Many

people including Andrew Cagney, Stephane Carrez, Randolph Chung, Nick

Duffek, Richard Henderson, Mark Kettenis, Grace Sainsbury, Kei

Sakamoto, Yoshinori Sato, Michael Snyder, Andreas Schwab, Jason

Thorpe, Corinna Vinschen, Ulrich Weigand, and Elena Zannoni, helped

with the migration of old architectures to this new framework.

Andrew Cagney completely re-designed and re-implemented @value{GDBN}'s

unwinder framework, this consisting of a fresh new design featuring

frame IDs, independent frame sniffers, and the sentinel frame.  Mark

Kettenis implemented the @sc{dwarf 2} unwinder, Jeff Johnston the

libunwind unwinder, and Andrew Cagney the dummy, sentinel, tramp, and

trad unwinders.  The architecture-specific changes, each involving a

complete rewrite of the architecture's frame code, were carried out by

Jim Blandy, Joel Brobecker, Kevin Buettner, Andrew Cagney, Stephane

Carrez, Randolph Chung, Orjan Friberg, Richard Henderson, Daniel

Jacobowitz, Jeff Johnston, Mark Kettenis, Theodore A. Roth, Kei

Sakamoto, Yoshinori Sato, Michael Snyder, Corinna Vinschen, and Ulrich

Weigand.

Christian Zankel, Ross Morley, Bob Wilson, and Maxim Grigoriev from

Tensilica, Inc.@: contributed support for Xtensa processors.  Others

who have worked on the Xtensa port of @value{GDBN} in the past include

Steve Tjiang, John Newlin, and Scott Foehner.

@node Sample Session

@chapter A Sample @value{GDBN} Session

You can use this manual at your leisure to read all about @value{GDBN}.

However, a handful of commands are enough to get started using the

debugger.  This chapter illustrates those commands.

@iftex

In this sample session, we emphasize user input like this: @b{input},

to make it easier to pick out from the surrounding output.

@end iftex

@c FIXME: this example may not be appropriate for some configs, where

@c FIXME...primary interest is in remote use.

One of the preliminary versions of @sc{gnu} @code{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 @code{m4}

session, we define a macro @code{foo} which expands to @code{0000}; we

then use the @code{m4} built-in @code{defn} to define @code{bar} as the

same thing.  However, when we change the open quote string to

@code{<QUOTE>} and the close quote string to @code{<UNQUOTE>}, the same

procedure fails to define a new synonym @code{baz}:

@smallexample

$ @b{cd gnu/m4}

$ @b{./m4}

@b{define(foo,0000)}

@b{foo}

0000

@b{define(bar,defn(`foo'))}

@b{bar}

0000

@b{changequote(<QUOTE>,<UNQUOTE>)}

@b{define(baz,defn(<QUOTE>foo<UNQUOTE>))}

@b{baz}

@b{Ctrl-d}

m4: End of input: 0: fatal error: EOF in string

@end smallexample

@noindent

Let us use @value{GDBN} to try to see what is going on.

@smallexample

$ @b{@value{GDBP} m4}

@c FIXME: this falsifies the exact text played out, to permit smallbook

@c FIXME... format to come out better.

@value{GDBN} 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 @value{GDBN}; type "show warranty"

 for details.

@value{GDBN} @value{GDBVN}, Copyright 1999 Free Software Foundation, Inc...

(@value{GDBP})

@end smallexample

@noindent

@value{GDBN} 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 @value{GDBN} to use a narrower display width than usual, so

that examples fit in this manual.

@smallexample

(@value{GDBP}) @b{set width 70}

@end smallexample

@noindent

We need to see how the @code{m4} built-in @code{changequote} works.

Having looked at the source, we know the relevant subroutine is

@code{m4_changequote}, so we set a breakpoint there with the @value{GDBN}

@code{break} command.

@smallexample

(@value{GDBP}) @b{break m4_changequote}

Breakpoint 1 at 0x62f4: file builtin.c, line 879.

@end smallexample

@noindent

Using the @code{run} command, we start @code{m4} running under @value{GDBN}

control; as long as control does not reach the @code{m4_changequote}

subroutine, the program runs as usual:

@smallexample

(@value{GDBP}) @b{run}

Starting program: /work/Editorial/gdb/gnu/m4/m4

@b{define(foo,0000)}

@b{foo}

0000

@end smallexample

@noindent

To trigger the breakpoint, we call @code{changequote}.  @value{GDBN}

suspends execution of @code{m4}, displaying information about the

context where it stops.

@smallexample

@b{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))

@end smallexample

@noindent

Now we use the command @code{n} (@code{next}) to advance execution to

the next line of the current function.

@smallexample

(@value{GDBP}) @b{n}

882         set_quotes((argc >= 2) ? TOKEN_DATA_TEXT(argv[1])\

 : nil,

@end smallexample

@noindent

@code{set_quotes} looks like a promising subroutine.  We can go into it

by using the command @code{s} (@code{step}) instead of @code{next}.

@code{step} goes to the next line to be executed in @emph{any}

subroutine, so it steps into @code{set_quotes}.

@smallexample

(@value{GDBP}) @b{s}

set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>")

    at input.c:530

530         if (lquote != def_lquote)

@end smallexample

@noindent

The display that shows the subroutine where @code{m4} is now

suspended (and its arguments) is called a stack frame display.  It

shows a summary of the stack.  We can use the @code{backtrace}

command (which can also be spelled @code{bt}), to see where we are

in the stack as a whole: the @code{backtrace} command displays a

stack frame for each active subroutine.

@smallexample

(@value{GDBP}) @b{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

@end smallexample

@noindent

We step through a few more lines to see what happens.  The first two

times, we can use @samp{s}; the next two times we use @code{n} to avoid

falling into the @code{xstrdup} subroutine.

@smallexample

(@value{GDBP}) @b{s}

0x3b5c  532         if (rquote != def_rquote)

(@value{GDBP}) @b{s}

0x3b80  535         lquote = (lq == nil || *lq == '\0') ?  \

def_lquote : xstrdup(lq);

(@value{GDBP}) @b{n}

536         rquote = (rq == nil || *rq == '\0') ? def_rquote\

 : xstrdup(rq);

(@value{GDBP}) @b{n}

538         len_lquote = strlen(rquote);

@end smallexample

@noindent

The last line displayed looks a little odd; we can examine the variables

@code{lquote} and @code{rquote} to see if they are in fact the new left

and right quotes we specified.  We use the command @code{p}

(@code{print}) to see their values.

@smallexample

(@value{GDBP}) @b{p lquote}

$1 = 0x35d40 "<QUOTE>"

(@value{GDBP}) @b{p rquote}

$2 = 0x35d50 "<UNQUOTE>"

@end smallexample

@noindent

@code{lquote} and @code{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 @code{l} (@code{list}) command.

@smallexample

(@value{GDBP}) @b{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

@end smallexample

@noindent

Let us step past the two lines that set @code{len_lquote} and

@code{len_rquote}, and then examine the values of those variables.

@smallexample

(@value{GDBP}) @b{n}

539         len_rquote = strlen(lquote);

(@value{GDBP}) @b{n}

540     @}

(@value{GDBP}) @b{p len_lquote}

$3 = 9

(@value{GDBP}) @b{p len_rquote}

$4 = 7

@end smallexample

@noindent

That certainly looks wrong, assuming @code{len_lquote} and

@code{len_rquote} are meant to be the lengths of @code{lquote} and

@code{rquote} respectively.  We can set them to better values using

the @code{p} command, since it can print the value of

any expression---and that expression can include subroutine calls and

assignments.

@smallexample

(@value{GDBP}) @b{p len_lquote=strlen(lquote)}

$5 = 7

(@value{GDBP}) @b{p len_rquote=strlen(rquote)}

$6 = 9

@end smallexample

@noindent

Is that enough to fix the problem of using the new quotes with the

@code{m4} built-in @code{defn}?  We can allow @code{m4} to continue

executing with the @code{c} (@code{continue}) command, and then try the

example that caused trouble initially:

@smallexample

(@value{GDBP}) @b{c}

Continuing.

@b{define(baz,defn(<QUOTE>foo<UNQUOTE>))}

baz

0000

@end smallexample

@noindent

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 @code{m4} exit by giving it an EOF as input:

@smallexample

@b{Ctrl-d}

Program exited normally.

@end smallexample

@noindent

The message @samp{Program exited normally.} is from @value{GDBN}; it

indicates @code{m4} has finished executing.  We can end our @value{GDBN}

session with the @value{GDBN} @code{quit} command.

@smallexample

(@value{GDBP}) @b{quit}

@end smallexample

@node Invocation

@chapter Getting In and Out of @value{GDBN}

This chapter discusses how to start @value{GDBN}, and how to get out of it.

The essentials are:

@itemize @bullet

@item

type @samp{@value{GDBP}} to start @value{GDBN}.

@item

type @kbd{quit} or @kbd{Ctrl-d} to exit.

@end itemize

@menu

* Invoking GDB::                How to start @value{GDBN}

* Quitting GDB::                How to quit @value{GDBN}

* Shell Commands::              How to use shell commands inside @value{GDBN}

* Logging Output::              How to log @value{GDBN}'s output to a file

@end menu

@node Invoking GDB

@section Invoking @value{GDBN}

Invoke @value{GDBN} by running the program @code{@value{GDBP}}.  Once started,

@value{GDBN} reads commands from the terminal until you tell it to exit.

You can also run @code{@value{GDBP}} 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 @value{GDBN} is with one argument,

specifying an executable program:

@smallexample

@value{GDBP} @var{program}

@end smallexample

@noindent

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

specified:

@smallexample

@value{GDBP} @var{program} @var{core}

@end smallexample

You can, instead, specify a process ID as a second argument, if you want

to debug a running process:

@smallexample

@value{GDBP} @var{program} 1234

@end smallexample

@noindent

would attach @value{GDBN} to process @code{1234} (unless you also have a file

named @file{1234}; @value{GDBN} does check for a core file first).

Taking advantage of the second command-line argument requires a fairly

complete operating system; when you use @value{GDBN} 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.  @value{GDBN}

will warn you if it is unable to attach or to read core dumps.

You can optionally have @code{@value{GDBP}} pass any arguments after the

executable file to the inferior using @code{--args}.  This option stops

option processing.

@smallexample

@value{GDBP} --args gcc -O2 -c foo.c

@end smallexample

This will cause @code{@value{GDBP}} to debug @code{gcc}, and to set

@code{gcc}'s command-line arguments (@pxref{Arguments}) to @samp{-O2 -c foo.c}.

You can run @code{@value{GDBP}} without printing the front material, which describes

@value{GDBN}'s non-warranty, by specifying @code{-silent}:

@smallexample

@value{GDBP} -silent

@end smallexample

@noindent

You can further control how @value{GDBN} starts up by using command-line

options.  @value{GDBN} itself can remind you of the options available.

@noindent

Type

@smallexample

@value{GDBP} -help

@end smallexample

@noindent

to display all available options and briefly describe their use

(@samp{@value{GDBP} -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

@samp{-x} option is used.

@menu

* File Options::                Choosing files

* Mode Options::                Choosing modes

* Startup::                     What @value{GDBN} does during startup

@end menu

@node File Options

@subsection Choosing Files

When @value{GDBN} 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 @samp{-se} and

@samp{-c} (or @samp{-p}) options respectively.  (@value{GDBN} reads the

first argument that does not have an associated option flag as

equivalent to the @samp{-se} option followed by that argument; and the

second argument that does not have an associated option flag, if any, as

equivalent to the @samp{-c}/@samp{-p} option followed by that argument.)

If the second argument begins with a decimal digit, @value{GDBN} will

first attempt to attach to it as a process, and if that fails, attempt

to open it as a corefile.  If you have a corefile whose name begins with

a digit, you can prevent @value{GDBN} from treating it as a pid by

prefixing it with @file{./}, e.g.@: @file{./12345}.

If @value{GDBN} 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.  @value{GDBN} 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 @samp{--} rather

than @samp{-}, though we illustrate the more usual convention.)

@c NOTE: the @cindex entries here use double dashes ON PURPOSE.  This

@c way, both those who look for -foo and --foo in the index, will find

@c it.

@table @code

@item -symbols @var{file}

@itemx -s @var{file}

@cindex @code{--symbols}

@cindex @code{-s}

Read symbol table from file @var{file}.

@item -exec @var{file}

@itemx -e @var{file}

@cindex @code{--exec}

@cindex @code{-e}

Use file @var{file} as the executable file to execute when appropriate,

and for examining pure data in conjunction with a core dump.

@item -se @var{file}

@cindex @code{--se}

Read symbol table from file @var{file} and use it as the executable

file.