]> git.ipfire.org Git - thirdparty/binutils-gdb.git/blame - gdb/doc/gdb.texinfo
import gdb-1999-08-23 snapshot
[thirdparty/binutils-gdb.git] / gdb / doc / gdb.texinfo
CommitLineData
c906108c
SS
1\input texinfo @c -*-texinfo-*-
2@c Copyright 1988-1999
3@c Free Software Foundation, Inc.
4@c
5@c %**start of header
6@c makeinfo ignores cmds prev to setfilename, so its arg cannot make use
7@c of @set vars. However, you can override filename with makeinfo -o.
8@setfilename gdb.info
9@c
10@include gdb-cfg.texi
11@c
c906108c 12@settitle Debugging with @value{GDBN}
c906108c
SS
13@setchapternewpage odd
14@c %**end of header
15
16@iftex
17@c @smallbook
18@c @cropmarks
19@end iftex
20
21@finalout
22@syncodeindex ky cp
23
24@c readline appendices use @vindex
25@syncodeindex vr cp
26
27@c !!set GDB manual's edition---not the same as GDB version!
28@set EDITION Seventh
29
30@c !!set GDB manual's revision date
31@set DATE February 1999
32
33@c THIS MANUAL REQUIRES TEXINFO-2 macros and info-makers to format properly.
34
35@ifinfo
36@c This is a dir.info fragment to support semi-automated addition of
37@c manuals to an info tree. zoo@cygnus.com is developing this facility.
38@format
39START-INFO-DIR-ENTRY
40* Gdb: (gdb). The @sc{gnu} debugger.
41END-INFO-DIR-ENTRY
42@end format
43@end ifinfo
44@c
45@c
46@ifinfo
47This file documents the @sc{gnu} debugger @value{GDBN}.
48
49
50This is the @value{EDITION} Edition, @value{DATE},
51of @cite{Debugging with @value{GDBN}: the @sc{gnu} Source-Level Debugger}
52for @value{GDBN} Version @value{GDBVN}.
53
54Copyright (C) 1988-1999 Free Software Foundation, Inc.
55
56Permission is granted to make and distribute verbatim copies of
57this manual provided the copyright notice and this permission notice
58are preserved on all copies.
59
60@ignore
61Permission is granted to process this file through TeX and print the
62results, provided the printed document carries copying permission
63notice identical to this one except for the removal of this paragraph
64(this paragraph not being relevant to the printed manual).
65
66@end ignore
67Permission is granted to copy and distribute modified versions of this
68manual under the conditions for verbatim copying, provided also that the
69entire resulting derived work is distributed under the terms of a
70permission notice identical to this one.
71
72Permission is granted to copy and distribute translations of this manual
73into another language, under the above conditions for modified versions.
74@end ifinfo
75
76@titlepage
77@title Debugging with @value{GDBN}
78@subtitle The @sc{gnu} Source-Level Debugger
c906108c 79@sp 1
c906108c
SS
80@subtitle @value{EDITION} Edition, for @value{GDBN} version @value{GDBVN}
81@subtitle @value{DATE}
82@author Richard M. Stallman and Roland H. Pesch
c906108c 83@page
c906108c
SS
84@tex
85{\parskip=0pt
53a5351d 86\hfill (Send bugs and comments on @value{GDBN} to bug-gdb\@gnu.org.)\par
c906108c
SS
87\hfill {\it Debugging with @value{GDBN}}\par
88\hfill \TeX{}info \texinfoversion\par
89}
90@end tex
53a5351d
JM
91
92@c ISBN seems to be wrong...
c906108c
SS
93
94@vskip 0pt plus 1filll
95Copyright @copyright{} 1988-1999 Free Software Foundation, Inc.
96@sp 2
c906108c
SS
97Published by the Free Software Foundation @*
9859 Temple Place - Suite 330, @*
99Boston, MA 02111-1307 USA @*
100Printed copies are available for $20 each. @*
101ISBN 1-882114-11-6 @*
c906108c
SS
102
103Permission is granted to make and distribute verbatim copies of
104this manual provided the copyright notice and this permission notice
105are preserved on all copies.
106
107Permission is granted to copy and distribute modified versions of this
108manual under the conditions for verbatim copying, provided also that the
109entire resulting derived work is distributed under the terms of a
110permission notice identical to this one.
111
112Permission is granted to copy and distribute translations of this manual
113into another language, under the above conditions for modified versions.
114@end titlepage
115@page
116
117@ifinfo
53a5351d 118@node Top
c906108c
SS
119@top Debugging with @value{GDBN}
120
121This file describes @value{GDBN}, the @sc{gnu} symbolic debugger.
122
123This is the @value{EDITION} Edition, @value{DATE}, for @value{GDBN} Version
124@value{GDBVN}.
125
126Copyright (C) 1988-1999 Free Software Foundation, Inc.
127@menu
128* Summary:: Summary of @value{GDBN}
c906108c 129* Sample Session:: A sample @value{GDBN} session
c906108c
SS
130
131* Invocation:: Getting in and out of @value{GDBN}
132* Commands:: @value{GDBN} commands
133* Running:: Running programs under @value{GDBN}
134* Stopping:: Stopping and continuing
135* Stack:: Examining the stack
136* Source:: Examining source files
137* Data:: Examining data
c906108c 138
7a292a7a 139* Languages:: Using @value{GDBN} with different languages
c906108c
SS
140
141* Symbols:: Examining the symbol table
142* Altering:: Altering execution
143* GDB Files:: @value{GDBN} files
144* Targets:: Specifying a debugging target
145* Controlling GDB:: Controlling @value{GDBN}
146* Sequences:: Canned sequences of commands
c906108c 147* Emacs:: Using @value{GDBN} under @sc{gnu} Emacs
c906108c
SS
148
149* GDB Bugs:: Reporting bugs in @value{GDBN}
c906108c 150* Formatting Documentation:: How to format and print @value{GDBN} documentation
c906108c
SS
151
152* Command Line Editing:: Command Line Editing
153* Using History Interactively:: Using History Interactively
154* Installing GDB:: Installing GDB
155* Index:: Index
c906108c
SS
156@end menu
157
158@end ifinfo
159
53a5351d 160@node Summary
c906108c
SS
161@unnumbered Summary of @value{GDBN}
162
163The purpose of a debugger such as @value{GDBN} is to allow you to see what is
164going on ``inside'' another program while it executes---or what another
165program was doing at the moment it crashed.
166
167@value{GDBN} can do four main kinds of things (plus other things in support of
168these) to help you catch bugs in the act:
169
170@itemize @bullet
171@item
172Start your program, specifying anything that might affect its behavior.
173
174@item
175Make your program stop on specified conditions.
176
177@item
178Examine what has happened, when your program has stopped.
179
180@item
181Change things in your program, so you can experiment with correcting the
182effects of one bug and go on to learn about another.
183@end itemize
184
cce74817 185You can use @value{GDBN} to debug programs written in C and C++.
c906108c 186For more information, see @ref{Support,,Supported languages}.
c906108c
SS
187For more information, see @ref{C,,C and C++}.
188
cce74817
JM
189@cindex Chill
190@cindex Modula-2
c906108c 191Support for Modula-2 and Chill is partial. For information on Modula-2,
cce74817 192see @ref{Modula-2,,Modula-2}. For information on Chill, see @ref{Chill}.
c906108c 193
cce74817
JM
194@cindex Pascal
195Debugging Pascal programs which use sets, subranges, file variables, or
196nested functions does not currently work. @value{GDBN} does not support
197entering expressions, printing values, or similar features using Pascal
198syntax.
c906108c 199
c906108c
SS
200@cindex Fortran
201@value{GDBN} can be used to debug programs written in Fortran, although
53a5351d 202it may be necessary to refer to some variables with a trailing
cce74817 203underscore.
c906108c 204
c906108c
SS
205@menu
206* Free Software:: Freely redistributable software
207* Contributors:: Contributors to GDB
208@end menu
209
53a5351d 210@node Free Software
c906108c
SS
211@unnumberedsec Free software
212
213@value{GDBN} is @dfn{free software}, protected by the @sc{gnu}
214General Public License
215(GPL). The GPL gives you the freedom to copy or adapt a licensed
216program---but every person getting a copy also gets with it the
217freedom to modify that copy (which means that they must get access to
218the source code), and the freedom to distribute further copies.
219Typical software companies use copyrights to limit your freedoms; the
220Free Software Foundation uses the GPL to preserve these freedoms.
221
222Fundamentally, the General Public License is a license which says that
223you have these freedoms and that you cannot take these freedoms away
224from anyone else.
225
53a5351d 226@node Contributors
c906108c
SS
227@unnumberedsec Contributors to GDB
228
229Richard Stallman was the original author of GDB, and of many other
230@sc{gnu} programs. Many others have contributed to its development.
231This section attempts to credit major contributors. One of the virtues
232of free software is that everyone is free to contribute to it; with
233regret, we cannot actually acknowledge everyone here. The file
234@file{ChangeLog} in the @value{GDBN} distribution approximates a
235blow-by-blow account.
236
237Changes much prior to version 2.0 are lost in the mists of time.
238
239@quotation
240@emph{Plea:} Additions to this section are particularly welcome. If you
241or your friends (or enemies, to be evenhanded) have been unfairly
242omitted from this list, we would like to add your names!
243@end quotation
244
245So that they may not regard their many labors as thankless, we
246particularly thank those who shepherded @value{GDBN} through major
247releases:
248Jim Blandy (release 4.18);
249Jason Molenda (release 4.17);
250Stan Shebs (release 4.14);
251Fred Fish (releases 4.16, 4.15, 4.13, 4.12, 4.11, 4.10, and 4.9);
252Stu Grossman and John Gilmore (releases 4.8, 4.7, 4.6, 4.5, and 4.4);
253John Gilmore (releases 4.3, 4.2, 4.1, 4.0, and 3.9);
254Jim Kingdon (releases 3.5, 3.4, and 3.3);
255and Randy Smith (releases 3.2, 3.1, and 3.0).
256
257Richard Stallman, assisted at various times by Peter TerMaat, Chris
258Hanson, and Richard Mlynarik, handled releases through 2.8.
259
c906108c
SS
260Michael Tiemann is the author of most of the @sc{gnu} C++ support in GDB,
261with significant additional contributions from Per Bothner. James
262Clark wrote the @sc{gnu} C++ demangler. Early work on C++ was by Peter
263TerMaat (who also did much general update work leading to release 3.0).
c906108c
SS
264
265@value{GDBN} 4 uses the BFD subroutine library to examine multiple
266object-file formats; BFD was a joint project of David V.
267Henkel-Wallace, Rich Pixley, Steve Chamberlain, and John Gilmore.
268
269David Johnson wrote the original COFF support; Pace Willison did
270the original support for encapsulated COFF.
271
272Brent Benson of Harris Computer Systems contributed DWARF 2 support.
273
274Adam de Boor and Bradley Davis contributed the ISI Optimum V support.
275Per Bothner, Noboyuki Hikichi, and Alessandro Forin contributed MIPS
276support.
277Jean-Daniel Fekete contributed Sun 386i support.
278Chris Hanson improved the HP9000 support.
279Noboyuki Hikichi and Tomoyuki Hasei contributed Sony/News OS 3 support.
280David Johnson contributed Encore Umax support.
281Jyrki Kuoppala contributed Altos 3068 support.
282Jeff Law contributed HP PA and SOM support.
283Keith Packard contributed NS32K support.
284Doug Rabson contributed Acorn Risc Machine support.
285Bob Rusk contributed Harris Nighthawk CX-UX support.
286Chris Smith contributed Convex support (and Fortran debugging).
287Jonathan Stone contributed Pyramid support.
288Michael Tiemann contributed SPARC support.
289Tim Tucker contributed support for the Gould NP1 and Gould Powernode.
290Pace Willison contributed Intel 386 support.
291Jay Vosburgh contributed Symmetry support.
292
293Andreas Schwab contributed M68K Linux support.
294
295Rich Schaefer and Peter Schauer helped with support of SunOS shared
296libraries.
297
298Jay Fenlason and Roland McGrath ensured that @value{GDBN} and GAS agree
299about several machine instruction sets.
300
301Patrick Duval, Ted Goldstein, Vikram Koka and Glenn Engel helped develop
302remote debugging. Intel Corporation, Wind River Systems, AMD, and ARM
303contributed remote debugging modules for the i960, VxWorks, A29K UDI,
304and RDI targets, respectively.
305
306Brian Fox is the author of the readline libraries providing
307command-line editing and command history.
308
7a292a7a
SS
309Andrew Beers of SUNY Buffalo wrote the language-switching code, the
310Modula-2 support, and contributed the Languages chapter of this manual.
c906108c
SS
311
312Fred Fish wrote most of the support for Unix System Vr4.
c906108c
SS
313He also enhanced the command-completion support to cover C++ overloaded
314symbols.
c906108c
SS
315
316Hitachi America, Ltd. sponsored the support for H8/300, H8/500, and
317Super-H processors.
318
319NEC sponsored the support for the v850, Vr4xxx, and Vr5xxx processors.
320
321Mitsubishi sponsored the support for D10V, D30V, and M32R/D processors.
322
323Toshiba sponsored the support for the TX39 Mips processor.
324
325Matsushita sponsored the support for the MN10200 and MN10300 processors.
326
327Fujitsu sponsored the support for SPARClite and FR30 processors
328
329Kung Hsu, Jeff Law, and Rick Sladkey added support for hardware
330watchpoints.
331
332Michael Snyder added support for tracepoints.
333
334Stu Grossman wrote gdbserver.
335
336Jim Kingdon, Peter Schauer, Ian Taylor, and Stu Grossman made
337nearly innumerable bug fixes and cleanups throughout GDB.
338
339The following people at the Hewlett-Packard Company contributed
340support for the PA-RISC 2.0 architecture, HP-UX 10.20, 10.30, and 11.0
341(narrow mode), HP's implementation of kernel threads, HP's aC++
342compiler, and the terminal user interface: Ben Krepp, Richard Title,
343John Bishop, Susan Macchia, Kathy Mann, Satish Pai, India Paul, Steve
344Rehrauer, and Elena Zannoni. Kim Haase provided HP-specific
345information in this manual.
346
347Cygnus Solutions has sponsored GDB maintenance and much of its
348development since 1991. Cygnus engineers who have worked on GDB
349fulltime include Mark Alexander, Jim Blandy, Per Bothner, Edith Epstein,
350Chris Faylor, Fred Fish, Martin Hunt, Jim Ingham, John Gilmore, Stu
351Grossman, Kung Hsu, Jim Kingdon, John Metzler, Fernando Nasser, Geoffrey
352Noer, Dawn Perchik, Rich Pixley, Zdenek Radouch, Keith Seitz, Stan
353Shebs, David Taylor, and Elena Zannoni. In addition, Dave Brolley, Ian
354Carmichael, Steve Chamberlain, Nick Clifton, JT Conklin, Stan Cox, DJ
355Delorie, Ulrich Drepper, Frank Eigler, Doug Evans, Sean Fagan, David
356Henkel-Wallace, Richard Henderson, Jeff Holcomb, Jeff Law, Jim Lemke,
357Tom Lord, Bob Manson, Michael Meissner, Jason Merrill, Catherine Moore,
358Drew Moseley, Ken Raeburn, Gavin Romig-Koch, Rob Savoye, Jamie Smith,
359Mike Stump, Ian Taylor, Angela Thomas, Michael Tiemann, Tom Tromey, Ron
360Unrau, Jim Wilson, and David Zuhn have made contributions both large
361and small.
362
363
53a5351d 364@node Sample Session
c906108c
SS
365@chapter A Sample @value{GDBN} Session
366
367You can use this manual at your leisure to read all about @value{GDBN}.
368However, a handful of commands are enough to get started using the
369debugger. This chapter illustrates those commands.
370
371@iftex
372In this sample session, we emphasize user input like this: @b{input},
373to make it easier to pick out from the surrounding output.
374@end iftex
375
376@c FIXME: this example may not be appropriate for some configs, where
377@c FIXME...primary interest is in remote use.
378
379One of the preliminary versions of @sc{gnu} @code{m4} (a generic macro
380processor) exhibits the following bug: sometimes, when we change its
381quote strings from the default, the commands used to capture one macro
382definition within another stop working. In the following short @code{m4}
383session, we define a macro @code{foo} which expands to @code{0000}; we
384then use the @code{m4} built-in @code{defn} to define @code{bar} as the
385same thing. However, when we change the open quote string to
386@code{<QUOTE>} and the close quote string to @code{<UNQUOTE>}, the same
387procedure fails to define a new synonym @code{baz}:
388
389@smallexample
390$ @b{cd gnu/m4}
391$ @b{./m4}
392@b{define(foo,0000)}
393
394@b{foo}
3950000
396@b{define(bar,defn(`foo'))}
397
398@b{bar}
3990000
400@b{changequote(<QUOTE>,<UNQUOTE>)}
401
402@b{define(baz,defn(<QUOTE>foo<UNQUOTE>))}
403@b{baz}
404@b{C-d}
405m4: End of input: 0: fatal error: EOF in string
406@end smallexample
407
408@noindent
409Let us use @value{GDBN} to try to see what is going on.
410
c906108c
SS
411@smallexample
412$ @b{@value{GDBP} m4}
413@c FIXME: this falsifies the exact text played out, to permit smallbook
414@c FIXME... format to come out better.
415@value{GDBN} is free software and you are welcome to distribute copies
416 of it under certain conditions; type "show copying" to see
417 the conditions.
418There is absolutely no warranty for @value{GDBN}; type "show warranty"
419 for details.
420
421@value{GDBN} @value{GDBVN}, Copyright 1999 Free Software Foundation, Inc...
422(@value{GDBP})
423@end smallexample
c906108c
SS
424
425@noindent
426@value{GDBN} reads only enough symbol data to know where to find the
427rest when needed; as a result, the first prompt comes up very quickly.
428We now tell @value{GDBN} to use a narrower display width than usual, so
429that examples fit in this manual.
430
431@smallexample
432(@value{GDBP}) @b{set width 70}
433@end smallexample
434
435@noindent
436We need to see how the @code{m4} built-in @code{changequote} works.
437Having looked at the source, we know the relevant subroutine is
438@code{m4_changequote}, so we set a breakpoint there with the @value{GDBN}
439@code{break} command.
440
441@smallexample
442(@value{GDBP}) @b{break m4_changequote}
443Breakpoint 1 at 0x62f4: file builtin.c, line 879.
444@end smallexample
445
446@noindent
447Using the @code{run} command, we start @code{m4} running under @value{GDBN}
448control; as long as control does not reach the @code{m4_changequote}
449subroutine, the program runs as usual:
450
451@smallexample
452(@value{GDBP}) @b{run}
453Starting program: /work/Editorial/gdb/gnu/m4/m4
454@b{define(foo,0000)}
455
456@b{foo}
4570000
458@end smallexample
459
460@noindent
461To trigger the breakpoint, we call @code{changequote}. @value{GDBN}
462suspends execution of @code{m4}, displaying information about the
463context where it stops.
464
465@smallexample
466@b{changequote(<QUOTE>,<UNQUOTE>)}
467
468Breakpoint 1, m4_changequote (argc=3, argv=0x33c70)
469 at builtin.c:879
470879 if (bad_argc(TOKEN_DATA_TEXT(argv[0]),argc,1,3))
471@end smallexample
472
473@noindent
474Now we use the command @code{n} (@code{next}) to advance execution to
475the next line of the current function.
476
477@smallexample
478(@value{GDBP}) @b{n}
479882 set_quotes((argc >= 2) ? TOKEN_DATA_TEXT(argv[1])\
480 : nil,
481@end smallexample
482
483@noindent
484@code{set_quotes} looks like a promising subroutine. We can go into it
485by using the command @code{s} (@code{step}) instead of @code{next}.
486@code{step} goes to the next line to be executed in @emph{any}
487subroutine, so it steps into @code{set_quotes}.
488
489@smallexample
490(@value{GDBP}) @b{s}
491set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>")
492 at input.c:530
493530 if (lquote != def_lquote)
494@end smallexample
495
496@noindent
497The display that shows the subroutine where @code{m4} is now
498suspended (and its arguments) is called a stack frame display. It
499shows a summary of the stack. We can use the @code{backtrace}
500command (which can also be spelled @code{bt}), to see where we are
501in the stack as a whole: the @code{backtrace} command displays a
502stack frame for each active subroutine.
503
504@smallexample
505(@value{GDBP}) @b{bt}
506#0 set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>")
507 at input.c:530
508#1 0x6344 in m4_changequote (argc=3, argv=0x33c70)
509 at builtin.c:882
510#2 0x8174 in expand_macro (sym=0x33320) at macro.c:242
511#3 0x7a88 in expand_token (obs=0x0, t=209696, td=0xf7fffa30)
512 at macro.c:71
513#4 0x79dc in expand_input () at macro.c:40
514#5 0x2930 in main (argc=0, argv=0xf7fffb20) at m4.c:195
515@end smallexample
516
517@noindent
518We step through a few more lines to see what happens. The first two
519times, we can use @samp{s}; the next two times we use @code{n} to avoid
520falling into the @code{xstrdup} subroutine.
521
522@smallexample
523(@value{GDBP}) @b{s}
5240x3b5c 532 if (rquote != def_rquote)
525(@value{GDBP}) @b{s}
5260x3b80 535 lquote = (lq == nil || *lq == '\0') ? \
527def_lquote : xstrdup(lq);
528(@value{GDBP}) @b{n}
529536 rquote = (rq == nil || *rq == '\0') ? def_rquote\
530 : xstrdup(rq);
531(@value{GDBP}) @b{n}
532538 len_lquote = strlen(rquote);
533@end smallexample
534
535@noindent
536The last line displayed looks a little odd; we can examine the variables
537@code{lquote} and @code{rquote} to see if they are in fact the new left
538and right quotes we specified. We use the command @code{p}
539(@code{print}) to see their values.
540
541@smallexample
542(@value{GDBP}) @b{p lquote}
543$1 = 0x35d40 "<QUOTE>"
544(@value{GDBP}) @b{p rquote}
545$2 = 0x35d50 "<UNQUOTE>"
546@end smallexample
547
548@noindent
549@code{lquote} and @code{rquote} are indeed the new left and right quotes.
550To look at some context, we can display ten lines of source
551surrounding the current line with the @code{l} (@code{list}) command.
552
553@smallexample
554(@value{GDBP}) @b{l}
555533 xfree(rquote);
556534
557535 lquote = (lq == nil || *lq == '\0') ? def_lquote\
558 : xstrdup (lq);
559536 rquote = (rq == nil || *rq == '\0') ? def_rquote\
560 : xstrdup (rq);
561537
562538 len_lquote = strlen(rquote);
563539 len_rquote = strlen(lquote);
564540 @}
565541
566542 void
567@end smallexample
568
569@noindent
570Let us step past the two lines that set @code{len_lquote} and
571@code{len_rquote}, and then examine the values of those variables.
572
573@smallexample
574(@value{GDBP}) @b{n}
575539 len_rquote = strlen(lquote);
576(@value{GDBP}) @b{n}
577540 @}
578(@value{GDBP}) @b{p len_lquote}
579$3 = 9
580(@value{GDBP}) @b{p len_rquote}
581$4 = 7
582@end smallexample
583
584@noindent
585That certainly looks wrong, assuming @code{len_lquote} and
586@code{len_rquote} are meant to be the lengths of @code{lquote} and
587@code{rquote} respectively. We can set them to better values using
588the @code{p} command, since it can print the value of
589any expression---and that expression can include subroutine calls and
590assignments.
591
592@smallexample
593(@value{GDBP}) @b{p len_lquote=strlen(lquote)}
594$5 = 7
595(@value{GDBP}) @b{p len_rquote=strlen(rquote)}
596$6 = 9
597@end smallexample
598
599@noindent
600Is that enough to fix the problem of using the new quotes with the
601@code{m4} built-in @code{defn}? We can allow @code{m4} to continue
602executing with the @code{c} (@code{continue}) command, and then try the
603example that caused trouble initially:
604
605@smallexample
606(@value{GDBP}) @b{c}
607Continuing.
608
609@b{define(baz,defn(<QUOTE>foo<UNQUOTE>))}
610
611baz
6120000
613@end smallexample
614
615@noindent
616Success! The new quotes now work just as well as the default ones. The
617problem seems to have been just the two typos defining the wrong
618lengths. We allow @code{m4} exit by giving it an EOF as input:
619
620@smallexample
621@b{C-d}
622Program exited normally.
623@end smallexample
624
625@noindent
626The message @samp{Program exited normally.} is from @value{GDBN}; it
627indicates @code{m4} has finished executing. We can end our @value{GDBN}
628session with the @value{GDBN} @code{quit} command.
629
630@smallexample
631(@value{GDBP}) @b{quit}
632@end smallexample
c906108c 633
53a5351d 634@node Invocation
c906108c
SS
635@chapter Getting In and Out of @value{GDBN}
636
637This chapter discusses how to start @value{GDBN}, and how to get out of it.
638The essentials are:
639@itemize @bullet
640@item
53a5351d 641type @samp{@value{GDBP}} to start @value{GDBN}.
c906108c
SS
642@item
643type @kbd{quit} or @kbd{C-d} to exit.
644@end itemize
645
646@menu
647* Invoking GDB:: How to start @value{GDBN}
648* Quitting GDB:: How to quit @value{GDBN}
649* Shell Commands:: How to use shell commands inside @value{GDBN}
650@end menu
651
53a5351d 652@node Invoking GDB
c906108c
SS
653@section Invoking @value{GDBN}
654
c906108c
SS
655Invoke @value{GDBN} by running the program @code{@value{GDBP}}. Once started,
656@value{GDBN} reads commands from the terminal until you tell it to exit.
657
658You can also run @code{@value{GDBP}} with a variety of arguments and options,
659to specify more of your debugging environment at the outset.
660
c906108c
SS
661The command-line options described here are designed
662to cover a variety of situations; in some environments, some of these
663options may effectively be unavailable.
c906108c
SS
664
665The most usual way to start @value{GDBN} is with one argument,
666specifying an executable program:
667
668@example
669@value{GDBP} @var{program}
670@end example
671
c906108c
SS
672@noindent
673You can also start with both an executable program and a core file
674specified:
675
676@example
677@value{GDBP} @var{program} @var{core}
678@end example
679
680You can, instead, specify a process ID as a second argument, if you want
681to debug a running process:
682
683@example
684@value{GDBP} @var{program} 1234
685@end example
686
687@noindent
688would attach @value{GDBN} to process @code{1234} (unless you also have a file
689named @file{1234}; @value{GDBN} does check for a core file first).
690
c906108c
SS
691Taking advantage of the second command-line argument requires a fairly
692complete operating system; when you use @value{GDBN} as a remote debugger
693attached to a bare board, there may not be any notion of ``process'',
694and there is often no way to get a core dump.
c906108c
SS
695
696You can run @code{gdb} without printing the front material, which describes
697@value{GDBN}'s non-warranty, by specifying @code{-silent}:
698
699@smallexample
700@value{GDBP} -silent
701@end smallexample
702
703@noindent
704You can further control how @value{GDBN} starts up by using command-line
705options. @value{GDBN} itself can remind you of the options available.
706
707@noindent
708Type
709
710@example
711@value{GDBP} -help
712@end example
713
714@noindent
715to display all available options and briefly describe their use
716(@samp{@value{GDBP} -h} is a shorter equivalent).
717
718All options and command line arguments you give are processed
719in sequential order. The order makes a difference when the
720@samp{-x} option is used.
721
722
723@menu
c906108c
SS
724* File Options:: Choosing files
725* Mode Options:: Choosing modes
726@end menu
727
c906108c
SS
728@node File Options
729@subsection Choosing files
730
53a5351d 731When @value{GDBN} starts
c906108c
SS
732specifying an executable file and core file (or process ID). This is
733the same as if the arguments were specified by the @samp{-se} and
734@samp{-c} options respectively. (@value{GDBN} reads the first argument
735that does not have an associated option flag as equivalent to the
736@samp{-se} option followed by that argument; and the second argument
737that does not have an associated option flag, if any, as equivalent to
738the @samp{-c} option followed by that argument.)
7a292a7a
SS
739
740If @value{GDBN} has not been configured to included core file support,
741such as for most embedded targets, then it will complain about a second
742argument and ignore it.
c906108c
SS
743
744Many options have both long and short forms; both are shown in the
745following list. @value{GDBN} also recognizes the long forms if you truncate
746them, so long as enough of the option is present to be unambiguous.
747(If you prefer, you can flag option arguments with @samp{--} rather
748than @samp{-}, though we illustrate the more usual convention.)
749
750@table @code
751@item -symbols @var{file}
752@itemx -s @var{file}
753Read symbol table from file @var{file}.
754
755@item -exec @var{file}
756@itemx -e @var{file}
7a292a7a
SS
757Use file @var{file} as the executable file to execute when appropriate,
758and for examining pure data in conjunction with a core dump.
c906108c
SS
759
760@item -se @var{file}
761Read symbol table from file @var{file} and use it as the executable
762file.
763
c906108c
SS
764@item -core @var{file}
765@itemx -c @var{file}
766Use file @var{file} as a core dump to examine.
767
768@item -c @var{number}
769Connect to process ID @var{number}, as with the @code{attach} command
770(unless there is a file in core-dump format named @var{number}, in which
771case @samp{-c} specifies that file as a core dump to read).
c906108c
SS
772
773@item -command @var{file}
774@itemx -x @var{file}
775Execute @value{GDBN} commands from file @var{file}. @xref{Command
776Files,, Command files}.
777
778@item -directory @var{directory}
779@itemx -d @var{directory}
780Add @var{directory} to the path to search for source files.
781
c906108c
SS
782@item -m
783@itemx -mapped
784@emph{Warning: this option depends on operating system facilities that are not
785supported on all systems.}@*
786If memory-mapped files are available on your system through the @code{mmap}
787system call, you can use this option
788to have @value{GDBN} write the symbols from your
789program into a reusable file in the current directory. If the program you are debugging is
790called @file{/tmp/fred}, the mapped symbol file is @file{./fred.syms}.
791Future @value{GDBN} debugging sessions notice the presence of this file,
792and can quickly map in symbol information from it, rather than reading
793the symbol table from the executable program.
794
795The @file{.syms} file is specific to the host machine where @value{GDBN}
796is run. It holds an exact image of the internal @value{GDBN} symbol
797table. It cannot be shared across multiple host platforms.
c906108c 798
c906108c
SS
799@item -r
800@itemx -readnow
801Read each symbol file's entire symbol table immediately, rather than
802the default, which is to read it incrementally as it is needed.
803This makes startup slower, but makes future operations faster.
53a5351d 804
c906108c
SS
805@end table
806
c906108c
SS
807The @code{-mapped} and @code{-readnow} options are typically combined in
808order to build a @file{.syms} file that contains complete symbol
809information. (@xref{Files,,Commands to specify files}, for
53a5351d 810information on @file{.syms} files.) A simple @value{GDBN} invocation to do
c906108c
SS
811nothing but build a @file{.syms} file for future use is:
812
813@example
814 gdb -batch -nx -mapped -readnow programname
815@end example
c906108c 816
53a5351d 817@node Mode Options
c906108c
SS
818@subsection Choosing modes
819
820You can run @value{GDBN} in various alternative modes---for example, in
821batch mode or quiet mode.
822
823@table @code
824@item -nx
825@itemx -n
826Do not execute commands from any initialization files (normally called
827@file{.gdbinit}, or @file{gdb.ini} on PCs). Normally, the commands in
828these files are executed after all the command options and arguments
829have been processed. @xref{Command Files,,Command files}.
830
831@item -quiet
832@itemx -q
833``Quiet''. Do not print the introductory and copyright messages. These
834messages are also suppressed in batch mode.
835
836@item -batch
837Run in batch mode. Exit with status @code{0} after processing all the
838command files specified with @samp{-x} (and all commands from
839initialization files, if not inhibited with @samp{-n}). Exit with
840nonzero status if an error occurs in executing the @value{GDBN} commands
841in the command files.
842
843Batch mode may be useful for running @value{GDBN} as a filter, for example to
844download and run a program on another computer; in order to make this
845more useful, the message
846
847@example
848Program exited normally.
849@end example
850
851@noindent
852(which is ordinarily issued whenever a program running under @value{GDBN} control
853terminates) is not issued when running in batch mode.
854
855@item -cd @var{directory}
856Run @value{GDBN} using @var{directory} as its working directory,
857instead of the current directory.
858
c906108c
SS
859@item -fullname
860@itemx -f
7a292a7a
SS
861@sc{gnu} Emacs sets this option when it runs @value{GDBN} as a
862subprocess. It tells @value{GDBN} to output the full file name and line
863number in a standard, recognizable fashion each time a stack frame is
864displayed (which includes each time your program stops). This
865recognizable format looks like two @samp{\032} characters, followed by
866the file name, line number and character position separated by colons,
867and a newline. The Emacs-to-@value{GDBN} interface program uses the two
868@samp{\032} characters as a signal to display the source code for the
869frame.
c906108c 870
c906108c
SS
871@item -b @var{bps}
872Set the line speed (baud rate or bits per second) of any serial
873interface used by @value{GDBN} for remote debugging.
c906108c
SS
874
875@item -tty @var{device}
876Run using @var{device} for your program's standard input and output.
877@c FIXME: kingdon thinks there is more to -tty. Investigate.
c906108c 878
53a5351d
JM
879@c resolve the situation of these eventually
880@c @item -tui
881@c Use a Terminal User Interface. For information, use your Web browser to
882@c read the file @file{TUI.html}, which is usually installed in the
883@c directory @code{/opt/langtools/wdb/doc} on HP-UX systems. Do not use
884@c this option if you run @value{GDBN} from Emacs (see @pxref{Emacs, ,Using
885@c @value{GDBN} under @sc{gnu} Emacs}).
886
887@c @item -xdb
888@c Run in XDB compatibility mode, allowing the use of certain XDB commands.
889@c For information, see the file @file{xdb_trans.html}, which is usually
890@c installed in the directory @code{/opt/langtools/wdb/doc} on HP-UX
891@c systems.
892
c906108c
SS
893@end table
894
53a5351d 895@node Quitting GDB
c906108c
SS
896@section Quitting @value{GDBN}
897@cindex exiting @value{GDBN}
898@cindex leaving @value{GDBN}
899
900@table @code
901@kindex quit @r{[}@var{expression}@r{]}
902@kindex q
903@item quit
904To exit @value{GDBN}, use the @code{quit} command (abbreviated @code{q}), or
905type an end-of-file character (usually @kbd{C-d}). If you do not supply
906@var{expression}, @value{GDBN} will terminate normally; otherwise it will
907terminate using the result of @var{expression} as the error code.
908@end table
909
910@cindex interrupt
911An interrupt (often @kbd{C-c}) does not exit from @value{GDBN}, but rather
912terminates the action of any @value{GDBN} command that is in progress and
913returns to @value{GDBN} command level. It is safe to type the interrupt
914character at any time because @value{GDBN} does not allow it to take effect
915until a time when it is safe.
916
c906108c
SS
917If you have been using @value{GDBN} to control an attached process or
918device, you can release it with the @code{detach} command
919(@pxref{Attach, ,Debugging an already-running process}).
c906108c 920
53a5351d 921@node Shell Commands
c906108c
SS
922@section Shell commands
923
924If you need to execute occasional shell commands during your
925debugging session, there is no need to leave or suspend @value{GDBN}; you can
926just use the @code{shell} command.
927
928@table @code
929@kindex shell
930@cindex shell escape
931@item shell @var{command string}
932Invoke a standard shell to execute @var{command string}.
c906108c
SS
933If it exists, the environment variable @code{SHELL} determines which
934shell to run. Otherwise @value{GDBN} uses @code{/bin/sh}.
c906108c
SS
935@end table
936
937The utility @code{make} is often needed in development environments.
938You do not have to use the @code{shell} command for this purpose in
939@value{GDBN}:
940
941@table @code
942@kindex make
943@cindex calling make
944@item make @var{make-args}
945Execute the @code{make} program with the specified
946arguments. This is equivalent to @samp{shell make @var{make-args}}.
947@end table
948
53a5351d 949@node Commands
c906108c
SS
950@chapter @value{GDBN} Commands
951
952You can abbreviate a @value{GDBN} command to the first few letters of the command
953name, if that abbreviation is unambiguous; and you can repeat certain
954@value{GDBN} commands by typing just @key{RET}. You can also use the @key{TAB}
955key to get @value{GDBN} to fill out the rest of a word in a command (or to
956show you the alternatives available, if there is more than one possibility).
957
958@menu
959* Command Syntax:: How to give commands to @value{GDBN}
960* Completion:: Command completion
961* Help:: How to ask @value{GDBN} for help
962@end menu
963
53a5351d 964@node Command Syntax
c906108c
SS
965@section Command syntax
966
967A @value{GDBN} command is a single line of input. There is no limit on
968how long it can be. It starts with a command name, which is followed by
969arguments whose meaning depends on the command name. For example, the
970command @code{step} accepts an argument which is the number of times to
971step, as in @samp{step 5}. You can also use the @code{step} command
972with no arguments. Some command names do not allow any arguments.
973
974@cindex abbreviation
975@value{GDBN} command names may always be truncated if that abbreviation is
976unambiguous. Other possible command abbreviations are listed in the
977documentation for individual commands. In some cases, even ambiguous
978abbreviations are allowed; for example, @code{s} is specially defined as
979equivalent to @code{step} even though there are other commands whose
980names start with @code{s}. You can test abbreviations by using them as
981arguments to the @code{help} command.
982
983@cindex repeating commands
984@kindex RET
985A blank line as input to @value{GDBN} (typing just @key{RET}) means to
986repeat the previous command. Certain commands (for example, @code{run})
987will not repeat this way; these are commands whose unintentional
988repetition might cause trouble and which you are unlikely to want to
989repeat.
990
991The @code{list} and @code{x} commands, when you repeat them with
992@key{RET}, construct new arguments rather than repeating
993exactly as typed. This permits easy scanning of source or memory.
994
995@value{GDBN} can also use @key{RET} in another way: to partition lengthy
996output, in a way similar to the common utility @code{more}
997(@pxref{Screen Size,,Screen size}). Since it is easy to press one
998@key{RET} too many in this situation, @value{GDBN} disables command
999repetition after any command that generates this sort of display.
1000
1001@kindex #
1002@cindex comment
1003Any text from a @kbd{#} to the end of the line is a comment; it does
1004nothing. This is useful mainly in command files (@pxref{Command
1005Files,,Command files}).
1006
53a5351d 1007@node Completion
c906108c
SS
1008@section Command completion
1009
1010@cindex completion
1011@cindex word completion
1012@value{GDBN} can fill in the rest of a word in a command for you, if there is
1013only one possibility; it can also show you what the valid possibilities
1014are for the next word in a command, at any time. This works for @value{GDBN}
1015commands, @value{GDBN} subcommands, and the names of symbols in your program.
1016
1017Press the @key{TAB} key whenever you want @value{GDBN} to fill out the rest
1018of a word. If there is only one possibility, @value{GDBN} fills in the
1019word, and waits for you to finish the command (or press @key{RET} to
1020enter it). For example, if you type
1021
1022@c FIXME "@key" does not distinguish its argument sufficiently to permit
1023@c complete accuracy in these examples; space introduced for clarity.
1024@c If texinfo enhancements make it unnecessary, it would be nice to
1025@c replace " @key" by "@key" in the following...
1026@example
1027(@value{GDBP}) info bre @key{TAB}
1028@end example
1029
1030@noindent
1031@value{GDBN} fills in the rest of the word @samp{breakpoints}, since that is
1032the only @code{info} subcommand beginning with @samp{bre}:
1033
1034@example
1035(@value{GDBP}) info breakpoints
1036@end example
1037
1038@noindent
1039You can either press @key{RET} at this point, to run the @code{info
1040breakpoints} command, or backspace and enter something else, if
1041@samp{breakpoints} does not look like the command you expected. (If you
1042were sure you wanted @code{info breakpoints} in the first place, you
1043might as well just type @key{RET} immediately after @samp{info bre},
1044to exploit command abbreviations rather than command completion).
1045
1046If there is more than one possibility for the next word when you press
1047@key{TAB}, @value{GDBN} sounds a bell. You can either supply more
1048characters and try again, or just press @key{TAB} a second time;
1049@value{GDBN} displays all the possible completions for that word. For
1050example, you might want to set a breakpoint on a subroutine whose name
1051begins with @samp{make_}, but when you type @kbd{b make_@key{TAB}} @value{GDBN}
1052just sounds the bell. Typing @key{TAB} again displays all the
1053function names in your program that begin with those characters, for
1054example:
1055
1056@example
1057(@value{GDBP}) b make_ @key{TAB}
1058@exdent @value{GDBN} sounds bell; press @key{TAB} again, to see:
1059make_a_section_from_file make_environ
1060make_abs_section make_function_type
1061make_blockvector make_pointer_type
1062make_cleanup make_reference_type
1063make_command make_symbol_completion_list
1064(@value{GDBP}) b make_
1065@end example
1066
1067@noindent
1068After displaying the available possibilities, @value{GDBN} copies your
1069partial input (@samp{b make_} in the example) so you can finish the
1070command.
1071
1072If you just want to see the list of alternatives in the first place, you
1073can press @kbd{M-?} rather than pressing @key{TAB} twice. @kbd{M-?}
7a292a7a 1074means @kbd{@key{META} ?}. You can type this either by holding down a
c906108c 1075key designated as the @key{META} shift on your keyboard (if there is
7a292a7a 1076one) while typing @kbd{?}, or as @key{ESC} followed by @kbd{?}.
c906108c
SS
1077
1078@cindex quotes in commands
1079@cindex completion of quoted strings
1080Sometimes the string you need, while logically a ``word'', may contain
7a292a7a
SS
1081parentheses or other characters that @value{GDBN} normally excludes from
1082its notion of a word. To permit word completion to work in this
1083situation, you may enclose words in @code{'} (single quote marks) in
1084@value{GDBN} commands.
c906108c 1085
c906108c
SS
1086The most likely situation where you might need this is in typing the
1087name of a C++ function. This is because C++ allows function overloading
1088(multiple definitions of the same function, distinguished by argument
1089type). For example, when you want to set a breakpoint you may need to
1090distinguish whether you mean the version of @code{name} that takes an
1091@code{int} parameter, @code{name(int)}, or the version that takes a
1092@code{float} parameter, @code{name(float)}. To use the word-completion
1093facilities in this situation, type a single quote @code{'} at the
1094beginning of the function name. This alerts @value{GDBN} that it may need to
1095consider more information than usual when you press @key{TAB} or
1096@kbd{M-?} to request word completion:
1097
1098@example
1099(@value{GDBP}) b 'bubble( @key{M-?}
1100bubble(double,double) bubble(int,int)
1101(@value{GDBP}) b 'bubble(
1102@end example
1103
1104In some cases, @value{GDBN} can tell that completing a name requires using
1105quotes. When this happens, @value{GDBN} inserts the quote for you (while
1106completing as much as it can) if you do not type the quote in the first
1107place:
1108
1109@example
1110(@value{GDBP}) b bub @key{TAB}
1111@exdent @value{GDBN} alters your input line to the following, and rings a bell:
1112(@value{GDBP}) b 'bubble(
1113@end example
1114
1115@noindent
1116In general, @value{GDBN} can tell that a quote is needed (and inserts it) if
1117you have not yet started typing the argument list when you ask for
1118completion on an overloaded symbol.
1119
7a292a7a 1120For more information about overloaded functions, @pxref{C plus plus
c906108c
SS
1121expressions, ,C++ expressions}. You can use the command @code{set
1122overload-resolution off} to disable overload resolution;
1123@pxref{Debugging C plus plus, ,@value{GDBN} features for C++}.
c906108c
SS
1124
1125
53a5351d 1126@node Help
c906108c
SS
1127@section Getting help
1128@cindex online documentation
1129@kindex help
1130
1131You can always ask @value{GDBN} itself for information on its commands,
1132using the command @code{help}.
1133
1134@table @code
1135@kindex h
1136@item help
1137@itemx h
1138You can use @code{help} (abbreviated @code{h}) with no arguments to
1139display a short list of named classes of commands:
1140
1141@smallexample
1142(@value{GDBP}) help
1143List of classes of commands:
1144
1145running -- Running the program
1146stack -- Examining the stack
1147data -- Examining data
1148breakpoints -- Making program stop at certain points
1149files -- Specifying and examining files
1150status -- Status inquiries
1151support -- Support facilities
1152user-defined -- User-defined commands
1153aliases -- Aliases of other commands
1154obscure -- Obscure features
1155
1156Type "help" followed by a class name for a list of
1157commands in that class.
1158Type "help" followed by command name for full
1159documentation.
1160Command name abbreviations are allowed if unambiguous.
1161(@value{GDBP})
1162@end smallexample
1163
1164@item help @var{class}
1165Using one of the general help classes as an argument, you can get a
1166list of the individual commands in that class. For example, here is the
1167help display for the class @code{status}:
1168
1169@smallexample
1170(@value{GDBP}) help status
1171Status inquiries.
1172
1173List of commands:
1174
1175@c Line break in "show" line falsifies real output, but needed
1176@c to fit in smallbook page size.
1177show -- Generic command for showing things set
1178 with "set"
1179info -- Generic command for printing status
1180
1181Type "help" followed by command name for full
1182documentation.
1183Command name abbreviations are allowed if unambiguous.
1184(@value{GDBP})
1185@end smallexample
1186
1187@item help @var{command}
1188With a command name as @code{help} argument, @value{GDBN} displays a
1189short paragraph on how to use that command.
1190
1191@kindex complete
1192@item complete @var{args}
1193The @code{complete @var{args}} command lists all the possible completions
1194for the beginning of a command. Use @var{args} to specify the beginning of the
1195command you want completed. For example:
1196
1197@smallexample
1198complete i
1199@end smallexample
1200
1201@noindent results in:
1202
1203@smallexample
1204@group
1205info
1206inspect
1207ignore
1208@end group
1209@end smallexample
1210
1211@noindent This is intended for use by @sc{gnu} Emacs.
1212@end table
1213
1214In addition to @code{help}, you can use the @value{GDBN} commands @code{info}
1215and @code{show} to inquire about the state of your program, or the state
1216of @value{GDBN} itself. Each command supports many topics of inquiry; this
1217manual introduces each of them in the appropriate context. The listings
1218under @code{info} and under @code{show} in the Index point to
1219all the sub-commands. @xref{Index}.
1220
1221@c @group
1222@table @code
1223@kindex info
1224@kindex i
1225@item info
1226This command (abbreviated @code{i}) is for describing the state of your
1227program. For example, you can list the arguments given to your program
1228with @code{info args}, list the registers currently in use with @code{info
1229registers}, or list the breakpoints you have set with @code{info breakpoints}.
1230You can get a complete list of the @code{info} sub-commands with
1231@w{@code{help info}}.
1232
1233@kindex set
1234@item set
1235You can assign the result of an expression to an environment variable with
1236@code{set}. For example, you can set the @value{GDBN} prompt to a $-sign with
1237@code{set prompt $}.
1238
1239@kindex show
1240@item show
1241In contrast to @code{info}, @code{show} is for describing the state of
1242@value{GDBN} itself.
1243You can change most of the things you can @code{show}, by using the
1244related command @code{set}; for example, you can control what number
1245system is used for displays with @code{set radix}, or simply inquire
1246which is currently in use with @code{show radix}.
1247
1248@kindex info set
1249To display all the settable parameters and their current
1250values, you can use @code{show} with no arguments; you may also use
1251@code{info set}. Both commands produce the same display.
1252@c FIXME: "info set" violates the rule that "info" is for state of
1253@c FIXME...program. Ck w/ GNU: "info set" to be called something else,
1254@c FIXME...or change desc of rule---eg "state of prog and debugging session"?
1255@end table
1256@c @end group
1257
1258Here are three miscellaneous @code{show} subcommands, all of which are
1259exceptional in lacking corresponding @code{set} commands:
1260
1261@table @code
1262@kindex show version
1263@cindex version number
1264@item show version
1265Show what version of @value{GDBN} is running. You should include this
1266information in @value{GDBN} bug-reports. If multiple versions of @value{GDBN} are in
1267use at your site, you may occasionally want to determine which version
1268of @value{GDBN} you are running; as @value{GDBN} evolves, new commands are introduced,
1269and old ones may wither away. The version number is also announced
1270when you start @value{GDBN}.
1271
1272@kindex show copying
1273@item show copying
1274Display information about permission for copying @value{GDBN}.
1275
1276@kindex show warranty
1277@item show warranty
1278Display the @sc{gnu} ``NO WARRANTY'' statement.
1279@end table
1280
53a5351d 1281@node Running
c906108c
SS
1282@chapter Running Programs Under @value{GDBN}
1283
1284When you run a program under @value{GDBN}, you must first generate
1285debugging information when you compile it.
7a292a7a
SS
1286
1287You may start @value{GDBN} with its arguments, if any, in an environment
1288of your choice. If you are doing native debugging, you may redirect
1289your program's input and output, debug an already running process, or
1290kill a child process.
c906108c
SS
1291
1292@menu
1293* Compilation:: Compiling for debugging
1294* Starting:: Starting your program
c906108c
SS
1295* Arguments:: Your program's arguments
1296* Environment:: Your program's environment
c906108c
SS
1297
1298* Working Directory:: Your program's working directory
1299* Input/Output:: Your program's input and output
1300* Attach:: Debugging an already-running process
1301* Kill Process:: Killing the child process
c906108c 1302* Process Information:: Additional process information
c906108c
SS
1303
1304* Threads:: Debugging programs with multiple threads
1305* Processes:: Debugging programs with multiple processes
1306@end menu
1307
53a5351d 1308@node Compilation
c906108c
SS
1309@section Compiling for debugging
1310
1311In order to debug a program effectively, you need to generate
1312debugging information when you compile it. This debugging information
1313is stored in the object file; it describes the data type of each
1314variable or function and the correspondence between source line numbers
1315and addresses in the executable code.
1316
1317To request debugging information, specify the @samp{-g} option when you run
1318the compiler.
1319
1320Many C compilers are unable to handle the @samp{-g} and @samp{-O}
1321options together. Using those compilers, you cannot generate optimized
1322executables containing debugging information.
1323
53a5351d
JM
1324@value{NGCC}, the @sc{gnu} C compiler, supports @samp{-g} with or
1325without @samp{-O}, making it possible to debug optimized code. We
1326recommend that you @emph{always} use @samp{-g} whenever you compile a
1327program. You may think your program is correct, but there is no sense
1328in pushing your luck.
c906108c
SS
1329
1330@cindex optimized code, debugging
1331@cindex debugging optimized code
1332When you debug a program compiled with @samp{-g -O}, remember that the
1333optimizer is rearranging your code; the debugger shows you what is
1334really there. Do not be too surprised when the execution path does not
1335exactly match your source file! An extreme example: if you define a
1336variable, but never use it, @value{GDBN} never sees that
1337variable---because the compiler optimizes it out of existence.
1338
1339Some things do not work as well with @samp{-g -O} as with just
1340@samp{-g}, particularly on machines with instruction scheduling. If in
1341doubt, recompile with @samp{-g} alone, and if this fixes the problem,
1342please report it to us as a bug (including a test case!).
1343
1344Older versions of the @sc{gnu} C compiler permitted a variant option
1345@w{@samp{-gg}} for debugging information. @value{GDBN} no longer supports this
1346format; if your @sc{gnu} C compiler has this option, do not use it.
1347
1348@need 2000
53a5351d 1349@node Starting
c906108c
SS
1350@section Starting your program
1351@cindex starting
1352@cindex running
1353
1354@table @code
1355@kindex run
1356@item run
1357@itemx r
7a292a7a
SS
1358Use the @code{run} command to start your program under @value{GDBN}.
1359You must first specify the program name (except on VxWorks) with an
1360argument to @value{GDBN} (@pxref{Invocation, ,Getting In and Out of
1361@value{GDBN}}), or by using the @code{file} or @code{exec-file} command
1362(@pxref{Files, ,Commands to specify files}).
c906108c
SS
1363
1364@end table
1365
c906108c
SS
1366If you are running your program in an execution environment that
1367supports processes, @code{run} creates an inferior process and makes
1368that process run your program. (In environments without processes,
1369@code{run} jumps to the start of your program.)
1370
1371The execution of a program is affected by certain information it
1372receives from its superior. @value{GDBN} provides ways to specify this
1373information, which you must do @emph{before} starting your program. (You
1374can change it after starting your program, but such changes only affect
1375your program the next time you start it.) This information may be
1376divided into four categories:
1377
1378@table @asis
1379@item The @emph{arguments.}
1380Specify the arguments to give your program as the arguments of the
1381@code{run} command. If a shell is available on your target, the shell
1382is used to pass the arguments, so that you may use normal conventions
1383(such as wildcard expansion or variable substitution) in describing
1384the arguments.
1385In Unix systems, you can control which shell is used with the
1386@code{SHELL} environment variable.
1387@xref{Arguments, ,Your program's arguments}.
1388
1389@item The @emph{environment.}
1390Your program normally inherits its environment from @value{GDBN}, but you can
1391use the @value{GDBN} commands @code{set environment} and @code{unset
1392environment} to change parts of the environment that affect
1393your program. @xref{Environment, ,Your program's environment}.
1394
1395@item The @emph{working directory.}
1396Your program inherits its working directory from @value{GDBN}. You can set
1397the @value{GDBN} working directory with the @code{cd} command in @value{GDBN}.
1398@xref{Working Directory, ,Your program's working directory}.
1399
1400@item The @emph{standard input and output.}
1401Your program normally uses the same device for standard input and
1402standard output as @value{GDBN} is using. You can redirect input and output
1403in the @code{run} command line, or you can use the @code{tty} command to
1404set a different device for your program.
1405@xref{Input/Output, ,Your program's input and output}.
1406
1407@cindex pipes
1408@emph{Warning:} While input and output redirection work, you cannot use
1409pipes to pass the output of the program you are debugging to another
1410program; if you attempt this, @value{GDBN} is likely to wind up debugging the
1411wrong program.
1412@end table
c906108c
SS
1413
1414When you issue the @code{run} command, your program begins to execute
1415immediately. @xref{Stopping, ,Stopping and continuing}, for discussion
1416of how to arrange for your program to stop. Once your program has
1417stopped, you may call functions in your program, using the @code{print}
1418or @code{call} commands. @xref{Data, ,Examining Data}.
1419
1420If the modification time of your symbol file has changed since the last
1421time @value{GDBN} read its symbols, @value{GDBN} discards its symbol
1422table, and reads it again. When it does this, @value{GDBN} tries to retain
1423your current breakpoints.
1424
53a5351d 1425@node Arguments
c906108c
SS
1426@section Your program's arguments
1427
1428@cindex arguments (to your program)
1429The arguments to your program can be specified by the arguments of the
1430@code{run} command.
1431They are passed to a shell, which expands wildcard characters and
1432performs redirection of I/O, and thence to your program. Your
1433@code{SHELL} environment variable (if it exists) specifies what shell
1434@value{GDBN} uses. If you do not define @code{SHELL}, @value{GDBN} uses
1435@code{/bin/sh}.
1436
1437@code{run} with no arguments uses the same arguments used by the previous
1438@code{run}, or those set by the @code{set args} command.
1439
1440@kindex set args
1441@table @code
1442@item set args
1443Specify the arguments to be used the next time your program is run. If
1444@code{set args} has no arguments, @code{run} executes your program
1445with no arguments. Once you have run your program with arguments,
1446using @code{set args} before the next @code{run} is the only way to run
1447it again without arguments.
1448
1449@kindex show args
1450@item show args
1451Show the arguments to give your program when it is started.
1452@end table
1453
53a5351d 1454@node Environment
c906108c
SS
1455@section Your program's environment
1456
1457@cindex environment (of your program)
1458The @dfn{environment} consists of a set of environment variables and
1459their values. Environment variables conventionally record such things as
1460your user name, your home directory, your terminal type, and your search
1461path for programs to run. Usually you set up environment variables with
1462the shell and they are inherited by all the other programs you run. When
1463debugging, it can be useful to try running your program with a modified
1464environment without having to start @value{GDBN} over again.
1465
1466@table @code
1467@kindex path
1468@item path @var{directory}
1469Add @var{directory} to the front of the @code{PATH} environment variable
1470(the search path for executables), for both @value{GDBN} and your program.
1471You may specify several directory names, separated by @samp{:} or
1472whitespace. If @var{directory} is already in the path, it is moved to
1473the front, so it is searched sooner.
1474
1475You can use the string @samp{$cwd} to refer to whatever is the current
1476working directory at the time @value{GDBN} searches the path. If you
1477use @samp{.} instead, it refers to the directory where you executed the
1478@code{path} command. @value{GDBN} replaces @samp{.} in the
1479@var{directory} argument (with the current path) before adding
1480@var{directory} to the search path.
1481@c 'path' is explicitly nonrepeatable, but RMS points out it is silly to
1482@c document that, since repeating it would be a no-op.
1483
1484@kindex show paths
1485@item show paths
1486Display the list of search paths for executables (the @code{PATH}
1487environment variable).
1488
1489@kindex show environment
1490@item show environment @r{[}@var{varname}@r{]}
1491Print the value of environment variable @var{varname} to be given to
1492your program when it starts. If you do not supply @var{varname},
1493print the names and values of all environment variables to be given to
1494your program. You can abbreviate @code{environment} as @code{env}.
1495
1496@kindex set environment
53a5351d 1497@item set environment @var{varname} @r{[}=@var{value}@r{]}
c906108c
SS
1498Set environment variable @var{varname} to @var{value}. The value
1499changes for your program only, not for @value{GDBN} itself. @var{value} may
1500be any string; the values of environment variables are just strings, and
1501any interpretation is supplied by your program itself. The @var{value}
1502parameter is optional; if it is eliminated, the variable is set to a
1503null value.
1504@c "any string" here does not include leading, trailing
1505@c blanks. Gnu asks: does anyone care?
1506
1507For example, this command:
1508
1509@example
1510set env USER = foo
1511@end example
1512
1513@noindent
1514tells a Unix program, when subsequently run, that its user is named
1515@samp{foo}. (The spaces around @samp{=} are used for clarity here; they
1516are not actually required.)
1517
1518@kindex unset environment
1519@item unset environment @var{varname}
1520Remove variable @var{varname} from the environment to be passed to your
1521program. This is different from @samp{set env @var{varname} =};
1522@code{unset environment} removes the variable from the environment,
1523rather than assigning it an empty value.
1524@end table
1525
1526@emph{Warning:} @value{GDBN} runs your program using the shell indicated
1527by your @code{SHELL} environment variable if it exists (or
1528@code{/bin/sh} if not). If your @code{SHELL} variable names a shell
1529that runs an initialization file---such as @file{.cshrc} for C-shell, or
1530@file{.bashrc} for BASH---any variables you set in that file affect
1531your program. You may wish to move setting of environment variables to
1532files that are only run when you sign on, such as @file{.login} or
1533@file{.profile}.
1534
53a5351d 1535@node Working Directory
c906108c
SS
1536@section Your program's working directory
1537
1538@cindex working directory (of your program)
1539Each time you start your program with @code{run}, it inherits its
1540working directory from the current working directory of @value{GDBN}.
1541The @value{GDBN} working directory is initially whatever it inherited
1542from its parent process (typically the shell), but you can specify a new
1543working directory in @value{GDBN} with the @code{cd} command.
1544
1545The @value{GDBN} working directory also serves as a default for the commands
1546that specify files for @value{GDBN} to operate on. @xref{Files, ,Commands to
1547specify files}.
1548
1549@table @code
1550@kindex cd
1551@item cd @var{directory}
1552Set the @value{GDBN} working directory to @var{directory}.
1553
1554@kindex pwd
1555@item pwd
1556Print the @value{GDBN} working directory.
1557@end table
1558
53a5351d 1559@node Input/Output
c906108c
SS
1560@section Your program's input and output
1561
1562@cindex redirection
1563@cindex i/o
1564@cindex terminal
1565By default, the program you run under @value{GDBN} does input and output to
1566the same terminal that @value{GDBN} uses. @value{GDBN} switches the terminal
1567to its own terminal modes to interact with you, but it records the terminal
1568modes your program was using and switches back to them when you continue
1569running your program.
1570
1571@table @code
1572@kindex info terminal
1573@item info terminal
1574Displays information recorded by @value{GDBN} about the terminal modes your
1575program is using.
1576@end table
1577
1578You can redirect your program's input and/or output using shell
1579redirection with the @code{run} command. For example,
1580
1581@example
1582run > outfile
1583@end example
1584
1585@noindent
1586starts your program, diverting its output to the file @file{outfile}.
1587
1588@kindex tty
1589@cindex controlling terminal
1590Another way to specify where your program should do input and output is
1591with the @code{tty} command. This command accepts a file name as
1592argument, and causes this file to be the default for future @code{run}
1593commands. It also resets the controlling terminal for the child
1594process, for future @code{run} commands. For example,
1595
1596@example
1597tty /dev/ttyb
1598@end example
1599
1600@noindent
1601directs that processes started with subsequent @code{run} commands
1602default to do input and output on the terminal @file{/dev/ttyb} and have
1603that as their controlling terminal.
1604
1605An explicit redirection in @code{run} overrides the @code{tty} command's
1606effect on the input/output device, but not its effect on the controlling
1607terminal.
1608
1609When you use the @code{tty} command or redirect input in the @code{run}
1610command, only the input @emph{for your program} is affected. The input
1611for @value{GDBN} still comes from your terminal.
1612
53a5351d 1613@node Attach
c906108c
SS
1614@section Debugging an already-running process
1615@kindex attach
1616@cindex attach
1617
1618@table @code
1619@item attach @var{process-id}
1620This command attaches to a running process---one that was started
1621outside @value{GDBN}. (@code{info files} shows your active
1622targets.) The command takes as argument a process ID. The usual way to
1623find out the process-id of a Unix process is with the @code{ps} utility,
1624or with the @samp{jobs -l} shell command.
1625
1626@code{attach} does not repeat if you press @key{RET} a second time after
1627executing the command.
1628@end table
1629
1630To use @code{attach}, your program must be running in an environment
1631which supports processes; for example, @code{attach} does not work for
1632programs on bare-board targets that lack an operating system. You must
1633also have permission to send the process a signal.
1634
1635When you use @code{attach}, the debugger finds the program running in
1636the process first by looking in the current working directory, then (if
1637the program is not found) by using the source file search path
1638(@pxref{Source Path, ,Specifying source directories}). You can also use
1639the @code{file} command to load the program. @xref{Files, ,Commands to
1640Specify Files}.
1641
1642The first thing @value{GDBN} does after arranging to debug the specified
1643process is to stop it. You can examine and modify an attached process
53a5351d
JM
1644with all the @value{GDBN} commands that are ordinarily available when
1645you start processes with @code{run}. You can insert breakpoints; you
1646can step and continue; you can modify storage. If you would rather the
1647process continue running, you may use the @code{continue} command after
c906108c
SS
1648attaching @value{GDBN} to the process.
1649
1650@table @code
1651@kindex detach
1652@item detach
1653When you have finished debugging the attached process, you can use the
1654@code{detach} command to release it from @value{GDBN} control. Detaching
1655the process continues its execution. After the @code{detach} command,
1656that process and @value{GDBN} become completely independent once more, and you
1657are ready to @code{attach} another process or start one with @code{run}.
1658@code{detach} does not repeat if you press @key{RET} again after
1659executing the command.
1660@end table
1661
1662If you exit @value{GDBN} or use the @code{run} command while you have an
1663attached process, you kill that process. By default, @value{GDBN} asks
1664for confirmation if you try to do either of these things; you can
1665control whether or not you need to confirm by using the @code{set
1666confirm} command (@pxref{Messages/Warnings, ,Optional warnings and
1667messages}).
1668
53a5351d 1669@node Kill Process
c906108c 1670@section Killing the child process
c906108c
SS
1671
1672@table @code
1673@kindex kill
1674@item kill
1675Kill the child process in which your program is running under @value{GDBN}.
1676@end table
1677
1678This command is useful if you wish to debug a core dump instead of a
1679running process. @value{GDBN} ignores any core dump file while your program
1680is running.
1681
1682On some operating systems, a program cannot be executed outside @value{GDBN}
1683while you have breakpoints set on it inside @value{GDBN}. You can use the
1684@code{kill} command in this situation to permit running your program
1685outside the debugger.
1686
1687The @code{kill} command is also useful if you wish to recompile and
1688relink your program, since on many systems it is impossible to modify an
1689executable file while it is running in a process. In this case, when you
1690next type @code{run}, @value{GDBN} notices that the file has changed, and
1691reads the symbol table again (while trying to preserve your current
1692breakpoint settings).
1693
53a5351d 1694@node Process Information
c906108c
SS
1695@section Additional process information
1696
1697@kindex /proc
1698@cindex process image
7a292a7a 1699
c906108c
SS
1700Some operating systems provide a facility called @samp{/proc} that can
1701be used to examine the image of a running process using file-system
1702subroutines. If @value{GDBN} is configured for an operating system with this
1703facility, the command @code{info proc} is available to report on several
1704kinds of information about the process running your program.
1705@code{info proc} works only on SVR4 systems that support @code{procfs}.
7a292a7a
SS
1706This includes OSF/1 (Digital Unix), Solaris, Irix, and Unixware,
1707but not HP-UX or Linux, for example.
c906108c
SS
1708
1709@table @code
1710@kindex info proc
1711@item info proc
1712Summarize available information about the process.
1713
1714@kindex info proc mappings
1715@item info proc mappings
1716Report on the address ranges accessible in the program, with information
1717on whether your program may read, write, or execute each range.
1718
1719@kindex info proc times
1720@item info proc times
1721Starting time, user CPU time, and system CPU time for your program and
1722its children.
1723
1724@kindex info proc id
1725@item info proc id
1726Report on the process IDs related to your program: its own process ID,
1727the ID of its parent, the process group ID, and the session ID.
1728
1729@kindex info proc status
1730@item info proc status
1731General information on the state of the process. If the process is
1732stopped, this report includes the reason for stopping, and any signal
1733received.
1734
1735@item info proc all
1736Show all the above information about the process.
1737@end table
c906108c 1738
53a5351d 1739@node Threads
c906108c 1740@section Debugging programs with multiple threads
c906108c
SS
1741
1742@cindex threads of execution
1743@cindex multiple threads
1744@cindex switching threads
1745In some operating systems, such as HP-UX and Solaris, a single program
1746may have more than one @dfn{thread} of execution. The precise semantics
1747of threads differ from one operating system to another, but in general
1748the threads of a single program are akin to multiple processes---except
1749that they share one address space (that is, they can all examine and
1750modify the same variables). On the other hand, each thread has its own
1751registers and execution stack, and perhaps private memory.
1752
1753@value{GDBN} provides these facilities for debugging multi-thread
1754programs:
1755
1756@itemize @bullet
1757@item automatic notification of new threads
1758@item @samp{thread @var{threadno}}, a command to switch among threads
1759@item @samp{info threads}, a command to inquire about existing threads
1760@item @samp{thread apply [@var{threadno}] [@var{all}] @var{args}},
1761a command to apply a command to a list of threads
1762@item thread-specific breakpoints
1763@end itemize
1764
c906108c
SS
1765@quotation
1766@emph{Warning:} These facilities are not yet available on every
1767@value{GDBN} configuration where the operating system supports threads.
1768If your @value{GDBN} does not support threads, these commands have no
1769effect. For example, a system without thread support shows no output
1770from @samp{info threads}, and always rejects the @code{thread} command,
1771like this:
1772
1773@smallexample
1774(@value{GDBP}) info threads
1775(@value{GDBP}) thread 1
1776Thread ID 1 not known. Use the "info threads" command to
1777see the IDs of currently known threads.
1778@end smallexample
1779@c FIXME to implementors: how hard would it be to say "sorry, this GDB
1780@c doesn't support threads"?
1781@end quotation
c906108c
SS
1782
1783@cindex focus of debugging
1784@cindex current thread
1785The @value{GDBN} thread debugging facility allows you to observe all
1786threads while your program runs---but whenever @value{GDBN} takes
1787control, one thread in particular is always the focus of debugging.
1788This thread is called the @dfn{current thread}. Debugging commands show
1789program information from the perspective of the current thread.
1790
c906108c
SS
1791@kindex New @var{systag}
1792@cindex thread identifier (system)
1793@c FIXME-implementors!! It would be more helpful if the [New...] message
1794@c included GDB's numeric thread handle, so you could just go to that
1795@c thread without first checking `info threads'.
1796Whenever @value{GDBN} detects a new thread in your program, it displays
1797the target system's identification for the thread with a message in the
1798form @samp{[New @var{systag}]}. @var{systag} is a thread identifier
1799whose form varies depending on the particular system. For example, on
1800LynxOS, you might see
1801
1802@example
1803[New process 35 thread 27]
1804@end example
1805
1806@noindent
1807when @value{GDBN} notices a new thread. In contrast, on an SGI system,
1808the @var{systag} is simply something like @samp{process 368}, with no
1809further qualifier.
1810
1811@c FIXME!! (1) Does the [New...] message appear even for the very first
1812@c thread of a program, or does it only appear for the
1813@c second---i.e., when it becomes obvious we have a multithread
1814@c program?
1815@c (2) *Is* there necessarily a first thread always? Or do some
1816@c multithread systems permit starting a program with multiple
1817@c threads ab initio?
1818
1819@cindex thread number
1820@cindex thread identifier (GDB)
1821For debugging purposes, @value{GDBN} associates its own thread
1822number---always a single integer---with each thread in your program.
1823
1824@table @code
1825@kindex info threads
1826@item info threads
1827Display a summary of all threads currently in your
1828program. @value{GDBN} displays for each thread (in this order):
1829
1830@enumerate
1831@item the thread number assigned by @value{GDBN}
1832
1833@item the target system's thread identifier (@var{systag})
1834
1835@item the current stack frame summary for that thread
1836@end enumerate
1837
1838@noindent
1839An asterisk @samp{*} to the left of the @value{GDBN} thread number
1840indicates the current thread.
1841
1842For example,
1843@end table
1844@c end table here to get a little more width for example
1845
1846@smallexample
1847(@value{GDBP}) info threads
1848 3 process 35 thread 27 0x34e5 in sigpause ()
1849 2 process 35 thread 23 0x34e5 in sigpause ()
1850* 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8)
1851 at threadtest.c:68
1852@end smallexample
53a5351d
JM
1853
1854On HP-UX systems:
c906108c
SS
1855
1856@cindex thread number
1857@cindex thread identifier (GDB)
1858For debugging purposes, @value{GDBN} associates its own thread
1859number---a small integer assigned in thread-creation order---with each
1860thread in your program.
1861
1862@kindex New @var{systag}
1863@cindex thread identifier (system)
1864@c FIXME-implementors!! It would be more helpful if the [New...] message
1865@c included GDB's numeric thread handle, so you could just go to that
1866@c thread without first checking `info threads'.
1867Whenever @value{GDBN} detects a new thread in your program, it displays
1868both @value{GDBN}'s thread number and the target system's identification for the thread with a message in the
1869form @samp{[New @var{systag}]}. @var{systag} is a thread identifier
1870whose form varies depending on the particular system. For example, on
1871HP-UX, you see
1872
1873@example
1874[New thread 2 (system thread 26594)]
1875@end example
1876
1877@noindent
1878when @value{GDBN} notices a new thread.
1879
1880@table @code
1881@kindex info threads
1882@item info threads
1883Display a summary of all threads currently in your
1884program. @value{GDBN} displays for each thread (in this order):
1885
1886@enumerate
1887@item the thread number assigned by @value{GDBN}
1888
1889@item the target system's thread identifier (@var{systag})
1890
1891@item the current stack frame summary for that thread
1892@end enumerate
1893
1894@noindent
1895An asterisk @samp{*} to the left of the @value{GDBN} thread number
1896indicates the current thread.
1897
1898For example,
1899@end table
1900@c end table here to get a little more width for example
1901
1902@example
1903(@value{GDBP}) info threads
1904 * 3 system thread 26607 worker (wptr=0x7b09c318 "@@") at quicksort.c:137
1905 2 system thread 26606 0x7b0030d8 in __ksleep () from /usr/lib/libc.2
1906 1 system thread 27905 0x7b003498 in _brk () from /usr/lib/libc.2
1907@end example
c906108c
SS
1908
1909@table @code
1910@kindex thread @var{threadno}
1911@item thread @var{threadno}
1912Make thread number @var{threadno} the current thread. The command
1913argument @var{threadno} is the internal @value{GDBN} thread number, as
1914shown in the first field of the @samp{info threads} display.
1915@value{GDBN} responds by displaying the system identifier of the thread
1916you selected, and its current stack frame summary:
1917
1918@smallexample
1919@c FIXME!! This example made up; find a @value{GDBN} w/threads and get real one
1920(@value{GDBP}) thread 2
c906108c 1921[Switching to process 35 thread 23]
c906108c
SS
19220x34e5 in sigpause ()
1923@end smallexample
1924
1925@noindent
1926As with the @samp{[New @dots{}]} message, the form of the text after
1927@samp{Switching to} depends on your system's conventions for identifying
1928threads.
1929
1930@kindex thread apply
1931@item thread apply [@var{threadno}] [@var{all}] @var{args}
1932The @code{thread apply} command allows you to apply a command to one or
1933more threads. Specify the numbers of the threads that you want affected
1934with the command argument @var{threadno}. @var{threadno} is the internal
1935@value{GDBN} thread number, as shown in the first field of the @samp{info
1936threads} display. To apply a command to all threads, use
1937@code{thread apply all} @var{args}.
1938@end table
1939
1940@cindex automatic thread selection
1941@cindex switching threads automatically
1942@cindex threads, automatic switching
1943Whenever @value{GDBN} stops your program, due to a breakpoint or a
1944signal, it automatically selects the thread where that breakpoint or
1945signal happened. @value{GDBN} alerts you to the context switch with a
1946message of the form @samp{[Switching to @var{systag}]} to identify the
1947thread.
1948
1949@xref{Thread Stops,,Stopping and starting multi-thread programs}, for
1950more information about how @value{GDBN} behaves when you stop and start
1951programs with multiple threads.
1952
1953@xref{Set Watchpoints,,Setting watchpoints}, for information about
1954watchpoints in programs with multiple threads.
c906108c 1955
53a5351d 1956@node Processes
c906108c
SS
1957@section Debugging programs with multiple processes
1958
1959@cindex fork, debugging programs which call
1960@cindex multiple processes
1961@cindex processes, multiple
53a5351d
JM
1962On most systems, @value{GDBN} has no special support for debugging
1963programs which create additional processes using the @code{fork}
1964function. When a program forks, @value{GDBN} will continue to debug the
1965parent process and the child process will run unimpeded. If you have
1966set a breakpoint in any code which the child then executes, the child
1967will get a @code{SIGTRAP} signal which (unless it catches the signal)
1968will cause it to terminate.
c906108c
SS
1969
1970However, if you want to debug the child process there is a workaround
1971which isn't too painful. Put a call to @code{sleep} in the code which
1972the child process executes after the fork. It may be useful to sleep
1973only if a certain environment variable is set, or a certain file exists,
1974so that the delay need not occur when you don't want to run @value{GDBN}
1975on the child. While the child is sleeping, use the @code{ps} program to
1976get its process ID. Then tell @value{GDBN} (a new invocation of
1977@value{GDBN} if you are also debugging the parent process) to attach to
1978the child process (see @ref{Attach}). From that point on you can debug
1979the child process just like any other process which you attached to.
c906108c 1980
53a5351d
JM
1981On HP-UX (11.x and later only?), @value{GDBN} provides support for
1982debugging programs that create additional processes using the
1983@code{fork} or @code{vfork} function.
c906108c
SS
1984
1985By default, when a program forks, @value{GDBN} will continue to debug
1986the parent process and the child process will run unimpeded.
1987
1988If you want to follow the child process instead of the parent process,
1989use the command @w{@code{set follow-fork-mode}}.
1990
1991@table @code
1992@kindex set follow-fork-mode
1993@item set follow-fork-mode @var{mode}
1994Set the debugger response to a program call of @code{fork} or
1995@code{vfork}. A call to @code{fork} or @code{vfork} creates a new
1996process. The @var{mode} can be:
1997
1998@table @code
1999@item parent
2000The original process is debugged after a fork. The child process runs
2001unimpeded.
2002
2003@item child
2004The new process is debugged after a fork. The parent process runs
2005unimpeded.
2006
2007@item ask
2008The debugger will ask for one of the above choices.
2009@end table
2010
2011@item show follow-fork-mode
2012Display the current debugger response to a fork or vfork call.
2013@end table
2014
2015If you ask to debug a child process and a @code{vfork} is followed by an
2016@code{exec}, @value{GDBN} executes the new target up to the first
2017breakpoint in the new target. If you have a breakpoint set on
2018@code{main} in your original program, the breakpoint will also be set on
2019the child process's @code{main}.
2020
2021When a child process is spawned by @code{vfork}, you cannot debug the
2022child or parent until an @code{exec} call completes.
2023
2024If you issue a @code{run} command to @value{GDBN} after an @code{exec}
2025call executes, the new target restarts. To restart the parent process,
2026use the @code{file} command with the parent executable name as its
2027argument.
2028
2029You can use the @code{catch} command to make @value{GDBN} stop whenever
2030a @code{fork}, @code{vfork}, or @code{exec} call is made. @xref{Set
2031Catchpoints, ,Setting catchpoints}.
c906108c 2032
53a5351d 2033@node Stopping
c906108c
SS
2034@chapter Stopping and Continuing
2035
2036The principal purposes of using a debugger are so that you can stop your
2037program before it terminates; or so that, if your program runs into
2038trouble, you can investigate and find out why.
2039
7a292a7a
SS
2040Inside @value{GDBN}, your program may stop for any of several reasons,
2041such as a signal, a breakpoint, or reaching a new line after a
2042@value{GDBN} command such as @code{step}. You may then examine and
2043change variables, set new breakpoints or remove old ones, and then
2044continue execution. Usually, the messages shown by @value{GDBN} provide
2045ample explanation of the status of your program---but you can also
2046explicitly request this information at any time.
c906108c
SS
2047
2048@table @code
2049@kindex info program
2050@item info program
2051Display information about the status of your program: whether it is
7a292a7a 2052running or not, what process it is, and why it stopped.
c906108c
SS
2053@end table
2054
2055@menu
2056* Breakpoints:: Breakpoints, watchpoints, and catchpoints
2057* Continuing and Stepping:: Resuming execution
c906108c 2058* Signals:: Signals
c906108c 2059* Thread Stops:: Stopping and starting multi-thread programs
c906108c
SS
2060@end menu
2061
53a5351d 2062@node Breakpoints
c906108c
SS
2063@section Breakpoints, watchpoints, and catchpoints
2064
2065@cindex breakpoints
2066A @dfn{breakpoint} makes your program stop whenever a certain point in
2067the program is reached. For each breakpoint, you can add conditions to
2068control in finer detail whether your program stops. You can set
2069breakpoints with the @code{break} command and its variants (@pxref{Set
2070Breaks, ,Setting breakpoints}), to specify the place where your program
2071should stop by line number, function name or exact address in the
2072program.
2073
2074In HP-UX, SunOS 4.x, SVR4, and Alpha OSF/1 configurations, you can set
2075breakpoints in shared libraries before the executable is run. There is
2076a minor limitation on HP-UX systems: you must wait until the executable
2077is run in order to set breakpoints in shared library routines that are
2078not called directly by the program (for example, routines that are
2079arguments in a @code{pthread_create} call).
2080
2081@cindex watchpoints
2082@cindex memory tracing
2083@cindex breakpoint on memory address
2084@cindex breakpoint on variable modification
2085A @dfn{watchpoint} is a special breakpoint that stops your program
2086when the value of an expression changes. You must use a different
2087command to set watchpoints (@pxref{Set Watchpoints, ,Setting
2088watchpoints}), but aside from that, you can manage a watchpoint like
2089any other breakpoint: you enable, disable, and delete both breakpoints
2090and watchpoints using the same commands.
2091
2092You can arrange to have values from your program displayed automatically
2093whenever @value{GDBN} stops at a breakpoint. @xref{Auto Display,,
2094Automatic display}.
2095
2096@cindex catchpoints
2097@cindex breakpoint on events
2098A @dfn{catchpoint} is another special breakpoint that stops your program
2099when a certain kind of event occurs, such as the throwing of a C++
2100exception or the loading of a library. As with watchpoints, you use a
2101different command to set a catchpoint (@pxref{Set Catchpoints, ,Setting
2102catchpoints}), but aside from that, you can manage a catchpoint like any
2103other breakpoint. (To stop when your program receives a signal, use the
2104@code{handle} command; @pxref{Signals, ,Signals}.)
2105
2106@cindex breakpoint numbers
2107@cindex numbers for breakpoints
2108@value{GDBN} assigns a number to each breakpoint, watchpoint, or
2109catchpoint when you create it; these numbers are successive integers
2110starting with one. In many of the commands for controlling various
2111features of breakpoints you use the breakpoint number to say which
2112breakpoint you want to change. Each breakpoint may be @dfn{enabled} or
2113@dfn{disabled}; if disabled, it has no effect on your program until you
2114enable it again.
2115
2116@menu
2117* Set Breaks:: Setting breakpoints
2118* Set Watchpoints:: Setting watchpoints
2119* Set Catchpoints:: Setting catchpoints
2120* Delete Breaks:: Deleting breakpoints
2121* Disabling:: Disabling breakpoints
2122* Conditions:: Break conditions
2123* Break Commands:: Breakpoint command lists
c906108c 2124* Breakpoint Menus:: Breakpoint menus
c906108c 2125
c906108c 2126@c * Error in Breakpoints:: ``Cannot insert breakpoints''
c906108c
SS
2127@end menu
2128
53a5351d 2129@node Set Breaks
c906108c
SS
2130@subsection Setting breakpoints
2131
2132@c FIXME LMB what does GDB do if no code on line of breakpt?
2133@c consider in particular declaration with/without initialization.
2134@c
2135@c FIXME 2 is there stuff on this already? break at fun start, already init?
2136
2137@kindex break
2138@kindex b
2139@kindex $bpnum
2140@cindex latest breakpoint
2141Breakpoints are set with the @code{break} command (abbreviated
2142@code{b}). The debugger convenience variable @samp{$bpnum} records the
2143number of the breakpoints you've set most recently; see @ref{Convenience
2144Vars,, Convenience variables}, for a discussion of what you can do with
2145convenience variables.
2146
2147You have several ways to say where the breakpoint should go.
2148
2149@table @code
2150@item break @var{function}
2151Set a breakpoint at entry to function @var{function}.
c906108c
SS
2152When using source languages that permit overloading of symbols, such as
2153C++, @var{function} may refer to more than one possible place to break.
2154@xref{Breakpoint Menus,,Breakpoint menus}, for a discussion of that situation.
c906108c
SS
2155
2156@item break +@var{offset}
2157@itemx break -@var{offset}
2158Set a breakpoint some number of lines forward or back from the position
2159at which execution stopped in the currently selected frame.
2160
2161@item break @var{linenum}
2162Set a breakpoint at line @var{linenum} in the current source file.
2163That file is the last file whose source text was printed. This
2164breakpoint stops your program just before it executes any of the
2165code on that line.
2166
2167@item break @var{filename}:@var{linenum}
2168Set a breakpoint at line @var{linenum} in source file @var{filename}.
2169
2170@item break @var{filename}:@var{function}
2171Set a breakpoint at entry to function @var{function} found in file
2172@var{filename}. Specifying a file name as well as a function name is
2173superfluous except when multiple files contain similarly named
2174functions.
2175
2176@item break *@var{address}
2177Set a breakpoint at address @var{address}. You can use this to set
2178breakpoints in parts of your program which do not have debugging
2179information or source files.
2180
2181@item break
2182When called without any arguments, @code{break} sets a breakpoint at
2183the next instruction to be executed in the selected stack frame
2184(@pxref{Stack, ,Examining the Stack}). In any selected frame but the
2185innermost, this makes your program stop as soon as control
2186returns to that frame. This is similar to the effect of a
2187@code{finish} command in the frame inside the selected frame---except
2188that @code{finish} does not leave an active breakpoint. If you use
2189@code{break} without an argument in the innermost frame, @value{GDBN} stops
2190the next time it reaches the current location; this may be useful
2191inside loops.
2192
2193@value{GDBN} normally ignores breakpoints when it resumes execution, until at
2194least one instruction has been executed. If it did not do this, you
2195would be unable to proceed past a breakpoint without first disabling the
2196breakpoint. This rule applies whether or not the breakpoint already
2197existed when your program stopped.
2198
2199@item break @dots{} if @var{cond}
2200Set a breakpoint with condition @var{cond}; evaluate the expression
2201@var{cond} each time the breakpoint is reached, and stop only if the
2202value is nonzero---that is, if @var{cond} evaluates as true.
2203@samp{@dots{}} stands for one of the possible arguments described
2204above (or no argument) specifying where to break. @xref{Conditions,
2205,Break conditions}, for more information on breakpoint conditions.
2206
2207@kindex tbreak
2208@item tbreak @var{args}
2209Set a breakpoint enabled only for one stop. @var{args} are the
2210same as for the @code{break} command, and the breakpoint is set in the same
2211way, but the breakpoint is automatically deleted after the first time your
2212program stops there. @xref{Disabling, ,Disabling breakpoints}.
2213
c906108c
SS
2214@kindex hbreak
2215@item hbreak @var{args}
2216Set a hardware-assisted breakpoint. @var{args} are the same as for the
2217@code{break} command and the breakpoint is set in the same way, but the
2218breakpoint requires hardware support and some target hardware may not
2219have this support. The main purpose of this is EPROM/ROM code
2220debugging, so you can set a breakpoint at an instruction without
2221changing the instruction. This can be used with the new trap-generation
2222provided by SPARClite DSU. DSU will generate traps when a program accesses
2223some data or instruction address that is assigned to the debug registers.
2224However the hardware breakpoint registers can only take two data breakpoints,
2225and @value{GDBN} will reject this command if more than two are used.
2226Delete or disable unused hardware breakpoints before setting
2227new ones. @xref{Conditions, ,Break conditions}.
2228
2229@kindex thbreak
2230@item thbreak @var{args}
2231Set a hardware-assisted breakpoint enabled only for one stop. @var{args}
2232are the same as for the @code{hbreak} command and the breakpoint is set in
2233the same way. However, like the @code{tbreak} command,
2234the breakpoint is automatically deleted after the
2235first time your program stops there. Also, like the @code{hbreak}
2236command, the breakpoint requires hardware support and some target hardware
2237may not have this support. @xref{Disabling, ,Disabling breakpoints}.
2238Also @xref{Conditions, ,Break conditions}.
c906108c
SS
2239
2240@kindex rbreak
2241@cindex regular expression
2242@item rbreak @var{regex}
2243@c FIXME what kind of regexp?
2244Set breakpoints on all functions matching the regular expression
2245@var{regex}. This command
2246sets an unconditional breakpoint on all matches, printing a list of all
2247breakpoints it set. Once these breakpoints are set, they are treated
2248just like the breakpoints set with the @code{break} command. You can
2249delete them, disable them, or make them conditional the same way as any
2250other breakpoint.
2251
c906108c
SS
2252When debugging C++ programs, @code{rbreak} is useful for setting
2253breakpoints on overloaded functions that are not members of any special
2254classes.
c906108c
SS
2255
2256@kindex info breakpoints
2257@cindex @code{$_} and @code{info breakpoints}
2258@item info breakpoints @r{[}@var{n}@r{]}
2259@itemx info break @r{[}@var{n}@r{]}
2260@itemx info watchpoints @r{[}@var{n}@r{]}
2261Print a table of all breakpoints, watchpoints, and catchpoints set and
2262not deleted, with the following columns for each breakpoint:
2263
2264@table @emph
2265@item Breakpoint Numbers
2266@item Type
2267Breakpoint, watchpoint, or catchpoint.
2268@item Disposition
2269Whether the breakpoint is marked to be disabled or deleted when hit.
2270@item Enabled or Disabled
2271Enabled breakpoints are marked with @samp{y}. @samp{n} marks breakpoints
2272that are not enabled.
2273@item Address
2274Where the breakpoint is in your program, as a memory address
2275@item What
2276Where the breakpoint is in the source for your program, as a file and
2277line number.
2278@end table
2279
2280@noindent
2281If a breakpoint is conditional, @code{info break} shows the condition on
2282the line following the affected breakpoint; breakpoint commands, if any,
2283are listed after that.
2284
2285@noindent
2286@code{info break} with a breakpoint
2287number @var{n} as argument lists only that breakpoint. The
2288convenience variable @code{$_} and the default examining-address for
2289the @code{x} command are set to the address of the last breakpoint
2290listed (@pxref{Memory, ,Examining memory}).
2291
2292@noindent
2293@code{info break} displays a count of the number of times the breakpoint
2294has been hit. This is especially useful in conjunction with the
2295@code{ignore} command. You can ignore a large number of breakpoint
2296hits, look at the breakpoint info to see how many times the breakpoint
2297was hit, and then run again, ignoring one less than that number. This
2298will get you quickly to the last hit of that breakpoint.
2299@end table
2300
2301@value{GDBN} allows you to set any number of breakpoints at the same place in
2302your program. There is nothing silly or meaningless about this. When
2303the breakpoints are conditional, this is even useful
2304(@pxref{Conditions, ,Break conditions}).
2305
2306@cindex negative breakpoint numbers
2307@cindex internal @value{GDBN} breakpoints
2308@value{GDBN} itself sometimes sets breakpoints in your program for special
2309purposes, such as proper handling of @code{longjmp} (in C programs).
2310These internal breakpoints are assigned negative numbers, starting with
2311@code{-1}; @samp{info breakpoints} does not display them.
2312
2313You can see these breakpoints with the @value{GDBN} maintenance command
2314@samp{maint info breakpoints}.
2315
2316@table @code
2317@kindex maint info breakpoints
2318@item maint info breakpoints
2319Using the same format as @samp{info breakpoints}, display both the
2320breakpoints you've set explicitly, and those @value{GDBN} is using for
2321internal purposes. Internal breakpoints are shown with negative
2322breakpoint numbers. The type column identifies what kind of breakpoint
2323is shown:
2324
2325@table @code
2326@item breakpoint
2327Normal, explicitly set breakpoint.
2328
2329@item watchpoint
2330Normal, explicitly set watchpoint.
2331
2332@item longjmp
2333Internal breakpoint, used to handle correctly stepping through
2334@code{longjmp} calls.
2335
2336@item longjmp resume
2337Internal breakpoint at the target of a @code{longjmp}.
2338
2339@item until
2340Temporary internal breakpoint used by the @value{GDBN} @code{until} command.
2341
2342@item finish
2343Temporary internal breakpoint used by the @value{GDBN} @code{finish} command.
2344
c906108c
SS
2345@item shlib events
2346Shared library events.
53a5351d 2347
c906108c 2348@end table
53a5351d 2349
c906108c
SS
2350@end table
2351
2352
53a5351d 2353@node Set Watchpoints
c906108c
SS
2354@subsection Setting watchpoints
2355
2356@cindex setting watchpoints
2357@cindex software watchpoints
2358@cindex hardware watchpoints
2359You can use a watchpoint to stop execution whenever the value of an
2360expression changes, without having to predict a particular place where
2361this may happen.
2362
2363Depending on your system, watchpoints may be implemented in software or
2364hardware. GDB does software watchpointing by single-stepping your
2365program and testing the variable's value each time, which is hundreds of
2366times slower than normal execution. (But this may still be worth it, to
2367catch errors where you have no clue what part of your program is the
2368culprit.)
2369
2370On some systems, such as HP-UX and Linux, GDB includes support for
2371hardware watchpoints, which do not slow down the running of your
2372program.
2373
2374@table @code
2375@kindex watch
2376@item watch @var{expr}
2377Set a watchpoint for an expression. @value{GDBN} will break when @var{expr}
2378is written into by the program and its value changes.
2379
2380@kindex rwatch
2381@item rwatch @var{expr}
2382Set a watchpoint that will break when watch @var{expr} is read by the program.
c906108c
SS
2383
2384@kindex awatch
2385@item awatch @var{expr}
2386Set a watchpoint that will break when @var{args} is read and written into
7be570e7 2387by the program.
c906108c
SS
2388
2389@kindex info watchpoints
2390@item info watchpoints
2391This command prints a list of watchpoints, breakpoints, and catchpoints;
2392it is the same as @code{info break}.
2393@end table
2394
2395@value{GDBN} sets a @dfn{hardware watchpoint} if possible. Hardware
2396watchpoints execute very quickly, and the debugger reports a change in
2397value at the exact instruction where the change occurs. If @value{GDBN}
2398cannot set a hardware watchpoint, it sets a software watchpoint, which
2399executes more slowly and reports the change in value at the next
2400statement, not the instruction, after the change occurs.
2401
2402When you issue the @code{watch} command, @value{GDBN} reports
2403
2404@example
2405Hardware watchpoint @var{num}: @var{expr}
2406@end example
2407
2408@noindent
2409if it was able to set a hardware watchpoint.
2410
7be570e7
JM
2411Currently, the @code{awatch} and @code{rwatch} commands can only set
2412hardware watchpoints, because accesses to data that don't change the
2413value of the watched expression cannot be detected without examining
2414every instruction as it is being executed, and @value{GDBN} does not do
2415that currently. If @value{GDBN} finds that it is unable to set a
2416hardware breakpoint with the @code{awatch} or @code{rwatch} command, it
2417will print a message like this:
2418
2419@smallexample
2420Expression cannot be implemented with read/access watchpoint.
2421@end smallexample
2422
2423Sometimes, @value{GDBN} cannot set a hardware watchpoint because the
2424data type of the watched expression is wider than what a hardware
2425watchpoint on the target machine can handle. For example, some systems
2426can only watch regions that are up to 4 bytes wide; on such systems you
2427cannot set hardware watchpoints for an expression that yields a
2428double-precision floating-point number (which is typically 8 bytes
2429wide). As a work-around, it might be possible to break the large region
2430into a series of smaller ones and watch them with separate watchpoints.
2431
2432If you set too many hardware watchpoints, @value{GDBN} might be unable
2433to insert all of them when you resume the execution of your program.
2434Since the precise number of active watchpoints is unknown until such
2435time as the program is about to be resumed, @value{GDBN} might not be
2436able to warn you about this when you set the watchpoints, and the
2437warning will be printed only when the program is resumed:
2438
2439@smallexample
2440Hardware watchpoint @var{num}: Could not insert watchpoint
2441@end smallexample
2442
2443@noindent
2444If this happens, delete or disable some of the watchpoints.
2445
2446The SPARClite DSU will generate traps when a program accesses some data
2447or instruction address that is assigned to the debug registers. For the
2448data addresses, DSU facilitates the @code{watch} command. However the
2449hardware breakpoint registers can only take two data watchpoints, and
2450both watchpoints must be the same kind. For example, you can set two
2451watchpoints with @code{watch} commands, two with @code{rwatch} commands,
2452@strong{or} two with @code{awatch} commands, but you cannot set one
2453watchpoint with one command and the other with a different command.
c906108c
SS
2454@value{GDBN} will reject the command if you try to mix watchpoints.
2455Delete or disable unused watchpoint commands before setting new ones.
2456
2457If you call a function interactively using @code{print} or @code{call},
2458any watchpoints you have set will be inactive until GDB reaches another
2459kind of breakpoint or the call completes.
2460
7be570e7
JM
2461@value{GDBN} automatically deletes watchpoints that watch local
2462(automatic) variables, or expressions that involve such variables, when
2463they go out of scope, that is, when the execution leaves the block in
2464which these variables were defined. In particular, when the program
2465being debugged terminates, @emph{all} local variables go out of scope,
2466and so only watchpoints that watch global variables remain set. If you
2467rerun the program, you will need to set all such watchpoints again. One
2468way of doing that would be to set a code breakpoint at the entry to the
2469@code{main} function and when it breaks, set all the watchpoints.
2470
c906108c
SS
2471@quotation
2472@cindex watchpoints and threads
2473@cindex threads and watchpoints
c906108c
SS
2474@emph{Warning:} In multi-thread programs, watchpoints have only limited
2475usefulness. With the current watchpoint implementation, @value{GDBN}
2476can only watch the value of an expression @emph{in a single thread}. If
2477you are confident that the expression can only change due to the current
2478thread's activity (and if you are also confident that no other thread
2479can become current), then you can use watchpoints as usual. However,
2480@value{GDBN} may not notice when a non-current thread's activity changes
2481the expression.
53a5351d
JM
2482
2483@emph{HP-UX Warning:} In multi-thread programs, software watchpoints
2484have only limited usefulness. If @value{GDBN} creates a software
2485watchpoint, it can only watch the value of an expression @emph{in a
2486single thread}. If you are confident that the expression can only
2487change due to the current thread's activity (and if you are also
2488confident that no other thread can become current), then you can use
2489software watchpoints as usual. However, @value{GDBN} may not notice
2490when a non-current thread's activity changes the expression. (Hardware
2491watchpoints, in contrast, watch an expression in all threads.)
c906108c 2492@end quotation
c906108c 2493
53a5351d 2494@node Set Catchpoints
c906108c
SS
2495@subsection Setting catchpoints
2496@cindex catchpoints
2497@cindex exception handlers
2498@cindex event handling
2499
2500You can use @dfn{catchpoints} to cause the debugger to stop for certain
2501kinds of program events, such as C++ exceptions or the loading of a
2502shared library. Use the @code{catch} command to set a catchpoint.
2503
2504@table @code
2505@kindex catch
2506@item catch @var{event}
2507Stop when @var{event} occurs. @var{event} can be any of the following:
2508@table @code
2509@item throw
2510@kindex catch throw
2511The throwing of a C++ exception.
2512
2513@item catch
2514@kindex catch catch
2515The catching of a C++ exception.
2516
2517@item exec
2518@kindex catch exec
2519A call to @code{exec}. This is currently only available for HP-UX.
2520
2521@item fork
2522@kindex catch fork
2523A call to @code{fork}. This is currently only available for HP-UX.
2524
2525@item vfork
2526@kindex catch vfork
2527A call to @code{vfork}. This is currently only available for HP-UX.
2528
2529@item load
2530@itemx load @var{libname}
2531@kindex catch load
2532The dynamic loading of any shared library, or the loading of the library
2533@var{libname}. This is currently only available for HP-UX.
2534
2535@item unload
2536@itemx unload @var{libname}
2537@kindex catch unload
2538The unloading of any dynamically loaded shared library, or the unloading
2539of the library @var{libname}. This is currently only available for HP-UX.
2540@end table
2541
2542@item tcatch @var{event}
2543Set a catchpoint that is enabled only for one stop. The catchpoint is
2544automatically deleted after the first time the event is caught.
2545
2546@end table
2547
2548Use the @code{info break} command to list the current catchpoints.
2549
2550There are currently some limitations to C++ exception handling
2551(@code{catch throw} and @code{catch catch}) in @value{GDBN}:
2552
2553@itemize @bullet
2554@item
2555If you call a function interactively, @value{GDBN} normally returns
2556control to you when the function has finished executing. If the call
2557raises an exception, however, the call may bypass the mechanism that
2558returns control to you and cause your program either to abort or to
2559simply continue running until it hits a breakpoint, catches a signal
2560that @value{GDBN} is listening for, or exits. This is the case even if
2561you set a catchpoint for the exception; catchpoints on exceptions are
2562disabled within interactive calls.
2563
2564@item
2565You cannot raise an exception interactively.
2566
2567@item
2568You cannot install an exception handler interactively.
2569@end itemize
2570
2571@cindex raise exceptions
2572Sometimes @code{catch} is not the best way to debug exception handling:
2573if you need to know exactly where an exception is raised, it is better to
2574stop @emph{before} the exception handler is called, since that way you
2575can see the stack before any unwinding takes place. If you set a
2576breakpoint in an exception handler instead, it may not be easy to find
2577out where the exception was raised.
2578
2579To stop just before an exception handler is called, you need some
2580knowledge of the implementation. In the case of @sc{gnu} C++, exceptions are
2581raised by calling a library function named @code{__raise_exception}
2582which has the following ANSI C interface:
2583
2584@example
2585 /* @var{addr} is where the exception identifier is stored.
2586 ID is the exception identifier. */
2587 void __raise_exception (void **@var{addr}, void *@var{id});
2588@end example
2589
2590@noindent
2591To make the debugger catch all exceptions before any stack
2592unwinding takes place, set a breakpoint on @code{__raise_exception}
2593(@pxref{Breakpoints, ,Breakpoints; watchpoints; and exceptions}).
2594
2595With a conditional breakpoint (@pxref{Conditions, ,Break conditions})
2596that depends on the value of @var{id}, you can stop your program when
2597a specific exception is raised. You can use multiple conditional
2598breakpoints to stop your program when any of a number of exceptions are
2599raised.
2600
2601
53a5351d 2602@node Delete Breaks
c906108c
SS
2603@subsection Deleting breakpoints
2604
2605@cindex clearing breakpoints, watchpoints, catchpoints
2606@cindex deleting breakpoints, watchpoints, catchpoints
2607It is often necessary to eliminate a breakpoint, watchpoint, or
2608catchpoint once it has done its job and you no longer want your program
2609to stop there. This is called @dfn{deleting} the breakpoint. A
2610breakpoint that has been deleted no longer exists; it is forgotten.
2611
2612With the @code{clear} command you can delete breakpoints according to
2613where they are in your program. With the @code{delete} command you can
2614delete individual breakpoints, watchpoints, or catchpoints by specifying
2615their breakpoint numbers.
2616
2617It is not necessary to delete a breakpoint to proceed past it. @value{GDBN}
2618automatically ignores breakpoints on the first instruction to be executed
2619when you continue execution without changing the execution address.
2620
2621@table @code
2622@kindex clear
2623@item clear
2624Delete any breakpoints at the next instruction to be executed in the
2625selected stack frame (@pxref{Selection, ,Selecting a frame}). When
2626the innermost frame is selected, this is a good way to delete a
2627breakpoint where your program just stopped.
2628
2629@item clear @var{function}
2630@itemx clear @var{filename}:@var{function}
2631Delete any breakpoints set at entry to the function @var{function}.
2632
2633@item clear @var{linenum}
2634@itemx clear @var{filename}:@var{linenum}
2635Delete any breakpoints set at or within the code of the specified line.
2636
2637@cindex delete breakpoints
2638@kindex delete
2639@kindex d
2640@item delete @r{[}breakpoints@r{]} @r{[}@var{bnums}@dots{}@r{]}
2641Delete the breakpoints, watchpoints, or catchpoints of the numbers
2642specified as arguments. If no argument is specified, delete all
2643breakpoints (@value{GDBN} asks confirmation, unless you have @code{set
2644confirm off}). You can abbreviate this command as @code{d}.
2645@end table
2646
53a5351d 2647@node Disabling
c906108c
SS
2648@subsection Disabling breakpoints
2649
2650@kindex disable breakpoints
2651@kindex enable breakpoints
2652Rather than deleting a breakpoint, watchpoint, or catchpoint, you might
2653prefer to @dfn{disable} it. This makes the breakpoint inoperative as if
2654it had been deleted, but remembers the information on the breakpoint so
2655that you can @dfn{enable} it again later.
2656
2657You disable and enable breakpoints, watchpoints, and catchpoints with
2658the @code{enable} and @code{disable} commands, optionally specifying one
2659or more breakpoint numbers as arguments. Use @code{info break} or
2660@code{info watch} to print a list of breakpoints, watchpoints, and
2661catchpoints if you do not know which numbers to use.
2662
2663A breakpoint, watchpoint, or catchpoint can have any of four different
2664states of enablement:
2665
2666@itemize @bullet
2667@item
2668Enabled. The breakpoint stops your program. A breakpoint set
2669with the @code{break} command starts out in this state.
2670@item
2671Disabled. The breakpoint has no effect on your program.
2672@item
2673Enabled once. The breakpoint stops your program, but then becomes
2674disabled. A breakpoint set with the @code{tbreak} command starts out in
2675this state.
2676@item
2677Enabled for deletion. The breakpoint stops your program, but
2678immediately after it does so it is deleted permanently.
2679@end itemize
2680
2681You can use the following commands to enable or disable breakpoints,
2682watchpoints, and catchpoints:
2683
2684@table @code
2685@kindex disable breakpoints
2686@kindex disable
2687@kindex dis
2688@item disable @r{[}breakpoints@r{]} @r{[}@var{bnums}@dots{}@r{]}
2689Disable the specified breakpoints---or all breakpoints, if none are
2690listed. A disabled breakpoint has no effect but is not forgotten. All
2691options such as ignore-counts, conditions and commands are remembered in
2692case the breakpoint is enabled again later. You may abbreviate
2693@code{disable} as @code{dis}.
2694
2695@kindex enable breakpoints
2696@kindex enable
2697@item enable @r{[}breakpoints@r{]} @r{[}@var{bnums}@dots{}@r{]}
2698Enable the specified breakpoints (or all defined breakpoints). They
2699become effective once again in stopping your program.
2700
2701@item enable @r{[}breakpoints@r{]} once @var{bnums}@dots{}
2702Enable the specified breakpoints temporarily. @value{GDBN} disables any
2703of these breakpoints immediately after stopping your program.
2704
2705@item enable @r{[}breakpoints@r{]} delete @var{bnums}@dots{}
2706Enable the specified breakpoints to work once, then die. @value{GDBN}
2707deletes any of these breakpoints as soon as your program stops there.
2708@end table
2709
2710Except for a breakpoint set with @code{tbreak} (@pxref{Set Breaks,
2711,Setting breakpoints}), breakpoints that you set are initially enabled;
2712subsequently, they become disabled or enabled only when you use one of
2713the commands above. (The command @code{until} can set and delete a
2714breakpoint of its own, but it does not change the state of your other
2715breakpoints; see @ref{Continuing and Stepping, ,Continuing and
2716stepping}.)
2717
53a5351d 2718@node Conditions
c906108c
SS
2719@subsection Break conditions
2720@cindex conditional breakpoints
2721@cindex breakpoint conditions
2722
2723@c FIXME what is scope of break condition expr? Context where wanted?
2724@c in particular for a watchpoint?
2725The simplest sort of breakpoint breaks every time your program reaches a
2726specified place. You can also specify a @dfn{condition} for a
2727breakpoint. A condition is just a Boolean expression in your
2728programming language (@pxref{Expressions, ,Expressions}). A breakpoint with
2729a condition evaluates the expression each time your program reaches it,
2730and your program stops only if the condition is @emph{true}.
2731
2732This is the converse of using assertions for program validation; in that
2733situation, you want to stop when the assertion is violated---that is,
2734when the condition is false. In C, if you want to test an assertion expressed
2735by the condition @var{assert}, you should set the condition
2736@samp{! @var{assert}} on the appropriate breakpoint.
2737
2738Conditions are also accepted for watchpoints; you may not need them,
2739since a watchpoint is inspecting the value of an expression anyhow---but
2740it might be simpler, say, to just set a watchpoint on a variable name,
2741and specify a condition that tests whether the new value is an interesting
2742one.
2743
2744Break conditions can have side effects, and may even call functions in
2745your program. This can be useful, for example, to activate functions
2746that log program progress, or to use your own print functions to
2747format special data structures. The effects are completely predictable
2748unless there is another enabled breakpoint at the same address. (In
2749that case, @value{GDBN} might see the other breakpoint first and stop your
2750program without checking the condition of this one.) Note that
2751breakpoint commands are usually more convenient and flexible for the
2752purpose of performing side effects when a breakpoint is reached
2753(@pxref{Break Commands, ,Breakpoint command lists}).
2754
2755Break conditions can be specified when a breakpoint is set, by using
2756@samp{if} in the arguments to the @code{break} command. @xref{Set
2757Breaks, ,Setting breakpoints}. They can also be changed at any time
2758with the @code{condition} command.
53a5351d 2759
c906108c
SS
2760You can also use the @code{if} keyword with the @code{watch} command.
2761The @code{catch} command does not recognize the @code{if} keyword;
2762@code{condition} is the only way to impose a further condition on a
2763catchpoint.
c906108c
SS
2764
2765@table @code
2766@kindex condition
2767@item condition @var{bnum} @var{expression}
2768Specify @var{expression} as the break condition for breakpoint,
2769watchpoint, or catchpoint number @var{bnum}. After you set a condition,
2770breakpoint @var{bnum} stops your program only if the value of
2771@var{expression} is true (nonzero, in C). When you use
2772@code{condition}, @value{GDBN} checks @var{expression} immediately for
2773syntactic correctness, and to determine whether symbols in it have
2774referents in the context of your breakpoint.
2775@c FIXME so what does GDB do if there is no referent? Moreover, what
2776@c about watchpoints?
2777@value{GDBN} does
2778not actually evaluate @var{expression} at the time the @code{condition}
2779command is given, however. @xref{Expressions, ,Expressions}.
2780
2781@item condition @var{bnum}
2782Remove the condition from breakpoint number @var{bnum}. It becomes
2783an ordinary unconditional breakpoint.
2784@end table
2785
2786@cindex ignore count (of breakpoint)
2787A special case of a breakpoint condition is to stop only when the
2788breakpoint has been reached a certain number of times. This is so
2789useful that there is a special way to do it, using the @dfn{ignore
2790count} of the breakpoint. Every breakpoint has an ignore count, which
2791is an integer. Most of the time, the ignore count is zero, and
2792therefore has no effect. But if your program reaches a breakpoint whose
2793ignore count is positive, then instead of stopping, it just decrements
2794the ignore count by one and continues. As a result, if the ignore count
2795value is @var{n}, the breakpoint does not stop the next @var{n} times
2796your program reaches it.
2797
2798@table @code
2799@kindex ignore
2800@item ignore @var{bnum} @var{count}
2801Set the ignore count of breakpoint number @var{bnum} to @var{count}.
2802The next @var{count} times the breakpoint is reached, your program's
2803execution does not stop; other than to decrement the ignore count, @value{GDBN}
2804takes no action.
2805
2806To make the breakpoint stop the next time it is reached, specify
2807a count of zero.
2808
2809When you use @code{continue} to resume execution of your program from a
2810breakpoint, you can specify an ignore count directly as an argument to
2811@code{continue}, rather than using @code{ignore}. @xref{Continuing and
2812Stepping,,Continuing and stepping}.
2813
2814If a breakpoint has a positive ignore count and a condition, the
2815condition is not checked. Once the ignore count reaches zero,
2816@value{GDBN} resumes checking the condition.
2817
2818You could achieve the effect of the ignore count with a condition such
2819as @w{@samp{$foo-- <= 0}} using a debugger convenience variable that
2820is decremented each time. @xref{Convenience Vars, ,Convenience
2821variables}.
2822@end table
2823
2824Ignore counts apply to breakpoints, watchpoints, and catchpoints.
2825
2826
53a5351d 2827@node Break Commands
c906108c
SS
2828@subsection Breakpoint command lists
2829
2830@cindex breakpoint commands
2831You can give any breakpoint (or watchpoint or catchpoint) a series of
2832commands to execute when your program stops due to that breakpoint. For
2833example, you might want to print the values of certain expressions, or
2834enable other breakpoints.
2835
2836@table @code
2837@kindex commands
2838@kindex end
2839@item commands @r{[}@var{bnum}@r{]}
2840@itemx @dots{} @var{command-list} @dots{}
2841@itemx end
2842Specify a list of commands for breakpoint number @var{bnum}. The commands
2843themselves appear on the following lines. Type a line containing just
2844@code{end} to terminate the commands.
2845
2846To remove all commands from a breakpoint, type @code{commands} and
2847follow it immediately with @code{end}; that is, give no commands.
2848
2849With no @var{bnum} argument, @code{commands} refers to the last
2850breakpoint, watchpoint, or catchpoint set (not to the breakpoint most
2851recently encountered).
2852@end table
2853
2854Pressing @key{RET} as a means of repeating the last @value{GDBN} command is
2855disabled within a @var{command-list}.
2856
2857You can use breakpoint commands to start your program up again. Simply
2858use the @code{continue} command, or @code{step}, or any other command
2859that resumes execution.
2860
2861Any other commands in the command list, after a command that resumes
2862execution, are ignored. This is because any time you resume execution
2863(even with a simple @code{next} or @code{step}), you may encounter
2864another breakpoint---which could have its own command list, leading to
2865ambiguities about which list to execute.
2866
2867@kindex silent
2868If the first command you specify in a command list is @code{silent}, the
2869usual message about stopping at a breakpoint is not printed. This may
2870be desirable for breakpoints that are to print a specific message and
2871then continue. If none of the remaining commands print anything, you
2872see no sign that the breakpoint was reached. @code{silent} is
2873meaningful only at the beginning of a breakpoint command list.
2874
2875The commands @code{echo}, @code{output}, and @code{printf} allow you to
2876print precisely controlled output, and are often useful in silent
2877breakpoints. @xref{Output, ,Commands for controlled output}.
2878
2879For example, here is how you could use breakpoint commands to print the
2880value of @code{x} at entry to @code{foo} whenever @code{x} is positive.
2881
2882@example
2883break foo if x>0
2884commands
2885silent
2886printf "x is %d\n",x
2887cont
2888end
2889@end example
2890
2891One application for breakpoint commands is to compensate for one bug so
2892you can test for another. Put a breakpoint just after the erroneous line
2893of code, give it a condition to detect the case in which something
2894erroneous has been done, and give it commands to assign correct values
2895to any variables that need them. End with the @code{continue} command
2896so that your program does not stop, and start with the @code{silent}
2897command so that no output is produced. Here is an example:
2898
2899@example
2900break 403
2901commands
2902silent
2903set x = y + 4
2904cont
2905end
2906@end example
2907
53a5351d 2908@node Breakpoint Menus
c906108c
SS
2909@subsection Breakpoint menus
2910@cindex overloading
2911@cindex symbol overloading
2912
2913Some programming languages (notably C++) permit a single function name
2914to be defined several times, for application in different contexts.
2915This is called @dfn{overloading}. When a function name is overloaded,
2916@samp{break @var{function}} is not enough to tell @value{GDBN} where you want
2917a breakpoint. If you realize this is a problem, you can use
2918something like @samp{break @var{function}(@var{types})} to specify which
2919particular version of the function you want. Otherwise, @value{GDBN} offers
2920you a menu of numbered choices for different possible breakpoints, and
2921waits for your selection with the prompt @samp{>}. The first two
2922options are always @samp{[0] cancel} and @samp{[1] all}. Typing @kbd{1}
2923sets a breakpoint at each definition of @var{function}, and typing
2924@kbd{0} aborts the @code{break} command without setting any new
2925breakpoints.
2926
2927For example, the following session excerpt shows an attempt to set a
2928breakpoint at the overloaded symbol @code{String::after}.
2929We choose three particular definitions of that function name:
2930
2931@c FIXME! This is likely to change to show arg type lists, at least
2932@smallexample
2933@group
2934(@value{GDBP}) b String::after
2935[0] cancel
2936[1] all
2937[2] file:String.cc; line number:867
2938[3] file:String.cc; line number:860
2939[4] file:String.cc; line number:875
2940[5] file:String.cc; line number:853
2941[6] file:String.cc; line number:846
2942[7] file:String.cc; line number:735
2943> 2 4 6
2944Breakpoint 1 at 0xb26c: file String.cc, line 867.
2945Breakpoint 2 at 0xb344: file String.cc, line 875.
2946Breakpoint 3 at 0xafcc: file String.cc, line 846.
2947Multiple breakpoints were set.
2948Use the "delete" command to delete unwanted
2949 breakpoints.
2950(@value{GDBP})
2951@end group
2952@end smallexample
c906108c
SS
2953
2954@c @ifclear BARETARGET
2955@c @node Error in Breakpoints
2956@c @subsection ``Cannot insert breakpoints''
2957@c
2958@c FIXME!! 14/6/95 Is there a real example of this? Let's use it.
2959@c
53a5351d 2960@c Under some operating systems
c906108c
SS
2961@c any other process is running that program. In this situation,
2962@c attempting to run or continue a program with a breakpoint causes
2963@c @value{GDBN} to stop the other process.
2964@c
2965@c When this happens, you have three ways to proceed:
2966@c
2967@c @enumerate
2968@c @item
2969@c Remove or disable the breakpoints, then continue.
2970@c
2971@c @item
2972@c Suspend @value{GDBN}, and copy the file containing your program to a new
2973@c name. Resume @value{GDBN} and use the @code{exec-file} command to specify
2974@c that @value{GDBN} should run your program under that name.
2975@c Then start your program again.
2976@c
2977@c @item
2978@c Relink your program so that the text segment is nonsharable, using the
2979@c linker option @samp{-N}. The operating system limitation may not apply
2980@c to nonsharable executables.
2981@c @end enumerate
2982@c @end ifclear
2983
53a5351d 2984@node Continuing and Stepping
c906108c
SS
2985@section Continuing and stepping
2986
2987@cindex stepping
2988@cindex continuing
2989@cindex resuming execution
2990@dfn{Continuing} means resuming program execution until your program
2991completes normally. In contrast, @dfn{stepping} means executing just
2992one more ``step'' of your program, where ``step'' may mean either one
2993line of source code, or one machine instruction (depending on what
7a292a7a
SS
2994particular command you use). Either when continuing or when stepping,
2995your program may stop even sooner, due to a breakpoint or a signal. (If
2996due to a signal, you may want to use @code{handle}, or use @samp{signal
29970} to resume execution. @xref{Signals, ,Signals}.)
c906108c
SS
2998
2999@table @code
3000@kindex continue
3001@kindex c
3002@kindex fg
3003@item continue @r{[}@var{ignore-count}@r{]}
3004@itemx c @r{[}@var{ignore-count}@r{]}
3005@itemx fg @r{[}@var{ignore-count}@r{]}
3006Resume program execution, at the address where your program last stopped;
3007any breakpoints set at that address are bypassed. The optional argument
3008@var{ignore-count} allows you to specify a further number of times to
3009ignore a breakpoint at this location; its effect is like that of
3010@code{ignore} (@pxref{Conditions, ,Break conditions}).
3011
3012The argument @var{ignore-count} is meaningful only when your program
3013stopped due to a breakpoint. At other times, the argument to
3014@code{continue} is ignored.
3015
3016The synonyms @code{c} and @code{fg} are provided purely for convenience,
3017and have exactly the same behavior as @code{continue}.
3018@end table
3019
3020To resume execution at a different place, you can use @code{return}
3021(@pxref{Returning, ,Returning from a function}) to go back to the
3022calling function; or @code{jump} (@pxref{Jumping, ,Continuing at a
3023different address}) to go to an arbitrary location in your program.
3024
3025A typical technique for using stepping is to set a breakpoint
3026(@pxref{Breakpoints, ,Breakpoints; watchpoints; and catchpoints}) at the
3027beginning of the function or the section of your program where a problem
3028is believed to lie, run your program until it stops at that breakpoint,
3029and then step through the suspect area, examining the variables that are
3030interesting, until you see the problem happen.
3031
3032@table @code
3033@kindex step
3034@kindex s
3035@item step
3036Continue running your program until control reaches a different source
3037line, then stop it and return control to @value{GDBN}. This command is
3038abbreviated @code{s}.
3039
3040@quotation
3041@c "without debugging information" is imprecise; actually "without line
3042@c numbers in the debugging information". (gcc -g1 has debugging info but
3043@c not line numbers). But it seems complex to try to make that
3044@c distinction here.
3045@emph{Warning:} If you use the @code{step} command while control is
3046within a function that was compiled without debugging information,
3047execution proceeds until control reaches a function that does have
3048debugging information. Likewise, it will not step into a function which
3049is compiled without debugging information. To step through functions
3050without debugging information, use the @code{stepi} command, described
3051below.
3052@end quotation
3053
3054The @code{step} command now only stops at the first instruction of a
3055source line. This prevents the multiple stops that used to occur in
3056switch statements, for loops, etc. @code{step} continues to stop if a
3057function that has debugging information is called within the line.
3058
3059Also, the @code{step} command now only enters a subroutine if there is line
3060number information for the subroutine. Otherwise it acts like the
3061@code{next} command. This avoids problems when using @code{cc -gl}
3062on MIPS machines. Previously, @code{step} entered subroutines if there
3063was any debugging information about the routine.
3064
3065@item step @var{count}
3066Continue running as in @code{step}, but do so @var{count} times. If a
7a292a7a
SS
3067breakpoint is reached, or a signal not related to stepping occurs before
3068@var{count} steps, stepping stops right away.
c906108c
SS
3069
3070@kindex next
3071@kindex n
3072@item next @r{[}@var{count}@r{]}
3073Continue to the next source line in the current (innermost) stack frame.
7a292a7a
SS
3074This is similar to @code{step}, but function calls that appear within
3075the line of code are executed without stopping. Execution stops when
3076control reaches a different line of code at the original stack level
3077that was executing when you gave the @code{next} command. This command
3078is abbreviated @code{n}.
c906108c
SS
3079
3080An argument @var{count} is a repeat count, as for @code{step}.
3081
3082
3083@c FIX ME!! Do we delete this, or is there a way it fits in with
3084@c the following paragraph? --- Vctoria
3085@c
3086@c @code{next} within a function that lacks debugging information acts like
3087@c @code{step}, but any function calls appearing within the code of the
3088@c function are executed without stopping.
3089
3090The @code{next} command now only stops at the first instruction of a
3091source line. This prevents the multiple stops that used to occur in
3092switch statements, for loops, etc.
3093
3094@kindex finish
3095@item finish
3096Continue running until just after function in the selected stack frame
3097returns. Print the returned value (if any).
3098
3099Contrast this with the @code{return} command (@pxref{Returning,
3100,Returning from a function}).
3101
3102@kindex until
3103@kindex u
3104@item until
3105@itemx u
3106Continue running until a source line past the current line, in the
3107current stack frame, is reached. This command is used to avoid single
3108stepping through a loop more than once. It is like the @code{next}
3109command, except that when @code{until} encounters a jump, it
3110automatically continues execution until the program counter is greater
3111than the address of the jump.
3112
3113This means that when you reach the end of a loop after single stepping
3114though it, @code{until} makes your program continue execution until it
3115exits the loop. In contrast, a @code{next} command at the end of a loop
3116simply steps back to the beginning of the loop, which forces you to step
3117through the next iteration.
3118
3119@code{until} always stops your program if it attempts to exit the current
3120stack frame.
3121
3122@code{until} may produce somewhat counterintuitive results if the order
3123of machine code does not match the order of the source lines. For
3124example, in the following excerpt from a debugging session, the @code{f}
3125(@code{frame}) command shows that execution is stopped at line
3126@code{206}; yet when we use @code{until}, we get to line @code{195}:
3127
3128@example
3129(@value{GDBP}) f
3130#0 main (argc=4, argv=0xf7fffae8) at m4.c:206
3131206 expand_input();
3132(@value{GDBP}) until
3133195 for ( ; argc > 0; NEXTARG) @{
3134@end example
3135
3136This happened because, for execution efficiency, the compiler had
3137generated code for the loop closure test at the end, rather than the
3138start, of the loop---even though the test in a C @code{for}-loop is
3139written before the body of the loop. The @code{until} command appeared
3140to step back to the beginning of the loop when it advanced to this
3141expression; however, it has not really gone to an earlier
3142statement---not in terms of the actual machine code.
3143
3144@code{until} with no argument works by means of single
3145instruction stepping, and hence is slower than @code{until} with an
3146argument.
3147
3148@item until @var{location}
3149@itemx u @var{location}
3150Continue running your program until either the specified location is
3151reached, or the current stack frame returns. @var{location} is any of
3152the forms of argument acceptable to @code{break} (@pxref{Set Breaks,
3153,Setting breakpoints}). This form of the command uses breakpoints,
3154and hence is quicker than @code{until} without an argument.
3155
3156@kindex stepi
3157@kindex si
3158@item stepi
3159@itemx si
3160Execute one machine instruction, then stop and return to the debugger.
3161
3162It is often useful to do @samp{display/i $pc} when stepping by machine
3163instructions. This makes @value{GDBN} automatically display the next
3164instruction to be executed, each time your program stops. @xref{Auto
3165Display,, Automatic display}.
3166
3167An argument is a repeat count, as in @code{step}.
3168
3169@need 750
3170@kindex nexti
3171@kindex ni
3172@item nexti
3173@itemx ni
3174Execute one machine instruction, but if it is a function call,
3175proceed until the function returns.
3176
3177An argument is a repeat count, as in @code{next}.
3178@end table
3179
53a5351d 3180@node Signals
c906108c
SS
3181@section Signals
3182@cindex signals
3183
3184A signal is an asynchronous event that can happen in a program. The
3185operating system defines the possible kinds of signals, and gives each
3186kind a name and a number. For example, in Unix @code{SIGINT} is the
3187signal a program gets when you type an interrupt (often @kbd{C-c});
3188@code{SIGSEGV} is the signal a program gets from referencing a place in
3189memory far away from all the areas in use; @code{SIGALRM} occurs when
3190the alarm clock timer goes off (which happens only if your program has
3191requested an alarm).
3192
3193@cindex fatal signals
3194Some signals, including @code{SIGALRM}, are a normal part of the
3195functioning of your program. Others, such as @code{SIGSEGV}, indicate
3196errors; these signals are @dfn{fatal} (kill your program immediately) if the
3197program has not specified in advance some other way to handle the signal.
3198@code{SIGINT} does not indicate an error in your program, but it is normally
3199fatal so it can carry out the purpose of the interrupt: to kill the program.
3200
3201@value{GDBN} has the ability to detect any occurrence of a signal in your
3202program. You can tell @value{GDBN} in advance what to do for each kind of
3203signal.
3204
3205@cindex handling signals
3206Normally, @value{GDBN} is set up to ignore non-erroneous signals like @code{SIGALRM}
3207(so as not to interfere with their role in the functioning of your program)
3208but to stop your program immediately whenever an error signal happens.
3209You can change these settings with the @code{handle} command.
3210
3211@table @code
3212@kindex info signals
3213@item info signals
3214Print a table of all the kinds of signals and how @value{GDBN} has been told to
3215handle each one. You can use this to see the signal numbers of all
3216the defined types of signals.
3217
3218@code{info handle} is the new alias for @code{info signals}.
3219
3220@kindex handle
3221@item handle @var{signal} @var{keywords}@dots{}
3222Change the way @value{GDBN} handles signal @var{signal}. @var{signal} can
3223be the number of a signal or its name (with or without the @samp{SIG} at the
3224beginning). The @var{keywords} say what change to make.
3225@end table
3226
3227@c @group
3228The keywords allowed by the @code{handle} command can be abbreviated.
3229Their full names are:
3230
3231@table @code
3232@item nostop
3233@value{GDBN} should not stop your program when this signal happens. It may
3234still print a message telling you that the signal has come in.
3235
3236@item stop
3237@value{GDBN} should stop your program when this signal happens. This implies
3238the @code{print} keyword as well.
3239
3240@item print
3241@value{GDBN} should print a message when this signal happens.
3242
3243@item noprint
3244@value{GDBN} should not mention the occurrence of the signal at all. This
3245implies the @code{nostop} keyword as well.
3246
3247@item pass
3248@value{GDBN} should allow your program to see this signal; your program
3249can handle the signal, or else it may terminate if the signal is fatal
3250and not handled.
3251
3252@item nopass
3253@value{GDBN} should not allow your program to see this signal.
3254@end table
3255@c @end group
3256
3257When a signal stops your program, the signal is not visible until you
3258continue. Your program sees the signal then, if @code{pass} is in
3259effect for the signal in question @emph{at that time}. In other words,
3260after @value{GDBN} reports a signal, you can use the @code{handle}
3261command with @code{pass} or @code{nopass} to control whether your
3262program sees that signal when you continue.
3263
3264You can also use the @code{signal} command to prevent your program from
3265seeing a signal, or cause it to see a signal it normally would not see,
3266or to give it any signal at any time. For example, if your program stopped
3267due to some sort of memory reference error, you might store correct
3268values into the erroneous variables and continue, hoping to see more
3269execution; but your program would probably terminate immediately as
3270a result of the fatal signal once it saw the signal. To prevent this,
3271you can continue with @samp{signal 0}. @xref{Signaling, ,Giving your
3272program a signal}.
c906108c 3273
53a5351d 3274@node Thread Stops
c906108c
SS
3275@section Stopping and starting multi-thread programs
3276
3277When your program has multiple threads (@pxref{Threads,, Debugging
3278programs with multiple threads}), you can choose whether to set
3279breakpoints on all threads, or on a particular thread.
3280
3281@table @code
3282@cindex breakpoints and threads
3283@cindex thread breakpoints
3284@kindex break @dots{} thread @var{threadno}
3285@item break @var{linespec} thread @var{threadno}
3286@itemx break @var{linespec} thread @var{threadno} if @dots{}
3287@var{linespec} specifies source lines; there are several ways of
3288writing them, but the effect is always to specify some source line.
3289
3290Use the qualifier @samp{thread @var{threadno}} with a breakpoint command
3291to specify that you only want @value{GDBN} to stop the program when a
3292particular thread reaches this breakpoint. @var{threadno} is one of the
3293numeric thread identifiers assigned by @value{GDBN}, shown in the first
3294column of the @samp{info threads} display.
3295
3296If you do not specify @samp{thread @var{threadno}} when you set a
3297breakpoint, the breakpoint applies to @emph{all} threads of your
3298program.
3299
3300You can use the @code{thread} qualifier on conditional breakpoints as
3301well; in this case, place @samp{thread @var{threadno}} before the
3302breakpoint condition, like this:
3303
3304@smallexample
3305(gdb) break frik.c:13 thread 28 if bartab > lim
3306@end smallexample
3307
3308@end table
3309
3310@cindex stopped threads
3311@cindex threads, stopped
3312Whenever your program stops under @value{GDBN} for any reason,
3313@emph{all} threads of execution stop, not just the current thread. This
3314allows you to examine the overall state of the program, including
3315switching between threads, without worrying that things may change
3316underfoot.
3317
3318@cindex continuing threads
3319@cindex threads, continuing
3320Conversely, whenever you restart the program, @emph{all} threads start
3321executing. @emph{This is true even when single-stepping} with commands
3322like @code{step} or @code{next}.
3323
3324In particular, @value{GDBN} cannot single-step all threads in lockstep.
3325Since thread scheduling is up to your debugging target's operating
3326system (not controlled by @value{GDBN}), other threads may
3327execute more than one statement while the current thread completes a
3328single step. Moreover, in general other threads stop in the middle of a
3329statement, rather than at a clean statement boundary, when the program
3330stops.
3331
3332You might even find your program stopped in another thread after
3333continuing or even single-stepping. This happens whenever some other
3334thread runs into a breakpoint, a signal, or an exception before the
3335first thread completes whatever you requested.
3336
3337On some OSes, you can lock the OS scheduler and thus allow only a single
3338thread to run.
3339
3340@table @code
3341@item set scheduler-locking @var{mode}
3342Set the scheduler locking mode. If it is @code{off}, then there is no
3343locking and any thread may run at any time. If @code{on}, then only the
3344current thread may run when the inferior is resumed. The @code{step}
3345mode optimizes for single-stepping. It stops other threads from
3346``seizing the prompt'' by preempting the current thread while you are
3347stepping. Other threads will only rarely (or never) get a chance to run
3348when you step. They are more likely to run when you ``next'' over a
3349function call, and they are completely free to run when you use commands
3350like ``continue'', ``until'', or ``finish''. However, unless another
3351thread hits a breakpoint during its timeslice, they will never steal the
3352GDB prompt away from the thread that you are debugging.
3353
3354@item show scheduler-locking
3355Display the current scheduler locking mode.
3356@end table
3357
c906108c 3358
53a5351d 3359@node Stack
c906108c
SS
3360@chapter Examining the Stack
3361
3362When your program has stopped, the first thing you need to know is where it
3363stopped and how it got there.
3364
3365@cindex call stack
3366Each time your program performs a function call, information about the call
3367is generated.
3368That information includes the location of the call in your program,
3369the arguments of the call,
3370and the local variables of the function being called.
3371The information is saved in a block of data called a @dfn{stack frame}.
3372The stack frames are allocated in a region of memory called the @dfn{call
3373stack}.
3374
3375When your program stops, the @value{GDBN} commands for examining the
3376stack allow you to see all of this information.
3377
3378@cindex selected frame
3379One of the stack frames is @dfn{selected} by @value{GDBN} and many
3380@value{GDBN} commands refer implicitly to the selected frame. In
3381particular, whenever you ask @value{GDBN} for the value of a variable in
3382your program, the value is found in the selected frame. There are
3383special @value{GDBN} commands to select whichever frame you are
3384interested in. @xref{Selection, ,Selecting a frame}.
3385
3386When your program stops, @value{GDBN} automatically selects the
3387currently executing frame and describes it briefly, similar to the
3388@code{frame} command (@pxref{Frame Info, ,Information about a frame}).
3389
3390@menu
3391* Frames:: Stack frames
3392* Backtrace:: Backtraces
3393* Selection:: Selecting a frame
3394* Frame Info:: Information on a frame
3395* Alpha/MIPS Stack:: Alpha and MIPS machines and the function stack
3396
3397@end menu
3398
53a5351d 3399@node Frames
c906108c
SS
3400@section Stack frames
3401
3402@cindex frame
3403@cindex stack frame
3404The call stack is divided up into contiguous pieces called @dfn{stack
3405frames}, or @dfn{frames} for short; each frame is the data associated
3406with one call to one function. The frame contains the arguments given
3407to the function, the function's local variables, and the address at
3408which the function is executing.
3409
3410@cindex initial frame
3411@cindex outermost frame
3412@cindex innermost frame
3413When your program is started, the stack has only one frame, that of the
3414function @code{main}. This is called the @dfn{initial} frame or the
3415@dfn{outermost} frame. Each time a function is called, a new frame is
3416made. Each time a function returns, the frame for that function invocation
3417is eliminated. If a function is recursive, there can be many frames for
3418the same function. The frame for the function in which execution is
3419actually occurring is called the @dfn{innermost} frame. This is the most
3420recently created of all the stack frames that still exist.
3421
3422@cindex frame pointer
3423Inside your program, stack frames are identified by their addresses. A
3424stack frame consists of many bytes, each of which has its own address; each
3425kind of computer has a convention for choosing one byte whose
3426address serves as the address of the frame. Usually this address is kept
3427in a register called the @dfn{frame pointer register} while execution is
3428going on in that frame.
3429
3430@cindex frame number
3431@value{GDBN} assigns numbers to all existing stack frames, starting with
3432zero for the innermost frame, one for the frame that called it,
3433and so on upward. These numbers do not really exist in your program;
3434they are assigned by @value{GDBN} to give you a way of designating stack
3435frames in @value{GDBN} commands.
3436
3437@c below produces an acceptable overful hbox. --mew 13aug1993
3438@cindex frameless execution
3439Some compilers provide a way to compile functions so that they operate
3440without stack frames. (For example, the @code{@value{GCC}} option
3441@samp{-fomit-frame-pointer} generates functions without a frame.)
3442This is occasionally done with heavily used library functions to save
3443the frame setup time. @value{GDBN} has limited facilities for dealing
3444with these function invocations. If the innermost function invocation
3445has no stack frame, @value{GDBN} nevertheless regards it as though
3446it had a separate frame, which is numbered zero as usual, allowing
3447correct tracing of the function call chain. However, @value{GDBN} has
3448no provision for frameless functions elsewhere in the stack.
3449
3450@table @code
3451@kindex frame
3452@item frame @var{args}
3453The @code{frame} command allows you to move from one stack frame to another,
3454and to print the stack frame you select. @var{args} may be either the
3455address of the frame or the stack frame number. Without an argument,
3456@code{frame} prints the current stack frame.
3457
3458@kindex select-frame
3459@item select-frame
3460The @code{select-frame} command allows you to move from one stack frame
3461to another without printing the frame. This is the silent version of
3462@code{frame}.
3463@end table
3464
53a5351d 3465@node Backtrace
c906108c
SS
3466@section Backtraces
3467
3468@cindex backtraces
3469@cindex tracebacks
3470@cindex stack traces
3471A backtrace is a summary of how your program got where it is. It shows one
3472line per frame, for many frames, starting with the currently executing
3473frame (frame zero), followed by its caller (frame one), and on up the
3474stack.
3475
3476@table @code
3477@kindex backtrace
3478@kindex bt
3479@item backtrace
3480@itemx bt
3481Print a backtrace of the entire stack: one line per frame for all
3482frames in the stack.
3483
3484You can stop the backtrace at any time by typing the system interrupt
3485character, normally @kbd{C-c}.
3486
3487@item backtrace @var{n}
3488@itemx bt @var{n}
3489Similar, but print only the innermost @var{n} frames.
3490
3491@item backtrace -@var{n}
3492@itemx bt -@var{n}
3493Similar, but print only the outermost @var{n} frames.
3494@end table
3495
3496@kindex where
3497@kindex info stack
3498@kindex info s
3499The names @code{where} and @code{info stack} (abbreviated @code{info s})
3500are additional aliases for @code{backtrace}.
3501
3502Each line in the backtrace shows the frame number and the function name.
3503The program counter value is also shown---unless you use @code{set
3504print address off}. The backtrace also shows the source file name and
3505line number, as well as the arguments to the function. The program
3506counter value is omitted if it is at the beginning of the code for that
3507line number.
3508
3509Here is an example of a backtrace. It was made with the command
3510@samp{bt 3}, so it shows the innermost three frames.
3511
3512@smallexample
3513@group
3514#0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8)
3515 at builtin.c:993
3516#1 0x6e38 in expand_macro (sym=0x2b600) at macro.c:242
3517#2 0x6840 in expand_token (obs=0x0, t=177664, td=0xf7fffb08)
3518 at macro.c:71
3519(More stack frames follow...)
3520@end group
3521@end smallexample
3522
3523@noindent
3524The display for frame zero does not begin with a program counter
3525value, indicating that your program has stopped at the beginning of the
3526code for line @code{993} of @code{builtin.c}.
3527
53a5351d 3528@node Selection
c906108c
SS
3529@section Selecting a frame
3530
3531Most commands for examining the stack and other data in your program work on
3532whichever stack frame is selected at the moment. Here are the commands for
3533selecting a stack frame; all of them finish by printing a brief description
3534of the stack frame just selected.
3535
3536@table @code
3537@kindex frame
3538@kindex f
3539@item frame @var{n}
3540@itemx f @var{n}
3541Select frame number @var{n}. Recall that frame zero is the innermost
3542(currently executing) frame, frame one is the frame that called the
3543innermost one, and so on. The highest-numbered frame is the one for
3544@code{main}.
3545
3546@item frame @var{addr}
3547@itemx f @var{addr}
3548Select the frame at address @var{addr}. This is useful mainly if the
3549chaining of stack frames has been damaged by a bug, making it
3550impossible for @value{GDBN} to assign numbers properly to all frames. In
3551addition, this can be useful when your program has multiple stacks and
3552switches between them.
3553
c906108c
SS
3554On the SPARC architecture, @code{frame} needs two addresses to
3555select an arbitrary frame: a frame pointer and a stack pointer.
3556
3557On the MIPS and Alpha architecture, it needs two addresses: a stack
3558pointer and a program counter.
3559
3560On the 29k architecture, it needs three addresses: a register stack
3561pointer, a program counter, and a memory stack pointer.
3562@c note to future updaters: this is conditioned on a flag
3563@c SETUP_ARBITRARY_FRAME in the tm-*.h files. The above is up to date
3564@c as of 27 Jan 1994.
c906108c
SS
3565
3566@kindex up
3567@item up @var{n}
3568Move @var{n} frames up the stack. For positive numbers @var{n}, this
3569advances toward the outermost frame, to higher frame numbers, to frames
3570that have existed longer. @var{n} defaults to one.
3571
3572@kindex down
3573@kindex do
3574@item down @var{n}
3575Move @var{n} frames down the stack. For positive numbers @var{n}, this
3576advances toward the innermost frame, to lower frame numbers, to frames
3577that were created more recently. @var{n} defaults to one. You may
3578abbreviate @code{down} as @code{do}.
3579@end table
3580
3581All of these commands end by printing two lines of output describing the
3582frame. The first line shows the frame number, the function name, the
3583arguments, and the source file and line number of execution in that
3584frame. The second line shows the text of that source line.
3585
3586@need 1000
3587For example:
3588
3589@smallexample
3590@group
3591(@value{GDBP}) up
3592#1 0x22f0 in main (argc=1, argv=0xf7fffbf4, env=0xf7fffbfc)
3593 at env.c:10
359410 read_input_file (argv[i]);
3595@end group
3596@end smallexample
3597
3598After such a printout, the @code{list} command with no arguments
3599prints ten lines centered on the point of execution in the frame.
3600@xref{List, ,Printing source lines}.
3601
3602@table @code
3603@kindex down-silently
3604@kindex up-silently
3605@item up-silently @var{n}
3606@itemx down-silently @var{n}
3607These two commands are variants of @code{up} and @code{down},
3608respectively; they differ in that they do their work silently, without
3609causing display of the new frame. They are intended primarily for use
3610in @value{GDBN} command scripts, where the output might be unnecessary and
3611distracting.
3612@end table
3613
53a5351d 3614@node Frame Info
c906108c
SS
3615@section Information about a frame
3616
3617There are several other commands to print information about the selected
3618stack frame.
3619
3620@table @code
3621@item frame
3622@itemx f
3623When used without any argument, this command does not change which
3624frame is selected, but prints a brief description of the currently
3625selected stack frame. It can be abbreviated @code{f}. With an
3626argument, this command is used to select a stack frame.
3627@xref{Selection, ,Selecting a frame}.
3628
3629@kindex info frame
3630@kindex info f
3631@item info frame
3632@itemx info f
3633This command prints a verbose description of the selected stack frame,
3634including:
3635
3636@itemize @bullet
3637@item
3638the address of the frame
3639@item
3640the address of the next frame down (called by this frame)
3641@item
3642the address of the next frame up (caller of this frame)
3643@item
3644the language in which the source code corresponding to this frame is written
3645@item
3646the address of the frame's arguments
3647@item
3648the program counter saved in it (the address of execution in the caller frame)
3649@item
3650which registers were saved in the frame
3651@end itemize
3652
3653@noindent The verbose description is useful when
3654something has gone wrong that has made the stack format fail to fit
3655the usual conventions.
3656
3657@item info frame @var{addr}
3658@itemx info f @var{addr}
3659Print a verbose description of the frame at address @var{addr}, without
3660selecting that frame. The selected frame remains unchanged by this
3661command. This requires the same kind of address (more than one for some
3662architectures) that you specify in the @code{frame} command.
3663@xref{Selection, ,Selecting a frame}.
3664
3665@kindex info args
3666@item info args
3667Print the arguments of the selected frame, each on a separate line.
3668
3669@item info locals
3670@kindex info locals
3671Print the local variables of the selected frame, each on a separate
3672line. These are all variables (declared either static or automatic)
3673accessible at the point of execution of the selected frame.
3674
c906108c
SS
3675@kindex info catch
3676@cindex catch exceptions
3677@cindex exception handlers
3678@item info catch
3679Print a list of all the exception handlers that are active in the
3680current stack frame at the current point of execution. To see other
3681exception handlers, visit the associated frame (using the @code{up},
3682@code{down}, or @code{frame} commands); then type @code{info catch}.
3683@xref{Set Catchpoints, , Setting catchpoints}.
53a5351d 3684
c906108c
SS
3685@end table
3686
53a5351d 3687@node Alpha/MIPS Stack
c906108c
SS
3688@section MIPS/Alpha machines and the function stack
3689
3690@cindex stack on Alpha
3691@cindex stack on MIPS
3692@cindex Alpha stack
3693@cindex MIPS stack
3694Alpha- and MIPS-based computers use an unusual stack frame, which
3695sometimes requires @value{GDBN} to search backward in the object code to
3696find the beginning of a function.
3697
3698@cindex response time, MIPS debugging
3699To improve response time (especially for embedded applications, where
3700@value{GDBN} may be restricted to a slow serial line for this search)
3701you may want to limit the size of this search, using one of these
3702commands:
3703
3704@table @code
3705@cindex @code{heuristic-fence-post} (Alpha,MIPS)
3706@item set heuristic-fence-post @var{limit}
3707Restrict @value{GDBN} to examining at most @var{limit} bytes in its search
3708for the beginning of a function. A value of @var{0} (the default)
3709means there is no limit. However, except for @var{0}, the larger the
3710limit the more bytes @code{heuristic-fence-post} must search and
3711therefore the longer it takes to run.
3712
3713@item show heuristic-fence-post
3714Display the current limit.
3715@end table
3716
3717@noindent
3718These commands are available @emph{only} when @value{GDBN} is configured
3719for debugging programs on Alpha or MIPS processors.
3720
3721
53a5351d 3722@node Source
c906108c
SS
3723@chapter Examining Source Files
3724
3725@value{GDBN} can print parts of your program's source, since the debugging
3726information recorded in the program tells @value{GDBN} what source files were
3727used to build it. When your program stops, @value{GDBN} spontaneously prints
3728the line where it stopped. Likewise, when you select a stack frame
3729(@pxref{Selection, ,Selecting a frame}), @value{GDBN} prints the line where
3730execution in that frame has stopped. You can print other portions of
3731source files by explicit command.
3732
7a292a7a
SS
3733If you use @value{GDBN} through its @sc{gnu} Emacs interface, you may
3734prefer to use Emacs facilities to view source; @pxref{Emacs, ,Using
3735@value{GDBN} under @sc{gnu} Emacs}.
c906108c
SS
3736
3737@menu
3738* List:: Printing source lines
c906108c 3739* Search:: Searching source files
c906108c
SS
3740* Source Path:: Specifying source directories
3741* Machine Code:: Source and machine code
3742@end menu
3743
53a5351d 3744@node List
c906108c
SS
3745@section Printing source lines
3746
3747@kindex list
3748@kindex l
3749To print lines from a source file, use the @code{list} command
3750(abbreviated @code{l}). By default, ten lines are printed.
3751There are several ways to specify what part of the file you want to print.
3752
3753Here are the forms of the @code{list} command most commonly used:
3754
3755@table @code
3756@item list @var{linenum}
3757Print lines centered around line number @var{linenum} in the
3758current source file.
3759
3760@item list @var{function}
3761Print lines centered around the beginning of function
3762@var{function}.
3763
3764@item list
3765Print more lines. If the last lines printed were printed with a
3766@code{list} command, this prints lines following the last lines
3767printed; however, if the last line printed was a solitary line printed
3768as part of displaying a stack frame (@pxref{Stack, ,Examining the
3769Stack}), this prints lines centered around that line.
3770
3771@item list -
3772Print lines just before the lines last printed.
3773@end table
3774
3775By default, @value{GDBN} prints ten source lines with any of these forms of
3776the @code{list} command. You can change this using @code{set listsize}:
3777
3778@table @code
3779@kindex set listsize
3780@item set listsize @var{count}
3781Make the @code{list} command display @var{count} source lines (unless
3782the @code{list} argument explicitly specifies some other number).
3783
3784@kindex show listsize
3785@item show listsize
3786Display the number of lines that @code{list} prints.
3787@end table
3788
3789Repeating a @code{list} command with @key{RET} discards the argument,
3790so it is equivalent to typing just @code{list}. This is more useful
3791than listing the same lines again. An exception is made for an
3792argument of @samp{-}; that argument is preserved in repetition so that
3793each repetition moves up in the source file.
3794
3795@cindex linespec
3796In general, the @code{list} command expects you to supply zero, one or two
3797@dfn{linespecs}. Linespecs specify source lines; there are several ways
3798of writing them but the effect is always to specify some source line.
3799Here is a complete description of the possible arguments for @code{list}:
3800
3801@table @code
3802@item list @var{linespec}
3803Print lines centered around the line specified by @var{linespec}.
3804
3805@item list @var{first},@var{last}
3806Print lines from @var{first} to @var{last}. Both arguments are
3807linespecs.
3808
3809@item list ,@var{last}
3810Print lines ending with @var{last}.
3811
3812@item list @var{first},
3813Print lines starting with @var{first}.
3814
3815@item list +
3816Print lines just after the lines last printed.
3817
3818@item list -
3819Print lines just before the lines last printed.
3820
3821@item list
3822As described in the preceding table.
3823@end table
3824
3825Here are the ways of specifying a single source line---all the
3826kinds of linespec.
3827
3828@table @code
3829@item @var{number}
3830Specifies line @var{number} of the current source file.
3831When a @code{list} command has two linespecs, this refers to
3832the same source file as the first linespec.
3833
3834@item +@var{offset}
3835Specifies the line @var{offset} lines after the last line printed.
3836When used as the second linespec in a @code{list} command that has
3837two, this specifies the line @var{offset} lines down from the
3838first linespec.
3839
3840@item -@var{offset}
3841Specifies the line @var{offset} lines before the last line printed.
3842
3843@item @var{filename}:@var{number}
3844Specifies line @var{number} in the source file @var{filename}.
3845
3846@item @var{function}
3847Specifies the line that begins the body of the function @var{function}.
3848For example: in C, this is the line with the open brace.
3849
3850@item @var{filename}:@var{function}
3851Specifies the line of the open-brace that begins the body of the
3852function @var{function} in the file @var{filename}. You only need the
3853file name with a function name to avoid ambiguity when there are
3854identically named functions in different source files.
3855
3856@item *@var{address}
3857Specifies the line containing the program address @var{address}.
3858@var{address} may be any expression.
3859@end table
3860
53a5351d 3861@node Search
c906108c
SS
3862@section Searching source files
3863@cindex searching
3864@kindex reverse-search
3865
3866There are two commands for searching through the current source file for a
3867regular expression.
3868
3869@table @code
3870@kindex search
3871@kindex forward-search
3872@item forward-search @var{regexp}
3873@itemx search @var{regexp}
3874The command @samp{forward-search @var{regexp}} checks each line,
3875starting with the one following the last line listed, for a match for
3876@var{regexp}. It lists the line that is found. You can use the
3877synonym @samp{search @var{regexp}} or abbreviate the command name as
3878@code{fo}.
3879
3880@item reverse-search @var{regexp}
3881The command @samp{reverse-search @var{regexp}} checks each line, starting
3882with the one before the last line listed and going backward, for a match
3883for @var{regexp}. It lists the line that is found. You can abbreviate
3884this command as @code{rev}.
3885@end table
c906108c 3886
53a5351d 3887@node Source Path
c906108c
SS
3888@section Specifying source directories
3889
3890@cindex source path
3891@cindex directories for source files
3892Executable programs sometimes do not record the directories of the source
3893files from which they were compiled, just the names. Even when they do,
3894the directories could be moved between the compilation and your debugging
3895session. @value{GDBN} has a list of directories to search for source files;
3896this is called the @dfn{source path}. Each time @value{GDBN} wants a source file,
3897it tries all the directories in the list, in the order they are present
3898in the list, until it finds a file with the desired name. Note that
3899the executable search path is @emph{not} used for this purpose. Neither is
3900the current working directory, unless it happens to be in the source
3901path.
3902
3903If @value{GDBN} cannot find a source file in the source path, and the
3904object program records a directory, @value{GDBN} tries that directory
3905too. If the source path is empty, and there is no record of the
3906compilation directory, @value{GDBN} looks in the current directory as a
3907last resort.
3908
3909Whenever you reset or rearrange the source path, @value{GDBN} clears out
3910any information it has cached about where source files are found and where
3911each line is in the file.
3912
3913@kindex directory
3914@kindex dir
3915When you start @value{GDBN}, its source path is empty.
3916To add other directories, use the @code{directory} command.
3917
3918@table @code
3919@item directory @var{dirname} @dots{}
3920@item dir @var{dirname} @dots{}
3921Add directory @var{dirname} to the front of the source path. Several
3922directory names may be given to this command, separated by @samp{:} or
3923whitespace. You may specify a directory that is already in the source
3924path; this moves it forward, so @value{GDBN} searches it sooner.
3925
3926@kindex cdir
3927@kindex cwd
3928@kindex $cdir
3929@kindex $cwd
3930@cindex compilation directory
3931@cindex current directory
3932@cindex working directory
3933@cindex directory, current
3934@cindex directory, compilation
3935You can use the string @samp{$cdir} to refer to the compilation
3936directory (if one is recorded), and @samp{$cwd} to refer to the current
3937working directory. @samp{$cwd} is not the same as @samp{.}---the former
3938tracks the current working directory as it changes during your @value{GDBN}
3939session, while the latter is immediately expanded to the current
3940directory at the time you add an entry to the source path.
3941
3942@item directory
3943Reset the source path to empty again. This requires confirmation.
3944
3945@c RET-repeat for @code{directory} is explicitly disabled, but since
3946@c repeating it would be a no-op we do not say that. (thanks to RMS)
3947
3948@item show directories
3949@kindex show directories
3950Print the source path: show which directories it contains.
3951@end table
3952
3953If your source path is cluttered with directories that are no longer of
3954interest, @value{GDBN} may sometimes cause confusion by finding the wrong
3955versions of source. You can correct the situation as follows:
3956
3957@enumerate
3958@item
3959Use @code{directory} with no argument to reset the source path to empty.
3960
3961@item
3962Use @code{directory} with suitable arguments to reinstall the
3963directories you want in the source path. You can add all the
3964directories in one command.
3965@end enumerate
3966
53a5351d 3967@node Machine Code
c906108c
SS
3968@section Source and machine code
3969
3970You can use the command @code{info line} to map source lines to program
3971addresses (and vice versa), and the command @code{disassemble} to display
3972a range of addresses as machine instructions. When run under @sc{gnu} Emacs
3973mode, the @code{info line} command now causes the arrow to point to the
3974line specified. Also, @code{info line} prints addresses in symbolic form as
3975well as hex.
3976
3977@table @code
3978@kindex info line
3979@item info line @var{linespec}
3980Print the starting and ending addresses of the compiled code for
3981source line @var{linespec}. You can specify source lines in any of
3982the ways understood by the @code{list} command (@pxref{List, ,Printing
3983source lines}).
3984@end table
3985
3986For example, we can use @code{info line} to discover the location of
3987the object code for the first line of function
3988@code{m4_changequote}:
3989
3990@smallexample
3991(@value{GDBP}) info line m4_changecom
3992Line 895 of "builtin.c" starts at pc 0x634c and ends at 0x6350.
3993@end smallexample
3994
3995@noindent
3996We can also inquire (using @code{*@var{addr}} as the form for
3997@var{linespec}) what source line covers a particular address:
3998@smallexample
3999(@value{GDBP}) info line *0x63ff
4000Line 926 of "builtin.c" starts at pc 0x63e4 and ends at 0x6404.
4001@end smallexample
4002
4003@cindex @code{$_} and @code{info line}
4004After @code{info line}, the default address for the @code{x} command
4005is changed to the starting address of the line, so that @samp{x/i} is
4006sufficient to begin examining the machine code (@pxref{Memory,
4007,Examining memory}). Also, this address is saved as the value of the
4008convenience variable @code{$_} (@pxref{Convenience Vars, ,Convenience
4009variables}).
4010
4011@table @code
4012@kindex disassemble
4013@cindex assembly instructions
4014@cindex instructions, assembly
4015@cindex machine instructions
4016@cindex listing machine instructions
4017@item disassemble
4018This specialized command dumps a range of memory as machine
4019instructions. The default memory range is the function surrounding the
4020program counter of the selected frame. A single argument to this
4021command is a program counter value; @value{GDBN} dumps the function
4022surrounding this value. Two arguments specify a range of addresses
4023(first inclusive, second exclusive) to dump.
4024@end table
4025
c906108c
SS
4026The following example shows the disassembly of a range of addresses of
4027HP PA-RISC 2.0 code:
4028
4029@smallexample
4030(@value{GDBP}) disas 0x32c4 0x32e4
4031Dump of assembler code from 0x32c4 to 0x32e4:
40320x32c4 <main+204>: addil 0,dp
40330x32c8 <main+208>: ldw 0x22c(sr0,r1),r26
40340x32cc <main+212>: ldil 0x3000,r31
40350x32d0 <main+216>: ble 0x3f8(sr4,r31)
40360x32d4 <main+220>: ldo 0(r31),rp
40370x32d8 <main+224>: addil -0x800,dp
40380x32dc <main+228>: ldo 0x588(r1),r26
40390x32e0 <main+232>: ldil 0x3000,r31
4040End of assembler dump.
4041@end smallexample
c906108c
SS
4042
4043Some architectures have more than one commonly-used set of instruction
4044mnemonics or other syntax.
4045
4046@table @code
4047@kindex set assembly-language
4048@cindex assembly instructions
4049@cindex instructions, assembly
4050@cindex machine instructions
4051@cindex listing machine instructions
4052@item set assembly-language @var{instruction-set}
4053Select the instruction set to use when disassembling the
4054program via the @code{disassemble} or @code{x/i} commands.
4055
4056Currently this command is only defined for the Intel x86 family. You
4057can set @var{instruction-set} to either @code{i386} or @code{i8086}.
4058The default is @code{i386}.
4059@end table
4060
4061
53a5351d 4062@node Data
c906108c
SS
4063@chapter Examining Data
4064
4065@cindex printing data
4066@cindex examining data
4067@kindex print
4068@kindex inspect
4069@c "inspect" is not quite a synonym if you are using Epoch, which we do not
4070@c document because it is nonstandard... Under Epoch it displays in a
4071@c different window or something like that.
4072The usual way to examine data in your program is with the @code{print}
7a292a7a
SS
4073command (abbreviated @code{p}), or its synonym @code{inspect}. It
4074evaluates and prints the value of an expression of the language your
4075program is written in (@pxref{Languages, ,Using @value{GDBN} with
4076Different Languages}).
c906108c
SS
4077
4078@table @code
4079@item print @var{exp}
4080@itemx print /@var{f} @var{exp}
4081@var{exp} is an expression (in the source language). By default the
4082value of @var{exp} is printed in a format appropriate to its data type;
4083you can choose a different format by specifying @samp{/@var{f}}, where
4084@var{f} is a letter specifying the format; @pxref{Output Formats,,Output
4085formats}.
4086
4087@item print
4088@itemx print /@var{f}
4089If you omit @var{exp}, @value{GDBN} displays the last value again (from the
4090@dfn{value history}; @pxref{Value History, ,Value history}). This allows you to
4091conveniently inspect the same value in an alternative format.
4092@end table
4093
4094A more low-level way of examining data is with the @code{x} command.
4095It examines data in memory at a specified address and prints it in a
4096specified format. @xref{Memory, ,Examining memory}.
4097
7a292a7a
SS
4098If you are interested in information about types, or about how the
4099fields of a struct or class are declared, use the @code{ptype @var{exp}}
4100command rather than @code{print}. @xref{Symbols, ,Examining the Symbol
4101Table}.
c906108c
SS
4102
4103@menu
4104* Expressions:: Expressions
4105* Variables:: Program variables
4106* Arrays:: Artificial arrays
4107* Output Formats:: Output formats
4108* Memory:: Examining memory
4109* Auto Display:: Automatic display
4110* Print Settings:: Print settings
4111* Value History:: Value history
4112* Convenience Vars:: Convenience variables
4113* Registers:: Registers
c906108c 4114* Floating Point Hardware:: Floating point hardware
c906108c
SS
4115@end menu
4116
53a5351d 4117@node Expressions
c906108c
SS
4118@section Expressions
4119
4120@cindex expressions
4121@code{print} and many other @value{GDBN} commands accept an expression and
4122compute its value. Any kind of constant, variable or operator defined
4123by the programming language you are using is valid in an expression in
4124@value{GDBN}. This includes conditional expressions, function calls, casts
4125and string constants. It unfortunately does not include symbols defined
4126by preprocessor @code{#define} commands.
4127
4128@value{GDBN} now supports array constants in expressions input by
4129the user. The syntax is @var{@{element, element@dots{}@}}. For example,
4130you can now use the command @code{print @{1, 2, 3@}} to build up an array in
4131memory that is malloc'd in the target program.
4132
c906108c
SS
4133Because C is so widespread, most of the expressions shown in examples in
4134this manual are in C. @xref{Languages, , Using @value{GDBN} with Different
4135Languages}, for information on how to use expressions in other
4136languages.
4137
4138In this section, we discuss operators that you can use in @value{GDBN}
4139expressions regardless of your programming language.
4140
4141Casts are supported in all languages, not just in C, because it is so
4142useful to cast a number into a pointer in order to examine a structure
4143at that address in memory.
4144@c FIXME: casts supported---Mod2 true?
c906108c
SS
4145
4146@value{GDBN} supports these operators, in addition to those common
4147to programming languages:
4148
4149@table @code
4150@item @@
4151@samp{@@} is a binary operator for treating parts of memory as arrays.
4152@xref{Arrays, ,Artificial arrays}, for more information.
4153
4154@item ::
4155@samp{::} allows you to specify a variable in terms of the file or
4156function where it is defined. @xref{Variables, ,Program variables}.
4157
4158@cindex @{@var{type}@}
4159@cindex type casting memory
4160@cindex memory, viewing as typed object
4161@cindex casts, to view memory
4162@item @{@var{type}@} @var{addr}
4163Refers to an object of type @var{type} stored at address @var{addr} in
4164memory. @var{addr} may be any expression whose value is an integer or
4165pointer (but parentheses are required around binary operators, just as in
4166a cast). This construct is allowed regardless of what kind of data is
4167normally supposed to reside at @var{addr}.
4168@end table
4169
53a5351d 4170@node Variables
c906108c
SS
4171@section Program variables
4172
4173The most common kind of expression to use is the name of a variable
4174in your program.
4175
4176Variables in expressions are understood in the selected stack frame
4177(@pxref{Selection, ,Selecting a frame}); they must be either:
4178
4179@itemize @bullet
4180@item
4181global (or file-static)
4182@end itemize
4183
4184@noindent or
4185
4186@itemize @bullet
4187@item
4188visible according to the scope rules of the
4189programming language from the point of execution in that frame
4190@end itemize
4191
4192@noindent This means that in the function
4193
4194@example
4195foo (a)
4196 int a;
4197@{
4198 bar (a);
4199 @{
4200 int b = test ();
4201 bar (b);
4202 @}
4203@}
4204@end example
4205
4206@noindent
4207you can examine and use the variable @code{a} whenever your program is
4208executing within the function @code{foo}, but you can only use or
4209examine the variable @code{b} while your program is executing inside
4210the block where @code{b} is declared.
4211
4212@cindex variable name conflict
4213There is an exception: you can refer to a variable or function whose
4214scope is a single source file even if the current execution point is not
4215in this file. But it is possible to have more than one such variable or
4216function with the same name (in different source files). If that
4217happens, referring to that name has unpredictable effects. If you wish,
4218you can specify a static variable in a particular function or file,
4219using the colon-colon notation:
4220
4221@cindex colon-colon
4222@iftex
4223@c info cannot cope with a :: index entry, but why deprive hard copy readers?
4224@kindex ::
4225@end iftex
4226@example
4227@var{file}::@var{variable}
4228@var{function}::@var{variable}
4229@end example
4230
4231@noindent
4232Here @var{file} or @var{function} is the name of the context for the
4233static @var{variable}. In the case of file names, you can use quotes to
4234make sure @value{GDBN} parses the file name as a single word---for example,
4235to print a global value of @code{x} defined in @file{f2.c}:
4236
4237@example
4238(@value{GDBP}) p 'f2.c'::x
4239@end example
4240
c906108c
SS
4241@cindex C++ scope resolution
4242This use of @samp{::} is very rarely in conflict with the very similar
4243use of the same notation in C++. @value{GDBN} also supports use of the C++
4244scope resolution operator in @value{GDBN} expressions.
4245@c FIXME: Um, so what happens in one of those rare cases where it's in
4246@c conflict?? --mew
c906108c
SS
4247
4248@cindex wrong values
4249@cindex variable values, wrong
4250@quotation
4251@emph{Warning:} Occasionally, a local variable may appear to have the
4252wrong value at certain points in a function---just after entry to a new
4253scope, and just before exit.
4254@end quotation
4255You may see this problem when you are stepping by machine instructions.
4256This is because, on most machines, it takes more than one instruction to
4257set up a stack frame (including local variable definitions); if you are
4258stepping by machine instructions, variables may appear to have the wrong
4259values until the stack frame is completely built. On exit, it usually
4260also takes more than one machine instruction to destroy a stack frame;
4261after you begin stepping through that group of instructions, local
4262variable definitions may be gone.
4263
4264This may also happen when the compiler does significant optimizations.
4265To be sure of always seeing accurate values, turn off all optimization
4266when compiling.
4267
53a5351d 4268@node Arrays
c906108c
SS
4269@section Artificial arrays
4270
4271@cindex artificial array
4272@kindex @@
4273It is often useful to print out several successive objects of the
4274same type in memory; a section of an array, or an array of
4275dynamically determined size for which only a pointer exists in the
4276program.
4277
4278You can do this by referring to a contiguous span of memory as an
4279@dfn{artificial array}, using the binary operator @samp{@@}. The left
4280operand of @samp{@@} should be the first element of the desired array
4281and be an individual object. The right operand should be the desired length
4282of the array. The result is an array value whose elements are all of
4283the type of the left argument. The first element is actually the left
4284argument; the second element comes from bytes of memory immediately
4285following those that hold the first element, and so on. Here is an
4286example. If a program says
4287
4288@example
4289int *array = (int *) malloc (len * sizeof (int));
4290@end example
4291
4292@noindent
4293you can print the contents of @code{array} with
4294
4295@example
4296p *array@@len
4297@end example
4298
4299The left operand of @samp{@@} must reside in memory. Array values made
4300with @samp{@@} in this way behave just like other arrays in terms of
4301subscripting, and are coerced to pointers when used in expressions.
4302Artificial arrays most often appear in expressions via the value history
4303(@pxref{Value History, ,Value history}), after printing one out.
4304
4305Another way to create an artificial array is to use a cast.
4306This re-interprets a value as if it were an array.
4307The value need not be in memory:
4308@example
4309(@value{GDBP}) p/x (short[2])0x12345678
4310$1 = @{0x1234, 0x5678@}
4311@end example
4312
4313As a convenience, if you leave the array length out (as in
4314@samp{(@var{type})[])@var{value}}) gdb calculates the size to fill
4315the value (as @samp{sizeof(@var{value})/sizeof(@var{type})}:
4316@example
4317(@value{GDBP}) p/x (short[])0x12345678
4318$2 = @{0x1234, 0x5678@}
4319@end example
4320
4321Sometimes the artificial array mechanism is not quite enough; in
4322moderately complex data structures, the elements of interest may not
4323actually be adjacent---for example, if you are interested in the values
4324of pointers in an array. One useful work-around in this situation is
4325to use a convenience variable (@pxref{Convenience Vars, ,Convenience
4326variables}) as a counter in an expression that prints the first
4327interesting value, and then repeat that expression via @key{RET}. For
4328instance, suppose you have an array @code{dtab} of pointers to
4329structures, and you are interested in the values of a field @code{fv}
4330in each structure. Here is an example of what you might type:
4331
4332@example
4333set $i = 0
4334p dtab[$i++]->fv
4335@key{RET}
4336@key{RET}
4337@dots{}
4338@end example
4339
53a5351d 4340@node Output Formats
c906108c
SS
4341@section Output formats
4342
4343@cindex formatted output
4344@cindex output formats
4345By default, @value{GDBN} prints a value according to its data type. Sometimes
4346this is not what you want. For example, you might want to print a number
4347in hex, or a pointer in decimal. Or you might want to view data in memory
4348at a certain address as a character string or as an instruction. To do
4349these things, specify an @dfn{output format} when you print a value.
4350
4351The simplest use of output formats is to say how to print a value
4352already computed. This is done by starting the arguments of the
4353@code{print} command with a slash and a format letter. The format
4354letters supported are:
4355
4356@table @code
4357@item x
4358Regard the bits of the value as an integer, and print the integer in
4359hexadecimal.
4360
4361@item d
4362Print as integer in signed decimal.
4363
4364@item u
4365Print as integer in unsigned decimal.
4366
4367@item o
4368Print as integer in octal.
4369
4370@item t
4371Print as integer in binary. The letter @samp{t} stands for ``two''.
4372@footnote{@samp{b} cannot be used because these format letters are also
4373used with the @code{x} command, where @samp{b} stands for ``byte'';
4374@pxref{Memory,,Examining memory}.}
4375
4376@item a
4377@cindex unknown address, locating
4378Print as an address, both absolute in hexadecimal and as an offset from
4379the nearest preceding symbol. You can use this format used to discover
4380where (in what function) an unknown address is located:
4381
4382@example
4383(@value{GDBP}) p/a 0x54320
4384$3 = 0x54320 <_initialize_vx+396>
4385@end example
4386
4387@item c
4388Regard as an integer and print it as a character constant.
4389
4390@item f
4391Regard the bits of the value as a floating point number and print
4392using typical floating point syntax.
4393@end table
4394
4395For example, to print the program counter in hex (@pxref{Registers}), type
4396
4397@example
4398p/x $pc
4399@end example
4400
4401@noindent
4402Note that no space is required before the slash; this is because command
4403names in @value{GDBN} cannot contain a slash.
4404
4405To reprint the last value in the value history with a different format,
4406you can use the @code{print} command with just a format and no
4407expression. For example, @samp{p/x} reprints the last value in hex.
4408
53a5351d 4409@node Memory
c906108c
SS
4410@section Examining memory
4411
4412You can use the command @code{x} (for ``examine'') to examine memory in
4413any of several formats, independently of your program's data types.
4414
4415@cindex examining memory
4416@table @code
4417@kindex x
4418@item x/@var{nfu} @var{addr}
4419@itemx x @var{addr}
4420@itemx x
4421Use the @code{x} command to examine memory.
4422@end table
4423
4424@var{n}, @var{f}, and @var{u} are all optional parameters that specify how
4425much memory to display and how to format it; @var{addr} is an
4426expression giving the address where you want to start displaying memory.
4427If you use defaults for @var{nfu}, you need not type the slash @samp{/}.
4428Several commands set convenient defaults for @var{addr}.
4429
4430@table @r
4431@item @var{n}, the repeat count
4432The repeat count is a decimal integer; the default is 1. It specifies
4433how much memory (counting by units @var{u}) to display.
4434@c This really is **decimal**; unaffected by 'set radix' as of GDB
4435@c 4.1.2.
4436
4437@item @var{f}, the display format
4438The display format is one of the formats used by @code{print},
4439@samp{s} (null-terminated string), or @samp{i} (machine instruction).
4440The default is @samp{x} (hexadecimal) initially.
4441The default changes each time you use either @code{x} or @code{print}.
4442
4443@item @var{u}, the unit size
4444The unit size is any of
4445
4446@table @code
4447@item b
4448Bytes.
4449@item h
4450Halfwords (two bytes).
4451@item w
4452Words (four bytes). This is the initial default.
4453@item g
4454Giant words (eight bytes).
4455@end table
4456
4457Each time you specify a unit size with @code{x}, that size becomes the
4458default unit the next time you use @code{x}. (For the @samp{s} and
4459@samp{i} formats, the unit size is ignored and is normally not written.)
4460
4461@item @var{addr}, starting display address
4462@var{addr} is the address where you want @value{GDBN} to begin displaying
4463memory. The expression need not have a pointer value (though it may);
4464it is always interpreted as an integer address of a byte of memory.
4465@xref{Expressions, ,Expressions}, for more information on expressions. The default for
4466@var{addr} is usually just after the last address examined---but several
4467other commands also set the default address: @code{info breakpoints} (to
4468the address of the last breakpoint listed), @code{info line} (to the
4469starting address of a line), and @code{print} (if you use it to display
4470a value from memory).
4471@end table
4472
4473For example, @samp{x/3uh 0x54320} is a request to display three halfwords
4474(@code{h}) of memory, formatted as unsigned decimal integers (@samp{u}),
4475starting at address @code{0x54320}. @samp{x/4xw $sp} prints the four
4476words (@samp{w}) of memory above the stack pointer (here, @samp{$sp};
4477@pxref{Registers}) in hexadecimal (@samp{x}).
4478
4479Since the letters indicating unit sizes are all distinct from the
4480letters specifying output formats, you do not have to remember whether
4481unit size or format comes first; either order works. The output
4482specifications @samp{4xw} and @samp{4wx} mean exactly the same thing.
4483(However, the count @var{n} must come first; @samp{wx4} does not work.)
4484
4485Even though the unit size @var{u} is ignored for the formats @samp{s}
4486and @samp{i}, you might still want to use a count @var{n}; for example,
4487@samp{3i} specifies that you want to see three machine instructions,
4488including any operands. The command @code{disassemble} gives an
4489alternative way of inspecting machine instructions; @pxref{Machine
4490Code,,Source and machine code}.
4491
4492All the defaults for the arguments to @code{x} are designed to make it
4493easy to continue scanning memory with minimal specifications each time
4494you use @code{x}. For example, after you have inspected three machine
4495instructions with @samp{x/3i @var{addr}}, you can inspect the next seven
4496with just @samp{x/7}. If you use @key{RET} to repeat the @code{x} command,
4497the repeat count @var{n} is used again; the other arguments default as
4498for successive uses of @code{x}.
4499
4500@cindex @code{$_}, @code{$__}, and value history
4501The addresses and contents printed by the @code{x} command are not saved
4502in the value history because there is often too much of them and they
4503would get in the way. Instead, @value{GDBN} makes these values available for
4504subsequent use in expressions as values of the convenience variables
4505@code{$_} and @code{$__}. After an @code{x} command, the last address
4506examined is available for use in expressions in the convenience variable
4507@code{$_}. The contents of that address, as examined, are available in
4508the convenience variable @code{$__}.
4509
4510If the @code{x} command has a repeat count, the address and contents saved
4511are from the last memory unit printed; this is not the same as the last
4512address printed if several units were printed on the last line of output.
4513
53a5351d 4514@node Auto Display
c906108c
SS
4515@section Automatic display
4516@cindex automatic display
4517@cindex display of expressions
4518
4519If you find that you want to print the value of an expression frequently
4520(to see how it changes), you might want to add it to the @dfn{automatic
4521display list} so that @value{GDBN} prints its value each time your program stops.
4522Each expression added to the list is given a number to identify it;
4523to remove an expression from the list, you specify that number.
4524The automatic display looks like this:
4525
4526@example
45272: foo = 38
45283: bar[5] = (struct hack *) 0x3804
4529@end example
4530
4531@noindent
4532This display shows item numbers, expressions and their current values. As with
4533displays you request manually using @code{x} or @code{print}, you can
4534specify the output format you prefer; in fact, @code{display} decides
4535whether to use @code{print} or @code{x} depending on how elaborate your
4536format specification is---it uses @code{x} if you specify a unit size,
4537or one of the two formats (@samp{i} and @samp{s}) that are only
4538supported by @code{x}; otherwise it uses @code{print}.
4539
4540@table @code
4541@kindex display
4542@item display @var{exp}
4543Add the expression @var{exp} to the list of expressions to display
4544each time your program stops. @xref{Expressions, ,Expressions}.
4545
4546@code{display} does not repeat if you press @key{RET} again after using it.
4547
4548@item display/@var{fmt} @var{exp}
4549For @var{fmt} specifying only a display format and not a size or
4550count, add the expression @var{exp} to the auto-display list but
4551arrange to display it each time in the specified format @var{fmt}.
4552@xref{Output Formats,,Output formats}.
4553
4554@item display/@var{fmt} @var{addr}
4555For @var{fmt} @samp{i} or @samp{s}, or including a unit-size or a
4556number of units, add the expression @var{addr} as a memory address to
4557be examined each time your program stops. Examining means in effect
4558doing @samp{x/@var{fmt} @var{addr}}. @xref{Memory, ,Examining memory}.
4559@end table
4560
4561For example, @samp{display/i $pc} can be helpful, to see the machine
4562instruction about to be executed each time execution stops (@samp{$pc}
4563is a common name for the program counter; @pxref{Registers}).
4564
4565@table @code
4566@kindex delete display
4567@kindex undisplay
4568@item undisplay @var{dnums}@dots{}
4569@itemx delete display @var{dnums}@dots{}
4570Remove item numbers @var{dnums} from the list of expressions to display.
4571
4572@code{undisplay} does not repeat if you press @key{RET} after using it.
4573(Otherwise you would just get the error @samp{No display number @dots{}}.)
4574
4575@kindex disable display
4576@item disable display @var{dnums}@dots{}
4577Disable the display of item numbers @var{dnums}. A disabled display
4578item is not printed automatically, but is not forgotten. It may be
4579enabled again later.
4580
4581@kindex enable display
4582@item enable display @var{dnums}@dots{}
4583Enable display of item numbers @var{dnums}. It becomes effective once
4584again in auto display of its expression, until you specify otherwise.
4585
4586@item display
4587Display the current values of the expressions on the list, just as is
4588done when your program stops.
4589
4590@kindex info display
4591@item info display
4592Print the list of expressions previously set up to display
4593automatically, each one with its item number, but without showing the
4594values. This includes disabled expressions, which are marked as such.
4595It also includes expressions which would not be displayed right now
4596because they refer to automatic variables not currently available.
4597@end table
4598
4599If a display expression refers to local variables, then it does not make
4600sense outside the lexical context for which it was set up. Such an
4601expression is disabled when execution enters a context where one of its
4602variables is not defined. For example, if you give the command
4603@code{display last_char} while inside a function with an argument
4604@code{last_char}, @value{GDBN} displays this argument while your program
4605continues to stop inside that function. When it stops elsewhere---where
4606there is no variable @code{last_char}---the display is disabled
4607automatically. The next time your program stops where @code{last_char}
4608is meaningful, you can enable the display expression once again.
4609
53a5351d 4610@node Print Settings
c906108c
SS
4611@section Print settings
4612
4613@cindex format options
4614@cindex print settings
4615@value{GDBN} provides the following ways to control how arrays, structures,
4616and symbols are printed.
4617
4618@noindent
4619These settings are useful for debugging programs in any language:
4620
4621@table @code
4622@kindex set print address
4623@item set print address
4624@itemx set print address on
4625@value{GDBN} prints memory addresses showing the location of stack
4626traces, structure values, pointer values, breakpoints, and so forth,
4627even when it also displays the contents of those addresses. The default
4628is @code{on}. For example, this is what a stack frame display looks like with
4629@code{set print address on}:
4630
4631@smallexample
4632@group
4633(@value{GDBP}) f
4634#0 set_quotes (lq=0x34c78 "<<", rq=0x34c88 ">>")
4635 at input.c:530
4636530 if (lquote != def_lquote)
4637@end group
4638@end smallexample
4639
4640@item set print address off
4641Do not print addresses when displaying their contents. For example,
4642this is the same stack frame displayed with @code{set print address off}:
4643
4644@smallexample
4645@group
4646(@value{GDBP}) set print addr off
4647(@value{GDBP}) f
4648#0 set_quotes (lq="<<", rq=">>") at input.c:530
4649530 if (lquote != def_lquote)
4650@end group
4651@end smallexample
4652
4653You can use @samp{set print address off} to eliminate all machine
4654dependent displays from the @value{GDBN} interface. For example, with
4655@code{print address off}, you should get the same text for backtraces on
4656all machines---whether or not they involve pointer arguments.
4657
4658@kindex show print address
4659@item show print address
4660Show whether or not addresses are to be printed.
4661@end table
4662
4663When @value{GDBN} prints a symbolic address, it normally prints the
4664closest earlier symbol plus an offset. If that symbol does not uniquely
4665identify the address (for example, it is a name whose scope is a single
4666source file), you may need to clarify. One way to do this is with
4667@code{info line}, for example @samp{info line *0x4537}. Alternately,
4668you can set @value{GDBN} to print the source file and line number when
4669it prints a symbolic address:
4670
4671@table @code
4672@kindex set print symbol-filename
4673@item set print symbol-filename on
4674Tell @value{GDBN} to print the source file name and line number of a
4675symbol in the symbolic form of an address.
4676
4677@item set print symbol-filename off
4678Do not print source file name and line number of a symbol. This is the
4679default.
4680
4681@kindex show print symbol-filename
4682@item show print symbol-filename
4683Show whether or not @value{GDBN} will print the source file name and
4684line number of a symbol in the symbolic form of an address.
4685@end table
4686
4687Another situation where it is helpful to show symbol filenames and line
4688numbers is when disassembling code; @value{GDBN} shows you the line
4689number and source file that corresponds to each instruction.
4690
4691Also, you may wish to see the symbolic form only if the address being
4692printed is reasonably close to the closest earlier symbol:
4693
4694@table @code
4695@kindex set print max-symbolic-offset
4696@item set print max-symbolic-offset @var{max-offset}
4697Tell @value{GDBN} to only display the symbolic form of an address if the
4698offset between the closest earlier symbol and the address is less than
4699@var{max-offset}. The default is 0, which tells @value{GDBN}
4700to always print the symbolic form of an address if any symbol precedes it.
4701
4702@kindex show print max-symbolic-offset
4703@item show print max-symbolic-offset
4704Ask how large the maximum offset is that @value{GDBN} prints in a
4705symbolic address.
4706@end table
4707
4708@cindex wild pointer, interpreting
4709@cindex pointer, finding referent
4710If you have a pointer and you are not sure where it points, try
4711@samp{set print symbol-filename on}. Then you can determine the name
4712and source file location of the variable where it points, using
4713@samp{p/a @var{pointer}}. This interprets the address in symbolic form.
4714For example, here @value{GDBN} shows that a variable @code{ptt} points
4715at another variable @code{t}, defined in @file{hi2.c}:
4716
4717@example
4718(@value{GDBP}) set print symbol-filename on
4719(@value{GDBP}) p/a ptt
4720$4 = 0xe008 <t in hi2.c>
4721@end example
4722
4723@quotation
4724@emph{Warning:} For pointers that point to a local variable, @samp{p/a}
4725does not show the symbol name and filename of the referent, even with
4726the appropriate @code{set print} options turned on.
4727@end quotation
4728
4729Other settings control how different kinds of objects are printed:
4730
4731@table @code
4732@kindex set print array
4733@item set print array
4734@itemx set print array on
4735Pretty print arrays. This format is more convenient to read,
4736but uses more space. The default is off.
4737
4738@item set print array off
4739Return to compressed format for arrays.
4740
4741@kindex show print array
4742@item show print array
4743Show whether compressed or pretty format is selected for displaying
4744arrays.
4745
4746@kindex set print elements
4747@item set print elements @var{number-of-elements}
4748Set a limit on how many elements of an array @value{GDBN} will print.
4749If @value{GDBN} is printing a large array, it stops printing after it has
4750printed the number of elements set by the @code{set print elements} command.
4751This limit also applies to the display of strings.
4752Setting @var{number-of-elements} to zero means that the printing is unlimited.
4753
4754@kindex show print elements
4755@item show print elements
4756Display the number of elements of a large array that @value{GDBN} will print.
4757If the number is 0, then the printing is unlimited.
4758
4759@kindex set print null-stop
4760@item set print null-stop
4761Cause @value{GDBN} to stop printing the characters of an array when the first
4762@sc{NULL} is encountered. This is useful when large arrays actually
4763contain only short strings.
4764
4765@kindex set print pretty
4766@item set print pretty on
4767Cause @value{GDBN} to print structures in an indented format with one member
4768per line, like this:
4769
4770@smallexample
4771@group
4772$1 = @{
4773 next = 0x0,
4774 flags = @{
4775 sweet = 1,
4776 sour = 1
4777 @},
4778 meat = 0x54 "Pork"
4779@}
4780@end group
4781@end smallexample
4782
4783@item set print pretty off
4784Cause @value{GDBN} to print structures in a compact format, like this:
4785
4786@smallexample
4787@group
4788$1 = @{next = 0x0, flags = @{sweet = 1, sour = 1@}, \
4789meat = 0x54 "Pork"@}
4790@end group
4791@end smallexample
4792
4793@noindent
4794This is the default format.
4795
4796@kindex show print pretty
4797@item show print pretty
4798Show which format @value{GDBN} is using to print structures.
4799
4800@kindex set print sevenbit-strings
4801@item set print sevenbit-strings on
4802Print using only seven-bit characters; if this option is set,
4803@value{GDBN} displays any eight-bit characters (in strings or
4804character values) using the notation @code{\}@var{nnn}. This setting is
4805best if you are working in English (@sc{ascii}) and you use the
4806high-order bit of characters as a marker or ``meta'' bit.
4807
4808@item set print sevenbit-strings off
4809Print full eight-bit characters. This allows the use of more
4810international character sets, and is the default.
4811
4812@kindex show print sevenbit-strings
4813@item show print sevenbit-strings
4814Show whether or not @value{GDBN} is printing only seven-bit characters.
4815
4816@kindex set print union
4817@item set print union on
4818Tell @value{GDBN} to print unions which are contained in structures. This
4819is the default setting.
4820
4821@item set print union off
4822Tell @value{GDBN} not to print unions which are contained in structures.
4823
4824@kindex show print union
4825@item show print union
4826Ask @value{GDBN} whether or not it will print unions which are contained in
4827structures.
4828
4829For example, given the declarations
4830
4831@smallexample
4832typedef enum @{Tree, Bug@} Species;
4833typedef enum @{Big_tree, Acorn, Seedling@} Tree_forms;
4834typedef enum @{Caterpillar, Cocoon, Butterfly@}
4835 Bug_forms;
4836
4837struct thing @{
4838 Species it;
4839 union @{
4840 Tree_forms tree;
4841 Bug_forms bug;
4842 @} form;
4843@};
4844
4845struct thing foo = @{Tree, @{Acorn@}@};
4846@end smallexample
4847
4848@noindent
4849with @code{set print union on} in effect @samp{p foo} would print
4850
4851@smallexample
4852$1 = @{it = Tree, form = @{tree = Acorn, bug = Cocoon@}@}
4853@end smallexample
4854
4855@noindent
4856and with @code{set print union off} in effect it would print
4857
4858@smallexample
4859$1 = @{it = Tree, form = @{...@}@}
4860@end smallexample
4861@end table
4862
c906108c
SS
4863@need 1000
4864@noindent
4865These settings are of interest when debugging C++ programs:
4866
4867@table @code
4868@cindex demangling
4869@kindex set print demangle
4870@item set print demangle
4871@itemx set print demangle on
4872Print C++ names in their source form rather than in the encoded
4873(``mangled'') form passed to the assembler and linker for type-safe
4874linkage. The default is @samp{on}.
4875
4876@kindex show print demangle
4877@item show print demangle
4878Show whether C++ names are printed in mangled or demangled form.
4879
4880@kindex set print asm-demangle
4881@item set print asm-demangle
4882@itemx set print asm-demangle on
4883Print C++ names in their source form rather than their mangled form, even
4884in assembler code printouts such as instruction disassemblies.
4885The default is off.
4886
4887@kindex show print asm-demangle
4888@item show print asm-demangle
4889Show whether C++ names in assembly listings are printed in mangled
4890or demangled form.
4891
4892@kindex set demangle-style
4893@cindex C++ symbol decoding style
4894@cindex symbol decoding style, C++
4895@item set demangle-style @var{style}
4896Choose among several encoding schemes used by different compilers to
4897represent C++ names. The choices for @var{style} are currently:
4898
4899@table @code
4900@item auto
4901Allow @value{GDBN} to choose a decoding style by inspecting your program.
4902
4903@item gnu
4904Decode based on the @sc{gnu} C++ compiler (@code{g++}) encoding algorithm.
c906108c 4905This is the default.
c906108c
SS
4906
4907@item hp
4908Decode based on the HP ANSI C++ (@code{aCC}) encoding algorithm.
4909
4910@item lucid
4911Decode based on the Lucid C++ compiler (@code{lcc}) encoding algorithm.
4912
4913@item arm
4914Decode using the algorithm in the @cite{C++ Annotated Reference Manual}.
4915@strong{Warning:} this setting alone is not sufficient to allow
4916debugging @code{cfront}-generated executables. @value{GDBN} would
4917require further enhancement to permit that.
4918
4919@end table
4920If you omit @var{style}, you will see a list of possible formats.
4921
4922@kindex show demangle-style
4923@item show demangle-style
4924Display the encoding style currently in use for decoding C++ symbols.
4925
4926@kindex set print object
4927@item set print object
4928@itemx set print object on
4929When displaying a pointer to an object, identify the @emph{actual}
4930(derived) type of the object rather than the @emph{declared} type, using
4931the virtual function table.
4932
4933@item set print object off
4934Display only the declared type of objects, without reference to the
4935virtual function table. This is the default setting.
4936
4937@kindex show print object
4938@item show print object
4939Show whether actual, or declared, object types are displayed.
4940
4941@kindex set print static-members
4942@item set print static-members
4943@itemx set print static-members on
4944Print static members when displaying a C++ object. The default is on.
4945
4946@item set print static-members off
4947Do not print static members when displaying a C++ object.
4948
4949@kindex show print static-members
4950@item show print static-members
4951Show whether C++ static members are printed, or not.
4952
4953@c These don't work with HP ANSI C++ yet.
4954@kindex set print vtbl
4955@item set print vtbl
4956@itemx set print vtbl on
4957Pretty print C++ virtual function tables. The default is off.
c906108c
SS
4958(The @code{vtbl} commands do not work on programs compiled with the HP
4959ANSI C++ compiler (@code{aCC}).)
c906108c
SS
4960
4961@item set print vtbl off
4962Do not pretty print C++ virtual function tables.
4963
4964@kindex show print vtbl
4965@item show print vtbl
4966Show whether C++ virtual function tables are pretty printed, or not.
4967@end table
c906108c 4968
53a5351d 4969@node Value History
c906108c
SS
4970@section Value history
4971
4972@cindex value history
4973Values printed by the @code{print} command are saved in the @value{GDBN}
4974@dfn{value history}. This allows you to refer to them in other expressions.
4975Values are kept until the symbol table is re-read or discarded
4976(for example with the @code{file} or @code{symbol-file} commands).
4977When the symbol table changes, the value history is discarded,
4978since the values may contain pointers back to the types defined in the
4979symbol table.
4980
4981@cindex @code{$}
4982@cindex @code{$$}
4983@cindex history number
4984The values printed are given @dfn{history numbers} by which you can
4985refer to them. These are successive integers starting with one.
4986@code{print} shows you the history number assigned to a value by
4987printing @samp{$@var{num} = } before the value; here @var{num} is the
4988history number.
4989
4990To refer to any previous value, use @samp{$} followed by the value's
4991history number. The way @code{print} labels its output is designed to
4992remind you of this. Just @code{$} refers to the most recent value in
4993the history, and @code{$$} refers to the value before that.
4994@code{$$@var{n}} refers to the @var{n}th value from the end; @code{$$2}
4995is the value just prior to @code{$$}, @code{$$1} is equivalent to
4996@code{$$}, and @code{$$0} is equivalent to @code{$}.
4997
4998For example, suppose you have just printed a pointer to a structure and
4999want to see the contents of the structure. It suffices to type
5000
5001@example
5002p *$
5003@end example
5004
5005If you have a chain of structures where the component @code{next} points
5006to the next one, you can print the contents of the next one with this:
5007
5008@example
5009p *$.next
5010@end example
5011
5012@noindent
5013You can print successive links in the chain by repeating this
5014command---which you can do by just typing @key{RET}.
5015
5016Note that the history records values, not expressions. If the value of
5017@code{x} is 4 and you type these commands:
5018
5019@example
5020print x
5021set x=5
5022@end example
5023
5024@noindent
5025then the value recorded in the value history by the @code{print} command
5026remains 4 even though the value of @code{x} has changed.
5027
5028@table @code
5029@kindex show values
5030@item show values
5031Print the last ten values in the value history, with their item numbers.
5032This is like @samp{p@ $$9} repeated ten times, except that @code{show
5033values} does not change the history.
5034
5035@item show values @var{n}
5036Print ten history values centered on history item number @var{n}.
5037
5038@item show values +
5039Print ten history values just after the values last printed. If no more
5040values are available, @code{show values +} produces no display.
5041@end table
5042
5043Pressing @key{RET} to repeat @code{show values @var{n}} has exactly the
5044same effect as @samp{show values +}.
5045
53a5351d 5046@node Convenience Vars
c906108c
SS
5047@section Convenience variables
5048
5049@cindex convenience variables
5050@value{GDBN} provides @dfn{convenience variables} that you can use within
5051@value{GDBN} to hold on to a value and refer to it later. These variables
5052exist entirely within @value{GDBN}; they are not part of your program, and
5053setting a convenience variable has no direct effect on further execution
5054of your program. That is why you can use them freely.
5055
5056Convenience variables are prefixed with @samp{$}. Any name preceded by
5057@samp{$} can be used for a convenience variable, unless it is one of
5058the predefined machine-specific register names (@pxref{Registers}).
5059(Value history references, in contrast, are @emph{numbers} preceded
5060by @samp{$}. @xref{Value History, ,Value history}.)
5061
5062You can save a value in a convenience variable with an assignment
5063expression, just as you would set a variable in your program.
5064For example:
5065
5066@example
5067set $foo = *object_ptr
5068@end example
5069
5070@noindent
5071would save in @code{$foo} the value contained in the object pointed to by
5072@code{object_ptr}.
5073
5074Using a convenience variable for the first time creates it, but its
5075value is @code{void} until you assign a new value. You can alter the
5076value with another assignment at any time.
5077
5078Convenience variables have no fixed types. You can assign a convenience
5079variable any type of value, including structures and arrays, even if
5080that variable already has a value of a different type. The convenience
5081variable, when used as an expression, has the type of its current value.
5082
5083@table @code
5084@kindex show convenience
5085@item show convenience
5086Print a list of convenience variables used so far, and their values.
5087Abbreviated @code{show con}.
5088@end table
5089
5090One of the ways to use a convenience variable is as a counter to be
5091incremented or a pointer to be advanced. For example, to print
5092a field from successive elements of an array of structures:
5093
5094@example
5095set $i = 0
5096print bar[$i++]->contents
5097@end example
5098
5099@noindent Repeat that command by typing @key{RET}.
5100
5101Some convenience variables are created automatically by @value{GDBN} and given
5102values likely to be useful.
5103
5104@table @code
5105@kindex $_
5106@item $_
5107The variable @code{$_} is automatically set by the @code{x} command to
5108the last address examined (@pxref{Memory, ,Examining memory}). Other
5109commands which provide a default address for @code{x} to examine also
5110set @code{$_} to that address; these commands include @code{info line}
5111and @code{info breakpoint}. The type of @code{$_} is @code{void *}
5112except when set by the @code{x} command, in which case it is a pointer
5113to the type of @code{$__}.
5114
5115@kindex $__
5116@item $__
5117The variable @code{$__} is automatically set by the @code{x} command
5118to the value found in the last address examined. Its type is chosen
5119to match the format in which the data was printed.
5120
5121@item $_exitcode
5122@kindex $_exitcode
5123The variable @code{$_exitcode} is automatically set to the exit code when
5124the program being debugged terminates.
5125@end table
5126
53a5351d
JM
5127On HP-UX systems, if you refer to a function or variable name that
5128begins with a dollar sign, @value{GDBN} searches for a user or system
5129name first, before it searches for a convenience variable.
c906108c 5130
53a5351d 5131@node Registers
c906108c
SS
5132@section Registers
5133
5134@cindex registers
5135You can refer to machine register contents, in expressions, as variables
5136with names starting with @samp{$}. The names of registers are different
5137for each machine; use @code{info registers} to see the names used on
5138your machine.
5139
5140@table @code
5141@kindex info registers
5142@item info registers
5143Print the names and values of all registers except floating-point
5144registers (in the selected stack frame).
5145
5146@kindex info all-registers
5147@cindex floating point registers
5148@item info all-registers
5149Print the names and values of all registers, including floating-point
5150registers.
5151
5152@item info registers @var{regname} @dots{}
5153Print the @dfn{relativized} value of each specified register @var{regname}.
5154As discussed in detail below, register values are normally relative to
5155the selected stack frame. @var{regname} may be any register name valid on
5156the machine you are using, with or without the initial @samp{$}.
5157@end table
5158
5159@value{GDBN} has four ``standard'' register names that are available (in
5160expressions) on most machines---whenever they do not conflict with an
5161architecture's canonical mnemonics for registers. The register names
5162@code{$pc} and @code{$sp} are used for the program counter register and
5163the stack pointer. @code{$fp} is used for a register that contains a
5164pointer to the current stack frame, and @code{$ps} is used for a
5165register that contains the processor status. For example,
5166you could print the program counter in hex with
5167
5168@example
5169p/x $pc
5170@end example
5171
5172@noindent
5173or print the instruction to be executed next with
5174
5175@example
5176x/i $pc
5177@end example
5178
5179@noindent
5180or add four to the stack pointer@footnote{This is a way of removing
5181one word from the stack, on machines where stacks grow downward in
5182memory (most machines, nowadays). This assumes that the innermost
5183stack frame is selected; setting @code{$sp} is not allowed when other
5184stack frames are selected. To pop entire frames off the stack,
5185regardless of machine architecture, use @code{return};
5186@pxref{Returning, ,Returning from a function}.} with
5187
5188@example
5189set $sp += 4
5190@end example
5191
5192Whenever possible, these four standard register names are available on
5193your machine even though the machine has different canonical mnemonics,
5194so long as there is no conflict. The @code{info registers} command
5195shows the canonical names. For example, on the SPARC, @code{info
5196registers} displays the processor status register as @code{$psr} but you
5197can also refer to it as @code{$ps}.
5198
5199@value{GDBN} always considers the contents of an ordinary register as an
5200integer when the register is examined in this way. Some machines have
5201special registers which can hold nothing but floating point; these
5202registers are considered to have floating point values. There is no way
5203to refer to the contents of an ordinary register as floating point value
5204(although you can @emph{print} it as a floating point value with
5205@samp{print/f $@var{regname}}).
5206
5207Some registers have distinct ``raw'' and ``virtual'' data formats. This
5208means that the data format in which the register contents are saved by
5209the operating system is not the same one that your program normally
5210sees. For example, the registers of the 68881 floating point
5211coprocessor are always saved in ``extended'' (raw) format, but all C
5212programs expect to work with ``double'' (virtual) format. In such
5213cases, @value{GDBN} normally works with the virtual format only (the format
5214that makes sense for your program), but the @code{info registers} command
5215prints the data in both formats.
5216
5217Normally, register values are relative to the selected stack frame
5218(@pxref{Selection, ,Selecting a frame}). This means that you get the
5219value that the register would contain if all stack frames farther in
5220were exited and their saved registers restored. In order to see the
5221true contents of hardware registers, you must select the innermost
5222frame (with @samp{frame 0}).
5223
5224However, @value{GDBN} must deduce where registers are saved, from the machine
5225code generated by your compiler. If some registers are not saved, or if
5226@value{GDBN} is unable to locate the saved registers, the selected stack
5227frame makes no difference.
5228
c906108c
SS
5229@table @code
5230@kindex set rstack_high_address
5231@cindex AMD 29K register stack
5232@cindex register stack, AMD29K
5233@item set rstack_high_address @var{address}
5234On AMD 29000 family processors, registers are saved in a separate
5235``register stack''. There is no way for @value{GDBN} to determine the extent
5236of this stack. Normally, @value{GDBN} just assumes that the stack is ``large
5237enough''. This may result in @value{GDBN} referencing memory locations that
5238do not exist. If necessary, you can get around this problem by
5239specifying the ending address of the register stack with the @code{set
5240rstack_high_address} command. The argument should be an address, which
5241you probably want to precede with @samp{0x} to specify in
5242hexadecimal.
5243
5244@kindex show rstack_high_address
5245@item show rstack_high_address
5246Display the current limit of the register stack, on AMD 29000 family
5247processors.
5248@end table
c906108c 5249
53a5351d 5250@node Floating Point Hardware
c906108c
SS
5251@section Floating point hardware
5252@cindex floating point
5253
5254Depending on the configuration, @value{GDBN} may be able to give
5255you more information about the status of the floating point hardware.
5256
5257@table @code
5258@kindex info float
5259@item info float
5260Display hardware-dependent information about the floating
5261point unit. The exact contents and layout vary depending on the
5262floating point chip. Currently, @samp{info float} is supported on
5263the ARM and x86 machines.
5264@end table
c906108c 5265
53a5351d 5266@node Languages
c906108c
SS
5267@chapter Using @value{GDBN} with Different Languages
5268@cindex languages
5269
c906108c
SS
5270Although programming languages generally have common aspects, they are
5271rarely expressed in the same manner. For instance, in ANSI C,
5272dereferencing a pointer @code{p} is accomplished by @code{*p}, but in
5273Modula-2, it is accomplished by @code{p^}. Values can also be
5274represented (and displayed) differently. Hex numbers in C appear as
5275@samp{0x1ae}, while in Modula-2 they appear as @samp{1AEH}.
c906108c
SS
5276
5277@cindex working language
5278Language-specific information is built into @value{GDBN} for some languages,
5279allowing you to express operations like the above in your program's
5280native language, and allowing @value{GDBN} to output values in a manner
5281consistent with the syntax of your program's native language. The
5282language you use to build expressions is called the @dfn{working
5283language}.
5284
5285@menu
5286* Setting:: Switching between source languages
5287* Show:: Displaying the language
c906108c 5288* Checks:: Type and range checks
c906108c
SS
5289* Support:: Supported languages
5290@end menu
5291
53a5351d 5292@node Setting
c906108c
SS
5293@section Switching between source languages
5294
5295There are two ways to control the working language---either have @value{GDBN}
5296set it automatically, or select it manually yourself. You can use the
5297@code{set language} command for either purpose. On startup, @value{GDBN}
5298defaults to setting the language automatically. The working language is
5299used to determine how expressions you type are interpreted, how values
5300are printed, etc.
5301
5302In addition to the working language, every source file that
5303@value{GDBN} knows about has its own working language. For some object
5304file formats, the compiler might indicate which language a particular
5305source file is in. However, most of the time @value{GDBN} infers the
5306language from the name of the file. The language of a source file
5307controls whether C++ names are demangled---this way @code{backtrace} can
5308show each frame appropriately for its own language. There is no way to
5309set the language of a source file from within @value{GDBN}.
5310
5311This is most commonly a problem when you use a program, such
5312as @code{cfront} or @code{f2c}, that generates C but is written in
5313another language. In that case, make the
5314program use @code{#line} directives in its C output; that way
5315@value{GDBN} will know the correct language of the source code of the original
5316program, and will display that source code, not the generated C code.
5317
5318@menu
5319* Filenames:: Filename extensions and languages.
5320* Manually:: Setting the working language manually
5321* Automatically:: Having @value{GDBN} infer the source language
5322@end menu
5323
53a5351d 5324@node Filenames
c906108c
SS
5325@subsection List of filename extensions and languages
5326
5327If a source file name ends in one of the following extensions, then
5328@value{GDBN} infers that its language is the one indicated.
5329
5330@table @file
5331
5332@item .c
5333C source file
5334
5335@item .C
5336@itemx .cc
5337@itemx .cp
5338@itemx .cpp
5339@itemx .cxx
5340@itemx .c++
5341C++ source file
5342
5343@item .f
5344@itemx .F
5345Fortran source file
5346
c906108c
SS
5347@item .ch
5348@itemx .c186
5349@itemx .c286
5350CHILL source file.
c906108c 5351
c906108c
SS
5352@item .mod
5353Modula-2 source file
c906108c
SS
5354
5355@item .s
5356@itemx .S
5357Assembler source file. This actually behaves almost like C, but
5358@value{GDBN} does not skip over function prologues when stepping.
5359@end table
5360
5361In addition, you may set the language associated with a filename
5362extension. @xref{Show, , Displaying the language}.
5363
53a5351d 5364@node Manually
c906108c
SS
5365@subsection Setting the working language
5366
5367If you allow @value{GDBN} to set the language automatically,
5368expressions are interpreted the same way in your debugging session and
5369your program.
5370
5371@kindex set language
5372If you wish, you may set the language manually. To do this, issue the
5373command @samp{set language @var{lang}}, where @var{lang} is the name of
5374a language, such as
c906108c 5375@code{c} or @code{modula-2}.
c906108c
SS
5376For a list of the supported languages, type @samp{set language}.
5377
c906108c
SS
5378Setting the language manually prevents @value{GDBN} from updating the working
5379language automatically. This can lead to confusion if you try
5380to debug a program when the working language is not the same as the
5381source language, when an expression is acceptable to both
5382languages---but means different things. For instance, if the current
5383source file were written in C, and @value{GDBN} was parsing Modula-2, a
5384command such as:
5385
5386@example
5387print a = b + c
5388@end example
5389
5390@noindent
5391might not have the effect you intended. In C, this means to add
5392@code{b} and @code{c} and place the result in @code{a}. The result
5393printed would be the value of @code{a}. In Modula-2, this means to compare
5394@code{a} to the result of @code{b+c}, yielding a @code{BOOLEAN} value.
c906108c 5395
53a5351d 5396@node Automatically
c906108c
SS
5397@subsection Having @value{GDBN} infer the source language
5398
5399To have @value{GDBN} set the working language automatically, use
5400@samp{set language local} or @samp{set language auto}. @value{GDBN}
5401then infers the working language. That is, when your program stops in a
5402frame (usually by encountering a breakpoint), @value{GDBN} sets the
5403working language to the language recorded for the function in that
5404frame. If the language for a frame is unknown (that is, if the function
5405or block corresponding to the frame was defined in a source file that
5406does not have a recognized extension), the current working language is
5407not changed, and @value{GDBN} issues a warning.
5408
5409This may not seem necessary for most programs, which are written
5410entirely in one source language. However, program modules and libraries
5411written in one source language can be used by a main program written in
5412a different source language. Using @samp{set language auto} in this
5413case frees you from having to set the working language manually.
5414
53a5351d 5415@node Show
c906108c 5416@section Displaying the language
c906108c
SS
5417
5418The following commands help you find out which language is the
5419working language, and also what language source files were written in.
5420
5421@kindex show language
5422@kindex info frame
5423@kindex info source
5424@table @code
5425@item show language
5426Display the current working language. This is the
5427language you can use with commands such as @code{print} to
5428build and compute expressions that may involve variables in your program.
5429
5430@item info frame
5431Display the source language for this frame. This language becomes the
5432working language if you use an identifier from this frame.
5433@xref{Frame Info, ,Information about a frame}, to identify the other
5434information listed here.
5435
5436@item info source
5437Display the source language of this source file.
5438@xref{Symbols, ,Examining the Symbol Table}, to identify the other
5439information listed here.
5440@end table
5441
5442In unusual circumstances, you may have source files with extensions
5443not in the standard list. You can then set the extension associated
5444with a language explicitly:
5445
5446@kindex set extension-language
5447@kindex info extensions
5448@table @code
5449@item set extension-language @var{.ext} @var{language}
5450Set source files with extension @var{.ext} to be assumed to be in
5451the source language @var{language}.
5452
5453@item info extensions
5454List all the filename extensions and the associated languages.
5455@end table
5456
53a5351d 5457@node Checks
c906108c
SS
5458@section Type and range checking
5459
5460@quotation
5461@emph{Warning:} In this release, the @value{GDBN} commands for type and range
5462checking are included, but they do not yet have any effect. This
5463section documents the intended facilities.
5464@end quotation
5465@c FIXME remove warning when type/range code added
5466
5467Some languages are designed to guard you against making seemingly common
5468errors through a series of compile- and run-time checks. These include
5469checking the type of arguments to functions and operators, and making
5470sure mathematical overflows are caught at run time. Checks such as
5471these help to ensure a program's correctness once it has been compiled
5472by eliminating type mismatches, and providing active checks for range
5473errors when your program is running.
5474
5475@value{GDBN} can check for conditions like the above if you wish.
5476Although @value{GDBN} does not check the statements in your program, it
5477can check expressions entered directly into @value{GDBN} for evaluation via
5478the @code{print} command, for example. As with the working language,
5479@value{GDBN} can also decide whether or not to check automatically based on
5480your program's source language. @xref{Support, ,Supported languages},
5481for the default settings of supported languages.
5482
5483@menu
5484* Type Checking:: An overview of type checking
5485* Range Checking:: An overview of range checking
5486@end menu
5487
5488@cindex type checking
5489@cindex checks, type
53a5351d 5490@node Type Checking
c906108c
SS
5491@subsection An overview of type checking
5492
5493Some languages, such as Modula-2, are strongly typed, meaning that the
5494arguments to operators and functions have to be of the correct type,
5495otherwise an error occurs. These checks prevent type mismatch
5496errors from ever causing any run-time problems. For example,
5497
5498@smallexample
54991 + 2 @result{} 3
5500@exdent but
5501@error{} 1 + 2.3
5502@end smallexample
5503
5504The second example fails because the @code{CARDINAL} 1 is not
5505type-compatible with the @code{REAL} 2.3.
5506
5507For the expressions you use in @value{GDBN} commands, you can tell the
5508@value{GDBN} type checker to skip checking;
5509to treat any mismatches as errors and abandon the expression;
5510or to only issue warnings when type mismatches occur,
5511but evaluate the expression anyway. When you choose the last of
5512these, @value{GDBN} evaluates expressions like the second example above, but
5513also issues a warning.
5514
5515Even if you turn type checking off, there may be other reasons
5516related to type that prevent @value{GDBN} from evaluating an expression.
5517For instance, @value{GDBN} does not know how to add an @code{int} and
5518a @code{struct foo}. These particular type errors have nothing to do
5519with the language in use, and usually arise from expressions, such as
5520the one described above, which make little sense to evaluate anyway.
5521
5522Each language defines to what degree it is strict about type. For
5523instance, both Modula-2 and C require the arguments to arithmetical
5524operators to be numbers. In C, enumerated types and pointers can be
5525represented as numbers, so that they are valid arguments to mathematical
5526operators. @xref{Support, ,Supported languages}, for further
5527details on specific languages.
5528
5529@value{GDBN} provides some additional commands for controlling the type checker:
5530
5531@kindex set check
5532@kindex set check type
5533@kindex show check type
5534@table @code
5535@item set check type auto
5536Set type checking on or off based on the current working language.
5537@xref{Support, ,Supported languages}, for the default settings for
5538each language.
5539
5540@item set check type on
5541@itemx set check type off
5542Set type checking on or off, overriding the default setting for the
5543current working language. Issue a warning if the setting does not
5544match the language default. If any type mismatches occur in
5545evaluating an expression while typechecking is on, @value{GDBN} prints a
5546message and aborts evaluation of the expression.
5547
5548@item set check type warn
5549Cause the type checker to issue warnings, but to always attempt to
5550evaluate the expression. Evaluating the expression may still
5551be impossible for other reasons. For example, @value{GDBN} cannot add
5552numbers and structures.
5553
5554@item show type
5555Show the current setting of the type checker, and whether or not @value{GDBN}
5556is setting it automatically.
5557@end table
5558
5559@cindex range checking
5560@cindex checks, range
53a5351d 5561@node Range Checking
c906108c
SS
5562@subsection An overview of range checking
5563
5564In some languages (such as Modula-2), it is an error to exceed the
5565bounds of a type; this is enforced with run-time checks. Such range
5566checking is meant to ensure program correctness by making sure
5567computations do not overflow, or indices on an array element access do
5568not exceed the bounds of the array.
5569
5570For expressions you use in @value{GDBN} commands, you can tell
5571@value{GDBN} to treat range errors in one of three ways: ignore them,
5572always treat them as errors and abandon the expression, or issue
5573warnings but evaluate the expression anyway.
5574
5575A range error can result from numerical overflow, from exceeding an
5576array index bound, or when you type a constant that is not a member
5577of any type. Some languages, however, do not treat overflows as an
5578error. In many implementations of C, mathematical overflow causes the
5579result to ``wrap around'' to lower values---for example, if @var{m} is
5580the largest integer value, and @var{s} is the smallest, then
5581
5582@example
5583@var{m} + 1 @result{} @var{s}
5584@end example
5585
5586This, too, is specific to individual languages, and in some cases
5587specific to individual compilers or machines. @xref{Support, ,
5588Supported languages}, for further details on specific languages.
5589
5590@value{GDBN} provides some additional commands for controlling the range checker:
5591
5592@kindex set check
5593@kindex set check range
5594@kindex show check range
5595@table @code
5596@item set check range auto
5597Set range checking on or off based on the current working language.
5598@xref{Support, ,Supported languages}, for the default settings for
5599each language.
5600
5601@item set check range on
5602@itemx set check range off
5603Set range checking on or off, overriding the default setting for the
5604current working language. A warning is issued if the setting does not
5605match the language default. If a range error occurs, then a message
5606is printed and evaluation of the expression is aborted.
5607
5608@item set check range warn
5609Output messages when the @value{GDBN} range checker detects a range error,
5610but attempt to evaluate the expression anyway. Evaluating the
5611expression may still be impossible for other reasons, such as accessing
5612memory that the process does not own (a typical example from many Unix
5613systems).
5614
5615@item show range
5616Show the current setting of the range checker, and whether or not it is
5617being set automatically by @value{GDBN}.
5618@end table
c906108c 5619
53a5351d 5620@node Support
c906108c 5621@section Supported languages
c906108c 5622
cce74817
JM
5623@value{GDBN} supports C, C++, Fortran, Java, Chill, assembly, and Modula-2.
5624@c This is false ...
c906108c
SS
5625Some @value{GDBN} features may be used in expressions regardless of the
5626language you use: the @value{GDBN} @code{@@} and @code{::} operators,
5627and the @samp{@{type@}addr} construct (@pxref{Expressions,
5628,Expressions}) can be used with the constructs of any supported
5629language.
5630
5631The following sections detail to what degree each source language is
5632supported by @value{GDBN}. These sections are not meant to be language
5633tutorials or references, but serve only as a reference guide to what the
5634@value{GDBN} expression parser accepts, and what input and output
5635formats should look like for different languages. There are many good
5636books written on each of these languages; please look to these for a
5637language reference or tutorial.
5638
c906108c 5639@menu
7a292a7a 5640* C:: C and C++
cce74817
JM
5641* Modula-2:: Modula-2
5642* Chill:: Chill
c906108c
SS
5643@end menu
5644
53a5351d 5645@node C
c906108c 5646@subsection C and C++
7a292a7a 5647
c906108c
SS
5648@cindex C and C++
5649@cindex expressions in C or C++
c906108c
SS
5650
5651Since C and C++ are so closely related, many features of @value{GDBN} apply
5652to both languages. Whenever this is the case, we discuss those languages
5653together.
5654
c906108c
SS
5655@cindex C++
5656@kindex g++
5657@cindex @sc{gnu} C++
5658The C++ debugging facilities are jointly implemented by the C++
5659compiler and @value{GDBN}. Therefore, to debug your C++ code
5660effectively, you must compile your C++ programs with a supported
5661C++ compiler, such as @sc{gnu} @code{g++}, or the HP ANSI C++
5662compiler (@code{aCC}).
5663
5664For best results when using @sc{gnu} C++, use the stabs debugging
5665format. You can select that format explicitly with the @code{g++}
5666command-line options @samp{-gstabs} or @samp{-gstabs+}. See
5667@ref{Debugging Options,,Options for Debugging Your Program or @sc{gnu}
5668CC, gcc.info, Using @sc{gnu} CC}, for more information.
c906108c 5669
c906108c
SS
5670@menu
5671* C Operators:: C and C++ operators
5672* C Constants:: C and C++ constants
7a292a7a 5673* C plus plus expressions:: C++ expressions
c906108c 5674* C Defaults:: Default settings for C and C++
c906108c 5675* C Checks:: C and C++ type and range checks
c906108c
SS
5676* Debugging C:: @value{GDBN} and C
5677* Debugging C plus plus:: @value{GDBN} features for C++
5678@end menu
c906108c 5679
53a5351d 5680@node C Operators
c906108c 5681@subsubsection C and C++ operators
7a292a7a
SS
5682
5683@cindex C and C++ operators
c906108c
SS
5684
5685Operators must be defined on values of specific types. For instance,
5686@code{+} is defined on numbers, but not on structures. Operators are
5687often defined on groups of types.
5688
c906108c 5689For the purposes of C and C++, the following definitions hold:
c906108c
SS
5690
5691@itemize @bullet
53a5351d 5692
c906108c 5693@item
c906108c
SS
5694@emph{Integral types} include @code{int} with any of its storage-class
5695specifiers; @code{char}; @code{enum}; and, for C++, @code{bool}.
c906108c
SS
5696
5697@item
5698@emph{Floating-point types} include @code{float} and @code{double}.
5699
5700@item
53a5351d 5701@emph{Pointer types} include all types defined as @code{(@var{type} *)}.
c906108c
SS
5702
5703@item
5704@emph{Scalar types} include all of the above.
53a5351d 5705
c906108c
SS
5706@end itemize
5707
5708@noindent
5709The following operators are supported. They are listed here
5710in order of increasing precedence:
5711
5712@table @code
5713@item ,
5714The comma or sequencing operator. Expressions in a comma-separated list
5715are evaluated from left to right, with the result of the entire
5716expression being the last expression evaluated.
5717
5718@item =
5719Assignment. The value of an assignment expression is the value
5720assigned. Defined on scalar types.
5721
5722@item @var{op}=
5723Used in an expression of the form @w{@code{@var{a} @var{op}= @var{b}}},
5724and translated to @w{@code{@var{a} = @var{a op b}}}.
5725@w{@code{@var{op}=}} and @code{=} have the same precendence.
5726@var{op} is any one of the operators @code{|}, @code{^}, @code{&},
5727@code{<<}, @code{>>}, @code{+}, @code{-}, @code{*}, @code{/}, @code{%}.
5728
5729@item ?:
5730The ternary operator. @code{@var{a} ? @var{b} : @var{c}} can be thought
5731of as: if @var{a} then @var{b} else @var{c}. @var{a} should be of an
5732integral type.
5733
5734@item ||
5735Logical @sc{or}. Defined on integral types.
5736
5737@item &&
5738Logical @sc{and}. Defined on integral types.
5739
5740@item |
5741Bitwise @sc{or}. Defined on integral types.
5742
5743@item ^
5744Bitwise exclusive-@sc{or}. Defined on integral types.
5745
5746@item &
5747Bitwise @sc{and}. Defined on integral types.
5748
5749@item ==@r{, }!=
5750Equality and inequality. Defined on scalar types. The value of these
5751expressions is 0 for false and non-zero for true.
5752
5753@item <@r{, }>@r{, }<=@r{, }>=
5754Less than, greater than, less than or equal, greater than or equal.
5755Defined on scalar types. The value of these expressions is 0 for false
5756and non-zero for true.
5757
5758@item <<@r{, }>>
5759left shift, and right shift. Defined on integral types.
5760
5761@item @@
5762The @value{GDBN} ``artificial array'' operator (@pxref{Expressions, ,Expressions}).
5763
5764@item +@r{, }-
5765Addition and subtraction. Defined on integral types, floating-point types and
5766pointer types.
5767
5768@item *@r{, }/@r{, }%
5769Multiplication, division, and modulus. Multiplication and division are
5770defined on integral and floating-point types. Modulus is defined on
5771integral types.
5772
5773@item ++@r{, }--
5774Increment and decrement. When appearing before a variable, the
5775operation is performed before the variable is used in an expression;
5776when appearing after it, the variable's value is used before the
5777operation takes place.
5778
5779@item *
5780Pointer dereferencing. Defined on pointer types. Same precedence as
5781@code{++}.
5782
5783@item &
5784Address operator. Defined on variables. Same precedence as @code{++}.
5785
c906108c
SS
5786For debugging C++, @value{GDBN} implements a use of @samp{&} beyond what is
5787allowed in the C++ language itself: you can use @samp{&(&@var{ref})}
5788(or, if you prefer, simply @samp{&&@var{ref}}) to examine the address
5789where a C++ reference variable (declared with @samp{&@var{ref}}) is
5790stored.
c906108c
SS
5791
5792@item -
5793Negative. Defined on integral and floating-point types. Same
5794precedence as @code{++}.
5795
5796@item !
5797Logical negation. Defined on integral types. Same precedence as
5798@code{++}.
5799
5800@item ~
5801Bitwise complement operator. Defined on integral types. Same precedence as
5802@code{++}.
5803
5804
5805@item .@r{, }->
5806Structure member, and pointer-to-structure member. For convenience,
5807@value{GDBN} regards the two as equivalent, choosing whether to dereference a
5808pointer based on the stored type information.
5809Defined on @code{struct} and @code{union} data.
5810
c906108c
SS
5811@item .*@r{, }->*
5812Dereferences of pointers to members.
c906108c
SS
5813
5814@item []
5815Array indexing. @code{@var{a}[@var{i}]} is defined as
5816@code{*(@var{a}+@var{i})}. Same precedence as @code{->}.
5817
5818@item ()
5819Function parameter list. Same precedence as @code{->}.
5820
c906108c 5821@item ::
7a292a7a
SS
5822C++ scope resolution operator. Defined on @code{struct}, @code{union},
5823and @code{class} types.
c906108c
SS
5824
5825@item ::
7a292a7a
SS
5826Doubled colons also represent the @value{GDBN} scope operator
5827(@pxref{Expressions, ,Expressions}). Same precedence as @code{::},
5828above.
c906108c
SS
5829@end table
5830
c906108c
SS
5831If an operator is redefined in the user code, @value{GDBN} usually
5832attempts to invoke the redefined version instead of using the operator's
5833predefined meaning.
c906108c 5834
c906108c
SS
5835@menu
5836* C Constants::
5837@end menu
5838
53a5351d 5839@node C Constants
c906108c 5840@subsubsection C and C++ constants
c906108c
SS
5841
5842@cindex C and C++ constants
c906108c 5843
7a292a7a 5844@value{GDBN} allows you to express the constants of C and C++ in the
c906108c 5845following ways:
c906108c
SS
5846
5847@itemize @bullet
5848@item
5849Integer constants are a sequence of digits. Octal constants are
5850specified by a leading @samp{0} (i.e. zero), and hexadecimal constants by
5851a leading @samp{0x} or @samp{0X}. Constants may also end with a letter
5852@samp{l}, specifying that the constant should be treated as a
5853@code{long} value.
5854
5855@item
5856Floating point constants are a sequence of digits, followed by a decimal
5857point, followed by a sequence of digits, and optionally followed by an
5858exponent. An exponent is of the form:
5859@samp{@w{e@r{[[}+@r{]|}-@r{]}@var{nnn}}}, where @var{nnn} is another
5860sequence of digits. The @samp{+} is optional for positive exponents.
5861
5862@item
5863Enumerated constants consist of enumerated identifiers, or their
5864integral equivalents.
5865
5866@item
5867Character constants are a single character surrounded by single quotes
5868(@code{'}), or a number---the ordinal value of the corresponding character
5869(usually its @sc{ASCII} value). Within quotes, the single character may
5870be represented by a letter or by @dfn{escape sequences}, which are of
5871the form @samp{\@var{nnn}}, where @var{nnn} is the octal representation
5872of the character's ordinal value; or of the form @samp{\@var{x}}, where
5873@samp{@var{x}} is a predefined special character---for example,
5874@samp{\n} for newline.
5875
5876@item
5877String constants are a sequence of character constants surrounded
5878by double quotes (@code{"}).
5879
5880@item
5881Pointer constants are an integral value. You can also write pointers
5882to constants using the C operator @samp{&}.
5883
5884@item
5885Array constants are comma-separated lists surrounded by braces @samp{@{}
5886and @samp{@}}; for example, @samp{@{1,2,3@}} is a three-element array of
5887integers, @samp{@{@{1,2@}, @{3,4@}, @{5,6@}@}} is a three-by-two array,
5888and @samp{@{&"hi", &"there", &"fred"@}} is a three-element array of pointers.
5889@end itemize
5890
c906108c 5891@menu
7a292a7a 5892* C plus plus expressions::
c906108c 5893* C Defaults::
c906108c 5894* C Checks::
c906108c
SS
5895
5896* Debugging C::
5897@end menu
5898
53a5351d 5899@node C plus plus expressions
c906108c 5900@subsubsection C++ expressions
c906108c
SS
5901
5902@cindex expressions in C++
5903@value{GDBN} expression handling can interpret most C++ expressions.
5904
c906108c
SS
5905@cindex C++ support, not in @sc{coff}
5906@cindex @sc{coff} versus C++
5907@cindex C++ and object formats
5908@cindex object formats and C++
5909@cindex a.out and C++
5910@cindex @sc{ecoff} and C++
5911@cindex @sc{xcoff} and C++
5912@cindex @sc{elf}/stabs and C++
5913@cindex @sc{elf}/@sc{dwarf} and C++
5914@c FIXME!! GDB may eventually be able to debug C++ using DWARF; check
5915@c periodically whether this has happened...
5916@quotation
5917@emph{Warning:} @value{GDBN} can only debug C++ code if you use the
5918proper compiler. Typically, C++ debugging depends on the use of
5919additional debugging information in the symbol table, and thus requires
5920special support. In particular, if your compiler generates a.out, MIPS
5921@sc{ecoff}, RS/6000 @sc{xcoff}, or @sc{elf} with stabs extensions to the
5922symbol table, these facilities are all available. (With @sc{gnu} CC,
5923you can use the @samp{-gstabs} option to request stabs debugging
5924extensions explicitly.) Where the object code format is standard
5925@sc{coff} or @sc{dwarf} in @sc{elf}, on the other hand, most of the C++
5926support in @value{GDBN} does @emph{not} work.
5927@end quotation
c906108c
SS
5928
5929@enumerate
5930
5931@cindex member functions
5932@item
5933Member function calls are allowed; you can use expressions like
5934
5935@example
5936count = aml->GetOriginal(x, y)
5937@end example
5938
5939@kindex this
5940@cindex namespace in C++
5941@item
5942While a member function is active (in the selected stack frame), your
5943expressions have the same namespace available as the member function;
5944that is, @value{GDBN} allows implicit references to the class instance
5945pointer @code{this} following the same rules as C++.
5946
c906108c
SS
5947@cindex call overloaded functions
5948@cindex overloaded functions
5949@cindex type conversions in C++
5950@item
5951You can call overloaded functions; @value{GDBN} resolves the function
5952call to the right definition, with some restrictions. GDB does not
5953perform overload resolution involving user-defined type conversions,
5954calls to constructors, or instantiations of templates that do not exist
5955in the program. It also cannot handle ellipsis argument lists or
5956default arguments.
5957
5958It does perform integral conversions and promotions, floating-point
5959promotions, arithmetic conversions, pointer conversions, conversions of
5960class objects to base classes, and standard conversions such as those of
5961functions or arrays to pointers; it requires an exact match on the
5962number of function arguments.
5963
5964Overload resolution is always performed, unless you have specified
5965@code{set overload-resolution off}. @xref{Debugging C plus plus,
5966,@value{GDBN} features for C++}.
5967
5968You must specify@code{set overload-resolution off} in order to use an
5969explicit function signature to call an overloaded function, as in
5970@smallexample
5971p 'foo(char,int)'('x', 13)
5972@end smallexample
5973The @value{GDBN} command-completion facility can simplify this;
5974@pxref{Completion, ,Command completion}.
5975
c906108c
SS
5976@cindex reference declarations
5977@item
5978@value{GDBN} understands variables declared as C++ references; you can use
5979them in expressions just as you do in C++ source---they are automatically
5980dereferenced.
5981
5982In the parameter list shown when @value{GDBN} displays a frame, the values of
5983reference variables are not displayed (unlike other variables); this
5984avoids clutter, since references are often used for large structures.
5985The @emph{address} of a reference variable is always shown, unless
5986you have specified @samp{set print address off}.
5987
5988@item
5989@value{GDBN} supports the C++ name resolution operator @code{::}---your
5990expressions can use it just as expressions in your program do. Since
5991one scope may be defined in another, you can use @code{::} repeatedly if
5992necessary, for example in an expression like
5993@samp{@var{scope1}::@var{scope2}::@var{name}}. @value{GDBN} also allows
5994resolving name scope by reference to source files, in both C and C++
5995debugging (@pxref{Variables, ,Program variables}).
5996@end enumerate
5997
53a5351d
JM
5998In addition, when used with HP's C++ compiler, @value{GDBN} supports
5999calling virtual functions correctly, printing out virtual bases of
6000objects, calling functions in a base subobject, casting objects, and
6001invoking user-defined operators.
c906108c 6002
53a5351d 6003@node C Defaults
c906108c 6004@subsubsection C and C++ defaults
7a292a7a 6005
c906108c
SS
6006@cindex C and C++ defaults
6007
c906108c
SS
6008If you allow @value{GDBN} to set type and range checking automatically, they
6009both default to @code{off} whenever the working language changes to
6010C or C++. This happens regardless of whether you or @value{GDBN}
6011selects the working language.
c906108c
SS
6012
6013If you allow @value{GDBN} to set the language automatically, it
6014recognizes source files whose names end with @file{.c}, @file{.C}, or
6015@file{.cc}, etc, and when @value{GDBN} enters code compiled from one of
6016these files, it sets the working language to C or C++.
6017@xref{Automatically, ,Having @value{GDBN} infer the source language},
6018for further details.
6019
c906108c
SS
6020@c Type checking is (a) primarily motivated by Modula-2, and (b)
6021@c unimplemented. If (b) changes, it might make sense to let this node
6022@c appear even if Mod-2 does not, but meanwhile ignore it. roland 16jul93.
7a292a7a 6023
53a5351d 6024@node C Checks
c906108c 6025@subsubsection C and C++ type and range checks
7a292a7a 6026
c906108c
SS
6027@cindex C and C++ checks
6028
6029By default, when @value{GDBN} parses C or C++ expressions, type checking
6030is not used. However, if you turn type checking on, @value{GDBN}
6031considers two variables type equivalent if:
6032
6033@itemize @bullet
6034@item
6035The two variables are structured and have the same structure, union, or
6036enumerated tag.
6037
6038@item
6039The two variables have the same type name, or types that have been
6040declared equivalent through @code{typedef}.
6041
6042@ignore
6043@c leaving this out because neither J Gilmore nor R Pesch understand it.
6044@c FIXME--beers?
6045@item
6046The two @code{struct}, @code{union}, or @code{enum} variables are
6047declared in the same declaration. (Note: this may not be true for all C
6048compilers.)
6049@end ignore
6050@end itemize
6051
6052Range checking, if turned on, is done on mathematical operations. Array
6053indices are not checked, since they are often used to index a pointer
6054that is not itself an array.
c906108c 6055
53a5351d 6056@node Debugging C
c906108c 6057@subsubsection @value{GDBN} and C
c906108c
SS
6058
6059The @code{set print union} and @code{show print union} commands apply to
6060the @code{union} type. When set to @samp{on}, any @code{union} that is
7a292a7a
SS
6061inside a @code{struct} or @code{class} is also printed. Otherwise, it
6062appears as @samp{@{...@}}.
c906108c
SS
6063
6064The @code{@@} operator aids in the debugging of dynamic arrays, formed
6065with pointers and a memory allocation function. @xref{Expressions,
6066,Expressions}.
6067
c906108c
SS
6068@menu
6069* Debugging C plus plus::
6070@end menu
6071
53a5351d 6072@node Debugging C plus plus
c906108c 6073@subsubsection @value{GDBN} features for C++
c906108c
SS
6074
6075@cindex commands for C++
7a292a7a 6076
c906108c
SS
6077Some @value{GDBN} commands are particularly useful with C++, and some are
6078designed specifically for use with C++. Here is a summary:
6079
6080@table @code
6081@cindex break in overloaded functions
6082@item @r{breakpoint menus}
6083When you want a breakpoint in a function whose name is overloaded,
6084@value{GDBN} breakpoint menus help you specify which function definition
6085you want. @xref{Breakpoint Menus,,Breakpoint menus}.
6086
6087@cindex overloading in C++
6088@item rbreak @var{regex}
6089Setting breakpoints using regular expressions is helpful for setting
6090breakpoints on overloaded functions that are not members of any special
6091classes.
6092@xref{Set Breaks, ,Setting breakpoints}.
6093
6094@cindex C++ exception handling
6095@item catch throw
6096@itemx catch catch
6097Debug C++ exception handling using these commands. @xref{Set
6098Catchpoints, , Setting catchpoints}.
6099
6100@cindex inheritance
6101@item ptype @var{typename}
6102Print inheritance relationships as well as other information for type
6103@var{typename}.
6104@xref{Symbols, ,Examining the Symbol Table}.
6105
6106@cindex C++ symbol display
6107@item set print demangle
6108@itemx show print demangle
6109@itemx set print asm-demangle
6110@itemx show print asm-demangle
6111Control whether C++ symbols display in their source form, both when
6112displaying code as C++ source and when displaying disassemblies.
6113@xref{Print Settings, ,Print settings}.
6114
6115@item set print object
6116@itemx show print object
6117Choose whether to print derived (actual) or declared types of objects.
6118@xref{Print Settings, ,Print settings}.
6119
6120@item set print vtbl
6121@itemx show print vtbl
6122Control the format for printing virtual function tables.
6123@xref{Print Settings, ,Print settings}.
c906108c
SS
6124(The @code{vtbl} commands do not work on programs compiled with the HP
6125ANSI C++ compiler (@code{aCC}).)
6126
6127@kindex set overload-resolution
6128@cindex overloaded functions
6129@item set overload-resolution on
6130Enable overload resolution for C++ expression evaluation. The default
6131is on. For overloaded functions, @value{GDBN} evaluates the arguments
6132and searches for a function whose signature matches the argument types,
7a292a7a 6133using the standard C++ conversion rules (@pxref{C plus plus expressions, ,C++
c906108c
SS
6134expressions} for details). If it cannot find a match, it emits a
6135message.
6136
6137@item set overload-resolution off
6138Disable overload resolution for C++ expression evaluation. For
6139overloaded functions that are not class member functions, @value{GDBN}
6140chooses the first function of the specified name that it finds in the
6141symbol table, whether or not its arguments are of the correct type. For
6142overloaded functions that are class member functions, @value{GDBN}
6143searches for a function whose signature @emph{exactly} matches the
6144argument types.
c906108c
SS
6145
6146@item @r{Overloaded symbol names}
6147You can specify a particular definition of an overloaded symbol, using
6148the same notation that is used to declare such symbols in C++: type
6149@code{@var{symbol}(@var{types})} rather than just @var{symbol}. You can
6150also use the @value{GDBN} command-line word completion facilities to list the
6151available choices, or to finish the type list for you.
6152@xref{Completion,, Command completion}, for details on how to do this.
6153@end table
c906108c 6154
53a5351d 6155@node Modula-2
c906108c 6156@subsection Modula-2
7a292a7a 6157
c906108c
SS
6158@cindex Modula-2
6159
6160The extensions made to @value{GDBN} to support Modula-2 only support
6161output from the @sc{gnu} Modula-2 compiler (which is currently being
6162developed). Other Modula-2 compilers are not currently supported, and
6163attempting to debug executables produced by them is most likely
6164to give an error as @value{GDBN} reads in the executable's symbol
6165table.
6166
6167@cindex expressions in Modula-2
6168@menu
6169* M2 Operators:: Built-in operators
6170* Built-In Func/Proc:: Built-in functions and procedures
6171* M2 Constants:: Modula-2 constants
6172* M2 Defaults:: Default settings for Modula-2
6173* Deviations:: Deviations from standard Modula-2
6174* M2 Checks:: Modula-2 type and range checks
6175* M2 Scope:: The scope operators @code{::} and @code{.}
6176* GDB/M2:: @value{GDBN} and Modula-2
6177@end menu
6178
53a5351d 6179@node M2 Operators
c906108c
SS
6180@subsubsection Operators
6181@cindex Modula-2 operators
6182
6183Operators must be defined on values of specific types. For instance,
6184@code{+} is defined on numbers, but not on structures. Operators are
6185often defined on groups of types. For the purposes of Modula-2, the
6186following definitions hold:
6187
6188@itemize @bullet
6189
6190@item
6191@emph{Integral types} consist of @code{INTEGER}, @code{CARDINAL}, and
6192their subranges.
6193
6194@item
6195@emph{Character types} consist of @code{CHAR} and its subranges.
6196
6197@item
6198@emph{Floating-point types} consist of @code{REAL}.
6199
6200@item
6201@emph{Pointer types} consist of anything declared as @code{POINTER TO
6202@var{type}}.
6203
6204@item
6205@emph{Scalar types} consist of all of the above.
6206
6207@item
6208@emph{Set types} consist of @code{SET} and @code{BITSET} types.
6209
6210@item
6211@emph{Boolean types} consist of @code{BOOLEAN}.
6212@end itemize
6213
6214@noindent
6215The following operators are supported, and appear in order of
6216increasing precedence:
6217
6218@table @code
6219@item ,
6220Function argument or array index separator.
6221
6222@item :=
6223Assignment. The value of @var{var} @code{:=} @var{value} is
6224@var{value}.
6225
6226@item <@r{, }>
6227Less than, greater than on integral, floating-point, or enumerated
6228types.
6229
6230@item <=@r{, }>=
6231Less than, greater than, less than or equal to, greater than or equal to
6232on integral, floating-point and enumerated types, or set inclusion on
6233set types. Same precedence as @code{<}.
6234
6235@item =@r{, }<>@r{, }#
6236Equality and two ways of expressing inequality, valid on scalar types.
6237Same precedence as @code{<}. In @value{GDBN} scripts, only @code{<>} is
6238available for inequality, since @code{#} conflicts with the script
6239comment character.
6240
6241@item IN
6242Set membership. Defined on set types and the types of their members.
6243Same precedence as @code{<}.
6244
6245@item OR
6246Boolean disjunction. Defined on boolean types.
6247
6248@item AND@r{, }&
6249Boolean conjuction. Defined on boolean types.
6250
6251@item @@
6252The @value{GDBN} ``artificial array'' operator (@pxref{Expressions, ,Expressions}).
6253
6254@item +@r{, }-
6255Addition and subtraction on integral and floating-point types, or union
6256and difference on set types.
6257
6258@item *
6259Multiplication on integral and floating-point types, or set intersection
6260on set types.
6261
6262@item /
6263Division on floating-point types, or symmetric set difference on set
6264types. Same precedence as @code{*}.
6265
6266@item DIV@r{, }MOD
6267Integer division and remainder. Defined on integral types. Same
6268precedence as @code{*}.
6269
6270@item -
6271Negative. Defined on @code{INTEGER} and @code{REAL} data.
6272
6273@item ^
6274Pointer dereferencing. Defined on pointer types.
6275
6276@item NOT
6277Boolean negation. Defined on boolean types. Same precedence as
6278@code{^}.
6279
6280@item .
6281@code{RECORD} field selector. Defined on @code{RECORD} data. Same
6282precedence as @code{^}.
6283
6284@item []
6285Array indexing. Defined on @code{ARRAY} data. Same precedence as @code{^}.
6286
6287@item ()
6288Procedure argument list. Defined on @code{PROCEDURE} objects. Same precedence
6289as @code{^}.
6290
6291@item ::@r{, }.
6292@value{GDBN} and Modula-2 scope operators.
6293@end table
6294
6295@quotation
6296@emph{Warning:} Sets and their operations are not yet supported, so @value{GDBN}
6297treats the use of the operator @code{IN}, or the use of operators
6298@code{+}, @code{-}, @code{*}, @code{/}, @code{=}, , @code{<>}, @code{#},
6299@code{<=}, and @code{>=} on sets as an error.
6300@end quotation
6301
6302@cindex Modula-2 built-ins
53a5351d 6303@node Built-In Func/Proc
c906108c
SS
6304@subsubsection Built-in functions and procedures
6305
6306Modula-2 also makes available several built-in procedures and functions.
6307In describing these, the following metavariables are used:
6308
6309@table @var
6310
6311@item a
6312represents an @code{ARRAY} variable.
6313
6314@item c
6315represents a @code{CHAR} constant or variable.
6316
6317@item i
6318represents a variable or constant of integral type.
6319
6320@item m
6321represents an identifier that belongs to a set. Generally used in the
6322same function with the metavariable @var{s}. The type of @var{s} should
6323be @code{SET OF @var{mtype}} (where @var{mtype} is the type of @var{m}).
6324
6325@item n
6326represents a variable or constant of integral or floating-point type.
6327
6328@item r
6329represents a variable or constant of floating-point type.
6330
6331@item t
6332represents a type.
6333
6334@item v
6335represents a variable.
6336
6337@item x
6338represents a variable or constant of one of many types. See the
6339explanation of the function for details.
6340@end table
6341
6342All Modula-2 built-in procedures also return a result, described below.
6343
6344@table @code
6345@item ABS(@var{n})
6346Returns the absolute value of @var{n}.
6347
6348@item CAP(@var{c})
6349If @var{c} is a lower case letter, it returns its upper case
6350equivalent, otherwise it returns its argument
6351
6352@item CHR(@var{i})
6353Returns the character whose ordinal value is @var{i}.
6354
6355@item DEC(@var{v})
6356Decrements the value in the variable @var{v}. Returns the new value.
6357
6358@item DEC(@var{v},@var{i})
6359Decrements the value in the variable @var{v} by @var{i}. Returns the
6360new value.
6361
6362@item EXCL(@var{m},@var{s})
6363Removes the element @var{m} from the set @var{s}. Returns the new
6364set.
6365
6366@item FLOAT(@var{i})
6367Returns the floating point equivalent of the integer @var{i}.
6368
6369@item HIGH(@var{a})
6370Returns the index of the last member of @var{a}.
6371
6372@item INC(@var{v})
6373Increments the value in the variable @var{v}. Returns the new value.
6374
6375@item INC(@var{v},@var{i})
6376Increments the value in the variable @var{v} by @var{i}. Returns the
6377new value.
6378
6379@item INCL(@var{m},@var{s})
6380Adds the element @var{m} to the set @var{s} if it is not already
6381there. Returns the new set.
6382
6383@item MAX(@var{t})
6384Returns the maximum value of the type @var{t}.
6385
6386@item MIN(@var{t})
6387Returns the minimum value of the type @var{t}.
6388
6389@item ODD(@var{i})
6390Returns boolean TRUE if @var{i} is an odd number.
6391
6392@item ORD(@var{x})
6393Returns the ordinal value of its argument. For example, the ordinal
6394value of a character is its ASCII value (on machines supporting the
6395ASCII character set). @var{x} must be of an ordered type, which include
6396integral, character and enumerated types.
6397
6398@item SIZE(@var{x})
6399Returns the size of its argument. @var{x} can be a variable or a type.
6400
6401@item TRUNC(@var{r})
6402Returns the integral part of @var{r}.
6403
6404@item VAL(@var{t},@var{i})
6405Returns the member of the type @var{t} whose ordinal value is @var{i}.
6406@end table
6407
6408@quotation
6409@emph{Warning:} Sets and their operations are not yet supported, so
6410@value{GDBN} treats the use of procedures @code{INCL} and @code{EXCL} as
6411an error.
6412@end quotation
6413
6414@cindex Modula-2 constants
53a5351d 6415@node M2 Constants
c906108c
SS
6416@subsubsection Constants
6417
6418@value{GDBN} allows you to express the constants of Modula-2 in the following
6419ways:
6420
6421@itemize @bullet
6422
6423@item
6424Integer constants are simply a sequence of digits. When used in an
6425expression, a constant is interpreted to be type-compatible with the
6426rest of the expression. Hexadecimal integers are specified by a
6427trailing @samp{H}, and octal integers by a trailing @samp{B}.
6428
6429@item
6430Floating point constants appear as a sequence of digits, followed by a
6431decimal point and another sequence of digits. An optional exponent can
6432then be specified, in the form @samp{E@r{[}+@r{|}-@r{]}@var{nnn}}, where
6433@samp{@r{[}+@r{|}-@r{]}@var{nnn}} is the desired exponent. All of the
6434digits of the floating point constant must be valid decimal (base 10)
6435digits.
6436
6437@item
6438Character constants consist of a single character enclosed by a pair of
6439like quotes, either single (@code{'}) or double (@code{"}). They may
6440also be expressed by their ordinal value (their ASCII value, usually)
6441followed by a @samp{C}.
6442
6443@item
6444String constants consist of a sequence of characters enclosed by a
6445pair of like quotes, either single (@code{'}) or double (@code{"}).
6446Escape sequences in the style of C are also allowed. @xref{C
6447Constants, ,C and C++ constants}, for a brief explanation of escape
6448sequences.
6449
6450@item
6451Enumerated constants consist of an enumerated identifier.
6452
6453@item
6454Boolean constants consist of the identifiers @code{TRUE} and
6455@code{FALSE}.
6456
6457@item
6458Pointer constants consist of integral values only.
6459
6460@item
6461Set constants are not yet supported.
6462@end itemize
6463
53a5351d 6464@node M2 Defaults
c906108c
SS
6465@subsubsection Modula-2 defaults
6466@cindex Modula-2 defaults
6467
6468If type and range checking are set automatically by @value{GDBN}, they
6469both default to @code{on} whenever the working language changes to
6470Modula-2. This happens regardless of whether you, or @value{GDBN},
6471selected the working language.
6472
6473If you allow @value{GDBN} to set the language automatically, then entering
6474code compiled from a file whose name ends with @file{.mod} sets the
6475working language to Modula-2. @xref{Automatically, ,Having @value{GDBN} set
6476the language automatically}, for further details.
6477
53a5351d 6478@node Deviations
c906108c
SS
6479@subsubsection Deviations from standard Modula-2
6480@cindex Modula-2, deviations from
6481
6482A few changes have been made to make Modula-2 programs easier to debug.
6483This is done primarily via loosening its type strictness:
6484
6485@itemize @bullet
6486@item
6487Unlike in standard Modula-2, pointer constants can be formed by
6488integers. This allows you to modify pointer variables during
6489debugging. (In standard Modula-2, the actual address contained in a
6490pointer variable is hidden from you; it can only be modified
6491through direct assignment to another pointer variable or expression that
6492returned a pointer.)
6493
6494@item
6495C escape sequences can be used in strings and characters to represent
6496non-printable characters. @value{GDBN} prints out strings with these
6497escape sequences embedded. Single non-printable characters are
6498printed using the @samp{CHR(@var{nnn})} format.
6499
6500@item
6501The assignment operator (@code{:=}) returns the value of its right-hand
6502argument.
6503
6504@item
6505All built-in procedures both modify @emph{and} return their argument.
6506@end itemize
6507
53a5351d 6508@node M2 Checks
c906108c
SS
6509@subsubsection Modula-2 type and range checks
6510@cindex Modula-2 checks
6511
6512@quotation
6513@emph{Warning:} in this release, @value{GDBN} does not yet perform type or
6514range checking.
6515@end quotation
6516@c FIXME remove warning when type/range checks added
6517
6518@value{GDBN} considers two Modula-2 variables type equivalent if:
6519
6520@itemize @bullet
6521@item
6522They are of types that have been declared equivalent via a @code{TYPE
6523@var{t1} = @var{t2}} statement
6524
6525@item
6526They have been declared on the same line. (Note: This is true of the
6527@sc{gnu} Modula-2 compiler, but it may not be true of other compilers.)
6528@end itemize
6529
6530As long as type checking is enabled, any attempt to combine variables
6531whose types are not equivalent is an error.
6532
6533Range checking is done on all mathematical operations, assignment, array
6534index bounds, and all built-in functions and procedures.
6535
53a5351d 6536@node M2 Scope
c906108c
SS
6537@subsubsection The scope operators @code{::} and @code{.}
6538@cindex scope
6539@kindex .
6540@cindex colon, doubled as scope operator
6541@ifinfo
6542@kindex colon-colon
6543@c Info cannot handle :: but TeX can.
6544@end ifinfo
6545@iftex
6546@kindex ::
6547@end iftex
6548
6549There are a few subtle differences between the Modula-2 scope operator
6550(@code{.}) and the @value{GDBN} scope operator (@code{::}). The two have
6551similar syntax:
6552
6553@example
6554
6555@var{module} . @var{id}
6556@var{scope} :: @var{id}
6557@end example
6558
6559@noindent
6560where @var{scope} is the name of a module or a procedure,
6561@var{module} the name of a module, and @var{id} is any declared
6562identifier within your program, except another module.
6563
6564Using the @code{::} operator makes @value{GDBN} search the scope
6565specified by @var{scope} for the identifier @var{id}. If it is not
6566found in the specified scope, then @value{GDBN} searches all scopes
6567enclosing the one specified by @var{scope}.
6568
6569Using the @code{.} operator makes @value{GDBN} search the current scope for
6570the identifier specified by @var{id} that was imported from the
6571definition module specified by @var{module}. With this operator, it is
6572an error if the identifier @var{id} was not imported from definition
6573module @var{module}, or if @var{id} is not an identifier in
6574@var{module}.
6575
53a5351d 6576@node GDB/M2
c906108c
SS
6577@subsubsection @value{GDBN} and Modula-2
6578
6579Some @value{GDBN} commands have little use when debugging Modula-2 programs.
6580Five subcommands of @code{set print} and @code{show print} apply
6581specifically to C and C++: @samp{vtbl}, @samp{demangle},
6582@samp{asm-demangle}, @samp{object}, and @samp{union}. The first four
6583apply to C++, and the last to the C @code{union} type, which has no direct
6584analogue in Modula-2.
6585
6586The @code{@@} operator (@pxref{Expressions, ,Expressions}), while available
6587while using any language, is not useful with Modula-2. Its
6588intent is to aid the debugging of @dfn{dynamic arrays}, which cannot be
6589created in Modula-2 as they can in C or C++. However, because an
6590address can be specified by an integral constant, the construct
6591@samp{@{@var{type}@}@var{adrexp}} is still useful. (@pxref{Expressions, ,Expressions})
6592
6593@cindex @code{#} in Modula-2
6594In @value{GDBN} scripts, the Modula-2 inequality operator @code{#} is
6595interpreted as the beginning of a comment. Use @code{<>} instead.
c906108c 6596
53a5351d 6597@node Chill
cce74817
JM
6598@subsection Chill
6599
6600The extensions made to @value{GDBN} to support Chill only support output
6601from the GNU Chill compiler. Other Chill compilers are not currently
6602supported, and attempting to debug executables produced by them is most
6603likely to give an error as @value{GDBN} reads in the executable's symbol
6604table.
6605
6606This section covers the following Chill related topics and the features
6607of @value{GDBN} which support these topics.
6608
6609@menu
6610* How modes are displayed:: How modes are displayed
6611* Locations:: Locations and their accesses
6612* Values and their Operations:: Values and their Operations
53a5351d
JM
6613* Chill type and range checks::
6614* Chill defaults::
cce74817
JM
6615@end menu
6616
6617@node How modes are displayed
6618@subsubsection How modes are displayed
6619
6620The Chill Datatype- (Mode) support of @value{GDBN} is directly related
6621with the functionality of the GNU Chill compiler, and therefore deviates
6622slightly from the standard specification of the Chill language. The
6623provided modes are:
6624@table @code
6625@item @r{@emph{Discrete modes:}}
6626@itemize @bullet
6627@item
6628@emph{Integer Modes} which are predefined by @code{BYTE, UBYTE, INT,
6629UINT, LONG, ULONG},
6630@item
6631@emph{Boolean Mode} which is predefined by @code{BOOL},
6632@item
6633@emph{Character Mode} which is predefined by @code{CHAR},
6634@item
6635@emph{Set Mode} which is displayed by the keyword @code{SET}.
6636@smallexample
6637(@value{GDBP}) ptype x
6638type = SET (karli = 10, susi = 20, fritzi = 100)
6639@end smallexample
6640If the type is an unnumbered set the set element values are omitted.
6641@item
6642@emph{Range Mode} which is displayed by @code{type = <basemode>
6643(<lower bound> : <upper bound>)}, where @code{<lower bound>, <upper
6644bound>} can be of any discrete literal expression (e.g. set element
6645names).
6646@end itemize
6647
6648@item @r{@emph{Powerset Mode:}}
6649A Powerset Mode is displayed by the keyword @code{POWERSET} followed by
6650the member mode of the powerset. The member mode can be any discrete mode.
6651@smallexample
6652(@value{GDBP}) ptype x
6653type = POWERSET SET (egon, hugo, otto)
6654@end smallexample
6655
6656@item @r{@emph{Reference Modes:}}
6657@itemize @bullet
6658@item
6659@emph{Bound Reference Mode} which is diplayed by the keyword @code{REF}
6660followed by the mode name to which the reference is bound.
6661@item
6662@emph{Free Reference Mode} which is displayed by the keyword @code{PTR}.
6663@end itemize
6664
6665@item @r{@emph{Procedure mode}}
6666The procedure mode is displayed by @code{type = PROC(<parameter list>)
6667<return mode> EXCEPTIONS (<exception list>)}. The @code{<parameter
6668list>} is a list of the parameter modes. @code{<return mode>} indicates
6669the mode of the result of the procedure if any. The exceptionlist lists
6670all possible exceptions which can be raised by the procedure.
6671
6672@ignore
6673@item @r{@emph{Instance mode}}
6674The instance mode is represented by a structure, which has a static
6675type, and is therefore not really of interest.
6676@end ignore
6677
6678@item @r{@emph{Synchronization Modes:}}
6679@itemize @bullet
6680@item
6681@emph{Event Mode} which is displayed by @code{EVENT (<event length>)},
6682where @code{(<event length>)} is optional.
6683@item
6684@emph{Buffer Mode} which is displayed by @code{BUFFER (<buffer length>)
6685<buffer element mode>}, where @code{(<buffer length>)} is optional.
6686@end itemize
6687
6688@item @r{@emph{Timing Modes:}}
6689@itemize @bullet
6690@item
6691@emph{Duration Mode} which is predefined by @code{DURATION}
6692@item
6693@emph{Absolute Time Mode} which is predefined by @code{TIME}
6694@end itemize
6695
6696@item @r{@emph{Real Modes:}}
6697Real Modes are predefined with @code{REAL} and @code{LONG_REAL}.
6698
6699@item @r{@emph{String Modes:}}
6700@itemize @bullet
6701@item
6702@emph{Character String Mode} which is displayed by @code{CHARS(<string
6703length>)}, followed by the keyword @code{VARYING} if the String Mode is
6704a varying mode
6705@item
6706@emph{Bit String Mode} which is displayed by @code{BOOLS(<string
6707length>)}.
6708@end itemize
6709
6710@item @r{@emph{Array Mode:}}
6711The Array Mode is displayed by the keyword @code{ARRAY(<range>)}
6712followed by the element mode (which may in turn be an array mode).
6713@smallexample
6714(@value{GDBP}) ptype x
6715type = ARRAY (1:42)
6716 ARRAY (1:20)
6717 SET (karli = 10, susi = 20, fritzi = 100)
6718@end smallexample
6719
6720@item @r{@emph{Structure Mode}}
6721The Structure mode is displayed by the keyword @code{STRUCT(<field
6722list>)}. The @code{<field list>} consists of names and modes of fields
6723of the structure. Variant structures have the keyword @code{CASE <field>
6724OF <variant fields> ESAC} in their field list. Since the current version
6725of the GNU Chill compiler doesn't implement tag processing (no runtime
6726checks of variant fields, and therefore no debugging info), the output
6727always displays all variant fields.
6728@smallexample
6729(@value{GDBP}) ptype str
6730type = STRUCT (
6731 as x,
6732 bs x,
6733 CASE bs OF
6734 (karli):
6735 cs a
6736 (ott):
6737 ds x
6738 ESAC
6739)
6740@end smallexample
6741@end table
6742
6743@node Locations
6744@subsubsection Locations and their accesses
6745
6746A location in Chill is an object which can contain values.
6747
6748A value of a location is generally accessed by the (declared) name of
6749the location. The output conforms to the specification of values in
53a5351d 6750Chill programs. How values are specified
cce74817
JM
6751is the topic of the next section.
6752
6753The pseudo-location @code{RESULT} (or @code{result}) can be used to
6754display or change the result of a currently-active procedure:
6755@smallexample
6756set result := EXPR
6757@end smallexample
6758- does the same as the Chill action @code{RESULT EXPR} (which
6759is not available in gdb).
6760
6761Values of reference mode locations are printed by @code{PTR(<hex
6762value>)} in case of a free reference mode, and by @code{(REF <reference
6763mode>) (<hex-value>)} in case of a bound reference. @code{<hex value>}
6764represents the address where the reference points to. To access the
6765value of the location referenced by the pointer, use the dereference
6766operator `@code{->}'.
6767
6768Values of procedure mode locations are displayed by @code{@{ PROC
6769(<argument modes> ) <return mode> @} <address> <name of procedure
6770location>}. @code{<argument modes>} is a list of modes according to the
6771parameter specification of the procedure and @code{<address>} shows the
6772address of the entry point.
6773
6774@ignore
6775Locations of instance modes are displayed just like a structure with two
6776fields specifying the @emph{process type} and the @emph{copy number} of
6777the investigated instance location@footnote{This comes from the current
6778implementation of instances. They are implemented as a structure (no
6779na). The output should be something like @code{[<name of the process>;
6780<instance number>]}.}. The field names are @code{__proc_type} and
6781@code{__proc_copy}.
6782
6783Locations of synchronization modes are displayed like a structure with
6784the field name @code{__event_data} in case of a event mode location, and
6785like a structure with the field @code{__buffer_data} in case of a buffer
6786mode location (refer to previous paragraph).
6787
6788Structure Mode locations are printed by @code{[.<field name>: <value>,
6789...]}. The @code{<field name>} corresponds to the structure mode
6790definition and the layout of @code{<value>} varies depending of the mode
6791of the field. If the investigated structure mode location is of variant
6792structure mode the variant parts of the structure are enclosed in curled
6793braces (`@code{@{@}}'). Fields enclosed by `@code{@{,@}}' are residing
6794on the same memory location and represent the current values of the
6795memory location in their specific modes. Since no tag processing is done
6796all variants are displayed. A variant field is printed by
6797@code{(<variant name>) = .<field name>: <value>}. (who implements the
6798stuff ???)
6799@smallexample
6800(@value{GDBP}) print str1 $4 = [.as: 0, .bs: karli, .<TAG>: { (karli) =
6801[.cs: []], (susi) = [.ds: susi]}]
6802@end smallexample
6803@end ignore
6804
6805Substructures of string mode-, array mode- or structure mode-values
6806(e.g. array slices, fields of structure locations) are accessed using
6807certain operations which are descibed in the next chapter.
6808
6809A location value may be interpreted as having a different mode using the
6810location conversion. This mode conversion is written as @code{<mode
6811name>(<location>)}. The user has to consider that the sizes of the modes
6812have to be equal otherwise an error message occurs. Further no range
6813checking of the location against the destination mode is performed and
6814therefore the result can be quite confusing.
6815@smallexample
6816(@value{GDBP}) print int (s(3 up 4)) XXX TO be filled in !! XXX
6817@end smallexample
6818
6819@node Values and their Operations
6820@subsubsection Values and their Operations
6821
6822Values are used to alter locations, to investigate complex structures in
6823more detail or to filter relevant information out of a large amount of
6824data. There are several (mode dependent) operations defined which enable
6825such investigations. These operations are not only applicable to
6826constant values but also to locations, which can become quite useful
6827when debugging complex structures. During parsing the command line
6828(e.g. evaluating an expression) @value{GDBN} treats location names as
6829the values behind these locations.
6830
6831This subchapters describes how values have to be specified and which
6832operations are legal to be used with such values.
6833
6834@table @code
6835@item Literal Values
6836Literal values are specified in the same manner as in GNU Chill programs.
6837For detailed specification refer to the GNU Chill implementation Manual
6838chapter 1.5.
6839
6840@ignore
6841@itemize @bullet
6842@item
6843@emph{Integer Literals} are specified in the same manner as in Chill
6844programs (refer z200/88 chpt 5.2.4.2)
6845@item
6846@emph{Boolean Literals} are defined by @code{TRUE} and @code{FALSE}.
6847@item
6848@emph{Character Literals} are defined by @code{'<character>'}. (e.g.
6849@code{'M'})
6850@item
6851@emph{Set Literals} are defined by a name which was specified in a set
6852mode. The value delivered by a Set Literal is the set value. This is
6853comparable to an enumaration in C/C++ language.
6854@item
6855@emph{Emptiness Literal} is predefined by @code{NULL}. The value of the
6856emptiness literal delivers either the empty reference value, the empty
6857procedure value or the empty instance value.
6858
6859@item
6860@emph{Character String Literals} are defined by a sequence of characters
6861enclosed in single- or double quotes. If a single- or double quote has
6862to be part of the string literal it has to be stuffed (specified twice).
6863@item
6864@emph{Bitstring Literals} are specified in the same manner as in Chill
6865programs (refer z200/88 chpt 5.2.4.8).
6866@item
6867@emph{Floating point literals} are specified in the same manner as in
6868(gnu-)Chill programs (refer GNU Chill implementation Manual chapter 1.5).
6869@end itemize
6870@end ignore
6871
6872@item Tuple Values
6873A tuple is specified by @code{<mode name>[<tuple>]}, where @code{<mode
6874name>} can be omitted if the mode of the tuple is unambigous. This
6875unambiguity is derived from the context of a evaluated expression.
6876@code{<tuple>} can be one of the following:
6877@itemize @bullet
6878@item @emph{Powerset Tuple}
6879@item @emph{Array Tuple}
6880@item @emph{Structure Tuple}
6881Powerset tuples, array tuples and structure tuples are specified in the
6882same manner as in Chill programs refer z200/88 chpt 5.2.5.
6883@end itemize
6884
6885@item String Element Value
6886A string element value is specified by @code{<string value>(<index>)},
6887where @code{<index>} is a integer expression. It delivers a character
6888value which is equivalent to the character indexed by @code{<index>} in
6889the string.
6890
6891@item String Slice Value
6892A string slice value is specified by @code{<string value>(<slice
6893spec>)}, where @code{<slice spec>} can be either a range of integer
6894expressions or specified by @code{<start expr> up <size>}.
6895@code{<size>} denotes the number of elements which the slice contains.
6896The delivered value is a string value, which is part of the specified
6897string.
6898
6899@item Array Element Values
6900An array element value is specified by @code{<array value>(<expr>)} and
6901delivers a array element value of the mode of the specified array.
6902
6903@item Array Slice Values
6904An array slice is specified by @code{<array value>(<slice spec>)}, where
6905@code{<slice spec>} can be either a range specified by expressions or by
6906@code{<start expr> up <size>}. @code{<size>} denotes the number of
6907arrayelements the slice contains. The delivered value is an array value
6908which is part of the specified array.
6909
6910@item Structure Field Values
6911A structure field value is derived by @code{<structure value>.<field
6912name>}, where @code{<field name>} indcates the name of a field specified
6913in the mode definition of the structure. The mode of the delivered value
6914corresponds to this mode definition in the structure definition.
6915
6916@item Procedure Call Value
6917The procedure call value is derived from the return value of the
6918procedure@footnote{If a procedure call is used for instance in an
6919expression, then this procedure is called with all its side
6920effects. This can lead to confusing results if used carelessly.}.
6921
6922Values of duration mode locations are represented by ULONG literals.
6923
6924Values of time mode locations are represented by TIME(<secs>:<nsecs>).
6925
6926@ignore
6927This is not implemented yet:
6928@item Built-in Value
6929@noindent
6930The following built in functions are provided:
6931@table @code
6932@item @code{ADDR()}
6933@item @code{NUM()}
6934@item @code{PRED()}
6935@item @code{SUCC()}
6936@item @code{ABS()}
6937@item @code{CARD()}
6938@item @code{MAX()}
6939@item @code{MIN()}
6940@item @code{SIZE()}
6941@item @code{UPPER()}
6942@item @code{LOWER()}
6943@item @code{LENGTH()}
6944@item @code{SIN()}
6945@item @code{COS()}
6946@item @code{TAN()}
6947@item @code{ARCSIN()}
6948@item @code{ARCCOS()}
6949@item @code{ARCTAN()}
6950@item @code{EXP()}
6951@item @code{LN()}
6952@item @code{LOG()}
6953@item @code{SQRT()}
6954@end table
6955
6956For a detailed description refer to the GNU Chill implementation manual
6957chapter 1.6.
6958@end ignore
6959
6960@item Zero-adic Operator Value
6961The zero-adic operator value is derived from the instance value for the
6962current active process.
6963
6964@item Expression Values
6965The value delivered by an expression is the result of the evaluation of
6966the specified expression. If there are error conditions (mode
6967incompatibility, etc.) the evaluation of expressions is aborted with a
6968corresponding error message. Expressions may be paranthesised which
6969causes the evaluation of this expression before any other expression
6970which uses the result of the paranthesised expression. The following
6971operators are supported by @value{GDBN}:
6972@table @code
6973@item @code{OR, ORIF, XOR}
6974@item @code{AND, ANDIF}
6975@item @code{NOT}
6976Logical operators defined over operands of boolean mode.
6977@item @code{=, /=}
6978Equality and inequality operators defined over all modes.
6979@item @code{>, >=}
6980@item @code{<, <=}
6981Relational operators defined over predefined modes.
6982@item @code{+, -}
6983@item @code{*, /, MOD, REM}
6984Arithmetic operators defined over predefined modes.
6985@item @code{-}
6986Change sign operator.
6987@item @code{//}
6988String concatenation operator.
6989@item @code{()}
6990String repetition operator.
6991@item @code{->}
6992Referenced location operator which can be used either to take the
6993address of a location (@code{->loc}), or to dereference a reference
6994location (@code{loc->}).
6995@item @code{OR, XOR}
6996@item @code{AND}
6997@item @code{NOT}
6998Powerset and bitstring operators.
6999@item @code{>, >=}
7000@item @code{<, <=}
7001Powerset inclusion operators.
7002@item @code{IN}
7003Membership operator.
7004@end table
7005@end table
7006
53a5351d 7007@node Chill type and range checks
cce74817
JM
7008@subsubsection Chill type and range checks
7009
7010@value{GDBN} considers two Chill variables mode equivalent if the sizes
7011of the two modes are equal. This rule applies recursively to more
7012complex datatypes which means that complex modes are treated
7013eqivalent if all element modes (which also can be complex modes like
7014structures, arrays, etc.) have the same size.
7015
7016Range checking is done on all mathematical operations, assignment, array
7017index bounds and all built in procedures.
7018
7019Strong type checks are forced using the @value{GDBN} command @code{set
7020check strong}. This enforces strong type and range checks on all
7021operations where Chill constructs are used (expressions, built in
7022functions, etc.) in respect to the semantics as defined in the z.200
7023language specification.
7024
7025@noindent
7026All checks can be disabled by the @value{GDBN} command @code{set check
7027off}.
7028
7029@ignore
53a5351d 7030@c Deviations from the Chill Standard Z200/88
cce74817
JM
7031see last paragraph ?
7032@end ignore
7033
53a5351d 7034@node Chill defaults
cce74817
JM
7035@subsubsection Chill defaults
7036
7037If type and range checking are set automatically by @value{GDBN}, they
7038both default to @code{on} whenever the working language changes to
7039Chill. This happens regardless of whether you, or @value{GDBN},
7040selected the working language.
7041
7042If you allow @value{GDBN} to set the language automatically, then entering
7043code compiled from a file whose name ends with @file{.ch} sets the
7044working language to Chill. @xref{Automatically, ,Having @value{GDBN} set
7045the language automatically}, for further details.
7046
53a5351d 7047@node Symbols
c906108c
SS
7048@chapter Examining the Symbol Table
7049
7050The commands described in this section allow you to inquire about the
7051symbols (names of variables, functions and types) defined in your
7052program. This information is inherent in the text of your program and
7053does not change as your program executes. @value{GDBN} finds it in your
7054program's symbol table, in the file indicated when you started @value{GDBN}
7055(@pxref{File Options, ,Choosing files}), or by one of the
7056file-management commands (@pxref{Files, ,Commands to specify files}).
7057
7058@cindex symbol names
7059@cindex names of symbols
7060@cindex quoting names
7061Occasionally, you may need to refer to symbols that contain unusual
7062characters, which @value{GDBN} ordinarily treats as word delimiters. The
7063most frequent case is in referring to static variables in other
7064source files (@pxref{Variables,,Program variables}). File names
7065are recorded in object files as debugging symbols, but @value{GDBN} would
7066ordinarily parse a typical file name, like @file{foo.c}, as the three words
7067@samp{foo} @samp{.} @samp{c}. To allow @value{GDBN} to recognize
7068@samp{foo.c} as a single symbol, enclose it in single quotes; for example,
7069
7070@example
7071p 'foo.c'::x
7072@end example
7073
7074@noindent
7075looks up the value of @code{x} in the scope of the file @file{foo.c}.
7076
7077@table @code
7078@kindex info address
7079@item info address @var{symbol}
7080Describe where the data for @var{symbol} is stored. For a register
7081variable, this says which register it is kept in. For a non-register
7082local variable, this prints the stack-frame offset at which the variable
7083is always stored.
7084
7085Note the contrast with @samp{print &@var{symbol}}, which does not work
7086at all for a register variable, and for a stack local variable prints
7087the exact address of the current instantiation of the variable.
7088
7089@kindex whatis
7090@item whatis @var{exp}
7091Print the data type of expression @var{exp}. @var{exp} is not
7092actually evaluated, and any side-effecting operations (such as
7093assignments or function calls) inside it do not take place.
7094@xref{Expressions, ,Expressions}.
7095
7096@item whatis
7097Print the data type of @code{$}, the last value in the value history.
7098
7099@kindex ptype
7100@item ptype @var{typename}
7101Print a description of data type @var{typename}. @var{typename} may be
7a292a7a
SS
7102the name of a type, or for C code it may have the form @samp{class
7103@var{class-name}}, @samp{struct @var{struct-tag}}, @samp{union
7104@var{union-tag}} or @samp{enum @var{enum-tag}}.
c906108c
SS
7105
7106@item ptype @var{exp}
7107@itemx ptype
7108Print a description of the type of expression @var{exp}. @code{ptype}
7109differs from @code{whatis} by printing a detailed description, instead
7110of just the name of the type.
7111
7112For example, for this variable declaration:
7113
7114@example
7115struct complex @{double real; double imag;@} v;
7116@end example
7117
7118@noindent
7119the two commands give this output:
7120
7121@example
7122@group
7123(@value{GDBP}) whatis v
7124type = struct complex
7125(@value{GDBP}) ptype v
7126type = struct complex @{
7127 double real;
7128 double imag;
7129@}
7130@end group
7131@end example
7132
7133@noindent
7134As with @code{whatis}, using @code{ptype} without an argument refers to
7135the type of @code{$}, the last value in the value history.
7136
7137@kindex info types
7138@item info types @var{regexp}
7139@itemx info types
7140Print a brief description of all types whose name matches @var{regexp}
7141(or all types in your program, if you supply no argument). Each
7142complete typename is matched as though it were a complete line; thus,
7143@samp{i type value} gives information on all types in your program whose
7144name includes the string @code{value}, but @samp{i type ^value$} gives
7145information only on types whose complete name is @code{value}.
7146
7147This command differs from @code{ptype} in two ways: first, like
7148@code{whatis}, it does not print a detailed description; second, it
7149lists all source files where a type is defined.
7150
7151@kindex info source
7152@item info source
7153Show the name of the current source file---that is, the source file for
7154the function containing the current point of execution---and the language
7155it was written in.
7156
7157@kindex info sources
7158@item info sources
7159Print the names of all source files in your program for which there is
7160debugging information, organized into two lists: files whose symbols
7161have already been read, and files whose symbols will be read when needed.
7162
7163@kindex info functions
7164@item info functions
7165Print the names and data types of all defined functions.
7166
7167@item info functions @var{regexp}
7168Print the names and data types of all defined functions
7169whose names contain a match for regular expression @var{regexp}.
7170Thus, @samp{info fun step} finds all functions whose names
7171include @code{step}; @samp{info fun ^step} finds those whose names
7172start with @code{step}.
7173
7174@kindex info variables
7175@item info variables
7176Print the names and data types of all variables that are declared
7177outside of functions (i.e., excluding local variables).
7178
7179@item info variables @var{regexp}
7180Print the names and data types of all variables (except for local
7181variables) whose names contain a match for regular expression
7182@var{regexp}.
7183
7184@ignore
7185This was never implemented.
7186@kindex info methods
7187@item info methods
7188@itemx info methods @var{regexp}
7189The @code{info methods} command permits the user to examine all defined
7190methods within C++ program, or (with the @var{regexp} argument) a
7191specific set of methods found in the various C++ classes. Many
7192C++ classes provide a large number of methods. Thus, the output
7193from the @code{ptype} command can be overwhelming and hard to use. The
7194@code{info-methods} command filters the methods, printing only those
7195which match the regular-expression @var{regexp}.
7196@end ignore
7197
c906108c
SS
7198@cindex reloading symbols
7199Some systems allow individual object files that make up your program to
7a292a7a
SS
7200be replaced without stopping and restarting your program. For example,
7201in VxWorks you can simply recompile a defective object file and keep on
7202running. If you are running on one of these systems, you can allow
7203@value{GDBN} to reload the symbols for automatically relinked modules:
c906108c
SS
7204
7205@table @code
7206@kindex set symbol-reloading
7207@item set symbol-reloading on
7208Replace symbol definitions for the corresponding source file when an
7209object file with a particular name is seen again.
7210
7211@item set symbol-reloading off
7212Do not replace symbol definitions when re-encountering object files of
7213the same name. This is the default state; if you are not running on a
7214system that permits automatically relinking modules, you should leave
7215@code{symbol-reloading} off, since otherwise @value{GDBN} may discard symbols
7216when linking large programs, that may contain several modules (from
7217different directories or libraries) with the same name.
7218
7219@kindex show symbol-reloading
7220@item show symbol-reloading
7221Show the current @code{on} or @code{off} setting.
7222@end table
c906108c 7223
c906108c
SS
7224@kindex set opaque-type-resolution
7225@item set opaque-type-resolution on
7226Tell @value{GDBN} to resolve opaque types. An opaque type is a type
7227declared as a pointer to a @code{struct}, @code{class}, or
7228@code{union}---for example, @code{struct MyType *}---that is used in one
7229source file although the full declaration of @code{struct MyType} is in
7230another source file. The default is on.
7231
7232A change in the setting of this subcommand will not take effect until
7233the next time symbols for a file are loaded.
7234
7235@item set opaque-type-resolution off
7236Tell @value{GDBN} not to resolve opaque types. In this case, the type
7237is printed as follows:
7238@smallexample
7239@{<no data fields>@}
7240@end smallexample
7241
7242@kindex show opaque-type-resolution
7243@item show opaque-type-resolution
7244Show whether opaque types are resolved or not.
c906108c
SS
7245
7246@kindex maint print symbols
7247@cindex symbol dump
7248@kindex maint print psymbols
7249@cindex partial symbol dump
7250@item maint print symbols @var{filename}
7251@itemx maint print psymbols @var{filename}
7252@itemx maint print msymbols @var{filename}
7253Write a dump of debugging symbol data into the file @var{filename}.
7254These commands are used to debug the @value{GDBN} symbol-reading code. Only
7255symbols with debugging data are included. If you use @samp{maint print
7256symbols}, @value{GDBN} includes all the symbols for which it has already
7257collected full details: that is, @var{filename} reflects symbols for
7258only those files whose symbols @value{GDBN} has read. You can use the
7259command @code{info sources} to find out which files these are. If you
7260use @samp{maint print psymbols} instead, the dump shows information about
7261symbols that @value{GDBN} only knows partially---that is, symbols defined in
7262files that @value{GDBN} has skimmed, but not yet read completely. Finally,
7263@samp{maint print msymbols} dumps just the minimal symbol information
7264required for each object file from which @value{GDBN} has read some symbols.
7265@xref{Files, ,Commands to specify files}, for a discussion of how
7266@value{GDBN} reads symbols (in the description of @code{symbol-file}).
7267@end table
7268
53a5351d 7269@node Altering
c906108c
SS
7270@chapter Altering Execution
7271
7272Once you think you have found an error in your program, you might want to
7273find out for certain whether correcting the apparent error would lead to
7274correct results in the rest of the run. You can find the answer by
7275experiment, using the @value{GDBN} features for altering execution of the
7276program.
7277
7278For example, you can store new values into variables or memory
7a292a7a
SS
7279locations, give your program a signal, restart it at a different
7280address, or even return prematurely from a function.
c906108c
SS
7281
7282@menu
7283* Assignment:: Assignment to variables
7284* Jumping:: Continuing at a different address
c906108c 7285* Signaling:: Giving your program a signal
c906108c
SS
7286* Returning:: Returning from a function
7287* Calling:: Calling your program's functions
7288* Patching:: Patching your program
7289@end menu
7290
53a5351d 7291@node Assignment
c906108c
SS
7292@section Assignment to variables
7293
7294@cindex assignment
7295@cindex setting variables
7296To alter the value of a variable, evaluate an assignment expression.
7297@xref{Expressions, ,Expressions}. For example,
7298
7299@example
7300print x=4
7301@end example
7302
7303@noindent
7304stores the value 4 into the variable @code{x}, and then prints the
7305value of the assignment expression (which is 4).
c906108c
SS
7306@xref{Languages, ,Using @value{GDBN} with Different Languages}, for more
7307information on operators in supported languages.
c906108c
SS
7308
7309@kindex set variable
7310@cindex variables, setting
7311If you are not interested in seeing the value of the assignment, use the
7312@code{set} command instead of the @code{print} command. @code{set} is
7313really the same as @code{print} except that the expression's value is
7314not printed and is not put in the value history (@pxref{Value History,
7315,Value history}). The expression is evaluated only for its effects.
7316
c906108c
SS
7317If the beginning of the argument string of the @code{set} command
7318appears identical to a @code{set} subcommand, use the @code{set
7319variable} command instead of just @code{set}. This command is identical
7320to @code{set} except for its lack of subcommands. For example, if your
7321program has a variable @code{width}, you get an error if you try to set
7322a new value with just @samp{set width=13}, because @value{GDBN} has the
7323command @code{set width}:
7324
7325@example
7326(@value{GDBP}) whatis width
7327type = double
7328(@value{GDBP}) p width
7329$4 = 13
7330(@value{GDBP}) set width=47
7331Invalid syntax in expression.
7332@end example
7333
7334@noindent
7335The invalid expression, of course, is @samp{=47}. In
7336order to actually set the program's variable @code{width}, use
7337
7338@example
7339(@value{GDBP}) set var width=47
7340@end example
53a5351d 7341
c906108c
SS
7342Because the @code{set} command has many subcommands that can conflict
7343with the names of program variables, it is a good idea to use the
7344@code{set variable} command instead of just @code{set}. For example, if
7345your program has a variable @code{g}, you run into problems if you try
7346to set a new value with just @samp{set g=4}, because @value{GDBN} has
7347the command @code{set gnutarget}, abbreviated @code{set g}:
7348
7349@example
7350@group
7351(@value{GDBP}) whatis g
7352type = double
7353(@value{GDBP}) p g
7354$1 = 1
7355(@value{GDBP}) set g=4
7356(gdb) p g
7357$2 = 1
7358(@value{GDBP}) r
7359The program being debugged has been started already.
7360Start it from the beginning? (y or n) y
7361Starting program: /home/smith/cc_progs/a.out
7362"/home/smith/cc_progs/a.out": can't open to read symbols: Invalid bfd target.
7363(@value{GDBP}) show g
7364The current BFD target is "=4".
7365@end group
7366@end example
7367
7368@noindent
7369The program variable @code{g} did not change, and you silently set the
7370@code{gnutarget} to an invalid value. In order to set the variable
7371@code{g}, use
7372
7373@example
7374(@value{GDBP}) set var g=4
7375@end example
c906108c
SS
7376
7377@value{GDBN} allows more implicit conversions in assignments than C; you can
7378freely store an integer value into a pointer variable or vice versa,
7379and you can convert any structure to any other structure that is the
7380same length or shorter.
7381@comment FIXME: how do structs align/pad in these conversions?
7382@comment /doc@cygnus.com 18dec1990
7383
7384To store values into arbitrary places in memory, use the @samp{@{@dots{}@}}
7385construct to generate a value of specified type at a specified address
7386(@pxref{Expressions, ,Expressions}). For example, @code{@{int@}0x83040} refers
7387to memory location @code{0x83040} as an integer (which implies a certain size
7388and representation in memory), and
7389
7390@example
7391set @{int@}0x83040 = 4
7392@end example
7393
7394@noindent
7395stores the value 4 into that memory location.
7396
53a5351d 7397@node Jumping
c906108c
SS
7398@section Continuing at a different address
7399
7400Ordinarily, when you continue your program, you do so at the place where
7401it stopped, with the @code{continue} command. You can instead continue at
7402an address of your own choosing, with the following commands:
7403
7404@table @code
7405@kindex jump
7406@item jump @var{linespec}
7407Resume execution at line @var{linespec}. Execution stops again
7408immediately if there is a breakpoint there. @xref{List, ,Printing
7409source lines}, for a description of the different forms of
7410@var{linespec}. It is common practice to use the @code{tbreak} command
7411in conjunction with @code{jump}. @xref{Set Breaks, ,Setting
7412breakpoints}.
7413
7414The @code{jump} command does not change the current stack frame, or
7415the stack pointer, or the contents of any memory location or any
7416register other than the program counter. If line @var{linespec} is in
7417a different function from the one currently executing, the results may
7418be bizarre if the two functions expect different patterns of arguments or
7419of local variables. For this reason, the @code{jump} command requests
7420confirmation if the specified line is not in the function currently
7421executing. However, even bizarre results are predictable if you are
7422well acquainted with the machine-language code of your program.
7423
7424@item jump *@var{address}
7425Resume execution at the instruction at address @var{address}.
7426@end table
7427
c906108c 7428@c Doesn't work on HP-UX; have to set $pcoqh and $pcoqt.
53a5351d
JM
7429On many systems, you can get much the same effect as the @code{jump}
7430command by storing a new value into the register @code{$pc}. The
7431difference is that this does not start your program running; it only
7432changes the address of where it @emph{will} run when you continue. For
7433example,
c906108c
SS
7434
7435@example
7436set $pc = 0x485
7437@end example
7438
7439@noindent
7440makes the next @code{continue} command or stepping command execute at
7441address @code{0x485}, rather than at the address where your program stopped.
7442@xref{Continuing and Stepping, ,Continuing and stepping}.
c906108c
SS
7443
7444The most common occasion to use the @code{jump} command is to back
7445up---perhaps with more breakpoints set---over a portion of a program
7446that has already executed, in order to examine its execution in more
7447detail.
7448
c906108c 7449@c @group
53a5351d 7450@node Signaling
c906108c
SS
7451@section Giving your program a signal
7452
7453@table @code
7454@kindex signal
7455@item signal @var{signal}
7456Resume execution where your program stopped, but immediately give it the
7457signal @var{signal}. @var{signal} can be the name or the number of a
7458signal. For example, on many systems @code{signal 2} and @code{signal
7459SIGINT} are both ways of sending an interrupt signal.
7460
7461Alternatively, if @var{signal} is zero, continue execution without
7462giving a signal. This is useful when your program stopped on account of
7463a signal and would ordinary see the signal when resumed with the
7464@code{continue} command; @samp{signal 0} causes it to resume without a
7465signal.
7466
7467@code{signal} does not repeat when you press @key{RET} a second time
7468after executing the command.
7469@end table
7470@c @end group
7471
7472Invoking the @code{signal} command is not the same as invoking the
7473@code{kill} utility from the shell. Sending a signal with @code{kill}
7474causes @value{GDBN} to decide what to do with the signal depending on
7475the signal handling tables (@pxref{Signals}). The @code{signal} command
7476passes the signal directly to your program.
7477
c906108c 7478
53a5351d 7479@node Returning
c906108c
SS
7480@section Returning from a function
7481
7482@table @code
7483@cindex returning from a function
7484@kindex return
7485@item return
7486@itemx return @var{expression}
7487You can cancel execution of a function call with the @code{return}
7488command. If you give an
7489@var{expression} argument, its value is used as the function's return
7490value.
7491@end table
7492
7493When you use @code{return}, @value{GDBN} discards the selected stack frame
7494(and all frames within it). You can think of this as making the
7495discarded frame return prematurely. If you wish to specify a value to
7496be returned, give that value as the argument to @code{return}.
7497
7498This pops the selected stack frame (@pxref{Selection, ,Selecting a
7499frame}), and any other frames inside of it, leaving its caller as the
7500innermost remaining frame. That frame becomes selected. The
7501specified value is stored in the registers used for returning values
7502of functions.
7503
7504The @code{return} command does not resume execution; it leaves the
7505program stopped in the state that would exist if the function had just
7506returned. In contrast, the @code{finish} command (@pxref{Continuing
7507and Stepping, ,Continuing and stepping}) resumes execution until the
7508selected stack frame returns naturally.
7509
53a5351d 7510@node Calling
c906108c
SS
7511@section Calling program functions
7512
7513@cindex calling functions
7514@kindex call
7515@table @code
7516@item call @var{expr}
7517Evaluate the expression @var{expr} without displaying @code{void}
7518returned values.
7519@end table
7520
7521You can use this variant of the @code{print} command if you want to
7522execute a function from your program, but without cluttering the output
7523with @code{void} returned values. If the result is not void, it
7524is printed and saved in the value history.
7525
c906108c
SS
7526For the A29K, a user-controlled variable @code{call_scratch_address},
7527specifies the location of a scratch area to be used when @value{GDBN}
7528calls a function in the target. This is necessary because the usual
7529method of putting the scratch area on the stack does not work in systems
7530that have separate instruction and data spaces.
c906108c 7531
53a5351d 7532@node Patching
c906108c 7533@section Patching programs
7a292a7a 7534
c906108c
SS
7535@cindex patching binaries
7536@cindex writing into executables
c906108c 7537@cindex writing into corefiles
c906108c 7538
7a292a7a
SS
7539By default, @value{GDBN} opens the file containing your program's
7540executable code (or the corefile) read-only. This prevents accidental
7541alterations to machine code; but it also prevents you from intentionally
7542patching your program's binary.
c906108c
SS
7543
7544If you'd like to be able to patch the binary, you can specify that
7545explicitly with the @code{set write} command. For example, you might
7546want to turn on internal debugging flags, or even to make emergency
7547repairs.
7548
7549@table @code
7550@kindex set write
7551@item set write on
7552@itemx set write off
7a292a7a
SS
7553If you specify @samp{set write on}, @value{GDBN} opens executable and
7554core files for both reading and writing; if you specify @samp{set write
c906108c
SS
7555off} (the default), @value{GDBN} opens them read-only.
7556
7557If you have already loaded a file, you must load it again (using the
7a292a7a
SS
7558@code{exec-file} or @code{core-file} command) after changing @code{set
7559write}, for your new setting to take effect.
c906108c
SS
7560
7561@item show write
7562@kindex show write
7a292a7a
SS
7563Display whether executable files and core files are opened for writing
7564as well as reading.
c906108c
SS
7565@end table
7566
53a5351d 7567@node GDB Files
c906108c
SS
7568@chapter @value{GDBN} Files
7569
7a292a7a
SS
7570@value{GDBN} needs to know the file name of the program to be debugged,
7571both in order to read its symbol table and in order to start your
7572program. To debug a core dump of a previous run, you must also tell
7573@value{GDBN} the name of the core dump file.
c906108c
SS
7574
7575@menu
7576* Files:: Commands to specify files
7577* Symbol Errors:: Errors reading symbol files
7578@end menu
7579
53a5351d 7580@node Files
c906108c 7581@section Commands to specify files
c906108c 7582
7a292a7a 7583@cindex symbol table
c906108c 7584@cindex core dump file
7a292a7a
SS
7585
7586You may want to specify executable and core dump file names. The usual
7587way to do this is at start-up time, using the arguments to
7588@value{GDBN}'s start-up commands (@pxref{Invocation, , Getting In and
7589Out of @value{GDBN}}).
c906108c
SS
7590
7591Occasionally it is necessary to change to a different file during a
7592@value{GDBN} session. Or you may run @value{GDBN} and forget to specify
7593a file you want to use. In these situations the @value{GDBN} commands
7594to specify new files are useful.
7595
7596@table @code
7597@cindex executable file
7598@kindex file
7599@item file @var{filename}
7600Use @var{filename} as the program to be debugged. It is read for its
7601symbols and for the contents of pure memory. It is also the program
7602executed when you use the @code{run} command. If you do not specify a
7603directory and the file is not found in the @value{GDBN} working directory,
7604@value{GDBN} uses the environment variable @code{PATH} as a list of
7605directories to search, just as the shell does when looking for a program
7606to run. You can change the value of this variable, for both @value{GDBN}
7607and your program, using the @code{path} command.
7608
c906108c
SS
7609On systems with memory-mapped files, an auxiliary file
7610@file{@var{filename}.syms} may hold symbol table information for
7611@var{filename}. If so, @value{GDBN} maps in the symbol table from
7612@file{@var{filename}.syms}, starting up more quickly. See the
7613descriptions of the file options @samp{-mapped} and @samp{-readnow}
7614(available on the command line, and with the commands @code{file},
7615@code{symbol-file}, or @code{add-symbol-file}, described below),
7616for more information.
c906108c
SS
7617
7618@item file
7619@code{file} with no argument makes @value{GDBN} discard any information it
7620has on both executable file and the symbol table.
7621
7622@kindex exec-file
7623@item exec-file @r{[} @var{filename} @r{]}
7624Specify that the program to be run (but not the symbol table) is found
7625in @var{filename}. @value{GDBN} searches the environment variable @code{PATH}
7626if necessary to locate your program. Omitting @var{filename} means to
7627discard information on the executable file.
7628
7629@kindex symbol-file
7630@item symbol-file @r{[} @var{filename} @r{]}
7631Read symbol table information from file @var{filename}. @code{PATH} is
7632searched when necessary. Use the @code{file} command to get both symbol
7633table and program to run from the same file.
7634
7635@code{symbol-file} with no argument clears out @value{GDBN} information on your
7636program's symbol table.
7637
7638The @code{symbol-file} command causes @value{GDBN} to forget the contents
7639of its convenience variables, the value history, and all breakpoints and
7640auto-display expressions. This is because they may contain pointers to
7641the internal data recording symbols and data types, which are part of
7642the old symbol table data being discarded inside @value{GDBN}.
7643
7644@code{symbol-file} does not repeat if you press @key{RET} again after
7645executing it once.
7646
7647When @value{GDBN} is configured for a particular environment, it
7648understands debugging information in whatever format is the standard
7649generated for that environment; you may use either a @sc{gnu} compiler, or
7650other compilers that adhere to the local conventions.
c906108c
SS
7651Best results are usually obtained from @sc{gnu} compilers; for example,
7652using @code{@value{GCC}} you can generate debugging information for
7653optimized code.
c906108c
SS
7654
7655For most kinds of object files, with the exception of old SVR3 systems
7656using COFF, the @code{symbol-file} command does not normally read the
7657symbol table in full right away. Instead, it scans the symbol table
7658quickly to find which source files and which symbols are present. The
7659details are read later, one source file at a time, as they are needed.
7660
7661The purpose of this two-stage reading strategy is to make @value{GDBN}
7662start up faster. For the most part, it is invisible except for
7663occasional pauses while the symbol table details for a particular source
7664file are being read. (The @code{set verbose} command can turn these
7665pauses into messages if desired. @xref{Messages/Warnings, ,Optional
7666warnings and messages}.)
7667
c906108c
SS
7668We have not implemented the two-stage strategy for COFF yet. When the
7669symbol table is stored in COFF format, @code{symbol-file} reads the
7670symbol table data in full right away. Note that ``stabs-in-COFF''
7671still does the two-stage strategy, since the debug info is actually
7672in stabs format.
7673
7674@kindex readnow
7675@cindex reading symbols immediately
7676@cindex symbols, reading immediately
7677@kindex mapped
7678@cindex memory-mapped symbol file
7679@cindex saving symbol table
7680@item symbol-file @var{filename} @r{[} -readnow @r{]} @r{[} -mapped @r{]}
7681@itemx file @var{filename} @r{[} -readnow @r{]} @r{[} -mapped @r{]}
7682You can override the @value{GDBN} two-stage strategy for reading symbol
7683tables by using the @samp{-readnow} option with any of the commands that
7684load symbol table information, if you want to be sure @value{GDBN} has the
7685entire symbol table available.
c906108c 7686
c906108c
SS
7687If memory-mapped files are available on your system through the
7688@code{mmap} system call, you can use another option, @samp{-mapped}, to
7689cause @value{GDBN} to write the symbols for your program into a reusable
7690file. Future @value{GDBN} debugging sessions map in symbol information
7691from this auxiliary symbol file (if the program has not changed), rather
7692than spending time reading the symbol table from the executable
7693program. Using the @samp{-mapped} option has the same effect as
7694starting @value{GDBN} with the @samp{-mapped} command-line option.
7695
7696You can use both options together, to make sure the auxiliary symbol
7697file has all the symbol information for your program.
7698
7699The auxiliary symbol file for a program called @var{myprog} is called
7700@samp{@var{myprog}.syms}. Once this file exists (so long as it is newer
7701than the corresponding executable), @value{GDBN} always attempts to use
7702it when you debug @var{myprog}; no special options or commands are
7703needed.
7704
7705The @file{.syms} file is specific to the host machine where you run
7706@value{GDBN}. It holds an exact image of the internal @value{GDBN}
7707symbol table. It cannot be shared across multiple host platforms.
c906108c
SS
7708
7709@c FIXME: for now no mention of directories, since this seems to be in
7710@c flux. 13mar1992 status is that in theory GDB would look either in
7711@c current dir or in same dir as myprog; but issues like competing
7712@c GDB's, or clutter in system dirs, mean that in practice right now
7713@c only current dir is used. FFish says maybe a special GDB hierarchy
7714@c (eg rooted in val of env var GDBSYMS) could exist for mappable symbol
7715@c files.
7716
7717@kindex core
7718@kindex core-file
7719@item core-file @r{[} @var{filename} @r{]}
7720Specify the whereabouts of a core dump file to be used as the ``contents
7721of memory''. Traditionally, core files contain only some parts of the
7722address space of the process that generated them; @value{GDBN} can access the
7723executable file itself for other parts.
7724
7725@code{core-file} with no argument specifies that no core file is
7726to be used.
7727
7728Note that the core file is ignored when your program is actually running
7a292a7a
SS
7729under @value{GDBN}. So, if you have been running your program and you
7730wish to debug a core file instead, you must kill the subprocess in which
7731the program is running. To do this, use the @code{kill} command
c906108c 7732(@pxref{Kill Process, ,Killing the child process}).
c906108c 7733
c906108c
SS
7734@kindex add-symbol-file
7735@cindex dynamic linking
7736@item add-symbol-file @var{filename} @var{address}
7737@itemx add-symbol-file @var{filename} @var{address} @r{[} -readnow @r{]} @r{[} -mapped @r{]}
7738The @code{add-symbol-file} command reads additional symbol table information
7739from the file @var{filename}. You would use this command when @var{filename}
7740has been dynamically loaded (by some other means) into the program that
7741is running. @var{address} should be the memory address at which the
7742file has been loaded; @value{GDBN} cannot figure this out for itself.
7743You can specify @var{address} as an expression.
7744
7745The symbol table of the file @var{filename} is added to the symbol table
7746originally read with the @code{symbol-file} command. You can use the
7747@code{add-symbol-file} command any number of times; the new symbol data thus
7748read keeps adding to the old. To discard all old symbol data instead,
7749use the @code{symbol-file} command.
7750
7751@code{add-symbol-file} does not repeat if you press @key{RET} after using it.
7752
7753You can use the @samp{-mapped} and @samp{-readnow} options just as with
7754the @code{symbol-file} command, to change how @value{GDBN} manages the symbol
7755table information for @var{filename}.
7756
7757@kindex add-shared-symbol-file
7758@item add-shared-symbol-file
7759The @code{add-shared-symbol-file} command can be used only under Harris' CXUX
7760operating system for the Motorola 88k. @value{GDBN} automatically looks for
7761shared libraries, however if @value{GDBN} does not find yours, you can run
7762@code{add-shared-symbol-file}. It takes no arguments.
c906108c 7763
c906108c
SS
7764@kindex section
7765@item section
7766The @code{section} command changes the base address of section SECTION of
7767the exec file to ADDR. This can be used if the exec file does not contain
7768section addresses, (such as in the a.out format), or when the addresses
7769specified in the file itself are wrong. Each section must be changed
7770separately. The ``info files'' command lists all the sections and their
7771addresses.
c906108c
SS
7772
7773@kindex info files
7774@kindex info target
7775@item info files
7776@itemx info target
7a292a7a
SS
7777@code{info files} and @code{info target} are synonymous; both print the
7778current target (@pxref{Targets, ,Specifying a Debugging Target}),
7779including the names of the executable and core dump files currently in
7780use by @value{GDBN}, and the files from which symbols were loaded. The
7781command @code{help target} lists all possible targets rather than
7782current ones.
7783
c906108c
SS
7784@end table
7785
7786All file-specifying commands allow both absolute and relative file names
7787as arguments. @value{GDBN} always converts the file name to an absolute file
7788name and remembers it that way.
7789
c906108c 7790@cindex shared libraries
c906108c
SS
7791@value{GDBN} supports HP-UX, SunOS, SVr4, Irix 5, and IBM RS/6000 shared
7792libraries.
53a5351d 7793
c906108c
SS
7794@value{GDBN} automatically loads symbol definitions from shared libraries
7795when you use the @code{run} command, or when you examine a core file.
7796(Before you issue the @code{run} command, @value{GDBN} does not understand
7797references to a function in a shared library, however---unless you are
7798debugging a core file).
53a5351d
JM
7799
7800On HP-UX, if the program loads a library explicitly, @value{GDBN}
7801automatically loads the symbols at the time of the @code{shl_load} call.
7802
c906108c
SS
7803@c FIXME: some @value{GDBN} release may permit some refs to undef
7804@c FIXME...symbols---eg in a break cmd---assuming they are from a shared
7805@c FIXME...lib; check this from time to time when updating manual
7806
7807@table @code
7808@kindex info sharedlibrary
7809@kindex info share
7810@item info share
7811@itemx info sharedlibrary
7812Print the names of the shared libraries which are currently loaded.
7813
7814@kindex sharedlibrary
7815@kindex share
7816@item sharedlibrary @var{regex}
7817@itemx share @var{regex}
7818
7819Load shared object library symbols for files matching a
7820Unix regular expression.
7821As with files loaded automatically, it only loads shared libraries
7822required by your program for a core file or after typing @code{run}. If
7823@var{regex} is omitted all shared libraries required by your program are
7824loaded.
7825@end table
7826
53a5351d
JM
7827On HP-UX systems, @value{GDBN} detects the loading of a shared library
7828and automatically reads in symbols from the newly loaded library, up to
7829a threshold that is initially set but that you can modify if you wish.
c906108c
SS
7830
7831Beyond that threshold, symbols from shared libraries must be explicitly
7832loaded. To load these symbols, use the command @code{sharedlibrary}
7833@var{filename}. The base address of the shared library is determined
7834automatically by @value{GDBN} and need not be specified.
7835
7836To display or set the threshold, use the commands:
7837
7838@table @code
7839@kindex set auto-solib-add
7840@item set auto-solib-add @var{threshold}
7841Set the autoloading size threshold, in megabytes. If @var{threshold} is
7842nonzero, symbols from all shared object libraries will be loaded
7843automatically when the inferior begins execution or when the dynamic
7844linker informs @value{GDBN} that a new library has been loaded, until
7845the symbol table of the program and libraries exceeds this threshold.
7846Otherwise, symbols must be loaded manually, using the
7847@code{sharedlibrary} command. The default threshold is 100 megabytes.
7848
7849@kindex show auto-solib-add
7850@item show auto-solib-add
7851Display the current autoloading size threshold, in megabytes.
7852@end table
c906108c 7853
53a5351d 7854@node Symbol Errors
c906108c
SS
7855@section Errors reading symbol files
7856
7857While reading a symbol file, @value{GDBN} occasionally encounters problems,
7858such as symbol types it does not recognize, or known bugs in compiler
7859output. By default, @value{GDBN} does not notify you of such problems, since
7860they are relatively common and primarily of interest to people
7861debugging compilers. If you are interested in seeing information
7862about ill-constructed symbol tables, you can either ask @value{GDBN} to print
7863only one message about each such type of problem, no matter how many
7864times the problem occurs; or you can ask @value{GDBN} to print more messages,
7865to see how many times the problems occur, with the @code{set
7866complaints} command (@pxref{Messages/Warnings, ,Optional warnings and
7867messages}).
7868
7869The messages currently printed, and their meanings, include:
7870
7871@table @code
7872@item inner block not inside outer block in @var{symbol}
7873
7874The symbol information shows where symbol scopes begin and end
7875(such as at the start of a function or a block of statements). This
7876error indicates that an inner scope block is not fully contained
7877in its outer scope blocks.
7878
7879@value{GDBN} circumvents the problem by treating the inner block as if it had
7880the same scope as the outer block. In the error message, @var{symbol}
7881may be shown as ``@code{(don't know)}'' if the outer block is not a
7882function.
7883
7884@item block at @var{address} out of order
7885
7886The symbol information for symbol scope blocks should occur in
7887order of increasing addresses. This error indicates that it does not
7888do so.
7889
7890@value{GDBN} does not circumvent this problem, and has trouble
7891locating symbols in the source file whose symbols it is reading. (You
7892can often determine what source file is affected by specifying
7893@code{set verbose on}. @xref{Messages/Warnings, ,Optional warnings and
7894messages}.)
7895
7896@item bad block start address patched
7897
7898The symbol information for a symbol scope block has a start address
7899smaller than the address of the preceding source line. This is known
7900to occur in the SunOS 4.1.1 (and earlier) C compiler.
7901
7902@value{GDBN} circumvents the problem by treating the symbol scope block as
7903starting on the previous source line.
7904
7905@item bad string table offset in symbol @var{n}
7906
7907@cindex foo
7908Symbol number @var{n} contains a pointer into the string table which is
7909larger than the size of the string table.
7910
7911@value{GDBN} circumvents the problem by considering the symbol to have the
7912name @code{foo}, which may cause other problems if many symbols end up
7913with this name.
7914
7915@item unknown symbol type @code{0x@var{nn}}
7916
7a292a7a
SS
7917The symbol information contains new data types that @value{GDBN} does
7918not yet know how to read. @code{0x@var{nn}} is the symbol type of the
7919misunderstood information, in hexadecimal.
c906108c 7920
7a292a7a
SS
7921@value{GDBN} circumvents the error by ignoring this symbol information.
7922This usually allows you to debug your program, though certain symbols
c906108c 7923are not accessible. If you encounter such a problem and feel like
7a292a7a
SS
7924debugging it, you can debug @code{@value{GDBP}} with itself, breakpoint
7925on @code{complain}, then go up to the function @code{read_dbx_symtab}
7926and examine @code{*bufp} to see the symbol.
c906108c
SS
7927
7928@item stub type has NULL name
c906108c 7929
7a292a7a 7930@value{GDBN} could not find the full definition for a struct or class.
c906108c 7931
7a292a7a 7932@item const/volatile indicator missing (ok if using g++ v1.x), got@dots{}
c906108c 7933The symbol information for a C++ member function is missing some
7a292a7a
SS
7934information that recent versions of the compiler should have output for
7935it.
c906108c
SS
7936
7937@item info mismatch between compiler and debugger
7938
7939@value{GDBN} could not parse a type specification output by the compiler.
7a292a7a 7940
c906108c
SS
7941@end table
7942
53a5351d 7943@node Targets
c906108c 7944@chapter Specifying a Debugging Target
7a292a7a 7945
c906108c
SS
7946@cindex debugging target
7947@kindex target
7948
7949A @dfn{target} is the execution environment occupied by your program.
53a5351d
JM
7950
7951Often, @value{GDBN} runs in the same host environment as your program;
7952in that case, the debugging target is specified as a side effect when
7953you use the @code{file} or @code{core} commands. When you need more
c906108c
SS
7954flexibility---for example, running @value{GDBN} on a physically separate
7955host, or controlling a standalone system over a serial port or a
53a5351d
JM
7956realtime system over a TCP/IP connection---you can use the @code{target}
7957command to specify one of the target types configured for @value{GDBN}
7958(@pxref{Target Commands, ,Commands for managing targets}).
c906108c
SS
7959
7960@menu
7961* Active Targets:: Active targets
7962* Target Commands:: Commands for managing targets
c906108c
SS
7963* Byte Order:: Choosing target byte order
7964* Remote:: Remote debugging
96baa820 7965* KOD:: Kernel Object Display
c906108c
SS
7966
7967@end menu
7968
53a5351d 7969@node Active Targets
c906108c 7970@section Active targets
7a292a7a 7971
c906108c
SS
7972@cindex stacking targets
7973@cindex active targets
7974@cindex multiple targets
7975
c906108c 7976There are three classes of targets: processes, core files, and
7a292a7a
SS
7977executable files. @value{GDBN} can work concurrently on up to three
7978active targets, one in each class. This allows you to (for example)
7979start a process and inspect its activity without abandoning your work on
7980a core file.
c906108c
SS
7981
7982For example, if you execute @samp{gdb a.out}, then the executable file
7983@code{a.out} is the only active target. If you designate a core file as
7984well---presumably from a prior run that crashed and coredumped---then
7985@value{GDBN} has two active targets and uses them in tandem, looking
7986first in the corefile target, then in the executable file, to satisfy
7987requests for memory addresses. (Typically, these two classes of target
7988are complementary, since core files contain only a program's
7989read-write memory---variables and so on---plus machine status, while
7990executable files contain only the program text and initialized data.)
c906108c
SS
7991
7992When you type @code{run}, your executable file becomes an active process
7a292a7a
SS
7993target as well. When a process target is active, all @value{GDBN}
7994commands requesting memory addresses refer to that target; addresses in
7995an active core file or executable file target are obscured while the
7996process target is active.
c906108c 7997
7a292a7a
SS
7998Use the @code{core-file} and @code{exec-file} commands to select a new
7999core file or executable target (@pxref{Files, ,Commands to specify
c906108c 8000files}). To specify as a target a process that is already running, use
7a292a7a
SS
8001the @code{attach} command (@pxref{Attach, ,Debugging an already-running
8002process}).
c906108c 8003
53a5351d 8004@node Target Commands
c906108c
SS
8005@section Commands for managing targets
8006
8007@table @code
8008@item target @var{type} @var{parameters}
7a292a7a
SS
8009Connects the @value{GDBN} host environment to a target machine or
8010process. A target is typically a protocol for talking to debugging
8011facilities. You use the argument @var{type} to specify the type or
8012protocol of the target machine.
c906108c
SS
8013
8014Further @var{parameters} are interpreted by the target protocol, but
8015typically include things like device names or host names to connect
8016with, process numbers, and baud rates.
c906108c
SS
8017
8018The @code{target} command does not repeat if you press @key{RET} again
8019after executing the command.
8020
8021@kindex help target
8022@item help target
8023Displays the names of all targets available. To display targets
8024currently selected, use either @code{info target} or @code{info files}
8025(@pxref{Files, ,Commands to specify files}).
8026
8027@item help target @var{name}
8028Describe a particular target, including any parameters necessary to
8029select it.
8030
8031@kindex set gnutarget
8032@item set gnutarget @var{args}
8033@value{GDBN} uses its own library BFD to read your files. @value{GDBN}
8034knows whether it is reading an @dfn{executable},
8035a @dfn{core}, or a @dfn{.o} file; however, you can specify the file format
8036with the @code{set gnutarget} command. Unlike most @code{target} commands,
8037with @code{gnutarget} the @code{target} refers to a program, not a machine.
8038
8039@emph{Warning:} To specify a file format with @code{set gnutarget},
8040you must know the actual BFD name.
8041
8042@noindent @xref{Files, , Commands to specify files}.
8043
8044@kindex show gnutarget
8045@item show gnutarget
8046Use the @code{show gnutarget} command to display what file format
8047@code{gnutarget} is set to read. If you have not set @code{gnutarget},
8048@value{GDBN} will determine the file format for each file automatically,
8049and @code{show gnutarget} displays @samp{The current BDF target is "auto"}.
8050@end table
8051
c906108c
SS
8052Here are some common targets (available, or not, depending on the GDB
8053configuration):
c906108c
SS
8054
8055@table @code
8056@kindex target exec
8057@item target exec @var{program}
8058An executable file. @samp{target exec @var{program}} is the same as
8059@samp{exec-file @var{program}}.
8060
c906108c
SS
8061@kindex target core
8062@item target core @var{filename}
8063A core dump file. @samp{target core @var{filename}} is the same as
8064@samp{core-file @var{filename}}.
c906108c
SS
8065
8066@kindex target remote
8067@item target remote @var{dev}
8068Remote serial target in GDB-specific protocol. The argument @var{dev}
8069specifies what serial device to use for the connection (e.g.
8070@file{/dev/ttya}). @xref{Remote, ,Remote debugging}. @code{target remote}
8071now supports the @code{load} command. This is only useful if you have
8072some other way of getting the stub to the target system, and you can put
8073it somewhere in memory where it won't get clobbered by the download.
8074
c906108c
SS
8075@kindex target sim
8076@item target sim
8077CPU simulator. @xref{Simulator,,Simulated CPU Target}.
c906108c
SS
8078@end table
8079
8080The following targets are all CPU-specific, and only available for
8081specific configurations.
8082@c should organize by CPU
8083
8084@table @code
8085
8086@kindex target abug
8087@item target abug @var{dev}
8088ABug ROM monitor for M68K.
8089
8090@kindex target adapt
8091@item target adapt @var{dev}
8092Adapt monitor for A29K.
8093
8094@kindex target amd-eb
8095@item target amd-eb @var{dev} @var{speed} @var{PROG}
8096@cindex AMD EB29K
8097Remote PC-resident AMD EB29K board, attached over serial lines.
8098@var{dev} is the serial device, as for @code{target remote};
8099@var{speed} allows you to specify the linespeed; and @var{PROG} is the
8100name of the program to be debugged, as it appears to DOS on the PC.
8101@xref{EB29K Remote, ,The EBMON protocol for AMD29K}.
8102
8103@kindex target array
8104@item target array @var{dev}
8105Array Tech LSI33K RAID controller board.
8106
8107@kindex target bug
8108@item target bug @var{dev}
8109BUG monitor, running on a MVME187 (m88k) board.
8110
8111@kindex target cpu32bug
8112@item target cpu32bug @var{dev}
8113CPU32BUG monitor, running on a CPU32 (M68K) board.
8114
8115@kindex target dbug
8116@item target dbug @var{dev}
8117dBUG ROM monitor for Motorola ColdFire.
8118
8119@kindex target ddb
8120@item target ddb @var{dev}
8121NEC's DDB monitor for Mips Vr4300.
8122
8123@kindex target dink32
8124@item target dink32 @var{dev}
8125DINK32 ROM monitor for PowerPC.
8126
8127@kindex target e7000
8128@item target e7000 @var{dev}
8129E7000 emulator for Hitachi H8 and SH.
8130
8131@kindex target es1800
8132@item target es1800 @var{dev}
8133ES-1800 emulator for M68K.
8134
8135@kindex target est
8136@item target est @var{dev}
8137EST-300 ICE monitor, running on a CPU32 (M68K) board.
8138
8139@kindex target hms
8140@item target hms @var{dev}
8141A Hitachi SH, H8/300, or H8/500 board, attached via serial line to your host.
c906108c
SS
8142Use special commands @code{device} and @code{speed} to control the serial
8143line and the communications speed used.
8144@xref{Hitachi Remote,,@value{GDBN} and Hitachi Microprocessors}.
8145
8146@kindex target lsi
8147@item target lsi @var{dev}
8148LSI ROM monitor for Mips.
8149
8150@kindex target m32r
8151@item target m32r @var{dev}
8152Mitsubishi M32R/D ROM monitor.
8153
8154@kindex target mips
8155@item target mips @var{dev}
8156IDT/SIM ROM monitor for Mips.
8157
8158@kindex target mon960
8159@item target mon960 @var{dev}
8160MON960 monitor for Intel i960.
8161
8162@kindex target nindy
8163@item target nindy @var{devicename}
8164An Intel 960 board controlled by a Nindy Monitor. @var{devicename} is
8165the name of the serial device to use for the connection, e.g.
8166@file{/dev/ttya}. @xref{i960-Nindy Remote, ,@value{GDBN} with a remote i960 (Nindy)}.
8167
8168@kindex target nrom
8169@item target nrom @var{dev}
8170NetROM ROM emulator. This target only supports downloading.
8171
8172@kindex target op50n
8173@item target op50n @var{dev}
8174OP50N monitor, running on an OKI HPPA board.
8175
8176@kindex target pmon
8177@item target pmon @var{dev}
8178PMON ROM monitor for Mips.
8179
8180@kindex target ppcbug
8181@item target ppcbug @var{dev}
8182@kindex target ppcbug1
8183@item target ppcbug1 @var{dev}
8184PPCBUG ROM monitor for PowerPC.
8185
8186@kindex target r3900
8187@item target r3900 @var{dev}
8188Densan DVE-R3900 ROM monitor for Toshiba R3900 Mips.
8189
8190@kindex target rdi
8191@item target rdi @var{dev}
8192ARM Angel monitor, via RDI library interface.
8193
8194@kindex target rdp
8195@item target rdp @var{dev}
8196ARM Demon monitor.
8197
8198@kindex target rom68k
8199@item target rom68k @var{dev}
8200ROM 68K monitor, running on an M68K IDP board.
8201
8202@kindex target rombug
8203@item target rombug @var{dev}
8204ROMBUG ROM monitor for OS/9000.
8205
8206@kindex target sds
8207@item target sds @var{dev}
8208SDS monitor, running on a PowerPC board (such as Motorola's ADS).
8209
8210@kindex target sparclite
8211@item target sparclite @var{dev}
8212Fujitsu sparclite boards, used only for the purpose of loading.
8213You must use an additional command to debug the program.
8214For example: target remote @var{dev} using @value{GDBN} standard
8215remote protocol.
8216
8217@kindex target sh3
8218@kindex target sh3e
8219@item target sh3 @var{dev}
8220@item target sh3e @var{dev}
8221Hitachi SH-3 and SH-3E target systems.
8222
8223@kindex target st2000
8224@item target st2000 @var{dev} @var{speed}
8225A Tandem ST2000 phone switch, running Tandem's STDBUG protocol. @var{dev}
8226is the name of the device attached to the ST2000 serial line;
8227@var{speed} is the communication line speed. The arguments are not used
8228if @value{GDBN} is configured to connect to the ST2000 using TCP or Telnet.
8229@xref{ST2000 Remote,,@value{GDBN} with a Tandem ST2000}.
8230
8231@kindex target udi
8232@item target udi @var{keyword}
8233Remote AMD29K target, using the AMD UDI protocol. The @var{keyword}
8234argument specifies which 29K board or simulator to use. @xref{UDI29K
8235Remote,,The UDI protocol for AMD29K}.
8236
8237@kindex target vxworks
8238@item target vxworks @var{machinename}
8239A VxWorks system, attached via TCP/IP. The argument @var{machinename}
8240is the target system's machine name or IP address.
8241@xref{VxWorks Remote, ,@value{GDBN} and VxWorks}.
8242
8243@kindex target w89k
8244@item target w89k @var{dev}
8245W89K monitor, running on a Winbond HPPA board.
8246
c906108c
SS
8247@end table
8248
c906108c
SS
8249Different targets are available on different configurations of @value{GDBN};
8250your configuration may have more or fewer targets.
c906108c
SS
8251
8252Many remote targets require you to download the executable's code
8253once you've successfully established a connection.
8254
8255@table @code
8256
8257@kindex load @var{filename}
8258@item load @var{filename}
c906108c
SS
8259Depending on what remote debugging facilities are configured into
8260@value{GDBN}, the @code{load} command may be available. Where it exists, it
8261is meant to make @var{filename} (an executable) available for debugging
8262on the remote system---by downloading, or dynamic linking, for example.
8263@code{load} also records the @var{filename} symbol table in @value{GDBN}, like
8264the @code{add-symbol-file} command.
8265
8266If your @value{GDBN} does not have a @code{load} command, attempting to
8267execute it gets the error message ``@code{You can't do that when your
8268target is @dots{}}''
c906108c
SS
8269
8270The file is loaded at whatever address is specified in the executable.
8271For some object file formats, you can specify the load address when you
8272link the program; for other formats, like a.out, the object file format
8273specifies a fixed address.
8274@c FIXME! This would be a good place for an xref to the GNU linker doc.
8275
c906108c
SS
8276On VxWorks, @code{load} links @var{filename} dynamically on the
8277current target system as well as adding its symbols in @value{GDBN}.
c906108c 8278
c906108c
SS
8279@cindex download to Nindy-960
8280With the Nindy interface to an Intel 960 board, @code{load}
8281downloads @var{filename} to the 960 as well as adding its symbols in
8282@value{GDBN}.
c906108c 8283
c906108c
SS
8284@cindex download to H8/300 or H8/500
8285@cindex H8/300 or H8/500 download
8286@cindex download to Hitachi SH
8287@cindex Hitachi SH download
8288When you select remote debugging to a Hitachi SH, H8/300, or H8/500 board
8289(@pxref{Hitachi Remote,,@value{GDBN} and Hitachi Microprocessors}),
8290the @code{load} command downloads your program to the Hitachi board and also
8291opens it as the current executable target for @value{GDBN} on your host
8292(like the @code{file} command).
c906108c
SS
8293
8294@code{load} does not repeat if you press @key{RET} again after using it.
8295@end table
8296
53a5351d 8297@node Byte Order
c906108c 8298@section Choosing target byte order
7a292a7a 8299
c906108c
SS
8300@cindex choosing target byte order
8301@cindex target byte order
8302@kindex set endian big
8303@kindex set endian little
8304@kindex set endian auto
8305@kindex show endian
8306
8307Some types of processors, such as the MIPS, PowerPC, and Hitachi SH,
8308offer the ability to run either big-endian or little-endian byte
8309orders. Usually the executable or symbol will include a bit to
8310designate the endian-ness, and you will not need to worry about
8311which to use. However, you may still find it useful to adjust
8312GDB's idea of processor endian-ness manually.
8313
8314@table @code
8315@kindex set endian big
8316@item set endian big
8317Instruct @value{GDBN} to assume the target is big-endian.
8318
8319@kindex set endian little
8320@item set endian little
8321Instruct @value{GDBN} to assume the target is little-endian.
8322
8323@kindex set endian auto
8324@item set endian auto
8325Instruct @value{GDBN} to use the byte order associated with the
8326executable.
8327
8328@item show endian
8329Display @value{GDBN}'s current idea of the target byte order.
8330
8331@end table
8332
8333Note that these commands merely adjust interpretation of symbolic
8334data on the host, and that they have absolutely no effect on the
8335target system.
8336
53a5351d 8337@node Remote
c906108c
SS
8338@section Remote debugging
8339@cindex remote debugging
8340
8341If you are trying to debug a program running on a machine that cannot run
8342@value{GDBN} in the usual way, it is often useful to use remote debugging.
8343For example, you might use remote debugging on an operating system kernel,
8344or on a small system which does not have a general purpose operating system
8345powerful enough to run a full-featured debugger.
8346
8347Some configurations of @value{GDBN} have special serial or TCP/IP interfaces
8348to make this work with particular debugging targets. In addition,
8349@value{GDBN} comes with a generic serial protocol (specific to @value{GDBN},
8350but not specific to any particular target system) which you can use if you
8351write the remote stubs---the code that runs on the remote system to
8352communicate with @value{GDBN}.
8353
8354Other remote targets may be available in your
8355configuration of @value{GDBN}; use @code{help target} to list them.
c906108c 8356
c906108c
SS
8357@c Text on starting up GDB in various specific cases; it goes up front
8358@c in manuals configured for any of those particular situations, here
8359@c otherwise.
8360@menu
c906108c 8361* Remote Serial:: @value{GDBN} remote serial protocol
c906108c 8362* i960-Nindy Remote:: @value{GDBN} with a remote i960 (Nindy)
c906108c
SS
8363* UDI29K Remote:: The UDI protocol for AMD29K
8364* EB29K Remote:: The EBMON protocol for AMD29K
c906108c 8365* VxWorks Remote:: @value{GDBN} and VxWorks
c906108c 8366* ST2000 Remote:: @value{GDBN} with a Tandem ST2000
c906108c 8367* Hitachi Remote:: @value{GDBN} and Hitachi Microprocessors
c906108c 8368* MIPS Remote:: @value{GDBN} and MIPS boards
c906108c 8369* Sparclet Remote:: @value{GDBN} and Sparclet boards
c906108c 8370* Simulator:: Simulated CPU target
c906108c
SS
8371@end menu
8372
8373@include remote.texi
7a292a7a 8374
c906108c 8375
53a5351d 8376@node KOD
96baa820
JM
8377@section Kernel Object Display
8378@cindex kernel object display
8379@cindex kernel object
8380@cindex KOD
8381
8382Some targets support kernel object display. Using this facility,
8383@value{GDBN} communicates specially with the underlying operating system
8384and can display information about operating system-level objects such as
8385mutexes and other synchronization objects. Exactly which objects can be
8386displayed is determined on a per-OS basis.
8387
8388Use the @code{set os} command to set the operating system. This tells
8389@value{GDBN} which kernel object display module to initialize:
8390
8391@example
8392(gdb) set os cisco
8393@end example
8394
8395If @code{set os} succeeds, @value{GDBN} will display some information
8396about the operating system, and will create a new @code{info} command
8397which can be used to query the target. The @code{info} command is named
8398after the operating system:
8399
8400@example
8401(gdb) info cisco
8402List of Cisco Kernel Objects
8403Object Description
8404any Any and all objects
8405@end example
8406
8407Further subcommands can be used to query about particular objects known
8408by the kernel.
8409
8410There is currently no way to determine whether a given operating system
8411is supported other than to try it.
8412
8413
c906108c
SS
8414@node Controlling GDB
8415@chapter Controlling @value{GDBN}
8416
53a5351d
JM
8417You can alter the way @value{GDBN} interacts with you by using the
8418@code{set} command. For commands controlling how @value{GDBN} displays
8419data, @pxref{Print Settings, ,Print settings}; other settings are
8420described here.
c906108c
SS
8421
8422@menu
8423* Prompt:: Prompt
8424* Editing:: Command editing
8425* History:: Command history
8426* Screen Size:: Screen size
8427* Numbers:: Numbers
8428* Messages/Warnings:: Optional warnings and messages
8429@end menu
8430
53a5351d 8431@node Prompt
c906108c
SS
8432@section Prompt
8433
8434@cindex prompt
8435
8436@value{GDBN} indicates its readiness to read a command by printing a string
8437called the @dfn{prompt}. This string is normally @samp{(@value{GDBP})}. You
8438can change the prompt string with the @code{set prompt} command. For
8439instance, when debugging @value{GDBN} with @value{GDBN}, it is useful to change
8440the prompt in one of the @value{GDBN} sessions so that you can always tell
8441which one you are talking to.
8442
8443@emph{Note:} @code{set prompt} no longer adds a space for you after the
8444prompt you set. This allows you to set a prompt which ends in a space
8445or a prompt that does not.
8446
8447@table @code
8448@kindex set prompt
8449@item set prompt @var{newprompt}
8450Directs @value{GDBN} to use @var{newprompt} as its prompt string henceforth.
8451
8452@kindex show prompt
8453@item show prompt
8454Prints a line of the form: @samp{Gdb's prompt is: @var{your-prompt}}
8455@end table
8456
53a5351d 8457@node Editing
c906108c
SS
8458@section Command editing
8459@cindex readline
8460@cindex command line editing
8461
8462@value{GDBN} reads its input commands via the @dfn{readline} interface. This
8463@sc{gnu} library provides consistent behavior for programs which provide a
8464command line interface to the user. Advantages are @sc{gnu} Emacs-style
8465or @dfn{vi}-style inline editing of commands, @code{csh}-like history
8466substitution, and a storage and recall of command history across
8467debugging sessions.
8468
8469You may control the behavior of command line editing in @value{GDBN} with the
8470command @code{set}.
8471
8472@table @code
8473@kindex set editing
8474@cindex editing
8475@item set editing
8476@itemx set editing on
8477Enable command line editing (enabled by default).
8478
8479@item set editing off
8480Disable command line editing.
8481
8482@kindex show editing
8483@item show editing
8484Show whether command line editing is enabled.
8485@end table
8486
53a5351d 8487@node History
c906108c
SS
8488@section Command history
8489
8490@value{GDBN} can keep track of the commands you type during your
8491debugging sessions, so that you can be certain of precisely what
8492happened. Use these commands to manage the @value{GDBN} command
8493history facility.
8494
8495@table @code
8496@cindex history substitution
8497@cindex history file
8498@kindex set history filename
8499@kindex GDBHISTFILE
8500@item set history filename @var{fname}
8501Set the name of the @value{GDBN} command history file to @var{fname}.
8502This is the file where @value{GDBN} reads an initial command history
8503list, and where it writes the command history from this session when it
8504exits. You can access this list through history expansion or through
8505the history command editing characters listed below. This file defaults
8506to the value of the environment variable @code{GDBHISTFILE}, or to
8507@file{./.gdb_history} if this variable is not set.
8508
8509@cindex history save
8510@kindex set history save
8511@item set history save
8512@itemx set history save on
8513Record command history in a file, whose name may be specified with the
8514@code{set history filename} command. By default, this option is disabled.
8515
8516@item set history save off
8517Stop recording command history in a file.
8518
8519@cindex history size
8520@kindex set history size
8521@item set history size @var{size}
8522Set the number of commands which @value{GDBN} keeps in its history list.
8523This defaults to the value of the environment variable
8524@code{HISTSIZE}, or to 256 if this variable is not set.
8525@end table
8526
8527@cindex history expansion
8528History expansion assigns special meaning to the character @kbd{!}.
8529@ifset have-readline-appendices
8530@xref{Event Designators}.
8531@end ifset
8532
8533Since @kbd{!} is also the logical not operator in C, history expansion
8534is off by default. If you decide to enable history expansion with the
8535@code{set history expansion on} command, you may sometimes need to
8536follow @kbd{!} (when it is used as logical not, in an expression) with
8537a space or a tab to prevent it from being expanded. The readline
8538history facilities do not attempt substitution on the strings
8539@kbd{!=} and @kbd{!(}, even when history expansion is enabled.
8540
8541The commands to control history expansion are:
8542
8543@table @code
8544@kindex set history expansion
8545@item set history expansion on
8546@itemx set history expansion
8547Enable history expansion. History expansion is off by default.
8548
8549@item set history expansion off
8550Disable history expansion.
8551
8552The readline code comes with more complete documentation of
8553editing and history expansion features. Users unfamiliar with @sc{gnu} Emacs
8554or @code{vi} may wish to read it.
8555@ifset have-readline-appendices
8556@xref{Command Line Editing}.
8557@end ifset
8558
8559@c @group
8560@kindex show history
8561@item show history
8562@itemx show history filename
8563@itemx show history save
8564@itemx show history size
8565@itemx show history expansion
8566These commands display the state of the @value{GDBN} history parameters.
8567@code{show history} by itself displays all four states.
8568@c @end group
8569@end table
8570
8571@table @code
8572@kindex show commands
8573@item show commands
8574Display the last ten commands in the command history.
8575
8576@item show commands @var{n}
8577Print ten commands centered on command number @var{n}.
8578
8579@item show commands +
8580Print ten commands just after the commands last printed.
8581@end table
8582
53a5351d 8583@node Screen Size
c906108c
SS
8584@section Screen size
8585@cindex size of screen
8586@cindex pauses in output
8587
8588Certain commands to @value{GDBN} may produce large amounts of
8589information output to the screen. To help you read all of it,
8590@value{GDBN} pauses and asks you for input at the end of each page of
8591output. Type @key{RET} when you want to continue the output, or @kbd{q}
8592to discard the remaining output. Also, the screen width setting
8593determines when to wrap lines of output. Depending on what is being
8594printed, @value{GDBN} tries to break the line at a readable place,
8595rather than simply letting it overflow onto the following line.
8596
8597Normally @value{GDBN} knows the size of the screen from the termcap data base
8598together with the value of the @code{TERM} environment variable and the
8599@code{stty rows} and @code{stty cols} settings. If this is not correct,
8600you can override it with the @code{set height} and @code{set
8601width} commands:
8602
8603@table @code
8604@kindex set height
8605@kindex set width
8606@kindex show width
8607@kindex show height
8608@item set height @var{lpp}
8609@itemx show height
8610@itemx set width @var{cpl}
8611@itemx show width
8612These @code{set} commands specify a screen height of @var{lpp} lines and
8613a screen width of @var{cpl} characters. The associated @code{show}
8614commands display the current settings.
8615
8616If you specify a height of zero lines, @value{GDBN} does not pause during
8617output no matter how long the output is. This is useful if output is to a
8618file or to an editor buffer.
8619
8620Likewise, you can specify @samp{set width 0} to prevent @value{GDBN}
8621from wrapping its output.
8622@end table
8623
53a5351d 8624@node Numbers
c906108c
SS
8625@section Numbers
8626@cindex number representation
8627@cindex entering numbers
8628
8629You can always enter numbers in octal, decimal, or hexadecimal in @value{GDBN} by
8630the usual conventions: octal numbers begin with @samp{0}, decimal
8631numbers end with @samp{.}, and hexadecimal numbers begin with @samp{0x}.
8632Numbers that begin with none of these are, by default, entered in base
863310; likewise, the default display for numbers---when no particular
8634format is specified---is base 10. You can change the default base for
8635both input and output with the @code{set radix} command.
8636
8637@table @code
8638@kindex set input-radix
8639@item set input-radix @var{base}
8640Set the default base for numeric input. Supported choices
8641for @var{base} are decimal 8, 10, or 16. @var{base} must itself be
8642specified either unambiguously or using the current default radix; for
8643example, any of
8644
8645@smallexample
8646set radix 012
8647set radix 10.
8648set radix 0xa
8649@end smallexample
8650
8651@noindent
8652sets the base to decimal. On the other hand, @samp{set radix 10}
8653leaves the radix unchanged no matter what it was.
8654
8655@kindex set output-radix
8656@item set output-radix @var{base}
8657Set the default base for numeric display. Supported choices
8658for @var{base} are decimal 8, 10, or 16. @var{base} must itself be
8659specified either unambiguously or using the current default radix.
8660
8661@kindex show input-radix
8662@item show input-radix
8663Display the current default base for numeric input.
8664
8665@kindex show output-radix
8666@item show output-radix
8667Display the current default base for numeric display.
8668@end table
8669
53a5351d 8670@node Messages/Warnings
c906108c
SS
8671@section Optional warnings and messages
8672
8673By default, @value{GDBN} is silent about its inner workings. If you are running
8674on a slow machine, you may want to use the @code{set verbose} command.
8675This makes @value{GDBN} tell you when it does a lengthy internal operation, so
8676you will not think it has crashed.
8677
8678Currently, the messages controlled by @code{set verbose} are those
8679which announce that the symbol table for a source file is being read;
8680see @code{symbol-file} in @ref{Files, ,Commands to specify files}.
8681
8682@table @code
8683@kindex set verbose
8684@item set verbose on
8685Enables @value{GDBN} output of certain informational messages.
8686
8687@item set verbose off
8688Disables @value{GDBN} output of certain informational messages.
8689
8690@kindex show verbose
8691@item show verbose
8692Displays whether @code{set verbose} is on or off.
8693@end table
8694
8695By default, if @value{GDBN} encounters bugs in the symbol table of an object
8696file, it is silent; but if you are debugging a compiler, you may find
8697this information useful (@pxref{Symbol Errors, ,Errors reading symbol files}).
8698
8699@table @code
8700@kindex set complaints
8701@item set complaints @var{limit}
8702Permits @value{GDBN} to output @var{limit} complaints about each type of unusual
8703symbols before becoming silent about the problem. Set @var{limit} to
8704zero to suppress all complaints; set it to a large number to prevent
8705complaints from being suppressed.
8706
8707@kindex show complaints
8708@item show complaints
8709Displays how many symbol complaints @value{GDBN} is permitted to produce.
8710@end table
8711
8712By default, @value{GDBN} is cautious, and asks what sometimes seems to be a
8713lot of stupid questions to confirm certain commands. For example, if
8714you try to run a program which is already running:
8715
8716@example
8717(@value{GDBP}) run
8718The program being debugged has been started already.
8719Start it from the beginning? (y or n)
8720@end example
8721
8722If you are willing to unflinchingly face the consequences of your own
8723commands, you can disable this ``feature'':
8724
8725@table @code
8726@kindex set confirm
8727@cindex flinching
8728@cindex confirmation
8729@cindex stupid questions
8730@item set confirm off
8731Disables confirmation requests.
8732
8733@item set confirm on
8734Enables confirmation requests (the default).
8735
8736@kindex show confirm
8737@item show confirm
8738Displays state of confirmation requests.
8739@end table
8740
53a5351d 8741@node Sequences
c906108c
SS
8742@chapter Canned Sequences of Commands
8743
8744Aside from breakpoint commands (@pxref{Break Commands, ,Breakpoint
8745command lists}), @value{GDBN} provides two ways to store sequences of commands
8746for execution as a unit: user-defined commands and command files.
8747
8748@menu
8749* Define:: User-defined commands
8750* Hooks:: User-defined command hooks
8751* Command Files:: Command files
8752* Output:: Commands for controlled output
8753@end menu
8754
53a5351d 8755@node Define
c906108c
SS
8756@section User-defined commands
8757
8758@cindex user-defined command
8759A @dfn{user-defined command} is a sequence of @value{GDBN} commands to which
8760you assign a new name as a command. This is done with the @code{define}
8761command. User commands may accept up to 10 arguments separated by whitespace.
8762Arguments are accessed within the user command via @var{$arg0@dots{}$arg9}.
8763A trivial example:
8764
8765@smallexample
8766define adder
8767 print $arg0 + $arg1 + $arg2
8768@end smallexample
8769
8770@noindent To execute the command use:
8771
8772@smallexample
8773adder 1 2 3
8774@end smallexample
8775
8776@noindent This defines the command @code{adder}, which prints the sum of
8777its three arguments. Note the arguments are text substitutions, so they may
8778reference variables, use complex expressions, or even perform inferior
8779functions calls.
8780
8781@table @code
8782@kindex define
8783@item define @var{commandname}
8784Define a command named @var{commandname}. If there is already a command
8785by that name, you are asked to confirm that you want to redefine it.
8786
8787The definition of the command is made up of other @value{GDBN} command lines,
8788which are given following the @code{define} command. The end of these
8789commands is marked by a line containing @code{end}.
8790
8791@kindex if
8792@kindex else
8793@item if
8794Takes a single argument, which is an expression to evaluate.
8795It is followed by a series of commands that are executed
8796only if the expression is true (nonzero).
8797There can then optionally be a line @code{else}, followed
8798by a series of commands that are only executed if the expression
8799was false. The end of the list is marked by a line containing @code{end}.
8800
8801@kindex while
8802@item while
8803The syntax is similar to @code{if}: the command takes a single argument,
8804which is an expression to evaluate, and must be followed by the commands to
8805execute, one per line, terminated by an @code{end}.
8806The commands are executed repeatedly as long as the expression
8807evaluates to true.
8808
8809@kindex document
8810@item document @var{commandname}
8811Document the user-defined command @var{commandname}, so that it can be
8812accessed by @code{help}. The command @var{commandname} must already be
8813defined. This command reads lines of documentation just as @code{define}
8814reads the lines of the command definition, ending with @code{end}.
8815After the @code{document} command is finished, @code{help} on command
8816@var{commandname} displays the documentation you have written.
8817
8818You may use the @code{document} command again to change the
8819documentation of a command. Redefining the command with @code{define}
8820does not change the documentation.
8821
8822@kindex help user-defined
8823@item help user-defined
8824List all user-defined commands, with the first line of the documentation
8825(if any) for each.
8826
8827@kindex show user
8828@item show user
8829@itemx show user @var{commandname}
8830Display the @value{GDBN} commands used to define @var{commandname} (but not its
8831documentation). If no @var{commandname} is given, display the
8832definitions for all user-defined commands.
8833@end table
8834
8835When user-defined commands are executed, the
8836commands of the definition are not printed. An error in any command
8837stops execution of the user-defined command.
8838
8839If used interactively, commands that would ask for confirmation proceed
8840without asking when used inside a user-defined command. Many @value{GDBN}
8841commands that normally print messages to say what they are doing omit the
8842messages when used in a user-defined command.
8843
53a5351d 8844@node Hooks
c906108c
SS
8845@section User-defined command hooks
8846@cindex command files
8847
8848You may define @emph{hooks}, which are a special kind of user-defined
8849command. Whenever you run the command @samp{foo}, if the user-defined
8850command @samp{hook-foo} exists, it is executed (with no arguments)
8851before that command.
8852
8853In addition, a pseudo-command, @samp{stop} exists. Defining
8854(@samp{hook-stop}) makes the associated commands execute every time
8855execution stops in your program: before breakpoint commands are run,
8856displays are printed, or the stack frame is printed.
8857
c906108c
SS
8858For example, to ignore @code{SIGALRM} signals while
8859single-stepping, but treat them normally during normal execution,
8860you could define:
8861
8862@example
8863define hook-stop
8864handle SIGALRM nopass
8865end
8866
8867define hook-run
8868handle SIGALRM pass
8869end
8870
8871define hook-continue
8872handle SIGLARM pass
8873end
8874@end example
c906108c
SS
8875
8876You can define a hook for any single-word command in @value{GDBN}, but
8877not for command aliases; you should define a hook for the basic command
8878name, e.g. @code{backtrace} rather than @code{bt}.
8879@c FIXME! So how does Joe User discover whether a command is an alias
8880@c or not?
8881If an error occurs during the execution of your hook, execution of
8882@value{GDBN} commands stops and @value{GDBN} issues a prompt
8883(before the command that you actually typed had a chance to run).
8884
8885If you try to define a hook which does not match any known command, you
8886get a warning from the @code{define} command.
8887
53a5351d 8888@node Command Files
c906108c
SS
8889@section Command files
8890
8891@cindex command files
8892A command file for @value{GDBN} is a file of lines that are @value{GDBN}
8893commands. Comments (lines starting with @kbd{#}) may also be included.
8894An empty line in a command file does nothing; it does not mean to repeat
8895the last command, as it would from the terminal.
8896
8897@cindex init file
8898@cindex @file{.gdbinit}
8899When you start @value{GDBN}, it automatically executes commands from its
8900@dfn{init files}. These are files named @file{.gdbinit} on Unix, or
8901@file{gdb.ini} on DOS/Windows. @value{GDBN} reads the init file (if
8902any) in your home directory, then processes command line options and
8903operands, and then reads the init file (if any) in the current working
8904directory. This is so the init file in your home directory can set
8905options (such as @code{set complaints}) which affect the processing of
8906the command line options and operands. The init files are not executed
8907if you use the @samp{-nx} option; @pxref{Mode Options, ,Choosing modes}.
8908
c906108c
SS
8909@cindex init file name
8910On some configurations of @value{GDBN}, the init file is known by a
8911different name (these are typically environments where a specialized
8912form of @value{GDBN} may need to coexist with other forms, hence a
8913different name for the specialized version's init file). These are the
8914environments with special init file names:
8915
8916@kindex .vxgdbinit
8917@itemize @bullet
8918@item
8919VxWorks (Wind River Systems real-time OS): @samp{.vxgdbinit}
8920
8921@kindex .os68gdbinit
8922@item
8923OS68K (Enea Data Systems real-time OS): @samp{.os68gdbinit}
8924
8925@kindex .esgdbinit
8926@item
8927ES-1800 (Ericsson Telecom AB M68000 emulator): @samp{.esgdbinit}
8928@end itemize
c906108c
SS
8929
8930You can also request the execution of a command file with the
8931@code{source} command:
8932
8933@table @code
8934@kindex source
8935@item source @var{filename}
8936Execute the command file @var{filename}.
8937@end table
8938
8939The lines in a command file are executed sequentially. They are not
8940printed as they are executed. An error in any command terminates execution
8941of the command file.
8942
8943Commands that would ask for confirmation if used interactively proceed
8944without asking when used in a command file. Many @value{GDBN} commands that
8945normally print messages to say what they are doing omit the messages
8946when called from command files.
8947
53a5351d 8948@node Output
c906108c
SS
8949@section Commands for controlled output
8950
8951During the execution of a command file or a user-defined command, normal
8952@value{GDBN} output is suppressed; the only output that appears is what is
8953explicitly printed by the commands in the definition. This section
8954describes three commands useful for generating exactly the output you
8955want.
8956
8957@table @code
8958@kindex echo
8959@item echo @var{text}
8960@c I do not consider backslash-space a standard C escape sequence
8961@c because it is not in ANSI.
8962Print @var{text}. Nonprinting characters can be included in
8963@var{text} using C escape sequences, such as @samp{\n} to print a
8964newline. @strong{No newline is printed unless you specify one.}
8965In addition to the standard C escape sequences, a backslash followed
8966by a space stands for a space. This is useful for displaying a
8967string with spaces at the beginning or the end, since leading and
8968trailing spaces are otherwise trimmed from all arguments.
8969To print @samp{@w{ }and foo =@w{ }}, use the command
8970@samp{echo \@w{ }and foo = \@w{ }}.
8971
8972A backslash at the end of @var{text} can be used, as in C, to continue
8973the command onto subsequent lines. For example,
8974
8975@example
8976echo This is some text\n\
8977which is continued\n\
8978onto several lines.\n
8979@end example
8980
8981produces the same output as
8982
8983@example
8984echo This is some text\n
8985echo which is continued\n
8986echo onto several lines.\n
8987@end example
8988
8989@kindex output
8990@item output @var{expression}
8991Print the value of @var{expression} and nothing but that value: no
8992newlines, no @samp{$@var{nn} = }. The value is not entered in the
8993value history either. @xref{Expressions, ,Expressions}, for more information
8994on expressions.
8995
8996@item output/@var{fmt} @var{expression}
8997Print the value of @var{expression} in format @var{fmt}. You can use
8998the same formats as for @code{print}. @xref{Output Formats,,Output
8999formats}, for more information.
9000
9001@kindex printf
9002@item printf @var{string}, @var{expressions}@dots{}
9003Print the values of the @var{expressions} under the control of
9004@var{string}. The @var{expressions} are separated by commas and may be
9005either numbers or pointers. Their values are printed as specified by
9006@var{string}, exactly as if your program were to execute the C
9007subroutine
9008
9009@example
9010printf (@var{string}, @var{expressions}@dots{});
9011@end example
9012
9013For example, you can print two values in hex like this:
9014
9015@smallexample
9016printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo
9017@end smallexample
9018
9019The only backslash-escape sequences that you can use in the format
9020string are the simple ones that consist of backslash followed by a
9021letter.
9022@end table
9023
53a5351d 9024@node Emacs
c906108c
SS
9025@chapter Using @value{GDBN} under @sc{gnu} Emacs
9026
9027@cindex Emacs
9028@cindex @sc{gnu} Emacs
9029A special interface allows you to use @sc{gnu} Emacs to view (and
9030edit) the source files for the program you are debugging with
9031@value{GDBN}.
9032
9033To use this interface, use the command @kbd{M-x gdb} in Emacs. Give the
9034executable file you want to debug as an argument. This command starts
9035@value{GDBN} as a subprocess of Emacs, with input and output through a newly
9036created Emacs buffer.
53a5351d 9037@c (Do not use the @code{-tui} option to run @value{GDBN} from Emacs.)
c906108c
SS
9038
9039Using @value{GDBN} under Emacs is just like using @value{GDBN} normally except for two
9040things:
9041
9042@itemize @bullet
9043@item
9044All ``terminal'' input and output goes through the Emacs buffer.
9045@end itemize
9046
9047This applies both to @value{GDBN} commands and their output, and to the input
9048and output done by the program you are debugging.
9049
9050This is useful because it means that you can copy the text of previous
9051commands and input them again; you can even use parts of the output
9052in this way.
9053
9054All the facilities of Emacs' Shell mode are available for interacting
9055with your program. In particular, you can send signals the usual
9056way---for example, @kbd{C-c C-c} for an interrupt, @kbd{C-c C-z} for a
9057stop.
9058
9059@itemize @bullet
9060@item
9061@value{GDBN} displays source code through Emacs.
9062@end itemize
9063
9064Each time @value{GDBN} displays a stack frame, Emacs automatically finds the
9065source file for that frame and puts an arrow (@samp{=>}) at the
9066left margin of the current line. Emacs uses a separate buffer for
9067source display, and splits the screen to show both your @value{GDBN} session
9068and the source.
9069
9070Explicit @value{GDBN} @code{list} or search commands still produce output as
9071usual, but you probably have no reason to use them from Emacs.
9072
9073@quotation
9074@emph{Warning:} If the directory where your program resides is not your
9075current directory, it can be easy to confuse Emacs about the location of
9076the source files, in which case the auxiliary display buffer does not
9077appear to show your source. @value{GDBN} can find programs by searching your
9078environment's @code{PATH} variable, so the @value{GDBN} input and output
9079session proceeds normally; but Emacs does not get enough information
9080back from @value{GDBN} to locate the source files in this situation. To
9081avoid this problem, either start @value{GDBN} mode from the directory where
9082your program resides, or specify an absolute file name when prompted for the
9083@kbd{M-x gdb} argument.
9084
9085A similar confusion can result if you use the @value{GDBN} @code{file} command to
9086switch to debugging a program in some other location, from an existing
9087@value{GDBN} buffer in Emacs.
9088@end quotation
9089
9090By default, @kbd{M-x gdb} calls the program called @file{gdb}. If
9091you need to call @value{GDBN} by a different name (for example, if you keep
9092several configurations around, with different names) you can set the
9093Emacs variable @code{gdb-command-name}; for example,
9094
9095@example
9096(setq gdb-command-name "mygdb")
9097@end example
9098
9099@noindent
9100(preceded by @kbd{ESC ESC}, or typed in the @code{*scratch*} buffer, or
9101in your @file{.emacs} file) makes Emacs call the program named
9102``@code{mygdb}'' instead.
9103
9104In the @value{GDBN} I/O buffer, you can use these special Emacs commands in
9105addition to the standard Shell mode commands:
9106
9107@table @kbd
9108@item C-h m
9109Describe the features of Emacs' @value{GDBN} Mode.
9110
9111@item M-s
9112Execute to another source line, like the @value{GDBN} @code{step} command; also
9113update the display window to show the current file and location.
9114
9115@item M-n
9116Execute to next source line in this function, skipping all function
9117calls, like the @value{GDBN} @code{next} command. Then update the display window
9118to show the current file and location.
9119
9120@item M-i
9121Execute one instruction, like the @value{GDBN} @code{stepi} command; update
9122display window accordingly.
9123
9124@item M-x gdb-nexti
9125Execute to next instruction, using the @value{GDBN} @code{nexti} command; update
9126display window accordingly.
9127
9128@item C-c C-f
9129Execute until exit from the selected stack frame, like the @value{GDBN}
9130@code{finish} command.
9131
9132@item M-c
9133Continue execution of your program, like the @value{GDBN} @code{continue}
9134command.
9135
9136@emph{Warning:} In Emacs v19, this command is @kbd{C-c C-p}.
9137
9138@item M-u
9139Go up the number of frames indicated by the numeric argument
9140(@pxref{Arguments, , Numeric Arguments, Emacs, The @sc{gnu} Emacs Manual}),
9141like the @value{GDBN} @code{up} command.
9142
9143@emph{Warning:} In Emacs v19, this command is @kbd{C-c C-u}.
9144
9145@item M-d
9146Go down the number of frames indicated by the numeric argument, like the
9147@value{GDBN} @code{down} command.
9148
9149@emph{Warning:} In Emacs v19, this command is @kbd{C-c C-d}.
9150
9151@item C-x &
9152Read the number where the cursor is positioned, and insert it at the end
9153of the @value{GDBN} I/O buffer. For example, if you wish to disassemble code
9154around an address that was displayed earlier, type @kbd{disassemble};
9155then move the cursor to the address display, and pick up the
9156argument for @code{disassemble} by typing @kbd{C-x &}.
9157
9158You can customize this further by defining elements of the list
9159@code{gdb-print-command}; once it is defined, you can format or
9160otherwise process numbers picked up by @kbd{C-x &} before they are
9161inserted. A numeric argument to @kbd{C-x &} indicates that you
9162wish special formatting, and also acts as an index to pick an element of the
9163list. If the list element is a string, the number to be inserted is
9164formatted using the Emacs function @code{format}; otherwise the number
9165is passed as an argument to the corresponding list element.
9166@end table
9167
9168In any source file, the Emacs command @kbd{C-x SPC} (@code{gdb-break})
9169tells @value{GDBN} to set a breakpoint on the source line point is on.
9170
9171If you accidentally delete the source-display buffer, an easy way to get
9172it back is to type the command @code{f} in the @value{GDBN} buffer, to
9173request a frame display; when you run under Emacs, this recreates
9174the source buffer if necessary to show you the context of the current
9175frame.
9176
9177The source files displayed in Emacs are in ordinary Emacs buffers
9178which are visiting the source files in the usual way. You can edit
9179the files with these buffers if you wish; but keep in mind that @value{GDBN}
9180communicates with Emacs in terms of line numbers. If you add or
9181delete lines from the text, the line numbers that @value{GDBN} knows cease
9182to correspond properly with the code.
9183
9184@c The following dropped because Epoch is nonstandard. Reactivate
9185@c if/when v19 does something similar. ---doc@cygnus.com 19dec1990
9186@ignore
9187@kindex Emacs Epoch environment
9188@kindex Epoch
9189@kindex inspect
9190
9191Version 18 of @sc{gnu} Emacs has a built-in window system
9192called the @code{epoch}
9193environment. Users of this environment can use a new command,
9194@code{inspect} which performs identically to @code{print} except that
9195each value is printed in its own window.
9196@end ignore
c906108c
SS
9197
9198@node GDB Bugs
c906108c
SS
9199@chapter Reporting Bugs in @value{GDBN}
9200@cindex bugs in @value{GDBN}
9201@cindex reporting bugs in @value{GDBN}
9202
9203Your bug reports play an essential role in making @value{GDBN} reliable.
9204
9205Reporting a bug may help you by bringing a solution to your problem, or it
9206may not. But in any case the principal function of a bug report is to help
9207the entire community by making the next version of @value{GDBN} work better. Bug
9208reports are your contribution to the maintenance of @value{GDBN}.
9209
9210In order for a bug report to serve its purpose, you must include the
9211information that enables us to fix the bug.
9212
9213@menu
9214* Bug Criteria:: Have you found a bug?
9215* Bug Reporting:: How to report bugs
9216@end menu
9217
53a5351d 9218@node Bug Criteria
c906108c
SS
9219@section Have you found a bug?
9220@cindex bug criteria
9221
9222If you are not sure whether you have found a bug, here are some guidelines:
9223
9224@itemize @bullet
9225@cindex fatal signal
9226@cindex debugger crash
9227@cindex crash of debugger
9228@item
9229If the debugger gets a fatal signal, for any input whatever, that is a
9230@value{GDBN} bug. Reliable debuggers never crash.
9231
9232@cindex error on valid input
9233@item
9234If @value{GDBN} produces an error message for valid input, that is a
9235bug. (Note that if you're cross debugging, the problem may also be
9236somewhere in the connection to the target.)
9237
9238@cindex invalid input
9239@item
9240If @value{GDBN} does not produce an error message for invalid input,
9241that is a bug. However, you should note that your idea of
9242``invalid input'' might be our idea of ``an extension'' or ``support
9243for traditional practice''.
9244
9245@item
9246If you are an experienced user of debugging tools, your suggestions
9247for improvement of @value{GDBN} are welcome in any case.
9248@end itemize
9249
53a5351d 9250@node Bug Reporting
c906108c
SS
9251@section How to report bugs
9252@cindex bug reports
9253@cindex @value{GDBN} bugs, reporting
9254
c906108c
SS
9255A number of companies and individuals offer support for @sc{gnu} products.
9256If you obtained @value{GDBN} from a support organization, we recommend you
9257contact that organization first.
9258
9259You can find contact information for many support companies and
9260individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs
9261distribution.
9262@c should add a web page ref...
9263
9264In any event, we also recommend that you send bug reports for
9265@value{GDBN} to this addresses:
9266
9267@example
9268bug-gdb@@prep.ai.mit.edu
9269@end example
9270
9271@strong{Do not send bug reports to @samp{info-gdb}, or to
9272@samp{help-gdb}, or to any newsgroups.} Most users of @value{GDBN} do
9273not want to receive bug reports. Those that do have arranged to receive
9274@samp{bug-gdb}.
9275
9276The mailing list @samp{bug-gdb} has a newsgroup @samp{gnu.gdb.bug} which
9277serves as a repeater. The mailing list and the newsgroup carry exactly
9278the same messages. Often people think of posting bug reports to the
9279newsgroup instead of mailing them. This appears to work, but it has one
9280problem which can be crucial: a newsgroup posting often lacks a mail
9281path back to the sender. Thus, if we need to ask for more information,
9282we may be unable to reach you. For this reason, it is better to send
9283bug reports to the mailing list.
9284
9285As a last resort, send bug reports on paper to:
9286
9287@example
9288@sc{gnu} Debugger Bugs
9289Free Software Foundation Inc.
929059 Temple Place - Suite 330
9291Boston, MA 02111-1307
9292USA
9293@end example
c906108c
SS
9294
9295The fundamental principle of reporting bugs usefully is this:
9296@strong{report all the facts}. If you are not sure whether to state a
9297fact or leave it out, state it!
9298
9299Often people omit facts because they think they know what causes the
9300problem and assume that some details do not matter. Thus, you might
9301assume that the name of the variable you use in an example does not matter.
9302Well, probably it does not, but one cannot be sure. Perhaps the bug is a
9303stray memory reference which happens to fetch from the location where that
9304name is stored in memory; perhaps, if the name were different, the contents
9305of that location would fool the debugger into doing the right thing despite
9306the bug. Play it safe and give a specific, complete example. That is the
9307easiest thing for you to do, and the most helpful.
9308
9309Keep in mind that the purpose of a bug report is to enable us to fix the
9310bug. It may be that the bug has been reported previously, but neither
9311you nor we can know that unless your bug report is complete and
9312self-contained.
9313
9314Sometimes people give a few sketchy facts and ask, ``Does this ring a
9315bell?'' Those bug reports are useless, and we urge everyone to
9316@emph{refuse to respond to them} except to chide the sender to report
9317bugs properly.
9318
9319To enable us to fix the bug, you should include all these things:
9320
9321@itemize @bullet
9322@item
9323The version of @value{GDBN}. @value{GDBN} announces it if you start
9324with no arguments; you can also print it at any time using @code{show
9325version}.
9326
9327Without this, we will not know whether there is any point in looking for
9328the bug in the current version of @value{GDBN}.
9329
9330@item
9331The type of machine you are using, and the operating system name and
9332version number.
9333
c906108c
SS
9334@item
9335What compiler (and its version) was used to compile @value{GDBN}---e.g.
9336``@value{GCC}--2.8.1''.
c906108c
SS
9337
9338@item
9339What compiler (and its version) was used to compile the program you are
9340debugging---e.g. ``@value{GCC}--2.8.1'', or ``HP92453-01 A.10.32.03 HP
9341C Compiler''. For GCC, you can say @code{gcc --version} to get this
9342information; for other compilers, see the documentation for those
9343compilers.
9344
9345@item
9346The command arguments you gave the compiler to compile your example and
9347observe the bug. For example, did you use @samp{-O}? To guarantee
9348you will not omit something important, list them all. A copy of the
9349Makefile (or the output from make) is sufficient.
9350
9351If we were to try to guess the arguments, we would probably guess wrong
9352and then we might not encounter the bug.
9353
9354@item
9355A complete input script, and all necessary source files, that will
9356reproduce the bug.
9357
9358@item
9359A description of what behavior you observe that you believe is
9360incorrect. For example, ``It gets a fatal signal.''
9361
9362Of course, if the bug is that @value{GDBN} gets a fatal signal, then we
9363will certainly notice it. But if the bug is incorrect output, we might
9364not notice unless it is glaringly wrong. You might as well not give us
9365a chance to make a mistake.
9366
9367Even if the problem you experience is a fatal signal, you should still
9368say so explicitly. Suppose something strange is going on, such as, your
9369copy of @value{GDBN} is out of synch, or you have encountered a bug in
9370the C library on your system. (This has happened!) Your copy might
9371crash and ours would not. If you told us to expect a crash, then when
9372ours fails to crash, we would know that the bug was not happening for
9373us. If you had not told us to expect a crash, then we would not be able
9374to draw any conclusion from our observations.
9375
c906108c
SS
9376@item
9377If you wish to suggest changes to the @value{GDBN} source, send us context
9378diffs. If you even discuss something in the @value{GDBN} source, refer to
9379it by context, not by line number.
9380
9381The line numbers in our development sources will not match those in your
9382sources. Your line numbers would convey no useful information to us.
53a5351d 9383
c906108c
SS
9384@end itemize
9385
9386Here are some things that are not necessary:
9387
9388@itemize @bullet
9389@item
9390A description of the envelope of the bug.
9391
9392Often people who encounter a bug spend a lot of time investigating
9393which changes to the input file will make the bug go away and which
9394changes will not affect it.
9395
9396This is often time consuming and not very useful, because the way we
9397will find the bug is by running a single example under the debugger
9398with breakpoints, not by pure deduction from a series of examples.
9399We recommend that you save your time for something else.
9400
9401Of course, if you can find a simpler example to report @emph{instead}
9402of the original one, that is a convenience for us. Errors in the
9403output will be easier to spot, running under the debugger will take
9404less time, and so on.
9405
9406However, simplification is not vital; if you do not want to do this,
9407report the bug anyway and send us the entire test case you used.
9408
9409@item
9410A patch for the bug.
9411
9412A patch for the bug does help us if it is a good one. But do not omit
9413the necessary information, such as the test case, on the assumption that
9414a patch is all we need. We might see problems with your patch and decide
9415to fix the problem another way, or we might not understand it at all.
9416
9417Sometimes with a program as complicated as @value{GDBN} it is very hard to
9418construct an example that will make the program follow a certain path
9419through the code. If you do not send us the example, we will not be able
9420to construct one, so we will not be able to verify that the bug is fixed.
9421
9422And if we cannot understand what bug you are trying to fix, or why your
9423patch should be an improvement, we will not install it. A test case will
9424help us to understand.
9425
9426@item
9427A guess about what the bug is or what it depends on.
9428
9429Such guesses are usually wrong. Even we cannot guess right about such
9430things without first using the debugger to find the facts.
9431@end itemize
9432
9433@c The readline documentation is distributed with the readline code
9434@c and consists of the two following files:
9435@c rluser.texinfo
7be570e7 9436@c inc-hist.texinfo
c906108c
SS
9437@c Use -I with makeinfo to point to the appropriate directory,
9438@c environment var TEXINPUTS with TeX.
9439@include rluser.texinfo
7be570e7 9440@include inc-hist.texinfo
c906108c
SS
9441
9442
c906108c 9443@node Formatting Documentation
c906108c
SS
9444@appendix Formatting Documentation
9445
9446@cindex @value{GDBN} reference card
9447@cindex reference card
9448The @value{GDBN} 4 release includes an already-formatted reference card, ready
9449for printing with PostScript or Ghostscript, in the @file{gdb}
9450subdirectory of the main source directory@footnote{In
9451@file{gdb-@value{GDBVN}/gdb/refcard.ps} of the version @value{GDBVN}
9452release.}. If you can use PostScript or Ghostscript with your printer,
9453you can print the reference card immediately with @file{refcard.ps}.
9454
9455The release also includes the source for the reference card. You
9456can format it, using @TeX{}, by typing:
9457
9458@example
9459make refcard.dvi
9460@end example
9461
9462The @value{GDBN} reference card is designed to print in @dfn{landscape}
9463mode on US ``letter'' size paper;
9464that is, on a sheet 11 inches wide by 8.5 inches
9465high. You will need to specify this form of printing as an option to
9466your @sc{dvi} output program.
9467
9468@cindex documentation
9469
9470All the documentation for @value{GDBN} comes as part of the machine-readable
9471distribution. The documentation is written in Texinfo format, which is
9472a documentation system that uses a single source file to produce both
9473on-line information and a printed manual. You can use one of the Info
9474formatting commands to create the on-line version of the documentation
9475and @TeX{} (or @code{texi2roff}) to typeset the printed version.
9476
9477@value{GDBN} includes an already formatted copy of the on-line Info
9478version of this manual in the @file{gdb} subdirectory. The main Info
9479file is @file{gdb-@value{GDBVN}/gdb/gdb.info}, and it refers to
9480subordinate files matching @samp{gdb.info*} in the same directory. If
9481necessary, you can print out these files, or read them with any editor;
9482but they are easier to read using the @code{info} subsystem in @sc{gnu}
9483Emacs or the standalone @code{info} program, available as part of the
9484@sc{gnu} Texinfo distribution.
9485
9486If you want to format these Info files yourself, you need one of the
9487Info formatting programs, such as @code{texinfo-format-buffer} or
9488@code{makeinfo}.
9489
9490If you have @code{makeinfo} installed, and are in the top level
9491@value{GDBN} source directory (@file{gdb-@value{GDBVN}}, in the case of
9492version @value{GDBVN}), you can make the Info file by typing:
9493
9494@example
9495cd gdb
9496make gdb.info
9497@end example
9498
9499If you want to typeset and print copies of this manual, you need @TeX{},
9500a program to print its @sc{dvi} output files, and @file{texinfo.tex}, the
9501Texinfo definitions file.
9502
9503@TeX{} is a typesetting program; it does not print files directly, but
9504produces output files called @sc{dvi} files. To print a typeset
9505document, you need a program to print @sc{dvi} files. If your system
9506has @TeX{} installed, chances are it has such a program. The precise
9507command to use depends on your system; @kbd{lpr -d} is common; another
9508(for PostScript devices) is @kbd{dvips}. The @sc{dvi} print command may
9509require a file name without any extension or a @samp{.dvi} extension.
9510
9511@TeX{} also requires a macro definitions file called
9512@file{texinfo.tex}. This file tells @TeX{} how to typeset a document
9513written in Texinfo format. On its own, @TeX{} cannot either read or
9514typeset a Texinfo file. @file{texinfo.tex} is distributed with GDB
9515and is located in the @file{gdb-@var{version-number}/texinfo}
9516directory.
9517
9518If you have @TeX{} and a @sc{dvi} printer program installed, you can
9519typeset and print this manual. First switch to the the @file{gdb}
9520subdirectory of the main source directory (for example, to
9521@file{gdb-@value{GDBVN}/gdb}) and type:
9522
9523@example
9524make gdb.dvi
9525@end example
9526
9527Then give @file{gdb.dvi} to your @sc{dvi} printing program.
c906108c 9528
53a5351d 9529@node Installing GDB
c906108c
SS
9530@appendix Installing @value{GDBN}
9531@cindex configuring @value{GDBN}
9532@cindex installation
9533
c906108c
SS
9534@value{GDBN} comes with a @code{configure} script that automates the process
9535of preparing @value{GDBN} for installation; you can then use @code{make} to
9536build the @code{gdb} program.
9537@iftex
9538@c irrelevant in info file; it's as current as the code it lives with.
9539@footnote{If you have a more recent version of @value{GDBN} than @value{GDBVN},
9540look at the @file{README} file in the sources; we may have improved the
9541installation procedures since publishing this manual.}
9542@end iftex
9543
9544The @value{GDBN} distribution includes all the source code you need for
9545@value{GDBN} in a single directory, whose name is usually composed by
9546appending the version number to @samp{gdb}.
9547
9548For example, the @value{GDBN} version @value{GDBVN} distribution is in the
9549@file{gdb-@value{GDBVN}} directory. That directory contains:
9550
9551@table @code
9552@item gdb-@value{GDBVN}/configure @r{(and supporting files)}
9553script for configuring @value{GDBN} and all its supporting libraries
9554
9555@item gdb-@value{GDBVN}/gdb
9556the source specific to @value{GDBN} itself
9557
9558@item gdb-@value{GDBVN}/bfd
9559source for the Binary File Descriptor library
9560
9561@item gdb-@value{GDBVN}/include
9562@sc{gnu} include files
9563
9564@item gdb-@value{GDBVN}/libiberty
9565source for the @samp{-liberty} free software library
9566
9567@item gdb-@value{GDBVN}/opcodes
9568source for the library of opcode tables and disassemblers
9569
9570@item gdb-@value{GDBVN}/readline
9571source for the @sc{gnu} command-line interface
9572
9573@item gdb-@value{GDBVN}/glob
9574source for the @sc{gnu} filename pattern-matching subroutine
9575
9576@item gdb-@value{GDBVN}/mmalloc
9577source for the @sc{gnu} memory-mapped malloc package
9578@end table
9579
9580The simplest way to configure and build @value{GDBN} is to run @code{configure}
9581from the @file{gdb-@var{version-number}} source directory, which in
9582this example is the @file{gdb-@value{GDBVN}} directory.
9583
9584First switch to the @file{gdb-@var{version-number}} source directory
9585if you are not already in it; then run @code{configure}. Pass the
9586identifier for the platform on which @value{GDBN} will run as an
9587argument.
9588
9589For example:
9590
9591@example
9592cd gdb-@value{GDBVN}
9593./configure @var{host}
9594make
9595@end example
9596
9597@noindent
9598where @var{host} is an identifier such as @samp{sun4} or
9599@samp{decstation}, that identifies the platform where @value{GDBN} will run.
9600(You can often leave off @var{host}; @code{configure} tries to guess the
9601correct value by examining your system.)
9602
9603Running @samp{configure @var{host}} and then running @code{make} builds the
9604@file{bfd}, @file{readline}, @file{mmalloc}, and @file{libiberty}
9605libraries, then @code{gdb} itself. The configured source files, and the
9606binaries, are left in the corresponding source directories.
9607
9608@need 750
9609@code{configure} is a Bourne-shell (@code{/bin/sh}) script; if your
9610system does not recognize this automatically when you run a different
9611shell, you may need to run @code{sh} on it explicitly:
9612
9613@example
9614sh configure @var{host}
9615@end example
9616
9617If you run @code{configure} from a directory that contains source
9618directories for multiple libraries or programs, such as the
9619@file{gdb-@value{GDBVN}} source directory for version @value{GDBVN}, @code{configure}
9620creates configuration files for every directory level underneath (unless
9621you tell it not to, with the @samp{--norecursion} option).
9622
9623You can run the @code{configure} script from any of the
9624subordinate directories in the @value{GDBN} distribution if you only want to
9625configure that subdirectory, but be sure to specify a path to it.
9626
9627For example, with version @value{GDBVN}, type the following to configure only
9628the @code{bfd} subdirectory:
9629
9630@example
9631@group
9632cd gdb-@value{GDBVN}/bfd
9633../configure @var{host}
9634@end group
9635@end example
9636
9637You can install @code{@value{GDBP}} anywhere; it has no hardwired paths.
9638However, you should make sure that the shell on your path (named by
9639the @samp{SHELL} environment variable) is publicly readable. Remember
9640that @value{GDBN} uses the shell to start your program---some systems refuse to
9641let @value{GDBN} debug child processes whose programs are not readable.
9642
9643@menu
9644* Separate Objdir:: Compiling @value{GDBN} in another directory
9645* Config Names:: Specifying names for hosts and targets
9646* Configure Options:: Summary of options for configure
9647@end menu
9648
53a5351d 9649@node Separate Objdir
c906108c
SS
9650@section Compiling @value{GDBN} in another directory
9651
9652If you want to run @value{GDBN} versions for several host or target machines,
9653you need a different @code{gdb} compiled for each combination of
9654host and target. @code{configure} is designed to make this easy by
9655allowing you to generate each configuration in a separate subdirectory,
9656rather than in the source directory. If your @code{make} program
9657handles the @samp{VPATH} feature (@sc{gnu} @code{make} does), running
9658@code{make} in each of these directories builds the @code{gdb}
9659program specified there.
9660
9661To build @code{gdb} in a separate directory, run @code{configure}
9662with the @samp{--srcdir} option to specify where to find the source.
9663(You also need to specify a path to find @code{configure}
9664itself from your working directory. If the path to @code{configure}
9665would be the same as the argument to @samp{--srcdir}, you can leave out
9666the @samp{--srcdir} option; it is assumed.)
9667
9668For example, with version @value{GDBVN}, you can build @value{GDBN} in a
9669separate directory for a Sun 4 like this:
9670
9671@example
9672@group
9673cd gdb-@value{GDBVN}
9674mkdir ../gdb-sun4
9675cd ../gdb-sun4
9676../gdb-@value{GDBVN}/configure sun4
9677make
9678@end group
9679@end example
9680
9681When @code{configure} builds a configuration using a remote source
9682directory, it creates a tree for the binaries with the same structure
9683(and using the same names) as the tree under the source directory. In
9684the example, you'd find the Sun 4 library @file{libiberty.a} in the
9685directory @file{gdb-sun4/libiberty}, and @value{GDBN} itself in
9686@file{gdb-sun4/gdb}.
9687
9688One popular reason to build several @value{GDBN} configurations in separate
9689directories is to configure @value{GDBN} for cross-compiling (where
9690@value{GDBN} runs on one machine---the @dfn{host}---while debugging
9691programs that run on another machine---the @dfn{target}).
9692You specify a cross-debugging target by
9693giving the @samp{--target=@var{target}} option to @code{configure}.
9694
9695When you run @code{make} to build a program or library, you must run
9696it in a configured directory---whatever directory you were in when you
9697called @code{configure} (or one of its subdirectories).
9698
9699The @code{Makefile} that @code{configure} generates in each source
9700directory also runs recursively. If you type @code{make} in a source
9701directory such as @file{gdb-@value{GDBVN}} (or in a separate configured
9702directory configured with @samp{--srcdir=@var{dirname}/gdb-@value{GDBVN}}), you
9703will build all the required libraries, and then build GDB.
9704
9705When you have multiple hosts or targets configured in separate
9706directories, you can run @code{make} on them in parallel (for example,
9707if they are NFS-mounted on each of the hosts); they will not interfere
9708with each other.
9709
53a5351d 9710@node Config Names
c906108c
SS
9711@section Specifying names for hosts and targets
9712
9713The specifications used for hosts and targets in the @code{configure}
9714script are based on a three-part naming scheme, but some short predefined
9715aliases are also supported. The full naming scheme encodes three pieces
9716of information in the following pattern:
9717
9718@example
9719@var{architecture}-@var{vendor}-@var{os}
9720@end example
9721
9722For example, you can use the alias @code{sun4} as a @var{host} argument,
9723or as the value for @var{target} in a @code{--target=@var{target}}
9724option. The equivalent full name is @samp{sparc-sun-sunos4}.
9725
9726The @code{configure} script accompanying @value{GDBN} does not provide
9727any query facility to list all supported host and target names or
9728aliases. @code{configure} calls the Bourne shell script
9729@code{config.sub} to map abbreviations to full names; you can read the
9730script, if you wish, or you can use it to test your guesses on
9731abbreviations---for example:
9732
9733@smallexample
9734% sh config.sub i386-linux
9735i386-pc-linux-gnu
9736% sh config.sub alpha-linux
9737alpha-unknown-linux-gnu
9738% sh config.sub hp9k700
9739hppa1.1-hp-hpux
9740% sh config.sub sun4
9741sparc-sun-sunos4.1.1
9742% sh config.sub sun3
9743m68k-sun-sunos4.1.1
9744% sh config.sub i986v
9745Invalid configuration `i986v': machine `i986v' not recognized
9746@end smallexample
9747
9748@noindent
9749@code{config.sub} is also distributed in the @value{GDBN} source
9750directory (@file{gdb-@value{GDBVN}}, for version @value{GDBVN}).
9751
53a5351d 9752@node Configure Options
c906108c
SS
9753@section @code{configure} options
9754
9755Here is a summary of the @code{configure} options and arguments that
9756are most often useful for building @value{GDBN}. @code{configure} also has
9757several other options not listed here. @inforef{What Configure
9758Does,,configure.info}, for a full explanation of @code{configure}.
9759
9760@example
9761configure @r{[}--help@r{]}
9762 @r{[}--prefix=@var{dir}@r{]}
9763 @r{[}--exec-prefix=@var{dir}@r{]}
9764 @r{[}--srcdir=@var{dirname}@r{]}
9765 @r{[}--norecursion@r{]} @r{[}--rm@r{]}
9766 @r{[}--target=@var{target}@r{]}
9767 @var{host}
9768@end example
9769
9770@noindent
9771You may introduce options with a single @samp{-} rather than
9772@samp{--} if you prefer; but you may abbreviate option names if you use
9773@samp{--}.
9774
9775@table @code
9776@item --help
9777Display a quick summary of how to invoke @code{configure}.
9778
9779@item --prefix=@var{dir}
9780Configure the source to install programs and files under directory
9781@file{@var{dir}}.
9782
9783@item --exec-prefix=@var{dir}
9784Configure the source to install programs under directory
9785@file{@var{dir}}.
9786
9787@c avoid splitting the warning from the explanation:
9788@need 2000
9789@item --srcdir=@var{dirname}
9790@strong{Warning: using this option requires @sc{gnu} @code{make}, or another
9791@code{make} that implements the @code{VPATH} feature.}@*
9792Use this option to make configurations in directories separate from the
9793@value{GDBN} source directories. Among other things, you can use this to
9794build (or maintain) several configurations simultaneously, in separate
9795directories. @code{configure} writes configuration specific files in
9796the current directory, but arranges for them to use the source in the
9797directory @var{dirname}. @code{configure} creates directories under
9798the working directory in parallel to the source directories below
9799@var{dirname}.
9800
9801@item --norecursion
9802Configure only the directory level where @code{configure} is executed; do not
9803propagate configuration to subdirectories.
9804
9805@item --target=@var{target}
9806Configure @value{GDBN} for cross-debugging programs running on the specified
9807@var{target}. Without this option, @value{GDBN} is configured to debug
9808programs that run on the same machine (@var{host}) as @value{GDBN} itself.
9809
9810There is no convenient way to generate a list of all available targets.
9811
9812@item @var{host} @dots{}
9813Configure @value{GDBN} to run on the specified @var{host}.
9814
9815There is no convenient way to generate a list of all available hosts.
9816@end table
9817
9818There are many other options available as well, but they are generally
9819needed for special purposes only.
c906108c 9820
53a5351d 9821@node Index
c906108c
SS
9822@unnumbered Index
9823
9824@printindex cp
9825
9826@tex
9827% I think something like @colophon should be in texinfo. In the
9828% meantime:
9829\long\def\colophon{\hbox to0pt{}\vfill
9830\centerline{The body of this manual is set in}
9831\centerline{\fontname\tenrm,}
9832\centerline{with headings in {\bf\fontname\tenbf}}
9833\centerline{and examples in {\tt\fontname\tentt}.}
9834\centerline{{\it\fontname\tenit\/},}
9835\centerline{{\bf\fontname\tenbf}, and}
9836\centerline{{\sl\fontname\tensl\/}}
9837\centerline{are used for emphasis.}\vfill}
9838\page\colophon
9839% Blame: doc@cygnus.com, 1991.
9840@end tex
9841
9842@contents
9843@bye