Fri Jan 22 14:22:44 1993 Ian Lance Taylor (ian@cygnus.com)
[deliverable/binutils-gdb.git] / gdb / doc / gdb.texinfo
CommitLineData
b80282d5 1_dnl__ -*-Texinfo-*-
1041a570 2_dnl__ Copyright (c) 1988 1989 1990 1991 1992 Free Software Foundation, Inc.
b21b18e1 3_dnl__ $Id$<>_dnl__
29a2b744 4\input texinfo @c -*-texinfo-*-
1041a570 5@c Copyright (c) 1988 1989 1990 1991 1992 Free Software Foundation, Inc.
29a2b744 6@c %**start of header
5a131cc7 7@setfilename _GDBP__.info
29a2b744 8_if__(_GENERIC__)
a6463583 9@settitle Debugging with _GDBN__
29a2b744
RP
10_fi__(_GENERIC__)
11_if__(!_GENERIC__)
a6463583 12@settitle Debugging with _GDBN__ (_HOST__)
29a2b744
RP
13_fi__(!_GENERIC__)
14@setchapternewpage odd
fb4bb43e
RP
15@c @smallbook
16@c @cropmarks
29a2b744
RP
17@c %**end of header
18
19@finalout
20@syncodeindex ky cp
21
22_0__@c ===> NOTE! <==_1__
23@c Determine the edition number in *three* places by hand:
24@c 1. First ifinfo section 2. title page 3. top node
25@c To find the locations, search for !!set
26
27@c The following is for Pesch for his RCS system.
28@c This revision number *not* the same as the Edition number.
29@tex
30\def\$#1${{#1}} % Kluge: collect RCS revision info without $...$
31\xdef\manvers{\$Revision$} % For use in headers, footers too
32@end tex
33
d24e0922 34@c GDB CHANGELOG CONSULTED BETWEEN:
29a2b744
RP
35@c Fri Oct 11 23:27:06 1991 John Gilmore (gnu at cygnus.com)
36@c Sat Dec 22 02:51:40 1990 John Gilmore (gnu at cygint)
37
9c3ad547 38@c THIS MANUAL REQUIRES TEXINFO-2 macros and info-makers to format properly.
29a2b744 39
b7becc8f
RP
40@ifinfo
41@format
42START-INFO-DIR-ENTRY
29a2b744 43* Gdb: (gdb). The GNU debugger.
b7becc8f
RP
44END-INFO-DIR-ENTRY
45@end format
46@end ifinfo
5a131cc7
RP
47_if__(0)
48
a6d0b6d3
RP
49NOTE: this manual is marked up for preprocessing with a collection
50of m4 macros called "pretex.m4".
51
9bcc06ef
RP
52THIS IS THE SOURCE PRIOR TO PREPROCESSING. The full source needs to
53be run through m4 before either tex- or info- formatting: for example,
08665207 54_0__
3e0d0a27 55 m4 pretex.m4 none.m4 all.m4 gdb.texinfo >gdb-all.texinfo
70b88761 56will produce (assuming your path finds either GNU m4 >= 0.84, or SysV
1041a570 57m4; Berkeley will not do) a file suitable for formatting. See the text in
70b88761 58"pretex.m4" for a fuller explanation (and the macro definitions).
29a2b744 59_1__
e91b87a3 60
9bcc06ef 61_fi__(0)
70b88761 62@c
70b88761
RP
63@ifinfo
64This file documents the GNU debugger _GDBN__.
65
29a2b744 66@c !!set edition, date, version
a37d76c9 67This is Edition 4.06, October 1992,
a6463583 68of @cite{Debugging with _GDBN__: the GNU Source-Level Debugger}
29a2b744
RP
69for GDB Version _GDB_VN__.
70
95d5ceb9 71Copyright (C) 1988, 1989, 1990, 1991, 1992 Free Software Foundation, Inc.
70b88761
RP
72
73Permission is granted to make and distribute verbatim copies of
74this manual provided the copyright notice and this permission notice
75are preserved on all copies.
76
77@ignore
78Permission is granted to process this file through TeX and print the
79results, provided the printed document carries copying permission
80notice identical to this one except for the removal of this paragraph
81(this paragraph not being relevant to the printed manual).
82
83@end ignore
84Permission is granted to copy and distribute modified versions of this
85manual under the conditions for verbatim copying, provided also that the
86section entitled ``GNU General Public License'' is included exactly as
87in the original, and provided that the entire resulting derived work is
88distributed under the terms of a permission notice identical to this
89one.
90
91Permission is granted to copy and distribute translations of this manual
92into another language, under the above conditions for modified versions,
93except that the section entitled ``GNU General Public License'' may be
94included in a translation approved by the Free Software Foundation
95instead of in the original English.
96@end ifinfo
1041a570 97
70b88761 98@titlepage
a6463583 99@title Debugging with _GDBN__
95d5ceb9 100@subtitle The GNU Source-Level Debugger
70b88761 101_if__(!_GENERIC__)
c7cb8acb 102@subtitle on _HOST__ Systems
70b88761
RP
103_fi__(!_GENERIC__)
104@sp 1
29a2b744 105@c !!set edition, date, version
a6463583 106@subtitle Edition 4.06, for _GDBN__ version _GDB_VN__
a37d76c9 107@subtitle October 1992
29a2b744 108@author by Richard M. Stallman and Roland H. Pesch
70b88761
RP
109@page
110@tex
111{\parskip=0pt
93ac5532 112\hfill pesch\@cygnus.com\par
712b9893 113\hfill (Send bugs and comments on _GDBN__ to bug-gdb\@prep.ai.mit.edu.)
a6463583 114\hfill {\it Debugging with _GDBN__}, \manvers\par
70b88761
RP
115\hfill \TeX{}info \texinfoversion\par
116}
117@end tex
118
119@vskip 0pt plus 1filll
1041a570 120Copyright @copyright{} 1988, 1989, 1990, 1991, 1992 Free Software Foundation, Inc.
70b88761
RP
121
122Permission is granted to make and distribute verbatim copies of
123this manual provided the copyright notice and this permission notice
124are preserved on all copies.
125
126Permission is granted to copy and distribute modified versions of this
127manual under the conditions for verbatim copying, provided also that the
128section entitled ``GNU General Public License'' is included exactly as
129in the original, and provided that the entire resulting derived work is
130distributed under the terms of a permission notice identical to this
131one.
132
133Permission is granted to copy and distribute translations of this manual
134into another language, under the above conditions for modified versions,
135except that the section entitled ``GNU General Public License'' may be
136included in a translation approved by the Free Software Foundation
137instead of in the original English.
138@end titlepage
139@page
140
70b88761 141@ifinfo
4eb4cf57 142@node Top
a6463583 143@top Debugging with _GDBN__
29a2b744
RP
144
145This file describes _GDBN__, the GNU symbolic debugger.
146
147@c !!set edition, date, version
a37d76c9 148This is Edition 4.06, October 1992, for GDB Version _GDB_VN__.
70b88761
RP
149@end ifinfo
150
151@menu
b80282d5 152* Summary:: Summary of _GDBN__
4eb4cf57 153_if__(_GENERIC__ || !_H8__)
c7cb8acb 154* New Features:: New features since GDB version 3.5
4eb4cf57 155_fi__(_GENERIC__ || !_H8__)
0f153e74 156_if__(!_BARE__)
95d5ceb9 157* Sample Session:: A sample _GDBN__ session
0f153e74 158_fi__(!_BARE__)
29a2b744
RP
159* Invocation:: Getting in and out of _GDBN__
160* Commands:: _GDBN__ commands
161* Running:: Running programs under _GDBN__
162* Stopping:: Stopping and continuing
163* Stack:: Examining the stack
164* Source:: Examining source files
165* Data:: Examining data
4eb4cf57 166_if__(!_CONLY__)
29a2b744 167* Languages:: Using _GDBN__ with different languages
4eb4cf57
RP
168_fi__(!_CONLY__)
169_if__(_CONLY__)
170* C:: C and C++
171_fi__(_CONLY__)
29a2b744
RP
172* Symbols:: Examining the symbol table
173* Altering:: Altering execution
174* _GDBN__ Files:: _GDBN__'s files
175* Targets:: Specifying a debugging target
c2bbbb22 176* Controlling _GDBN__:: Controlling _GDBN__
29a2b744 177* Sequences:: Canned sequences of commands
4eb4cf57 178_if__(!_DOSHOST__)
b80282d5 179* Emacs:: Using _GDBN__ under GNU Emacs
4eb4cf57 180_fi__(!_DOSHOST__)
29a2b744 181* _GDBN__ Bugs:: Reporting bugs in _GDBN__
77fe5411 182_if__(_GENERIC__||!_H8__)
e251e767 183* Renamed Commands::
77fe5411 184_fi__(_GENERIC__||!_H8__)
77b46d13 185* Formatting Documentation:: How to format and print GDB documentation
c7cb8acb 186* Installing GDB:: Installing GDB
b80282d5
RP
187* Copying:: GNU GENERAL PUBLIC LICENSE
188* Index:: Index
70b88761
RP
189@end menu
190
4eb4cf57 191@node Summary
70b88761
RP
192@unnumbered Summary of _GDBN__
193
194The purpose of a debugger such as _GDBN__ is to allow you to see what is
195going on ``inside'' another program while it executes---or what another
1041a570 196program was doing at the moment it crashed.
70b88761
RP
197
198_GDBN__ can do four main kinds of things (plus other things in support of
1041a570 199these) to help you catch bugs in the act:
70b88761
RP
200
201@itemize @bullet
202@item
203Start your program, specifying anything that might affect its behavior.
204
205@item
206Make your program stop on specified conditions.
207
208@item
209Examine what has happened, when your program has stopped.
210
211@item
212Change things in your program, so you can experiment with correcting the
213effects of one bug and go on to learn about another.
214@end itemize
215
0f153e74 216_if__(!_CONLY__)
c2bbbb22
RP
217You can use _GDBN__ to debug programs written in C, C++, and Modula-2.
218Fortran support will be added when a GNU Fortran compiler is ready.
0f153e74 219_fi__(!_CONLY__)
70b88761
RP
220
221@menu
b80282d5
RP
222* Free Software:: Free Software
223* Contributors:: Contributors to GDB
70b88761
RP
224@end menu
225
4eb4cf57 226@node Free Software
70b88761 227@unnumberedsec Free Software
1041a570
RP
228
229_GDBN__ is @dfn{free software}, protected by the GNU General Public License
230(GPL). The GPL gives you the freedom to copy or adapt a licensed
70b88761
RP
231program---but every person getting a copy also gets with it the
232freedom to modify that copy (which means that they must get access to
233the source code), and the freedom to distribute further copies.
234Typical software companies use copyrights to limit your freedoms; the
235Free Software Foundation uses the GPL to preserve these freedoms.
236
237Fundamentally, the General Public License is a license which says that
29a2b744 238you have these freedoms and that you cannot take these freedoms away
70b88761
RP
239from anyone else.
240
0f153e74 241_if__(!_AGGLOMERATION__)
29a2b744 242For full details, @pxref{Copying, ,GNU GENERAL PUBLIC LICENSE}.
0f153e74 243_fi__(!_AGGLOMERATION__)
1041a570 244
4eb4cf57 245@node Contributors
70b88761
RP
246@unnumberedsec Contributors to GDB
247
248Richard Stallman was the original author of GDB, and of many other GNU
249programs. Many others have contributed to its development. This
250section attempts to credit major contributors. One of the virtues of
251free software is that everyone is free to contribute to it; with
252regret, we cannot actually acknowledge everyone here. The file
253@file{ChangeLog} in the GDB distribution approximates a blow-by-blow
254account.
255
256Changes much prior to version 2.0 are lost in the mists of time.
257
258@quotation
259@emph{Plea:} Additions to this section are particularly welcome. If you
260or your friends (or enemies; let's be evenhanded) have been unfairly
261omitted from this list, we would like to add your names!
262@end quotation
263
264So that they may not regard their long labor as thankless, we
69bbcf05 265particularly thank those who shepherded GDB through major releases: Stu
6f3ec223
RP
266Grossman and John Gilmore (releases 4.6, 4.5, 4.4), John Gilmore
267(releases 4.3, 4.2, 4.1, 4.0, and 3.9); Jim Kingdon (releases 3.5, 3.4,
2683.3); and Randy Smith (releases 3.2, 3.1, 3.0). As major maintainer of
269GDB for some period, each contributed significantly to the structure,
270stability, and capabilities of the entire debugger.
70b88761
RP
271
272Richard Stallman, assisted at various times by Pete TerMaat, Chris
273Hanson, and Richard Mlynarik, handled releases through 2.8.
274
275Michael Tiemann is the author of most of the GNU C++ support in GDB,
276with significant additional contributions from Per Bothner. James
277Clark wrote the GNU C++ demangler. Early work on C++ was by Peter
278TerMaat (who also did much general update work leading to release 3.0).
279
1041a570
RP
280GDB 4 uses the BFD subroutine library to examine multiple
281object-file formats; BFD was a joint project of David V.
282Henkel-Wallace, Rich Pixley, Steve Chamberlain, and John Gilmore.
70b88761 283
1041a570
RP
284David Johnson wrote the original COFF support; Pace Willison did
285the original support for encapsulated COFF.
70b88761
RP
286
287Adam de Boor and Bradley Davis contributed the ISI Optimum V support.
288Per Bothner, Noboyuki Hikichi, and Alessandro Forin contributed MIPS
1041a570
RP
289support. Jean-Daniel Fekete contributed Sun 386i support. Chris
290Hanson improved the HP9000 support. Noboyuki Hikichi and Tomoyuki
291Hasei contributed Sony/News OS 3 support. David Johnson contributed
292Encore Umax support. Jyrki Kuoppala contributed Altos 3068 support.
293Keith Packard contributed NS32K support. Doug Rabson contributed
294Acorn Risc Machine support. Chris Smith contributed Convex support
295(and Fortran debugging). Jonathan Stone contributed Pyramid support.
296Michael Tiemann contributed SPARC support. Tim Tucker contributed
297support for the Gould NP1 and Gould Powernode. Pace Willison
298contributed Intel 386 support. Jay Vosburgh contributed Symmetry
299support.
70b88761 300
c338a2fd
RP
301Rich Schaefer and Peter Schauer helped with support of SunOS shared
302libraries.
70b88761
RP
303
304Jay Fenlason and Roland McGrath ensured that GDB and GAS agree about
305several machine instruction sets.
306
1041a570
RP
307Patrick Duval, Ted Goldstein, Vikram Koka and Glenn Engel helped
308develop remote debugging. Intel Corporation and Wind River Systems
309contributed remote debugging modules for their products.
70b88761 310
1041a570
RP
311Brian Fox is the author of the readline libraries providing
312command-line editing and command history.
70b88761 313
1041a570
RP
314Andrew Beers of SUNY Buffalo wrote the language-switching code and
315the Modula-2 support, and contributed the Languages chapter of this
316manual.
c2bbbb22 317
6f3ec223
RP
318Fred Fish wrote most of the support for Unix System Vr4, and enhanced
319the command-completion support to cover C++ overloaded symbols.
14d01801 320
4eb4cf57
RP
321_if__(_GENERIC__ || !_H8__)
322@node New Features
c7cb8acb 323@unnumbered New Features since GDB version 3.5
70b88761
RP
324
325@table @emph
326@item Targets
327Using the new command @code{target}, you can select at runtime whether
328you are debugging local files, local processes, standalone systems over
b80282d5
RP
329a serial port, realtime systems over a TCP/IP connection, etc. The
330command @code{load} can download programs into a remote system. Serial
b21b18e1
RP
331stubs are available for Motorola 680x0, Intel 80386, and Sparc remote
332systems; GDB also supports debugging realtime processes running under
b80282d5 333VxWorks, using SunRPC Remote Procedure Calls over TCP/IP to talk to a
b21b18e1
RP
334debugger stub on the target system. Internally, GDB now uses a function
335vector to mediate access to different targets; if you need to add your
336own support for a remote protocol, this makes it much easier.
70b88761
RP
337
338@item Watchpoints
c7cb8acb 339GDB now sports watchpoints as well as breakpoints. You can use a
70b88761
RP
340watchpoint to stop execution whenever the value of an expression
341changes, without having to predict a particular place in your program
342where this may happen.
343
b80282d5
RP
344@item Wide Output
345Commands that issue wide output now insert newlines at places designed
346to make the output more readable.
347
70b88761 348@item Object Code Formats
c7cb8acb 349GDB uses a new library called the Binary File Descriptor (BFD)
3d3ab540
RP
350Library to permit it to switch dynamically, without reconfiguration or
351recompilation, between different object-file formats. Formats currently
352supported are COFF, a.out, and the Intel 960 b.out; files may be read as
353.o's, archive libraries, or core dumps. BFD is available as a
354subroutine library so that other programs may take advantage of it, and
355the other GNU binary utilities are being converted to use it.
70b88761 356
b80282d5 357@item Configuration and Ports
70b88761 358Compile-time configuration (to select a particular architecture and
7463aadd 359operating system) is much easier. The script @code{configure} now
c7cb8acb
RP
360allows you to configure GDB as either a native debugger or a
361cross-debugger. @xref{Installing GDB}, for details on how to
6a8cb0e7 362configure.
70b88761
RP
363
364@item Interaction
c7cb8acb 365The user interface to GDB's control variables has been simplified
70b88761
RP
366and consolidated in two commands, @code{set} and @code{show}. Output
367lines are now broken at readable places, rather than overflowing onto
368the next line. You can suppress output of machine-level addresses,
369displaying only source language information.
370
b80282d5 371@item C++
c7cb8acb 372GDB now supports C++ multiple inheritance (if used with a GCC
b80282d5 373version 2 compiler), and also has limited support for C++ exception
c7cb8acb 374handling, with the commands @code{catch} and @code{info catch}: GDB
b80282d5
RP
375can break when an exception is raised, before the stack is peeled back
376to the exception handler's context.
70b88761 377
c2bbbb22 378@item Modula-2
c7cb8acb 379GDB now has preliminary support for the GNU Modula-2 compiler,
c2bbbb22 380currently under development at the State University of New York at
c7cb8acb 381Buffalo. Coordinated development of both GDB and the GNU Modula-2
5b0fdf7b
RP
382compiler will continue into 1992. Other Modula-2 compilers are
383currently not supported, and attempting to debug programs compiled with
384them will likely result in an error as the symbol table of the
385executable is read in.
c2bbbb22 386
70b88761 387@item Command Rationalization
c7cb8acb 388Many GDB commands have been renamed to make them easier to remember
70b88761
RP
389and use. In particular, the subcommands of @code{info} and
390@code{show}/@code{set} are grouped to make the former refer to the state
c7cb8acb 391of your program, and the latter refer to the state of GDB itself.
70b88761
RP
392@xref{Renamed Commands}, for details on what commands were renamed.
393
70b88761 394@item Shared Libraries
77b46d13
JG
395GDB 4 can debug programs and core files that use SunOS, SVR4, or IBM RS/6000
396shared libraries.
b80282d5
RP
397
398@item Reference Card
6f3ec223
RP
399GDB 4 has a reference card. @xref{Formatting Documentation,,Formatting
400the Documentation}, for instructions to print it.
70b88761
RP
401
402@item Work in Progress
403Kernel debugging for BSD and Mach systems; Tahoe and HPPA architecture
404support.
70b88761 405@end table
4eb4cf57 406_fi__(_GENERIC__ || !_H8__)
70b88761 407
0f153e74 408_if__(!_BARE__)
4eb4cf57 409@node Sample Session
70b88761
RP
410@chapter A Sample _GDBN__ Session
411
412You can use this manual at your leisure to read all about _GDBN__.
413However, a handful of commands are enough to get started using the
414debugger. This chapter illustrates these commands.
415
416@iftex
6ca72cc6 417In this sample session, we emphasize user input like this: @b{input},
70b88761
RP
418to make it easier to pick out from the surrounding output.
419@end iftex
420
421@c FIXME: this example may not be appropriate for some configs, where
422@c FIXME...primary interest is in remote use.
423_0__
424One of the preliminary versions of GNU @code{m4} (a generic macro
425processor) exhibits the following bug: sometimes, when we change its
426quote strings from the default, the commands used to capture one macro's
427definition in another stop working. In the following short @code{m4}
428session, we define a macro @code{foo} which expands to @code{0000}; we
29a2b744 429then use the @code{m4} built-in @code{defn} to define @code{bar} as the
70b88761
RP
430same thing. However, when we change the open quote string to
431@code{<QUOTE>} and the close quote string to @code{<UNQUOTE>}, the same
432procedure fails to define a new synonym @code{baz}:
433
434@smallexample
6ca72cc6
RP
435$ @b{cd gnu/m4}
436$ @b{./m4}
437@b{define(foo,0000)}
70b88761 438
6ca72cc6 439@b{foo}
70b88761 4400000
6ca72cc6 441@b{define(bar,defn(`foo'))}
70b88761 442
6ca72cc6 443@b{bar}
70b88761 4440000
6ca72cc6 445@b{changequote(<QUOTE>,<UNQUOTE>)}
70b88761 446
6ca72cc6
RP
447@b{define(baz,defn(<QUOTE>foo<UNQUOTE>))}
448@b{baz}
449@b{C-d}
70b88761
RP
450m4: End of input: 0: fatal error: EOF in string
451@end smallexample
452
453@noindent
454Let's use _GDBN__ to try to see what's going on.
455
456@smallexample
6ca72cc6 457$ @b{_GDBP__ m4}
203eea5d
RP
458@c FIXME: this falsifies the exact text played out, to permit smallbook
459@c FIXME... format to come out better.
460GDB is free software and you are welcome to distribute copies
461 of it under certain conditions; type "show copying" to see
462 the conditions.
463There is absolutely no warranty for GDB; type "show warranty"
464for details.
5b0fdf7b 465GDB _GDB_VN__, Copyright 1992 Free Software Foundation, Inc...
e251e767 466(_GDBP__)
70b88761
RP
467@end smallexample
468
469@noindent
1041a570
RP
470_GDBN__ reads only enough symbol data to know where to find the rest when
471needed; as a result, the first prompt comes up very quickly. We now
472tell _GDBN__ to use a narrower display width than usual, so that examples
473will fit in this manual.
70b88761
RP
474
475@smallexample
6ca72cc6 476(_GDBP__) @b{set width 70}
70b88761
RP
477@end smallexample
478
e251e767 479@noindent
29a2b744 480Let's see how the @code{m4} built-in @code{changequote} works.
70b88761
RP
481Having looked at the source, we know the relevant subroutine is
482@code{m4_changequote}, so we set a breakpoint there with _GDBN__'s
483@code{break} command.
484
485@smallexample
6ca72cc6 486(_GDBP__) @b{break m4_changequote}
70b88761
RP
487Breakpoint 1 at 0x62f4: file builtin.c, line 879.
488@end smallexample
489
490@noindent
491Using the @code{run} command, we start @code{m4} running under _GDBN__
492control; as long as control does not reach the @code{m4_changequote}
493subroutine, the program runs as usual:
494
495@smallexample
6ca72cc6 496(_GDBP__) @b{run}
e251e767 497Starting program: /work/Editorial/gdb/gnu/m4/m4
6ca72cc6 498@b{define(foo,0000)}
70b88761 499
6ca72cc6 500@b{foo}
70b88761
RP
5010000
502@end smallexample
503
504@noindent
505To trigger the breakpoint, we call @code{changequote}. _GDBN__
506suspends execution of @code{m4}, displaying information about the
507context where it stops.
508
509@smallexample
6ca72cc6 510@b{changequote(<QUOTE>,<UNQUOTE>)}
70b88761 511
203eea5d
RP
512Breakpoint 1, m4_changequote (argc=3, argv=0x33c70)
513 at builtin.c:879
38962738 514879 if (bad_argc(TOKEN_DATA_TEXT(argv[0]),argc,1,3))
70b88761
RP
515@end smallexample
516
517@noindent
518Now we use the command @code{n} (@code{next}) to advance execution to
519the next line of the current function.
520
521@smallexample
6ca72cc6 522(_GDBP__) @b{n}
203eea5d
RP
523882 set_quotes((argc >= 2) ? TOKEN_DATA_TEXT(argv[1])\
524 : nil,
70b88761
RP
525@end smallexample
526
527@noindent
528@code{set_quotes} looks like a promising subroutine. We can go into it
529by using the command @code{s} (@code{step}) instead of @code{next}.
530@code{step} goes to the next line to be executed in @emph{any}
e251e767 531subroutine, so it steps into @code{set_quotes}.
70b88761
RP
532
533@smallexample
6ca72cc6 534(_GDBP__) @b{s}
70b88761
RP
535set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>")
536 at input.c:530
537530 if (lquote != def_lquote)
538@end smallexample
539
540@noindent
29a2b744
RP
541The display that shows the subroutine where @code{m4} is now
542suspended (and its arguments) is called a stack frame display. It
543shows a summary of the stack. We can use the @code{backtrace}
544command (which can also be spelled @code{bt}), to see where we are
545in the stack as a whole: the @code{backtrace} command displays a
546stack frame for each active subroutine.
70b88761
RP
547
548@smallexample
6ca72cc6 549(_GDBP__) @b{bt}
70b88761
RP
550#0 set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>")
551 at input.c:530
203eea5d
RP
552#1 0x6344 in m4_changequote (argc=3, argv=0x33c70)
553 at builtin.c:882
70b88761
RP
554#2 0x8174 in expand_macro (sym=0x33320) at macro.c:242
555#3 0x7a88 in expand_token (obs=0x0, t=209696, td=0xf7fffa30)
556 at macro.c:71
557#4 0x79dc in expand_input () at macro.c:40
558#5 0x2930 in main (argc=0, argv=0xf7fffb20) at m4.c:195
559@end smallexample
560
561@noindent
562Let's step through a few more lines to see what happens. The first two
563times, we can use @samp{s}; the next two times we use @code{n} to avoid
564falling into the @code{xstrdup} subroutine.
1041a570 565
70b88761 566@smallexample
6ca72cc6 567(_GDBP__) @b{s}
70b88761 5680x3b5c 532 if (rquote != def_rquote)
6ca72cc6 569(_GDBP__) @b{s}
203eea5d
RP
5700x3b80 535 lquote = (lq == nil || *lq == '\0') ? \
571def_lquote : xstrdup(lq);
6ca72cc6 572(_GDBP__) @b{n}
203eea5d
RP
573536 rquote = (rq == nil || *rq == '\0') ? def_rquote\
574 : xstrdup(rq);
6ca72cc6 575(_GDBP__) @b{n}
70b88761
RP
576538 len_lquote = strlen(rquote);
577@end smallexample
578
579@noindent
580The last line displayed looks a little odd; let's examine the variables
581@code{lquote} and @code{rquote} to see if they are in fact the new left
582and right quotes we specified. We can use the command @code{p}
583(@code{print}) to see their values.
584
585@smallexample
6ca72cc6 586(_GDBP__) @b{p lquote}
70b88761 587$1 = 0x35d40 "<QUOTE>"
6ca72cc6 588(_GDBP__) @b{p rquote}
70b88761
RP
589$2 = 0x35d50 "<UNQUOTE>"
590@end smallexample
591
592@noindent
593@code{lquote} and @code{rquote} are indeed the new left and right quotes.
594Let's look at some context; we can display ten lines of source
595surrounding the current line, with the @code{l} (@code{list}) command.
596
597@smallexample
6ca72cc6 598(_GDBP__) @b{l}
70b88761 599533 xfree(rquote);
e251e767 600534
203eea5d
RP
601535 lquote = (lq == nil || *lq == '\0') ? def_lquote\
602 : xstrdup (lq);
603536 rquote = (rq == nil || *rq == '\0') ? def_rquote\
604 : xstrdup (rq);
e251e767 605537
70b88761
RP
606538 len_lquote = strlen(rquote);
607539 len_rquote = strlen(lquote);
608540 @}
e251e767 609541
70b88761
RP
610542 void
611@end smallexample
612
613@noindent
614Let's step past the two lines that set @code{len_lquote} and
615@code{len_rquote}, and then examine the values of those variables.
616
617@smallexample
6ca72cc6 618(_GDBP__) @b{n}
70b88761 619539 len_rquote = strlen(lquote);
6ca72cc6 620(_GDBP__) @b{n}
70b88761 621540 @}
6ca72cc6 622(_GDBP__) @b{p len_lquote}
70b88761 623$3 = 9
6ca72cc6 624(_GDBP__) @b{p len_rquote}
70b88761
RP
625$4 = 7
626@end smallexample
627
628@noindent
629That certainly looks wrong, assuming @code{len_lquote} and
630@code{len_rquote} are meant to be the lengths of @code{lquote} and
631@code{rquote} respectively. Let's try setting them to better values.
632We can use the @code{p} command for this, since it'll print the value of
633any expression---and that expression can include subroutine calls and
e251e767 634assignments.
70b88761
RP
635
636@smallexample
6ca72cc6 637(_GDBP__) @b{p len_lquote=strlen(lquote)}
70b88761 638$5 = 7
6ca72cc6 639(_GDBP__) @b{p len_rquote=strlen(rquote)}
70b88761
RP
640$6 = 9
641@end smallexample
642
643@noindent
644Let's see if that fixes the problem of using the new quotes with the
645@code{m4} built-in @code{defn}. We can allow @code{m4} to continue
646executing with the @code{c} (@code{continue}) command, and then try the
647example that caused trouble initially:
648
649@smallexample
6ca72cc6 650(_GDBP__) @b{c}
70b88761
RP
651Continuing.
652
6ca72cc6 653@b{define(baz,defn(<QUOTE>foo<UNQUOTE>))}
70b88761
RP
654
655baz
6560000
657@end smallexample
658
659@noindent
660Success! The new quotes now work just as well as the default ones. The
661problem seems to have been just the two typos defining the wrong
662lengths. We'll let @code{m4} exit by giving it an EOF as input.
663
664@smallexample
6ca72cc6 665@b{C-d}
70b88761
RP
666Program exited normally.
667@end smallexample
668
e251e767 669@noindent
70b88761
RP
670The message @samp{Program exited normally.} is from _GDBN__; it
671indicates @code{m4} has finished executing. We can end our _GDBN__
672session with the _GDBN__ @code{quit} command.
673
674@smallexample
6ca72cc6 675(_GDBP__) @b{quit}
70b88761 676_1__@end smallexample
0f153e74 677_fi__(!_BARE__)
70b88761 678
4eb4cf57 679@node Invocation
70b88761
RP
680@chapter Getting In and Out of _GDBN__
681
c7cb8acb
RP
682This chapter discusses how to start _GDBN__, and how to get out of it.
683(The essentials: type @samp{_GDBP__} to start GDB, and type @kbd{quit}
684or @kbd{C-d} to exit.)
29a2b744 685
70b88761 686@menu
29a2b744 687* Invoking _GDBN__:: Starting _GDBN__
c2bbbb22 688* Leaving _GDBN__:: Leaving _GDBN__
4eb4cf57 689_if__(!_BARE__)
b80282d5 690* Shell Commands:: Shell Commands
4eb4cf57 691_fi__(!_BARE__)
70b88761
RP
692@end menu
693
4eb4cf57 694@node Invoking _GDBN__
70b88761
RP
695@section Starting _GDBN__
696
4eb4cf57
RP
697_if__(_H8__)
698For details on starting up _GDBP__ as a
699remote debugger attached to a Hitachi H8/300 board, see @ref{Hitachi
700H8/300 Remote,,_GDBN__ and the Hitachi H8/300}.
701_fi__(_H8__)
702
703Start _GDBN__ by running the program @code{_GDBP__}. Once it's running,
1041a570 704_GDBN__ reads commands from the terminal until you tell it to exit.
70b88761 705
c7cb8acb
RP
706You can also run @code{_GDBP__} with a variety of arguments and options,
707to specify more of your debugging environment at the outset.
708
0005054f 709_if__(_GENERIC__)
c7cb8acb
RP
710The command-line options described here are designed
711to cover a variety of situations; in some environments, some of these
712options may effectively be unavailable.
0005054f 713_fi__(_GENERIC__)
c7cb8acb 714
4eb4cf57
RP
715The most usual way to start _GDBN__ is with one argument,
716specifying an executable program:
1041a570 717
70b88761 718@example
29a2b744 719_GDBP__ @var{program}
70b88761 720@end example
1041a570 721
4eb4cf57 722_if__(!_BARE__)
70b88761 723@noindent
29a2b744
RP
724You can also start with both an executable program and a core file
725specified:
1041a570 726
70b88761 727@example
29a2b744 728_GDBP__ @var{program} @var{core}
70b88761
RP
729@end example
730
b80282d5
RP
731You can, instead, specify a process ID as a second argument, if you want
732to debug a running process:
1041a570 733
b80282d5 734@example
29a2b744 735_GDBP__ @var{program} 1234
b80282d5 736@end example
1041a570 737
b80282d5
RP
738@noindent
739would attach _GDBN__ to process @code{1234} (unless you also have a file
740named @file{1234}; _GDBN__ does check for a core file first).
741
c7cb8acb
RP
742Taking advantage of the second command-line argument requires a fairly
743complete operating system; when you use _GDBN__ as a remote debugger
744attached to a bare board, there may not be any notion of ``process'',
745and there is often no way to get a core dump.
4eb4cf57 746_fi__(!_BARE__)
c7cb8acb 747
70b88761
RP
748@noindent
749You can further control how _GDBN__ starts up by using command-line
29a2b744
RP
750options. _GDBN__ itself can remind you of the options available.
751
752@noindent
753Type
754
70b88761
RP
755@example
756_GDBP__ -help
757@end example
29a2b744 758
70b88761 759@noindent
29a2b744 760to display all available options and briefly describe their use
70b88761
RP
761(@samp{_GDBP__ -h} is a shorter equivalent).
762
763All options and command line arguments you give are processed
764in sequential order. The order makes a difference when the
e251e767 765@samp{-x} option is used.
70b88761
RP
766
767@menu
70b88761
RP
768_if__(!_GENERIC__)
769_include__(gdbinv-m.m4)_dnl__
770_fi__(!_GENERIC__)
4eb4cf57
RP
771* File Options:: Choosing Files
772* Mode Options:: Choosing Modes
70b88761
RP
773@end menu
774
4eb4cf57
RP
775_if__(!_GENERIC__)
776_include__(gdbinv-s.m4)
777_fi__(!_GENERIC__)
778
779@node File Options
70b88761
RP
780@subsection Choosing Files
781
4eb4cf57 782_if__(!_BARE__)
29a2b744
RP
783When _GDBN__ starts, it reads any arguments other than options as
784specifying an executable file and core file (or process ID). This is
785the same as if the arguments were specified by the @samp{-se} and
786@samp{-c} options respectively. (_GDBN__ reads the first argument
787that does not have an associated option flag as equivalent to the
788@samp{-se} option followed by that argument; and the second argument
789that does not have an associated option flag, if any, as equivalent to
790the @samp{-c} option followed by that argument.)
4eb4cf57
RP
791_fi__(!_BARE__)
792_if__(_BARE__)
793When _GDBN__ starts, it reads any argument other than options as
794specifying an executable file. This is the same as if the argument was
795specified by the @samp{-se} option.
796_fi__(_BARE__)
29a2b744
RP
797
798Many options have both long and short forms; both are shown in the
799following list. _GDBN__ also recognizes the long forms if you truncate
800them, so long as enough of the option is present to be unambiguous.
801(If you prefer, you can flag option arguments with @samp{--} rather
802than @samp{-}, though we illustrate the more usual convention.)
70b88761
RP
803
804@table @code
805@item -symbols=@var{file}
806@itemx -s @var{file}
807Read symbol table from file @var{file}.
808
809@item -exec=@var{file}
810@itemx -e @var{file}
811Use file @var{file} as the executable file to execute when
812appropriate, and for examining pure data in conjunction with a core
813dump.
814
3d3ab540 815@item -se=@var{file}
70b88761
RP
816Read symbol table from file @var{file} and use it as the executable
817file.
818
4eb4cf57 819_if__(!_BARE__)
70b88761
RP
820@item -core=@var{file}
821@itemx -c @var{file}
822Use file @var{file} as a core dump to examine.
4eb4cf57 823_fi__(!_BARE__)
70b88761
RP
824
825@item -command=@var{file}
826@itemx -x @var{file}
827Execute _GDBN__ commands from file @var{file}. @xref{Command Files}.
828
829@item -directory=@var{directory}
830@itemx -d @var{directory}
831Add @var{directory} to the path to search for source files.
14d01801 832
4eb4cf57 833_if__(!_BARE__)
14d01801
RP
834@item -m
835@itemx -mapped
836@emph{Warning: this option depends on operating system facilities that are not
837supported on all systems.}@*
77b46d13
JG
838If memory-mapped files are available on your system through the @code{mmap}
839system call, you can use this option
5a2c1d85 840to have _GDBN__ write the symbols from your
77b46d13
JG
841program into a reusable file in the current directory. If the program you are debugging is
842called @file{/tmp/fred}, the mapped symbol file will be @file{./fred.syms}.
843Future _GDBN__ debugging sessions will notice the presence of this file,
844and will quickly map in symbol information from it, rather than reading
845the symbol table from the executable program.
846
847The @file{.syms} file is specific to the host machine on which _GDBN__ is run.
848It holds an exact image of _GDBN__'s internal symbol table. It cannot be
849shared across multiple host platforms.
4eb4cf57 850_fi__(!_BARE__)
77b46d13
JG
851
852@item -r
853@itemx -readnow
854Read each symbol file's entire symbol table immediately, rather than
855the default, which is to read it incrementally as it is needed.
856This makes startup slower, but makes future operations faster.
70b88761
RP
857@end table
858
4eb4cf57 859_if__(!_BARE__)
77b46d13
JG
860The @code{-mapped} and @code{-readnow} options are typically combined in order to
861build a @file{.syms} file that contains complete symbol information.
862A simple GDB invocation to do nothing but build a @file{.syms} file for future
863use is:
864
865@example
866 gdb -batch -nx -mapped -readnow programname
867@end example
4eb4cf57 868_fi__(!_BARE__)
77b46d13 869
4eb4cf57 870@node Mode Options
1041a570
RP
871@subsection Choosing Modes
872
29a2b744
RP
873You can run _GDBN__ in various alternative modes---for example, in
874batch mode or quiet mode.
70b88761
RP
875
876@table @code
877@item -nx
878@itemx -n
879Do not execute commands from any @file{_GDBINIT__} initialization files.
880Normally, the commands in these files are executed after all the
e251e767 881command options and arguments have been processed.
c728f1f0 882@xref{Command Files}.
70b88761
RP
883
884@item -quiet
885@itemx -q
886``Quiet''. Do not print the introductory and copyright messages. These
c338a2fd 887messages are also suppressed in batch mode.
70b88761
RP
888
889@item -batch
890Run in batch mode. Exit with status @code{0} after processing all the command
891files specified with @samp{-x} (and @file{_GDBINIT__}, if not inhibited).
892Exit with nonzero status if an error occurs in executing the _GDBN__
e251e767 893commands in the command files.
70b88761
RP
894
895Batch mode may be useful for running _GDBN__ as a filter, for example to
896download and run a program on another computer; in order to make this
e251e767 897more useful, the message
1041a570 898
70b88761
RP
899@example
900Program exited normally.
901@end example
1041a570 902
70b88761
RP
903@noindent
904(which is ordinarily issued whenever a program running under _GDBN__ control
905terminates) is not issued when running in batch mode.
906
3d3ab540 907@item -cd=@var{directory}
70b88761
RP
908Run _GDBN__ using @var{directory} as its working directory,
909instead of the current directory.
910
6ca72cc6 911_if__(_LUCID__)
45c53080 912@item -context @var{authentication}
6ca72cc6
RP
913When the Energize programming system starts up _GDBN__, it uses this
914option to trigger an alternate mode of interaction.
915@var{authentication} is a pair of numeric codes that identify _GDBN__
916as a client in the Energize environment. Avoid this option when you run
917_GDBN__ directly from the command line. See @ref{Energize,,Using
918_GDBN__ with Energize} for more discussion of using _GDBN__ with Energize.
919_fi__(_LUCID__)
920
70b88761
RP
921@item -fullname
922@itemx -f
923Emacs sets this option when it runs _GDBN__ as a subprocess. It tells _GDBN__
924to output the full file name and line number in a standard,
925recognizable fashion each time a stack frame is displayed (which
29a2b744 926includes each time your program stops). This recognizable format looks
70b88761
RP
927like two @samp{\032} characters, followed by the file name, line number
928and character position separated by colons, and a newline. The
929Emacs-to-_GDBN__ interface program uses the two @samp{\032} characters as
930a signal to display the source code for the frame.
931
4eb4cf57 932_if__(_GENERIC__ || !_H8__)
70b88761
RP
933@item -b @var{bps}
934Set the line speed (baud rate or bits per second) of any serial
935interface used by _GDBN__ for remote debugging.
936
3d3ab540 937@item -tty=@var{device}
70b88761 938Run using @var{device} for your program's standard input and output.
29a2b744 939@c FIXME: kingdon thinks there is more to -tty. Investigate.
4eb4cf57 940_fi__(_GENERIC__ || !_H8__)
70b88761
RP
941@end table
942
4eb4cf57 943@node Leaving _GDBN__
70b88761
RP
944@section Leaving _GDBN__
945@cindex exiting _GDBN__
1041a570 946
70b88761
RP
947@table @code
948@item quit
949@kindex quit
950@kindex q
951To exit _GDBN__, use the @code{quit} command (abbreviated @code{q}), or type
e251e767 952an end-of-file character (usually @kbd{C-d}).
70b88761
RP
953@end table
954
955@cindex interrupt
956An interrupt (often @kbd{C-c}) will not exit from _GDBN__, but rather
957will terminate the action of any _GDBN__ command that is in progress and
958return to _GDBN__ command level. It is safe to type the interrupt
959character at any time because _GDBN__ does not allow it to take effect
960until a time when it is safe.
961
4eb4cf57 962_if__(!_BARE__)
1041a570
RP
963If you have been using _GDBN__ to control an attached process or device, you
964can release it with the @code{detach} command; @pxref{Attach,
965,Debugging an Already-Running Process}..
4eb4cf57 966_fi__(!_BARE__)
70b88761 967
4eb4cf57
RP
968_if__(!_BARE__)
969@node Shell Commands
70b88761 970@section Shell Commands
1041a570 971
70b88761 972If you need to execute occasional shell commands during your
29a2b744 973debugging session, there is no need to leave or suspend _GDBN__; you can
70b88761
RP
974just use the @code{shell} command.
975
976@table @code
977@item shell @var{command string}
978@kindex shell
979@cindex shell escape
980Directs _GDBN__ to invoke an inferior shell to execute @var{command
981string}. If it exists, the environment variable @code{SHELL} is used
982for the name of the shell to run. Otherwise _GDBN__ uses
983@code{/bin/sh}.
984@end table
985
986The utility @code{make} is often needed in development environments.
29a2b744 987You do not have to use the @code{shell} command for this purpose in _GDBN__:
70b88761
RP
988
989@table @code
990@item make @var{make-args}
991@kindex make
992@cindex calling make
993Causes _GDBN__ to execute an inferior @code{make} program with the specified
994arguments. This is equivalent to @samp{shell make @var{make-args}}.
995@end table
4eb4cf57 996_fi__(!_BARE__)
70b88761 997
4eb4cf57 998@node Commands
70b88761
RP
999@chapter _GDBN__ Commands
1000
6f3ec223
RP
1001You can abbreviate a _GDBN__ command to the first few letters of the command
1002name, if that abbreviation is unambiguous; and you can repeat certain
84c2fcad 1003_GDBN__ commands by typing just @key{RET}. You can also use the @key{TAB}
6f3ec223
RP
1004key to get _GDBN__ to fill out the rest of a word in a command (or to
1005show you the alternatives available, if there's more than one possibility).
29a2b744 1006
70b88761 1007@menu
b80282d5 1008* Command Syntax:: Command Syntax
6f3ec223 1009* Completion:: Command Completion
b80282d5 1010* Help:: Getting Help
70b88761
RP
1011@end menu
1012
4eb4cf57 1013@node Command Syntax
70b88761 1014@section Command Syntax
1041a570 1015
70b88761
RP
1016A _GDBN__ command is a single line of input. There is no limit on how long
1017it can be. It starts with a command name, which is followed by arguments
1018whose meaning depends on the command name. For example, the command
1019@code{step} accepts an argument which is the number of times to step,
1020as in @samp{step 5}. You can also use the @code{step} command with
1021no arguments. Some command names do not allow any arguments.
1022
1023@cindex abbreviation
1024_GDBN__ command names may always be truncated if that abbreviation is
1025unambiguous. Other possible command abbreviations are listed in the
1026documentation for individual commands. In some cases, even ambiguous
1027abbreviations are allowed; for example, @code{s} is specially defined as
1028equivalent to @code{step} even though there are other commands whose
1029names start with @code{s}. You can test abbreviations by using them as
7463aadd 1030arguments to the @code{help} command.
70b88761 1031
e251e767 1032@cindex repeating commands
70b88761
RP
1033@kindex RET
1034A blank line as input to _GDBN__ (typing just @key{RET}) means to
1035repeat the previous command. Certain commands (for example, @code{run})
1036will not repeat this way; these are commands for which unintentional
1037repetition might cause trouble and which you are unlikely to want to
1038repeat.
1039
1040The @code{list} and @code{x} commands, when you repeat them with
1041@key{RET}, construct new arguments rather than repeating
1042exactly as typed. This permits easy scanning of source or memory.
1043
b80282d5
RP
1044_GDBN__ can also use @key{RET} in another way: to partition lengthy
1045output, in a way similar to the common utility @code{more}
29a2b744 1046(@pxref{Screen Size}). Since it is easy to press one @key{RET} too many
b80282d5
RP
1047in this situation, _GDBN__ disables command repetition after any command
1048that generates this sort of display.
1049
70b88761
RP
1050@kindex #
1051@cindex comment
1052A line of input starting with @kbd{#} is a comment; it does nothing.
29a2b744 1053This is useful mainly in command files (@pxref{Command Files}).
70b88761 1054
4eb4cf57 1055@node Completion
6f3ec223
RP
1056@section Command Completion
1057
1058@cindex completion
1059@cindex word completion
1060_GDBN__ can fill in the rest of a word in a command for you, if there's
1061only one possibility; it can also show you what the valid possibilities
1062are for the next word in a command, at any time. This works for _GDBN__
1063commands, _GDBN__ subcommands, and the names of symbols in your program.
1064
1065Press the @key{TAB} key whenever you want _GDBN__ to fill out the rest
1066of a word. If there's only one possibility, _GDBN__ will fill in the
1067word, and wait for you to finish the command (or press @key{RET} to
1068enter it). For example, if you type
1069
0fdc6e27
RP
1070@c FIXME "@key" doesn't distinguish its argument sufficiently to permit
1071@c complete accuracy in these examples; space introduced for clarity.
1072@c If texinfo enhancements make it unnecessary, it would be nice to
1073@c replace " @key" by "@key" in the following...
6f3ec223 1074@example
0fdc6e27 1075(_GDBP__) info bre @key{TAB}
6f3ec223
RP
1076@end example
1077
1078@noindent
1079_GDBN__ fills in the rest of the word @samp{breakpoints}, since that's
1080the only @code{info} subcommand beginning with @samp{bre}:
1081
1082@example
1083(_GDBP__) info breakpoints
1084@end example
1085
1086@noindent
1087You can either press @key{RET} at this point, to run the @code{info
1088breakpoints} command, or backspace and enter something else, if
1089@samp{breakpoints} doesn't look like the command you expected. (If you
1090were sure you wanted @code{info breakpoints} in the first place, you
1091might as well just type @key{RET} immediately after @samp{info bre},
1092to exploit command abbreviations rather than command completion).
1093
1094If there is more than one possibility for the next word when you press
1095@key{TAB}, _GDBN__ will sound a bell. You can either supply more
1096characters and try again, or just press @key{TAB} a second time, and
1097_GDBN__ will display all the possible completions for that word. For
1098example, you might want to set a breakpoint on a subroutine whose name
b1385986 1099begins with @samp{make_}, but when you type @kbd{b make_@key{TAB}} _GDBN__
6f3ec223
RP
1100just sounds the bell. Typing @key{TAB} again will display all the
1101function names in your program that begin with those characters, for
1102example:
1103
1104@example
0fdc6e27 1105(_GDBP__) b make_ @key{TAB}
b1385986 1106@exdent _GDBN__ sounds bell; press @key{TAB} again, to see:
6f3ec223
RP
1107make_a_section_from_file make_environ
1108make_abs_section make_function_type
1109make_blockvector make_pointer_type
1110make_cleanup make_reference_type
1111make_command make_symbol_completion_list
b1385986 1112(GDBP__) b make_
6f3ec223
RP
1113@end example
1114
1115@noindent
1116After displaying the available possibilities, _GDBN__ copies your
b1385986 1117partial input (@samp{b make_} in the example) so you can finish the
6f3ec223
RP
1118command.
1119
1120If you just want to see the list of alternatives in the first place, you
b1385986 1121can press @kbd{M-?} rather than pressing @key{TAB} twice. @kbd{M-?}
0f153e74
RP
1122means @kbd{@key{META} ?}. You can type this
1123_if__(_GENERIC__||!_DOSHOST__)
1124either by holding down a
b1385986 1125key designated as the @key{META} shift on your keyboard (if there is
0f153e74
RP
1126one) while typing @kbd{?}, or
1127_fi__(_GENERIC__||!_DOSHOST__)
1128as @key{ESC} followed by @kbd{?}.
6f3ec223
RP
1129
1130@cindex quotes in commands
1131@cindex completion of quoted strings
1132Sometimes the string you need, while logically a ``word'', may contain
1133parentheses or other characters that _GDBN__ normally excludes from its
1134notion of a word. To permit word completion to work in this situation,
1135you may enclose words in @code{'} (single quote marks) in _GDBN__ commands.
1136
1137The most likely situation where you might need this is in typing the
1138name of a C++ function. This is because C++ allows function overloading
1139(multiple definitions of the same function, distinguished by argument
b1385986
RP
1140type). For example, when you want to set a breakpoint you may need to
1141distinguish whether you mean the version of @code{name} that takes an
1142@code{int} parameter, @code{name(int)}, or the version that takes a
1143@code{float} parameter, @code{name(float)}. To use the word-completion
1144facilities in this situation, type a single quote @code{'} at the
1145beginning of the function name. This alerts _GDBN__ that it may need to
1146consider more information than usual when you press @key{TAB} or
1147@kbd{M-?} to request word completion:
6f3ec223
RP
1148
1149@example
0fdc6e27
RP
1150(_GDBP__) b 'bubble( @key{M-?}
1151bubble(double,double) bubble(int,int)
1152(_GDBP__) b 'bubble(
6f3ec223
RP
1153@end example
1154
0fdc6e27
RP
1155In some cases, _GDBN__ can tell that completing a name will require
1156quotes. When this happens, _GDBN__ will insert the quote for you (while
1157completing as much as it can) if you do not type the quote in the first
1158place:
1159
1160@example
1161(_GDBP__) b bub @key{TAB}
1162@exdent _GDBN__ alters your input line to the following, and rings a bell:
1163(_GDBP__) b 'bubble(
1164@end example
1165
1166@noindent
1167In general, _GDBN__ can tell that a quote is needed (and inserts it) if
1168you have not yet started typing the argument list when you ask for
1169completion on an overloaded symbol.
1170
1171
4eb4cf57 1172@node Help
70b88761
RP
1173@section Getting Help
1174@cindex online documentation
1175@kindex help
1041a570 1176
70b88761 1177You can always ask _GDBN__ itself for information on its commands, using the
e251e767 1178command @code{help}.
70b88761
RP
1179
1180@table @code
1181@item help
1182@itemx h
1183@kindex h
1184You can use @code{help} (abbreviated @code{h}) with no arguments to
1185display a short list of named classes of commands:
1041a570 1186
70b88761
RP
1187@smallexample
1188(_GDBP__) help
1189List of classes of commands:
1190
1191running -- Running the program
1192stack -- Examining the stack
1193data -- Examining data
1194breakpoints -- Making program stop at certain points
1195files -- Specifying and examining files
1196status -- Status inquiries
1197support -- Support facilities
1198user-defined -- User-defined commands
1199aliases -- Aliases of other commands
1200obscure -- Obscure features
1201
203eea5d
RP
1202Type "help" followed by a class name for a list of
1203commands in that class.
1204Type "help" followed by command name for full
1205documentation.
70b88761 1206Command name abbreviations are allowed if unambiguous.
e251e767 1207(_GDBP__)
70b88761
RP
1208@end smallexample
1209
1210@item help @var{class}
1211Using one of the general help classes as an argument, you can get a
1212list of the individual commands in that class. For example, here is the
1213help display for the class @code{status}:
1041a570 1214
70b88761
RP
1215@smallexample
1216(_GDBP__) help status
1217Status inquiries.
1218
1219List of commands:
1220
1221show -- Generic command for showing things set with "set"
1222info -- Generic command for printing status
1223
203eea5d
RP
1224Type "help" followed by command name for full
1225documentation.
70b88761 1226Command name abbreviations are allowed if unambiguous.
e251e767 1227(_GDBP__)
70b88761
RP
1228@end smallexample
1229
1230@item help @var{command}
1231With a command name as @code{help} argument, _GDBN__ will display a
e251e767 1232short paragraph on how to use that command.
70b88761
RP
1233@end table
1234
1235In addition to @code{help}, you can use the _GDBN__ commands @code{info}
1236and @code{show} to inquire about the state of your program, or the state
1237of _GDBN__ itself. Each command supports many topics of inquiry; this
1238manual introduces each of them in the appropriate context. The listings
1239under @code{info} and under @code{show} in the Index point to
29a2b744 1240all the sub-commands. @xref{Index}.
70b88761
RP
1241
1242@c @group
1243@table @code
1244@item info
1245@kindex info
1246@kindex i
1247This command (abbreviated @code{i}) is for describing the state of your
1248program; for example, it can list the arguments given to your program
1249(@code{info args}), the registers currently in use (@code{info
1041a570 1250registers}), or the breakpoints you have set (@code{info breakpoints}).
70b88761
RP
1251You can get a complete list of the @code{info} sub-commands with
1252@w{@code{help info}}.
1253
1254@kindex show
1255@item show
1256In contrast, @code{show} is for describing the state of _GDBN__ itself.
1257You can change most of the things you can @code{show}, by using the
1258related command @code{set}; for example, you can control what number
1259system is used for displays with @code{set radix}, or simply inquire
e251e767 1260which is currently in use with @code{show radix}.
70b88761
RP
1261
1262@kindex info set
1263To display all the settable parameters and their current
1264values, you can use @code{show} with no arguments; you may also use
1265@code{info set}. Both commands produce the same display.
1266@c FIXME: "info set" violates the rule that "info" is for state of
1267@c FIXME...program. Ck w/ GNU: "info set" to be called something else,
1268@c FIXME...or change desc of rule---eg "state of prog and debugging session"?
1269@end table
1270@c @end group
1271
1272Here are three miscellaneous @code{show} subcommands, all of which are
1273exceptional in lacking corresponding @code{set} commands:
1274
1275@table @code
1276@kindex show version
3d3ab540 1277@cindex version number
70b88761
RP
1278@item show version
1279Show what version of _GDBN__ is running. You should include this
1041a570
RP
1280information in _GDBN__ bug-reports. If multiple versions of _GDBN__ are in
1281use at your site, you may occasionally want to make sure what version
1282of _GDBN__ you are running; as _GDBN__ evolves, new commands are introduced,
1283and old ones may wither away. The version number is also announced
1284when you start _GDBN__ with no arguments.
70b88761
RP
1285
1286@kindex show copying
1287@item show copying
1288Display information about permission for copying _GDBN__.
1289
1290@kindex show warranty
1291@item show warranty
1292Display the GNU ``NO WARRANTY'' statement.
1293@end table
1294
4eb4cf57 1295@node Running
70b88761
RP
1296@chapter Running Programs Under _GDBN__
1297
1041a570
RP
1298To debug a program, you must run it under _GDBN__.
1299
70b88761 1300@menu
b80282d5
RP
1301* Compilation:: Compiling for Debugging
1302* Starting:: Starting your Program
4eb4cf57 1303_if__(!_BARE__)
b80282d5
RP
1304* Arguments:: Your Program's Arguments
1305* Environment:: Your Program's Environment
1306* Working Directory:: Your Program's Working Directory
1307* Input/Output:: Your Program's Input and Output
1308* Attach:: Debugging an Already-Running Process
1309* Kill Process:: Killing the Child Process
d24e0922 1310* Process Information:: Additional Process Information
4eb4cf57 1311_fi__(!_BARE__)
70b88761
RP
1312@end menu
1313
4eb4cf57 1314@node Compilation
70b88761
RP
1315@section Compiling for Debugging
1316
1317In order to debug a program effectively, you need to generate
1318debugging information when you compile it. This debugging information
1319is stored in the object file; it describes the data type of each
1320variable or function and the correspondence between source line numbers
1321and addresses in the executable code.
1322
1323To request debugging information, specify the @samp{-g} option when you run
1324the compiler.
1325
1326Many C compilers are unable to handle the @samp{-g} and @samp{-O}
1327options together. Using those compilers, you cannot generate optimized
1328executables containing debugging information.
1329
c7cb8acb
RP
1330_GCC__, the GNU C compiler, supports @samp{-g} with or without
1331@samp{-O}, making it possible to debug optimized code. We recommend
1332that you @emph{always} use @samp{-g} whenever you compile a program.
1333You may think your program is correct, but there is no sense in pushing
1334your luck.
70b88761 1335
6ca72cc6
RP
1336@cindex optimized code, debugging
1337@cindex debugging optimized code
1338When you debug a program compiled with @samp{-g -O}, remember that the
1339optimizer is rearranging your code; the debugger will show you what's
1340really there. Don't be too surprised when the execution path doesn't
1341exactly match your source file! An extreme example: if you define a
1342variable, but never use it, _GDBN__ will never see that
1343variable---because the compiler optimizes it out of existence.
1344
70b88761
RP
1345Some things do not work as well with @samp{-g -O} as with just
1346@samp{-g}, particularly on machines with instruction scheduling. If in
1347doubt, recompile with @samp{-g} alone, and if this fixes the problem,
1348please report it as a bug (including a test case!).
1349
1350Older versions of the GNU C compiler permitted a variant option
c7cb8acb 1351@w{@samp{-gg}} for debugging information. _GDBN__ no longer supports this
70b88761
RP
1352format; if your GNU C compiler has this option, do not use it.
1353
1354@ignore
1355@comment As far as I know, there are no cases in which _GDBN__ will
1356@comment produce strange output in this case. (but no promises).
1357If your program includes archives made with the @code{ar} program, and
1358if the object files used as input to @code{ar} were compiled without the
1359@samp{-g} option and have names longer than 15 characters, _GDBN__ will get
29a2b744 1360confused reading your program's symbol table. No error message will be
70b88761
RP
1361given, but _GDBN__ may behave strangely. The reason for this problem is a
1362deficiency in the Unix archive file format, which cannot represent file
1363names longer than 15 characters.
1364
1365To avoid this problem, compile the archive members with the @samp{-g}
1366option or use shorter file names. Alternatively, use a version of GNU
1367@code{ar} dated more recently than August 1989.
1368@end ignore
1369
4eb4cf57 1370@node Starting
70b88761
RP
1371@section Starting your Program
1372@cindex starting
1373@cindex running
1041a570 1374
70b88761
RP
1375@table @code
1376@item run
1377@itemx r
1378@kindex run
1041a570
RP
1379Use the @code{run} command to start your program under _GDBN__. You must
1380first specify the program name
e251e767 1381_if__(_VXWORKS__)
7463aadd 1382(except on VxWorks)
70b88761 1383_fi__(_VXWORKS__)
1041a570
RP
1384with an argument to
1385_GDBN__ (@pxref{Invocation, ,Getting In and Out of _GDBN__}), or by using the
1386@code{file} or @code{exec-file} command (@pxref{Files, ,Commands to
1387Specify Files}).
1388
70b88761
RP
1389@end table
1390
4eb4cf57 1391_if__(!_BARE__)
29a2b744
RP
1392If you are running your program in an execution environment that
1393supports processes, @code{run} creates an inferior process and makes
1394that process run your program. (In environments without processes,
1395@code{run} jumps to the start of your program.)
70b88761
RP
1396
1397The execution of a program is affected by certain information it
1398receives from its superior. _GDBN__ provides ways to specify this
6ca72cc6 1399information, which you must do @emph{before} starting your program. (You
29a2b744
RP
1400can change it after starting your program, but such changes will only affect
1401your program the next time you start it.) This information may be
70b88761
RP
1402divided into four categories:
1403
1404@table @asis
6ca72cc6 1405@item The @emph{arguments.}
29a2b744 1406Specify the arguments to give your program as the arguments of the
1041a570
RP
1407@code{run} command. If a shell is available on your target, the shell
1408is used to pass the arguments, so that you may use normal conventions
1409(such as wildcard expansion or variable substitution) in describing
1410the arguments. In Unix systems, you can control which shell is used
1411with the @code{SHELL} environment variable. @xref{Arguments, ,Your
1412Program's Arguments}.
70b88761 1413
6ca72cc6 1414@item The @emph{environment.}
70b88761
RP
1415Your program normally inherits its environment from _GDBN__, but you can
1416use the _GDBN__ commands @code{set environment} and @code{unset
1417environment} to change parts of the environment that will be given to
1041a570 1418your program. @xref{Environment, ,Your Program's Environment}.
70b88761 1419
6ca72cc6 1420@item The @emph{working directory.}
70b88761
RP
1421Your program inherits its working directory from _GDBN__. You can set
1422_GDBN__'s working directory with the @code{cd} command in _GDBN__.
29a2b744 1423@xref{Working Directory, ,Your Program's Working Directory}.
70b88761 1424
6ca72cc6 1425@item The @emph{standard input and output.}
70b88761
RP
1426Your program normally uses the same device for standard input and
1427standard output as _GDBN__ is using. You can redirect input and output
1428in the @code{run} command line, or you can use the @code{tty} command to
1429set a different device for your program.
1041a570 1430@xref{Input/Output, ,Your Program's Input and Output}.
3d3ab540
RP
1431
1432@cindex pipes
29a2b744
RP
1433@emph{Warning:} While input and output redirection work, you cannot use
1434pipes to pass the output of the program you are debugging to another
3d3ab540
RP
1435program; if you attempt this, _GDBN__ is likely to wind up debugging the
1436wrong program.
70b88761 1437@end table
4eb4cf57 1438_fi__(!_BARE__)
70b88761 1439
1041a570 1440When you issue the @code{run} command, your program begins to execute
4eb4cf57
RP
1441immediately. @xref{Stopping, ,Stopping and Continuing}, for discussion
1442of how to arrange for your program to stop. Once your program has
1443stopped, you may calls functions in your program, using the @code{print}
1444or @code{call} commands. @xref{Data, ,Examining Data}.
70b88761 1445
29a2b744 1446If the modification time of your symbol file has changed since the
1041a570
RP
1447last time _GDBN__ read its symbols, _GDBN__ will discard its symbol table and
1448re-read it. When it does this, _GDBN__ tries to retain your current
1449breakpoints.
70b88761 1450
4eb4cf57
RP
1451_if__(!_BARE__)
1452@node Arguments
70b88761
RP
1453@section Your Program's Arguments
1454
1455@cindex arguments (to your program)
1456The arguments to your program can be specified by the arguments of the
1457@code{run} command. They are passed to a shell, which expands wildcard
29a2b744 1458characters and performs redirection of I/O, and thence to your program.
70b88761
RP
1459_GDBN__ uses the shell indicated by your environment variable
1460@code{SHELL} if it exists; otherwise, _GDBN__ uses @code{/bin/sh}.
1461
1462@code{run} with no arguments uses the same arguments used by the previous
1463@code{run}, or those set by the @code{set args} command.
1464
1465@kindex set args
1466@table @code
1467@item set args
1468Specify the arguments to be used the next time your program is run. If
1469@code{set args} has no arguments, @code{run} will execute your program
e251e767 1470with no arguments. Once you have run your program with arguments,
70b88761
RP
1471using @code{set args} before the next @code{run} is the only way to run
1472it again without arguments.
1473
1474@item show args
1475@kindex show args
1476Show the arguments to give your program when it is started.
1477@end table
1478
4eb4cf57 1479@node Environment
70b88761
RP
1480@section Your Program's Environment
1481
1482@cindex environment (of your program)
1483The @dfn{environment} consists of a set of environment variables and
1484their values. Environment variables conventionally record such things as
1485your user name, your home directory, your terminal type, and your search
1486path for programs to run. Usually you set up environment variables with
1487the shell and they are inherited by all the other programs you run. When
29a2b744 1488debugging, it can be useful to try running your program with a modified
70b88761
RP
1489environment without having to start _GDBN__ over again.
1490
1491@table @code
1492@item path @var{directory}
1493@kindex path
1494Add @var{directory} to the front of the @code{PATH} environment variable
1495(the search path for executables), for both _GDBN__ and your program.
1496You may specify several directory names, separated by @samp{:} or
1497whitespace. If @var{directory} is already in the path, it is moved to
e251e767 1498the front, so it will be searched sooner.
7463aadd
RP
1499
1500You can use the string @samp{$cwd} to refer to whatever is the current
1501working directory at the time _GDBN__ searches the path. If you use
1502@samp{.} instead, it refers to the directory where you executed the
1503@code{path} command. _GDBN__ fills in the current path where needed in
1504the @var{directory} argument, before adding it to the search path.
29a2b744 1505@c 'path' is explicitly nonrepeatable, but RMS points out it is silly to
70b88761
RP
1506@c document that, since repeating it would be a no-op.
1507
1508@item show paths
1509@kindex show paths
1510Display the list of search paths for executables (the @code{PATH}
1511environment variable).
1512
1513@item show environment @r{[}@var{varname}@r{]}
1514@kindex show environment
1515Print the value of environment variable @var{varname} to be given to
29a2b744 1516your program when it starts. If you do not supply @var{varname},
70b88761
RP
1517print the names and values of all environment variables to be given to
1518your program. You can abbreviate @code{environment} as @code{env}.
1519
7463aadd 1520@item set environment @var{varname} @r{[}=@r{]} @var{value}
70b88761
RP
1521@kindex set environment
1522Sets environment variable @var{varname} to @var{value}. The value
1523changes for your program only, not for _GDBN__ itself. @var{value} may
1524be any string; the values of environment variables are just strings, and
1525any interpretation is supplied by your program itself. The @var{value}
1526parameter is optional; if it is eliminated, the variable is set to a
1527null value.
29a2b744 1528@c "any string" here does not include leading, trailing
70b88761
RP
1529@c blanks. Gnu asks: does anyone care?
1530
1531For example, this command:
1532
1533@example
1534set env USER = foo
1535@end example
1536
1537@noindent
1538tells a Unix program, when subsequently run, that its user is named
1539@samp{foo}. (The spaces around @samp{=} are used for clarity here; they
1540are not actually required.)
1541
1542@item unset environment @var{varname}
1543@kindex unset environment
1544Remove variable @var{varname} from the environment to be passed to your
1545program. This is different from @samp{set env @var{varname} =};
1546@code{unset environment} removes the variable from the environment,
e251e767 1547rather than assigning it an empty value.
70b88761
RP
1548@end table
1549
4eb4cf57 1550@node Working Directory
70b88761
RP
1551@section Your Program's Working Directory
1552
1553@cindex working directory (of your program)
1554Each time you start your program with @code{run}, it inherits its
1555working directory from the current working directory of _GDBN__. _GDBN__'s
1556working directory is initially whatever it inherited from its parent
1557process (typically the shell), but you can specify a new working
1558directory in _GDBN__ with the @code{cd} command.
1559
1560The _GDBN__ working directory also serves as a default for the commands
1041a570
RP
1561that specify files for _GDBN__ to operate on. @xref{Files, ,Commands to
1562Specify Files}.
70b88761
RP
1563
1564@table @code
1565@item cd @var{directory}
1566@kindex cd
1567Set _GDBN__'s working directory to @var{directory}.
1568
1569@item pwd
1570@kindex pwd
1571Print _GDBN__'s working directory.
1572@end table
1573
4eb4cf57 1574@node Input/Output
70b88761
RP
1575@section Your Program's Input and Output
1576
1577@cindex redirection
1578@cindex i/o
1579@cindex terminal
1580By default, the program you run under _GDBN__ does input and output to
1581the same terminal that _GDBN__ uses. _GDBN__ switches the terminal to
1582its own terminal modes to interact with you, but it records the terminal
1583modes your program was using and switches back to them when you continue
1584running your program.
1585
1586@table @code
1587@item info terminal
1588@kindex info terminal
1589Displays _GDBN__'s recorded information about the terminal modes your
1590program is using.
1591@end table
1592
29a2b744 1593You can redirect your program's input and/or output using shell
70b88761
RP
1594redirection with the @code{run} command. For example,
1595
1596_0__@example
1597run > outfile
1598_1__@end example
1599
1600@noindent
29a2b744 1601starts your program, diverting its output to the file @file{outfile}.
70b88761
RP
1602
1603@kindex tty
1604@cindex controlling terminal
29a2b744 1605Another way to specify where your program should do input and output is
70b88761
RP
1606with the @code{tty} command. This command accepts a file name as
1607argument, and causes this file to be the default for future @code{run}
1608commands. It also resets the controlling terminal for the child
1609process, for future @code{run} commands. For example,
1610
1611@example
1612tty /dev/ttyb
1613@end example
1614
1615@noindent
1616directs that processes started with subsequent @code{run} commands
1617default to do input and output on the terminal @file{/dev/ttyb} and have
1618that as their controlling terminal.
1619
1620An explicit redirection in @code{run} overrides the @code{tty} command's
1621effect on the input/output device, but not its effect on the controlling
1622terminal.
1623
1624When you use the @code{tty} command or redirect input in the @code{run}
1625command, only the input @emph{for your program} is affected. The input
1626for _GDBN__ still comes from your terminal.
1627
4eb4cf57 1628@node Attach
70b88761
RP
1629@section Debugging an Already-Running Process
1630@kindex attach
1631@cindex attach
1632
1633@table @code
1634@item attach @var{process-id}
1635This command
1636attaches to a running process---one that was started outside _GDBN__.
1637(@code{info files} will show your active targets.) The command takes as
1638argument a process ID. The usual way to find out the process-id of
1639a Unix process is with the @code{ps} utility, or with the @samp{jobs -l}
e251e767 1640shell command.
70b88761
RP
1641
1642@code{attach} will not repeat if you press @key{RET} a second time after
1643executing the command.
1644@end table
1645
1646To use @code{attach}, you must be debugging in an environment which
1647supports processes. You must also have permission to send the process a
1648signal, and it must have the same effective user ID as the _GDBN__
1649process.
1650
1651When using @code{attach}, you should first use the @code{file} command
1652to specify the program running in the process and load its symbol table.
29a2b744 1653@xref{Files, ,Commands to Specify Files}.
70b88761
RP
1654
1655The first thing _GDBN__ does after arranging to debug the specified
1656process is to stop it. You can examine and modify an attached process
1657with all the _GDBN__ commands that are ordinarily available when you start
1658processes with @code{run}. You can insert breakpoints; you can step and
1659continue; you can modify storage. If you would rather the process
1660continue running, you may use the @code{continue} command after
1661attaching _GDBN__ to the process.
1662
1663@table @code
1664@item detach
1665@kindex detach
1666When you have finished debugging the attached process, you can use the
1667@code{detach} command to release it from _GDBN__'s control. Detaching
1668the process continues its execution. After the @code{detach} command,
1669that process and _GDBN__ become completely independent once more, and you
1670are ready to @code{attach} another process or start one with @code{run}.
1671@code{detach} will not repeat if you press @key{RET} again after
1672executing the command.
1673@end table
1674
1675If you exit _GDBN__ or use the @code{run} command while you have an attached
1676process, you kill that process. By default, you will be asked for
1677confirmation if you try to do either of these things; you can control
1678whether or not you need to confirm by using the @code{set confirm} command
29a2b744 1679(@pxref{Messages/Warnings, ,Optional Warnings and Messages}).
70b88761 1680
4eb4cf57 1681@node Kill Process
70b88761
RP
1682@c @group
1683@section Killing the Child Process
1684
1685@table @code
1686@item kill
1687@kindex kill
1688Kill the child process in which your program is running under _GDBN__.
1689@end table
1690
1691This command is useful if you wish to debug a core dump instead of a
1692running process. _GDBN__ ignores any core dump file while your program
1693is running.
1694@c @end group
1695
29a2b744 1696On some operating systems, a program cannot be executed outside _GDBN__
70b88761 1697while you have breakpoints set on it inside _GDBN__. You can use the
29a2b744 1698@code{kill} command in this situation to permit running your program
70b88761
RP
1699outside the debugger.
1700
1701The @code{kill} command is also useful if you wish to recompile and
29a2b744 1702relink your program, since on many systems it is impossible to modify an
70b88761
RP
1703executable file while it is running in a process. In this case, when you
1704next type @code{run}, _GDBN__ will notice that the file has changed, and
1705will re-read the symbol table (while trying to preserve your current
1706breakpoint settings).
1707
4eb4cf57 1708@node Process Information
d24e0922
RP
1709@section Additional Process Information
1710
1711@kindex /proc
1712@cindex process image
1713Some operating systems provide a facility called @samp{/proc} that can
cc9bc574
RP
1714be used to examine the image of a running process using file-system
1715subroutines. If _GDBN__ is configured for an operating system with this
1716facility, the command @code{info proc} is available to report on several
1717kinds of information about the process running your program.
d24e0922
RP
1718
1719@table @code
1720@item info proc
1721@kindex info proc
1722Summarize available information about the process.
1723
1724@item info proc mappings
1725@kindex info proc mappings
1726Report on the address ranges accessible in the program, with information
1727on whether your program may read, write, or execute each range.
1728
1729@item info proc times
1730@kindex info proc times
1731Starting time, user CPU time, and system CPU time for your program and
1732its children.
1733
1734@item info proc id
1735@kindex info proc id
1736Report on the process ID's related to your program: its own process id,
1737the id of its parent, the process group id, and the session id.
1738
1739@item info proc status
1740@kindex info proc status
1741General information on the state of the process. If the process is
1742stopped, this report includes the reason for stopping, and any signal
1743received.
cc9bc574
RP
1744
1745@item info proc all
1746Show all the above information about the process.
d24e0922 1747@end table
4eb4cf57 1748_fi__(!_BARE__)
d24e0922 1749
4eb4cf57 1750@node Stopping
70b88761
RP
1751@chapter Stopping and Continuing
1752
1753The principal purpose of using a debugger is so that you can stop your
29a2b744 1754program before it terminates; or so that, if your program runs into
70b88761
RP
1755trouble, you can investigate and find out why.
1756
1757Inside _GDBN__, your program may stop for any of several reasons, such
1758as a signal, a breakpoint, or reaching a new line after a _GDBN__
1759command such as @code{step}. You may then examine and change
1760variables, set new breakpoints or remove old ones, and then continue
1761execution. Usually, the messages shown by _GDBN__ provide ample
1762explanation of the status of your program---but you can also explicitly
1763request this information at any time.
1764
1765@table @code
1766@item info program
1767@kindex info program
1768Display information about the status of your program: whether it is
1769running or not, what process it is, and why it stopped.
1770@end table
1771
1772@menu
0f153e74 1773_if__(!_CONLY__)
b80282d5 1774* Breakpoints:: Breakpoints, Watchpoints, and Exceptions
0f153e74
RP
1775_fi__(!_CONLY__)
1776_if__(_CONLY__)
1777* Breakpoints:: Breakpoints and Watchpoints
1778_fi__(_CONLY__)
b80282d5 1779* Continuing and Stepping:: Resuming Execution
4eb4cf57 1780_if__(_GENERIC__ || !_H8__)
b80282d5 1781* Signals:: Signals
4eb4cf57 1782_fi__(_GENERIC__ || !_H8__)
70b88761
RP
1783@end menu
1784
4eb4cf57 1785@node Breakpoints
0f153e74 1786_if__(!_CONLY__)
70b88761 1787@section Breakpoints, Watchpoints, and Exceptions
0f153e74
RP
1788_fi__(!_CONLY__)
1789_if__(_CONLY__)
1790@section Breakpoints and Watchpoints
1791_fi__(_CONLY__)
70b88761
RP
1792
1793@cindex breakpoints
1794A @dfn{breakpoint} makes your program stop whenever a certain point in
1041a570 1795the program is reached. For each breakpoint, you can add various
29a2b744 1796conditions to control in finer detail whether your program will stop.
70b88761 1797You can set breakpoints with the @code{break} command and its variants
29a2b744
RP
1798(@pxref{Set Breaks, ,Setting Breakpoints}), to specify the place where
1799your program should stop by line number, function name or exact address
0f153e74
RP
1800in the program.
1801_if__(!_CONLY__)
1802In languages with exception handling (such as GNU C++), you can also set
1803breakpoints where an exception is raised (@pxref{Exception Handling,
1804,Breakpoints and Exceptions}).
1805_fi__(!_CONLY__)
70b88761
RP
1806
1807@cindex watchpoints
6ca72cc6
RP
1808@cindex memory tracing
1809@cindex breakpoint on memory address
1810@cindex breakpoint on variable modification
29a2b744
RP
1811A @dfn{watchpoint} is a special breakpoint that stops your program
1812when the value of an expression changes. You must use a different
1813command to set watchpoints (@pxref{Set Watchpoints, ,Setting
1814Watchpoints}), but aside from that, you can manage a watchpoint like
1815any other breakpoint: you enable, disable, and delete both breakpoints
1041a570 1816and watchpoints using the same commands.
70b88761 1817
6ca72cc6
RP
1818@cindex breakpoint numbers
1819@cindex numbers for breakpoints
1820_GDBN__ assigns a number to each breakpoint or watchpoint when you
1821create it; these numbers are successive integers starting with one. In
1822many of the commands for controlling various features of breakpoints you
1823use the breakpoint number to say which breakpoint you want to change.
1824Each breakpoint may be @dfn{enabled} or @dfn{disabled}; if disabled, it has
29a2b744 1825no effect on your program until you enable it again.
70b88761
RP
1826
1827@menu
b80282d5
RP
1828* Set Breaks:: Setting Breakpoints
1829* Set Watchpoints:: Setting Watchpoints
1830* Exception Handling:: Breakpoints and Exceptions
1831* Delete Breaks:: Deleting Breakpoints
1832* Disabling:: Disabling Breakpoints
1833* Conditions:: Break Conditions
1834* Break Commands:: Breakpoint Command Lists
1835* Breakpoint Menus:: Breakpoint Menus
e251e767 1836* Error in Breakpoints::
70b88761
RP
1837@end menu
1838
4eb4cf57 1839@node Set Breaks
70b88761
RP
1840@subsection Setting Breakpoints
1841
4906534f
RP
1842@c FIXME LMB what does GDB do if no code on line of breakpt?
1843@c consider in particular declaration with/without initialization.
1844@c
1845@c FIXME 2 is there stuff on this already? break at fun start, already init?
1846
70b88761
RP
1847@kindex break
1848@kindex b
6ca72cc6
RP
1849@kindex $bpnum
1850@cindex latest breakpoint
1851Breakpoints are set with the @code{break} command (abbreviated
1852@code{b}). The debugger convenience variable @samp{$bpnum} records the
1853number of the beakpoint you've set most recently; see @ref{Convenience
d24e0922 1854Vars,, Convenience Variables}, for a discussion of what you can do with
6ca72cc6 1855convenience variables.
70b88761
RP
1856
1857You have several ways to say where the breakpoint should go.
1858
1859@table @code
1860@item break @var{function}
0f153e74
RP
1861Set a breakpoint at entry to function @var{function}.
1862_if__(!_CONLY__)
1863When using source languages that permit overloading of symbols, such as
1864C++, @var{function} may refer to more than one possible place to break.
70b88761 1865@xref{Breakpoint Menus}, for a discussion of that situation.
0f153e74 1866_fi__(!_CONLY__)
70b88761
RP
1867
1868@item break +@var{offset}
1869@itemx break -@var{offset}
1870Set a breakpoint some number of lines forward or back from the position
1871at which execution stopped in the currently selected frame.
1872
1873@item break @var{linenum}
1874Set a breakpoint at line @var{linenum} in the current source file.
1875That file is the last file whose source text was printed. This
29a2b744 1876breakpoint will stop your program just before it executes any of the
70b88761
RP
1877code on that line.
1878
1879@item break @var{filename}:@var{linenum}
1880Set a breakpoint at line @var{linenum} in source file @var{filename}.
1881
1882@item break @var{filename}:@var{function}
1883Set a breakpoint at entry to function @var{function} found in file
1884@var{filename}. Specifying a file name as well as a function name is
1885superfluous except when multiple files contain similarly named
1886functions.
1887
1888@item break *@var{address}
1889Set a breakpoint at address @var{address}. You can use this to set
29a2b744 1890breakpoints in parts of your program which do not have debugging
70b88761
RP
1891information or source files.
1892
1893@item break
29a2b744
RP
1894When called without any arguments, @code{break} sets a breakpoint at
1895the next instruction to be executed in the selected stack frame
1896(@pxref{Stack, ,Examining the Stack}). In any selected frame but the
1897innermost, this will cause your program to stop as soon as control
1898returns to that frame. This is similar to the effect of a
1899@code{finish} command in the frame inside the selected frame---except
1900that @code{finish} does not leave an active breakpoint. If you use
1041a570
RP
1901@code{break} without an argument in the innermost frame, _GDBN__ will stop
1902the next time it reaches the current location; this may be useful
1903inside loops.
70b88761
RP
1904
1905_GDBN__ normally ignores breakpoints when it resumes execution, until at
1906least one instruction has been executed. If it did not do this, you
1907would be unable to proceed past a breakpoint without first disabling the
1908breakpoint. This rule applies whether or not the breakpoint already
29a2b744 1909existed when your program stopped.
70b88761
RP
1910
1911@item break @dots{} if @var{cond}
1912Set a breakpoint with condition @var{cond}; evaluate the expression
1913@var{cond} each time the breakpoint is reached, and stop only if the
3d3ab540 1914value is nonzero---that is, if @var{cond} evaluates as true.
1041a570
RP
1915@samp{@dots{}} stands for one of the possible arguments described
1916above (or no argument) specifying where to break. @xref{Conditions,
1917,Break Conditions}, for more information on breakpoint conditions.
70b88761
RP
1918
1919@item tbreak @var{args}
1920@kindex tbreak
1921Set a breakpoint enabled only for one stop. @var{args} are the
1922same as for the @code{break} command, and the breakpoint is set in the same
29a2b744
RP
1923way, but the breakpoint is automatically disabled after the first time your
1924program stops there. @xref{Disabling, ,Disabling Breakpoints}.
70b88761
RP
1925
1926@item rbreak @var{regex}
1927@kindex rbreak
1928@cindex regular expression
4906534f 1929@c FIXME what kind of regexp?
70b88761 1930Set breakpoints on all functions matching the regular expression
b80282d5 1931@var{regex}. This command
70b88761
RP
1932sets an unconditional breakpoint on all matches, printing a list of all
1933breakpoints it set. Once these breakpoints are set, they are treated
1934just like the breakpoints set with the @code{break} command. They can
1935be deleted, disabled, made conditional, etc., in the standard ways.
1936
0f153e74 1937_if__(!_CONLY__)
b80282d5
RP
1938When debugging C++ programs, @code{rbreak} is useful for setting
1939breakpoints on overloaded functions that are not members of any special
1940classes.
0f153e74 1941_fi__(!_CONLY__)
b80282d5 1942
70b88761 1943@kindex info breakpoints
c338a2fd 1944@cindex @code{$_} and @code{info breakpoints}
70b88761 1945@item info breakpoints @r{[}@var{n}@r{]}
6ca72cc6
RP
1946@itemx info break @r{[}@var{n}@r{]}
1947@itemx info watchpoints @r{[}@var{n}@r{]}
1948Print a table of all breakpoints and watchpoints set and not
1949deleted, with the following columns for each breakpoint:
1950
1951@table @emph
1952@item Breakpoint Numbers
1953@item Type
1954Breakpoint or watchpoint.
1955@item Disposition
1956Whether the breakpoint is marked to be disabled or deleted when hit.
1957@item Enabled or Disabled
d24e0922 1958Enabled breakpoints are marked with @samp{y}. @samp{n} marks breakpoints
6ca72cc6
RP
1959that are not enabled.
1960@item Address
1961Where the breakpoint is in your program, as a memory address
1962@item What
1963Where the breakpoint is in the source for your program, as a file and
1964line number.
1965@end table
1966
1967@noindent
1968Breakpoint commands, if any, are listed after the line for the
1969corresponding breakpoint.
1970
1971@noindent
1972@code{info break} with a breakpoint
29a2b744
RP
1973number @var{n} as argument lists only that breakpoint. The
1974convenience variable @code{$_} and the default examining-address for
1975the @code{x} command are set to the address of the last breakpoint
6ca72cc6 1976listed (@pxref{Memory, ,Examining Memory}).
1041a570 1977@end table
70b88761 1978
1041a570
RP
1979_GDBN__ allows you to set any number of breakpoints at the same place in
1980your program. There is nothing silly or meaningless about this. When
1981the breakpoints are conditional, this is even useful
29a2b744 1982(@pxref{Conditions, ,Break Conditions}).
70b88761 1983
6ca72cc6
RP
1984@cindex negative breakpoint numbers
1985@cindex internal _GDBN__ breakpoints
1986_GDBN__ itself sometimes sets breakpoints in your program for special
1987purposes, such as proper handling of @code{longjmp} (in C programs).
1988These internal breakpoints are assigned negative numbers, starting with
5a2c1d85 1989@code{-1}; @samp{info breakpoints} does not display them.
d48da190 1990
5a2c1d85
RP
1991You can see these breakpoints with the _GDBN__ maintenance command
1992@samp{maint info breakpoints}.
6ca72cc6
RP
1993
1994@table @code
d48da190
RP
1995@kindex maint info breakpoints
1996@item maint info breakpoints
6ca72cc6
RP
1997Using the same format as @samp{info breakpoints}, display both the
1998breakpoints you've set explicitly, and those _GDBN__ is using for
1999internal purposes. Internal breakpoints are shown with negative
2000breakpoint numbers. The type column identifies what kind of breakpoint
2001is shown:
2002
2003@table @code
2004@item breakpoint
2005Normal, explicitly set breakpoint.
2006
2007@item watchpoint
2008Normal, explicitly set watchpoint.
2009
2010@item longjmp
2011Internal breakpoint, used to handle correctly stepping through
2012@code{longjmp} calls.
2013
2014@item longjmp resume
2015Internal breakpoint at the target of a @code{longjmp}.
2016
2017@item until
2018Temporary internal breakpoint used by the _GDBN__ @code{until} command.
2019
2020@item finish
2021Temporary internal breakpoint used by the _GDBN__ @code{finish} command.
2022@end table
2023
2024@end table
2025
2026
4eb4cf57 2027@node Set Watchpoints
70b88761
RP
2028@subsection Setting Watchpoints
2029@cindex setting watchpoints
1041a570 2030
70b88761 2031You can use a watchpoint to stop execution whenever the value of an
e251e767 2032expression changes, without having to predict a particular place
70b88761
RP
2033where this may happen.
2034
2035Watchpoints currently execute two orders of magnitude more slowly than
2036other breakpoints, but this can well be worth it to catch errors where
2037you have no clue what part of your program is the culprit. Some
2038processors provide special hardware to support watchpoint evaluation; future
2039releases of _GDBN__ will use such hardware if it is available.
2040
2041@table @code
e251e767 2042@kindex watch
70b88761
RP
2043@item watch @var{expr}
2044Set a watchpoint for an expression.
2045
2046@kindex info watchpoints
2047@item info watchpoints
6ca72cc6
RP
2048This command prints a list of watchpoints and breakpoints; it is the
2049same as @code{info break}.
70b88761
RP
2050@end table
2051
4eb4cf57 2052@node Exception Handling
70b88761
RP
2053@subsection Breakpoints and Exceptions
2054@cindex exception handlers
2055
b80282d5 2056Some languages, such as GNU C++, implement exception handling. You can
29a2b744
RP
2057use _GDBN__ to examine what caused your program to raise an exception,
2058and to list the exceptions your program is prepared to handle at a
70b88761
RP
2059given point in time.
2060
2061@table @code
2062@item catch @var{exceptions}
2063@kindex catch
2064You can set breakpoints at active exception handlers by using the
2065@code{catch} command. @var{exceptions} is a list of names of exceptions
2066to catch.
2067@end table
2068
29a2b744
RP
2069You can use @code{info catch} to list active exception handlers.
2070@xref{Frame Info, ,Information About a Frame}.
70b88761
RP
2071
2072There are currently some limitations to exception handling in _GDBN__.
2073These will be corrected in a future release.
2074
2075@itemize @bullet
2076@item
2077If you call a function interactively, _GDBN__ normally returns
2078control to you when the function has finished executing. If the call
2079raises an exception, however, the call may bypass the mechanism that
29a2b744 2080returns control to you and cause your program to simply continue
70b88761
RP
2081running until it hits a breakpoint, catches a signal that _GDBN__ is
2082listening for, or exits.
2083@item
2084You cannot raise an exception interactively.
2085@item
2086You cannot interactively install an exception handler.
2087@end itemize
2088
2089@cindex raise exceptions
2090Sometimes @code{catch} is not the best way to debug exception handling:
29a2b744 2091if you need to know exactly where an exception is raised, it is better to
70b88761
RP
2092stop @emph{before} the exception handler is called, since that way you
2093can see the stack before any unwinding takes place. If you set a
2094breakpoint in an exception handler instead, it may not be easy to find
2095out where the exception was raised.
2096
2097To stop just before an exception handler is called, you need some
b80282d5 2098knowledge of the implementation. In the case of GNU C++, exceptions are
70b88761
RP
2099raised by calling a library function named @code{__raise_exception}
2100which has the following ANSI C interface:
2101
2102@example
b80282d5 2103 /* @var{addr} is where the exception identifier is stored.
70b88761
RP
2104 ID is the exception identifier. */
2105 void __raise_exception (void **@var{addr}, void *@var{id});
2106@end example
2107
2108@noindent
2109To make the debugger catch all exceptions before any stack
2110unwinding takes place, set a breakpoint on @code{__raise_exception}
29a2b744 2111(@pxref{Breakpoints, ,Breakpoints Watchpoints and Exceptions}).
70b88761 2112
29a2b744
RP
2113With a conditional breakpoint (@pxref{Conditions, ,Break Conditions})
2114that depends on the value of @var{id}, you can stop your program when
2115a specific exception is raised. You can use multiple conditional
2116breakpoints to stop your program when any of a number of exceptions are
2117raised.
70b88761 2118
4eb4cf57 2119@node Delete Breaks
70b88761
RP
2120@subsection Deleting Breakpoints
2121
2122@cindex clearing breakpoints, watchpoints
2123@cindex deleting breakpoints, watchpoints
2124It is often necessary to eliminate a breakpoint or watchpoint once it
29a2b744 2125has done its job and you no longer want your program to stop there. This
70b88761
RP
2126is called @dfn{deleting} the breakpoint. A breakpoint that has been
2127deleted no longer exists; it is forgotten.
2128
2129With the @code{clear} command you can delete breakpoints according to
29a2b744 2130where they are in your program. With the @code{delete} command you can
70b88761
RP
2131delete individual breakpoints or watchpoints by specifying their
2132breakpoint numbers.
2133
2134It is not necessary to delete a breakpoint to proceed past it. _GDBN__
2135automatically ignores breakpoints on the first instruction to be executed
2136when you continue execution without changing the execution address.
2137
2138@table @code
2139@item clear
2140@kindex clear
2141Delete any breakpoints at the next instruction to be executed in the
29a2b744
RP
2142selected stack frame (@pxref{Selection, ,Selecting a Frame}). When
2143the innermost frame is selected, this is a good way to delete a
2144breakpoint where your program just stopped.
70b88761
RP
2145
2146@item clear @var{function}
2147@itemx clear @var{filename}:@var{function}
2148Delete any breakpoints set at entry to the function @var{function}.
2149
2150@item clear @var{linenum}
2151@itemx clear @var{filename}:@var{linenum}
2152Delete any breakpoints set at or within the code of the specified line.
2153
2154@item delete @r{[}breakpoints@r{]} @r{[}@var{bnums}@dots{}@r{]}
2155@cindex delete breakpoints
2156@kindex delete
2157@kindex d
2158Delete the breakpoints or watchpoints of the numbers specified as
2159arguments. If no argument is specified, delete all breakpoints (_GDBN__
1041a570 2160asks confirmation, unless you have @code{set confirm off}). You
70b88761
RP
2161can abbreviate this command as @code{d}.
2162@end table
2163
4eb4cf57 2164@node Disabling
70b88761
RP
2165@subsection Disabling Breakpoints
2166
2167@cindex disabled breakpoints
2168@cindex enabled breakpoints
2169Rather than deleting a breakpoint or watchpoint, you might prefer to
2170@dfn{disable} it. This makes the breakpoint inoperative as if it had
2171been deleted, but remembers the information on the breakpoint so that
2172you can @dfn{enable} it again later.
2173
2174You disable and enable breakpoints and watchpoints with the
2175@code{enable} and @code{disable} commands, optionally specifying one or
2176more breakpoint numbers as arguments. Use @code{info break} or
2177@code{info watch} to print a list of breakpoints or watchpoints if you
29a2b744 2178do not know which numbers to use.
70b88761
RP
2179
2180A breakpoint or watchpoint can have any of four different states of
2181enablement:
2182
2183@itemize @bullet
2184@item
29a2b744 2185Enabled. The breakpoint will stop your program. A breakpoint set
70b88761
RP
2186with the @code{break} command starts out in this state.
2187@item
29a2b744 2188Disabled. The breakpoint has no effect on your program.
70b88761 2189@item
29a2b744 2190Enabled once. The breakpoint will stop your program, but
70b88761
RP
2191when it does so it will become disabled. A breakpoint set
2192with the @code{tbreak} command starts out in this state.
2193@item
29a2b744 2194Enabled for deletion. The breakpoint will stop your program, but
70b88761
RP
2195immediately after it does so it will be deleted permanently.
2196@end itemize
2197
2198You can use the following commands to enable or disable breakpoints and
2199watchpoints:
2200
2201@table @code
2202@item disable @r{[}breakpoints@r{]} @r{[}@var{bnums}@dots{}@r{]}
2203@kindex disable breakpoints
2204@kindex disable
2205@kindex dis
2206Disable the specified breakpoints---or all breakpoints, if none are
2207listed. A disabled breakpoint has no effect but is not forgotten. All
2208options such as ignore-counts, conditions and commands are remembered in
2209case the breakpoint is enabled again later. You may abbreviate
2210@code{disable} as @code{dis}.
2211
2212@item enable @r{[}breakpoints@r{]} @r{[}@var{bnums}@dots{}@r{]}
2213@kindex enable breakpoints
2214@kindex enable
2215Enable the specified breakpoints (or all defined breakpoints). They
29a2b744 2216become effective once again in stopping your program.
70b88761
RP
2217
2218@item enable @r{[}breakpoints@r{]} once @var{bnums}@dots{}
2219Enable the specified breakpoints temporarily. Each will be disabled
29a2b744 2220again the next time it stops your program.
70b88761
RP
2221
2222@item enable @r{[}breakpoints@r{]} delete @var{bnums}@dots{}
2223Enable the specified breakpoints to work once and then die. Each of
29a2b744 2224the breakpoints will be deleted the next time it stops your program.
70b88761
RP
2225@end table
2226
29a2b744
RP
2227Save for a breakpoint set with @code{tbreak} (@pxref{Set Breaks,
2228,Setting Breakpoints}), breakpoints that you set are initially
2229enabled; subsequently, they become disabled or enabled only when you
2230use one of the commands above. (The command @code{until} can set and
2231delete a breakpoint of its own, but it will not change the state of
98fe4566 2232your other breakpoints; see @ref{Continuing and Stepping, ,Continuing and Stepping}.)
70b88761 2233
4eb4cf57 2234@node Conditions
70b88761
RP
2235@subsection Break Conditions
2236@cindex conditional breakpoints
2237@cindex breakpoint conditions
2238
4906534f
RP
2239@c FIXME what is scope of break condition expr? Context where wanted?
2240@c in particular for a watchpoint?
29a2b744 2241The simplest sort of breakpoint breaks every time your program reaches a
70b88761
RP
2242specified place. You can also specify a @dfn{condition} for a
2243breakpoint. A condition is just a Boolean expression in your
1041a570
RP
2244programming language (@pxref{Expressions, ,Expressions}). A breakpoint with
2245a condition evaluates the expression each time your program reaches it,
2246and your program stops only if the condition is @emph{true}.
3d3ab540
RP
2247
2248This is the converse of using assertions for program validation; in that
2249situation, you want to stop when the assertion is violated---that is,
2250when the condition is false. In C, if you want to test an assertion expressed
e251e767 2251by the condition @var{assert}, you should set the condition
3d3ab540 2252@samp{! @var{assert}} on the appropriate breakpoint.
70b88761
RP
2253
2254Conditions are also accepted for watchpoints; you may not need them,
2255since a watchpoint is inspecting the value of an expression anyhow---but
2256it might be simpler, say, to just set a watchpoint on a variable name,
2257and specify a condition that tests whether the new value is an interesting
e251e767 2258one.
70b88761 2259
29a2b744 2260Break conditions can have side effects, and may even call functions in
70b88761 2261your program. This can be useful, for example, to activate functions
29a2b744
RP
2262that log program progress, or to use your own print functions to
2263format special data structures. The effects are completely predictable
2264unless there is another enabled breakpoint at the same address. (In
2265that case, _GDBN__ might see the other breakpoint first and stop your
2266program without checking the condition of this one.) Note that
2267breakpoint commands are usually more convenient and flexible for the
2268purpose of performing side effects when a breakpoint is reached
2269(@pxref{Break Commands, ,Breakpoint Command Lists}).
70b88761
RP
2270
2271Break conditions can be specified when a breakpoint is set, by using
29a2b744
RP
2272@samp{if} in the arguments to the @code{break} command. @xref{Set
2273Breaks, ,Setting Breakpoints}. They can also be changed at any time
2274with the @code{condition} command. The @code{watch} command does not
2275recognize the @code{if} keyword; @code{condition} is the only way to
2276impose a further condition on a watchpoint.
70b88761 2277
e251e767
RP
2278@table @code
2279@item condition @var{bnum} @var{expression}
2280@kindex condition
70b88761
RP
2281Specify @var{expression} as the break condition for breakpoint or
2282watchpoint number @var{bnum}. From now on, this breakpoint will stop
29a2b744 2283your program only if the value of @var{expression} is true (nonzero, in
70b88761
RP
2284C). When you use @code{condition}, _GDBN__ checks @var{expression}
2285immediately for syntactic correctness, and to determine whether symbols
1041a570 2286in it have referents in the context of your breakpoint.
29a2b744 2287@c FIXME so what does GDB do if there is no referent? Moreover, what
4906534f
RP
2288@c about watchpoints?
2289_GDBN__ does
70b88761 2290not actually evaluate @var{expression} at the time the @code{condition}
1041a570 2291command is given, however. @xref{Expressions, ,Expressions}.
70b88761
RP
2292
2293@item condition @var{bnum}
2294Remove the condition from breakpoint number @var{bnum}. It becomes
2295an ordinary unconditional breakpoint.
2296@end table
2297
2298@cindex ignore count (of breakpoint)
2299A special case of a breakpoint condition is to stop only when the
2300breakpoint has been reached a certain number of times. This is so
2301useful that there is a special way to do it, using the @dfn{ignore
2302count} of the breakpoint. Every breakpoint has an ignore count, which
2303is an integer. Most of the time, the ignore count is zero, and
29a2b744 2304therefore has no effect. But if your program reaches a breakpoint whose
70b88761
RP
2305ignore count is positive, then instead of stopping, it just decrements
2306the ignore count by one and continues. As a result, if the ignore count
2307value is @var{n}, the breakpoint will not stop the next @var{n} times it
2308is reached.
2309
2310@table @code
2311@item ignore @var{bnum} @var{count}
2312@kindex ignore
2313Set the ignore count of breakpoint number @var{bnum} to @var{count}.
2314The next @var{count} times the breakpoint is reached, your program's
2315execution will not stop; other than to decrement the ignore count, _GDBN__
2316takes no action.
2317
2318To make the breakpoint stop the next time it is reached, specify
2319a count of zero.
2320
2321@item continue @var{count}
2322@itemx c @var{count}
2323@itemx fg @var{count}
2324@kindex continue @var{count}
29a2b744
RP
2325Continue execution of your program, setting the ignore count of the
2326breakpoint where your program stopped to @var{count} minus one.
2327Thus, your program will not stop at this breakpoint until the
70b88761
RP
2328@var{count}'th time it is reached.
2329
29a2b744 2330An argument to this command is meaningful only when your program stopped
70b88761
RP
2331due to a breakpoint. At other times, the argument to @code{continue} is
2332ignored.
2333
2334The synonym @code{fg} is provided purely for convenience, and has
2335exactly the same behavior as other forms of the command.
2336@end table
2337
2338If a breakpoint has a positive ignore count and a condition, the condition
2339is not checked. Once the ignore count reaches zero, the condition will
2340be checked.
2341
29a2b744 2342You could achieve the effect of the ignore count with a condition such
1041a570
RP
2343as _0__@w{@samp{$foo-- <= 0}}_1__ using a debugger convenience variable that
2344is decremented each time. @xref{Convenience Vars, ,Convenience
2345Variables}.
70b88761 2346
4eb4cf57 2347@node Break Commands
70b88761
RP
2348@subsection Breakpoint Command Lists
2349
2350@cindex breakpoint commands
2351You can give any breakpoint (or watchpoint) a series of commands to
29a2b744 2352execute when your program stops due to that breakpoint. For example, you
70b88761
RP
2353might want to print the values of certain expressions, or enable other
2354breakpoints.
2355
2356@table @code
2357@item commands @r{[}@var{bnum}@r{]}
2358@itemx @dots{} @var{command-list} @dots{}
2359@itemx end
2360@kindex commands
2361@kindex end
2362Specify a list of commands for breakpoint number @var{bnum}. The commands
2363themselves appear on the following lines. Type a line containing just
2364@code{end} to terminate the commands.
2365
203eea5d
RP
2366To remove all commands from a breakpoint, type @code{commands} and
2367follow it immediately with @code{end}; that is, give no commands.
70b88761
RP
2368
2369With no @var{bnum} argument, @code{commands} refers to the last
2370breakpoint or watchpoint set (not to the breakpoint most recently
2371encountered).
2372@end table
2373
2374Pressing @key{RET} as a means of repeating the last _GDBN__ command is
2375disabled within a @var{command-list}.
2376
29a2b744 2377You can use breakpoint commands to start your program up again. Simply
70b88761
RP
2378use the @code{continue} command, or @code{step}, or any other command
2379that resumes execution. Subsequent commands in the command list are
2380ignored.
2381
2382@kindex silent
2383If the first command specified is @code{silent}, the usual message about
2384stopping at a breakpoint is not printed. This may be desirable for
2385breakpoints that are to print a specific message and then continue.
2386If the remaining commands too print nothing, you will see no sign that
e251e767 2387the breakpoint was reached at all. @code{silent} is meaningful only
70b88761
RP
2388at the beginning of a breakpoint command list.
2389
29a2b744
RP
2390The commands @code{echo} and @code{output} that allow you to print
2391precisely controlled output are often useful in silent breakpoints.
2392@xref{Output, ,Commands for Controlled Output}.
70b88761
RP
2393
2394For example, here is how you could use breakpoint commands to print the
2395value of @code{x} at entry to @code{foo} whenever @code{x} is positive.
2396
2397_0__@example
2398break foo if x>0
2399commands
2400silent
2401echo x is\040
2402output x
2403echo \n
2404cont
2405end
2406_1__@end example
2407
2408One application for breakpoint commands is to compensate for one bug so
2409you can test for another. Put a breakpoint just after the erroneous line
2410of code, give it a condition to detect the case in which something
2411erroneous has been done, and give it commands to assign correct values
2412to any variables that need them. End with the @code{continue} command
29a2b744 2413so that your program does not stop, and start with the @code{silent}
70b88761
RP
2414command so that no output is produced. Here is an example:
2415
2416@example
2417break 403
2418commands
2419silent
2420set x = y + 4
2421cont
2422end
2423@end example
2424
2425@cindex lost output
2426One deficiency in the operation of automatically continuing breakpoints
2427under Unix appears when your program uses raw mode for the terminal.
2428_GDBN__ switches back to its own terminal modes (not raw) before executing
2429commands, and then must switch back to raw mode when your program is
e251e767 2430continued. This causes any pending terminal input to be lost.
70b88761
RP
2431@c FIXME: revisit below when GNU sys avail.
2432@c In the GNU system, this will be fixed by changing the behavior of
2433@c terminal modes.
2434
2435Under Unix, you can get around this problem by writing actions into
2436the breakpoint condition rather than in commands. For example
2437
2438@example
2439condition 5 (x = y + 4), 0
2440@end example
2441
2442@noindent
1041a570
RP
2443specifies a condition expression (@pxref{Expressions, ,Expressions}) that will
2444change @code{x} as needed, then always have the value zero so your
2445program will not stop. No input is lost here, because _GDBN__ evaluates
2446break conditions without changing the terminal modes. When you want
2447to have nontrivial conditions for performing the side effects, the
2448operators @samp{&&}, @samp{||} and @samp{?@dots{}:} may be useful.
70b88761 2449
4eb4cf57 2450@node Breakpoint Menus
70b88761 2451@subsection Breakpoint Menus
b80282d5 2452@cindex overloading
e251e767 2453@cindex symbol overloading
70b88761
RP
2454
2455Some programming languages (notably C++) permit a single function name
2456to be defined several times, for application in different contexts.
2457This is called @dfn{overloading}. When a function name is overloaded,
6f3ec223
RP
2458@samp{break @var{function}} is not enough to tell _GDBN__ where you want
2459a breakpoint. If you realize this will be a problem, you can use
2460something like @samp{break @var{function}(@var{types})} to specify which
2461particular version of the function you want. Otherwise, _GDBN__ offers
2462you a menu of numbered choices for different possible breakpoints, and
2463waits for your selection with the prompt @samp{>}. The first two
2464options are always @samp{[0] cancel} and @samp{[1] all}. Typing @kbd{1}
2465sets a breakpoint at each definition of @var{function}, and typing
2466@kbd{0} aborts the @code{break} command without setting any new
2467breakpoints.
70b88761
RP
2468
2469For example, the following session excerpt shows an attempt to set a
e251e767 2470breakpoint at the overloaded symbol @code{String::after}.
70b88761
RP
2471We choose three particular definitions of that function name:
2472
6f3ec223 2473@c FIXME! This is likely to change to show arg type lists, at least
70b88761
RP
2474@example
2475(_GDBP__) b String::after
2476[0] cancel
2477[1] all
2478[2] file:String.cc; line number:867
2479[3] file:String.cc; line number:860
2480[4] file:String.cc; line number:875
2481[5] file:String.cc; line number:853
2482[6] file:String.cc; line number:846
2483[7] file:String.cc; line number:735
2484> 2 4 6
2485Breakpoint 1 at 0xb26c: file String.cc, line 867.
2486Breakpoint 2 at 0xb344: file String.cc, line 875.
2487Breakpoint 3 at 0xafcc: file String.cc, line 846.
2488Multiple breakpoints were set.
2489Use the "delete" command to delete unwanted breakpoints.
e251e767 2490(_GDBP__)
70b88761
RP
2491@end example
2492
4eb4cf57 2493@node Error in Breakpoints
70b88761
RP
2494@subsection ``Cannot Insert Breakpoints''
2495
e251e767 2496@c FIXME: "cannot insert breakpoints" error, v unclear.
70b88761 2497@c Q in pending mail to Gilmore. ---pesch@cygnus.com, 26mar91
e251e767 2498@c some light may be shed by looking at instances of
d24e0922 2499@c ONE_PROCESS_WRITETEXT. But error message seems possible otherwise
c338a2fd 2500@c too. pesch, 20sep91
70b88761
RP
2501Under some operating systems, breakpoints cannot be used in a program if
2502any other process is running that program. In this situation,
2503attempting to run or continue a program with a breakpoint causes _GDBN__
2504to stop the other process.
2505
2506When this happens, you have three ways to proceed:
2507
2508@enumerate
2509@item
2510Remove or disable the breakpoints, then continue.
2511
2512@item
29a2b744 2513Suspend _GDBN__, and copy the file containing your program to a new name.
70b88761 2514Resume _GDBN__ and use the @code{exec-file} command to specify that _GDBN__
29a2b744 2515should run your program under that name. Then start your program again.
70b88761
RP
2516
2517@c FIXME: RMS commented here "Show example". Maybe when someone
2518@c explains the first FIXME: in this section...
2519
2520@item
29a2b744 2521Relink your program so that the text segment is nonsharable, using the
70b88761
RP
2522linker option @samp{-N}. The operating system limitation may not apply
2523to nonsharable executables.
2524@end enumerate
2525
4eb4cf57 2526@node Continuing and Stepping
3d3ab540 2527@section Continuing and Stepping
70b88761
RP
2528
2529@cindex stepping
7463aadd
RP
2530@cindex continuing
2531@cindex resuming execution
3d3ab540 2532@dfn{Continuing} means resuming program execution until your program
cedaf8bc
RP
2533completes normally. In contrast, @dfn{stepping} means executing just
2534one more ``step'' of your program, where ``step'' may mean either one
2535line of source code, or one machine instruction (depending on what
2536particular command you use). Either when continuing
4eb4cf57
RP
2537or when stepping, your program may stop even sooner, due to
2538_if__(_BARE__)
2539a breakpoint.
2540_fi__(_BARE__)
2541_if__(!_BARE__)
2542a breakpoint or to a signal. (If due to a signal, you may want to use
2543@code{handle}, or use @samp{signal 0} to resume execution.
2544@xref{Signals, ,Signals}.)
2545_fi__(!_BARE__)
3d3ab540
RP
2546
2547@table @code
2548@item continue @r{[}@var{ignore-count}@r{]}
2549@kindex continue
29a2b744 2550Resume program execution, at the address where your program last stopped;
3d3ab540
RP
2551any breakpoints set at that address are bypassed. The optional argument
2552@var{ignore-count} allows you to specify a further number of times to
2553ignore a breakpoint at this location; its effect is like that of
29a2b744 2554@code{ignore} (@pxref{Conditions, ,Break Conditions}).
3d3ab540
RP
2555
2556To resume execution at a different place, you can use @code{return}
29a2b744
RP
2557(@pxref{Returning, ,Returning from a Function}) to go back to the
2558calling function; or @code{jump} (@pxref{Jumping, ,Continuing at a
1041a570 2559Different Address}) to go to an arbitrary location in your program.
3d3ab540 2560@end table
7463aadd
RP
2561
2562A typical technique for using stepping is to set a breakpoint
29a2b744
RP
2563(@pxref{Breakpoints, ,Breakpoints Watchpoints and Exceptions}) at the
2564beginning of the function or the section of your program where a
2565problem is believed to lie, run your program until it stops at that
2566breakpoint, and then step through the suspect area, examining the
2567variables that are interesting, until you see the problem happen.
70b88761
RP
2568
2569@table @code
2570@item step
2571@kindex step
2572@kindex s
29a2b744 2573Continue running your program until control reaches a different source
7463aadd 2574line, then stop it and return control to _GDBN__. This command is
70b88761
RP
2575abbreviated @code{s}.
2576
3d3ab540
RP
2577@quotation
2578@emph{Warning:} If you use the @code{step} command while control is
2579within a function that was compiled without debugging information,
2580execution will proceed until control reaches another function.
2581@end quotation
70b88761
RP
2582
2583@item step @var{count}
2584Continue running as in @code{step}, but do so @var{count} times. If a
2585breakpoint is reached or a signal not related to stepping occurs before
2586@var{count} steps, stepping stops right away.
2587
7463aadd 2588@item next @r{[}@var{count}@r{]}
70b88761
RP
2589@kindex next
2590@kindex n
7463aadd
RP
2591Continue to the next source line in the current (innermost) stack frame.
2592Similar to @code{step}, but any function calls appearing within the line
2593of code are executed without stopping. Execution stops when control
2594reaches a different line of code at the stack level which was executing
2595when the @code{next} command was given. This command is abbreviated
2596@code{n}.
70b88761 2597
7463aadd 2598An argument @var{count} is a repeat count, as for @code{step}.
70b88761
RP
2599
2600@code{next} within a function that lacks debugging information acts like
2601@code{step}, but any function calls appearing within the code of the
2602function are executed without stopping.
2603
2604@item finish
2605@kindex finish
7463aadd
RP
2606Continue running until just after function in the selected stack frame
2607returns. Print the returned value (if any).
70b88761 2608
29a2b744 2609Contrast this with the @code{return} command (@pxref{Returning,
1041a570 2610,Returning from a Function}).
70b88761
RP
2611
2612@item until
2613@kindex until
2614@item u
2615@kindex u
2616Continue running until a source line past the current line, in the
2617current stack frame, is reached. This command is used to avoid single
2618stepping through a loop more than once. It is like the @code{next}
2619command, except that when @code{until} encounters a jump, it
2620automatically continues execution until the program counter is greater
2621than the address of the jump.
2622
2623This means that when you reach the end of a loop after single stepping
29a2b744 2624though it, @code{until} will cause your program to continue execution
70b88761
RP
2625until the loop is exited. In contrast, a @code{next} command at the end
2626of a loop will simply step back to the beginning of the loop, which
2627would force you to step through the next iteration.
2628
29a2b744 2629@code{until} always stops your program if it attempts to exit the current
70b88761
RP
2630stack frame.
2631
2632@code{until} may produce somewhat counterintuitive results if the order
7463aadd 2633of machine code does not match the order of the source lines. For
70b88761
RP
2634example, in the following excerpt from a debugging session, the @code{f}
2635(@code{frame}) command shows that execution is stopped at line
2636@code{206}; yet when we use @code{until}, we get to line @code{195}:
2637
2638@example
2639(_GDBP__) f
2640#0 main (argc=4, argv=0xf7fffae8) at m4.c:206
b80282d5 2641206 expand_input();
70b88761 2642(_GDBP__) until
b80282d5 2643195 for ( ; argc > 0; NEXTARG) @{
70b88761
RP
2644@end example
2645
7463aadd
RP
2646This happened because, for execution efficiency, the compiler had
2647generated code for the loop closure test at the end, rather than the
2648start, of the loop---even though the test in a C @code{for}-loop is
2649written before the body of the loop. The @code{until} command appeared
2650to step back to the beginning of the loop when it advanced to this
2651expression; however, it has not really gone to an earlier
2652statement---not in terms of the actual machine code.
70b88761
RP
2653
2654@code{until} with no argument works by means of single
2655instruction stepping, and hence is slower than @code{until} with an
2656argument.
2657
2658@item until @var{location}
2659@item u @var{location}
29a2b744
RP
2660Continue running your program until either the specified location is
2661reached, or the current stack frame returns. @var{location} is any of
2662the forms of argument acceptable to @code{break} (@pxref{Set Breaks,
2663,Setting Breakpoints}). This form of the command uses breakpoints,
1041a570 2664and hence is quicker than @code{until} without an argument.
70b88761
RP
2665
2666@item stepi
2667@itemx si
2668@kindex stepi
2669@kindex si
2670Execute one machine instruction, then stop and return to the debugger.
2671
2672It is often useful to do @samp{display/i $pc} when stepping by machine
2673instructions. This will cause the next instruction to be executed to
29a2b744
RP
2674be displayed automatically at each stop. @xref{Auto Display,
2675,Automatic Display}.
70b88761
RP
2676
2677An argument is a repeat count, as in @code{step}.
2678
2679@item nexti
2680@itemx ni
2681@kindex nexti
2682@kindex ni
2683Execute one machine instruction, but if it is a function call,
2684proceed until the function returns.
2685
2686An argument is a repeat count, as in @code{next}.
70b88761
RP
2687@end table
2688
4eb4cf57
RP
2689_if__(_GENERIC__ || !_H8__)
2690@node Signals
70b88761
RP
2691@section Signals
2692@cindex signals
2693
2694A signal is an asynchronous event that can happen in a program. The
2695operating system defines the possible kinds of signals, and gives each
2696kind a name and a number. For example, in Unix @code{SIGINT} is the
2697signal a program gets when you type an interrupt (often @kbd{C-c});
2698@code{SIGSEGV} is the signal a program gets from referencing a place in
2699memory far away from all the areas in use; @code{SIGALRM} occurs when
29a2b744 2700the alarm clock timer goes off (which happens only if your program has
70b88761
RP
2701requested an alarm).
2702
2703@cindex fatal signals
2704Some signals, including @code{SIGALRM}, are a normal part of the
29a2b744
RP
2705functioning of your program. Others, such as @code{SIGSEGV}, indicate
2706errors; these signals are @dfn{fatal} (kill your program immediately) if the
70b88761 2707program has not specified in advance some other way to handle the signal.
29a2b744 2708@code{SIGINT} does not indicate an error in your program, but it is normally
70b88761
RP
2709fatal so it can carry out the purpose of the interrupt: to kill the program.
2710
29a2b744
RP
2711_GDBN__ has the ability to detect any occurrence of a signal in your
2712program. You can tell _GDBN__ in advance what to do for each kind of
2713signal.
70b88761
RP
2714
2715@cindex handling signals
2716Normally, _GDBN__ is set up to ignore non-erroneous signals like @code{SIGALRM}
29a2b744
RP
2717(so as not to interfere with their role in the functioning of your program)
2718but to stop your program immediately whenever an error signal happens.
70b88761
RP
2719You can change these settings with the @code{handle} command.
2720
2721@table @code
2722@item info signals
2723@kindex info signals
2724Print a table of all the kinds of signals and how _GDBN__ has been told to
2725handle each one. You can use this to see the signal numbers of all
2726the defined types of signals.
2727
2728@item handle @var{signal} @var{keywords}@dots{}
2729@kindex handle
2730Change the way _GDBN__ handles signal @var{signal}. @var{signal} can be the
2731number of a signal or its name (with or without the @samp{SIG} at the
2732beginning). The @var{keywords} say what change to make.
2733@end table
2734
2735@c @group
2736The keywords allowed by the @code{handle} command can be abbreviated.
2737Their full names are:
2738
2739@table @code
2740@item nostop
29a2b744 2741_GDBN__ should not stop your program when this signal happens. It may
70b88761
RP
2742still print a message telling you that the signal has come in.
2743
2744@item stop
29a2b744 2745_GDBN__ should stop your program when this signal happens. This implies
70b88761
RP
2746the @code{print} keyword as well.
2747
2748@item print
2749_GDBN__ should print a message when this signal happens.
2750
2751@item noprint
2752_GDBN__ should not mention the occurrence of the signal at all. This
2753implies the @code{nostop} keyword as well.
2754
2755@item pass
29a2b744 2756_GDBN__ should allow your program to see this signal; your program will be
70b88761
RP
2757able to handle the signal, or may be terminated if the signal is fatal
2758and not handled.
2759
2760@item nopass
29a2b744 2761_GDBN__ should not allow your program to see this signal.
70b88761
RP
2762@end table
2763@c @end group
2764
29a2b744 2765When a signal has been set to stop your program, your program cannot see the
70b88761 2766signal until you continue. It will see the signal then, if @code{pass} is
6ca72cc6 2767in effect for the signal in question @emph{at that time}. In other words,
70b88761
RP
2768after _GDBN__ reports a signal, you can use the @code{handle} command with
2769@code{pass} or @code{nopass} to control whether that signal will be seen by
29a2b744 2770your program when you later continue it.
70b88761 2771
29a2b744 2772You can also use the @code{signal} command to prevent your program from
70b88761 2773seeing a signal, or cause it to see a signal it normally would not see,
29a2b744 2774or to give it any signal at any time. For example, if your program stopped
7463aadd
RP
2775due to some sort of memory reference error, you might store correct
2776values into the erroneous variables and continue, hoping to see more
29a2b744
RP
2777execution; but your program would probably terminate immediately as
2778a result of the fatal signal once it saw the signal. To prevent this,
2779you can continue with @samp{signal 0}. @xref{Signaling, ,Giving your
2780Program a Signal}.
4eb4cf57 2781_fi__(_GENERIC__ || !_H8__)
70b88761 2782
4eb4cf57 2783@node Stack
70b88761
RP
2784@chapter Examining the Stack
2785
2786When your program has stopped, the first thing you need to know is where it
2787stopped and how it got there.
2788
2789@cindex call stack
2790Each time your program performs a function call, the information about
29a2b744 2791where in your program the call was made from is saved in a block of data
70b88761
RP
2792called a @dfn{stack frame}. The frame also contains the arguments of the
2793call and the local variables of the function that was called. All the
2794stack frames are allocated in a region of memory called the @dfn{call
2795stack}.
2796
2797When your program stops, the _GDBN__ commands for examining the stack allow you
2798to see all of this information.
2799
2800@cindex selected frame
2801One of the stack frames is @dfn{selected} by _GDBN__ and many _GDBN__ commands
2802refer implicitly to the selected frame. In particular, whenever you ask
29a2b744 2803_GDBN__ for the value of a variable in your program, the value is found in the
70b88761
RP
2804selected frame. There are special _GDBN__ commands to select whichever frame
2805you are interested in.
2806
29a2b744 2807When your program stops, _GDBN__ automatically selects the currently executing
70b88761 2808frame and describes it briefly as the @code{frame} command does
29a2b744 2809(@pxref{Frame Info, ,Information About a Frame}).
70b88761
RP
2810
2811@menu
b80282d5
RP
2812* Frames:: Stack Frames
2813* Backtrace:: Backtraces
2814* Selection:: Selecting a Frame
2815* Frame Info:: Information on a Frame
70b88761
RP
2816@end menu
2817
4eb4cf57 2818@node Frames
70b88761
RP
2819@section Stack Frames
2820
2821@cindex frame
2822@cindex stack frame
2823The call stack is divided up into contiguous pieces called @dfn{stack
2824frames}, or @dfn{frames} for short; each frame is the data associated
2825with one call to one function. The frame contains the arguments given
2826to the function, the function's local variables, and the address at
2827which the function is executing.
2828
2829@cindex initial frame
2830@cindex outermost frame
2831@cindex innermost frame
2832When your program is started, the stack has only one frame, that of the
2833function @code{main}. This is called the @dfn{initial} frame or the
2834@dfn{outermost} frame. Each time a function is called, a new frame is
2835made. Each time a function returns, the frame for that function invocation
2836is eliminated. If a function is recursive, there can be many frames for
2837the same function. The frame for the function in which execution is
2838actually occurring is called the @dfn{innermost} frame. This is the most
2839recently created of all the stack frames that still exist.
2840
2841@cindex frame pointer
2842Inside your program, stack frames are identified by their addresses. A
2843stack frame consists of many bytes, each of which has its own address; each
2844kind of computer has a convention for choosing one of those bytes whose
2845address serves as the address of the frame. Usually this address is kept
2846in a register called the @dfn{frame pointer register} while execution is
2847going on in that frame.
2848
2849@cindex frame number
2850_GDBN__ assigns numbers to all existing stack frames, starting with
2851zero for the innermost frame, one for the frame that called it,
2852and so on upward. These numbers do not really exist in your program;
2853they are assigned by _GDBN__ to give you a way of designating stack
2854frames in _GDBN__ commands.
2855
2856@cindex frameless execution
2857Some compilers allow functions to be compiled so that they operate
2858without stack frames. (For example, the @code{_GCC__} option
2859@samp{-fomit-frame-pointer} will generate functions without a frame.)
2860This is occasionally done with heavily used library functions to save
2861the frame setup time. _GDBN__ has limited facilities for dealing with
2862these function invocations. If the innermost function invocation has no
2863stack frame, _GDBN__ will nevertheless regard it as though it had a
2864separate frame, which is numbered zero as usual, allowing correct
2865tracing of the function call chain. However, _GDBN__ has no provision
2866for frameless functions elsewhere in the stack.
2867
4eb4cf57 2868@node Backtrace
70b88761
RP
2869@section Backtraces
2870
29a2b744 2871A backtrace is a summary of how your program got where it is. It shows one
70b88761
RP
2872line per frame, for many frames, starting with the currently executing
2873frame (frame zero), followed by its caller (frame one), and on up the
2874stack.
2875
2876@table @code
2877@item backtrace
2878@itemx bt
2879@kindex backtrace
2880@kindex bt
2881Print a backtrace of the entire stack: one line per frame for all
2882frames in the stack.
2883
2884You can stop the backtrace at any time by typing the system interrupt
2885character, normally @kbd{C-c}.
2886
2887@item backtrace @var{n}
2888@itemx bt @var{n}
2889Similar, but print only the innermost @var{n} frames.
2890
2891@item backtrace -@var{n}
2892@itemx bt -@var{n}
2893Similar, but print only the outermost @var{n} frames.
2894@end table
2895
2896@kindex where
2897@kindex info stack
2898@kindex info s
2899The names @code{where} and @code{info stack} (abbreviated @code{info s})
2900are additional aliases for @code{backtrace}.
2901
2902Each line in the backtrace shows the frame number and the function name.
2903The program counter value is also shown---unless you use @code{set
2904print address off}. The backtrace also shows the source file name and
2905line number, as well as the arguments to the function. The program
2906counter value is omitted if it is at the beginning of the code for that
2907line number.
2908
2909Here is an example of a backtrace. It was made with the command
2910@samp{bt 3}, so it shows the innermost three frames.
2911
2912@smallexample
2913@group
203eea5d
RP
2914#0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8)
2915 at builtin.c:993
70b88761
RP
2916#1 0x6e38 in expand_macro (sym=0x2b600) at macro.c:242
2917#2 0x6840 in expand_token (obs=0x0, t=177664, td=0xf7fffb08)
2918 at macro.c:71
2919(More stack frames follow...)
2920@end group
2921@end smallexample
2922
2923@noindent
29a2b744
RP
2924The display for frame zero does not begin with a program counter
2925value, indicating that your program has stopped at the beginning of the
70b88761
RP
2926code for line @code{993} of @code{builtin.c}.
2927
4eb4cf57 2928@node Selection
70b88761
RP
2929@section Selecting a Frame
2930
29a2b744 2931Most commands for examining the stack and other data in your program work on
70b88761
RP
2932whichever stack frame is selected at the moment. Here are the commands for
2933selecting a stack frame; all of them finish by printing a brief description
2934of the stack frame just selected.
2935
2936@table @code
2937@item frame @var{n}
2938@itemx f @var{n}
2939@kindex frame
2940@kindex f
2941Select frame number @var{n}. Recall that frame zero is the innermost
2942(currently executing) frame, frame one is the frame that called the
2943innermost one, and so on. The highest-numbered frame is @code{main}'s
2944frame.
2945
2946@item frame @var{addr}
2947@itemx f @var{addr}
2948Select the frame at address @var{addr}. This is useful mainly if the
2949chaining of stack frames has been damaged by a bug, making it
2950impossible for _GDBN__ to assign numbers properly to all frames. In
29a2b744 2951addition, this can be useful when your program has multiple stacks and
70b88761
RP
2952switches between them.
2953
c728f1f0 2954_if__(_SPARC__)
70b88761 2955On the SPARC architecture, @code{frame} needs two addresses to
e251e767 2956select an arbitrary frame: a frame pointer and a stack pointer.
70b88761
RP
2957@c note to future updaters: this is conditioned on a flag
2958@c FRAME_SPECIFICATION_DYADIC in the tm-*.h files, currently only used
2959@c by SPARC, hence the specific attribution. Generalize or list all
2960@c possibilities if more supported machines start doing this.
c728f1f0 2961_fi__(_SPARC__)
70b88761
RP
2962
2963@item up @var{n}
2964@kindex up
2965Move @var{n} frames up the stack. For positive numbers @var{n}, this
2966advances toward the outermost frame, to higher frame numbers, to frames
2967that have existed longer. @var{n} defaults to one.
2968
2969@item down @var{n}
2970@kindex down
2971@kindex do
2972Move @var{n} frames down the stack. For positive numbers @var{n}, this
2973advances toward the innermost frame, to lower frame numbers, to frames
2974that were created more recently. @var{n} defaults to one. You may
2975abbreviate @code{down} as @code{do}.
2976@end table
2977
2978All of these commands end by printing two lines of output describing the
2979frame. The first line shows the frame number, the function name, the
2980arguments, and the source file and line number of execution in that
2981frame. The second line shows the text of that source line. For
2982example:
2983
2984@smallexample
29a2b744 2985@group
70b88761 2986(_GDBP__) up
203eea5d
RP
2987#1 0x22f0 in main (argc=1, argv=0xf7fffbf4, env=0xf7fffbfc)
2988 at env.c:10
70b88761 298910 read_input_file (argv[i]);
29a2b744 2990@end group
70b88761
RP
2991@end smallexample
2992
29a2b744
RP
2993After such a printout, the @code{list} command with no arguments will
2994print ten lines centered on the point of execution in the frame.
2995@xref{List, ,Printing Source Lines}.
70b88761
RP
2996
2997@table @code
2998@item up-silently @var{n}
2999@itemx down-silently @var{n}
3000@kindex down-silently
3001@kindex up-silently
3002These two commands are variants of @code{up} and @code{down},
3003respectively; they differ in that they do their work silently, without
3004causing display of the new frame. They are intended primarily for use
3005in _GDBN__ command scripts, where the output might be unnecessary and
e251e767 3006distracting.
70b88761
RP
3007@end table
3008
4eb4cf57 3009@node Frame Info
70b88761
RP
3010@section Information About a Frame
3011
3012There are several other commands to print information about the selected
3013stack frame.
3014
3015@table @code
3016@item frame
3017@itemx f
29a2b744
RP
3018When used without any argument, this command does not change which
3019frame is selected, but prints a brief description of the currently
70b88761 3020selected stack frame. It can be abbreviated @code{f}. With an
29a2b744
RP
3021argument, this command is used to select a stack frame
3022(@pxref{Selection, ,Selecting a Frame}).
70b88761
RP
3023
3024@item info frame
70b88761 3025@itemx info f
29a2b744 3026@kindex info frame
70b88761
RP
3027@kindex info f
3028This command prints a verbose description of the selected stack frame,
3029including the address of the frame, the addresses of the next frame down
c2bbbb22
RP
3030(called by this frame) and the next frame up (caller of this frame), the
3031language that the source code corresponding to this frame was written in,
70b88761
RP
3032the address of the frame's arguments, the program counter saved in it
3033(the address of execution in the caller frame), and which registers
3034were saved in the frame. The verbose description is useful when
3035something has gone wrong that has made the stack format fail to fit
3036the usual conventions.
3037
3038@item info frame @var{addr}
3039@itemx info f @var{addr}
3040Print a verbose description of the frame at address @var{addr},
3041without selecting that frame. The selected frame remains unchanged by
3042this command.
3043
3044@item info args
3045@kindex info args
3046Print the arguments of the selected frame, each on a separate line.
3047
3048@item info locals
3049@kindex info locals
3050Print the local variables of the selected frame, each on a separate
3051line. These are all variables declared static or automatic within all
3052program blocks that execution in this frame is currently inside of.
3053
3054@item info catch
3055@kindex info catch
3056@cindex catch exceptions
3057@cindex exception handlers
3058Print a list of all the exception handlers that are active in the
3059current stack frame at the current point of execution. To see other
3060exception handlers, visit the associated frame (using the @code{up},
3061@code{down}, or @code{frame} commands); then type @code{info catch}.
1041a570 3062@xref{Exception Handling, ,Breakpoints and Exceptions}.
70b88761
RP
3063@end table
3064
4eb4cf57 3065@node Source
70b88761
RP
3066@chapter Examining Source Files
3067
3068_GDBN__ can print parts of your program's source, since the debugging
1041a570
RP
3069information recorded in your program tells _GDBN__ what source files were
3070used to build it. When your program stops, _GDBN__ spontaneously prints
3071the line where it stopped. Likewise, when you select a stack frame
3072(@pxref{Selection, ,Selecting a Frame}), _GDBN__ prints the line where
3073execution in that frame has stopped. You can print other portions of
3074source files by explicit command.
70b88761 3075
4eb4cf57 3076_if__(!_DOSHOST__)
1041a570
RP
3077If you use _GDBN__ through its GNU Emacs interface, you may prefer to use
3078Emacs facilities to view source; @pxref{Emacs, ,Using _GDBN__ under GNU
3079Emacs}.
4eb4cf57 3080_fi__(!_DOSHOST__)
70b88761
RP
3081
3082@menu
b80282d5 3083* List:: Printing Source Lines
6f28dd0b 3084_if__(_GENERIC__ || !_H8__)
b80282d5 3085* Search:: Searching Source Files
6f28dd0b 3086_fi__(_GENERIC__ || !_H8__)
b80282d5
RP
3087* Source Path:: Specifying Source Directories
3088* Machine Code:: Source and Machine Code
70b88761
RP
3089@end menu
3090
4eb4cf57 3091@node List
70b88761
RP
3092@section Printing Source Lines
3093
3094@kindex list
3095@kindex l
3096To print lines from a source file, use the @code{list} command
3097(abbreviated @code{l}). There are several ways to specify what part
3098of the file you want to print.
3099
3100Here are the forms of the @code{list} command most commonly used:
3101
3102@table @code
3103@item list @var{linenum}
c338a2fd 3104Print lines centered around line number @var{linenum} in the
70b88761
RP
3105current source file.
3106
3107@item list @var{function}
c338a2fd 3108Print lines centered around the beginning of function
70b88761
RP
3109@var{function}.
3110
3111@item list
c338a2fd
RP
3112Print more lines. If the last lines printed were printed with a
3113@code{list} command, this prints lines following the last lines
70b88761 3114printed; however, if the last line printed was a solitary line printed
29a2b744 3115as part of displaying a stack frame (@pxref{Stack, ,Examining the
1041a570 3116Stack}), this prints lines centered around that line.
70b88761
RP
3117
3118@item list -
c338a2fd
RP
3119Print lines just before the lines last printed.
3120@end table
3121
3122By default, _GDBN__ prints ten source lines with any of these forms of
3123the @code{list} command. You can change this using @code{set listsize}:
3124
3125@table @code
3126@item set listsize @var{count}
3127@kindex set listsize
3128Make the @code{list} command display @var{count} source lines (unless
3129the @code{list} argument explicitly specifies some other number).
3130
3131@item show listsize
3132@kindex show listsize
3133Display the number of lines that @code{list} will currently display by
e251e767 3134default.
70b88761
RP
3135@end table
3136
3137Repeating a @code{list} command with @key{RET} discards the argument,
3138so it is equivalent to typing just @code{list}. This is more useful
3139than listing the same lines again. An exception is made for an
3140argument of @samp{-}; that argument is preserved in repetition so that
3141each repetition moves up in the source file.
3142
3143@cindex linespec
3144In general, the @code{list} command expects you to supply zero, one or two
3145@dfn{linespecs}. Linespecs specify source lines; there are several ways
3146of writing them but the effect is always to specify some source line.
3147Here is a complete description of the possible arguments for @code{list}:
3148
3149@table @code
3150@item list @var{linespec}
c338a2fd 3151Print lines centered around the line specified by @var{linespec}.
70b88761
RP
3152
3153@item list @var{first},@var{last}
3154Print lines from @var{first} to @var{last}. Both arguments are
3155linespecs.
3156
3157@item list ,@var{last}
c338a2fd 3158Print lines ending with @var{last}.
70b88761
RP
3159
3160@item list @var{first},
c338a2fd 3161Print lines starting with @var{first}.
70b88761
RP
3162
3163@item list +
c338a2fd 3164Print lines just after the lines last printed.
70b88761
RP
3165
3166@item list -
c338a2fd 3167Print lines just before the lines last printed.
70b88761
RP
3168
3169@item list
3170As described in the preceding table.
3171@end table
3172
3173Here are the ways of specifying a single source line---all the
3174kinds of linespec.
3175
3176@table @code
3177@item @var{number}
3178Specifies line @var{number} of the current source file.
3179When a @code{list} command has two linespecs, this refers to
3180the same source file as the first linespec.
3181
3182@item +@var{offset}
3183Specifies the line @var{offset} lines after the last line printed.
3184When used as the second linespec in a @code{list} command that has
3185two, this specifies the line @var{offset} lines down from the
3186first linespec.
3187
3188@item -@var{offset}
3189Specifies the line @var{offset} lines before the last line printed.
3190
3191@item @var{filename}:@var{number}
3192Specifies line @var{number} in the source file @var{filename}.
3193
3194@item @var{function}
3195@c FIXME: "of the open-brace" is C-centric. When we add other langs...
3196Specifies the line of the open-brace that begins the body of the
3197function @var{function}.
3198
3199@item @var{filename}:@var{function}
3200Specifies the line of the open-brace that begins the body of the
3201function @var{function} in the file @var{filename}. You only need the
3202file name with a function name to avoid ambiguity when there are
3203identically named functions in different source files.
3204
3205@item *@var{address}
3206Specifies the line containing the program address @var{address}.
3207@var{address} may be any expression.
3208@end table
3209
6f28dd0b 3210_if__(_GENERIC__ || !_H8__)
4eb4cf57 3211@node Search
70b88761
RP
3212@section Searching Source Files
3213@cindex searching
3214@kindex reverse-search
3215
3216There are two commands for searching through the current source file for a
3217regular expression.
3218
3219@table @code
3220@item forward-search @var{regexp}
3221@itemx search @var{regexp}
3222@kindex search
3223@kindex forward-search
1041a570
RP
3224The command @samp{forward-search @var{regexp}} checks each line,
3225starting with the one following the last line listed, for a match for
3226@var{regexp}. It lists the line that is found. You can use
3227synonym @samp{search @var{regexp}} or abbreviate the command name as
3228@code{fo}.
70b88761
RP
3229
3230@item reverse-search @var{regexp}
3231The command @samp{reverse-search @var{regexp}} checks each line, starting
3232with the one before the last line listed and going backward, for a match
3233for @var{regexp}. It lists the line that is found. You can abbreviate
3234this command as @code{rev}.
3235@end table
6f28dd0b 3236_fi__(_GENERIC__ || !_H8__)
70b88761 3237
4eb4cf57 3238@node Source Path
70b88761
RP
3239@section Specifying Source Directories
3240
3241@cindex source path
3242@cindex directories for source files
3243Executable programs sometimes do not record the directories of the source
3244files from which they were compiled, just the names. Even when they do,
3245the directories could be moved between the compilation and your debugging
3246session. _GDBN__ has a list of directories to search for source files;
3247this is called the @dfn{source path}. Each time _GDBN__ wants a source file,
3248it tries all the directories in the list, in the order they are present
3249in the list, until it finds a file with the desired name. Note that
3250the executable search path is @emph{not} used for this purpose. Neither is
3251the current working directory, unless it happens to be in the source
3252path.
3253
29a2b744 3254If _GDBN__ cannot find a source file in the source path, and the object
70b88761
RP
3255program records a directory, _GDBN__ tries that directory too. If the
3256source path is empty, and there is no record of the compilation
3257directory, _GDBN__ will, as a last resort, look in the current
3258directory.
3259
3260Whenever you reset or rearrange the source path, _GDBN__ will clear out
3261any information it has cached about where source files are found, where
3262each line is in the file, etc.
3263
3264@kindex directory
3265When you start _GDBN__, its source path is empty.
3266To add other directories, use the @code{directory} command.
3267
3268@table @code
3269@item directory @var{dirname} @dots{}
3270Add directory @var{dirname} to the front of the source path. Several
3271directory names may be given to this command, separated by @samp{:} or
3272whitespace. You may specify a directory that is already in the source
e251e767 3273path; this moves it forward, so it will be searched sooner.
7463aadd
RP
3274
3275You can use the string @samp{$cdir} to refer to the compilation
3276directory (if one is recorded), and @samp{$cwd} to refer to the current
3277working directory. @samp{$cwd} is not the same as @samp{.}---the former
3278tracks the current working directory as it changes during your _GDBN__
3279session, while the latter is immediately expanded to the current
3280directory at the time you add an entry to the source path.
70b88761
RP
3281
3282@item directory
3283Reset the source path to empty again. This requires confirmation.
3284
3285@c RET-repeat for @code{directory} is explicitly disabled, but since
29a2b744 3286@c repeating it would be a no-op we do not say that. (thanks to RMS)
70b88761
RP
3287
3288@item show directories
3289@kindex show directories
3290Print the source path: show which directories it contains.
3291@end table
3292
3293If your source path is cluttered with directories that are no longer of
3294interest, _GDBN__ may sometimes cause confusion by finding the wrong
3295versions of source. You can correct the situation as follows:
3296
3297@enumerate
3298@item
3299Use @code{directory} with no argument to reset the source path to empty.
3300
3301@item
3302Use @code{directory} with suitable arguments to reinstall the
3303directories you want in the source path. You can add all the
3304directories in one command.
3305@end enumerate
3306
4eb4cf57 3307@node Machine Code
70b88761 3308@section Source and Machine Code
1041a570 3309
70b88761
RP
3310You can use the command @code{info line} to map source lines to program
3311addresses (and viceversa), and the command @code{disassemble} to display
3312a range of addresses as machine instructions.
3313
3314@table @code
3315@item info line @var{linespec}
3316@kindex info line
3317Print the starting and ending addresses of the compiled code for
1041a570
RP
3318source line @var{linespec}. You can specify source lines in any of
3319the ways understood by the @code{list} command (@pxref{List, ,Printing
3320Source Lines}).
70b88761
RP
3321@end table
3322
1041a570
RP
3323For example, we can use @code{info line} to discover the location of
3324the object code for the first line of function
3325@code{m4_changequote}:
3326
70b88761
RP
3327@smallexample
3328(_GDBP__) info line m4_changecom
3329Line 895 of "builtin.c" starts at pc 0x634c and ends at 0x6350.
3330@end smallexample
3331
3332@noindent
3333We can also inquire (using @code{*@var{addr}} as the form for
3334@var{linespec}) what source line covers a particular address:
3335@smallexample
3336(_GDBP__) info line *0x63ff
3337Line 926 of "builtin.c" starts at pc 0x63e4 and ends at 0x6404.
3338@end smallexample
3339
c338a2fd 3340@cindex @code{$_} and @code{info line}
29a2b744
RP
3341After @code{info line}, the default address for the @code{x} command
3342is changed to the starting address of the line, so that @samp{x/i} is
3343sufficient to begin examining the machine code (@pxref{Memory,
3344,Examining Memory}). Also, this address is saved as the value of the
3345convenience variable @code{$_} (@pxref{Convenience Vars, ,Convenience
3346Variables}).
70b88761
RP
3347
3348@table @code
3349@kindex disassemble
3350@item disassemble
e94b4a2b
RP
3351This specialized command dumps a range of memory as machine
3352instructions. The default memory range is the function surrounding the
3353program counter of the selected frame. A single argument to this
3354command is a program counter value; the function surrounding this value
3355will be dumped. Two arguments specify a range of addresses (first
3356inclusive, second exclusive) to dump.
70b88761
RP
3357@end table
3358
4eb4cf57 3359_if__(_GENERIC__||!_H8__)
70b88761 3360We can use @code{disassemble} to inspect the object code
4eb4cf57
RP
3361range shown in the last @code{info line} example (the example
3362shows SPARC machine instructions):
70b88761 3363
4eb4cf57 3364_0__
70b88761
RP
3365@smallexample
3366(_GDBP__) disas 0x63e4 0x6404
3367Dump of assembler code from 0x63e4 to 0x6404:
b80282d5
RP
33680x63e4 <builtin_init+5340>: ble 0x63f8 <builtin_init+5360>
33690x63e8 <builtin_init+5344>: sethi %hi(0x4c00), %o0
33700x63ec <builtin_init+5348>: ld [%i1+4], %o0
33710x63f0 <builtin_init+5352>: b 0x63fc <builtin_init+5364>
33720x63f4 <builtin_init+5356>: ld [%o0+4], %o0
33730x63f8 <builtin_init+5360>: or %o0, 0x1a4, %o0
33740x63fc <builtin_init+5364>: call 0x9288 <path_search>
e251e767 33750x6400 <builtin_init+5368>: nop
70b88761 3376End of assembler dump.
70b88761 3377@end smallexample
4eb4cf57
RP
3378_1__
3379_fi__(_GENERIC__||!_H8__)
3380
3381_if__(!_GENERIC__||_H8__)
3382For example, here is the beginning of the output for the
3383disassembly of a function @code{fact}:
70b88761 3384
4eb4cf57
RP
3385_0__
3386@smallexample
3387(_GDBP__) disas fact
3388Dump of assembler code for function fact:
3389to 0x808c:
33900x802c <fact>: 6d f2 mov.w r2,@@-r7
33910x802e <fact+2>: 6d f3 mov.w r3,@@-r7
33920x8030 <fact+4>: 6d f6 mov.w r6,@@-r7
33930x8032 <fact+6>: 0d 76 mov.w r7,r6
33940x8034 <fact+8>: 6f 70 00 08 mov.w @@(0x8,r7),r0
33950x8038 <fact+12> 19 11 sub.w r1,r1
3396 .
3397 .
3398 .
3399@end smallexample
3400_1__
3401_fi__(!_GENERIC__||_H8__)
3402
3403
3404@node Data
70b88761
RP
3405@chapter Examining Data
3406
3407@cindex printing data
3408@cindex examining data
3409@kindex print
3410@kindex inspect
1041a570 3411@c "inspect" is not quite a synonym if you are using Epoch, which we do not
29a2b744 3412@c document because it is nonstandard... Under Epoch it displays in a
70b88761
RP
3413@c different window or something like that.
3414The usual way to examine data in your program is with the @code{print}
4eb4cf57
RP
3415command (abbreviated @code{p}), or its synonym @code{inspect}.
3416_if__(!_CONLY__)
3417It evaluates and prints the value of an expression of the language your
1041a570 3418program is written in (@pxref{Languages, ,Using _GDBN__ with Different
4eb4cf57
RP
3419Languages}).
3420_fi__(!_CONLY__)
70b88761 3421
e0dacfd1
RP
3422@table @code
3423@item print @var{exp}
3424@itemx print /@var{f} @var{exp}
3425@var{exp} is an expression (in the source language). By default
70b88761 3426the value of @var{exp} is printed in a format appropriate to its data
e0dacfd1
RP
3427type; you can choose a different format by specifying @samp{/@var{f}},
3428where @var{f} is a letter specifying the format; @pxref{Output formats}.
3429
3430@item print
3431@itemx print /@var{f}
3432If you omit @var{exp}, _GDBN__ displays the last value again (from the
1041a570 3433@dfn{value history}; @pxref{Value History, ,Value History}). This allows you to
e0dacfd1
RP
3434conveniently inspect the same value in an alternative format.
3435@end table
70b88761
RP
3436
3437A more low-level way of examining data is with the @code{x} command.
3438It examines data in memory at a specified address and prints it in a
29a2b744 3439specified format. @xref{Memory, ,Examining Memory}.
70b88761 3440
29a2b744 3441If you are interested in information about types, or about how the fields
b80282d5 3442of a struct or class are declared, use the @code{ptype @var{exp}}
1041a570 3443command rather than @code{print}. @xref{Symbols, ,Examining the Symbol Table}.
b80282d5 3444
70b88761 3445@menu
b80282d5
RP
3446* Expressions:: Expressions
3447* Variables:: Program Variables
3448* Arrays:: Artificial Arrays
3449* Output formats:: Output formats
3450* Memory:: Examining Memory
3451* Auto Display:: Automatic Display
3452* Print Settings:: Print Settings
3453* Value History:: Value History
3454* Convenience Vars:: Convenience Variables
3455* Registers:: Registers
4eb4cf57 3456_if__(_GENERIC__ || !_H8__)
b80282d5 3457* Floating Point Hardware:: Floating Point Hardware
4eb4cf57 3458_fi__(_GENERIC__ || !_H8__)
70b88761
RP
3459@end menu
3460
4eb4cf57 3461@node Expressions
70b88761
RP
3462@section Expressions
3463
3464@cindex expressions
3465@code{print} and many other _GDBN__ commands accept an expression and
3466compute its value. Any kind of constant, variable or operator defined
3467by the programming language you are using is legal in an expression in
3468_GDBN__. This includes conditional expressions, function calls, casts
3469and string constants. It unfortunately does not include symbols defined
b80282d5 3470by preprocessor @code{#define} commands.
70b88761 3471
4eb4cf57 3472_if__(!_CONLY__)
c2bbbb22 3473Because C is so widespread, most of the expressions shown in examples in
1041a570 3474this manual are in C. @xref{Languages, , Using _GDBN__ with Different
c2bbbb22 3475Languages}, for information on how to use expressions in other
e251e767 3476languages.
c2bbbb22
RP
3477
3478In this section, we discuss operators that you can use in _GDBN__
e251e767 3479expressions regardless of your programming language.
c2bbbb22 3480
70b88761
RP
3481Casts are supported in all languages, not just in C, because it is so
3482useful to cast a number into a pointer so as to examine a structure
3483at that address in memory.
c2bbbb22 3484@c FIXME: casts supported---Mod2 true?
4eb4cf57 3485_fi__(!_CONLY__)
70b88761 3486
c2bbbb22 3487_GDBN__ supports these operators in addition to those of programming
70b88761
RP
3488languages:
3489
3490@table @code
3491@item @@
3492@samp{@@} is a binary operator for treating parts of memory as arrays.
1041a570 3493@xref{Arrays, ,Artificial Arrays}, for more information.
70b88761
RP
3494
3495@item ::
3496@samp{::} allows you to specify a variable in terms of the file or
1041a570 3497function where it is defined. @xref{Variables, ,Program Variables}.
70b88761
RP
3498
3499@item @{@var{type}@} @var{addr}
3500Refers to an object of type @var{type} stored at address @var{addr} in
3501memory. @var{addr} may be any expression whose value is an integer or
3502pointer (but parentheses are required around binary operators, just as in
3503a cast). This construct is allowed regardless of what kind of data is
1041a570 3504normally supposed to reside at @var{addr}.
70b88761
RP
3505@end table
3506
4eb4cf57 3507@node Variables
70b88761
RP
3508@section Program Variables
3509
3510The most common kind of expression to use is the name of a variable
3511in your program.
3512
3513Variables in expressions are understood in the selected stack frame
29a2b744
RP
3514(@pxref{Selection, ,Selecting a Frame}); they must either be global
3515(or static) or be visible according to the scope rules of the
3516programming language from the point of execution in that frame. This
3517means that in the function
70b88761
RP
3518
3519@example
3520foo (a)
3521 int a;
3522@{
3523 bar (a);
3524 @{
3525 int b = test ();
3526 bar (b);
3527 @}
3528@}
3529@end example
3530
3531@noindent
29a2b744 3532the variable @code{a} is usable whenever your program is executing
70b88761 3533within the function @code{foo}, but the variable @code{b} is visible
29a2b744 3534only while your program is executing inside the block in which @code{b}
70b88761
RP
3535is declared.
3536
3537@cindex variable name conflict
3538There is an exception: you can refer to a variable or function whose
3539scope is a single source file even if the current execution point is not
3540in this file. But it is possible to have more than one such variable or
6ca72cc6
RP
3541function with the same name (in different source files). If that
3542happens, referring to that name has unpredictable effects. If you wish,
3543you can specify a static variable in a particular function or file,
3544using the colon-colon notation:
70b88761
RP
3545
3546@cindex colon-colon
a6d0b6d3 3547@iftex
29a2b744 3548@c info cannot cope with a :: index entry, but why deprive hard copy readers?
70b88761 3549@kindex ::
a6d0b6d3 3550@end iftex
70b88761
RP
3551@example
3552@var{file}::@var{variable}
6ca72cc6 3553@var{function}::@var{variable}
70b88761
RP
3554@end example
3555
3556@noindent
6ca72cc6 3557Here @var{file} or @var{function} is the name of the context for the
6c380b13
RP
3558static @var{variable}. In the case of file names, you can use quotes to
3559make sure _GDBN__ parses the file name as a single word---for example,
3560to print a global value of @code{x} defined in @file{f2.c}:
3561
3562@example
3563(_GDBP__) p 'f2.c'::x
3564@end example
70b88761 3565
0f153e74 3566_if__(!_CONLY__)
c2bbbb22 3567@cindex C++ scope resolution
70b88761
RP
3568This use of @samp{::} is very rarely in conflict with the very similar
3569use of the same notation in C++. _GDBN__ also supports use of the C++
c2bbbb22 3570scope resolution operator in _GDBN__ expressions.
0f153e74 3571_fi__(!_CONLY__)
70b88761 3572
3d3ab540
RP
3573@cindex wrong values
3574@cindex variable values, wrong
3575@quotation
3576@emph{Warning:} Occasionally, a local variable may appear to have the
3577wrong value at certain points in a function---just after entry to the
29a2b744 3578function, and just before exit. You may see this problem when you are
3d3ab540
RP
3579stepping by machine instructions. This is because on most machines, it
3580takes more than one instruction to set up a stack frame (including local
29a2b744 3581variable definitions); if you are stepping by machine instructions,
3d3ab540
RP
3582variables may appear to have the wrong values until the stack frame is
3583completely built. On function exit, it usually also takes more than one
3584machine instruction to destroy a stack frame; after you begin stepping
3585through that group of instructions, local variable definitions may be
3586gone.
3587@end quotation
3588
4eb4cf57 3589@node Arrays
70b88761
RP
3590@section Artificial Arrays
3591
3592@cindex artificial array
3593@kindex @@
3594It is often useful to print out several successive objects of the
3595same type in memory; a section of an array, or an array of
3596dynamically determined size for which only a pointer exists in the
3597program.
3598
3599This can be done by constructing an @dfn{artificial array} with the
3600binary operator @samp{@@}. The left operand of @samp{@@} should be
3601the first element of the desired array, as an individual object.
3602The right operand should be the desired length of the array. The result is
3603an array value whose elements are all of the type of the left argument.
3604The first element is actually the left argument; the second element
3605comes from bytes of memory immediately following those that hold the
3606first element, and so on. Here is an example. If a program says
3607
3608@example
3609int *array = (int *) malloc (len * sizeof (int));
3610@end example
3611
3612@noindent
3613you can print the contents of @code{array} with
3614
3615@example
3616p *array@@len
3617@end example
3618
3619The left operand of @samp{@@} must reside in memory. Array values made
3620with @samp{@@} in this way behave just like other arrays in terms of
3621subscripting, and are coerced to pointers when used in expressions.
3622Artificial arrays most often appear in expressions via the value history
1041a570 3623(@pxref{Value History, ,Value History}), after printing one out.)
70b88761 3624
1041a570 3625Sometimes the artificial array mechanism is not quite enough; in
3d3ab540 3626moderately complex data structures, the elements of interest may not
1041a570
RP
3627actually be adjacent---for example, if you are interested in the values
3628of pointers in an array. One useful work-around in this situation is
3629to use a convenience variable (@pxref{Convenience Vars, ,Convenience
3630Variables}) as a counter in an expression that prints the first
3631interesting value, and then repeat that expression via @key{RET}. For
3632instance, suppose you have an array @code{dtab} of pointers to
3633structures, and you are interested in the values of a field @code{fv}
3634in each structure. Here is an example of what you might type:
3635
3d3ab540
RP
3636@example
3637set $i = 0
3638p dtab[$i++]->fv
3639@key{RET}
3640@key{RET}
3641@dots{}
3642@end example
3643
4eb4cf57 3644@node Output formats
70b88761
RP
3645@section Output formats
3646
3647@cindex formatted output
3648@cindex output formats
3649By default, _GDBN__ prints a value according to its data type. Sometimes
3650this is not what you want. For example, you might want to print a number
3651in hex, or a pointer in decimal. Or you might want to view data in memory
3652at a certain address as a character string or as an instruction. To do
3653these things, specify an @dfn{output format} when you print a value.
3654
3655The simplest use of output formats is to say how to print a value
3656already computed. This is done by starting the arguments of the
3657@code{print} command with a slash and a format letter. The format
3658letters supported are:
3659
3660@table @code
3661@item x
3662Regard the bits of the value as an integer, and print the integer in
3663hexadecimal.
3664
3665@item d
3666Print as integer in signed decimal.
3667
3668@item u
3669Print as integer in unsigned decimal.
3670
3671@item o
3672Print as integer in octal.
3673
3674@item t
3675Print as integer in binary. The letter @samp{t} stands for ``two''.
3676
3677@item a
3678Print as an address, both absolute in hex and as an offset from the
3679nearest preceding symbol. This format can be used to discover where (in
3680what function) an unknown address is located:
1041a570 3681
70b88761
RP
3682@example
3683(_GDBP__) p/a 0x54320
3684_0__$3 = 0x54320 <_initialize_vx+396>_1__
3685@end example
3686
70b88761
RP
3687@item c
3688Regard as an integer and print it as a character constant.
3689
3690@item f
3691Regard the bits of the value as a floating point number and print
3692using typical floating point syntax.
3693@end table
3694
3695For example, to print the program counter in hex (@pxref{Registers}), type
3696
3697@example
3698p/x $pc
3699@end example
3700
3701@noindent
3702Note that no space is required before the slash; this is because command
3703names in _GDBN__ cannot contain a slash.
3704
3705To reprint the last value in the value history with a different format,
3706you can use the @code{print} command with just a format and no
3707expression. For example, @samp{p/x} reprints the last value in hex.
3708
4eb4cf57 3709@node Memory
70b88761
RP
3710@section Examining Memory
3711
1041a570
RP
3712You can use the command @code{x} (for ``examine'') to examine memory in
3713any of several formats, independently of your program's data types.
3714
70b88761
RP
3715@cindex examining memory
3716@table @code
3717@kindex x
cedaf8bc
RP
3718@item x/@var{nfu} @var{addr}
3719@itemx x @var{addr}
3720@itemx x
1041a570
RP
3721Use the command @code{x} to examine memory.
3722@end table
3723
3724@var{n}, @var{f}, and @var{u} are all optional parameters that specify how
3725much memory to display and how to format it; @var{addr} is an
cedaf8bc
RP
3726expression giving the address where you want to start displaying memory.
3727If you use defaults for @var{nfu}, you need not type the slash @samp{/}.
3728Several commands set convenient defaults for @var{addr}.
70b88761 3729
1041a570
RP
3730@table @r
3731@item @var{n}, the repeat count
3732The repeat count is a decimal integer; the default is 1. It specifies
3733how much memory (counting by units @var{u}) to display.
cedaf8bc
RP
3734@c This really is **decimal**; unaffected by 'set radix' as of GDB
3735@c 4.1.2.
70b88761 3736
1041a570
RP
3737@item @var{f}, the display format
3738The display format is one of the formats used by @code{print},
cedaf8bc
RP
3739or @samp{s} (null-terminated string) or @samp{i} (machine instruction).
3740The default is @samp{x} (hexadecimal) initially, or the format from the
3741last time you used either @code{x} or @code{print}.
70b88761 3742
1041a570
RP
3743@item @var{u}, the unit size
3744The unit size is any of
70b88761
RP
3745@table @code
3746@item b
cedaf8bc 3747Bytes.
70b88761 3748@item h
cedaf8bc 3749Halfwords (two bytes).
70b88761 3750@item w
cedaf8bc 3751Words (four bytes). This is the initial default.
70b88761 3752@item g
cedaf8bc 3753Giant words (eight bytes).
70b88761
RP
3754@end table
3755
cedaf8bc
RP
3756Each time you specify a unit size with @code{x}, that size becomes the
3757default unit the next time you use @code{x}. (For the @samp{s} and
3758@samp{i} formats, the unit size is ignored and is normally not written.)
3759
1041a570 3760@item @var{addr}, starting display address
cedaf8bc
RP
3761@var{addr} is the address where you want _GDBN__ to begin displaying
3762memory. The expression need not have a pointer value (though it may);
3763it is always interpreted as an integer address of a byte of memory.
1041a570 3764@xref{Expressions, ,Expressions}, for more information on expressions. The default for
cedaf8bc
RP
3765@var{addr} is usually just after the last address examined---but several
3766other commands also set the default address: @code{info breakpoints} (to
3767the address of the last breakpoint listed), @code{info line} (to the
3768starting address of a line), and @code{print} (if you use it to display
3769a value from memory).
1041a570 3770@end table
70b88761 3771
cedaf8bc
RP
3772For example, @samp{x/3uh 0x54320} is a request to display three halfwords
3773(@code{h}) of memory, formatted as unsigned decimal integers (@samp{u}),
3774starting at address @code{0x54320}. @samp{x/4xw $sp} prints the four
3775words (@samp{w}) of memory above the stack pointer (here, @samp{$sp};
3776@pxref{Registers}) in hexadecimal (@samp{x}).
70b88761 3777
cedaf8bc 3778Since the letters indicating unit sizes are all distinct from the
29a2b744 3779letters specifying output formats, you do not have to remember whether
cedaf8bc
RP
3780unit size or format comes first; either order will work. The output
3781specifications @samp{4xw} and @samp{4wx} mean exactly the same thing.
3782(However, the count @var{n} must come first; @samp{wx4} will not work.)
3783
3784Even though the unit size @var{u} is ignored for the formats @samp{s}
3785and @samp{i}, you might still want to use a count @var{n}; for example,
3786@samp{3i} specifies that you want to see three machine instructions,
3787including any operands. The command @code{disassemble} gives an
3788alternative way of inspecting machine instructions; @pxref{Machine
3789Code}.
3790
3791All the defaults for the arguments to @code{x} are designed to make it
3792easy to continue scanning memory with minimal specifications each time
1041a570 3793you use @code{x}. For example, after you have inspected three machine
cedaf8bc
RP
3794instructions with @samp{x/3i @var{addr}}, you can inspect the next seven
3795with just @samp{x/7}. If you use @key{RET} to repeat the @code{x} command,
3796the repeat count @var{n} is used again; the other arguments default as
3797for successive uses of @code{x}.
70b88761 3798
c338a2fd 3799@cindex @code{$_}, @code{$__}, and value history
cedaf8bc 3800The addresses and contents printed by the @code{x} command are not saved
70b88761
RP
3801in the value history because there is often too much of them and they
3802would get in the way. Instead, _GDBN__ makes these values available for
3803subsequent use in expressions as values of the convenience variables
3804@code{$_} and @code{$__}. After an @code{x} command, the last address
3805examined is available for use in expressions in the convenience variable
3806@code{$_}. The contents of that address, as examined, are available in
3807the convenience variable @code{$__}.
3808
3809If the @code{x} command has a repeat count, the address and contents saved
3810are from the last memory unit printed; this is not the same as the last
3811address printed if several units were printed on the last line of output.
3812
4eb4cf57 3813@node Auto Display
70b88761
RP
3814@section Automatic Display
3815@cindex automatic display
3816@cindex display of expressions
3817
3818If you find that you want to print the value of an expression frequently
3819(to see how it changes), you might want to add it to the @dfn{automatic
29a2b744 3820display list} so that _GDBN__ will print its value each time your program stops.
70b88761
RP
3821Each expression added to the list is given a number to identify it;
3822to remove an expression from the list, you specify that number.
3823The automatic display looks like this:
3824
3825@example
38262: foo = 38
38273: bar[5] = (struct hack *) 0x3804
3828@end example
3829
3830@noindent
3831showing item numbers, expressions and their current values. As with
3832displays you request manually using @code{x} or @code{print}, you can
3833specify the output format you prefer; in fact, @code{display} decides
3834whether to use @code{print} or @code{x} depending on how elaborate your
3835format specification is---it uses @code{x} if you specify a unit size,
3836or one of the two formats (@samp{i} and @samp{s}) that are only
3837supported by @code{x}; otherwise it uses @code{print}.
3838
3839@table @code
3840@item display @var{exp}
3841@kindex display
3842Add the expression @var{exp} to the list of expressions to display
1041a570 3843each time your program stops. @xref{Expressions, ,Expressions}.
70b88761
RP
3844
3845@code{display} will not repeat if you press @key{RET} again after using it.
3846
3847@item display/@var{fmt} @var{exp}
3848For @var{fmt} specifying only a display format and not a size or
3849count, add the expression @var{exp} to the auto-display list but
3850arranges to display it each time in the specified format @var{fmt}.
3851@xref{Output formats}.
3852
3853@item display/@var{fmt} @var{addr}
3854For @var{fmt} @samp{i} or @samp{s}, or including a unit-size or a
3855number of units, add the expression @var{addr} as a memory address to
29a2b744
RP
3856be examined each time your program stops. Examining means in effect
3857doing @samp{x/@var{fmt} @var{addr}}. @xref{Memory, ,Examining Memory}.
70b88761
RP
3858@end table
3859
3860For example, @samp{display/i $pc} can be helpful, to see the machine
3861instruction about to be executed each time execution stops (@samp{$pc}
3862is a common name for the program counter; @pxref{Registers}).
3863
3864@table @code
3865@item undisplay @var{dnums}@dots{}
3866@itemx delete display @var{dnums}@dots{}
3867@kindex delete display
3868@kindex undisplay
3869Remove item numbers @var{dnums} from the list of expressions to display.
3870
3871@code{undisplay} will not repeat if you press @key{RET} after using it.
3872(Otherwise you would just get the error @samp{No display number @dots{}}.)
3873
3874@item disable display @var{dnums}@dots{}
3875@kindex disable display
3876Disable the display of item numbers @var{dnums}. A disabled display
3877item is not printed automatically, but is not forgotten. It may be
3878enabled again later.
3879
3880@item enable display @var{dnums}@dots{}
3881@kindex enable display
3882Enable display of item numbers @var{dnums}. It becomes effective once
3883again in auto display of its expression, until you specify otherwise.
3884
3885@item display
3886Display the current values of the expressions on the list, just as is
29a2b744 3887done when your program stops.
70b88761
RP
3888
3889@item info display
3890@kindex info display
3891Print the list of expressions previously set up to display
3892automatically, each one with its item number, but without showing the
3893values. This includes disabled expressions, which are marked as such.
3894It also includes expressions which would not be displayed right now
3895because they refer to automatic variables not currently available.
3896@end table
3897
3898If a display expression refers to local variables, then it does not make
3899sense outside the lexical context for which it was set up. Such an
3900expression is disabled when execution enters a context where one of its
3901variables is not defined. For example, if you give the command
3902@code{display last_char} while inside a function with an argument
29a2b744 3903@code{last_char}, then this argument will be displayed while your program
70b88761
RP
3904continues to stop inside that function. When it stops elsewhere---where
3905there is no variable @code{last_char}---display is disabled. The next time
3906your program stops where @code{last_char} is meaningful, you can enable the
3907display expression once again.
3908
4eb4cf57 3909@node Print Settings
70b88761
RP
3910@section Print Settings
3911
3912@cindex format options
3913@cindex print settings
3914_GDBN__ provides the following ways to control how arrays, structures,
e251e767 3915and symbols are printed.
70b88761
RP
3916
3917@noindent
3918These settings are useful for debugging programs in any language:
3919
3920@table @code
3921@item set print address
3922@item set print address on
3923@kindex set print address
3924_GDBN__ will print memory addresses showing the location of stack
3925traces, structure values, pointer values, breakpoints, and so forth,
3926even when it also displays the contents of those addresses. The default
3927is on. For example, this is what a stack frame display looks like, with
3928@code{set print address on}:
1041a570 3929
70b88761 3930@smallexample
1041a570 3931@group
70b88761 3932(_GDBP__) f
e251e767 3933#0 set_quotes (lq=0x34c78 "<<", rq=0x34c88 ">>")
70b88761 3934 at input.c:530
b80282d5 3935530 if (lquote != def_lquote)
1041a570 3936@end group
70b88761
RP
3937@end smallexample
3938
3939@item set print address off
3940Do not print addresses when displaying their contents. For example,
3941this is the same stack frame displayed with @code{set print address off}:
1041a570 3942
70b88761 3943@example
1041a570 3944@group
70b88761
RP
3945(_GDBP__) set print addr off
3946(_GDBP__) f
3947#0 set_quotes (lq="<<", rq=">>") at input.c:530
b80282d5 3948530 if (lquote != def_lquote)
1041a570 3949@end group
70b88761
RP
3950@end example
3951
3952@item show print address
3953@kindex show print address
3954Show whether or not addresses are to be printed.
3955
3956@item set print array
3957@itemx set print array on
3958@kindex set print array
3959_GDBN__ will pretty print arrays. This format is more convenient to read,
3960but uses more space. The default is off.
3961
3962@item set print array off.
3963Return to compressed format for arrays.
3964
3965@item show print array
3966@kindex show print array
3967Show whether compressed or pretty format is selected for displaying
e251e767 3968arrays.
70b88761
RP
3969
3970@item set print elements @var{number-of-elements}
3971@kindex set print elements
3972If _GDBN__ is printing a large array, it will stop printing after it has
3973printed the number of elements set by the @code{set print elements} command.
3974This limit also applies to the display of strings.
3975
3976@item show print elements
3977@kindex show print elements
3978Display the number of elements of a large array that _GDBN__ will print
3979before losing patience.
3980
3981@item set print pretty on
3982@kindex set print pretty
3983Cause _GDBN__ to print structures in an indented format with one member per
3984line, like this:
3985
3986@example
1041a570 3987@group
70b88761
RP
3988$1 = @{
3989 next = 0x0,
3990 flags = @{
3991 sweet = 1,
3992 sour = 1
3993 @},
3994 meat = 0x54 "Pork"
3995@}
1041a570 3996@end group
70b88761
RP
3997@end example
3998
3999@item set print pretty off
4000Cause _GDBN__ to print structures in a compact format, like this:
4001
4002@smallexample
1041a570 4003@group
38962738
RP
4004$1 = @{next = 0x0, flags = @{sweet = 1, sour = 1@}, \
4005meat = 0x54 "Pork"@}
1041a570 4006@end group
70b88761
RP
4007@end smallexample
4008
4009@noindent
4010This is the default format.
4011
4012@item show print pretty
4013@kindex show print pretty
4014Show which format _GDBN__ will use to print structures.
4015
4016@item set print sevenbit-strings on
f2857bd9 4017@kindex set print sevenbit-strings
e251e767 4018Print using only seven-bit characters; if this option is set,
70b88761
RP
4019_GDBN__ will display any eight-bit characters (in strings or character
4020values) using the notation @code{\}@var{nnn}. For example, @kbd{M-a} is
4021displayed as @code{\341}.
4022
4023@item set print sevenbit-strings off
4024Print using either seven-bit or eight-bit characters, as required. This
4025is the default.
4026
4027@item show print sevenbit-strings
f2857bd9 4028@kindex show print sevenbit-strings
70b88761
RP
4029Show whether or not _GDBN__ will print only seven-bit characters.
4030
4031@item set print union on
4032@kindex set print union
4033Tell _GDBN__ to print unions which are contained in structures. This is the
4034default setting.
4035
4036@item set print union off
4037Tell _GDBN__ not to print unions which are contained in structures.
4038
4039@item show print union
4040@kindex show print union
4041Ask _GDBN__ whether or not it will print unions which are contained in
e251e767 4042structures.
70b88761
RP
4043
4044For example, given the declarations
4045
4046@smallexample
4047typedef enum @{Tree, Bug@} Species;
4048typedef enum @{Big_tree, Acorn, Seedling@} Tree_forms;
203eea5d
RP
4049typedef enum @{Caterpillar, Cocoon, Butterfly@}
4050 Bug_forms;
70b88761
RP
4051
4052struct thing @{
4053 Species it;
4054 union @{
4055 Tree_forms tree;
4056 Bug_forms bug;
4057 @} form;
4058@};
4059
4060struct thing foo = @{Tree, @{Acorn@}@};
4061@end smallexample
4062
4063@noindent
4064with @code{set print union on} in effect @samp{p foo} would print
4065
4066@smallexample
4067$1 = @{it = Tree, form = @{tree = Acorn, bug = Cocoon@}@}
4068@end smallexample
4069
4070@noindent
4071and with @code{set print union off} in effect it would print
4072
4073@smallexample
4074$1 = @{it = Tree, form = @{...@}@}
4075@end smallexample
4076@end table
4077
4078@noindent
4079These settings are of interest when debugging C++ programs:
4080
4081@table @code
e251e767
RP
4082@item set print demangle
4083@itemx set print demangle on
70b88761
RP
4084@kindex set print demangle
4085Print C++ names in their source form rather than in the mangled form
4086in which they are passed to the assembler and linker for type-safe linkage.
4087The default is on.
4088
4089@item show print demangle
4090@kindex show print demangle
4091Show whether C++ names will be printed in mangled or demangled form.
4092
e251e767
RP
4093@item set print asm-demangle
4094@itemx set print asm-demangle on
70b88761
RP
4095@kindex set print asm-demangle
4096Print C++ names in their source form rather than their mangled form, even
4097in assembler code printouts such as instruction disassemblies.
4098The default is off.
4099
4100@item show print asm-demangle
4101@kindex show print asm-demangle
4102Show whether C++ names in assembly listings will be printed in mangled
4103or demangled form.
4104
4105@item set print object
4106@itemx set print object on
4107@kindex set print object
4108When displaying a pointer to an object, identify the @emph{actual}
4109(derived) type of the object rather than the @emph{declared} type, using
4110the virtual function table.
4111
4112@item set print object off
4113Display only the declared type of objects, without reference to the
4114virtual function table. This is the default setting.
4115
4116@item show print object
4117@kindex show print object
4118Show whether actual, or declared, object types will be displayed.
4119
e251e767
RP
4120@item set print vtbl
4121@itemx set print vtbl on
70b88761
RP
4122@kindex set print vtbl
4123Pretty print C++ virtual function tables. The default is off.
4124
4125@item set print vtbl off
4126Do not pretty print C++ virtual function tables.
4127
4128@item show print vtbl
4129@kindex show print vtbl
4130Show whether C++ virtual function tables are pretty printed, or not.
70b88761
RP
4131@end table
4132
4eb4cf57 4133@node Value History
70b88761
RP
4134@section Value History
4135
4136@cindex value history
4137Values printed by the @code{print} command are saved in _GDBN__'s @dfn{value
4138history} so that you can refer to them in other expressions. Values are
4139kept until the symbol table is re-read or discarded (for example with
4140the @code{file} or @code{symbol-file} commands). When the symbol table
4141changes, the value history is discarded, since the values may contain
4142pointers back to the types defined in the symbol table.
4143
4144@cindex @code{$}
4145@cindex @code{$$}
4146@cindex history number
4147The values printed are given @dfn{history numbers} for you to refer to them
4148by. These are successive integers starting with one. @code{print} shows you
4149the history number assigned to a value by printing @samp{$@var{num} = }
4150before the value; here @var{num} is the history number.
4151
4152To refer to any previous value, use @samp{$} followed by the value's
4153history number. The way @code{print} labels its output is designed to
4154remind you of this. Just @code{$} refers to the most recent value in
4155the history, and @code{$$} refers to the value before that.
4156@code{$$@var{n}} refers to the @var{n}th value from the end; @code{$$2}
4157is the value just prior to @code{$$}, @code{$$1} is equivalent to
4158@code{$$}, and @code{$$0} is equivalent to @code{$}.
4159
4160For example, suppose you have just printed a pointer to a structure and
4161want to see the contents of the structure. It suffices to type
4162
4163@example
4164p *$
4165@end example
4166
4167If you have a chain of structures where the component @code{next} points
4168to the next one, you can print the contents of the next one with this:
4169
4170@example
4171p *$.next
4172@end example
4173
4174@noindent
4175You can print successive links in the chain by repeating this
4176command---which you can do by just typing @key{RET}.
4177
4178Note that the history records values, not expressions. If the value of
4179@code{x} is 4 and you type these commands:
4180
4181@example
4182print x
4183set x=5
4184@end example
4185
4186@noindent
4187then the value recorded in the value history by the @code{print} command
4188remains 4 even though the value of @code{x} has changed.
4189
4190@table @code
4191@kindex show values
4192@item show values
4193Print the last ten values in the value history, with their item numbers.
4194This is like @samp{p@ $$9} repeated ten times, except that @code{show
4195values} does not change the history.
4196
4197@item show values @var{n}
4198Print ten history values centered on history item number @var{n}.
4199
4200@item show values +
4201Print ten history values just after the values last printed. If no more
4202values are available, produces no display.
4203@end table
4204
4205Pressing @key{RET} to repeat @code{show values @var{n}} has exactly the
e251e767 4206same effect as @samp{show values +}.
70b88761 4207
4eb4cf57 4208@node Convenience Vars
70b88761
RP
4209@section Convenience Variables
4210
4211@cindex convenience variables
4212_GDBN__ provides @dfn{convenience variables} that you can use within
4213_GDBN__ to hold on to a value and refer to it later. These variables
4214exist entirely within _GDBN__; they are not part of your program, and
4215setting a convenience variable has no direct effect on further execution
1041a570 4216of your program. That is why you can use them freely.
70b88761
RP
4217
4218Convenience variables are prefixed with @samp{$}. Any name preceded by
4219@samp{$} can be used for a convenience variable, unless it is one of
4220the predefined machine-specific register names (@pxref{Registers}).
4221(Value history references, in contrast, are @emph{numbers} preceded
1041a570 4222by @samp{$}. @xref{Value History, ,Value History}.)
70b88761
RP
4223
4224You can save a value in a convenience variable with an assignment
4225expression, just as you would set a variable in your program. Example:
4226
4227@example
4228set $foo = *object_ptr
4229@end example
4230
4231@noindent
4232would save in @code{$foo} the value contained in the object pointed to by
4233@code{object_ptr}.
4234
4235Using a convenience variable for the first time creates it; but its value
4236is @code{void} until you assign a new value. You can alter the value with
4237another assignment at any time.
4238
4239Convenience variables have no fixed types. You can assign a convenience
4240variable any type of value, including structures and arrays, even if
4241that variable already has a value of a different type. The convenience
4242variable, when used as an expression, has the type of its current value.
4243
4244@table @code
4245@item show convenience
4246@kindex show convenience
4247Print a list of convenience variables used so far, and their values.
4248Abbreviated @code{show con}.
4249@end table
4250
4251One of the ways to use a convenience variable is as a counter to be
4252incremented or a pointer to be advanced. For example, to print
4253a field from successive elements of an array of structures:
4254
4255_0__@example
4256set $i = 0
4257print bar[$i++]->contents
4258@i{@dots{} repeat that command by typing @key{RET}.}
4259_1__@end example
4260
4261Some convenience variables are created automatically by _GDBN__ and given
4262values likely to be useful.
4263
4264@table @code
4265@item $_
c338a2fd 4266@kindex $_
70b88761 4267The variable @code{$_} is automatically set by the @code{x} command to
29a2b744
RP
4268the last address examined (@pxref{Memory, ,Examining Memory}). Other
4269commands which provide a default address for @code{x} to examine also
4270set @code{$_} to that address; these commands include @code{info line}
4271and @code{info breakpoint}. The type of @code{$_} is @code{void *}
4272except when set by the @code{x} command, in which case it is a pointer
4273to the type of @code{$__}.
70b88761
RP
4274
4275@item $__
c338a2fd 4276@kindex $__
70b88761 4277The variable @code{$__} is automatically set by the @code{x} command
c2bbbb22
RP
4278to the value found in the last address examined. Its type is chosen
4279to match the format in which the data was printed.
70b88761
RP
4280@end table
4281
4eb4cf57 4282@node Registers
70b88761
RP
4283@section Registers
4284
4285@cindex registers
b80282d5 4286You can refer to machine register contents, in expressions, as variables
70b88761
RP
4287with names starting with @samp{$}. The names of registers are different
4288for each machine; use @code{info registers} to see the names used on
e251e767 4289your machine.
70b88761
RP
4290
4291@table @code
4292@item info registers
4293@kindex info registers
b80282d5
RP
4294Print the names and values of all registers except floating-point
4295registers (in the selected stack frame).
4296
4297@item info all-registers
4298@kindex info all-registers
4299@cindex floating point registers
4300Print the names and values of all registers, including floating-point
4301registers.
70b88761 4302
4eb4cf57 4303@item info registers @var{regname} @dots{}
0d1cd01e
JG
4304Print the relativized value of each specified register @var{regname}.
4305@var{regname} may be any register name valid on the machine you are using, with
70b88761
RP
4306or without the initial @samp{$}.
4307@end table
4308
09267865 4309_GDBN__ has four ``standard'' register names that are available (in
29a2b744 4310expressions) on most machines---whenever they do not conflict with an
09267865
RP
4311architecture's canonical mnemonics for registers. The register names
4312@code{$pc} and @code{$sp} are used for the program counter register and
4313the stack pointer. @code{$fp} is used for a register that contains a
4314pointer to the current stack frame, and @code{$ps} is used for a
4315register that contains the processor status. For example,
70b88761 4316you could print the program counter in hex with
1041a570 4317
70b88761
RP
4318@example
4319p/x $pc
4320@end example
4321
4322@noindent
4323or print the instruction to be executed next with
1041a570 4324
70b88761
RP
4325@example
4326x/i $pc
4327@end example
4328
4329@noindent
29a2b744
RP
4330or add four to the stack pointer @footnote{This is a way of removing
4331one word from the stack, on machines where stacks grow downward in
4332memory (most machines, nowadays). This assumes that the innermost
4333stack frame is selected; setting @code{$sp} is not allowed when other
4334stack frames are selected. To pop entire frames off the stack,
4335regardless of machine architecture, use @code{return};
1041a570
RP
4336@pxref{Returning, ,Returning from a Function}.} with
4337
70b88761
RP
4338@example
4339set $sp += 4
4340@end example
4341
09267865
RP
4342Whenever possible, these four standard register names are available on
4343your machine even though the machine has different canonical mnemonics,
4344so long as there is no conflict. The @code{info registers} command
4345shows the canonical names. For example, on the SPARC, @code{info
70b88761
RP
4346registers} displays the processor status register as @code{$psr} but you
4347can also refer to it as @code{$ps}.
4348
4349_GDBN__ always considers the contents of an ordinary register as an
4350integer when the register is examined in this way. Some machines have
4351special registers which can hold nothing but floating point; these
4352registers are considered to have floating point values. There is no way
4353to refer to the contents of an ordinary register as floating point value
4354(although you can @emph{print} it as a floating point value with
4355@samp{print/f $@var{regname}}).
4356
4357Some registers have distinct ``raw'' and ``virtual'' data formats. This
4358means that the data format in which the register contents are saved by
4359the operating system is not the same one that your program normally
4360sees. For example, the registers of the 68881 floating point
4361coprocessor are always saved in ``extended'' (raw) format, but all C
4362programs expect to work with ``double'' (virtual) format. In such
4363cases, _GDBN__ normally works with the virtual format only (the format that
4364makes sense for your program), but the @code{info registers} command
4365prints the data in both formats.
4366
4367Normally, register values are relative to the selected stack frame
29a2b744
RP
4368(@pxref{Selection, ,Selecting a Frame}). This means that you get the
4369value that the register would contain if all stack frames farther in
4370were exited and their saved registers restored. In order to see the
4371true contents of hardware registers, you must select the innermost
4372frame (with @samp{frame 0}).
70b88761
RP
4373
4374However, _GDBN__ must deduce where registers are saved, from the machine
4375code generated by your compiler. If some registers are not saved, or if
4376_GDBN__ is unable to locate the saved registers, the selected stack
4377frame will make no difference.
4378
d8a68b28 4379_if__(_AMD29K__)
03a77779 4380@table @code
d8a68b28
JG
4381@item set rstack_high_address @var{address}
4382@kindex set rstack_high_address
03a77779
RP
4383@cindex AMD 29K register stack
4384@cindex register stack, AMD29K
4385On AMD 29000 family processors, registers are saved in a separate
4386``register stack''. There is no way for _GDBN__ to determine the extent
4387of this stack. Normally, _GDBN__ just assumes that the stack is ``large
4388enough''. This may result in _GDBN__ referencing memory locations that
4389don't exist. If necessary, you can get around this problem by
4390specifying the ending address of the register stack with the @code{set
4391rstack_high_address} command. The argument should be an address, which
4392you will probably want to precede with @samp{0x} to specify in
4393hexadecimal.
d8a68b28
JG
4394
4395@item show rstack_high_address
4396@kindex show rstack_high_address
03a77779
RP
4397Display the current limit of the register stack, on AMD 29000 family
4398processors.
4399@end table
d8a68b28
JG
4400_fi__(_AMD29K__)
4401
4eb4cf57
RP
4402_if__(_GENERIC__ || !_H8__)
4403@node Floating Point Hardware
70b88761
RP
4404@section Floating Point Hardware
4405@cindex floating point
1041a570 4406
70b88761
RP
4407Depending on the host machine architecture, _GDBN__ may be able to give
4408you more information about the status of the floating point hardware.
4409
4410@table @code
4411@item info float
4412@kindex info float
4413If available, provides hardware-dependent information about the floating
4414point unit. The exact contents and layout vary depending on the
4415floating point chip.
4416@end table
4417@c FIXME: this is a cop-out. Try to get examples, explanations. Only
e251e767
RP
4418@c FIXME...supported currently on arm's and 386's. Mark properly with
4419@c FIXME... m4 macros to isolate general statements from hardware-dep,
70b88761 4420@c FIXME... at that point.
4eb4cf57 4421_fi__(_GENERIC__ || !_H8__)
70b88761 4422
4eb4cf57
RP
4423_if__(!_CONLY__)
4424@node Languages
c2bbbb22
RP
4425@chapter Using _GDBN__ with Different Languages
4426@cindex languages
4427
4428Although programming languages generally have common aspects, they are
4429rarely expressed in the same manner. For instance, in ANSI C,
4430dereferencing a pointer @code{p} is accomplished by @code{*p}, but in
4431Modula-2, it is accomplished by @code{p^}. Values can also be
4432represented (and displayed) differently. Hex numbers in C are written
4433like @samp{0x1ae}, while in Modula-2 they appear as @samp{1AEH}.
4434
4435@cindex working language
4436Language-specific information is built into _GDBN__ for some languages,
29a2b744 4437allowing you to express operations like the above in your program's
c2bbbb22 4438native language, and allowing _GDBN__ to output values in a manner
29a2b744 4439consistent with the syntax of your program's native language. The
c2bbbb22
RP
4440language you use to build expressions, called the @dfn{working
4441language}, can be selected manually, or _GDBN__ can set it
4442automatically.
4443
4444@menu
4445* Setting:: Switching between source languages
4446* Show:: Displaying the language
4447* Checks:: Type and Range checks
4448* Support:: Supported languages
4449@end menu
4450
4eb4cf57 4451@node Setting
c2bbbb22
RP
4452@section Switching between source languages
4453
4454There are two ways to control the working language---either have _GDBN__
4455set it automatically, or select it manually yourself. You can use the
4456@code{set language} command for either purpose. On startup, _GDBN__
4457defaults to setting the language automatically.
4458
4459@menu
4460* Manually:: Setting the working language manually
4461* Automatically:: Having _GDBN__ infer the source language
4462@end menu
4463
4eb4cf57 4464@node Manually
c2bbbb22
RP
4465@subsection Setting the working language
4466
4467@kindex set language
4468To set the language, issue the command @samp{set language @var{lang}},
c338a2fd
RP
4469where @var{lang} is the name of a language: @code{c} or @code{modula-2}.
4470For a list of the supported languages, type @samp{set language}.
c2bbbb22
RP
4471
4472Setting the language manually prevents _GDBN__ from updating the working
4473language automatically. This can lead to confusion if you try
4474to debug a program when the working language is not the same as the
4475source language, when an expression is acceptable to both
4476languages---but means different things. For instance, if the current
4477source file were written in C, and _GDBN__ was parsing Modula-2, a
4478command such as:
4479
4480@example
4481print a = b + c
4482@end example
4483
4484@noindent
4485might not have the effect you intended. In C, this means to add
4486@code{b} and @code{c} and place the result in @code{a}. The result
4487printed would be the value of @code{a}. In Modula-2, this means to compare
4488@code{a} to the result of @code{b+c}, yielding a @code{BOOLEAN} value.
4489
4490If you allow _GDBN__ to set the language automatically, then
4491you can count on expressions evaluating the same way in your debugging
4492session and in your program.
4493
4eb4cf57 4494@node Automatically
c2bbbb22
RP
4495@subsection Having _GDBN__ infer the source language
4496
4497To have _GDBN__ set the working language automatically, use @samp{set
4498language local} or @samp{set language auto}. _GDBN__ then infers the
4499language that a program was written in by looking at the name of its
4500source files, and examining their extensions:
4501
4502@table @file
4503@item *.mod
4504Modula-2 source file
4505
4506@item *.c
5a2c1d85
RP
4507C source file
4508
4509@item *.C
c2bbbb22 4510@itemx *.cc
5a2c1d85 4511C++ source file
c2bbbb22
RP
4512@end table
4513
4514This information is recorded for each function or procedure in a source
4515file. When your program stops in a frame (usually by encountering a
4516breakpoint), _GDBN__ sets the working language to the language recorded
4517for the function in that frame. If the language for a frame is unknown
4518(that is, if the function or block corresponding to the frame was
4519defined in a source file that does not have a recognized extension), the
4520current working language is not changed, and _GDBN__ issues a warning.
4521
4522This may not seem necessary for most programs, which are written
4523entirely in one source language. However, program modules and libraries
4524written in one source language can be used by a main program written in
4525a different source language. Using @samp{set language auto} in this
4526case frees you from having to set the working language manually.
4527
4eb4cf57 4528@node Show
c2bbbb22
RP
4529@section Displaying the language
4530
4531The following commands will help you find out which language is the
4532working language, and also what language source files were written in.
4533
4534@kindex show language
4535@kindex info frame
4536@kindex info source
4537@table @code
4538@item show language
4539Display the current working language. This is the
4540language you can use with commands such as @code{print} to
29a2b744 4541build and compute expressions that may involve variables in your program.
c2bbbb22
RP
4542
4543@item info frame
1041a570 4544Among the other information listed here (@pxref{Frame Info, ,Information
c2bbbb22
RP
4545about a Frame}) is the source language for this frame. This is the
4546language that will become the working language if you ever use an
4547identifier that is in this frame.
4548
4549@item info source
1041a570 4550Among the other information listed here (@pxref{Symbols, ,Examining the
c2bbbb22 4551Symbol Table}) is the source language of this source file.
c2bbbb22
RP
4552@end table
4553
4eb4cf57 4554@node Checks
c2bbbb22
RP
4555@section Type and range Checking
4556
4557@quotation
4558@emph{Warning:} In this release, the _GDBN__ commands for type and range
4559checking are included, but they do not yet have any effect. This
4560section documents the intended facilities.
4561@end quotation
4562@c FIXME remove warning when type/range code added
4563
4564Some languages are designed to guard you against making seemingly common
4565errors through a series of compile- and run-time checks. These include
4566checking the type of arguments to functions and operators, and making
4567sure mathematical overflows are caught at run time. Checks such as
4568these help to ensure a program's correctness once it has been compiled
4569by eliminating type mismatches, and providing active checks for range
29a2b744 4570errors when your program is running.
c2bbbb22 4571
1041a570
RP
4572_GDBN__ can check for conditions like the above if you wish.
4573Although _GDBN__ will not check the statements in your program, it
4574can check expressions entered directly into _GDBN__ for evaluation via
4575the @code{print} command, for example. As with the working language,
c2bbbb22 4576_GDBN__ can also decide whether or not to check automatically based on
1041a570
RP
4577your program's source language. @xref{Support, ,Supported Languages},
4578for the default settings of supported languages.
c2bbbb22
RP
4579
4580@menu
4581* Type Checking:: An overview of type checking
4582* Range Checking:: An overview of range checking
4583@end menu
4584
4585@cindex type checking
4586@cindex checks, type
4eb4cf57 4587@node Type Checking
c2bbbb22
RP
4588@subsection An overview of type checking
4589
4590Some languages, such as Modula-2, are strongly typed, meaning that the
4591arguments to operators and functions have to be of the correct type,
4592otherwise an error occurs. These checks prevent type mismatch
4593errors from ever causing any run-time problems. For example,
4594
4595@example
45961 + 2 @result{} 3
1041a570 4597@exdent but
c2bbbb22
RP
4598@error{} 1 + 2.3
4599@end example
4600
4601The second example fails because the @code{CARDINAL} 1 is not
4602type-compatible with the @code{REAL} 2.3.
4603
4604For expressions you use in _GDBN__ commands, you can tell the _GDBN__
4605type checker to skip checking; to treat any mismatches as errors and
4606abandon the expression; or only issue warnings when type mismatches
4607occur, but evaluate the expression anyway. When you choose the last of
4608these, _GDBN__ evaluates expressions like the second example above, but
4609also issues a warning.
4610
4611Even though you may turn type checking off, other type-based reasons may
4612prevent _GDBN__ from evaluating an expression. For instance, _GDBN__ does not
4613know how to add an @code{int} and a @code{struct foo}. These particular
4614type errors have nothing to do with the language in use, and usually
4615arise from expressions, such as the one described above, which make
4616little sense to evaluate anyway.
4617
4618Each language defines to what degree it is strict about type. For
4619instance, both Modula-2 and C require the arguments to arithmetical
4620operators to be numbers. In C, enumerated types and pointers can be
4621represented as numbers, so that they are valid arguments to mathematical
1041a570 4622operators. @xref{Support, ,Supported Languages}, for further
c2bbbb22
RP
4623details on specific languages.
4624
4625_GDBN__ provides some additional commands for controlling the type checker:
4626
4627@kindex set check
4628@kindex set check type
4629@kindex show check type
4630@table @code
4631@item set check type auto
e251e767 4632Set type checking on or off based on the current working language.
1041a570 4633@xref{Support, ,Supported Languages}, for the default settings for
c2bbbb22
RP
4634each language.
4635
4636@item set check type on
4637@itemx set check type off
4638Set type checking on or off, overriding the default setting for the
4639current working language. Issue a warning if the setting does not
4640match the language's default. If any type mismatches occur in
4641evaluating an expression while typechecking is on, _GDBN__ prints a
4642message and aborts evaluation of the expression.
4643
4644@item set check type warn
4645Cause the type checker to issue warnings, but to always attempt to
4646evaluate the expression. Evaluating the expression may still
4647be impossible for other reasons. For example, _GDBN__ cannot add
4648numbers and structures.
4649
4650@item show type
e251e767 4651Show the current setting of the type checker, and whether or not _GDBN__ is
c2bbbb22
RP
4652setting it automatically.
4653@end table
4654
4655@cindex range checking
4656@cindex checks, range
4eb4cf57 4657@node Range Checking
c2bbbb22
RP
4658@subsection An overview of Range Checking
4659
4660In some languages (such as Modula-2), it is an error to exceed the
4661bounds of a type; this is enforced with run-time checks. Such range
4662checking is meant to ensure program correctness by making sure
4663computations do not overflow, or indices on an array element access do
4664not exceed the bounds of the array.
4665
4666For expressions you use in _GDBN__ commands, you can tell _GDBN__ to
4667ignore range errors; to always treat them as errors and abandon the
4668expression; or to issue warnings when a range error occurs but evaluate
4669the expression anyway.
4670
4671A range error can result from numerical overflow, from exceeding an
4672array index bound, or when you type in a constant that is not a member
4673of any type. Some languages, however, do not treat overflows as an
4674error. In many implementations of C, mathematical overflow causes the
4675result to ``wrap around'' to lower values---for example, if @var{m} is
4676the largest integer value, and @var{s} is the smallest, then
1041a570 4677
c2bbbb22
RP
4678@example
4679@var{m} + 1 @result{} @var{s}
4680@end example
4681
4682This, too, is specific to individual languages, and in some cases
1041a570 4683specific to individual compilers or machines. @xref{Support, ,
c2bbbb22
RP
4684Supported Languages}, for further details on specific languages.
4685
4686_GDBN__ provides some additional commands for controlling the range checker:
4687
4688@kindex set check
4689@kindex set check range
4690@kindex show check range
4691@table @code
4692@item set check range auto
e251e767 4693Set range checking on or off based on the current working language.
1041a570 4694@xref{Support, ,Supported Languages}, for the default settings for
c2bbbb22
RP
4695each language.
4696
4697@item set check range on
4698@itemx set check range off
4699Set range checking on or off, overriding the default setting for the
4700current working language. A warning is issued if the setting does not
4701match the language's default. If a range error occurs, then a message
4702is printed and evaluation of the expression is aborted.
4703
4704@item set check range warn
4705Output messages when the _GDBN__ range checker detects a range error,
4706but attempt to evaluate the expression anyway. Evaluating the
4707expression may still be impossible for other reasons, such as accessing
4708memory that the process does not own (a typical example from many UNIX
4709systems).
4710
4711@item show range
e251e767 4712Show the current setting of the range checker, and whether or not it is
c2bbbb22
RP
4713being set automatically by _GDBN__.
4714@end table
4715
4eb4cf57 4716@node Support
c2bbbb22
RP
4717@section Supported Languages
4718
5a2c1d85 4719_GDBN__ 4 supports C, C++, and Modula-2. Some _GDBN__
1041a570
RP
4720features may be used in expressions regardless of the language you
4721use: the _GDBN__ @code{@@} and @code{::} operators, and the
4722@samp{@{type@}addr} construct (@pxref{Expressions, ,Expressions}) can be
4723used with the constructs of any of the supported languages.
c2bbbb22
RP
4724
4725The following sections detail to what degree each of these
4726source languages is supported by _GDBN__. These sections are
4727not meant to be language tutorials or references, but serve only as a
4728reference guide to what the _GDBN__ expression parser will accept, and
4729what input and output formats should look like for different languages.
4730There are many good books written on each of these languages; please
4731look to these for a language reference or tutorial.
4732
4733@menu
4734* C:: C and C++
4735* Modula-2:: Modula-2
4736@end menu
4737
4eb4cf57 4738@node C
c2bbbb22
RP
4739@subsection C and C++
4740@cindex C and C++
c2bbbb22 4741@cindex expressions in C or C++
0f153e74 4742
5a2c1d85
RP
4743Since C and C++ are so closely related, many features of _GDBN__ apply
4744to both languages. Whenever this is the case, we discuss both languages
4745together.
b80282d5
RP
4746
4747@cindex C++
4748@kindex g++
4749@cindex GNU C++
c2bbbb22
RP
4750The C++ debugging facilities are jointly implemented by the GNU C++
4751compiler and _GDBN__. Therefore, to debug your C++ code effectively,
4752you must compile your C++ programs with the GNU C++ compiler,
4753@code{g++}.
0f153e74
RP
4754_fi__(!_CONLY__)
4755_if__(_CONLY__)
4756@node C
4757@chapter C Language Support
4758@cindex C language
4759@cindex expressions in C
4760
4761Information specific to the C language is built into _GDBN__ so that you
4762can use C expressions while degugging. This also permits _GDBN__ to
4763output values in a manner consistent with C conventions.
c2bbbb22 4764
0f153e74
RP
4765@menu
4766* C Operators:: C Operators
4767* C Constants:: C Constants
4768* Debugging C:: _GDBN__ and C
4769@end menu
4770_fi__(_CONLY__)
4771_if__(!_CONLY__)
b80282d5 4772@menu
c2bbbb22
RP
4773* C Operators:: C and C++ Operators
4774* C Constants:: C and C++ Constants
4775* Cplusplus expressions:: C++ Expressions
4776* C Defaults:: Default settings for C and C++
4777* C Checks:: C and C++ Type and Range Checks
4778* Debugging C:: _GDBN__ and C
4779* Debugging C plus plus:: Special features for C++
b80282d5 4780@end menu
0f153e74 4781_fi__(!_CONLY__)
b80282d5 4782
0f153e74 4783_if__(!_CONLY__)
c2bbbb22 4784@cindex C and C++ operators
4eb4cf57 4785@node C Operators
c2bbbb22 4786@subsubsection C and C++ Operators
4eb4cf57
RP
4787_fi__(!_CONLY__)
4788_if__(_CONLY__)
0f153e74
RP
4789@cindex C operators
4790@node C Operators
4791@section C Operators
4eb4cf57 4792_fi__(_CONLY__)
c2bbbb22
RP
4793
4794Operators must be defined on values of specific types. For instance,
4795@code{+} is defined on numbers, but not on structures. Operators are
0f153e74
RP
4796often defined on groups of types.
4797
4798_if__(!_CONLY__)
4799For the purposes of C and C++, the following definitions hold:
4800_fi__(!_CONLY__)
c2bbbb22
RP
4801
4802@itemize @bullet
e251e767 4803@item
c2bbbb22
RP
4804@emph{Integral types} include @code{int} with any of its storage-class
4805specifiers, @code{char}, and @code{enum}s.
4806
4807@item
4808@emph{Floating-point types} include @code{float} and @code{double}.
4809
4810@item
4811@emph{Pointer types} include all types defined as @code{(@var{type}
4812*)}.
4813
e251e767 4814@item
c2bbbb22 4815@emph{Scalar types} include all of the above.
c2bbbb22
RP
4816@end itemize
4817
4818@noindent
4819The following operators are supported. They are listed here
4820in order of increasing precedence:
4821
4822@table @code
1041a570 4823_0__@item ,
c2bbbb22
RP
4824The comma or sequencing operator. Expressions in a comma-separated list
4825are evaluated from left to right, with the result of the entire
4826expression being the last expression evaluated.
4827
4828@item =
4829Assignment. The value of an assignment expression is the value
4830assigned. Defined on scalar types.
4831
4832@item @var{op}=
1041a570
RP
4833Used in an expression of the form @w{@code{@var{a} @var{op}= @var{b}}},
4834and translated to @w{@code{@var{a} = @var{a op b}}}.
4835@w{@code{@var{op}=}} and @code{=} have the same precendence.
4836@var{op} is any one of the operators @code{|}, @code{^}, @code{&},
4837@code{<<}, @code{>>}, @code{+}, @code{-}, @code{*}, @code{/}, @code{%}.
c2bbbb22
RP
4838
4839@item ?:
4840The ternary operator. @code{@var{a} ? @var{b} : @var{c}} can be thought
4841of as: if @var{a} then @var{b} else @var{c}. @var{a} should be of an
4842integral type.
4843
4844@item ||
1041a570 4845Logical @sc{or}. Defined on integral types.
c2bbbb22
RP
4846
4847@item &&
1041a570 4848Logical @sc{and}. Defined on integral types.
c2bbbb22
RP
4849
4850@item |
1041a570 4851Bitwise @sc{or}. Defined on integral types.
c2bbbb22
RP
4852
4853@item ^
1041a570 4854Bitwise exclusive-@sc{or}. Defined on integral types.
c2bbbb22
RP
4855
4856@item &
1041a570 4857Bitwise @sc{and}. Defined on integral types.
c2bbbb22
RP
4858
4859@item ==@r{, }!=
4860Equality and inequality. Defined on scalar types. The value of these
4861expressions is 0 for false and non-zero for true.
4862
4863@item <@r{, }>@r{, }<=@r{, }>=
4864Less than, greater than, less than or equal, greater than or equal.
4865Defined on scalar types. The value of these expressions is 0 for false
4866and non-zero for true.
4867
4868@item <<@r{, }>>
0f153e74 4869left shift, and right shift. Defined on integral types._1__
c2bbbb22 4870
e251e767 4871@item @@
1041a570 4872The _GDBN__ ``artificial array'' operator (@pxref{Expressions, ,Expressions}).
c2bbbb22
RP
4873
4874@item +@r{, }-
4875Addition and subtraction. Defined on integral types, floating-point types and
e251e767 4876pointer types.
c2bbbb22
RP
4877
4878@item *@r{, }/@r{, }%
4879Multiplication, division, and modulus. Multiplication and division are
4880defined on integral and floating-point types. Modulus is defined on
4881integral types.
4882
4883@item ++@r{, }--
4884Increment and decrement. When appearing before a variable, the
4885operation is performed before the variable is used in an expression;
4886when appearing after it, the variable's value is used before the
4887operation takes place.
4888
4889@item *
4890Pointer dereferencing. Defined on pointer types. Same precedence as
4891@code{++}.
4892
4893@item &
4894Address operator. Defined on variables. Same precedence as @code{++}.
4895
0f153e74 4896_if__(!_CONLY__)
6ca72cc6
RP
4897For debugging C++, _GDBN__ implements a use of @samp{&} beyond what's
4898allowed in the C++ language itself: you can use @samp{&(&@var{ref})}
4899(or, if you prefer, simply @samp{&&@var{ref}} to examine the address
4900where a C++ reference variable (declared with @samp{&@var{ref}}) is
4901stored.
0f153e74 4902_fi__(!_CONLY__)
6ca72cc6 4903
c2bbbb22
RP
4904@item -
4905Negative. Defined on integral and floating-point types. Same
4906precedence as @code{++}.
4907
4908@item !
4909Logical negation. Defined on integral types. Same precedence as
4910@code{++}.
4911
4912@item ~
4913Bitwise complement operator. Defined on integral types. Same precedence as
4914@code{++}.
4915
0f153e74 4916_0__
c2bbbb22
RP
4917@item .@r{, }->
4918Structure member, and pointer-to-structure member. For convenience,
4919_GDBN__ regards the two as equivalent, choosing whether to dereference a
e251e767 4920pointer based on the stored type information.
c2bbbb22
RP
4921Defined on @code{struct}s and @code{union}s.
4922
4923@item []
4924Array indexing. @code{@var{a}[@var{i}]} is defined as
4925@code{*(@var{a}+@var{i})}. Same precedence as @code{->}.
4926
4927@item ()
0f153e74 4928Function parameter list. Same precedence as @code{->}._1__
c2bbbb22 4929
0f153e74 4930_if__(!_CONLY__)
c2bbbb22
RP
4931@item ::
4932C++ scope resolution operator. Defined on
4933@code{struct}, @code{union}, and @code{class} types.
0f153e74 4934_fi__(!_CONLY__)
c2bbbb22
RP
4935
4936@item ::
0f153e74
RP
4937The _GDBN__ scope operator (@pxref{Expressions, ,Expressions}).
4938_if__(!_CONLY__)
4939Same precedence as @code{::}, above.
4940_fi__(!_CONLY__)
c2bbbb22
RP
4941@end table
4942
0f153e74 4943_if__(!_CONLY__)
c2bbbb22 4944@cindex C and C++ constants
4eb4cf57 4945@node C Constants
c2bbbb22 4946@subsubsection C and C++ Constants
0f153e74
RP
4947
4948_GDBN__ allows you to express the constants of C and C++ in the
4949following ways:
4eb4cf57
RP
4950_fi__(!_CONLY__)
4951_if__(_CONLY__)
0f153e74
RP
4952@cindex C constants
4953@node C Constants
4954@section C Constants
c2bbbb22 4955
0f153e74 4956_GDBN__ allows you to express the constants of C in the
c2bbbb22 4957following ways:
0f153e74 4958_fi__(_CONLY__)
c2bbbb22
RP
4959
4960@itemize @bullet
c2bbbb22
RP
4961@item
4962Integer constants are a sequence of digits. Octal constants are
4963specified by a leading @samp{0} (ie. zero), and hexadecimal constants by
1041a570 4964a leading @samp{0x} or @samp{0X}. Constants may also end with a letter
c2bbbb22
RP
4965@samp{l}, specifying that the constant should be treated as a
4966@code{long} value.
4967
4968@item
4969Floating point constants are a sequence of digits, followed by a decimal
4970point, followed by a sequence of digits, and optionally followed by an
4971exponent. An exponent is of the form:
4972@samp{@w{e@r{[[}+@r{]|}-@r{]}@var{nnn}}}, where @var{nnn} is another
4973sequence of digits. The @samp{+} is optional for positive exponents.
4974
4975@item
4976Enumerated constants consist of enumerated identifiers, or their
4977integral equivalents.
4978
4979@item
4980Character constants are a single character surrounded by single quotes
4981(@code{'}), or a number---the ordinal value of the corresponding character
4982(usually its @sc{ASCII} value). Within quotes, the single character may
4983be represented by a letter or by @dfn{escape sequences}, which are of
4984the form @samp{\@var{nnn}}, where @var{nnn} is the octal representation
4985of the character's ordinal value; or of the form @samp{\@var{x}}, where
4986@samp{@var{x}} is a predefined special character---for example,
4987@samp{\n} for newline.
4988
4989@item
4990String constants are a sequence of character constants surrounded
4991by double quotes (@code{"}).
4992
4993@item
4994Pointer constants are an integral value.
c2bbbb22
RP
4995@end itemize
4996
4eb4cf57 4997_if__(!_CONLY__)
0f153e74 4998@node Cplusplus expressions
c2bbbb22 4999@subsubsection C++ Expressions
b80282d5
RP
5000
5001@cindex expressions in C++
b1385986
RP
5002_GDBN__'s expression handling has a number of extensions to
5003interpret a significant subset of C++ expressions.
5004
5005@cindex C++ support, not in @sc{coff}
5006@cindex @sc{coff} versus C++
5007@cindex C++ and object formats
5008@cindex object formats and C++
5009@cindex a.out and C++
5010@cindex @sc{ecoff} and C++
5011@cindex @sc{xcoff} and C++
5012@cindex @sc{elf}/stabs and C++
5013@cindex @sc{elf}/@sc{dwarf} and C++
5014@quotation
5015@emph{Warning:} Most of these extensions depend on the use of additional
5016debugging information in the symbol table, and thus require a rich,
5017extendable object code format. In particular, if your system uses
5018a.out, MIPS @sc{ecoff}, RS/6000 @sc{xcoff}, or Sun @sc{elf} with stabs
5019extensions to the symbol table, these facilities are all available.
5020Where the object code format is standard @sc{coff}, on the other hand,
5021most of the C++ support in _GDBN__ will @emph{not} work, nor can it.
5022For the standard SVr4 debugging format, @sc{dwarf} in @sc{elf}, the
5023standard is still evolving, so the C++ support in _GDBN__ is still
5024fragile; when this debugging format stabilizes, however, C++ support
5025will also be available on systems that use it.
5026@end quotation
b80282d5
RP
5027
5028@enumerate
5029
5030@cindex member functions
e251e767 5031@item
b80282d5 5032Member function calls are allowed; you can use expressions like
1041a570 5033
b80282d5
RP
5034@example
5035count = aml->GetOriginal(x, y)
5036@end example
5037
5038@kindex this
5039@cindex namespace in C++
e251e767 5040@item
b80282d5
RP
5041While a member function is active (in the selected stack frame), your
5042expressions have the same namespace available as the member function;
5043that is, _GDBN__ allows implicit references to the class instance
5044pointer @code{this} following the same rules as C++.
5045
5046@cindex call overloaded functions
5047@cindex type conversions in C++
e251e767 5048@item
b80282d5
RP
5049You can call overloaded functions; _GDBN__ will resolve the function
5050call to the right definition, with one restriction---you must use
5051arguments of the type required by the function that you want to call.
5052_GDBN__ will not perform conversions requiring constructors or
5053user-defined type operators.
5054
5055@cindex reference declarations
5056@item
5057_GDBN__ understands variables declared as C++ references; you can use them in
5058expressions just as you do in C++ source---they are automatically
e251e767 5059dereferenced.
b80282d5
RP
5060
5061In the parameter list shown when _GDBN__ displays a frame, the values of
5062reference variables are not displayed (unlike other variables); this
5063avoids clutter, since references are often used for large structures.
5064The @emph{address} of a reference variable is always shown, unless
1041a570 5065you have specified @samp{set print address off}.
b80282d5
RP
5066
5067@item
5068_GDBN__ supports the C++ name resolution operator @code{::}---your
c2bbbb22
RP
5069expressions can use it just as expressions in your program do. Since
5070one scope may be defined in another, you can use @code{::} repeatedly if
5071necessary, for example in an expression like
5072@samp{@var{scope1}::@var{scope2}::@var{name}}. _GDBN__ also allows
5073resolving name scope by reference to source files, in both C and C++
1041a570 5074debugging (@pxref{Variables, ,Program Variables}).
b80282d5
RP
5075@end enumerate
5076
4eb4cf57 5077@node C Defaults
c2bbbb22
RP
5078@subsubsection C and C++ Defaults
5079@cindex C and C++ defaults
5080
e251e767
RP
5081If you allow _GDBN__ to set type and range checking automatically, they
5082both default to @code{off} whenever the working language changes to
5a2c1d85 5083C or C++. This happens regardless of whether you, or _GDBN__,
c2bbbb22
RP
5084selected the working language.
5085
5086If you allow _GDBN__ to set the language automatically, it sets the
5a2c1d85
RP
5087working language to C or C++ on entering code compiled from a source file
5088whose name ends with @file{.c}, @file{.C}, or @file{.cc}.
1041a570 5089@xref{Automatically, ,Having _GDBN__ infer the source language}, for
c2bbbb22
RP
5090further details.
5091
4eb4cf57 5092@node C Checks
c2bbbb22
RP
5093@subsubsection C and C++ Type and Range Checks
5094@cindex C and C++ checks
5095
5096@quotation
5097@emph{Warning:} in this release, _GDBN__ does not yet perform type or
5098range checking.
5099@end quotation
5100@c FIXME remove warning when type/range checks added
5101
5102By default, when _GDBN__ parses C or C++ expressions, type checking
5103is not used. However, if you turn type checking on, _GDBN__ will
5104consider two variables type equivalent if:
5105
5106@itemize @bullet
5107@item
5108The two variables are structured and have the same structure, union, or
5109enumerated tag.
5110
e251e767 5111@item
c2bbbb22
RP
5112Two two variables have the same type name, or types that have been
5113declared equivalent through @code{typedef}.
5114
5115@ignore
5116@c leaving this out because neither J Gilmore nor R Pesch understand it.
5117@c FIXME--beers?
5118@item
5119The two @code{struct}, @code{union}, or @code{enum} variables are
5120declared in the same declaration. (Note: this may not be true for all C
5121compilers.)
5122@end ignore
c2bbbb22
RP
5123@end itemize
5124
5125Range checking, if turned on, is done on mathematical operations. Array
5126indices are not checked, since they are often used to index a pointer
5127that is not itself an array.
0f153e74 5128_fi__(!_CONLY__)
c2bbbb22 5129
4eb4cf57
RP
5130@node Debugging C
5131_if__(!_CONLY__)
c2bbbb22 5132@subsubsection _GDBN__ and C
4eb4cf57
RP
5133_fi__(!_CONLY__)
5134_if__(_CONLY__)
5135@section _GDBN__ and C
5136_fi__(_CONLY__)
c2bbbb22
RP
5137
5138The @code{set print union} and @code{show print union} commands apply to
5139the @code{union} type. When set to @samp{on}, any @code{union} that is
5140inside a @code{struct} or @code{class} will also be printed.
5141Otherwise, it will appear as @samp{@{...@}}.
5142
5143The @code{@@} operator aids in the debugging of dynamic arrays, formed
1041a570 5144with pointers and a memory allocation function. (@pxref{Expressions, ,Expressions})
c2bbbb22 5145
0f153e74 5146_if__(!_CONLY__)
4eb4cf57
RP
5147@node Debugging C plus plus
5148_if__(!_CONLY__)
6f3ec223 5149@subsubsection _GDBN__ Features for C++
4eb4cf57
RP
5150_fi__(!_CONLY__)
5151_if__(_CONLY__)
5152@section _GDBN__ Features for C++
5153_fi__(_CONLY__)
b80282d5
RP
5154
5155@cindex commands for C++
5156Some _GDBN__ commands are particularly useful with C++, and some are
5157designed specifically for use with C++. Here is a summary:
5158
5159@table @code
5160@cindex break in overloaded functions
5161@item @r{breakpoint menus}
5162When you want a breakpoint in a function whose name is overloaded,
5163_GDBN__'s breakpoint menus help you specify which function definition
5164you want. @xref{Breakpoint Menus}.
5165
5166@cindex overloading in C++
5167@item rbreak @var{regex}
5168Setting breakpoints using regular expressions is helpful for setting
5169breakpoints on overloaded functions that are not members of any special
e251e767 5170classes.
29a2b744 5171@xref{Set Breaks, ,Setting Breakpoints}.
b80282d5
RP
5172
5173@cindex C++ exception handling
5174@item catch @var{exceptions}
5175@itemx info catch
29a2b744 5176Debug C++ exception handling using these commands. @xref{Exception
1041a570 5177Handling, ,Breakpoints and Exceptions}.
b80282d5 5178
e251e767 5179@cindex inheritance
b80282d5
RP
5180@item ptype @var{typename}
5181Print inheritance relationships as well as other information for type
e251e767 5182@var{typename}.
1041a570 5183@xref{Symbols, ,Examining the Symbol Table}.
b80282d5
RP
5184
5185@cindex C++ symbol display
5186@item set print demangle
5187@itemx show print demangle
5188@itemx set print asm-demangle
5189@itemx show print asm-demangle
5190Control whether C++ symbols display in their source form, both when
5191displaying code as C++ source and when displaying disassemblies.
1041a570 5192@xref{Print Settings, ,Print Settings}.
b80282d5
RP
5193
5194@item set print object
5195@itemx show print object
e251e767 5196Choose whether to print derived (actual) or declared types of objects.
1041a570 5197@xref{Print Settings, ,Print Settings}.
b80282d5
RP
5198
5199@item set print vtbl
5200@itemx show print vtbl
5201Control the format for printing virtual function tables.
1041a570 5202@xref{Print Settings, ,Print Settings}.
6f3ec223
RP
5203
5204@item @r{Overloaded symbol names}
5205You can specify a particular definition of an overloaded symbol, using
5206the same notation that's used to declare such symbols in C++: type
5207@code{@var{symbol}(@var{types})} rather than just @var{symbol}. You can
5208also use _GDBN__'s command-line word completion facilities to list the
5209available choices, or to finish the type list for you.
5210@xref{Completion,, Command Completion}, for details on how to do this.
b80282d5
RP
5211@end table
5212
4eb4cf57 5213@node Modula-2
c2bbbb22
RP
5214@subsection Modula-2
5215@cindex Modula-2
5216
5217The extensions made to _GDBN__ to support Modula-2 support output
5218from the GNU Modula-2 compiler (which is currently being developed).
5219Other Modula-2 compilers are not currently supported, and attempting to
5220debug executables produced by them will most likely result in an error
5221as _GDBN__ reads in the executable's symbol table.
5222
5223@cindex expressions in Modula-2
5224@menu
5225* M2 Operators:: Built-in operators
29a2b744 5226* Built-In Func/Proc:: Built-in Functions and Procedures
c2bbbb22
RP
5227* M2 Constants:: Modula-2 Constants
5228* M2 Defaults:: Default settings for Modula-2
5229* Deviations:: Deviations from standard Modula-2
5230* M2 Checks:: Modula-2 Type and Range Checks
5231* M2 Scope:: The scope operators @code{::} and @code{.}
5232* GDB/M2:: _GDBN__ and Modula-2
5233@end menu
5234
4eb4cf57 5235@node M2 Operators
c2bbbb22
RP
5236@subsubsection Operators
5237@cindex Modula-2 operators
5238
5239Operators must be defined on values of specific types. For instance,
5240@code{+} is defined on numbers, but not on structures. Operators are
5241often defined on groups of types. For the purposes of Modula-2, the
5242following definitions hold:
5243
5244@itemize @bullet
5245
5246@item
5247@emph{Integral types} consist of @code{INTEGER}, @code{CARDINAL}, and
5248their subranges.
5249
5250@item
5251@emph{Character types} consist of @code{CHAR} and its subranges.
5252
5253@item
5254@emph{Floating-point types} consist of @code{REAL}.
5255
5256@item
5257@emph{Pointer types} consist of anything declared as @code{POINTER TO
5258@var{type}}.
5259
5260@item
5261@emph{Scalar types} consist of all of the above.
5262
5263@item
5264@emph{Set types} consist of @code{SET}s and @code{BITSET}s.
5265
5266@item
5267@emph{Boolean types} consist of @code{BOOLEAN}.
c2bbbb22
RP
5268@end itemize
5269
5270@noindent
5271The following operators are supported, and appear in order of
5272increasing precedence:
5273
5274@table @code
c2bbbb22
RP
5275@item ,
5276Function argument or array index separator.
1041a570 5277_0__
c2bbbb22
RP
5278@item :=
5279Assignment. The value of @var{var} @code{:=} @var{value} is
5280@var{value}.
5281
5282@item <@r{, }>
5283Less than, greater than on integral, floating-point, or enumerated
5284types.
5285
5286@item <=@r{, }>=
5287Less than, greater than, less than or equal to, greater than or equal to
5288on integral, floating-point and enumerated types, or set inclusion on
5289set types. Same precedence as @code{<}.
5290
5291@item =@r{, }<>@r{, }#
5292Equality and two ways of expressing inequality, valid on scalar types.
5293Same precedence as @code{<}. In _GDBN__ scripts, only @code{<>} is
5294available for inequality, since @code{#} conflicts with the script
5295comment character.
5296
5297@item IN
5298Set membership. Defined on set types and the types of their members.
5299Same precedence as @code{<}.
5300
5301@item OR
5302Boolean disjunction. Defined on boolean types.
5303
5304@item AND@r{, }&
5305Boolean conjuction. Defined on boolean types.
5306
5307@item @@
1041a570 5308The _GDBN__ ``artificial array'' operator (@pxref{Expressions, ,Expressions}).
c2bbbb22
RP
5309
5310@item +@r{, }-
5311Addition and subtraction on integral and floating-point types, or union
5312and difference on set types.
5313
5314@item *
5315Multiplication on integral and floating-point types, or set intersection
5316on set types.
5317
5318@item /
5319Division on floating-point types, or symmetric set difference on set
5320types. Same precedence as @code{*}.
5321
5322@item DIV@r{, }MOD
5323Integer division and remainder. Defined on integral types. Same
5324precedence as @code{*}.
5325
5326@item -
5327Negative. Defined on @code{INTEGER}s and @code{REAL}s.
5328
5329@item ^
e251e767 5330Pointer dereferencing. Defined on pointer types.
c2bbbb22
RP
5331
5332@item NOT
5333Boolean negation. Defined on boolean types. Same precedence as
5334@code{^}.
5335
5336@item .
5337@code{RECORD} field selector. Defined on @code{RECORD}s. Same
5338precedence as @code{^}.
5339
5340@item []
5341Array indexing. Defined on @code{ARRAY}s. Same precedence as @code{^}.
5342
5343@item ()
5344Procedure argument list. Defined on @code{PROCEDURE}s. Same precedence
5345as @code{^}.
5346
5347@item ::@r{, }.
5348_GDBN__ and Modula-2 scope operators.
c2bbbb22
RP
5349@end table
5350
5351@quotation
5352@emph{Warning:} Sets and their operations are not yet supported, so _GDBN__
5353will treat the use of the operator @code{IN}, or the use of operators
5354@code{+}, @code{-}, @code{*}, @code{/}, @code{=}, , @code{<>}, @code{#},
5355@code{<=}, and @code{>=} on sets as an error.
5356@end quotation
5357_1__
29a2b744 5358@cindex Modula-2 built-ins
4eb4cf57 5359@node Built-In Func/Proc
c2bbbb22
RP
5360@subsubsection Built-in Functions and Procedures
5361
5362Modula-2 also makes available several built-in procedures and functions.
5363In describing these, the following metavariables are used:
5364
5365@table @var
5366
5367@item a
5368represents an @code{ARRAY} variable.
5369
5370@item c
5371represents a @code{CHAR} constant or variable.
5372
5373@item i
5374represents a variable or constant of integral type.
5375
5376@item m
5377represents an identifier that belongs to a set. Generally used in the
5378same function with the metavariable @var{s}. The type of @var{s} should
5379be @code{SET OF @var{mtype}} (where @var{mtype} is the type of @var{m}.
5380
5381@item n
5382represents a variable or constant of integral or floating-point type.
5383
5384@item r
5385represents a variable or constant of floating-point type.
5386
5387@item t
5388represents a type.
5389
5390@item v
5391represents a variable.
5392
5393@item x
5394represents a variable or constant of one of many types. See the
5395explanation of the function for details.
c2bbbb22
RP
5396@end table
5397
5398All Modula-2 built-in procedures also return a result, described below.
5399
5400@table @code
5401@item ABS(@var{n})
5402Returns the absolute value of @var{n}.
5403
5404@item CAP(@var{c})
5405If @var{c} is a lower case letter, it returns its upper case
5406equivalent, otherwise it returns its argument
5407
5408@item CHR(@var{i})
5409Returns the character whose ordinal value is @var{i}.
5410
5411@item DEC(@var{v})
5412Decrements the value in the variable @var{v}. Returns the new value.
5413
5414@item DEC(@var{v},@var{i})
5415Decrements the value in the variable @var{v} by @var{i}. Returns the
5416new value.
5417
5418@item EXCL(@var{m},@var{s})
5419Removes the element @var{m} from the set @var{s}. Returns the new
5420set.
5421
5422@item FLOAT(@var{i})
5423Returns the floating point equivalent of the integer @var{i}.
5424
5425@item HIGH(@var{a})
5426Returns the index of the last member of @var{a}.
5427
5428@item INC(@var{v})
5429Increments the value in the variable @var{v}. Returns the new value.
5430
5431@item INC(@var{v},@var{i})
5432Increments the value in the variable @var{v} by @var{i}. Returns the
5433new value.
5434
5435@item INCL(@var{m},@var{s})
5436Adds the element @var{m} to the set @var{s} if it is not already
5437there. Returns the new set.
5438
5439@item MAX(@var{t})
5440Returns the maximum value of the type @var{t}.
5441
5442@item MIN(@var{t})
5443Returns the minimum value of the type @var{t}.
5444
5445@item ODD(@var{i})
5446Returns boolean TRUE if @var{i} is an odd number.
5447
5448@item ORD(@var{x})
5449Returns the ordinal value of its argument. For example, the ordinal
5450value of a character is its ASCII value (on machines supporting the
5451ASCII character set). @var{x} must be of an ordered type, which include
5452integral, character and enumerated types.
5453
5454@item SIZE(@var{x})
5455Returns the size of its argument. @var{x} can be a variable or a type.
5456
5457@item TRUNC(@var{r})
5458Returns the integral part of @var{r}.
5459
5460@item VAL(@var{t},@var{i})
5461Returns the member of the type @var{t} whose ordinal value is @var{i}.
5462@end table
5463
5464@quotation
5465@emph{Warning:} Sets and their operations are not yet supported, so
5466_GDBN__ will treat the use of procedures @code{INCL} and @code{EXCL} as
5467an error.
5468@end quotation
5469
5470@cindex Modula-2 constants
4eb4cf57 5471@node M2 Constants
c2bbbb22
RP
5472@subsubsection Constants
5473
5474_GDBN__ allows you to express the constants of Modula-2 in the following
5475ways:
5476
5477@itemize @bullet
5478
5479@item
5480Integer constants are simply a sequence of digits. When used in an
5481expression, a constant is interpreted to be type-compatible with the
5482rest of the expression. Hexadecimal integers are specified by a
5483trailing @samp{H}, and octal integers by a trailing @samp{B}.
5484
5485@item
5486Floating point constants appear as a sequence of digits, followed by a
5487decimal point and another sequence of digits. An optional exponent can
5488then be specified, in the form @samp{E@r{[}+@r{|}-@r{]}@var{nnn}}, where
5489@samp{@r{[}+@r{|}-@r{]}@var{nnn}} is the desired exponent. All of the
5490digits of the floating point constant must be valid decimal (base 10)
5491digits.
5492
5493@item
5494Character constants consist of a single character enclosed by a pair of
5495like quotes, either single (@code{'}) or double (@code{"}). They may
5496also be expressed by their ordinal value (their ASCII value, usually)
5497followed by a @samp{C}.
5498
5499@item
1041a570
RP
5500String constants consist of a sequence of characters enclosed by a
5501pair of like quotes, either single (@code{'}) or double (@code{"}).
5502Escape sequences in the style of C are also allowed. @xref{C
5503Constants, ,C and C++ Constants}, for a brief explanation of escape
5504sequences.
c2bbbb22
RP
5505
5506@item
5507Enumerated constants consist of an enumerated identifier.
5508
5509@item
5510Boolean constants consist of the identifiers @code{TRUE} and
5511@code{FALSE}.
5512
5513@item
5514Pointer constants consist of integral values only.
5515
5516@item
5517Set constants are not yet supported.
c2bbbb22
RP
5518@end itemize
5519
4eb4cf57 5520@node M2 Defaults
c2bbbb22
RP
5521@subsubsection Modula-2 Defaults
5522@cindex Modula-2 defaults
5523
e251e767
RP
5524If type and range checking are set automatically by _GDBN__, they
5525both default to @code{on} whenever the working language changes to
c2bbbb22
RP
5526Modula-2. This happens regardless of whether you, or _GDBN__,
5527selected the working language.
5528
5529If you allow _GDBN__ to set the language automatically, then entering
5530code compiled from a file whose name ends with @file{.mod} will set the
1041a570 5531working language to Modula-2. @xref{Automatically, ,Having _GDBN__ set
c2bbbb22
RP
5532the language automatically}, for further details.
5533
4eb4cf57 5534@node Deviations
c2bbbb22
RP
5535@subsubsection Deviations from Standard Modula-2
5536@cindex Modula-2, deviations from
5537
5538A few changes have been made to make Modula-2 programs easier to debug.
5539This is done primarily via loosening its type strictness:
5540
5541@itemize @bullet
e251e767 5542@item
c2bbbb22
RP
5543Unlike in standard Modula-2, pointer constants can be formed by
5544integers. This allows you to modify pointer variables during
5545debugging. (In standard Modula-2, the actual address contained in a
5546pointer variable is hidden from you; it can only be modified
5547through direct assignment to another pointer variable or expression that
5548returned a pointer.)
5549
e251e767 5550@item
c2bbbb22
RP
5551C escape sequences can be used in strings and characters to represent
5552non-printable characters. _GDBN__ will print out strings with these
5553escape sequences embedded. Single non-printable characters are
5554printed using the @samp{CHR(@var{nnn})} format.
5555
5556@item
5557The assignment operator (@code{:=}) returns the value of its right-hand
5558argument.
5559
5560@item
29a2b744 5561All built-in procedures both modify @emph{and} return their argument.
e251e767 5562@end itemize
c2bbbb22 5563
4eb4cf57 5564@node M2 Checks
c2bbbb22
RP
5565@subsubsection Modula-2 Type and Range Checks
5566@cindex Modula-2 checks
5567
5568@quotation
5569@emph{Warning:} in this release, _GDBN__ does not yet perform type or
5570range checking.
5571@end quotation
5572@c FIXME remove warning when type/range checks added
5573
5574_GDBN__ considers two Modula-2 variables type equivalent if:
5575
5576@itemize @bullet
5577@item
5578They are of types that have been declared equivalent via a @code{TYPE
5579@var{t1} = @var{t2}} statement
5580
5581@item
5582They have been declared on the same line. (Note: This is true of the
5583GNU Modula-2 compiler, but it may not be true of other compilers.)
c2bbbb22
RP
5584@end itemize
5585
5586As long as type checking is enabled, any attempt to combine variables
5587whose types are not equivalent is an error.
5588
5589Range checking is done on all mathematical operations, assignment, array
29a2b744 5590index bounds, and all built-in functions and procedures.
c2bbbb22 5591
4eb4cf57 5592@node M2 Scope
c2bbbb22
RP
5593@subsubsection The scope operators @code{::} and @code{.}
5594@cindex scope
5595@kindex .
e94b4a2b 5596@cindex colon, doubled as scope operator
1041a570
RP
5597@ifinfo
5598@kindex colon-colon
5599@c Info cannot handoe :: but TeX can.
5600@end ifinfo
5601@iftex
c2bbbb22 5602@kindex ::
1041a570 5603@end iftex
c2bbbb22
RP
5604
5605There are a few subtle differences between the Modula-2 scope operator
5606(@code{.}) and the _GDBN__ scope operator (@code{::}). The two have
5607similar syntax:
5608
5609@example
5610
5611@var{module} . @var{id}
5612@var{scope} :: @var{id}
c2bbbb22
RP
5613@end example
5614
5615@noindent
5616where @var{scope} is the name of a module or a procedure,
29a2b744
RP
5617@var{module} the name of a module, and @var{id} is any declared
5618identifier within your program, except another module.
c2bbbb22
RP
5619
5620Using the @code{::} operator makes _GDBN__ search the scope
5621specified by @var{scope} for the identifier @var{id}. If it is not
5622found in the specified scope, then _GDBN__ will search all scopes
5623enclosing the one specified by @var{scope}.
5624
5625Using the @code{.} operator makes _GDBN__ search the current scope for
5626the identifier specified by @var{id} that was imported from the
5627definition module specified by @var{module}. With this operator, it is
5628an error if the identifier @var{id} was not imported from definition
5629module @var{module}, or if @var{id} is not an identifier in
5630@var{module}.
5631
4eb4cf57 5632@node GDB/M2
c2bbbb22
RP
5633@subsubsection _GDBN__ and Modula-2
5634
5635Some _GDBN__ commands have little use when debugging Modula-2 programs.
5636Five subcommands of @code{set print} and @code{show print} apply
5637specifically to C and C++: @samp{vtbl}, @samp{demangle},
5638@samp{asm-demangle}, @samp{object}, and @samp{union}. The first four
5639apply to C++, and the last to C's @code{union} type, which has no direct
5640analogue in Modula-2.
5641
1041a570 5642The @code{@@} operator (@pxref{Expressions, ,Expressions}), while available
c2bbbb22
RP
5643while using any language, is not useful with Modula-2. Its
5644intent is to aid the debugging of @dfn{dynamic arrays}, which cannot be
5645created in Modula-2 as they can in C or C++. However, because an
5646address can be specified by an integral constant, the construct
1041a570 5647@samp{@{@var{type}@}@var{adrexp}} is still useful. (@pxref{Expressions, ,Expressions})
c2bbbb22
RP
5648_0__
5649@cindex @code{#} in Modula-2
5650In _GDBN__ scripts, the Modula-2 inequality operator @code{#} is
5651interpreted as the beginning of a comment. Use @code{<>} instead.
5652_1__
4eb4cf57
RP
5653_fi__(!_CONLY__)
5654
5655@node Symbols
70b88761
RP
5656@chapter Examining the Symbol Table
5657
5658The commands described in this section allow you to inquire about the
5659symbols (names of variables, functions and types) defined in your
5660program. This information is inherent in the text of your program and
29a2b744 5661does not change as your program executes. _GDBN__ finds it in your
e251e767 5662program's symbol table, in the file indicated when you started _GDBN__
1041a570
RP
5663(@pxref{File Options, ,Choosing Files}), or by one of the
5664file-management commands (@pxref{Files, ,Commands to Specify Files}).
70b88761 5665
6c380b13
RP
5666@c FIXME! This might be intentionally specific to C and C++; if so, move
5667@c to someplace in C section of lang chapter.
5668@cindex symbol names
5669@cindex names of symbols
5670@cindex quoting names
5671Occasionally, you may need to refer to symbols that contain unusual
5672characters, which _GDBN__ ordinarily treats as word delimiters. The
5673most frequent case is in referring to static variables in other
5674source files (@pxref{Variables,,Program Variables}). File names
5675are recorded in object files as debugging symbols, but _GDBN__ would
5676ordinarily parse a typical file name, like @file{foo.c}, as the three words
5677@samp{foo} @samp{.} @samp{c}. To allow _GDBN__ to recognize
5678@samp{foo.c} as a single symbol, enclose it in single quotes; for example,
5679
5680@example
5681p 'foo.c'::x
5682@end example
5683
5684@noindent
5685looks up the value of @code{x} in the scope of the file @file{foo.c}.
5686
70b88761
RP
5687@table @code
5688@item info address @var{symbol}
5689@kindex info address
5690Describe where the data for @var{symbol} is stored. For a register
5691variable, this says which register it is kept in. For a non-register
5692local variable, this prints the stack-frame offset at which the variable
5693is always stored.
5694
5695Note the contrast with @samp{print &@var{symbol}}, which does not work
5696at all for a register variables, and for a stack local variable prints
5697the exact address of the current instantiation of the variable.
5698
5699@item whatis @var{exp}
5700@kindex whatis
5701Print the data type of expression @var{exp}. @var{exp} is not
5702actually evaluated, and any side-effecting operations (such as
5703assignments or function calls) inside it do not take place.
1041a570 5704@xref{Expressions, ,Expressions}.
70b88761
RP
5705
5706@item whatis
5707Print the data type of @code{$}, the last value in the value history.
5708
5709@item ptype @var{typename}
5710@kindex ptype
5711Print a description of data type @var{typename}. @var{typename} may be
5712the name of a type, or for C code it may have the form
5713@samp{struct @var{struct-tag}}, @samp{union @var{union-tag}} or
1041a570 5714@samp{enum @var{enum-tag}}.
70b88761
RP
5715
5716@item ptype @var{exp}
e0dacfd1 5717@itemx ptype
70b88761 5718Print a description of the type of expression @var{exp}. @code{ptype}
1041a570
RP
5719differs from @code{whatis} by printing a detailed description, instead
5720of just the name of the type. For example, if your program declares a
5721variable as
5722
70b88761
RP
5723@example
5724struct complex @{double real; double imag;@} v;
5725@end example
1041a570 5726
70b88761
RP
5727@noindent
5728compare the output of the two commands:
1041a570 5729
70b88761 5730@example
1041a570 5731@group
70b88761
RP
5732(_GDBP__) whatis v
5733type = struct complex
5734(_GDBP__) ptype v
5735type = struct complex @{
5736 double real;
5737 double imag;
5738@}
1041a570 5739@end group
70b88761 5740@end example
1041a570 5741
e0dacfd1
RP
5742@noindent
5743As with @code{whatis}, using @code{ptype} without an argument refers to
5744the type of @code{$}, the last value in the value history.
70b88761
RP
5745
5746@item info types @var{regexp}
5747@itemx info types
e251e767 5748@kindex info types
70b88761
RP
5749Print a brief description of all types whose name matches @var{regexp}
5750(or all types in your program, if you supply no argument). Each
5751complete typename is matched as though it were a complete line; thus,
5752@samp{i type value} gives information on all types in your program whose
5753name includes the string @code{value}, but @samp{i type ^value$} gives
5754information only on types whose complete name is @code{value}.
5755
5756This command differs from @code{ptype} in two ways: first, like
5757@code{whatis}, it does not print a detailed description; second, it
5758lists all source files where a type is defined.
5759
5760@item info source
5761@kindex info source
5762Show the name of the current source file---that is, the source file for
c2bbbb22
RP
5763the function containing the current point of execution---and the language
5764it was written in.
70b88761
RP
5765
5766@item info sources
5767@kindex info sources
29a2b744 5768Print the names of all source files in your program for which there is
b80282d5
RP
5769debugging information, organized into two lists: files whose symbols
5770have already been read, and files whose symbols will be read when needed.
70b88761
RP
5771
5772@item info functions
5773@kindex info functions
5774Print the names and data types of all defined functions.
5775
5776@item info functions @var{regexp}
5777Print the names and data types of all defined functions
5778whose names contain a match for regular expression @var{regexp}.
5779Thus, @samp{info fun step} finds all functions whose names
5780include @code{step}; @samp{info fun ^step} finds those whose names
5781start with @code{step}.
5782
5783@item info variables
5784@kindex info variables
5785Print the names and data types of all variables that are declared
5786outside of functions (i.e., excluding local variables).
5787
5788@item info variables @var{regexp}
5789Print the names and data types of all variables (except for local
5790variables) whose names contain a match for regular expression
5791@var{regexp}.
5792
70b88761
RP
5793@ignore
5794This was never implemented.
5795@item info methods
5796@itemx info methods @var{regexp}
5797@kindex info methods
5798The @code{info methods} command permits the user to examine all defined
5799methods within C++ program, or (with the @var{regexp} argument) a
5800specific set of methods found in the various C++ classes. Many
5801C++ classes provide a large number of methods. Thus, the output
5802from the @code{ptype} command can be overwhelming and hard to use. The
5803@code{info-methods} command filters the methods, printing only those
5804which match the regular-expression @var{regexp}.
5805@end ignore
5806
d48da190
RP
5807@item maint print symbols @var{filename}
5808@itemx maint print psymbols @var{filename}
5809@itemx maint print msymbols @var{filename}
5810@kindex maint print symbols
440d9834 5811@cindex symbol dump
d48da190 5812@kindex maint print psymbols
440d9834
RP
5813@cindex partial symbol dump
5814Write a dump of debugging symbol data into the file @var{filename}.
e0dacfd1 5815These commands are used to debug the _GDBN__ symbol-reading code. Only
d48da190
RP
5816symbols with debugging data are included. If you use @samp{maint print
5817symbols}, _GDBN__ includes all the symbols for which it has already
5818collected full details: that is, @var{filename} reflects symbols for
5819only those files whose symbols _GDBN__ has read. You can use the
5820command @code{info sources} to find out which files these are. If you
5821use @samp{maint print psymbols} instead, the dump shows information about
5822symbols that _GDBN__ only knows partially---that is, symbols defined in
5823files that _GDBN__ has skimmed, but not yet read completely. Finally,
5824@samp{maint print msymbols} dumps just the minimal symbol information
5825required for each object file from which _GDBN__ has read some symbols.
5826The description of @code{symbol-file} explains how _GDBN__ reads
5827symbols; both @code{info source} and @code{symbol-file} are described in
5828@ref{Files, ,Commands to Specify Files}.
70b88761
RP
5829@end table
5830
4eb4cf57 5831@node Altering
70b88761
RP
5832@chapter Altering Execution
5833
29a2b744 5834Once you think you have found an error in your program, you might want to
70b88761
RP
5835find out for certain whether correcting the apparent error would lead to
5836correct results in the rest of the run. You can find the answer by
5837experiment, using the _GDBN__ features for altering execution of the
5838program.
5839
5840For example, you can store new values into variables or memory
29a2b744 5841locations, give your program a signal, restart it at a different address,
70b88761
RP
5842or even return prematurely from a function to its caller.
5843
5844@menu
b80282d5
RP
5845* Assignment:: Assignment to Variables
5846* Jumping:: Continuing at a Different Address
4eb4cf57 5847_if__(!_BARE__)
29a2b744 5848* Signaling:: Giving your program a Signal
4eb4cf57 5849_fi__(!_BARE__)
b80282d5
RP
5850* Returning:: Returning from a Function
5851* Calling:: Calling your Program's Functions
c338a2fd 5852* Patching:: Patching your Program
70b88761
RP
5853@end menu
5854
4eb4cf57 5855@node Assignment
70b88761
RP
5856@section Assignment to Variables
5857
5858@cindex assignment
5859@cindex setting variables
5860To alter the value of a variable, evaluate an assignment expression.
1041a570 5861@xref{Expressions, ,Expressions}. For example,
70b88761
RP
5862
5863@example
5864print x=4
5865@end example
5866
5867@noindent
1041a570 5868stores the value 4 into the variable @code{x}, and then prints the
4eb4cf57
RP
5869value of the assignment expression (which is 4).
5870_if__(!_CONLY__)
5871@xref{Languages, ,Using _GDBN__ with Different Languages}, for more
5872information on operators in supported languages.
5873_fi__(!_CONLY__)
70b88761 5874
70b88761
RP
5875@kindex set variable
5876@cindex variables, setting
5877If you are not interested in seeing the value of the assignment, use the
5878@code{set} command instead of the @code{print} command. @code{set} is
5879really the same as @code{print} except that the expression's value is not
1041a570 5880printed and is not put in the value history (@pxref{Value History, ,Value History}). The
70b88761
RP
5881expression is evaluated only for its effects.
5882
5883If the beginning of the argument string of the @code{set} command
5884appears identical to a @code{set} subcommand, use the @code{set
5885variable} command instead of just @code{set}. This command is identical
5886to @code{set} except for its lack of subcommands. For example, a
5887program might well have a variable @code{width}---which leads to
5888an error if we try to set a new value with just @samp{set width=13}, as
1041a570
RP
5889we might if @code{set width} did not happen to be a _GDBN__ command:
5890
70b88761
RP
5891@example
5892(_GDBP__) whatis width
5893type = double
5894(_GDBP__) p width
5895$4 = 13
5896(_GDBP__) set width=47
5897Invalid syntax in expression.
5898@end example
1041a570 5899
70b88761
RP
5900@noindent
5901The invalid expression, of course, is @samp{=47}. What we can do in
e251e767 5902order to actually set our program's variable @code{width} is
1041a570 5903
70b88761
RP
5904@example
5905(_GDBP__) set var width=47
5906@end example
5907
1041a570
RP
5908_GDBN__ allows more implicit conversions in assignments than C; you can
5909freely store an integer value into a pointer variable or vice versa,
5910and any structure can be converted to any other structure that is the
5911same length or shorter.
e251e767 5912@comment FIXME: how do structs align/pad in these conversions?
70b88761
RP
5913@comment /pesch@cygnus.com 18dec1990
5914
5915To store values into arbitrary places in memory, use the @samp{@{@dots{}@}}
5916construct to generate a value of specified type at a specified address
1041a570 5917(@pxref{Expressions, ,Expressions}). For example, @code{@{int@}0x83040} refers
70b88761
RP
5918to memory location @code{0x83040} as an integer (which implies a certain size
5919and representation in memory), and
5920
5921@example
5922set @{int@}0x83040 = 4
5923@end example
5924
5925@noindent
5926stores the value 4 into that memory location.
5927
4eb4cf57 5928@node Jumping
70b88761
RP
5929@section Continuing at a Different Address
5930
29a2b744 5931Ordinarily, when you continue your program, you do so at the place where
70b88761
RP
5932it stopped, with the @code{continue} command. You can instead continue at
5933an address of your own choosing, with the following commands:
5934
5935@table @code
5936@item jump @var{linespec}
5937@kindex jump
5938Resume execution at line @var{linespec}. Execution will stop
29a2b744
RP
5939immediately if there is a breakpoint there. @xref{List, ,Printing
5940Source Lines}, for a description of the different forms of
5941@var{linespec}.
70b88761
RP
5942
5943The @code{jump} command does not change the current stack frame, or
5944the stack pointer, or the contents of any memory location or any
5945register other than the program counter. If line @var{linespec} is in
5946a different function from the one currently executing, the results may
5947be bizarre if the two functions expect different patterns of arguments or
5948of local variables. For this reason, the @code{jump} command requests
5949confirmation if the specified line is not in the function currently
5950executing. However, even bizarre results are predictable if you are
29a2b744 5951well acquainted with the machine-language code of your program.
70b88761
RP
5952
5953@item jump *@var{address}
5954Resume execution at the instruction at address @var{address}.
5955@end table
5956
5957You can get much the same effect as the @code{jump} command by storing a
5958new value into the register @code{$pc}. The difference is that this
29a2b744 5959does not start your program running; it only changes the address where it
70b88761
RP
5960@emph{will} run when it is continued. For example,
5961
5962@example
5963set $pc = 0x485
5964@end example
5965
5966@noindent
5967causes the next @code{continue} command or stepping command to execute at
1041a570
RP
5968address @code{0x485}, rather than at the address where your program stopped.
5969@xref{Continuing and Stepping, ,Continuing and Stepping}.
70b88761
RP
5970
5971The most common occasion to use the @code{jump} command is to back up,
5972perhaps with more breakpoints set, over a portion of a program that has
5973already executed, in order to examine its execution in more detail.
5974
4eb4cf57
RP
5975_if__(!_BARE__)
5976@node Signaling
70b88761 5977@c @group
29a2b744 5978@section Giving your program a Signal
70b88761
RP
5979
5980@table @code
5981@item signal @var{signalnum}
5982@kindex signal
29a2b744 5983Resume execution where your program stopped, but give it immediately the
70b88761
RP
5984signal number @var{signalnum}.
5985
5986Alternatively, if @var{signalnum} is zero, continue execution without
29a2b744 5987giving a signal. This is useful when your program stopped on account of
70b88761
RP
5988a signal and would ordinary see the signal when resumed with the
5989@code{continue} command; @samp{signal 0} causes it to resume without a
5990signal.
5991
5992@code{signal} does not repeat when you press @key{RET} a second time
5993after executing the command.
5994@end table
5995@c @end group
4eb4cf57 5996_fi__(!_BARE__)
70b88761 5997
4eb4cf57 5998@node Returning
70b88761
RP
5999@section Returning from a Function
6000
6001@table @code
6002@item return
6003@itemx return @var{expression}
6004@cindex returning from a function
6005@kindex return
6006You can cancel execution of a function call with the @code{return}
6007command. If you give an
6008@var{expression} argument, its value is used as the function's return
e251e767 6009value.
70b88761
RP
6010@end table
6011
6012When you use @code{return}, _GDBN__ discards the selected stack frame
6013(and all frames within it). You can think of this as making the
6014discarded frame return prematurely. If you wish to specify a value to
6015be returned, give that value as the argument to @code{return}.
6016
29a2b744
RP
6017This pops the selected stack frame (@pxref{Selection, ,Selecting a
6018Frame}), and any other frames inside of it, leaving its caller as the
6019innermost remaining frame. That frame becomes selected. The
6020specified value is stored in the registers used for returning values
6021of functions.
70b88761
RP
6022
6023The @code{return} command does not resume execution; it leaves the
6024program stopped in the state that would exist if the function had just
1041a570
RP
6025returned. In contrast, the @code{finish} command (@pxref{Continuing
6026and Stepping, ,Continuing and Stepping}) resumes execution until the
6027selected stack frame returns naturally.
70b88761 6028
4eb4cf57 6029@node Calling
70b88761
RP
6030@section Calling your Program's Functions
6031
6032@cindex calling functions
6033@kindex call
6034@table @code
6035@item call @var{expr}
6036Evaluate the expression @var{expr} without displaying @code{void}
6037returned values.
6038@end table
6039
6040You can use this variant of the @code{print} command if you want to
6041execute a function from your program, but without cluttering the output
6042with @code{void} returned values. The result is printed and saved in
6043the value history, if it is not void.
6044
4eb4cf57 6045@node Patching
c338a2fd
RP
6046@section Patching your Program
6047@cindex patching binaries
6048@cindex writing into executables
6049@cindex writing into corefiles
1041a570 6050
c338a2fd
RP
6051By default, _GDBN__ opens the file containing your program's executable
6052code (or the corefile) read-only. This prevents accidental alterations
6053to machine code; but it also prevents you from intentionally patching
6054your program's binary.
6055
6056If you'd like to be able to patch the binary, you can specify that
6057explicitly with the @code{set write} command. For example, you might
6058want to turn on internal debugging flags, or even to make emergency
e251e767 6059repairs.
c338a2fd
RP
6060
6061@table @code
6062@item set write on
6063@itemx set write off
6064@kindex set write
0f153e74
RP
6065If you specify @samp{set write on}, _GDBN__ will open executable
6066_if__(!_BARE__)
6067and core
6068_fi__(!_BARE__)
6069files for both reading and writing; if you specify @samp{set write
c338a2fd
RP
6070off} (the default), _GDBN__ will open them read-only.
6071
1041a570 6072If you have already loaded a file, you must load it
c338a2fd
RP
6073again (using the @code{exec-file} or @code{core-file} command) after
6074changing @code{set write}, for your new setting to take effect.
6075
6076@item show write
7d7ff5f6 6077@kindex show write
0f153e74
RP
6078Display whether executable files
6079_if__(!_BARE__)
6080and core files
6081_fi__(!_BARE__)
6082will be opened for writing as well as reading.
c338a2fd
RP
6083@end table
6084
4eb4cf57 6085@node _GDBN__ Files
70b88761
RP
6086@chapter _GDBN__'s Files
6087
1041a570 6088_GDBN__ needs to know the file name of the program to be debugged, both in
4eb4cf57
RP
6089order to read its symbol table and in order to start your program.
6090_if__(!_BARE__)
6091To debug a core dump of a previous run, _GDBN__ must be told the file
6092name of the core dump.
6093_fi__(!_BARE__)
1041a570 6094
70b88761 6095@menu
b80282d5
RP
6096* Files:: Commands to Specify Files
6097* Symbol Errors:: Errors Reading Symbol Files
70b88761
RP
6098@end menu
6099
4eb4cf57 6100@node Files
70b88761 6101@section Commands to Specify Files
70b88761 6102@cindex symbol table
70b88761 6103
4eb4cf57 6104_if__(!_BARE__)
0f153e74 6105@cindex core dump file
1041a570
RP
6106The usual way to specify executable and core dump file names is with
6107the command arguments given when you start _GDBN__, (@pxref{Invocation,
6108,Getting In and Out of _GDBN__}.
4eb4cf57
RP
6109_fi__(!_BARE__)
6110_if__(_BARE__)
6111The usual way to specify an executable file name is with
6112the command argument given when you start _GDBN__, (@pxref{Invocation,
6113,Getting In and Out of _GDBN__}.
6114_fi__(_BARE__)
70b88761
RP
6115
6116Occasionally it is necessary to change to a different file during a
4eb4cf57 6117_GDBN__ session. Or you may run _GDBN__ and forget to specify a file you
70b88761
RP
6118want to use. In these situations the _GDBN__ commands to specify new files
6119are useful.
6120
6121@table @code
6122@item file @var{filename}
6123@cindex executable file
6124@kindex file
6125Use @var{filename} as the program to be debugged. It is read for its
6126symbols and for the contents of pure memory. It is also the program
6127executed when you use the @code{run} command. If you do not specify a
1041a570
RP
6128directory and the file is not found in _GDBN__'s working directory, _GDBN__
6129uses the environment variable @code{PATH} as a list of directories to
6130search, just as the shell does when looking for a program to run. You
6131can change the value of this variable, for both _GDBN__ and your program,
6132using the @code{path} command.
70b88761 6133
14d01801
RP
6134On systems with memory-mapped files, an auxiliary symbol table file
6135@file{@var{filename}.syms} may be available for @var{filename}. If it
6136is, _GDBN__ will map in the symbol table from
6137@file{@var{filename}.syms}, starting up more quickly. See the
95d5ceb9 6138descriptions of the options @samp{-mapped} and @samp{-readnow} (available
77b46d13
JG
6139on the command line, and with the commands @code{file}, @code{symbol-file},
6140or @code{add-symbol-file}), for more information.
14d01801 6141
e0dacfd1 6142@item file
70b88761
RP
6143@code{file} with no argument makes _GDBN__ discard any information it
6144has on both executable file and the symbol table.
6145
e0dacfd1 6146@item exec-file @r{[} @var{filename} @r{]}
70b88761
RP
6147@kindex exec-file
6148Specify that the program to be run (but not the symbol table) is found
6149in @var{filename}. _GDBN__ will search the environment variable @code{PATH}
29a2b744 6150if necessary to locate your program. Omitting @var{filename} means to
e0dacfd1 6151discard information on the executable file.
70b88761 6152
e0dacfd1 6153@item symbol-file @r{[} @var{filename} @r{]}
70b88761
RP
6154@kindex symbol-file
6155Read symbol table information from file @var{filename}. @code{PATH} is
6156searched when necessary. Use the @code{file} command to get both symbol
6157table and program to run from the same file.
6158
6159@code{symbol-file} with no argument clears out _GDBN__'s information on your
6160program's symbol table.
6161
6162The @code{symbol-file} command causes _GDBN__ to forget the contents of its
6163convenience variables, the value history, and all breakpoints and
6164auto-display expressions. This is because they may contain pointers to
6165the internal data recording symbols and data types, which are part of
6166the old symbol table data being discarded inside _GDBN__.
6167
6168@code{symbol-file} will not repeat if you press @key{RET} again after
6169executing it once.
6170
14d01801
RP
6171When _GDBN__ is configured for a particular environment, it will
6172understand debugging information in whatever format is the standard
6173generated for that environment; you may use either a GNU compiler, or
6174other compilers that adhere to the local conventions. Best results are
6175usually obtained from GNU compilers; for example, using @code{_GCC__}
6176you can generate debugging information for optimized code.
6177
70b88761 6178On some kinds of object files, the @code{symbol-file} command does not
14d01801 6179normally read the symbol table in full right away. Instead, it scans
70b88761
RP
6180the symbol table quickly to find which source files and which symbols
6181are present. The details are read later, one source file at a time,
1041a570 6182as they are needed.
70b88761
RP
6183
6184The purpose of this two-stage reading strategy is to make _GDBN__ start up
1041a570
RP
6185faster. For the most part, it is invisible except for occasional
6186pauses while the symbol table details for a particular source file are
6187being read. (The @code{set verbose} command can turn these pauses
6188into messages if desired. @xref{Messages/Warnings, ,Optional Warnings
6189and Messages}.)
70b88761
RP
6190
6191When the symbol table is stored in COFF format, @code{symbol-file} does
1041a570 6192read the symbol table data in full right away. We have not implemented
70b88761
RP
6193the two-stage strategy for COFF yet.
6194
95d5ceb9
RP
6195@item symbol-file @var{filename} @r{[} -readnow @r{]} @r{[} -mapped @r{]}
6196@itemx file @var{filename} @r{[} -readnow @r{]} @r{[} -mapped @r{]}
14d01801
RP
6197@kindex readnow
6198@cindex reading symbols immediately
6199@cindex symbols, reading immediately
6200@kindex mapped
6201@cindex memory-mapped symbol file
38962738 6202@cindex saving symbol table
14d01801 6203You can override the _GDBN__ two-stage strategy for reading symbol
95d5ceb9 6204tables by using the @samp{-readnow} option with any of the commands that
14d01801
RP
6205load symbol table information, if you want to be sure _GDBN__ has the
6206entire symbol table available.
6207
4eb4cf57 6208_if__(!_BARE__)
14d01801 6209If memory-mapped files are available on your system through the
95d5ceb9 6210@code{mmap} system call, you can use another option, @samp{-mapped}, to
77b46d13
JG
6211cause _GDBN__ to write the symbols for your program into a reusable
6212file. Future _GDBN__ debugging sessions will map in symbol information
6213from this auxiliary symbol file (if the program hasn't changed), rather
6214than spending time reading the symbol table from the executable
6215program. Using the @samp{-mapped} option has the same effect as
6216starting _GDBN__ with the @samp{-mapped} command-line option.
14d01801 6217
95d5ceb9 6218You can use both options together, to make sure the auxiliary symbol
14d01801
RP
6219file has all the symbol information for your program.
6220
77b46d13
JG
6221The @code{.syms} file is specific to the host machine on which GDB is run.
6222It holds an exact image of GDB's internal symbol table. It cannot be
6223shared across multiple host platforms.
6224
14d01801
RP
6225The auxiliary symbol file for a program called @var{myprog} is called
6226@samp{@var{myprog}.syms}. Once this file exists (so long as it is newer
6227than the corresponding executable), _GDBN__ will always attempt to use
6228it when you debug @var{myprog}; no special options or commands are
6229needed.
6230@c FIXME: for now no mention of directories, since this seems to be in
6231@c flux. 13mar1992 status is that in theory GDB would look either in
6232@c current dir or in same dir as myprog; but issues like competing
6233@c GDB's, or clutter in system dirs, mean that in practice right now
6234@c only current dir is used. FFish says maybe a special GDB hierarchy
6235@c (eg rooted in val of env var GDBSYMS) could exist for mappable symbol
6236@c files.
70b88761 6237
e0dacfd1 6238@item core-file @r{[} @var{filename} @r{]}
70b88761
RP
6239@kindex core
6240@kindex core-file
6241Specify the whereabouts of a core dump file to be used as the ``contents
6242of memory''. Traditionally, core files contain only some parts of the
6243address space of the process that generated them; _GDBN__ can access the
6244executable file itself for other parts.
6245
6246@code{core-file} with no argument specifies that no core file is
6247to be used.
6248
6249Note that the core file is ignored when your program is actually running
29a2b744 6250under _GDBN__. So, if you have been running your program and you wish to
70b88761
RP
6251debug a core file instead, you must kill the subprocess in which the
6252program is running. To do this, use the @code{kill} command
1041a570 6253(@pxref{Kill Process, ,Killing the Child Process}).
4eb4cf57 6254_fi__(!_BARE__)
70b88761
RP
6255
6256@item load @var{filename}
6257@kindex load
6258_if__(_GENERIC__)
6259Depending on what remote debugging facilities are configured into
6260_GDBN__, the @code{load} command may be available. Where it exists, it
6261is meant to make @var{filename} (an executable) available for debugging
6262on the remote system---by downloading, or dynamic linking, for example.
6263@code{load} also records @var{filename}'s symbol table in _GDBN__, like
6264the @code{add-symbol-file} command.
6265
6266If @code{load} is not available on your _GDBN__, attempting to execute
6267it gets the error message ``@code{You can't do that when your target is
e251e767 6268@dots{}}''
70b88761
RP
6269_fi__(_GENERIC__)
6270
e251e767 6271_if__(_VXWORKS__)
70b88761
RP
6272On VxWorks, @code{load} will dynamically link @var{filename} on the
6273current target system as well as adding its symbols in _GDBN__.
6274_fi__(_VXWORKS__)
6275
6276_if__(_I960__)
6277@cindex download to Nindy-960
6278With the Nindy interface to an Intel 960 board, @code{load} will
6279download @var{filename} to the 960 as well as adding its symbols in
e251e767 6280_GDBN__.
70b88761
RP
6281_fi__(_I960__)
6282
c7cb8acb
RP
6283_if__(_H8__)
6284@cindex download to H8/300
6285@cindex H8/300 download
6286When you select remote debugging to a Hitachi H8/300 board (@pxref{Hitachi
6287H8/300 Remote,,_GDBN__ and the Hitachi H8/300}), the
6288@code{load} command downloads your program to the H8/300 and also opens
6289it as the current executable target for _GDBN__ on your host (like the
6290@code{file} command).
6291_fi__(_H8__)
6292
70b88761
RP
6293@code{load} will not repeat if you press @key{RET} again after using it.
6294
0f153e74 6295_if__(!_BARE__)
70b88761 6296@item add-symbol-file @var{filename} @var{address}
95d5ceb9 6297@itemx add-symbol-file @var{filename} @var{address} @r{[} -readnow @r{]} @r{[} -mapped @r{]}
70b88761
RP
6298@kindex add-symbol-file
6299@cindex dynamic linking
6300The @code{add-symbol-file} command reads additional symbol table information
b80282d5 6301from the file @var{filename}. You would use this command when @var{filename}
70b88761
RP
6302has been dynamically loaded (by some other means) into the program that
6303is running. @var{address} should be the memory address at which the
6304file has been loaded; _GDBN__ cannot figure this out for itself.
6305
6306The symbol table of the file @var{filename} is added to the symbol table
6307originally read with the @code{symbol-file} command. You can use the
6308@code{add-symbol-file} command any number of times; the new symbol data thus
6309read keeps adding to the old. To discard all old symbol data instead,
e251e767 6310use the @code{symbol-file} command.
70b88761
RP
6311
6312@code{add-symbol-file} will not repeat if you press @key{RET} after using it.
6313
95d5ceb9
RP
6314You can use the @samp{-mapped} and @samp{-readnow} options just as with
6315the @code{symbol-file} command, to change how _GDBN__ manages the symbol
0f153e74
RP
6316table information for @var{filename}.
6317_fi__(!_BARE__)
95d5ceb9 6318
70b88761
RP
6319@item info files
6320@itemx info target
6321@kindex info files
6322@kindex info target
1041a570
RP
6323@code{info files} and @code{info target} are synonymous; both print
6324the current targets (@pxref{Targets, ,Specifying a Debugging Target}),
6325including the names of the executable and core dump files currently in
6326use by _GDBN__, and the files from which symbols were loaded. The command
6327@code{help targets} lists all possible targets rather than current
6328ones.
70b88761
RP
6329
6330@end table
6331
6332All file-specifying commands allow both absolute and relative file names
6333as arguments. _GDBN__ always converts the file name to an absolute path
6334name and remembers it that way.
6335
4eb4cf57 6336_if__(!_BARE__)
70b88761 6337@cindex shared libraries
77b46d13
JG
6338_GDBN__ supports SunOS, SVR4, and IBM RS/6000 shared libraries.
6339_GDBN__ automatically loads symbol definitions from shared libraries
6340when you use the @code{run} command, or when you examine a core file.
6341(Before you issue the @code{run} command, _GDBN__ will not understand
6342references to a function in a shared library, however---unless you are
6343debugging a core file).
c338a2fd 6344@c FIXME: next _GDBN__ release should permit some refs to undef
1041a570 6345@c FIXME...symbols---eg in a break cmd---assuming they are from a shared lib
70b88761
RP
6346
6347@table @code
70b88761
RP
6348@item info share
6349@itemx info sharedlibrary
6350@kindex info sharedlibrary
6351@kindex info share
c338a2fd 6352Print the names of the shared libraries which are currently loaded.
70b88761 6353
c338a2fd
RP
6354@item sharedlibrary @var{regex}
6355@itemx share @var{regex}
6356@kindex sharedlibrary
6357@kindex share
6358This is an obsolescent command; you can use it to explicitly
6359load shared object library symbols for files matching a UNIX regular
6360expression, but as with files loaded automatically, it will only load
6361shared libraries required by your program for a core file or after
6362typing @code{run}. If @var{regex} is omitted all shared libraries
6363required by your program are loaded.
6364@end table
4eb4cf57 6365_fi__(!_BARE__)
70b88761 6366
4eb4cf57 6367@node Symbol Errors
70b88761 6368@section Errors Reading Symbol Files
1041a570
RP
6369
6370While reading a symbol file, _GDBN__ will occasionally encounter problems,
6371such as symbol types it does not recognize, or known bugs in compiler
6372output. By default, _GDBN__ does not notify you of such problems, since
6373they are relatively common and primarily of interest to people
6374debugging compilers. If you are interested in seeing information
b80282d5
RP
6375about ill-constructed symbol tables, you can either ask _GDBN__ to print
6376only one message about each such type of problem, no matter how many
6377times the problem occurs; or you can ask _GDBN__ to print more messages,
1041a570
RP
6378to see how many times the problems occur, with the @code{set
6379complaints} command (@pxref{Messages/Warnings, ,Optional Warnings and
6380Messages}).
70b88761
RP
6381
6382The messages currently printed, and their meanings, are:
6383
6384@table @code
6385@item inner block not inside outer block in @var{symbol}
6386
6387The symbol information shows where symbol scopes begin and end
6388(such as at the start of a function or a block of statements). This
6389error indicates that an inner scope block is not fully contained
e251e767 6390in its outer scope blocks.
70b88761
RP
6391
6392_GDBN__ circumvents the problem by treating the inner block as if it had
6393the same scope as the outer block. In the error message, @var{symbol}
6394may be shown as ``@code{(don't know)}'' if the outer block is not a
6395function.
6396
6397@item block at @var{address} out of order
6398
e251e767 6399The symbol information for symbol scope blocks should occur in
70b88761 6400order of increasing addresses. This error indicates that it does not
e251e767 6401do so.
70b88761
RP
6402
6403_GDBN__ does not circumvent this problem, and will have trouble locating
6404symbols in the source file whose symbols being read. (You can often
6405determine what source file is affected by specifying @code{set verbose
29a2b744 6406on}. @xref{Messages/Warnings, ,Optional Warnings and Messages}.)
70b88761
RP
6407
6408@item bad block start address patched
6409
6410The symbol information for a symbol scope block has a start address
6411smaller than the address of the preceding source line. This is known
e251e767 6412to occur in the SunOS 4.1.1 (and earlier) C compiler.
70b88761
RP
6413
6414_GDBN__ circumvents the problem by treating the symbol scope block as
6415starting on the previous source line.
6416
70b88761
RP
6417@item bad string table offset in symbol @var{n}
6418
6419@cindex foo
6420Symbol number @var{n} contains a pointer into the string table which is
e251e767 6421larger than the size of the string table.
70b88761
RP
6422
6423_GDBN__ circumvents the problem by considering the symbol to have the
6424name @code{foo}, which may cause other problems if many symbols end up
6425with this name.
6426
6427@item unknown symbol type @code{0x@var{nn}}
6428
6429The symbol information contains new data types that _GDBN__ does not yet
6430know how to read. @code{0x@var{nn}} is the symbol type of the misunderstood
e251e767 6431information, in hexadecimal.
70b88761
RP
6432
6433_GDBN__ circumvents the error by ignoring this symbol information. This
29a2b744 6434will usually allow your program to be debugged, though certain symbols
70b88761
RP
6435will not be accessible. If you encounter such a problem and feel like
6436debugging it, you can debug @code{_GDBP__} with itself, breakpoint on
6437@code{complain}, then go up to the function @code{read_dbx_symtab} and
6438examine @code{*bufp} to see the symbol.
6439
6440@item stub type has NULL name
e251e767 6441_GDBN__ could not find the full definition for a struct or class.
70b88761 6442
440d9834 6443@item const/volatile indicator missing (ok if using g++ v1.x), got@dots{}
70b88761
RP
6444
6445The symbol information for a C++ member function is missing some
440d9834
RP
6446information that recent versions of the compiler should have output
6447for it.
70b88761 6448
440d9834 6449@item info mismatch between compiler and debugger
70b88761 6450
440d9834 6451_GDBN__ could not parse a type specification output by the compiler.
70b88761
RP
6452@end table
6453
4eb4cf57 6454@node Targets
e251e767 6455@chapter Specifying a Debugging Target
70b88761
RP
6456@cindex debugging target
6457@kindex target
1041a570 6458
cedaf8bc 6459A @dfn{target} is the execution environment occupied by your program.
0f153e74 6460_if__(!_BARE__)
1041a570
RP
6461Often, _GDBN__ runs in the same host environment as your program; in
6462that case, the debugging target is specified as a side effect when you
6463use the @code{file} or @code{core} commands. When you need more
6464flexibility---for example, running _GDBN__ on a physically separate
6465host, or controlling a standalone system over a serial port or a
0f153e74
RP
6466realtime system over a TCP/IP connection---you
6467_fi__(!_BARE__)
6468_if__(_BARE__)
6469You
6470_fi__(_BARE__)
6471can use the @code{target} command to specify one of the target types
6472configured for _GDBN__ (@pxref{Target Commands, ,Commands for Managing
6473Targets}).
70b88761
RP
6474
6475@menu
b80282d5
RP
6476* Active Targets:: Active Targets
6477* Target Commands:: Commands for Managing Targets
6478* Remote:: Remote Debugging
70b88761
RP
6479@end menu
6480
4eb4cf57 6481@node Active Targets
70b88761
RP
6482@section Active Targets
6483@cindex stacking targets
6484@cindex active targets
6485@cindex multiple targets
6486
0f153e74 6487_if__(!_BARE__)
cedaf8bc
RP
6488There are three classes of targets: processes, core files, and
6489executable files. _GDBN__ can work concurrently on up to three active
6490targets, one in each class. This allows you to (for example) start a
6491process and inspect its activity without abandoning your work on a core
6492file.
70b88761 6493
cedaf8bc
RP
6494If, for example, you execute @samp{gdb a.out}, then the executable file
6495@code{a.out} is the only active target. If you designate a core file as
6496well---presumably from a prior run that crashed and coredumped---then
6497_GDBN__ has two active targets and will use them in tandem, looking
6498first in the corefile target, then in the executable file, to satisfy
6499requests for memory addresses. (Typically, these two classes of target
29a2b744 6500are complementary, since core files contain only a program's
cedaf8bc
RP
6501read-write memory---variables and so on---plus machine status, while
6502executable files contain only the program text and initialized data.)
0f153e74 6503_fi__(!_BARE__)
cedaf8bc
RP
6504
6505When you type @code{run}, your executable file becomes an active process
6506target as well. When a process target is active, all _GDBN__ commands
0f153e74
RP
6507requesting memory addresses refer to that target; addresses in an
6508_if__(!_BARE__)
6509active core file or
6510_fi__(!_BARE__)
6511executable file target are obscured while the process
cedaf8bc
RP
6512target is active.
6513
4eb4cf57
RP
6514_if__(_BARE__)
6515Use the @code{exec-file} command to select a
6516new executable target (@pxref{Files, ,Commands to Specify
6517Files}).
6518_fi__(_BARE__)
6519_if__(!_BARE__)
1041a570
RP
6520Use the @code{core-file} and @code{exec-file} commands to select a
6521new core file or executable target (@pxref{Files, ,Commands to Specify
6522Files}). To specify as a target a process that is already running, use
6523the @code{attach} command (@pxref{Attach, ,Debugging an
6524Already-Running Process}.).
4eb4cf57 6525_fi__(!_BARE__)
70b88761 6526
4eb4cf57 6527@node Target Commands
70b88761
RP
6528@section Commands for Managing Targets
6529
6530@table @code
6531@item target @var{type} @var{parameters}
6532Connects the _GDBN__ host environment to a target machine or process. A
6533target is typically a protocol for talking to debugging facilities. You
6534use the argument @var{type} to specify the type or protocol of the
6535target machine.
6536
6537Further @var{parameters} are interpreted by the target protocol, but
6538typically include things like device names or host names to connect
e251e767 6539with, process numbers, and baud rates.
70b88761
RP
6540
6541The @code{target} command will not repeat if you press @key{RET} again
6542after executing the command.
6543
6544@item help target
6545@kindex help target
6546Displays the names of all targets available. To display targets
6547currently selected, use either @code{info target} or @code{info files}
29a2b744 6548(@pxref{Files, ,Commands to Specify Files}).
70b88761
RP
6549
6550@item help target @var{name}
6551Describe a particular target, including any parameters necessary to
6552select it.
6553@end table
6554
c7cb8acb 6555Here are some common targets (available, or not, depending on the GDB
70b88761
RP
6556configuration):
6557
6558@table @code
6559@item target exec @var{prog}
6560@kindex target exec
6561An executable file. @samp{target exec @var{prog}} is the same as
6562@samp{exec-file @var{prog}}.
6563
6564@item target core @var{filename}
6565@kindex target core
6566A core dump file. @samp{target core @var{filename}} is the same as
6567@samp{core-file @var{filename}}.
6568
0f153e74 6569_if__(_REMOTESTUB__)
70b88761
RP
6570@item target remote @var{dev}
6571@kindex target remote
c7cb8acb 6572Remote serial target in GDB-specific protocol. The argument @var{dev}
70b88761 6573specifies what serial device to use for the connection (e.g.
1041a570 6574@file{/dev/ttya}). @xref{Remote, ,Remote Debugging}.
0f153e74 6575_fi__(_REMOTESTUB__)
70b88761
RP
6576
6577_if__(_AMD29K__)
6578@item target amd-eb @var{dev} @var{speed} @var{PROG}
6579@kindex target amd-eb
6580@cindex AMD EB29K
6581Remote PC-resident AMD EB29K board, attached over serial lines.
6582@var{dev} is the serial device, as for @code{target remote};
6583@var{speed} allows you to specify the linespeed; and @var{PROG} is the
6584name of the program to be debugged, as it appears to DOS on the PC.
77fe5411
RP
6585@xref{EB29K Remote, ,_GDBN__ with a Remote EB29K}.
6586
70b88761 6587_fi__(_AMD29K__)
c7cb8acb
RP
6588_if__(_H8__)
6589@item target hms
6590@kindex target hms
6591A Hitachi H8/300 board, attached via serial line to your host. Use
6592special commands @code{device} and @code{speed} to control the serial
6593line and the communications speed used. @xref{Hitachi H8/300
6594Remote,,_GDBN__ and the Hitachi H8/300}.
6595
6596_fi__(_H8__)
70b88761
RP
6597_if__(_I960__)
6598@item target nindy @var{devicename}
6599@kindex target nindy
6600An Intel 960 board controlled by a Nindy Monitor. @var{devicename} is
6601the name of the serial device to use for the connection, e.g.
1041a570 6602@file{/dev/ttya}. @xref{i960-Nindy Remote, ,_GDBN__ with a Remote i960 (Nindy)}.
70b88761
RP
6603
6604_fi__(_I960__)
77fe5411
RP
6605_if__(_ST2000__)
6606@item target st2000 @var{dev} @var{speed}
6607@kindex target st2000
6608A Tandem ST2000 phone switch, running Tandem's STDBUG protocol. @var{dev}
6609is the name of the device attached to the ST2000 serial line;
6610@var{speed} is the communication line speed. The arguments are not used
6611if _GDBN__ is configured to connect to the ST2000 using TCP or Telnet.
6612@xref{ST2000 Remote,,_GDBN__ with a Tandem ST2000}.
6613
6614_fi__(_ST2000__)
70b88761
RP
6615_if__(_VXWORKS__)
6616@item target vxworks @var{machinename}
6617@kindex target vxworks
6618A VxWorks system, attached via TCP/IP. The argument @var{machinename}
6619is the target system's machine name or IP address.
1041a570 6620@xref{VxWorks Remote, ,_GDBN__ and VxWorks}.
70b88761
RP
6621_fi__(_VXWORKS__)
6622@end table
6623
6624_if__(_GENERIC__)
6625Different targets are available on different configurations of _GDBN__; your
6626configuration may have more or fewer targets.
6627_fi__(_GENERIC__)
6628
4eb4cf57 6629@node Remote
70b88761
RP
6630@section Remote Debugging
6631@cindex remote debugging
6632
29a2b744 6633If you are trying to debug a program running on a machine that cannot run
c7cb8acb 6634GDB in the usual way, it is often useful to use remote debugging. For
70b88761
RP
6635example, you might use remote debugging on an operating system kernel, or on
6636a small system which does not have a general purpose operating system
e251e767 6637powerful enough to run a full-featured debugger.
70b88761 6638
c7cb8acb 6639Some configurations of GDB have special serial or TCP/IP interfaces
70b88761 6640to make this work with particular debugging targets. In addition,
c7cb8acb 6641GDB comes with a generic serial protocol (specific to GDB, but
70b88761
RP
6642not specific to any particular target system) which you can use if you
6643write the remote stubs---the code that will run on the remote system to
c7cb8acb 6644communicate with GDB.
70b88761 6645
70b88761 6646Other remote targets may be available in your
c7cb8acb 6647configuration of GDB; use @code{help targets} to list them.
70b88761
RP
6648
6649_if__(_GENERIC__)
1041a570
RP
6650_dnl__ Text on starting up GDB in various specific cases; it goes up front
6651_dnl__ in manuals configured for any of those particular situations, here
6652_dnl__ otherwise.
6653@menu
6654_include__(gdbinv-m.m4)<>_dnl__
6655@end menu
70b88761
RP
6656_include__(gdbinv-s.m4)
6657_fi__(_GENERIC__)
6658
4eb4cf57 6659@node Controlling _GDBN__
70b88761
RP
6660@chapter Controlling _GDBN__
6661
6662You can alter many aspects of _GDBN__'s interaction with you by using
6663the @code{set} command. For commands controlling how _GDBN__ displays
1041a570 6664data, @pxref{Print Settings, ,Print Settings}; other settings are described here.
70b88761
RP
6665
6666@menu
b80282d5
RP
6667* Prompt:: Prompt
6668* Editing:: Command Editing
6669* History:: Command History
6670* Screen Size:: Screen Size
6671* Numbers:: Numbers
6672* Messages/Warnings:: Optional Warnings and Messages
70b88761
RP
6673@end menu
6674
4eb4cf57 6675@node Prompt
70b88761
RP
6676@section Prompt
6677@cindex prompt
1041a570 6678
70b88761
RP
6679_GDBN__ indicates its readiness to read a command by printing a string
6680called the @dfn{prompt}. This string is normally @samp{(_GDBP__)}. You
6681can change the prompt string with the @code{set prompt} command. For
6682instance, when debugging _GDBN__ with _GDBN__, it is useful to change
6683the prompt in one of the _GDBN__<>s so that you can always tell which
6684one you are talking to.
6685
6686@table @code
6687@item set prompt @var{newprompt}
6688@kindex set prompt
6689Directs _GDBN__ to use @var{newprompt} as its prompt string henceforth.
6690@kindex show prompt
6691@item show prompt
6692Prints a line of the form: @samp{Gdb's prompt is: @var{your-prompt}}
6693@end table
6694
4eb4cf57 6695@node Editing
70b88761
RP
6696@section Command Editing
6697@cindex readline
6698@cindex command line editing
1041a570 6699
70b88761
RP
6700_GDBN__ reads its input commands via the @dfn{readline} interface. This
6701GNU library provides consistent behavior for programs which provide a
6702command line interface to the user. Advantages are @code{emacs}-style
6703or @code{vi}-style inline editing of commands, @code{csh}-like history
6704substitution, and a storage and recall of command history across
6705debugging sessions.
6706
6707You may control the behavior of command line editing in _GDBN__ with the
e251e767 6708command @code{set}.
70b88761
RP
6709
6710@table @code
6711@kindex set editing
6712@cindex editing
6713@item set editing
6714@itemx set editing on
6715Enable command line editing (enabled by default).
6716
6717@item set editing off
6718Disable command line editing.
6719
6720@kindex show editing
6721@item show editing
6722Show whether command line editing is enabled.
6723@end table
6724
4eb4cf57 6725@node History
70b88761 6726@section Command History
1041a570 6727
70b88761
RP
6728@table @code
6729@cindex history substitution
6730@cindex history file
6731@kindex set history filename
6732@item set history filename @var{fname}
6733Set the name of the _GDBN__ command history file to @var{fname}. This is
6734the file from which _GDBN__ will read an initial command history
6735list or to which it will write this list when it exits. This list is
6736accessed through history expansion or through the history
6737command editing characters listed below. This file defaults to the
6738value of the environment variable @code{GDBHISTFILE}, or to
6739@file{./.gdb_history} if this variable is not set.
6740
6741@cindex history save
6742@kindex set history save
6743@item set history save
6744@itemx set history save on
6745Record command history in a file, whose name may be specified with the
6746@code{set history filename} command. By default, this option is disabled.
6747
6748@item set history save off
6749Stop recording command history in a file.
6750
6751@cindex history size
6752@kindex set history size
6753@item set history size @var{size}
6754Set the number of commands which _GDBN__ will keep in its history list.
6755This defaults to the value of the environment variable
6756@code{HISTSIZE}, or to 256 if this variable is not set.
6757@end table
6758
6759@cindex history expansion
6760History expansion assigns special meaning to the character @kbd{!}.
6761@iftex
1041a570 6762@xref{Event Designators}.
70b88761
RP
6763@end iftex
6764Since @kbd{!} is also the logical not operator in C, history expansion
6765is off by default. If you decide to enable history expansion with the
6766@code{set history expansion on} command, you may sometimes need to
6767follow @kbd{!} (when it is used as logical not, in an expression) with
6768a space or a tab to prevent it from being expanded. The readline
6769history facilities will not attempt substitution on the strings
6770@kbd{!=} and @kbd{!(}, even when history expansion is enabled.
6771
6772The commands to control history expansion are:
6773
6774@table @code
6775
6776@kindex set history expansion
6777@item set history expansion on
6778@itemx set history expansion
6779Enable history expansion. History expansion is off by default.
6780
6781@item set history expansion off
6782Disable history expansion.
6783
6784The readline code comes with more complete documentation of
6785editing and history expansion features. Users unfamiliar with @code{emacs}
e251e767 6786or @code{vi} may wish to read it.
70b88761
RP
6787@iftex
6788@xref{Command Line Editing}.
6789@end iftex
6790
6791@c @group
6792@kindex show history
6793@item show history
6794@itemx show history filename
6795@itemx show history save
6796@itemx show history size
6797@itemx show history expansion
6798These commands display the state of the _GDBN__ history parameters.
6799@code{show history} by itself displays all four states.
6800@c @end group
70b88761
RP
6801@end table
6802
6803@table @code
6804@kindex show commands
6805@item show commands
6806Display the last ten commands in the command history.
6807
6808@item show commands @var{n}
6809Print ten commands centered on command number @var{n}.
6810
6811@item show commands +
6812Print ten commands just after the commands last printed.
70b88761
RP
6813@end table
6814
4eb4cf57 6815@node Screen Size
70b88761
RP
6816@section Screen Size
6817@cindex size of screen
6818@cindex pauses in output
1041a570 6819
70b88761
RP
6820Certain commands to _GDBN__ may produce large amounts of information
6821output to the screen. To help you read all of it, _GDBN__ pauses and
6822asks you for input at the end of each page of output. Type @key{RET}
6823when you want to continue the output. _GDBN__ also uses the screen
6824width setting to determine when to wrap lines of output. Depending on
6825what is being printed, it tries to break the line at a readable place,
6826rather than simply letting it overflow onto the following line.
6827
6828Normally _GDBN__ knows the size of the screen from the termcap data base
6829together with the value of the @code{TERM} environment variable and the
6830@code{stty rows} and @code{stty cols} settings. If this is not correct,
6831you can override it with the @code{set height} and @code{set
6832width} commands:
6833
6834@table @code
6835@item set height @var{lpp}
6836@itemx show height
6837@itemx set width @var{cpl}
6838@itemx show width
6839@kindex set height
6840@kindex set width
6841@kindex show width
6842@kindex show height
6843These @code{set} commands specify a screen height of @var{lpp} lines and
6844a screen width of @var{cpl} characters. The associated @code{show}
6845commands display the current settings.
6846
6847If you specify a height of zero lines, _GDBN__ will not pause during output
6848no matter how long the output is. This is useful if output is to a file
6849or to an editor buffer.
6850@end table
6851
4eb4cf57 6852@node Numbers
70b88761
RP
6853@section Numbers
6854@cindex number representation
6855@cindex entering numbers
1041a570 6856
70b88761
RP
6857You can always enter numbers in octal, decimal, or hexadecimal in _GDBN__ by
6858the usual conventions: octal numbers begin with @samp{0}, decimal
6859numbers end with @samp{.}, and hexadecimal numbers begin with @samp{0x}.
6860Numbers that begin with none of these are, by default, entered in base
686110; likewise, the default display for numbers---when no particular
6862format is specified---is base 10. You can change the default base for
6863both input and output with the @code{set radix} command.
6864
6865@table @code
6866@kindex set radix
6867@item set radix @var{base}
6868Set the default base for numeric input and display. Supported choices
c2bbbb22 6869for @var{base} are decimal 2, 8, 10, 16. @var{base} must itself be
70b88761
RP
6870specified either unambiguously or using the current default radix; for
6871example, any of
6872
6873@example
c2bbbb22 6874set radix 1010
70b88761
RP
6875set radix 012
6876set radix 10.
6877set radix 0xa
6878@end example
6879
6880@noindent
6881will set the base to decimal. On the other hand, @samp{set radix 10}
6882will leave the radix unchanged no matter what it was.
6883
6884@kindex show radix
6885@item show radix
6886Display the current default base for numeric input and display.
70b88761
RP
6887@end table
6888
4eb4cf57 6889@node Messages/Warnings
70b88761 6890@section Optional Warnings and Messages
1041a570 6891
70b88761
RP
6892By default, _GDBN__ is silent about its inner workings. If you are running
6893on a slow machine, you may want to use the @code{set verbose} command.
6894It will make _GDBN__ tell you when it does a lengthy internal operation, so
1041a570 6895you will not think it has crashed.
70b88761 6896
1041a570 6897Currently, the messages controlled by @code{set verbose} are those
d48da190
RP
6898which announce that the symbol table for a source file is being read;
6899see @code{symbol-file} in @ref{Files, ,Commands to Specify Files}.
70b88761
RP
6900
6901@table @code
6902@kindex set verbose
6903@item set verbose on
6904Enables _GDBN__'s output of certain informational messages.
6905
6906@item set verbose off
6907Disables _GDBN__'s output of certain informational messages.
6908
6909@kindex show verbose
6910@item show verbose
6911Displays whether @code{set verbose} is on or off.
6912@end table
6913
b80282d5
RP
6914By default, if _GDBN__ encounters bugs in the symbol table of an object
6915file, it is silent; but if you are debugging a compiler, you may find
1041a570 6916this information useful (@pxref{Symbol Errors, ,Errors Reading Symbol Files}).
70b88761
RP
6917
6918@table @code
6919@kindex set complaints
6920@item set complaints @var{limit}
6921Permits _GDBN__ to output @var{limit} complaints about each type of unusual
6922symbols before becoming silent about the problem. Set @var{limit} to
6923zero to suppress all complaints; set it to a large number to prevent
6924complaints from being suppressed.
6925
6926@kindex show complaints
6927@item show complaints
6928Displays how many symbol complaints _GDBN__ is permitted to produce.
6929@end table
6930
b21b18e1 6931By default, _GDBN__ is cautious, and asks what sometimes seems to be a
70b88761
RP
6932lot of stupid questions to confirm certain commands. For example, if
6933you try to run a program which is already running:
1041a570 6934
70b88761
RP
6935@example
6936(_GDBP__) run
6937The program being debugged has been started already.
e251e767 6938Start it from the beginning? (y or n)
70b88761
RP
6939@end example
6940
29a2b744 6941If you are willing to unflinchingly face the consequences of your own
70b88761
RP
6942commands, you can disable this ``feature'':
6943
6944@table @code
6945@kindex set confirm
6946@cindex flinching
6947@cindex confirmation
6948@cindex stupid questions
6949@item set confirm off
6950Disables confirmation requests.
6951
6952@item set confirm on
6953Enables confirmation requests (the default).
6954
6955@item show confirm
6956@kindex show confirm
6957Displays state of confirmation requests.
6958@end table
6959
29a2b744 6960@c FIXME this does not really belong here. But where *does* it belong?
b80282d5
RP
6961@cindex reloading symbols
6962Some systems allow individual object files that make up your program to
6963be replaced without stopping and restarting your program.
6964_if__(_VXWORKS__)
6965For example, in VxWorks you can simply recompile a defective object file
6966and keep on running.
6967_fi__(_VXWORKS__)
29a2b744 6968If you are running on one of these systems, you can allow _GDBN__ to
1041a570
RP
6969reload the symbols for automatically relinked modules:
6970
b80282d5
RP
6971@table @code
6972@kindex set symbol-reloading
6973@item set symbol-reloading on
6974Replace symbol definitions for the corresponding source file when an
6975object file with a particular name is seen again.
6976
6977@item set symbol-reloading off
1041a570 6978Do not replace symbol definitions when re-encountering object files of
29a2b744 6979the same name. This is the default state; if you are not running on a
b80282d5
RP
6980system that permits automatically relinking modules, you should leave
6981@code{symbol-reloading} off, since otherwise _GDBN__ may discard symbols
6982when linking large programs, that may contain several modules (from
6983different directories or libraries) with the same name.
6984
6985@item show symbol-reloading
6986Show the current @code{on} or @code{off} setting.
6987@end table
6988
4eb4cf57 6989@node Sequences
70b88761
RP
6990@chapter Canned Sequences of Commands
6991
29a2b744 6992Aside from breakpoint commands (@pxref{Break Commands, ,Breakpoint
1041a570
RP
6993Command Lists}), _GDBN__ provides two ways to store sequences of commands
6994for execution as a unit: user-defined commands and command files.
70b88761
RP
6995
6996@menu
b80282d5 6997* Define:: User-Defined Commands
35a15d60 6998* Hooks:: User-Defined Command Hooks
b80282d5
RP
6999* Command Files:: Command Files
7000* Output:: Commands for Controlled Output
70b88761
RP
7001@end menu
7002
4eb4cf57 7003@node Define
70b88761
RP
7004@section User-Defined Commands
7005
7006@cindex user-defined command
7007A @dfn{user-defined command} is a sequence of _GDBN__ commands to which you
7008assign a new name as a command. This is done with the @code{define}
7009command.
7010
7011@table @code
7012@item define @var{commandname}
7013@kindex define
7014Define a command named @var{commandname}. If there is already a command
7015by that name, you are asked to confirm that you want to redefine it.
7016
7017The definition of the command is made up of other _GDBN__ command lines,
7018which are given following the @code{define} command. The end of these
7019commands is marked by a line containing @code{end}.
7020
7021@item document @var{commandname}
7022@kindex document
7023Give documentation to the user-defined command @var{commandname}. The
7024command @var{commandname} must already be defined. This command reads
7025lines of documentation just as @code{define} reads the lines of the
7026command definition, ending with @code{end}. After the @code{document}
7027command is finished, @code{help} on command @var{commandname} will print
7028the documentation you have specified.
7029
7030You may use the @code{document} command again to change the
7031documentation of a command. Redefining the command with @code{define}
7032does not change the documentation.
7033
7034@item help user-defined
7035@kindex help user-defined
7036List all user-defined commands, with the first line of the documentation
7037(if any) for each.
7038
4768ba62
JG
7039@item show user
7040@itemx show user @var{commandname}
7041@kindex show user
70b88761
RP
7042Display the _GDBN__ commands used to define @var{commandname} (but not its
7043documentation). If no @var{commandname} is given, display the
7044definitions for all user-defined commands.
7045@end table
7046
7047User-defined commands do not take arguments. When they are executed, the
7048commands of the definition are not printed. An error in any command
7049stops execution of the user-defined command.
7050
7051Commands that would ask for confirmation if used interactively proceed
7052without asking when used inside a user-defined command. Many _GDBN__ commands
7053that normally print messages to say what they are doing omit the messages
7054when used in a user-defined command.
7055
35a15d60
JG
7056@node Hooks
7057@section User-Defined Command Hooks
7058@cindex command files
7059
7060You may define @emph{hooks}, which are a special kind of user-defined
7061command. Whenever you run the command @samp{foo}, if the user-defined
7062command @samp{hook-foo} exists, it is executed (with no arguments)
7063before that command.
7064
7065In addition, a pseudo-command, @samp{stop} exists. Hooking this command
7066will cause your hook to be executed every time execution stops in the
7067inferior program, before breakpoint commands are run, displays are
7068printed, or the stack frame is printed.
7069
7070For example, to cause @code{SIGALRM} signals to be ignored while
7071single-stepping, but cause them to be resumed during normal execution,
7072you could do:
7073
7074@example
7075define hook-stop
7076handle SIGALRM nopass
7077end
7078
7079define hook-run
7080handle SIGALRM pass
7081end
7082
7083define hook-continue
7084handle SIGLARM pass
7085end
7086@end example
7087
7088Any single-word command in GDB can be hooked. Aliases for other commands
7089cannot be hooked (you should hook the basic command name, e.g. @code{backtrace}
7090rather than @code{bt}). If an error occurs during the execution of your
7091hook, execution of GDB commands stops and you are returned to the GDB
7092prompt (before the command that you actually typed had a chance to run).
7093
7094If you try to define a hook which doesn't match any known command, you
7095will get a warning from the @code{define} command.
7096
4eb4cf57 7097@node Command Files
70b88761
RP
7098@section Command Files
7099
7100@cindex command files
7101A command file for _GDBN__ is a file of lines that are _GDBN__ commands. Comments
7102(lines starting with @kbd{#}) may also be included. An empty line in a
7103command file does nothing; it does not mean to repeat the last command, as
7104it would from the terminal.
7105
7106@cindex init file
7107@cindex @file{_GDBINIT__}
7108When you start _GDBN__, it automatically executes commands from its
1041a570
RP
7109@dfn{init files}. These are files named @file{_GDBINIT__}. _GDBN__ reads
7110the init file (if any) in your home directory and then the init file
7111(if any) in the current working directory. (The init files are not
7112executed if you use the @samp{-nx} option; @pxref{Mode Options,
7113,Choosing Modes}.) You can also request the execution of a command
7114file with the @code{source} command:
70b88761
RP
7115
7116@table @code
7117@item source @var{filename}
7118@kindex source
7119Execute the command file @var{filename}.
7120@end table
7121
7122The lines in a command file are executed sequentially. They are not
7123printed as they are executed. An error in any command terminates execution
7124of the command file.
7125
7126Commands that would ask for confirmation if used interactively proceed
7127without asking when used in a command file. Many _GDBN__ commands that
7128normally print messages to say what they are doing omit the messages
7129when called from command files.
7130
4eb4cf57 7131@node Output
70b88761
RP
7132@section Commands for Controlled Output
7133
7134During the execution of a command file or a user-defined command, normal
7135_GDBN__ output is suppressed; the only output that appears is what is
7136explicitly printed by the commands in the definition. This section
7137describes three commands useful for generating exactly the output you
7138want.
7139
7140@table @code
7141@item echo @var{text}
7142@kindex echo
29a2b744
RP
7143@c I do not consider backslash-space a standard C escape sequence
7144@c because it is not in ANSI.
1041a570
RP
7145Print @var{text}. Nonprinting characters can be included in
7146@var{text} using C escape sequences, such as @samp{\n} to print a
7147newline. @strong{No newline will be printed unless you specify one.}
7148In addition to the standard C escape sequences, a backslash followed
7149by a space stands for a space. This is useful for outputting a
7150string with spaces at the beginning or the end, since leading and
7151trailing spaces are otherwise trimmed from all arguments.
7152To print @samp{@w{ }and foo =@w{ }}, use the command
7153@samp{echo \@w{ }and foo = \@w{ }}.
70b88761
RP
7154
7155A backslash at the end of @var{text} can be used, as in C, to continue
7156the command onto subsequent lines. For example,
7157
7158@example
7159echo This is some text\n\
7160which is continued\n\
7161onto several lines.\n
7162@end example
7163
7164produces the same output as
7165
7166@example
7167echo This is some text\n
7168echo which is continued\n
7169echo onto several lines.\n
7170@end example
7171
7172@item output @var{expression}
7173@kindex output
7174Print the value of @var{expression} and nothing but that value: no
7175newlines, no @samp{$@var{nn} = }. The value is not entered in the
1041a570 7176value history either. @xref{Expressions, ,Expressions}, for more information on
e251e767 7177expressions.
70b88761
RP
7178
7179@item output/@var{fmt} @var{expression}
7180Print the value of @var{expression} in format @var{fmt}. You can use
7181the same formats as for @code{print}; @pxref{Output formats}, for more
7182information.
7183
7184@item printf @var{string}, @var{expressions}@dots{}
7185@kindex printf
7186Print the values of the @var{expressions} under the control of
7187@var{string}. The @var{expressions} are separated by commas and may
7188be either numbers or pointers. Their values are printed as specified
29a2b744 7189by @var{string}, exactly as if your program were to execute
70b88761
RP
7190
7191@example
7192printf (@var{string}, @var{expressions}@dots{});
7193@end example
7194
7195For example, you can print two values in hex like this:
7196
0fd24984 7197@smallexample
70b88761 7198printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo
0fd24984 7199@end smallexample
70b88761
RP
7200
7201The only backslash-escape sequences that you can use in the format
7202string are the simple ones that consist of backslash followed by a
7203letter.
7204@end table
7205
4eb4cf57
RP
7206_if__(!_DOSHOST__)
7207@node Emacs
70b88761
RP
7208@chapter Using _GDBN__ under GNU Emacs
7209
7210@cindex emacs
7211A special interface allows you to use GNU Emacs to view (and
7212edit) the source files for the program you are debugging with
7213_GDBN__.
7214
7215To use this interface, use the command @kbd{M-x gdb} in Emacs. Give the
7216executable file you want to debug as an argument. This command starts
7217_GDBN__ as a subprocess of Emacs, with input and output through a newly
7218created Emacs buffer.
7219
7220Using _GDBN__ under Emacs is just like using _GDBN__ normally except for two
7221things:
7222
7223@itemize @bullet
7224@item
e251e767 7225All ``terminal'' input and output goes through the Emacs buffer.
70b88761
RP
7226@end itemize
7227
7228This applies both to _GDBN__ commands and their output, and to the input
7229and output done by the program you are debugging.
7230
7231This is useful because it means that you can copy the text of previous
7232commands and input them again; you can even use parts of the output
7233in this way.
7234
3d3ab540
RP
7235All the facilities of Emacs' Shell mode are available for interacting
7236with your program. In particular, you can send signals the usual
7237way---for example, @kbd{C-c C-c} for an interrupt, @kbd{C-c C-z} for a
7238stop.
70b88761
RP
7239
7240@itemize @bullet
7241@item
e251e767 7242_GDBN__ displays source code through Emacs.
70b88761
RP
7243@end itemize
7244
7245Each time _GDBN__ displays a stack frame, Emacs automatically finds the
7246source file for that frame and puts an arrow (_0__@samp{=>}_1__) at the
7247left margin of the current line. Emacs uses a separate buffer for
7248source display, and splits the window to show both your _GDBN__ session
7249and the source.
7250
7251Explicit _GDBN__ @code{list} or search commands still produce output as
7252usual, but you probably will have no reason to use them.
7253
7254@quotation
7255@emph{Warning:} If the directory where your program resides is not your
7256current directory, it can be easy to confuse Emacs about the location of
7257the source files, in which case the auxiliary display buffer will not
7258appear to show your source. _GDBN__ can find programs by searching your
7259environment's @code{PATH} variable, so the _GDBN__ input and output
29a2b744 7260session will proceed normally; but Emacs does not get enough information
70b88761
RP
7261back from _GDBN__ to locate the source files in this situation. To
7262avoid this problem, either start _GDBN__ mode from the directory where
7263your program resides, or specify a full path name when prompted for the
7264@kbd{M-x gdb} argument.
7265
7266A similar confusion can result if you use the _GDBN__ @code{file} command to
7267switch to debugging a program in some other location, from an existing
7268_GDBN__ buffer in Emacs.
7269@end quotation
7270
7271By default, @kbd{M-x gdb} calls the program called @file{gdb}. If
7272you need to call _GDBN__ by a different name (for example, if you keep
7273several configurations around, with different names) you can set the
7274Emacs variable @code{gdb-command-name}; for example,
1041a570 7275
70b88761
RP
7276@example
7277(setq gdb-command-name "mygdb")
7278@end example
1041a570 7279
70b88761
RP
7280@noindent
7281(preceded by @kbd{ESC ESC}, or typed in the @code{*scratch*} buffer, or
7282in your @file{.emacs} file) will make Emacs call the program named
7283``@code{mygdb}'' instead.
7284
7285In the _GDBN__ I/O buffer, you can use these special Emacs commands in
7286addition to the standard Shell mode commands:
7287
7288@table @kbd
7289@item C-h m
7290Describe the features of Emacs' _GDBN__ Mode.
7291
7292@item M-s
7293Execute to another source line, like the _GDBN__ @code{step} command; also
7294update the display window to show the current file and location.
7295
7296@item M-n
7297Execute to next source line in this function, skipping all function
7298calls, like the _GDBN__ @code{next} command. Then update the display window
7299to show the current file and location.
7300
7301@item M-i
7302Execute one instruction, like the _GDBN__ @code{stepi} command; update
7303display window accordingly.
7304
7305@item M-x gdb-nexti
7306Execute to next instruction, using the _GDBN__ @code{nexti} command; update
7307display window accordingly.
7308
7309@item C-c C-f
7310Execute until exit from the selected stack frame, like the _GDBN__
7311@code{finish} command.
7312
7313@item M-c
29a2b744 7314Continue execution of your program, like the _GDBN__ @code{continue}
1041a570 7315command.
203eea5d
RP
7316
7317@emph{Warning:} In Emacs v19, this command is @kbd{C-c C-p}.
70b88761
RP
7318
7319@item M-u
7320Go up the number of frames indicated by the numeric argument
7321(@pxref{Arguments, , Numeric Arguments, emacs, The GNU Emacs Manual}),
1041a570 7322like the _GDBN__ @code{up} command.
203eea5d 7323
1041a570 7324@emph{Warning:} In Emacs v19, this command is @kbd{C-c C-u}.
70b88761
RP
7325
7326@item M-d
7327Go down the number of frames indicated by the numeric argument, like the
1041a570 7328_GDBN__ @code{down} command.
203eea5d
RP
7329
7330@emph{Warning:} In Emacs v19, this command is @kbd{C-c C-d}.
70b88761
RP
7331
7332@item C-x &
7333Read the number where the cursor is positioned, and insert it at the end
7334of the _GDBN__ I/O buffer. For example, if you wish to disassemble code
7335around an address that was displayed earlier, type @kbd{disassemble};
7336then move the cursor to the address display, and pick up the
e251e767 7337argument for @code{disassemble} by typing @kbd{C-x &}.
70b88761
RP
7338
7339You can customize this further on the fly by defining elements of the list
7340@code{gdb-print-command}; once it is defined, you can format or
7341otherwise process numbers picked up by @kbd{C-x &} before they are
c2bbbb22 7342inserted. A numeric argument to @kbd{C-x &} will both indicate that you
70b88761
RP
7343wish special formatting, and act as an index to pick an element of the
7344list. If the list element is a string, the number to be inserted is
7345formatted using the Emacs function @code{format}; otherwise the number
7346is passed as an argument to the corresponding list element.
70b88761
RP
7347@end table
7348
7349In any source file, the Emacs command @kbd{C-x SPC} (@code{gdb-break})
7350tells _GDBN__ to set a breakpoint on the source line point is on.
7351
7352If you accidentally delete the source-display buffer, an easy way to get
7353it back is to type the command @code{f} in the _GDBN__ buffer, to
7354request a frame display; when you run under Emacs, this will recreate
7355the source buffer if necessary to show you the context of the current
7356frame.
7357
7358The source files displayed in Emacs are in ordinary Emacs buffers
7359which are visiting the source files in the usual way. You can edit
7360the files with these buffers if you wish; but keep in mind that _GDBN__
7361communicates with Emacs in terms of line numbers. If you add or
7362delete lines from the text, the line numbers that _GDBN__ knows will cease
7363to correspond properly to the code.
7364
7365@c The following dropped because Epoch is nonstandard. Reactivate
7366@c if/when v19 does something similar. ---pesch@cygnus.com 19dec1990
7367@ignore
e251e767 7368@kindex emacs epoch environment
70b88761
RP
7369@kindex epoch
7370@kindex inspect
7371
7372Version 18 of Emacs has a built-in window system called the @code{epoch}
7373environment. Users of this environment can use a new command,
7374@code{inspect} which performs identically to @code{print} except that
7375each value is printed in its own window.
7376@end ignore
4eb4cf57 7377_fi__(!_DOSHOST__)
70b88761 7378
6ca72cc6 7379_if__(_LUCID__)
4eb4cf57 7380@node Energize
6ca72cc6
RP
7381@chapter Using _GDBN__ with Energize
7382
7383@cindex Energize
7384The Energize Programming System is an integrated development environment
7385that includes a point-and-click interface to many programming tools.
7386When you use _GDBN__ in this environment, you can use the standard
7387Energize graphical interface to drive _GDBN__; you can also, if you
7388choose, type _GDBN__ commands as usual in a debugging window. Even if
7389you use the graphical interface, the debugging window (which uses Emacs,
7390and resembles the standard Emacs interface to _GDBN__) displays the
7391equivalent commands, so that the history of your debugging session is
7392properly reflected.
7393
7394When Energize starts up a _GDBN__ session, it uses one of the
7395command-line options @samp{-energize} or @samp{-cadillac} (``cadillac''
7396is the name of the communications protocol used by the Energize system).
7397This option makes _GDBN__ run as one of the tools in the Energize Tool
7398Set: it sends all output to the Energize kernel, and accept input from
7399it as well.
7400
7401See the user manual for the Energize Programming System for
7402information on how to use the Energize graphical interface and the other
7403development tools that Energize integrates with _GDBN__.
7404
6ca72cc6 7405_fi__(_LUCID__)
4eb4cf57
RP
7406
7407@node _GDBN__ Bugs
70b88761
RP
7408@chapter Reporting Bugs in _GDBN__
7409@cindex Bugs in _GDBN__
7410@cindex Reporting Bugs in _GDBN__
7411
7412Your bug reports play an essential role in making _GDBN__ reliable.
7413
7414Reporting a bug may help you by bringing a solution to your problem, or it
7415may not. But in any case the principal function of a bug report is to help
7416the entire community by making the next version of _GDBN__ work better. Bug
7417reports are your contribution to the maintenance of _GDBN__.
7418
7419In order for a bug report to serve its purpose, you must include the
7420information that enables us to fix the bug.
7421
7422@menu
b80282d5
RP
7423* Bug Criteria:: Have You Found a Bug?
7424* Bug Reporting:: How to Report Bugs
70b88761
RP
7425@end menu
7426
4eb4cf57 7427@node Bug Criteria
70b88761
RP
7428@section Have You Found a Bug?
7429@cindex Bug Criteria
7430
7431If you are not sure whether you have found a bug, here are some guidelines:
7432
7433@itemize @bullet
7434@item
0f153e74
RP
7435@cindex fatal signal
7436@cindex core dump
70b88761
RP
7437If the debugger gets a fatal signal, for any input whatever, that is a
7438_GDBN__ bug. Reliable debuggers never crash.
7439
7440@item
0f153e74 7441@cindex error on valid input
70b88761
RP
7442If _GDBN__ produces an error message for valid input, that is a bug.
7443
7444@item
7445@cindex Invalid Input
7446If _GDBN__ does not produce an error message for invalid input,
7447that is a bug. However, you should note that your idea of
7448``invalid input'' might be our idea of ``an extension'' or ``support
7449for traditional practice''.
7450
7451@item
7452If you are an experienced user of debugging tools, your suggestions
7453for improvement of _GDBN__ are welcome in any case.
7454@end itemize
7455
4eb4cf57 7456@node Bug Reporting
70b88761 7457@section How to Report Bugs
0f153e74
RP
7458@cindex bug reports
7459@cindex _GDBN__ bugs, reporting
70b88761
RP
7460
7461A number of companies and individuals offer support for GNU products.
7462If you obtained _GDBN__ from a support organization, we recommend you
e251e767 7463contact that organization first.
70b88761
RP
7464
7465Contact information for many support companies and individuals is
7466available in the file @file{etc/SERVICE} in the GNU Emacs distribution.
7467
7468In any event, we also recommend that you send bug reports for _GDBN__ to one
7469of these addresses:
7470
7471@example
7472bug-gdb@@prep.ai.mit.edu
7473@{ucbvax|mit-eddie|uunet@}!prep.ai.mit.edu!bug-gdb
7474@end example
7475
7476@strong{Do not send bug reports to @samp{info-gdb}, or to
7477@samp{help-gdb}, or to any newsgroups.} Most users of _GDBN__ do not want to
7478receive bug reports. Those that do, have arranged to receive @samp{bug-gdb}.
7479
3d3ab540
RP
7480The mailing list @samp{bug-gdb} has a newsgroup @samp{gnu.gdb.bug} which
7481serves as a repeater. The mailing list and the newsgroup carry exactly
7482the same messages. Often people think of posting bug reports to the
7483newsgroup instead of mailing them. This appears to work, but it has one
7484problem which can be crucial: a newsgroup posting often lacks a mail
7485path back to the sender. Thus, if we need to ask for more information,
7486we may be unable to reach you. For this reason, it is better to send
7487bug reports to the mailing list.
70b88761
RP
7488
7489As a last resort, send bug reports on paper to:
7490
7491@example
7492GNU Debugger Bugs
3d3ab540 7493Free Software Foundation
70b88761
RP
7494545 Tech Square
7495Cambridge, MA 02139
7496@end example
7497
7498The fundamental principle of reporting bugs usefully is this:
7499@strong{report all the facts}. If you are not sure whether to state a
7500fact or leave it out, state it!
7501
7502Often people omit facts because they think they know what causes the
29a2b744 7503problem and assume that some details do not matter. Thus, you might
70b88761 7504assume that the name of the variable you use in an example does not matter.
29a2b744 7505Well, probably it does not, but one cannot be sure. Perhaps the bug is a
70b88761
RP
7506stray memory reference which happens to fetch from the location where that
7507name is stored in memory; perhaps, if the name were different, the contents
7508of that location would fool the debugger into doing the right thing despite
7509the bug. Play it safe and give a specific, complete example. That is the
7510easiest thing for you to do, and the most helpful.
7511
7512Keep in mind that the purpose of a bug report is to enable us to fix
1041a570 7513the bug if it is new to us. It is not as important as what happens if
70b88761
RP
7514the bug is already known. Therefore, always write your bug reports on
7515the assumption that the bug has not been reported previously.
7516
7517Sometimes people give a few sketchy facts and ask, ``Does this ring a
7518bell?'' Those bug reports are useless, and we urge everyone to
7519@emph{refuse to respond to them} except to chide the sender to report
7520bugs properly.
7521
7522To enable us to fix the bug, you should include all these things:
7523
7524@itemize @bullet
7525@item
7526The version of _GDBN__. _GDBN__ announces it if you start with no
7527arguments; you can also print it at any time using @code{show version}.
7528
1041a570 7529Without this, we will not know whether there is any point in looking for
70b88761
RP
7530the bug in the current version of _GDBN__.
7531
7532@item
ddf21240
JG
7533The type of machine you are using, and the operating system name and
7534version number.
70b88761
RP
7535
7536@item
7537What compiler (and its version) was used to compile _GDBN__---e.g.
c7cb8acb 7538``_GCC__-2.0''.
70b88761 7539
ddf21240
JG
7540@item
7541What compiler (and its version) was used to compile the program you
c7cb8acb 7542are debugging---e.g. ``_GCC__-2.0''.
ddf21240 7543
70b88761
RP
7544@item
7545The command arguments you gave the compiler to compile your example and
7546observe the bug. For example, did you use @samp{-O}? To guarantee
1041a570 7547you will not omit something important, list them all. A copy of the
ddf21240 7548Makefile (or the output from make) is sufficient.
70b88761
RP
7549
7550If we were to try to guess the arguments, we would probably guess wrong
7551and then we might not encounter the bug.
7552
7553@item
ddf21240
JG
7554A complete input script, and all necessary source files, that will
7555reproduce the bug.
70b88761
RP
7556
7557@item
7558A description of what behavior you observe that you believe is
7559incorrect. For example, ``It gets a fatal signal.''
7560
7561Of course, if the bug is that _GDBN__ gets a fatal signal, then we will
7562certainly notice it. But if the bug is incorrect output, we might not
7563notice unless it is glaringly wrong. We are human, after all. You
7564might as well not give us a chance to make a mistake.
7565
7566Even if the problem you experience is a fatal signal, you should still
7567say so explicitly. Suppose something strange is going on, such as,
7568your copy of _GDBN__ is out of synch, or you have encountered a
7569bug in the C library on your system. (This has happened!) Your copy
7570might crash and ours would not. If you told us to expect a crash,
7571then when ours fails to crash, we would know that the bug was not
7572happening for us. If you had not told us to expect a crash, then we
7573would not be able to draw any conclusion from our observations.
7574
7575@item
7576If you wish to suggest changes to the _GDBN__ source, send us context
7577diffs. If you even discuss something in the _GDBN__ source, refer to
7578it by context, not by line number.
7579
1041a570 7580The line numbers in our development sources will not match those in your
70b88761 7581sources. Your line numbers would convey no useful information to us.
70b88761
RP
7582@end itemize
7583
7584Here are some things that are not necessary:
7585
7586@itemize @bullet
7587@item
7588A description of the envelope of the bug.
7589
7590Often people who encounter a bug spend a lot of time investigating
7591which changes to the input file will make the bug go away and which
7592changes will not affect it.
7593
7594This is often time consuming and not very useful, because the way we
7595will find the bug is by running a single example under the debugger
7596with breakpoints, not by pure deduction from a series of examples.
7597We recommend that you save your time for something else.
7598
7599Of course, if you can find a simpler example to report @emph{instead}
7600of the original one, that is a convenience for us. Errors in the
7601output will be easier to spot, running under the debugger will take
e251e767 7602less time, etc.
70b88761 7603
29a2b744 7604However, simplification is not vital; if you do not want to do this,
70b88761
RP
7605report the bug anyway and send us the entire test case you used.
7606
7607@item
7608A patch for the bug.
7609
29a2b744 7610A patch for the bug does help us if it is a good one. But do not omit
70b88761
RP
7611the necessary information, such as the test case, on the assumption that
7612a patch is all we need. We might see problems with your patch and decide
7613to fix the problem another way, or we might not understand it at all.
7614
7615Sometimes with a program as complicated as _GDBN__ it is very hard to
7616construct an example that will make the program follow a certain path
1041a570
RP
7617through the code. If you do not send us the example, we will not be able
7618to construct one, so we will not be able to verify that the bug is fixed.
70b88761 7619
29a2b744 7620And if we cannot understand what bug you are trying to fix, or why your
1041a570 7621patch should be an improvement, we will not install it. A test case will
70b88761
RP
7622help us to understand.
7623
7624@item
7625A guess about what the bug is or what it depends on.
7626
29a2b744 7627Such guesses are usually wrong. Even we cannot guess right about such
70b88761
RP
7628things without first using the debugger to find the facts.
7629@end itemize
7630
1041a570
RP
7631@c Note: no need to update nodes for rdl-apps.texi since it appears
7632@c *only* in the TeX version of the manual.
7633@c Note: eventually, make a cross reference to the readline Info nodes.
70b88761 7634@iftex
cacf5942
RP
7635@c appendices describing GNU readline. Distributed with readline code.
7636@include rluser.texinfo
7637@include inc-hist.texi
70b88761
RP
7638@end iftex
7639
4eb4cf57
RP
7640_if__(_GENERIC__||!_H8__)
7641@node Renamed Commands
70b88761
RP
7642@appendix Renamed Commands
7643
c7cb8acb 7644The following commands were renamed in GDB 4, in order to make the
70b88761
RP
7645command set as a whole more consistent and easier to use and remember:
7646
e251e767
RP
7647@kindex add-syms
7648@kindex delete environment
7649@kindex info copying
7650@kindex info convenience
7651@kindex info directories
7652@kindex info editing
7653@kindex info history
7654@kindex info targets
7655@kindex info values
7656@kindex info version
7657@kindex info warranty
7658@kindex set addressprint
7659@kindex set arrayprint
7660@kindex set prettyprint
7661@kindex set screen-height
7662@kindex set screen-width
7663@kindex set unionprint
7664@kindex set vtblprint
7665@kindex set demangle
7666@kindex set asm-demangle
7667@kindex set sevenbit-strings
7668@kindex set array-max
7669@kindex set caution
7670@kindex set history write
7671@kindex show addressprint
7672@kindex show arrayprint
7673@kindex show prettyprint
7674@kindex show screen-height
7675@kindex show screen-width
7676@kindex show unionprint
7677@kindex show vtblprint
7678@kindex show demangle
7679@kindex show asm-demangle
7680@kindex show sevenbit-strings
7681@kindex show array-max
7682@kindex show caution
7683@kindex show history write
7684@kindex unset
70b88761 7685
92b73793 7686@c TEXI2ROFF-KILL
70b88761 7687@ifinfo
92b73793 7688@c END TEXI2ROFF-KILL
cf496415
RP
7689@example
7690OLD COMMAND NEW COMMAND
92b73793 7691@c TEXI2ROFF-KILL
cf496415 7692--------------- -------------------------------
92b73793 7693@c END TEXI2ROFF-KILL
cf496415
RP
7694add-syms add-symbol-file
7695delete environment unset environment
7696info convenience show convenience
7697info copying show copying
e251e767 7698info directories show directories
cf496415
RP
7699info editing show commands
7700info history show values
7701info targets help target
7702info values show values
7703info version show version
7704info warranty show warranty
7705set/show addressprint set/show print address
7706set/show array-max set/show print elements
7707set/show arrayprint set/show print array
7708set/show asm-demangle set/show print asm-demangle
7709set/show caution set/show confirm
7710set/show demangle set/show print demangle
7711set/show history write set/show history save
7712set/show prettyprint set/show print pretty
7713set/show screen-height set/show height
7714set/show screen-width set/show width
7715set/show sevenbit-strings set/show print sevenbit-strings
7716set/show unionprint set/show print union
7717set/show vtblprint set/show print vtbl
7718
7719unset [No longer an alias for delete]
7720@end example
92b73793 7721@c TEXI2ROFF-KILL
70b88761
RP
7722@end ifinfo
7723
7724@tex
7725\vskip \parskip\vskip \baselineskip
7726\halign{\tt #\hfil &\qquad#&\tt #\hfil\cr
7727{\bf Old Command} &&{\bf New Command}\cr
7728add-syms &&add-symbol-file\cr
7729delete environment &&unset environment\cr
7730info convenience &&show convenience\cr
7731info copying &&show copying\cr
7732info directories &&show directories \cr
7733info editing &&show commands\cr
7734info history &&show values\cr
7735info targets &&help target\cr
7736info values &&show values\cr
7737info version &&show version\cr
7738info warranty &&show warranty\cr
7739set{\rm / }show addressprint &&set{\rm / }show print address\cr
7740set{\rm / }show array-max &&set{\rm / }show print elements\cr
7741set{\rm / }show arrayprint &&set{\rm / }show print array\cr
7742set{\rm / }show asm-demangle &&set{\rm / }show print asm-demangle\cr
7743set{\rm / }show caution &&set{\rm / }show confirm\cr
7744set{\rm / }show demangle &&set{\rm / }show print demangle\cr
7745set{\rm / }show history write &&set{\rm / }show history save\cr
7746set{\rm / }show prettyprint &&set{\rm / }show print pretty\cr
7747set{\rm / }show screen-height &&set{\rm / }show height\cr
7748set{\rm / }show screen-width &&set{\rm / }show width\cr
7749set{\rm / }show sevenbit-strings &&set{\rm / }show print sevenbit-strings\cr
7750set{\rm / }show unionprint &&set{\rm / }show print union\cr
7751set{\rm / }show vtblprint &&set{\rm / }show print vtbl\cr
7752\cr
7753unset &&\rm(No longer an alias for delete)\cr
7754}
7755@end tex
92b73793 7756@c END TEXI2ROFF-KILL
4eb4cf57 7757_fi__(_GENERIC__||!_H8__)
70b88761 7758
0f153e74 7759_if__(!_PRECONFIGURED__)
4eb4cf57 7760@node Formatting Documentation
77b46d13
JG
7761@appendix Formatting the Documentation
7762
7763@cindex GDB reference card
7764@cindex reference card
7765The GDB 4 release includes an already-formatted reference card, ready
b1385986 7766for printing with PostScript or GhostScript, in the @file{gdb}
77b46d13 7767subdirectory of the main source directory---in
b1385986
RP
7768@file{gdb-_GDB_VN__/gdb/refcard.ps} of the version _GDB_VN__ release.
7769If you can use PostScript or GhostScript with your printer, you can
7770print the reference card immediately with @file{refcard.ps}.
77b46d13
JG
7771
7772The release also includes the source for the reference card. You
7773can format it, using @TeX{}, by typing:
7774
7775@example
7776make refcard.dvi
7777@end example
7778
7779The GDB reference card is designed to print in landscape mode on US
7780``letter'' size paper; that is, on a sheet 11 inches wide by 8.5 inches
7781high. You will need to specify this form of printing as an option to
7782your @sc{dvi} output program.
7783
7784@cindex documentation
7785
7786All the documentation for GDB comes as part of the machine-readable
7787distribution. The documentation is written in Texinfo format, which is
7788a documentation system that uses a single source file to produce both
7789on-line information and a printed manual. You can use one of the Info
7790formatting commands to create the on-line version of the documentation
7791and @TeX{} (or @code{texi2roff}) to typeset the printed version.
7792
7793GDB includes an already formatted copy of the on-line Info version of
7794this manual in the @file{gdb} subdirectory. The main Info file is
7795@file{gdb-@var{version-number}/gdb/gdb.info}, and it refers to
a89f94c2
RP
7796subordinate files matching @samp{gdb.info*} in the same directory. If
7797necessary, you can print out these files, or read them with any editor;
7798but they are easier to read using the @code{info} subsystem in GNU Emacs
7799or the standalone @code{info} program, available as part of the GNU
7800Texinfo distribution.
77b46d13
JG
7801
7802If you want to format these Info files yourself, you need one of the
7803Info formatting programs, such as @code{texinfo-format-buffer} or
7804@code{makeinfo}.
7805
7806If you have @code{makeinfo} installed, and are in the top level GDB
7807source directory (@file{gdb-_GDB_VN__}, in the case of version _GDB_VN__), you can
7808make the Info file by typing:
7809
7810@example
7811cd gdb
7812make gdb.info
7813@end example
7814
7815If you want to typeset and print copies of this manual, you need
7816@TeX{}, a printing program such as @code{lpr}, and @file{texinfo.tex},
7817the Texinfo definitions file.
7818
83bfcbae 7819@TeX{} is a typesetting program; it does not print files directly, but
77b46d13
JG
7820produces output files called @sc{dvi} files. To print a typeset
7821document, you need a program to print @sc{dvi} files. If your system
7822has @TeX{} installed, chances are it has such a program. The precise
7823command to use depends on your system; @kbd{lpr -d} is common; another
7824is @kbd{dvips}. The @sc{dvi} print command may require a file name
7825without any extension or a @samp{.dvi} extension.
7826
7827@TeX{} also requires a macro definitions file called
7828@file{texinfo.tex}. This file tells @TeX{} how to typeset a document
7829written in Texinfo format. On its own, @TeX{} cannot read, much less
7830typeset a Texinfo file. @file{texinfo.tex} is distributed with GDB
7831and is located in the @file{gdb-@var{version-number}/texinfo}
7832directory.
7833
7834If you have @TeX{} and a @sc{dvi} printer program installed, you can
7835typeset and print this manual. First switch to the the @file{gdb}
7836subdirectory of the main source directory (for example, to
7837@file{gdb-_GDB_VN__/gdb}) and then type:
7838
7839@example
7840make gdb.dvi
7841@end example
7842
4eb4cf57 7843@node Installing GDB
c7cb8acb
RP
7844@appendix Installing GDB
7845@cindex configuring GDB
70b88761
RP
7846@cindex installation
7847
f672bb7f
RP
7848@iftex
7849@c irrelevant in info file; it's as current as the code it lives with.
7850@quotation
7851@emph{Warning:} These installation instructions are current as of
c7cb8acb
RP
7852GDB version _GDB_VN__. If you're installing a more recent release
7853of GDB, we may have improved the installation procedures since
f672bb7f
RP
7854printing this manual; see the @file{README} file included in your
7855release for the most recent instructions.
7856@end quotation
7857@end iftex
7858
c7cb8acb
RP
7859GDB comes with a @code{configure} script that automates the process
7860of preparing GDB for installation; you can then use @code{make} to
7861build the program.
b80282d5 7862
c7cb8acb 7863The GDB distribution includes all the source code you need for GDB in
1041a570
RP
7864a single directory, whose name is usually composed by appending the
7865version number to @samp{gdb}.
7866
c7cb8acb 7867For example, the GDB version _GDB_VN__ distribution is in the @file{gdb-_GDB_VN__}
1041a570 7868directory. That directory contains:
b80282d5 7869
3d3ab540 7870@table @code
c7637ea6 7871@item gdb-_GDB_VN__/configure @r{(and supporting files)}
c7cb8acb 7872script for configuring GDB and all its supporting libraries.
b80282d5 7873
3e0d0a27 7874@item gdb-_GDB_VN__/gdb
c7cb8acb 7875the source specific to GDB itself
3d3ab540 7876
3e0d0a27 7877@item gdb-_GDB_VN__/bfd
77b46d13 7878source for the Binary File Descriptor library
3d3ab540 7879
3e0d0a27 7880@item gdb-_GDB_VN__/include
b80282d5 7881GNU include files
3d3ab540 7882
3e0d0a27 7883@item gdb-_GDB_VN__/libiberty
3d3ab540
RP
7884source for the @samp{-liberty} free software library
7885
3214c51c
JG
7886@item gdb-_GDB_VN__/opcodes
7887source for the library of opcode tables and disassemblers
7888
3e0d0a27 7889@item gdb-_GDB_VN__/readline
b80282d5 7890source for the GNU command-line interface
77b46d13
JG
7891
7892@item gdb-_GDB_VN__/glob
7893source for the GNU filename pattern-matching subroutine
7894
7895@item gdb-_GDB_VN__/mmalloc
7896source for the GNU memory-mapped malloc package
3d3ab540 7897@end table
1041a570 7898
c7cb8acb 7899The simplest way to configure and build GDB is to run @code{configure}
1041a570
RP
7900from the @file{gdb-@var{version-number}} source directory, which in
7901this example is the @file{gdb-_GDB_VN__} directory.
7902
7903First switch to the @file{gdb-@var{version-number}} source directory
7904if you are not already in it; then run @code{configure}. Pass the
c7cb8acb 7905identifier for the platform on which GDB will run as an
1041a570
RP
7906argument.
7907
7908For example:
7909
7463aadd 7910@example
3e0d0a27 7911cd gdb-_GDB_VN__
3d3ab540 7912./configure @var{host}
7463aadd
RP
7913make
7914@end example
1041a570 7915
7463aadd 7916@noindent
1041a570 7917where @var{host} is an identifier such as @samp{sun4} or
c7cb8acb 7918@samp{decstation}, that identifies the platform where GDB will run.
1041a570 7919
38962738
RP
7920Running @samp{configure @var{host}} followed by @code{make} builds the
7921@file{bfd}, @file{readline}, @file{mmalloc}, and @file{libiberty}
7922libraries, then @code{gdb} itself. The configured source files, and the
7923binaries, are left in the corresponding source directories.
3d3ab540 7924
e251e767 7925@code{configure} is a Bourne-shell (@code{/bin/sh}) script; if your
29a2b744 7926system does not recognize this automatically when you run a different
1041a570
RP
7927shell, you may need to run @code{sh} on it explicitly:
7928
7929@example
7930sh configure @var{host}
7931@end example
e251e767 7932
f672bb7f
RP
7933If you run @code{configure} from a directory that contains source
7934directories for multiple libraries or programs, such as the
7935@file{gdb-_GDB_VN__} source directory for version _GDB_VN__, @code{configure}
7936creates configuration files for every directory level underneath (unless
98349959 7937you tell it not to, with the @samp{--norecursion} option).
f672bb7f
RP
7938
7939You can run the @code{configure} script from any of the
c7cb8acb 7940subordinate directories in the GDB distribution, if you only want to
1041a570
RP
7941configure that subdirectory; but be sure to specify a path to it.
7942
7943For example, with version _GDB_VN__, type the following to configure only
7944the @code{bfd} subdirectory:
7945
e251e767 7946@example
203eea5d 7947@group
e251e767
RP
7948cd gdb-_GDB_VN__/bfd
7949../configure @var{host}
203eea5d 7950@end group
e251e767
RP
7951@end example
7952
1041a570
RP
7953You can install @code{_GDBP__} anywhere; it has no hardwired paths.
7954However, you should make sure that the shell on your path (named by
7955the @samp{SHELL} environment variable) is publicly readable. Remember
c7cb8acb
RP
7956that GDB uses the shell to start your program---some systems refuse to
7957let GDB debug child processes whose programs are not readable.
3d3ab540
RP
7958
7959@menu
c7cb8acb 7960* Separate Objdir:: Compiling GDB in another directory
b80282d5
RP
7961* Config Names:: Specifying names for hosts and targets
7962* configure Options:: Summary of options for configure
3d3ab540
RP
7963@end menu
7964
4eb4cf57 7965@node Separate Objdir
c7cb8acb 7966@section Compiling GDB in Another Directory
1041a570 7967
c7cb8acb
RP
7968If you want to run GDB versions for several host or target machines,
7969you'll need a different @code{gdb} compiled for each combination of
1041a570 7970host and target. @code{configure} is designed to make this easy by
f672bb7f
RP
7971allowing you to generate each configuration in a separate subdirectory,
7972rather than in the source directory. If your @code{make} program
7973handles the @samp{VPATH} feature (GNU @code{make} does), running
c7cb8acb 7974@code{make} in each of these directories then builds the @code{gdb}
f672bb7f 7975program specified there.
b80282d5 7976
c7cb8acb 7977To build @code{gdb} in a separate directory, run @code{configure}
f672bb7f 7978with the @samp{--srcdir} option to specify where to find the source.
77b46d13
JG
7979(You'll also need to specify a path to find @code{configure}
7980itself from your working directory. If the path to @code{configure}
7981would be the same as the argument to @samp{--srcdir}, you can leave out
7982the @samp{--srcdir} option; it will be assumed.)
1041a570 7983
c7cb8acb 7984For example, with version _GDB_VN__, you can build GDB in a separate
f672bb7f 7985directory for a Sun 4 like this:
70b88761
RP
7986
7987@example
3d3ab540 7988@group
3e0d0a27 7989cd gdb-_GDB_VN__
f672bb7f
RP
7990mkdir ../gdb-sun4
7991cd ../gdb-sun4
77b46d13 7992../gdb-_GDB_VN__/configure sun4
70b88761 7993make
3d3ab540 7994@end group
70b88761
RP
7995@end example
7996
f672bb7f
RP
7997When @code{configure} builds a configuration using a remote source
7998directory, it creates a tree for the binaries with the same structure
7999(and using the same names) as the tree under the source directory. In
8000the example, you'd find the Sun 4 library @file{libiberty.a} in the
c7cb8acb 8001directory @file{gdb-sun4/libiberty}, and GDB itself in
f672bb7f 8002@file{gdb-sun4/gdb}.
1041a570 8003
38962738 8004One popular reason to build several GDB configurations in separate
c7cb8acb 8005directories is to configure GDB for cross-compiling (where GDB
f672bb7f
RP
8006runs on one machine---the host---while debugging programs that run on
8007another machine---the target). You specify a cross-debugging target by
8008giving the @samp{--target=@var{target}} option to @code{configure}.
c7637ea6 8009
1041a570 8010When you run @code{make} to build a program or library, you must run
f672bb7f
RP
8011it in a configured directory---whatever directory you were in when you
8012called @code{configure} (or one of its subdirectories).
c7637ea6
RP
8013
8014The @code{Makefile} generated by @code{configure} for each source
f672bb7f
RP
8015directory also runs recursively. If you type @code{make} in a source
8016directory such as @file{gdb-_GDB_VN__} (or in a separate configured
8017directory configured with @samp{--srcdir=@var{path}/gdb-_GDB_VN__}), you
c7cb8acb 8018will build all the required libraries, then build GDB.
3d3ab540 8019
f672bb7f
RP
8020When you have multiple hosts or targets configured in separate
8021directories, you can run @code{make} on them in parallel (for example,
8022if they are NFS-mounted on each of the hosts); they will not interfere
8023with each other.
3d3ab540 8024
4eb4cf57 8025@node Config Names
b80282d5
RP
8026@section Specifying Names for Hosts and Targets
8027
8028The specifications used for hosts and targets in the @code{configure}
8029script are based on a three-part naming scheme, but some short predefined
8030aliases are also supported. The full naming scheme encodes three pieces
e251e767 8031of information in the following pattern:
1041a570 8032
b80282d5
RP
8033@example
8034@var{architecture}-@var{vendor}-@var{os}
8035@end example
8036
8037For example, you can use the alias @code{sun4} as a @var{host} argument
5e3186ab 8038or in a @code{--target=@var{target}} option, but the equivalent full name
e251e767 8039is @samp{sparc-sun-sunos4}.
b80282d5 8040
c7cb8acb 8041The @code{configure} script accompanying GDB does not provide
b80282d5
RP
8042any query facility to list all supported host and target names or
8043aliases. @code{configure} calls the Bourne shell script
8044@code{config.sub} to map abbreviations to full names; you can read the
8045script, if you wish, or you can use it to test your guesses on
8046abbreviations---for example:
1041a570 8047
b1385986 8048@smallexample
b80282d5 8049% sh config.sub sun4
6a8cb0e7 8050sparc-sun-sunos411
b80282d5 8051% sh config.sub sun3
6a8cb0e7 8052m68k-sun-sunos411
b80282d5 8053% sh config.sub decstation
6a8cb0e7 8054mips-dec-ultrix42
b80282d5
RP
8055% sh config.sub hp300bsd
8056m68k-hp-bsd
8057% sh config.sub i386v
6a8cb0e7 8058i386-unknown-sysv
e94b4a2b 8059% sh config.sub i786v
6a8cb0e7 8060Invalid configuration `i786v': machine `i786v' not recognized
b1385986 8061@end smallexample
1041a570 8062
c7637ea6 8063@noindent
1041a570
RP
8064@code{config.sub} is also distributed in the GDB source
8065directory (@file{gdb-_GDB_VN__}, for version _GDB_VN__).
b80282d5 8066
4eb4cf57 8067@node configure Options
3d3ab540 8068@section @code{configure} Options
7463aadd 8069
d48da190
RP
8070Here is a summary of the @code{configure} options and arguments that
8071are most often useful for building _GDBN__. @code{configure} also has
8072several other options not listed here. @inforef{What Configure
8073Does,,configure.info}, for a full explanation of @code{configure}.
8074@c FIXME: Would this be more, or less, useful as an xref (ref to printed
8075@c manual in the printed manual, ref to info file only from the info file)?
7463aadd
RP
8076
8077@example
d48da190
RP
8078configure @r{[}--help@r{]}
8079 @r{[}--prefix=@var{dir}@r{]}
8080 @r{[}--srcdir=@var{path}@r{]}
f672bb7f
RP
8081 @r{[}--norecursion@r{]} @r{[}--rm@r{]}
8082 @r{[}--target=@var{target}@r{]} @var{host}
7463aadd 8083@end example
1041a570 8084
3d3ab540 8085@noindent
f672bb7f
RP
8086You may introduce options with a single @samp{-} rather than
8087@samp{--} if you prefer; but you may abbreviate option names if you use
8088@samp{--}.
70b88761
RP
8089
8090@table @code
d48da190
RP
8091@item --help
8092Display a quick summary of how to invoke @code{configure}.
8093
8094@item -prefix=@var{dir}
8095Configure the source to install programs and files under directory
8096@file{@var{dir}}.
8097
f672bb7f 8098@item --srcdir=@var{path}
6ca72cc6
RP
8099@strong{Warning: using this option requires GNU @code{make}, or another
8100@code{make} that implements the @code{VPATH} feature.}@*
f672bb7f 8101Use this option to make configurations in directories separate from the
c7cb8acb 8102GDB source directories. Among other things, you can use this to
f672bb7f
RP
8103build (or maintain) several configurations simultaneously, in separate
8104directories. @code{configure} writes configuration specific files in
8105the current directory, but arranges for them to use the source in the
8106directory @var{path}. @code{configure} will create directories under
8107the working directory in parallel to the source directories below
8108@var{path}.
8109
8110@item --norecursion
8111Configure only the directory level where @code{configure} is executed; do not
7463aadd
RP
8112propagate configuration to subdirectories.
8113
f672bb7f 8114@item --rm
b80282d5 8115Remove the configuration that the other arguments specify.
7463aadd 8116
29a2b744 8117@c This does not work (yet if ever). FIXME.
f672bb7f 8118@c @item --parse=@var{lang} @dots{}
c7cb8acb
RP
8119@c Configure the GDB expression parser to parse the listed languages.
8120@c @samp{all} configures GDB for all supported languages. To get a
d7b569d5 8121@c list of all supported languages, omit the argument. Without this
c7cb8acb 8122@c option, GDB is configured to parse all supported languages.
c2bbbb22 8123
f672bb7f 8124@item --target=@var{target}
c7cb8acb
RP
8125Configure GDB for cross-debugging programs running on the specified
8126@var{target}. Without this option, GDB is configured to debug
8127programs that run on the same machine (@var{host}) as GDB itself.
b80282d5
RP
8128
8129There is no convenient way to generate a list of all available targets.
7463aadd
RP
8130
8131@item @var{host} @dots{}
c7cb8acb 8132Configure GDB to run on the specified @var{host}.
b80282d5
RP
8133
8134There is no convenient way to generate a list of all available hosts.
70b88761
RP
8135@end table
8136
3d3ab540
RP
8137@noindent
8138@code{configure} accepts other options, for compatibility with
b80282d5 8139configuring other GNU tools recursively; but these are the only
c7cb8acb 8140options that affect GDB or its supporting libraries.
0f153e74 8141_fi__(!_PRECONFIGURED__)
3d3ab540 8142
0f153e74 8143_if__(!_AGGLOMERATION__)
4eb4cf57 8144@node Copying
70b88761 8145@unnumbered GNU GENERAL PUBLIC LICENSE
7463aadd 8146@center Version 2, June 1991
70b88761
RP
8147
8148@display
7463aadd 8149Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc.
70b88761
RP
8150675 Mass Ave, Cambridge, MA 02139, USA
8151
8152Everyone is permitted to copy and distribute verbatim copies
8153of this license document, but changing it is not allowed.
8154@end display
8155
8156@unnumberedsec Preamble
8157
7463aadd
RP
8158 The licenses for most software are designed to take away your
8159freedom to share and change it. By contrast, the GNU General Public
70b88761 8160License is intended to guarantee your freedom to share and change free
7463aadd
RP
8161software---to make sure the software is free for all its users. This
8162General Public License applies to most of the Free Software
8163Foundation's software and to any other program whose authors commit to
8164using it. (Some other Free Software Foundation software is covered by
8165the GNU Library General Public License instead.) You can apply it to
8166your programs, too.
70b88761
RP
8167
8168 When we speak of free software, we are referring to freedom, not
7463aadd
RP
8169price. Our General Public Licenses are designed to make sure that you
8170have the freedom to distribute copies of free software (and charge for
8171this service if you wish), that you receive source code or can get it
8172if you want it, that you can change the software or use pieces of it
8173in new free programs; and that you know you can do these things.
70b88761
RP
8174
8175 To protect your rights, we need to make restrictions that forbid
8176anyone to deny you these rights or to ask you to surrender the rights.
8177These restrictions translate to certain responsibilities for you if you
8178distribute copies of the software, or if you modify it.
8179
7463aadd 8180 For example, if you distribute copies of such a program, whether
70b88761
RP
8181gratis or for a fee, you must give the recipients all the rights that
8182you have. You must make sure that they, too, receive or can get the
7463aadd
RP
8183source code. And you must show them these terms so they know their
8184rights.
70b88761
RP
8185
8186 We protect your rights with two steps: (1) copyright the software, and
8187(2) offer you this license which gives you legal permission to copy,
8188distribute and/or modify the software.
8189
8190 Also, for each author's protection and ours, we want to make certain
8191that everyone understands that there is no warranty for this free
8192software. If the software is modified by someone else and passed on, we
8193want its recipients to know that what they have is not the original, so
8194that any problems introduced by others will not reflect on the original
8195authors' reputations.
8196
7463aadd
RP
8197 Finally, any free program is threatened constantly by software
8198patents. We wish to avoid the danger that redistributors of a free
8199program will individually obtain patent licenses, in effect making the
8200program proprietary. To prevent this, we have made it clear that any
8201patent must be licensed for everyone's free use or not licensed at all.
8202
70b88761
RP
8203 The precise terms and conditions for copying, distribution and
8204modification follow.
8205
8206@iftex
7463aadd 8207@unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
70b88761
RP
8208@end iftex
8209@ifinfo
7463aadd 8210@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
70b88761
RP
8211@end ifinfo
8212
8213@enumerate
8214@item
7463aadd
RP
8215This License applies to any program or other work which contains
8216a notice placed by the copyright holder saying it may be distributed
8217under the terms of this General Public License. The ``Program'', below,
8218refers to any such program or work, and a ``work based on the Program''
8219means either the Program or any derivative work under copyright law:
8220that is to say, a work containing the Program or a portion of it,
8221either verbatim or with modifications and/or translated into another
8222language. (Hereinafter, translation is included without limitation in
8223the term ``modification''.) Each licensee is addressed as ``you''.
8224
8225Activities other than copying, distribution and modification are not
8226covered by this License; they are outside its scope. The act of
8227running the Program is not restricted, and the output from the Program
8228is covered only if its contents constitute a work based on the
8229Program (independent of having been made by running the Program).
8230Whether that is true depends on what the Program does.
70b88761
RP
8231
8232@item
7463aadd
RP
8233You may copy and distribute verbatim copies of the Program's
8234source code as you receive it, in any medium, provided that you
8235conspicuously and appropriately publish on each copy an appropriate
8236copyright notice and disclaimer of warranty; keep intact all the
8237notices that refer to this License and to the absence of any warranty;
8238and give any other recipients of the Program a copy of this License
8239along with the Program.
70b88761 8240
7463aadd
RP
8241You may charge a fee for the physical act of transferring a copy, and
8242you may at your option offer warranty protection in exchange for a fee.
70b88761 8243
70b88761 8244@item
7463aadd
RP
8245You may modify your copy or copies of the Program or any portion
8246of it, thus forming a work based on the Program, and copy and
8247distribute such modifications or work under the terms of Section 1
8248above, provided that you also meet all of these conditions:
70b88761 8249
1041a570 8250@enumerate a
70b88761 8251@item
7463aadd
RP
8252You must cause the modified files to carry prominent notices
8253stating that you changed the files and the date of any change.
70b88761
RP
8254
8255@item
7463aadd
RP
8256You must cause any work that you distribute or publish, that in
8257whole or in part contains or is derived from the Program or any
8258part thereof, to be licensed as a whole at no charge to all third
8259parties under the terms of this License.
70b88761
RP
8260
8261@item
7463aadd
RP
8262If the modified program normally reads commands interactively
8263when run, you must cause it, when started running for such
8264interactive use in the most ordinary way, to print or display an
8265announcement including an appropriate copyright notice and a
8266notice that there is no warranty (or else, saying that you provide
8267a warranty) and that users may redistribute the program under
8268these conditions, and telling the user how to view a copy of this
8269License. (Exception: if the Program itself is interactive but
8270does not normally print such an announcement, your work based on
8271the Program is not required to print an announcement.)
1041a570 8272@end enumerate
7463aadd
RP
8273
8274These requirements apply to the modified work as a whole. If
8275identifiable sections of that work are not derived from the Program,
8276and can be reasonably considered independent and separate works in
8277themselves, then this License, and its terms, do not apply to those
8278sections when you distribute them as separate works. But when you
8279distribute the same sections as part of a whole which is a work based
8280on the Program, the distribution of the whole must be on the terms of
8281this License, whose permissions for other licensees extend to the
8282entire whole, and thus to each and every part regardless of who wrote it.
8283
8284Thus, it is not the intent of this section to claim rights or contest
8285your rights to work written entirely by you; rather, the intent is to
8286exercise the right to control the distribution of derivative or
8287collective works based on the Program.
8288
8289In addition, mere aggregation of another work not based on the Program
8290with the Program (or with a work based on the Program) on a volume of
8291a storage or distribution medium does not bring the other work under
8292the scope of this License.
70b88761
RP
8293
8294@item
7463aadd
RP
8295You may copy and distribute the Program (or a work based on it,
8296under Section 2) in object code or executable form under the terms of
8297Sections 1 and 2 above provided that you also do one of the following:
70b88761 8298
1041a570 8299@enumerate a
70b88761 8300@item
7463aadd
RP
8301Accompany it with the complete corresponding machine-readable
8302source code, which must be distributed under the terms of Sections
83031 and 2 above on a medium customarily used for software interchange; or,
70b88761
RP
8304
8305@item
7463aadd
RP
8306Accompany it with a written offer, valid for at least three
8307years, to give any third party, for a charge no more than your
8308cost of physically performing source distribution, a complete
8309machine-readable copy of the corresponding source code, to be
8310distributed under the terms of Sections 1 and 2 above on a medium
8311customarily used for software interchange; or,
70b88761
RP
8312
8313@item
7463aadd
RP
8314Accompany it with the information you received as to the offer
8315to distribute corresponding source code. (This alternative is
70b88761 8316allowed only for noncommercial distribution and only if you
7463aadd
RP
8317received the program in object code or executable form with such
8318an offer, in accord with Subsection b above.)
1041a570 8319@end enumerate
7463aadd
RP
8320
8321The source code for a work means the preferred form of the work for
8322making modifications to it. For an executable work, complete source
8323code means all the source code for all modules it contains, plus any
8324associated interface definition files, plus the scripts used to
8325control compilation and installation of the executable. However, as a
8326special exception, the source code distributed need not include
8327anything that is normally distributed (in either source or binary
8328form) with the major components (compiler, kernel, and so on) of the
8329operating system on which the executable runs, unless that component
8330itself accompanies the executable.
8331
8332If distribution of executable or object code is made by offering
8333access to copy from a designated place, then offering equivalent
8334access to copy the source code from the same place counts as
8335distribution of the source code, even though third parties are not
8336compelled to copy the source along with the object code.
70b88761
RP
8337
8338@item
7463aadd
RP
8339You may not copy, modify, sublicense, or distribute the Program
8340except as expressly provided under this License. Any attempt
8341otherwise to copy, modify, sublicense or distribute the Program is
8342void, and will automatically terminate your rights under this License.
8343However, parties who have received copies, or rights, from you under
8344this License will not have their licenses terminated so long as such
8345parties remain in full compliance.
70b88761
RP
8346
8347@item
7463aadd
RP
8348You are not required to accept this License, since you have not
8349signed it. However, nothing else grants you permission to modify or
8350distribute the Program or its derivative works. These actions are
8351prohibited by law if you do not accept this License. Therefore, by
8352modifying or distributing the Program (or any work based on the
8353Program), you indicate your acceptance of this License to do so, and
8354all its terms and conditions for copying, distributing or modifying
8355the Program or works based on it.
70b88761
RP
8356
8357@item
8358Each time you redistribute the Program (or any work based on the
7463aadd
RP
8359Program), the recipient automatically receives a license from the
8360original licensor to copy, distribute or modify the Program subject to
8361these terms and conditions. You may not impose any further
8362restrictions on the recipients' exercise of the rights granted herein.
8363You are not responsible for enforcing compliance by third parties to
8364this License.
8365
8366@item
8367If, as a consequence of a court judgment or allegation of patent
8368infringement or for any other reason (not limited to patent issues),
8369conditions are imposed on you (whether by court order, agreement or
8370otherwise) that contradict the conditions of this License, they do not
8371excuse you from the conditions of this License. If you cannot
8372distribute so as to satisfy simultaneously your obligations under this
8373License and any other pertinent obligations, then as a consequence you
8374may not distribute the Program at all. For example, if a patent
8375license would not permit royalty-free redistribution of the Program by
8376all those who receive copies directly or indirectly through you, then
8377the only way you could satisfy both it and this License would be to
8378refrain entirely from distribution of the Program.
8379
8380If any portion of this section is held invalid or unenforceable under
8381any particular circumstance, the balance of the section is intended to
8382apply and the section as a whole is intended to apply in other
8383circumstances.
8384
8385It is not the purpose of this section to induce you to infringe any
8386patents or other property right claims or to contest validity of any
8387such claims; this section has the sole purpose of protecting the
8388integrity of the free software distribution system, which is
8389implemented by public license practices. Many people have made
8390generous contributions to the wide range of software distributed
8391through that system in reliance on consistent application of that
8392system; it is up to the author/donor to decide if he or she is willing
8393to distribute software through any other system and a licensee cannot
8394impose that choice.
8395
8396This section is intended to make thoroughly clear what is believed to
8397be a consequence of the rest of this License.
8398
8399@item
8400If the distribution and/or use of the Program is restricted in
8401certain countries either by patents or by copyrighted interfaces, the
8402original copyright holder who places the Program under this License
8403may add an explicit geographical distribution limitation excluding
8404those countries, so that distribution is permitted only in or among
8405countries not thus excluded. In such case, this License incorporates
8406the limitation as if written in the body of this License.
70b88761
RP
8407
8408@item
8409The Free Software Foundation may publish revised and/or new versions
8410of the General Public License from time to time. Such new versions will
8411be similar in spirit to the present version, but may differ in detail to
8412address new problems or concerns.
8413
8414Each version is given a distinguishing version number. If the Program
7463aadd 8415specifies a version number of this License which applies to it and ``any
70b88761
RP
8416later version'', you have the option of following the terms and conditions
8417either of that version or of any later version published by the Free
8418Software Foundation. If the Program does not specify a version number of
7463aadd 8419this License, you may choose any version ever published by the Free Software
70b88761
RP
8420Foundation.
8421
8422@item
8423If you wish to incorporate parts of the Program into other free
8424programs whose distribution conditions are different, write to the author
8425to ask for permission. For software which is copyrighted by the Free
8426Software Foundation, write to the Free Software Foundation; we sometimes
8427make exceptions for this. Our decision will be guided by the two goals
8428of preserving the free status of all derivatives of our free software and
8429of promoting the sharing and reuse of software generally.
8430
8431@iftex
8432@heading NO WARRANTY
8433@end iftex
8434@ifinfo
8435@center NO WARRANTY
8436@end ifinfo
8437
8438@item
8439BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
8440FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
8441OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
8442PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
8443OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
8444MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
8445TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
8446PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
8447REPAIR OR CORRECTION.
8448
8449@item
7463aadd
RP
8450IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
8451WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
70b88761 8452REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
7463aadd
RP
8453INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
8454OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
8455TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
8456YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
8457PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
8458POSSIBILITY OF SUCH DAMAGES.
70b88761
RP
8459@end enumerate
8460
8461@iftex
8462@heading END OF TERMS AND CONDITIONS
8463@end iftex
8464@ifinfo
8465@center END OF TERMS AND CONDITIONS
8466@end ifinfo
8467
8468@page
54e6b3c3 8469@unnumberedsec Applying These Terms to Your New Programs
70b88761
RP
8470
8471 If you develop a new program, and you want it to be of the greatest
7463aadd
RP
8472possible use to the public, the best way to achieve this is to make it
8473free software which everyone can redistribute and change under these terms.
70b88761 8474
7463aadd
RP
8475 To do so, attach the following notices to the program. It is safest
8476to attach them to the start of each source file to most effectively
8477convey the exclusion of warranty; and each file should have at least
8478the ``copyright'' line and a pointer to where the full notice is found.
70b88761
RP
8479
8480@smallexample
203eea5d 8481@var{one line to give the program's name and an idea of what it does.}
70b88761
RP
8482Copyright (C) 19@var{yy} @var{name of author}
8483
203eea5d
RP
8484This program is free software; you can redistribute it and/or
8485modify it under the terms of the GNU General Public License
8486as published by the Free Software Foundation; either version 2
8487of the License, or (at your option) any later version.
70b88761
RP
8488
8489This program is distributed in the hope that it will be useful,
8490but WITHOUT ANY WARRANTY; without even the implied warranty of
8491MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
8492GNU General Public License for more details.
8493
8494You should have received a copy of the GNU General Public License
203eea5d
RP
8495along with this program; if not, write to the
8496Free Software Foundation, Inc., 675 Mass Ave,
8497Cambridge, MA 02139, USA.
70b88761
RP
8498@end smallexample
8499
8500Also add information on how to contact you by electronic and paper mail.
8501
8502If the program is interactive, make it output a short notice like this
8503when it starts in an interactive mode:
8504
8505@smallexample
8506Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
203eea5d
RP
8507Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
8508type `show w'. This is free software, and you are welcome
8509to redistribute it under certain conditions; type `show c'
8510for details.
70b88761
RP
8511@end smallexample
8512
7463aadd
RP
8513The hypothetical commands @samp{show w} and @samp{show c} should show
8514the appropriate parts of the General Public License. Of course, the
8515commands you use may be called something other than @samp{show w} and
8516@samp{show c}; they could even be mouse-clicks or menu items---whatever
8517suits your program.
70b88761
RP
8518
8519You should also get your employer (if you work as a programmer) or your
8520school, if any, to sign a ``copyright disclaimer'' for the program, if
8521necessary. Here is a sample; alter the names:
8522
1041a570
RP
8523@example
8524Yoyodyne, Inc., hereby disclaims all copyright
8525interest in the program `Gnomovision'
8526(which makes passes at compilers) written
8527by James Hacker.
70b88761
RP
8528
8529@var{signature of Ty Coon}, 1 April 1989
8530Ty Coon, President of Vice
1041a570 8531@end example
7463aadd
RP
8532
8533This General Public License does not permit incorporating your program into
8534proprietary programs. If your program is a subroutine library, you may
8535consider it more useful to permit linking proprietary applications with the
8536library. If this is what you want to do, use the GNU Library General
8537Public License instead of this License.
0f153e74 8538_fi__(!_AGGLOMERATION__)
70b88761 8539
4eb4cf57 8540@node Index
d2e08421 8541@unnumbered Index
e91b87a3 8542
8543@printindex cp
8544
fe3f5fc8
RP
8545@tex
8546% I think something like @colophon should be in texinfo. In the
8547% meantime:
8548\long\def\colophon{\hbox to0pt{}\vfill
8549\centerline{The body of this manual is set in}
8550\centerline{\fontname\tenrm,}
8551\centerline{with headings in {\bf\fontname\tenbf}}
8552\centerline{and examples in {\tt\fontname\tentt}.}
a6d0b6d3
RP
8553\centerline{{\it\fontname\tenit\/},}
8554\centerline{{\bf\fontname\tenbf}, and}
fe3f5fc8
RP
8555\centerline{{\sl\fontname\tensl\/}}
8556\centerline{are used for emphasis.}\vfill}
8557\page\colophon
a6d0b6d3 8558% Blame: pesch@cygnus.com, 1991.
fe3f5fc8
RP
8559@end tex
8560
e91b87a3 8561@contents
8562@bye
This page took 0.549445 seconds and 4 git commands to generate.