Subversion Repositories or1k

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

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

@c Copyright 1988-2000

@c Copyright 1988-2000

@c Free Software Foundation, Inc.

@c Free Software Foundation, Inc.

@c

@c

@c %**start of header

@c %**start of header

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

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

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

@setfilename gdb.info

@setfilename gdb.info

@c

@c

@include gdb-cfg.texi

@include gdb-cfg.texi

@c

@c

@settitle Debugging with @value{GDBN}

@settitle Debugging with @value{GDBN}

@setchapternewpage odd

@setchapternewpage odd

@c %**end of header

@c %**end of header

@iftex

@iftex

@c @smallbook

@c @smallbook

@c @cropmarks

@c @cropmarks

@end iftex

@end iftex

@finalout

@finalout

@syncodeindex ky cp

@syncodeindex ky cp

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

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

@c annotate.texi uses @findex.

@c annotate.texi uses @findex.

@syncodeindex vr cp

@syncodeindex vr cp

@syncodeindex fn cp

@syncodeindex fn cp

@c gdbmi uses @findex

@c gdbmi uses @findex

@syncodeindex fn cp

@syncodeindex fn cp

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

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

@set EDITION Eighth

@set EDITION Eighth

@c !!set GDB manual's revision date

@c !!set GDB manual's revision date

@set DATE March 2000

@set DATE March 2000

@c THIS MANUAL REQUIRES TEXINFO 3.12 OR LATER.

@c THIS MANUAL REQUIRES TEXINFO 3.12 OR LATER.

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

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

@c manuals to an info tree.

@c manuals to an info tree.

@dircategory Programming & development tools.

@dircategory Programming & development tools.

@direntry

@direntry

* Gdb: (gdb).                     The @sc{gnu} debugger.

* Gdb: (gdb).                     The @sc{gnu} debugger.

@end direntry

@end direntry

@ifinfo

@ifinfo

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

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

This is the @value{EDITION} Edition, @value{DATE},

This is the @value{EDITION} Edition, @value{DATE},

of @cite{Debugging with @value{GDBN}: the @sc{gnu} Source-Level Debugger}

of @cite{Debugging with @value{GDBN}: the @sc{gnu} Source-Level Debugger}

for @value{GDBN} Version @value{GDBVN}.

for @value{GDBN} Version @value{GDBVN}.

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

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

Permission is granted to make and distribute verbatim copies of

Permission is granted to make and distribute verbatim copies of

this manual provided the copyright notice and this permission notice

this manual provided the copyright notice and this permission notice

are preserved on all copies.

are preserved on all copies.

@ignore

@ignore

Permission is granted to process this file through TeX and print the

Permission is granted to process this file through TeX and print the

results, provided the printed document carries copying permission

results, provided the printed document carries copying permission

notice identical to this one except for the removal of this paragraph

notice identical to this one except for the removal of this paragraph

(this paragraph not being relevant to the printed manual).

(this paragraph not being relevant to the printed manual).

@end ignore

@end ignore

Permission is granted to copy and distribute modified versions of this

Permission is granted to copy and distribute modified versions of this

manual under the conditions for verbatim copying, provided also that the

manual under the conditions for verbatim copying, provided also that the

entire resulting derived work is distributed under the terms of a

entire resulting derived work is distributed under the terms of a

permission notice identical to this one.

permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual

Permission is granted to copy and distribute translations of this manual

into another language, under the above conditions for modified versions.

into another language, under the above conditions for modified versions.

@end ifinfo

@end ifinfo

@titlepage

@titlepage

@title Debugging with @value{GDBN}

@title Debugging with @value{GDBN}

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

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

@sp 1

@sp 1

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

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

@subtitle @value{DATE}

@subtitle @value{DATE}

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

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

@page

@page

@tex

@tex

{\parskip=0pt

{\parskip=0pt

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

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

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

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

\hfill \TeX{}info \texinfoversion\par

\hfill \TeX{}info \texinfoversion\par

}

}

@end tex

@end tex

@vskip 0pt plus 1filll

@vskip 0pt plus 1filll

Copyright @copyright{} 1988-2000 Free Software Foundation, Inc.

Copyright @copyright{} 1988-2000 Free Software Foundation, Inc.

@sp 2

@sp 2

Published by the Free Software Foundation @*

Published by the Free Software Foundation @*

59 Temple Place - Suite 330, @*

59 Temple Place - Suite 330, @*

Boston, MA 02111-1307 USA @*

Boston, MA 02111-1307 USA @*

ISBN 1-882114-77-9 @*

ISBN 1-882114-77-9 @*

Permission is granted to make and distribute verbatim copies of

Permission is granted to make and distribute verbatim copies of

this manual provided the copyright notice and this permission notice

this manual provided the copyright notice and this permission notice

are preserved on all copies.

are preserved on all copies.

Permission is granted to copy and distribute modified versions of this

Permission is granted to copy and distribute modified versions of this

manual under the conditions for verbatim copying, provided also that the

manual under the conditions for verbatim copying, provided also that the

entire resulting derived work is distributed under the terms of a

entire resulting derived work is distributed under the terms of a

permission notice identical to this one.

permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual

Permission is granted to copy and distribute translations of this manual

into another language, under the above conditions for modified versions.

into another language, under the above conditions for modified versions.

@end titlepage

@end titlepage

@page

@page

@ifinfo

@ifinfo

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

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

@top Debugging with @value{GDBN}

