2 @setfilename _GDBP__.info
4 @c THIS MANUAL REQUIRES TEXINFO-2 macros and info-makers to format properly.
6 @c NOTE: this manual is marked up for preprocessing with a collection
7 @c of m4 macros called "pretex.m4". If you see <_if__> and <_fi__>
8 @c scattered around the source, you have the full source before
9 @c preprocessing; if you don't, you have the source configured for
10 @c _HOST__ architectures (and you can of course get the full source,
11 @c with all configurations, from wherever you got this).
14 THIS IS THE FULL SOURCE. The full source needs to be run through m4
15 before either tex- or info- formatting: for example,
17 m4 pretex.m4 none.m4 m680x0.m4 gdb.texinfo >gdb-680x0.texinfo
19 will produce (assuming your path finds either GNU or SysV m4; Berkeley
20 won't do) a file suitable for formatting. See the text in "pretex.m4"
21 for a fuller explanation (and the macro definitions).
22 To permit maximum flexibility, the full source also does not contain
23 any "info" markup that can be generated automatically; you should first
24 preprocess it as above, then run it through C-u texinfo-master-menu,
25 before actually info-formatting it.
29 @c FOR UPDATES LEADING TO THIS DRAFT, GDB CHANGELOG CONSULTED BETWEEN:
30 @c Sun May 19 05:36:59 1991 John Gilmore (gnu at cygint.cygnus.com)
31 @c Sat Dec 22 02:51:40 1990 John Gilmore (gnu at cygint)
33 This file documents the GNU debugger _GDBN__.
35 Copyright (C) 1988, 1989, 1990, 1991 Free Software Foundation, Inc.
37 Permission is granted to make and distribute verbatim copies of
38 this manual provided the copyright notice and this permission notice
39 are preserved on all copies.
42 Permission is granted to process this file through TeX and print the
43 results, provided the printed document carries copying permission
44 notice identical to this one except for the removal of this paragraph
45 (this paragraph not being relevant to the printed manual).
48 Permission is granted to copy and distribute modified versions of this
49 manual under the conditions for verbatim copying, provided also that the
50 section entitled ``GNU General Public License'' is included exactly as
51 in the original, and provided that the entire resulting derived work is
52 distributed under the terms of a permission notice identical to this
55 Permission is granted to copy and distribute translations of this manual
56 into another language, under the above conditions for modified versions,
57 except that the section entitled ``GNU General Public License'' may be
58 included in a translation approved by the Free Software Foundation
59 instead of in the original English.
62 @setchapternewpage odd
64 @settitle Using _GDBN__ (v4.0)
67 @settitle Using _GDBN__ v4.0 (_HOST__)
74 @subtitle{A Guide to the GNU Source-Level Debugger}
76 @subtitle{On _HOST__ Systems}
79 @c Maybe crank this up to "Fourth Edition" when released at FSF
80 @c @subtitle Third Edition---_GDBN__ version 4.0
81 @subtitle _GDBN__ version 4.0
83 @author{Richard M. Stallman@qquad @hfill Free Software Foundation}
84 @author{Roland H. Pesch@qquad @hfill Cygnus Support}
88 \def\$#1${{#1}} % Kluge: collect RCS revision info without $...$
89 \xdef\manvers{\$Revision$} % For use in headers, footers too
91 \hfill rms\@ai.mit.edu, pesch\@cygnus.com\par
92 \hfill {\it Using _GDBN__}, \manvers\par
93 \hfill \TeX{}info \texinfoversion\par
97 @vskip 0pt plus 1filll
98 Copyright @copyright{} 1988, 1989, 1990, 1991 Free Software Foundation, Inc.
100 Permission is granted to make and distribute verbatim copies of
101 this manual provided the copyright notice and this permission notice
102 are preserved on all copies.
104 Permission is granted to copy and distribute modified versions of this
105 manual under the conditions for verbatim copying, provided also that the
106 section entitled ``GNU General Public License'' is included exactly as
107 in the original, and provided that the entire resulting derived work is
108 distributed under the terms of a permission notice identical to this
111 Permission is granted to copy and distribute translations of this manual
112 into another language, under the above conditions for modified versions,
113 except that the section entitled ``GNU General Public License'' may be
114 included in a translation approved by the Free Software Foundation
115 instead of in the original English.
119 @node Top, Summary, (dir), (dir)
121 This file describes version 4.0 of GDB, the GNU symbolic debugger.
125 * Summary:: Summary of _GDBN__
126 * New Features:: New Features in _GDBN__ version 4.0
127 * Sample Session:: A Sample _GDBN__ Session
128 * Invocation:: Getting In and Out of _GDBN__
130 * Running:: Running Programs Under _GDBN__
131 * Stopping:: Stopping and Continuing
132 * Stack:: Examining the Stack
133 * Source:: Examining Source Files
134 * Data:: Examining Data
135 * Symbols:: Examining the Symbol Table
136 * Altering:: Altering Execution
138 * Targets:: Specifying a Debugging Target
139 * Controlling _GDBN__:: Controlling _GDBN__
140 * Sequences:: Canned Sequences of Commands
141 * Emacs:: Using _GDBN__ under GNU Emacs
142 * _GDBN__ Bugs:: Reporting Bugs in _GDBN__
144 * Installing _GDBN__:: Installing _GDBN__
145 * Copying:: GNU GENERAL PUBLIC LICENSE
149 @node Summary, New Features, Top, Top
150 @unnumbered Summary of _GDBN__
152 The purpose of a debugger such as _GDBN__ is to allow you to see what is
153 going on ``inside'' another program while it executes---or what another
154 program was doing at the moment it crashed.
156 _GDBN__ can do four main kinds of things (plus other things in support of
157 these) to help you catch bugs in the act:
161 Start your program, specifying anything that might affect its behavior.
164 Make your program stop on specified conditions.
167 Examine what has happened, when your program has stopped.
170 Change things in your program, so you can experiment with correcting the
171 effects of one bug and go on to learn about another.
174 _GDBN__ can be used to debug programs written in C and C++. Pascal support
175 is being implemented, and Fortran support will be added when a GNU
176 Fortran compiler is ready.
179 * Free Software:: Free Software
180 * Contributors:: Contributors to GDB
183 @node Free Software, Contributors, Summary, Summary
184 @unnumberedsec Free Software
185 _GDBN__ is @dfn{free software}, protected by the GNU General Public License (GPL).
186 The GPL gives you the freedom to copy or adapt a licensed
187 program---but every person getting a copy also gets with it the
188 freedom to modify that copy (which means that they must get access to
189 the source code), and the freedom to distribute further copies.
190 Typical software companies use copyrights to limit your freedoms; the
191 Free Software Foundation uses the GPL to preserve these freedoms.
193 Fundamentally, the General Public License is a license which says that
194 you have these freedoms and that you can't take these freedoms away
197 @c FIXME: (passim) go through all xrefs, expanding to use text headings
198 For full details, @pxref{Copying}.
199 @node Contributors, , Free Software, Summary
200 @unnumberedsec Contributors to GDB
202 Richard Stallman was the original author of GDB, as with many GNU
203 programs. Many others have contributed to its development. This
204 section attempts to credit major contributors. One of the virtues of
205 free software is that everyone is free to contribute to it; with
206 regret, we cannot actually acknowledge everyone here. The file
207 @file{ChangeLog} in the GDB distribution approximates a blow-by-blow
210 Changes much prior to version 2.0 are lost in the mists of time.
213 @emph{Plea:} Additions to this section are particularly welcome. If you
214 or your friends (or enemies; let's be evenhanded) have been unfairly
215 omitted from this list, we would like to add your names!
218 So that they may not regard their long labor as thankless, we
219 particularly thank those who shepherded GDB through major releases:
220 John Gilmore (release 4.0); Jim Kingdon (releases 3.9, 3.5, 3.4, 3.3);
221 and Randy Smith (releases 3.2, 3.1, 3.0). As major maintainer of GDB
222 for some period, each contributed significantly to the structure,
223 stability, and capabilities of the entire debugger.
225 Richard Stallman, assisted at various times by Pete TerMaat, Chris
226 Hanson, and Richard Mlynarik, handled releases through 2.8.
228 Michael Tiemann is the author of most of the GNU C++ support in GDB,
229 with significant additional contributions from Per Bothner. James
230 Clark wrote the GNU C++ demangler. Early work on C++ was by Peter
231 TerMaat (who also did much general update work leading to release 3.0).
233 GDB 4.0 uses the BFD subroutine library to examine multiple
234 object-file formats; BFD was a joint project of V. Gumby
235 Henkel-Wallace, Rich Pixley, Steve Chamberlain, and John Gilmore.
237 David Johnson wrote the original COFF support; Pace Willison did
238 the original support for encapsulated COFF.
240 Adam de Boor and Bradley Davis contributed the ISI Optimum V support.
241 Per Bothner, Noboyuki Hikichi, and Alessandro Forin contributed MIPS
242 support. Jean-Daniel Fekete contributed Sun 386i support. Chris
243 Hanson improved the HP9000 support. Noboyuki Hikichi and Tomoyuki
244 Hasei contributed Sony/News OS 3 support. David Johnson contributed
245 Encore Umax support. Jyrki Kuoppala contributed Altos 3068 support.
246 Keith Packard contributed NS32K support. Doug Rabson contributed
247 Acorn Risc Machine support. Chris Smith contributed Convex support
248 (and Fortran debugging). Jonathan Stone contributed Pyramid support.
249 Michael Tiemann contributed SPARC support. Tim Tucker contributed
250 support for the Gould NP1 and Gould Powernode. Pace Willison
251 contributed Intel 386 support. Jay Vosburgh contributed Symmetry
254 Rich Schaefer helped with support of SunOS shared libraries.
256 Jay Fenlason and Roland McGrath ensured that GDB and GAS agree about
257 several machine instruction sets.
259 Patrick Duval, Ted Goldstein, Vikram Koka and Glenn Engel helped
260 develop remote debugging. Intel Corporation and Wind River Systems
261 contributed remote debugging modules for their products.
263 Brian Fox is the author of the readline libraries providing
264 command-line editing and command history.
266 @node New Features, Sample Session, Summary, Top
267 @unnumbered New Features since _GDBN__ version 3.5
271 Using the new command @code{target}, you can select at runtime whether
272 you are debugging local files, local processes, standalone systems over
273 a serial port, realtime systems over a TCP/IP connection, etc.
274 Internally, _GDBN__ now uses a function vector to mediate access to
275 different targets; if you need to add your own support for a remote
276 protocol, this makes it much easier.
279 _GDBN__ now sports watchpoints as well as breakpoints. You can use a
280 watchpoint to stop execution whenever the value of an expression
281 changes, without having to predict a particular place in your program
282 where this may happen.
284 @item Object Code Formats
285 _GDBN__ uses a new scheme called Binary File Descriptors (BFD) to permit
286 it to switch dynamically, without reconfiguration or recompilation,
287 between different object-file formats. Formats currently supported are
288 COFF, a.out, and the Intel 960 b.out; files may be read as .o's, archive
289 libraries, or core dumps. BFD is available as a subroutine library so
290 that other programs may take advantage of it, and the other GNU binary
291 utilities are being converted to use it.
294 Compile-time configuration (to select a particular architecture and
295 operating system) is much easier. The script @code{config.gdb} now
296 handles specification of separate host and target configurations.
299 The user interface to _GDBN__'s control variables has been simplified
300 and consolidated in two commands, @code{set} and @code{show}. Output
301 lines are now broken at readable places, rather than overflowing onto
302 the next line. You can suppress output of machine-level addresses,
303 displaying only source language information.
306 @item Source Language
307 _GDBN__ now has limited support for C++ exception handling: _GDBN__ can
308 break when an exception is raised, before the stack is peeled back to
309 the exception handler's context.
311 @item Command Rationalization
312 Many _GDBN__ commands have been renamed to make them easier to remember
313 and use. In particular, the subcommands of @code{info} and
314 @code{show}/@code{set} are grouped to make the former refer to the state
315 of your program, and the latter refer to the state of _GDBN__ itself.
316 @xref{Renamed Commands}, for details on what commands were renamed.
319 _GDBN__ has been ported to the following new architectures: AT&T 3b1,
320 Acorn RISC machine, HP300 running HPUX, big- and little-endian MIPS
321 machines, Motorola 88k, Sun 386i, and Sun 3 running SunOS 4. In
322 addition, the following are supported as targets only: AMD 29k, Intel
323 960, and Wind River's VxWorks.
325 @item Shared Libraries
326 _GDBN__ 4.0 supports SunOS shared libraries.
328 @item Work in Progress
329 Kernel debugging for BSD and Mach systems; Tahoe and HPPA architecture
334 @node Sample Session, Invocation, New Features, Top
335 @chapter A Sample _GDBN__ Session
337 You can use this manual at your leisure to read all about _GDBN__.
338 However, a handful of commands are enough to get started using the
339 debugger. This chapter illustrates these commands.
342 In this sample session, we emphasize user input like this: @i{input},
343 to make it easier to pick out from the surrounding output.
346 @c FIXME: this example may not be appropriate for some configs, where
347 @c FIXME...primary interest is in remote use.
349 One of the preliminary versions of GNU @code{m4} (a generic macro
350 processor) exhibits the following bug: sometimes, when we change its
351 quote strings from the default, the commands used to capture one macro's
352 definition in another stop working. In the following short @code{m4}
353 session, we define a macro @code{foo} which expands to @code{0000}; we
354 then use the @code{m4} builtin @code{defn} to define @code{bar} as the
355 same thing. However, when we change the open quote string to
356 @code{<QUOTE>} and the close quote string to @code{<UNQUOTE>}, the same
357 procedure fails to define a new synonym @code{baz}:
366 @i{define(bar,defn(`foo'))}
370 @i{changequote(<QUOTE>,<UNQUOTE>)}
372 @i{define(baz,defn(<QUOTE>foo<UNQUOTE>))}
375 m4: End of input: 0: fatal error: EOF in string
379 Let's use _GDBN__ to try to see what's going on.
383 Reading symbol data from m4...done.
388 _GDBN__ only reads enough symbol data to know where to find the rest
389 when needed; as a result, the first prompt comes up very quickly. We
390 then tell _GDBN__ to use a narrower display width than usual, so
391 that examples will fit in this manual.
394 (_GDBP__) @i{set width 70}
398 Let's see how the @code{m4} builtin @code{changequote} works.
399 Having looked at the source, we know the relevant subroutine is
400 @code{m4_changequote}, so we set a breakpoint there with _GDBN__'s
401 @code{break} command.
404 (_GDBP__) @i{break m4_changequote}
405 Breakpoint 1 at 0x62f4: file builtin.c, line 879.
409 Using the @code{run} command, we start @code{m4} running under _GDBN__
410 control; as long as control does not reach the @code{m4_changequote}
411 subroutine, the program runs as usual:
415 Starting program: /work/Editorial/gdb/gnu/m4/m4
423 To trigger the breakpoint, we call @code{changequote}. _GDBN__
424 suspends execution of @code{m4}, displaying information about the
425 context where it stops.
428 @i{changequote(<QUOTE>,<UNQUOTE>)}
430 Breakpoint 1, m4_changequote (argc=3, argv=0x33c70) at builtin.c:879
431 879 if (bad_argc(TOKEN_DATA_TEXT(argv[0]), argc, 1, 3))
435 Now we use the command @code{n} (@code{next}) to advance execution to
436 the next line of the current function.
440 882 set_quotes((argc >= 2) ? TOKEN_DATA_TEXT(argv[1]) : nil,
444 @code{set_quotes} looks like a promising subroutine. We can go into it
445 by using the command @code{s} (@code{step}) instead of @code{next}.
446 @code{step} goes to the next line to be executed in @emph{any}
447 subroutine, so it steps into @code{set_quotes}.
451 set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>")
453 530 if (lquote != def_lquote)
457 The summary display showing the subroutine where @code{m4} is now
458 suspended (and its arguments) is called a stack frame display. We can
459 use the @code{backtrace} command (which can also be spelled @code{bt}),
460 to see where we are in the stack: it displays a stack frame for each
465 #0 set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>")
467 #1 0x6344 in m4_changequote (argc=3, argv=0x33c70) at builtin.c:882
468 #2 0x8174 in expand_macro (sym=0x33320) at macro.c:242
469 #3 0x7a88 in expand_token (obs=0x0, t=209696, td=0xf7fffa30)
471 #4 0x79dc in expand_input () at macro.c:40
472 #5 0x2930 in main (argc=0, argv=0xf7fffb20) at m4.c:195
476 Let's step through a few more lines to see what happens. The first two
477 times, we can use @samp{s}; the next two times we use @code{n} to avoid
478 falling into the @code{xstrdup} subroutine.
481 0x3b5c 532 if (rquote != def_rquote)
483 0x3b80 535 lquote = (lq == nil || *lq == '\0') ? def_lquote :\
486 536 rquote = (rq == nil || *rq == '\0') ? def_rquote : xstrdup\
489 538 len_lquote = strlen(rquote);
493 The last line displayed looks a little odd; let's examine the variables
494 @code{lquote} and @code{rquote} to see if they are in fact the new left
495 and right quotes we specified. We can use the command @code{p}
496 (@code{print}) to see their values.
499 (_GDBP__) @i{p lquote}
500 $1 = 0x35d40 "<QUOTE>"
501 (_GDBP__) @i{p rquote}
502 $2 = 0x35d50 "<UNQUOTE>"
506 @code{lquote} and @code{rquote} are indeed the new left and right quotes.
507 Let's look at some context; we can display ten lines of source
508 surrounding the current line, with the @code{l} (@code{list}) command.
514 535 lquote = (lq == nil || *lq == '\0') ? def_lquote : xstrdup\
516 536 rquote = (rq == nil || *rq == '\0') ? def_rquote : xstrdup\
519 538 len_lquote = strlen(rquote);
520 539 len_rquote = strlen(lquote);
527 Let's step past the two lines that set @code{len_lquote} and
528 @code{len_rquote}, and then examine the values of those variables.
532 539 len_rquote = strlen(lquote);
535 (_GDBP__) @i{p len_lquote}
537 (_GDBP__) @i{p len_rquote}
542 That certainly looks wrong, assuming @code{len_lquote} and
543 @code{len_rquote} are meant to be the lengths of @code{lquote} and
544 @code{rquote} respectively. Let's try setting them to better values.
545 We can use the @code{p} command for this, since it'll print the value of
546 any expression---and that expression can include subroutine calls and
550 (_GDBP__) p len_lquote=strlen(lquote)
552 (_GDBP__) p len_rquote=strlen(rquote)
557 Let's see if that fixes the problem of using the new quotes with the
558 @code{m4} built-in @code{defn}. We can allow @code{m4} to continue
559 executing with the @code{c} (@code{continue}) command, and then try the
560 example that caused trouble initially:
566 @i{define(baz,defn(<QUOTE>foo<UNQUOTE>))}
573 Success! The new quotes now work just as well as the default ones. The
574 problem seems to have been just the two typos defining the wrong
575 lengths. We'll let @code{m4} exit by giving it an EOF as input.
579 Program exited normally.
583 The message @samp{Program exited normally.} is from _GDBN__; it
584 indicates @code{m4} has finished executing. We can end our _GDBN__
585 session with the _GDBN__ @code{quit} command.
591 _1__@end smallexample
594 @node Invocation, Commands, Sample Session, Top
595 @chapter Getting In and Out of _GDBN__
598 * Starting _GDBN__:: Starting _GDBN__
599 * Leaving _GDBN__:: Leaving _GDBN__
600 * Shell Commands:: Shell Commands
603 @node Starting _GDBN__, Leaving _GDBN__, Invocation, Invocation
604 @section Starting _GDBN__
606 _GDBN__ is invoked with the shell command @code{_GDBP__}. Once started,
607 it reads commands from the terminal until you tell it to exit.
609 You can run @code{_GDBP__} with no arguments or options; but the most
610 usual way to start _GDBN__ is with one argument or two, specifying an
611 executable program as the argument:
616 You can also start with both an executable program and a core file specified:
622 You can further control how _GDBN__ starts up by using command-line
623 options. _GDBN__ itself can remind you of the options available:
628 will display all available options and briefly describe their use
629 (@samp{_GDBP__ -h} is a shorter equivalent).
631 All options and command line arguments you give are processed
632 in sequential order. The order makes a difference when the
633 @samp{-x} option is used.
636 * File Options:: Choosing Files
637 * Mode Options:: Choosing Modes
641 * i960-Nindy Remote::
649 @node File Options, Mode Options, Starting _GDBN__, Starting _GDBN__
650 @subsection Choosing Files
652 As shown above, any arguments other than options specify an executable
653 file and core file; that is, the first argument encountered with no
654 associated option flag is equivalent to a @samp{-se} option, and the
655 second, if any, is equivalent to a @samp{-c} option. Many options have
656 both long and short forms; both are shown here. The long forms are also
657 recognized if you truncate them, so long as enough of the option is
658 present to be unambiguous. (If you prefer, you can flag option
659 arguments with @samp{+} rather than @samp{-}, though we illustrate the
660 more usual convention.)
663 @item -symbols=@var{file}
665 Read symbol table from file @var{file}.
667 @item -exec=@var{file}
669 Use file @var{file} as the executable file to execute when
670 appropriate, and for examining pure data in conjunction with a core
674 Read symbol table from file @var{file} and use it as the executable
677 @item -core=@var{file}
679 Use file @var{file} as a core dump to examine.
681 @item -command=@var{file}
683 Execute _GDBN__ commands from file @var{file}. @xref{Command Files}.
685 @item -directory=@var{directory}
686 @itemx -d @var{directory}
687 Add @var{directory} to the path to search for source files.
690 @node Mode Options, i960-Nindy Remote, File Options, Starting _GDBN__
691 @subsection Choosing Modes
696 Do not execute commands from any @file{_GDBINIT__} initialization files.
697 Normally, the commands in these files are executed after all the
698 command options and arguments have been processed. @xref{Command
703 ``Quiet''. Do not print the introductory and copyright messages. These
704 messages are also suppressed in batch mode, or if an executable file name is
705 specified on the _GDBN__ command line.
708 Run in batch mode. Exit with status @code{0} after processing all the command
709 files specified with @samp{-x} (and @file{_GDBINIT__}, if not inhibited).
710 Exit with nonzero status if an error occurs in executing the _GDBN__
711 commands in the command files.
713 Batch mode may be useful for running _GDBN__ as a filter, for example to
714 download and run a program on another computer; in order to make this
715 more useful, the message
717 Program exited normally.
720 (which is ordinarily issued whenever a program running under _GDBN__ control
721 terminates) is not issued when running in batch mode.
723 @item -cd @var{directory}
724 Run _GDBN__ using @var{directory} as its working directory,
725 instead of the current directory.
729 This option is used when Emacs runs _GDBN__ as a subprocess. It tells _GDBN__
730 to output the full file name and line number in a standard,
731 recognizable fashion each time a stack frame is displayed (which
732 includes each time the program stops). This recognizable format looks
733 like two @samp{\032} characters, followed by the file name, line number
734 and character position separated by colons, and a newline. The
735 Emacs-to-_GDBN__ interface program uses the two @samp{\032} characters as
736 a signal to display the source code for the frame.
739 Set the line speed (baud rate or bits per second) of any serial
740 interface used by _GDBN__ for remote debugging.
742 @item -tty @var{device}
743 Run using @var{device} for your program's standard input and output.
744 @c FIXME: kingdon thinks there's more to -tty. Investigate.
749 @c This text diverted to "Remote Debugging" section in general case;
750 @c however, if we're doing a manual specifically for one of these, it
751 @c belongs up front (in "Getting In and Out" chapter).
754 @node i960-Nindy Remote, EB29K Remote, Mode Options, Starting _GDBN__
755 @subsection _GDBN__ with a Remote i960 (Nindy)
759 @dfn{Nindy} is a ROM Monitor program for Intel 960 target systems. When
760 _GDBN__ is configured to control a remote Intel 960 using Nindy, you can
761 tell _GDBN__ how to connect to the 960 in several ways:
765 Through command line options specifying serial port, version of the
766 Nindy protocol, and communications speed;
769 By responding to a prompt on startup;
772 By using the @code{target} command at any point during your _GDBN__
773 session. @xref{Target Commands}.
778 * Nindy Startup:: Startup with Nindy
779 * Nindy Options:: Options for Nindy
780 * Nindy reset:: Nindy Reset Command
783 @node Nindy Startup, Nindy Options, i960-Nindy Remote, i960-Nindy Remote
784 @subsubsection Startup with Nindy
786 If you simply start @code{_GDBN__} without using any command-line
787 options, you are prompted for what serial port to use, @emph{before} you
788 reach the ordinary _GDBN__ prompt:
790 Attach /dev/ttyNN -- specify NN, or "quit" to quit:
793 Respond to the prompt with whatever suffix (after @samp{/dev/tty})
794 identifies the serial port you want to use. You can, if you choose,
795 simply start up with no Nindy connection by responding to the prompt
796 with an empty line. If you do this, and later wish to attach to Nindy,
797 use @code{target} (@pxref{Target Commands}).
799 @node Nindy Options, Nindy reset, Nindy Startup, i960-Nindy Remote
800 @subsubsection Options for Nindy
802 These are the startup options for beginning your _GDBN__ session with a
803 Nindy-960 board attached:
807 Specify the serial port name of a serial interface to be used to connect
808 to the target system. This option is only available when _GDBN__ is
809 configured for the Intel 960 target architecture. You may specify
810 @var{port} as any of: a full pathname (e.g. @samp{-r /dev/ttya}), a
811 device name in @file{/dev} (e.g. @samp{-r ttya}), or simply the unique
812 suffix for a specific @code{tty} (e.g. @samp{-r a}).
815 (An uppercase letter ``O'', not a zero.) Specify that _GDBN__ should use
816 the ``old'' Nindy monitor protocol to connect to the target system.
817 This option is only available when _GDBN__ is configured for the Intel 960
821 @emph{Warning:} if you specify @samp{-O}, but are actually trying to
822 connect to a target system that expects the newer protocol, the connection
823 will fail, appearing to be a speed mismatch. _GDBN__ will repeatedly
824 attempt to reconnect at several different line speeds. You can abort
825 this process with an interrupt.
829 Specify that _GDBN__ should first send a @code{BREAK} signal to the target
830 system, in an attempt to reset it, before connecting to a Nindy target.
833 @emph{Warning:} Many target systems do not have the hardware that this
834 requires; it only works with a few boards.
839 The standard @samp{-b} option controls the line speed used on the serial
843 @node Nindy reset, , Nindy Options, i960-Nindy Remote
844 @subsubsection Nindy Reset Command
848 For a Nindy target, this command sends a ``break'' to the remote target
849 system; this is only useful if the target has been equipped with a
850 circuit to perform a hard reset (or some other interesting action) when
857 @node EB29K Remote, VxWorks Remote, i960-Nindy Remote, Starting _GDBN__
858 @subsection _GDBN__ with a Remote EB29K
861 @cindex running 29K programs
863 To use _GDBN__ from a Unix system to run programs on AMD's EB29K
864 board in a PC, you must first connect a serial cable between the PC
865 and a serial port on the Unix system. In the following, we assume
866 you've hooked the cable between the PC's @file{COM1} port and
867 @file{/dev/ttya} on the Unix system.
870 * Comms (EB29K):: Communications Setup
871 * _GDBP__-EB29K:: EB29K cross-debugging
872 * Remote Log:: Remote Log
875 @node Comms (EB29K), _GDBP__-EB29K, EB29K Remote, EB29K Remote
876 @subsubsection Communications Setup
877 The next step is to set up the PC's port, by doing something like the
878 following in DOS on the PC:
880 C:\> MODE com1:9600,n,8,1,none
883 This example---run on an MS DOS 4.0 system---sets the PC port to 9600
884 bps, no parity, eight data bits, one stop bit, and no ``retry'' action;
885 you must match the communications parameters when establishing the Unix
886 end of the connection as well.
887 @c FIXME: Who knows what this "no retry action" crud from the DOS manual may
888 @c mean? It's optional; leave it out? ---pesch@cygnus.com, 25feb91
890 To give control of the PC to the Unix side of the serial line, type
891 the following at the DOS console:
896 (Later, if you wish to return control to the DOS console, you can use
897 the command @code{CTTY con}---but you must send it over the device that
898 had control, in our example over the @file{COM1} serial line).
900 From the Unix host, use a communications program such as @code{tip} or
901 @code{cu} to communicate with the PC; for example,
903 cu -s 9600 -l /dev/ttya
906 The @code{cu} options shown specify, respectively, the linespeed and the
907 serial port to use. If you use @code{tip} instead, your command line
908 may look something like the following:
913 Your system may define a different name where our example uses
914 @file{/dev/ttya} as the argument to @code{tip}. The communications
915 parameters, including what port to use, are associated with the
916 @code{tip} argument in the ``remote'' descriptions file---normally the
917 system table @file{/etc/remote}.
918 @c FIXME: What if anything needs doing to match the "n,8,1,none" part of
919 @c the DOS side's comms setup? cu can support -o (odd
920 @c parity), -e (even parity)---apparently no settings for no parity or
921 @c for character size. Taken from stty maybe...? John points out tip
922 @c can set these as internal variables, eg ~s parity=none; man stty
923 @c suggests that it *might* work to stty these options with stdin or
924 @c stdout redirected... ---pesch@cygnus.com, 25feb91
927 Using the @code{tip} or @code{cu} connection, change the DOS working
928 directory to the directory containing a copy of your 29K program, then
929 start the PC program @code{EBMON} (an EB29K control program supplied
930 with your board by AMD). You should see an initial display from
931 @code{EBMON} similar to the one that follows, ending with the
932 @code{EBMON} prompt @samp{#}---
936 G:\> CD \usr\joe\work29k
938 G:\USR\JOE\WORK29K> EBMON
939 Am29000 PC Coprocessor Board Monitor, version 3.0-18
940 Copyright 1990 Advanced Micro Devices, Inc.
941 Written by Gibbons and Associates, Inc.
943 Enter '?' or 'H' for help
945 PC Coprocessor Type = EB29K
947 Memory Base = 0xd0000
949 Data Memory Size = 2048KB
950 Available I-RAM Range = 0x8000 to 0x1fffff
951 Available D-RAM Range = 0x80002000 to 0x801fffff
954 Register Stack Size = 0x800
955 Memory Stack Size = 0x1800
958 Am29027 Available = No
959 Byte Write Available = Yes
964 Then exit the @code{cu} or @code{tip} program (done in the example by
965 typing @code{~.} at the @code{EBMON} prompt). @code{EBMON} will keep
966 running, ready for _GDBN__ to take over.
968 For this example, we've assumed what is probably the most convenient
969 way to make sure the same 29K program is on both the PC and the Unix
970 system: a PC/NFS connection that establishes ``drive @code{G:}'' on the
971 PC as a file system on the Unix host. If you don't have PC/NFS or
972 something similar connecting the two systems, you must arrange some
973 other way---perhaps floppy-disk transfer---of getting the 29K program
974 from the Unix system to the PC; _GDBN__ will @emph{not} download it over the
977 @node _GDBP__-EB29K, Remote Log, Comms (EB29K), EB29K Remote
978 @subsubsection EB29K cross-debugging
979 Finally, @code{cd} to the directory containing an image of your 29K
980 program on the Unix system, and start _GDBN__---specifying as argument the
981 name of your 29K program:
986 Now you can use the @code{target} command:
988 target amd-eb /dev/ttya 9600 MYFOO
990 @c FIXME: test above 'target amd-eb' as spelled, with caps! caps are meant to
991 @c emphasize that this is the name as seen by DOS (since I think DOS is
992 @c single-minded about case of letters). ---pesch@cygnus.com, 25feb91
995 In this example, we've assumed your program is in a file called
996 @file{myfoo}. Note that the filename given as the last argument to
997 @code{target amd-eb} should be the name of the program as it appears to DOS.
998 In our example this is simply @code{MYFOO}, but in general it can include
999 a DOS path, and depending on your transfer mechanism may not resemble
1000 the name on the Unix side.
1002 At this point, you can set any breakpoints you wish; when you're ready
1003 to see your program run on the 29K board, use the _GDBN__ command
1006 To stop debugging the remote program, use the _GDBN__ @code{detach}
1009 To return control of the PC to its console, use @code{tip} or @code{cu}
1010 once again, after your _GDBN__ session has concluded, to attach to
1011 @code{EBMON}. You can then type the command @code{q} to shut down
1012 @code{EBMON}, returning control to the DOS command-line interpreter.
1013 Type @code{CTTY con} to return command input to the main DOS console,
1014 and type @kbd{~.} to leave @code{tip} or @code{cu}.
1016 @node Remote Log, , _GDBP__-EB29K, EB29K Remote
1017 @subsubsection Remote Log
1019 @cindex log file for EB29K
1020 The @code{target amd-eb} command creates a file @file{eb.log} in the
1021 current working directory, to help debug problems with the connection.
1022 @file{eb.log} records all the output from @code{EBMON}, including echoes
1023 of the commands sent to it. Running @samp{tail -f} on this file in
1024 another window often helps to understand trouble with @code{EBMON}, or
1025 unexpected events on the PC side of the connection.
1029 @node VxWorks Remote, , EB29K Remote, Starting _GDBN__
1030 @subsection _GDBN__ and VxWorks
1032 _GDBN__ enables developers to spawn and debug tasks running on networked
1033 VxWorks targets from a Unix host. Already-running tasks spawned from
1034 the VxWorks shell can also be debugged. _GDBN__ uses code that runs on
1035 both the UNIX host and on the VxWorks target. The program
1036 @code{_GDBP__} is installed and executed on the UNIX host.
1038 The remote debugging interface (RDB) routines are installed and executed
1039 on the VxWorks target. These routines are included in the VxWorks library
1040 @file{rdb.a} and are incorporated into the system image when source-level
1041 debugging is enabled in the VxWorks configuration.
1043 @kindex{INCLUDE_RDB}
1044 Defining @code{INCLUDE_RDB} in the VxWorks configuration file
1045 @file{configAll.h} includes the RDB interface routines and spawns the
1046 source debugging task @code{tRdbTask} when VxWorks is booted. For more
1047 information on configuring and remaking VxWorks, see the @cite{VxWorks
1048 Programmer's Guide}.
1050 Once you have included the RDB interface in your VxWorks system image
1051 and set your Unix execution search path to find _GDBN__, you are ready
1052 to run _GDBN__. From your UNIX host, type:
1058 _GDBN__ will come up showing the prompt:
1065 * VxWorks connection:: Connecting to VxWorks
1066 * VxWorks download:: VxWorks Download
1067 * VxWorks attach:: Running Tasks
1070 @node VxWorks connection, VxWorks download, VxWorks Remote, VxWorks Remote
1071 @subsubsection Connecting to VxWorks
1073 The _GDBN__ command @code{target} lets you connect to a VxWorks target on the
1074 network. To connect to a target whose host name is ``@code{tt}'', type:
1077 (_GDBP__) target vxworks tt
1080 _GDBN__ will display a message similar to the following:
1083 Attaching remote machine across net... Success!
1086 _GDBN__ will then attempt to read the symbol tables of any object
1087 modules loaded into the VxWorks target since it was last booted.
1088 _GDBN__ locates these files by searching the directories listed in the
1089 command search path (@pxref{Environment}); if it fails to find an
1090 object file, it will display a message such as:
1093 prog.o: No such file or directory.
1096 This will cause the @code{target} command to abort. When this happens,
1097 you should add the appropriate directory to the search path, with the
1098 _GDBN__ command @code{path}, and execute the @code{target} command
1101 @node VxWorks download, VxWorks attach, VxWorks connection, VxWorks Remote
1102 @subsubsection VxWorks Download
1104 @cindex download to VxWorks
1105 If you have connected to the VxWorks target and you want to debug an
1106 object that has not yet been loaded, you can use the _GDBN__ @code{load}
1107 command to download a file from UNIX to VxWorks incrementally. The
1108 object file given as an argument to the @code{load} command is actually
1109 opened twice: first by the VxWorks target in order to download the code,
1110 then by _GDBN__ in order to read the symbol table. This can lead to
1111 problems if the current working directories on the two systems differ.
1112 It is simplest to set the working directory on both systems to the
1113 directory in which the object file resides, and then to reference the
1114 file by its name, without any path. Thus, to load a program
1115 @file{prog.o}, residing in @file{wherever/vw/demo/rdb}, on VxWorks type:
1118 -> cd "wherever/vw/demo/rdb"
1124 (_GDBP__) cd wherever/vw/demo/rdb
1125 (_GDBP__) load prog.o
1128 _GDBN__ will display a response similar to the following:
1131 Reading symbol data from wherever/vw/demo/rdb/prog.o... done.
1134 You can also use the @code{load} command to reload an object module
1135 after editing and recompiling the corresponding source file. Note that
1136 this will cause _GDBN__ to delete all currently-defined breakpoints,
1137 auto-displays, and convenience variables, and to clear the value
1138 history. (This is necessary in order to preserve the integrity of
1139 debugger data structures that reference the target system's symbol
1142 @node VxWorks attach, , VxWorks download, VxWorks Remote
1143 @subsubsection Running Tasks
1145 @cindex running VxWorks tasks
1146 You can also attach to an existing task using the @code{attach} command as
1150 (_GDBP__) attach @var{task}
1153 where @var{task} is the VxWorks hexadecimal task ID. The task can be running
1154 or suspended when you attach to it. If running, it will be suspended at
1155 the time of attachment.
1160 @c end of text diverted to section "Remote Debugging" for general case
1163 @node Leaving _GDBN__, Shell Commands, Starting _GDBN__, Invocation
1164 @section Leaving _GDBN__
1165 @cindex exiting _GDBN__
1170 To exit _GDBN__, use the @code{quit} command (abbreviated @code{q}), or type
1171 an end-of-file character (usually @kbd{C-d}).
1175 An interrupt (often @kbd{C-c}) will not exit from _GDBN__, but rather
1176 will terminate the action of any _GDBN__ command that is in progress and
1177 return to _GDBN__ command level. It is safe to type the interrupt
1178 character at any time because _GDBN__ does not allow it to take effect
1179 until a time when it is safe.
1181 If you've been using _GDBN__ to control an attached process or device,
1182 you can release it with the @code{detach} command; @pxref{Attach}.
1184 @node Shell Commands, , Leaving _GDBN__, Invocation
1185 @section Shell Commands
1186 If you just need to execute occasional shell commands during your
1187 debugging session, there's no need to leave or suspend _GDBN__; you can
1188 just use the @code{shell} command.
1191 @item shell @var{command string}
1193 @cindex shell escape
1194 Directs _GDBN__ to invoke an inferior shell to execute @var{command
1195 string}. If it exists, the environment variable @code{SHELL} is used
1196 for the name of the shell to run. Otherwise _GDBN__ uses
1200 The utility @code{make} is often needed in development environments.
1201 You don't have to use the @code{shell} command for this purpose in _GDBN__:
1204 @item make @var{make-args}
1206 @cindex calling make
1207 Causes _GDBN__ to execute an inferior @code{make} program with the specified
1208 arguments. This is equivalent to @samp{shell make @var{make-args}}.
1211 @node Commands, Running, Invocation, Top
1212 @chapter _GDBN__ Commands
1215 * Command Syntax:: Command Syntax
1216 * Help:: Getting Help
1219 @node Command Syntax, Help, Commands, Commands
1220 @section Command Syntax
1221 A _GDBN__ command is a single line of input. There is no limit on how long
1222 it can be. It starts with a command name, which is followed by arguments
1223 whose meaning depends on the command name. For example, the command
1224 @code{step} accepts an argument which is the number of times to step,
1225 as in @samp{step 5}. You can also use the @code{step} command with
1226 no arguments. Some command names do not allow any arguments.
1228 @cindex abbreviation
1229 _GDBN__ command names may always be truncated if that abbreviation is
1230 unambiguous. Other possible command abbreviations are listed in the
1231 documentation for individual commands. Sometimes even ambiguous
1232 abbreviations are allowed; for example, @code{s} is specially defined as
1233 equivalent to @code{step} even though there are other commands whose
1234 names start with @code{s}.
1236 @cindex repeating commands
1237 A blank line as input to _GDBN__ means to repeat the previous command.
1238 Certain commands (for example, @code{run}) will not repeat this way;
1239 these are commands for which unintentional repetition might cause
1240 trouble and which you are unlikely to want to repeat.
1242 The @code{list} and @code{x} commands construct new arguments when
1243 repeated, rather than repeating exactly as typed, to permit easy
1244 scanning of source or memory.
1248 A line of input starting with @kbd{#} is a comment; it does nothing.
1249 This is useful mainly in command files (@xref{Command Files}).
1251 @node Help, , Command Syntax, Commands
1252 @section Getting Help
1253 @cindex online documentation
1255 You can always ask _GDBN__ itself for information on its commands, using the
1256 command @code{help}.
1262 You can use @code{help} (abbreviated @code{h}) with no arguments to
1263 display a short list of named categories of commands:
1266 List of classes of commands:
1268 running -- Running the program
1269 stack -- Examining the stack
1270 data -- Examining data
1271 breakpoints -- Making program stop at certain points
1272 files -- Specifying and examining files
1273 status -- Status inquiries
1274 support -- Support facilities
1275 user-defined -- User-defined commands
1276 aliases -- Aliases of other commands
1277 obscure -- Obscure features
1279 Type "help" followed by a class name for a list of commands in that class.
1280 Type "help" followed by command name for full documentation.
1281 Command name abbreviations are allowed if unambiguous.
1285 @item help @var{category}
1286 Using one of the general help categories as an argument, you can get a
1287 list of the individual commands in a category. For example, here is the
1288 help display for category @code{status}:
1290 (_GDBP__) help status
1295 show -- Generic command for showing things set with "set"
1296 info -- Generic command for printing status
1298 Type "help" followed by command name for full documentation.
1299 Command name abbreviations are allowed if unambiguous.
1303 @item help @var{command}
1304 With a command name as @code{help} argument, _GDBN__ will display a
1305 short paragraph on how to use that command.
1308 In addition to @code{help}, you can use the _GDBN__ commands @code{info}
1309 and @code{show} to inquire about the state of your program, or the state
1310 of _GDBN__ itself. Both commands support many topics of inquiry; this
1311 manual introduces each of them in the appropriate context. The listings
1312 under @code{info} and under @code{show} in the Index point to
1313 all the sub-commands.
1314 @c FIXME: @pxref{Index} used to be here, but even though it shows up in
1315 @c FIXME...the 'aux' file with a pageno the xref can't find it.
1321 This command (abbreviated @code{i}) is for describing the state of your
1322 program; for example, it can list the arguments given to your program
1323 (@code{info args}), the registers currently in use (@code{info
1324 registers}), or the breakpoints you've set (@code{info breakpoints}).
1325 You can get a complete list of the @code{info} sub-commands with
1330 In contrast, @code{show} is for describing the state of _GDBN__ itself.
1331 You can change most of the things you can @code{show}, by using the
1332 related command @code{set}; for example, you can control what number
1333 system is used for displays with @code{set radix}, or simply inquire
1334 which is currently in use with @code{show radix}.
1337 To display all the settable parameters and their current
1338 values, you can use @code{show} with no arguments; you may also use
1339 @code{info set}. Both commands produce the same display.
1340 @c FIXME: "info set" violates the rule that "info" is for state of
1341 @c FIXME...program. Ck w/ GNU: "info set" to be called something else,
1342 @c FIXME...or change desc of rule---eg "state of prog and debugging session"?
1345 Here are three miscellaneous @code{show} subcommands, all of which are
1346 exceptional in lacking corresponding @code{set} commands:
1349 @kindex show version
1351 Show what version of _GDBN__ is running. You should include this
1352 information in _GDBN__ bug-reports. If multiple versions of _GDBN__ are
1353 in use at your site, you may occasionally want to make sure what version
1354 of _GDBN__ you're running; as _GDBN__ evolves, new commands are
1355 introduced, and old ones may wither away. The version number is also
1356 announced when you start _GDBN__ with no arguments.
1358 @kindex show copying
1360 Display information about permission for copying _GDBN__.
1362 @kindex show warranty
1364 Display the GNU ``NO WARRANTY'' statement.
1367 @node Running, Stopping, Commands, Top
1368 @chapter Running Programs Under _GDBN__
1371 * Compilation:: Compiling for Debugging
1372 * Starting:: Starting your Program
1373 * Arguments:: Your Program's Arguments
1374 * Environment:: Your Program's Environment
1375 * Working Directory:: Your Program's Working Directory
1376 * Input/Output:: Your Program's Input and Output
1377 * Attach:: Debugging an Already-Running Process
1378 * Kill Process:: Killing the Child Process
1381 @node Compilation, Starting, Running, Running
1382 @section Compiling for Debugging
1384 In order to debug a program effectively, you need to generate
1385 debugging information when you compile it. This debugging information
1386 is stored in the object file; it describes the data type of each
1387 variable or function and the correspondence between source line numbers
1388 and addresses in the executable code.
1390 To request debugging information, specify the @samp{-g} option when you run
1393 Many C compilers are unable to handle the @samp{-g} and @samp{-O}
1394 options together. Using those compilers, you cannot generate optimized
1395 executables containing debugging information.
1397 The GNU C compiler supports @samp{-g} with or without @samp{-O}, making it
1398 possible to debug optimized code. We recommend that you @emph{always} use
1399 @samp{-g} whenever you compile a program. You may think the program is
1400 correct, but there's no sense in pushing your luck.
1402 Some things do not work as well with @samp{-g -O} as with just
1403 @samp{-g}, particularly on machines with instruction scheduling. If in
1404 doubt, recompile with @samp{-g} alone, and if this fixes the problem,
1405 please report it as a bug (including a test case!).
1407 Older versions of the GNU C compiler permitted a variant option
1408 @samp{-gg} for debugging information. _GDBN__ no longer supports this
1409 format; if your GNU C compiler has this option, do not use it.
1412 @comment As far as I know, there are no cases in which _GDBN__ will
1413 @comment produce strange output in this case. (but no promises).
1414 If your program includes archives made with the @code{ar} program, and
1415 if the object files used as input to @code{ar} were compiled without the
1416 @samp{-g} option and have names longer than 15 characters, _GDBN__ will get
1417 confused reading the program's symbol table. No error message will be
1418 given, but _GDBN__ may behave strangely. The reason for this problem is a
1419 deficiency in the Unix archive file format, which cannot represent file
1420 names longer than 15 characters.
1422 To avoid this problem, compile the archive members with the @samp{-g}
1423 option or use shorter file names. Alternatively, use a version of GNU
1424 @code{ar} dated more recently than August 1989.
1428 @node Starting, Arguments, Compilation, Running
1429 @section Starting your Program
1436 Use the @code{run} command to start your program under _GDBN__.
1438 Except on VxWorks, you
1443 must first specify the program name with an argument to _GDBN__
1444 (@pxref{Invocation}), or using the @code{file} or @code{exec-file}
1445 command (@pxref{Files}).@refill
1448 On targets that support processes, @code{run} creates an inferior
1449 process and makes that process run your program. On other targets,
1450 @code{run} jumps to the start of the program.
1452 The execution of a program is affected by certain information it
1453 receives from its superior. _GDBN__ provides ways to specify this
1454 information, which you must do @i{before} starting the program. (You
1455 can change it after starting the program, but such changes will only affect
1456 the program the next time you start it.) This information may be
1457 divided into four categories:
1460 @item The @i{arguments.}
1461 You specify the arguments to give your program as the arguments of the
1462 @code{run} command. If a shell is available on your target, the shell
1463 is used to pass the arguments, so that you may use normal conventions
1464 (such as wildcard expansion or variable substitution) in
1465 describing the arguments. In Unix systems, you can control which shell
1466 is used with the @code{SHELL} environment variable. @xref{Arguments}.@refill
1468 @item The @i{environment.}
1469 Your program normally inherits its environment from _GDBN__, but you can
1470 use the _GDBN__ commands @code{set environment} and @code{unset
1471 environment} to change parts of the environment that will be given to
1472 the program. @xref{Environment}.@refill
1474 @item The @i{working directory.}
1475 Your program inherits its working directory from _GDBN__. You can set
1476 _GDBN__'s working directory with the @code{cd} command in _GDBN__.
1477 @xref{Working Directory}.
1479 @item The @i{standard input and output.}
1480 Your program normally uses the same device for standard input and
1481 standard output as _GDBN__ is using. You can redirect input and output
1482 in the @code{run} command line, or you can use the @code{tty} command to
1483 set a different device for your program.
1484 @xref{Input/Output}.
1487 When you issue the @code{run} command, your program begins to execute
1488 immediately. @xref{Stopping}, for discussion of how to arrange for your
1489 program to stop. Once your program has been started by the @code{run}
1490 command (and then stopped), you may evaluate expressions that involve
1491 calls to functions in the inferior, using the @code{print} or
1492 @code{call} commands. @xref{Data}.
1494 If the modification time of your symbol file has changed since the last
1495 time _GDBN__ read its symbols, _GDBN__ will discard its symbol table and re-read
1496 it. In this process, it tries to retain your current breakpoints.
1498 @node Arguments, Environment, Starting, Running
1499 @section Your Program's Arguments
1501 @cindex arguments (to your program)
1502 The arguments to your program can be specified by the arguments of the
1503 @code{run} command. They are passed to a shell, which expands wildcard
1504 characters and performs redirection of I/O, and thence to the program.
1505 _GDBN__ uses the shell indicated by your environment variable
1506 @code{SHELL} if it exists; otherwise, _GDBN__ uses @code{/bin/sh}.
1508 @code{run} with no arguments uses the same arguments used by the previous
1509 @code{run}, or those set by the @code{set args} command.
1514 Specify the arguments to be used the next time your program is run. If
1515 @code{set args} has no arguments, @code{run} will execute your program
1516 with no arguments. Once you have run your program with arguments, this
1517 is the only way to run it again without arguments.
1521 Show the arguments to give your program when it is started.
1524 @node Environment, Working Directory, Arguments, Running
1525 @section Your Program's Environment
1527 @cindex environment (of your program)
1528 The @dfn{environment} consists of a set of environment variables and
1529 their values. Environment variables conventionally record such things as
1530 your user name, your home directory, your terminal type, and your search
1531 path for programs to run. Usually you set up environment variables with
1532 the shell and they are inherited by all the other programs you run. When
1533 debugging, it can be useful to try running the program with a modified
1534 environment without having to start _GDBN__ over again.
1537 @item path @var{directory}
1539 Add @var{directory} to the front of the @code{PATH} environment variable
1540 (the search path for executables), for both _GDBN__ and your program.
1541 You may specify several directory names, separated by @samp{:} or
1542 whitespace. If @var{directory} is already in the path, it is moved to
1543 the front, so it will be searched sooner. You can use the string
1544 @samp{$cwd} to refer to whatever is the current working directory at the
1545 time _GDBN__ searches the path. @footnote{If you use @samp{.} instead,
1546 it refers to the directory where you executed the @code{path} command.
1547 _GDBN__ fills in the current path where needed in the @var{directory}
1548 argument, before adding it to the search path.}
1549 @c 'path' is explicitly nonrepeatable, but RMS points out it's silly to
1550 @c document that, since repeating it would be a no-op.
1554 Display the list of search paths for executables (the @code{PATH}
1555 environment variable).
1557 @item show environment @var{varname}
1558 @kindex show environment
1559 Print the value of environment variable @var{varname} to be given to
1560 your program when it starts.
1562 @item show environment
1563 Print the names and values of all environment variables to be given to
1566 @item set environment @var{varname} @var{value}
1567 @itemx set environment @var{varname} = @var{value}
1568 @kindex set environment
1569 Sets environment variable @var{varname} to @var{value}. The value
1570 changes for your program only, not for _GDBN__ itself. @var{value} may
1571 be any string; the values of environment variables are just strings, and
1572 any interpretation is supplied by your program itself. The @var{value}
1573 parameter is optional; if it is eliminated, the variable is set to a
1575 @c "any string" here doesn't include leading, trailing
1576 @c blanks. Gnu asks: does anyone care?
1578 For example, this command:
1585 tells a Unix program, when subsequently run, that its user is named
1586 @samp{foo}. (The spaces around @samp{=} are used for clarity here; they
1587 are not actually required.)
1589 @item unset environment @var{varname}
1590 @kindex unset environment
1591 Remove variable @var{varname} from the environment to be passed to your
1592 program. This is different from @samp{set env @var{varname} =};
1593 @code{unset environment} removes the variable from the environment,
1594 rather than assigning it an empty value.
1597 @node Working Directory, Input/Output, Environment, Running
1598 @section Your Program's Working Directory
1600 @cindex working directory (of your program)
1601 Each time you start your program with @code{run}, it inherits its
1602 working directory from the current working directory of _GDBN__. _GDBN__'s
1603 working directory is initially whatever it inherited from its parent
1604 process (typically the shell), but you can specify a new working
1605 directory in _GDBN__ with the @code{cd} command.
1607 The _GDBN__ working directory also serves as a default for the commands
1608 that specify files for _GDBN__ to operate on. @xref{Files}.
1611 @item cd @var{directory}
1613 Set _GDBN__'s working directory to @var{directory}.
1617 Print _GDBN__'s working directory.
1620 @node Input/Output, Attach, Working Directory, Running
1621 @section Your Program's Input and Output
1626 @cindex controlling terminal
1627 By default, the program you run under _GDBN__ does input and output to
1628 the same terminal that _GDBN__ uses. _GDBN__ switches the terminal to
1629 its own terminal modes to interact with you, but it records the terminal
1630 modes your program was using and switches back to them when you continue
1631 running your program.
1635 @kindex info terminal
1636 Displays _GDBN__'s recorded information about the terminal modes your
1640 You can redirect the program's input and/or output using shell
1641 redirection with the @code{run} command. For example,
1648 starts the program, diverting its output to the file @file{outfile}.
1651 Another way to specify where the program should do input and output is
1652 with the @code{tty} command. This command accepts a file name as
1653 argument, and causes this file to be the default for future @code{run}
1654 commands. It also resets the controlling terminal for the child
1655 process, for future @code{run} commands. For example,
1662 directs that processes started with subsequent @code{run} commands
1663 default to do input and output on the terminal @file{/dev/ttyb} and have
1664 that as their controlling terminal.
1666 An explicit redirection in @code{run} overrides the @code{tty} command's
1667 effect on the input/output device, but not its effect on the controlling
1670 When you use the @code{tty} command or redirect input in the @code{run}
1671 command, only the input @emph{for your program} is affected. The input
1672 for _GDBN__ still comes from your terminal.
1674 @node Attach, Kill Process, Input/Output, Running
1675 @section Debugging an Already-Running Process
1680 @item attach @var{process-id}
1682 attaches to a running process---one that was started outside _GDBN__.
1683 (@code{info files} will show your active targets.) The command takes as
1684 argument a process ID. The usual way to find out the process-id of
1685 a Unix process is with the @code{ps} utility, or with the @samp{jobs -l}
1688 @code{attach} will not repeat if you press @key{RET} a second time after
1689 executing the command.
1692 To use @code{attach}, you must be debugging in an environment which
1693 supports processes. You must also have permission to send the process a
1694 signal, and it must have the same effective user ID as the _GDBN__
1697 When using @code{attach}, you should first use the @code{file} command
1698 to specify the program running in the process and load its symbol table.
1701 The first thing _GDBN__ does after arranging to debug the specified
1702 process is to stop it. You can examine and modify an attached process
1703 with all the _GDBN__ commands that ordinarily available when you start
1704 processes with @code{run}. You can insert breakpoints; you can step and
1705 continue; you can modify storage. If you would rather the process
1706 continue running, you may use the @code{continue} command after
1707 attaching _GDBN__ to the process.
1712 When you have finished debugging the attached process, you can use the
1713 @code{detach} command to release it from _GDBN__'s control. Detaching
1714 the process continues its execution. After the @code{detach} command,
1715 that process and _GDBN__ become completely independent once more, and you
1716 are ready to @code{attach} another process or start one with @code{run}.
1717 @code{detach} will not repeat if you press @key{RET} again after
1718 executing the command.
1721 If you exit _GDBN__ or use the @code{run} command while you have an attached
1722 process, you kill that process. By default, you will be asked for
1723 confirmation if you try to do either of these things; you can control
1724 whether or not you need to confirm by using the @code{set confirm} command
1725 (@pxref{Messages/Warnings}).
1728 @node Kill Process, , Attach, Running
1729 @section Killing the Child Process
1734 Kill the child process in which your program is running under _GDBN__.
1737 This command is useful if you wish to debug a core dump instead of a
1738 running process. _GDBN__ ignores any core dump file while your program
1742 On some operating systems, you can't execute your program in another
1743 process while breakpoints are active inside _GDBN__. You can use the
1744 @code{kill} command in this situation to permit running the program
1745 outside the debugger.
1747 The @code{kill} command is also useful if you wish to recompile and
1748 relink the program, since on many systems it is impossible to modify an
1749 executable file which is running in a process. In this case, when you
1750 next type @code{run}, _GDBN__ will notice that the file has changed, and
1751 will re-read the symbol table (while trying to preserve your current
1752 breakpoint settings).
1754 @node Stopping, Stack, Running, Top
1755 @chapter Stopping and Continuing
1757 When you run a program normally, it runs until it terminates. The
1758 principal purpose of using a debugger is so that you can stop your
1759 program before it terminates; or so that, if the program runs into
1760 trouble, you can investigate and find out why.
1762 Inside _GDBN__, your program may stop for any of several reasons, such
1763 as a signal, a breakpoint, or reaching a new line after a _GDBN__
1764 command such as @code{step}. Usually, the messages shown by _GDBN__
1765 provide ample explanation of the status of your program---but you can
1766 also explicitly request this information at any time.
1770 @kindex info program
1771 Display information about the status of your program: whether it is
1772 running or not, what process it is, and why it stopped.
1776 * Breakpoints:: Breakpoints, Watchpoints, and Exceptions
1777 * Stepping:: Stepping
1778 * Continuing:: Continuing
1782 @node Breakpoints, Stepping, Stopping, Stopping
1783 @section Breakpoints, Watchpoints, and Exceptions
1786 A @dfn{breakpoint} makes your program stop whenever a certain point in
1787 the program is reached. For each breakpoint, you can add various
1788 conditions to control in finer detail whether the program will stop.
1789 You can set breakpoints with the @code{break} command and its variants
1790 (@pxref{Set Breaks}), to specify the place where the program should stop
1791 by line number, function name or exact address in the program. In
1792 languages with exception handling (such as GNU C++), you can also set
1793 breakpoints where an execption is raised (@pxref{Exception Handling}).
1796 A @dfn{watchpoint} is a special breakpoint that stops your program when
1797 the value of an expression changes. You must use a different command to
1798 set watchpoints (@pxref{Set Watchpoints}), but aside from that, you can
1799 manage a watchpoint exactly like any other breakpoint: you enable, disable, and
1800 delete both breakpoints and watchpoints using exactly the same commands.
1802 Each breakpoint or watchpoint is assigned a number when it is created;
1803 these numbers are successive integers starting with one. In many of the
1804 commands for controlling various features of breakpoints you use the
1805 breakpoint number to say which breakpoint you want to change. Each
1806 breakpoint may be @dfn{enabled} or @dfn{disabled}; if disabled, it has
1807 no effect on the program until you enable it again.
1810 * Set Breaks:: Setting Breakpoints
1811 * Set Watchpoints:: Setting Watchpoints
1812 * Exception Handling:: Breakpoints and Exceptions
1813 * Delete Breaks:: Deleting Breakpoints
1814 * Disabling:: Disabling Breakpoints
1815 * Conditions:: Break Conditions
1816 * Break Commands:: Breakpoint Command Lists
1817 * Breakpoint Menus:: Breakpoint Menus
1818 * Error in Breakpoints::
1821 @node Set Breaks, Set Watchpoints, Breakpoints, Breakpoints
1822 @subsection Setting Breakpoints
1826 Breakpoints are set with the @code{break} command (abbreviated @code{b}).
1828 You have several ways to say where the breakpoint should go.
1831 @item break @var{function}
1832 Set a breakpoint at entry to function @var{function}. When using source
1833 languages that permit overloading of symbols, such as C++,
1834 @var{function} may refer to more than one possible place to break.
1835 @xref{Breakpoint Menus}, for a discussion of that situation.
1837 @item break +@var{offset}
1838 @itemx break -@var{offset}
1839 Set a breakpoint some number of lines forward or back from the position
1840 at which execution stopped in the currently selected frame.
1842 @item break @var{linenum}
1843 Set a breakpoint at line @var{linenum} in the current source file.
1844 That file is the last file whose source text was printed. This
1845 breakpoint will stop the program just before it executes any of the
1848 @item break @var{filename}:@var{linenum}
1849 Set a breakpoint at line @var{linenum} in source file @var{filename}.
1851 @item break @var{filename}:@var{function}
1852 Set a breakpoint at entry to function @var{function} found in file
1853 @var{filename}. Specifying a file name as well as a function name is
1854 superfluous except when multiple files contain similarly named
1857 @item break *@var{address}
1858 Set a breakpoint at address @var{address}. You can use this to set
1859 breakpoints in parts of the program which do not have debugging
1860 information or source files.
1863 When called without any arguments, @code{break} sets a breakpoint at the
1864 next instruction to be executed in the selected stack frame
1865 (@pxref{Stack}). In any selected frame but the innermost, this will
1866 cause the program to stop as soon as control returns to that frame.
1867 This is similar to the effect of a @code{finish} command in the frame
1868 inside the selected frame---except that @code{finish} doesn't leave an
1869 active breakpoint. If you use @code{break} without an argument in the
1870 innermost frame, _GDBN__ will stop the next time it reaches the current
1871 location; this may be useful inside loops.
1873 _GDBN__ normally ignores breakpoints when it resumes execution, until at
1874 least one instruction has been executed. If it did not do this, you
1875 would be unable to proceed past a breakpoint without first disabling the
1876 breakpoint. This rule applies whether or not the breakpoint already
1877 existed when the program stopped.
1879 @item break @dots{} if @var{cond}
1880 Set a breakpoint with condition @var{cond}; evaluate the expression
1881 @var{cond} each time the breakpoint is reached, and stop only if the
1882 value is nonzero. @samp{@dots{}} stands for one of the possible
1883 arguments described above (or no argument) specifying where to break.
1884 @xref{Conditions}, for more information on breakpoint conditions.
1886 @item tbreak @var{args}
1888 Set a breakpoint enabled only for one stop. @var{args} are the
1889 same as in the @code{break} command, and the breakpoint is set in the same
1890 way, but the breakpoint is automatically disabled the first time it
1891 is hit. @xref{Disabling}.
1893 @item rbreak @var{regex}
1895 Set a breakpoint on all functions matching @var{regex}. This is
1896 useful for setting breakpoints on overloaded functions that are not
1897 members of any special classes. This command sets an unconditional
1898 breakpoint on all matches, printing a list of all breakpoints it set.
1899 Once these breakpoints are set, they are treated just like the
1900 breakpoints set with the @code{break} command. They can be deleted,
1901 disabled, made conditional, etc., in the standard ways.
1903 @kindex info breakpoints
1905 @item info breakpoints
1906 The command @code{info breakpoints} prints a list of all breakpoints
1907 (but not watchpoints) set and not deleted, showing their numbers, where
1908 in the program they are, and any special features in use for them.
1909 Disabled breakpoints are included in the list, but marked as disabled.
1910 @code{info break} with a breakpoint number as argument lists only that
1911 breakpoint. The convenience variable @code{$_} and the default
1912 examining-address for the @code{x} command are set to the address of the
1913 last breakpoint listed (@pxref{Memory}). The equivalent command for
1914 watchpoints is @code{info watch}.
1917 _GDBN__ allows you to set any number of breakpoints at the same place in the
1918 program. There is nothing silly or meaningless about this. When the
1919 breakpoints are conditional, this is even useful (@pxref{Conditions}).
1921 @node Set Watchpoints, Exception Handling, Set Breaks, Breakpoints
1922 @subsection Setting Watchpoints
1923 @cindex setting watchpoints
1924 You can use a watchpoint to stop execution whenever the value of an
1925 expression changes, without having to predict a particular place in the
1926 inferior process where this may happen.
1928 Watchpoints currently execute two orders of magnitude more slowly than
1929 other breakpoints, but this can well be worth it to catch errors where
1930 you have no clue what part of your program is the culprit. Some
1931 processors provide special hardware to implement this feature; future
1932 releases of _GDBN__ will use such hardware if it is available.
1936 @item watch @var{expr}
1937 Set a watchpoint for an expression.
1939 @kindex info watchpoints
1940 @item info watchpoints
1941 This command prints a list of watchpoints; it is otherwise similar to
1945 @node Exception Handling, Delete Breaks, Set Watchpoints, Breakpoints
1946 @subsection Breakpoints and Exceptions
1947 @cindex exception handlers
1949 Some languages, such as GNU C++, implement exception handling. _GDBN__
1950 can be used to examine what caused the program to raise an exception
1951 and to list the exceptions the program is prepared to handle at a
1952 given point in time.
1955 @item catch @var{exceptions}
1958 You can set breakpoints at active exception handlers by using the
1959 @code{catch} command. @var{exceptions} is a list of names of exceptions
1963 You can use @code{info catch} to list active exception handlers;
1966 There are currently some limitations to exception handling in _GDBN__.
1967 These will be corrected in a future release.
1971 If you call a function interactively, _GDBN__ normally returns
1972 control to you when the function has finished executing. If the call
1973 raises an exception, however, the call may bypass the mechanism that
1974 returns control to the user and cause the program to simply continue
1975 running until it hits a breakpoint, catches a signal that _GDBN__ is
1976 listening for, or exits.
1978 You cannot raise an exception interactively.
1980 You cannot interactively install an exception handler.
1983 @cindex raise exceptions
1984 Sometimes @code{catch} is not the best way to debug exception handling:
1985 if you need to know exactly where an exception is raised, it's better to
1986 stop @emph{before} the exception handler is called, since that way you
1987 can see the stack before any unwinding takes place. If you set a
1988 breakpoint in an exception handler instead, it may not be easy to find
1989 out where the exception was raised.
1991 To stop just before an exception handler is called, you need some
1992 knowledge of the implementation. In the case of GNU C++ exception are
1993 raised by calling a library function named @code{__raise_exception}
1994 which has the following ANSI C interface:
1997 /* ADDR is where the exception identifier is stored.
1998 ID is the exception identifier. */
1999 void __raise_exception (void **@var{addr}, void *@var{id});
2003 To make the debugger catch all exceptions before any stack
2004 unwinding takes place, set a breakpoint on @code{__raise_exception}
2005 (@pxref{Breakpoints}).
2007 With a conditional breakpoint (@xref{Conditions}) that depends on the
2008 value of @var{id}, you can stop your program when a specific exception
2009 is raised. You can use multiple conditional breakpoints to stop the
2010 program when any of a number of exceptions are raised.
2012 @node Delete Breaks, Disabling, Exception Handling, Breakpoints
2013 @subsection Deleting Breakpoints
2015 @cindex clearing breakpoints, watchpoints
2016 @cindex deleting breakpoints, watchpoints
2017 It is often necessary to eliminate a breakpoint or watchpoint once it
2018 has done its job and you no longer want the program to stop there. This
2019 is called @dfn{deleting} the breakpoint. A breakpoint that has been
2020 deleted no longer exists in any sense; it is forgotten.
2022 With the @code{clear} command you can delete breakpoints according to
2023 where they are in the program. With the @code{delete} command you can
2024 delete individual breakpoints or watchpoints by specifying their
2027 It is not necessary to delete a breakpoint to proceed past it. _GDBN__
2028 automatically ignores breakpoints on the first instruction to be executed
2029 when you continue execution without changing the execution address.
2034 Delete any breakpoints at the next instruction to be executed in the
2035 selected stack frame (@pxref{Selection}). When the innermost frame
2036 is selected, this is a good way to delete a breakpoint that the program
2039 @item clear @var{function}
2040 @itemx clear @var{filename}:@var{function}
2041 Delete any breakpoints set at entry to the function @var{function}.
2043 @item clear @var{linenum}
2044 @itemx clear @var{filename}:@var{linenum}
2045 Delete any breakpoints set at or within the code of the specified line.
2047 @item delete breakpoints @var{bnums}@dots{}
2048 @itemx delete @var{bnums}@dots{}
2050 @cindex delete breakpoints
2053 Delete the breakpoints or watchpoints of the numbers specified as
2054 arguments. If no argument is specified, delete all breakpoints. You
2055 can abbreviate this command as @code{d}.
2058 @node Disabling, Conditions, Delete Breaks, Breakpoints
2059 @subsection Disabling Breakpoints
2061 @cindex disabled breakpoints
2062 @cindex enabled breakpoints
2063 Rather than deleting a breakpoint or watchpoint, you might prefer to
2064 @dfn{disable} it. This makes the breakpoint inoperative as if it had
2065 been deleted, but remembers the information on the breakpoint so that
2066 you can @dfn{enable} it again later.
2068 You disable and enable breakpoints and watchpoints with the
2069 @code{enable} and @code{disable} commands, optionally specifying one or
2070 more breakpoint numbers as arguments. Use @code{info break} or
2071 @code{info watch} to print a list of breakpoints or watchpoints if you
2072 don't know which numbers to use.
2074 A breakpoint or watchpoint can have any of four different states of
2079 Enabled. The breakpoint will stop the program. A breakpoint made
2080 with the @code{break} command starts out in this state.
2082 Disabled. The breakpoint has no effect on the program.
2084 Enabled once. The breakpoint will stop the program, but
2085 when it does so it will become disabled. A breakpoint made
2086 with the @code{tbreak} command starts out in this state.
2088 Enabled for deletion. The breakpoint will stop the program, but
2089 immediately after it does so it will be deleted permanently.
2092 You can use the following commands to enable or disable breakpoints and
2096 @item disable breakpoints @var{bnums}@dots{}
2097 @itemx disable @var{bnums}@dots{}
2099 @kindex disable breakpoints
2102 Disable the specified breakpoints---or all breakpoints, if none are
2103 listed. A disabled breakpoint has no effect but is not forgotten. All
2104 options such as ignore-counts, conditions and commands are remembered in
2105 case the breakpoint is enabled again later. You may abbreviate
2106 @code{disable} as @code{dis}.
2108 @item enable breakpoints @var{bnums}@dots{}
2109 @itemx enable @var{bnums}@dots{}
2111 @kindex enable breakpoints
2113 Enable the specified breakpoints (or all defined breakpoints). They
2114 become effective once again in stopping the program, until you specify
2117 @item enable breakpoints once @var{bnums}@dots{}
2118 @itemx enable once @var{bnums}@dots{}
2119 Enable the specified breakpoints temporarily. Each will be disabled
2120 again the next time it stops the program (unless you have used one of
2121 these commands to specify a different state before that time comes).
2123 @item enable breakpoints delete @var{bnums}@dots{}
2124 @itemx enable delete @var{bnums}@dots{}
2125 Enable the specified breakpoints to work once and then die. Each of
2126 the breakpoints will be deleted the next time it stops the program
2127 (unless you have used one of these commands to specify a different
2128 state before that time comes).
2131 Save for a breakpoint set with @code{tbreak} (@pxref{Set Breaks}),
2132 breakpoints that you set initially enabled; subsequently, they become
2133 disabled or enabled only when you use one of the commands above. (The
2134 command @code{until} can set and delete a breakpoint of its own, but it
2135 will not change the state of your other breakpoints;
2138 @node Conditions, Break Commands, Disabling, Breakpoints
2139 @subsection Break Conditions
2140 @cindex conditional breakpoints
2141 @cindex breakpoint conditions
2143 The simplest sort of breakpoint breaks every time the program reaches a
2144 specified place. You can also specify a @dfn{condition} for a
2145 breakpoint. A condition is just a Boolean expression in your
2146 programming language. (@xref{Expressions}). A breakpoint with a
2147 condition evaluates the expression each time the program reaches it, and
2148 the program stops only if the condition is true.
2150 Conditions are also accepted for watchpoints; you may not need them,
2151 since a watchpoint is inspecting the value of an expression anyhow---but
2152 it might be simpler, say, to just set a watchpoint on a variable name,
2153 then have a condition that tests whether the new value is an interesting
2156 Break conditions may have side effects, and may even call functions in your
2157 program. These may sound like strange things to do, but their effects are
2158 completely predictable unless there is another enabled breakpoint at the
2159 same address. (In that case, _GDBN__ might see the other breakpoint first and
2160 stop the program without checking the condition of this one.) Note that
2161 breakpoint commands are usually more convenient and flexible for the
2162 purpose of performing side effects when a breakpoint is reached
2163 (@pxref{Break Commands}).
2165 Break conditions can be specified when a breakpoint is set, by using
2166 @samp{if} in the arguments to the @code{break} command. @xref{Set Breaks}.
2167 They can also be changed at any time with the @code{condition} command.
2168 The @code{watch} command doesn't recognize the @code{if} keyword;
2169 @code{condition} is the only way to impose a further condition on a
2173 @item condition @var{bnum} @var{expression}
2175 Specify @var{expression} as the break condition for breakpoint or
2176 watchpoint number @var{bnum}. From now on, this breakpoint will stop
2177 the program only if the value of @var{expression} is true (nonzero, in
2178 C). When you call @code{condition}, the expression you specify is
2179 checked immediately for syntactic correctness, and to determine whether
2180 symbols in it have referents in the context of your breakpoint. _GDBN__
2181 does not actually evaluate @var{expression} at the time the
2182 @code{condition} command is given, however. @xref{Expressions}.
2184 @item condition @var{bnum}
2185 Remove the condition from breakpoint number @var{bnum}. It becomes
2186 an ordinary unconditional breakpoint.
2189 @cindex ignore count (of breakpoint)
2190 A special case of a breakpoint condition is to stop only when the
2191 breakpoint has been reached a certain number of times. This is so
2192 useful that there is a special way to do it, using the @dfn{ignore
2193 count} of the breakpoint. Every breakpoint has an ignore count, which
2194 is an integer. Most of the time, the ignore count is zero, and
2195 therefore has no effect. But if the program reaches a breakpoint whose
2196 ignore count is positive, then instead of stopping, it just decrements
2197 the ignore count by one and continues. As a result, if the ignore count
2198 value is @var{n}, the breakpoint will not stop the next @var{n} times it
2202 @item ignore @var{bnum} @var{count}
2204 Set the ignore count of breakpoint number @var{bnum} to @var{count}.
2205 The next @var{count} times the breakpoint is reached, your program's
2206 execution will not stop; other than to decrement the ignore count, _GDBN__
2209 To make the breakpoint stop the next time it is reached, specify
2212 @item continue @var{count}
2213 @itemx c @var{count}
2214 @itemx fg @var{count}
2215 @kindex continue @var{count}
2216 Continue execution of the program, setting the ignore count of the
2217 breakpoint that the program stopped at to @var{count} minus one.
2218 Thus, the program will not stop at this breakpoint until the
2219 @var{count}'th time it is reached.
2221 An argument to this command is meaningful only when the program stopped
2222 due to a breakpoint. At other times, the argument to @code{continue} is
2225 The synonym @code{fg} is provided purely for convenience, and has
2226 exactly the same behavior as other forms of the command.
2229 If a breakpoint has a positive ignore count and a condition, the condition
2230 is not checked. Once the ignore count reaches zero, the condition will
2233 You could achieve the effect of the ignore count with a
2234 condition such as _0__@w{@samp{$foo-- <= 0}}_1__ using a debugger convenience
2235 variable that is decremented each time. @xref{Convenience Vars}.
2237 @node Break Commands, Breakpoint Menus, Conditions, Breakpoints
2238 @subsection Breakpoint Command Lists
2240 @cindex breakpoint commands
2241 You can give any breakpoint (or watchpoint) a series of commands to
2242 execute when the program stops due to that breakpoint. For example, you
2243 might want to print the values of certain expressions, or enable other
2247 @item commands @var{bnum}
2248 @itemx @dots{} @var{command-list} @dots{}
2252 Specify a list of commands for breakpoint number @var{bnum}. The commands
2253 themselves appear on the following lines. Type a line containing just
2254 @code{end} to terminate the commands.
2256 To remove all commands from a breakpoint, use the command
2257 @code{commands} and follow it immediately by @code{end}; that is, give
2260 With no @var{bnum} argument, @code{commands} refers to the last
2261 breakpoint or watchpoint set (not to the breakpoint most recently
2265 Pressing @key{RET} as a means of repeating the last _GDBN__ command is
2266 disabled from the time you enter @code{commands} to just after the
2267 corresponding @code{end}.
2269 You can use breakpoint commands to start the program up again. Simply
2270 use the @code{continue} command, or @code{step}, or any other command to
2271 resume execution. However, if you do this, any further commands in the
2272 same breakpoint's command list are ignored. When the program stops
2273 again, _GDBN__ will act according to the cause of that stop.
2276 If the first command specified is @code{silent}, the usual message about
2277 stopping at a breakpoint is not printed. This may be desirable for
2278 breakpoints that are to print a specific message and then continue.
2279 If the remaining commands too print nothing, you will see no sign that
2280 the breakpoint was reached at all. @code{silent} is not really a command;
2281 it is meaningful only at the beginning of the commands for a breakpoint.
2283 The commands @code{echo} and @code{output} that allow you to print precisely
2284 controlled output are often useful in silent breakpoints. @xref{Output}.
2286 For example, here is how you could use breakpoint commands to print the
2287 value of @code{x} at entry to @code{foo} whenever @code{x} is positive.
2300 One application for breakpoint commands is to correct one bug so you can
2301 test another. Put a breakpoint just after the erroneous line of code, give
2302 it a condition to detect the case in which something erroneous has been
2303 done, and give it commands to assign correct values to any variables that
2304 need them. End with the @code{continue} command so that the program does not
2305 stop, and start with the @code{silent} command so that no output is
2306 produced. Here is an example:
2318 One deficiency in the operation of automatically continuing breakpoints
2319 under Unix appears when your program uses raw mode for the terminal.
2320 _GDBN__ switches back to its own terminal modes (not raw) before executing
2321 commands, and then must switch back to raw mode when your program is
2322 continued. This causes any pending terminal input to be lost.
2323 In the GNU system, this will be fixed by changing the behavior of
2326 Under Unix, when you have this problem, you might be able to get around
2327 it by putting your actions into the breakpoint condition instead of
2328 commands. For example
2331 condition 5 (x = y + 4), 0
2335 specifies a condition expression (@xref{Expressions}) that will change
2336 @code{x} as needed, then always have the value zero so the program will not
2337 stop. Loss of input is avoided here because break conditions are
2338 evaluated without changing the terminal modes. When you want to have
2339 nontrivial conditions for performing the side effects, the operators
2340 @samp{&&}, @samp{||} and @samp{?@dots{}:} may be useful.
2342 @node Breakpoint Menus, Error in Breakpoints, Break Commands, Breakpoints
2343 @subsection Breakpoint Menus
2344 @cindex C++ overloading
2345 @cindex symbol overloading
2347 Some programming languages (notably C++) permit a single function name
2348 to be defined several times, for application in different contexts.
2349 This is called @dfn{overloading}. When a function name is overloaded,
2350 @samp{break @var{function}} is not enough to tell _GDBN__ where you want
2351 a breakpoint. _GDBN__ responds to this situation by offering you a menu
2352 of numbered choices for different possible breakpoints, and waiting for
2353 your selection with the prompt @samp{>}. The first two
2354 options are always @samp{[0] cancel} and @samp{[1] all}. Typing @kbd{1}
2355 will set a breakpoint at all the definitions available for
2356 @var{function}, and typing @kbd{0} will abort the @code{break} command
2357 without setting any new breakpoints.
2359 For example, the following session excerpt shows an attempt to set a
2360 breakpoint at the overloaded symbol @code{String::after}. In the
2361 example, we choose three particular definitions of the function:
2364 (_GDBP__) b String::after
2367 [2] file:String.cc; line number:867
2368 [3] file:String.cc; line number:860
2369 [4] file:String.cc; line number:875
2370 [5] file:String.cc; line number:853
2371 [6] file:String.cc; line number:846
2372 [7] file:String.cc; line number:735
2374 Breakpoint 1 at 0xb26c: file String.cc, line 867.
2375 Breakpoint 2 at 0xb344: file String.cc, line 875.
2376 Breakpoint 3 at 0xafcc: file String.cc, line 846.
2377 Multiple breakpoints were set.
2378 Use the "delete" command to delete unwanted breakpoints.
2383 @node Error in Breakpoints, , Breakpoint Menus, Breakpoints
2384 @subsection ``Cannot Insert Breakpoints''
2386 @c FIXME: "cannot insert breakpoints" error, v unclear.
2387 @c Q in pending mail to Gilmore. ---pesch@cygnus.com, 26mar91
2388 Under some operating systems, breakpoints cannot be used in a program if
2389 any other process is running that program. In this situation,
2390 attempting to run or continue a program with a breakpoint will cause _GDBN__
2391 to stop the other process.
2393 When this happens, you have three ways to proceed:
2397 Remove or disable the breakpoints, then continue.
2400 Suspend _GDBN__, and copy the file containing the program to a new name.
2401 Resume _GDBN__ and use the @code{exec-file} command to specify that _GDBN__
2402 should run the program under that name. Then start the program again.
2404 @c FIXME: RMS commented here "Show example". Maybe when someone
2405 @c explains the first FIXME: in this section...
2408 Relink the program so that the text segment is nonsharable, using the
2409 linker option @samp{-N}. The operating system limitation may not apply
2410 to nonsharable executables.
2413 @node Stepping, Continuing, Breakpoints, Stopping
2417 @dfn{Stepping} means setting your program in motion for a limited time,
2418 so that control will return automatically to _GDBN__ after one line of
2419 code or one machine instruction. @footnote{Your program might stop even
2420 sooner, during stepping, since a signal may arrive before your program
2421 reaches the next source line. Also, since breakpoints are active during
2422 stepping, your program will stop for them even if it has not gone as far
2423 as the stepping command specifies.}
2425 A typical technique for using stepping is to put a breakpoint
2426 (@pxref{Breakpoints}) at the beginning of the function or the section of
2427 the program in which a problem is believed to lie, run the program until
2428 it stops at that breakpoint, and then step through the suspect area,
2429 examining the variables that are interesting, until you see the problem
2436 Continue running the program until control reaches a different source
2437 line, then stop it and return control to the debugger. This command is
2438 abbreviated @code{s}.
2440 You may use the @code{step} command when control is within a function
2441 for which there is no debugging information. In that case, execution
2442 will proceed until control reaches a different function, or is about to
2443 return from this function.
2445 @item step @var{count}
2446 Continue running as in @code{step}, but do so @var{count} times. If a
2447 breakpoint is reached or a signal not related to stepping occurs before
2448 @var{count} steps, stepping stops right away.
2453 Continue to the next source line in the current stack frame. Similar to
2454 @code{step}, but any function calls appearing within the line of code
2455 are executed without stopping. Execution stops when control reaches a
2456 different line of code at the stack level which was executing when the
2457 @code{next} command was given. This command is abbreviated @code{n}.
2459 An argument is a repeat count, as in @code{step}.
2461 @code{next} within a function that lacks debugging information acts like
2462 @code{step}, but any function calls appearing within the code of the
2463 function are executed without stopping.
2467 Continue running until just after the selected stack frame returns (or
2468 until there is some other reason to stop, such as a fatal signal or a
2469 breakpoint). Print the value returned by the selected stack frame (if
2472 Contrast this with the @code{return} command (@pxref{Returning}).
2478 Continue running until a source line past the current line, in the
2479 current stack frame, is reached. This command is used to avoid single
2480 stepping through a loop more than once. It is like the @code{next}
2481 command, except that when @code{until} encounters a jump, it
2482 automatically continues execution until the program counter is greater
2483 than the address of the jump.
2485 This means that when you reach the end of a loop after single stepping
2486 though it, @code{until} will cause the program to continue execution
2487 until the loop is exited. In contrast, a @code{next} command at the end
2488 of a loop will simply step back to the beginning of the loop, which
2489 would force you to step through the next iteration.
2491 @code{until} always stops the program if it attempts to exit the current
2494 @code{until} may produce somewhat counterintuitive results if the order
2495 of the source lines does not match the actual order of execution. For
2496 example, in the following excerpt from a debugging session, the @code{f}
2497 (@code{frame}) command shows that execution is stopped at line
2498 @code{206}; yet when we use @code{until}, we get to line @code{195}:
2502 #0 main (argc=4, argv=0xf7fffae8) at m4.c:206
2505 195 for ( ; argc > 0; NEXTARG) @{
2508 In this case, (as for any C @code{for}-loop), the loop-step expression
2509 (here, @samp{argc > 0}) is executed @emph{after} the statements in the
2510 body of the loop, but is written before them. Therefore, the
2511 @code{until} command appeared to step back to the beginning of the loop
2512 when it advanced to this expression. However, it has not really gone to
2513 an earlier statement---not in terms of the actual machine code.
2515 @code{until} with no argument works by means of single
2516 instruction stepping, and hence is slower than @code{until} with an
2519 @item until @var{location}
2520 @item u @var{location}
2521 Continue running the program until either the specified location is
2522 reached, or the current (innermost) stack frame returns. @var{location}
2523 is any of the forms of argument acceptable to @code{break} (@pxref{Set
2524 Breaks}). This form of the command uses breakpoints, and hence is
2525 quicker than @code{until} without an argument.
2531 Execute one machine instruction, then stop and return to the debugger.
2533 It is often useful to do @samp{display/i $pc} when stepping by machine
2534 instructions. This will cause the next instruction to be executed to
2535 be displayed automatically at each stop. @xref{Auto Display}.
2537 An argument is a repeat count, as in @code{step}.
2543 Execute one machine instruction, but if it is a function call,
2544 proceed until the function returns.
2546 An argument is a repeat count, as in @code{next}.
2549 The @code{continue} command can be used after stepping to resume execution
2550 until the next breakpoint or signal.
2552 @node Continuing, Signals, Stepping, Stopping
2555 After your program stops, most likely you will want it to run some more if
2556 the bug you are looking for has not happened yet.
2561 Continue running the program at the place where it stopped.
2564 If the program stopped at a breakpoint, the place to continue running
2565 is the address of the breakpoint. You might expect that continuing would
2566 just stop at the same breakpoint immediately. In fact, @code{continue}
2567 takes special care to prevent that from happening. You do not need
2568 to disable the breakpoint to proceed through it after stopping there.
2569 You can, however, specify an ignore-count for the breakpoint that the
2570 program stopped at, by means of an argument to the @code{continue} command.
2573 If the program stopped because of a signal other than @code{SIGINT} or
2574 @code{SIGTRAP}, continuing will cause the program to see that signal.
2575 You may not want this to happen. For example, if the program stopped
2576 due to some sort of memory reference error, you might store correct
2577 values into the erroneous variables and continue, hoping to see more
2578 execution; but the program would probably terminate immediately as
2579 a result of the fatal signal once it sees the signal. To prevent this,
2580 you can continue with @samp{signal 0}. @xref{Signaling}. You can
2581 also act in advance to control what signals your program will see, using
2582 the @code{handle} command (@pxref{Signals}).
2584 @node Signals, , Continuing, Stopping
2588 A signal is an asynchronous event that can happen in a program. The
2589 operating system defines the possible kinds of signals, and gives each
2590 kind a name and a number. For example, in Unix @code{SIGINT} is the
2591 signal a program gets when you type an interrupt (often @kbd{C-c});
2592 @code{SIGSEGV} is the signal a program gets from referencing a place in
2593 memory far away from all the areas in use; @code{SIGALRM} occurs when
2594 the alarm clock timer goes off (which happens only if the program has
2595 requested an alarm).
2597 @cindex fatal signals
2598 Some signals, including @code{SIGALRM}, are a normal part of the
2599 functioning of the program. Others, such as @code{SIGSEGV}, indicate
2600 errors; these signals are @dfn{fatal} (kill the program immediately) if the
2601 program has not specified in advance some other way to handle the signal.
2602 @code{SIGINT} does not indicate an error in the program, but it is normally
2603 fatal so it can carry out the purpose of the interrupt: to kill the program.
2605 _GDBN__ has the ability to detect any occurrence of a signal in the program
2606 running under _GDBN__'s control. You can tell _GDBN__ in advance what to do for
2607 each kind of signal.
2609 @cindex handling signals
2610 Normally, _GDBN__ is set up to ignore non-erroneous signals like @code{SIGALRM}
2611 (so as not to interfere with their role in the functioning of the program)
2612 but to stop the program immediately whenever an error signal happens.
2613 You can change these settings with the @code{handle} command.
2617 @kindex info signals
2618 Print a table of all the kinds of signals and how _GDBN__ has been told to
2619 handle each one. You can use this to see the signal numbers of all
2620 the defined types of signals.
2622 @item handle @var{signal} @var{keywords}@dots{}
2624 Change the way _GDBN__ handles signal @var{signal}. @var{signal} can be the
2625 number of a signal or its name (with or without the @samp{SIG} at the
2626 beginning). The @var{keywords} say what change to make.
2630 The keywords allowed by the @code{handle} command can be abbreviated.
2631 Their full names are:
2635 _GDBN__ should not stop the program when this signal happens. It may
2636 still print a message telling you that the signal has come in.
2639 _GDBN__ should stop the program when this signal happens. This implies
2640 the @code{print} keyword as well.
2643 _GDBN__ should print a message when this signal happens.
2646 _GDBN__ should not mention the occurrence of the signal at all. This
2647 implies the @code{nostop} keyword as well.
2650 _GDBN__ should allow the program to see this signal; the program will be
2651 able to handle the signal, or may be terminated if the signal is fatal
2655 _GDBN__ should not allow the program to see this signal.
2659 When a signal has been set to stop the program, the program cannot see the
2660 signal until you continue. It will see the signal then, if @code{pass} is
2661 in effect for the signal in question @i{at that time}. In other words,
2662 after _GDBN__ reports a signal, you can use the @code{handle} command with
2663 @code{pass} or @code{nopass} to control whether that signal will be seen by
2664 the program when you later continue it.
2666 You can also use the @code{signal} command to prevent the program from
2667 seeing a signal, or cause it to see a signal it normally would not see,
2668 or to give it any signal at any time. @xref{Signaling}.
2671 @node Stack, Source, Stopping, Top
2672 @chapter Examining the Stack
2674 When your program has stopped, the first thing you need to know is where it
2675 stopped and how it got there.
2678 Each time your program performs a function call, the information about
2679 where in the program the call was made from is saved in a block of data
2680 called a @dfn{stack frame}. The frame also contains the arguments of the
2681 call and the local variables of the function that was called. All the
2682 stack frames are allocated in a region of memory called the @dfn{call
2685 When your program stops, the _GDBN__ commands for examining the stack allow you
2686 to see all of this information.
2688 @cindex selected frame
2689 One of the stack frames is @dfn{selected} by _GDBN__ and many _GDBN__ commands
2690 refer implicitly to the selected frame. In particular, whenever you ask
2691 _GDBN__ for the value of a variable in the program, the value is found in the
2692 selected frame. There are special _GDBN__ commands to select whichever frame
2693 you are interested in.
2695 When the program stops, _GDBN__ automatically selects the currently executing
2696 frame and describes it briefly as the @code{frame} command does
2697 (@pxref{Frame Info, Info}).
2700 * Frames:: Stack Frames
2701 * Backtrace:: Backtraces
2702 * Selection:: Selecting a Frame
2703 * Frame Info:: Information on a Frame
2706 @node Frames, Backtrace, Stack, Stack
2707 @section Stack Frames
2711 The call stack is divided up into contiguous pieces called @dfn{stack
2712 frames}, or @dfn{frames} for short; each frame is the data associated
2713 with one call to one function. The frame contains the arguments given
2714 to the function, the function's local variables, and the address at
2715 which the function is executing.
2717 @cindex initial frame
2718 @cindex outermost frame
2719 @cindex innermost frame
2720 When your program is started, the stack has only one frame, that of the
2721 function @code{main}. This is called the @dfn{initial} frame or the
2722 @dfn{outermost} frame. Each time a function is called, a new frame is
2723 made. Each time a function returns, the frame for that function invocation
2724 is eliminated. If a function is recursive, there can be many frames for
2725 the same function. The frame for the function in which execution is
2726 actually occurring is called the @dfn{innermost} frame. This is the most
2727 recently created of all the stack frames that still exist.
2729 @cindex frame pointer
2730 Inside your program, stack frames are identified by their addresses. A
2731 stack frame consists of many bytes, each of which has its own address; each
2732 kind of computer has a convention for choosing one of those bytes whose
2733 address serves as the address of the frame. Usually this address is kept
2734 in a register called the @dfn{frame pointer register} while execution is
2735 going on in that frame.
2737 @cindex frame number
2738 _GDBN__ assigns numbers to all existing stack frames, starting with
2739 zero for the innermost frame, one for the frame that called it,
2740 and so on upward. These numbers do not really exist in your program;
2741 they are assigned by _GDBN__ to give you a way of designating stack
2742 frames in _GDBN__ commands.
2744 @cindex frameless execution
2745 Some compilers allow functions to be compiled so that they operate
2746 without stack frames. (For example, the @code{_GCC__} option
2747 @samp{-fomit-frame-pointer} will generate functions without a frame.)
2748 This is occasionally done with heavily used library functions to save
2749 the frame setup time. _GDBN__ has limited facilities for dealing with
2750 these function invocations. If the innermost function invocation has no
2751 stack frame, _GDBN__ will nevertheless regard it as though it had a
2752 separate frame, which is numbered zero as usual, allowing correct
2753 tracing of the function call chain. However, _GDBN__ has no provision
2754 for frameless functions elsewhere in the stack.
2756 @node Backtrace, Selection, Frames, Stack
2759 A backtrace is a summary of how the program got where it is. It shows one
2760 line per frame, for many frames, starting with the currently executing
2761 frame (frame zero), followed by its caller (frame one), and on up the
2769 Print a backtrace of the entire stack: one line per frame for all
2770 frames in the stack.
2772 You can stop the backtrace at any time by typing the system interrupt
2773 character, normally @kbd{Control-C}.
2775 @item backtrace @var{n}
2777 Similar, but print only the innermost @var{n} frames.
2779 @item backtrace -@var{n}
2781 Similar, but print only the outermost @var{n} frames.
2787 The names @code{where} and @code{info stack} (abbreviated @code{info s})
2788 are additional aliases for @code{backtrace}.
2790 Each line in the backtrace shows the frame number and the function name.
2791 The program counter value is also shown---unless you use @code{set
2792 print address off}. The backtrace also shows the source file name and
2793 line number, as well as the arguments to the function. The program
2794 counter value is omitted if it is at the beginning of the code for that
2797 Here is an example of a backtrace. It was made with the command
2798 @samp{bt 3}, so it shows the innermost three frames.
2802 #0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8) at builtin.c:993
2803 #1 0x6e38 in expand_macro (sym=0x2b600) at macro.c:242
2804 #2 0x6840 in expand_token (obs=0x0, t=177664, td=0xf7fffb08)
2806 (More stack frames follow...)
2811 The display for frame zero doesn't begin with a program counter
2812 value, indicating that the program has stopped at the beginning of the
2813 code for line @code{993} of @code{builtin.c}.
2815 @node Selection, Frame Info, Backtrace, Stack
2816 @section Selecting a Frame
2818 Most commands for examining the stack and other data in the program work on
2819 whichever stack frame is selected at the moment. Here are the commands for
2820 selecting a stack frame; all of them finish by printing a brief description
2821 of the stack frame just selected.
2828 Select frame number @var{n}. Recall that frame zero is the innermost
2829 (currently executing) frame, frame one is the frame that called the
2830 innermost one, and so on. The highest-numbered frame is @code{main}'s
2833 @item frame @var{addr}
2835 Select the frame at address @var{addr}. This is useful mainly if the
2836 chaining of stack frames has been damaged by a bug, making it
2837 impossible for _GDBN__ to assign numbers properly to all frames. In
2838 addition, this can be useful when the program has multiple stacks and
2839 switches between them.
2842 On the SPARC architecture, @code{frame} needs two addresses to
2843 select an arbitrary frame: a frame pointer and a stack pointer.
2844 @c note to future updaters: this is conditioned on a flag
2845 @c FRAME_SPECIFICATION_DYADIC in the tm-*.h files, currently only used
2846 @c by SPARC, hence the specific attribution. Generalize or list all
2847 @c possibilities if more supported machines start doing this.
2852 Move @var{n} frames up the stack. For positive numbers @var{n}, this
2853 advances toward the outermost frame, to higher frame numbers, to frames
2854 that have existed longer. @var{n} defaults to one.
2859 Move @var{n} frames down the stack. For positive numbers @var{n}, this
2860 advances toward the innermost frame, to lower frame numbers, to frames
2861 that were created more recently. @var{n} defaults to one. You may
2862 abbreviate @code{down} as @code{do}.
2865 All of these commands end by printing two lines of output describing the
2866 frame. The first line shows the frame number, the function name, the
2867 arguments, and the source file and line number of execution in that
2868 frame. The second line shows the text of that source line. For
2873 #1 0x22f0 in main (argc=1, argv=0xf7fffbf4, env=0xf7fffbfc) at env.c:10
2874 10 read_input_file (argv[i]);
2877 After such a printout, the @code{list} command with no arguments will print
2878 ten lines centered on the point of execution in the frame. @xref{List}.
2881 @item up-silently @var{n}
2882 @itemx down-silently @var{n}
2883 @kindex down-silently
2885 These two commands are variants of @code{up} and @code{down},
2886 respectively; they differ in that they do their work silently, without
2887 causing display of the new frame. They are intended primarily for use
2888 in _GDBN__ command scripts, where the output might be unnecessary and
2893 @node Frame Info, , Selection, Stack
2894 @section Information About a Frame
2896 There are several other commands to print information about the selected
2902 When used without any argument, this command does not change which frame
2903 is selected, but prints a brief description of the currently
2904 selected stack frame. It can be abbreviated @code{f}. With an
2905 argument, this command is used to select a stack frame (@pxref{Selection}).
2911 This command prints a verbose description of the selected stack frame,
2912 including the address of the frame, the addresses of the next frame down
2913 (called by this frame) and the next frame up (caller of this frame),
2914 the address of the frame's arguments, the program counter saved in it
2915 (the address of execution in the caller frame), and which registers
2916 were saved in the frame. The verbose description is useful when
2917 something has gone wrong that has made the stack format fail to fit
2918 the usual conventions.
2920 @item info frame @var{addr}
2921 @itemx info f @var{addr}
2922 Print a verbose description of the frame at address @var{addr},
2923 without selecting that frame. The selected frame remains unchanged by
2928 Print the arguments of the selected frame, each on a separate line.
2932 Print the local variables of the selected frame, each on a separate
2933 line. These are all variables declared static or automatic within all
2934 program blocks that execution in this frame is currently inside of.
2938 @cindex catch exceptions
2939 @cindex exception handlers
2940 Print a list of all the exception handlers that are active in the
2941 current stack frame at the current point of execution. To see other
2942 exception handlers, visit the associated frame (using the @code{up},
2943 @code{down}, or @code{frame} commands); then type @code{info catch}.
2944 @xref{Exception Handling}.
2947 @node Source, Data, Stack, Top
2948 @chapter Examining Source Files
2950 _GDBN__ can print parts of your program's source, since the debugging
2951 information recorded in your program tells _GDBN__ what source files
2952 were used to built it. When your program stops, _GDBN__ spontaneously
2953 prints the line where it stopped. Likewise, when you select a stack
2954 frame (@pxref{Selection}), _GDBN__ prints the line where execution in
2955 that frame has stopped. You can print other portions of source files by
2958 If you use _GDBN__ through its GNU Emacs interface, you may prefer to
2959 use Emacs facilities to view source; @pxref{Emacs}.
2962 * List:: Printing Source Lines
2963 * Search:: Searching Source Files
2964 * Source Path:: Specifying Source Directories
2965 * Machine Code:: Source and Machine Code
2968 @node List, Search, Source, Source
2969 @section Printing Source Lines
2973 To print lines from a source file, use the @code{list} command
2974 (abbreviated @code{l}). There are several ways to specify what part
2975 of the file you want to print.
2977 Here are the forms of the @code{list} command most commonly used:
2980 @item list @var{linenum}
2981 Print ten lines centered around line number @var{linenum} in the
2982 current source file.
2984 @item list @var{function}
2985 Print ten lines centered around the beginning of function
2989 Print ten more lines. If the last lines printed were printed with a
2990 @code{list} command, this prints ten lines following the last lines
2991 printed; however, if the last line printed was a solitary line printed
2992 as part of displaying a stack frame (@pxref{Stack}), this prints ten
2993 lines centered around that line.
2996 Print ten lines just before the lines last printed.
2999 Repeating a @code{list} command with @key{RET} discards the argument,
3000 so it is equivalent to typing just @code{list}. This is more useful
3001 than listing the same lines again. An exception is made for an
3002 argument of @samp{-}; that argument is preserved in repetition so that
3003 each repetition moves up in the source file.
3006 In general, the @code{list} command expects you to supply zero, one or two
3007 @dfn{linespecs}. Linespecs specify source lines; there are several ways
3008 of writing them but the effect is always to specify some source line.
3009 Here is a complete description of the possible arguments for @code{list}:
3012 @item list @var{linespec}
3013 Print ten lines centered around the line specified by @var{linespec}.
3015 @item list @var{first},@var{last}
3016 Print lines from @var{first} to @var{last}. Both arguments are
3019 @item list ,@var{last}
3020 Print ten lines ending with @var{last}.
3022 @item list @var{first},
3023 Print ten lines starting with @var{first}.
3026 Print ten lines just after the lines last printed.
3029 Print ten lines just before the lines last printed.
3032 As described in the preceding table.
3035 Here are the ways of specifying a single source line---all the
3040 Specifies line @var{number} of the current source file.
3041 When a @code{list} command has two linespecs, this refers to
3042 the same source file as the first linespec.
3045 Specifies the line @var{offset} lines after the last line printed.
3046 When used as the second linespec in a @code{list} command that has
3047 two, this specifies the line @var{offset} lines down from the
3051 Specifies the line @var{offset} lines before the last line printed.
3053 @item @var{filename}:@var{number}
3054 Specifies line @var{number} in the source file @var{filename}.
3056 @item @var{function}
3057 @c FIXME: "of the open-brace" is C-centric. When we add other langs...
3058 Specifies the line of the open-brace that begins the body of the
3059 function @var{function}.
3061 @item @var{filename}:@var{function}
3062 Specifies the line of the open-brace that begins the body of the
3063 function @var{function} in the file @var{filename}. You only need the
3064 file name with a function name to avoid ambiguity when there are
3065 identically named functions in different source files.
3067 @item *@var{address}
3068 Specifies the line containing the program address @var{address}.
3069 @var{address} may be any expression.
3072 @node Search, Source Path, List, Source
3073 @section Searching Source Files
3075 @kindex reverse-search
3077 There are two commands for searching through the current source file for a
3081 @item forward-search @var{regexp}
3082 @itemx search @var{regexp}
3084 @kindex forward-search
3085 The command @samp{forward-search @var{regexp}} checks each line, starting
3086 with the one following the last line listed, for a match for @var{regexp}.
3087 It lists the line that is found. You can abbreviate the command name
3088 as @code{fo}. The synonym @samp{search @var{regexp}} is also supported.
3090 @item reverse-search @var{regexp}
3091 The command @samp{reverse-search @var{regexp}} checks each line, starting
3092 with the one before the last line listed and going backward, for a match
3093 for @var{regexp}. It lists the line that is found. You can abbreviate
3094 this command as @code{rev}.
3097 @node Source Path, Machine Code, Search, Source
3098 @section Specifying Source Directories
3101 @cindex directories for source files
3102 Executable programs sometimes do not record the directories of the source
3103 files from which they were compiled, just the names. Even when they do,
3104 the directories could be moved between the compilation and your debugging
3105 session. _GDBN__ has a list of directories to search for source files;
3106 this is called the @dfn{source path}. Each time _GDBN__ wants a source file,
3107 it tries all the directories in the list, in the order they are present
3108 in the list, until it finds a file with the desired name. Note that
3109 the executable search path is @emph{not} used for this purpose. Neither is
3110 the current working directory, unless it happens to be in the source
3113 If _GDBN__ can't find a source file in the source path, and the object
3114 program records a directory, _GDBN__ tries that directory too. If the
3115 source path is empty, and there is no record of the compilation
3116 directory, _GDBN__ will, as a last resort, look in the current
3119 Whenever you reset or rearrange the source path, _GDBN__ will clear out
3120 any information it has cached about where source files are found, where
3121 each line is in the file, etc.
3124 When you start _GDBN__, its source path is empty.
3125 To add other directories, use the @code{directory} command.
3128 @item directory @var{dirname} @dots{}
3129 Add directory @var{dirname} to the front of the source path. Several
3130 directory names may be given to this command, separated by @samp{:} or
3131 whitespace. You may specify a directory that is already in the source
3132 path; this moves it forward, so it will be searched sooner. You can use
3133 the string @samp{$cdir} to refer to the compilation directory (if one is
3134 recorded), and @samp{$cwd} to refer to the current working directory.
3135 @footnote{@samp{$cwd} is not the same as @samp{.}---the former tracks
3136 the current working directory as it changes during your _GDBN__ session,
3137 while the latter is immediately expanded to the current directory at the
3138 time you add an entry to the source path.}
3141 Reset the source path to empty again. This requires confirmation.
3143 @c RET-repeat for @code{directory} is explicitly disabled, but since
3144 @c repeating it would be a no-op we don't say that. (thanks to RMS)
3146 @item show directories
3147 @kindex show directories
3148 Print the source path: show which directories it contains.
3151 If your source path is cluttered with directories that are no longer of
3152 interest, _GDBN__ may sometimes cause confusion by finding the wrong
3153 versions of source. You can correct the situation as follows:
3157 Use @code{directory} with no argument to reset the source path to empty.
3160 Use @code{directory} with suitable arguments to reinstall the
3161 directories you want in the source path. You can add all the
3162 directories in one command.
3165 @node Machine Code, , Source Path, Source
3166 @section Source and Machine Code
3167 You can use the command @code{info line} to map source lines to program
3168 addresses (and viceversa), and the command @code{disassemble} to display
3169 a range of addresses as machine instructions.
3172 @item info line @var{linespec}
3174 Print the starting and ending addresses of the compiled code for
3175 source line @var{linespec}. You can specify source lines in any of the
3176 ways understood by the @code{list} command (@pxref{List}).
3179 For example, we can use @code{info line} to inquire on where the object
3180 code for the first line of function @code{m4_changequote} lies:
3182 (_GDBP__) info line m4_changecom
3183 Line 895 of "builtin.c" starts at pc 0x634c and ends at 0x6350.
3187 We can also inquire (using @code{*@var{addr}} as the form for
3188 @var{linespec}) what source line covers a particular address:
3190 (_GDBP__) info line *0x63ff
3191 Line 926 of "builtin.c" starts at pc 0x63e4 and ends at 0x6404.
3195 After @code{info line}, the default address for the @code{x}
3196 command is changed to the starting address of the line, so that
3197 @samp{x/i} is sufficient to begin examining the machine code
3198 (@pxref{Memory}). Also, this address is saved as the value of the
3199 convenience variable @code{$_} (@pxref{Convenience Vars}).
3204 This specialized command is provided to dump a range of memory as
3205 machine instructions. The default memory range is the function
3206 surrounding the program counter of the selected frame. A single
3207 argument to this command is a program counter value; the function
3208 surrounding this value will be dumped. Two arguments (separated by one
3209 or more spaces) specify a range of addresses (first inclusive, second
3210 exclusive) to be dumped.
3213 We can use @code{disassemble} to inspect the object code
3214 range shown in the last @code{info line} example:
3217 (_GDBP__) disas 0x63e4 0x6404
3218 Dump of assembler code from 0x63e4 to 0x6404:
3219 0x63e4 <builtin_init+5340>: ble 0x63f8 <builtin_init+5360>
3220 0x63e8 <builtin_init+5344>: sethi %hi(0x4c00), %o0
3221 0x63ec <builtin_init+5348>: ld [%i1+4], %o0
3222 0x63f0 <builtin_init+5352>: b 0x63fc <builtin_init+5364>
3223 0x63f4 <builtin_init+5356>: ld [%o0+4], %o0
3224 0x63f8 <builtin_init+5360>: or %o0, 0x1a4, %o0
3225 0x63fc <builtin_init+5364>: call 0x9288 <path_search>
3226 0x6400 <builtin_init+5368>: nop
3227 End of assembler dump.
3232 @node Data, Symbols, Source, Top
3233 @chapter Examining Data
3235 @cindex printing data
3236 @cindex examining data
3239 @c "inspect" isn't quite a synonym if you're using Epoch, which we don't
3240 @c document because it's nonstandard... Under Epoch it displays in a
3241 @c different window or something like that.
3242 The usual way to examine data in your program is with the @code{print}
3243 command (abbreviated @code{p}), or its synonym @code{inspect}. It
3244 evaluates and prints the value of any valid expression of the language
3245 the program is written in (for now, C or C++). You type
3252 where @var{exp} is any valid expression (in the source language), and
3253 the value of @var{exp} is printed in a format appropriate to its data
3256 A more low-level way of examining data is with the @code{x} command.
3257 It examines data in memory at a specified address and prints it in a
3258 specified format. @xref{Memory}.
3261 * Expressions:: Expressions
3262 * Variables:: Program Variables
3263 * Arrays:: Artificial Arrays
3264 * Output formats:: Output formats
3265 * Memory:: Examining Memory
3266 * Auto Display:: Automatic Display
3267 * Print Settings:: Print Settings
3268 * Value History:: Value History
3269 * Convenience Vars:: Convenience Variables
3270 * Registers:: Registers
3271 * Floating Point Hardware:: Floating Point Hardware
3274 @node Expressions, Variables, Data, Data
3275 @section Expressions
3278 @code{print} and many other _GDBN__ commands accept an expression and
3279 compute its value. Any kind of constant, variable or operator defined
3280 by the programming language you are using is legal in an expression in
3281 _GDBN__. This includes conditional expressions, function calls, casts
3282 and string constants. It unfortunately does not include symbols defined
3283 by preprocessor @code{#define} commands, or C++ expressions involving
3284 @samp{::}, the name resolution operator.
3285 @c FIXME: actually C++ a::b works except in obscure circumstances where it
3286 @c FIXME...can conflict with GDB's own name scope resolution.
3288 Casts are supported in all languages, not just in C, because it is so
3289 useful to cast a number into a pointer so as to examine a structure
3290 at that address in memory.
3292 _GDBN__ supports three kinds of operator in addition to those of programming
3297 @samp{@@} is a binary operator for treating parts of memory as arrays.
3298 @xref{Arrays}, for more information.
3301 @samp{::} allows you to specify a variable in terms of the file or
3302 function where it is defined. @xref{Variables}.
3304 @item @{@var{type}@} @var{addr}
3305 Refers to an object of type @var{type} stored at address @var{addr} in
3306 memory. @var{addr} may be any expression whose value is an integer or
3307 pointer (but parentheses are required around binary operators, just as in
3308 a cast). This construct is allowed regardless of what kind of data is
3309 normally supposed to reside at @var{addr}.@refill
3312 @node Variables, Arrays, Expressions, Data
3313 @section Program Variables
3315 The most common kind of expression to use is the name of a variable
3318 Variables in expressions are understood in the selected stack frame
3319 (@pxref{Selection}); they must either be global (or static) or be visible
3320 according to the scope rules of the programming language from the point of
3321 execution in that frame. This means that in the function
3336 the variable @code{a} is usable whenever the program is executing
3337 within the function @code{foo}, but the variable @code{b} is visible
3338 only while the program is executing inside the block in which @code{b}
3341 @cindex variable name conflict
3342 There is an exception: you can refer to a variable or function whose
3343 scope is a single source file even if the current execution point is not
3344 in this file. But it is possible to have more than one such variable or
3345 function with the same name (in different source files). If that happens,
3346 referring to that name has unpredictable effects. If you wish, you can
3347 specify a variable in a particular file, using the colon-colon notation:
3352 @var{file}::@var{variable}
3356 Here @var{file} is the name of the source file whose variable you want.
3358 @cindex C++ name resolution
3359 This use of @samp{::} is very rarely in conflict with the very similar
3360 use of the same notation in C++. _GDBN__ also supports use of the C++
3361 name resolution operator in _GDBN__ expressions.
3363 @node Arrays, Output formats, Variables, Data
3364 @section Artificial Arrays
3366 @cindex artificial array
3368 It is often useful to print out several successive objects of the
3369 same type in memory; a section of an array, or an array of
3370 dynamically determined size for which only a pointer exists in the
3373 This can be done by constructing an @dfn{artificial array} with the
3374 binary operator @samp{@@}. The left operand of @samp{@@} should be
3375 the first element of the desired array, as an individual object.
3376 The right operand should be the desired length of the array. The result is
3377 an array value whose elements are all of the type of the left argument.
3378 The first element is actually the left argument; the second element
3379 comes from bytes of memory immediately following those that hold the
3380 first element, and so on. Here is an example. If a program says
3383 int *array = (int *) malloc (len * sizeof (int));
3387 you can print the contents of @code{array} with
3393 The left operand of @samp{@@} must reside in memory. Array values made
3394 with @samp{@@} in this way behave just like other arrays in terms of
3395 subscripting, and are coerced to pointers when used in expressions.
3396 Artificial arrays most often appear in expressions via the value history
3397 (@pxref{Value History}), after printing one out.)
3399 @node Output formats, Memory, Arrays, Data
3400 @section Output formats
3402 @cindex formatted output
3403 @cindex output formats
3404 By default, _GDBN__ prints a value according to its data type. Sometimes
3405 this is not what you want. For example, you might want to print a number
3406 in hex, or a pointer in decimal. Or you might want to view data in memory
3407 at a certain address as a character string or as an instruction. To do
3408 these things, specify an @dfn{output format} when you print a value.
3410 The simplest use of output formats is to say how to print a value
3411 already computed. This is done by starting the arguments of the
3412 @code{print} command with a slash and a format letter. The format
3413 letters supported are:
3417 Regard the bits of the value as an integer, and print the integer in
3421 Print as integer in signed decimal.
3424 Print as integer in unsigned decimal.
3427 Print as integer in octal.
3430 Print as integer in binary. The letter @samp{t} stands for ``two''.
3433 Print as an address, both absolute in hex and as an offset from the
3434 nearest preceding symbol. This format can be used to discover where (in
3435 what function) an unknown address is located:
3437 (_GDBP__) p/a 0x54320
3438 _0__$3 = 0x54320 <_initialize_vx+396>_1__
3443 Regard as an integer and print it as a character constant.
3446 Regard the bits of the value as a floating point number and print
3447 using typical floating point syntax.
3450 For example, to print the program counter in hex (@pxref{Registers}), type
3457 Note that no space is required before the slash; this is because command
3458 names in _GDBN__ cannot contain a slash.
3460 To reprint the last value in the value history with a different format,
3461 you can use the @code{print} command with just a format and no
3462 expression. For example, @samp{p/x} reprints the last value in hex.
3464 @node Memory, Auto Display, Output formats, Data
3465 @section Examining Memory
3467 @cindex examining memory
3470 @item x/@var{nfu} @var{expr}
3471 The command @code{x} (for `examine') can be used to examine memory
3472 without being constrained by your program's data types. You can specify
3473 the unit size @var{u} of memory to inspect, and a repeat count @var{n} of how
3474 many of those units to display. @code{x} understands the formats
3475 @var{f} used by @code{print}; two additional formats, @samp{s} (string)
3476 and @samp{i} (machine instruction) can be used without specifying a unit
3480 For example, @samp{x/3uh 0x54320} is a request to display three halfwords
3481 (@code{h}) of memory, formatted as unsigned decimal integers (@samp{u}),
3482 starting at address @code{0x54320}. @samp{x/4xw $sp} prints the four
3483 words (@samp{w}) of memory above the stack pointer (here, @samp{$sp};
3484 @pxref{Registers}) in hexadecimal (@samp{x}).
3486 Since the letters indicating unit sizes are all distinct from the
3487 letters specifying output formats, you don't have to remember whether
3488 unit size or format comes first; either order will work. The output
3489 specifications @samp{4xw} and @samp{4wx} mean exactly the same thing.
3491 After the format specification, you supply an expression for the address
3492 where _GDBN__ is to begin reading from memory. The expression need not
3493 have a pointer value (though it may); it is always interpreted as an
3494 integer address of a byte of memory. @xref{Expressions} for more
3495 information on expressions.
3497 These are the memory units @var{u} you can specify with the @code{x}
3502 Examine individual bytes.
3505 Examine halfwords (two bytes each).
3508 Examine words (four bytes each).
3511 Many assemblers and cpu designers still use `word' for a 16-bit quantity,
3512 as a holdover from specific predecessor machines of the 1970's that really
3513 did use two-byte words. But more generally the term `word' has always
3514 referred to the size of quantity that a machine normally operates on and
3515 stores in its registers. This is 32 bits for all the machines that _GDBN__
3519 Examine giant words (8 bytes).
3522 You can combine these unit specifications with any of the formats
3523 described for @code{print}. @xref{Output formats}.
3525 @code{x} has two additional output specifications which derive the unit
3526 size from the data inspected:
3530 Print a null-terminated string of characters. Any explicitly specified
3531 unit size is ignored; instead, the unit is however many bytes it takes
3532 to reach a null character (including the null character).
3535 Print a machine instruction in assembler syntax (or nearly). Any
3536 specified unit size is ignored; the number of bytes in an instruction
3537 varies depending on the type of machine, the opcode and the addressing
3538 modes used. The command @code{disassemble} gives an alternative way of
3539 inspecting machine instructions. @xref{Machine Code}.
3542 If you omit either the format @var{f} or the unit size @var{u}, @code{x}
3543 will use the same one that was used last. If you don't use any letters
3544 or digits after the slash, you can omit the slash as well.
3546 You can also omit the address to examine. Then the address used is just
3547 after the last unit examined. This is why string and instruction
3548 formats actually compute a unit-size based on the data: so that the next
3549 string or instruction examined will start in the right place.
3551 When the @code{print} command shows a value that resides in memory,
3552 @code{print} also sets the default address for the @code{x} command.
3553 @code{info line} also sets the default for @code{x}, to the address of
3554 the start of the machine code for the specified line (@pxref{Machine
3555 Code}), and @code{info breakpoints} sets it to the address of the last
3556 breakpoint listed (@pxref{Set Breaks}).
3558 When you use @key{RET} to repeat an @code{x} command, the address
3559 specified previously (if any) is ignored, so that the repeated command
3560 examines the successive locations in memory rather than the same ones.
3562 You can examine several consecutive units of memory with one command by
3563 writing a repeat-count after the slash (before the format letters, if
3564 any). Omitting the repeat count @var{n} displays one unit of the
3565 appropriate size. The repeat count must be a decimal integer. It has
3566 the same effect as repeating the @code{x} command @var{n} times except
3567 that the output may be more compact, with several units per line. For
3575 prints ten instructions starting with the one to be executed next in the
3576 selected frame. After doing this, you could print a further seven
3584 ---where the format and address are allowed to default.
3588 The addresses and contents printed by the @code{x} command are not put
3589 in the value history because there is often too much of them and they
3590 would get in the way. Instead, _GDBN__ makes these values available for
3591 subsequent use in expressions as values of the convenience variables
3592 @code{$_} and @code{$__}. After an @code{x} command, the last address
3593 examined is available for use in expressions in the convenience variable
3594 @code{$_}. The contents of that address, as examined, are available in
3595 the convenience variable @code{$__}.
3597 If the @code{x} command has a repeat count, the address and contents saved
3598 are from the last memory unit printed; this is not the same as the last
3599 address printed if several units were printed on the last line of output.
3601 @node Auto Display, Print Settings, Memory, Data
3602 @section Automatic Display
3603 @cindex automatic display
3604 @cindex display of expressions
3606 If you find that you want to print the value of an expression frequently
3607 (to see how it changes), you might want to add it to the @dfn{automatic
3608 display list} so that _GDBN__ will print its value each time the program stops.
3609 Each expression added to the list is given a number to identify it;
3610 to remove an expression from the list, you specify that number.
3611 The automatic display looks like this:
3615 3: bar[5] = (struct hack *) 0x3804
3619 showing item numbers, expressions and their current values. As with
3620 displays you request manually using @code{x} or @code{print}, you can
3621 specify the output format you prefer; in fact, @code{display} decides
3622 whether to use @code{print} or @code{x} depending on how elaborate your
3623 format specification is---it uses @code{x} if you specify a unit size,
3624 or one of the two formats (@samp{i} and @samp{s}) that are only
3625 supported by @code{x}; otherwise it uses @code{print}.
3628 @item display @var{exp}
3630 Add the expression @var{exp} to the list of expressions to display
3631 each time the program stops. @xref{Expressions}.
3633 @code{display} will not repeat if you press @key{RET} again after using it.
3635 @item display/@var{fmt} @var{exp}
3636 For @var{fmt} specifying only a display format and not a size or
3637 count, add the expression @var{exp} to the auto-display list but
3638 arranges to display it each time in the specified format @var{fmt}.
3639 @xref{Output formats}.
3641 @item display/@var{fmt} @var{addr}
3642 For @var{fmt} @samp{i} or @samp{s}, or including a unit-size or a
3643 number of units, add the expression @var{addr} as a memory address to
3644 be examined each time the program stops. Examining means in effect
3645 doing @samp{x/@var{fmt} @var{addr}}. @xref{Memory}.
3648 For example, @samp{display/i $pc} can be helpful, to see the machine
3649 instruction about to be executed each time execution stops (@samp{$pc}
3650 is a common name for the program counter; @pxref{Registers}).
3653 @item undisplay @var{dnums}@dots{}
3654 @itemx delete display @var{dnums}@dots{}
3655 @kindex delete display
3657 Remove item numbers @var{dnums} from the list of expressions to display.
3659 @code{undisplay} will not repeat if you press @key{RET} after using it.
3660 (Otherwise you would just get the error @samp{No display number dots{}}.)
3662 @item disable display @var{dnums}@dots{}
3663 @kindex disable display
3664 Disable the display of item numbers @var{dnums}. A disabled display
3665 item is not printed automatically, but is not forgotten. It may be
3666 enabled again later.
3668 @item enable display @var{dnums}@dots{}
3669 @kindex enable display
3670 Enable display of item numbers @var{dnums}. It becomes effective once
3671 again in auto display of its expression, until you specify otherwise.
3674 Display the current values of the expressions on the list, just as is
3675 done when the program stops.
3678 @kindex info display
3679 Print the list of expressions previously set up to display
3680 automatically, each one with its item number, but without showing the
3681 values. This includes disabled expressions, which are marked as such.
3682 It also includes expressions which would not be displayed right now
3683 because they refer to automatic variables not currently available.
3686 If a display expression refers to local variables, then it does not make
3687 sense outside the lexical context for which it was set up. Such an
3688 expression is disabled when execution enters a context where one of its
3689 variables is not defined. For example, if you give the command
3690 @code{display last_char} while inside a function with an argument
3691 @code{last_char}, then this argument will be displayed while the program
3692 continues to stop inside that function. When it stops elsewhere---where
3693 there is no variable @code{last_char}---display is disabled. The next time
3694 your program stops where @code{last_char} is meaningful, you can enable the
3695 display expression once again.
3697 @node Print Settings, Value History, Auto Display, Data
3698 @section Print Settings
3700 @cindex format options
3701 @cindex print settings
3702 _GDBN__ provides the following ways to control how arrays, structures,
3703 and symbols are printed.
3706 These settings are useful for debugging programs in any language:
3709 @item set print address
3710 @item set print address on
3711 @kindex set print address
3712 _GDBN__ will print memory addresses showing the location of stack
3713 traces, structure values, pointer values, breakpoints, and so forth,
3714 even when it also displays the contents of those addresses. The default
3715 is on. For example, this is what a stack frame display looks like, with
3716 @code{set print address on}:
3719 #0 set_quotes (lq=0x34c78 "<<", rq=0x34c88 ">>")
3721 530 if (lquote != def_lquote)
3724 @item set print address off
3725 Do not print addresses when displaying their contents. For example,
3726 this is the same stack frame displayed with @code{set print address off}:
3728 (_GDBP__) set print addr off
3730 #0 set_quotes (lq="<<", rq=">>") at input.c:530
3731 530 if (lquote != def_lquote)
3734 @item show print address
3735 @kindex show print address
3736 Show whether or not addresses are to be printed.
3738 @item set print array
3739 @itemx set print array on
3740 @kindex set print array
3741 _GDBN__ will pretty print arrays. This format is more convenient to read,
3742 but uses more space. The default is off.
3744 @item set print array off.
3745 Return to compressed format for arrays.
3747 @item show print array
3748 @kindex show print array
3749 Show whether compressed or pretty format is selected for displaying
3752 @item set print elements @var{number-of-elements}
3753 @kindex set print elements
3754 If _GDBN__ is printing a large array, it will stop printing after it has
3755 printed the number of elements set by the @code{set print elements} command.
3756 This limit also applies to the display of strings.
3758 @item show print elements
3759 @kindex show print elements
3760 Display the number of elements of a large array that _GDBN__ will print
3761 before losing patience.
3763 @item set print pretty on
3764 @kindex set print pretty
3765 Cause _GDBN__ to print structures in an indented format with one member per
3779 @item set print pretty off
3780 Cause _GDBN__ to print structures in a compact format, like this:
3783 $1 = @{next = 0x0, flags = @{sweet = 1, sour = 1@}, meat \
3788 This is the default format.
3790 @item show print pretty
3791 @kindex show print pretty
3792 Show which format _GDBN__ will use to print structures.
3794 @item set print sevenbit-strings on
3795 Print using only seven-bit characters; if this option is set,
3796 _GDBN__ will display any eight-bit characters (in strings or character
3797 values) using the notation @code{\}@var{nnn}. For example, @kbd{M-a} is
3798 displayed as @code{\341}.
3800 @item set print sevenbit-strings off
3801 Print using either seven-bit or eight-bit characters, as required. This
3804 @item show print sevenbit-strings
3805 Show whether or not _GDBN__ will print only seven-bit characters.
3807 @item set print union on
3808 @kindex set print union
3809 Tell _GDBN__ to print unions which are contained in structures. This is the
3812 @item set print union off
3813 Tell _GDBN__ not to print unions which are contained in structures.
3815 @item show print union
3816 @kindex show print union
3817 Ask _GDBN__ whether or not it will print unions which are contained in
3820 For example, given the declarations
3823 typedef enum @{Tree, Bug@} Species;
3824 typedef enum @{Big_tree, Acorn, Seedling@} Tree_forms;
3825 typedef enum @{Caterpillar, Cocoon, Butterfly@} Bug_forms;
3835 struct thing foo = @{Tree, @{Acorn@}@};
3839 with @code{set print union on} in effect @samp{p foo} would print
3842 $1 = @{it = Tree, form = @{tree = Acorn, bug = Cocoon@}@}
3846 and with @code{set print union off} in effect it would print
3849 $1 = @{it = Tree, form = @{...@}@}
3854 These settings are of interest when debugging C++ programs:
3857 @item set print demangle
3858 @itemx set print demangle on
3859 @kindex set print demangle
3860 Print C++ names in their source form rather than in the mangled form
3861 in which they are passed to the assembler and linker for type-safe linkage.
3864 @item show print demangle
3865 @kindex show print demangle
3866 Show whether C++ names will be printed in mangled or demangled form.
3868 @item set print asm-demangle
3869 @itemx set print asm-demangle on
3870 @kindex set print asm-demangle
3871 Print C++ names in their source form rather than their mangled form, even
3872 in assembler code printouts such as instruction disassemblies.
3875 @item show print asm-demangle
3876 @kindex show print asm-demangle
3877 Show whether C++ names in assembly listings will be printed in mangled
3880 @item set print object
3881 @itemx set print object on
3882 @kindex set print object
3883 When displaying a pointer to an object, identify the @emph{actual}
3884 (derived) type of the object rather than the @emph{declared} type, using
3885 the virtual function table.
3887 @item set print object off
3888 Display only the declared type of objects, without reference to the
3889 virtual function table. This is the default setting.
3891 @item show print object
3892 @kindex show print object
3893 Show whether actual, or declared, object types will be displayed.
3895 @item set print vtbl
3896 @itemx set print vtbl on
3897 @kindex set print vtbl
3898 Pretty print C++ virtual function tables. The default is off.
3900 @item set print vtbl off
3901 Do not pretty print C++ virtual function tables.
3903 @item show print vtbl
3904 @kindex show print vtbl
3905 Show whether C++ virtual function tables are pretty printed, or not.
3909 @node Value History, Convenience Vars, Print Settings, Data
3910 @section Value History
3912 @cindex value history
3913 Values printed by the @code{print} command are saved in _GDBN__'s @dfn{value
3914 history} so that you can refer to them in other expressions. Values are
3915 kept until the symbol table is re-read or discarded (for example with
3916 the @code{file} or @code{symbol-file} commands). When the symbol table
3917 changes, the value history is discarded, since the values may contain
3918 pointers back to the types defined in the symbol table.
3922 @cindex history number
3923 The values printed are given @dfn{history numbers} for you to refer to them
3924 by. These are successive integers starting with one. @code{print} shows you
3925 the history number assigned to a value by printing @samp{$@var{num} = }
3926 before the value; here @var{num} is the history number.
3928 To refer to any previous value, use @samp{$} followed by the value's
3929 history number. The way @code{print} labels its output is designed to
3930 remind you of this. Just @code{$} refers to the most recent value in
3931 the history, and @code{$$} refers to the value before that.
3932 @code{$$@var{n}} refers to the @var{n}th value from the end; @code{$$2}
3933 is the value just prior to @code{$$}, @code{$$1} is equivalent to
3934 @code{$$}, and @code{$$0} is equivalent to @code{$}.
3936 For example, suppose you have just printed a pointer to a structure and
3937 want to see the contents of the structure. It suffices to type
3943 If you have a chain of structures where the component @code{next} points
3944 to the next one, you can print the contents of the next one with this:
3951 You can print successive links in the chain by repeating this
3952 command---which you can do by just typing @key{RET}.
3954 Note that the history records values, not expressions. If the value of
3955 @code{x} is 4 and you type these commands:
3963 then the value recorded in the value history by the @code{print} command
3964 remains 4 even though the value of @code{x} has changed.
3969 Print the last ten values in the value history, with their item numbers.
3970 This is like @samp{p@ $$9} repeated ten times, except that @code{show
3971 values} does not change the history.
3973 @item show values @var{n}
3974 Print ten history values centered on history item number @var{n}.
3977 Print ten history values just after the values last printed. If no more
3978 values are available, produces no display.
3981 Pressing @key{RET} to repeat @code{show values @var{n}} has exactly the
3982 same effect as @samp{show values +}.
3984 @node Convenience Vars, Registers, Value History, Data
3985 @section Convenience Variables
3987 @cindex convenience variables
3988 _GDBN__ provides @dfn{convenience variables} that you can use within
3989 _GDBN__ to hold on to a value and refer to it later. These variables
3990 exist entirely within _GDBN__; they are not part of your program, and
3991 setting a convenience variable has no direct effect on further execution
3992 of your program. That's why you can use them freely.
3994 Convenience variables are prefixed with @samp{$}. Any name preceded by
3995 @samp{$} can be used for a convenience variable, unless it is one of
3996 the predefined machine-specific register names (@pxref{Registers}).
3997 (Value history references, in contrast, are @emph{numbers} preceded
3998 by @samp{$}. @xref{Value History}.)
4000 You can save a value in a convenience variable with an assignment
4001 expression, just as you would set a variable in your program. Example:
4004 set $foo = *object_ptr
4008 would save in @code{$foo} the value contained in the object pointed to by
4011 Using a convenience variable for the first time creates it; but its value
4012 is @code{void} until you assign a new value. You can alter the value with
4013 another assignment at any time.
4015 Convenience variables have no fixed types. You can assign a convenience
4016 variable any type of value, including structures and arrays, even if
4017 that variable already has a value of a different type. The convenience
4018 variable, when used as an expression, has the type of its current value.
4021 @item show convenience
4022 @kindex show convenience
4023 Print a list of convenience variables used so far, and their values.
4024 Abbreviated @code{show con}.
4027 One of the ways to use a convenience variable is as a counter to be
4028 incremented or a pointer to be advanced. For example, to print
4029 a field from successive elements of an array of structures:
4033 print bar[$i++]->contents
4034 @i{@dots{} repeat that command by typing @key{RET}.}
4037 Some convenience variables are created automatically by _GDBN__ and given
4038 values likely to be useful.
4042 The variable @code{$_} is automatically set by the @code{x} command to
4043 the last address examined (@pxref{Memory}). Other commands which
4044 provide a default address for @code{x} to examine also set @code{$_}
4045 to that address; these commands include @code{info line} and @code{info
4049 The variable @code{$__} is automatically set by the @code{x} command
4050 to the value found in the last address examined.
4053 @node Registers, Floating Point Hardware, Convenience Vars, Data
4057 Machine register contents can be referred to in expressions as variables
4058 with names starting with @samp{$}. The names of registers are different
4059 for each machine; use @code{info registers} to see the names used on
4063 @item info registers
4064 @kindex info registers
4065 Print the names and values of all registers (in the selected stack frame).
4067 @item info registers @var{regname}
4068 Print the relativized value of register @var{regname}. @var{regname}
4069 may be any register name valid on the machine you are using, with
4070 or without the initial @samp{$}.
4073 The register names @code{$pc} and @code{$sp} are used on most machines
4074 for the program counter register and the stack pointer. For example,
4075 you could print the program counter in hex with
4081 or print the instruction to be executed next with
4087 or add four to the stack pointer with
4093 The last is a way of removing one word from the stack, on machines where
4094 stacks grow downward in memory (most machines, nowadays). This assumes
4095 that the innermost stack frame is selected; setting @code{$sp} is
4096 not allowed when other stack frames are selected. (To pop entire frames
4097 off the stack, regardless of machine architecture, use @code{return};
4100 Often @code{$fp} is used for a register that contains a pointer to the
4101 current stack frame, and @code{$ps} is sometimes used for a register
4102 that contains the processor status. These standard register names may
4103 be available on your machine even though the @code{info registers}
4104 command shows other names. For example, on the SPARC, @code{info
4105 registers} displays the processor status register as @code{$psr} but you
4106 can also refer to it as @code{$ps}.
4108 _GDBN__ always considers the contents of an ordinary register as an
4109 integer when the register is examined in this way. Some machines have
4110 special registers which can hold nothing but floating point; these
4111 registers are considered to have floating point values. There is no way
4112 to refer to the contents of an ordinary register as floating point value
4113 (although you can @emph{print} it as a floating point value with
4114 @samp{print/f $@var{regname}}).
4116 Some registers have distinct ``raw'' and ``virtual'' data formats. This
4117 means that the data format in which the register contents are saved by
4118 the operating system is not the same one that your program normally
4119 sees. For example, the registers of the 68881 floating point
4120 coprocessor are always saved in ``extended'' (raw) format, but all C
4121 programs expect to work with ``double'' (virtual) format. In such
4122 cases, _GDBN__ normally works with the virtual format only (the format that
4123 makes sense for your program), but the @code{info registers} command
4124 prints the data in both formats.
4126 Normally, register values are relative to the selected stack frame
4127 (@pxref{Selection}). This means that you get the value that the
4128 register would contain if all stack frames farther in were exited and
4129 their saved registers restored. In order to see the true contents of
4130 hardware registers, you must select the innermost frame (with
4133 However, _GDBN__ must deduce where registers are saved, from the machine
4134 code generated by your compiler. If some registers are not saved, or if
4135 _GDBN__ is unable to locate the saved registers, the selected stack
4136 frame will make no difference.
4138 @node Floating Point Hardware, , Registers, Data
4139 @section Floating Point Hardware
4140 @cindex floating point
4141 Depending on the host machine architecture, _GDBN__ may be able to give
4142 you more information about the status of the floating point hardware.
4147 If available, provides hardware-dependent information about the floating
4148 point unit. The exact contents and layout vary depending on the
4149 floating point chip.
4151 @c FIXME: this is a cop-out. Try to get examples, explanations. Only
4152 @c FIXME...supported currently on arm's and 386's. Mark properly with
4153 @c FIXME... m4 macros to isolate general statements from hardware-dep,
4154 @c FIXME... at that point.
4156 @node Symbols, Altering, Data, Top
4157 @chapter Examining the Symbol Table
4159 The commands described in this section allow you to inquire about the
4160 symbols (names of variables, functions and types) defined in your
4161 program. This information is inherent in the text of your program and
4162 does not change as the program executes. _GDBN__ finds it in your
4163 program's symbol table, in the file indicated when you started _GDBN__
4164 (@pxref{File Options}), or by one of the file-management commands
4168 @item info address @var{symbol}
4169 @kindex info address
4170 Describe where the data for @var{symbol} is stored. For a register
4171 variable, this says which register it is kept in. For a non-register
4172 local variable, this prints the stack-frame offset at which the variable
4175 Note the contrast with @samp{print &@var{symbol}}, which does not work
4176 at all for a register variables, and for a stack local variable prints
4177 the exact address of the current instantiation of the variable.
4179 @item whatis @var{exp}
4181 Print the data type of expression @var{exp}. @var{exp} is not
4182 actually evaluated, and any side-effecting operations (such as
4183 assignments or function calls) inside it do not take place.
4187 Print the data type of @code{$}, the last value in the value history.
4189 @item ptype @var{typename}
4191 Print a description of data type @var{typename}. @var{typename} may be
4192 the name of a type, or for C code it may have the form
4193 @samp{struct @var{struct-tag}}, @samp{union @var{union-tag}} or
4194 @samp{enum @var{enum-tag}}.@refill
4196 @item ptype @var{exp}
4197 Print a description of the type of expression @var{exp}. @code{ptype}
4198 differs from @code{whatis} by printing a detailed description, instead of just
4199 the name of the type. For example, if your program declares a variable
4202 struct complex {double real; double imag;} v;
4205 compare the output of the two commands:
4208 type = struct complex
4210 type = struct complex {
4216 @item info types @var{regexp}
4219 Print a brief description of all types whose name matches @var{regexp}
4220 (or all types in your program, if you supply no argument). Each
4221 complete typename is matched as though it were a complete line; thus,
4222 @samp{i type value} gives information on all types in your program whose
4223 name includes the string @code{value}, but @samp{i type ^value$} gives
4224 information only on types whose complete name is @code{value}.
4226 This command differs from @code{ptype} in two ways: first, like
4227 @code{whatis}, it does not print a detailed description; second, it
4228 lists all source files where a type is defined.
4232 Show the name of the current source file---that is, the source file for
4233 the function containing the current point of execution.
4236 @kindex info sources
4237 Print the names of all source files in the program for which there is
4238 debugging information, organized into two lists: those for which symbols
4239 have been read in, and those for which symbols will be read in on
4241 @c FIXME: above passive AND awkward!
4243 @item info functions
4244 @kindex info functions
4245 Print the names and data types of all defined functions.
4247 @item info functions @var{regexp}
4248 Print the names and data types of all defined functions
4249 whose names contain a match for regular expression @var{regexp}.
4250 Thus, @samp{info fun step} finds all functions whose names
4251 include @code{step}; @samp{info fun ^step} finds those whose names
4252 start with @code{step}.
4254 @item info variables
4255 @kindex info variables
4256 Print the names and data types of all variables that are declared
4257 outside of functions (i.e., excluding local variables).
4259 @item info variables @var{regexp}
4260 Print the names and data types of all variables (except for local
4261 variables) whose names contain a match for regular expression
4266 This was never implemented.
4268 @itemx info methods @var{regexp}
4269 @kindex info methods
4270 The @code{info methods} command permits the user to examine all defined
4271 methods within C++ program, or (with the @var{regexp} argument) a
4272 specific set of methods found in the various C++ classes. Many
4273 C++ classes provide a large number of methods. Thus, the output
4274 from the @code{ptype} command can be overwhelming and hard to use. The
4275 @code{info-methods} command filters the methods, printing only those
4276 which match the regular-expression @var{regexp}.
4279 @item printsyms @var{filename}
4281 Write a complete dump of the debugger's symbol data into the
4282 file @var{filename}.
4285 @node Altering, _GDBN__ Files, Symbols, Top
4286 @chapter Altering Execution
4288 Once you think you have found an error in the program, you might want to
4289 find out for certain whether correcting the apparent error would lead to
4290 correct results in the rest of the run. You can find the answer by
4291 experiment, using the _GDBN__ features for altering execution of the
4294 For example, you can store new values into variables or memory
4295 locations, give the program a signal, restart it at a different address,
4296 or even return prematurely from a function to its caller.
4299 * Assignment:: Assignment to Variables
4300 * Jumping:: Continuing at a Different Address
4301 * Signaling:: Giving the Program a Signal
4302 * Returning:: Returning from a Function
4303 * Calling:: Calling your Program's Functions
4306 @node Assignment, Jumping, Altering, Altering
4307 @section Assignment to Variables
4310 @cindex setting variables
4311 To alter the value of a variable, evaluate an assignment expression.
4312 @xref{Expressions}. For example,
4319 would store the value 4 into the variable @code{x}, and then print the
4320 value of the assignment expression (which is 4). All the assignment
4321 operators of C are supported, including the increment operators
4322 @samp{++} and @samp{--}, and combining assignments such as @samp{+=} and
4326 @kindex set variable
4327 @cindex variables, setting
4328 If you are not interested in seeing the value of the assignment, use the
4329 @code{set} command instead of the @code{print} command. @code{set} is
4330 really the same as @code{print} except that the expression's value is not
4331 printed and is not put in the value history (@pxref{Value History}). The
4332 expression is evaluated only for its effects.
4334 If the beginning of the argument string of the @code{set} command
4335 appears identical to a @code{set} subcommand, use the @code{set
4336 variable} command instead of just @code{set}. This command is identical
4337 to @code{set} except for its lack of subcommands. For example, a
4338 program might well have a variable @code{width}---which leads to
4339 an error if we try to set a new value with just @samp{set width=13}, as
4340 we might if @code{set width} didn't happen to be a _GDBN__ command:
4342 (_GDBP__) whatis width
4346 (_GDBP__) set width=47
4347 Invalid syntax in expression.
4350 The invalid expression, of course, is @samp{=47}. What we can do in
4351 order to actually set our program's variable @code{width} is
4353 (_GDBP__) set var width=47
4356 _GDBN__ allows more implicit conversions in assignments than C does; you can
4357 freely store an integer value into a pointer variable or vice versa, and
4358 any structure can be converted to any other structure that is the same
4360 @comment FIXME: how do structs align/pad in these conversions?
4361 @comment /pesch@cygnus.com 18dec1990
4363 To store values into arbitrary places in memory, use the @samp{@{@dots{}@}}
4364 construct to generate a value of specified type at a specified address
4365 (@pxref{Expressions}). For example, @code{@{int@}0x83040} refers
4366 to memory location @code{0x83040} as an integer (which implies a certain size
4367 and representation in memory), and
4370 set @{int@}0x83040 = 4
4374 stores the value 4 into that memory location.
4376 @node Jumping, Signaling, Assignment, Altering
4377 @section Continuing at a Different Address
4379 Ordinarily, when you continue the program, you do so at the place where
4380 it stopped, with the @code{continue} command. You can instead continue at
4381 an address of your own choosing, with the following commands:
4384 @item jump @var{linespec}
4386 Resume execution at line @var{linespec}. Execution will stop
4387 immediately if there is a breakpoint there. @xref{List} for a
4388 description of the different forms of @var{linespec}.
4390 The @code{jump} command does not change the current stack frame, or
4391 the stack pointer, or the contents of any memory location or any
4392 register other than the program counter. If line @var{linespec} is in
4393 a different function from the one currently executing, the results may
4394 be bizarre if the two functions expect different patterns of arguments or
4395 of local variables. For this reason, the @code{jump} command requests
4396 confirmation if the specified line is not in the function currently
4397 executing. However, even bizarre results are predictable if you are
4398 well acquainted with the machine-language code of the program.
4400 @item jump *@var{address}
4401 Resume execution at the instruction at address @var{address}.
4404 You can get much the same effect as the @code{jump} command by storing a
4405 new value into the register @code{$pc}. The difference is that this
4406 does not start the program running; it only changes the address where it
4407 @emph{will} run when it is continued. For example,
4414 causes the next @code{continue} command or stepping command to execute at
4415 address 0x485, rather than at the address where the program stopped.
4418 The most common occasion to use the @code{jump} command is to back up,
4419 perhaps with more breakpoints set, over a portion of a program that has
4420 already executed, in order to examine its execution in more detail.
4423 @node Signaling, Returning, Jumping, Altering
4424 @section Giving the Program a Signal
4427 @item signal @var{signalnum}
4429 Resume execution where the program stopped, but give it immediately the
4430 signal number @var{signalnum}.
4432 Alternatively, if @var{signalnum} is zero, continue execution without
4433 giving a signal. This is useful when the program stopped on account of
4434 a signal and would ordinary see the signal when resumed with the
4435 @code{continue} command; @samp{signal 0} causes it to resume without a
4438 @code{signal} does not repeat when you press @key{RET} a second time
4439 after executing the command.
4443 @node Returning, Calling, Signaling, Altering
4444 @section Returning from a Function
4448 @itemx return @var{expression}
4449 @cindex returning from a function
4451 You can cancel execution of a function call with the @code{return}
4452 command. If you give an
4453 @var{expression} argument, its value is used as the function's return
4457 When you use @code{return}, _GDBN__ discards the selected stack frame
4458 (and all frames within it). You can think of this as making the
4459 discarded frame return prematurely. If you wish to specify a value to
4460 be returned, give that value as the argument to @code{return}.
4462 This pops the selected stack frame (@pxref{Selection}), and any other
4463 frames inside of it, leaving its caller as the innermost remaining
4464 frame. That frame becomes selected. The specified value is stored in
4465 the registers used for returning values of functions.
4467 The @code{return} command does not resume execution; it leaves the
4468 program stopped in the state that would exist if the function had just
4469 returned. In contrast, the @code{finish} command (@pxref{Stepping})
4470 resumes execution until the selected stack frame returns naturally.
4472 @node Calling, , Returning, Altering
4473 @section Calling your Program's Functions
4475 @cindex calling functions
4478 @item call @var{expr}
4479 Evaluate the expression @var{expr} without displaying @code{void}
4483 You can use this variant of the @code{print} command if you want to
4484 execute a function from your program, but without cluttering the output
4485 with @code{void} returned values. The result is printed and saved in
4486 the value history, if it is not void.
4488 @node _GDBN__ Files, Targets, Altering, Top
4489 @chapter _GDBN__'s Files
4492 * Files:: Commands to Specify Files
4493 * Symbol Errors:: Errors Reading Symbol Files
4496 @node Files, Symbol Errors, _GDBN__ Files, _GDBN__ Files
4497 @section Commands to Specify Files
4498 @cindex core dump file
4499 @cindex symbol table
4500 _GDBN__ needs to know the file name of the program to be debugged, both in
4501 order to read its symbol table and in order to start the program. To
4502 debug a core dump of a previous run, _GDBN__ must be told the file name of
4505 The usual way to specify the executable and core dump file names is with
4506 the command arguments given when you start _GDBN__, as discussed in
4509 Occasionally it is necessary to change to a different file during a
4510 _GDBN__ session. Or you may run _GDBN__ and forget to specify the files you
4511 want to use. In these situations the _GDBN__ commands to specify new files
4515 @item file @var{filename}
4516 @cindex executable file
4518 Use @var{filename} as the program to be debugged. It is read for its
4519 symbols and for the contents of pure memory. It is also the program
4520 executed when you use the @code{run} command. If you do not specify a
4521 directory and the file is not found in _GDBN__'s working directory,
4523 _GDBN__ uses the environment variable @code{PATH} as a list of
4524 directories to search, just as the shell does when looking for a program
4525 to run. You can change the value of this variable, for both _GDBN__ and
4526 your program, using the @code{path} command.
4528 @code{file} with no argument makes _GDBN__ discard any information it
4529 has on both executable file and the symbol table.
4531 @item exec-file @var{filename}
4533 Specify that the program to be run (but not the symbol table) is found
4534 in @var{filename}. _GDBN__ will search the environment variable @code{PATH}
4535 if necessary to locate the program.
4537 @item symbol-file @var{filename}
4539 Read symbol table information from file @var{filename}. @code{PATH} is
4540 searched when necessary. Use the @code{file} command to get both symbol
4541 table and program to run from the same file.
4543 @code{symbol-file} with no argument clears out _GDBN__'s information on your
4544 program's symbol table.
4546 The @code{symbol-file} command causes _GDBN__ to forget the contents of its
4547 convenience variables, the value history, and all breakpoints and
4548 auto-display expressions. This is because they may contain pointers to
4549 the internal data recording symbols and data types, which are part of
4550 the old symbol table data being discarded inside _GDBN__.
4552 @code{symbol-file} will not repeat if you press @key{RET} again after
4555 On some kinds of object files, the @code{symbol-file} command does not
4556 actually read the symbol table in full right away. Instead, it scans
4557 the symbol table quickly to find which source files and which symbols
4558 are present. The details are read later, one source file at a time,
4559 when they are needed.
4561 The purpose of this two-stage reading strategy is to make _GDBN__ start up
4562 faster. For the most part, it is invisible except for occasional pauses
4563 while the symbol table details for a particular source file are being
4564 read. (The @code{set verbose} command can turn these pauses into
4565 messages if desired. @xref{Messages/Warnings}).
4567 When the symbol table is stored in COFF format, @code{symbol-file} does
4568 read the symbol table data in full right away. We haven't implemented
4569 the two-stage strategy for COFF yet.
4571 When _GDBN__ is configured for a particular environment, it will
4572 understand debugging information in whatever format is the standard
4573 generated for that environment; you may use either a GNU compiler, or
4574 other compilers that adhere to the local conventions. Best results are
4575 usually obtained from GNU compilers; for example, using @code{_GCC__}
4576 you can generate debugging information for optimized code.
4578 @item core-file @var{filename}
4579 @itemx core @var{filename}
4582 Specify the whereabouts of a core dump file to be used as the ``contents
4583 of memory''. Traditionally, core files contain only some parts of the
4584 address space of the process that generated them; _GDBN__ can access the
4585 executable file itself for other parts.
4587 @code{core-file} with no argument specifies that no core file is
4590 Note that the core file is ignored when your program is actually running
4591 under _GDBN__. So, if you have been running the program and you wish to
4592 debug a core file instead, you must kill the subprocess in which the
4593 program is running. To do this, use the @code{kill} command
4594 (@pxref{Kill Process}).
4596 @item load @var{filename}
4599 Depending on what remote debugging facilities are configured into
4600 _GDBN__, the @code{load} command may be available. Where it exists, it
4601 is meant to make @var{filename} (an executable) available for debugging
4602 on the remote system---by downloading, or dynamic linking, for example.
4603 @code{load} also records @var{filename}'s symbol table in _GDBN__, like
4604 the @code{add-symbol-file} command.
4606 If @code{load} is not available on your _GDBN__, attempting to execute
4607 it gets the error message ``@code{You can't do that when your target is
4612 On VxWorks, @code{load} will dynamically link @var{filename} on the
4613 current target system as well as adding its symbols in _GDBN__.
4617 @cindex download to Nindy-960
4618 With the Nindy interface to an Intel 960 board, @code{load} will
4619 download @var{filename} to the 960 as well as adding its symbols in
4623 @code{load} will not repeat if you press @key{RET} again after using it.
4625 @item add-symbol-file @var{filename} @var{address}
4626 @kindex add-symbol-file
4627 @cindex dynamic linking
4628 The @code{add-symbol-file} command reads additional symbol table information
4629 from the file @var{filename}. You would use this command when that file
4630 has been dynamically loaded (by some other means) into the program that
4631 is running. @var{address} should be the memory address at which the
4632 file has been loaded; _GDBN__ cannot figure this out for itself.
4634 The symbol table of the file @var{filename} is added to the symbol table
4635 originally read with the @code{symbol-file} command. You can use the
4636 @code{add-symbol-file} command any number of times; the new symbol data thus
4637 read keeps adding to the old. To discard all old symbol data instead,
4638 use the @code{symbol-file} command.
4640 @code{add-symbol-file} will not repeat if you press @key{RET} after using it.
4646 @code{info files} and @code{info target} are synonymous; both print the
4647 current targets (@pxref{Targets}), including the names of the executable
4648 and core dump files currently in use by _GDBN__, and the files from
4649 which symbols were loaded. The command @code{help targets} lists all
4650 possible targets rather than current ones.
4654 All file-specifying commands allow both absolute and relative file names
4655 as arguments. _GDBN__ always converts the file name to an absolute path
4656 name and remembers it that way.
4658 @kindex sharedlibrary
4660 @cindex shared libraries
4662 _GDBN__ supports the SunOS shared library format. Symbols from a shared
4663 library cannot be referenced before the shared library has been linked
4664 with the program. (That is to say, until after you type @code{run} and
4665 the function @code{main} has been entered; or when examining core
4666 files.) Once the shared library has been linked in, you can use the
4670 @item sharedlibrary @var{regex}
4671 @itemx share @var{regex}
4672 Load shared object library symbols for files matching a UNIX regular
4676 @itemx sharedlibrary
4677 Load symbols for all shared libraries.
4680 @itemx info sharedlibrary
4681 @kindex info sharedlibrary
4683 Print the names of the shared libraries which you have loaded with the
4684 @code{sharedlibrary} command.
4687 @code{sharedlibrary} does not repeat automatically when you press
4688 @key{RET} after using it once.
4690 @node Symbol Errors, , Files, _GDBN__ Files
4691 @section Errors Reading Symbol Files
4692 While a symbol file is being read, _GDBN__ will occasionally encounter
4693 problems, such as symbol types it does not recognize, or known bugs in
4694 compiler output. By default, it prints one message about each such
4695 type of problem, no matter how many times the problem occurs. You can
4696 ask it to print more messages, to see how many times the problems occur,
4697 or can shut the messages off entirely, with the @code{set
4698 complaints} command (@xref{Messages/Warnings}).
4700 The messages currently printed, and their meanings, are:
4703 @item inner block not inside outer block in @var{symbol}
4705 The symbol information shows where symbol scopes begin and end
4706 (such as at the start of a function or a block of statements). This
4707 error indicates that an inner scope block is not fully contained
4708 in its outer scope blocks.
4710 _GDBN__ circumvents the problem by treating the inner block as if it had
4711 the same scope as the outer block. In the error message, @var{symbol}
4712 may be shown as ``@code{(don't know)}'' if the outer block is not a
4715 @item block at @var{address} out of order
4717 The symbol information for symbol scope blocks should occur in
4718 order of increasing addresses. This error indicates that it does not
4721 _GDBN__ does not circumvent this problem, and will have trouble locating
4722 symbols in the source file whose symbols being read. (You can often
4723 determine what source file is affected by specifying @code{set verbose
4724 on}. @xref{Messages/Warnings}.)
4726 @item bad block start address patched
4728 The symbol information for a symbol scope block has a start address
4729 smaller than the address of the preceding source line. This is known
4730 to occur in the SunOS 4.1.1 (and earlier) C compiler.
4732 _GDBN__ circumvents the problem by treating the symbol scope block as
4733 starting on the previous source line.
4735 @c @item{encountered DBX-style class variable debugging information.
4736 @c You seem to have compiled your program with "g++ -g0" instead of "g++ -g".
4737 @c Therefore _GDBN__ will not know about your class variables}
4739 @c This error indicates that the symbol information produced for a C++
4740 @c program includes zero-size fields, which indicated static fields in
4741 @c a previous release of the G++ compiler. This message is probably
4744 @item bad string table offset in symbol @var{n}
4747 Symbol number @var{n} contains a pointer into the string table which is
4748 larger than the size of the string table.
4750 _GDBN__ circumvents the problem by considering the symbol to have the
4751 name @code{foo}, which may cause other problems if many symbols end up
4754 @item unknown symbol type @code{0x@var{nn}}
4756 The symbol information contains new data types that _GDBN__ does not yet
4757 know how to read. @code{0x@var{nn}} is the symbol type of the misunderstood
4758 information, in hexadecimal.
4760 _GDBN__ circumvents the error by ignoring this symbol information. This
4761 will usually allow the program to be debugged, though certain symbols
4762 will not be accessible. If you encounter such a problem and feel like
4763 debugging it, you can debug @code{_GDBP__} with itself, breakpoint on
4764 @code{complain}, then go up to the function @code{read_dbx_symtab} and
4765 examine @code{*bufp} to see the symbol.
4767 @item stub type has NULL name
4768 _GDBN__ could not find the full definition for a struct or class.
4771 @c this is #if 0'd in dbxread.c as of (at least!) 17 may 1991
4772 @item const/volatile indicator missing, got '@var{X}'
4774 The symbol information for a C++ member function is missing some
4775 information that the compiler should have output for it.
4778 @item C++ type mismatch between compiler and debugger
4780 The debugger could not parse a type specification output by the compiler
4781 for some C++ object.
4785 @node Targets, Controlling _GDBN__, _GDBN__ Files, Top
4786 @chapter Specifying a Debugging Target
4787 @cindex debugging target
4789 A @dfn{target} is an interface between the debugger and a particular
4790 kind of file or process.
4792 Often, you will be able to run _GDBN__ in the same host environment as the
4793 program you are debugging; in that case, the debugging target can just be
4794 specified as a side effect of the @code{file} or @code{core} commands.
4795 When you need more flexibility---for example, running _GDBN__ on a
4796 physically separate host, controlling standalone systems over a
4797 serial port, or realtime systems over a TCP/IP connection---you can use
4798 the @code{target} command.
4801 * Active Targets:: Active Targets
4802 * Target Commands:: Commands for Managing Targets
4803 * Remote:: Remote Debugging
4806 @node Active Targets, Target Commands, Targets, Targets
4807 @section Active Targets
4808 @cindex stacking targets
4809 @cindex active targets
4810 @cindex multiple targets
4812 Targets are managed in three @dfn{strata} that correspond to different
4813 classes of target: processes, core files, and executable files. This
4814 allows you to (for example) start a process and inspect its activity
4815 without abandoning your work on a core file.
4817 More than one target can potentially respond to a request. In
4818 particular, when you access memory _GDBN__ will examine the three strata of
4819 targets until it finds a target that can handle that particular address.
4820 Strata are always examined in a fixed order: first a process if there is
4821 one, then a core file if there is one, and finally an executable file if
4822 there is one of those.
4824 When you specify a new target in a given stratum, it replaces any target
4825 previously in that stratum.
4827 To get rid of a target without replacing it, use the @code{detach}
4828 command. The related command @code{attach} provides you with a way of
4829 choosing a particular running process as a new target. @xref{Attach}.
4831 @node Target Commands, Remote, Active Targets, Targets
4832 @section Commands for Managing Targets
4835 @item target @var{type} @var{parameters}
4836 Connects the _GDBN__ host environment to a target machine or process. A
4837 target is typically a protocol for talking to debugging facilities. You
4838 use the argument @var{type} to specify the type or protocol of the
4841 Further @var{parameters} are interpreted by the target protocol, but
4842 typically include things like device names or host names to connect
4843 with, process numbers, and baud rates.
4845 The @code{target} command will not repeat if you press @key{RET} again
4846 after executing the command.
4850 Displays the names of all targets available. To display targets
4851 currently selected, use either @code{info target} or @code{info files}
4854 @item help target @var{name}
4855 Describe a particular target, including any parameters necessary to
4859 Here are some common targets (available, or not, depending on the _GDBN__
4863 @item target exec @var{prog}
4865 An executable file. @samp{target exec @var{prog}} is the same as
4866 @samp{exec-file @var{prog}}.
4868 @item target core @var{filename}
4870 A core dump file. @samp{target core @var{filename}} is the same as
4871 @samp{core-file @var{filename}}.
4873 @item target remote @var{dev}
4874 @kindex target remote
4875 Remote serial target in _GDBN__-specific protocol. The argument @var{dev}
4876 specifies what serial device to use for the connection (e.g.
4877 @file{/dev/ttya}). @xref{Remote}.
4880 @item target amd-eb @var{dev} @var{speed} @var{PROG}
4881 @kindex target amd-eb
4883 Remote PC-resident AMD EB29K board, attached over serial lines.
4884 @var{dev} is the serial device, as for @code{target remote};
4885 @var{speed} allows you to specify the linespeed; and @var{PROG} is the
4886 name of the program to be debugged, as it appears to DOS on the PC.
4887 @xref{EB29K Remote}.
4891 @item target nindy @var{devicename}
4892 @kindex target nindy
4893 An Intel 960 board controlled by a Nindy Monitor. @var{devicename} is
4894 the name of the serial device to use for the connection, e.g.
4895 @file{/dev/ttya}. @xref{i960-Nindy Remote}.
4899 @item target vxworks @var{machinename}
4900 @kindex target vxworks
4901 A VxWorks system, attached via TCP/IP. The argument @var{machinename}
4902 is the target system's machine name or IP address.
4903 @xref{VxWorks Remote}.
4908 Different targets are available on different configurations of _GDBN__; your
4909 configuration may have more or fewer targets.
4912 @node Remote, , Target Commands, Targets
4913 @section Remote Debugging
4914 @cindex remote debugging
4922 If you are trying to debug a program running on a machine that can't run
4923 _GDBN__ in the usual way, it is often useful to use remote debugging. For
4924 example, you might use remote debugging on an operating system kernel, or on
4925 a small system which does not have a general purpose operating system
4926 powerful enough to run a full-featured debugger.
4928 Some configurations of _GDBN__ have special serial or TCP/IP interfaces
4929 to make this work with particular debugging targets. In addition,
4930 _GDBN__ comes with a generic serial protocol (specific to _GDBN__, but
4931 not specific to any particular target system) which you can use if you
4932 write the remote stubs---the code that will run on the remote system to
4933 communicate with _GDBN__.
4935 To use the _GDBN__ remote serial protocol, the program to be debugged on
4936 the remote machine needs to contain a debugging stub which talks to
4937 _GDBN__ over the serial line. Several working remote stubs are
4938 distributed with _GDBN__; see the @file{README} file in the _GDBN__
4939 distribution for more information.
4941 For details of this communication protocol, see the comments in the
4942 _GDBN__ source file @file{remote.c}.
4944 To start remote debugging, first run _GDBN__ and specify as an executable file
4945 the program that is running in the remote machine. This tells _GDBN__ how
4946 to find the program's symbols and the contents of its pure text. Then
4947 establish communication using the @code{target remote} command with a device
4948 name as an argument. For example:
4951 target remote /dev/ttyb
4955 if the serial line is connected to the device named @file{/dev/ttyb}. This
4956 will stop the remote machine if it is not already stopped.
4958 Now you can use all the usual commands to examine and change data and to
4959 step and continue the remote program.
4961 To resume the remote program and stop debugging it, use the @code{detach}
4964 Other remote targets may be available in your
4965 configuration of _GDBN__; use @code{help targets} to list them.
4969 @c Text on starting up GDB in various specific cases; it goes up front
4970 @c in manuals configured for any of those particular situations, here
4974 @node Controlling _GDBN__, Sequences, Targets, Top
4975 @chapter Controlling _GDBN__
4977 You can alter many aspects of _GDBN__'s interaction with you by using
4978 the @code{set} command. For commands controlling how _GDBN__ displays
4979 data, @pxref{Print Settings}; other settings are described here.
4983 * Editing:: Command Editing
4984 * History:: Command History
4985 * Screen Size:: Screen Size
4987 * Messages/Warnings:: Optional Warnings and Messages
4990 @node Prompt, Editing, Controlling _GDBN__, Controlling _GDBN__
4993 _GDBN__ indicates its readiness to read a command by printing a string
4994 called the @dfn{prompt}. This string is normally @samp{(_GDBP__)}. You
4995 can change the prompt string with the @code{set prompt} command. For
4996 instance, when debugging _GDBN__ with _GDBN__, it is useful to change
4997 the prompt in one of the _GDBN__<>s so that you can always tell which
4998 one you are talking to.
5001 @item set prompt @var{newprompt}
5003 Directs _GDBN__ to use @var{newprompt} as its prompt string henceforth.
5006 Prints a line of the form: @samp{Gdb's prompt is: @var{your-prompt}}
5009 @node Editing, History, Prompt, Controlling _GDBN__
5010 @section Command Editing
5012 @cindex command line editing
5013 _GDBN__ reads its input commands via the @dfn{readline} interface. This
5014 GNU library provides consistent behavior for programs which provide a
5015 command line interface to the user. Advantages are @code{emacs}-style
5016 or @code{vi}-style inline editing of commands, @code{csh}-like history
5017 substitution, and a storage and recall of command history across
5020 You may control the behavior of command line editing in _GDBN__ with the
5027 @itemx set editing on
5028 Enable command line editing (enabled by default).
5030 @item set editing off
5031 Disable command line editing.
5033 @kindex show editing
5035 Show whether command line editing is enabled.
5037 @node History, Screen Size, Editing, Controlling _GDBN__
5038 @section Command History
5039 @cindex history substitution
5040 @cindex history file
5041 @kindex set history filename
5042 @item set history filename @var{fname}
5043 Set the name of the _GDBN__ command history file to @var{fname}. This is
5044 the file from which _GDBN__ will read an initial command history
5045 list or to which it will write this list when it exits. This list is
5046 accessed through history expansion or through the history
5047 command editing characters listed below. This file defaults to the
5048 value of the environment variable @code{GDBHISTFILE}, or to
5049 @file{./.gdb_history} if this variable is not set.
5051 @cindex history save
5052 @kindex set history save
5053 @item set history save
5054 @itemx set history save on
5055 Record command history in a file, whose name may be specified with the
5056 @code{set history filename} command. By default, this option is disabled.
5058 @item set history save off
5059 Stop recording command history in a file.
5061 @cindex history size
5062 @kindex set history size
5063 @item set history size @var{size}
5064 Set the number of commands which _GDBN__ will keep in its history list.
5065 This defaults to the value of the environment variable
5066 @code{HISTSIZE}, or to 256 if this variable is not set.
5069 @cindex history expansion
5070 History expansion assigns special meaning to the character @kbd{!}.
5072 (@xref{Event Designators}.)
5074 Since @kbd{!} is also the logical not operator in C, history expansion
5075 is off by default. If you decide to enable history expansion with the
5076 @code{set history expansion on} command, you may sometimes need to
5077 follow @kbd{!} (when it is used as logical not, in an expression) with
5078 a space or a tab to prevent it from being expanded. The readline
5079 history facilities will not attempt substitution on the strings
5080 @kbd{!=} and @kbd{!(}, even when history expansion is enabled.
5082 The commands to control history expansion are:
5086 @kindex set history expansion
5087 @item set history expansion on
5088 @itemx set history expansion
5089 Enable history expansion. History expansion is off by default.
5091 @item set history expansion off
5092 Disable history expansion.
5094 The readline code comes with more complete documentation of
5095 editing and history expansion features. Users unfamiliar with @code{emacs}
5096 or @code{vi} may wish to read it.
5098 @xref{Command Line Editing}.
5102 @kindex show history
5104 @itemx show history filename
5105 @itemx show history save
5106 @itemx show history size
5107 @itemx show history expansion
5108 These commands display the state of the _GDBN__ history parameters.
5109 @code{show history} by itself displays all four states.
5115 @kindex show commands
5117 Display the last ten commands in the command history.
5119 @item show commands @var{n}
5120 Print ten commands centered on command number @var{n}.
5122 @item show commands +
5123 Print ten commands just after the commands last printed.
5127 @node Screen Size, Numbers, History, Controlling _GDBN__
5128 @section Screen Size
5129 @cindex size of screen
5130 @cindex pauses in output
5131 Certain commands to _GDBN__ may produce large amounts of information
5132 output to the screen. To help you read all of it, _GDBN__ pauses and
5133 asks you for input at the end of each page of output. Type @key{RET}
5134 when you want to continue the output. _GDBN__ also uses the screen
5135 width setting to determine when to wrap lines of output. Depending on
5136 what is being printed, it tries to break the line at a readable place,
5137 rather than simply letting it overflow onto the following line.
5139 Normally _GDBN__ knows the size of the screen from the termcap data base
5140 together with the value of the @code{TERM} environment variable and the
5141 @code{stty rows} and @code{stty cols} settings. If this is not correct,
5142 you can override it with the @code{set height} and @code{set
5146 @item set height @var{lpp}
5148 @itemx set width @var{cpl}
5154 These @code{set} commands specify a screen height of @var{lpp} lines and
5155 a screen width of @var{cpl} characters. The associated @code{show}
5156 commands display the current settings.
5158 If you specify a height of zero lines, _GDBN__ will not pause during output
5159 no matter how long the output is. This is useful if output is to a file
5160 or to an editor buffer.
5163 @node Numbers, Messages/Warnings, Screen Size, Controlling _GDBN__
5165 @cindex number representation
5166 @cindex entering numbers
5167 You can always enter numbers in octal, decimal, or hexadecimal in _GDBN__ by
5168 the usual conventions: octal numbers begin with @samp{0}, decimal
5169 numbers end with @samp{.}, and hexadecimal numbers begin with @samp{0x}.
5170 Numbers that begin with none of these are, by default, entered in base
5171 10; likewise, the default display for numbers---when no particular
5172 format is specified---is base 10. You can change the default base for
5173 both input and output with the @code{set radix} command.
5177 @item set radix @var{base}
5178 Set the default base for numeric input and display. Supported choices
5179 for @var{base} are decimal 8, 10, 16. @var{base} must itself be
5180 specified either unambiguously or using the current default radix; for
5190 will set the base to decimal. On the other hand, @samp{set radix 10}
5191 will leave the radix unchanged no matter what it was.
5195 Display the current default base for numeric input and display.
5199 @node Messages/Warnings, , Numbers, Controlling _GDBN__
5200 @section Optional Warnings and Messages
5201 By default, _GDBN__ is silent about its inner workings. If you are running
5202 on a slow machine, you may want to use the @code{set verbose} command.
5203 It will make _GDBN__ tell you when it does a lengthy internal operation, so
5204 you won't think it has crashed.
5206 Currently, the messages controlled by @code{set verbose} are those which
5207 announce that the symbol table for a source file is being read
5208 (@pxref{Files}, in the description of the command
5209 @code{symbol-file}).
5210 @c The following is the right way to do it, but emacs 18.55 doesn't support
5211 @c @ref, and neither the emacs lisp manual version of texinfmt or makeinfo
5214 see @code{symbol-file} in @ref{Files}).
5219 @item set verbose on
5220 Enables _GDBN__'s output of certain informational messages.
5222 @item set verbose off
5223 Disables _GDBN__'s output of certain informational messages.
5225 @kindex show verbose
5227 Displays whether @code{set verbose} is on or off.
5230 By default, if _GDBN__ encounters bugs in the symbol table of an object file,
5231 it prints a single message about each type of problem it finds, then
5232 shuts up (@pxref{Symbol Errors}). You can suppress these messages, or allow more than one such
5233 message to be printed if you want to see how frequent the problems are.
5236 @kindex set complaints
5237 @item set complaints @var{limit}
5238 Permits _GDBN__ to output @var{limit} complaints about each type of unusual
5239 symbols before becoming silent about the problem. Set @var{limit} to
5240 zero to suppress all complaints; set it to a large number to prevent
5241 complaints from being suppressed.
5243 @kindex show complaints
5244 @item show complaints
5245 Displays how many symbol complaints _GDBN__ is permitted to produce.
5248 By default, _GDBN__ is cautious, and asks what sometimes seem to be a
5249 lot of stupid questions to confirm certain commands. For example, if
5250 you try to run a program which is already running:
5253 The program being debugged has been started already.
5254 Start it from the beginning? (y or n)
5257 If you're willing to unflinchingly face the consequences of your own
5258 commands, you can disable this ``feature'':
5263 @cindex confirmation
5264 @cindex stupid questions
5265 @item set confirm off
5266 Disables confirmation requests.
5268 @item set confirm on
5269 Enables confirmation requests (the default).
5272 @kindex show confirm
5273 Displays state of confirmation requests.
5276 @node Sequences, Emacs, Controlling _GDBN__, Top
5277 @chapter Canned Sequences of Commands
5279 Aside from breakpoint commands (@pxref{Break Commands}), _GDBN__ provides two
5280 ways to store sequences of commands for execution as a unit:
5281 user-defined commands and command files.
5284 * Define:: User-Defined Commands
5285 * Command Files:: Command Files
5286 * Output:: Commands for Controlled Output
5289 @node Define, Command Files, Sequences, Sequences
5290 @section User-Defined Commands
5292 @cindex user-defined command
5293 A @dfn{user-defined command} is a sequence of _GDBN__ commands to which you
5294 assign a new name as a command. This is done with the @code{define}
5298 @item define @var{commandname}
5300 Define a command named @var{commandname}. If there is already a command
5301 by that name, you are asked to confirm that you want to redefine it.
5303 The definition of the command is made up of other _GDBN__ command lines,
5304 which are given following the @code{define} command. The end of these
5305 commands is marked by a line containing @code{end}.
5307 @item document @var{commandname}
5309 Give documentation to the user-defined command @var{commandname}. The
5310 command @var{commandname} must already be defined. This command reads
5311 lines of documentation just as @code{define} reads the lines of the
5312 command definition, ending with @code{end}. After the @code{document}
5313 command is finished, @code{help} on command @var{commandname} will print
5314 the documentation you have specified.
5316 You may use the @code{document} command again to change the
5317 documentation of a command. Redefining the command with @code{define}
5318 does not change the documentation.
5320 @item help user-defined
5321 @kindex help user-defined
5322 List all user-defined commands, with the first line of the documentation
5326 @itemx info user @var{commandname}
5328 Display the _GDBN__ commands used to define @var{commandname} (but not its
5329 documentation). If no @var{commandname} is given, display the
5330 definitions for all user-defined commands.
5333 User-defined commands do not take arguments. When they are executed, the
5334 commands of the definition are not printed. An error in any command
5335 stops execution of the user-defined command.
5337 Commands that would ask for confirmation if used interactively proceed
5338 without asking when used inside a user-defined command. Many _GDBN__ commands
5339 that normally print messages to say what they are doing omit the messages
5340 when used in a user-defined command.
5342 @node Command Files, Output, Define, Sequences
5343 @section Command Files
5345 @cindex command files
5346 A command file for _GDBN__ is a file of lines that are _GDBN__ commands. Comments
5347 (lines starting with @kbd{#}) may also be included. An empty line in a
5348 command file does nothing; it does not mean to repeat the last command, as
5349 it would from the terminal.
5352 @cindex @file{_GDBINIT__}
5353 When you start _GDBN__, it automatically executes commands from its
5354 @dfn{init files}. These are files named @file{_GDBINIT__}. _GDBN__
5355 reads the init file (if any) in your home directory and then the init
5356 file (if any) in the current working directory. (The init files are not
5357 executed if you use the @samp{-nx} option; @pxref{Mode Options}.) You
5358 can also request the execution of a command file with the @code{source}
5362 @item source @var{filename}
5364 Execute the command file @var{filename}.
5367 The lines in a command file are executed sequentially. They are not
5368 printed as they are executed. An error in any command terminates execution
5369 of the command file.
5371 Commands that would ask for confirmation if used interactively proceed
5372 without asking when used in a command file. Many _GDBN__ commands that
5373 normally print messages to say what they are doing omit the messages
5374 when called from command files.
5376 @node Output, , Command Files, Sequences
5377 @section Commands for Controlled Output
5379 During the execution of a command file or a user-defined command, normal
5380 _GDBN__ output is suppressed; the only output that appears is what is
5381 explicitly printed by the commands in the definition. This section
5382 describes three commands useful for generating exactly the output you
5386 @item echo @var{text}
5388 @c I don't consider backslash-space a standard C escape sequence
5389 @c because it's not in ANSI.
5390 Print @var{text}. Nonprinting characters can be included in @var{text}
5391 using C escape sequences, such as @samp{\n} to print a newline. @b{No
5392 newline will be printed unless you specify one.} In addition to the
5393 standard C escape sequences, a backslash followed by a space stands for a
5394 space. This is useful for outputting a string with spaces at the
5395 beginning or the end, since leading and trailing spaces are otherwise
5396 trimmed from all arguments. Thus, to print @samp{@ and foo =@ }, use the
5397 command @samp{echo \@ and foo = \@ }.
5398 @c FIXME: verify hard copy actually issues enspaces for '@ '! Will this
5401 A backslash at the end of @var{text} can be used, as in C, to continue
5402 the command onto subsequent lines. For example,
5405 echo This is some text\n\
5406 which is continued\n\
5407 onto several lines.\n
5410 produces the same output as
5413 echo This is some text\n
5414 echo which is continued\n
5415 echo onto several lines.\n
5418 @item output @var{expression}
5420 Print the value of @var{expression} and nothing but that value: no
5421 newlines, no @samp{$@var{nn} = }. The value is not entered in the
5422 value history either. @xref{Expressions} for more information on
5425 @item output/@var{fmt} @var{expression}
5426 Print the value of @var{expression} in format @var{fmt}. You can use
5427 the same formats as for @code{print}; @pxref{Output formats}, for more
5430 @item printf @var{string}, @var{expressions}@dots{}
5432 Print the values of the @var{expressions} under the control of
5433 @var{string}. The @var{expressions} are separated by commas and may
5434 be either numbers or pointers. Their values are printed as specified
5435 by @var{string}, exactly as if the program were to execute
5438 printf (@var{string}, @var{expressions}@dots{});
5441 For example, you can print two values in hex like this:
5444 printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo
5447 The only backslash-escape sequences that you can use in the format
5448 string are the simple ones that consist of backslash followed by a
5452 @node Emacs, _GDBN__ Bugs, Sequences, Top
5453 @chapter Using _GDBN__ under GNU Emacs
5456 A special interface allows you to use GNU Emacs to view (and
5457 edit) the source files for the program you are debugging with
5460 To use this interface, use the command @kbd{M-x gdb} in Emacs. Give the
5461 executable file you want to debug as an argument. This command starts
5462 _GDBN__ as a subprocess of Emacs, with input and output through a newly
5463 created Emacs buffer.
5465 Using _GDBN__ under Emacs is just like using _GDBN__ normally except for two
5470 All ``terminal'' input and output goes through the Emacs buffer.
5473 This applies both to _GDBN__ commands and their output, and to the input
5474 and output done by the program you are debugging.
5476 This is useful because it means that you can copy the text of previous
5477 commands and input them again; you can even use parts of the output
5480 All the facilities of Emacs' Shell mode are available for this purpose.
5484 _GDBN__ displays source code through Emacs.
5487 Each time _GDBN__ displays a stack frame, Emacs automatically finds the
5488 source file for that frame and puts an arrow (_0__@samp{=>}_1__) at the
5489 left margin of the current line. Emacs uses a separate buffer for
5490 source display, and splits the window to show both your _GDBN__ session
5493 Explicit _GDBN__ @code{list} or search commands still produce output as
5494 usual, but you probably will have no reason to use them.
5497 @emph{Warning:} If the directory where your program resides is not your
5498 current directory, it can be easy to confuse Emacs about the location of
5499 the source files, in which case the auxiliary display buffer will not
5500 appear to show your source. _GDBN__ can find programs by searching your
5501 environment's @code{PATH} variable, so the _GDBN__ input and output
5502 session will proceed normally; but Emacs doesn't get enough information
5503 back from _GDBN__ to locate the source files in this situation. To
5504 avoid this problem, either start _GDBN__ mode from the directory where
5505 your program resides, or specify a full path name when prompted for the
5506 @kbd{M-x gdb} argument.
5508 A similar confusion can result if you use the _GDBN__ @code{file} command to
5509 switch to debugging a program in some other location, from an existing
5510 _GDBN__ buffer in Emacs.
5513 By default, @kbd{M-x gdb} calls the program called @file{gdb}. If
5514 you need to call _GDBN__ by a different name (for example, if you keep
5515 several configurations around, with different names) you can set the
5516 Emacs variable @code{gdb-command-name}; for example,
5518 (setq gdb-command-name "mygdb")
5521 (preceded by @kbd{ESC ESC}, or typed in the @code{*scratch*} buffer, or
5522 in your @file{.emacs} file) will make Emacs call the program named
5523 ``@code{mygdb}'' instead.
5525 In the _GDBN__ I/O buffer, you can use these special Emacs commands in
5526 addition to the standard Shell mode commands:
5530 Describe the features of Emacs' _GDBN__ Mode.
5533 Execute to another source line, like the _GDBN__ @code{step} command; also
5534 update the display window to show the current file and location.
5537 Execute to next source line in this function, skipping all function
5538 calls, like the _GDBN__ @code{next} command. Then update the display window
5539 to show the current file and location.
5542 Execute one instruction, like the _GDBN__ @code{stepi} command; update
5543 display window accordingly.
5546 Execute to next instruction, using the _GDBN__ @code{nexti} command; update
5547 display window accordingly.
5550 Execute until exit from the selected stack frame, like the _GDBN__
5551 @code{finish} command.
5554 Continue execution of the program, like the _GDBN__ @code{continue}
5555 command. @emph{Warning:} In Emacs v19, this command is @kbd{C-c C-p}.
5558 Go up the number of frames indicated by the numeric argument
5559 (@pxref{Arguments, , Numeric Arguments, emacs, The GNU Emacs Manual}),
5560 like the _GDBN__ @code{up} command. @emph{Warning:} In Emacs v19, this
5561 command is @kbd{C-c C-u}.@refill
5564 Go down the number of frames indicated by the numeric argument, like the
5565 _GDBN__ @code{down} command. @emph{Warning:} In Emacs v19, this command
5569 Read the number where the cursor is positioned, and insert it at the end
5570 of the _GDBN__ I/O buffer. For example, if you wish to disassemble code
5571 around an address that was displayed earlier, type @kbd{disassemble};
5572 then move the cursor to the address display, and pick up the
5573 argument for @code{disassemble} by typing @kbd{C-x &}.
5575 You can customize this further on the fly by defining elements of the list
5576 @code{gdb-print-command}; once it is defined, you can format or
5577 otherwise process numbers picked up by @kbd{C-x &} before they are
5578 inserted. A numeric argument to @kbd{C-x &} will both flag that you
5579 wish special formatting, and act as an index to pick an element of the
5580 list. If the list element is a string, the number to be inserted is
5581 formatted using the Emacs function @code{format}; otherwise the number
5582 is passed as an argument to the corresponding list element.
5586 In any source file, the Emacs command @kbd{C-x SPC} (@code{gdb-break})
5587 tells _GDBN__ to set a breakpoint on the source line point is on.
5589 If you accidentally delete the source-display buffer, an easy way to get
5590 it back is to type the command @code{f} in the _GDBN__ buffer, to
5591 request a frame display; when you run under Emacs, this will recreate
5592 the source buffer if necessary to show you the context of the current
5595 The source files displayed in Emacs are in ordinary Emacs buffers
5596 which are visiting the source files in the usual way. You can edit
5597 the files with these buffers if you wish; but keep in mind that _GDBN__
5598 communicates with Emacs in terms of line numbers. If you add or
5599 delete lines from the text, the line numbers that _GDBN__ knows will cease
5600 to correspond properly to the code.
5602 @c The following dropped because Epoch is nonstandard. Reactivate
5603 @c if/when v19 does something similar. ---pesch@cygnus.com 19dec1990
5605 @kindex emacs epoch environment
5609 Version 18 of Emacs has a built-in window system called the @code{epoch}
5610 environment. Users of this environment can use a new command,
5611 @code{inspect} which performs identically to @code{print} except that
5612 each value is printed in its own window.
5615 @node _GDBN__ Bugs, Renamed Commands, Emacs, Top
5616 @c node-name, next, previous, up
5617 @chapter Reporting Bugs in _GDBN__
5618 @cindex Bugs in _GDBN__
5619 @cindex Reporting Bugs in _GDBN__
5621 Your bug reports play an essential role in making _GDBN__ reliable.
5623 Reporting a bug may help you by bringing a solution to your problem, or it
5624 may not. But in any case the principal function of a bug report is to help
5625 the entire community by making the next version of _GDBN__ work better. Bug
5626 reports are your contribution to the maintenance of _GDBN__.
5628 In order for a bug report to serve its purpose, you must include the
5629 information that enables us to fix the bug.
5632 * Bug Criteria:: Have You Found a Bug?
5633 * Bug Reporting:: How to Report Bugs
5636 @node Bug Criteria, Bug Reporting, _GDBN__ Bugs, _GDBN__ Bugs
5637 @section Have You Found a Bug?
5638 @cindex Bug Criteria
5640 If you are not sure whether you have found a bug, here are some guidelines:
5644 @cindex Fatal Signal
5646 If the debugger gets a fatal signal, for any input whatever, that is a
5647 _GDBN__ bug. Reliable debuggers never crash.
5650 @cindex error on Valid Input
5651 If _GDBN__ produces an error message for valid input, that is a bug.
5654 @cindex Invalid Input
5655 If _GDBN__ does not produce an error message for invalid input,
5656 that is a bug. However, you should note that your idea of
5657 ``invalid input'' might be our idea of ``an extension'' or ``support
5658 for traditional practice''.
5661 If you are an experienced user of debugging tools, your suggestions
5662 for improvement of _GDBN__ are welcome in any case.
5665 @node Bug Reporting, , Bug Criteria, _GDBN__ Bugs
5666 @section How to Report Bugs
5668 @cindex Compiler Bugs, Reporting
5670 A number of companies and individuals offer support for GNU products.
5671 If you obtained _GDBN__ from a support organization, we recommend you
5672 contact that organization first.
5674 Contact information for many support companies and individuals is
5675 available in the file @file{etc/SERVICE} in the GNU Emacs distribution.
5677 In any event, we also recommend that you send bug reports for _GDBN__ to one
5681 bug-gdb@@prep.ai.mit.edu
5682 @{ucbvax|mit-eddie|uunet@}!prep.ai.mit.edu!bug-gdb
5685 @strong{Do not send bug reports to @samp{info-gdb}, or to
5686 @samp{help-gdb}, or to any newsgroups.} Most users of _GDBN__ do not want to
5687 receive bug reports. Those that do, have arranged to receive @samp{bug-gdb}.
5689 The mailing list @samp{bug-gdb} has a newsgroup which serves as a
5690 repeater. The mailing list and the newsgroup carry exactly the same
5691 messages. Often people think of posting bug reports to the newsgroup
5692 instead of mailing them. This appears to work, but it has one problem
5693 which can be crucial: a newsgroup posting often lacks a mail path
5694 back to the sender. Thus, if we need to ask for more information, we
5695 may be unable to reach you. For this reason, it is better to send bug
5696 reports to the mailing list.
5698 As a last resort, send bug reports on paper to:
5706 The fundamental principle of reporting bugs usefully is this:
5707 @strong{report all the facts}. If you are not sure whether to state a
5708 fact or leave it out, state it!
5710 Often people omit facts because they think they know what causes the
5711 problem and assume that some details don't matter. Thus, you might
5712 assume that the name of the variable you use in an example does not matter.
5713 Well, probably it doesn't, but one cannot be sure. Perhaps the bug is a
5714 stray memory reference which happens to fetch from the location where that
5715 name is stored in memory; perhaps, if the name were different, the contents
5716 of that location would fool the debugger into doing the right thing despite
5717 the bug. Play it safe and give a specific, complete example. That is the
5718 easiest thing for you to do, and the most helpful.
5720 Keep in mind that the purpose of a bug report is to enable us to fix
5721 the bug if it is new to us. It isn't as important what happens if
5722 the bug is already known. Therefore, always write your bug reports on
5723 the assumption that the bug has not been reported previously.
5725 Sometimes people give a few sketchy facts and ask, ``Does this ring a
5726 bell?'' Those bug reports are useless, and we urge everyone to
5727 @emph{refuse to respond to them} except to chide the sender to report
5730 To enable us to fix the bug, you should include all these things:
5734 The version of _GDBN__. _GDBN__ announces it if you start with no
5735 arguments; you can also print it at any time using @code{show version}.
5737 Without this, we won't know whether there is any point in looking for
5738 the bug in the current version of _GDBN__.
5741 A complete input script, and all necessary source files, that will
5745 What compiler (and its version) was used to compile _GDBN__---e.g.
5749 The command arguments you gave the compiler to compile your example and
5750 observe the bug. For example, did you use @samp{-O}? To guarantee
5751 you won't omit something important, list them all.
5753 If we were to try to guess the arguments, we would probably guess wrong
5754 and then we might not encounter the bug.
5757 The type of machine you are using, and the operating system name and
5761 A description of what behavior you observe that you believe is
5762 incorrect. For example, ``It gets a fatal signal.''
5764 Of course, if the bug is that _GDBN__ gets a fatal signal, then we will
5765 certainly notice it. But if the bug is incorrect output, we might not
5766 notice unless it is glaringly wrong. We are human, after all. You
5767 might as well not give us a chance to make a mistake.
5769 Even if the problem you experience is a fatal signal, you should still
5770 say so explicitly. Suppose something strange is going on, such as,
5771 your copy of _GDBN__ is out of synch, or you have encountered a
5772 bug in the C library on your system. (This has happened!) Your copy
5773 might crash and ours would not. If you told us to expect a crash,
5774 then when ours fails to crash, we would know that the bug was not
5775 happening for us. If you had not told us to expect a crash, then we
5776 would not be able to draw any conclusion from our observations.
5779 If you wish to suggest changes to the _GDBN__ source, send us context
5780 diffs. If you even discuss something in the _GDBN__ source, refer to
5781 it by context, not by line number.
5783 The line numbers in our development sources won't match those in your
5784 sources. Your line numbers would convey no useful information to us.
5788 Here are some things that are not necessary:
5792 A description of the envelope of the bug.
5794 Often people who encounter a bug spend a lot of time investigating
5795 which changes to the input file will make the bug go away and which
5796 changes will not affect it.
5798 This is often time consuming and not very useful, because the way we
5799 will find the bug is by running a single example under the debugger
5800 with breakpoints, not by pure deduction from a series of examples.
5801 We recommend that you save your time for something else.
5803 Of course, if you can find a simpler example to report @emph{instead}
5804 of the original one, that is a convenience for us. Errors in the
5805 output will be easier to spot, running under the debugger will take
5808 However, simplification is not vital; if you don't want to do this,
5809 report the bug anyway and send us the entire test case you used.
5812 A patch for the bug.
5814 A patch for the bug does help us if it is a good one. But don't omit
5815 the necessary information, such as the test case, on the assumption that
5816 a patch is all we need. We might see problems with your patch and decide
5817 to fix the problem another way, or we might not understand it at all.
5819 Sometimes with a program as complicated as _GDBN__ it is very hard to
5820 construct an example that will make the program follow a certain path
5821 through the code. If you don't send us the example, we won't be able
5822 to construct one, so we won't be able to verify that the bug is fixed.
5824 And if we can't understand what bug you are trying to fix, or why your
5825 patch should be an improvement, we won't install it. A test case will
5826 help us to understand.
5829 A guess about what the bug is or what it depends on.
5831 Such guesses are usually wrong. Even we can't guess right about such
5832 things without first using the debugger to find the facts.
5836 @include rdl-apps.texinfo
5839 @node Renamed Commands, Installing _GDBN__, _GDBN__ Bugs, Top
5840 @appendix Commands Renamed in 4.0
5842 The following commands were renamed in _GDBN__ 4.0, in order to make the
5843 command set as a whole more consistent and easier to use and remember:
5846 @kindex delete environment
5847 @kindex info copying
5848 @kindex info convenience
5849 @kindex info directories
5850 @kindex info editing
5851 @kindex info history
5852 @kindex info targets
5854 @kindex info version
5855 @kindex info warranty
5856 @kindex set addressprint
5857 @kindex set arrayprint
5858 @kindex set prettyprint
5859 @kindex set screen-height
5860 @kindex set screen-width
5861 @kindex set unionprint
5862 @kindex set vtblprint
5863 @kindex set demangle
5864 @kindex set asm-demangle
5865 @kindex set sevenbit-strings
5866 @kindex set array-max
5868 @kindex set history write
5869 @kindex show addressprint
5870 @kindex show arrayprint
5871 @kindex show prettyprint
5872 @kindex show screen-height
5873 @kindex show screen-width
5874 @kindex show unionprint
5875 @kindex show vtblprint
5876 @kindex show demangle
5877 @kindex show asm-demangle
5878 @kindex show sevenbit-strings
5879 @kindex show array-max
5880 @kindex show caution
5881 @kindex show history write
5885 OLD COMMAND NEW COMMAND
5886 --------------- ----------------------------------
5887 add-syms add-symbol-file
5888 delete environment unset environment
5889 info convenience show convenience
5890 info copying show copying
5891 info directories show directories
5892 info editing show commands
5893 info history show values
5894 info targets help target
5895 info values show values
5896 info version show version
5897 info warranty show warranty
5898 set/show addressprint set/show print address
5899 set/show array-max set/show print elements
5900 set/show arrayprint set/show print array
5901 set/show asm-demangle set/show print asm-demangle
5902 set/show caution set/show confirm
5903 set/show demangle set/show print demangle
5904 set/show history write set/show history save
5905 set/show prettyprint set/show print pretty
5906 set/show screen-height set/show height
5907 set/show screen-width set/show width
5908 set/show sevenbit-strings set/show print sevenbit-strings
5909 set/show unionprint set/show print union
5910 set/show vtblprint set/show print vtbl
5912 unset [ No longer an alias for delete ]
5916 \vskip \parskip\vskip \baselineskip
5917 \halign{\tt #\hfil &\qquad#&\tt #\hfil\cr
5918 {\bf Old Command} &&{\bf New Command}\cr
5919 add-syms &&add-symbol-file\cr
5920 delete environment &&unset environment\cr
5921 info convenience &&show convenience\cr
5922 info copying &&show copying\cr
5923 info directories &&show directories \cr
5924 info editing &&show commands\cr
5925 info history &&show values\cr
5926 info targets &&help target\cr
5927 info values &&show values\cr
5928 info version &&show version\cr
5929 info warranty &&show warranty\cr
5930 set{\rm / }show addressprint &&set{\rm / }show print address\cr
5931 set{\rm / }show array-max &&set{\rm / }show print elements\cr
5932 set{\rm / }show arrayprint &&set{\rm / }show print array\cr
5933 set{\rm / }show asm-demangle &&set{\rm / }show print asm-demangle\cr
5934 set{\rm / }show caution &&set{\rm / }show confirm\cr
5935 set{\rm / }show demangle &&set{\rm / }show print demangle\cr
5936 set{\rm / }show history write &&set{\rm / }show history save\cr
5937 set{\rm / }show prettyprint &&set{\rm / }show print pretty\cr
5938 set{\rm / }show screen-height &&set{\rm / }show height\cr
5939 set{\rm / }show screen-width &&set{\rm / }show width\cr
5940 set{\rm / }show sevenbit-strings &&set{\rm / }show print sevenbit-strings\cr
5941 set{\rm / }show unionprint &&set{\rm / }show print union\cr
5942 set{\rm / }show vtblprint &&set{\rm / }show print vtbl\cr
5944 unset &&\rm(No longer an alias for delete)\cr
5948 @node Installing _GDBN__, Copying, Renamed Commands, Top
5949 @appendix Installing _GDBN__
5950 @cindex configuring _GDBN__
5951 @cindex installation
5953 The script @code{config.gdb} automates the process of preparing _GDBN__
5954 for installation; you can then use @code{make} to actually build it.
5955 The best way to build _GDBN__ is in a subdirectory that records the
5956 configuration options used; this gives you a clean way of building
5957 _GDBN__ binaries with several different configuration options.
5958 @code{config.gdb} doesn't depend on this---it's just a good habit. For
5959 example, assuming the _GDBN__ source is in a directory called
5966 ../config.gdb sun3os4
5971 will install _GDBN__ on a Sun 3 running SunOS 4.
5975 @item config.gdb @var{machine}
5976 @itemx config.gdb -srcdir=@var{dir} @var{machine}
5977 This is the most usual way of configuring _GDBN__; to debug programs running
5978 on the same machine as _GDBN__ itself. If you wish to build the _GDBN__ binaries
5979 in a completely different directory from the sources, specify a path to
5980 the source directory using the @samp{-srcdir} option.
5982 @item config.gdb -host
5983 @cindex host environments
5984 Display a list of supported host environments for _GDBN__.
5986 @item config.gdb @var{host} @var{target}
5987 @itemx config.gdb -srcdir=@var{dir} @var{host} @var{target}
5988 @cindex cross-debugging
5989 _GDBN__ can also be used as a cross-debugger, running on a machine of one
5990 type while debugging a program running on a machine of another type.
5991 You configure it this way by specifying first the @var{host}, then the
5992 @var{target} environment on the @code{config.gdb} argument list; the
5993 @var{host} is where _GDBN__ runs, and the @var{target} is where your program
5994 runs. @xref{Remote}. Again, you can use @samp{-srcdir} to specify a
5995 path to the _GDBN__ source.
5997 @item config.gdb -target
5998 @cindex target environments
5999 Display a list of supported target environments for _GDBN__.
6002 @node Copying, Index, Installing _GDBN__, Top
6003 @appendix Copying GDB
6004 @c this is an attempt to kluge around what may be a bug in texinfo;
6005 @c @xrefs to this node came out pointing several pages further down when
6006 @c the @node was immediately followed by @unnumbered.
6007 @c While we're at it, might as well give an Appendix heading that
6008 @c matches RMS' preferred nodename "Copying".
6010 @unnumbered GNU GENERAL PUBLIC LICENSE
6011 @center Version 1, February 1989
6014 Copyright @copyright{} 1989 Free Software Foundation, Inc.
6015 675 Mass Ave, Cambridge, MA 02139, USA
6017 Everyone is permitted to copy and distribute verbatim copies
6018 of this license document, but changing it is not allowed.
6021 @unnumberedsec Preamble
6023 The license agreements of most software companies try to keep users
6024 at the mercy of those companies. By contrast, our General Public
6025 License is intended to guarantee your freedom to share and change free
6026 software---to make sure the software is free for all its users. The
6027 General Public License applies to the Free Software Foundation's
6028 software and to any other program whose authors commit to using it.
6029 You can use it for your programs, too.
6031 When we speak of free software, we are referring to freedom, not
6032 price. Specifically, the General Public License is designed to make
6033 sure that you have the freedom to give away or sell copies of free
6034 software, that you receive source code or can get it if you want it,
6035 that you can change the software or use pieces of it in new free
6036 programs; and that you know you can do these things.
6038 To protect your rights, we need to make restrictions that forbid
6039 anyone to deny you these rights or to ask you to surrender the rights.
6040 These restrictions translate to certain responsibilities for you if you
6041 distribute copies of the software, or if you modify it.
6043 For example, if you distribute copies of a such a program, whether
6044 gratis or for a fee, you must give the recipients all the rights that
6045 you have. You must make sure that they, too, receive or can get the
6046 source code. And you must tell them their rights.
6048 We protect your rights with two steps: (1) copyright the software, and
6049 (2) offer you this license which gives you legal permission to copy,
6050 distribute and/or modify the software.
6052 Also, for each author's protection and ours, we want to make certain
6053 that everyone understands that there is no warranty for this free
6054 software. If the software is modified by someone else and passed on, we
6055 want its recipients to know that what they have is not the original, so
6056 that any problems introduced by others will not reflect on the original
6057 authors' reputations.
6059 The precise terms and conditions for copying, distribution and
6060 modification follow.
6063 @unnumberedsec TERMS AND CONDITIONS
6066 @center TERMS AND CONDITIONS
6071 This License Agreement applies to any program or other work which
6072 contains a notice placed by the copyright holder saying it may be
6073 distributed under the terms of this General Public License. The
6074 ``Program'', below, refers to any such program or work, and a ``work based
6075 on the Program'' means either the Program or any work containing the
6076 Program or a portion of it, either verbatim or with modifications. Each
6077 licensee is addressed as ``you''.
6080 You may copy and distribute verbatim copies of the Program's source
6081 code as you receive it, in any medium, provided that you conspicuously and
6082 appropriately publish on each copy an appropriate copyright notice and
6083 disclaimer of warranty; keep intact all the notices that refer to this
6084 General Public License and to the absence of any warranty; and give any
6085 other recipients of the Program a copy of this General Public License
6086 along with the Program. You may charge a fee for the physical act of
6087 transferring a copy.
6090 You may modify your copy or copies of the Program or any portion of
6091 it, and copy and distribute such modifications under the terms of Paragraph
6092 1 above, provided that you also do the following:
6096 cause the modified files to carry prominent notices stating that
6097 you changed the files and the date of any change; and
6100 cause the whole of any work that you distribute or publish, that
6101 in whole or in part contains the Program or any part thereof, either
6102 with or without modifications, to be licensed at no charge to all
6103 third parties under the terms of this General Public License (except
6104 that you may choose to grant warranty protection to some or all
6105 third parties, at your option).
6108 If the modified program normally reads commands interactively when
6109 run, you must cause it, when started running for such interactive use
6110 in the simplest and most usual way, to print or display an
6111 announcement including an appropriate copyright notice and a notice
6112 that there is no warranty (or else, saying that you provide a
6113 warranty) and that users may redistribute the program under these
6114 conditions, and telling the user how to view a copy of this General
6118 You may charge a fee for the physical act of transferring a
6119 copy, and you may at your option offer warranty protection in
6123 Mere aggregation of another independent work with the Program (or its
6124 derivative) on a volume of a storage or distribution medium does not bring
6125 the other work under the scope of these terms.
6128 You may copy and distribute the Program (or a portion or derivative of
6129 it, under Paragraph 2) in object code or executable form under the terms of
6130 Paragraphs 1 and 2 above provided that you also do one of the following:
6134 accompany it with the complete corresponding machine-readable
6135 source code, which must be distributed under the terms of
6136 Paragraphs 1 and 2 above; or,
6139 accompany it with a written offer, valid for at least three
6140 years, to give any third party free (except for a nominal charge
6141 for the cost of distribution) a complete machine-readable copy of the
6142 corresponding source code, to be distributed under the terms of
6143 Paragraphs 1 and 2 above; or,
6146 accompany it with the information you received as to where the
6147 corresponding source code may be obtained. (This alternative is
6148 allowed only for noncommercial distribution and only if you
6149 received the program in object code or executable form alone.)
6152 Source code for a work means the preferred form of the work for making
6153 modifications to it. For an executable file, complete source code means
6154 all the source code for all modules it contains; but, as a special
6155 exception, it need not include source code for modules which are standard
6156 libraries that accompany the operating system on which the executable
6157 file runs, or for standard header files or definitions files that
6158 accompany that operating system.
6161 You may not copy, modify, sublicense, distribute or transfer the
6162 Program except as expressly provided under this General Public License.
6163 Any attempt otherwise to copy, modify, sublicense, distribute or transfer
6164 the Program is void, and will automatically terminate your rights to use
6165 the Program under this License. However, parties who have received
6166 copies, or rights to use copies, from you under this General Public
6167 License will not have their licenses terminated so long as such parties
6168 remain in full compliance.
6171 By copying, distributing or modifying the Program (or any work based
6172 on the Program) you indicate your acceptance of this license to do so,
6173 and all its terms and conditions.
6176 Each time you redistribute the Program (or any work based on the
6177 Program), the recipient automatically receives a license from the original
6178 licensor to copy, distribute or modify the Program subject to these
6179 terms and conditions. You may not impose any further restrictions on the
6180 recipients' exercise of the rights granted herein.
6183 The Free Software Foundation may publish revised and/or new versions
6184 of the General Public License from time to time. Such new versions will
6185 be similar in spirit to the present version, but may differ in detail to
6186 address new problems or concerns.
6188 Each version is given a distinguishing version number. If the Program
6189 specifies a version number of the license which applies to it and ``any
6190 later version'', you have the option of following the terms and conditions
6191 either of that version or of any later version published by the Free
6192 Software Foundation. If the Program does not specify a version number of
6193 the license, you may choose any version ever published by the Free Software
6197 If you wish to incorporate parts of the Program into other free
6198 programs whose distribution conditions are different, write to the author
6199 to ask for permission. For software which is copyrighted by the Free
6200 Software Foundation, write to the Free Software Foundation; we sometimes
6201 make exceptions for this. Our decision will be guided by the two goals
6202 of preserving the free status of all derivatives of our free software and
6203 of promoting the sharing and reuse of software generally.
6206 @heading NO WARRANTY
6213 BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
6214 FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
6215 OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
6216 PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
6217 OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
6218 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
6219 TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
6220 PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
6221 REPAIR OR CORRECTION.
6224 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL
6225 ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
6226 REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
6227 INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES
6228 ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT
6229 LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES
6230 SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE
6231 WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
6232 ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
6236 @heading END OF TERMS AND CONDITIONS
6239 @center END OF TERMS AND CONDITIONS
6243 @unnumberedsec Applying These Terms to Your New Programs
6245 If you develop a new program, and you want it to be of the greatest
6246 possible use to humanity, the best way to achieve this is to make it
6247 free software which everyone can redistribute and change under these
6250 To do so, attach the following notices to the program. It is safest to
6251 attach them to the start of each source file to most effectively convey
6252 the exclusion of warranty; and each file should have at least the
6253 ``copyright'' line and a pointer to where the full notice is found.
6256 @var{one line to give the program's name and a brief idea of what it does.}
6257 Copyright (C) 19@var{yy} @var{name of author}
6259 This program is free software; you can redistribute it and/or modify
6260 it under the terms of the GNU General Public License as published by
6261 the Free Software Foundation; either version 1, or (at your option)
6264 This program is distributed in the hope that it will be useful,
6265 but WITHOUT ANY WARRANTY; without even the implied warranty of
6266 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
6267 GNU General Public License for more details.
6269 You should have received a copy of the GNU General Public License
6270 along with this program; if not, write to the Free Software
6271 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
6274 Also add information on how to contact you by electronic and paper mail.
6276 If the program is interactive, make it output a short notice like this
6277 when it starts in an interactive mode:
6280 Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
6281 Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
6282 This is free software, and you are welcome to redistribute it
6283 under certain conditions; type `show c' for details.
6286 The hypothetical commands `show w' and `show c' should show the
6287 appropriate parts of the General Public License. Of course, the
6288 commands you use may be called something other than `show w' and `show
6289 c'; they could even be mouse-clicks or menu items---whatever suits your
6292 You should also get your employer (if you work as a programmer) or your
6293 school, if any, to sign a ``copyright disclaimer'' for the program, if
6294 necessary. Here is a sample; alter the names:
6297 Yoyodyne, Inc., hereby disclaims all copyright interest in the
6298 program `Gnomovision' (a program to direct compilers to make passes
6299 at assemblers) written by James Hacker.
6301 @var{signature of Ty Coon}, 1 April 1989
6302 Ty Coon, President of Vice
6305 That's all there is to it!
6307 @node Index, , Copying, Top
6313 % I think something like @colophon should be in texinfo. In the
6315 \long\def\colophon{\hbox to0pt{}\vfill
6316 \centerline{The body of this manual is set in}
6317 \centerline{\fontname\tenrm,}
6318 \centerline{with headings in {\bf\fontname\tenbf}}
6319 \centerline{and examples in {\tt\fontname\tentt}.}
6320 \centerline{{\it\fontname\tenit\/} and}
6321 \centerline{{\sl\fontname\tensl\/}}
6322 \centerline{are used for emphasis.}\vfill}
6324 % Blame: pesch@cygnus.com, 28mar91.