@top Debugging with @value{GDBN}

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

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

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

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

@value{GDBVN}.

@value{GDBVN}.

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

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

@menu

@menu

* Summary::                     Summary of @value{GDBN}

* Summary::                     Summary of @value{GDBN}

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

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

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

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

* Commands::                    @value{GDBN} commands

* Commands::                    @value{GDBN} commands

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

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

* Stopping::                    Stopping and continuing

* Stopping::                    Stopping and continuing

* Stack::                       Examining the stack

* Stack::                       Examining the stack

* Source::                      Examining source files

* Source::                      Examining source files

* Data::                        Examining data

* Data::                        Examining data

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

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

* Symbols::                     Examining the symbol table

* Symbols::                     Examining the symbol table

* Altering::                    Altering execution

* Altering::                    Altering execution

* GDB Files::                   @value{GDBN} files

* GDB Files::                   @value{GDBN} files

* Targets::                     Specifying a debugging target

* Targets::                     Specifying a debugging target

* Configurations::              Configuration-specific information

* Configurations::              Configuration-specific information

* Controlling GDB::             Controlling @value{GDBN}

* Controlling GDB::             Controlling @value{GDBN}

* Sequences::                   Canned sequences of commands

* Sequences::                   Canned sequences of commands

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

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

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

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

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

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

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

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

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

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

* Command Line Editing::        Command Line Editing

* Command Line Editing::        Command Line Editing

* Using History Interactively:: Using History Interactively

* Using History Interactively:: Using History Interactively

* Installing GDB::              Installing GDB

* Installing GDB::              Installing GDB

* Index::                       Index

* Index::                       Index

@end menu

@end menu

@end ifinfo

@end ifinfo

@c the replication sucks, but this avoids a texinfo 3.12 lameness

@c the replication sucks, but this avoids a texinfo 3.12 lameness

@ifhtml

@ifhtml

@node Top

@node Top

@top Debugging with @value{GDBN}

@top Debugging with @value{GDBN}

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

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

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

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

@value{GDBVN}.

@value{GDBVN}.

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

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

@menu

@menu

* Summary::                     Summary of @value{GDBN}

* Summary::                     Summary of @value{GDBN}

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

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

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

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

* Commands::                    @value{GDBN} commands

* Commands::                    @value{GDBN} commands

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

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

* Stopping::                    Stopping and continuing

* Stopping::                    Stopping and continuing

* Stack::                       Examining the stack

* Stack::                       Examining the stack

* Source::                      Examining source files

* Source::                      Examining source files

* Data::                        Examining data

* Data::                        Examining data

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

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

* Symbols::                     Examining the symbol table

* Symbols::                     Examining the symbol table

* Altering::                    Altering execution

* Altering::                    Altering execution

* GDB Files::                   @value{GDBN} files

* GDB Files::                   @value{GDBN} files

* Targets::                     Specifying a debugging target

* Targets::                     Specifying a debugging target

* Configurations::              Configuration-specific information

* Configurations::              Configuration-specific information

* Controlling GDB::             Controlling @value{GDBN}

* Controlling GDB::             Controlling @value{GDBN}

* Sequences::                   Canned sequences of commands

* Sequences::                   Canned sequences of commands

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

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

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

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

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

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

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

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

* Command Line Editing::        Command Line Editing

* Command Line Editing::        Command Line Editing

* Using History Interactively:: Using History Interactively

* Using History Interactively:: Using History Interactively

* Installing GDB::              Installing GDB

* Installing GDB::              Installing GDB

* Index::                       Index

* Index::                       Index

@end menu

@end menu

@end ifhtml

@end ifhtml

@node Summary

@node Summary

@unnumbered Summary of @value{GDBN}

@unnumbered Summary of @value{GDBN}

The purpose of a debugger such as @value{GDBN} is to allow you to see what is

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

going on ``inside'' another program while it executes---or what another

program was doing at the moment it crashed.

program was doing at the moment it crashed.

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

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

these) to help you catch bugs in the act:

these) to help you catch bugs in the act:

@itemize @bullet

@itemize @bullet

@item

@item

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

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

@item

@item

Make your program stop on specified conditions.

Make your program stop on specified conditions.

@item

@item

Examine what has happened, when your program has stopped.

Examine what has happened, when your program has stopped.

@item

@item

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

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

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

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

@end itemize

@end itemize

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

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

For more information, see @ref{Support,,Supported languages}.

For more information, see @ref{Support,,Supported languages}.

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

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

@cindex Chill

@cindex Chill

@cindex Modula-2

@cindex Modula-2

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

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

see @ref{Modula-2,,Modula-2}.  For information on Chill, see @ref{Chill}.

see @ref{Modula-2,,Modula-2}.  For information on Chill, see @ref{Chill}.

@cindex Pascal

@cindex Pascal

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

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

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

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

entering expressions, printing values, or similar features using Pascal

entering expressions, printing values, or similar features using Pascal

syntax.

syntax.

@cindex Fortran

@cindex Fortran

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

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

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

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

underscore.

underscore.

@menu

@menu

* Free Software::               Freely redistributable software

* Free Software::               Freely redistributable software

* Contributors::                Contributors to GDB

* Contributors::                Contributors to GDB

@end menu

@end menu

@node Free Software

@node Free Software

@unnumberedsec Free software

@unnumberedsec Free software

@value{GDBN} is @dfn{free software}, protected by the @sc{gnu}

@value{GDBN} is @dfn{free software}, protected by the @sc{gnu}

General Public License

General Public License

(GPL).  The GPL gives you the freedom to copy or adapt a licensed

(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

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

freedom to modify that copy (which means that they must get access to

the source code), and the freedom to distribute further copies.

the source code), and the freedom to distribute further copies.

Typical software companies use copyrights to limit your freedoms; the

Typical software companies use copyrights to limit your freedoms; the

Free Software Foundation uses the GPL to preserve these freedoms.

Free Software Foundation uses the GPL to preserve these freedoms.

Fundamentally, the General Public License is a license which says that

Fundamentally, the General Public License is a license which says that

you have these freedoms and that you cannot take these freedoms away

you have these freedoms and that you cannot take these freedoms away

from anyone else.

from anyone else.

@node Contributors

@node Contributors

@unnumberedsec Contributors to @value{GDBN}

@unnumberedsec Contributors to @value{GDBN}

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

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

other @sc{gnu} programs.  Many others have contributed to its

other @sc{gnu} programs.  Many others have contributed to its

development.  This section attempts to credit major contributors.  One

development.  This section attempts to credit major contributors.  One

of the virtues of free software is that everyone is free to contribute

of the virtues of free software is that everyone is free to contribute

to it; with regret, we cannot actually acknowledge everyone here.  The

to it; with regret, we cannot actually acknowledge everyone here.  The

file @file{ChangeLog} in the @value{GDBN} distribution approximates a

file @file{ChangeLog} in the @value{GDBN} distribution approximates a

blow-by-blow account.

blow-by-blow account.

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

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

@quotation

@quotation

@emph{Plea:} Additions to this section are particularly welcome.  If you

@emph{Plea:} Additions to this section are particularly welcome.  If you

or your friends (or enemies, to be evenhanded) have been unfairly

or your friends (or enemies, to be evenhanded) have been unfairly

omitted from this list, we would like to add your names!

omitted from this list, we would like to add your names!

@end quotation

@end quotation

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

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

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

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

releases:

releases:

Andrew Cagney (release 5.0);

Andrew Cagney (release 5.0);

Jim Blandy (release 4.18);

Jim Blandy (release 4.18);

Jason Molenda (release 4.17);

Jason Molenda (release 4.17);

Stan Shebs (release 4.14);

Stan Shebs (release 4.14);

Fred Fish (releases 4.16, 4.15, 4.13, 4.12, 4.11, 4.10, and 4.9);

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);

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);

John Gilmore (releases 4.3, 4.2, 4.1, 4.0, and 3.9);

Jim Kingdon (releases 3.5, 3.4, and 3.3);

Jim Kingdon (releases 3.5, 3.4, and 3.3);

and Randy Smith (releases 3.2, 3.1, and 3.0).

and Randy Smith (releases 3.2, 3.1, and 3.0).

Richard Stallman, assisted at various times by Peter TerMaat, Chris

Richard Stallman, assisted at various times by Peter TerMaat, Chris

Hanson, and Richard Mlynarik, handled releases through 2.8.

Hanson, and Richard Mlynarik, handled releases through 2.8.

Michael Tiemann is the author of most of the @sc{gnu} C++ support in

Michael Tiemann is the author of most of the @sc{gnu} C++ support in

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

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

Bothner.  James Clark wrote the @sc{gnu} C++ demangler.  Early work on

Bothner.  James Clark wrote the @sc{gnu} C++ demangler.  Early work on

C++ was by Peter TerMaat (who also did much general update work leading

C++ was by Peter TerMaat (who also did much general update work leading

to release 3.0).

to release 3.0).

@value{GDBN} 4 uses the BFD subroutine library to examine multiple

@value{GDBN} 4 uses the BFD subroutine library to examine multiple

object-file formats; BFD was a joint project of David V.

object-file formats; BFD was a joint project of David V.

Henkel-Wallace, Rich Pixley, Steve Chamberlain, and John Gilmore.

Henkel-Wallace, Rich Pixley, Steve Chamberlain, and John Gilmore.

David Johnson wrote the original COFF support; Pace Willison did

David Johnson wrote the original COFF support; Pace Willison did

the original support for encapsulated COFF.

the original support for encapsulated COFF.

Brent Benson of Harris Computer Systems contributed DWARF 2 support.

Brent Benson of Harris Computer Systems contributed DWARF 2 support.

Adam de Boor and Bradley Davis contributed the ISI Optimum V support.

Adam de Boor and Bradley Davis contributed the ISI Optimum V support.

Per Bothner, Noboyuki Hikichi, and Alessandro Forin contributed MIPS

Per Bothner, Noboyuki Hikichi, and Alessandro Forin contributed MIPS

support.

support.

Jean-Daniel Fekete contributed Sun 386i support.

Jean-Daniel Fekete contributed Sun 386i support.

Chris Hanson improved the HP9000 support.

Chris Hanson improved the HP9000 support.

Noboyuki Hikichi and Tomoyuki Hasei contributed Sony/News OS 3 support.

Noboyuki Hikichi and Tomoyuki Hasei contributed Sony/News OS 3 support.

David Johnson contributed Encore Umax support.

David Johnson contributed Encore Umax support.

Jyrki Kuoppala contributed Altos 3068 support.

Jyrki Kuoppala contributed Altos 3068 support.

Jeff Law contributed HP PA and SOM support.

Jeff Law contributed HP PA and SOM support.

Keith Packard contributed NS32K support.

Keith Packard contributed NS32K support.

Doug Rabson contributed Acorn Risc Machine support.

Doug Rabson contributed Acorn Risc Machine support.

Bob Rusk contributed Harris Nighthawk CX-UX support.

Bob Rusk contributed Harris Nighthawk CX-UX support.

Chris Smith contributed Convex support (and Fortran debugging).

Chris Smith contributed Convex support (and Fortran debugging).

Jonathan Stone contributed Pyramid support.

Jonathan Stone contributed Pyramid support.

Michael Tiemann contributed SPARC support.

Michael Tiemann contributed SPARC support.

Tim Tucker contributed support for the Gould NP1 and Gould Powernode.

Tim Tucker contributed support for the Gould NP1 and Gould Powernode.

Pace Willison contributed Intel 386 support.

Pace Willison contributed Intel 386 support.

Jay Vosburgh contributed Symmetry support.

Jay Vosburgh contributed Symmetry support.

Andreas Schwab contributed M68K Linux support.

Andreas Schwab contributed M68K Linux support.

Rich Schaefer and Peter Schauer helped with support of SunOS shared

Rich Schaefer and Peter Schauer helped with support of SunOS shared

libraries.

libraries.

Jay Fenlason and Roland McGrath ensured that @value{GDBN} and GAS agree

Jay Fenlason and Roland McGrath ensured that @value{GDBN} and GAS agree

about several machine instruction sets.

about several machine instruction sets.

Patrick Duval, Ted Goldstein, Vikram Koka and Glenn Engel helped develop

Patrick Duval, Ted Goldstein, Vikram Koka and Glenn Engel helped develop

remote debugging.  Intel Corporation, Wind River Systems, AMD, and ARM

remote debugging.  Intel Corporation, Wind River Systems, AMD, and ARM

contributed remote debugging modules for the i960, VxWorks, A29K UDI,

contributed remote debugging modules for the i960, VxWorks, A29K UDI,

and RDI targets, respectively.

and RDI targets, respectively.

Brian Fox is the author of the readline libraries providing

Brian Fox is the author of the readline libraries providing

command-line editing and command history.

command-line editing and command history.

Andrew Beers of SUNY Buffalo wrote the language-switching code, the

Andrew Beers of SUNY Buffalo wrote the language-switching code, the

Modula-2 support, and contributed the Languages chapter of this manual.

Modula-2 support, and contributed the Languages chapter of this manual.

Fred Fish wrote most of the support for Unix System Vr4.

Fred Fish wrote most of the support for Unix System Vr4.

He also enhanced the command-completion support to cover C++ overloaded

He also enhanced the command-completion support to cover C++ overloaded

symbols.

symbols.

Hitachi America, Ltd. sponsored the support for H8/300, H8/500, and

Hitachi America, Ltd. sponsored the support for H8/300, H8/500, and

Super-H processors.

Super-H processors.

NEC sponsored the support for the v850, Vr4xxx, and Vr5xxx processors.

NEC sponsored the support for the v850, Vr4xxx, and Vr5xxx processors.

Mitsubishi sponsored the support for D10V, D30V, and M32R/D processors.

Mitsubishi sponsored the support for D10V, D30V, and M32R/D processors.

Toshiba sponsored the support for the TX39 Mips processor.

Toshiba sponsored the support for the TX39 Mips processor.

Matsushita sponsored the support for the MN10200 and MN10300 processors.

Matsushita sponsored the support for the MN10200 and MN10300 processors.

Fujitsu sponsored the support for SPARClite and FR30 processors.

Fujitsu sponsored the support for SPARClite and FR30 processors.

Kung Hsu, Jeff Law, and Rick Sladkey added support for hardware

Kung Hsu, Jeff Law, and Rick Sladkey added support for hardware

watchpoints.

watchpoints.

Michael Snyder added support for tracepoints.

Michael Snyder added support for tracepoints.

Stu Grossman wrote gdbserver.

Stu Grossman wrote gdbserver.

Jim Kingdon, Peter Schauer, Ian Taylor, and Stu Grossman made

Jim Kingdon, Peter Schauer, Ian Taylor, and Stu Grossman made

nearly innumerable bug fixes and cleanups throughout @value{GDBN}.

nearly innumerable bug fixes and cleanups throughout @value{GDBN}.

The following people at the Hewlett-Packard Company contributed

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

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++

(narrow mode), HP's implementation of kernel threads, HP's aC++

compiler, and the terminal user interface: Ben Krepp, Richard Title,

compiler, and the terminal user interface: Ben Krepp, Richard Title,

John Bishop, Susan Macchia, Kathy Mann, Satish Pai, India Paul, Steve

John Bishop, Susan Macchia, Kathy Mann, Satish Pai, India Paul, Steve

Rehrauer, and Elena Zannoni.  Kim Haase provided HP-specific

Rehrauer, and Elena Zannoni.  Kim Haase provided HP-specific

information in this manual.

information in this manual.

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

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

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

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

fulltime include Mark Alexander, Jim Blandy, Per Bothner, Kevin

fulltime include Mark Alexander, Jim Blandy, Per Bothner, Kevin

Buettner, Edith Epstein, Chris Faylor, Fred Fish, Martin Hunt, Jim

Buettner, Edith Epstein, Chris Faylor, Fred Fish, Martin Hunt, Jim

Ingham, John Gilmore, Stu Grossman, Kung Hsu, Jim Kingdon, John Metzler,

Ingham, John Gilmore, Stu Grossman, Kung Hsu, Jim Kingdon, John Metzler,

Fernando Nasser, Geoffrey Noer, Dawn Perchik, Rich Pixley, Zdenek

Fernando Nasser, Geoffrey Noer, Dawn Perchik, Rich Pixley, Zdenek

Radouch, Keith Seitz, Stan Shebs, David Taylor, and Elena Zannoni.  In

Radouch, Keith Seitz, Stan Shebs, David Taylor, and Elena Zannoni.  In

addition, Dave Brolley, Ian Carmichael, Steve Chamberlain, Nick Clifton,

addition, Dave Brolley, Ian Carmichael, Steve Chamberlain, Nick Clifton,

JT Conklin, Stan Cox, DJ Delorie, Ulrich Drepper, Frank Eigler, Doug

JT Conklin, Stan Cox, DJ Delorie, Ulrich Drepper, Frank Eigler, Doug

Evans, Sean Fagan, David Henkel-Wallace, Richard Henderson, Jeff

Evans, Sean Fagan, David Henkel-Wallace, Richard Henderson, Jeff

Holcomb, Jeff Law, Jim Lemke, Tom Lord, Bob Manson, Michael Meissner,

Holcomb, Jeff Law, Jim Lemke, Tom Lord, Bob Manson, Michael Meissner,

Jason Merrill, Catherine Moore, Drew Moseley, Ken Raeburn, Gavin

Jason Merrill, Catherine Moore, Drew Moseley, Ken Raeburn, Gavin

Romig-Koch, Rob Savoye, Jamie Smith, Mike Stump, Ian Taylor, Angela

Romig-Koch, Rob Savoye, Jamie Smith, Mike Stump, Ian Taylor, Angela

Thomas, Michael Tiemann, Tom Tromey, Ron Unrau, Jim Wilson, and David

Thomas, Michael Tiemann, Tom Tromey, Ron Unrau, Jim Wilson, and David

Zuhn have made contributions both large and small.

Zuhn have made contributions both large and small.

@node Sample Session

@node Sample Session

@chapter A Sample @value{GDBN} Session

@chapter A Sample @value{GDBN} Session

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

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

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

debugger.  This chapter illustrates those commands.

debugger.  This chapter illustrates those commands.

@iftex

@iftex

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

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

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

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

@end iftex

@end iftex

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

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

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

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

One of the preliminary versions of @sc{gnu} @code{m4} (a generic macro

One of the preliminary versions of @sc{gnu} @code{m4} (a generic macro

processor) exhibits the following bug: sometimes, when we change its

processor) exhibits the following bug: sometimes, when we change its

quote strings from the default, the commands used to capture one macro

quote strings from the default, the commands used to capture one macro

definition within another stop working.  In the following short @code{m4}

definition within another stop working.  In the following short @code{m4}

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

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

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

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

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

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

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

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

@smallexample

@smallexample

$ @b{cd gnu/m4}

$ @b{cd gnu/m4}

$ @b{./m4}

$ @b{./m4}

@b{define(foo,0000)}

@b{define(foo,0000)}

@b{foo}

@b{foo}

0000

0000

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

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

@b{bar}

@b{bar}

0000

0000

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

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

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

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

@b{baz}

@b{baz}

@b{C-d}

@b{C-d}

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

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

@end smallexample

@end smallexample

@noindent

@noindent

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

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

@smallexample

@smallexample

$ @b{@value{GDBP} m4}

$ @b{@value{GDBP} m4}

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

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

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

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

@value{GDBN} is free software and you are welcome to distribute copies

@value{GDBN} is free software and you are welcome to distribute copies

 of it under certain conditions; type "show copying" to see

 of it under certain conditions; type "show copying" to see

 the conditions.

 the conditions.

There is absolutely no warranty for @value{GDBN}; type "show warranty"

There is absolutely no warranty for @value{GDBN}; type "show warranty"

 for details.

 for details.

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

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

(@value{GDBP})

(@value{GDBP})

@end smallexample

@end smallexample

@noindent

@noindent

@value{GDBN} reads only enough symbol data to know where to find the

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

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

We now tell @value{GDBN} to use a narrower display width than usual, so

that examples fit in this manual.

that examples fit in this manual.

@smallexample

@smallexample

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

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

@end smallexample

@end smallexample

@noindent

@noindent

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

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

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

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{m4_changequote}, so we set a breakpoint there with the @value{GDBN}

@code{break} command.

@code{break} command.

@smallexample

@smallexample

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

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

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

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

@end smallexample

@end smallexample

@noindent

@noindent

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

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}

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

subroutine, the program runs as usual:

subroutine, the program runs as usual:

@smallexample

@smallexample

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

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

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

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

@b{define(foo,0000)}

@b{define(foo,0000)}

@b{foo}

@b{foo}

0000

0000

@end smallexample

@end smallexample

@noindent

@noindent

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

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

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

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

context where it stops.

context where it stops.

@smallexample

@smallexample

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

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

Breakpoint 1, m4_changequote (argc=3, argv=0x33c70)

Breakpoint 1, m4_changequote (argc=3, argv=0x33c70)

    at builtin.c:879

    at builtin.c:879

879         if (bad_argc(TOKEN_DATA_TEXT(argv[0]),argc,1,3))

879         if (bad_argc(TOKEN_DATA_TEXT(argv[0]),argc,1,3))

@end smallexample

@end smallexample

@noindent

@noindent

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

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

the next line of the current function.

the next line of the current function.

@smallexample

@smallexample

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

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

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

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

 : nil,

 : nil,

@end smallexample

@end smallexample

@noindent

@noindent

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

@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}.

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}

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

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

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

@smallexample

@smallexample

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

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

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

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

    at input.c:530

    at input.c:530

530         if (lquote != def_lquote)

530         if (lquote != def_lquote)

@end smallexample

@end smallexample

@noindent

@noindent

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

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

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

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

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

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

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

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

stack frame for each active subroutine.

stack frame for each active subroutine.

@smallexample

@smallexample

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

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

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

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

    at input.c:530

    at input.c:530

#1  0x6344 in m4_changequote (argc=3, argv=0x33c70)

#1  0x6344 in m4_changequote (argc=3, argv=0x33c70)

    at builtin.c:882

    at builtin.c:882

#2  0x8174 in expand_macro (sym=0x33320) at macro.c:242

#2  0x8174 in expand_macro (sym=0x33320) at macro.c:242

#3  0x7a88 in expand_token (obs=0x0, t=209696, td=0xf7fffa30)

#3  0x7a88 in expand_token (obs=0x0, t=209696, td=0xf7fffa30)

    at macro.c:71

    at macro.c:71

#4  0x79dc in expand_input () at macro.c:40

#4  0x79dc in expand_input () at macro.c:40

#5  0x2930 in main (argc=0, argv=0xf7fffb20) at m4.c:195

#5  0x2930 in main (argc=0, argv=0xf7fffb20) at m4.c:195

@end smallexample

@end smallexample

@noindent

@noindent

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

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

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

falling into the @code{xstrdup} subroutine.

falling into the @code{xstrdup} subroutine.

@smallexample

@smallexample

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

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

0x3b5c  532         if (rquote != def_rquote)

0x3b5c  532         if (rquote != def_rquote)

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

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

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

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

def_lquote : xstrdup(lq);

def_lquote : xstrdup(lq);

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

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

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

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

 : xstrdup(rq);

 : xstrdup(rq);

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

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

538         len_lquote = strlen(rquote);

538         len_lquote = strlen(rquote);

@end smallexample

@end smallexample

@noindent

@noindent

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

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

@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}

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

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

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

@smallexample

@smallexample

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

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

$1 = 0x35d40 "<QUOTE>"

$1 = 0x35d40 "<QUOTE>"

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

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

$2 = 0x35d50 "<UNQUOTE>"

$2 = 0x35d50 "<UNQUOTE>"

@end smallexample

@end smallexample

@noindent

@noindent

@code{lquote} and @code{rquote} are indeed the new left and right quotes.

@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

To look at some context, we can display ten lines of source

surrounding the current line with the @code{l} (@code{list}) command.

surrounding the current line with the @code{l} (@code{list}) command.

@smallexample

@smallexample

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

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

533             xfree(rquote);

533             xfree(rquote);

534

534

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

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

 : xstrdup (lq);

 : xstrdup (lq);

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

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

 : xstrdup (rq);

 : xstrdup (rq);

537

537

538         len_lquote = strlen(rquote);

538         len_lquote = strlen(rquote);

539         len_rquote = strlen(lquote);

539         len_rquote = strlen(lquote);

540     @}

540     @}

541

541

542     void

542     void

@end smallexample

@end smallexample

@noindent

@noindent

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

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

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

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

@smallexample

@smallexample

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

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

539         len_rquote = strlen(lquote);

539         len_rquote = strlen(lquote);

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

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

540     @}

540     @}

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

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

$3 = 9

$3 = 9

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

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

$4 = 7

$4 = 7

@end smallexample

@end smallexample

@noindent

@noindent

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

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

@code{len_rquote} are meant to be the lengths of @code{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

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

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

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

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

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

assignments.

assignments.

@smallexample

@smallexample

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

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

$5 = 7

$5 = 7

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

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

$6 = 9

$6 = 9

@end smallexample

@end smallexample

@noindent

@noindent

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

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

@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

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

example that caused trouble initially:

example that caused trouble initially:

@smallexample

@smallexample

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

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

Continuing.

Continuing.

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

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

baz

baz

0000

0000

@end smallexample

@end smallexample

@noindent

@noindent

Success!  The new quotes now work just as well as the default ones.  The

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

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:

lengths.  We allow @code{m4} exit by giving it an EOF as input:

@smallexample

@smallexample

@b{C-d}

@b{C-d}

Program exited normally.

Program exited normally.

@end smallexample

@end smallexample

@noindent

@noindent

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

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

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

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

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

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

@smallexample

@smallexample

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

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

@end smallexample

@end smallexample

@node Invocation

@node Invocation

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

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

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

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

The essentials are:

The essentials are:

@itemize @bullet

@itemize @bullet

@item

@item

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

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

@item

@item

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

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

@end itemize

@end itemize

@menu

@menu

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

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

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

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

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

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

@end menu

@end menu

@node Invoking GDB

@node Invoking GDB

@section Invoking @value{GDBN}

@section Invoking @value{GDBN}

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

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.

@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,

You can also run @code{@value{GDBP}} with a variety of arguments and options,

to specify more of your debugging environment at the outset.

to specify more of your debugging environment at the outset.

The command-line options described here are designed

The command-line options described here are designed

to cover a variety of situations; in some environments, some of these

to cover a variety of situations; in some environments, some of these

options may effectively be unavailable.

options may effectively be unavailable.

The most usual way to start @value{GDBN} is with one argument,

The most usual way to start @value{GDBN} is with one argument,

specifying an executable program:

specifying an executable program:

@example

@example

@value{GDBP} @var{program}

@value{GDBP} @var{program}

@end example

@end example

@noindent

@noindent

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

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

specified:

specified:

@example

@example

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

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

@end example

@end example

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

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

to debug a running process:

to debug a running process:

@example

@example

@value{GDBP} @var{program} 1234

@value{GDBP} @var{program} 1234

@end example

@end example

@noindent

@noindent

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

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

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

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

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

complete operating system; when you use @value{GDBN} as a remote

complete operating system; when you use @value{GDBN} as a remote

debugger attached to a bare board, there may not be any notion of

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}

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

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

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

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

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

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

@smallexample

@smallexample

@value{GDBP} -silent

@value{GDBP} -silent

@end smallexample

@end smallexample

@noindent

@noindent

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

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

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

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

@noindent

@noindent

Type

Type

@example

@example

@value{GDBP} -help

@value{GDBP} -help

@end example

@end example

@noindent

@noindent

to display all available options and briefly describe their use

to display all available options and briefly describe their use

(@samp{@value{GDBP} -h} is a shorter equivalent).

(@samp{@value{GDBP} -h} is a shorter equivalent).

All options and command line arguments you give are processed

All options and command line arguments you give are processed

in sequential order.  The order makes a difference when the

in sequential order.  The order makes a difference when the

@samp{-x} option is used.

@samp{-x} option is used.

@menu

@menu

* File Options::                Choosing files

* File Options::                Choosing files

* Mode Options::                Choosing modes

* Mode Options::                Choosing modes

@end menu

@end menu

@node File Options

@node File Options

@subsection Choosing files

@subsection Choosing files

When @value{GDBN} starts, it reads any arguments other than options as

When @value{GDBN} starts, it reads any arguments other than options as

specifying an executable file and core file (or process ID).  This is

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

the same as if the arguments were specified by the @samp{-se} and

@samp{-c} options respectively.  (@value{GDBN} reads the first argument

@samp{-c} options respectively.  (@value{GDBN} reads the first argument

that does not have an associated option flag as equivalent to the

that does not have an associated option flag as equivalent to the

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

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

that does not have an associated option flag, if any, as equivalent to

that does not have an associated option flag, if any, as equivalent to

the @samp{-c} option followed by that argument.)

the @samp{-c} option followed by that argument.)

If @value{GDBN} has not been configured to included core file support,

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

such as for most embedded targets, then it will complain about a second

argument and ignore it.

argument and ignore it.

Many options have both long and short forms; both are shown in the

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

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.

them, so long as enough of the option is present to be unambiguous.

(If you prefer, you can flag option arguments with @samp{--} rather

(If you prefer, you can flag option arguments with @samp{--} rather

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

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

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

@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 way, both those who look for -foo and --foo in the index, will find

@c it.

@c it.

@table @code

@table @code

@item -symbols @var{file}

@item -symbols @var{file}

@itemx -s @var{file}

@itemx -s @var{file}

@cindex @code{--symbols}

@cindex @code{--symbols}

@cindex @code{-s}

@cindex @code{-s}

Read symbol table from file @var{file}.

Read symbol table from file @var{file}.

@item -exec @var{file}

@item -exec @var{file}

@itemx -e @var{file}

@itemx -e @var{file}

@cindex @code{--exec}

@cindex @code{--exec}

@cindex @code{-e}

@cindex @code{-e}

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

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

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

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

@item -se @var{file}

@item -se @var{file}

@cindex @code{--se}

@cindex @code{--se}

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

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

file.

file.

@item -core @var{file}

@item -core @var{file}

@itemx -c @var{file}

@itemx -c @var{file}

@cindex @code{--core}

@cindex @code{--core}

@cindex @code{-c}

@cindex @code{-c}

Use file @var{file} as a core dump to examine.

Use file @var{file} as a core dump to examine.

@item -c @var{number}

@item -c @var{number}

Connect to process ID @var{number}, as with the @code{attach} command

Connect to process ID @var{number}, as with the @code{attach} command

(unless there is a file in core-dump format named @var{number}, in which

(unless there is a file in core-dump format named @var{number}, in which

case @samp{-c} specifies that file as a core dump to read).

case @samp{-c} specifies that file as a core dump to read).

@item -command @var{file}

@item -command @var{file}

@itemx -x @var{file}

@itemx -x @var{file}

@cindex @code{--command}

@cindex @code{--command}

@cindex @code{-x}

@cindex @code{-x}

Execute @value{GDBN} commands from file @var{file}.  @xref{Command

Execute @value{GDBN} commands from file @var{file}.  @xref{Command

Files,, Command files}.

Files,, Command files}.

@item -directory @var{directory}

@item -directory @var{directory}

@itemx -d @var{directory}

@itemx -d @var{directory}

@cindex @code{--directory}

@cindex @code{--directory}

@cindex @code{-d}

@cindex @code{-d}

Add @var{directory} to the path to search for source files.

Add @var{directory} to the path to search for source files.

@item -m

@item -m

@itemx -mapped

@itemx -mapped

@cindex @code{--mapped}

@cindex @code{--mapped}

@cindex @code{-m}

@cindex @code{-m}

@emph{Warning: this option depends on operating system facilities that are not

@emph{Warning: this option depends on operating system facilities that are not

supported on all systems.}@*

supported on all systems.}@*

If memory-mapped files are available on your system through the @code{mmap}

If memory-mapped files are available on your system through the @code{mmap}

system call, you can use this option

system call, you can use this option

to have @value{GDBN} write the symbols from your

to have @value{GDBN} write the symbols from your

program into a reusable file in the current directory.  If the program you are debugging is

program into a reusable file in the current directory.  If the program you are debugging is

called @file{/tmp/fred}, the mapped symbol file is @file{/tmp/fred.syms}.

called @file{/tmp/fred}, the mapped symbol file is @file{/tmp/fred.syms}.

Future @value{GDBN} debugging sessions notice the presence of this file,

Future @value{GDBN} debugging sessions notice the presence of this file,

and can quickly map in symbol information from it, rather than reading

and can quickly map in symbol information from it, rather than reading

the symbol table from the executable program.

the symbol table from the executable program.

The @file{.syms} file is specific to the host machine where @value{GDBN}

The @file{.syms} file is specific to the host machine where @value{GDBN}

is run.  It holds an exact image of the internal @value{GDBN} symbol

is run.  It holds an exact image of the internal @value{GDBN} symbol

table.  It cannot be shared across multiple host platforms.

table.  It cannot be shared across multiple host platforms.

@item -r

@item -r

@itemx -readnow

@itemx -readnow

@cindex @code{--readnow}

@cindex @code{--readnow}

@cindex @code{-r}

@cindex @code{-r}

Read each symbol file's entire symbol table immediately, rather than

Read each symbol file's entire symbol table immediately, rather than

the default, which is to read it incrementally as it is needed.

the default, which is to read it incrementally as it is needed.

This makes startup slower, but makes future operations faster.

This makes startup slower, but makes future operations faster.

@end table

@end table

You typically combine the @code{-mapped} and @code{-readnow} options in

You typically combine the @code{-mapped} and @code{-readnow} options in

order to build a @file{.syms} file that contains complete symbol

order to build a @file{.syms} file that contains complete symbol

information.  (@xref{Files,,Commands to specify files}, for information

information.  (@xref{Files,,Commands to specify files}, for information

on @file{.syms} files.)  A simple @value{GDBN} invocation to do nothing

on @file{.syms} files.)  A simple @value{GDBN} invocation to do nothing

but build a @file{.syms} file for future use is:

but build a @file{.syms} file for future use is:

@example

@example

gdb -batch -nx -mapped -readnow programname

gdb -batch -nx -mapped -readnow programname

@end example

@end example

@node Mode Options

@node Mode Options

@subsection Choosing modes

@subsection Choosing modes

You can run @value{GDBN} in various alternative modes---for example, in

You can run @value{GDBN} in various alternative modes---for example, in

batch mode or quiet mode.

batch mode or quiet mode.

@table @code

@table @code

@item -nx

@item -nx

@itemx -n

@itemx -n

@cindex @code{--nx}

@cindex @code{--nx}

@cindex @code{-n}

@cindex @code{-n}

Do not execute commands found in any initialization files (normally

Do not execute commands found in any initialization files (normally

called @file{.gdbinit}, or @file{gdb.ini} on PCs).  Normally,

called @file{.gdbinit}, or @file{gdb.ini} on PCs).  Normally,

@value{GDBN} executes the commands in these files after all the command

@value{GDBN} executes the commands in these files after all the command

options and arguments have been processed.  @xref{Command Files,,Command

options and arguments have been processed.  @xref{Command Files,,Command

files}.

files}.

@item -quiet

@item -quiet

@itemx -silent

@itemx -silent

@itemx -q

@itemx -q

@cindex @code{--quiet}

@cindex @code{--quiet}

@cindex @code{--silent}

@cindex @code{--silent}

@cindex @code{-q}

@cindex @code{-q}

``Quiet''.  Do not print the introductory and copyright messages.  These

``Quiet''.  Do not print the introductory and copyright messages.  These

messages are also suppressed in batch mode.

messages are also suppressed in batch mode.

@item -batch

@item -batch

@cindex @code{--batch}

@cindex @code{--batch}

Run in batch mode.  Exit with status @code{0} after processing all the

Run in batch mode.  Exit with status @code{0} after processing all the

command files specified with @samp{-x} (and all commands from

command files specified with @samp{-x} (and all commands from

initialization files, if not inhibited with @samp{-n}).  Exit with

initialization files, if not inhibited with @samp{-n}).  Exit with

nonzero status if an error occurs in executing the @value{GDBN} commands

nonzero status if an error occurs in executing the @value{GDBN} commands

in the command files.

in the command files.

Batch mode may be useful for running @value{GDBN} as a filter, for

Batch mode may be useful for running @value{GDBN} as a filter, for

example to download and run a program on another computer; in order to

example to download and run a program on another computer; in order to

make this more useful, the message

make this more useful, the message

@example

@example

Program exited normally.

Program exited normally.

@end example

@end example

@noindent

@noindent

(which is ordinarily issued whenever a program running under

(which is ordinarily issued whenever a program running under

@value{GDBN} control terminates) is not issued when running in batch

@value{GDBN} control terminates) is not issued when running in batch

mode.

mode.

@item -nowindows

@item -nowindows

@itemx -nw

@itemx -nw

@cindex @code{--nowindows}

@cindex @code{--nowindows}