]> Git Repo - binutils.git/blame - gdb/doc/gdb.texinfo
Enable new thread support for Linux/IA-64.
[binutils.git] / gdb / doc / gdb.texinfo
CommitLineData
c906108c 1\input texinfo @c -*-texinfo-*-
29e57380 2@c Copyright 1988-2001
c906108c
SS
3@c Free Software Foundation, Inc.
4@c
5d161b24 5@c %**start of header
c906108c
SS
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
41afff9a 24@c readline appendices use @vindex, @findex and @ftable,
48e934c6 25@c annotate.texi and gdbmi use @findex.
c906108c 26@syncodeindex vr cp
41afff9a 27@syncodeindex fn cp
c906108c
SS
28
29@c !!set GDB manual's edition---not the same as GDB version!
6d2ebf8b 30@set EDITION Eighth
c906108c
SS
31
32@c !!set GDB manual's revision date
6d2ebf8b 33@set DATE March 2000
c906108c 34
6d2ebf8b 35@c THIS MANUAL REQUIRES TEXINFO 3.12 OR LATER.
c906108c 36
c906108c 37@c This is a dir.info fragment to support semi-automated addition of
6d2ebf8b 38@c manuals to an info tree.
96a2c332
SS
39@dircategory Programming & development tools.
40@direntry
c906108c 41* Gdb: (gdb). The @sc{gnu} debugger.
96a2c332
SS
42@end direntry
43
c906108c
SS
44@ifinfo
45This file documents the @sc{gnu} debugger @value{GDBN}.
46
47
5d161b24 48This is the @value{EDITION} Edition, @value{DATE},
c906108c
SS
49of @cite{Debugging with @value{GDBN}: the @sc{gnu} Source-Level Debugger}
50for @value{GDBN} Version @value{GDBVN}.
51
6d2ebf8b 52Copyright (C) 1988-2000 Free Software Foundation, Inc.
c906108c
SS
53
54Permission is granted to make and distribute verbatim copies of
55this manual provided the copyright notice and this permission notice
56are preserved on all copies.
57
58@ignore
59Permission is granted to process this file through TeX and print the
60results, provided the printed document carries copying permission
61notice identical to this one except for the removal of this paragraph
62(this paragraph not being relevant to the printed manual).
63
64@end ignore
65Permission is granted to copy and distribute modified versions of this
66manual under the conditions for verbatim copying, provided also that the
67entire resulting derived work is distributed under the terms of a
68permission notice identical to this one.
69
70Permission is granted to copy and distribute translations of this manual
71into another language, under the above conditions for modified versions.
72@end ifinfo
73
74@titlepage
75@title Debugging with @value{GDBN}
76@subtitle The @sc{gnu} Source-Level Debugger
c906108c 77@sp 1
c906108c
SS
78@subtitle @value{EDITION} Edition, for @value{GDBN} version @value{GDBVN}
79@subtitle @value{DATE}
9e9c5ae7 80@author Richard Stallman, Roland Pesch, Stan Shebs, et al.
c906108c 81@page
c906108c
SS
82@tex
83{\parskip=0pt
53a5351d 84\hfill (Send bugs and comments on @value{GDBN} to bug-gdb\@gnu.org.)\par
c906108c
SS
85\hfill {\it Debugging with @value{GDBN}}\par
86\hfill \TeX{}info \texinfoversion\par
87}
88@end tex
53a5351d 89
c906108c 90@vskip 0pt plus 1filll
6d2ebf8b 91Copyright @copyright{} 1988-2000 Free Software Foundation, Inc.
c906108c 92@sp 2
c906108c
SS
93Published by the Free Software Foundation @*
9459 Temple Place - Suite 330, @*
95Boston, MA 02111-1307 USA @*
6d2ebf8b
SS
96ISBN 1-882114-77-9 @*
97
c906108c
SS
98Permission is granted to make and distribute verbatim copies of
99this manual provided the copyright notice and this permission notice
100are preserved on all copies.
101
102Permission is granted to copy and distribute modified versions of this
103manual under the conditions for verbatim copying, provided also that the
104entire resulting derived work is distributed under the terms of a
105permission notice identical to this one.
106
107Permission is granted to copy and distribute translations of this manual
108into another language, under the above conditions for modified versions.
109@end titlepage
110@page
111
b9deaee7 112@ifinfo
6d2ebf8b
SS
113@node Top, Summary, (dir), (dir)
114
c906108c
SS
115@top Debugging with @value{GDBN}
116
117This file describes @value{GDBN}, the @sc{gnu} symbolic debugger.
118
5d161b24 119This is the @value{EDITION} Edition, @value{DATE}, for @value{GDBN} Version
c906108c
SS
120@value{GDBVN}.
121
6d2ebf8b
SS
122Copyright (C) 1988-2000 Free Software Foundation, Inc.
123
124@menu
125* Summary:: Summary of @value{GDBN}
126* Sample Session:: A sample @value{GDBN} session
127
128* Invocation:: Getting in and out of @value{GDBN}
129* Commands:: @value{GDBN} commands
130* Running:: Running programs under @value{GDBN}
131* Stopping:: Stopping and continuing
132* Stack:: Examining the stack
133* Source:: Examining source files
134* Data:: Examining data
135
136* Languages:: Using @value{GDBN} with different languages
137
138* Symbols:: Examining the symbol table
139* Altering:: Altering execution
140* GDB Files:: @value{GDBN} files
141* Targets:: Specifying a debugging target
142* Configurations:: Configuration-specific information
143* Controlling GDB:: Controlling @value{GDBN}
144* Sequences:: Canned sequences of commands
145* Emacs:: Using @value{GDBN} under @sc{gnu} Emacs
146* Annotations:: @value{GDBN}'s annotation interface.
7162c0ca 147* GDB/MI:: @value{GDBN}'s Machine Interface.
6d2ebf8b
SS
148
149* GDB Bugs:: Reporting bugs in @value{GDBN}
150* Formatting Documentation:: How to format and print @value{GDBN} documentation
151
152* Command Line Editing:: Command Line Editing
153* Using History Interactively:: Using History Interactively
154* Installing GDB:: Installing GDB
155* Index:: Index
156@end menu
157
b9deaee7 158@end ifinfo
6d2ebf8b
SS
159
160@c the replication sucks, but this avoids a texinfo 3.12 lameness
161
162@ifhtml
163@node Top
164
165@top Debugging with @value{GDBN}
166
167This file describes @value{GDBN}, the @sc{gnu} symbolic debugger.
168
169This is the @value{EDITION} Edition, @value{DATE}, for @value{GDBN} Version
170@value{GDBVN}.
171
172Copyright (C) 1988-2000 Free Software Foundation, Inc.
173
c906108c
SS
174@menu
175* Summary:: Summary of @value{GDBN}
c906108c 176* Sample Session:: A sample @value{GDBN} session
c906108c
SS
177
178* Invocation:: Getting in and out of @value{GDBN}
179* Commands:: @value{GDBN} commands
180* Running:: Running programs under @value{GDBN}
181* Stopping:: Stopping and continuing
182* Stack:: Examining the stack
183* Source:: Examining source files
184* Data:: Examining data
c906108c 185
7a292a7a 186* Languages:: Using @value{GDBN} with different languages
c906108c
SS
187
188* Symbols:: Examining the symbol table
189* Altering:: Altering execution
190* GDB Files:: @value{GDBN} files
191* Targets:: Specifying a debugging target
104c1213 192* Configurations:: Configuration-specific information
c906108c
SS
193* Controlling GDB:: Controlling @value{GDBN}
194* Sequences:: Canned sequences of commands
c906108c 195* Emacs:: Using @value{GDBN} under @sc{gnu} Emacs
6d2ebf8b 196* Annotations:: @value{GDBN}'s annotation interface.
c906108c
SS
197
198* GDB Bugs:: Reporting bugs in @value{GDBN}
c906108c 199* Formatting Documentation:: How to format and print @value{GDBN} documentation
c906108c
SS
200
201* Command Line Editing:: Command Line Editing
202* Using History Interactively:: Using History Interactively
203* Installing GDB:: Installing GDB
204* Index:: Index
c906108c
SS
205@end menu
206
6d2ebf8b
SS
207@end ifhtml
208
449f3b6c
AC
209@c TeX can handle the contents at the start but makeinfo 3.12 can not
210@iftex
211@contents
212@end iftex
213
6d2ebf8b 214@node Summary
c906108c
SS
215@unnumbered Summary of @value{GDBN}
216
217The purpose of a debugger such as @value{GDBN} is to allow you to see what is
218going on ``inside'' another program while it executes---or what another
219program was doing at the moment it crashed.
220
221@value{GDBN} can do four main kinds of things (plus other things in support of
222these) to help you catch bugs in the act:
223
224@itemize @bullet
225@item
226Start your program, specifying anything that might affect its behavior.
227
228@item
229Make your program stop on specified conditions.
230
231@item
232Examine what has happened, when your program has stopped.
233
234@item
235Change things in your program, so you can experiment with correcting the
236effects of one bug and go on to learn about another.
237@end itemize
238
cce74817 239You can use @value{GDBN} to debug programs written in C and C++.
c906108c 240For more information, see @ref{Support,,Supported languages}.
c906108c
SS
241For more information, see @ref{C,,C and C++}.
242
cce74817
JM
243@cindex Chill
244@cindex Modula-2
c906108c 245Support for Modula-2 and Chill is partial. For information on Modula-2,
cce74817 246see @ref{Modula-2,,Modula-2}. For information on Chill, see @ref{Chill}.
c906108c 247
cce74817
JM
248@cindex Pascal
249Debugging Pascal programs which use sets, subranges, file variables, or
250nested functions does not currently work. @value{GDBN} does not support
251entering expressions, printing values, or similar features using Pascal
252syntax.
c906108c 253
c906108c
SS
254@cindex Fortran
255@value{GDBN} can be used to debug programs written in Fortran, although
53a5351d 256it may be necessary to refer to some variables with a trailing
cce74817 257underscore.
c906108c 258
c906108c
SS
259@menu
260* Free Software:: Freely redistributable software
261* Contributors:: Contributors to GDB
262@end menu
263
6d2ebf8b 264@node Free Software
c906108c
SS
265@unnumberedsec Free software
266
5d161b24 267@value{GDBN} is @dfn{free software}, protected by the @sc{gnu}
c906108c
SS
268General Public License
269(GPL). The GPL gives you the freedom to copy or adapt a licensed
270program---but every person getting a copy also gets with it the
271freedom to modify that copy (which means that they must get access to
272the source code), and the freedom to distribute further copies.
273Typical software companies use copyrights to limit your freedoms; the
274Free Software Foundation uses the GPL to preserve these freedoms.
275
276Fundamentally, the General Public License is a license which says that
277you have these freedoms and that you cannot take these freedoms away
278from anyone else.
279
6d2ebf8b 280@node Contributors
96a2c332
SS
281@unnumberedsec Contributors to @value{GDBN}
282
283Richard Stallman was the original author of @value{GDBN}, and of many
284other @sc{gnu} programs. Many others have contributed to its
285development. This section attempts to credit major contributors. One
286of the virtues of free software is that everyone is free to contribute
287to it; with regret, we cannot actually acknowledge everyone here. The
288file @file{ChangeLog} in the @value{GDBN} distribution approximates a
c906108c
SS
289blow-by-blow account.
290
291Changes much prior to version 2.0 are lost in the mists of time.
292
293@quotation
294@emph{Plea:} Additions to this section are particularly welcome. If you
295or your friends (or enemies, to be evenhanded) have been unfairly
296omitted from this list, we would like to add your names!
297@end quotation
298
299So that they may not regard their many labors as thankless, we
300particularly thank those who shepherded @value{GDBN} through major
301releases:
8c70017b 302Andrew Cagney (release 5.0);
c906108c
SS
303Jim Blandy (release 4.18);
304Jason Molenda (release 4.17);
305Stan Shebs (release 4.14);
306Fred Fish (releases 4.16, 4.15, 4.13, 4.12, 4.11, 4.10, and 4.9);
307Stu Grossman and John Gilmore (releases 4.8, 4.7, 4.6, 4.5, and 4.4);
308John Gilmore (releases 4.3, 4.2, 4.1, 4.0, and 3.9);
309Jim Kingdon (releases 3.5, 3.4, and 3.3);
310and Randy Smith (releases 3.2, 3.1, and 3.0).
311
312Richard Stallman, assisted at various times by Peter TerMaat, Chris
313Hanson, and Richard Mlynarik, handled releases through 2.8.
314
96a2c332
SS
315Michael Tiemann is the author of most of the @sc{gnu} C++ support in
316@value{GDBN}, with significant additional contributions from Per
317Bothner. James Clark wrote the @sc{gnu} C++ demangler. Early work on
318C++ was by Peter TerMaat (who also did much general update work leading
319to release 3.0).
c906108c
SS
320
321@value{GDBN} 4 uses the BFD subroutine library to examine multiple
322object-file formats; BFD was a joint project of David V.
323Henkel-Wallace, Rich Pixley, Steve Chamberlain, and John Gilmore.
324
325David Johnson wrote the original COFF support; Pace Willison did
326the original support for encapsulated COFF.
327
96c405b3 328Brent Benson of Harris Computer Systems contributed DWARF2 support.
c906108c
SS
329
330Adam de Boor and Bradley Davis contributed the ISI Optimum V support.
331Per Bothner, Noboyuki Hikichi, and Alessandro Forin contributed MIPS
332support.
333Jean-Daniel Fekete contributed Sun 386i support.
334Chris Hanson improved the HP9000 support.
335Noboyuki Hikichi and Tomoyuki Hasei contributed Sony/News OS 3 support.
336David Johnson contributed Encore Umax support.
337Jyrki Kuoppala contributed Altos 3068 support.
338Jeff Law contributed HP PA and SOM support.
339Keith Packard contributed NS32K support.
340Doug Rabson contributed Acorn Risc Machine support.
341Bob Rusk contributed Harris Nighthawk CX-UX support.
342Chris Smith contributed Convex support (and Fortran debugging).
343Jonathan Stone contributed Pyramid support.
344Michael Tiemann contributed SPARC support.
345Tim Tucker contributed support for the Gould NP1 and Gould Powernode.
346Pace Willison contributed Intel 386 support.
347Jay Vosburgh contributed Symmetry support.
348
349Andreas Schwab contributed M68K Linux support.
350
351Rich Schaefer and Peter Schauer helped with support of SunOS shared
352libraries.
353
354Jay Fenlason and Roland McGrath ensured that @value{GDBN} and GAS agree
355about several machine instruction sets.
356
357Patrick Duval, Ted Goldstein, Vikram Koka and Glenn Engel helped develop
358remote debugging. Intel Corporation, Wind River Systems, AMD, and ARM
359contributed remote debugging modules for the i960, VxWorks, A29K UDI,
360and RDI targets, respectively.
361
362Brian Fox is the author of the readline libraries providing
363command-line editing and command history.
364
7a292a7a
SS
365Andrew Beers of SUNY Buffalo wrote the language-switching code, the
366Modula-2 support, and contributed the Languages chapter of this manual.
c906108c 367
5d161b24 368Fred Fish wrote most of the support for Unix System Vr4.
c906108c
SS
369He also enhanced the command-completion support to cover C++ overloaded
370symbols.
c906108c
SS
371
372Hitachi America, Ltd. sponsored the support for H8/300, H8/500, and
373Super-H processors.
374
375NEC sponsored the support for the v850, Vr4xxx, and Vr5xxx processors.
376
377Mitsubishi sponsored the support for D10V, D30V, and M32R/D processors.
378
379Toshiba sponsored the support for the TX39 Mips processor.
380
381Matsushita sponsored the support for the MN10200 and MN10300 processors.
382
96a2c332 383Fujitsu sponsored the support for SPARClite and FR30 processors.
c906108c
SS
384
385Kung Hsu, Jeff Law, and Rick Sladkey added support for hardware
386watchpoints.
387
388Michael Snyder added support for tracepoints.
389
390Stu Grossman wrote gdbserver.
391
392Jim Kingdon, Peter Schauer, Ian Taylor, and Stu Grossman made
96a2c332 393nearly innumerable bug fixes and cleanups throughout @value{GDBN}.
c906108c
SS
394
395The following people at the Hewlett-Packard Company contributed
396support for the PA-RISC 2.0 architecture, HP-UX 10.20, 10.30, and 11.0
397(narrow mode), HP's implementation of kernel threads, HP's aC++
398compiler, and the terminal user interface: Ben Krepp, Richard Title,
399John Bishop, Susan Macchia, Kathy Mann, Satish Pai, India Paul, Steve
400Rehrauer, and Elena Zannoni. Kim Haase provided HP-specific
401information in this manual.
402
96a2c332
SS
403Cygnus Solutions has sponsored @value{GDBN} maintenance and much of its
404development since 1991. Cygnus engineers who have worked on @value{GDBN}
2df3850c
JM
405fulltime include Mark Alexander, Jim Blandy, Per Bothner, Kevin
406Buettner, Edith Epstein, Chris Faylor, Fred Fish, Martin Hunt, Jim
407Ingham, John Gilmore, Stu Grossman, Kung Hsu, Jim Kingdon, John Metzler,
408Fernando Nasser, Geoffrey Noer, Dawn Perchik, Rich Pixley, Zdenek
409Radouch, Keith Seitz, Stan Shebs, David Taylor, and Elena Zannoni. In
410addition, Dave Brolley, Ian Carmichael, Steve Chamberlain, Nick Clifton,
411JT Conklin, Stan Cox, DJ Delorie, Ulrich Drepper, Frank Eigler, Doug
412Evans, Sean Fagan, David Henkel-Wallace, Richard Henderson, Jeff
413Holcomb, Jeff Law, Jim Lemke, Tom Lord, Bob Manson, Michael Meissner,
414Jason Merrill, Catherine Moore, Drew Moseley, Ken Raeburn, Gavin
415Romig-Koch, Rob Savoye, Jamie Smith, Mike Stump, Ian Taylor, Angela
416Thomas, Michael Tiemann, Tom Tromey, Ron Unrau, Jim Wilson, and David
417Zuhn have made contributions both large and small.
c906108c
SS
418
419
6d2ebf8b 420@node Sample Session
c906108c
SS
421@chapter A Sample @value{GDBN} Session
422
423You can use this manual at your leisure to read all about @value{GDBN}.
424However, a handful of commands are enough to get started using the
425debugger. This chapter illustrates those commands.
426
427@iftex
428In this sample session, we emphasize user input like this: @b{input},
429to make it easier to pick out from the surrounding output.
430@end iftex
431
432@c FIXME: this example may not be appropriate for some configs, where
433@c FIXME...primary interest is in remote use.
434
435One of the preliminary versions of @sc{gnu} @code{m4} (a generic macro
436processor) exhibits the following bug: sometimes, when we change its
437quote strings from the default, the commands used to capture one macro
438definition within another stop working. In the following short @code{m4}
439session, we define a macro @code{foo} which expands to @code{0000}; we
440then use the @code{m4} built-in @code{defn} to define @code{bar} as the
441same thing. However, when we change the open quote string to
442@code{<QUOTE>} and the close quote string to @code{<UNQUOTE>}, the same
443procedure fails to define a new synonym @code{baz}:
444
445@smallexample
446$ @b{cd gnu/m4}
447$ @b{./m4}
448@b{define(foo,0000)}
449
450@b{foo}
4510000
452@b{define(bar,defn(`foo'))}
453
454@b{bar}
4550000
456@b{changequote(<QUOTE>,<UNQUOTE>)}
457
458@b{define(baz,defn(<QUOTE>foo<UNQUOTE>))}
459@b{baz}
460@b{C-d}
461m4: End of input: 0: fatal error: EOF in string
462@end smallexample
463
464@noindent
465Let us use @value{GDBN} to try to see what is going on.
466
c906108c
SS
467@smallexample
468$ @b{@value{GDBP} m4}
469@c FIXME: this falsifies the exact text played out, to permit smallbook
470@c FIXME... format to come out better.
471@value{GDBN} is free software and you are welcome to distribute copies
5d161b24 472 of it under certain conditions; type "show copying" to see
c906108c 473 the conditions.
5d161b24 474There is absolutely no warranty for @value{GDBN}; type "show warranty"
c906108c
SS
475 for details.
476
477@value{GDBN} @value{GDBVN}, Copyright 1999 Free Software Foundation, Inc...
478(@value{GDBP})
479@end smallexample
c906108c
SS
480
481@noindent
482@value{GDBN} reads only enough symbol data to know where to find the
483rest when needed; as a result, the first prompt comes up very quickly.
484We now tell @value{GDBN} to use a narrower display width than usual, so
485that examples fit in this manual.
486
487@smallexample
488(@value{GDBP}) @b{set width 70}
489@end smallexample
490
491@noindent
492We need to see how the @code{m4} built-in @code{changequote} works.
493Having looked at the source, we know the relevant subroutine is
494@code{m4_changequote}, so we set a breakpoint there with the @value{GDBN}
495@code{break} command.
496
497@smallexample
498(@value{GDBP}) @b{break m4_changequote}
499Breakpoint 1 at 0x62f4: file builtin.c, line 879.
500@end smallexample
501
502@noindent
503Using the @code{run} command, we start @code{m4} running under @value{GDBN}
504control; as long as control does not reach the @code{m4_changequote}
505subroutine, the program runs as usual:
506
507@smallexample
508(@value{GDBP}) @b{run}
509Starting program: /work/Editorial/gdb/gnu/m4/m4
510@b{define(foo,0000)}
511
512@b{foo}
5130000
514@end smallexample
515
516@noindent
517To trigger the breakpoint, we call @code{changequote}. @value{GDBN}
518suspends execution of @code{m4}, displaying information about the
519context where it stops.
520
521@smallexample
522@b{changequote(<QUOTE>,<UNQUOTE>)}
523
5d161b24 524Breakpoint 1, m4_changequote (argc=3, argv=0x33c70)
c906108c
SS
525 at builtin.c:879
526879 if (bad_argc(TOKEN_DATA_TEXT(argv[0]),argc,1,3))
527@end smallexample
528
529@noindent
530Now we use the command @code{n} (@code{next}) to advance execution to
531the next line of the current function.
532
533@smallexample
534(@value{GDBP}) @b{n}
535882 set_quotes((argc >= 2) ? TOKEN_DATA_TEXT(argv[1])\
536 : nil,
537@end smallexample
538
539@noindent
540@code{set_quotes} looks like a promising subroutine. We can go into it
541by using the command @code{s} (@code{step}) instead of @code{next}.
542@code{step} goes to the next line to be executed in @emph{any}
543subroutine, so it steps into @code{set_quotes}.
544
545@smallexample
546(@value{GDBP}) @b{s}
547set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>")
548 at input.c:530
549530 if (lquote != def_lquote)
550@end smallexample
551
552@noindent
553The display that shows the subroutine where @code{m4} is now
554suspended (and its arguments) is called a stack frame display. It
555shows a summary of the stack. We can use the @code{backtrace}
556command (which can also be spelled @code{bt}), to see where we are
557in the stack as a whole: the @code{backtrace} command displays a
558stack frame for each active subroutine.
559
560@smallexample
561(@value{GDBP}) @b{bt}
562#0 set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>")
563 at input.c:530
5d161b24 564#1 0x6344 in m4_changequote (argc=3, argv=0x33c70)
c906108c
SS
565 at builtin.c:882
566#2 0x8174 in expand_macro (sym=0x33320) at macro.c:242
567#3 0x7a88 in expand_token (obs=0x0, t=209696, td=0xf7fffa30)
568 at macro.c:71
569#4 0x79dc in expand_input () at macro.c:40
570#5 0x2930 in main (argc=0, argv=0xf7fffb20) at m4.c:195
571@end smallexample
572
573@noindent
574We step through a few more lines to see what happens. The first two
575times, we can use @samp{s}; the next two times we use @code{n} to avoid
576falling into the @code{xstrdup} subroutine.
577
578@smallexample
579(@value{GDBP}) @b{s}
5800x3b5c 532 if (rquote != def_rquote)
581(@value{GDBP}) @b{s}
5820x3b80 535 lquote = (lq == nil || *lq == '\0') ? \
583def_lquote : xstrdup(lq);
584(@value{GDBP}) @b{n}
585536 rquote = (rq == nil || *rq == '\0') ? def_rquote\
586 : xstrdup(rq);
587(@value{GDBP}) @b{n}
588538 len_lquote = strlen(rquote);
589@end smallexample
590
591@noindent
592The last line displayed looks a little odd; we can examine the variables
593@code{lquote} and @code{rquote} to see if they are in fact the new left
594and right quotes we specified. We use the command @code{p}
595(@code{print}) to see their values.
596
597@smallexample
598(@value{GDBP}) @b{p lquote}
599$1 = 0x35d40 "<QUOTE>"
600(@value{GDBP}) @b{p rquote}
601$2 = 0x35d50 "<UNQUOTE>"
602@end smallexample
603
604@noindent
605@code{lquote} and @code{rquote} are indeed the new left and right quotes.
606To look at some context, we can display ten lines of source
607surrounding the current line with the @code{l} (@code{list}) command.
608
609@smallexample
610(@value{GDBP}) @b{l}
611533 xfree(rquote);
612534
613535 lquote = (lq == nil || *lq == '\0') ? def_lquote\
614 : xstrdup (lq);
615536 rquote = (rq == nil || *rq == '\0') ? def_rquote\
616 : xstrdup (rq);
617537
618538 len_lquote = strlen(rquote);
619539 len_rquote = strlen(lquote);
620540 @}
621541
622542 void
623@end smallexample
624
625@noindent
626Let us step past the two lines that set @code{len_lquote} and
627@code{len_rquote}, and then examine the values of those variables.
628
629@smallexample
630(@value{GDBP}) @b{n}
631539 len_rquote = strlen(lquote);
632(@value{GDBP}) @b{n}
633540 @}
634(@value{GDBP}) @b{p len_lquote}
635$3 = 9
636(@value{GDBP}) @b{p len_rquote}
637$4 = 7
638@end smallexample
639
640@noindent
641That certainly looks wrong, assuming @code{len_lquote} and
642@code{len_rquote} are meant to be the lengths of @code{lquote} and
643@code{rquote} respectively. We can set them to better values using
644the @code{p} command, since it can print the value of
645any expression---and that expression can include subroutine calls and
646assignments.
647
648@smallexample
649(@value{GDBP}) @b{p len_lquote=strlen(lquote)}
650$5 = 7
651(@value{GDBP}) @b{p len_rquote=strlen(rquote)}
652$6 = 9
653@end smallexample
654
655@noindent
656Is that enough to fix the problem of using the new quotes with the
657@code{m4} built-in @code{defn}? We can allow @code{m4} to continue
658executing with the @code{c} (@code{continue}) command, and then try the
659example that caused trouble initially:
660
661@smallexample
662(@value{GDBP}) @b{c}
663Continuing.
664
665@b{define(baz,defn(<QUOTE>foo<UNQUOTE>))}
666
667baz
6680000
669@end smallexample
670
671@noindent
672Success! The new quotes now work just as well as the default ones. The
673problem seems to have been just the two typos defining the wrong
674lengths. We allow @code{m4} exit by giving it an EOF as input:
675
676@smallexample
677@b{C-d}
678Program exited normally.
679@end smallexample
680
681@noindent
682The message @samp{Program exited normally.} is from @value{GDBN}; it
683indicates @code{m4} has finished executing. We can end our @value{GDBN}
684session with the @value{GDBN} @code{quit} command.
685
686@smallexample
687(@value{GDBP}) @b{quit}
688@end smallexample
c906108c 689
6d2ebf8b 690@node Invocation
c906108c
SS
691@chapter Getting In and Out of @value{GDBN}
692
693This chapter discusses how to start @value{GDBN}, and how to get out of it.
5d161b24 694The essentials are:
c906108c 695@itemize @bullet
5d161b24 696@item
53a5351d 697type @samp{@value{GDBP}} to start @value{GDBN}.
5d161b24 698@item
c906108c
SS
699type @kbd{quit} or @kbd{C-d} to exit.
700@end itemize
701
702@menu
703* Invoking GDB:: How to start @value{GDBN}
704* Quitting GDB:: How to quit @value{GDBN}
705* Shell Commands:: How to use shell commands inside @value{GDBN}
706@end menu
707
6d2ebf8b 708@node Invoking GDB
c906108c
SS
709@section Invoking @value{GDBN}
710
c906108c
SS
711Invoke @value{GDBN} by running the program @code{@value{GDBP}}. Once started,
712@value{GDBN} reads commands from the terminal until you tell it to exit.
713
714You can also run @code{@value{GDBP}} with a variety of arguments and options,
715to specify more of your debugging environment at the outset.
716
c906108c
SS
717The command-line options described here are designed
718to cover a variety of situations; in some environments, some of these
5d161b24 719options may effectively be unavailable.
c906108c
SS
720
721The most usual way to start @value{GDBN} is with one argument,
722specifying an executable program:
723
724@example
725@value{GDBP} @var{program}
726@end example
727
c906108c
SS
728@noindent
729You can also start with both an executable program and a core file
730specified:
731
732@example
733@value{GDBP} @var{program} @var{core}
734@end example
735
736You can, instead, specify a process ID as a second argument, if you want
737to debug a running process:
738
739@example
740@value{GDBP} @var{program} 1234
741@end example
742
743@noindent
744would attach @value{GDBN} to process @code{1234} (unless you also have a file
745named @file{1234}; @value{GDBN} does check for a core file first).
746
c906108c 747Taking advantage of the second command-line argument requires a fairly
2df3850c
JM
748complete operating system; when you use @value{GDBN} as a remote
749debugger attached to a bare board, there may not be any notion of
750``process'', and there is often no way to get a core dump. @value{GDBN}
751will warn you if it is unable to attach or to read core dumps.
c906108c 752
96a2c332 753You can run @code{@value{GDBP}} without printing the front material, which describes
c906108c
SS
754@value{GDBN}'s non-warranty, by specifying @code{-silent}:
755
756@smallexample
757@value{GDBP} -silent
758@end smallexample
759
760@noindent
761You can further control how @value{GDBN} starts up by using command-line
762options. @value{GDBN} itself can remind you of the options available.
763
764@noindent
765Type
766
767@example
768@value{GDBP} -help
769@end example
770
771@noindent
772to display all available options and briefly describe their use
773(@samp{@value{GDBP} -h} is a shorter equivalent).
774
775All options and command line arguments you give are processed
776in sequential order. The order makes a difference when the
777@samp{-x} option is used.
778
779
780@menu
c906108c
SS
781* File Options:: Choosing files
782* Mode Options:: Choosing modes
783@end menu
784
6d2ebf8b 785@node File Options
c906108c
SS
786@subsection Choosing files
787
2df3850c 788When @value{GDBN} starts, it reads any arguments other than options as
c906108c
SS
789specifying an executable file and core file (or process ID). This is
790the same as if the arguments were specified by the @samp{-se} and
791@samp{-c} options respectively. (@value{GDBN} reads the first argument
792that does not have an associated option flag as equivalent to the
793@samp{-se} option followed by that argument; and the second argument
794that does not have an associated option flag, if any, as equivalent to
795the @samp{-c} option followed by that argument.)
7a292a7a
SS
796
797If @value{GDBN} has not been configured to included core file support,
798such as for most embedded targets, then it will complain about a second
799argument and ignore it.
c906108c
SS
800
801Many options have both long and short forms; both are shown in the
802following list. @value{GDBN} also recognizes the long forms if you truncate
803them, so long as enough of the option is present to be unambiguous.
804(If you prefer, you can flag option arguments with @samp{--} rather
805than @samp{-}, though we illustrate the more usual convention.)
806
d700128c
EZ
807@c NOTE: the @cindex entries here use double dashes ON PURPOSE. This
808@c way, both those who look for -foo and --foo in the index, will find
809@c it.
810
c906108c
SS
811@table @code
812@item -symbols @var{file}
813@itemx -s @var{file}
d700128c
EZ
814@cindex @code{--symbols}
815@cindex @code{-s}
c906108c
SS
816Read symbol table from file @var{file}.
817
818@item -exec @var{file}
819@itemx -e @var{file}
d700128c
EZ
820@cindex @code{--exec}
821@cindex @code{-e}
7a292a7a
SS
822Use file @var{file} as the executable file to execute when appropriate,
823and for examining pure data in conjunction with a core dump.
c906108c
SS
824
825@item -se @var{file}
d700128c 826@cindex @code{--se}
c906108c
SS
827Read symbol table from file @var{file} and use it as the executable
828file.
829
c906108c
SS
830@item -core @var{file}
831@itemx -c @var{file}
d700128c
EZ
832@cindex @code{--core}
833@cindex @code{-c}
c906108c
SS
834Use file @var{file} as a core dump to examine.
835
836@item -c @var{number}
837Connect to process ID @var{number}, as with the @code{attach} command
838(unless there is a file in core-dump format named @var{number}, in which
839case @samp{-c} specifies that file as a core dump to read).
c906108c
SS
840
841@item -command @var{file}
842@itemx -x @var{file}
d700128c
EZ
843@cindex @code{--command}
844@cindex @code{-x}
c906108c
SS
845Execute @value{GDBN} commands from file @var{file}. @xref{Command
846Files,, Command files}.
847
848@item -directory @var{directory}
849@itemx -d @var{directory}
d700128c
EZ
850@cindex @code{--directory}
851@cindex @code{-d}
c906108c
SS
852Add @var{directory} to the path to search for source files.
853
c906108c
SS
854@item -m
855@itemx -mapped
d700128c
EZ
856@cindex @code{--mapped}
857@cindex @code{-m}
c906108c
SS
858@emph{Warning: this option depends on operating system facilities that are not
859supported on all systems.}@*
860If memory-mapped files are available on your system through the @code{mmap}
5d161b24 861system call, you can use this option
c906108c
SS
862to have @value{GDBN} write the symbols from your
863program into a reusable file in the current directory. If the program you are debugging is
96a2c332 864called @file{/tmp/fred}, the mapped symbol file is @file{/tmp/fred.syms}.
c906108c
SS
865Future @value{GDBN} debugging sessions notice the presence of this file,
866and can quickly map in symbol information from it, rather than reading
867the symbol table from the executable program.
868
869The @file{.syms} file is specific to the host machine where @value{GDBN}
870is run. It holds an exact image of the internal @value{GDBN} symbol
871table. It cannot be shared across multiple host platforms.
c906108c 872
c906108c
SS
873@item -r
874@itemx -readnow
d700128c
EZ
875@cindex @code{--readnow}
876@cindex @code{-r}
c906108c
SS
877Read each symbol file's entire symbol table immediately, rather than
878the default, which is to read it incrementally as it is needed.
879This makes startup slower, but makes future operations faster.
53a5351d 880
c906108c
SS
881@end table
882
2df3850c 883You typically combine the @code{-mapped} and @code{-readnow} options in
c906108c 884order to build a @file{.syms} file that contains complete symbol
2df3850c
JM
885information. (@xref{Files,,Commands to specify files}, for information
886on @file{.syms} files.) A simple @value{GDBN} invocation to do nothing
887but build a @file{.syms} file for future use is:
c906108c
SS
888
889@example
2df3850c 890gdb -batch -nx -mapped -readnow programname
c906108c 891@end example
c906108c 892
6d2ebf8b 893@node Mode Options
c906108c
SS
894@subsection Choosing modes
895
896You can run @value{GDBN} in various alternative modes---for example, in
897batch mode or quiet mode.
898
899@table @code
900@item -nx
901@itemx -n
d700128c
EZ
902@cindex @code{--nx}
903@cindex @code{-n}
2df3850c
JM
904Do not execute commands found in any initialization files (normally
905called @file{.gdbinit}, or @file{gdb.ini} on PCs). Normally,
906@value{GDBN} executes the commands in these files after all the command
907options and arguments have been processed. @xref{Command Files,,Command
908files}.
c906108c
SS
909
910@item -quiet
d700128c 911@itemx -silent
c906108c 912@itemx -q
d700128c
EZ
913@cindex @code{--quiet}
914@cindex @code{--silent}
915@cindex @code{-q}
c906108c
SS
916``Quiet''. Do not print the introductory and copyright messages. These
917messages are also suppressed in batch mode.
918
919@item -batch
d700128c 920@cindex @code{--batch}
c906108c
SS
921Run in batch mode. Exit with status @code{0} after processing all the
922command files specified with @samp{-x} (and all commands from
923initialization files, if not inhibited with @samp{-n}). Exit with
924nonzero status if an error occurs in executing the @value{GDBN} commands
925in the command files.
926
2df3850c
JM
927Batch mode may be useful for running @value{GDBN} as a filter, for
928example to download and run a program on another computer; in order to
929make this more useful, the message
c906108c
SS
930
931@example
932Program exited normally.
933@end example
934
935@noindent
2df3850c
JM
936(which is ordinarily issued whenever a program running under
937@value{GDBN} control terminates) is not issued when running in batch
938mode.
939
940@item -nowindows
941@itemx -nw
d700128c
EZ
942@cindex @code{--nowindows}
943@cindex @code{-nw}
2df3850c 944``No windows''. If @value{GDBN} comes with a graphical user interface
96a2c332 945(GUI) built in, then this option tells @value{GDBN} to only use the command-line
2df3850c
JM
946interface. If no GUI is available, this option has no effect.
947
948@item -windows
949@itemx -w
d700128c
EZ
950@cindex @code{--windows}
951@cindex @code{-w}
2df3850c
JM
952If @value{GDBN} includes a GUI, then this option requires it to be
953used if possible.
c906108c
SS
954
955@item -cd @var{directory}
d700128c 956@cindex @code{--cd}
c906108c
SS
957Run @value{GDBN} using @var{directory} as its working directory,
958instead of the current directory.
959
c906108c
SS
960@item -fullname
961@itemx -f
d700128c
EZ
962@cindex @code{--fullname}
963@cindex @code{-f}
7a292a7a
SS
964@sc{gnu} Emacs sets this option when it runs @value{GDBN} as a
965subprocess. It tells @value{GDBN} to output the full file name and line
966number in a standard, recognizable fashion each time a stack frame is
967displayed (which includes each time your program stops). This
968recognizable format looks like two @samp{\032} characters, followed by
969the file name, line number and character position separated by colons,
970and a newline. The Emacs-to-@value{GDBN} interface program uses the two
971@samp{\032} characters as a signal to display the source code for the
972frame.
c906108c 973
d700128c
EZ
974@item -epoch
975@cindex @code{--epoch}
976The Epoch Emacs-@value{GDBN} interface sets this option when it runs
977@value{GDBN} as a subprocess. It tells @value{GDBN} to modify its print
978routines so as to allow Epoch to display values of expressions in a
979separate window.
980
981@item -annotate @var{level}
982@cindex @code{--annotate}
983This option sets the @dfn{annotation level} inside @value{GDBN}. Its
984effect is identical to using @samp{set annotate @var{level}}
985(@pxref{Annotations}).
986Annotation level controls how much information does @value{GDBN} print
987together with its prompt, values of expressions, source lines, and other
988types of output. Level 0 is the normal, level 1 is for use when
989@value{GDBN} is run as a subprocess of @sc{gnu} Emacs, level 2 is the
990maximum annotation suitable for programs that control @value{GDBN}.
991
992@item -async
993@cindex @code{--async}
994Use the asynchronous event loop for the command-line interface.
995@value{GDBN} processes all events, such as user keyboard input, via a
996special event loop. This allows @value{GDBN} to accept and process user
997commands in parallel with the debugged process being
998run@footnote{@value{GDBN} built with @sc{djgpp} tools for
999MS-DOS/MS-Windows supports this mode of operation, but the event loop is
1000suspended when the debuggee runs.}, so you don't need to wait for
1001control to return to @value{GDBN} before you type the next command.
1002(@emph{Note:} as of version 5.0, the target side of the asynchronous
1003operation is not yet in place, so @samp{-async} does not work fully
1004yet.)
1005@c FIXME: when the target side of the event loop is done, the above NOTE
1006@c should be removed.
1007
1008When the standard input is connected to a terminal device, @value{GDBN}
1009uses the asynchronous event loop by default, unless disabled by the
1010@samp{-noasync} option.
1011
1012@item -noasync
1013@cindex @code{--noasync}
1014Disable the asynchronous event loop for the command-line interface.
1015
2df3850c
JM
1016@item -baud @var{bps}
1017@itemx -b @var{bps}
d700128c
EZ
1018@cindex @code{--baud}
1019@cindex @code{-b}
c906108c
SS
1020Set the line speed (baud rate or bits per second) of any serial
1021interface used by @value{GDBN} for remote debugging.
c906108c
SS
1022
1023@item -tty @var{device}
d700128c
EZ
1024@itemx -t @var{device}
1025@cindex @code{--tty}
1026@cindex @code{-t}
c906108c
SS
1027Run using @var{device} for your program's standard input and output.
1028@c FIXME: kingdon thinks there is more to -tty. Investigate.
c906108c 1029
53a5351d
JM
1030@c resolve the situation of these eventually
1031@c @item -tui
d700128c 1032@c @cindex @code{--tui}
53a5351d
JM
1033@c Use a Terminal User Interface. For information, use your Web browser to
1034@c read the file @file{TUI.html}, which is usually installed in the
1035@c directory @code{/opt/langtools/wdb/doc} on HP-UX systems. Do not use
1036@c this option if you run @value{GDBN} from Emacs (see @pxref{Emacs, ,Using
1037@c @value{GDBN} under @sc{gnu} Emacs}).
1038
1039@c @item -xdb
d700128c 1040@c @cindex @code{--xdb}
53a5351d
JM
1041@c Run in XDB compatibility mode, allowing the use of certain XDB commands.
1042@c For information, see the file @file{xdb_trans.html}, which is usually
1043@c installed in the directory @code{/opt/langtools/wdb/doc} on HP-UX
1044@c systems.
1045
d700128c
EZ
1046@item -interpreter @var{interp}
1047@cindex @code{--interpreter}
1048Use the interpreter @var{interp} for interface with the controlling
1049program or device. This option is meant to be set by programs which
1050communicate with @value{GDBN} using it as a back end. For example,
1051@samp{--interpreter=mi} causes @value{GDBN} to use the @dfn{gdbmi
7162c0ca 1052interface} (@pxref{GDB/MI, , The @sc{gdb/mi} Interface}).
d700128c
EZ
1053
1054@item -write
1055@cindex @code{--write}
1056Open the executable and core files for both reading and writing. This
1057is equivalent to the @samp{set write on} command inside @value{GDBN}
1058(@pxref{Patching}).
1059
1060@item -statistics
1061@cindex @code{--statistics}
1062This option causes @value{GDBN} to print statistics about time and
1063memory usage after it completes each command and returns to the prompt.
1064
1065@item -version
1066@cindex @code{--version}
1067This option causes @value{GDBN} to print its version number and
1068no-warranty blurb, and exit.
1069
c906108c
SS
1070@end table
1071
6d2ebf8b 1072@node Quitting GDB
c906108c
SS
1073@section Quitting @value{GDBN}
1074@cindex exiting @value{GDBN}
1075@cindex leaving @value{GDBN}
1076
1077@table @code
1078@kindex quit @r{[}@var{expression}@r{]}
41afff9a 1079@kindex q @r{(@code{quit})}
96a2c332
SS
1080@item quit @r{[}@var{expression}@r{]}
1081@itemx q
1082To exit @value{GDBN}, use the @code{quit} command (abbreviated
1083@code{q}), or type an end-of-file character (usually @kbd{C-d}). If you
1084do not supply @var{expression}, @value{GDBN} will terminate normally;
1085otherwise it will terminate using the result of @var{expression} as the
1086error code.
c906108c
SS
1087@end table
1088
1089@cindex interrupt
1090An interrupt (often @kbd{C-c}) does not exit from @value{GDBN}, but rather
1091terminates the action of any @value{GDBN} command that is in progress and
1092returns to @value{GDBN} command level. It is safe to type the interrupt
1093character at any time because @value{GDBN} does not allow it to take effect
1094until a time when it is safe.
1095
c906108c
SS
1096If you have been using @value{GDBN} to control an attached process or
1097device, you can release it with the @code{detach} command
1098(@pxref{Attach, ,Debugging an already-running process}).
c906108c 1099
6d2ebf8b 1100@node Shell Commands
c906108c
SS
1101@section Shell commands
1102
1103If you need to execute occasional shell commands during your
1104debugging session, there is no need to leave or suspend @value{GDBN}; you can
1105just use the @code{shell} command.
1106
1107@table @code
1108@kindex shell
1109@cindex shell escape
1110@item shell @var{command string}
1111Invoke a standard shell to execute @var{command string}.
c906108c 1112If it exists, the environment variable @code{SHELL} determines which
d4f3574e
SS
1113shell to run. Otherwise @value{GDBN} uses the default shell
1114(@file{/bin/sh} on Unix systems, @file{COMMAND.COM} on MS-DOS, etc.).
c906108c
SS
1115@end table
1116
1117The utility @code{make} is often needed in development environments.
1118You do not have to use the @code{shell} command for this purpose in
1119@value{GDBN}:
1120
1121@table @code
1122@kindex make
1123@cindex calling make
1124@item make @var{make-args}
1125Execute the @code{make} program with the specified
1126arguments. This is equivalent to @samp{shell make @var{make-args}}.
1127@end table
1128
6d2ebf8b 1129@node Commands
c906108c
SS
1130@chapter @value{GDBN} Commands
1131
1132You can abbreviate a @value{GDBN} command to the first few letters of the command
1133name, if that abbreviation is unambiguous; and you can repeat certain
1134@value{GDBN} commands by typing just @key{RET}. You can also use the @key{TAB}
1135key to get @value{GDBN} to fill out the rest of a word in a command (or to
1136show you the alternatives available, if there is more than one possibility).
1137
1138@menu
1139* Command Syntax:: How to give commands to @value{GDBN}
1140* Completion:: Command completion
1141* Help:: How to ask @value{GDBN} for help
1142@end menu
1143
6d2ebf8b 1144@node Command Syntax
c906108c
SS
1145@section Command syntax
1146
1147A @value{GDBN} command is a single line of input. There is no limit on
1148how long it can be. It starts with a command name, which is followed by
1149arguments whose meaning depends on the command name. For example, the
1150command @code{step} accepts an argument which is the number of times to
1151step, as in @samp{step 5}. You can also use the @code{step} command
96a2c332 1152with no arguments. Some commands do not allow any arguments.
c906108c
SS
1153
1154@cindex abbreviation
1155@value{GDBN} command names may always be truncated if that abbreviation is
1156unambiguous. Other possible command abbreviations are listed in the
1157documentation for individual commands. In some cases, even ambiguous
1158abbreviations are allowed; for example, @code{s} is specially defined as
1159equivalent to @code{step} even though there are other commands whose
1160names start with @code{s}. You can test abbreviations by using them as
1161arguments to the @code{help} command.
1162
1163@cindex repeating commands
41afff9a 1164@kindex RET @r{(repeat last command)}
c906108c 1165A blank line as input to @value{GDBN} (typing just @key{RET}) means to
96a2c332 1166repeat the previous command. Certain commands (for example, @code{run})
c906108c
SS
1167will not repeat this way; these are commands whose unintentional
1168repetition might cause trouble and which you are unlikely to want to
1169repeat.
1170
1171The @code{list} and @code{x} commands, when you repeat them with
1172@key{RET}, construct new arguments rather than repeating
1173exactly as typed. This permits easy scanning of source or memory.
1174
1175@value{GDBN} can also use @key{RET} in another way: to partition lengthy
1176output, in a way similar to the common utility @code{more}
1177(@pxref{Screen Size,,Screen size}). Since it is easy to press one
1178@key{RET} too many in this situation, @value{GDBN} disables command
1179repetition after any command that generates this sort of display.
1180
41afff9a 1181@kindex # @r{(a comment)}
c906108c
SS
1182@cindex comment
1183Any text from a @kbd{#} to the end of the line is a comment; it does
1184nothing. This is useful mainly in command files (@pxref{Command
1185Files,,Command files}).
1186
6d2ebf8b 1187@node Completion
c906108c
SS
1188@section Command completion
1189
1190@cindex completion
1191@cindex word completion
1192@value{GDBN} can fill in the rest of a word in a command for you, if there is
1193only one possibility; it can also show you what the valid possibilities
1194are for the next word in a command, at any time. This works for @value{GDBN}
1195commands, @value{GDBN} subcommands, and the names of symbols in your program.
1196
1197Press the @key{TAB} key whenever you want @value{GDBN} to fill out the rest
1198of a word. If there is only one possibility, @value{GDBN} fills in the
1199word, and waits for you to finish the command (or press @key{RET} to
1200enter it). For example, if you type
1201
1202@c FIXME "@key" does not distinguish its argument sufficiently to permit
1203@c complete accuracy in these examples; space introduced for clarity.
1204@c If texinfo enhancements make it unnecessary, it would be nice to
1205@c replace " @key" by "@key" in the following...
1206@example
1207(@value{GDBP}) info bre @key{TAB}
1208@end example
1209
1210@noindent
1211@value{GDBN} fills in the rest of the word @samp{breakpoints}, since that is
1212the only @code{info} subcommand beginning with @samp{bre}:
1213
1214@example
1215(@value{GDBP}) info breakpoints
1216@end example
1217
1218@noindent
1219You can either press @key{RET} at this point, to run the @code{info
1220breakpoints} command, or backspace and enter something else, if
1221@samp{breakpoints} does not look like the command you expected. (If you
1222were sure you wanted @code{info breakpoints} in the first place, you
1223might as well just type @key{RET} immediately after @samp{info bre},
1224to exploit command abbreviations rather than command completion).
1225
1226If there is more than one possibility for the next word when you press
1227@key{TAB}, @value{GDBN} sounds a bell. You can either supply more
1228characters and try again, or just press @key{TAB} a second time;
1229@value{GDBN} displays all the possible completions for that word. For
1230example, you might want to set a breakpoint on a subroutine whose name
1231begins with @samp{make_}, but when you type @kbd{b make_@key{TAB}} @value{GDBN}
1232just sounds the bell. Typing @key{TAB} again displays all the
1233function names in your program that begin with those characters, for
1234example:
1235
1236@example
1237(@value{GDBP}) b make_ @key{TAB}
1238@exdent @value{GDBN} sounds bell; press @key{TAB} again, to see:
5d161b24
DB
1239make_a_section_from_file make_environ
1240make_abs_section make_function_type
1241make_blockvector make_pointer_type
1242make_cleanup make_reference_type
c906108c
SS
1243make_command make_symbol_completion_list
1244(@value{GDBP}) b make_
1245@end example
1246
1247@noindent
1248After displaying the available possibilities, @value{GDBN} copies your
1249partial input (@samp{b make_} in the example) so you can finish the
1250command.
1251
1252If you just want to see the list of alternatives in the first place, you
1253can press @kbd{M-?} rather than pressing @key{TAB} twice. @kbd{M-?}
7a292a7a 1254means @kbd{@key{META} ?}. You can type this either by holding down a
c906108c 1255key designated as the @key{META} shift on your keyboard (if there is
7a292a7a 1256one) while typing @kbd{?}, or as @key{ESC} followed by @kbd{?}.
c906108c
SS
1257
1258@cindex quotes in commands
1259@cindex completion of quoted strings
1260Sometimes the string you need, while logically a ``word'', may contain
7a292a7a
SS
1261parentheses or other characters that @value{GDBN} normally excludes from
1262its notion of a word. To permit word completion to work in this
1263situation, you may enclose words in @code{'} (single quote marks) in
1264@value{GDBN} commands.
c906108c 1265
c906108c
SS
1266The most likely situation where you might need this is in typing the
1267name of a C++ function. This is because C++ allows function overloading
1268(multiple definitions of the same function, distinguished by argument
1269type). For example, when you want to set a breakpoint you may need to
1270distinguish whether you mean the version of @code{name} that takes an
1271@code{int} parameter, @code{name(int)}, or the version that takes a
1272@code{float} parameter, @code{name(float)}. To use the word-completion
1273facilities in this situation, type a single quote @code{'} at the
1274beginning of the function name. This alerts @value{GDBN} that it may need to
1275consider more information than usual when you press @key{TAB} or
1276@kbd{M-?} to request word completion:
1277
1278@example
96a2c332 1279(@value{GDBP}) b 'bubble( @kbd{M-?}
c906108c
SS
1280bubble(double,double) bubble(int,int)
1281(@value{GDBP}) b 'bubble(
1282@end example
1283
1284In some cases, @value{GDBN} can tell that completing a name requires using
1285quotes. When this happens, @value{GDBN} inserts the quote for you (while
1286completing as much as it can) if you do not type the quote in the first
1287place:
1288
1289@example
1290(@value{GDBP}) b bub @key{TAB}
1291@exdent @value{GDBN} alters your input line to the following, and rings a bell:
1292(@value{GDBP}) b 'bubble(
1293@end example
1294
1295@noindent
1296In general, @value{GDBN} can tell that a quote is needed (and inserts it) if
1297you have not yet started typing the argument list when you ask for
1298completion on an overloaded symbol.
1299
d4f3574e 1300For more information about overloaded functions, see @ref{C plus plus
c906108c
SS
1301expressions, ,C++ expressions}. You can use the command @code{set
1302overload-resolution off} to disable overload resolution;
d4f3574e 1303see @ref{Debugging C plus plus, ,@value{GDBN} features for C++}.
c906108c
SS
1304
1305
6d2ebf8b 1306@node Help
c906108c
SS
1307@section Getting help
1308@cindex online documentation
1309@kindex help
1310
5d161b24 1311You can always ask @value{GDBN} itself for information on its commands,
c906108c
SS
1312using the command @code{help}.
1313
1314@table @code
41afff9a 1315@kindex h @r{(@code{help})}
c906108c
SS
1316@item help
1317@itemx h
1318You can use @code{help} (abbreviated @code{h}) with no arguments to
1319display a short list of named classes of commands:
1320
1321@smallexample
1322(@value{GDBP}) help
1323List of classes of commands:
1324
2df3850c 1325aliases -- Aliases of other commands
c906108c 1326breakpoints -- Making program stop at certain points
2df3850c 1327data -- Examining data
c906108c 1328files -- Specifying and examining files
2df3850c
JM
1329internals -- Maintenance commands
1330obscure -- Obscure features
1331running -- Running the program
1332stack -- Examining the stack
c906108c
SS
1333status -- Status inquiries
1334support -- Support facilities
96a2c332
SS
1335tracepoints -- Tracing of program execution without@*
1336 stopping the program
c906108c 1337user-defined -- User-defined commands
c906108c 1338
5d161b24 1339Type "help" followed by a class name for a list of
c906108c 1340commands in that class.
5d161b24 1341Type "help" followed by command name for full
c906108c
SS
1342documentation.
1343Command name abbreviations are allowed if unambiguous.
1344(@value{GDBP})
1345@end smallexample
96a2c332 1346@c the above line break eliminates huge line overfull...
c906108c
SS
1347
1348@item help @var{class}
1349Using one of the general help classes as an argument, you can get a
1350list of the individual commands in that class. For example, here is the
1351help display for the class @code{status}:
1352
1353@smallexample
1354(@value{GDBP}) help status
1355Status inquiries.
1356
1357List of commands:
1358
1359@c Line break in "show" line falsifies real output, but needed
1360@c to fit in smallbook page size.
2df3850c
JM
1361info -- Generic command for showing things
1362 about the program being debugged
1363show -- Generic command for showing things
1364 about the debugger
c906108c 1365
5d161b24 1366Type "help" followed by command name for full
c906108c
SS
1367documentation.
1368Command name abbreviations are allowed if unambiguous.
1369(@value{GDBP})
1370@end smallexample
1371
1372@item help @var{command}
1373With a command name as @code{help} argument, @value{GDBN} displays a
1374short paragraph on how to use that command.
1375
6837a0a2
DB
1376@kindex apropos
1377@item apropos @var{args}
1378The @code{apropos @var{args}} command searches through all of the @value{GDBN}
1379commands, and their documentation, for the regular expression specified in
1380@var{args}. It prints out all matches found. For example:
1381
1382@smallexample
1383apropos reload
1384@end smallexample
1385
1386@noindent results in:
1387
1388@smallexample
6d2ebf8b
SS
1389@c @group
1390set symbol-reloading -- Set dynamic symbol table reloading
1391 multiple times in one run
1392show symbol-reloading -- Show dynamic symbol table reloading
1393 multiple times in one run
1394@c @end group
6837a0a2
DB
1395@end smallexample
1396
c906108c
SS
1397@kindex complete
1398@item complete @var{args}
1399The @code{complete @var{args}} command lists all the possible completions
1400for the beginning of a command. Use @var{args} to specify the beginning of the
1401command you want completed. For example:
1402
1403@smallexample
1404complete i
1405@end smallexample
1406
1407@noindent results in:
1408
1409@smallexample
1410@group
2df3850c
JM
1411if
1412ignore
c906108c
SS
1413info
1414inspect
c906108c
SS
1415@end group
1416@end smallexample
1417
1418@noindent This is intended for use by @sc{gnu} Emacs.
1419@end table
1420
1421In addition to @code{help}, you can use the @value{GDBN} commands @code{info}
1422and @code{show} to inquire about the state of your program, or the state
1423of @value{GDBN} itself. Each command supports many topics of inquiry; this
1424manual introduces each of them in the appropriate context. The listings
1425under @code{info} and under @code{show} in the Index point to
1426all the sub-commands. @xref{Index}.
1427
1428@c @group
1429@table @code
1430@kindex info
41afff9a 1431@kindex i @r{(@code{info})}
c906108c
SS
1432@item info
1433This command (abbreviated @code{i}) is for describing the state of your
1434program. For example, you can list the arguments given to your program
1435with @code{info args}, list the registers currently in use with @code{info
1436registers}, or list the breakpoints you have set with @code{info breakpoints}.
1437You can get a complete list of the @code{info} sub-commands with
1438@w{@code{help info}}.
1439
1440@kindex set
1441@item set
5d161b24 1442You can assign the result of an expression to an environment variable with
c906108c
SS
1443@code{set}. For example, you can set the @value{GDBN} prompt to a $-sign with
1444@code{set prompt $}.
1445
1446@kindex show
1447@item show
5d161b24 1448In contrast to @code{info}, @code{show} is for describing the state of
c906108c
SS
1449@value{GDBN} itself.
1450You can change most of the things you can @code{show}, by using the
1451related command @code{set}; for example, you can control what number
1452system is used for displays with @code{set radix}, or simply inquire
1453which is currently in use with @code{show radix}.
1454
1455@kindex info set
1456To display all the settable parameters and their current
1457values, you can use @code{show} with no arguments; you may also use
1458@code{info set}. Both commands produce the same display.
1459@c FIXME: "info set" violates the rule that "info" is for state of
1460@c FIXME...program. Ck w/ GNU: "info set" to be called something else,
1461@c FIXME...or change desc of rule---eg "state of prog and debugging session"?
1462@end table
1463@c @end group
1464
1465Here are three miscellaneous @code{show} subcommands, all of which are
1466exceptional in lacking corresponding @code{set} commands:
1467
1468@table @code
1469@kindex show version
1470@cindex version number
1471@item show version
1472Show what version of @value{GDBN} is running. You should include this
2df3850c
JM
1473information in @value{GDBN} bug-reports. If multiple versions of
1474@value{GDBN} are in use at your site, you may need to determine which
1475version of @value{GDBN} you are running; as @value{GDBN} evolves, new
1476commands are introduced, and old ones may wither away. Also, many
1477system vendors ship variant versions of @value{GDBN}, and there are
96a2c332 1478variant versions of @value{GDBN} in @sc{gnu}/Linux distributions as well.
2df3850c
JM
1479The version number is the same as the one announced when you start
1480@value{GDBN}.
c906108c
SS
1481
1482@kindex show copying
1483@item show copying
1484Display information about permission for copying @value{GDBN}.
1485
1486@kindex show warranty
1487@item show warranty
2df3850c 1488Display the @sc{gnu} ``NO WARRANTY'' statement, or a warranty,
96a2c332 1489if your version of @value{GDBN} comes with one.
2df3850c 1490
c906108c
SS
1491@end table
1492
6d2ebf8b 1493@node Running
c906108c
SS
1494@chapter Running Programs Under @value{GDBN}
1495
1496When you run a program under @value{GDBN}, you must first generate
1497debugging information when you compile it.
7a292a7a
SS
1498
1499You may start @value{GDBN} with its arguments, if any, in an environment
1500of your choice. If you are doing native debugging, you may redirect
1501your program's input and output, debug an already running process, or
1502kill a child process.
c906108c
SS
1503
1504@menu
1505* Compilation:: Compiling for debugging
1506* Starting:: Starting your program
c906108c
SS
1507* Arguments:: Your program's arguments
1508* Environment:: Your program's environment
c906108c
SS
1509
1510* Working Directory:: Your program's working directory
1511* Input/Output:: Your program's input and output
1512* Attach:: Debugging an already-running process
1513* Kill Process:: Killing the child process
c906108c
SS
1514
1515* Threads:: Debugging programs with multiple threads
1516* Processes:: Debugging programs with multiple processes
1517@end menu
1518
6d2ebf8b 1519@node Compilation
c906108c
SS
1520@section Compiling for debugging
1521
1522In order to debug a program effectively, you need to generate
1523debugging information when you compile it. This debugging information
1524is stored in the object file; it describes the data type of each
1525variable or function and the correspondence between source line numbers
1526and addresses in the executable code.
1527
1528To request debugging information, specify the @samp{-g} option when you run
1529the compiler.
1530
1531Many C compilers are unable to handle the @samp{-g} and @samp{-O}
1532options together. Using those compilers, you cannot generate optimized
1533executables containing debugging information.
1534
53a5351d
JM
1535@value{NGCC}, the @sc{gnu} C compiler, supports @samp{-g} with or
1536without @samp{-O}, making it possible to debug optimized code. We
1537recommend that you @emph{always} use @samp{-g} whenever you compile a
1538program. You may think your program is correct, but there is no sense
1539in pushing your luck.
c906108c
SS
1540
1541@cindex optimized code, debugging
1542@cindex debugging optimized code
1543When you debug a program compiled with @samp{-g -O}, remember that the
1544optimizer is rearranging your code; the debugger shows you what is
1545really there. Do not be too surprised when the execution path does not
1546exactly match your source file! An extreme example: if you define a
1547variable, but never use it, @value{GDBN} never sees that
1548variable---because the compiler optimizes it out of existence.
1549
1550Some things do not work as well with @samp{-g -O} as with just
1551@samp{-g}, particularly on machines with instruction scheduling. If in
1552doubt, recompile with @samp{-g} alone, and if this fixes the problem,
1553please report it to us as a bug (including a test case!).
1554
1555Older versions of the @sc{gnu} C compiler permitted a variant option
1556@w{@samp{-gg}} for debugging information. @value{GDBN} no longer supports this
1557format; if your @sc{gnu} C compiler has this option, do not use it.
1558
1559@need 2000
6d2ebf8b 1560@node Starting
c906108c
SS
1561@section Starting your program
1562@cindex starting
1563@cindex running
1564
1565@table @code
1566@kindex run
41afff9a 1567@kindex r @r{(@code{run})}
c906108c
SS
1568@item run
1569@itemx r
7a292a7a
SS
1570Use the @code{run} command to start your program under @value{GDBN}.
1571You must first specify the program name (except on VxWorks) with an
1572argument to @value{GDBN} (@pxref{Invocation, ,Getting In and Out of
1573@value{GDBN}}), or by using the @code{file} or @code{exec-file} command
1574(@pxref{Files, ,Commands to specify files}).
c906108c
SS
1575
1576@end table
1577
c906108c
SS
1578If you are running your program in an execution environment that
1579supports processes, @code{run} creates an inferior process and makes
1580that process run your program. (In environments without processes,
1581@code{run} jumps to the start of your program.)
1582
1583The execution of a program is affected by certain information it
1584receives from its superior. @value{GDBN} provides ways to specify this
1585information, which you must do @emph{before} starting your program. (You
1586can change it after starting your program, but such changes only affect
1587your program the next time you start it.) This information may be
1588divided into four categories:
1589
1590@table @asis
1591@item The @emph{arguments.}
1592Specify the arguments to give your program as the arguments of the
1593@code{run} command. If a shell is available on your target, the shell
1594is used to pass the arguments, so that you may use normal conventions
1595(such as wildcard expansion or variable substitution) in describing
1596the arguments.
1597In Unix systems, you can control which shell is used with the
1598@code{SHELL} environment variable.
1599@xref{Arguments, ,Your program's arguments}.
1600
1601@item The @emph{environment.}
1602Your program normally inherits its environment from @value{GDBN}, but you can
1603use the @value{GDBN} commands @code{set environment} and @code{unset
1604environment} to change parts of the environment that affect
1605your program. @xref{Environment, ,Your program's environment}.
1606
1607@item The @emph{working directory.}
1608Your program inherits its working directory from @value{GDBN}. You can set
1609the @value{GDBN} working directory with the @code{cd} command in @value{GDBN}.
1610@xref{Working Directory, ,Your program's working directory}.
1611
1612@item The @emph{standard input and output.}
1613Your program normally uses the same device for standard input and
1614standard output as @value{GDBN} is using. You can redirect input and output
1615in the @code{run} command line, or you can use the @code{tty} command to
1616set a different device for your program.
1617@xref{Input/Output, ,Your program's input and output}.
1618
1619@cindex pipes
1620@emph{Warning:} While input and output redirection work, you cannot use
1621pipes to pass the output of the program you are debugging to another
1622program; if you attempt this, @value{GDBN} is likely to wind up debugging the
1623wrong program.
1624@end table
c906108c
SS
1625
1626When you issue the @code{run} command, your program begins to execute
1627immediately. @xref{Stopping, ,Stopping and continuing}, for discussion
1628of how to arrange for your program to stop. Once your program has
1629stopped, you may call functions in your program, using the @code{print}
1630or @code{call} commands. @xref{Data, ,Examining Data}.
1631
1632If the modification time of your symbol file has changed since the last
1633time @value{GDBN} read its symbols, @value{GDBN} discards its symbol
1634table, and reads it again. When it does this, @value{GDBN} tries to retain
1635your current breakpoints.
1636
6d2ebf8b 1637@node Arguments
c906108c
SS
1638@section Your program's arguments
1639
1640@cindex arguments (to your program)
1641The arguments to your program can be specified by the arguments of the
5d161b24 1642@code{run} command.
c906108c
SS
1643They are passed to a shell, which expands wildcard characters and
1644performs redirection of I/O, and thence to your program. Your
1645@code{SHELL} environment variable (if it exists) specifies what shell
1646@value{GDBN} uses. If you do not define @code{SHELL}, @value{GDBN} uses
d4f3574e
SS
1647the default shell (@file{/bin/sh} on Unix).
1648
1649On non-Unix systems, the program is usually invoked directly by
1650@value{GDBN}, which emulates I/O redirection via the appropriate system
1651calls, and the wildcard characters are expanded by the startup code of
1652the program, not by the shell.
c906108c
SS
1653
1654@code{run} with no arguments uses the same arguments used by the previous
1655@code{run}, or those set by the @code{set args} command.
1656
c906108c 1657@table @code
41afff9a 1658@kindex set args
c906108c
SS
1659@item set args
1660Specify the arguments to be used the next time your program is run. If
1661@code{set args} has no arguments, @code{run} executes your program
1662with no arguments. Once you have run your program with arguments,
1663using @code{set args} before the next @code{run} is the only way to run
1664it again without arguments.
1665
1666@kindex show args
1667@item show args
1668Show the arguments to give your program when it is started.
1669@end table
1670
6d2ebf8b 1671@node Environment
c906108c
SS
1672@section Your program's environment
1673
1674@cindex environment (of your program)
1675The @dfn{environment} consists of a set of environment variables and
1676their values. Environment variables conventionally record such things as
1677your user name, your home directory, your terminal type, and your search
1678path for programs to run. Usually you set up environment variables with
1679the shell and they are inherited by all the other programs you run. When
1680debugging, it can be useful to try running your program with a modified
1681environment without having to start @value{GDBN} over again.
1682
1683@table @code
1684@kindex path
1685@item path @var{directory}
1686Add @var{directory} to the front of the @code{PATH} environment variable
17cc6a06
EZ
1687(the search path for executables) that will be passed to your program.
1688The value of @code{PATH} used by @value{GDBN} does not change.
d4f3574e
SS
1689You may specify several directory names, separated by whitespace or by a
1690system-dependent separator character (@samp{:} on Unix, @samp{;} on
1691MS-DOS and MS-Windows). If @var{directory} is already in the path, it
1692is moved to the front, so it is searched sooner.
c906108c
SS
1693
1694You can use the string @samp{$cwd} to refer to whatever is the current
1695working directory at the time @value{GDBN} searches the path. If you
1696use @samp{.} instead, it refers to the directory where you executed the
1697@code{path} command. @value{GDBN} replaces @samp{.} in the
1698@var{directory} argument (with the current path) before adding
1699@var{directory} to the search path.
1700@c 'path' is explicitly nonrepeatable, but RMS points out it is silly to
1701@c document that, since repeating it would be a no-op.
1702
1703@kindex show paths
1704@item show paths
1705Display the list of search paths for executables (the @code{PATH}
1706environment variable).
1707
1708@kindex show environment
1709@item show environment @r{[}@var{varname}@r{]}
1710Print the value of environment variable @var{varname} to be given to
1711your program when it starts. If you do not supply @var{varname},
1712print the names and values of all environment variables to be given to
1713your program. You can abbreviate @code{environment} as @code{env}.
1714
1715@kindex set environment
53a5351d 1716@item set environment @var{varname} @r{[}=@var{value}@r{]}
c906108c
SS
1717Set environment variable @var{varname} to @var{value}. The value
1718changes for your program only, not for @value{GDBN} itself. @var{value} may
1719be any string; the values of environment variables are just strings, and
1720any interpretation is supplied by your program itself. The @var{value}
1721parameter is optional; if it is eliminated, the variable is set to a
1722null value.
1723@c "any string" here does not include leading, trailing
1724@c blanks. Gnu asks: does anyone care?
1725
1726For example, this command:
1727
1728@example
1729set env USER = foo
1730@end example
1731
1732@noindent
d4f3574e 1733tells the debugged program, when subsequently run, that its user is named
c906108c
SS
1734@samp{foo}. (The spaces around @samp{=} are used for clarity here; they
1735are not actually required.)
1736
1737@kindex unset environment
1738@item unset environment @var{varname}
1739Remove variable @var{varname} from the environment to be passed to your
1740program. This is different from @samp{set env @var{varname} =};
1741@code{unset environment} removes the variable from the environment,
1742rather than assigning it an empty value.
1743@end table
1744
d4f3574e
SS
1745@emph{Warning:} On Unix systems, @value{GDBN} runs your program using
1746the shell indicated
c906108c
SS
1747by your @code{SHELL} environment variable if it exists (or
1748@code{/bin/sh} if not). If your @code{SHELL} variable names a shell
1749that runs an initialization file---such as @file{.cshrc} for C-shell, or
1750@file{.bashrc} for BASH---any variables you set in that file affect
1751your program. You may wish to move setting of environment variables to
1752files that are only run when you sign on, such as @file{.login} or
1753@file{.profile}.
1754
6d2ebf8b 1755@node Working Directory
c906108c
SS
1756@section Your program's working directory
1757
1758@cindex working directory (of your program)
1759Each time you start your program with @code{run}, it inherits its
1760working directory from the current working directory of @value{GDBN}.
1761The @value{GDBN} working directory is initially whatever it inherited
1762from its parent process (typically the shell), but you can specify a new
1763working directory in @value{GDBN} with the @code{cd} command.
1764
1765The @value{GDBN} working directory also serves as a default for the commands
1766that specify files for @value{GDBN} to operate on. @xref{Files, ,Commands to
1767specify files}.
1768
1769@table @code
1770@kindex cd
1771@item cd @var{directory}
1772Set the @value{GDBN} working directory to @var{directory}.
1773
1774@kindex pwd
1775@item pwd
1776Print the @value{GDBN} working directory.
1777@end table
1778
6d2ebf8b 1779@node Input/Output
c906108c
SS
1780@section Your program's input and output
1781
1782@cindex redirection
1783@cindex i/o
1784@cindex terminal
1785By default, the program you run under @value{GDBN} does input and output to
5d161b24 1786the same terminal that @value{GDBN} uses. @value{GDBN} switches the terminal
c906108c
SS
1787to its own terminal modes to interact with you, but it records the terminal
1788modes your program was using and switches back to them when you continue
1789running your program.
1790
1791@table @code
1792@kindex info terminal
1793@item info terminal
1794Displays information recorded by @value{GDBN} about the terminal modes your
1795program is using.
1796@end table
1797
1798You can redirect your program's input and/or output using shell
1799redirection with the @code{run} command. For example,
1800
1801@example
1802run > outfile
1803@end example
1804
1805@noindent
1806starts your program, diverting its output to the file @file{outfile}.
1807
1808@kindex tty
1809@cindex controlling terminal
1810Another way to specify where your program should do input and output is
1811with the @code{tty} command. This command accepts a file name as
1812argument, and causes this file to be the default for future @code{run}
1813commands. It also resets the controlling terminal for the child
1814process, for future @code{run} commands. For example,
1815
1816@example
1817tty /dev/ttyb
1818@end example
1819
1820@noindent
1821directs that processes started with subsequent @code{run} commands
1822default to do input and output on the terminal @file{/dev/ttyb} and have
1823that as their controlling terminal.
1824
1825An explicit redirection in @code{run} overrides the @code{tty} command's
1826effect on the input/output device, but not its effect on the controlling
1827terminal.
1828
1829When you use the @code{tty} command or redirect input in the @code{run}
1830command, only the input @emph{for your program} is affected. The input
1831for @value{GDBN} still comes from your terminal.
1832
6d2ebf8b 1833@node Attach
c906108c
SS
1834@section Debugging an already-running process
1835@kindex attach
1836@cindex attach
1837
1838@table @code
1839@item attach @var{process-id}
1840This command attaches to a running process---one that was started
1841outside @value{GDBN}. (@code{info files} shows your active
1842targets.) The command takes as argument a process ID. The usual way to
1843find out the process-id of a Unix process is with the @code{ps} utility,
1844or with the @samp{jobs -l} shell command.
1845
1846@code{attach} does not repeat if you press @key{RET} a second time after
1847executing the command.
1848@end table
1849
1850To use @code{attach}, your program must be running in an environment
1851which supports processes; for example, @code{attach} does not work for
1852programs on bare-board targets that lack an operating system. You must
1853also have permission to send the process a signal.
1854
1855When you use @code{attach}, the debugger finds the program running in
1856the process first by looking in the current working directory, then (if
1857the program is not found) by using the source file search path
1858(@pxref{Source Path, ,Specifying source directories}). You can also use
1859the @code{file} command to load the program. @xref{Files, ,Commands to
1860Specify Files}.
1861
1862The first thing @value{GDBN} does after arranging to debug the specified
1863process is to stop it. You can examine and modify an attached process
53a5351d
JM
1864with all the @value{GDBN} commands that are ordinarily available when
1865you start processes with @code{run}. You can insert breakpoints; you
1866can step and continue; you can modify storage. If you would rather the
1867process continue running, you may use the @code{continue} command after
c906108c
SS
1868attaching @value{GDBN} to the process.
1869
1870@table @code
1871@kindex detach
1872@item detach
1873When you have finished debugging the attached process, you can use the
1874@code{detach} command to release it from @value{GDBN} control. Detaching
1875the process continues its execution. After the @code{detach} command,
1876that process and @value{GDBN} become completely independent once more, and you
1877are ready to @code{attach} another process or start one with @code{run}.
1878@code{detach} does not repeat if you press @key{RET} again after
1879executing the command.
1880@end table
1881
1882If you exit @value{GDBN} or use the @code{run} command while you have an
1883attached process, you kill that process. By default, @value{GDBN} asks
1884for confirmation if you try to do either of these things; you can
1885control whether or not you need to confirm by using the @code{set
1886confirm} command (@pxref{Messages/Warnings, ,Optional warnings and
1887messages}).
1888
6d2ebf8b 1889@node Kill Process
c906108c 1890@section Killing the child process
c906108c
SS
1891
1892@table @code
1893@kindex kill
1894@item kill
1895Kill the child process in which your program is running under @value{GDBN}.
1896@end table
1897
1898This command is useful if you wish to debug a core dump instead of a
1899running process. @value{GDBN} ignores any core dump file while your program
1900is running.
1901
1902On some operating systems, a program cannot be executed outside @value{GDBN}
1903while you have breakpoints set on it inside @value{GDBN}. You can use the
1904@code{kill} command in this situation to permit running your program
1905outside the debugger.
1906
1907The @code{kill} command is also useful if you wish to recompile and
1908relink your program, since on many systems it is impossible to modify an
1909executable file while it is running in a process. In this case, when you
1910next type @code{run}, @value{GDBN} notices that the file has changed, and
1911reads the symbol table again (while trying to preserve your current
1912breakpoint settings).
1913
6d2ebf8b 1914@node Threads
c906108c 1915@section Debugging programs with multiple threads
c906108c
SS
1916
1917@cindex threads of execution
1918@cindex multiple threads
1919@cindex switching threads
1920In some operating systems, such as HP-UX and Solaris, a single program
1921may have more than one @dfn{thread} of execution. The precise semantics
1922of threads differ from one operating system to another, but in general
1923the threads of a single program are akin to multiple processes---except
1924that they share one address space (that is, they can all examine and
1925modify the same variables). On the other hand, each thread has its own
1926registers and execution stack, and perhaps private memory.
1927
1928@value{GDBN} provides these facilities for debugging multi-thread
1929programs:
1930
1931@itemize @bullet
1932@item automatic notification of new threads
1933@item @samp{thread @var{threadno}}, a command to switch among threads
1934@item @samp{info threads}, a command to inquire about existing threads
5d161b24 1935@item @samp{thread apply [@var{threadno}] [@var{all}] @var{args}},
c906108c
SS
1936a command to apply a command to a list of threads
1937@item thread-specific breakpoints
1938@end itemize
1939
c906108c
SS
1940@quotation
1941@emph{Warning:} These facilities are not yet available on every
1942@value{GDBN} configuration where the operating system supports threads.
1943If your @value{GDBN} does not support threads, these commands have no
1944effect. For example, a system without thread support shows no output
1945from @samp{info threads}, and always rejects the @code{thread} command,
1946like this:
1947
1948@smallexample
1949(@value{GDBP}) info threads
1950(@value{GDBP}) thread 1
1951Thread ID 1 not known. Use the "info threads" command to
1952see the IDs of currently known threads.
1953@end smallexample
1954@c FIXME to implementors: how hard would it be to say "sorry, this GDB
1955@c doesn't support threads"?
1956@end quotation
c906108c
SS
1957
1958@cindex focus of debugging
1959@cindex current thread
1960The @value{GDBN} thread debugging facility allows you to observe all
1961threads while your program runs---but whenever @value{GDBN} takes
1962control, one thread in particular is always the focus of debugging.
1963This thread is called the @dfn{current thread}. Debugging commands show
1964program information from the perspective of the current thread.
1965
41afff9a 1966@cindex @code{New} @var{systag} message
c906108c
SS
1967@cindex thread identifier (system)
1968@c FIXME-implementors!! It would be more helpful if the [New...] message
1969@c included GDB's numeric thread handle, so you could just go to that
1970@c thread without first checking `info threads'.
1971Whenever @value{GDBN} detects a new thread in your program, it displays
1972the target system's identification for the thread with a message in the
1973form @samp{[New @var{systag}]}. @var{systag} is a thread identifier
1974whose form varies depending on the particular system. For example, on
1975LynxOS, you might see
1976
1977@example
1978[New process 35 thread 27]
1979@end example
1980
1981@noindent
1982when @value{GDBN} notices a new thread. In contrast, on an SGI system,
1983the @var{systag} is simply something like @samp{process 368}, with no
1984further qualifier.
1985
1986@c FIXME!! (1) Does the [New...] message appear even for the very first
1987@c thread of a program, or does it only appear for the
1988@c second---i.e., when it becomes obvious we have a multithread
1989@c program?
1990@c (2) *Is* there necessarily a first thread always? Or do some
1991@c multithread systems permit starting a program with multiple
5d161b24 1992@c threads ab initio?
c906108c
SS
1993
1994@cindex thread number
1995@cindex thread identifier (GDB)
1996For debugging purposes, @value{GDBN} associates its own thread
1997number---always a single integer---with each thread in your program.
1998
1999@table @code
2000@kindex info threads
2001@item info threads
2002Display a summary of all threads currently in your
2003program. @value{GDBN} displays for each thread (in this order):
2004
2005@enumerate
2006@item the thread number assigned by @value{GDBN}
2007
2008@item the target system's thread identifier (@var{systag})
2009
2010@item the current stack frame summary for that thread
2011@end enumerate
2012
2013@noindent
2014An asterisk @samp{*} to the left of the @value{GDBN} thread number
2015indicates the current thread.
2016
5d161b24 2017For example,
c906108c
SS
2018@end table
2019@c end table here to get a little more width for example
2020
2021@smallexample
2022(@value{GDBP}) info threads
2023 3 process 35 thread 27 0x34e5 in sigpause ()
2024 2 process 35 thread 23 0x34e5 in sigpause ()
2025* 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8)
2026 at threadtest.c:68
2027@end smallexample
53a5351d
JM
2028
2029On HP-UX systems:
c906108c
SS
2030
2031@cindex thread number
2032@cindex thread identifier (GDB)
2033For debugging purposes, @value{GDBN} associates its own thread
2034number---a small integer assigned in thread-creation order---with each
2035thread in your program.
2036
41afff9a
EZ
2037@cindex @code{New} @var{systag} message, on HP-UX
2038@cindex thread identifier (system), on HP-UX
c906108c
SS
2039@c FIXME-implementors!! It would be more helpful if the [New...] message
2040@c included GDB's numeric thread handle, so you could just go to that
2041@c thread without first checking `info threads'.
2042Whenever @value{GDBN} detects a new thread in your program, it displays
2043both @value{GDBN}'s thread number and the target system's identification for the thread with a message in the
2044form @samp{[New @var{systag}]}. @var{systag} is a thread identifier
2045whose form varies depending on the particular system. For example, on
2046HP-UX, you see
2047
2048@example
2049[New thread 2 (system thread 26594)]
2050@end example
2051
2052@noindent
5d161b24 2053when @value{GDBN} notices a new thread.
c906108c
SS
2054
2055@table @code
2056@kindex info threads
2057@item info threads
2058Display a summary of all threads currently in your
2059program. @value{GDBN} displays for each thread (in this order):
2060
2061@enumerate
2062@item the thread number assigned by @value{GDBN}
2063
2064@item the target system's thread identifier (@var{systag})
2065
2066@item the current stack frame summary for that thread
2067@end enumerate
2068
2069@noindent
2070An asterisk @samp{*} to the left of the @value{GDBN} thread number
2071indicates the current thread.
2072
5d161b24 2073For example,
c906108c
SS
2074@end table
2075@c end table here to get a little more width for example
2076
2077@example
2078(@value{GDBP}) info threads
6d2ebf8b
SS
2079 * 3 system thread 26607 worker (wptr=0x7b09c318 "@@") \@*
2080 at quicksort.c:137
2081 2 system thread 26606 0x7b0030d8 in __ksleep () \@*
2082 from /usr/lib/libc.2
2083 1 system thread 27905 0x7b003498 in _brk () \@*
2084 from /usr/lib/libc.2
c906108c 2085@end example
c906108c
SS
2086
2087@table @code
2088@kindex thread @var{threadno}
2089@item thread @var{threadno}
2090Make thread number @var{threadno} the current thread. The command
2091argument @var{threadno} is the internal @value{GDBN} thread number, as
2092shown in the first field of the @samp{info threads} display.
2093@value{GDBN} responds by displaying the system identifier of the thread
2094you selected, and its current stack frame summary:
2095
2096@smallexample
2097@c FIXME!! This example made up; find a @value{GDBN} w/threads and get real one
2098(@value{GDBP}) thread 2
c906108c 2099[Switching to process 35 thread 23]
c906108c
SS
21000x34e5 in sigpause ()
2101@end smallexample
2102
2103@noindent
2104As with the @samp{[New @dots{}]} message, the form of the text after
2105@samp{Switching to} depends on your system's conventions for identifying
5d161b24 2106threads.
c906108c
SS
2107
2108@kindex thread apply
2109@item thread apply [@var{threadno}] [@var{all}] @var{args}
2110The @code{thread apply} command allows you to apply a command to one or
2111more threads. Specify the numbers of the threads that you want affected
2112with the command argument @var{threadno}. @var{threadno} is the internal
2113@value{GDBN} thread number, as shown in the first field of the @samp{info
5d161b24
DB
2114threads} display. To apply a command to all threads, use
2115@code{thread apply all} @var{args}.
c906108c
SS
2116@end table
2117
2118@cindex automatic thread selection
2119@cindex switching threads automatically
2120@cindex threads, automatic switching
2121Whenever @value{GDBN} stops your program, due to a breakpoint or a
2122signal, it automatically selects the thread where that breakpoint or
2123signal happened. @value{GDBN} alerts you to the context switch with a
2124message of the form @samp{[Switching to @var{systag}]} to identify the
2125thread.
2126
2127@xref{Thread Stops,,Stopping and starting multi-thread programs}, for
2128more information about how @value{GDBN} behaves when you stop and start
2129programs with multiple threads.
2130
2131@xref{Set Watchpoints,,Setting watchpoints}, for information about
2132watchpoints in programs with multiple threads.
c906108c 2133
6d2ebf8b 2134@node Processes
c906108c
SS
2135@section Debugging programs with multiple processes
2136
2137@cindex fork, debugging programs which call
2138@cindex multiple processes
2139@cindex processes, multiple
53a5351d
JM
2140On most systems, @value{GDBN} has no special support for debugging
2141programs which create additional processes using the @code{fork}
2142function. When a program forks, @value{GDBN} will continue to debug the
2143parent process and the child process will run unimpeded. If you have
2144set a breakpoint in any code which the child then executes, the child
2145will get a @code{SIGTRAP} signal which (unless it catches the signal)
2146will cause it to terminate.
c906108c
SS
2147
2148However, if you want to debug the child process there is a workaround
2149which isn't too painful. Put a call to @code{sleep} in the code which
2150the child process executes after the fork. It may be useful to sleep
2151only if a certain environment variable is set, or a certain file exists,
2152so that the delay need not occur when you don't want to run @value{GDBN}
2153on the child. While the child is sleeping, use the @code{ps} program to
2154get its process ID. Then tell @value{GDBN} (a new invocation of
2155@value{GDBN} if you are also debugging the parent process) to attach to
d4f3574e 2156the child process (@pxref{Attach}). From that point on you can debug
c906108c 2157the child process just like any other process which you attached to.
c906108c 2158
53a5351d
JM
2159On HP-UX (11.x and later only?), @value{GDBN} provides support for
2160debugging programs that create additional processes using the
2161@code{fork} or @code{vfork} function.
c906108c
SS
2162
2163By default, when a program forks, @value{GDBN} will continue to debug
2164the parent process and the child process will run unimpeded.
2165
2166If you want to follow the child process instead of the parent process,
2167use the command @w{@code{set follow-fork-mode}}.
2168
2169@table @code
2170@kindex set follow-fork-mode
2171@item set follow-fork-mode @var{mode}
2172Set the debugger response to a program call of @code{fork} or
2173@code{vfork}. A call to @code{fork} or @code{vfork} creates a new
2174process. The @var{mode} can be:
2175
2176@table @code
2177@item parent
2178The original process is debugged after a fork. The child process runs
2df3850c 2179unimpeded. This is the default.
c906108c
SS
2180
2181@item child
2182The new process is debugged after a fork. The parent process runs
2183unimpeded.
2184
2185@item ask
2186The debugger will ask for one of the above choices.
2187@end table
2188
2189@item show follow-fork-mode
2df3850c 2190Display the current debugger response to a @code{fork} or @code{vfork} call.
c906108c
SS
2191@end table
2192
2193If you ask to debug a child process and a @code{vfork} is followed by an
2194@code{exec}, @value{GDBN} executes the new target up to the first
2195breakpoint in the new target. If you have a breakpoint set on
2196@code{main} in your original program, the breakpoint will also be set on
2197the child process's @code{main}.
2198
2199When a child process is spawned by @code{vfork}, you cannot debug the
2200child or parent until an @code{exec} call completes.
2201
2202If you issue a @code{run} command to @value{GDBN} after an @code{exec}
2203call executes, the new target restarts. To restart the parent process,
2204use the @code{file} command with the parent executable name as its
2205argument.
2206
2207You can use the @code{catch} command to make @value{GDBN} stop whenever
2208a @code{fork}, @code{vfork}, or @code{exec} call is made. @xref{Set
2209Catchpoints, ,Setting catchpoints}.
c906108c 2210
6d2ebf8b 2211@node Stopping
c906108c
SS
2212@chapter Stopping and Continuing
2213
2214The principal purposes of using a debugger are so that you can stop your
2215program before it terminates; or so that, if your program runs into
2216trouble, you can investigate and find out why.
2217
7a292a7a
SS
2218Inside @value{GDBN}, your program may stop for any of several reasons,
2219such as a signal, a breakpoint, or reaching a new line after a
2220@value{GDBN} command such as @code{step}. You may then examine and
2221change variables, set new breakpoints or remove old ones, and then
2222continue execution. Usually, the messages shown by @value{GDBN} provide
2223ample explanation of the status of your program---but you can also
2224explicitly request this information at any time.
c906108c
SS
2225
2226@table @code
2227@kindex info program
2228@item info program
2229Display information about the status of your program: whether it is
7a292a7a 2230running or not, what process it is, and why it stopped.
c906108c
SS
2231@end table
2232
2233@menu
2234* Breakpoints:: Breakpoints, watchpoints, and catchpoints
2235* Continuing and Stepping:: Resuming execution
c906108c 2236* Signals:: Signals
c906108c 2237* Thread Stops:: Stopping and starting multi-thread programs
c906108c
SS
2238@end menu
2239
6d2ebf8b 2240@node Breakpoints
c906108c
SS
2241@section Breakpoints, watchpoints, and catchpoints
2242
2243@cindex breakpoints
2244A @dfn{breakpoint} makes your program stop whenever a certain point in
2245the program is reached. For each breakpoint, you can add conditions to
2246control in finer detail whether your program stops. You can set
2247breakpoints with the @code{break} command and its variants (@pxref{Set
2248Breaks, ,Setting breakpoints}), to specify the place where your program
2249should stop by line number, function name or exact address in the
2250program.
2251
2252In HP-UX, SunOS 4.x, SVR4, and Alpha OSF/1 configurations, you can set
2253breakpoints in shared libraries before the executable is run. There is
2254a minor limitation on HP-UX systems: you must wait until the executable
2255is run in order to set breakpoints in shared library routines that are
2256not called directly by the program (for example, routines that are
2257arguments in a @code{pthread_create} call).
2258
2259@cindex watchpoints
2260@cindex memory tracing
2261@cindex breakpoint on memory address
2262@cindex breakpoint on variable modification
2263A @dfn{watchpoint} is a special breakpoint that stops your program
2264when the value of an expression changes. You must use a different
2265command to set watchpoints (@pxref{Set Watchpoints, ,Setting
2266watchpoints}), but aside from that, you can manage a watchpoint like
2267any other breakpoint: you enable, disable, and delete both breakpoints
2268and watchpoints using the same commands.
2269
2270You can arrange to have values from your program displayed automatically
2271whenever @value{GDBN} stops at a breakpoint. @xref{Auto Display,,
2272Automatic display}.
2273
2274@cindex catchpoints
2275@cindex breakpoint on events
2276A @dfn{catchpoint} is another special breakpoint that stops your program
2277when a certain kind of event occurs, such as the throwing of a C++
2278exception or the loading of a library. As with watchpoints, you use a
2279different command to set a catchpoint (@pxref{Set Catchpoints, ,Setting
2280catchpoints}), but aside from that, you can manage a catchpoint like any
2281other breakpoint. (To stop when your program receives a signal, use the
d4f3574e 2282@code{handle} command; see @ref{Signals, ,Signals}.)
c906108c
SS
2283
2284@cindex breakpoint numbers
2285@cindex numbers for breakpoints
2286@value{GDBN} assigns a number to each breakpoint, watchpoint, or
2287catchpoint when you create it; these numbers are successive integers
2288starting with one. In many of the commands for controlling various
2289features of breakpoints you use the breakpoint number to say which
2290breakpoint you want to change. Each breakpoint may be @dfn{enabled} or
2291@dfn{disabled}; if disabled, it has no effect on your program until you
2292enable it again.
2293
c5394b80
JM
2294@cindex breakpoint ranges
2295@cindex ranges of breakpoints
2296Some @value{GDBN} commands accept a range of breakpoints on which to
2297operate. A breakpoint range is either a single breakpoint number, like
2298@samp{5}, or two such numbers, in increasing order, separated by a
2299hyphen, like @samp{5-7}. When a breakpoint range is given to a command,
2300all breakpoint in that range are operated on.
2301
c906108c
SS
2302@menu
2303* Set Breaks:: Setting breakpoints
2304* Set Watchpoints:: Setting watchpoints
2305* Set Catchpoints:: Setting catchpoints
2306* Delete Breaks:: Deleting breakpoints
2307* Disabling:: Disabling breakpoints
2308* Conditions:: Break conditions
2309* Break Commands:: Breakpoint command lists
c906108c 2310* Breakpoint Menus:: Breakpoint menus
d4f3574e 2311* Error in Breakpoints:: ``Cannot insert breakpoints''
c906108c
SS
2312@end menu
2313
6d2ebf8b 2314@node Set Breaks
c906108c
SS
2315@subsection Setting breakpoints
2316
5d161b24 2317@c FIXME LMB what does GDB do if no code on line of breakpt?
c906108c
SS
2318@c consider in particular declaration with/without initialization.
2319@c
2320@c FIXME 2 is there stuff on this already? break at fun start, already init?
2321
2322@kindex break
41afff9a
EZ
2323@kindex b @r{(@code{break})}
2324@vindex $bpnum@r{, convenience variable}
c906108c
SS
2325@cindex latest breakpoint
2326Breakpoints are set with the @code{break} command (abbreviated
5d161b24 2327@code{b}). The debugger convenience variable @samp{$bpnum} records the
f3b28801 2328number of the breakpoint you've set most recently; see @ref{Convenience
c906108c
SS
2329Vars,, Convenience variables}, for a discussion of what you can do with
2330convenience variables.
2331
2332You have several ways to say where the breakpoint should go.
2333
2334@table @code
2335@item break @var{function}
5d161b24 2336Set a breakpoint at entry to function @var{function}.
c906108c
SS
2337When using source languages that permit overloading of symbols, such as
2338C++, @var{function} may refer to more than one possible place to break.
2339@xref{Breakpoint Menus,,Breakpoint menus}, for a discussion of that situation.
c906108c
SS
2340
2341@item break +@var{offset}
2342@itemx break -@var{offset}
2343Set a breakpoint some number of lines forward or back from the position
d4f3574e 2344at which execution stopped in the currently selected @dfn{stack frame}.
2df3850c 2345(@xref{Frames, ,Frames}, for a description of stack frames.)
c906108c
SS
2346
2347@item break @var{linenum}
2348Set a breakpoint at line @var{linenum} in the current source file.
d4f3574e
SS
2349The current source file is the last file whose source text was printed.
2350The breakpoint will stop your program just before it executes any of the
c906108c
SS
2351code on that line.
2352
2353@item break @var{filename}:@var{linenum}
2354Set a breakpoint at line @var{linenum} in source file @var{filename}.
2355
2356@item break @var{filename}:@var{function}
2357Set a breakpoint at entry to function @var{function} found in file
2358@var{filename}. Specifying a file name as well as a function name is
2359superfluous except when multiple files contain similarly named
2360functions.
2361
2362@item break *@var{address}
2363Set a breakpoint at address @var{address}. You can use this to set
2364breakpoints in parts of your program which do not have debugging
2365information or source files.
2366
2367@item break
2368When called without any arguments, @code{break} sets a breakpoint at
2369the next instruction to be executed in the selected stack frame
2370(@pxref{Stack, ,Examining the Stack}). In any selected frame but the
2371innermost, this makes your program stop as soon as control
2372returns to that frame. This is similar to the effect of a
2373@code{finish} command in the frame inside the selected frame---except
2374that @code{finish} does not leave an active breakpoint. If you use
2375@code{break} without an argument in the innermost frame, @value{GDBN} stops
2376the next time it reaches the current location; this may be useful
2377inside loops.
2378
2379@value{GDBN} normally ignores breakpoints when it resumes execution, until at
2380least one instruction has been executed. If it did not do this, you
2381would be unable to proceed past a breakpoint without first disabling the
2382breakpoint. This rule applies whether or not the breakpoint already
2383existed when your program stopped.
2384
2385@item break @dots{} if @var{cond}
2386Set a breakpoint with condition @var{cond}; evaluate the expression
2387@var{cond} each time the breakpoint is reached, and stop only if the
2388value is nonzero---that is, if @var{cond} evaluates as true.
2389@samp{@dots{}} stands for one of the possible arguments described
2390above (or no argument) specifying where to break. @xref{Conditions,
2391,Break conditions}, for more information on breakpoint conditions.
2392
2393@kindex tbreak
2394@item tbreak @var{args}
2395Set a breakpoint enabled only for one stop. @var{args} are the
2396same as for the @code{break} command, and the breakpoint is set in the same
2397way, but the breakpoint is automatically deleted after the first time your
2398program stops there. @xref{Disabling, ,Disabling breakpoints}.
2399
c906108c
SS
2400@kindex hbreak
2401@item hbreak @var{args}
d4f3574e
SS
2402Set a hardware-assisted breakpoint. @var{args} are the same as for the
2403@code{break} command and the breakpoint is set in the same way, but the
c906108c
SS
2404breakpoint requires hardware support and some target hardware may not
2405have this support. The main purpose of this is EPROM/ROM code
d4f3574e
SS
2406debugging, so you can set a breakpoint at an instruction without
2407changing the instruction. This can be used with the new trap-generation
2408provided by SPARClite DSU and some x86-based targets. These targets
2409will generate traps when a program accesses some data or instruction
2410address that is assigned to the debug registers. However the hardware
2411breakpoint registers can take a limited number of breakpoints. For
2412example, on the DSU, only two data breakpoints can be set at a time, and
2413@value{GDBN} will reject this command if more than two are used. Delete
2414or disable unused hardware breakpoints before setting new ones
2415(@pxref{Disabling, ,Disabling}). @xref{Conditions, ,Break conditions}.
c906108c
SS
2416
2417@kindex thbreak
2418@item thbreak @var{args}
2419Set a hardware-assisted breakpoint enabled only for one stop. @var{args}
2420are the same as for the @code{hbreak} command and the breakpoint is set in
5d161b24 2421the same way. However, like the @code{tbreak} command,
c906108c
SS
2422the breakpoint is automatically deleted after the
2423first time your program stops there. Also, like the @code{hbreak}
5d161b24
DB
2424command, the breakpoint requires hardware support and some target hardware
2425may not have this support. @xref{Disabling, ,Disabling breakpoints}.
d4f3574e 2426See also @ref{Conditions, ,Break conditions}.
c906108c
SS
2427
2428@kindex rbreak
2429@cindex regular expression
2430@item rbreak @var{regex}
c906108c 2431Set breakpoints on all functions matching the regular expression
11cf8741
JM
2432@var{regex}. This command sets an unconditional breakpoint on all
2433matches, printing a list of all breakpoints it set. Once these
2434breakpoints are set, they are treated just like the breakpoints set with
2435the @code{break} command. You can delete them, disable them, or make
2436them conditional the same way as any other breakpoint.
2437
2438The syntax of the regular expression is the standard one used with tools
2439like @file{grep}. Note that this is different from the syntax used by
2440shells, so for instance @code{foo*} matches all functions that include
2441an @code{fo} followed by zero or more @code{o}s. There is an implicit
2442@code{.*} leading and trailing the regular expression you supply, so to
2443match only functions that begin with @code{foo}, use @code{^foo}.
c906108c 2444
c906108c
SS
2445When debugging C++ programs, @code{rbreak} is useful for setting
2446breakpoints on overloaded functions that are not members of any special
2447classes.
c906108c
SS
2448
2449@kindex info breakpoints
2450@cindex @code{$_} and @code{info breakpoints}
2451@item info breakpoints @r{[}@var{n}@r{]}
2452@itemx info break @r{[}@var{n}@r{]}
2453@itemx info watchpoints @r{[}@var{n}@r{]}
2454Print a table of all breakpoints, watchpoints, and catchpoints set and
2455not deleted, with the following columns for each breakpoint:
2456
2457@table @emph
2458@item Breakpoint Numbers
2459@item Type
2460Breakpoint, watchpoint, or catchpoint.
2461@item Disposition
2462Whether the breakpoint is marked to be disabled or deleted when hit.
2463@item Enabled or Disabled
2464Enabled breakpoints are marked with @samp{y}. @samp{n} marks breakpoints
2465that are not enabled.
2466@item Address
2df3850c 2467Where the breakpoint is in your program, as a memory address.
c906108c
SS
2468@item What
2469Where the breakpoint is in the source for your program, as a file and
2470line number.
2471@end table
2472
2473@noindent
2474If a breakpoint is conditional, @code{info break} shows the condition on
2475the line following the affected breakpoint; breakpoint commands, if any,
2476are listed after that.
2477
2478@noindent
2479@code{info break} with a breakpoint
2480number @var{n} as argument lists only that breakpoint. The
2481convenience variable @code{$_} and the default examining-address for
2482the @code{x} command are set to the address of the last breakpoint
5d161b24 2483listed (@pxref{Memory, ,Examining memory}).
c906108c
SS
2484
2485@noindent
2486@code{info break} displays a count of the number of times the breakpoint
2487has been hit. This is especially useful in conjunction with the
2488@code{ignore} command. You can ignore a large number of breakpoint
2489hits, look at the breakpoint info to see how many times the breakpoint
2490was hit, and then run again, ignoring one less than that number. This
2491will get you quickly to the last hit of that breakpoint.
2492@end table
2493
2494@value{GDBN} allows you to set any number of breakpoints at the same place in
2495your program. There is nothing silly or meaningless about this. When
2496the breakpoints are conditional, this is even useful
2497(@pxref{Conditions, ,Break conditions}).
2498
2499@cindex negative breakpoint numbers
2500@cindex internal @value{GDBN} breakpoints
2501@value{GDBN} itself sometimes sets breakpoints in your program for special
2502purposes, such as proper handling of @code{longjmp} (in C programs).
2503These internal breakpoints are assigned negative numbers, starting with
2504@code{-1}; @samp{info breakpoints} does not display them.
2505
2506You can see these breakpoints with the @value{GDBN} maintenance command
2507@samp{maint info breakpoints}.
2508
2509@table @code
2510@kindex maint info breakpoints
2511@item maint info breakpoints
2512Using the same format as @samp{info breakpoints}, display both the
2513breakpoints you've set explicitly, and those @value{GDBN} is using for
2514internal purposes. Internal breakpoints are shown with negative
2515breakpoint numbers. The type column identifies what kind of breakpoint
2516is shown:
2517
2518@table @code
2519@item breakpoint
2520Normal, explicitly set breakpoint.
2521
2522@item watchpoint
2523Normal, explicitly set watchpoint.
2524
2525@item longjmp
2526Internal breakpoint, used to handle correctly stepping through
2527@code{longjmp} calls.
2528
2529@item longjmp resume
2530Internal breakpoint at the target of a @code{longjmp}.
2531
2532@item until
2533Temporary internal breakpoint used by the @value{GDBN} @code{until} command.
2534
2535@item finish
2536Temporary internal breakpoint used by the @value{GDBN} @code{finish} command.
2537
c906108c
SS
2538@item shlib events
2539Shared library events.
53a5351d 2540
c906108c 2541@end table
53a5351d 2542
c906108c
SS
2543@end table
2544
2545
6d2ebf8b 2546@node Set Watchpoints
c906108c
SS
2547@subsection Setting watchpoints
2548
2549@cindex setting watchpoints
2550@cindex software watchpoints
2551@cindex hardware watchpoints
2552You can use a watchpoint to stop execution whenever the value of an
2553expression changes, without having to predict a particular place where
2554this may happen.
2555
2556Depending on your system, watchpoints may be implemented in software or
2df3850c 2557hardware. @value{GDBN} does software watchpointing by single-stepping your
c906108c
SS
2558program and testing the variable's value each time, which is hundreds of
2559times slower than normal execution. (But this may still be worth it, to
2560catch errors where you have no clue what part of your program is the
2561culprit.)
2562
d4f3574e 2563On some systems, such as HP-UX, Linux and some other x86-based targets,
2df3850c 2564@value{GDBN} includes support for
c906108c
SS
2565hardware watchpoints, which do not slow down the running of your
2566program.
2567
2568@table @code
2569@kindex watch
2570@item watch @var{expr}
2571Set a watchpoint for an expression. @value{GDBN} will break when @var{expr}
2572is written into by the program and its value changes.
2573
2574@kindex rwatch
2575@item rwatch @var{expr}
2576Set a watchpoint that will break when watch @var{expr} is read by the program.
c906108c
SS
2577
2578@kindex awatch
2579@item awatch @var{expr}
2df3850c 2580Set a watchpoint that will break when @var{expr} is either read or written into
7be570e7 2581by the program.
c906108c
SS
2582
2583@kindex info watchpoints
2584@item info watchpoints
2585This command prints a list of watchpoints, breakpoints, and catchpoints;
2586it is the same as @code{info break}.
2587@end table
2588
2589@value{GDBN} sets a @dfn{hardware watchpoint} if possible. Hardware
2590watchpoints execute very quickly, and the debugger reports a change in
2591value at the exact instruction where the change occurs. If @value{GDBN}
2592cannot set a hardware watchpoint, it sets a software watchpoint, which
2593executes more slowly and reports the change in value at the next
2594statement, not the instruction, after the change occurs.
2595
2596When you issue the @code{watch} command, @value{GDBN} reports
2597
2598@example
2599Hardware watchpoint @var{num}: @var{expr}
2600@end example
2601
2602@noindent
2603if it was able to set a hardware watchpoint.
2604
7be570e7
JM
2605Currently, the @code{awatch} and @code{rwatch} commands can only set
2606hardware watchpoints, because accesses to data that don't change the
2607value of the watched expression cannot be detected without examining
2608every instruction as it is being executed, and @value{GDBN} does not do
2609that currently. If @value{GDBN} finds that it is unable to set a
2610hardware breakpoint with the @code{awatch} or @code{rwatch} command, it
2611will print a message like this:
2612
2613@smallexample
2614Expression cannot be implemented with read/access watchpoint.
2615@end smallexample
2616
2617Sometimes, @value{GDBN} cannot set a hardware watchpoint because the
2618data type of the watched expression is wider than what a hardware
2619watchpoint on the target machine can handle. For example, some systems
2620can only watch regions that are up to 4 bytes wide; on such systems you
2621cannot set hardware watchpoints for an expression that yields a
2622double-precision floating-point number (which is typically 8 bytes
2623wide). As a work-around, it might be possible to break the large region
2624into a series of smaller ones and watch them with separate watchpoints.
2625
2626If you set too many hardware watchpoints, @value{GDBN} might be unable
2627to insert all of them when you resume the execution of your program.
2628Since the precise number of active watchpoints is unknown until such
2629time as the program is about to be resumed, @value{GDBN} might not be
2630able to warn you about this when you set the watchpoints, and the
2631warning will be printed only when the program is resumed:
2632
2633@smallexample
2634Hardware watchpoint @var{num}: Could not insert watchpoint
2635@end smallexample
2636
2637@noindent
2638If this happens, delete or disable some of the watchpoints.
2639
2640The SPARClite DSU will generate traps when a program accesses some data
2641or instruction address that is assigned to the debug registers. For the
2642data addresses, DSU facilitates the @code{watch} command. However the
2643hardware breakpoint registers can only take two data watchpoints, and
2644both watchpoints must be the same kind. For example, you can set two
2645watchpoints with @code{watch} commands, two with @code{rwatch} commands,
2646@strong{or} two with @code{awatch} commands, but you cannot set one
2647watchpoint with one command and the other with a different command.
c906108c
SS
2648@value{GDBN} will reject the command if you try to mix watchpoints.
2649Delete or disable unused watchpoint commands before setting new ones.
2650
2651If you call a function interactively using @code{print} or @code{call},
2df3850c 2652any watchpoints you have set will be inactive until @value{GDBN} reaches another
c906108c
SS
2653kind of breakpoint or the call completes.
2654
7be570e7
JM
2655@value{GDBN} automatically deletes watchpoints that watch local
2656(automatic) variables, or expressions that involve such variables, when
2657they go out of scope, that is, when the execution leaves the block in
2658which these variables were defined. In particular, when the program
2659being debugged terminates, @emph{all} local variables go out of scope,
2660and so only watchpoints that watch global variables remain set. If you
2661rerun the program, you will need to set all such watchpoints again. One
2662way of doing that would be to set a code breakpoint at the entry to the
2663@code{main} function and when it breaks, set all the watchpoints.
2664
c906108c
SS
2665@quotation
2666@cindex watchpoints and threads
2667@cindex threads and watchpoints
c906108c
SS
2668@emph{Warning:} In multi-thread programs, watchpoints have only limited
2669usefulness. With the current watchpoint implementation, @value{GDBN}
2670can only watch the value of an expression @emph{in a single thread}. If
2671you are confident that the expression can only change due to the current
2672thread's activity (and if you are also confident that no other thread
2673can become current), then you can use watchpoints as usual. However,
2674@value{GDBN} may not notice when a non-current thread's activity changes
2675the expression.
53a5351d 2676
d4f3574e 2677@c FIXME: this is almost identical to the previous paragraph.
53a5351d
JM
2678@emph{HP-UX Warning:} In multi-thread programs, software watchpoints
2679have only limited usefulness. If @value{GDBN} creates a software
2680watchpoint, it can only watch the value of an expression @emph{in a
2681single thread}. If you are confident that the expression can only
2682change due to the current thread's activity (and if you are also
2683confident that no other thread can become current), then you can use
2684software watchpoints as usual. However, @value{GDBN} may not notice
2685when a non-current thread's activity changes the expression. (Hardware
2686watchpoints, in contrast, watch an expression in all threads.)
c906108c 2687@end quotation
c906108c 2688
6d2ebf8b 2689@node Set Catchpoints
c906108c 2690@subsection Setting catchpoints
d4f3574e 2691@cindex catchpoints, setting
c906108c
SS
2692@cindex exception handlers
2693@cindex event handling
2694
2695You can use @dfn{catchpoints} to cause the debugger to stop for certain
2696kinds of program events, such as C++ exceptions or the loading of a
2697shared library. Use the @code{catch} command to set a catchpoint.
2698
2699@table @code
2700@kindex catch
2701@item catch @var{event}
2702Stop when @var{event} occurs. @var{event} can be any of the following:
2703@table @code
2704@item throw
2705@kindex catch throw
2706The throwing of a C++ exception.
2707
2708@item catch
2709@kindex catch catch
2710The catching of a C++ exception.
2711
2712@item exec
2713@kindex catch exec
2714A call to @code{exec}. This is currently only available for HP-UX.
2715
2716@item fork
2717@kindex catch fork
2718A call to @code{fork}. This is currently only available for HP-UX.
2719
2720@item vfork
2721@kindex catch vfork
2722A call to @code{vfork}. This is currently only available for HP-UX.
2723
2724@item load
2725@itemx load @var{libname}
2726@kindex catch load
2727The dynamic loading of any shared library, or the loading of the library
2728@var{libname}. This is currently only available for HP-UX.
2729
2730@item unload
2731@itemx unload @var{libname}
2732@kindex catch unload
2733The unloading of any dynamically loaded shared library, or the unloading
2734of the library @var{libname}. This is currently only available for HP-UX.
2735@end table
2736
2737@item tcatch @var{event}
2738Set a catchpoint that is enabled only for one stop. The catchpoint is
2739automatically deleted after the first time the event is caught.
2740
2741@end table
2742
2743Use the @code{info break} command to list the current catchpoints.
2744
2745There are currently some limitations to C++ exception handling
2746(@code{catch throw} and @code{catch catch}) in @value{GDBN}:
2747
2748@itemize @bullet
2749@item
2750If you call a function interactively, @value{GDBN} normally returns
2751control to you when the function has finished executing. If the call
2752raises an exception, however, the call may bypass the mechanism that
2753returns control to you and cause your program either to abort or to
2754simply continue running until it hits a breakpoint, catches a signal
2755that @value{GDBN} is listening for, or exits. This is the case even if
2756you set a catchpoint for the exception; catchpoints on exceptions are
2757disabled within interactive calls.
2758
2759@item
2760You cannot raise an exception interactively.
2761
2762@item
2763You cannot install an exception handler interactively.
2764@end itemize
2765
2766@cindex raise exceptions
2767Sometimes @code{catch} is not the best way to debug exception handling:
2768if you need to know exactly where an exception is raised, it is better to
2769stop @emph{before} the exception handler is called, since that way you
2770can see the stack before any unwinding takes place. If you set a
2771breakpoint in an exception handler instead, it may not be easy to find
2772out where the exception was raised.
2773
2774To stop just before an exception handler is called, you need some
2775knowledge of the implementation. In the case of @sc{gnu} C++, exceptions are
2776raised by calling a library function named @code{__raise_exception}
2777which has the following ANSI C interface:
2778
2779@example
2780 /* @var{addr} is where the exception identifier is stored.
d4f3574e
SS
2781 @var{id} is the exception identifier. */
2782 void __raise_exception (void **addr, void *id);
c906108c
SS
2783@end example
2784
2785@noindent
2786To make the debugger catch all exceptions before any stack
2787unwinding takes place, set a breakpoint on @code{__raise_exception}
2788(@pxref{Breakpoints, ,Breakpoints; watchpoints; and exceptions}).
2789
2790With a conditional breakpoint (@pxref{Conditions, ,Break conditions})
2791that depends on the value of @var{id}, you can stop your program when
2792a specific exception is raised. You can use multiple conditional
2793breakpoints to stop your program when any of a number of exceptions are
2794raised.
2795
2796
6d2ebf8b 2797@node Delete Breaks
c906108c
SS
2798@subsection Deleting breakpoints
2799
2800@cindex clearing breakpoints, watchpoints, catchpoints
2801@cindex deleting breakpoints, watchpoints, catchpoints
2802It is often necessary to eliminate a breakpoint, watchpoint, or
2803catchpoint once it has done its job and you no longer want your program
2804to stop there. This is called @dfn{deleting} the breakpoint. A
2805breakpoint that has been deleted no longer exists; it is forgotten.
2806
2807With the @code{clear} command you can delete breakpoints according to
2808where they are in your program. With the @code{delete} command you can
2809delete individual breakpoints, watchpoints, or catchpoints by specifying
2810their breakpoint numbers.
2811
2812It is not necessary to delete a breakpoint to proceed past it. @value{GDBN}
2813automatically ignores breakpoints on the first instruction to be executed
2814when you continue execution without changing the execution address.
2815
2816@table @code
2817@kindex clear
2818@item clear
2819Delete any breakpoints at the next instruction to be executed in the
2820selected stack frame (@pxref{Selection, ,Selecting a frame}). When
2821the innermost frame is selected, this is a good way to delete a
2822breakpoint where your program just stopped.
2823
2824@item clear @var{function}
2825@itemx clear @var{filename}:@var{function}
2826Delete any breakpoints set at entry to the function @var{function}.
2827
2828@item clear @var{linenum}
2829@itemx clear @var{filename}:@var{linenum}
2830Delete any breakpoints set at or within the code of the specified line.
2831
2832@cindex delete breakpoints
2833@kindex delete
41afff9a 2834@kindex d @r{(@code{delete})}
c5394b80
JM
2835@item delete @r{[}breakpoints@r{]} @r{[}@var{range}@dots{}@r{]}
2836Delete the breakpoints, watchpoints, or catchpoints of the breakpoint
2837ranges specified as arguments. If no argument is specified, delete all
c906108c
SS
2838breakpoints (@value{GDBN} asks confirmation, unless you have @code{set
2839confirm off}). You can abbreviate this command as @code{d}.
2840@end table
2841
6d2ebf8b 2842@node Disabling
c906108c
SS
2843@subsection Disabling breakpoints
2844
2845@kindex disable breakpoints
2846@kindex enable breakpoints
2847Rather than deleting a breakpoint, watchpoint, or catchpoint, you might
2848prefer to @dfn{disable} it. This makes the breakpoint inoperative as if
2849it had been deleted, but remembers the information on the breakpoint so
2850that you can @dfn{enable} it again later.
2851
2852You disable and enable breakpoints, watchpoints, and catchpoints with
2853the @code{enable} and @code{disable} commands, optionally specifying one
2854or more breakpoint numbers as arguments. Use @code{info break} or
2855@code{info watch} to print a list of breakpoints, watchpoints, and
2856catchpoints if you do not know which numbers to use.
2857
2858A breakpoint, watchpoint, or catchpoint can have any of four different
2859states of enablement:
2860
2861@itemize @bullet
2862@item
2863Enabled. The breakpoint stops your program. A breakpoint set
2864with the @code{break} command starts out in this state.
2865@item
2866Disabled. The breakpoint has no effect on your program.
2867@item
2868Enabled once. The breakpoint stops your program, but then becomes
d4f3574e 2869disabled.
c906108c
SS
2870@item
2871Enabled for deletion. The breakpoint stops your program, but
d4f3574e
SS
2872immediately after it does so it is deleted permanently. A breakpoint
2873set with the @code{tbreak} command starts out in this state.
c906108c
SS
2874@end itemize
2875
2876You can use the following commands to enable or disable breakpoints,
2877watchpoints, and catchpoints:
2878
2879@table @code
2880@kindex disable breakpoints
2881@kindex disable
41afff9a 2882@kindex dis @r{(@code{disable})}
c5394b80 2883@item disable @r{[}breakpoints@r{]} @r{[}@var{range}@dots{}@r{]}
c906108c
SS
2884Disable the specified breakpoints---or all breakpoints, if none are
2885listed. A disabled breakpoint has no effect but is not forgotten. All
2886options such as ignore-counts, conditions and commands are remembered in
2887case the breakpoint is enabled again later. You may abbreviate
2888@code{disable} as @code{dis}.
2889
2890@kindex enable breakpoints
2891@kindex enable
c5394b80 2892@item enable @r{[}breakpoints@r{]} @r{[}@var{range}@dots{}@r{]}
c906108c
SS
2893Enable the specified breakpoints (or all defined breakpoints). They
2894become effective once again in stopping your program.
2895
c5394b80 2896@item enable @r{[}breakpoints@r{]} once @var{range}@dots{}
c906108c
SS
2897Enable the specified breakpoints temporarily. @value{GDBN} disables any
2898of these breakpoints immediately after stopping your program.
2899
c5394b80 2900@item enable @r{[}breakpoints@r{]} delete @var{range}@dots{}
c906108c
SS
2901Enable the specified breakpoints to work once, then die. @value{GDBN}
2902deletes any of these breakpoints as soon as your program stops there.
2903@end table
2904
d4f3574e
SS
2905@c FIXME: I think the following ``Except for [...] @code{tbreak}'' is
2906@c confusing: tbreak is also initially enabled.
c906108c
SS
2907Except for a breakpoint set with @code{tbreak} (@pxref{Set Breaks,
2908,Setting breakpoints}), breakpoints that you set are initially enabled;
2909subsequently, they become disabled or enabled only when you use one of
2910the commands above. (The command @code{until} can set and delete a
2911breakpoint of its own, but it does not change the state of your other
2912breakpoints; see @ref{Continuing and Stepping, ,Continuing and
2913stepping}.)
2914
6d2ebf8b 2915@node Conditions
c906108c
SS
2916@subsection Break conditions
2917@cindex conditional breakpoints
2918@cindex breakpoint conditions
2919
2920@c FIXME what is scope of break condition expr? Context where wanted?
5d161b24 2921@c in particular for a watchpoint?
c906108c
SS
2922The simplest sort of breakpoint breaks every time your program reaches a
2923specified place. You can also specify a @dfn{condition} for a
2924breakpoint. A condition is just a Boolean expression in your
2925programming language (@pxref{Expressions, ,Expressions}). A breakpoint with
2926a condition evaluates the expression each time your program reaches it,
2927and your program stops only if the condition is @emph{true}.
2928
2929This is the converse of using assertions for program validation; in that
2930situation, you want to stop when the assertion is violated---that is,
2931when the condition is false. In C, if you want to test an assertion expressed
2932by the condition @var{assert}, you should set the condition
2933@samp{! @var{assert}} on the appropriate breakpoint.
2934
2935Conditions are also accepted for watchpoints; you may not need them,
2936since a watchpoint is inspecting the value of an expression anyhow---but
2937it might be simpler, say, to just set a watchpoint on a variable name,
2938and specify a condition that tests whether the new value is an interesting
2939one.
2940
2941Break conditions can have side effects, and may even call functions in
2942your program. This can be useful, for example, to activate functions
2943that log program progress, or to use your own print functions to
2944format special data structures. The effects are completely predictable
2945unless there is another enabled breakpoint at the same address. (In
2946that case, @value{GDBN} might see the other breakpoint first and stop your
2947program without checking the condition of this one.) Note that
d4f3574e
SS
2948breakpoint commands are usually more convenient and flexible than break
2949conditions for the
c906108c
SS
2950purpose of performing side effects when a breakpoint is reached
2951(@pxref{Break Commands, ,Breakpoint command lists}).
2952
2953Break conditions can be specified when a breakpoint is set, by using
2954@samp{if} in the arguments to the @code{break} command. @xref{Set
2955Breaks, ,Setting breakpoints}. They can also be changed at any time
2956with the @code{condition} command.
53a5351d 2957
c906108c
SS
2958You can also use the @code{if} keyword with the @code{watch} command.
2959The @code{catch} command does not recognize the @code{if} keyword;
2960@code{condition} is the only way to impose a further condition on a
2961catchpoint.
c906108c
SS
2962
2963@table @code
2964@kindex condition
2965@item condition @var{bnum} @var{expression}
2966Specify @var{expression} as the break condition for breakpoint,
2967watchpoint, or catchpoint number @var{bnum}. After you set a condition,
2968breakpoint @var{bnum} stops your program only if the value of
2969@var{expression} is true (nonzero, in C). When you use
2970@code{condition}, @value{GDBN} checks @var{expression} immediately for
2971syntactic correctness, and to determine whether symbols in it have
d4f3574e
SS
2972referents in the context of your breakpoint. If @var{expression} uses
2973symbols not referenced in the context of the breakpoint, @value{GDBN}
2974prints an error message:
2975
2976@example
2977No symbol "foo" in current context.
2978@end example
2979
2980@noindent
c906108c
SS
2981@value{GDBN} does
2982not actually evaluate @var{expression} at the time the @code{condition}
d4f3574e
SS
2983command (or a command that sets a breakpoint with a condition, like
2984@code{break if @dots{}}) is given, however. @xref{Expressions, ,Expressions}.
c906108c
SS
2985
2986@item condition @var{bnum}
2987Remove the condition from breakpoint number @var{bnum}. It becomes
2988an ordinary unconditional breakpoint.
2989@end table
2990
2991@cindex ignore count (of breakpoint)
2992A special case of a breakpoint condition is to stop only when the
2993breakpoint has been reached a certain number of times. This is so
2994useful that there is a special way to do it, using the @dfn{ignore
2995count} of the breakpoint. Every breakpoint has an ignore count, which
2996is an integer. Most of the time, the ignore count is zero, and
2997therefore has no effect. But if your program reaches a breakpoint whose
2998ignore count is positive, then instead of stopping, it just decrements
2999the ignore count by one and continues. As a result, if the ignore count
3000value is @var{n}, the breakpoint does not stop the next @var{n} times
3001your program reaches it.
3002
3003@table @code
3004@kindex ignore
3005@item ignore @var{bnum} @var{count}
3006Set the ignore count of breakpoint number @var{bnum} to @var{count}.
3007The next @var{count} times the breakpoint is reached, your program's
3008execution does not stop; other than to decrement the ignore count, @value{GDBN}
3009takes no action.
3010
3011To make the breakpoint stop the next time it is reached, specify
3012a count of zero.
3013
3014When you use @code{continue} to resume execution of your program from a
3015breakpoint, you can specify an ignore count directly as an argument to
3016@code{continue}, rather than using @code{ignore}. @xref{Continuing and
3017Stepping,,Continuing and stepping}.
3018
3019If a breakpoint has a positive ignore count and a condition, the
3020condition is not checked. Once the ignore count reaches zero,
3021@value{GDBN} resumes checking the condition.
3022
3023You could achieve the effect of the ignore count with a condition such
3024as @w{@samp{$foo-- <= 0}} using a debugger convenience variable that
3025is decremented each time. @xref{Convenience Vars, ,Convenience
3026variables}.
3027@end table
3028
3029Ignore counts apply to breakpoints, watchpoints, and catchpoints.
3030
3031
6d2ebf8b 3032@node Break Commands
c906108c
SS
3033@subsection Breakpoint command lists
3034
3035@cindex breakpoint commands
3036You can give any breakpoint (or watchpoint or catchpoint) a series of
3037commands to execute when your program stops due to that breakpoint. For
3038example, you might want to print the values of certain expressions, or
3039enable other breakpoints.
3040
3041@table @code
3042@kindex commands
3043@kindex end
3044@item commands @r{[}@var{bnum}@r{]}
3045@itemx @dots{} @var{command-list} @dots{}
3046@itemx end
3047Specify a list of commands for breakpoint number @var{bnum}. The commands
3048themselves appear on the following lines. Type a line containing just
3049@code{end} to terminate the commands.
3050
3051To remove all commands from a breakpoint, type @code{commands} and
3052follow it immediately with @code{end}; that is, give no commands.
3053
3054With no @var{bnum} argument, @code{commands} refers to the last
3055breakpoint, watchpoint, or catchpoint set (not to the breakpoint most
3056recently encountered).
3057@end table
3058
3059Pressing @key{RET} as a means of repeating the last @value{GDBN} command is
3060disabled within a @var{command-list}.
3061
3062You can use breakpoint commands to start your program up again. Simply
3063use the @code{continue} command, or @code{step}, or any other command
3064that resumes execution.
3065
3066Any other commands in the command list, after a command that resumes
3067execution, are ignored. This is because any time you resume execution
3068(even with a simple @code{next} or @code{step}), you may encounter
3069another breakpoint---which could have its own command list, leading to
3070ambiguities about which list to execute.
3071
3072@kindex silent
3073If the first command you specify in a command list is @code{silent}, the
3074usual message about stopping at a breakpoint is not printed. This may
3075be desirable for breakpoints that are to print a specific message and
3076then continue. If none of the remaining commands print anything, you
3077see no sign that the breakpoint was reached. @code{silent} is
3078meaningful only at the beginning of a breakpoint command list.
3079
3080The commands @code{echo}, @code{output}, and @code{printf} allow you to
3081print precisely controlled output, and are often useful in silent
3082breakpoints. @xref{Output, ,Commands for controlled output}.
3083
3084For example, here is how you could use breakpoint commands to print the
3085value of @code{x} at entry to @code{foo} whenever @code{x} is positive.
3086
3087@example
3088break foo if x>0
3089commands
3090silent
3091printf "x is %d\n",x
3092cont
3093end
3094@end example
3095
3096One application for breakpoint commands is to compensate for one bug so
3097you can test for another. Put a breakpoint just after the erroneous line
3098of code, give it a condition to detect the case in which something
3099erroneous has been done, and give it commands to assign correct values
3100to any variables that need them. End with the @code{continue} command
3101so that your program does not stop, and start with the @code{silent}
3102command so that no output is produced. Here is an example:
3103
3104@example
3105break 403
3106commands
3107silent
3108set x = y + 4
3109cont
3110end
3111@end example
3112
6d2ebf8b 3113@node Breakpoint Menus
c906108c
SS
3114@subsection Breakpoint menus
3115@cindex overloading
3116@cindex symbol overloading
3117
3118Some programming languages (notably C++) permit a single function name
3119to be defined several times, for application in different contexts.
3120This is called @dfn{overloading}. When a function name is overloaded,
3121@samp{break @var{function}} is not enough to tell @value{GDBN} where you want
3122a breakpoint. If you realize this is a problem, you can use
3123something like @samp{break @var{function}(@var{types})} to specify which
3124particular version of the function you want. Otherwise, @value{GDBN} offers
3125you a menu of numbered choices for different possible breakpoints, and
3126waits for your selection with the prompt @samp{>}. The first two
3127options are always @samp{[0] cancel} and @samp{[1] all}. Typing @kbd{1}
3128sets a breakpoint at each definition of @var{function}, and typing
3129@kbd{0} aborts the @code{break} command without setting any new
3130breakpoints.
3131
3132For example, the following session excerpt shows an attempt to set a
3133breakpoint at the overloaded symbol @code{String::after}.
3134We choose three particular definitions of that function name:
3135
3136@c FIXME! This is likely to change to show arg type lists, at least
3137@smallexample
3138@group
3139(@value{GDBP}) b String::after
3140[0] cancel
3141[1] all
3142[2] file:String.cc; line number:867
3143[3] file:String.cc; line number:860
3144[4] file:String.cc; line number:875
3145[5] file:String.cc; line number:853
3146[6] file:String.cc; line number:846
3147[7] file:String.cc; line number:735
3148> 2 4 6
3149Breakpoint 1 at 0xb26c: file String.cc, line 867.
3150Breakpoint 2 at 0xb344: file String.cc, line 875.
3151Breakpoint 3 at 0xafcc: file String.cc, line 846.
3152Multiple breakpoints were set.
3153Use the "delete" command to delete unwanted
3154 breakpoints.
3155(@value{GDBP})
3156@end group
3157@end smallexample
c906108c
SS
3158
3159@c @ifclear BARETARGET
6d2ebf8b 3160@node Error in Breakpoints
d4f3574e 3161@subsection ``Cannot insert breakpoints''
c906108c
SS
3162@c
3163@c FIXME!! 14/6/95 Is there a real example of this? Let's use it.
3164@c
d4f3574e
SS
3165Under some operating systems, breakpoints cannot be used in a program if
3166any other process is running that program. In this situation,
5d161b24 3167attempting to run or continue a program with a breakpoint causes
d4f3574e
SS
3168@value{GDBN} to print an error message:
3169
3170@example
3171Cannot insert breakpoints.
3172The same program may be running in another process.
3173@end example
3174
3175When this happens, you have three ways to proceed:
3176
3177@enumerate
3178@item
3179Remove or disable the breakpoints, then continue.
3180
3181@item
5d161b24 3182Suspend @value{GDBN}, and copy the file containing your program to a new
d4f3574e 3183name. Resume @value{GDBN} and use the @code{exec-file} command to specify
5d161b24 3184that @value{GDBN} should run your program under that name.
d4f3574e
SS
3185Then start your program again.
3186
3187@item
3188Relink your program so that the text segment is nonsharable, using the
3189linker option @samp{-N}. The operating system limitation may not apply
3190to nonsharable executables.
3191@end enumerate
c906108c
SS
3192@c @end ifclear
3193
d4f3574e
SS
3194A similar message can be printed if you request too many active
3195hardware-assisted breakpoints and watchpoints:
3196
3197@c FIXME: the precise wording of this message may change; the relevant
3198@c source change is not committed yet (Sep 3, 1999).
3199@smallexample
3200Stopped; cannot insert breakpoints.
3201You may have requested too many hardware breakpoints and watchpoints.
3202@end smallexample
3203
3204@noindent
3205This message is printed when you attempt to resume the program, since
3206only then @value{GDBN} knows exactly how many hardware breakpoints and
3207watchpoints it needs to insert.
3208
3209When this message is printed, you need to disable or remove some of the
3210hardware-assisted breakpoints and watchpoints, and then continue.
3211
3212
6d2ebf8b 3213@node Continuing and Stepping
c906108c
SS
3214@section Continuing and stepping
3215
3216@cindex stepping
3217@cindex continuing
3218@cindex resuming execution
3219@dfn{Continuing} means resuming program execution until your program
3220completes normally. In contrast, @dfn{stepping} means executing just
3221one more ``step'' of your program, where ``step'' may mean either one
3222line of source code, or one machine instruction (depending on what
7a292a7a
SS
3223particular command you use). Either when continuing or when stepping,
3224your program may stop even sooner, due to a breakpoint or a signal. (If
d4f3574e
SS
3225it stops due to a signal, you may want to use @code{handle}, or use
3226@samp{signal 0} to resume execution. @xref{Signals, ,Signals}.)
c906108c
SS
3227
3228@table @code
3229@kindex continue
41afff9a
EZ
3230@kindex c @r{(@code{continue})}
3231@kindex fg @r{(resume foreground execution)}
c906108c
SS
3232@item continue @r{[}@var{ignore-count}@r{]}
3233@itemx c @r{[}@var{ignore-count}@r{]}
3234@itemx fg @r{[}@var{ignore-count}@r{]}
3235Resume program execution, at the address where your program last stopped;
3236any breakpoints set at that address are bypassed. The optional argument
3237@var{ignore-count} allows you to specify a further number of times to
3238ignore a breakpoint at this location; its effect is like that of
3239@code{ignore} (@pxref{Conditions, ,Break conditions}).
3240
3241The argument @var{ignore-count} is meaningful only when your program
3242stopped due to a breakpoint. At other times, the argument to
3243@code{continue} is ignored.
3244
d4f3574e
SS
3245The synonyms @code{c} and @code{fg} (for @dfn{foreground}, as the
3246debugged program is deemed to be the foreground program) are provided
3247purely for convenience, and have exactly the same behavior as
3248@code{continue}.
c906108c
SS
3249@end table
3250
3251To resume execution at a different place, you can use @code{return}
3252(@pxref{Returning, ,Returning from a function}) to go back to the
3253calling function; or @code{jump} (@pxref{Jumping, ,Continuing at a
3254different address}) to go to an arbitrary location in your program.
3255
3256A typical technique for using stepping is to set a breakpoint
3257(@pxref{Breakpoints, ,Breakpoints; watchpoints; and catchpoints}) at the
3258beginning of the function or the section of your program where a problem
3259is believed to lie, run your program until it stops at that breakpoint,
3260and then step through the suspect area, examining the variables that are
3261interesting, until you see the problem happen.
3262
3263@table @code
3264@kindex step
41afff9a 3265@kindex s @r{(@code{step})}
c906108c
SS
3266@item step
3267Continue running your program until control reaches a different source
3268line, then stop it and return control to @value{GDBN}. This command is
3269abbreviated @code{s}.
3270
3271@quotation
3272@c "without debugging information" is imprecise; actually "without line
3273@c numbers in the debugging information". (gcc -g1 has debugging info but
3274@c not line numbers). But it seems complex to try to make that
3275@c distinction here.
3276@emph{Warning:} If you use the @code{step} command while control is
3277within a function that was compiled without debugging information,
3278execution proceeds until control reaches a function that does have
3279debugging information. Likewise, it will not step into a function which
3280is compiled without debugging information. To step through functions
3281without debugging information, use the @code{stepi} command, described
3282below.
3283@end quotation
3284
4a92d011
EZ
3285The @code{step} command only stops at the first instruction of a source
3286line. This prevents the multiple stops that could otherwise occur in
3287@code{switch} statements, @code{for} loops, etc. @code{step} continues
3288to stop if a function that has debugging information is called within
3289the line. In other words, @code{step} @emph{steps inside} any functions
3290called within the line.
c906108c 3291
d4f3574e
SS
3292Also, the @code{step} command only enters a function if there is line
3293number information for the function. Otherwise it acts like the
5d161b24 3294@code{next} command. This avoids problems when using @code{cc -gl}
c906108c 3295on MIPS machines. Previously, @code{step} entered subroutines if there
5d161b24 3296was any debugging information about the routine.
c906108c
SS
3297
3298@item step @var{count}
3299Continue running as in @code{step}, but do so @var{count} times. If a
7a292a7a
SS
3300breakpoint is reached, or a signal not related to stepping occurs before
3301@var{count} steps, stepping stops right away.
c906108c
SS
3302
3303@kindex next
41afff9a 3304@kindex n @r{(@code{next})}
c906108c
SS
3305@item next @r{[}@var{count}@r{]}
3306Continue to the next source line in the current (innermost) stack frame.
7a292a7a
SS
3307This is similar to @code{step}, but function calls that appear within
3308the line of code are executed without stopping. Execution stops when
3309control reaches a different line of code at the original stack level
3310that was executing when you gave the @code{next} command. This command
3311is abbreviated @code{n}.
c906108c
SS
3312
3313An argument @var{count} is a repeat count, as for @code{step}.
3314
3315
3316@c FIX ME!! Do we delete this, or is there a way it fits in with
3317@c the following paragraph? --- Vctoria
3318@c
3319@c @code{next} within a function that lacks debugging information acts like
3320@c @code{step}, but any function calls appearing within the code of the
3321@c function are executed without stopping.
3322
d4f3574e
SS
3323The @code{next} command only stops at the first instruction of a
3324source line. This prevents multiple stops that could otherwise occur in
4a92d011 3325@code{switch} statements, @code{for} loops, etc.
c906108c 3326
b90a5f51
CF
3327@kindex set step-mode
3328@item set step-mode
3329@cindex functions without line info, and stepping
3330@cindex stepping into functions with no line info
3331@itemx set step-mode on
4a92d011 3332The @code{set step-mode on} command causes the @code{step} command to
b90a5f51
CF
3333stop at the first instruction of a function which contains no debug line
3334information rather than stepping over it.
3335
4a92d011
EZ
3336This is useful in cases where you may be interested in inspecting the
3337machine instructions of a function which has no symbolic info and do not
3338want @value{GDBN} to automatically skip over this function.
b90a5f51
CF
3339
3340@item set step-mode off
4a92d011 3341Causes the @code{step} command to step over any functions which contains no
b90a5f51
CF
3342debug information. This is the default.
3343
c906108c
SS
3344@kindex finish
3345@item finish
3346Continue running until just after function in the selected stack frame
3347returns. Print the returned value (if any).
3348
3349Contrast this with the @code{return} command (@pxref{Returning,
3350,Returning from a function}).
3351
3352@kindex until
41afff9a 3353@kindex u @r{(@code{until})}
c906108c
SS
3354@item until
3355@itemx u
3356Continue running until a source line past the current line, in the
3357current stack frame, is reached. This command is used to avoid single
3358stepping through a loop more than once. It is like the @code{next}
3359command, except that when @code{until} encounters a jump, it
3360automatically continues execution until the program counter is greater
3361than the address of the jump.
3362
3363This means that when you reach the end of a loop after single stepping
3364though it, @code{until} makes your program continue execution until it
3365exits the loop. In contrast, a @code{next} command at the end of a loop
3366simply steps back to the beginning of the loop, which forces you to step
3367through the next iteration.
3368
3369@code{until} always stops your program if it attempts to exit the current
3370stack frame.
3371
3372@code{until} may produce somewhat counterintuitive results if the order
3373of machine code does not match the order of the source lines. For
3374example, in the following excerpt from a debugging session, the @code{f}
3375(@code{frame}) command shows that execution is stopped at line
3376@code{206}; yet when we use @code{until}, we get to line @code{195}:
3377
3378@example
3379(@value{GDBP}) f
3380#0 main (argc=4, argv=0xf7fffae8) at m4.c:206
3381206 expand_input();
3382(@value{GDBP}) until
3383195 for ( ; argc > 0; NEXTARG) @{
3384@end example
3385
3386This happened because, for execution efficiency, the compiler had
3387generated code for the loop closure test at the end, rather than the
3388start, of the loop---even though the test in a C @code{for}-loop is
3389written before the body of the loop. The @code{until} command appeared
3390to step back to the beginning of the loop when it advanced to this
3391expression; however, it has not really gone to an earlier
3392statement---not in terms of the actual machine code.
3393
3394@code{until} with no argument works by means of single
3395instruction stepping, and hence is slower than @code{until} with an
3396argument.
3397
3398@item until @var{location}
3399@itemx u @var{location}
3400Continue running your program until either the specified location is
3401reached, or the current stack frame returns. @var{location} is any of
3402the forms of argument acceptable to @code{break} (@pxref{Set Breaks,
3403,Setting breakpoints}). This form of the command uses breakpoints,
3404and hence is quicker than @code{until} without an argument.
3405
3406@kindex stepi
41afff9a 3407@kindex si @r{(@code{stepi})}
c906108c 3408@item stepi
96a2c332 3409@itemx stepi @var{arg}
c906108c
SS
3410@itemx si
3411Execute one machine instruction, then stop and return to the debugger.
3412
3413It is often useful to do @samp{display/i $pc} when stepping by machine
3414instructions. This makes @value{GDBN} automatically display the next
3415instruction to be executed, each time your program stops. @xref{Auto
3416Display,, Automatic display}.
3417
3418An argument is a repeat count, as in @code{step}.
3419
3420@need 750
3421@kindex nexti
41afff9a 3422@kindex ni @r{(@code{nexti})}
c906108c 3423@item nexti
96a2c332 3424@itemx nexti @var{arg}
c906108c
SS
3425@itemx ni
3426Execute one machine instruction, but if it is a function call,
3427proceed until the function returns.
3428
3429An argument is a repeat count, as in @code{next}.
3430@end table
3431
6d2ebf8b 3432@node Signals
c906108c
SS
3433@section Signals
3434@cindex signals
3435
3436A signal is an asynchronous event that can happen in a program. The
3437operating system defines the possible kinds of signals, and gives each
3438kind a name and a number. For example, in Unix @code{SIGINT} is the
d4f3574e 3439signal a program gets when you type an interrupt character (often @kbd{C-c});
c906108c
SS
3440@code{SIGSEGV} is the signal a program gets from referencing a place in
3441memory far away from all the areas in use; @code{SIGALRM} occurs when
3442the alarm clock timer goes off (which happens only if your program has
3443requested an alarm).
3444
3445@cindex fatal signals
3446Some signals, including @code{SIGALRM}, are a normal part of the
3447functioning of your program. Others, such as @code{SIGSEGV}, indicate
d4f3574e 3448errors; these signals are @dfn{fatal} (they kill your program immediately) if the
c906108c
SS
3449program has not specified in advance some other way to handle the signal.
3450@code{SIGINT} does not indicate an error in your program, but it is normally
3451fatal so it can carry out the purpose of the interrupt: to kill the program.
3452
3453@value{GDBN} has the ability to detect any occurrence of a signal in your
3454program. You can tell @value{GDBN} in advance what to do for each kind of
3455signal.
3456
3457@cindex handling signals
3458Normally, @value{GDBN} is set up to ignore non-erroneous signals like @code{SIGALRM}
3459(so as not to interfere with their role in the functioning of your program)
3460but to stop your program immediately whenever an error signal happens.
3461You can change these settings with the @code{handle} command.
3462
3463@table @code
3464@kindex info signals
3465@item info signals
96a2c332 3466@itemx info handle
c906108c
SS
3467Print a table of all the kinds of signals and how @value{GDBN} has been told to
3468handle each one. You can use this to see the signal numbers of all
3469the defined types of signals.
3470
d4f3574e 3471@code{info handle} is an alias for @code{info signals}.
c906108c
SS
3472
3473@kindex handle
3474@item handle @var{signal} @var{keywords}@dots{}
5d161b24 3475Change the way @value{GDBN} handles signal @var{signal}. @var{signal} can
c906108c
SS
3476be the number of a signal or its name (with or without the @samp{SIG} at the
3477beginning). The @var{keywords} say what change to make.
3478@end table
3479
3480@c @group
3481The keywords allowed by the @code{handle} command can be abbreviated.
3482Their full names are:
3483
3484@table @code
3485@item nostop
3486@value{GDBN} should not stop your program when this signal happens. It may
3487still print a message telling you that the signal has come in.
3488
3489@item stop
3490@value{GDBN} should stop your program when this signal happens. This implies
3491the @code{print} keyword as well.
3492
3493@item print
3494@value{GDBN} should print a message when this signal happens.
3495
3496@item noprint
3497@value{GDBN} should not mention the occurrence of the signal at all. This
3498implies the @code{nostop} keyword as well.
3499
3500@item pass
3501@value{GDBN} should allow your program to see this signal; your program
3502can handle the signal, or else it may terminate if the signal is fatal
3503and not handled.
3504
3505@item nopass
3506@value{GDBN} should not allow your program to see this signal.
3507@end table
3508@c @end group
3509
d4f3574e
SS
3510When a signal stops your program, the signal is not visible to the
3511program until you
c906108c
SS
3512continue. Your program sees the signal then, if @code{pass} is in
3513effect for the signal in question @emph{at that time}. In other words,
3514after @value{GDBN} reports a signal, you can use the @code{handle}
3515command with @code{pass} or @code{nopass} to control whether your
3516program sees that signal when you continue.
3517
3518You can also use the @code{signal} command to prevent your program from
3519seeing a signal, or cause it to see a signal it normally would not see,
3520or to give it any signal at any time. For example, if your program stopped
3521due to some sort of memory reference error, you might store correct
3522values into the erroneous variables and continue, hoping to see more
3523execution; but your program would probably terminate immediately as
3524a result of the fatal signal once it saw the signal. To prevent this,
3525you can continue with @samp{signal 0}. @xref{Signaling, ,Giving your
5d161b24 3526program a signal}.
c906108c 3527
6d2ebf8b 3528@node Thread Stops
c906108c
SS
3529@section Stopping and starting multi-thread programs
3530
3531When your program has multiple threads (@pxref{Threads,, Debugging
3532programs with multiple threads}), you can choose whether to set
3533breakpoints on all threads, or on a particular thread.
3534
3535@table @code
3536@cindex breakpoints and threads
3537@cindex thread breakpoints
3538@kindex break @dots{} thread @var{threadno}
3539@item break @var{linespec} thread @var{threadno}
3540@itemx break @var{linespec} thread @var{threadno} if @dots{}
3541@var{linespec} specifies source lines; there are several ways of
3542writing them, but the effect is always to specify some source line.
3543
3544Use the qualifier @samp{thread @var{threadno}} with a breakpoint command
3545to specify that you only want @value{GDBN} to stop the program when a
3546particular thread reaches this breakpoint. @var{threadno} is one of the
3547numeric thread identifiers assigned by @value{GDBN}, shown in the first
3548column of the @samp{info threads} display.
3549
3550If you do not specify @samp{thread @var{threadno}} when you set a
3551breakpoint, the breakpoint applies to @emph{all} threads of your
3552program.
3553
3554You can use the @code{thread} qualifier on conditional breakpoints as
3555well; in this case, place @samp{thread @var{threadno}} before the
3556breakpoint condition, like this:
3557
3558@smallexample
2df3850c 3559(@value{GDBP}) break frik.c:13 thread 28 if bartab > lim
c906108c
SS
3560@end smallexample
3561
3562@end table
3563
3564@cindex stopped threads
3565@cindex threads, stopped
3566Whenever your program stops under @value{GDBN} for any reason,
3567@emph{all} threads of execution stop, not just the current thread. This
3568allows you to examine the overall state of the program, including
3569switching between threads, without worrying that things may change
3570underfoot.
3571
3572@cindex continuing threads
3573@cindex threads, continuing
3574Conversely, whenever you restart the program, @emph{all} threads start
3575executing. @emph{This is true even when single-stepping} with commands
5d161b24 3576like @code{step} or @code{next}.
c906108c
SS
3577
3578In particular, @value{GDBN} cannot single-step all threads in lockstep.
3579Since thread scheduling is up to your debugging target's operating
3580system (not controlled by @value{GDBN}), other threads may
3581execute more than one statement while the current thread completes a
3582single step. Moreover, in general other threads stop in the middle of a
3583statement, rather than at a clean statement boundary, when the program
3584stops.
3585
3586You might even find your program stopped in another thread after
3587continuing or even single-stepping. This happens whenever some other
3588thread runs into a breakpoint, a signal, or an exception before the
3589first thread completes whatever you requested.
3590
3591On some OSes, you can lock the OS scheduler and thus allow only a single
3592thread to run.
3593
3594@table @code
3595@item set scheduler-locking @var{mode}
3596Set the scheduler locking mode. If it is @code{off}, then there is no
3597locking and any thread may run at any time. If @code{on}, then only the
3598current thread may run when the inferior is resumed. The @code{step}
3599mode optimizes for single-stepping. It stops other threads from
3600``seizing the prompt'' by preempting the current thread while you are
3601stepping. Other threads will only rarely (or never) get a chance to run
d4f3574e 3602when you step. They are more likely to run when you @samp{next} over a
c906108c 3603function call, and they are completely free to run when you use commands
d4f3574e 3604like @samp{continue}, @samp{until}, or @samp{finish}. However, unless another
c906108c 3605thread hits a breakpoint during its timeslice, they will never steal the
2df3850c 3606@value{GDBN} prompt away from the thread that you are debugging.
c906108c
SS
3607
3608@item show scheduler-locking
3609Display the current scheduler locking mode.
3610@end table
3611
c906108c 3612
6d2ebf8b 3613@node Stack
c906108c
SS
3614@chapter Examining the Stack
3615
3616When your program has stopped, the first thing you need to know is where it
3617stopped and how it got there.
3618
3619@cindex call stack
5d161b24
DB
3620Each time your program performs a function call, information about the call
3621is generated.
3622That information includes the location of the call in your program,
3623the arguments of the call,
c906108c 3624and the local variables of the function being called.
5d161b24 3625The information is saved in a block of data called a @dfn{stack frame}.
c906108c
SS
3626The stack frames are allocated in a region of memory called the @dfn{call
3627stack}.
3628
3629When your program stops, the @value{GDBN} commands for examining the
3630stack allow you to see all of this information.
3631
3632@cindex selected frame
3633One of the stack frames is @dfn{selected} by @value{GDBN} and many
3634@value{GDBN} commands refer implicitly to the selected frame. In
3635particular, whenever you ask @value{GDBN} for the value of a variable in
3636your program, the value is found in the selected frame. There are
3637special @value{GDBN} commands to select whichever frame you are
3638interested in. @xref{Selection, ,Selecting a frame}.
3639
3640When your program stops, @value{GDBN} automatically selects the
5d161b24 3641currently executing frame and describes it briefly, similar to the
c906108c
SS
3642@code{frame} command (@pxref{Frame Info, ,Information about a frame}).
3643
3644@menu
3645* Frames:: Stack frames
3646* Backtrace:: Backtraces
3647* Selection:: Selecting a frame
3648* Frame Info:: Information on a frame
c906108c
SS
3649
3650@end menu
3651
6d2ebf8b 3652@node Frames
c906108c
SS
3653@section Stack frames
3654
d4f3574e 3655@cindex frame, definition
c906108c
SS
3656@cindex stack frame
3657The call stack is divided up into contiguous pieces called @dfn{stack
3658frames}, or @dfn{frames} for short; each frame is the data associated
3659with one call to one function. The frame contains the arguments given
3660to the function, the function's local variables, and the address at
3661which the function is executing.
3662
3663@cindex initial frame
3664@cindex outermost frame
3665@cindex innermost frame
3666When your program is started, the stack has only one frame, that of the
3667function @code{main}. This is called the @dfn{initial} frame or the
3668@dfn{outermost} frame. Each time a function is called, a new frame is
3669made. Each time a function returns, the frame for that function invocation
3670is eliminated. If a function is recursive, there can be many frames for
3671the same function. The frame for the function in which execution is
3672actually occurring is called the @dfn{innermost} frame. This is the most
3673recently created of all the stack frames that still exist.
3674
3675@cindex frame pointer
3676Inside your program, stack frames are identified by their addresses. A
3677stack frame consists of many bytes, each of which has its own address; each
3678kind of computer has a convention for choosing one byte whose
3679address serves as the address of the frame. Usually this address is kept
3680in a register called the @dfn{frame pointer register} while execution is
3681going on in that frame.
3682
3683@cindex frame number
3684@value{GDBN} assigns numbers to all existing stack frames, starting with
3685zero for the innermost frame, one for the frame that called it,
3686and so on upward. These numbers do not really exist in your program;
3687they are assigned by @value{GDBN} to give you a way of designating stack
3688frames in @value{GDBN} commands.
3689
6d2ebf8b
SS
3690@c The -fomit-frame-pointer below perennially causes hbox overflow
3691@c underflow problems.
c906108c
SS
3692@cindex frameless execution
3693Some compilers provide a way to compile functions so that they operate
6d2ebf8b
SS
3694without stack frames. (For example, the @value{GCC} option
3695@example
3696@samp{-fomit-frame-pointer}
3697@end example
3698generates functions without a frame.)
c906108c
SS
3699This is occasionally done with heavily used library functions to save
3700the frame setup time. @value{GDBN} has limited facilities for dealing
3701with these function invocations. If the innermost function invocation
3702has no stack frame, @value{GDBN} nevertheless regards it as though
3703it had a separate frame, which is numbered zero as usual, allowing
3704correct tracing of the function call chain. However, @value{GDBN} has
3705no provision for frameless functions elsewhere in the stack.
3706
3707@table @code
d4f3574e 3708@kindex frame@r{, command}
41afff9a 3709@cindex current stack frame
c906108c 3710@item frame @var{args}
5d161b24 3711The @code{frame} command allows you to move from one stack frame to another,
c906108c 3712and to print the stack frame you select. @var{args} may be either the
5d161b24
DB
3713address of the frame or the stack frame number. Without an argument,
3714@code{frame} prints the current stack frame.
c906108c
SS
3715
3716@kindex select-frame
41afff9a 3717@cindex selecting frame silently
c906108c
SS
3718@item select-frame
3719The @code{select-frame} command allows you to move from one stack frame
3720to another without printing the frame. This is the silent version of
3721@code{frame}.
3722@end table
3723
6d2ebf8b 3724@node Backtrace
c906108c
SS
3725@section Backtraces
3726
3727@cindex backtraces
3728@cindex tracebacks
3729@cindex stack traces
3730A backtrace is a summary of how your program got where it is. It shows one
3731line per frame, for many frames, starting with the currently executing
3732frame (frame zero), followed by its caller (frame one), and on up the
3733stack.
3734
3735@table @code
3736@kindex backtrace
41afff9a 3737@kindex bt @r{(@code{backtrace})}
c906108c
SS
3738@item backtrace
3739@itemx bt
3740Print a backtrace of the entire stack: one line per frame for all
3741frames in the stack.
3742
3743You can stop the backtrace at any time by typing the system interrupt
3744character, normally @kbd{C-c}.
3745
3746@item backtrace @var{n}
3747@itemx bt @var{n}
3748Similar, but print only the innermost @var{n} frames.
3749
3750@item backtrace -@var{n}
3751@itemx bt -@var{n}
3752Similar, but print only the outermost @var{n} frames.
3753@end table
3754
3755@kindex where
3756@kindex info stack
41afff9a 3757@kindex info s @r{(@code{info stack})}
c906108c
SS
3758The names @code{where} and @code{info stack} (abbreviated @code{info s})
3759are additional aliases for @code{backtrace}.
3760
3761Each line in the backtrace shows the frame number and the function name.
3762The program counter value is also shown---unless you use @code{set
3763print address off}. The backtrace also shows the source file name and
3764line number, as well as the arguments to the function. The program
3765counter value is omitted if it is at the beginning of the code for that
3766line number.
3767
3768Here is an example of a backtrace. It was made with the command
3769@samp{bt 3}, so it shows the innermost three frames.
3770
3771@smallexample
3772@group
5d161b24 3773#0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8)
c906108c
SS
3774 at builtin.c:993
3775#1 0x6e38 in expand_macro (sym=0x2b600) at macro.c:242
3776#2 0x6840 in expand_token (obs=0x0, t=177664, td=0xf7fffb08)
3777 at macro.c:71
3778(More stack frames follow...)
3779@end group
3780@end smallexample
3781
3782@noindent
3783The display for frame zero does not begin with a program counter
3784value, indicating that your program has stopped at the beginning of the
3785code for line @code{993} of @code{builtin.c}.
3786
6d2ebf8b 3787@node Selection
c906108c
SS
3788@section Selecting a frame
3789
3790Most commands for examining the stack and other data in your program work on
3791whichever stack frame is selected at the moment. Here are the commands for
3792selecting a stack frame; all of them finish by printing a brief description
3793of the stack frame just selected.
3794
3795@table @code
d4f3574e 3796@kindex frame@r{, selecting}
41afff9a 3797@kindex f @r{(@code{frame})}
c906108c
SS
3798@item frame @var{n}
3799@itemx f @var{n}
3800Select frame number @var{n}. Recall that frame zero is the innermost
3801(currently executing) frame, frame one is the frame that called the
3802innermost one, and so on. The highest-numbered frame is the one for
3803@code{main}.
3804
3805@item frame @var{addr}
3806@itemx f @var{addr}
3807Select the frame at address @var{addr}. This is useful mainly if the
3808chaining of stack frames has been damaged by a bug, making it
3809impossible for @value{GDBN} to assign numbers properly to all frames. In
3810addition, this can be useful when your program has multiple stacks and
3811switches between them.
3812
c906108c
SS
3813On the SPARC architecture, @code{frame} needs two addresses to
3814select an arbitrary frame: a frame pointer and a stack pointer.
3815
3816On the MIPS and Alpha architecture, it needs two addresses: a stack
3817pointer and a program counter.
3818
3819On the 29k architecture, it needs three addresses: a register stack
3820pointer, a program counter, and a memory stack pointer.
3821@c note to future updaters: this is conditioned on a flag
3822@c SETUP_ARBITRARY_FRAME in the tm-*.h files. The above is up to date
3823@c as of 27 Jan 1994.
c906108c
SS
3824
3825@kindex up
3826@item up @var{n}
3827Move @var{n} frames up the stack. For positive numbers @var{n}, this
3828advances toward the outermost frame, to higher frame numbers, to frames
3829that have existed longer. @var{n} defaults to one.
3830
3831@kindex down
41afff9a 3832@kindex do @r{(@code{down})}
c906108c
SS
3833@item down @var{n}
3834Move @var{n} frames down the stack. For positive numbers @var{n}, this
3835advances toward the innermost frame, to lower frame numbers, to frames
3836that were created more recently. @var{n} defaults to one. You may
3837abbreviate @code{down} as @code{do}.
3838@end table
3839
3840All of these commands end by printing two lines of output describing the
3841frame. The first line shows the frame number, the function name, the
3842arguments, and the source file and line number of execution in that
5d161b24 3843frame. The second line shows the text of that source line.
c906108c
SS
3844
3845@need 1000
3846For example:
3847
3848@smallexample
3849@group
3850(@value{GDBP}) up
3851#1 0x22f0 in main (argc=1, argv=0xf7fffbf4, env=0xf7fffbfc)
3852 at env.c:10
385310 read_input_file (argv[i]);
3854@end group
3855@end smallexample
3856
3857After such a printout, the @code{list} command with no arguments
3858prints ten lines centered on the point of execution in the frame.
3859@xref{List, ,Printing source lines}.
3860
3861@table @code
3862@kindex down-silently
3863@kindex up-silently
3864@item up-silently @var{n}
3865@itemx down-silently @var{n}
3866These two commands are variants of @code{up} and @code{down},
3867respectively; they differ in that they do their work silently, without
3868causing display of the new frame. They are intended primarily for use
3869in @value{GDBN} command scripts, where the output might be unnecessary and
3870distracting.
3871@end table
3872
6d2ebf8b 3873@node Frame Info
c906108c
SS
3874@section Information about a frame
3875
3876There are several other commands to print information about the selected
3877stack frame.
3878
3879@table @code
3880@item frame
3881@itemx f
3882When used without any argument, this command does not change which
3883frame is selected, but prints a brief description of the currently
3884selected stack frame. It can be abbreviated @code{f}. With an
3885argument, this command is used to select a stack frame.
3886@xref{Selection, ,Selecting a frame}.
3887
3888@kindex info frame
41afff9a 3889@kindex info f @r{(@code{info frame})}
c906108c
SS
3890@item info frame
3891@itemx info f
3892This command prints a verbose description of the selected stack frame,
3893including:
3894
3895@itemize @bullet
5d161b24
DB
3896@item
3897the address of the frame
c906108c
SS
3898@item
3899the address of the next frame down (called by this frame)
3900@item
3901the address of the next frame up (caller of this frame)
3902@item
3903the language in which the source code corresponding to this frame is written
3904@item
3905the address of the frame's arguments
3906@item
d4f3574e
SS
3907the address of the frame's local variables
3908@item
c906108c
SS
3909the program counter saved in it (the address of execution in the caller frame)
3910@item
3911which registers were saved in the frame
3912@end itemize
3913
3914@noindent The verbose description is useful when
3915something has gone wrong that has made the stack format fail to fit
3916the usual conventions.
3917
3918@item info frame @var{addr}
3919@itemx info f @var{addr}
3920Print a verbose description of the frame at address @var{addr}, without
3921selecting that frame. The selected frame remains unchanged by this
3922command. This requires the same kind of address (more than one for some
3923architectures) that you specify in the @code{frame} command.
3924@xref{Selection, ,Selecting a frame}.
3925
3926@kindex info args
3927@item info args
3928Print the arguments of the selected frame, each on a separate line.
3929
3930@item info locals
3931@kindex info locals
3932Print the local variables of the selected frame, each on a separate
3933line. These are all variables (declared either static or automatic)
3934accessible at the point of execution of the selected frame.
3935
c906108c 3936@kindex info catch
d4f3574e
SS
3937@cindex catch exceptions, list active handlers
3938@cindex exception handlers, how to list
c906108c
SS
3939@item info catch
3940Print a list of all the exception handlers that are active in the
3941current stack frame at the current point of execution. To see other
3942exception handlers, visit the associated frame (using the @code{up},
3943@code{down}, or @code{frame} commands); then type @code{info catch}.
3944@xref{Set Catchpoints, , Setting catchpoints}.
53a5351d 3945
c906108c
SS
3946@end table
3947
c906108c 3948
6d2ebf8b 3949@node Source
c906108c
SS
3950@chapter Examining Source Files
3951
3952@value{GDBN} can print parts of your program's source, since the debugging
3953information recorded in the program tells @value{GDBN} what source files were
3954used to build it. When your program stops, @value{GDBN} spontaneously prints
3955the line where it stopped. Likewise, when you select a stack frame
3956(@pxref{Selection, ,Selecting a frame}), @value{GDBN} prints the line where
3957execution in that frame has stopped. You can print other portions of
3958source files by explicit command.
3959
7a292a7a 3960If you use @value{GDBN} through its @sc{gnu} Emacs interface, you may
d4f3574e 3961prefer to use Emacs facilities to view source; see @ref{Emacs, ,Using
7a292a7a 3962@value{GDBN} under @sc{gnu} Emacs}.
c906108c
SS
3963
3964@menu
3965* List:: Printing source lines
c906108c 3966* Search:: Searching source files
c906108c
SS
3967* Source Path:: Specifying source directories
3968* Machine Code:: Source and machine code
3969@end menu
3970
6d2ebf8b 3971@node List
c906108c
SS
3972@section Printing source lines
3973
3974@kindex list
41afff9a 3975@kindex l @r{(@code{list})}
c906108c 3976To print lines from a source file, use the @code{list} command
5d161b24 3977(abbreviated @code{l}). By default, ten lines are printed.
c906108c
SS
3978There are several ways to specify what part of the file you want to print.
3979
3980Here are the forms of the @code{list} command most commonly used:
3981
3982@table @code
3983@item list @var{linenum}
3984Print lines centered around line number @var{linenum} in the
3985current source file.
3986
3987@item list @var{function}
3988Print lines centered around the beginning of function
3989@var{function}.
3990
3991@item list
3992Print more lines. If the last lines printed were printed with a
3993@code{list} command, this prints lines following the last lines
3994printed; however, if the last line printed was a solitary line printed
3995as part of displaying a stack frame (@pxref{Stack, ,Examining the
3996Stack}), this prints lines centered around that line.
3997
3998@item list -
3999Print lines just before the lines last printed.
4000@end table
4001
4002By default, @value{GDBN} prints ten source lines with any of these forms of
4003the @code{list} command. You can change this using @code{set listsize}:
4004
4005@table @code
4006@kindex set listsize
4007@item set listsize @var{count}
4008Make the @code{list} command display @var{count} source lines (unless
4009the @code{list} argument explicitly specifies some other number).
4010
4011@kindex show listsize
4012@item show listsize
4013Display the number of lines that @code{list} prints.
4014@end table
4015
4016Repeating a @code{list} command with @key{RET} discards the argument,
4017so it is equivalent to typing just @code{list}. This is more useful
4018than listing the same lines again. An exception is made for an
4019argument of @samp{-}; that argument is preserved in repetition so that
4020each repetition moves up in the source file.
4021
4022@cindex linespec
4023In general, the @code{list} command expects you to supply zero, one or two
4024@dfn{linespecs}. Linespecs specify source lines; there are several ways
d4f3574e 4025of writing them, but the effect is always to specify some source line.
c906108c
SS
4026Here is a complete description of the possible arguments for @code{list}:
4027
4028@table @code
4029@item list @var{linespec}
4030Print lines centered around the line specified by @var{linespec}.
4031
4032@item list @var{first},@var{last}
4033Print lines from @var{first} to @var{last}. Both arguments are
4034linespecs.
4035
4036@item list ,@var{last}
4037Print lines ending with @var{last}.
4038
4039@item list @var{first},
4040Print lines starting with @var{first}.
4041
4042@item list +
4043Print lines just after the lines last printed.
4044
4045@item list -
4046Print lines just before the lines last printed.
4047
4048@item list
4049As described in the preceding table.
4050@end table
4051
4052Here are the ways of specifying a single source line---all the
4053kinds of linespec.
4054
4055@table @code
4056@item @var{number}
4057Specifies line @var{number} of the current source file.
4058When a @code{list} command has two linespecs, this refers to
4059the same source file as the first linespec.
4060
4061@item +@var{offset}
4062Specifies the line @var{offset} lines after the last line printed.
4063When used as the second linespec in a @code{list} command that has
4064two, this specifies the line @var{offset} lines down from the
4065first linespec.
4066
4067@item -@var{offset}
4068Specifies the line @var{offset} lines before the last line printed.
4069
4070@item @var{filename}:@var{number}
4071Specifies line @var{number} in the source file @var{filename}.
4072
4073@item @var{function}
4074Specifies the line that begins the body of the function @var{function}.
4075For example: in C, this is the line with the open brace.
4076
4077@item @var{filename}:@var{function}
4078Specifies the line of the open-brace that begins the body of the
4079function @var{function} in the file @var{filename}. You only need the
4080file name with a function name to avoid ambiguity when there are
4081identically named functions in different source files.
4082
4083@item *@var{address}
4084Specifies the line containing the program address @var{address}.
4085@var{address} may be any expression.
4086@end table
4087
6d2ebf8b 4088@node Search
c906108c
SS
4089@section Searching source files
4090@cindex searching
4091@kindex reverse-search
4092
4093There are two commands for searching through the current source file for a
4094regular expression.
4095
4096@table @code
4097@kindex search
4098@kindex forward-search
4099@item forward-search @var{regexp}
4100@itemx search @var{regexp}
4101The command @samp{forward-search @var{regexp}} checks each line,
4102starting with the one following the last line listed, for a match for
5d161b24 4103@var{regexp}. It lists the line that is found. You can use the
c906108c
SS
4104synonym @samp{search @var{regexp}} or abbreviate the command name as
4105@code{fo}.
4106
4107@item reverse-search @var{regexp}
4108The command @samp{reverse-search @var{regexp}} checks each line, starting
4109with the one before the last line listed and going backward, for a match
4110for @var{regexp}. It lists the line that is found. You can abbreviate
4111this command as @code{rev}.
4112@end table
c906108c 4113
6d2ebf8b 4114@node Source Path
c906108c
SS
4115@section Specifying source directories
4116
4117@cindex source path
4118@cindex directories for source files
4119Executable programs sometimes do not record the directories of the source
4120files from which they were compiled, just the names. Even when they do,
4121the directories could be moved between the compilation and your debugging
4122session. @value{GDBN} has a list of directories to search for source files;
4123this is called the @dfn{source path}. Each time @value{GDBN} wants a source file,
4124it tries all the directories in the list, in the order they are present
4125in the list, until it finds a file with the desired name. Note that
4126the executable search path is @emph{not} used for this purpose. Neither is
4127the current working directory, unless it happens to be in the source
4128path.
4129
4130If @value{GDBN} cannot find a source file in the source path, and the
4131object program records a directory, @value{GDBN} tries that directory
4132too. If the source path is empty, and there is no record of the
4133compilation directory, @value{GDBN} looks in the current directory as a
4134last resort.
4135
4136Whenever you reset or rearrange the source path, @value{GDBN} clears out
4137any information it has cached about where source files are found and where
4138each line is in the file.
4139
4140@kindex directory
4141@kindex dir
d4f3574e
SS
4142When you start @value{GDBN}, its source path includes only @samp{cdir}
4143and @samp{cwd}, in that order.
c906108c
SS
4144To add other directories, use the @code{directory} command.
4145
4146@table @code
4147@item directory @var{dirname} @dots{}
4148@item dir @var{dirname} @dots{}
4149Add directory @var{dirname} to the front of the source path. Several
d4f3574e
SS
4150directory names may be given to this command, separated by @samp{:}
4151(@samp{;} on MS-DOS and MS-Windows, where @samp{:} usually appears as
4152part of absolute file names) or
c906108c
SS
4153whitespace. You may specify a directory that is already in the source
4154path; this moves it forward, so @value{GDBN} searches it sooner.
4155
4156@kindex cdir
4157@kindex cwd
41afff9a
EZ
4158@vindex $cdir@r{, convenience variable}
4159@vindex $cwdr@r{, convenience variable}
c906108c
SS
4160@cindex compilation directory
4161@cindex current directory
4162@cindex working directory
4163@cindex directory, current
4164@cindex directory, compilation
4165You can use the string @samp{$cdir} to refer to the compilation
4166directory (if one is recorded), and @samp{$cwd} to refer to the current
4167working directory. @samp{$cwd} is not the same as @samp{.}---the former
4168tracks the current working directory as it changes during your @value{GDBN}
4169session, while the latter is immediately expanded to the current
4170directory at the time you add an entry to the source path.
4171
4172@item directory
4173Reset the source path to empty again. This requires confirmation.
4174
4175@c RET-repeat for @code{directory} is explicitly disabled, but since
4176@c repeating it would be a no-op we do not say that. (thanks to RMS)
4177
4178@item show directories
4179@kindex show directories
4180Print the source path: show which directories it contains.
4181@end table
4182
4183If your source path is cluttered with directories that are no longer of
4184interest, @value{GDBN} may sometimes cause confusion by finding the wrong
4185versions of source. You can correct the situation as follows:
4186
4187@enumerate
4188@item
4189Use @code{directory} with no argument to reset the source path to empty.
4190
4191@item
4192Use @code{directory} with suitable arguments to reinstall the
4193directories you want in the source path. You can add all the
4194directories in one command.
4195@end enumerate
4196
6d2ebf8b 4197@node Machine Code
c906108c
SS
4198@section Source and machine code
4199
4200You can use the command @code{info line} to map source lines to program
4201addresses (and vice versa), and the command @code{disassemble} to display
4202a range of addresses as machine instructions. When run under @sc{gnu} Emacs
d4f3574e 4203mode, the @code{info line} command causes the arrow to point to the
5d161b24 4204line specified. Also, @code{info line} prints addresses in symbolic form as
c906108c
SS
4205well as hex.
4206
4207@table @code
4208@kindex info line
4209@item info line @var{linespec}
4210Print the starting and ending addresses of the compiled code for
4211source line @var{linespec}. You can specify source lines in any of
4212the ways understood by the @code{list} command (@pxref{List, ,Printing
4213source lines}).
4214@end table
4215
4216For example, we can use @code{info line} to discover the location of
4217the object code for the first line of function
4218@code{m4_changequote}:
4219
d4f3574e
SS
4220@c FIXME: I think this example should also show the addresses in
4221@c symbolic form, as they usually would be displayed.
c906108c 4222@smallexample
96a2c332 4223(@value{GDBP}) info line m4_changequote
c906108c
SS
4224Line 895 of "builtin.c" starts at pc 0x634c and ends at 0x6350.
4225@end smallexample
4226
4227@noindent
4228We can also inquire (using @code{*@var{addr}} as the form for
4229@var{linespec}) what source line covers a particular address:
4230@smallexample
4231(@value{GDBP}) info line *0x63ff
4232Line 926 of "builtin.c" starts at pc 0x63e4 and ends at 0x6404.
4233@end smallexample
4234
4235@cindex @code{$_} and @code{info line}
41afff9a 4236@kindex x@r{(examine), and} info line
c906108c
SS
4237After @code{info line}, the default address for the @code{x} command
4238is changed to the starting address of the line, so that @samp{x/i} is
4239sufficient to begin examining the machine code (@pxref{Memory,
4240,Examining memory}). Also, this address is saved as the value of the
4241convenience variable @code{$_} (@pxref{Convenience Vars, ,Convenience
4242variables}).
4243
4244@table @code
4245@kindex disassemble
4246@cindex assembly instructions
4247@cindex instructions, assembly
4248@cindex machine instructions
4249@cindex listing machine instructions
4250@item disassemble
4251This specialized command dumps a range of memory as machine
4252instructions. The default memory range is the function surrounding the
4253program counter of the selected frame. A single argument to this
4254command is a program counter value; @value{GDBN} dumps the function
4255surrounding this value. Two arguments specify a range of addresses
4256(first inclusive, second exclusive) to dump.
4257@end table
4258
c906108c
SS
4259The following example shows the disassembly of a range of addresses of
4260HP PA-RISC 2.0 code:
4261
4262@smallexample
4263(@value{GDBP}) disas 0x32c4 0x32e4
4264Dump of assembler code from 0x32c4 to 0x32e4:
42650x32c4 <main+204>: addil 0,dp
42660x32c8 <main+208>: ldw 0x22c(sr0,r1),r26
42670x32cc <main+212>: ldil 0x3000,r31
42680x32d0 <main+216>: ble 0x3f8(sr4,r31)
42690x32d4 <main+220>: ldo 0(r31),rp
42700x32d8 <main+224>: addil -0x800,dp
42710x32dc <main+228>: ldo 0x588(r1),r26
42720x32e0 <main+232>: ldil 0x3000,r31
4273End of assembler dump.
4274@end smallexample
c906108c
SS
4275
4276Some architectures have more than one commonly-used set of instruction
4277mnemonics or other syntax.
4278
4279@table @code
d4f3574e 4280@kindex set disassembly-flavor
c906108c
SS
4281@cindex assembly instructions
4282@cindex instructions, assembly
4283@cindex machine instructions
4284@cindex listing machine instructions
d4f3574e
SS
4285@cindex Intel disassembly flavor
4286@cindex AT&T disassembly flavor
4287@item set disassembly-flavor @var{instruction-set}
c906108c
SS
4288Select the instruction set to use when disassembling the
4289program via the @code{disassemble} or @code{x/i} commands.
4290
4291Currently this command is only defined for the Intel x86 family. You
d4f3574e
SS
4292can set @var{instruction-set} to either @code{intel} or @code{att}.
4293The default is @code{att}, the AT&T flavor used by default by Unix
4294assemblers for x86-based targets.
c906108c
SS
4295@end table
4296
4297
6d2ebf8b 4298@node Data
c906108c
SS
4299@chapter Examining Data
4300
4301@cindex printing data
4302@cindex examining data
4303@kindex print
4304@kindex inspect
4305@c "inspect" is not quite a synonym if you are using Epoch, which we do not
4306@c document because it is nonstandard... Under Epoch it displays in a
4307@c different window or something like that.
4308The usual way to examine data in your program is with the @code{print}
7a292a7a
SS
4309command (abbreviated @code{p}), or its synonym @code{inspect}. It
4310evaluates and prints the value of an expression of the language your
4311program is written in (@pxref{Languages, ,Using @value{GDBN} with
4312Different Languages}).
c906108c
SS
4313
4314@table @code
d4f3574e
SS
4315@item print @var{expr}
4316@itemx print /@var{f} @var{expr}
4317@var{expr} is an expression (in the source language). By default the
4318value of @var{expr} is printed in a format appropriate to its data type;
c906108c 4319you can choose a different format by specifying @samp{/@var{f}}, where
d4f3574e 4320@var{f} is a letter specifying the format; see @ref{Output Formats,,Output
c906108c
SS
4321formats}.
4322
4323@item print
4324@itemx print /@var{f}
d4f3574e 4325If you omit @var{expr}, @value{GDBN} displays the last value again (from the
c906108c
SS
4326@dfn{value history}; @pxref{Value History, ,Value history}). This allows you to
4327conveniently inspect the same value in an alternative format.
4328@end table
4329
4330A more low-level way of examining data is with the @code{x} command.
4331It examines data in memory at a specified address and prints it in a
4332specified format. @xref{Memory, ,Examining memory}.
4333
7a292a7a 4334If you are interested in information about types, or about how the
d4f3574e
SS
4335fields of a struct or a class are declared, use the @code{ptype @var{exp}}
4336command rather than @code{print}. @xref{Symbols, ,Examining the Symbol
7a292a7a 4337Table}.
c906108c
SS
4338
4339@menu
4340* Expressions:: Expressions
4341* Variables:: Program variables
4342* Arrays:: Artificial arrays
4343* Output Formats:: Output formats
4344* Memory:: Examining memory
4345* Auto Display:: Automatic display
4346* Print Settings:: Print settings
4347* Value History:: Value history
4348* Convenience Vars:: Convenience variables
4349* Registers:: Registers
c906108c 4350* Floating Point Hardware:: Floating point hardware
29e57380 4351* Memory Region Attributes:: Memory region attributes
c906108c
SS
4352@end menu
4353
6d2ebf8b 4354@node Expressions
c906108c
SS
4355@section Expressions
4356
4357@cindex expressions
4358@code{print} and many other @value{GDBN} commands accept an expression and
4359compute its value. Any kind of constant, variable or operator defined
4360by the programming language you are using is valid in an expression in
4361@value{GDBN}. This includes conditional expressions, function calls, casts
4362and string constants. It unfortunately does not include symbols defined
4363by preprocessor @code{#define} commands.
4364
d4f3574e
SS
4365@value{GDBN} supports array constants in expressions input by
4366the user. The syntax is @{@var{element}, @var{element}@dots{}@}. For example,
5d161b24 4367you can use the command @code{print @{1, 2, 3@}} to build up an array in
d4f3574e 4368memory that is @code{malloc}ed in the target program.
c906108c 4369
c906108c
SS
4370Because C is so widespread, most of the expressions shown in examples in
4371this manual are in C. @xref{Languages, , Using @value{GDBN} with Different
4372Languages}, for information on how to use expressions in other
4373languages.
4374
4375In this section, we discuss operators that you can use in @value{GDBN}
4376expressions regardless of your programming language.
4377
4378Casts are supported in all languages, not just in C, because it is so
4379useful to cast a number into a pointer in order to examine a structure
4380at that address in memory.
4381@c FIXME: casts supported---Mod2 true?
c906108c
SS
4382
4383@value{GDBN} supports these operators, in addition to those common
4384to programming languages:
4385
4386@table @code
4387@item @@
4388@samp{@@} is a binary operator for treating parts of memory as arrays.
4389@xref{Arrays, ,Artificial arrays}, for more information.
4390
4391@item ::
4392@samp{::} allows you to specify a variable in terms of the file or
4393function where it is defined. @xref{Variables, ,Program variables}.
4394
4395@cindex @{@var{type}@}
4396@cindex type casting memory
4397@cindex memory, viewing as typed object
4398@cindex casts, to view memory
4399@item @{@var{type}@} @var{addr}
4400Refers to an object of type @var{type} stored at address @var{addr} in
4401memory. @var{addr} may be any expression whose value is an integer or
4402pointer (but parentheses are required around binary operators, just as in
4403a cast). This construct is allowed regardless of what kind of data is
4404normally supposed to reside at @var{addr}.
4405@end table
4406
6d2ebf8b 4407@node Variables
c906108c
SS
4408@section Program variables
4409
4410The most common kind of expression to use is the name of a variable
4411in your program.
4412
4413Variables in expressions are understood in the selected stack frame
4414(@pxref{Selection, ,Selecting a frame}); they must be either:
4415
4416@itemize @bullet
4417@item
4418global (or file-static)
4419@end itemize
4420
5d161b24 4421@noindent or
c906108c
SS
4422
4423@itemize @bullet
4424@item
4425visible according to the scope rules of the
4426programming language from the point of execution in that frame
5d161b24 4427@end itemize
c906108c
SS
4428
4429@noindent This means that in the function
4430
4431@example
4432foo (a)
4433 int a;
4434@{
4435 bar (a);
4436 @{
4437 int b = test ();
4438 bar (b);
4439 @}
4440@}
4441@end example
4442
4443@noindent
4444you can examine and use the variable @code{a} whenever your program is
4445executing within the function @code{foo}, but you can only use or
4446examine the variable @code{b} while your program is executing inside
4447the block where @code{b} is declared.
4448
4449@cindex variable name conflict
4450There is an exception: you can refer to a variable or function whose
4451scope is a single source file even if the current execution point is not
4452in this file. But it is possible to have more than one such variable or
4453function with the same name (in different source files). If that
4454happens, referring to that name has unpredictable effects. If you wish,
4455you can specify a static variable in a particular function or file,
4456using the colon-colon notation:
4457
d4f3574e 4458@cindex colon-colon, context for variables/functions
c906108c
SS
4459@iftex
4460@c info cannot cope with a :: index entry, but why deprive hard copy readers?
41afff9a 4461@cindex @code{::}, context for variables/functions
c906108c
SS
4462@end iftex
4463@example
4464@var{file}::@var{variable}
4465@var{function}::@var{variable}
4466@end example
4467
4468@noindent
4469Here @var{file} or @var{function} is the name of the context for the
4470static @var{variable}. In the case of file names, you can use quotes to
4471make sure @value{GDBN} parses the file name as a single word---for example,
4472to print a global value of @code{x} defined in @file{f2.c}:
4473
4474@example
4475(@value{GDBP}) p 'f2.c'::x
4476@end example
4477
c906108c
SS
4478@cindex C++ scope resolution
4479This use of @samp{::} is very rarely in conflict with the very similar
4480use of the same notation in C++. @value{GDBN} also supports use of the C++
4481scope resolution operator in @value{GDBN} expressions.
4482@c FIXME: Um, so what happens in one of those rare cases where it's in
4483@c conflict?? --mew
c906108c
SS
4484
4485@cindex wrong values
4486@cindex variable values, wrong
4487@quotation
4488@emph{Warning:} Occasionally, a local variable may appear to have the
4489wrong value at certain points in a function---just after entry to a new
4490scope, and just before exit.
4491@end quotation
4492You may see this problem when you are stepping by machine instructions.
4493This is because, on most machines, it takes more than one instruction to
4494set up a stack frame (including local variable definitions); if you are
4495stepping by machine instructions, variables may appear to have the wrong
4496values until the stack frame is completely built. On exit, it usually
4497also takes more than one machine instruction to destroy a stack frame;
4498after you begin stepping through that group of instructions, local
4499variable definitions may be gone.
4500
4501This may also happen when the compiler does significant optimizations.
4502To be sure of always seeing accurate values, turn off all optimization
4503when compiling.
4504
d4f3574e
SS
4505@cindex ``No symbol "foo" in current context''
4506Another possible effect of compiler optimizations is to optimize
4507unused variables out of existence, or assign variables to registers (as
4508opposed to memory addresses). Depending on the support for such cases
4509offered by the debug info format used by the compiler, @value{GDBN}
4510might not be able to display values for such local variables. If that
4511happens, @value{GDBN} will print a message like this:
4512
4513@example
4514No symbol "foo" in current context.
4515@end example
4516
4517To solve such problems, either recompile without optimizations, or use a
4518different debug info format, if the compiler supports several such
4519formats. For example, @value{NGCC}, the @sc{gnu} C/C++ compiler usually
4520supports the @samp{-gstabs} option. @samp{-gstabs} produces debug info
4521in a format that is superior to formats such as COFF. You may be able
96c405b3 4522to use DWARF2 (@samp{-gdwarf-2}), which is also an effective form for
d4f3574e
SS
4523debug info. See @ref{Debugging Options,,Options for Debugging Your
4524Program or @sc{gnu} CC, gcc.info, Using @sc{gnu} CC}, for more
4525information.
4526
4527
6d2ebf8b 4528@node Arrays
c906108c
SS
4529@section Artificial arrays
4530
4531@cindex artificial array
41afff9a 4532@kindex @@@r{, referencing memory as an array}
c906108c
SS
4533It is often useful to print out several successive objects of the
4534same type in memory; a section of an array, or an array of
4535dynamically determined size for which only a pointer exists in the
4536program.
4537
4538You can do this by referring to a contiguous span of memory as an
4539@dfn{artificial array}, using the binary operator @samp{@@}. The left
4540operand of @samp{@@} should be the first element of the desired array
4541and be an individual object. The right operand should be the desired length
4542of the array. The result is an array value whose elements are all of
4543the type of the left argument. The first element is actually the left
4544argument; the second element comes from bytes of memory immediately
4545following those that hold the first element, and so on. Here is an
4546example. If a program says
4547
4548@example
4549int *array = (int *) malloc (len * sizeof (int));
4550@end example
4551
4552@noindent
4553you can print the contents of @code{array} with
4554
4555@example
4556p *array@@len
4557@end example
4558
4559The left operand of @samp{@@} must reside in memory. Array values made
4560with @samp{@@} in this way behave just like other arrays in terms of
4561subscripting, and are coerced to pointers when used in expressions.
4562Artificial arrays most often appear in expressions via the value history
4563(@pxref{Value History, ,Value history}), after printing one out.
4564
4565Another way to create an artificial array is to use a cast.
4566This re-interprets a value as if it were an array.
4567The value need not be in memory:
4568@example
4569(@value{GDBP}) p/x (short[2])0x12345678
4570$1 = @{0x1234, 0x5678@}
4571@end example
4572
4573As a convenience, if you leave the array length out (as in
c3f6f71d 4574@samp{(@var{type}[])@var{value}}) @value{GDBN} calculates the size to fill
c906108c
SS
4575the value (as @samp{sizeof(@var{value})/sizeof(@var{type})}:
4576@example
4577(@value{GDBP}) p/x (short[])0x12345678
4578$2 = @{0x1234, 0x5678@}
4579@end example
4580
4581Sometimes the artificial array mechanism is not quite enough; in
4582moderately complex data structures, the elements of interest may not
4583actually be adjacent---for example, if you are interested in the values
4584of pointers in an array. One useful work-around in this situation is
4585to use a convenience variable (@pxref{Convenience Vars, ,Convenience
4586variables}) as a counter in an expression that prints the first
4587interesting value, and then repeat that expression via @key{RET}. For
4588instance, suppose you have an array @code{dtab} of pointers to
4589structures, and you are interested in the values of a field @code{fv}
4590in each structure. Here is an example of what you might type:
4591
4592@example
4593set $i = 0
4594p dtab[$i++]->fv
4595@key{RET}
4596@key{RET}
4597@dots{}
4598@end example
4599
6d2ebf8b 4600@node Output Formats
c906108c
SS
4601@section Output formats
4602
4603@cindex formatted output
4604@cindex output formats
4605By default, @value{GDBN} prints a value according to its data type. Sometimes
4606this is not what you want. For example, you might want to print a number
4607in hex, or a pointer in decimal. Or you might want to view data in memory
4608at a certain address as a character string or as an instruction. To do
4609these things, specify an @dfn{output format} when you print a value.
4610
4611The simplest use of output formats is to say how to print a value
4612already computed. This is done by starting the arguments of the
4613@code{print} command with a slash and a format letter. The format
4614letters supported are:
4615
4616@table @code
4617@item x
4618Regard the bits of the value as an integer, and print the integer in
4619hexadecimal.
4620
4621@item d
4622Print as integer in signed decimal.
4623
4624@item u
4625Print as integer in unsigned decimal.
4626
4627@item o
4628Print as integer in octal.
4629
4630@item t
4631Print as integer in binary. The letter @samp{t} stands for ``two''.
4632@footnote{@samp{b} cannot be used because these format letters are also
4633used with the @code{x} command, where @samp{b} stands for ``byte'';
d4f3574e 4634see @ref{Memory,,Examining memory}.}
c906108c
SS
4635
4636@item a
4637@cindex unknown address, locating
4638Print as an address, both absolute in hexadecimal and as an offset from
4639the nearest preceding symbol. You can use this format used to discover
4640where (in what function) an unknown address is located:
4641
4642@example
4643(@value{GDBP}) p/a 0x54320
4644$3 = 0x54320 <_initialize_vx+396>
4645@end example
4646
4647@item c
4648Regard as an integer and print it as a character constant.
4649
4650@item f
4651Regard the bits of the value as a floating point number and print
4652using typical floating point syntax.
4653@end table
4654
4655For example, to print the program counter in hex (@pxref{Registers}), type
4656
4657@example
4658p/x $pc
4659@end example
4660
4661@noindent
4662Note that no space is required before the slash; this is because command
4663names in @value{GDBN} cannot contain a slash.
4664
4665To reprint the last value in the value history with a different format,
4666you can use the @code{print} command with just a format and no
4667expression. For example, @samp{p/x} reprints the last value in hex.
4668
6d2ebf8b 4669@node Memory
c906108c
SS
4670@section Examining memory
4671
4672You can use the command @code{x} (for ``examine'') to examine memory in
4673any of several formats, independently of your program's data types.
4674
4675@cindex examining memory
4676@table @code
41afff9a 4677@kindex x @r{(examine memory)}
c906108c
SS
4678@item x/@var{nfu} @var{addr}
4679@itemx x @var{addr}
4680@itemx x
4681Use the @code{x} command to examine memory.
4682@end table
4683
4684@var{n}, @var{f}, and @var{u} are all optional parameters that specify how
4685much memory to display and how to format it; @var{addr} is an
4686expression giving the address where you want to start displaying memory.
4687If you use defaults for @var{nfu}, you need not type the slash @samp{/}.
4688Several commands set convenient defaults for @var{addr}.
4689
4690@table @r
4691@item @var{n}, the repeat count
4692The repeat count is a decimal integer; the default is 1. It specifies
4693how much memory (counting by units @var{u}) to display.
4694@c This really is **decimal**; unaffected by 'set radix' as of GDB
4695@c 4.1.2.
4696
4697@item @var{f}, the display format
4698The display format is one of the formats used by @code{print},
4699@samp{s} (null-terminated string), or @samp{i} (machine instruction).
4700The default is @samp{x} (hexadecimal) initially.
4701The default changes each time you use either @code{x} or @code{print}.
4702
4703@item @var{u}, the unit size
4704The unit size is any of
4705
4706@table @code
4707@item b
4708Bytes.
4709@item h
4710Halfwords (two bytes).
4711@item w
4712Words (four bytes). This is the initial default.
4713@item g
4714Giant words (eight bytes).
4715@end table
4716
4717Each time you specify a unit size with @code{x}, that size becomes the
4718default unit the next time you use @code{x}. (For the @samp{s} and
4719@samp{i} formats, the unit size is ignored and is normally not written.)
4720
4721@item @var{addr}, starting display address
4722@var{addr} is the address where you want @value{GDBN} to begin displaying
4723memory. The expression need not have a pointer value (though it may);
4724it is always interpreted as an integer address of a byte of memory.
4725@xref{Expressions, ,Expressions}, for more information on expressions. The default for
4726@var{addr} is usually just after the last address examined---but several
4727other commands also set the default address: @code{info breakpoints} (to
4728the address of the last breakpoint listed), @code{info line} (to the
4729starting address of a line), and @code{print} (if you use it to display
4730a value from memory).
4731@end table
4732
4733For example, @samp{x/3uh 0x54320} is a request to display three halfwords
4734(@code{h}) of memory, formatted as unsigned decimal integers (@samp{u}),
4735starting at address @code{0x54320}. @samp{x/4xw $sp} prints the four
4736words (@samp{w}) of memory above the stack pointer (here, @samp{$sp};
d4f3574e 4737@pxref{Registers, ,Registers}) in hexadecimal (@samp{x}).
c906108c
SS
4738
4739Since the letters indicating unit sizes are all distinct from the
4740letters specifying output formats, you do not have to remember whether
4741unit size or format comes first; either order works. The output
4742specifications @samp{4xw} and @samp{4wx} mean exactly the same thing.
4743(However, the count @var{n} must come first; @samp{wx4} does not work.)
4744
4745Even though the unit size @var{u} is ignored for the formats @samp{s}
4746and @samp{i}, you might still want to use a count @var{n}; for example,
4747@samp{3i} specifies that you want to see three machine instructions,
4748including any operands. The command @code{disassemble} gives an
d4f3574e 4749alternative way of inspecting machine instructions; see @ref{Machine
c906108c
SS
4750Code,,Source and machine code}.
4751
4752All the defaults for the arguments to @code{x} are designed to make it
4753easy to continue scanning memory with minimal specifications each time
4754you use @code{x}. For example, after you have inspected three machine
4755instructions with @samp{x/3i @var{addr}}, you can inspect the next seven
4756with just @samp{x/7}. If you use @key{RET} to repeat the @code{x} command,
4757the repeat count @var{n} is used again; the other arguments default as
4758for successive uses of @code{x}.
4759
4760@cindex @code{$_}, @code{$__}, and value history
4761The addresses and contents printed by the @code{x} command are not saved
4762in the value history because there is often too much of them and they
4763would get in the way. Instead, @value{GDBN} makes these values available for
4764subsequent use in expressions as values of the convenience variables
4765@code{$_} and @code{$__}. After an @code{x} command, the last address
4766examined is available for use in expressions in the convenience variable
4767@code{$_}. The contents of that address, as examined, are available in
4768the convenience variable @code{$__}.
4769
4770If the @code{x} command has a repeat count, the address and contents saved
4771are from the last memory unit printed; this is not the same as the last
4772address printed if several units were printed on the last line of output.
4773
6d2ebf8b 4774@node Auto Display
c906108c
SS
4775@section Automatic display
4776@cindex automatic display
4777@cindex display of expressions
4778
4779If you find that you want to print the value of an expression frequently
4780(to see how it changes), you might want to add it to the @dfn{automatic
4781display list} so that @value{GDBN} prints its value each time your program stops.
4782Each expression added to the list is given a number to identify it;
4783to remove an expression from the list, you specify that number.
4784The automatic display looks like this:
4785
4786@example
47872: foo = 38
47883: bar[5] = (struct hack *) 0x3804
4789@end example
4790
4791@noindent
4792This display shows item numbers, expressions and their current values. As with
4793displays you request manually using @code{x} or @code{print}, you can
4794specify the output format you prefer; in fact, @code{display} decides
4795whether to use @code{print} or @code{x} depending on how elaborate your
4796format specification is---it uses @code{x} if you specify a unit size,
4797or one of the two formats (@samp{i} and @samp{s}) that are only
4798supported by @code{x}; otherwise it uses @code{print}.
4799
4800@table @code
4801@kindex display
d4f3574e
SS
4802@item display @var{expr}
4803Add the expression @var{expr} to the list of expressions to display
c906108c
SS
4804each time your program stops. @xref{Expressions, ,Expressions}.
4805
4806@code{display} does not repeat if you press @key{RET} again after using it.
4807
d4f3574e 4808@item display/@var{fmt} @var{expr}
c906108c 4809For @var{fmt} specifying only a display format and not a size or
d4f3574e 4810count, add the expression @var{expr} to the auto-display list but
c906108c
SS
4811arrange to display it each time in the specified format @var{fmt}.
4812@xref{Output Formats,,Output formats}.
4813
4814@item display/@var{fmt} @var{addr}
4815For @var{fmt} @samp{i} or @samp{s}, or including a unit-size or a
4816number of units, add the expression @var{addr} as a memory address to
4817be examined each time your program stops. Examining means in effect
4818doing @samp{x/@var{fmt} @var{addr}}. @xref{Memory, ,Examining memory}.
4819@end table
4820
4821For example, @samp{display/i $pc} can be helpful, to see the machine
4822instruction about to be executed each time execution stops (@samp{$pc}
d4f3574e 4823is a common name for the program counter; @pxref{Registers, ,Registers}).
c906108c
SS
4824
4825@table @code
4826@kindex delete display
4827@kindex undisplay
4828@item undisplay @var{dnums}@dots{}
4829@itemx delete display @var{dnums}@dots{}
4830Remove item numbers @var{dnums} from the list of expressions to display.
4831
4832@code{undisplay} does not repeat if you press @key{RET} after using it.
4833(Otherwise you would just get the error @samp{No display number @dots{}}.)
4834
4835@kindex disable display
4836@item disable display @var{dnums}@dots{}
4837Disable the display of item numbers @var{dnums}. A disabled display
4838item is not printed automatically, but is not forgotten. It may be
4839enabled again later.
4840
4841@kindex enable display
4842@item enable display @var{dnums}@dots{}
4843Enable display of item numbers @var{dnums}. It becomes effective once
4844again in auto display of its expression, until you specify otherwise.
4845
4846@item display
4847Display the current values of the expressions on the list, just as is
4848done when your program stops.
4849
4850@kindex info display
4851@item info display
4852Print the list of expressions previously set up to display
4853automatically, each one with its item number, but without showing the
4854values. This includes disabled expressions, which are marked as such.
4855It also includes expressions which would not be displayed right now
4856because they refer to automatic variables not currently available.
4857@end table
4858
4859If a display expression refers to local variables, then it does not make
4860sense outside the lexical context for which it was set up. Such an
4861expression is disabled when execution enters a context where one of its
4862variables is not defined. For example, if you give the command
4863@code{display last_char} while inside a function with an argument
4864@code{last_char}, @value{GDBN} displays this argument while your program
4865continues to stop inside that function. When it stops elsewhere---where
4866there is no variable @code{last_char}---the display is disabled
4867automatically. The next time your program stops where @code{last_char}
4868is meaningful, you can enable the display expression once again.
4869
6d2ebf8b 4870@node Print Settings
c906108c
SS
4871@section Print settings
4872
4873@cindex format options
4874@cindex print settings
4875@value{GDBN} provides the following ways to control how arrays, structures,
4876and symbols are printed.
4877
4878@noindent
4879These settings are useful for debugging programs in any language:
4880
4881@table @code
4882@kindex set print address
4883@item set print address
4884@itemx set print address on
4885@value{GDBN} prints memory addresses showing the location of stack
4886traces, structure values, pointer values, breakpoints, and so forth,
4887even when it also displays the contents of those addresses. The default
4888is @code{on}. For example, this is what a stack frame display looks like with
4889@code{set print address on}:
4890
4891@smallexample
4892@group
4893(@value{GDBP}) f
4894#0 set_quotes (lq=0x34c78 "<<", rq=0x34c88 ">>")
4895 at input.c:530
4896530 if (lquote != def_lquote)
4897@end group
4898@end smallexample
4899
4900@item set print address off
4901Do not print addresses when displaying their contents. For example,
4902this is the same stack frame displayed with @code{set print address off}:
4903
4904@smallexample
4905@group
4906(@value{GDBP}) set print addr off
4907(@value{GDBP}) f
4908#0 set_quotes (lq="<<", rq=">>") at input.c:530
4909530 if (lquote != def_lquote)
4910@end group
4911@end smallexample
4912
4913You can use @samp{set print address off} to eliminate all machine
4914dependent displays from the @value{GDBN} interface. For example, with
4915@code{print address off}, you should get the same text for backtraces on
4916all machines---whether or not they involve pointer arguments.
4917
4918@kindex show print address
4919@item show print address
4920Show whether or not addresses are to be printed.
4921@end table
4922
4923When @value{GDBN} prints a symbolic address, it normally prints the
4924closest earlier symbol plus an offset. If that symbol does not uniquely
4925identify the address (for example, it is a name whose scope is a single
4926source file), you may need to clarify. One way to do this is with
4927@code{info line}, for example @samp{info line *0x4537}. Alternately,
4928you can set @value{GDBN} to print the source file and line number when
4929it prints a symbolic address:
4930
4931@table @code
4932@kindex set print symbol-filename
4933@item set print symbol-filename on
4934Tell @value{GDBN} to print the source file name and line number of a
4935symbol in the symbolic form of an address.
4936
4937@item set print symbol-filename off
4938Do not print source file name and line number of a symbol. This is the
4939default.
4940
4941@kindex show print symbol-filename
4942@item show print symbol-filename
4943Show whether or not @value{GDBN} will print the source file name and
4944line number of a symbol in the symbolic form of an address.
4945@end table
4946
4947Another situation where it is helpful to show symbol filenames and line
4948numbers is when disassembling code; @value{GDBN} shows you the line
4949number and source file that corresponds to each instruction.
4950
4951Also, you may wish to see the symbolic form only if the address being
4952printed is reasonably close to the closest earlier symbol:
4953
4954@table @code
4955@kindex set print max-symbolic-offset
4956@item set print max-symbolic-offset @var{max-offset}
4957Tell @value{GDBN} to only display the symbolic form of an address if the
4958offset between the closest earlier symbol and the address is less than
5d161b24 4959@var{max-offset}. The default is 0, which tells @value{GDBN}
c906108c
SS
4960to always print the symbolic form of an address if any symbol precedes it.
4961
4962@kindex show print max-symbolic-offset
4963@item show print max-symbolic-offset
4964Ask how large the maximum offset is that @value{GDBN} prints in a
4965symbolic address.
4966@end table
4967
4968@cindex wild pointer, interpreting
4969@cindex pointer, finding referent
4970If you have a pointer and you are not sure where it points, try
4971@samp{set print symbol-filename on}. Then you can determine the name
4972and source file location of the variable where it points, using
4973@samp{p/a @var{pointer}}. This interprets the address in symbolic form.
4974For example, here @value{GDBN} shows that a variable @code{ptt} points
4975at another variable @code{t}, defined in @file{hi2.c}:
4976
4977@example
4978(@value{GDBP}) set print symbol-filename on
4979(@value{GDBP}) p/a ptt
4980$4 = 0xe008 <t in hi2.c>
4981@end example
4982
4983@quotation
4984@emph{Warning:} For pointers that point to a local variable, @samp{p/a}
4985does not show the symbol name and filename of the referent, even with
4986the appropriate @code{set print} options turned on.
4987@end quotation
4988
4989Other settings control how different kinds of objects are printed:
4990
4991@table @code
4992@kindex set print array
4993@item set print array
4994@itemx set print array on
4995Pretty print arrays. This format is more convenient to read,
4996but uses more space. The default is off.
4997
4998@item set print array off
4999Return to compressed format for arrays.
5000
5001@kindex show print array
5002@item show print array
5003Show whether compressed or pretty format is selected for displaying
5004arrays.
5005
5006@kindex set print elements
5007@item set print elements @var{number-of-elements}
5008Set a limit on how many elements of an array @value{GDBN} will print.
5009If @value{GDBN} is printing a large array, it stops printing after it has
5010printed the number of elements set by the @code{set print elements} command.
5011This limit also applies to the display of strings.
d4f3574e 5012When @value{GDBN} starts, this limit is set to 200.
c906108c
SS
5013Setting @var{number-of-elements} to zero means that the printing is unlimited.
5014
5015@kindex show print elements
5016@item show print elements
5017Display the number of elements of a large array that @value{GDBN} will print.
5018If the number is 0, then the printing is unlimited.
5019
5020@kindex set print null-stop
5021@item set print null-stop
5022Cause @value{GDBN} to stop printing the characters of an array when the first
d4f3574e 5023@sc{null} is encountered. This is useful when large arrays actually
c906108c 5024contain only short strings.
d4f3574e 5025The default is off.
c906108c
SS
5026
5027@kindex set print pretty
5028@item set print pretty on
5d161b24 5029Cause @value{GDBN} to print structures in an indented format with one member
c906108c
SS
5030per line, like this:
5031
5032@smallexample
5033@group
5034$1 = @{
5035 next = 0x0,
5036 flags = @{
5037 sweet = 1,
5038 sour = 1
5039 @},
5040 meat = 0x54 "Pork"
5041@}
5042@end group
5043@end smallexample
5044
5045@item set print pretty off
5046Cause @value{GDBN} to print structures in a compact format, like this:
5047
5048@smallexample
5049@group
5050$1 = @{next = 0x0, flags = @{sweet = 1, sour = 1@}, \
5051meat = 0x54 "Pork"@}
5052@end group
5053@end smallexample
5054
5055@noindent
5056This is the default format.
5057
5058@kindex show print pretty
5059@item show print pretty
5060Show which format @value{GDBN} is using to print structures.
5061
5062@kindex set print sevenbit-strings
5063@item set print sevenbit-strings on
5064Print using only seven-bit characters; if this option is set,
5065@value{GDBN} displays any eight-bit characters (in strings or
5066character values) using the notation @code{\}@var{nnn}. This setting is
5067best if you are working in English (@sc{ascii}) and you use the
5068high-order bit of characters as a marker or ``meta'' bit.
5069
5070@item set print sevenbit-strings off
5071Print full eight-bit characters. This allows the use of more
5072international character sets, and is the default.
5073
5074@kindex show print sevenbit-strings
5075@item show print sevenbit-strings
5076Show whether or not @value{GDBN} is printing only seven-bit characters.
5077
5078@kindex set print union
5079@item set print union on
5d161b24 5080Tell @value{GDBN} to print unions which are contained in structures. This
c906108c
SS
5081is the default setting.
5082
5083@item set print union off
5084Tell @value{GDBN} not to print unions which are contained in structures.
5085
5086@kindex show print union
5087@item show print union
5088Ask @value{GDBN} whether or not it will print unions which are contained in
5089structures.
5090
5091For example, given the declarations
5092
5093@smallexample
5094typedef enum @{Tree, Bug@} Species;
5095typedef enum @{Big_tree, Acorn, Seedling@} Tree_forms;
5d161b24 5096typedef enum @{Caterpillar, Cocoon, Butterfly@}
c906108c
SS
5097 Bug_forms;
5098
5099struct thing @{
5100 Species it;
5101 union @{
5102 Tree_forms tree;
5103 Bug_forms bug;
5104 @} form;
5105@};
5106
5107struct thing foo = @{Tree, @{Acorn@}@};
5108@end smallexample
5109
5110@noindent
5111with @code{set print union on} in effect @samp{p foo} would print
5112
5113@smallexample
5114$1 = @{it = Tree, form = @{tree = Acorn, bug = Cocoon@}@}
5115@end smallexample
5116
5117@noindent
5118and with @code{set print union off} in effect it would print
5119
5120@smallexample
5121$1 = @{it = Tree, form = @{...@}@}
5122@end smallexample
5123@end table
5124
c906108c
SS
5125@need 1000
5126@noindent
5127These settings are of interest when debugging C++ programs:
5128
5129@table @code
5130@cindex demangling
5131@kindex set print demangle
5132@item set print demangle
5133@itemx set print demangle on
5134Print C++ names in their source form rather than in the encoded
5135(``mangled'') form passed to the assembler and linker for type-safe
d4f3574e 5136linkage. The default is on.
c906108c
SS
5137
5138@kindex show print demangle
5139@item show print demangle
5140Show whether C++ names are printed in mangled or demangled form.
5141
5142@kindex set print asm-demangle
5143@item set print asm-demangle
5144@itemx set print asm-demangle on
5145Print C++ names in their source form rather than their mangled form, even
5146in assembler code printouts such as instruction disassemblies.
5147The default is off.
5148
5149@kindex show print asm-demangle
5150@item show print asm-demangle
5151Show whether C++ names in assembly listings are printed in mangled
5152or demangled form.
5153
5154@kindex set demangle-style
5155@cindex C++ symbol decoding style
5156@cindex symbol decoding style, C++
5157@item set demangle-style @var{style}
5158Choose among several encoding schemes used by different compilers to
5159represent C++ names. The choices for @var{style} are currently:
5160
5161@table @code
5162@item auto
5163Allow @value{GDBN} to choose a decoding style by inspecting your program.
5164
5165@item gnu
5d161b24 5166Decode based on the @sc{gnu} C++ compiler (@code{g++}) encoding algorithm.
c906108c 5167This is the default.
c906108c
SS
5168
5169@item hp
5170Decode based on the HP ANSI C++ (@code{aCC}) encoding algorithm.
5171
5172@item lucid
5173Decode based on the Lucid C++ compiler (@code{lcc}) encoding algorithm.
5174
5175@item arm
5176Decode using the algorithm in the @cite{C++ Annotated Reference Manual}.
5177@strong{Warning:} this setting alone is not sufficient to allow
5178debugging @code{cfront}-generated executables. @value{GDBN} would
5179require further enhancement to permit that.
5180
5181@end table
5182If you omit @var{style}, you will see a list of possible formats.
5183
5184@kindex show demangle-style
5185@item show demangle-style
5186Display the encoding style currently in use for decoding C++ symbols.
5187
5188@kindex set print object
5189@item set print object
5190@itemx set print object on
5191When displaying a pointer to an object, identify the @emph{actual}
5192(derived) type of the object rather than the @emph{declared} type, using
5193the virtual function table.
5194
5195@item set print object off
5196Display only the declared type of objects, without reference to the
5197virtual function table. This is the default setting.
5198
5199@kindex show print object
5200@item show print object
5201Show whether actual, or declared, object types are displayed.
5202
5203@kindex set print static-members
5204@item set print static-members
5205@itemx set print static-members on
5206Print static members when displaying a C++ object. The default is on.
5207
5208@item set print static-members off
5209Do not print static members when displaying a C++ object.
5210
5211@kindex show print static-members
5212@item show print static-members
5213Show whether C++ static members are printed, or not.
5214
5215@c These don't work with HP ANSI C++ yet.
5216@kindex set print vtbl
5217@item set print vtbl
5218@itemx set print vtbl on
5219Pretty print C++ virtual function tables. The default is off.
c906108c
SS
5220(The @code{vtbl} commands do not work on programs compiled with the HP
5221ANSI C++ compiler (@code{aCC}).)
c906108c
SS
5222
5223@item set print vtbl off
5224Do not pretty print C++ virtual function tables.
5225
5226@kindex show print vtbl
5227@item show print vtbl
5228Show whether C++ virtual function tables are pretty printed, or not.
5229@end table
c906108c 5230
6d2ebf8b 5231@node Value History
c906108c
SS
5232@section Value history
5233
5234@cindex value history
5d161b24
DB
5235Values printed by the @code{print} command are saved in the @value{GDBN}
5236@dfn{value history}. This allows you to refer to them in other expressions.
5237Values are kept until the symbol table is re-read or discarded
5238(for example with the @code{file} or @code{symbol-file} commands).
5239When the symbol table changes, the value history is discarded,
5240since the values may contain pointers back to the types defined in the
c906108c
SS
5241symbol table.
5242
5243@cindex @code{$}
5244@cindex @code{$$}
5245@cindex history number
5246The values printed are given @dfn{history numbers} by which you can
5247refer to them. These are successive integers starting with one.
5248@code{print} shows you the history number assigned to a value by
5249printing @samp{$@var{num} = } before the value; here @var{num} is the
5250history number.
5251
5252To refer to any previous value, use @samp{$} followed by the value's
5253history number. The way @code{print} labels its output is designed to
5254remind you of this. Just @code{$} refers to the most recent value in
5255the history, and @code{$$} refers to the value before that.
5256@code{$$@var{n}} refers to the @var{n}th value from the end; @code{$$2}
5257is the value just prior to @code{$$}, @code{$$1} is equivalent to
5258@code{$$}, and @code{$$0} is equivalent to @code{$}.
5259
5260For example, suppose you have just printed a pointer to a structure and
5261want to see the contents of the structure. It suffices to type
5262
5263@example
5264p *$
5265@end example
5266
5267If you have a chain of structures where the component @code{next} points
5268to the next one, you can print the contents of the next one with this:
5269
5270@example
5271p *$.next
5272@end example
5273
5274@noindent
5275You can print successive links in the chain by repeating this
5276command---which you can do by just typing @key{RET}.
5277
5278Note that the history records values, not expressions. If the value of
5279@code{x} is 4 and you type these commands:
5280
5281@example
5282print x
5283set x=5
5284@end example
5285
5286@noindent
5287then the value recorded in the value history by the @code{print} command
5288remains 4 even though the value of @code{x} has changed.
5289
5290@table @code
5291@kindex show values
5292@item show values
5293Print the last ten values in the value history, with their item numbers.
5294This is like @samp{p@ $$9} repeated ten times, except that @code{show
5295values} does not change the history.
5296
5297@item show values @var{n}
5298Print ten history values centered on history item number @var{n}.
5299
5300@item show values +
5301Print ten history values just after the values last printed. If no more
5302values are available, @code{show values +} produces no display.
5303@end table
5304
5305Pressing @key{RET} to repeat @code{show values @var{n}} has exactly the
5306same effect as @samp{show values +}.
5307
6d2ebf8b 5308@node Convenience Vars
c906108c
SS
5309@section Convenience variables
5310
5311@cindex convenience variables
5312@value{GDBN} provides @dfn{convenience variables} that you can use within
5313@value{GDBN} to hold on to a value and refer to it later. These variables
5314exist entirely within @value{GDBN}; they are not part of your program, and
5315setting a convenience variable has no direct effect on further execution
5316of your program. That is why you can use them freely.
5317
5318Convenience variables are prefixed with @samp{$}. Any name preceded by
5319@samp{$} can be used for a convenience variable, unless it is one of
d4f3574e 5320the predefined machine-specific register names (@pxref{Registers, ,Registers}).
c906108c
SS
5321(Value history references, in contrast, are @emph{numbers} preceded
5322by @samp{$}. @xref{Value History, ,Value history}.)
5323
5324You can save a value in a convenience variable with an assignment
5325expression, just as you would set a variable in your program.
5326For example:
5327
5328@example
5329set $foo = *object_ptr
5330@end example
5331
5332@noindent
5333would save in @code{$foo} the value contained in the object pointed to by
5334@code{object_ptr}.
5335
5336Using a convenience variable for the first time creates it, but its
5337value is @code{void} until you assign a new value. You can alter the
5338value with another assignment at any time.
5339
5340Convenience variables have no fixed types. You can assign a convenience
5341variable any type of value, including structures and arrays, even if
5342that variable already has a value of a different type. The convenience
5343variable, when used as an expression, has the type of its current value.
5344
5345@table @code
5346@kindex show convenience
5347@item show convenience
5348Print a list of convenience variables used so far, and their values.
d4f3574e 5349Abbreviated @code{show conv}.
c906108c
SS
5350@end table
5351
5352One of the ways to use a convenience variable is as a counter to be
5353incremented or a pointer to be advanced. For example, to print
5354a field from successive elements of an array of structures:
5355
5356@example
5357set $i = 0
5358print bar[$i++]->contents
5359@end example
5360
d4f3574e
SS
5361@noindent
5362Repeat that command by typing @key{RET}.
c906108c
SS
5363
5364Some convenience variables are created automatically by @value{GDBN} and given
5365values likely to be useful.
5366
5367@table @code
41afff9a 5368@vindex $_@r{, convenience variable}
c906108c
SS
5369@item $_
5370The variable @code{$_} is automatically set by the @code{x} command to
5371the last address examined (@pxref{Memory, ,Examining memory}). Other
5372commands which provide a default address for @code{x} to examine also
5373set @code{$_} to that address; these commands include @code{info line}
5374and @code{info breakpoint}. The type of @code{$_} is @code{void *}
5375except when set by the @code{x} command, in which case it is a pointer
5376to the type of @code{$__}.
5377
41afff9a 5378@vindex $__@r{, convenience variable}
c906108c
SS
5379@item $__
5380The variable @code{$__} is automatically set by the @code{x} command
5381to the value found in the last address examined. Its type is chosen
5382to match the format in which the data was printed.
5383
5384@item $_exitcode
41afff9a 5385@vindex $_exitcode@r{, convenience variable}
c906108c
SS
5386The variable @code{$_exitcode} is automatically set to the exit code when
5387the program being debugged terminates.
5388@end table
5389
53a5351d
JM
5390On HP-UX systems, if you refer to a function or variable name that
5391begins with a dollar sign, @value{GDBN} searches for a user or system
5392name first, before it searches for a convenience variable.
c906108c 5393
6d2ebf8b 5394@node Registers
c906108c
SS
5395@section Registers
5396
5397@cindex registers
5398You can refer to machine register contents, in expressions, as variables
5399with names starting with @samp{$}. The names of registers are different
5400for each machine; use @code{info registers} to see the names used on
5401your machine.
5402
5403@table @code
5404@kindex info registers
5405@item info registers
5406Print the names and values of all registers except floating-point
5407registers (in the selected stack frame).
5408
5409@kindex info all-registers
5410@cindex floating point registers
5411@item info all-registers
5412Print the names and values of all registers, including floating-point
5413registers.
5414
5415@item info registers @var{regname} @dots{}
5416Print the @dfn{relativized} value of each specified register @var{regname}.
5d161b24
DB
5417As discussed in detail below, register values are normally relative to
5418the selected stack frame. @var{regname} may be any register name valid on
c906108c
SS
5419the machine you are using, with or without the initial @samp{$}.
5420@end table
5421
5422@value{GDBN} has four ``standard'' register names that are available (in
5423expressions) on most machines---whenever they do not conflict with an
5424architecture's canonical mnemonics for registers. The register names
5425@code{$pc} and @code{$sp} are used for the program counter register and
5426the stack pointer. @code{$fp} is used for a register that contains a
5427pointer to the current stack frame, and @code{$ps} is used for a
5428register that contains the processor status. For example,
5429you could print the program counter in hex with
5430
5431@example
5432p/x $pc
5433@end example
5434
5435@noindent
5436or print the instruction to be executed next with
5437
5438@example
5439x/i $pc
5440@end example
5441
5442@noindent
5443or add four to the stack pointer@footnote{This is a way of removing
5444one word from the stack, on machines where stacks grow downward in
5445memory (most machines, nowadays). This assumes that the innermost
5446stack frame is selected; setting @code{$sp} is not allowed when other
5447stack frames are selected. To pop entire frames off the stack,
5448regardless of machine architecture, use @code{return};
d4f3574e 5449see @ref{Returning, ,Returning from a function}.} with
c906108c
SS
5450
5451@example
5452set $sp += 4
5453@end example
5454
5455Whenever possible, these four standard register names are available on
5456your machine even though the machine has different canonical mnemonics,
5457so long as there is no conflict. The @code{info registers} command
5458shows the canonical names. For example, on the SPARC, @code{info
5459registers} displays the processor status register as @code{$psr} but you
d4f3574e
SS
5460can also refer to it as @code{$ps}; and on x86-based machines @code{$ps}
5461is an alias for the @sc{eflags} register.
c906108c
SS
5462
5463@value{GDBN} always considers the contents of an ordinary register as an
5464integer when the register is examined in this way. Some machines have
5465special registers which can hold nothing but floating point; these
5466registers are considered to have floating point values. There is no way
5467to refer to the contents of an ordinary register as floating point value
5468(although you can @emph{print} it as a floating point value with
5469@samp{print/f $@var{regname}}).
5470
5471Some registers have distinct ``raw'' and ``virtual'' data formats. This
5472means that the data format in which the register contents are saved by
5473the operating system is not the same one that your program normally
5474sees. For example, the registers of the 68881 floating point
5475coprocessor are always saved in ``extended'' (raw) format, but all C
5476programs expect to work with ``double'' (virtual) format. In such
5d161b24 5477cases, @value{GDBN} normally works with the virtual format only (the format
c906108c
SS
5478that makes sense for your program), but the @code{info registers} command
5479prints the data in both formats.
5480
5481Normally, register values are relative to the selected stack frame
5482(@pxref{Selection, ,Selecting a frame}). This means that you get the
5483value that the register would contain if all stack frames farther in
5484were exited and their saved registers restored. In order to see the
5485true contents of hardware registers, you must select the innermost
5486frame (with @samp{frame 0}).
5487
5488However, @value{GDBN} must deduce where registers are saved, from the machine
5489code generated by your compiler. If some registers are not saved, or if
5490@value{GDBN} is unable to locate the saved registers, the selected stack
5491frame makes no difference.
5492
6d2ebf8b 5493@node Floating Point Hardware
c906108c
SS
5494@section Floating point hardware
5495@cindex floating point
5496
5497Depending on the configuration, @value{GDBN} may be able to give
5498you more information about the status of the floating point hardware.
5499
5500@table @code
5501@kindex info float
5502@item info float
5503Display hardware-dependent information about the floating
5504point unit. The exact contents and layout vary depending on the
5505floating point chip. Currently, @samp{info float} is supported on
5506the ARM and x86 machines.
5507@end table
c906108c 5508
29e57380
C
5509@node Memory Region Attributes
5510@section Memory Region Attributes
5511@cindex memory region attributes
5512
5513@dfn{Memory region attributes} allow you to describe special handling
5514required by regions of your target's memory. @value{GDBN} uses attributes
5515to determine whether to allow certain types of memory accesses; whether to
5516use specific width accesses; and whether to cache target memory.
5517
5518Defined memory regions can be individually enabled and disabled. When a
5519memory region is disabled, @value{GDBN} uses the default attributes when
5520accessing memory in that region. Similarly, if no memory regions have
5521been defined, @value{GDBN} uses the default attributes when accessing
5522all memory.
5523
5524When a memory region is defined, it is given a number to identify it;
5525to enable, disable, or remove a memory region, you specify that number.
5526
5527@table @code
5528@kindex mem
5529@item mem @var{address1} @var{address1} @var{attributes}@dots{}
5530Define memory region bounded by @var{address1} and @var{address2}
5531with attributes @var{attributes}@dots{}.
5532
5533@kindex delete mem
5534@item delete mem @var{nums}@dots{}
5535Remove memory region numbers @var{nums}.
5536
5537@kindex disable mem
5538@item disable mem @var{nums}@dots{}
5539Disable memory region numbers @var{nums}.
5540A disabled memory region is not forgotten.
5541It may be enabled again later.
5542
5543@kindex enable mem
5544@item enable mem @var{nums}@dots{}
5545Enable memory region numbers @var{nums}.
5546
5547@kindex info mem
5548@item info mem
5549Print a table of all defined memory regions, with the following columns
5550for each region.
5551
5552@table @emph
5553@item Memory Region Number
5554@item Enabled or Disabled.
5555Enabled memory regions are marked with @samp{y}.
5556Disabled memory regions are marked with @samp{n}.
5557
5558@item Lo Address
5559The address defining the inclusive lower bound of the memory region.
5560
5561@item Hi Address
5562The address defining the exclusive upper bound of the memory region.
5563
5564@item Attributes
5565The list of attributes set for this memory region.
5566@end table
5567@end table
5568
5569
5570@subsection Attributes
5571
5572@subsubsection Memory Access Mode
5573The access mode attributes set whether @value{GDBN} may make read or
5574write accesses to a memory region.
5575
5576While these attributes prevent @value{GDBN} from performing invalid
5577memory accesses, they do nothing to prevent the target system, I/O DMA,
5578etc. from accessing memory.
5579
5580@table @code
5581@item ro
5582Memory is read only.
5583@item wo
5584Memory is write only.
5585@item rw
5586Memory is read/write (default).
5587@end table
5588
5589@subsubsection Memory Access Size
5590The acccess size attributes tells @value{GDBN} to use specific sized
5591accesses in the memory region. Often memory mapped device registers
5592require specific sized accesses. If no access size attribute is
5593specified, @value{GDBN} may use accesses of any size.
5594
5595@table @code
5596@item 8
5597Use 8 bit memory accesses.
5598@item 16
5599Use 16 bit memory accesses.
5600@item 32
5601Use 32 bit memory accesses.
5602@item 64
5603Use 64 bit memory accesses.
5604@end table
5605
5606@c @subsubsection Hardware/Software Breakpoints
5607@c The hardware/software breakpoint attributes set whether @value{GDBN}
5608@c will use hardware or software breakpoints for the internal breakpoints
5609@c used by the step, next, finish, until, etc. commands.
5610@c
5611@c @table @code
5612@c @item hwbreak
5613@c Always use hardware breakpoints
5614@c @item swbreak (default)
5615@c @end table
5616
5617@subsubsection Data Cache
5618The data cache attributes set whether @value{GDBN} will cache target
5619memory. While this generally improves performance by reducing debug
5620protocol overhead, it can lead to incorrect results because @value{GDBN}
5621does not know about volatile variables or memory mapped device
5622registers.
5623
5624@table @code
5625@item cache
5626Enable @value{GDBN} to cache target memory.
5627@item nocache (default)
5628Disable @value{GDBN} from caching target memory.
5629@end table
5630
5631@c @subsubsection Memory Write Verification
5632@c The memory write verification attributes set whether @value{GDBN}
5633@c will re-reads data after each write to verify the write was successful.
5634@c
5635@c @table @code
5636@c @item verify
5637@c @item noverify (default)
5638@c @end table
5639
6d2ebf8b 5640@node Languages
c906108c
SS
5641@chapter Using @value{GDBN} with Different Languages
5642@cindex languages
5643
c906108c
SS
5644Although programming languages generally have common aspects, they are
5645rarely expressed in the same manner. For instance, in ANSI C,
5646dereferencing a pointer @code{p} is accomplished by @code{*p}, but in
5647Modula-2, it is accomplished by @code{p^}. Values can also be
5d161b24 5648represented (and displayed) differently. Hex numbers in C appear as
c906108c 5649@samp{0x1ae}, while in Modula-2 they appear as @samp{1AEH}.
c906108c
SS
5650
5651@cindex working language
5652Language-specific information is built into @value{GDBN} for some languages,
5653allowing you to express operations like the above in your program's
5654native language, and allowing @value{GDBN} to output values in a manner
5655consistent with the syntax of your program's native language. The
5656language you use to build expressions is called the @dfn{working
5657language}.
5658
5659@menu
5660* Setting:: Switching between source languages
5661* Show:: Displaying the language
c906108c 5662* Checks:: Type and range checks
c906108c
SS
5663* Support:: Supported languages
5664@end menu
5665
6d2ebf8b 5666@node Setting
c906108c
SS
5667@section Switching between source languages
5668
5669There are two ways to control the working language---either have @value{GDBN}
5670set it automatically, or select it manually yourself. You can use the
5671@code{set language} command for either purpose. On startup, @value{GDBN}
5672defaults to setting the language automatically. The working language is
5673used to determine how expressions you type are interpreted, how values
5674are printed, etc.
5675
5676In addition to the working language, every source file that
5677@value{GDBN} knows about has its own working language. For some object
5678file formats, the compiler might indicate which language a particular
5679source file is in. However, most of the time @value{GDBN} infers the
5680language from the name of the file. The language of a source file
5681controls whether C++ names are demangled---this way @code{backtrace} can
5682show each frame appropriately for its own language. There is no way to
d4f3574e
SS
5683set the language of a source file from within @value{GDBN}, but you can
5684set the language associated with a filename extension. @xref{Show, ,
5685Displaying the language}.
c906108c
SS
5686
5687This is most commonly a problem when you use a program, such
5d161b24 5688as @code{cfront} or @code{f2c}, that generates C but is written in
c906108c
SS
5689another language. In that case, make the
5690program use @code{#line} directives in its C output; that way
5691@value{GDBN} will know the correct language of the source code of the original
5692program, and will display that source code, not the generated C code.
5693
5694@menu
5695* Filenames:: Filename extensions and languages.
5696* Manually:: Setting the working language manually
5697* Automatically:: Having @value{GDBN} infer the source language
5698@end menu
5699
6d2ebf8b 5700@node Filenames
c906108c
SS
5701@subsection List of filename extensions and languages
5702
5703If a source file name ends in one of the following extensions, then
5704@value{GDBN} infers that its language is the one indicated.
5705
5706@table @file
5707
5708@item .c
5709C source file
5710
5711@item .C
5712@itemx .cc
5713@itemx .cp
5714@itemx .cpp
5715@itemx .cxx
5716@itemx .c++
5717C++ source file
5718
5719@item .f
5720@itemx .F
5721Fortran source file
5722
c906108c
SS
5723@item .ch
5724@itemx .c186
5725@itemx .c286
96a2c332 5726CHILL source file
c906108c 5727
c906108c
SS
5728@item .mod
5729Modula-2 source file
c906108c
SS
5730
5731@item .s
5732@itemx .S
5733Assembler source file. This actually behaves almost like C, but
5734@value{GDBN} does not skip over function prologues when stepping.
5735@end table
5736
5737In addition, you may set the language associated with a filename
5738extension. @xref{Show, , Displaying the language}.
5739
6d2ebf8b 5740@node Manually
c906108c
SS
5741@subsection Setting the working language
5742
5743If you allow @value{GDBN} to set the language automatically,
5744expressions are interpreted the same way in your debugging session and
5745your program.
5746
5747@kindex set language
5748If you wish, you may set the language manually. To do this, issue the
5749command @samp{set language @var{lang}}, where @var{lang} is the name of
5d161b24 5750a language, such as
c906108c 5751@code{c} or @code{modula-2}.
c906108c
SS
5752For a list of the supported languages, type @samp{set language}.
5753
c906108c
SS
5754Setting the language manually prevents @value{GDBN} from updating the working
5755language automatically. This can lead to confusion if you try
5756to debug a program when the working language is not the same as the
5757source language, when an expression is acceptable to both
5758languages---but means different things. For instance, if the current
5759source file were written in C, and @value{GDBN} was parsing Modula-2, a
5760command such as:
5761
5762@example
5763print a = b + c
5764@end example
5765
5766@noindent
5767might not have the effect you intended. In C, this means to add
5768@code{b} and @code{c} and place the result in @code{a}. The result
5769printed would be the value of @code{a}. In Modula-2, this means to compare
5770@code{a} to the result of @code{b+c}, yielding a @code{BOOLEAN} value.
c906108c 5771
6d2ebf8b 5772@node Automatically
c906108c
SS
5773@subsection Having @value{GDBN} infer the source language
5774
5775To have @value{GDBN} set the working language automatically, use
5776@samp{set language local} or @samp{set language auto}. @value{GDBN}
5777then infers the working language. That is, when your program stops in a
5778frame (usually by encountering a breakpoint), @value{GDBN} sets the
5779working language to the language recorded for the function in that
5780frame. If the language for a frame is unknown (that is, if the function
5781or block corresponding to the frame was defined in a source file that
5782does not have a recognized extension), the current working language is
5783not changed, and @value{GDBN} issues a warning.
5784
5785This may not seem necessary for most programs, which are written
5786entirely in one source language. However, program modules and libraries
5787written in one source language can be used by a main program written in
5788a different source language. Using @samp{set language auto} in this
5789case frees you from having to set the working language manually.
5790
6d2ebf8b 5791@node Show
c906108c 5792@section Displaying the language
c906108c
SS
5793
5794The following commands help you find out which language is the
5795working language, and also what language source files were written in.
5796
5797@kindex show language
d4f3574e
SS
5798@kindex info frame@r{, show the source language}
5799@kindex info source@r{, show the source language}
c906108c
SS
5800@table @code
5801@item show language
5802Display the current working language. This is the
5803language you can use with commands such as @code{print} to
5804build and compute expressions that may involve variables in your program.
5805
5806@item info frame
5d161b24 5807Display the source language for this frame. This language becomes the
c906108c 5808working language if you use an identifier from this frame.
5d161b24 5809@xref{Frame Info, ,Information about a frame}, to identify the other
c906108c
SS
5810information listed here.
5811
5812@item info source
5813Display the source language of this source file.
5d161b24 5814@xref{Symbols, ,Examining the Symbol Table}, to identify the other
c906108c
SS
5815information listed here.
5816@end table
5817
5818In unusual circumstances, you may have source files with extensions
5819not in the standard list. You can then set the extension associated
5820with a language explicitly:
5821
5822@kindex set extension-language
5823@kindex info extensions
5824@table @code
5825@item set extension-language @var{.ext} @var{language}
5826Set source files with extension @var{.ext} to be assumed to be in
5827the source language @var{language}.
5828
5829@item info extensions
5830List all the filename extensions and the associated languages.
5831@end table
5832
6d2ebf8b 5833@node Checks
c906108c
SS
5834@section Type and range checking
5835
5836@quotation
5837@emph{Warning:} In this release, the @value{GDBN} commands for type and range
5838checking are included, but they do not yet have any effect. This
5839section documents the intended facilities.
5840@end quotation
5841@c FIXME remove warning when type/range code added
5842
5843Some languages are designed to guard you against making seemingly common
5844errors through a series of compile- and run-time checks. These include
5845checking the type of arguments to functions and operators, and making
5846sure mathematical overflows are caught at run time. Checks such as
5847these help to ensure a program's correctness once it has been compiled
5848by eliminating type mismatches, and providing active checks for range
5849errors when your program is running.
5850
5851@value{GDBN} can check for conditions like the above if you wish.
5852Although @value{GDBN} does not check the statements in your program, it
5853can check expressions entered directly into @value{GDBN} for evaluation via
5854the @code{print} command, for example. As with the working language,
5855@value{GDBN} can also decide whether or not to check automatically based on
5856your program's source language. @xref{Support, ,Supported languages},
5857for the default settings of supported languages.
5858
5859@menu
5860* Type Checking:: An overview of type checking
5861* Range Checking:: An overview of range checking
5862@end menu
5863
5864@cindex type checking
5865@cindex checks, type
6d2ebf8b 5866@node Type Checking
c906108c
SS
5867@subsection An overview of type checking
5868
5869Some languages, such as Modula-2, are strongly typed, meaning that the
5870arguments to operators and functions have to be of the correct type,
5871otherwise an error occurs. These checks prevent type mismatch
5872errors from ever causing any run-time problems. For example,
5873
5874@smallexample
58751 + 2 @result{} 3
5876@exdent but
5877@error{} 1 + 2.3
5878@end smallexample
5879
5880The second example fails because the @code{CARDINAL} 1 is not
5881type-compatible with the @code{REAL} 2.3.
5882
5d161b24
DB
5883For the expressions you use in @value{GDBN} commands, you can tell the
5884@value{GDBN} type checker to skip checking;
5885to treat any mismatches as errors and abandon the expression;
5886or to only issue warnings when type mismatches occur,
c906108c
SS
5887but evaluate the expression anyway. When you choose the last of
5888these, @value{GDBN} evaluates expressions like the second example above, but
5889also issues a warning.
5890
5d161b24
DB
5891Even if you turn type checking off, there may be other reasons
5892related to type that prevent @value{GDBN} from evaluating an expression.
5893For instance, @value{GDBN} does not know how to add an @code{int} and
5894a @code{struct foo}. These particular type errors have nothing to do
5895with the language in use, and usually arise from expressions, such as
c906108c
SS
5896the one described above, which make little sense to evaluate anyway.
5897
5898Each language defines to what degree it is strict about type. For
5899instance, both Modula-2 and C require the arguments to arithmetical
5900operators to be numbers. In C, enumerated types and pointers can be
5901represented as numbers, so that they are valid arguments to mathematical
5902operators. @xref{Support, ,Supported languages}, for further
5903details on specific languages.
5904
5905@value{GDBN} provides some additional commands for controlling the type checker:
5906
d4f3574e 5907@kindex set check@r{, type}
c906108c
SS
5908@kindex set check type
5909@kindex show check type
5910@table @code
5911@item set check type auto
5912Set type checking on or off based on the current working language.
5913@xref{Support, ,Supported languages}, for the default settings for
5914each language.
5915
5916@item set check type on
5917@itemx set check type off
5918Set type checking on or off, overriding the default setting for the
5919current working language. Issue a warning if the setting does not
5920match the language default. If any type mismatches occur in
d4f3574e 5921evaluating an expression while type checking is on, @value{GDBN} prints a
c906108c
SS
5922message and aborts evaluation of the expression.
5923
5924@item set check type warn
5925Cause the type checker to issue warnings, but to always attempt to
5926evaluate the expression. Evaluating the expression may still
5927be impossible for other reasons. For example, @value{GDBN} cannot add
5928numbers and structures.
5929
5930@item show type
5d161b24 5931Show the current setting of the type checker, and whether or not @value{GDBN}
c906108c
SS
5932is setting it automatically.
5933@end table
5934
5935@cindex range checking
5936@cindex checks, range
6d2ebf8b 5937@node Range Checking
c906108c
SS
5938@subsection An overview of range checking
5939
5940In some languages (such as Modula-2), it is an error to exceed the
5941bounds of a type; this is enforced with run-time checks. Such range
5942checking is meant to ensure program correctness by making sure
5943computations do not overflow, or indices on an array element access do
5944not exceed the bounds of the array.
5945
5946For expressions you use in @value{GDBN} commands, you can tell
5947@value{GDBN} to treat range errors in one of three ways: ignore them,
5948always treat them as errors and abandon the expression, or issue
5949warnings but evaluate the expression anyway.
5950
5951A range error can result from numerical overflow, from exceeding an
5952array index bound, or when you type a constant that is not a member
5953of any type. Some languages, however, do not treat overflows as an
5954error. In many implementations of C, mathematical overflow causes the
5955result to ``wrap around'' to lower values---for example, if @var{m} is
5956the largest integer value, and @var{s} is the smallest, then
5957
5958@example
5959@var{m} + 1 @result{} @var{s}
5960@end example
5961
5962This, too, is specific to individual languages, and in some cases
5963specific to individual compilers or machines. @xref{Support, ,
5964Supported languages}, for further details on specific languages.
5965
5966@value{GDBN} provides some additional commands for controlling the range checker:
5967
d4f3574e 5968@kindex set check@r{, range}
c906108c
SS
5969@kindex set check range
5970@kindex show check range
5971@table @code
5972@item set check range auto
5973Set range checking on or off based on the current working language.
5974@xref{Support, ,Supported languages}, for the default settings for
5975each language.
5976
5977@item set check range on
5978@itemx set check range off
5979Set range checking on or off, overriding the default setting for the
5980current working language. A warning is issued if the setting does not
c3f6f71d
JM
5981match the language default. If a range error occurs and range checking is on,
5982then a message is printed and evaluation of the expression is aborted.
c906108c
SS
5983
5984@item set check range warn
5985Output messages when the @value{GDBN} range checker detects a range error,
5986but attempt to evaluate the expression anyway. Evaluating the
5987expression may still be impossible for other reasons, such as accessing
5988memory that the process does not own (a typical example from many Unix
5989systems).
5990
5991@item show range
5992Show the current setting of the range checker, and whether or not it is
5993being set automatically by @value{GDBN}.
5994@end table
c906108c 5995
6d2ebf8b 5996@node Support
c906108c 5997@section Supported languages
c906108c 5998
cce74817
JM
5999@value{GDBN} supports C, C++, Fortran, Java, Chill, assembly, and Modula-2.
6000@c This is false ...
c906108c
SS
6001Some @value{GDBN} features may be used in expressions regardless of the
6002language you use: the @value{GDBN} @code{@@} and @code{::} operators,
6003and the @samp{@{type@}addr} construct (@pxref{Expressions,
6004,Expressions}) can be used with the constructs of any supported
6005language.
6006
6007The following sections detail to what degree each source language is
6008supported by @value{GDBN}. These sections are not meant to be language
6009tutorials or references, but serve only as a reference guide to what the
6010@value{GDBN} expression parser accepts, and what input and output
6011formats should look like for different languages. There are many good
6012books written on each of these languages; please look to these for a
6013language reference or tutorial.
6014
c906108c 6015@menu
7a292a7a 6016* C:: C and C++
cce74817 6017* Modula-2:: Modula-2
104c1213 6018* Chill:: Chill
c906108c
SS
6019@end menu
6020
6d2ebf8b 6021@node C
c906108c 6022@subsection C and C++
7a292a7a 6023
c906108c
SS
6024@cindex C and C++
6025@cindex expressions in C or C++
c906108c
SS
6026
6027Since C and C++ are so closely related, many features of @value{GDBN} apply
6028to both languages. Whenever this is the case, we discuss those languages
6029together.
6030
41afff9a
EZ
6031@cindex C@t{++}
6032@cindex @code{g++}, @sc{gnu} C@t{++} compiler
c906108c
SS
6033@cindex @sc{gnu} C++
6034The C++ debugging facilities are jointly implemented by the C++
6035compiler and @value{GDBN}. Therefore, to debug your C++ code
6036effectively, you must compile your C++ programs with a supported
6037C++ compiler, such as @sc{gnu} @code{g++}, or the HP ANSI C++
6038compiler (@code{aCC}).
6039
6040For best results when using @sc{gnu} C++, use the stabs debugging
6041format. You can select that format explicitly with the @code{g++}
6042command-line options @samp{-gstabs} or @samp{-gstabs+}. See
6043@ref{Debugging Options,,Options for Debugging Your Program or @sc{gnu}
6044CC, gcc.info, Using @sc{gnu} CC}, for more information.
c906108c 6045
c906108c
SS
6046@menu
6047* C Operators:: C and C++ operators
6048* C Constants:: C and C++ constants
7a292a7a 6049* C plus plus expressions:: C++ expressions
c906108c 6050* C Defaults:: Default settings for C and C++
c906108c 6051* C Checks:: C and C++ type and range checks
c906108c
SS
6052* Debugging C:: @value{GDBN} and C
6053* Debugging C plus plus:: @value{GDBN} features for C++
6054@end menu
c906108c 6055
6d2ebf8b 6056@node C Operators
c906108c 6057@subsubsection C and C++ operators
7a292a7a
SS
6058
6059@cindex C and C++ operators
c906108c
SS
6060
6061Operators must be defined on values of specific types. For instance,
6062@code{+} is defined on numbers, but not on structures. Operators are
5d161b24 6063often defined on groups of types.
c906108c 6064
c906108c 6065For the purposes of C and C++, the following definitions hold:
c906108c
SS
6066
6067@itemize @bullet
53a5351d 6068
c906108c 6069@item
c906108c
SS
6070@emph{Integral types} include @code{int} with any of its storage-class
6071specifiers; @code{char}; @code{enum}; and, for C++, @code{bool}.
c906108c
SS
6072
6073@item
d4f3574e
SS
6074@emph{Floating-point types} include @code{float}, @code{double}, and
6075@code{long double} (if supported by the target platform).
c906108c
SS
6076
6077@item
53a5351d 6078@emph{Pointer types} include all types defined as @code{(@var{type} *)}.
c906108c
SS
6079
6080@item
6081@emph{Scalar types} include all of the above.
53a5351d 6082
c906108c
SS
6083@end itemize
6084
6085@noindent
6086The following operators are supported. They are listed here
6087in order of increasing precedence:
6088
6089@table @code
6090@item ,
6091The comma or sequencing operator. Expressions in a comma-separated list
6092are evaluated from left to right, with the result of the entire
6093expression being the last expression evaluated.
6094
6095@item =
6096Assignment. The value of an assignment expression is the value
6097assigned. Defined on scalar types.
6098
6099@item @var{op}=
6100Used in an expression of the form @w{@code{@var{a} @var{op}= @var{b}}},
6101and translated to @w{@code{@var{a} = @var{a op b}}}.
d4f3574e 6102@w{@code{@var{op}=}} and @code{=} have the same precedence.
c906108c
SS
6103@var{op} is any one of the operators @code{|}, @code{^}, @code{&},
6104@code{<<}, @code{>>}, @code{+}, @code{-}, @code{*}, @code{/}, @code{%}.
6105
6106@item ?:
6107The ternary operator. @code{@var{a} ? @var{b} : @var{c}} can be thought
6108of as: if @var{a} then @var{b} else @var{c}. @var{a} should be of an
6109integral type.
6110
6111@item ||
6112Logical @sc{or}. Defined on integral types.
6113
6114@item &&
6115Logical @sc{and}. Defined on integral types.
6116
6117@item |
6118Bitwise @sc{or}. Defined on integral types.
6119
6120@item ^
6121Bitwise exclusive-@sc{or}. Defined on integral types.
6122
6123@item &
6124Bitwise @sc{and}. Defined on integral types.
6125
6126@item ==@r{, }!=
6127Equality and inequality. Defined on scalar types. The value of these
6128expressions is 0 for false and non-zero for true.
6129
6130@item <@r{, }>@r{, }<=@r{, }>=
6131Less than, greater than, less than or equal, greater than or equal.
6132Defined on scalar types. The value of these expressions is 0 for false
6133and non-zero for true.
6134
6135@item <<@r{, }>>
6136left shift, and right shift. Defined on integral types.
6137
6138@item @@
6139The @value{GDBN} ``artificial array'' operator (@pxref{Expressions, ,Expressions}).
6140
6141@item +@r{, }-
6142Addition and subtraction. Defined on integral types, floating-point types and
6143pointer types.
6144
6145@item *@r{, }/@r{, }%
6146Multiplication, division, and modulus. Multiplication and division are
6147defined on integral and floating-point types. Modulus is defined on
6148integral types.
6149
6150@item ++@r{, }--
6151Increment and decrement. When appearing before a variable, the
6152operation is performed before the variable is used in an expression;
6153when appearing after it, the variable's value is used before the
6154operation takes place.
6155
6156@item *
6157Pointer dereferencing. Defined on pointer types. Same precedence as
6158@code{++}.
6159
6160@item &
6161Address operator. Defined on variables. Same precedence as @code{++}.
6162
c906108c
SS
6163For debugging C++, @value{GDBN} implements a use of @samp{&} beyond what is
6164allowed in the C++ language itself: you can use @samp{&(&@var{ref})}
6165(or, if you prefer, simply @samp{&&@var{ref}}) to examine the address
6166where a C++ reference variable (declared with @samp{&@var{ref}}) is
6167stored.
c906108c
SS
6168
6169@item -
6170Negative. Defined on integral and floating-point types. Same
6171precedence as @code{++}.
6172
6173@item !
6174Logical negation. Defined on integral types. Same precedence as
6175@code{++}.
6176
6177@item ~
6178Bitwise complement operator. Defined on integral types. Same precedence as
6179@code{++}.
6180
6181
6182@item .@r{, }->
6183Structure member, and pointer-to-structure member. For convenience,
6184@value{GDBN} regards the two as equivalent, choosing whether to dereference a
6185pointer based on the stored type information.
6186Defined on @code{struct} and @code{union} data.
6187
c906108c
SS
6188@item .*@r{, }->*
6189Dereferences of pointers to members.
c906108c
SS
6190
6191@item []
6192Array indexing. @code{@var{a}[@var{i}]} is defined as
6193@code{*(@var{a}+@var{i})}. Same precedence as @code{->}.
6194
6195@item ()
6196Function parameter list. Same precedence as @code{->}.
6197
c906108c 6198@item ::
7a292a7a
SS
6199C++ scope resolution operator. Defined on @code{struct}, @code{union},
6200and @code{class} types.
c906108c
SS
6201
6202@item ::
7a292a7a
SS
6203Doubled colons also represent the @value{GDBN} scope operator
6204(@pxref{Expressions, ,Expressions}). Same precedence as @code{::},
6205above.
c906108c
SS
6206@end table
6207
c906108c
SS
6208If an operator is redefined in the user code, @value{GDBN} usually
6209attempts to invoke the redefined version instead of using the operator's
6210predefined meaning.
c906108c 6211
c906108c 6212@menu
5d161b24 6213* C Constants::
c906108c
SS
6214@end menu
6215
6d2ebf8b 6216@node C Constants
c906108c 6217@subsubsection C and C++ constants
c906108c
SS
6218
6219@cindex C and C++ constants
c906108c 6220
7a292a7a 6221@value{GDBN} allows you to express the constants of C and C++ in the
c906108c 6222following ways:
c906108c
SS
6223
6224@itemize @bullet
6225@item
6226Integer constants are a sequence of digits. Octal constants are
6227specified by a leading @samp{0} (i.e. zero), and hexadecimal constants by
6228a leading @samp{0x} or @samp{0X}. Constants may also end with a letter
6229@samp{l}, specifying that the constant should be treated as a
6230@code{long} value.
6231
6232@item
6233Floating point constants are a sequence of digits, followed by a decimal
6234point, followed by a sequence of digits, and optionally followed by an
6235exponent. An exponent is of the form:
6236@samp{@w{e@r{[[}+@r{]|}-@r{]}@var{nnn}}}, where @var{nnn} is another
6237sequence of digits. The @samp{+} is optional for positive exponents.
d4f3574e
SS
6238A floating-point constant may also end with a letter @samp{f} or
6239@samp{F}, specifying that the constant should be treated as being of
6240the @code{float} (as opposed to the default @code{double}) type; or with
6241a letter @samp{l} or @samp{L}, which specifies a @code{long double}
6242constant.
c906108c
SS
6243
6244@item
6245Enumerated constants consist of enumerated identifiers, or their
6246integral equivalents.
6247
6248@item
6249Character constants are a single character surrounded by single quotes
6250(@code{'}), or a number---the ordinal value of the corresponding character
d4f3574e 6251(usually its @sc{ascii} value). Within quotes, the single character may
c906108c
SS
6252be represented by a letter or by @dfn{escape sequences}, which are of
6253the form @samp{\@var{nnn}}, where @var{nnn} is the octal representation
6254of the character's ordinal value; or of the form @samp{\@var{x}}, where
6255@samp{@var{x}} is a predefined special character---for example,
6256@samp{\n} for newline.
6257
6258@item
96a2c332
SS
6259String constants are a sequence of character constants surrounded by
6260double quotes (@code{"}). Any valid character constant (as described
6261above) may appear. Double quotes within the string must be preceded by
6262a backslash, so for instance @samp{"a\"b'c"} is a string of five
6263characters.
c906108c
SS
6264
6265@item
6266Pointer constants are an integral value. You can also write pointers
6267to constants using the C operator @samp{&}.
6268
6269@item
6270Array constants are comma-separated lists surrounded by braces @samp{@{}
6271and @samp{@}}; for example, @samp{@{1,2,3@}} is a three-element array of
6272integers, @samp{@{@{1,2@}, @{3,4@}, @{5,6@}@}} is a three-by-two array,
6273and @samp{@{&"hi", &"there", &"fred"@}} is a three-element array of pointers.
6274@end itemize
6275
c906108c 6276@menu
5d161b24
DB
6277* C plus plus expressions::
6278* C Defaults::
6279* C Checks::
c906108c 6280
5d161b24 6281* Debugging C::
c906108c
SS
6282@end menu
6283
6d2ebf8b 6284@node C plus plus expressions
c906108c 6285@subsubsection C++ expressions
c906108c
SS
6286
6287@cindex expressions in C++
6288@value{GDBN} expression handling can interpret most C++ expressions.
6289
c906108c
SS
6290@cindex C++ support, not in @sc{coff}
6291@cindex @sc{coff} versus C++
6292@cindex C++ and object formats
6293@cindex object formats and C++
6294@cindex a.out and C++
6295@cindex @sc{ecoff} and C++
6296@cindex @sc{xcoff} and C++
6297@cindex @sc{elf}/stabs and C++
6298@cindex @sc{elf}/@sc{dwarf} and C++
6299@c FIXME!! GDB may eventually be able to debug C++ using DWARF; check
6300@c periodically whether this has happened...
6301@quotation
6302@emph{Warning:} @value{GDBN} can only debug C++ code if you use the
6303proper compiler. Typically, C++ debugging depends on the use of
6304additional debugging information in the symbol table, and thus requires
6305special support. In particular, if your compiler generates a.out, MIPS
6306@sc{ecoff}, RS/6000 @sc{xcoff}, or @sc{elf} with stabs extensions to the
6307symbol table, these facilities are all available. (With @sc{gnu} CC,
6308you can use the @samp{-gstabs} option to request stabs debugging
6309extensions explicitly.) Where the object code format is standard
6310@sc{coff} or @sc{dwarf} in @sc{elf}, on the other hand, most of the C++
6311support in @value{GDBN} does @emph{not} work.
6312@end quotation
c906108c
SS
6313
6314@enumerate
6315
6316@cindex member functions
6317@item
6318Member function calls are allowed; you can use expressions like
6319
6320@example
6321count = aml->GetOriginal(x, y)
6322@end example
6323
41afff9a 6324@vindex this@r{, inside C@t{++} member functions}
c906108c
SS
6325@cindex namespace in C++
6326@item
6327While a member function is active (in the selected stack frame), your
6328expressions have the same namespace available as the member function;
6329that is, @value{GDBN} allows implicit references to the class instance
6330pointer @code{this} following the same rules as C++.
6331
c906108c 6332@cindex call overloaded functions
d4f3574e 6333@cindex overloaded functions, calling
c906108c
SS
6334@cindex type conversions in C++
6335@item
6336You can call overloaded functions; @value{GDBN} resolves the function
d4f3574e 6337call to the right definition, with some restrictions. @value{GDBN} does not
c906108c
SS
6338perform overload resolution involving user-defined type conversions,
6339calls to constructors, or instantiations of templates that do not exist
6340in the program. It also cannot handle ellipsis argument lists or
6341default arguments.
6342
6343It does perform integral conversions and promotions, floating-point
6344promotions, arithmetic conversions, pointer conversions, conversions of
6345class objects to base classes, and standard conversions such as those of
6346functions or arrays to pointers; it requires an exact match on the
6347number of function arguments.
6348
6349Overload resolution is always performed, unless you have specified
6350@code{set overload-resolution off}. @xref{Debugging C plus plus,
6351,@value{GDBN} features for C++}.
6352
d4f3574e 6353You must specify @code{set overload-resolution off} in order to use an
c906108c
SS
6354explicit function signature to call an overloaded function, as in
6355@smallexample
6356p 'foo(char,int)'('x', 13)
6357@end smallexample
d4f3574e 6358
c906108c 6359The @value{GDBN} command-completion facility can simplify this;
d4f3574e 6360see @ref{Completion, ,Command completion}.
c906108c 6361
c906108c
SS
6362@cindex reference declarations
6363@item
5d161b24 6364@value{GDBN} understands variables declared as C++ references; you can use
c906108c
SS
6365them in expressions just as you do in C++ source---they are automatically
6366dereferenced.
6367
6368In the parameter list shown when @value{GDBN} displays a frame, the values of
6369reference variables are not displayed (unlike other variables); this
6370avoids clutter, since references are often used for large structures.
6371The @emph{address} of a reference variable is always shown, unless
6372you have specified @samp{set print address off}.
6373
6374@item
6375@value{GDBN} supports the C++ name resolution operator @code{::}---your
6376expressions can use it just as expressions in your program do. Since
6377one scope may be defined in another, you can use @code{::} repeatedly if
6378necessary, for example in an expression like
6379@samp{@var{scope1}::@var{scope2}::@var{name}}. @value{GDBN} also allows
6380resolving name scope by reference to source files, in both C and C++
6381debugging (@pxref{Variables, ,Program variables}).
6382@end enumerate
6383
53a5351d
JM
6384In addition, when used with HP's C++ compiler, @value{GDBN} supports
6385calling virtual functions correctly, printing out virtual bases of
6386objects, calling functions in a base subobject, casting objects, and
6387invoking user-defined operators.
c906108c 6388
6d2ebf8b 6389@node C Defaults
c906108c 6390@subsubsection C and C++ defaults
7a292a7a 6391
c906108c
SS
6392@cindex C and C++ defaults
6393
c906108c
SS
6394If you allow @value{GDBN} to set type and range checking automatically, they
6395both default to @code{off} whenever the working language changes to
6396C or C++. This happens regardless of whether you or @value{GDBN}
6397selects the working language.
c906108c
SS
6398
6399If you allow @value{GDBN} to set the language automatically, it
6400recognizes source files whose names end with @file{.c}, @file{.C}, or
6401@file{.cc}, etc, and when @value{GDBN} enters code compiled from one of
6402these files, it sets the working language to C or C++.
6403@xref{Automatically, ,Having @value{GDBN} infer the source language},
6404for further details.
6405
c906108c
SS
6406@c Type checking is (a) primarily motivated by Modula-2, and (b)
6407@c unimplemented. If (b) changes, it might make sense to let this node
6408@c appear even if Mod-2 does not, but meanwhile ignore it. roland 16jul93.
7a292a7a 6409
6d2ebf8b 6410@node C Checks
c906108c 6411@subsubsection C and C++ type and range checks
7a292a7a 6412
c906108c
SS
6413@cindex C and C++ checks
6414
6415By default, when @value{GDBN} parses C or C++ expressions, type checking
6416is not used. However, if you turn type checking on, @value{GDBN}
6417considers two variables type equivalent if:
6418
6419@itemize @bullet
6420@item
6421The two variables are structured and have the same structure, union, or
6422enumerated tag.
6423
6424@item
6425The two variables have the same type name, or types that have been
6426declared equivalent through @code{typedef}.
6427
6428@ignore
6429@c leaving this out because neither J Gilmore nor R Pesch understand it.
6430@c FIXME--beers?
6431@item
6432The two @code{struct}, @code{union}, or @code{enum} variables are
6433declared in the same declaration. (Note: this may not be true for all C
6434compilers.)
6435@end ignore
6436@end itemize
6437
6438Range checking, if turned on, is done on mathematical operations. Array
6439indices are not checked, since they are often used to index a pointer
6440that is not itself an array.
c906108c 6441
6d2ebf8b 6442@node Debugging C
c906108c 6443@subsubsection @value{GDBN} and C
c906108c
SS
6444
6445The @code{set print union} and @code{show print union} commands apply to
6446the @code{union} type. When set to @samp{on}, any @code{union} that is
7a292a7a
SS
6447inside a @code{struct} or @code{class} is also printed. Otherwise, it
6448appears as @samp{@{...@}}.
c906108c
SS
6449
6450The @code{@@} operator aids in the debugging of dynamic arrays, formed
6451with pointers and a memory allocation function. @xref{Expressions,
6452,Expressions}.
6453
c906108c 6454@menu
5d161b24 6455* Debugging C plus plus::
c906108c
SS
6456@end menu
6457
6d2ebf8b 6458@node Debugging C plus plus
c906108c 6459@subsubsection @value{GDBN} features for C++
c906108c
SS
6460
6461@cindex commands for C++
7a292a7a 6462
c906108c
SS
6463Some @value{GDBN} commands are particularly useful with C++, and some are
6464designed specifically for use with C++. Here is a summary:
6465
6466@table @code
6467@cindex break in overloaded functions
6468@item @r{breakpoint menus}
6469When you want a breakpoint in a function whose name is overloaded,
6470@value{GDBN} breakpoint menus help you specify which function definition
6471you want. @xref{Breakpoint Menus,,Breakpoint menus}.
6472
6473@cindex overloading in C++
6474@item rbreak @var{regex}
6475Setting breakpoints using regular expressions is helpful for setting
6476breakpoints on overloaded functions that are not members of any special
6477classes.
6478@xref{Set Breaks, ,Setting breakpoints}.
6479
6480@cindex C++ exception handling
6481@item catch throw
6482@itemx catch catch
6483Debug C++ exception handling using these commands. @xref{Set
6484Catchpoints, , Setting catchpoints}.
6485
6486@cindex inheritance
6487@item ptype @var{typename}
6488Print inheritance relationships as well as other information for type
6489@var{typename}.
6490@xref{Symbols, ,Examining the Symbol Table}.
6491
6492@cindex C++ symbol display
6493@item set print demangle
6494@itemx show print demangle
6495@itemx set print asm-demangle
6496@itemx show print asm-demangle
6497Control whether C++ symbols display in their source form, both when
6498displaying code as C++ source and when displaying disassemblies.
6499@xref{Print Settings, ,Print settings}.
6500
6501@item set print object
6502@itemx show print object
6503Choose whether to print derived (actual) or declared types of objects.
6504@xref{Print Settings, ,Print settings}.
6505
6506@item set print vtbl
6507@itemx show print vtbl
6508Control the format for printing virtual function tables.
6509@xref{Print Settings, ,Print settings}.
c906108c
SS
6510(The @code{vtbl} commands do not work on programs compiled with the HP
6511ANSI C++ compiler (@code{aCC}).)
6512
6513@kindex set overload-resolution
d4f3574e 6514@cindex overloaded functions, overload resolution
c906108c
SS
6515@item set overload-resolution on
6516Enable overload resolution for C++ expression evaluation. The default
6517is on. For overloaded functions, @value{GDBN} evaluates the arguments
6518and searches for a function whose signature matches the argument types,
d4f3574e
SS
6519using the standard C++ conversion rules (see @ref{C plus plus expressions, ,C++
6520expressions}, for details). If it cannot find a match, it emits a
c906108c
SS
6521message.
6522
6523@item set overload-resolution off
6524Disable overload resolution for C++ expression evaluation. For
6525overloaded functions that are not class member functions, @value{GDBN}
6526chooses the first function of the specified name that it finds in the
6527symbol table, whether or not its arguments are of the correct type. For
6528overloaded functions that are class member functions, @value{GDBN}
6529searches for a function whose signature @emph{exactly} matches the
6530argument types.
c906108c
SS
6531
6532@item @r{Overloaded symbol names}
6533You can specify a particular definition of an overloaded symbol, using
6534the same notation that is used to declare such symbols in C++: type
6535@code{@var{symbol}(@var{types})} rather than just @var{symbol}. You can
6536also use the @value{GDBN} command-line word completion facilities to list the
6537available choices, or to finish the type list for you.
6538@xref{Completion,, Command completion}, for details on how to do this.
6539@end table
c906108c 6540
6d2ebf8b 6541@node Modula-2
c906108c 6542@subsection Modula-2
7a292a7a 6543
d4f3574e 6544@cindex Modula-2, @value{GDBN} support
c906108c
SS
6545
6546The extensions made to @value{GDBN} to support Modula-2 only support
6547output from the @sc{gnu} Modula-2 compiler (which is currently being
6548developed). Other Modula-2 compilers are not currently supported, and
6549attempting to debug executables produced by them is most likely
6550to give an error as @value{GDBN} reads in the executable's symbol
6551table.
6552
6553@cindex expressions in Modula-2
6554@menu
6555* M2 Operators:: Built-in operators
6556* Built-In Func/Proc:: Built-in functions and procedures
6557* M2 Constants:: Modula-2 constants
6558* M2 Defaults:: Default settings for Modula-2
6559* Deviations:: Deviations from standard Modula-2
6560* M2 Checks:: Modula-2 type and range checks
6561* M2 Scope:: The scope operators @code{::} and @code{.}
6562* GDB/M2:: @value{GDBN} and Modula-2
6563@end menu
6564
6d2ebf8b 6565@node M2 Operators
c906108c
SS
6566@subsubsection Operators
6567@cindex Modula-2 operators
6568
6569Operators must be defined on values of specific types. For instance,
6570@code{+} is defined on numbers, but not on structures. Operators are
6571often defined on groups of types. For the purposes of Modula-2, the
6572following definitions hold:
6573
6574@itemize @bullet
6575
6576@item
6577@emph{Integral types} consist of @code{INTEGER}, @code{CARDINAL}, and
6578their subranges.
6579
6580@item
6581@emph{Character types} consist of @code{CHAR} and its subranges.
6582
6583@item
6584@emph{Floating-point types} consist of @code{REAL}.
6585
6586@item
6587@emph{Pointer types} consist of anything declared as @code{POINTER TO
6588@var{type}}.
6589
6590@item
6591@emph{Scalar types} consist of all of the above.
6592
6593@item
6594@emph{Set types} consist of @code{SET} and @code{BITSET} types.
6595
6596@item
6597@emph{Boolean types} consist of @code{BOOLEAN}.
6598@end itemize
6599
6600@noindent
6601The following operators are supported, and appear in order of
6602increasing precedence:
6603
6604@table @code
6605@item ,
6606Function argument or array index separator.
6607
6608@item :=
6609Assignment. The value of @var{var} @code{:=} @var{value} is
6610@var{value}.
6611
6612@item <@r{, }>
6613Less than, greater than on integral, floating-point, or enumerated
6614types.
6615
6616@item <=@r{, }>=
96a2c332 6617Less than or equal to, greater than or equal to
c906108c
SS
6618on integral, floating-point and enumerated types, or set inclusion on
6619set types. Same precedence as @code{<}.
6620
6621@item =@r{, }<>@r{, }#
6622Equality and two ways of expressing inequality, valid on scalar types.
6623Same precedence as @code{<}. In @value{GDBN} scripts, only @code{<>} is
6624available for inequality, since @code{#} conflicts with the script
6625comment character.
6626
6627@item IN
6628Set membership. Defined on set types and the types of their members.
6629Same precedence as @code{<}.
6630
6631@item OR
6632Boolean disjunction. Defined on boolean types.
6633
6634@item AND@r{, }&
d4f3574e 6635Boolean conjunction. Defined on boolean types.
c906108c
SS
6636
6637@item @@
6638The @value{GDBN} ``artificial array'' operator (@pxref{Expressions, ,Expressions}).
6639
6640@item +@r{, }-
6641Addition and subtraction on integral and floating-point types, or union
6642and difference on set types.
6643
6644@item *
6645Multiplication on integral and floating-point types, or set intersection
6646on set types.
6647
6648@item /
6649Division on floating-point types, or symmetric set difference on set
6650types. Same precedence as @code{*}.
6651
6652@item DIV@r{, }MOD
6653Integer division and remainder. Defined on integral types. Same
6654precedence as @code{*}.
6655
6656@item -
6657Negative. Defined on @code{INTEGER} and @code{REAL} data.
6658
6659@item ^
6660Pointer dereferencing. Defined on pointer types.
6661
6662@item NOT
6663Boolean negation. Defined on boolean types. Same precedence as
6664@code{^}.
6665
6666@item .
6667@code{RECORD} field selector. Defined on @code{RECORD} data. Same
6668precedence as @code{^}.
6669
6670@item []
6671Array indexing. Defined on @code{ARRAY} data. Same precedence as @code{^}.
6672
6673@item ()
6674Procedure argument list. Defined on @code{PROCEDURE} objects. Same precedence
6675as @code{^}.
6676
6677@item ::@r{, }.
6678@value{GDBN} and Modula-2 scope operators.
6679@end table
6680
6681@quotation
6682@emph{Warning:} Sets and their operations are not yet supported, so @value{GDBN}
6683treats the use of the operator @code{IN}, or the use of operators
6684@code{+}, @code{-}, @code{*}, @code{/}, @code{=}, , @code{<>}, @code{#},
6685@code{<=}, and @code{>=} on sets as an error.
6686@end quotation
6687
6688@cindex Modula-2 built-ins
6d2ebf8b 6689@node Built-In Func/Proc
c906108c
SS
6690@subsubsection Built-in functions and procedures
6691
6692Modula-2 also makes available several built-in procedures and functions.
6693In describing these, the following metavariables are used:
6694
6695@table @var
6696
6697@item a
6698represents an @code{ARRAY} variable.
6699
6700@item c
6701represents a @code{CHAR} constant or variable.
6702
6703@item i
6704represents a variable or constant of integral type.
6705
6706@item m
6707represents an identifier that belongs to a set. Generally used in the
6708same function with the metavariable @var{s}. The type of @var{s} should
6709be @code{SET OF @var{mtype}} (where @var{mtype} is the type of @var{m}).
6710
6711@item n
6712represents a variable or constant of integral or floating-point type.
6713
6714@item r
6715represents a variable or constant of floating-point type.
6716
6717@item t
6718represents a type.
6719
6720@item v
6721represents a variable.
6722
6723@item x
6724represents a variable or constant of one of many types. See the
6725explanation of the function for details.
6726@end table
6727
6728All Modula-2 built-in procedures also return a result, described below.
6729
6730@table @code
6731@item ABS(@var{n})
6732Returns the absolute value of @var{n}.
6733
6734@item CAP(@var{c})
6735If @var{c} is a lower case letter, it returns its upper case
c3f6f71d 6736equivalent, otherwise it returns its argument.
c906108c
SS
6737
6738@item CHR(@var{i})
6739Returns the character whose ordinal value is @var{i}.
6740
6741@item DEC(@var{v})
c3f6f71d 6742Decrements the value in the variable @var{v} by one. Returns the new value.
c906108c
SS
6743
6744@item DEC(@var{v},@var{i})
6745Decrements the value in the variable @var{v} by @var{i}. Returns the
6746new value.
6747
6748@item EXCL(@var{m},@var{s})
6749Removes the element @var{m} from the set @var{s}. Returns the new
6750set.
6751
6752@item FLOAT(@var{i})
6753Returns the floating point equivalent of the integer @var{i}.
6754
6755@item HIGH(@var{a})
6756Returns the index of the last member of @var{a}.
6757
6758@item INC(@var{v})
c3f6f71d 6759Increments the value in the variable @var{v} by one. Returns the new value.
c906108c
SS
6760
6761@item INC(@var{v},@var{i})
6762Increments the value in the variable @var{v} by @var{i}. Returns the
6763new value.
6764
6765@item INCL(@var{m},@var{s})
6766Adds the element @var{m} to the set @var{s} if it is not already
6767there. Returns the new set.
6768
6769@item MAX(@var{t})
6770Returns the maximum value of the type @var{t}.
6771
6772@item MIN(@var{t})
6773Returns the minimum value of the type @var{t}.
6774
6775@item ODD(@var{i})
6776Returns boolean TRUE if @var{i} is an odd number.
6777
6778@item ORD(@var{x})
6779Returns the ordinal value of its argument. For example, the ordinal
c3f6f71d
JM
6780value of a character is its @sc{ascii} value (on machines supporting the
6781@sc{ascii} character set). @var{x} must be of an ordered type, which include
c906108c
SS
6782integral, character and enumerated types.
6783
6784@item SIZE(@var{x})
6785Returns the size of its argument. @var{x} can be a variable or a type.
6786
6787@item TRUNC(@var{r})
6788Returns the integral part of @var{r}.
6789
6790@item VAL(@var{t},@var{i})
6791Returns the member of the type @var{t} whose ordinal value is @var{i}.
6792@end table
6793
6794@quotation
6795@emph{Warning:} Sets and their operations are not yet supported, so
6796@value{GDBN} treats the use of procedures @code{INCL} and @code{EXCL} as
6797an error.
6798@end quotation
6799
6800@cindex Modula-2 constants
6d2ebf8b 6801@node M2 Constants
c906108c
SS
6802@subsubsection Constants
6803
6804@value{GDBN} allows you to express the constants of Modula-2 in the following
6805ways:
6806
6807@itemize @bullet
6808
6809@item
6810Integer constants are simply a sequence of digits. When used in an
6811expression, a constant is interpreted to be type-compatible with the
6812rest of the expression. Hexadecimal integers are specified by a
6813trailing @samp{H}, and octal integers by a trailing @samp{B}.
6814
6815@item
6816Floating point constants appear as a sequence of digits, followed by a
6817decimal point and another sequence of digits. An optional exponent can
6818then be specified, in the form @samp{E@r{[}+@r{|}-@r{]}@var{nnn}}, where
6819@samp{@r{[}+@r{|}-@r{]}@var{nnn}} is the desired exponent. All of the
6820digits of the floating point constant must be valid decimal (base 10)
6821digits.
6822
6823@item
6824Character constants consist of a single character enclosed by a pair of
6825like quotes, either single (@code{'}) or double (@code{"}). They may
c3f6f71d 6826also be expressed by their ordinal value (their @sc{ascii} value, usually)
c906108c
SS
6827followed by a @samp{C}.
6828
6829@item
6830String constants consist of a sequence of characters enclosed by a
6831pair of like quotes, either single (@code{'}) or double (@code{"}).
6832Escape sequences in the style of C are also allowed. @xref{C
6833Constants, ,C and C++ constants}, for a brief explanation of escape
6834sequences.
6835
6836@item
6837Enumerated constants consist of an enumerated identifier.
6838
6839@item
6840Boolean constants consist of the identifiers @code{TRUE} and
6841@code{FALSE}.
6842
6843@item
6844Pointer constants consist of integral values only.
6845
6846@item
6847Set constants are not yet supported.
6848@end itemize
6849
6d2ebf8b 6850@node M2 Defaults
c906108c
SS
6851@subsubsection Modula-2 defaults
6852@cindex Modula-2 defaults
6853
6854If type and range checking are set automatically by @value{GDBN}, they
6855both default to @code{on} whenever the working language changes to
d4f3574e 6856Modula-2. This happens regardless of whether you or @value{GDBN}
c906108c
SS
6857selected the working language.
6858
6859If you allow @value{GDBN} to set the language automatically, then entering
6860code compiled from a file whose name ends with @file{.mod} sets the
d4f3574e 6861working language to Modula-2. @xref{Automatically, ,Having @value{GDBN} set
c906108c
SS
6862the language automatically}, for further details.
6863
6d2ebf8b 6864@node Deviations
c906108c
SS
6865@subsubsection Deviations from standard Modula-2
6866@cindex Modula-2, deviations from
6867
6868A few changes have been made to make Modula-2 programs easier to debug.
6869This is done primarily via loosening its type strictness:
6870
6871@itemize @bullet
6872@item
6873Unlike in standard Modula-2, pointer constants can be formed by
6874integers. This allows you to modify pointer variables during
6875debugging. (In standard Modula-2, the actual address contained in a
6876pointer variable is hidden from you; it can only be modified
6877through direct assignment to another pointer variable or expression that
6878returned a pointer.)
6879
6880@item
6881C escape sequences can be used in strings and characters to represent
6882non-printable characters. @value{GDBN} prints out strings with these
6883escape sequences embedded. Single non-printable characters are
6884printed using the @samp{CHR(@var{nnn})} format.
6885
6886@item
6887The assignment operator (@code{:=}) returns the value of its right-hand
6888argument.
6889
6890@item
6891All built-in procedures both modify @emph{and} return their argument.
6892@end itemize
6893
6d2ebf8b 6894@node M2 Checks
c906108c
SS
6895@subsubsection Modula-2 type and range checks
6896@cindex Modula-2 checks
6897
6898@quotation
6899@emph{Warning:} in this release, @value{GDBN} does not yet perform type or
6900range checking.
6901@end quotation
6902@c FIXME remove warning when type/range checks added
6903
6904@value{GDBN} considers two Modula-2 variables type equivalent if:
6905
6906@itemize @bullet
6907@item
6908They are of types that have been declared equivalent via a @code{TYPE
6909@var{t1} = @var{t2}} statement
6910
6911@item
6912They have been declared on the same line. (Note: This is true of the
6913@sc{gnu} Modula-2 compiler, but it may not be true of other compilers.)
6914@end itemize
6915
6916As long as type checking is enabled, any attempt to combine variables
6917whose types are not equivalent is an error.
6918
6919Range checking is done on all mathematical operations, assignment, array
6920index bounds, and all built-in functions and procedures.
6921
6d2ebf8b 6922@node M2 Scope
c906108c
SS
6923@subsubsection The scope operators @code{::} and @code{.}
6924@cindex scope
41afff9a 6925@cindex @code{.}, Modula-2 scope operator
c906108c
SS
6926@cindex colon, doubled as scope operator
6927@ifinfo
41afff9a 6928@vindex colon-colon@r{, in Modula-2}
c906108c
SS
6929@c Info cannot handle :: but TeX can.
6930@end ifinfo
6931@iftex
41afff9a 6932@vindex ::@r{, in Modula-2}
c906108c
SS
6933@end iftex
6934
6935There are a few subtle differences between the Modula-2 scope operator
6936(@code{.}) and the @value{GDBN} scope operator (@code{::}). The two have
6937similar syntax:
6938
6939@example
6940
6941@var{module} . @var{id}
6942@var{scope} :: @var{id}
6943@end example
6944
6945@noindent
6946where @var{scope} is the name of a module or a procedure,
6947@var{module} the name of a module, and @var{id} is any declared
6948identifier within your program, except another module.
6949
6950Using the @code{::} operator makes @value{GDBN} search the scope
6951specified by @var{scope} for the identifier @var{id}. If it is not
6952found in the specified scope, then @value{GDBN} searches all scopes
6953enclosing the one specified by @var{scope}.
6954
6955Using the @code{.} operator makes @value{GDBN} search the current scope for
6956the identifier specified by @var{id} that was imported from the
6957definition module specified by @var{module}. With this operator, it is
6958an error if the identifier @var{id} was not imported from definition
6959module @var{module}, or if @var{id} is not an identifier in
6960@var{module}.
6961
6d2ebf8b 6962@node GDB/M2
c906108c
SS
6963@subsubsection @value{GDBN} and Modula-2
6964
6965Some @value{GDBN} commands have little use when debugging Modula-2 programs.
6966Five subcommands of @code{set print} and @code{show print} apply
6967specifically to C and C++: @samp{vtbl}, @samp{demangle},
6968@samp{asm-demangle}, @samp{object}, and @samp{union}. The first four
6969apply to C++, and the last to the C @code{union} type, which has no direct
6970analogue in Modula-2.
6971
6972The @code{@@} operator (@pxref{Expressions, ,Expressions}), while available
d4f3574e 6973with any language, is not useful with Modula-2. Its
c906108c
SS
6974intent is to aid the debugging of @dfn{dynamic arrays}, which cannot be
6975created in Modula-2 as they can in C or C++. However, because an
6976address can be specified by an integral constant, the construct
d4f3574e 6977@samp{@{@var{type}@}@var{adrexp}} is still useful.
c906108c
SS
6978
6979@cindex @code{#} in Modula-2
6980In @value{GDBN} scripts, the Modula-2 inequality operator @code{#} is
6981interpreted as the beginning of a comment. Use @code{<>} instead.
c906108c 6982
6d2ebf8b 6983@node Chill
cce74817
JM
6984@subsection Chill
6985
6986The extensions made to @value{GDBN} to support Chill only support output
d4f3574e 6987from the @sc{gnu} Chill compiler. Other Chill compilers are not currently
cce74817
JM
6988supported, and attempting to debug executables produced by them is most
6989likely to give an error as @value{GDBN} reads in the executable's symbol
6990table.
6991
d4f3574e
SS
6992@c This used to say "... following Chill related topics ...", but since
6993@c menus are not shown in the printed manual, it would look awkward.
6994This section covers the Chill related topics and the features
cce74817
JM
6995of @value{GDBN} which support these topics.
6996
6997@menu
104c1213
JM
6998* How modes are displayed:: How modes are displayed
6999* Locations:: Locations and their accesses
cce74817 7000* Values and their Operations:: Values and their Operations
5d161b24 7001* Chill type and range checks::
53a5351d 7002* Chill defaults::
cce74817
JM
7003@end menu
7004
6d2ebf8b 7005@node How modes are displayed
cce74817
JM
7006@subsubsection How modes are displayed
7007
7008The Chill Datatype- (Mode) support of @value{GDBN} is directly related
d4f3574e 7009with the functionality of the @sc{gnu} Chill compiler, and therefore deviates
cce74817
JM
7010slightly from the standard specification of the Chill language. The
7011provided modes are:
d4f3574e
SS
7012
7013@c FIXME: this @table's contents effectively disable @code by using @r
7014@c on every @item. So why does it need @code?
cce74817
JM
7015@table @code
7016@item @r{@emph{Discrete modes:}}
7017@itemize @bullet
7018@item
7019@emph{Integer Modes} which are predefined by @code{BYTE, UBYTE, INT,
7020UINT, LONG, ULONG},
7021@item
5d161b24 7022@emph{Boolean Mode} which is predefined by @code{BOOL},
cce74817 7023@item
5d161b24 7024@emph{Character Mode} which is predefined by @code{CHAR},
cce74817
JM
7025@item
7026@emph{Set Mode} which is displayed by the keyword @code{SET}.
7027@smallexample
7028(@value{GDBP}) ptype x
7029type = SET (karli = 10, susi = 20, fritzi = 100)
7030@end smallexample
7031If the type is an unnumbered set the set element values are omitted.
7032@item
6d2ebf8b
SS
7033@emph{Range Mode} which is displayed by
7034@smallexample
7035@code{type = <basemode>(<lower bound> : <upper bound>)}
7036@end smallexample
7037where @code{<lower bound>, <upper bound>} can be of any discrete literal
7038expression (e.g. set element names).
cce74817
JM
7039@end itemize
7040
7041@item @r{@emph{Powerset Mode:}}
7042A Powerset Mode is displayed by the keyword @code{POWERSET} followed by
d4f3574e 7043the member mode of the powerset. The member mode can be any discrete mode.
cce74817
JM
7044@smallexample
7045(@value{GDBP}) ptype x
7046type = POWERSET SET (egon, hugo, otto)
7047@end smallexample
7048
7049@item @r{@emph{Reference Modes:}}
7050@itemize @bullet
7051@item
d4f3574e 7052@emph{Bound Reference Mode} which is displayed by the keyword @code{REF}
cce74817
JM
7053followed by the mode name to which the reference is bound.
7054@item
7055@emph{Free Reference Mode} which is displayed by the keyword @code{PTR}.
7056@end itemize
7057
7058@item @r{@emph{Procedure mode}}
7059The procedure mode is displayed by @code{type = PROC(<parameter list>)
7060<return mode> EXCEPTIONS (<exception list>)}. The @code{<parameter
d4f3574e
SS
7061list>} is a list of the parameter modes. @code{<return mode>} indicates
7062the mode of the result of the procedure if any. The exceptionlist lists
cce74817
JM
7063all possible exceptions which can be raised by the procedure.
7064
7065@ignore
7066@item @r{@emph{Instance mode}}
7067The instance mode is represented by a structure, which has a static
5d161b24 7068type, and is therefore not really of interest.
cce74817
JM
7069@end ignore
7070
5d161b24 7071@item @r{@emph{Synchronization Modes:}}
cce74817
JM
7072@itemize @bullet
7073@item
6d2ebf8b
SS
7074@emph{Event Mode} which is displayed by
7075@smallexample
7076@code{EVENT (<event length>)}
7077@end smallexample
cce74817
JM
7078where @code{(<event length>)} is optional.
7079@item
6d2ebf8b
SS
7080@emph{Buffer Mode} which is displayed by
7081@smallexample
7082@code{BUFFER (<buffer length>)<buffer element mode>}
7083@end smallexample
7084where @code{(<buffer length>)} is optional.
cce74817
JM
7085@end itemize
7086
5d161b24 7087@item @r{@emph{Timing Modes:}}
cce74817
JM
7088@itemize @bullet
7089@item
7090@emph{Duration Mode} which is predefined by @code{DURATION}
7091@item
7092@emph{Absolute Time Mode} which is predefined by @code{TIME}
7093@end itemize
7094
7095@item @r{@emph{Real Modes:}}
7096Real Modes are predefined with @code{REAL} and @code{LONG_REAL}.
7097
7098@item @r{@emph{String Modes:}}
7099@itemize @bullet
7100@item
6d2ebf8b
SS
7101@emph{Character String Mode} which is displayed by
7102@smallexample
7103@code{CHARS(<string length>)}
7104@end smallexample
7105followed by the keyword @code{VARYING} if the String Mode is a varying
7106mode
cce74817 7107@item
6d2ebf8b
SS
7108@emph{Bit String Mode} which is displayed by
7109@smallexample
7110@code{BOOLS(<string
7111length>)}
7112@end smallexample
cce74817
JM
7113@end itemize
7114
7115@item @r{@emph{Array Mode:}}
7116The Array Mode is displayed by the keyword @code{ARRAY(<range>)}
7117followed by the element mode (which may in turn be an array mode).
7118@smallexample
7119(@value{GDBP}) ptype x
5d161b24
DB
7120type = ARRAY (1:42)
7121 ARRAY (1:20)
cce74817
JM
7122 SET (karli = 10, susi = 20, fritzi = 100)
7123@end smallexample
7124
5d161b24 7125@item @r{@emph{Structure Mode}}
cce74817 7126The Structure mode is displayed by the keyword @code{STRUCT(<field
d4f3574e
SS
7127list>)}. The @code{<field list>} consists of names and modes of fields
7128of the structure. Variant structures have the keyword @code{CASE <field>
7129OF <variant fields> ESAC} in their field list. Since the current version
cce74817
JM
7130of the GNU Chill compiler doesn't implement tag processing (no runtime
7131checks of variant fields, and therefore no debugging info), the output
7132always displays all variant fields.
7133@smallexample
7134(@value{GDBP}) ptype str
7135type = STRUCT (
7136 as x,
7137 bs x,
7138 CASE bs OF
7139 (karli):
7140 cs a
7141 (ott):
7142 ds x
7143 ESAC
7144)
7145@end smallexample
7146@end table
7147
6d2ebf8b 7148@node Locations
cce74817
JM
7149@subsubsection Locations and their accesses
7150
7151A location in Chill is an object which can contain values.
7152
7153A value of a location is generally accessed by the (declared) name of
d4f3574e
SS
7154the location. The output conforms to the specification of values in
7155Chill programs. How values are specified
7156is the topic of the next section, @ref{Values and their Operations}.
cce74817
JM
7157
7158The pseudo-location @code{RESULT} (or @code{result}) can be used to
7159display or change the result of a currently-active procedure:
d4f3574e 7160
cce74817
JM
7161@smallexample
7162set result := EXPR
7163@end smallexample
d4f3574e
SS
7164
7165@noindent
7166This does the same as the Chill action @code{RESULT EXPR} (which
c3f6f71d 7167is not available in @value{GDBN}).
cce74817
JM
7168
7169Values of reference mode locations are printed by @code{PTR(<hex
7170value>)} in case of a free reference mode, and by @code{(REF <reference
d4f3574e 7171mode>) (<hex-value>)} in case of a bound reference. @code{<hex value>}
cce74817
JM
7172represents the address where the reference points to. To access the
7173value of the location referenced by the pointer, use the dereference
d4f3574e 7174operator @samp{->}.
cce74817 7175
6d2ebf8b
SS
7176Values of procedure mode locations are displayed by
7177@smallexample
7178@code{@{ PROC
cce74817 7179(<argument modes> ) <return mode> @} <address> <name of procedure
6d2ebf8b
SS
7180location>}
7181@end smallexample
7182@code{<argument modes>} is a list of modes according to the parameter
7183specification of the procedure and @code{<address>} shows the address of
7184the entry point.
cce74817
JM
7185
7186@ignore
7187Locations of instance modes are displayed just like a structure with two
7188fields specifying the @emph{process type} and the @emph{copy number} of
7189the investigated instance location@footnote{This comes from the current
d4f3574e
SS
7190implementation of instances. They are implemented as a structure (no
7191na). The output should be something like @code{[<name of the process>;
7192<instance number>]}.}. The field names are @code{__proc_type} and
cce74817
JM
7193@code{__proc_copy}.
7194
7195Locations of synchronization modes are displayed like a structure with
7196the field name @code{__event_data} in case of a event mode location, and
7197like a structure with the field @code{__buffer_data} in case of a buffer
7198mode location (refer to previous paragraph).
7199
7200Structure Mode locations are printed by @code{[.<field name>: <value>,
d4f3574e 7201...]}. The @code{<field name>} corresponds to the structure mode
cce74817 7202definition and the layout of @code{<value>} varies depending of the mode
d4f3574e
SS
7203of the field. If the investigated structure mode location is of variant
7204structure mode, the variant parts of the structure are enclosed in curled
7205braces (@samp{@{@}}). Fields enclosed by @samp{@{,@}} are residing
cce74817 7206on the same memory location and represent the current values of the
d4f3574e 7207memory location in their specific modes. Since no tag processing is done
cce74817 7208all variants are displayed. A variant field is printed by
d4f3574e 7209@code{(<variant name>) = .<field name>: <value>}. (who implements the
cce74817
JM
7210stuff ???)
7211@smallexample
7212(@value{GDBP}) print str1 $4 = [.as: 0, .bs: karli, .<TAG>: { (karli) =
7213[.cs: []], (susi) = [.ds: susi]}]
7214@end smallexample
7215@end ignore
7216
7217Substructures of string mode-, array mode- or structure mode-values
7218(e.g. array slices, fields of structure locations) are accessed using
d4f3574e
SS
7219certain operations which are described in the next section, @ref{Values
7220and their Operations}.
cce74817
JM
7221
7222A location value may be interpreted as having a different mode using the
d4f3574e
SS
7223location conversion. This mode conversion is written as @code{<mode
7224name>(<location>)}. The user has to consider that the sizes of the modes
7225have to be equal otherwise an error occurs. Furthermore, no range
7226checking of the location against the destination mode is performed, and
cce74817 7227therefore the result can be quite confusing.
d4f3574e 7228
cce74817
JM
7229@smallexample
7230(@value{GDBP}) print int (s(3 up 4)) XXX TO be filled in !! XXX
7231@end smallexample
7232
6d2ebf8b 7233@node Values and their Operations
cce74817
JM
7234@subsubsection Values and their Operations
7235
7236Values are used to alter locations, to investigate complex structures in
7237more detail or to filter relevant information out of a large amount of
d4f3574e
SS
7238data. There are several (mode dependent) operations defined which enable
7239such investigations. These operations are not only applicable to
cce74817 7240constant values but also to locations, which can become quite useful
d4f3574e 7241when debugging complex structures. During parsing the command line
cce74817
JM
7242(e.g. evaluating an expression) @value{GDBN} treats location names as
7243the values behind these locations.
7244
d4f3574e 7245This section describes how values have to be specified and which
cce74817
JM
7246operations are legal to be used with such values.
7247
7248@table @code
7249@item Literal Values
d4f3574e
SS
7250Literal values are specified in the same manner as in @sc{gnu} Chill programs.
7251For detailed specification refer to the @sc{gnu} Chill implementation Manual
cce74817 7252chapter 1.5.
d4f3574e
SS
7253@c FIXME: if the Chill Manual is a Texinfo documents, the above should
7254@c be converted to a @ref.
cce74817 7255
5d161b24 7256@ignore
cce74817
JM
7257@itemize @bullet
7258@item
7259@emph{Integer Literals} are specified in the same manner as in Chill
d4f3574e 7260programs (refer to the Chill Standard z200/88 chpt 5.2.4.2)
cce74817
JM
7261@item
7262@emph{Boolean Literals} are defined by @code{TRUE} and @code{FALSE}.
7263@item
7264@emph{Character Literals} are defined by @code{'<character>'}. (e.g.
7265@code{'M'})
7266@item
7267@emph{Set Literals} are defined by a name which was specified in a set
d4f3574e
SS
7268mode. The value delivered by a Set Literal is the set value. This is
7269comparable to an enumeration in C/C++ language.
cce74817 7270@item
d4f3574e 7271@emph{Emptiness Literal} is predefined by @code{NULL}. The value of the
cce74817 7272emptiness literal delivers either the empty reference value, the empty
5d161b24 7273procedure value or the empty instance value.
cce74817
JM
7274
7275@item
7276@emph{Character String Literals} are defined by a sequence of characters
d4f3574e 7277enclosed in single- or double quotes. If a single- or double quote has
cce74817
JM
7278to be part of the string literal it has to be stuffed (specified twice).
7279@item
7280@emph{Bitstring Literals} are specified in the same manner as in Chill
7281programs (refer z200/88 chpt 5.2.4.8).
7282@item
7283@emph{Floating point literals} are specified in the same manner as in
d4f3574e 7284(gnu-)Chill programs (refer @sc{gnu} Chill implementation Manual chapter 1.5).
cce74817
JM
7285@end itemize
7286@end ignore
7287
7288@item Tuple Values
7289A tuple is specified by @code{<mode name>[<tuple>]}, where @code{<mode
d4f3574e 7290name>} can be omitted if the mode of the tuple is unambiguous. This
cce74817
JM
7291unambiguity is derived from the context of a evaluated expression.
7292@code{<tuple>} can be one of the following:
d4f3574e 7293
cce74817
JM
7294@itemize @bullet
7295@item @emph{Powerset Tuple}
7296@item @emph{Array Tuple}
7297@item @emph{Structure Tuple}
7298Powerset tuples, array tuples and structure tuples are specified in the
d4f3574e 7299same manner as in Chill programs refer to z200/88 chpt 5.2.5.
cce74817
JM
7300@end itemize
7301
7302@item String Element Value
6d2ebf8b
SS
7303A string element value is specified by
7304@smallexample
7305@code{<string value>(<index>)}
7306@end smallexample
d4f3574e 7307where @code{<index>} is a integer expression. It delivers a character
cce74817
JM
7308value which is equivalent to the character indexed by @code{<index>} in
7309the string.
7310
7311@item String Slice Value
7312A string slice value is specified by @code{<string value>(<slice
7313spec>)}, where @code{<slice spec>} can be either a range of integer
7314expressions or specified by @code{<start expr> up <size>}.
7315@code{<size>} denotes the number of elements which the slice contains.
7316The delivered value is a string value, which is part of the specified
7317string.
7318
7319@item Array Element Values
7320An array element value is specified by @code{<array value>(<expr>)} and
7321delivers a array element value of the mode of the specified array.
7322
7323@item Array Slice Values
7324An array slice is specified by @code{<array value>(<slice spec>)}, where
7325@code{<slice spec>} can be either a range specified by expressions or by
d4f3574e
SS
7326@code{<start expr> up <size>}. @code{<size>} denotes the number of
7327arrayelements the slice contains. The delivered value is an array value
cce74817
JM
7328which is part of the specified array.
7329
7330@item Structure Field Values
7331A structure field value is derived by @code{<structure value>.<field
d4f3574e
SS
7332name>}, where @code{<field name>} indicates the name of a field specified
7333in the mode definition of the structure. The mode of the delivered value
cce74817
JM
7334corresponds to this mode definition in the structure definition.
7335
7336@item Procedure Call Value
7337The procedure call value is derived from the return value of the
7338procedure@footnote{If a procedure call is used for instance in an
7339expression, then this procedure is called with all its side
d4f3574e 7340effects. This can lead to confusing results if used carelessly.}.
cce74817 7341
d4f3574e 7342Values of duration mode locations are represented by @code{ULONG} literals.
cce74817 7343
6d2ebf8b
SS
7344Values of time mode locations appear as
7345@smallexample
7346@code{TIME(<secs>:<nsecs>)}
7347@end smallexample
7348
cce74817
JM
7349
7350@ignore
7351This is not implemented yet:
7352@item Built-in Value
7353@noindent
7354The following built in functions are provided:
d4f3574e 7355
cce74817
JM
7356@table @code
7357@item @code{ADDR()}
7358@item @code{NUM()}
7359@item @code{PRED()}
7360@item @code{SUCC()}
7361@item @code{ABS()}
7362@item @code{CARD()}
7363@item @code{MAX()}
7364@item @code{MIN()}
7365@item @code{SIZE()}
7366@item @code{UPPER()}
7367@item @code{LOWER()}
7368@item @code{LENGTH()}
7369@item @code{SIN()}
7370@item @code{COS()}
7371@item @code{TAN()}
7372@item @code{ARCSIN()}
7373@item @code{ARCCOS()}
7374@item @code{ARCTAN()}
7375@item @code{EXP()}
7376@item @code{LN()}
7377@item @code{LOG()}
7378@item @code{SQRT()}
7379@end table
7380
7381For a detailed description refer to the GNU Chill implementation manual
7382chapter 1.6.
7383@end ignore
7384
7385@item Zero-adic Operator Value
7386The zero-adic operator value is derived from the instance value for the
7387current active process.
7388
7389@item Expression Values
7390The value delivered by an expression is the result of the evaluation of
d4f3574e 7391the specified expression. If there are error conditions (mode
cce74817 7392incompatibility, etc.) the evaluation of expressions is aborted with a
d4f3574e 7393corresponding error message. Expressions may be parenthesised which
cce74817 7394causes the evaluation of this expression before any other expression
d4f3574e 7395which uses the result of the parenthesised expression. The following
cce74817 7396operators are supported by @value{GDBN}:
d4f3574e 7397
cce74817
JM
7398@table @code
7399@item @code{OR, ORIF, XOR}
d4f3574e
SS
7400@itemx @code{AND, ANDIF}
7401@itemx @code{NOT}
cce74817 7402Logical operators defined over operands of boolean mode.
d4f3574e 7403
cce74817
JM
7404@item @code{=, /=}
7405Equality and inequality operators defined over all modes.
d4f3574e 7406
cce74817 7407@item @code{>, >=}
d4f3574e 7408@itemx @code{<, <=}
cce74817 7409Relational operators defined over predefined modes.
d4f3574e 7410
cce74817 7411@item @code{+, -}
d4f3574e 7412@itemx @code{*, /, MOD, REM}
cce74817 7413Arithmetic operators defined over predefined modes.
d4f3574e 7414
cce74817
JM
7415@item @code{-}
7416Change sign operator.
d4f3574e 7417
cce74817
JM
7418@item @code{//}
7419String concatenation operator.
d4f3574e 7420
cce74817
JM
7421@item @code{()}
7422String repetition operator.
d4f3574e 7423
cce74817
JM
7424@item @code{->}
7425Referenced location operator which can be used either to take the
7426address of a location (@code{->loc}), or to dereference a reference
7427location (@code{loc->}).
d4f3574e 7428
cce74817 7429@item @code{OR, XOR}
d4f3574e
SS
7430@itemx @code{AND}
7431@itemx @code{NOT}
cce74817 7432Powerset and bitstring operators.
d4f3574e 7433
cce74817 7434@item @code{>, >=}
d4f3574e 7435@itemx @code{<, <=}
cce74817 7436Powerset inclusion operators.
d4f3574e 7437
cce74817
JM
7438@item @code{IN}
7439Membership operator.
7440@end table
7441@end table
7442
6d2ebf8b 7443@node Chill type and range checks
cce74817
JM
7444@subsubsection Chill type and range checks
7445
7446@value{GDBN} considers two Chill variables mode equivalent if the sizes
d4f3574e 7447of the two modes are equal. This rule applies recursively to more
cce74817 7448complex datatypes which means that complex modes are treated
d4f3574e 7449equivalent if all element modes (which also can be complex modes like
cce74817
JM
7450structures, arrays, etc.) have the same size.
7451
7452Range checking is done on all mathematical operations, assignment, array
7453index bounds and all built in procedures.
7454
7455Strong type checks are forced using the @value{GDBN} command @code{set
d4f3574e 7456check strong}. This enforces strong type and range checks on all
cce74817
JM
7457operations where Chill constructs are used (expressions, built in
7458functions, etc.) in respect to the semantics as defined in the z.200
7459language specification.
7460
cce74817
JM
7461All checks can be disabled by the @value{GDBN} command @code{set check
7462off}.
7463
5d161b24 7464@ignore
53a5351d 7465@c Deviations from the Chill Standard Z200/88
cce74817
JM
7466see last paragraph ?
7467@end ignore
7468
6d2ebf8b 7469@node Chill defaults
cce74817
JM
7470@subsubsection Chill defaults
7471
7472If type and range checking are set automatically by @value{GDBN}, they
7473both default to @code{on} whenever the working language changes to
d4f3574e 7474Chill. This happens regardless of whether you or @value{GDBN}
cce74817
JM
7475selected the working language.
7476
7477If you allow @value{GDBN} to set the language automatically, then entering
7478code compiled from a file whose name ends with @file{.ch} sets the
d4f3574e 7479working language to Chill. @xref{Automatically, ,Having @value{GDBN} set
cce74817
JM
7480the language automatically}, for further details.
7481
6d2ebf8b 7482@node Symbols
c906108c
SS
7483@chapter Examining the Symbol Table
7484
d4f3574e 7485The commands described in this chapter allow you to inquire about the
c906108c
SS
7486symbols (names of variables, functions and types) defined in your
7487program. This information is inherent in the text of your program and
7488does not change as your program executes. @value{GDBN} finds it in your
7489program's symbol table, in the file indicated when you started @value{GDBN}
7490(@pxref{File Options, ,Choosing files}), or by one of the
7491file-management commands (@pxref{Files, ,Commands to specify files}).
7492
7493@cindex symbol names
7494@cindex names of symbols
7495@cindex quoting names
7496Occasionally, you may need to refer to symbols that contain unusual
7497characters, which @value{GDBN} ordinarily treats as word delimiters. The
7498most frequent case is in referring to static variables in other
7499source files (@pxref{Variables,,Program variables}). File names
7500are recorded in object files as debugging symbols, but @value{GDBN} would
7501ordinarily parse a typical file name, like @file{foo.c}, as the three words
7502@samp{foo} @samp{.} @samp{c}. To allow @value{GDBN} to recognize
7503@samp{foo.c} as a single symbol, enclose it in single quotes; for example,
7504
7505@example
7506p 'foo.c'::x
7507@end example
7508
7509@noindent
7510looks up the value of @code{x} in the scope of the file @file{foo.c}.
7511
7512@table @code
7513@kindex info address
7514@item info address @var{symbol}
7515Describe where the data for @var{symbol} is stored. For a register
7516variable, this says which register it is kept in. For a non-register
7517local variable, this prints the stack-frame offset at which the variable
7518is always stored.
7519
7520Note the contrast with @samp{print &@var{symbol}}, which does not work
7521at all for a register variable, and for a stack local variable prints
7522the exact address of the current instantiation of the variable.
7523
7524@kindex whatis
d4f3574e
SS
7525@item whatis @var{expr}
7526Print the data type of expression @var{expr}. @var{expr} is not
c906108c
SS
7527actually evaluated, and any side-effecting operations (such as
7528assignments or function calls) inside it do not take place.
7529@xref{Expressions, ,Expressions}.
7530
7531@item whatis
7532Print the data type of @code{$}, the last value in the value history.
7533
7534@kindex ptype
7535@item ptype @var{typename}
7536Print a description of data type @var{typename}. @var{typename} may be
7a292a7a
SS
7537the name of a type, or for C code it may have the form @samp{class
7538@var{class-name}}, @samp{struct @var{struct-tag}}, @samp{union
7539@var{union-tag}} or @samp{enum @var{enum-tag}}.
c906108c 7540
d4f3574e 7541@item ptype @var{expr}
c906108c 7542@itemx ptype
d4f3574e 7543Print a description of the type of expression @var{expr}. @code{ptype}
c906108c
SS
7544differs from @code{whatis} by printing a detailed description, instead
7545of just the name of the type.
7546
7547For example, for this variable declaration:
7548
7549@example
7550struct complex @{double real; double imag;@} v;
7551@end example
7552
7553@noindent
7554the two commands give this output:
7555
7556@example
7557@group
7558(@value{GDBP}) whatis v
7559type = struct complex
7560(@value{GDBP}) ptype v
7561type = struct complex @{
7562 double real;
7563 double imag;
7564@}
7565@end group
7566@end example
7567
7568@noindent
7569As with @code{whatis}, using @code{ptype} without an argument refers to
7570the type of @code{$}, the last value in the value history.
7571
7572@kindex info types
7573@item info types @var{regexp}
7574@itemx info types
d4f3574e 7575Print a brief description of all types whose names match @var{regexp}
c906108c
SS
7576(or all types in your program, if you supply no argument). Each
7577complete typename is matched as though it were a complete line; thus,
7578@samp{i type value} gives information on all types in your program whose
d4f3574e 7579names include the string @code{value}, but @samp{i type ^value$} gives
c906108c
SS
7580information only on types whose complete name is @code{value}.
7581
7582This command differs from @code{ptype} in two ways: first, like
7583@code{whatis}, it does not print a detailed description; second, it
7584lists all source files where a type is defined.
7585
7586@kindex info source
7587@item info source
7588Show the name of the current source file---that is, the source file for
7589the function containing the current point of execution---and the language
7590it was written in.
7591
7592@kindex info sources
7593@item info sources
7594Print the names of all source files in your program for which there is
7595debugging information, organized into two lists: files whose symbols
7596have already been read, and files whose symbols will be read when needed.
7597
7598@kindex info functions
7599@item info functions
7600Print the names and data types of all defined functions.
7601
7602@item info functions @var{regexp}
7603Print the names and data types of all defined functions
7604whose names contain a match for regular expression @var{regexp}.
7605Thus, @samp{info fun step} finds all functions whose names
7606include @code{step}; @samp{info fun ^step} finds those whose names
7607start with @code{step}.
7608
7609@kindex info variables
7610@item info variables
7611Print the names and data types of all variables that are declared
7612outside of functions (i.e., excluding local variables).
7613
7614@item info variables @var{regexp}
7615Print the names and data types of all variables (except for local
7616variables) whose names contain a match for regular expression
7617@var{regexp}.
7618
7619@ignore
7620This was never implemented.
7621@kindex info methods
7622@item info methods
7623@itemx info methods @var{regexp}
7624The @code{info methods} command permits the user to examine all defined
7625methods within C++ program, or (with the @var{regexp} argument) a
7626specific set of methods found in the various C++ classes. Many
7627C++ classes provide a large number of methods. Thus, the output
7628from the @code{ptype} command can be overwhelming and hard to use. The
7629@code{info-methods} command filters the methods, printing only those
7630which match the regular-expression @var{regexp}.
7631@end ignore
7632
c906108c
SS
7633@cindex reloading symbols
7634Some systems allow individual object files that make up your program to
7a292a7a
SS
7635be replaced without stopping and restarting your program. For example,
7636in VxWorks you can simply recompile a defective object file and keep on
7637running. If you are running on one of these systems, you can allow
7638@value{GDBN} to reload the symbols for automatically relinked modules:
c906108c
SS
7639
7640@table @code
7641@kindex set symbol-reloading
7642@item set symbol-reloading on
7643Replace symbol definitions for the corresponding source file when an
7644object file with a particular name is seen again.
7645
7646@item set symbol-reloading off
6d2ebf8b
SS
7647Do not replace symbol definitions when encountering object files of the
7648same name more than once. This is the default state; if you are not
7649running on a system that permits automatic relinking of modules, you
7650should leave @code{symbol-reloading} off, since otherwise @value{GDBN}
7651may discard symbols when linking large programs, that may contain
7652several modules (from different directories or libraries) with the same
7653name.
c906108c
SS
7654
7655@kindex show symbol-reloading
7656@item show symbol-reloading
7657Show the current @code{on} or @code{off} setting.
7658@end table
c906108c 7659
c906108c
SS
7660@kindex set opaque-type-resolution
7661@item set opaque-type-resolution on
7662Tell @value{GDBN} to resolve opaque types. An opaque type is a type
7663declared as a pointer to a @code{struct}, @code{class}, or
7664@code{union}---for example, @code{struct MyType *}---that is used in one
7665source file although the full declaration of @code{struct MyType} is in
7666another source file. The default is on.
7667
7668A change in the setting of this subcommand will not take effect until
7669the next time symbols for a file are loaded.
7670
7671@item set opaque-type-resolution off
7672Tell @value{GDBN} not to resolve opaque types. In this case, the type
7673is printed as follows:
7674@smallexample
7675@{<no data fields>@}
7676@end smallexample
7677
7678@kindex show opaque-type-resolution
7679@item show opaque-type-resolution
7680Show whether opaque types are resolved or not.
c906108c
SS
7681
7682@kindex maint print symbols
7683@cindex symbol dump
7684@kindex maint print psymbols
7685@cindex partial symbol dump
7686@item maint print symbols @var{filename}
7687@itemx maint print psymbols @var{filename}
7688@itemx maint print msymbols @var{filename}
7689Write a dump of debugging symbol data into the file @var{filename}.
7690These commands are used to debug the @value{GDBN} symbol-reading code. Only
7691symbols with debugging data are included. If you use @samp{maint print
7692symbols}, @value{GDBN} includes all the symbols for which it has already
7693collected full details: that is, @var{filename} reflects symbols for
7694only those files whose symbols @value{GDBN} has read. You can use the
7695command @code{info sources} to find out which files these are. If you
7696use @samp{maint print psymbols} instead, the dump shows information about
7697symbols that @value{GDBN} only knows partially---that is, symbols defined in
7698files that @value{GDBN} has skimmed, but not yet read completely. Finally,
7699@samp{maint print msymbols} dumps just the minimal symbol information
7700required for each object file from which @value{GDBN} has read some symbols.
7701@xref{Files, ,Commands to specify files}, for a discussion of how
7702@value{GDBN} reads symbols (in the description of @code{symbol-file}).
7703@end table
7704
6d2ebf8b 7705@node Altering
c906108c
SS
7706@chapter Altering Execution
7707
7708Once you think you have found an error in your program, you might want to
7709find out for certain whether correcting the apparent error would lead to
7710correct results in the rest of the run. You can find the answer by
7711experiment, using the @value{GDBN} features for altering execution of the
7712program.
7713
7714For example, you can store new values into variables or memory
7a292a7a
SS
7715locations, give your program a signal, restart it at a different
7716address, or even return prematurely from a function.
c906108c
SS
7717
7718@menu
7719* Assignment:: Assignment to variables
7720* Jumping:: Continuing at a different address
c906108c 7721* Signaling:: Giving your program a signal
c906108c
SS
7722* Returning:: Returning from a function
7723* Calling:: Calling your program's functions
7724* Patching:: Patching your program
7725@end menu
7726
6d2ebf8b 7727@node Assignment
c906108c
SS
7728@section Assignment to variables
7729
7730@cindex assignment
7731@cindex setting variables
7732To alter the value of a variable, evaluate an assignment expression.
7733@xref{Expressions, ,Expressions}. For example,
7734
7735@example
7736print x=4
7737@end example
7738
7739@noindent
7740stores the value 4 into the variable @code{x}, and then prints the
5d161b24 7741value of the assignment expression (which is 4).
c906108c
SS
7742@xref{Languages, ,Using @value{GDBN} with Different Languages}, for more
7743information on operators in supported languages.
c906108c
SS
7744
7745@kindex set variable
7746@cindex variables, setting
7747If you are not interested in seeing the value of the assignment, use the
7748@code{set} command instead of the @code{print} command. @code{set} is
7749really the same as @code{print} except that the expression's value is
7750not printed and is not put in the value history (@pxref{Value History,
7751,Value history}). The expression is evaluated only for its effects.
7752
c906108c
SS
7753If the beginning of the argument string of the @code{set} command
7754appears identical to a @code{set} subcommand, use the @code{set
7755variable} command instead of just @code{set}. This command is identical
7756to @code{set} except for its lack of subcommands. For example, if your
7757program has a variable @code{width}, you get an error if you try to set
7758a new value with just @samp{set width=13}, because @value{GDBN} has the
7759command @code{set width}:
7760
7761@example
7762(@value{GDBP}) whatis width
7763type = double
7764(@value{GDBP}) p width
7765$4 = 13
7766(@value{GDBP}) set width=47
7767Invalid syntax in expression.
7768@end example
7769
7770@noindent
7771The invalid expression, of course, is @samp{=47}. In
7772order to actually set the program's variable @code{width}, use
7773
7774@example
7775(@value{GDBP}) set var width=47
7776@end example
53a5351d 7777
c906108c
SS
7778Because the @code{set} command has many subcommands that can conflict
7779with the names of program variables, it is a good idea to use the
7780@code{set variable} command instead of just @code{set}. For example, if
7781your program has a variable @code{g}, you run into problems if you try
7782to set a new value with just @samp{set g=4}, because @value{GDBN} has
7783the command @code{set gnutarget}, abbreviated @code{set g}:
7784
7785@example
7786@group
7787(@value{GDBP}) whatis g
7788type = double
7789(@value{GDBP}) p g
7790$1 = 1
7791(@value{GDBP}) set g=4
2df3850c 7792(@value{GDBP}) p g
c906108c
SS
7793$2 = 1
7794(@value{GDBP}) r
7795The program being debugged has been started already.
7796Start it from the beginning? (y or n) y
7797Starting program: /home/smith/cc_progs/a.out
6d2ebf8b
SS
7798"/home/smith/cc_progs/a.out": can't open to read symbols:
7799 Invalid bfd target.
c906108c
SS
7800(@value{GDBP}) show g
7801The current BFD target is "=4".
7802@end group
7803@end example
7804
7805@noindent
7806The program variable @code{g} did not change, and you silently set the
7807@code{gnutarget} to an invalid value. In order to set the variable
7808@code{g}, use
7809
7810@example
7811(@value{GDBP}) set var g=4
7812@end example
c906108c
SS
7813
7814@value{GDBN} allows more implicit conversions in assignments than C; you can
7815freely store an integer value into a pointer variable or vice versa,
7816and you can convert any structure to any other structure that is the
7817same length or shorter.
7818@comment FIXME: how do structs align/pad in these conversions?
7819@comment /[email protected] 18dec1990
7820
7821To store values into arbitrary places in memory, use the @samp{@{@dots{}@}}
7822construct to generate a value of specified type at a specified address
7823(@pxref{Expressions, ,Expressions}). For example, @code{@{int@}0x83040} refers
7824to memory location @code{0x83040} as an integer (which implies a certain size
7825and representation in memory), and
7826
7827@example
7828set @{int@}0x83040 = 4
7829@end example
7830
7831@noindent
7832stores the value 4 into that memory location.
7833
6d2ebf8b 7834@node Jumping
c906108c
SS
7835@section Continuing at a different address
7836
7837Ordinarily, when you continue your program, you do so at the place where
7838it stopped, with the @code{continue} command. You can instead continue at
7839an address of your own choosing, with the following commands:
7840
7841@table @code
7842@kindex jump
7843@item jump @var{linespec}
7844Resume execution at line @var{linespec}. Execution stops again
7845immediately if there is a breakpoint there. @xref{List, ,Printing
7846source lines}, for a description of the different forms of
7847@var{linespec}. It is common practice to use the @code{tbreak} command
7848in conjunction with @code{jump}. @xref{Set Breaks, ,Setting
7849breakpoints}.
7850
7851The @code{jump} command does not change the current stack frame, or
7852the stack pointer, or the contents of any memory location or any
7853register other than the program counter. If line @var{linespec} is in
7854a different function from the one currently executing, the results may
7855be bizarre if the two functions expect different patterns of arguments or
7856of local variables. For this reason, the @code{jump} command requests
7857confirmation if the specified line is not in the function currently
7858executing. However, even bizarre results are predictable if you are
7859well acquainted with the machine-language code of your program.
7860
7861@item jump *@var{address}
7862Resume execution at the instruction at address @var{address}.
7863@end table
7864
c906108c 7865@c Doesn't work on HP-UX; have to set $pcoqh and $pcoqt.
53a5351d
JM
7866On many systems, you can get much the same effect as the @code{jump}
7867command by storing a new value into the register @code{$pc}. The
7868difference is that this does not start your program running; it only
7869changes the address of where it @emph{will} run when you continue. For
7870example,
c906108c
SS
7871
7872@example
7873set $pc = 0x485
7874@end example
7875
7876@noindent
7877makes the next @code{continue} command or stepping command execute at
7878address @code{0x485}, rather than at the address where your program stopped.
7879@xref{Continuing and Stepping, ,Continuing and stepping}.
c906108c
SS
7880
7881The most common occasion to use the @code{jump} command is to back
7882up---perhaps with more breakpoints set---over a portion of a program
7883that has already executed, in order to examine its execution in more
7884detail.
7885
c906108c 7886@c @group
6d2ebf8b 7887@node Signaling
c906108c
SS
7888@section Giving your program a signal
7889
7890@table @code
7891@kindex signal
7892@item signal @var{signal}
7893Resume execution where your program stopped, but immediately give it the
7894signal @var{signal}. @var{signal} can be the name or the number of a
7895signal. For example, on many systems @code{signal 2} and @code{signal
7896SIGINT} are both ways of sending an interrupt signal.
7897
7898Alternatively, if @var{signal} is zero, continue execution without
7899giving a signal. This is useful when your program stopped on account of
7900a signal and would ordinary see the signal when resumed with the
7901@code{continue} command; @samp{signal 0} causes it to resume without a
7902signal.
7903
7904@code{signal} does not repeat when you press @key{RET} a second time
7905after executing the command.
7906@end table
7907@c @end group
7908
7909Invoking the @code{signal} command is not the same as invoking the
7910@code{kill} utility from the shell. Sending a signal with @code{kill}
7911causes @value{GDBN} to decide what to do with the signal depending on
7912the signal handling tables (@pxref{Signals}). The @code{signal} command
7913passes the signal directly to your program.
7914
c906108c 7915
6d2ebf8b 7916@node Returning
c906108c
SS
7917@section Returning from a function
7918
7919@table @code
7920@cindex returning from a function
7921@kindex return
7922@item return
7923@itemx return @var{expression}
7924You can cancel execution of a function call with the @code{return}
7925command. If you give an
7926@var{expression} argument, its value is used as the function's return
7927value.
7928@end table
7929
7930When you use @code{return}, @value{GDBN} discards the selected stack frame
7931(and all frames within it). You can think of this as making the
7932discarded frame return prematurely. If you wish to specify a value to
7933be returned, give that value as the argument to @code{return}.
7934
7935This pops the selected stack frame (@pxref{Selection, ,Selecting a
7936frame}), and any other frames inside of it, leaving its caller as the
7937innermost remaining frame. That frame becomes selected. The
7938specified value is stored in the registers used for returning values
7939of functions.
7940
7941The @code{return} command does not resume execution; it leaves the
7942program stopped in the state that would exist if the function had just
7943returned. In contrast, the @code{finish} command (@pxref{Continuing
7944and Stepping, ,Continuing and stepping}) resumes execution until the
7945selected stack frame returns naturally.
7946
6d2ebf8b 7947@node Calling
c906108c
SS
7948@section Calling program functions
7949
7950@cindex calling functions
7951@kindex call
7952@table @code
7953@item call @var{expr}
7954Evaluate the expression @var{expr} without displaying @code{void}
7955returned values.
7956@end table
7957
7958You can use this variant of the @code{print} command if you want to
7959execute a function from your program, but without cluttering the output
5d161b24
DB
7960with @code{void} returned values. If the result is not void, it
7961is printed and saved in the value history.
c906108c 7962
c906108c
SS
7963For the A29K, a user-controlled variable @code{call_scratch_address},
7964specifies the location of a scratch area to be used when @value{GDBN}
7965calls a function in the target. This is necessary because the usual
7966method of putting the scratch area on the stack does not work in systems
7967that have separate instruction and data spaces.
c906108c 7968
6d2ebf8b 7969@node Patching
c906108c 7970@section Patching programs
7a292a7a 7971
c906108c
SS
7972@cindex patching binaries
7973@cindex writing into executables
c906108c 7974@cindex writing into corefiles
c906108c 7975
7a292a7a
SS
7976By default, @value{GDBN} opens the file containing your program's
7977executable code (or the corefile) read-only. This prevents accidental
7978alterations to machine code; but it also prevents you from intentionally
7979patching your program's binary.
c906108c
SS
7980
7981If you'd like to be able to patch the binary, you can specify that
7982explicitly with the @code{set write} command. For example, you might
7983want to turn on internal debugging flags, or even to make emergency
7984repairs.
7985
7986@table @code
7987@kindex set write
7988@item set write on
7989@itemx set write off
7a292a7a
SS
7990If you specify @samp{set write on}, @value{GDBN} opens executable and
7991core files for both reading and writing; if you specify @samp{set write
c906108c
SS
7992off} (the default), @value{GDBN} opens them read-only.
7993
7994If you have already loaded a file, you must load it again (using the
7a292a7a
SS
7995@code{exec-file} or @code{core-file} command) after changing @code{set
7996write}, for your new setting to take effect.
c906108c
SS
7997
7998@item show write
7999@kindex show write
7a292a7a
SS
8000Display whether executable files and core files are opened for writing
8001as well as reading.
c906108c
SS
8002@end table
8003
6d2ebf8b 8004@node GDB Files
c906108c
SS
8005@chapter @value{GDBN} Files
8006
7a292a7a
SS
8007@value{GDBN} needs to know the file name of the program to be debugged,
8008both in order to read its symbol table and in order to start your
8009program. To debug a core dump of a previous run, you must also tell
8010@value{GDBN} the name of the core dump file.
c906108c
SS
8011
8012@menu
8013* Files:: Commands to specify files
8014* Symbol Errors:: Errors reading symbol files
8015@end menu
8016
6d2ebf8b 8017@node Files
c906108c 8018@section Commands to specify files
c906108c 8019
7a292a7a 8020@cindex symbol table
c906108c 8021@cindex core dump file
7a292a7a
SS
8022
8023You may want to specify executable and core dump file names. The usual
8024way to do this is at start-up time, using the arguments to
8025@value{GDBN}'s start-up commands (@pxref{Invocation, , Getting In and
8026Out of @value{GDBN}}).
c906108c
SS
8027
8028Occasionally it is necessary to change to a different file during a
8029@value{GDBN} session. Or you may run @value{GDBN} and forget to specify
8030a file you want to use. In these situations the @value{GDBN} commands
8031to specify new files are useful.
8032
8033@table @code
8034@cindex executable file
8035@kindex file
8036@item file @var{filename}
8037Use @var{filename} as the program to be debugged. It is read for its
8038symbols and for the contents of pure memory. It is also the program
8039executed when you use the @code{run} command. If you do not specify a
5d161b24
DB
8040directory and the file is not found in the @value{GDBN} working directory,
8041@value{GDBN} uses the environment variable @code{PATH} as a list of
8042directories to search, just as the shell does when looking for a program
8043to run. You can change the value of this variable, for both @value{GDBN}
c906108c
SS
8044and your program, using the @code{path} command.
8045
6d2ebf8b 8046On systems with memory-mapped files, an auxiliary file named
c906108c
SS
8047@file{@var{filename}.syms} may hold symbol table information for
8048@var{filename}. If so, @value{GDBN} maps in the symbol table from
8049@file{@var{filename}.syms}, starting up more quickly. See the
8050descriptions of the file options @samp{-mapped} and @samp{-readnow}
8051(available on the command line, and with the commands @code{file},
5d161b24 8052@code{symbol-file}, or @code{add-symbol-file}, described below),
c906108c 8053for more information.
c906108c
SS
8054
8055@item file
8056@code{file} with no argument makes @value{GDBN} discard any information it
8057has on both executable file and the symbol table.
8058
8059@kindex exec-file
8060@item exec-file @r{[} @var{filename} @r{]}
8061Specify that the program to be run (but not the symbol table) is found
8062in @var{filename}. @value{GDBN} searches the environment variable @code{PATH}
8063if necessary to locate your program. Omitting @var{filename} means to
8064discard information on the executable file.
8065
8066@kindex symbol-file
8067@item symbol-file @r{[} @var{filename} @r{]}
8068Read symbol table information from file @var{filename}. @code{PATH} is
8069searched when necessary. Use the @code{file} command to get both symbol
8070table and program to run from the same file.
8071
8072@code{symbol-file} with no argument clears out @value{GDBN} information on your
8073program's symbol table.
8074
5d161b24 8075The @code{symbol-file} command causes @value{GDBN} to forget the contents
c906108c
SS
8076of its convenience variables, the value history, and all breakpoints and
8077auto-display expressions. This is because they may contain pointers to
8078the internal data recording symbols and data types, which are part of
8079the old symbol table data being discarded inside @value{GDBN}.
8080
8081@code{symbol-file} does not repeat if you press @key{RET} again after
8082executing it once.
8083
8084When @value{GDBN} is configured for a particular environment, it
8085understands debugging information in whatever format is the standard
8086generated for that environment; you may use either a @sc{gnu} compiler, or
8087other compilers that adhere to the local conventions.
c906108c
SS
8088Best results are usually obtained from @sc{gnu} compilers; for example,
8089using @code{@value{GCC}} you can generate debugging information for
8090optimized code.
c906108c
SS
8091
8092For most kinds of object files, with the exception of old SVR3 systems
8093using COFF, the @code{symbol-file} command does not normally read the
8094symbol table in full right away. Instead, it scans the symbol table
8095quickly to find which source files and which symbols are present. The
8096details are read later, one source file at a time, as they are needed.
8097
8098The purpose of this two-stage reading strategy is to make @value{GDBN}
8099start up faster. For the most part, it is invisible except for
8100occasional pauses while the symbol table details for a particular source
8101file are being read. (The @code{set verbose} command can turn these
8102pauses into messages if desired. @xref{Messages/Warnings, ,Optional
8103warnings and messages}.)
8104
c906108c
SS
8105We have not implemented the two-stage strategy for COFF yet. When the
8106symbol table is stored in COFF format, @code{symbol-file} reads the
8107symbol table data in full right away. Note that ``stabs-in-COFF''
8108still does the two-stage strategy, since the debug info is actually
8109in stabs format.
8110
8111@kindex readnow
8112@cindex reading symbols immediately
8113@cindex symbols, reading immediately
8114@kindex mapped
8115@cindex memory-mapped symbol file
8116@cindex saving symbol table
8117@item symbol-file @var{filename} @r{[} -readnow @r{]} @r{[} -mapped @r{]}
8118@itemx file @var{filename} @r{[} -readnow @r{]} @r{[} -mapped @r{]}
8119You can override the @value{GDBN} two-stage strategy for reading symbol
8120tables by using the @samp{-readnow} option with any of the commands that
8121load symbol table information, if you want to be sure @value{GDBN} has the
5d161b24 8122entire symbol table available.
c906108c 8123
c906108c
SS
8124If memory-mapped files are available on your system through the
8125@code{mmap} system call, you can use another option, @samp{-mapped}, to
8126cause @value{GDBN} to write the symbols for your program into a reusable
8127file. Future @value{GDBN} debugging sessions map in symbol information
8128from this auxiliary symbol file (if the program has not changed), rather
8129than spending time reading the symbol table from the executable
8130program. Using the @samp{-mapped} option has the same effect as
8131starting @value{GDBN} with the @samp{-mapped} command-line option.
8132
8133You can use both options together, to make sure the auxiliary symbol
8134file has all the symbol information for your program.
8135
8136The auxiliary symbol file for a program called @var{myprog} is called
8137@samp{@var{myprog}.syms}. Once this file exists (so long as it is newer
8138than the corresponding executable), @value{GDBN} always attempts to use
8139it when you debug @var{myprog}; no special options or commands are
8140needed.
8141
8142The @file{.syms} file is specific to the host machine where you run
8143@value{GDBN}. It holds an exact image of the internal @value{GDBN}
8144symbol table. It cannot be shared across multiple host platforms.
c906108c
SS
8145
8146@c FIXME: for now no mention of directories, since this seems to be in
8147@c flux. 13mar1992 status is that in theory GDB would look either in
8148@c current dir or in same dir as myprog; but issues like competing
8149@c GDB's, or clutter in system dirs, mean that in practice right now
8150@c only current dir is used. FFish says maybe a special GDB hierarchy
8151@c (eg rooted in val of env var GDBSYMS) could exist for mappable symbol
8152@c files.
8153
8154@kindex core
8155@kindex core-file
8156@item core-file @r{[} @var{filename} @r{]}
8157Specify the whereabouts of a core dump file to be used as the ``contents
8158of memory''. Traditionally, core files contain only some parts of the
8159address space of the process that generated them; @value{GDBN} can access the
8160executable file itself for other parts.
8161
8162@code{core-file} with no argument specifies that no core file is
8163to be used.
8164
8165Note that the core file is ignored when your program is actually running
7a292a7a
SS
8166under @value{GDBN}. So, if you have been running your program and you
8167wish to debug a core file instead, you must kill the subprocess in which
8168the program is running. To do this, use the @code{kill} command
c906108c 8169(@pxref{Kill Process, ,Killing the child process}).
c906108c 8170
c906108c
SS
8171@kindex add-symbol-file
8172@cindex dynamic linking
8173@item add-symbol-file @var{filename} @var{address}
8174@itemx add-symbol-file @var{filename} @var{address} @r{[} -readnow @r{]} @r{[} -mapped @r{]}
d167840f 8175@itemx add-symbol-file @var{filename} @r{-s}@var{section} @var{address}
96a2c332
SS
8176The @code{add-symbol-file} command reads additional symbol table
8177information from the file @var{filename}. You would use this command
8178when @var{filename} has been dynamically loaded (by some other means)
8179into the program that is running. @var{address} should be the memory
8180address at which the file has been loaded; @value{GDBN} cannot figure
d167840f
EZ
8181this out for itself. You can additionally specify an arbitrary number
8182of @samp{@r{-s}@var{section} @var{address}} pairs, to give an explicit
8183section name and base address for that section. You can specify any
8184@var{address} as an expression.
c906108c
SS
8185
8186The symbol table of the file @var{filename} is added to the symbol table
8187originally read with the @code{symbol-file} command. You can use the
96a2c332
SS
8188@code{add-symbol-file} command any number of times; the new symbol data
8189thus read keeps adding to the old. To discard all old symbol data
8190instead, use the @code{symbol-file} command without any arguments.
c906108c
SS
8191
8192@code{add-symbol-file} does not repeat if you press @key{RET} after using it.
8193
8194You can use the @samp{-mapped} and @samp{-readnow} options just as with
8195the @code{symbol-file} command, to change how @value{GDBN} manages the symbol
8196table information for @var{filename}.
8197
8198@kindex add-shared-symbol-file
8199@item add-shared-symbol-file
8200The @code{add-shared-symbol-file} command can be used only under Harris' CXUX
5d161b24
DB
8201operating system for the Motorola 88k. @value{GDBN} automatically looks for
8202shared libraries, however if @value{GDBN} does not find yours, you can run
c906108c 8203@code{add-shared-symbol-file}. It takes no arguments.
c906108c 8204
c906108c
SS
8205@kindex section
8206@item section
5d161b24
DB
8207The @code{section} command changes the base address of section SECTION of
8208the exec file to ADDR. This can be used if the exec file does not contain
8209section addresses, (such as in the a.out format), or when the addresses
8210specified in the file itself are wrong. Each section must be changed
d4f3574e
SS
8211separately. The @code{info files} command, described below, lists all
8212the sections and their addresses.
c906108c
SS
8213
8214@kindex info files
8215@kindex info target
8216@item info files
8217@itemx info target
7a292a7a
SS
8218@code{info files} and @code{info target} are synonymous; both print the
8219current target (@pxref{Targets, ,Specifying a Debugging Target}),
8220including the names of the executable and core dump files currently in
8221use by @value{GDBN}, and the files from which symbols were loaded. The
8222command @code{help target} lists all possible targets rather than
8223current ones.
8224
c906108c
SS
8225@end table
8226
8227All file-specifying commands allow both absolute and relative file names
8228as arguments. @value{GDBN} always converts the file name to an absolute file
8229name and remembers it that way.
8230
c906108c 8231@cindex shared libraries
c906108c
SS
8232@value{GDBN} supports HP-UX, SunOS, SVr4, Irix 5, and IBM RS/6000 shared
8233libraries.
53a5351d 8234
c906108c
SS
8235@value{GDBN} automatically loads symbol definitions from shared libraries
8236when you use the @code{run} command, or when you examine a core file.
8237(Before you issue the @code{run} command, @value{GDBN} does not understand
8238references to a function in a shared library, however---unless you are
8239debugging a core file).
53a5351d
JM
8240
8241On HP-UX, if the program loads a library explicitly, @value{GDBN}
8242automatically loads the symbols at the time of the @code{shl_load} call.
8243
c906108c
SS
8244@c FIXME: some @value{GDBN} release may permit some refs to undef
8245@c FIXME...symbols---eg in a break cmd---assuming they are from a shared
8246@c FIXME...lib; check this from time to time when updating manual
8247
8248@table @code
8249@kindex info sharedlibrary
8250@kindex info share
8251@item info share
8252@itemx info sharedlibrary
8253Print the names of the shared libraries which are currently loaded.
8254
8255@kindex sharedlibrary
8256@kindex share
8257@item sharedlibrary @var{regex}
8258@itemx share @var{regex}
c906108c
SS
8259Load shared object library symbols for files matching a
8260Unix regular expression.
8261As with files loaded automatically, it only loads shared libraries
8262required by your program for a core file or after typing @code{run}. If
8263@var{regex} is omitted all shared libraries required by your program are
8264loaded.
8265@end table
8266
53a5351d
JM
8267On HP-UX systems, @value{GDBN} detects the loading of a shared library
8268and automatically reads in symbols from the newly loaded library, up to
8269a threshold that is initially set but that you can modify if you wish.
c906108c
SS
8270
8271Beyond that threshold, symbols from shared libraries must be explicitly
d4f3574e
SS
8272loaded. To load these symbols, use the command @code{sharedlibrary
8273@var{filename}}. The base address of the shared library is determined
c906108c
SS
8274automatically by @value{GDBN} and need not be specified.
8275
8276To display or set the threshold, use the commands:
8277
8278@table @code
8279@kindex set auto-solib-add
8280@item set auto-solib-add @var{threshold}
8281Set the autoloading size threshold, in megabytes. If @var{threshold} is
8282nonzero, symbols from all shared object libraries will be loaded
8283automatically when the inferior begins execution or when the dynamic
8284linker informs @value{GDBN} that a new library has been loaded, until
8285the symbol table of the program and libraries exceeds this threshold.
8286Otherwise, symbols must be loaded manually, using the
8287@code{sharedlibrary} command. The default threshold is 100 megabytes.
8288
8289@kindex show auto-solib-add
8290@item show auto-solib-add
8291Display the current autoloading size threshold, in megabytes.
8292@end table
c906108c 8293
6d2ebf8b 8294@node Symbol Errors
c906108c
SS
8295@section Errors reading symbol files
8296
8297While reading a symbol file, @value{GDBN} occasionally encounters problems,
8298such as symbol types it does not recognize, or known bugs in compiler
8299output. By default, @value{GDBN} does not notify you of such problems, since
8300they are relatively common and primarily of interest to people
8301debugging compilers. If you are interested in seeing information
8302about ill-constructed symbol tables, you can either ask @value{GDBN} to print
8303only one message about each such type of problem, no matter how many
8304times the problem occurs; or you can ask @value{GDBN} to print more messages,
8305to see how many times the problems occur, with the @code{set
8306complaints} command (@pxref{Messages/Warnings, ,Optional warnings and
8307messages}).
8308
8309The messages currently printed, and their meanings, include:
8310
8311@table @code
8312@item inner block not inside outer block in @var{symbol}
8313
8314The symbol information shows where symbol scopes begin and end
8315(such as at the start of a function or a block of statements). This
8316error indicates that an inner scope block is not fully contained
8317in its outer scope blocks.
8318
8319@value{GDBN} circumvents the problem by treating the inner block as if it had
8320the same scope as the outer block. In the error message, @var{symbol}
8321may be shown as ``@code{(don't know)}'' if the outer block is not a
8322function.
8323
8324@item block at @var{address} out of order
8325
8326The symbol information for symbol scope blocks should occur in
8327order of increasing addresses. This error indicates that it does not
8328do so.
8329
8330@value{GDBN} does not circumvent this problem, and has trouble
8331locating symbols in the source file whose symbols it is reading. (You
8332can often determine what source file is affected by specifying
8333@code{set verbose on}. @xref{Messages/Warnings, ,Optional warnings and
8334messages}.)
8335
8336@item bad block start address patched
8337
8338The symbol information for a symbol scope block has a start address
8339smaller than the address of the preceding source line. This is known
8340to occur in the SunOS 4.1.1 (and earlier) C compiler.
8341
8342@value{GDBN} circumvents the problem by treating the symbol scope block as
8343starting on the previous source line.
8344
8345@item bad string table offset in symbol @var{n}
8346
8347@cindex foo
8348Symbol number @var{n} contains a pointer into the string table which is
8349larger than the size of the string table.
8350
8351@value{GDBN} circumvents the problem by considering the symbol to have the
8352name @code{foo}, which may cause other problems if many symbols end up
8353with this name.
8354
8355@item unknown symbol type @code{0x@var{nn}}
8356
7a292a7a
SS
8357The symbol information contains new data types that @value{GDBN} does
8358not yet know how to read. @code{0x@var{nn}} is the symbol type of the
d4f3574e 8359uncomprehended information, in hexadecimal.
c906108c 8360
7a292a7a
SS
8361@value{GDBN} circumvents the error by ignoring this symbol information.
8362This usually allows you to debug your program, though certain symbols
c906108c 8363are not accessible. If you encounter such a problem and feel like
7a292a7a
SS
8364debugging it, you can debug @code{@value{GDBP}} with itself, breakpoint
8365on @code{complain}, then go up to the function @code{read_dbx_symtab}
8366and examine @code{*bufp} to see the symbol.
c906108c
SS
8367
8368@item stub type has NULL name
c906108c 8369
7a292a7a 8370@value{GDBN} could not find the full definition for a struct or class.
c906108c 8371
7a292a7a 8372@item const/volatile indicator missing (ok if using g++ v1.x), got@dots{}
c906108c 8373The symbol information for a C++ member function is missing some
7a292a7a
SS
8374information that recent versions of the compiler should have output for
8375it.
c906108c
SS
8376
8377@item info mismatch between compiler and debugger
8378
8379@value{GDBN} could not parse a type specification output by the compiler.
7a292a7a 8380
c906108c
SS
8381@end table
8382
6d2ebf8b 8383@node Targets
c906108c 8384@chapter Specifying a Debugging Target
7a292a7a 8385
c906108c
SS
8386@cindex debugging target
8387@kindex target
8388
8389A @dfn{target} is the execution environment occupied by your program.
53a5351d
JM
8390
8391Often, @value{GDBN} runs in the same host environment as your program;
8392in that case, the debugging target is specified as a side effect when
8393you use the @code{file} or @code{core} commands. When you need more
c906108c
SS
8394flexibility---for example, running @value{GDBN} on a physically separate
8395host, or controlling a standalone system over a serial port or a
53a5351d
JM
8396realtime system over a TCP/IP connection---you can use the @code{target}
8397command to specify one of the target types configured for @value{GDBN}
8398(@pxref{Target Commands, ,Commands for managing targets}).
c906108c
SS
8399
8400@menu
8401* Active Targets:: Active targets
8402* Target Commands:: Commands for managing targets
c906108c
SS
8403* Byte Order:: Choosing target byte order
8404* Remote:: Remote debugging
96baa820 8405* KOD:: Kernel Object Display
c906108c
SS
8406
8407@end menu
8408
6d2ebf8b 8409@node Active Targets
c906108c 8410@section Active targets
7a292a7a 8411
c906108c
SS
8412@cindex stacking targets
8413@cindex active targets
8414@cindex multiple targets
8415
c906108c 8416There are three classes of targets: processes, core files, and
7a292a7a
SS
8417executable files. @value{GDBN} can work concurrently on up to three
8418active targets, one in each class. This allows you to (for example)
8419start a process and inspect its activity without abandoning your work on
8420a core file.
c906108c
SS
8421
8422For example, if you execute @samp{gdb a.out}, then the executable file
8423@code{a.out} is the only active target. If you designate a core file as
8424well---presumably from a prior run that crashed and coredumped---then
8425@value{GDBN} has two active targets and uses them in tandem, looking
8426first in the corefile target, then in the executable file, to satisfy
8427requests for memory addresses. (Typically, these two classes of target
8428are complementary, since core files contain only a program's
8429read-write memory---variables and so on---plus machine status, while
8430executable files contain only the program text and initialized data.)
c906108c
SS
8431
8432When you type @code{run}, your executable file becomes an active process
7a292a7a
SS
8433target as well. When a process target is active, all @value{GDBN}
8434commands requesting memory addresses refer to that target; addresses in
8435an active core file or executable file target are obscured while the
8436process target is active.
c906108c 8437
7a292a7a
SS
8438Use the @code{core-file} and @code{exec-file} commands to select a new
8439core file or executable target (@pxref{Files, ,Commands to specify
c906108c 8440files}). To specify as a target a process that is already running, use
7a292a7a
SS
8441the @code{attach} command (@pxref{Attach, ,Debugging an already-running
8442process}).
c906108c 8443
6d2ebf8b 8444@node Target Commands
c906108c
SS
8445@section Commands for managing targets
8446
8447@table @code
8448@item target @var{type} @var{parameters}
7a292a7a
SS
8449Connects the @value{GDBN} host environment to a target machine or
8450process. A target is typically a protocol for talking to debugging
8451facilities. You use the argument @var{type} to specify the type or
8452protocol of the target machine.
c906108c
SS
8453
8454Further @var{parameters} are interpreted by the target protocol, but
8455typically include things like device names or host names to connect
8456with, process numbers, and baud rates.
c906108c
SS
8457
8458The @code{target} command does not repeat if you press @key{RET} again
8459after executing the command.
8460
8461@kindex help target
8462@item help target
8463Displays the names of all targets available. To display targets
8464currently selected, use either @code{info target} or @code{info files}
8465(@pxref{Files, ,Commands to specify files}).
8466
8467@item help target @var{name}
8468Describe a particular target, including any parameters necessary to
8469select it.
8470
8471@kindex set gnutarget
8472@item set gnutarget @var{args}
5d161b24 8473@value{GDBN} uses its own library BFD to read your files. @value{GDBN}
c906108c 8474knows whether it is reading an @dfn{executable},
5d161b24
DB
8475a @dfn{core}, or a @dfn{.o} file; however, you can specify the file format
8476with the @code{set gnutarget} command. Unlike most @code{target} commands,
c906108c
SS
8477with @code{gnutarget} the @code{target} refers to a program, not a machine.
8478
d4f3574e 8479@quotation
c906108c
SS
8480@emph{Warning:} To specify a file format with @code{set gnutarget},
8481you must know the actual BFD name.
d4f3574e 8482@end quotation
c906108c 8483
d4f3574e
SS
8484@noindent
8485@xref{Files, , Commands to specify files}.
c906108c 8486
5d161b24 8487@kindex show gnutarget
c906108c
SS
8488@item show gnutarget
8489Use the @code{show gnutarget} command to display what file format
8490@code{gnutarget} is set to read. If you have not set @code{gnutarget},
8491@value{GDBN} will determine the file format for each file automatically,
8492and @code{show gnutarget} displays @samp{The current BDF target is "auto"}.
8493@end table
8494
c906108c
SS
8495Here are some common targets (available, or not, depending on the GDB
8496configuration):
c906108c
SS
8497
8498@table @code
8499@kindex target exec
8500@item target exec @var{program}
8501An executable file. @samp{target exec @var{program}} is the same as
8502@samp{exec-file @var{program}}.
8503
c906108c
SS
8504@kindex target core
8505@item target core @var{filename}
8506A core dump file. @samp{target core @var{filename}} is the same as
8507@samp{core-file @var{filename}}.
c906108c
SS
8508
8509@kindex target remote
8510@item target remote @var{dev}
8511Remote serial target in GDB-specific protocol. The argument @var{dev}
8512specifies what serial device to use for the connection (e.g.
8513@file{/dev/ttya}). @xref{Remote, ,Remote debugging}. @code{target remote}
d4f3574e 8514supports the @code{load} command. This is only useful if you have
c906108c
SS
8515some other way of getting the stub to the target system, and you can put
8516it somewhere in memory where it won't get clobbered by the download.
8517
c906108c
SS
8518@kindex target sim
8519@item target sim
2df3850c 8520Builtin CPU simulator. @value{GDBN} includes simulators for most architectures.
104c1213
JM
8521In general,
8522@example
8523 target sim
8524 load
8525 run
8526@end example
d4f3574e 8527@noindent
104c1213 8528works; however, you cannot assume that a specific memory map, device
d4f3574e 8529drivers, or even basic I/O is available, although some simulators do
104c1213
JM
8530provide these. For info about any processor-specific simulator details,
8531see the appropriate section in @ref{Embedded Processors, ,Embedded
8532Processors}.
8533
c906108c
SS
8534@end table
8535
104c1213 8536Some configurations may include these targets as well:
c906108c
SS
8537
8538@table @code
8539
c906108c
SS
8540@kindex target nrom
8541@item target nrom @var{dev}
8542NetROM ROM emulator. This target only supports downloading.
8543
c906108c
SS
8544@end table
8545
5d161b24 8546Different targets are available on different configurations of @value{GDBN};
c906108c 8547your configuration may have more or fewer targets.
c906108c
SS
8548
8549Many remote targets require you to download the executable's code
8550once you've successfully established a connection.
8551
8552@table @code
8553
8554@kindex load @var{filename}
8555@item load @var{filename}
c906108c
SS
8556Depending on what remote debugging facilities are configured into
8557@value{GDBN}, the @code{load} command may be available. Where it exists, it
8558is meant to make @var{filename} (an executable) available for debugging
8559on the remote system---by downloading, or dynamic linking, for example.
8560@code{load} also records the @var{filename} symbol table in @value{GDBN}, like
8561the @code{add-symbol-file} command.
8562
8563If your @value{GDBN} does not have a @code{load} command, attempting to
8564execute it gets the error message ``@code{You can't do that when your
8565target is @dots{}}''
c906108c
SS
8566
8567The file is loaded at whatever address is specified in the executable.
8568For some object file formats, you can specify the load address when you
8569link the program; for other formats, like a.out, the object file format
8570specifies a fixed address.
8571@c FIXME! This would be a good place for an xref to the GNU linker doc.
8572
c906108c
SS
8573@code{load} does not repeat if you press @key{RET} again after using it.
8574@end table
8575
6d2ebf8b 8576@node Byte Order
c906108c 8577@section Choosing target byte order
7a292a7a 8578
c906108c
SS
8579@cindex choosing target byte order
8580@cindex target byte order
c906108c
SS
8581
8582Some types of processors, such as the MIPS, PowerPC, and Hitachi SH,
8583offer the ability to run either big-endian or little-endian byte
8584orders. Usually the executable or symbol will include a bit to
8585designate the endian-ness, and you will not need to worry about
8586which to use. However, you may still find it useful to adjust
d4f3574e 8587@value{GDBN}'s idea of processor endian-ness manually.
c906108c
SS
8588
8589@table @code
8590@kindex set endian big
8591@item set endian big
8592Instruct @value{GDBN} to assume the target is big-endian.
8593
8594@kindex set endian little
8595@item set endian little
8596Instruct @value{GDBN} to assume the target is little-endian.
8597
8598@kindex set endian auto
8599@item set endian auto
8600Instruct @value{GDBN} to use the byte order associated with the
8601executable.
8602
8603@item show endian
8604Display @value{GDBN}'s current idea of the target byte order.
8605
8606@end table
8607
8608Note that these commands merely adjust interpretation of symbolic
8609data on the host, and that they have absolutely no effect on the
8610target system.
8611
6d2ebf8b 8612@node Remote
c906108c
SS
8613@section Remote debugging
8614@cindex remote debugging
8615
8616If you are trying to debug a program running on a machine that cannot run
5d161b24
DB
8617@value{GDBN} in the usual way, it is often useful to use remote debugging.
8618For example, you might use remote debugging on an operating system kernel,
c906108c
SS
8619or on a small system which does not have a general purpose operating system
8620powerful enough to run a full-featured debugger.
8621
8622Some configurations of @value{GDBN} have special serial or TCP/IP interfaces
8623to make this work with particular debugging targets. In addition,
5d161b24 8624@value{GDBN} comes with a generic serial protocol (specific to @value{GDBN},
c906108c
SS
8625but not specific to any particular target system) which you can use if you
8626write the remote stubs---the code that runs on the remote system to
8627communicate with @value{GDBN}.
8628
8629Other remote targets may be available in your
8630configuration of @value{GDBN}; use @code{help target} to list them.
c906108c 8631
c906108c 8632@menu
c906108c 8633* Remote Serial:: @value{GDBN} remote serial protocol
c906108c
SS
8634@end menu
8635
6d2ebf8b 8636@node Remote Serial
104c1213 8637@subsection The @value{GDBN} remote serial protocol
7a292a7a 8638
104c1213
JM
8639@cindex remote serial debugging, overview
8640To debug a program running on another machine (the debugging
8641@dfn{target} machine), you must first arrange for all the usual
8642prerequisites for the program to run by itself. For example, for a C
8643program, you need:
c906108c 8644
104c1213
JM
8645@enumerate
8646@item
8647A startup routine to set up the C runtime environment; these usually
8648have a name like @file{crt0}. The startup routine may be supplied by
8649your hardware supplier, or you may have to write your own.
96baa820 8650
5d161b24 8651@item
d4f3574e 8652A C subroutine library to support your program's
104c1213 8653subroutine calls, notably managing input and output.
96baa820 8654
104c1213
JM
8655@item
8656A way of getting your program to the other machine---for example, a
8657download program. These are often supplied by the hardware
8658manufacturer, but you may have to write your own from hardware
8659documentation.
8660@end enumerate
96baa820 8661
104c1213
JM
8662The next step is to arrange for your program to use a serial port to
8663communicate with the machine where @value{GDBN} is running (the @dfn{host}
8664machine). In general terms, the scheme looks like this:
96baa820 8665
104c1213
JM
8666@table @emph
8667@item On the host,
8668@value{GDBN} already understands how to use this protocol; when everything
8669else is set up, you can simply use the @samp{target remote} command
8670(@pxref{Targets,,Specifying a Debugging Target}).
8671
8672@item On the target,
8673you must link with your program a few special-purpose subroutines that
8674implement the @value{GDBN} remote serial protocol. The file containing these
8675subroutines is called a @dfn{debugging stub}.
8676
8677On certain remote targets, you can use an auxiliary program
8678@code{gdbserver} instead of linking a stub into your program.
8679@xref{Server,,Using the @code{gdbserver} program}, for details.
8680@end table
96baa820 8681
104c1213
JM
8682The debugging stub is specific to the architecture of the remote
8683machine; for example, use @file{sparc-stub.c} to debug programs on
8684@sc{sparc} boards.
96baa820 8685
104c1213
JM
8686@cindex remote serial stub list
8687These working remote stubs are distributed with @value{GDBN}:
96baa820 8688
104c1213
JM
8689@table @code
8690
8691@item i386-stub.c
41afff9a 8692@cindex @file{i386-stub.c}
104c1213
JM
8693@cindex Intel
8694@cindex i386
8695For Intel 386 and compatible architectures.
8696
8697@item m68k-stub.c
41afff9a 8698@cindex @file{m68k-stub.c}
104c1213
JM
8699@cindex Motorola 680x0
8700@cindex m680x0
8701For Motorola 680x0 architectures.
8702
8703@item sh-stub.c
41afff9a 8704@cindex @file{sh-stub.c}
104c1213
JM
8705@cindex Hitachi
8706@cindex SH
8707For Hitachi SH architectures.
8708
8709@item sparc-stub.c
41afff9a 8710@cindex @file{sparc-stub.c}
104c1213
JM
8711@cindex Sparc
8712For @sc{sparc} architectures.
8713
8714@item sparcl-stub.c
41afff9a 8715@cindex @file{sparcl-stub.c}
104c1213
JM
8716@cindex Fujitsu
8717@cindex SparcLite
8718For Fujitsu @sc{sparclite} architectures.
8719
8720@end table
8721
8722The @file{README} file in the @value{GDBN} distribution may list other
8723recently added stubs.
8724
8725@menu
8726* Stub Contents:: What the stub can do for you
8727* Bootstrapping:: What you must do for the stub
8728* Debug Session:: Putting it all together
8729* Protocol:: Definition of the communication protocol
8730* Server:: Using the `gdbserver' program
8731* NetWare:: Using the `gdbserve.nlm' program
8732@end menu
8733
6d2ebf8b 8734@node Stub Contents
104c1213
JM
8735@subsubsection What the stub can do for you
8736
8737@cindex remote serial stub
8738The debugging stub for your architecture supplies these three
8739subroutines:
8740
8741@table @code
8742@item set_debug_traps
8743@kindex set_debug_traps
8744@cindex remote serial stub, initialization
8745This routine arranges for @code{handle_exception} to run when your
8746program stops. You must call this subroutine explicitly near the
8747beginning of your program.
8748
8749@item handle_exception
8750@kindex handle_exception
8751@cindex remote serial stub, main routine
8752This is the central workhorse, but your program never calls it
8753explicitly---the setup code arranges for @code{handle_exception} to
8754run when a trap is triggered.
8755
8756@code{handle_exception} takes control when your program stops during
8757execution (for example, on a breakpoint), and mediates communications
8758with @value{GDBN} on the host machine. This is where the communications
8759protocol is implemented; @code{handle_exception} acts as the @value{GDBN}
d4f3574e 8760representative on the target machine. It begins by sending summary
104c1213
JM
8761information on the state of your program, then continues to execute,
8762retrieving and transmitting any information @value{GDBN} needs, until you
8763execute a @value{GDBN} command that makes your program resume; at that point,
8764@code{handle_exception} returns control to your own code on the target
5d161b24 8765machine.
104c1213
JM
8766
8767@item breakpoint
8768@cindex @code{breakpoint} subroutine, remote
8769Use this auxiliary subroutine to make your program contain a
8770breakpoint. Depending on the particular situation, this may be the only
8771way for @value{GDBN} to get control. For instance, if your target
8772machine has some sort of interrupt button, you won't need to call this;
8773pressing the interrupt button transfers control to
8774@code{handle_exception}---in effect, to @value{GDBN}. On some machines,
8775simply receiving characters on the serial port may also trigger a trap;
8776again, in that situation, you don't need to call @code{breakpoint} from
8777your own program---simply running @samp{target remote} from the host
5d161b24 8778@value{GDBN} session gets control.
104c1213
JM
8779
8780Call @code{breakpoint} if none of these is true, or if you simply want
8781to make certain your program stops at a predetermined point for the
8782start of your debugging session.
8783@end table
8784
6d2ebf8b 8785@node Bootstrapping
104c1213
JM
8786@subsubsection What you must do for the stub
8787
8788@cindex remote stub, support routines
8789The debugging stubs that come with @value{GDBN} are set up for a particular
8790chip architecture, but they have no information about the rest of your
8791debugging target machine.
8792
8793First of all you need to tell the stub how to communicate with the
8794serial port.
8795
8796@table @code
8797@item int getDebugChar()
8798@kindex getDebugChar
8799Write this subroutine to read a single character from the serial port.
8800It may be identical to @code{getchar} for your target system; a
8801different name is used to allow you to distinguish the two if you wish.
8802
8803@item void putDebugChar(int)
8804@kindex putDebugChar
8805Write this subroutine to write a single character to the serial port.
5d161b24 8806It may be identical to @code{putchar} for your target system; a
104c1213
JM
8807different name is used to allow you to distinguish the two if you wish.
8808@end table
8809
8810@cindex control C, and remote debugging
8811@cindex interrupting remote targets
8812If you want @value{GDBN} to be able to stop your program while it is
8813running, you need to use an interrupt-driven serial driver, and arrange
8814for it to stop when it receives a @code{^C} (@samp{\003}, the control-C
8815character). That is the character which @value{GDBN} uses to tell the
8816remote system to stop.
8817
8818Getting the debugging target to return the proper status to @value{GDBN}
8819probably requires changes to the standard stub; one quick and dirty way
8820is to just execute a breakpoint instruction (the ``dirty'' part is that
8821@value{GDBN} reports a @code{SIGTRAP} instead of a @code{SIGINT}).
8822
8823Other routines you need to supply are:
8824
8825@table @code
8826@item void exceptionHandler (int @var{exception_number}, void *@var{exception_address})
8827@kindex exceptionHandler
8828Write this function to install @var{exception_address} in the exception
8829handling tables. You need to do this because the stub does not have any
8830way of knowing what the exception handling tables on your target system
8831are like (for example, the processor's table might be in @sc{rom},
8832containing entries which point to a table in @sc{ram}).
8833@var{exception_number} is the exception number which should be changed;
8834its meaning is architecture-dependent (for example, different numbers
8835might represent divide by zero, misaligned access, etc). When this
8836exception occurs, control should be transferred directly to
8837@var{exception_address}, and the processor state (stack, registers,
8838and so on) should be just as it is when a processor exception occurs. So if
8839you want to use a jump instruction to reach @var{exception_address}, it
8840should be a simple jump, not a jump to subroutine.
8841
8842For the 386, @var{exception_address} should be installed as an interrupt
8843gate so that interrupts are masked while the handler runs. The gate
8844should be at privilege level 0 (the most privileged level). The
8845@sc{sparc} and 68k stubs are able to mask interrupts themselves without
8846help from @code{exceptionHandler}.
8847
8848@item void flush_i_cache()
8849@kindex flush_i_cache
d4f3574e 8850On @sc{sparc} and @sc{sparclite} only, write this subroutine to flush the
104c1213
JM
8851instruction cache, if any, on your target machine. If there is no
8852instruction cache, this subroutine may be a no-op.
8853
8854On target machines that have instruction caches, @value{GDBN} requires this
8855function to make certain that the state of your program is stable.
8856@end table
8857
8858@noindent
8859You must also make sure this library routine is available:
8860
8861@table @code
8862@item void *memset(void *, int, int)
8863@kindex memset
8864This is the standard library function @code{memset} that sets an area of
8865memory to a known value. If you have one of the free versions of
8866@code{libc.a}, @code{memset} can be found there; otherwise, you must
8867either obtain it from your hardware manufacturer, or write your own.
8868@end table
8869
8870If you do not use the GNU C compiler, you may need other standard
8871library subroutines as well; this varies from one stub to another,
8872but in general the stubs are likely to use any of the common library
d4f3574e 8873subroutines which @code{@value{GCC}} generates as inline code.
104c1213
JM
8874
8875
6d2ebf8b 8876@node Debug Session
104c1213
JM
8877@subsubsection Putting it all together
8878
8879@cindex remote serial debugging summary
8880In summary, when your program is ready to debug, you must follow these
8881steps.
8882
8883@enumerate
8884@item
6d2ebf8b 8885Make sure you have defined the supporting low-level routines
104c1213
JM
8886(@pxref{Bootstrapping,,What you must do for the stub}):
8887@display
8888@code{getDebugChar}, @code{putDebugChar},
8889@code{flush_i_cache}, @code{memset}, @code{exceptionHandler}.
8890@end display
8891
8892@item
8893Insert these lines near the top of your program:
8894
8895@example
8896set_debug_traps();
8897breakpoint();
8898@end example
8899
8900@item
8901For the 680x0 stub only, you need to provide a variable called
8902@code{exceptionHook}. Normally you just use:
8903
8904@example
8905void (*exceptionHook)() = 0;
8906@end example
8907
d4f3574e 8908@noindent
104c1213 8909but if before calling @code{set_debug_traps}, you set it to point to a
598ca718 8910function in your program, that function is called when
104c1213
JM
8911@code{@value{GDBN}} continues after stopping on a trap (for example, bus
8912error). The function indicated by @code{exceptionHook} is called with
8913one parameter: an @code{int} which is the exception number.
8914
8915@item
8916Compile and link together: your program, the @value{GDBN} debugging stub for
8917your target architecture, and the supporting subroutines.
8918
8919@item
8920Make sure you have a serial connection between your target machine and
8921the @value{GDBN} host, and identify the serial port on the host.
8922
8923@item
8924@c The "remote" target now provides a `load' command, so we should
8925@c document that. FIXME.
8926Download your program to your target machine (or get it there by
8927whatever means the manufacturer provides), and start it.
8928
8929@item
8930To start remote debugging, run @value{GDBN} on the host machine, and specify
8931as an executable file the program that is running in the remote machine.
8932This tells @value{GDBN} how to find your program's symbols and the contents
8933of its pure text.
8934
d4f3574e 8935@item
104c1213 8936@cindex serial line, @code{target remote}
d4f3574e 8937Establish communication using the @code{target remote} command.
104c1213
JM
8938Its argument specifies how to communicate with the target
8939machine---either via a devicename attached to a direct serial line, or a
8940TCP port (usually to a terminal server which in turn has a serial line
8941to the target). For example, to use a serial line connected to the
8942device named @file{/dev/ttyb}:
8943
8944@example
8945target remote /dev/ttyb
8946@end example
8947
8948@cindex TCP port, @code{target remote}
8949To use a TCP connection, use an argument of the form
8950@code{@var{host}:port}. For example, to connect to port 2828 on a
8951terminal server named @code{manyfarms}:
8952
8953@example
8954target remote manyfarms:2828
8955@end example
8956@end enumerate
8957
8958Now you can use all the usual commands to examine and change data and to
8959step and continue the remote program.
8960
8961To resume the remote program and stop debugging it, use the @code{detach}
8962command.
8963
8964@cindex interrupting remote programs
8965@cindex remote programs, interrupting
8966Whenever @value{GDBN} is waiting for the remote program, if you type the
8967interrupt character (often @key{C-C}), @value{GDBN} attempts to stop the
8968program. This may or may not succeed, depending in part on the hardware
8969and the serial drivers the remote system uses. If you type the
8970interrupt character once again, @value{GDBN} displays this prompt:
8971
8972@example
8973Interrupted while waiting for the program.
8974Give up (and stop debugging it)? (y or n)
8975@end example
8976
8977If you type @kbd{y}, @value{GDBN} abandons the remote debugging session.
8978(If you decide you want to try again later, you can use @samp{target
8979remote} again to connect once more.) If you type @kbd{n}, @value{GDBN}
8980goes back to waiting.
8981
6d2ebf8b 8982@node Protocol
104c1213
JM
8983@subsubsection Communication protocol
8984
8985@cindex debugging stub, example
8986@cindex remote stub, example
8987@cindex stub example, remote debugging
8988The stub files provided with @value{GDBN} implement the target side of the
8989communication protocol, and the @value{GDBN} side is implemented in the
8990@value{GDBN} source file @file{remote.c}. Normally, you can simply allow
8991these subroutines to communicate, and ignore the details. (If you're
8992implementing your own stub file, you can still ignore the details: start
8993with one of the existing stub files. @file{sparc-stub.c} is the best
8994organized, and therefore the easiest to read.)
8995
8996However, there may be occasions when you need to know something about
8997the protocol---for example, if there is only one serial port to your
8998target machine, you might want your program to do something special if
8999it recognizes a packet meant for @value{GDBN}.
9000
9001In the examples below, @samp{<-} and @samp{->} are used to indicate
9002transmitted and received data respectfully.
9003
9004@cindex protocol, @value{GDBN} remote serial
9005@cindex serial protocol, @value{GDBN} remote
9006@cindex remote serial protocol
6cf7e474
AC
9007All @value{GDBN} commands and responses (other than acknowledgments) are
9008sent as a @var{packet}. A @var{packet} is introduced with the character
9009@samp{$}, the actual @var{packet-data}, and the terminating character
9010@samp{#} followed by a two-digit @var{checksum}:
104c1213
JM
9011
9012@example
9013@code{$}@var{packet-data}@code{#}@var{checksum}
9014@end example
9015@noindent
104c1213
JM
9016
9017@cindex checksum, for @value{GDBN} remote
9018@noindent
9019The two-digit @var{checksum} is computed as the modulo 256 sum of all
6cf7e474
AC
9020characters between the leading @samp{$} and the trailing @samp{#} (an
9021eight bit unsigned checksum).
9022
9023Implementors should note that prior to @value{GDBN} 5.0 the protocol
9024specification also included an optional two-digit @var{sequence-id}:
9025
9026@example
9027@code{$}@var{sequence-id}@code{:}@var{packet-data}@code{#}@var{checksum}
9028@end example
104c1213
JM
9029
9030@cindex sequence-id, for @value{GDBN} remote
9031@noindent
6cf7e474
AC
9032That @var{sequence-id} was appended to the acknowledgment. @value{GDBN}
9033has never output @var{sequence-id}s. Stubs that handle packets added
9034since @value{GDBN} 5.0 must not accept @var{sequence-id}.
104c1213 9035
6cf7e474 9036@cindex acknowledgment, for @value{GDBN} remote
104c1213
JM
9037When either the host or the target machine receives a packet, the first
9038response expected is an acknowledgment: either @samp{+} (to indicate
9039the package was received correctly) or @samp{-} (to request
9040retransmission):
9041
9042@example
9043<- @code{$}@var{packet-data}@code{#}@var{checksum}
9044-> @code{+}
9045@end example
9046@noindent
104c1213
JM
9047
9048The host (@value{GDBN}) sends @var{command}s, and the target (the
9049debugging stub incorporated in your program) sends a @var{response}. In
9050the case of step and continue @var{command}s, the response is only sent
9051when the operation has completed (the target has again stopped).
9052
9053@var{packet-data} consists of a sequence of characters with the
6cf7e474
AC
9054exception of @samp{#} and @samp{$} (see @samp{X} packet for additional
9055exceptions).
9056
9057Fields within the packet should be separated using @samp{,} @samp{;} or
9058@samp{:}. Except where otherwise noted all numbers are represented in
9059HEX with leading zeros suppressed.
9060
9061Implementors should note that prior to @value{GDBN} 5.0, the character
9062@samp{:} could not appear as the third character in a packet (as it
9063would potentially conflict with the @var{sequence-id}).
104c1213
JM
9064
9065Response @var{data} can be run-length encoded to save space. A @samp{*}
c3f6f71d 9066means that the next character is an @sc{ascii} encoding giving a repeat count
104c1213
JM
9067which stands for that many repetitions of the character preceding the
9068@samp{*}. The encoding is @code{n+29}, yielding a printable character
d4f3574e
SS
9069where @code{n >=3} (which is where rle starts to win). The printable
9070characters @samp{$}, @samp{#}, @samp{+} and @samp{-} or with a numeric
9071value greater than 126 should not be used.
9072
9073Some remote systems have used a different run-length encoding mechanism
9074loosely refered to as the cisco encoding. Following the @samp{*}
9075character are two hex digits that indicate the size of the packet.
104c1213
JM
9076
9077So:
9078@example
9079"@code{0* }"
9080@end example
9081@noindent
9082means the same as "0000".
9083
598ca718 9084The error response returned for some packets includes a two character
104c1213
JM
9085error number. That number is not well defined.
9086
9087For any @var{command} not supported by the stub, an empty response
9088(@samp{$#00}) should be returned. That way it is possible to extend the
9089protocol. A newer @value{GDBN} can tell if a packet is supported based
d4f3574e 9090on that response.
104c1213 9091
f1251bdd
C
9092A stub is required to support the @samp{g}, @samp{G}, @samp{m}, @samp{M},
9093@samp{c}, and @samp{s} @var{command}s. All other @var{command}s are
9094optional.
9095
104c1213
JM
9096Below is a complete list of all currently defined @var{command}s and
9097their corresponding response @var{data}:
598ca718 9098@page
104c1213
JM
9099@multitable @columnfractions .30 .30 .40
9100@item Packet
9101@tab Request
9102@tab Description
9103
f1251bdd 9104@item extended ops
104c1213
JM
9105@tab @code{!}
9106@tab
d4f3574e 9107Use the extended remote protocol. Sticky---only needs to be set once.
598ca718 9108The extended remote protocol supports the @samp{R} packet.
104c1213
JM
9109@item
9110@tab reply @samp{}
9111@tab
9112Stubs that support the extended remote protocol return @samp{} which,
9113unfortunately, is identical to the response returned by stubs that do not
9114support protocol extensions.
9115
9116@item last signal
9117@tab @code{?}
9118@tab
d4f3574e
SS
9119Indicate the reason the target halted. The reply is the same as for step
9120and continue.
9121@item
9122@tab reply
9123@tab see below
9124
104c1213
JM
9125
9126@item reserved
9127@tab @code{a}
5d161b24 9128@tab Reserved for future use
104c1213 9129
f1251bdd 9130@item set program arguments @strong{(reserved)}
104c1213
JM
9131@tab @code{A}@var{arglen}@code{,}@var{argnum}@code{,}@var{arg}@code{,...}
9132@tab
598ca718
EZ
9133@item
9134@tab
9135@tab
104c1213
JM
9136Initialized @samp{argv[]} array passed into program. @var{arglen}
9137specifies the number of bytes in the hex encoded byte stream @var{arg}.
d4f3574e 9138See @file{gdbserver} for more details.
104c1213
JM
9139@item
9140@tab reply @code{OK}
9141@item
9142@tab reply @code{E}@var{NN}
9143
9144@item set baud @strong{(deprecated)}
9145@tab @code{b}@var{baud}
9146@tab
9147Change the serial line speed to @var{baud}. JTC: @emph{When does the
9148transport layer state change? When it's received, or after the ACK is
9149transmitted. In either case, there are problems if the command or the
9150acknowledgment packet is dropped.} Stan: @emph{If people really wanted
9151to add something like this, and get it working for the first time, they
9152ought to modify ser-unix.c to send some kind of out-of-band message to a
9153specially-setup stub and have the switch happen "in between" packets, so
9154that from remote protocol's point of view, nothing actually
9155happened.}
9156
9157@item set breakpoint @strong{(deprecated)}
9158@tab @code{B}@var{addr},@var{mode}
9159@tab
9160Set (@var{mode} is @samp{S}) or clear (@var{mode} is @samp{C}) a
9161breakpoint at @var{addr}. @emph{This has been replaced by the @samp{Z} and
9162@samp{z} packets.}
9163
9164@item continue
9165@tab @code{c}@var{addr}
9166@tab
9167@var{addr} is address to resume. If @var{addr} is omitted, resume at
9168current address.
9169@item
9170@tab reply
9171@tab see below
9172
f1251bdd 9173@item continue with signal
104c1213
JM
9174@tab @code{C}@var{sig}@code{;}@var{addr}
9175@tab
9176Continue with signal @var{sig} (hex signal number). If
9177@code{;}@var{addr} is omitted, resume at same address.
9178@item
9179@tab reply
9180@tab see below
9181
598ca718 9182@item toggle debug @strong{(deprecated)}
104c1213
JM
9183@tab @code{d}
9184@tab
d4f3574e 9185toggle debug flag.
104c1213 9186
f1251bdd 9187@item detach
104c1213 9188@tab @code{D}
d4f3574e 9189@tab
2df3850c
JM
9190Detach @value{GDBN} from the remote system. Sent to the remote target before
9191@value{GDBN} disconnects.
d4f3574e
SS
9192@item
9193@tab reply @emph{no response}
9194@tab
598ca718 9195@value{GDBN} does not check for any response after sending this packet.
104c1213
JM
9196
9197@item reserved
9198@tab @code{e}
5d161b24 9199@tab Reserved for future use
104c1213
JM
9200
9201@item reserved
9202@tab @code{E}
5d161b24 9203@tab Reserved for future use
104c1213
JM
9204
9205@item reserved
9206@tab @code{f}
5d161b24 9207@tab Reserved for future use
104c1213
JM
9208
9209@item reserved
9210@tab @code{F}
5d161b24 9211@tab Reserved for future use
104c1213
JM
9212
9213@item read registers
9214@tab @code{g}
9215@tab Read general registers.
9216@item
9217@tab reply @var{XX...}
9218@tab
9219Each byte of register data is described by two hex digits. The bytes
9220with the register are transmitted in target byte order. The size of
d4f3574e 9221each register and their position within the @samp{g} @var{packet} are
2df3850c 9222determined by the @value{GDBN} internal macros @var{REGISTER_RAW_SIZE} and
d4f3574e
SS
9223@var{REGISTER_NAME} macros. The specification of several standard
9224@code{g} packets is specified below.
104c1213
JM
9225@item
9226@tab @code{E}@var{NN}
9227@tab for an error.
9228
9229@item write regs
9230@tab @code{G}@var{XX...}
9231@tab
9232See @samp{g} for a description of the @var{XX...} data.
9233@item
9234@tab reply @code{OK}
9235@tab for success
9236@item
9237@tab reply @code{E}@var{NN}
9238@tab for an error
9239
9240@item reserved
9241@tab @code{h}
5d161b24 9242@tab Reserved for future use
104c1213 9243
f1251bdd 9244@item set thread
104c1213
JM
9245@tab @code{H}@var{c}@var{t...}
9246@tab
d4f3574e
SS
9247Set thread for subsequent operations (@samp{m}, @samp{M}, @samp{g},
9248@samp{G}, et.al.). @var{c} = @samp{c} for thread used in step and
9249continue; @var{t...} can be -1 for all threads. @var{c} = @samp{g} for
9250thread used in other operations. If zero, pick a thread, any thread.
104c1213
JM
9251@item
9252@tab reply @code{OK}
9253@tab for success
9254@item
9255@tab reply @code{E}@var{NN}
9256@tab for an error
9257
d4f3574e
SS
9258@c FIXME: JTC:
9259@c 'H': How restrictive (or permissive) is the thread model. If a
5d161b24 9260@c thread is selected and stopped, are other threads allowed
d4f3574e
SS
9261@c to continue to execute? As I mentioned above, I think the
9262@c semantics of each command when a thread is selected must be
9263@c described. For example:
9264@c
9265@c 'g': If the stub supports threads and a specific thread is
9266@c selected, returns the register block from that thread;
9267@c otherwise returns current registers.
9268@c
9269@c 'G' If the stub supports threads and a specific thread is
9270@c selected, sets the registers of the register block of
9271@c that thread; otherwise sets current registers.
9272
f1251bdd 9273@item cycle step @strong{(draft)}
104c1213
JM
9274@tab @code{i}@var{addr}@code{,}@var{nnn}
9275@tab
9276Step the remote target by a single clock cycle. If @code{,}@var{nnn} is
9277present, cycle step @var{nnn} cycles. If @var{addr} is present, cycle
9278step starting at that address.
9279
f1251bdd 9280@item signal then cycle step @strong{(reserved)}
104c1213
JM
9281@tab @code{I}
9282@tab
9283See @samp{i} and @samp{S} for likely syntax and semantics.
9284
9285@item reserved
9286@tab @code{j}
9287@tab Reserved for future use
9288
9289@item reserved
9290@tab @code{J}
5d161b24 9291@tab Reserved for future use
104c1213 9292
f1251bdd 9293@item kill request
104c1213
JM
9294@tab @code{k}
9295@tab
d4f3574e
SS
9296FIXME: @emph{There is no description of how operate when a specific
9297thread context has been selected (ie. does 'k' kill only that thread?)}.
104c1213
JM
9298
9299@item reserved
9300@tab @code{l}
5d161b24 9301@tab Reserved for future use
104c1213
JM
9302
9303@item reserved
9304@tab @code{L}
5d161b24 9305@tab Reserved for future use
104c1213
JM
9306
9307@item read memory
9308@tab @code{m}@var{addr}@code{,}@var{length}
9309@tab
9310Read @var{length} bytes of memory starting at address @var{addr}.
2df3850c 9311Neither @value{GDBN} nor the stub assume that sized memory transfers are assumed
d4f3574e
SS
9312using word alligned accesses. FIXME: @emph{A word aligned memory
9313transfer mechanism is needed.}
104c1213
JM
9314@item
9315@tab reply @var{XX...}
9316@tab
d4f3574e 9317@var{XX...} is mem contents. Can be fewer bytes than requested if able
2df3850c 9318to read only part of the data. Neither @value{GDBN} nor the stub assume that
d4f3574e
SS
9319sized memory transfers are assumed using word alligned accesses. FIXME:
9320@emph{A word aligned memory transfer mechanism is needed.}
104c1213
JM
9321@item
9322@tab reply @code{E}@var{NN}
9323@tab @var{NN} is errno
9324
9325@item write mem
9326@tab @code{M}@var{addr},@var{length}@code{:}@var{XX...}
9327@tab
9328Write @var{length} bytes of memory starting at address @var{addr}.
9329@var{XX...} is the data.
9330@item
9331@tab reply @code{OK}
9332@tab for success
9333@item
9334@tab reply @code{E}@var{NN}
9335@tab
9336for an error (this includes the case where only part of the data was
9337written).
9338
9339@item reserved
9340@tab @code{n}
5d161b24 9341@tab Reserved for future use
104c1213
JM
9342
9343@item reserved
9344@tab @code{N}
5d161b24 9345@tab Reserved for future use
104c1213
JM
9346
9347@item reserved
9348@tab @code{o}
5d161b24 9349@tab Reserved for future use
104c1213
JM
9350
9351@item reserved
9352@tab @code{O}
5d161b24 9353@tab Reserved for future use
104c1213
JM
9354
9355@item read reg @strong{(reserved)}
9356@tab @code{p}@var{n...}
9357@tab
9358See write register.
9359@item
9360@tab return @var{r....}
9361@tab The hex encoded value of the register in target byte order.
9362
f1251bdd 9363@item write reg
104c1213
JM
9364@tab @code{P}@var{n...}@code{=}@var{r...}
9365@tab
9366Write register @var{n...} with value @var{r...}, which contains two hex
9367digits for each byte in the register (target byte order).
9368@item
9369@tab reply @code{OK}
9370@tab for success
9371@item
9372@tab reply @code{E}@var{NN}
9373@tab for an error
9374
f1251bdd 9375@item general query
104c1213
JM
9376@tab @code{q}@var{query}
9377@tab
598ca718 9378Request info about @var{query}. In general @value{GDBN} queries
104c1213 9379have a leading upper case letter. Custom vendor queries should use a
d4f3574e
SS
9380company prefix (in lower case) ex: @samp{qfsf.var}. @var{query} may
9381optionally be followed by a @samp{,} or @samp{;} separated list. Stubs
9382must ensure that they match the full @var{query} name.
104c1213
JM
9383@item
9384@tab reply @code{XX...}
d4f3574e 9385@tab Hex encoded data from query. The reply can not be empty.
104c1213
JM
9386@item
9387@tab reply @code{E}@var{NN}
9388@tab error reply
9389@item
9390@tab reply @samp{}
9391@tab Indicating an unrecognized @var{query}.
9392
f1251bdd 9393@item general set
104c1213
JM
9394@tab @code{Q}@var{var}@code{=}@var{val}
9395@tab
9396Set value of @var{var} to @var{val}. See @samp{q} for a discussing of
9397naming conventions.
9398
598ca718 9399@item reset @strong{(deprecated)}
d4f3574e
SS
9400@tab @code{r}
9401@tab
9402Reset the entire system.
104c1213 9403
f1251bdd 9404@item remote restart
104c1213
JM
9405@tab @code{R}@var{XX}
9406@tab
d4f3574e
SS
9407Restart the remote server. @var{XX} while needed has no clear
9408definition. FIXME: @emph{An example interaction explaining how this
9409packet is used in extended-remote mode is needed}.
104c1213 9410
f1251bdd 9411@item step
104c1213
JM
9412@tab @code{s}@var{addr}
9413@tab
9414@var{addr} is address to resume. If @var{addr} is omitted, resume at
9415same address.
9416@item
9417@tab reply
9418@tab see below
9419
f1251bdd 9420@item step with signal
104c1213
JM
9421@tab @code{S}@var{sig}@code{;}@var{addr}
9422@tab
9423Like @samp{C} but step not continue.
9424@item
9425@tab reply
9426@tab see below
9427
f1251bdd 9428@item search
104c1213
JM
9429@tab @code{t}@var{addr}@code{:}@var{PP}@code{,}@var{MM}
9430@tab
9431Search backwards starting at address @var{addr} for a match with pattern
9432@var{PP} and mask @var{MM}. @var{PP} and @var{MM} are 4
d4f3574e 9433bytes. @var{addr} must be at least 3 digits.
104c1213 9434
f1251bdd 9435@item thread alive
104c1213
JM
9436@tab @code{T}@var{XX}
9437@tab Find out if the thread XX is alive.
9438@item
9439@tab reply @code{OK}
9440@tab thread is still alive
9441@item
9442@tab reply @code{E}@var{NN}
9443@tab thread is dead
5d161b24 9444
104c1213
JM
9445@item reserved
9446@tab @code{u}
5d161b24 9447@tab Reserved for future use
104c1213
JM
9448
9449@item reserved
9450@tab @code{U}
5d161b24 9451@tab Reserved for future use
104c1213
JM
9452
9453@item reserved
9454@tab @code{v}
5d161b24 9455@tab Reserved for future use
104c1213
JM
9456
9457@item reserved
9458@tab @code{V}
5d161b24 9459@tab Reserved for future use
104c1213
JM
9460
9461@item reserved
9462@tab @code{w}
5d161b24 9463@tab Reserved for future use
104c1213
JM
9464
9465@item reserved
9466@tab @code{W}
5d161b24 9467@tab Reserved for future use
104c1213
JM
9468
9469@item reserved
9470@tab @code{x}
5d161b24 9471@tab Reserved for future use
104c1213 9472
f1251bdd 9473@item write mem (binary)
104c1213
JM
9474@tab @code{X}@var{addr}@code{,}@var{length}@var{:}@var{XX...}
9475@tab
9476@var{addr} is address, @var{length} is number of bytes, @var{XX...} is
d4f3574e
SS
9477binary data. The characters @code{$}, @code{#}, and @code{0x7d} are
9478escaped using @code{0x7d}.
104c1213
JM
9479@item
9480@tab reply @code{OK}
9481@tab for success
9482@item
9483@tab reply @code{E}@var{NN}
9484@tab for an error
9485
9486@item reserved
9487@tab @code{y}
5d161b24 9488@tab Reserved for future use
104c1213
JM
9489
9490@item reserved
9491@tab @code{Y}
5d161b24 9492@tab Reserved for future use
104c1213 9493
f1251bdd 9494@item remove break or watchpoint @strong{(draft)}
104c1213
JM
9495@tab @code{z}@var{t}@code{,}@var{addr}@code{,}@var{length}
9496@tab
9497See @samp{Z}.
9498
f1251bdd 9499@item insert break or watchpoint @strong{(draft)}
104c1213
JM
9500@tab @code{Z}@var{t}@code{,}@var{addr}@code{,}@var{length}
9501@tab
9502@var{t} is type: @samp{0} - software breakpoint, @samp{1} - hardware
9503breakpoint, @samp{2} - write watchpoint, @samp{3} - read watchpoint,
9504@samp{4} - access watchpoint; @var{addr} is address; @var{length} is in
9505bytes. For a software breakpoint, @var{length} specifies the size of
9506the instruction to be patched. For hardware breakpoints and watchpoints
d4f3574e
SS
9507@var{length} specifies the memory region to be monitored. To avoid
9508potential problems with duplicate packets, the operations should be
6d2ebf8b 9509implemented in an idempotent way.
104c1213
JM
9510@item
9511@tab reply @code{E}@var{NN}
9512@tab for an error
9513@item
9514@tab reply @code{OK}
9515@tab for success
9516@item
9517@tab @samp{}
9518@tab If not supported.
9519
9520@item reserved
9521@tab <other>
5d161b24 9522@tab Reserved for future use
104c1213
JM
9523
9524@end multitable
9525
d4f3574e
SS
9526The @samp{C}, @samp{c}, @samp{S}, @samp{s} and @samp{?} packets can
9527receive any of the below as a reply. In the case of the @samp{C},
9528@samp{c}, @samp{S} and @samp{s} packets, that reply is only returned
9529when the target halts. In the below the exact meaning of @samp{signal
9530number} is poorly defined. In general one of the UNIX signal numbering
9531conventions is used.
104c1213
JM
9532
9533@multitable @columnfractions .4 .6
9534
9535@item @code{S}@var{AA}
9536@tab @var{AA} is the signal number
9537
9538@item @code{T}@var{AA}@var{n...}@code{:}@var{r...}@code{;}@var{n...}@code{:}@var{r...}@code{;}@var{n...}@code{:}@var{r...}@code{;}
9539@tab
9540@var{AA} = two hex digit signal number; @var{n...} = register number
9541(hex), @var{r...} = target byte ordered register contents, size defined
9542by @code{REGISTER_RAW_SIZE}; @var{n...} = @samp{thread}, @var{r...} =
9543thread process ID, this is a hex integer; @var{n...} = other string not
d4f3574e 9544starting with valid hex digit. @value{GDBN} should ignore this
104c1213
JM
9545@var{n...}, @var{r...} pair and go on to the next. This way we can
9546extend the protocol.
9547
9548@item @code{W}@var{AA}
9549@tab
9550The process exited, and @var{AA} is the exit status. This is only
9551applicable for certains sorts of targets.
9552
9553@item @code{X}@var{AA}
9554@tab
9555The process terminated with signal @var{AA}.
9556
6d2ebf8b 9557@item @code{N}@var{AA}@code{;}@var{t...}@code{;}@var{d...}@code{;}@var{b...} @strong{(obsolete)}
104c1213 9558@tab
6d2ebf8b
SS
9559@var{AA} = signal number; @var{t...} = address of symbol "_start";
9560@var{d...} = base of data section; @var{b...} = base of bss section.
9561@emph{Note: only used by Cisco Systems targets. The difference between
9562this reply and the "qOffsets" query is that the 'N' packet may arrive
9563spontaneously whereas the 'qOffsets' is a query initiated by the host
9564debugger.}
104c1213
JM
9565
9566@item @code{O}@var{XX...}
9567@tab
c3f6f71d 9568@var{XX...} is hex encoding of @sc{ascii} data. This can happen at any time
104c1213
JM
9569while the program is running and the debugger should continue to wait
9570for 'W', 'T', etc.
9571
9572@end multitable
9573
d4f3574e
SS
9574The following set and query packets have already been defined.
9575
9576@multitable @columnfractions .2 .2 .6
9577
9578@item current thread
9579@tab @code{q}@code{C}
9580@tab Return the current thread id.
9581@item
9582@tab reply @code{QC}@var{pid}
9583@tab
9584Where @var{pid} is a HEX encoded 16 bit process id.
9585@item
9586@tab reply *
9587@tab Any other reply implies the old pid.
9588
bba2971c
MS
9589@item all thread ids
9590@tab @code{q}@code{fThreadInfo}
9591@item
9592@tab @code{q}@code{sThreadInfo}
d4f3574e 9593@tab
bba2971c
MS
9594Obtain a list of active thread ids from the target (OS). Since there
9595may be too many active threads to fit into one reply packet, this query
9596works iteratively: it may require more than one query/reply sequence to
9597obtain the entire list of threads. The first query of the sequence will
5d161b24 9598be the @code{qf}@code{ThreadInfo} query; subsequent queries in the
bba2971c 9599sequence will be the @code{qs}@code{ThreadInfo} query.
d4f3574e 9600@item
bba2971c
MS
9601@tab
9602@tab NOTE: replaces the @code{qL} query (see below).
d4f3574e 9603@item
5d161b24 9604@tab reply @code{m}@var{<id>}
bba2971c
MS
9605@tab A single thread id
9606@item
00e4a2e4 9607@tab reply @code{m}@var{<id>},@var{<id>...}
bba2971c
MS
9608@tab a comma-separated list of thread ids
9609@item
9610@tab reply @code{l}
9611@tab (lower case 'el') denotes end of list.
9612@item
9613@tab
9614@tab
9615In response to each query, the target will reply with a list of one
9616or more thread ids, in big-endian hex, separated by commas. GDB will
9617respond to each reply with a request for more thread ids (using the
9618@code{qs} form of the query), until the target responds with @code{l}
9619(lower-case el, for @code{'last'}).
9620
9621@item extra thread info
480ff1fb 9622@tab @code{q}@code{ThreadExtraInfo}@code{,}@var{id}
bba2971c
MS
9623@tab
9624@item
9625@tab
9626@tab
9627Where @var{<id>} is a thread-id in big-endian hex.
9628Obtain a printable string description of a thread's attributes from
9629the target OS. This string may contain anything that the target OS
9630thinks is interesting for @value{GDBN} to tell the user about the thread.
9631The string is displayed in @value{GDBN}'s @samp{info threads} display.
5d161b24 9632Some examples of possible thread extra info strings are "Runnable", or
bba2971c
MS
9633"Blocked on Mutex".
9634@item
9635@tab reply @var{XX...}
9636@tab
9637Where @var{XX...} is a hex encoding of @sc{ascii} data, comprising the
9638printable string containing the extra information about the thread's
9639attributes.
d4f3574e
SS
9640
9641@item query @var{LIST} or @var{threadLIST} @strong{(deprecated)}
9642@tab @code{q}@code{L}@var{startflag}@var{threadcount}@var{nextthread}
9643@tab
2b628194
MS
9644@item
9645@tab
9646@tab
d4f3574e
SS
9647Obtain thread information from RTOS. Where: @var{startflag} (one hex
9648digit) is one to indicate the first query and zero to indicate a
9649subsequent query; @var{threadcount} (two hex digits) is the maximum
9650number of threads the response packet can contain; and @var{nextthread}
9651(eight hex digits), for subsequent queries (@var{startflag} is zero), is
9652returned in the response as @var{argthread}.
9653@item
bba2971c
MS
9654@tab
9655@tab NOTE: this query is replaced by the @code{q}@code{fThreadInfo}
9656query (see above).
9657@item
d4f3574e
SS
9658@tab reply @code{q}@code{M}@var{count}@var{done}@var{argthread}@var{thread...}
9659@tab
2b628194
MS
9660@item
9661@tab
9662@tab
d4f3574e
SS
9663Where: @var{count} (two hex digits) is the number of threads being
9664returned; @var{done} (one hex digit) is zero to indicate more threads
9665and one indicates no further threads; @var{argthreadid} (eight hex
9666digits) is @var{nextthread} from the request packet; @var{thread...} is
9667a sequence of thread IDs from the target. @var{threadid} (eight hex
9668digits). See @code{remote.c:parse_threadlist_response()}.
9669
bba2971c
MS
9670@item compute CRC of memory block
9671@tab @code{q}@code{CRC:}@var{addr}@code{,}@var{length}
9672@tab
9673@item
9674@tab reply @code{E}@var{NN}
9675@tab An error (such as memory fault)
9676@item
9677@tab reply @code{C}@var{CRC32}
9678@tab A 32 bit cyclic redundancy check of the specified memory region.
9679
d4f3574e
SS
9680@item query sect offs
9681@tab @code{q}@code{Offsets}
917317f4
JM
9682@tab
9683Get section offsets that the target used when re-locating the downloaded
9684image. @emph{Note: while a @code{Bss} offset is included in the
9685response, @value{GDBN} ignores this and instead applies the @code{Data}
9686offset to the @code{Bss} section.}
d4f3574e
SS
9687@item
9688@tab reply @code{Text=}@var{xxx}@code{;Data=}@var{yyy}@code{;Bss=}@var{zzz}
9689
9690@item thread info request
9691@tab @code{q}@code{P}@var{mode}@var{threadid}
9692@tab
598ca718
EZ
9693@item
9694@tab
9695@tab
d4f3574e
SS
9696Returns information on @var{threadid}. Where: @var{mode} is a hex
9697encoded 32 bit mode; @var{threadid} is a hex encoded 64 bit thread ID.
9698@item
9699@tab reply *
9700@tab
9701See @code{remote.c:remote_unpack_thread_info_response()}.
9702
9703@item remote command
9704@tab @code{q}@code{Rcmd,}@var{COMMAND}
9705@tab
598ca718
EZ
9706@item
9707@tab
9708@tab
d4f3574e
SS
9709@var{COMMAND} (hex encoded) is passed to the local interpreter for
9710execution. Invalid commands should be reported using the output string.
9711Before the final result packet, the target may also respond with a
9712number of intermediate @code{O}@var{OUTPUT} console output
9713packets. @emph{Implementors should note that providing access to a
9714stubs's interpreter may have security implications}.
9715@item
9716@tab reply @code{OK}
9717@tab
9718A command response with no output.
9719@item
9720@tab reply @var{OUTPUT}
9721@tab
9722A command response with the hex encoded output string @var{OUTPUT}.
9723@item
9724@tab reply @code{E}@var{NN}
9725@tab
9726Indicate a badly formed request.
9727
9728@item
9729@tab reply @samp{}
9730@tab
9731When @samp{q}@samp{Rcmd} is not recognized.
9732
9733@end multitable
9734
9735The following @samp{g}/@samp{G} packets have previously been defined.
9736In the below, some thirty-two bit registers are transferred as sixty-four
9737bits. Those registers should be zero/sign extended (which?) to fill the
9738space allocated. Register bytes are transfered in target byte order.
9739The two nibbles within a register byte are transfered most-significant -
9740least-significant.
9741
9742@multitable @columnfractions .5 .5
9743
9744@item MIPS32
9745@tab
9746All registers are transfered as thirty-two bit quantities in the order:
974732 general-purpose; sr; lo; hi; bad; cause; pc; 32 floating-point
9748registers; fsr; fir; fp.
9749
9750@item MIPS64
9751@tab
9752All registers are transfered as sixty-four bit quantities (including
9753thirty-two bit registers such as @code{sr}). The ordering is the same
9754as @code{MIPS32}.
9755
9756@end multitable
9757
104c1213
JM
9758Example sequence of a target being re-started. Notice how the restart
9759does not get any direct output:
9760
9761@example
9762<- @code{R00}
9763-> @code{+}
9764@emph{target restarts}
9765<- @code{?}
9766-> @code{+}
9767-> @code{T001:1234123412341234}
9768<- @code{+}
9769@end example
9770
9771Example sequence of a target being stepped by a single instruction:
9772
9773@example
9774<- @code{G1445...}
9775-> @code{+}
9776<- @code{s}
9777-> @code{+}
9778@emph{time passes}
9779-> @code{T001:1234123412341234}
9780<- @code{+}
9781<- @code{g}
9782-> @code{+}
9783-> @code{1455...}
9784<- @code{+}
9785@end example
9786
6d2ebf8b 9787@node Server
104c1213
JM
9788@subsubsection Using the @code{gdbserver} program
9789
9790@kindex gdbserver
9791@cindex remote connection without stubs
9792@code{gdbserver} is a control program for Unix-like systems, which
9793allows you to connect your program with a remote @value{GDBN} via
9794@code{target remote}---but without linking in the usual debugging stub.
9795
9796@code{gdbserver} is not a complete replacement for the debugging stubs,
9797because it requires essentially the same operating-system facilities
9798that @value{GDBN} itself does. In fact, a system that can run
9799@code{gdbserver} to connect to a remote @value{GDBN} could also run
9800@value{GDBN} locally! @code{gdbserver} is sometimes useful nevertheless,
9801because it is a much smaller program than @value{GDBN} itself. It is
9802also easier to port than all of @value{GDBN}, so you may be able to get
9803started more quickly on a new system by using @code{gdbserver}.
9804Finally, if you develop code for real-time systems, you may find that
9805the tradeoffs involved in real-time operation make it more convenient to
9806do as much development work as possible on another system, for example
9807by cross-compiling. You can use @code{gdbserver} to make a similar
9808choice for debugging.
9809
9810@value{GDBN} and @code{gdbserver} communicate via either a serial line
9811or a TCP connection, using the standard @value{GDBN} remote serial
9812protocol.
9813
9814@table @emph
9815@item On the target machine,
9816you need to have a copy of the program you want to debug.
9817@code{gdbserver} does not need your program's symbol table, so you can
9818strip the program if necessary to save space. @value{GDBN} on the host
9819system does all the symbol handling.
9820
9821To use the server, you must tell it how to communicate with @value{GDBN};
9822the name of your program; and the arguments for your program. The
9823syntax is:
9824
9825@smallexample
9826target> gdbserver @var{comm} @var{program} [ @var{args} @dots{} ]
9827@end smallexample
9828
9829@var{comm} is either a device name (to use a serial line) or a TCP
9830hostname and portnumber. For example, to debug Emacs with the argument
9831@samp{foo.txt} and communicate with @value{GDBN} over the serial port
9832@file{/dev/com1}:
9833
9834@smallexample
9835target> gdbserver /dev/com1 emacs foo.txt
9836@end smallexample
9837
9838@code{gdbserver} waits passively for the host @value{GDBN} to communicate
9839with it.
9840
9841To use a TCP connection instead of a serial line:
9842
9843@smallexample
9844target> gdbserver host:2345 emacs foo.txt
9845@end smallexample
9846
9847The only difference from the previous example is the first argument,
9848specifying that you are communicating with the host @value{GDBN} via
9849TCP. The @samp{host:2345} argument means that @code{gdbserver} is to
9850expect a TCP connection from machine @samp{host} to local TCP port 2345.
9851(Currently, the @samp{host} part is ignored.) You can choose any number
9852you want for the port number as long as it does not conflict with any
9853TCP ports already in use on the target system (for example, @code{23} is
9854reserved for @code{telnet}).@footnote{If you choose a port number that
9855conflicts with another service, @code{gdbserver} prints an error message
d4f3574e 9856and exits.} You must use the same port number with the host @value{GDBN}
104c1213
JM
9857@code{target remote} command.
9858
9859@item On the @value{GDBN} host machine,
9860you need an unstripped copy of your program, since @value{GDBN} needs
9861symbols and debugging information. Start up @value{GDBN} as usual,
9862using the name of the local copy of your program as the first argument.
9863(You may also need the @w{@samp{--baud}} option if the serial line is
d4f3574e 9864running at anything other than 9600@dmn{bps}.) After that, use @code{target
104c1213
JM
9865remote} to establish communications with @code{gdbserver}. Its argument
9866is either a device name (usually a serial device, like
9867@file{/dev/ttyb}), or a TCP port descriptor in the form
9868@code{@var{host}:@var{PORT}}. For example:
9869
9870@smallexample
9871(@value{GDBP}) target remote /dev/ttyb
9872@end smallexample
9873
9874@noindent
9875communicates with the server via serial line @file{/dev/ttyb}, and
9876
9877@smallexample
9878(@value{GDBP}) target remote the-target:2345
9879@end smallexample
9880
9881@noindent
9882communicates via a TCP connection to port 2345 on host @w{@file{the-target}}.
9883For TCP connections, you must start up @code{gdbserver} prior to using
9884the @code{target remote} command. Otherwise you may get an error whose
9885text depends on the host system, but which usually looks something like
9886@samp{Connection refused}.
9887@end table
9888
6d2ebf8b 9889@node NetWare
104c1213
JM
9890@subsubsection Using the @code{gdbserve.nlm} program
9891
9892@kindex gdbserve.nlm
9893@code{gdbserve.nlm} is a control program for NetWare systems, which
9894allows you to connect your program with a remote @value{GDBN} via
9895@code{target remote}.
9896
9897@value{GDBN} and @code{gdbserve.nlm} communicate via a serial line,
9898using the standard @value{GDBN} remote serial protocol.
9899
9900@table @emph
9901@item On the target machine,
9902you need to have a copy of the program you want to debug.
9903@code{gdbserve.nlm} does not need your program's symbol table, so you
9904can strip the program if necessary to save space. @value{GDBN} on the
9905host system does all the symbol handling.
9906
9907To use the server, you must tell it how to communicate with
9908@value{GDBN}; the name of your program; and the arguments for your
9909program. The syntax is:
9910
5d161b24 9911@smallexample
104c1213
JM
9912load gdbserve [ BOARD=@var{board} ] [ PORT=@var{port} ]
9913 [ BAUD=@var{baud} ] @var{program} [ @var{args} @dots{} ]
9914@end smallexample
9915
9916@var{board} and @var{port} specify the serial line; @var{baud} specifies
9917the baud rate used by the connection. @var{port} and @var{node} default
d4f3574e 9918to 0, @var{baud} defaults to 9600@dmn{bps}.
104c1213
JM
9919
9920For example, to debug Emacs with the argument @samp{foo.txt}and
5d161b24 9921communicate with @value{GDBN} over serial port number 2 or board 1
d4f3574e 9922using a 19200@dmn{bps} connection:
104c1213
JM
9923
9924@smallexample
9925load gdbserve BOARD=1 PORT=2 BAUD=19200 emacs foo.txt
9926@end smallexample
9927
9928@item On the @value{GDBN} host machine,
9929you need an unstripped copy of your program, since @value{GDBN} needs
9930symbols and debugging information. Start up @value{GDBN} as usual,
9931using the name of the local copy of your program as the first argument.
9932(You may also need the @w{@samp{--baud}} option if the serial line is
d4f3574e 9933running at anything other than 9600@dmn{bps}. After that, use @code{target
104c1213
JM
9934remote} to establish communications with @code{gdbserve.nlm}. Its
9935argument is a device name (usually a serial device, like
9936@file{/dev/ttyb}). For example:
9937
9938@smallexample
9939(@value{GDBP}) target remote /dev/ttyb
9940@end smallexample
9941
9942@noindent
9943communications with the server via serial line @file{/dev/ttyb}.
9944@end table
9945
6d2ebf8b 9946@node KOD
104c1213
JM
9947@section Kernel Object Display
9948
9949@cindex kernel object display
9950@cindex kernel object
9951@cindex KOD
9952
9953Some targets support kernel object display. Using this facility,
9954@value{GDBN} communicates specially with the underlying operating system
9955and can display information about operating system-level objects such as
9956mutexes and other synchronization objects. Exactly which objects can be
9957displayed is determined on a per-OS basis.
9958
9959Use the @code{set os} command to set the operating system. This tells
9960@value{GDBN} which kernel object display module to initialize:
9961
9962@example
2df3850c 9963(@value{GDBP}) set os cisco
104c1213
JM
9964@end example
9965
9966If @code{set os} succeeds, @value{GDBN} will display some information
9967about the operating system, and will create a new @code{info} command
9968which can be used to query the target. The @code{info} command is named
9969after the operating system:
9970
9971@example
2df3850c 9972(@value{GDBP}) info cisco
104c1213
JM
9973List of Cisco Kernel Objects
9974Object Description
9975any Any and all objects
9976@end example
9977
9978Further subcommands can be used to query about particular objects known
9979by the kernel.
9980
9981There is currently no way to determine whether a given operating system
96baa820
JM
9982is supported other than to try it.
9983
9984
6d2ebf8b 9985@node Configurations
104c1213
JM
9986@chapter Configuration-Specific Information
9987
9988While nearly all @value{GDBN} commands are available for all native and
9989cross versions of the debugger, there are some exceptions. This chapter
9990describes things that are only available in certain configurations.
9991
9992There are three major categories of configurations: native
9993configurations, where the host and target are the same, embedded
9994operating system configurations, which are usually the same for several
9995different processor architectures, and bare embedded processors, which
9996are quite different from each other.
9997
9998@menu
9999* Native::
10000* Embedded OS::
10001* Embedded Processors::
10002* Architectures::
10003@end menu
10004
6d2ebf8b 10005@node Native
104c1213
JM
10006@section Native
10007
10008This section describes details specific to particular native
10009configurations.
10010
10011@menu
10012* HP-UX:: HP-UX
10013* SVR4 Process Information:: SVR4 process information
10014@end menu
10015
6d2ebf8b 10016@node HP-UX
104c1213
JM
10017@subsection HP-UX
10018
10019On HP-UX systems, if you refer to a function or variable name that
10020begins with a dollar sign, @value{GDBN} searches for a user or system
10021name first, before it searches for a convenience variable.
10022
6d2ebf8b 10023@node SVR4 Process Information
104c1213
JM
10024@subsection SVR4 process information
10025
10026@kindex /proc
10027@cindex process image
10028
10029Many versions of SVR4 provide a facility called @samp{/proc} that can be
10030used to examine the image of a running process using file-system
10031subroutines. If @value{GDBN} is configured for an operating system with
10032this facility, the command @code{info proc} is available to report on
10033several kinds of information about the process running your program.
10034@code{info proc} works only on SVR4 systems that include the
10035@code{procfs} code. This includes OSF/1 (Digital Unix), Solaris, Irix,
10036and Unixware, but not HP-UX or Linux, for example.
10037
10038@table @code
10039@kindex info proc
10040@item info proc
10041Summarize available information about the process.
10042
10043@kindex info proc mappings
10044@item info proc mappings
10045Report on the address ranges accessible in the program, with information
10046on whether your program may read, write, or execute each range.
10047
10048@kindex info proc times
10049@item info proc times
10050Starting time, user CPU time, and system CPU time for your program and
10051its children.
10052
10053@kindex info proc id
10054@item info proc id
10055Report on the process IDs related to your program: its own process ID,
10056the ID of its parent, the process group ID, and the session ID.
10057
10058@kindex info proc status
10059@item info proc status
10060General information on the state of the process. If the process is
10061stopped, this report includes the reason for stopping, and any signal
10062received.
10063
10064@item info proc all
10065Show all the above information about the process.
10066@end table
10067
6d2ebf8b 10068@node Embedded OS
104c1213
JM
10069@section Embedded Operating Systems
10070
10071This section describes configurations involving the debugging of
10072embedded operating systems that are available for several different
10073architectures.
10074
10075@menu
10076* VxWorks:: Using @value{GDBN} with VxWorks
10077@end menu
10078
10079@value{GDBN} includes the ability to debug programs running on
10080various real-time operating systems.
10081
6d2ebf8b 10082@node VxWorks
104c1213
JM
10083@subsection Using @value{GDBN} with VxWorks
10084
10085@cindex VxWorks
10086
10087@table @code
10088
10089@kindex target vxworks
10090@item target vxworks @var{machinename}
10091A VxWorks system, attached via TCP/IP. The argument @var{machinename}
10092is the target system's machine name or IP address.
10093
10094@end table
10095
10096On VxWorks, @code{load} links @var{filename} dynamically on the
10097current target system as well as adding its symbols in @value{GDBN}.
10098
10099@value{GDBN} enables developers to spawn and debug tasks running on networked
10100VxWorks targets from a Unix host. Already-running tasks spawned from
10101the VxWorks shell can also be debugged. @value{GDBN} uses code that runs on
10102both the Unix host and on the VxWorks target. The program
d4f3574e 10103@code{@value{GDBP}} is installed and executed on the Unix host. (It may be
104c1213 10104installed with the name @code{vxgdb}, to distinguish it from a
96a2c332 10105@value{GDBN} for debugging programs on the host itself.)
104c1213
JM
10106
10107@table @code
10108@item VxWorks-timeout @var{args}
10109@kindex vxworks-timeout
5d161b24
DB
10110All VxWorks-based targets now support the option @code{vxworks-timeout}.
10111This option is set by the user, and @var{args} represents the number of
10112seconds @value{GDBN} waits for responses to rpc's. You might use this if
10113your VxWorks target is a slow software simulator or is on the far side
104c1213
JM
10114of a thin network line.
10115@end table
10116
10117The following information on connecting to VxWorks was current when
10118this manual was produced; newer releases of VxWorks may use revised
10119procedures.
10120
10121@kindex INCLUDE_RDB
10122To use @value{GDBN} with VxWorks, you must rebuild your VxWorks kernel
10123to include the remote debugging interface routines in the VxWorks
10124library @file{rdb.a}. To do this, define @code{INCLUDE_RDB} in the
10125VxWorks configuration file @file{configAll.h} and rebuild your VxWorks
10126kernel. The resulting kernel contains @file{rdb.a}, and spawns the
10127source debugging task @code{tRdbTask} when VxWorks is booted. For more
10128information on configuring and remaking VxWorks, see the manufacturer's
10129manual.
10130@c VxWorks, see the @cite{VxWorks Programmer's Guide}.
10131
10132Once you have included @file{rdb.a} in your VxWorks system image and set
10133your Unix execution search path to find @value{GDBN}, you are ready to
96a2c332
SS
10134run @value{GDBN}. From your Unix host, run @code{@value{GDBP}} (or
10135@code{vxgdb}, depending on your installation).
104c1213
JM
10136
10137@value{GDBN} comes up showing the prompt:
10138
10139@example
10140(vxgdb)
10141@end example
10142
10143@menu
10144* VxWorks Connection:: Connecting to VxWorks
10145* VxWorks Download:: VxWorks download
10146* VxWorks Attach:: Running tasks
10147@end menu
10148
6d2ebf8b 10149@node VxWorks Connection
104c1213
JM
10150@subsubsection Connecting to VxWorks
10151
10152The @value{GDBN} command @code{target} lets you connect to a VxWorks target on the
10153network. To connect to a target whose host name is ``@code{tt}'', type:
10154
10155@example
10156(vxgdb) target vxworks tt
10157@end example
10158
10159@need 750
10160@value{GDBN} displays messages like these:
10161
10162@smallexample
5d161b24 10163Attaching remote machine across net...
104c1213
JM
10164Connected to tt.
10165@end smallexample
10166
10167@need 1000
10168@value{GDBN} then attempts to read the symbol tables of any object modules
10169loaded into the VxWorks target since it was last booted. @value{GDBN} locates
10170these files by searching the directories listed in the command search
10171path (@pxref{Environment, ,Your program's environment}); if it fails
10172to find an object file, it displays a message such as:
10173
10174@example
10175prog.o: No such file or directory.
10176@end example
10177
10178When this happens, add the appropriate directory to the search path with
10179the @value{GDBN} command @code{path}, and execute the @code{target}
10180command again.
10181
6d2ebf8b 10182@node VxWorks Download
104c1213
JM
10183@subsubsection VxWorks download
10184
10185@cindex download to VxWorks
10186If you have connected to the VxWorks target and you want to debug an
10187object that has not yet been loaded, you can use the @value{GDBN}
10188@code{load} command to download a file from Unix to VxWorks
10189incrementally. The object file given as an argument to the @code{load}
10190command is actually opened twice: first by the VxWorks target in order
10191to download the code, then by @value{GDBN} in order to read the symbol
10192table. This can lead to problems if the current working directories on
10193the two systems differ. If both systems have NFS mounted the same
10194filesystems, you can avoid these problems by using absolute paths.
10195Otherwise, it is simplest to set the working directory on both systems
10196to the directory in which the object file resides, and then to reference
10197the file by its name, without any path. For instance, a program
10198@file{prog.o} may reside in @file{@var{vxpath}/vw/demo/rdb} in VxWorks
10199and in @file{@var{hostpath}/vw/demo/rdb} on the host. To load this
10200program, type this on VxWorks:
10201
10202@example
10203-> cd "@var{vxpath}/vw/demo/rdb"
10204@end example
d4f3574e
SS
10205
10206@noindent
104c1213
JM
10207Then, in @value{GDBN}, type:
10208
10209@example
5d161b24 10210(vxgdb) cd @var{hostpath}/vw/demo/rdb
104c1213
JM
10211(vxgdb) load prog.o
10212@end example
10213
10214@value{GDBN} displays a response similar to this:
10215
10216@smallexample
10217Reading symbol data from wherever/vw/demo/rdb/prog.o... done.
10218@end smallexample
10219
10220You can also use the @code{load} command to reload an object module
10221after editing and recompiling the corresponding source file. Note that
10222this makes @value{GDBN} delete all currently-defined breakpoints,
10223auto-displays, and convenience variables, and to clear the value
10224history. (This is necessary in order to preserve the integrity of
d4f3574e 10225debugger's data structures that reference the target system's symbol
104c1213
JM
10226table.)
10227
6d2ebf8b 10228@node VxWorks Attach
104c1213
JM
10229@subsubsection Running tasks
10230
10231@cindex running VxWorks tasks
10232You can also attach to an existing task using the @code{attach} command as
10233follows:
10234
10235@example
10236(vxgdb) attach @var{task}
10237@end example
10238
10239@noindent
10240where @var{task} is the VxWorks hexadecimal task ID. The task can be running
10241or suspended when you attach to it. Running tasks are suspended at
10242the time of attachment.
10243
6d2ebf8b 10244@node Embedded Processors
104c1213
JM
10245@section Embedded Processors
10246
10247This section goes into details specific to particular embedded
10248configurations.
10249
10250@menu
10251* A29K Embedded:: AMD A29K Embedded
10252* ARM:: ARM
10253* H8/300:: Hitachi H8/300
10254* H8/500:: Hitachi H8/500
10255* i960:: Intel i960
10256* M32R/D:: Mitsubishi M32R/D
10257* M68K:: Motorola M68K
10258* M88K:: Motorola M88K
10259* MIPS Embedded:: MIPS Embedded
10260* PA:: HP PA Embedded
10261* PowerPC: PowerPC
10262* SH:: Hitachi SH
10263* Sparclet:: Tsqware Sparclet
10264* Sparclite:: Fujitsu Sparclite
10265* ST2000:: Tandem ST2000
10266* Z8000:: Zilog Z8000
10267@end menu
10268
6d2ebf8b 10269@node A29K Embedded
104c1213
JM
10270@subsection AMD A29K Embedded
10271
10272@menu
10273* A29K UDI::
10274* A29K EB29K::
10275* Comms (EB29K):: Communications setup
10276* gdb-EB29K:: EB29K cross-debugging
10277* Remote Log:: Remote log
10278@end menu
10279
10280@table @code
10281
10282@kindex target adapt
10283@item target adapt @var{dev}
10284Adapt monitor for A29K.
10285
10286@kindex target amd-eb
10287@item target amd-eb @var{dev} @var{speed} @var{PROG}
10288@cindex AMD EB29K
10289Remote PC-resident AMD EB29K board, attached over serial lines.
10290@var{dev} is the serial device, as for @code{target remote};
10291@var{speed} allows you to specify the linespeed; and @var{PROG} is the
10292name of the program to be debugged, as it appears to DOS on the PC.
10293@xref{A29K EB29K, ,EBMON protocol for AMD29K}.
10294
10295@end table
10296
6d2ebf8b 10297@node A29K UDI
104c1213
JM
10298@subsubsection A29K UDI
10299
10300@cindex UDI
10301@cindex AMD29K via UDI
10302
10303@value{GDBN} supports AMD's UDI (``Universal Debugger Interface'')
10304protocol for debugging the a29k processor family. To use this
10305configuration with AMD targets running the MiniMON monitor, you need the
10306program @code{MONTIP}, available from AMD at no charge. You can also
10307use @value{GDBN} with the UDI-conformant a29k simulator program
10308@code{ISSTIP}, also available from AMD.
10309
10310@table @code
10311@item target udi @var{keyword}
10312@kindex udi
10313Select the UDI interface to a remote a29k board or simulator, where
10314@var{keyword} is an entry in the AMD configuration file @file{udi_soc}.
10315This file contains keyword entries which specify parameters used to
10316connect to a29k targets. If the @file{udi_soc} file is not in your
10317working directory, you must set the environment variable @samp{UDICONF}
10318to its pathname.
10319@end table
10320
6d2ebf8b 10321@node A29K EB29K
104c1213
JM
10322@subsubsection EBMON protocol for AMD29K
10323
10324@cindex EB29K board
10325@cindex running 29K programs
10326
10327AMD distributes a 29K development board meant to fit in a PC, together
10328with a DOS-hosted monitor program called @code{EBMON}. As a shorthand
10329term, this development system is called the ``EB29K''. To use
10330@value{GDBN} from a Unix system to run programs on the EB29K board, you
10331must first connect a serial cable between the PC (which hosts the EB29K
10332board) and a serial port on the Unix system. In the following, we
10333assume you've hooked the cable between the PC's @file{COM1} port and
10334@file{/dev/ttya} on the Unix system.
10335
6d2ebf8b 10336@node Comms (EB29K)
104c1213
JM
10337@subsubsection Communications setup
10338
10339The next step is to set up the PC's port, by doing something like this
10340in DOS on the PC:
10341
10342@example
10343C:\> MODE com1:9600,n,8,1,none
10344@end example
10345
10346@noindent
10347This example---run on an MS DOS 4.0 system---sets the PC port to 9600
10348bps, no parity, eight data bits, one stop bit, and no ``retry'' action;
10349you must match the communications parameters when establishing the Unix
10350end of the connection as well.
10351@c FIXME: Who knows what this "no retry action" crud from the DOS manual may
5d161b24 10352@c mean? It's optional; leave it out? [email protected], 25feb91
d4f3574e
SS
10353@c
10354@c It's optional, but it's unwise to omit it: who knows what is the
10355@c default value set when the DOS machines boots? "No retry" means that
10356@c the DOS serial device driver won't retry the operation if it fails;
10357@c I understand that this is needed because the GDB serial protocol
10358@c handles any errors and retransmissions itself. ---Eli Zaretskii, 3sep99
104c1213
JM
10359
10360To give control of the PC to the Unix side of the serial line, type
10361the following at the DOS console:
10362
10363@example
10364C:\> CTTY com1
10365@end example
10366
10367@noindent
10368(Later, if you wish to return control to the DOS console, you can use
10369the command @code{CTTY con}---but you must send it over the device that
96a2c332 10370had control, in our example over the @file{COM1} serial line.)
104c1213
JM
10371
10372From the Unix host, use a communications program such as @code{tip} or
10373@code{cu} to communicate with the PC; for example,
10374
10375@example
10376cu -s 9600 -l /dev/ttya
10377@end example
10378
10379@noindent
10380The @code{cu} options shown specify, respectively, the linespeed and the
10381serial port to use. If you use @code{tip} instead, your command line
10382may look something like the following:
10383
10384@example
10385tip -9600 /dev/ttya
10386@end example
10387
10388@noindent
10389Your system may require a different name where we show
10390@file{/dev/ttya} as the argument to @code{tip}. The communications
10391parameters, including which port to use, are associated with the
10392@code{tip} argument in the ``remote'' descriptions file---normally the
10393system table @file{/etc/remote}.
10394@c FIXME: What if anything needs doing to match the "n,8,1,none" part of
10395@c the DOS side's comms setup? cu can support -o (odd
10396@c parity), -e (even parity)---apparently no settings for no parity or
10397@c for character size. Taken from stty maybe...? John points out tip
10398@c can set these as internal variables, eg ~s parity=none; man stty
10399@c suggests that it *might* work to stty these options with stdin or
10400@c stdout redirected... [email protected], 25feb91
d4f3574e
SS
10401@c
10402@c There's nothing to be done for the "none" part of the DOS MODE
10403@c command. The rest of the parameters should be matched by the
10404@c baudrate, bits, and parity used by the Unix side. ---Eli Zaretskii, 3Sep99
104c1213
JM
10405
10406@kindex EBMON
10407Using the @code{tip} or @code{cu} connection, change the DOS working
10408directory to the directory containing a copy of your 29K program, then
10409start the PC program @code{EBMON} (an EB29K control program supplied
10410with your board by AMD). You should see an initial display from
10411@code{EBMON} similar to the one that follows, ending with the
10412@code{EBMON} prompt @samp{#}---
10413
10414@example
10415C:\> G:
10416
10417G:\> CD \usr\joe\work29k
10418
10419G:\USR\JOE\WORK29K> EBMON
10420Am29000 PC Coprocessor Board Monitor, version 3.0-18
10421Copyright 1990 Advanced Micro Devices, Inc.
10422Written by Gibbons and Associates, Inc.
10423
10424Enter '?' or 'H' for help
10425
10426PC Coprocessor Type = EB29K
10427I/O Base = 0x208
10428Memory Base = 0xd0000
10429
10430Data Memory Size = 2048KB
10431Available I-RAM Range = 0x8000 to 0x1fffff
10432Available D-RAM Range = 0x80002000 to 0x801fffff
10433
10434PageSize = 0x400
10435Register Stack Size = 0x800
10436Memory Stack Size = 0x1800
10437
10438CPU PRL = 0x3
10439Am29027 Available = No
10440Byte Write Available = Yes
10441
10442# ~.
10443@end example
10444
10445Then exit the @code{cu} or @code{tip} program (done in the example by
10446typing @code{~.} at the @code{EBMON} prompt). @code{EBMON} keeps
10447running, ready for @value{GDBN} to take over.
10448
10449For this example, we've assumed what is probably the most convenient
10450way to make sure the same 29K program is on both the PC and the Unix
d4f3574e 10451system: a PC/NFS connection that establishes ``drive @file{G:}'' on the
104c1213
JM
10452PC as a file system on the Unix host. If you do not have PC/NFS or
10453something similar connecting the two systems, you must arrange some
10454other way---perhaps floppy-disk transfer---of getting the 29K program
10455from the Unix system to the PC; @value{GDBN} does @emph{not} download it over the
10456serial line.
10457
6d2ebf8b 10458@node gdb-EB29K
104c1213
JM
10459@subsubsection EB29K cross-debugging
10460
10461Finally, @code{cd} to the directory containing an image of your 29K
10462program on the Unix system, and start @value{GDBN}---specifying as argument the
10463name of your 29K program:
10464
10465@example
10466cd /usr/joe/work29k
10467@value{GDBP} myfoo
10468@end example
10469
10470@need 500
10471Now you can use the @code{target} command:
10472
10473@example
10474target amd-eb /dev/ttya 9600 MYFOO
10475@c FIXME: test above 'target amd-eb' as spelled, with caps! caps are meant to
10476@c emphasize that this is the name as seen by DOS (since I think DOS is
10477@c single-minded about case of letters). [email protected], 25feb91
10478@end example
10479
10480@noindent
10481In this example, we've assumed your program is in a file called
10482@file{myfoo}. Note that the filename given as the last argument to
10483@code{target amd-eb} should be the name of the program as it appears to DOS.
10484In our example this is simply @code{MYFOO}, but in general it can include
10485a DOS path, and depending on your transfer mechanism may not resemble
10486the name on the Unix side.
10487
10488At this point, you can set any breakpoints you wish; when you are ready
10489to see your program run on the 29K board, use the @value{GDBN} command
10490@code{run}.
10491
10492To stop debugging the remote program, use the @value{GDBN} @code{detach}
10493command.
10494
10495To return control of the PC to its console, use @code{tip} or @code{cu}
10496once again, after your @value{GDBN} session has concluded, to attach to
10497@code{EBMON}. You can then type the command @code{q} to shut down
10498@code{EBMON}, returning control to the DOS command-line interpreter.
d4f3574e 10499Type @kbd{CTTY con} to return command input to the main DOS console,
104c1213
JM
10500and type @kbd{~.} to leave @code{tip} or @code{cu}.
10501
6d2ebf8b 10502@node Remote Log
104c1213 10503@subsubsection Remote log
41afff9a 10504@cindex @file{eb.log}, a log file for EB29K
104c1213
JM
10505@cindex log file for EB29K
10506
10507The @code{target amd-eb} command creates a file @file{eb.log} in the
10508current working directory, to help debug problems with the connection.
10509@file{eb.log} records all the output from @code{EBMON}, including echoes
10510of the commands sent to it. Running @samp{tail -f} on this file in
10511another window often helps to understand trouble with @code{EBMON}, or
10512unexpected events on the PC side of the connection.
10513
6d2ebf8b 10514@node ARM
104c1213
JM
10515@subsection ARM
10516
10517@table @code
10518
10519@kindex target rdi
10520@item target rdi @var{dev}
10521ARM Angel monitor, via RDI library interface to ADP protocol. You may
10522use this target to communicate with both boards running the Angel
10523monitor, or with the EmbeddedICE JTAG debug device.
5d161b24 10524
104c1213
JM
10525@kindex target rdp
10526@item target rdp @var{dev}
10527ARM Demon monitor.
10528
10529@end table
10530
6d2ebf8b 10531@node H8/300
104c1213
JM
10532@subsection Hitachi H8/300
10533
10534@table @code
10535
d4f3574e 10536@kindex target hms@r{, with H8/300}
104c1213
JM
10537@item target hms @var{dev}
10538A Hitachi SH, H8/300, or H8/500 board, attached via serial line to your host.
10539Use special commands @code{device} and @code{speed} to control the serial
10540line and the communications speed used.
10541
d4f3574e 10542@kindex target e7000@r{, with H8/300}
104c1213
JM
10543@item target e7000 @var{dev}
10544E7000 emulator for Hitachi H8 and SH.
10545
d4f3574e
SS
10546@kindex target sh3@r{, with H8/300}
10547@kindex target sh3e@r{, with H8/300}
104c1213 10548@item target sh3 @var{dev}
96a2c332 10549@itemx target sh3e @var{dev}
104c1213
JM
10550Hitachi SH-3 and SH-3E target systems.
10551
10552@end table
10553
10554@cindex download to H8/300 or H8/500
10555@cindex H8/300 or H8/500 download
10556@cindex download to Hitachi SH
10557@cindex Hitachi SH download
10558When you select remote debugging to a Hitachi SH, H8/300, or H8/500
10559board, the @code{load} command downloads your program to the Hitachi
10560board and also opens it as the current executable target for
10561@value{GDBN} on your host (like the @code{file} command).
10562
10563@value{GDBN} needs to know these things to talk to your
5d161b24 10564Hitachi SH, H8/300, or H8/500:
104c1213
JM
10565
10566@enumerate
10567@item
10568that you want to use @samp{target hms}, the remote debugging interface
10569for Hitachi microprocessors, or @samp{target e7000}, the in-circuit
10570emulator for the Hitachi SH and the Hitachi 300H. (@samp{target hms} is
2df3850c 10571the default when @value{GDBN} is configured specifically for the Hitachi SH,
104c1213
JM
10572H8/300, or H8/500.)
10573
10574@item
10575what serial device connects your host to your Hitachi board (the first
10576serial device available on your host is the default).
10577
10578@item
10579what speed to use over the serial device.
10580@end enumerate
10581
10582@menu
10583* Hitachi Boards:: Connecting to Hitachi boards.
10584* Hitachi ICE:: Using the E7000 In-Circuit Emulator.
10585* Hitachi Special:: Special @value{GDBN} commands for Hitachi micros.
10586@end menu
10587
6d2ebf8b 10588@node Hitachi Boards
104c1213
JM
10589@subsubsection Connecting to Hitachi boards
10590
10591@c only for Unix hosts
10592@kindex device
10593@cindex serial device, Hitachi micros
96a2c332 10594Use the special @code{@value{GDBN}} command @samp{device @var{port}} if you
104c1213
JM
10595need to explicitly set the serial device. The default @var{port} is the
10596first available port on your host. This is only necessary on Unix
10597hosts, where it is typically something like @file{/dev/ttya}.
10598
10599@kindex speed
10600@cindex serial line speed, Hitachi micros
96a2c332 10601@code{@value{GDBN}} has another special command to set the communications
104c1213 10602speed: @samp{speed @var{bps}}. This command also is only used from Unix
2df3850c 10603hosts; on DOS hosts, set the line speed as usual from outside @value{GDBN} with
d4f3574e
SS
10604the DOS @code{mode} command (for instance,
10605@w{@kbd{mode com2:9600,n,8,1,p}} for a 9600@dmn{bps} connection).
104c1213
JM
10606
10607The @samp{device} and @samp{speed} commands are available only when you
10608use a Unix host to debug your Hitachi microprocessor programs. If you
10609use a DOS host,
10610@value{GDBN} depends on an auxiliary terminate-and-stay-resident program
10611called @code{asynctsr} to communicate with the development board
10612through a PC serial port. You must also use the DOS @code{mode} command
10613to set up the serial port on the DOS side.
10614
10615The following sample session illustrates the steps needed to start a
10616program under @value{GDBN} control on an H8/300. The example uses a
10617sample H8/300 program called @file{t.x}. The procedure is the same for
10618the Hitachi SH and the H8/500.
10619
10620First hook up your development board. In this example, we use a
10621board attached to serial port @code{COM2}; if you use a different serial
10622port, substitute its name in the argument of the @code{mode} command.
10623When you call @code{asynctsr}, the auxiliary comms program used by the
d4f3574e 10624debugger, you give it just the numeric part of the serial port's name;
104c1213
JM
10625for example, @samp{asyncstr 2} below runs @code{asyncstr} on
10626@code{COM2}.
10627
10628@example
10629C:\H8300\TEST> asynctsr 2
10630C:\H8300\TEST> mode com2:9600,n,8,1,p
10631
10632Resident portion of MODE loaded
10633
10634COM2: 9600, n, 8, 1, p
10635
10636@end example
10637
10638@quotation
10639@emph{Warning:} We have noticed a bug in PC-NFS that conflicts with
10640@code{asynctsr}. If you also run PC-NFS on your DOS host, you may need to
10641disable it, or even boot without it, to use @code{asynctsr} to control
10642your development board.
10643@end quotation
10644
d4f3574e 10645@kindex target hms@r{, and serial protocol}
104c1213
JM
10646Now that serial communications are set up, and the development board is
10647connected, you can start up @value{GDBN}. Call @code{@value{GDBP}} with
96a2c332 10648the name of your program as the argument. @code{@value{GDBN}} prompts
104c1213
JM
10649you, as usual, with the prompt @samp{(@value{GDBP})}. Use two special
10650commands to begin your debugging session: @samp{target hms} to specify
10651cross-debugging to the Hitachi board, and the @code{load} command to
10652download your program to the board. @code{load} displays the names of
10653the program's sections, and a @samp{*} for each 2K of data downloaded.
10654(If you want to refresh @value{GDBN} data on symbols or on the
10655executable file without downloading, use the @value{GDBN} commands
10656@code{file} or @code{symbol-file}. These commands, and @code{load}
10657itself, are described in @ref{Files,,Commands to specify files}.)
10658
10659@smallexample
10660(eg-C:\H8300\TEST) @value{GDBP} t.x
2df3850c 10661@value{GDBN} is free software and you are welcome to distribute copies
5d161b24 10662 of it under certain conditions; type "show copying" to see
104c1213 10663 the conditions.
5d161b24 10664There is absolutely no warranty for @value{GDBN}; type "show warranty"
104c1213 10665for details.
2df3850c
JM
10666@value{GDBN} @value{GDBVN}, Copyright 1992 Free Software Foundation, Inc...
10667(@value{GDBP}) target hms
104c1213 10668Connected to remote H8/300 HMS system.
2df3850c 10669(@value{GDBP}) load t.x
104c1213
JM
10670.text : 0x8000 .. 0xabde ***********
10671.data : 0xabde .. 0xad30 *
10672.stack : 0xf000 .. 0xf014 *
10673@end smallexample
10674
10675At this point, you're ready to run or debug your program. From here on,
10676you can use all the usual @value{GDBN} commands. The @code{break} command
10677sets breakpoints; the @code{run} command starts your program;
10678@code{print} or @code{x} display data; the @code{continue} command
10679resumes execution after stopping at a breakpoint. You can use the
10680@code{help} command at any time to find out more about @value{GDBN} commands.
10681
10682Remember, however, that @emph{operating system} facilities aren't
10683available on your development board; for example, if your program hangs,
10684you can't send an interrupt---but you can press the @sc{reset} switch!
10685
10686Use the @sc{reset} button on the development board
10687@itemize @bullet
10688@item
10689to interrupt your program (don't use @kbd{ctl-C} on the DOS host---it has
10690no way to pass an interrupt signal to the development board); and
10691
10692@item
10693to return to the @value{GDBN} command prompt after your program finishes
10694normally. The communications protocol provides no other way for @value{GDBN}
10695to detect program completion.
10696@end itemize
10697
10698In either case, @value{GDBN} sees the effect of a @sc{reset} on the
10699development board as a ``normal exit'' of your program.
10700
6d2ebf8b 10701@node Hitachi ICE
104c1213
JM
10702@subsubsection Using the E7000 in-circuit emulator
10703
d4f3574e 10704@kindex target e7000@r{, with Hitachi ICE}
104c1213
JM
10705You can use the E7000 in-circuit emulator to develop code for either the
10706Hitachi SH or the H8/300H. Use one of these forms of the @samp{target
10707e7000} command to connect @value{GDBN} to your E7000:
10708
10709@table @code
10710@item target e7000 @var{port} @var{speed}
10711Use this form if your E7000 is connected to a serial port. The
10712@var{port} argument identifies what serial port to use (for example,
10713@samp{com2}). The third argument is the line speed in bits per second
10714(for example, @samp{9600}).
10715
10716@item target e7000 @var{hostname}
10717If your E7000 is installed as a host on a TCP/IP network, you can just
10718specify its hostname; @value{GDBN} uses @code{telnet} to connect.
10719@end table
10720
6d2ebf8b 10721@node Hitachi Special
104c1213
JM
10722@subsubsection Special @value{GDBN} commands for Hitachi micros
10723
10724Some @value{GDBN} commands are available only for the H8/300:
10725
10726@table @code
10727
10728@kindex set machine
10729@kindex show machine
10730@item set machine h8300
10731@itemx set machine h8300h
10732Condition @value{GDBN} for one of the two variants of the H8/300
10733architecture with @samp{set machine}. You can use @samp{show machine}
10734to check which variant is currently in effect.
10735
10736@end table
10737
6d2ebf8b 10738@node H8/500
104c1213
JM
10739@subsection H8/500
10740
10741@table @code
10742
10743@kindex set memory @var{mod}
10744@cindex memory models, H8/500
10745@item set memory @var{mod}
10746@itemx show memory
10747Specify which H8/500 memory model (@var{mod}) you are using with
10748@samp{set memory}; check which memory model is in effect with @samp{show
10749memory}. The accepted values for @var{mod} are @code{small},
10750@code{big}, @code{medium}, and @code{compact}.
10751
10752@end table
10753
6d2ebf8b 10754@node i960
104c1213
JM
10755@subsection Intel i960
10756
10757@table @code
10758
10759@kindex target mon960
10760@item target mon960 @var{dev}
10761MON960 monitor for Intel i960.
10762
f0ca3dce 10763@kindex target nindy
104c1213
JM
10764@item target nindy @var{devicename}
10765An Intel 960 board controlled by a Nindy Monitor. @var{devicename} is
10766the name of the serial device to use for the connection, e.g.
10767@file{/dev/ttya}.
10768
10769@end table
10770
10771@cindex Nindy
10772@cindex i960
10773@dfn{Nindy} is a ROM Monitor program for Intel 960 target systems. When
10774@value{GDBN} is configured to control a remote Intel 960 using Nindy, you can
10775tell @value{GDBN} how to connect to the 960 in several ways:
10776
10777@itemize @bullet
10778@item
10779Through command line options specifying serial port, version of the
10780Nindy protocol, and communications speed;
10781
10782@item
10783By responding to a prompt on startup;
10784
10785@item
10786By using the @code{target} command at any point during your @value{GDBN}
10787session. @xref{Target Commands, ,Commands for managing targets}.
10788
104c1213
JM
10789@end itemize
10790
10791@cindex download to Nindy-960
10792With the Nindy interface to an Intel 960 board, @code{load}
10793downloads @var{filename} to the 960 as well as adding its symbols in
10794@value{GDBN}.
10795
10796@menu
10797* Nindy Startup:: Startup with Nindy
10798* Nindy Options:: Options for Nindy
10799* Nindy Reset:: Nindy reset command
10800@end menu
10801
6d2ebf8b 10802@node Nindy Startup
104c1213
JM
10803@subsubsection Startup with Nindy
10804
10805If you simply start @code{@value{GDBP}} without using any command-line
10806options, you are prompted for what serial port to use, @emph{before} you
10807reach the ordinary @value{GDBN} prompt:
10808
10809@example
5d161b24 10810Attach /dev/ttyNN -- specify NN, or "quit" to quit:
104c1213
JM
10811@end example
10812
10813@noindent
10814Respond to the prompt with whatever suffix (after @samp{/dev/tty})
10815identifies the serial port you want to use. You can, if you choose,
10816simply start up with no Nindy connection by responding to the prompt
10817with an empty line. If you do this and later wish to attach to Nindy,
10818use @code{target} (@pxref{Target Commands, ,Commands for managing targets}).
10819
6d2ebf8b 10820@node Nindy Options
104c1213
JM
10821@subsubsection Options for Nindy
10822
10823These are the startup options for beginning your @value{GDBN} session with a
10824Nindy-960 board attached:
10825
10826@table @code
10827@item -r @var{port}
10828Specify the serial port name of a serial interface to be used to connect
10829to the target system. This option is only available when @value{GDBN} is
10830configured for the Intel 960 target architecture. You may specify
10831@var{port} as any of: a full pathname (e.g. @samp{-r /dev/ttya}), a
10832device name in @file{/dev} (e.g. @samp{-r ttya}), or simply the unique
10833suffix for a specific @code{tty} (e.g. @samp{-r a}).
10834
10835@item -O
10836(An uppercase letter ``O'', not a zero.) Specify that @value{GDBN} should use
10837the ``old'' Nindy monitor protocol to connect to the target system.
10838This option is only available when @value{GDBN} is configured for the Intel 960
10839target architecture.
10840
10841@quotation
10842@emph{Warning:} if you specify @samp{-O}, but are actually trying to
10843connect to a target system that expects the newer protocol, the connection
10844fails, appearing to be a speed mismatch. @value{GDBN} repeatedly
10845attempts to reconnect at several different line speeds. You can abort
10846this process with an interrupt.
10847@end quotation
10848
10849@item -brk
10850Specify that @value{GDBN} should first send a @code{BREAK} signal to the target
10851system, in an attempt to reset it, before connecting to a Nindy target.
10852
10853@quotation
10854@emph{Warning:} Many target systems do not have the hardware that this
10855requires; it only works with a few boards.
10856@end quotation
10857@end table
10858
10859The standard @samp{-b} option controls the line speed used on the serial
10860port.
10861
10862@c @group
6d2ebf8b 10863@node Nindy Reset
104c1213
JM
10864@subsubsection Nindy reset command
10865
10866@table @code
10867@item reset
10868@kindex reset
10869For a Nindy target, this command sends a ``break'' to the remote target
10870system; this is only useful if the target has been equipped with a
10871circuit to perform a hard reset (or some other interesting action) when
10872a break is detected.
10873@end table
10874@c @end group
10875
6d2ebf8b 10876@node M32R/D
104c1213
JM
10877@subsection Mitsubishi M32R/D
10878
10879@table @code
10880
10881@kindex target m32r
10882@item target m32r @var{dev}
10883Mitsubishi M32R/D ROM monitor.
10884
10885@end table
10886
6d2ebf8b 10887@node M68K
104c1213
JM
10888@subsection M68k
10889
10890The Motorola m68k configuration includes ColdFire support, and
10891target command for the following ROM monitors.
10892
10893@table @code
10894
10895@kindex target abug
10896@item target abug @var{dev}
10897ABug ROM monitor for M68K.
10898
10899@kindex target cpu32bug
10900@item target cpu32bug @var{dev}
10901CPU32BUG monitor, running on a CPU32 (M68K) board.
10902
10903@kindex target dbug
10904@item target dbug @var{dev}
10905dBUG ROM monitor for Motorola ColdFire.
10906
10907@kindex target est
10908@item target est @var{dev}
10909EST-300 ICE monitor, running on a CPU32 (M68K) board.
10910
10911@kindex target rom68k
10912@item target rom68k @var{dev}
10913ROM 68K monitor, running on an M68K IDP board.
10914
10915@end table
10916
10917If @value{GDBN} is configured with @code{m68*-ericsson-*}, it will
10918instead have only a single special target command:
10919
10920@table @code
10921
10922@kindex target es1800
10923@item target es1800 @var{dev}
10924ES-1800 emulator for M68K.
10925
10926@end table
10927
10928[context?]
10929
10930@table @code
10931
10932@kindex target rombug
10933@item target rombug @var{dev}
10934ROMBUG ROM monitor for OS/9000.
10935
10936@end table
10937
6d2ebf8b 10938@node M88K
104c1213
JM
10939@subsection M88K
10940
10941@table @code
10942
10943@kindex target bug
10944@item target bug @var{dev}
10945BUG monitor, running on a MVME187 (m88k) board.
10946
10947@end table
10948
6d2ebf8b 10949@node MIPS Embedded
104c1213
JM
10950@subsection MIPS Embedded
10951
10952@cindex MIPS boards
10953@value{GDBN} can use the MIPS remote debugging protocol to talk to a
10954MIPS board attached to a serial line. This is available when
10955you configure @value{GDBN} with @samp{--target=mips-idt-ecoff}.
10956
10957@need 1000
10958Use these @value{GDBN} commands to specify the connection to your target board:
10959
10960@table @code
10961@item target mips @var{port}
10962@kindex target mips @var{port}
10963To run a program on the board, start up @code{@value{GDBP}} with the
10964name of your program as the argument. To connect to the board, use the
10965command @samp{target mips @var{port}}, where @var{port} is the name of
10966the serial port connected to the board. If the program has not already
10967been downloaded to the board, you may use the @code{load} command to
10968download it. You can then use all the usual @value{GDBN} commands.
10969
10970For example, this sequence connects to the target board through a serial
10971port, and loads and runs a program called @var{prog} through the
10972debugger:
10973
10974@example
10975host$ @value{GDBP} @var{prog}
2df3850c
JM
10976@value{GDBN} is free software and @dots{}
10977(@value{GDBP}) target mips /dev/ttyb
10978(@value{GDBP}) load @var{prog}
10979(@value{GDBP}) run
104c1213
JM
10980@end example
10981
10982@item target mips @var{hostname}:@var{portnumber}
10983On some @value{GDBN} host configurations, you can specify a TCP
10984connection (for instance, to a serial line managed by a terminal
10985concentrator) instead of a serial port, using the syntax
10986@samp{@var{hostname}:@var{portnumber}}.
10987
10988@item target pmon @var{port}
10989@kindex target pmon @var{port}
10990PMON ROM monitor.
10991
10992@item target ddb @var{port}
10993@kindex target ddb @var{port}
10994NEC's DDB variant of PMON for Vr4300.
10995
10996@item target lsi @var{port}
10997@kindex target lsi @var{port}
10998LSI variant of PMON.
10999
11000@kindex target r3900
11001@item target r3900 @var{dev}
11002Densan DVE-R3900 ROM monitor for Toshiba R3900 Mips.
11003
11004@kindex target array
11005@item target array @var{dev}
11006Array Tech LSI33K RAID controller board.
11007
11008@end table
11009
11010
11011@noindent
11012@value{GDBN} also supports these special commands for MIPS targets:
11013
11014@table @code
11015@item set processor @var{args}
11016@itemx show processor
11017@kindex set processor @var{args}
11018@kindex show processor
11019Use the @code{set processor} command to set the type of MIPS
11020processor when you want to access processor-type-specific registers.
5d161b24 11021For example, @code{set processor @var{r3041}} tells @value{GDBN}
96c405b3 11022to use the CPU registers appropriate for the 3041 chip.
5d161b24 11023Use the @code{show processor} command to see what MIPS processor @value{GDBN}
104c1213 11024is using. Use the @code{info reg} command to see what registers
5d161b24 11025@value{GDBN} is using.
104c1213
JM
11026
11027@item set mipsfpu double
11028@itemx set mipsfpu single
11029@itemx set mipsfpu none
11030@itemx show mipsfpu
11031@kindex set mipsfpu
11032@kindex show mipsfpu
11033@cindex MIPS remote floating point
11034@cindex floating point, MIPS remote
11035If your target board does not support the MIPS floating point
11036coprocessor, you should use the command @samp{set mipsfpu none} (if you
96a2c332 11037need this, you may wish to put the command in your @value{GDBN} init
104c1213
JM
11038file). This tells @value{GDBN} how to find the return value of
11039functions which return floating point values. It also allows
11040@value{GDBN} to avoid saving the floating point registers when calling
11041functions on the board. If you are using a floating point coprocessor
11042with only single precision floating point support, as on the @sc{r4650}
11043processor, use the command @samp{set mipsfpu single}. The default
11044double precision floating point coprocessor may be selected using
11045@samp{set mipsfpu double}.
11046
11047In previous versions the only choices were double precision or no
11048floating point, so @samp{set mipsfpu on} will select double precision
11049and @samp{set mipsfpu off} will select no floating point.
11050
11051As usual, you can inquire about the @code{mipsfpu} variable with
11052@samp{show mipsfpu}.
11053
11054@item set remotedebug @var{n}
11055@itemx show remotedebug
d4f3574e
SS
11056@kindex set remotedebug@r{, MIPS protocol}
11057@kindex show remotedebug@r{, MIPS protocol}
104c1213
JM
11058@cindex @code{remotedebug}, MIPS protocol
11059@cindex MIPS @code{remotedebug} protocol
11060@c FIXME! For this to be useful, you must know something about the MIPS
11061@c FIXME...protocol. Where is it described?
11062You can see some debugging information about communications with the board
11063by setting the @code{remotedebug} variable. If you set it to @code{1} using
11064@samp{set remotedebug 1}, every packet is displayed. If you set it
11065to @code{2}, every character is displayed. You can check the current value
11066at any time with the command @samp{show remotedebug}.
11067
11068@item set timeout @var{seconds}
11069@itemx set retransmit-timeout @var{seconds}
11070@itemx show timeout
11071@itemx show retransmit-timeout
11072@cindex @code{timeout}, MIPS protocol
11073@cindex @code{retransmit-timeout}, MIPS protocol
11074@kindex set timeout
11075@kindex show timeout
11076@kindex set retransmit-timeout
11077@kindex show retransmit-timeout
11078You can control the timeout used while waiting for a packet, in the MIPS
11079remote protocol, with the @code{set timeout @var{seconds}} command. The
11080default is 5 seconds. Similarly, you can control the timeout used while
11081waiting for an acknowledgement of a packet with the @code{set
11082retransmit-timeout @var{seconds}} command. The default is 3 seconds.
11083You can inspect both values with @code{show timeout} and @code{show
11084retransmit-timeout}. (These commands are @emph{only} available when
11085@value{GDBN} is configured for @samp{--target=mips-idt-ecoff}.)
11086
11087The timeout set by @code{set timeout} does not apply when @value{GDBN}
11088is waiting for your program to stop. In that case, @value{GDBN} waits
11089forever because it has no way of knowing how long the program is going
11090to run before stopping.
11091@end table
11092
6d2ebf8b 11093@node PowerPC
104c1213
JM
11094@subsection PowerPC
11095
11096@table @code
11097
11098@kindex target dink32
11099@item target dink32 @var{dev}
11100DINK32 ROM monitor.
11101
11102@kindex target ppcbug
11103@item target ppcbug @var{dev}
11104@kindex target ppcbug1
11105@item target ppcbug1 @var{dev}
11106PPCBUG ROM monitor for PowerPC.
11107
11108@kindex target sds
11109@item target sds @var{dev}
11110SDS monitor, running on a PowerPC board (such as Motorola's ADS).
11111
11112@end table
11113
6d2ebf8b 11114@node PA
104c1213
JM
11115@subsection HP PA Embedded
11116
11117@table @code
11118
11119@kindex target op50n
11120@item target op50n @var{dev}
11121OP50N monitor, running on an OKI HPPA board.
11122
11123@kindex target w89k
11124@item target w89k @var{dev}
11125W89K monitor, running on a Winbond HPPA board.
11126
11127@end table
11128
6d2ebf8b 11129@node SH
104c1213
JM
11130@subsection Hitachi SH
11131
11132@table @code
11133
d4f3574e 11134@kindex target hms@r{, with Hitachi SH}
104c1213
JM
11135@item target hms @var{dev}
11136A Hitachi SH board attached via serial line to your host. Use special
11137commands @code{device} and @code{speed} to control the serial line and
11138the communications speed used.
11139
d4f3574e 11140@kindex target e7000@r{, with Hitachi SH}
104c1213
JM
11141@item target e7000 @var{dev}
11142E7000 emulator for Hitachi SH.
11143
d4f3574e
SS
11144@kindex target sh3@r{, with SH}
11145@kindex target sh3e@r{, with SH}
104c1213
JM
11146@item target sh3 @var{dev}
11147@item target sh3e @var{dev}
11148Hitachi SH-3 and SH-3E target systems.
11149
11150@end table
11151
6d2ebf8b 11152@node Sparclet
104c1213
JM
11153@subsection Tsqware Sparclet
11154
11155@cindex Sparclet
11156
5d161b24
DB
11157@value{GDBN} enables developers to debug tasks running on
11158Sparclet targets from a Unix host.
104c1213
JM
11159@value{GDBN} uses code that runs on
11160both the Unix host and on the Sparclet target. The program
5d161b24 11161@code{@value{GDBP}} is installed and executed on the Unix host.
104c1213
JM
11162
11163@table @code
f0ca3dce 11164@item remotetimeout @var{args}
104c1213 11165@kindex remotetimeout
5d161b24
DB
11166@value{GDBN} supports the option @code{remotetimeout}.
11167This option is set by the user, and @var{args} represents the number of
11168seconds @value{GDBN} waits for responses.
104c1213
JM
11169@end table
11170
41afff9a 11171@cindex compiling, on Sparclet
5d161b24 11172When compiling for debugging, include the options @samp{-g} to get debug
d4f3574e 11173information and @samp{-Ttext} to relocate the program to where you wish to
5d161b24 11174load it on the target. You may also want to add the options @samp{-n} or
d4f3574e 11175@samp{-N} in order to reduce the size of the sections. Example:
104c1213
JM
11176
11177@example
11178sparclet-aout-gcc prog.c -Ttext 0x12010000 -g -o prog -N
11179@end example
11180
d4f3574e 11181You can use @code{objdump} to verify that the addresses are what you intended:
104c1213
JM
11182
11183@example
11184sparclet-aout-objdump --headers --syms prog
11185@end example
11186
41afff9a 11187@cindex running, on Sparclet
104c1213
JM
11188Once you have set
11189your Unix execution search path to find @value{GDBN}, you are ready to
5d161b24 11190run @value{GDBN}. From your Unix host, run @code{@value{GDBP}}
104c1213
JM
11191(or @code{sparclet-aout-gdb}, depending on your installation).
11192
11193@value{GDBN} comes up showing the prompt:
11194
11195@example
11196(gdbslet)
11197@end example
11198
11199@menu
11200* Sparclet File:: Setting the file to debug
11201* Sparclet Connection:: Connecting to Sparclet
11202* Sparclet Download:: Sparclet download
5d161b24 11203* Sparclet Execution:: Running and debugging
104c1213
JM
11204@end menu
11205
6d2ebf8b 11206@node Sparclet File
104c1213
JM
11207@subsubsection Setting file to debug
11208
11209The @value{GDBN} command @code{file} lets you choose with program to debug.
11210
11211@example
11212(gdbslet) file prog
11213@end example
11214
11215@need 1000
11216@value{GDBN} then attempts to read the symbol table of @file{prog}.
11217@value{GDBN} locates
11218the file by searching the directories listed in the command search
11219path.
11220If the file was compiled with debug information (option "-g"), source
11221files will be searched as well.
11222@value{GDBN} locates
11223the source files by searching the directories listed in the directory search
11224path (@pxref{Environment, ,Your program's environment}).
11225If it fails
11226to find a file, it displays a message such as:
11227
11228@example
11229prog: No such file or directory.
11230@end example
11231
11232When this happens, add the appropriate directories to the search paths with
5d161b24 11233the @value{GDBN} commands @code{path} and @code{dir}, and execute the
104c1213
JM
11234@code{target} command again.
11235
6d2ebf8b 11236@node Sparclet Connection
104c1213
JM
11237@subsubsection Connecting to Sparclet
11238
11239The @value{GDBN} command @code{target} lets you connect to a Sparclet target.
11240To connect to a target on serial port ``@code{ttya}'', type:
11241
11242@example
11243(gdbslet) target sparclet /dev/ttya
11244Remote target sparclet connected to /dev/ttya
5d161b24 11245main () at ../prog.c:3
104c1213
JM
11246@end example
11247
11248@need 750
11249@value{GDBN} displays messages like these:
11250
d4f3574e 11251@example
104c1213 11252Connected to ttya.
d4f3574e 11253@end example
104c1213 11254
6d2ebf8b 11255@node Sparclet Download
104c1213
JM
11256@subsubsection Sparclet download
11257
11258@cindex download to Sparclet
5d161b24 11259Once connected to the Sparclet target,
104c1213
JM
11260you can use the @value{GDBN}
11261@code{load} command to download the file from the host to the target.
11262The file name and load offset should be given as arguments to the @code{load}
11263command.
5d161b24 11264Since the file format is aout, the program must be loaded to the starting
d4f3574e 11265address. You can use @code{objdump} to find out what this value is. The load
104c1213
JM
11266offset is an offset which is added to the VMA (virtual memory address)
11267of each of the file's sections.
11268For instance, if the program
11269@file{prog} was linked to text address 0x1201000, with data at 0x12010160
11270and bss at 0x12010170, in @value{GDBN}, type:
11271
11272@example
11273(gdbslet) load prog 0x12010000
11274Loading section .text, size 0xdb0 vma 0x12010000
11275@end example
11276
5d161b24
DB
11277If the code is loaded at a different address then what the program was linked
11278to, you may need to use the @code{section} and @code{add-symbol-file} commands
104c1213
JM
11279to tell @value{GDBN} where to map the symbol table.
11280
6d2ebf8b 11281@node Sparclet Execution
104c1213
JM
11282@subsubsection Running and debugging
11283
11284@cindex running and debugging Sparclet programs
11285You can now begin debugging the task using @value{GDBN}'s execution control
5d161b24 11286commands, @code{b}, @code{step}, @code{run}, etc. See the @value{GDBN}
104c1213
JM
11287manual for the list of commands.
11288
11289@example
11290(gdbslet) b main
11291Breakpoint 1 at 0x12010000: file prog.c, line 3.
5d161b24 11292(gdbslet) run
104c1213
JM
11293Starting program: prog
11294Breakpoint 1, main (argc=1, argv=0xeffff21c) at prog.c:3
112953 char *symarg = 0;
11296(gdbslet) step
112974 char *execarg = "hello!";
5d161b24 11298(gdbslet)
104c1213
JM
11299@end example
11300
6d2ebf8b 11301@node Sparclite
104c1213
JM
11302@subsection Fujitsu Sparclite
11303
11304@table @code
11305
11306@kindex target sparclite
11307@item target sparclite @var{dev}
5d161b24
DB
11308Fujitsu sparclite boards, used only for the purpose of loading.
11309You must use an additional command to debug the program.
11310For example: target remote @var{dev} using @value{GDBN} standard
104c1213
JM
11311remote protocol.
11312
11313@end table
11314
6d2ebf8b 11315@node ST2000
104c1213
JM
11316@subsection Tandem ST2000
11317
2df3850c 11318@value{GDBN} may be used with a Tandem ST2000 phone switch, running Tandem's
104c1213
JM
11319STDBUG protocol.
11320
11321To connect your ST2000 to the host system, see the manufacturer's
11322manual. Once the ST2000 is physically attached, you can run:
11323
11324@example
11325target st2000 @var{dev} @var{speed}
11326@end example
11327
11328@noindent
11329to establish it as your debugging environment. @var{dev} is normally
11330the name of a serial device, such as @file{/dev/ttya}, connected to the
11331ST2000 via a serial line. You can instead specify @var{dev} as a TCP
11332connection (for example, to a serial line attached via a terminal
11333concentrator) using the syntax @code{@var{hostname}:@var{portnumber}}.
11334
11335The @code{load} and @code{attach} commands are @emph{not} defined for
11336this target; you must load your program into the ST2000 as you normally
11337would for standalone operation. @value{GDBN} reads debugging information
11338(such as symbols) from a separate, debugging version of the program
11339available on your host computer.
11340@c FIXME!! This is terribly vague; what little content is here is
11341@c basically hearsay.
11342
11343@cindex ST2000 auxiliary commands
11344These auxiliary @value{GDBN} commands are available to help you with the ST2000
11345environment:
11346
11347@table @code
11348@item st2000 @var{command}
11349@kindex st2000 @var{cmd}
11350@cindex STDBUG commands (ST2000)
11351@cindex commands to STDBUG (ST2000)
11352Send a @var{command} to the STDBUG monitor. See the manufacturer's
11353manual for available commands.
11354
11355@item connect
11356@cindex connect (to STDBUG)
11357Connect the controlling terminal to the STDBUG command monitor. When
11358you are done interacting with STDBUG, typing either of two character
11359sequences gets you back to the @value{GDBN} command prompt:
11360@kbd{@key{RET}~.} (Return, followed by tilde and period) or
11361@kbd{@key{RET}~@key{C-d}} (Return, followed by tilde and control-D).
11362@end table
11363
6d2ebf8b 11364@node Z8000
104c1213
JM
11365@subsection Zilog Z8000
11366
11367@cindex Z8000
11368@cindex simulator, Z8000
11369@cindex Zilog Z8000 simulator
11370
11371When configured for debugging Zilog Z8000 targets, @value{GDBN} includes
11372a Z8000 simulator.
11373
11374For the Z8000 family, @samp{target sim} simulates either the Z8002 (the
11375unsegmented variant of the Z8000 architecture) or the Z8001 (the
11376segmented variant). The simulator recognizes which architecture is
11377appropriate by inspecting the object code.
11378
11379@table @code
11380@item target sim @var{args}
11381@kindex sim
d4f3574e 11382@kindex target sim@r{, with Z8000}
104c1213
JM
11383Debug programs on a simulated CPU. If the simulator supports setup
11384options, specify them via @var{args}.
11385@end table
11386
11387@noindent
11388After specifying this target, you can debug programs for the simulated
11389CPU in the same style as programs for your host computer; use the
11390@code{file} command to load a new program image, the @code{run} command
11391to run your program, and so on.
11392
d4f3574e
SS
11393As well as making available all the usual machine registers
11394(@pxref{Registers, ,Registers}), the Z8000 simulator provides three
11395additional items of information as specially named registers:
104c1213
JM
11396
11397@table @code
11398
11399@item cycles
11400Counts clock-ticks in the simulator.
11401
11402@item insts
11403Counts instructions run in the simulator.
11404
11405@item time
11406Execution time in 60ths of a second.
11407
11408@end table
11409
11410You can refer to these values in @value{GDBN} expressions with the usual
11411conventions; for example, @w{@samp{b fputc if $cycles>5000}} sets a
11412conditional breakpoint that suspends only after at least 5000
11413simulated clock ticks.
11414
6d2ebf8b 11415@node Architectures
104c1213
JM
11416@section Architectures
11417
11418This section describes characteristics of architectures that affect
2df3850c 11419all uses of @value{GDBN} with the architecture, both native and cross.
104c1213
JM
11420
11421@menu
11422* A29K::
11423* Alpha::
11424* MIPS::
11425@end menu
11426
6d2ebf8b 11427@node A29K
104c1213
JM
11428@subsection A29K
11429
11430@table @code
11431
11432@kindex set rstack_high_address
11433@cindex AMD 29K register stack
11434@cindex register stack, AMD29K
11435@item set rstack_high_address @var{address}
11436On AMD 29000 family processors, registers are saved in a separate
d4f3574e 11437@dfn{register stack}. There is no way for @value{GDBN} to determine the
104c1213
JM
11438extent of this stack. Normally, @value{GDBN} just assumes that the
11439stack is ``large enough''. This may result in @value{GDBN} referencing
11440memory locations that do not exist. If necessary, you can get around
11441this problem by specifying the ending address of the register stack with
11442the @code{set rstack_high_address} command. The argument should be an
11443address, which you probably want to precede with @samp{0x} to specify in
11444hexadecimal.
11445
11446@kindex show rstack_high_address
11447@item show rstack_high_address
11448Display the current limit of the register stack, on AMD 29000 family
11449processors.
11450
11451@end table
11452
6d2ebf8b 11453@node Alpha
104c1213
JM
11454@subsection Alpha
11455
11456See the following section.
11457
6d2ebf8b 11458@node MIPS
104c1213
JM
11459@subsection MIPS
11460
11461@cindex stack on Alpha
11462@cindex stack on MIPS
11463@cindex Alpha stack
11464@cindex MIPS stack
11465Alpha- and MIPS-based computers use an unusual stack frame, which
11466sometimes requires @value{GDBN} to search backward in the object code to
11467find the beginning of a function.
11468
11469@cindex response time, MIPS debugging
11470To improve response time (especially for embedded applications, where
11471@value{GDBN} may be restricted to a slow serial line for this search)
11472you may want to limit the size of this search, using one of these
11473commands:
11474
11475@table @code
00e4a2e4 11476@cindex @code{heuristic-fence-post} (Alpha, MIPS)
104c1213
JM
11477@item set heuristic-fence-post @var{limit}
11478Restrict @value{GDBN} to examining at most @var{limit} bytes in its
11479search for the beginning of a function. A value of @var{0} (the
11480default) means there is no limit. However, except for @var{0}, the
11481larger the limit the more bytes @code{heuristic-fence-post} must search
11482and therefore the longer it takes to run.
11483
11484@item show heuristic-fence-post
11485Display the current limit.
11486@end table
11487
11488@noindent
11489These commands are available @emph{only} when @value{GDBN} is configured
11490for debugging programs on Alpha or MIPS processors.
11491
11492
6d2ebf8b 11493@node Controlling GDB
c906108c
SS
11494@chapter Controlling @value{GDBN}
11495
53a5351d
JM
11496You can alter the way @value{GDBN} interacts with you by using the
11497@code{set} command. For commands controlling how @value{GDBN} displays
d4f3574e 11498data, see @ref{Print Settings, ,Print settings}. Other settings are
53a5351d 11499described here.
c906108c
SS
11500
11501@menu
11502* Prompt:: Prompt
11503* Editing:: Command editing
11504* History:: Command history
11505* Screen Size:: Screen size
11506* Numbers:: Numbers
11507* Messages/Warnings:: Optional warnings and messages
5d161b24 11508* Debugging Output:: Optional messages about internal happenings
c906108c
SS
11509@end menu
11510
6d2ebf8b 11511@node Prompt
c906108c
SS
11512@section Prompt
11513
11514@cindex prompt
11515
11516@value{GDBN} indicates its readiness to read a command by printing a string
11517called the @dfn{prompt}. This string is normally @samp{(@value{GDBP})}. You
11518can change the prompt string with the @code{set prompt} command. For
11519instance, when debugging @value{GDBN} with @value{GDBN}, it is useful to change
5d161b24 11520the prompt in one of the @value{GDBN} sessions so that you can always tell
c906108c
SS
11521which one you are talking to.
11522
d4f3574e 11523@emph{Note:} @code{set prompt} does not add a space for you after the
c906108c
SS
11524prompt you set. This allows you to set a prompt which ends in a space
11525or a prompt that does not.
11526
11527@table @code
11528@kindex set prompt
11529@item set prompt @var{newprompt}
11530Directs @value{GDBN} to use @var{newprompt} as its prompt string henceforth.
11531
11532@kindex show prompt
11533@item show prompt
11534Prints a line of the form: @samp{Gdb's prompt is: @var{your-prompt}}
11535@end table
11536
6d2ebf8b 11537@node Editing
c906108c
SS
11538@section Command editing
11539@cindex readline
11540@cindex command line editing
11541
11542@value{GDBN} reads its input commands via the @dfn{readline} interface. This
11543@sc{gnu} library provides consistent behavior for programs which provide a
11544command line interface to the user. Advantages are @sc{gnu} Emacs-style
11545or @dfn{vi}-style inline editing of commands, @code{csh}-like history
11546substitution, and a storage and recall of command history across
11547debugging sessions.
11548
11549You may control the behavior of command line editing in @value{GDBN} with the
11550command @code{set}.
11551
11552@table @code
11553@kindex set editing
11554@cindex editing
11555@item set editing
11556@itemx set editing on
11557Enable command line editing (enabled by default).
11558
11559@item set editing off
11560Disable command line editing.
11561
11562@kindex show editing
11563@item show editing
11564Show whether command line editing is enabled.
11565@end table
11566
6d2ebf8b 11567@node History
c906108c
SS
11568@section Command history
11569
11570@value{GDBN} can keep track of the commands you type during your
11571debugging sessions, so that you can be certain of precisely what
11572happened. Use these commands to manage the @value{GDBN} command
11573history facility.
11574
11575@table @code
11576@cindex history substitution
11577@cindex history file
11578@kindex set history filename
11579@kindex GDBHISTFILE
11580@item set history filename @var{fname}
11581Set the name of the @value{GDBN} command history file to @var{fname}.
11582This is the file where @value{GDBN} reads an initial command history
11583list, and where it writes the command history from this session when it
11584exits. You can access this list through history expansion or through
11585the history command editing characters listed below. This file defaults
11586to the value of the environment variable @code{GDBHISTFILE}, or to
d4f3574e
SS
11587@file{./.gdb_history} (@file{./_gdb_history} on MS-DOS) if this variable
11588is not set.
c906108c
SS
11589
11590@cindex history save
11591@kindex set history save
11592@item set history save
11593@itemx set history save on
11594Record command history in a file, whose name may be specified with the
11595@code{set history filename} command. By default, this option is disabled.
11596
11597@item set history save off
11598Stop recording command history in a file.
11599
11600@cindex history size
11601@kindex set history size
11602@item set history size @var{size}
11603Set the number of commands which @value{GDBN} keeps in its history list.
11604This defaults to the value of the environment variable
11605@code{HISTSIZE}, or to 256 if this variable is not set.
11606@end table
11607
11608@cindex history expansion
11609History expansion assigns special meaning to the character @kbd{!}.
11610@ifset have-readline-appendices
11611@xref{Event Designators}.
11612@end ifset
11613
11614Since @kbd{!} is also the logical not operator in C, history expansion
11615is off by default. If you decide to enable history expansion with the
11616@code{set history expansion on} command, you may sometimes need to
11617follow @kbd{!} (when it is used as logical not, in an expression) with
11618a space or a tab to prevent it from being expanded. The readline
11619history facilities do not attempt substitution on the strings
11620@kbd{!=} and @kbd{!(}, even when history expansion is enabled.
11621
11622The commands to control history expansion are:
11623
11624@table @code
11625@kindex set history expansion
11626@item set history expansion on
11627@itemx set history expansion
11628Enable history expansion. History expansion is off by default.
11629
11630@item set history expansion off
11631Disable history expansion.
11632
11633The readline code comes with more complete documentation of
11634editing and history expansion features. Users unfamiliar with @sc{gnu} Emacs
11635or @code{vi} may wish to read it.
11636@ifset have-readline-appendices
11637@xref{Command Line Editing}.
11638@end ifset
11639
11640@c @group
11641@kindex show history
11642@item show history
11643@itemx show history filename
11644@itemx show history save
11645@itemx show history size
11646@itemx show history expansion
11647These commands display the state of the @value{GDBN} history parameters.
11648@code{show history} by itself displays all four states.
11649@c @end group
11650@end table
11651
11652@table @code
41afff9a 11653@kindex shows
c906108c
SS
11654@item show commands
11655Display the last ten commands in the command history.
11656
11657@item show commands @var{n}
11658Print ten commands centered on command number @var{n}.
11659
11660@item show commands +
11661Print ten commands just after the commands last printed.
11662@end table
11663
6d2ebf8b 11664@node Screen Size
c906108c
SS
11665@section Screen size
11666@cindex size of screen
11667@cindex pauses in output
11668
11669Certain commands to @value{GDBN} may produce large amounts of
11670information output to the screen. To help you read all of it,
11671@value{GDBN} pauses and asks you for input at the end of each page of
11672output. Type @key{RET} when you want to continue the output, or @kbd{q}
11673to discard the remaining output. Also, the screen width setting
11674determines when to wrap lines of output. Depending on what is being
11675printed, @value{GDBN} tries to break the line at a readable place,
11676rather than simply letting it overflow onto the following line.
11677
d4f3574e
SS
11678Normally @value{GDBN} knows the size of the screen from the terminal
11679driver software. For example, on Unix @value{GDBN} uses the termcap data base
c906108c 11680together with the value of the @code{TERM} environment variable and the
d4f3574e 11681@code{stty rows} and @code{stty cols} settings. If this is not correct,
c906108c
SS
11682you can override it with the @code{set height} and @code{set
11683width} commands:
11684
11685@table @code
11686@kindex set height
11687@kindex set width
11688@kindex show width
11689@kindex show height
11690@item set height @var{lpp}
11691@itemx show height
11692@itemx set width @var{cpl}
11693@itemx show width
11694These @code{set} commands specify a screen height of @var{lpp} lines and
11695a screen width of @var{cpl} characters. The associated @code{show}
11696commands display the current settings.
11697
5d161b24
DB
11698If you specify a height of zero lines, @value{GDBN} does not pause during
11699output no matter how long the output is. This is useful if output is to a
c906108c
SS
11700file or to an editor buffer.
11701
11702Likewise, you can specify @samp{set width 0} to prevent @value{GDBN}
11703from wrapping its output.
11704@end table
11705
6d2ebf8b 11706@node Numbers
c906108c
SS
11707@section Numbers
11708@cindex number representation
11709@cindex entering numbers
11710
2df3850c
JM
11711You can always enter numbers in octal, decimal, or hexadecimal in
11712@value{GDBN} by the usual conventions: octal numbers begin with
11713@samp{0}, decimal numbers end with @samp{.}, and hexadecimal numbers
11714begin with @samp{0x}. Numbers that begin with none of these are, by
11715default, entered in base 10; likewise, the default display for
11716numbers---when no particular format is specified---is base 10. You can
11717change the default base for both input and output with the @code{set
11718radix} command.
c906108c
SS
11719
11720@table @code
11721@kindex set input-radix
11722@item set input-radix @var{base}
11723Set the default base for numeric input. Supported choices
11724for @var{base} are decimal 8, 10, or 16. @var{base} must itself be
11725specified either unambiguously or using the current default radix; for
11726example, any of
11727
11728@smallexample
11729set radix 012
11730set radix 10.
11731set radix 0xa
11732@end smallexample
11733
11734@noindent
11735sets the base to decimal. On the other hand, @samp{set radix 10}
11736leaves the radix unchanged no matter what it was.
11737
11738@kindex set output-radix
11739@item set output-radix @var{base}
11740Set the default base for numeric display. Supported choices
11741for @var{base} are decimal 8, 10, or 16. @var{base} must itself be
11742specified either unambiguously or using the current default radix.
11743
11744@kindex show input-radix
11745@item show input-radix
11746Display the current default base for numeric input.
11747
11748@kindex show output-radix
11749@item show output-radix
11750Display the current default base for numeric display.
11751@end table
11752
6d2ebf8b 11753@node Messages/Warnings
c906108c
SS
11754@section Optional warnings and messages
11755
2df3850c
JM
11756By default, @value{GDBN} is silent about its inner workings. If you are
11757running on a slow machine, you may want to use the @code{set verbose}
11758command. This makes @value{GDBN} tell you when it does a lengthy
11759internal operation, so you will not think it has crashed.
c906108c
SS
11760
11761Currently, the messages controlled by @code{set verbose} are those
11762which announce that the symbol table for a source file is being read;
11763see @code{symbol-file} in @ref{Files, ,Commands to specify files}.
11764
11765@table @code
11766@kindex set verbose
11767@item set verbose on
11768Enables @value{GDBN} output of certain informational messages.
11769
11770@item set verbose off
11771Disables @value{GDBN} output of certain informational messages.
11772
11773@kindex show verbose
11774@item show verbose
11775Displays whether @code{set verbose} is on or off.
11776@end table
11777
2df3850c
JM
11778By default, if @value{GDBN} encounters bugs in the symbol table of an
11779object file, it is silent; but if you are debugging a compiler, you may
11780find this information useful (@pxref{Symbol Errors, ,Errors reading
11781symbol files}).
c906108c
SS
11782
11783@table @code
2df3850c 11784
c906108c
SS
11785@kindex set complaints
11786@item set complaints @var{limit}
2df3850c
JM
11787Permits @value{GDBN} to output @var{limit} complaints about each type of
11788unusual symbols before becoming silent about the problem. Set
11789@var{limit} to zero to suppress all complaints; set it to a large number
11790to prevent complaints from being suppressed.
c906108c
SS
11791
11792@kindex show complaints
11793@item show complaints
11794Displays how many symbol complaints @value{GDBN} is permitted to produce.
2df3850c 11795
c906108c
SS
11796@end table
11797
11798By default, @value{GDBN} is cautious, and asks what sometimes seems to be a
11799lot of stupid questions to confirm certain commands. For example, if
11800you try to run a program which is already running:
11801
11802@example
11803(@value{GDBP}) run
11804The program being debugged has been started already.
11805Start it from the beginning? (y or n)
11806@end example
11807
11808If you are willing to unflinchingly face the consequences of your own
11809commands, you can disable this ``feature'':
11810
11811@table @code
2df3850c 11812
c906108c
SS
11813@kindex set confirm
11814@cindex flinching
11815@cindex confirmation
11816@cindex stupid questions
11817@item set confirm off
11818Disables confirmation requests.
11819
11820@item set confirm on
11821Enables confirmation requests (the default).
11822
11823@kindex show confirm
11824@item show confirm
11825Displays state of confirmation requests.
2df3850c 11826
c906108c
SS
11827@end table
11828
6d2ebf8b 11829@node Debugging Output
5d161b24
DB
11830@section Optional messages about internal happenings
11831@table @code
11832@kindex set debug arch
11833@item set debug arch
11834Turns on or off display of gdbarch debugging info. The default is off
11835@kindex show debug arch
11836@item show debug arch
11837Displays the current state of displaying gdbarch debugging info.
11838@kindex set debug event
11839@item set debug event
11840Turns on or off display of @value{GDBN} event debugging info. The
11841default is off.
11842@kindex show debug event
11843@item show debug event
11844Displays the current state of displaying @value{GDBN} event debugging
11845info.
11846@kindex set debug expression
11847@item set debug expression
11848Turns on or off display of @value{GDBN} expression debugging info. The
11849default is off.
11850@kindex show debug expression
11851@item show debug expression
11852Displays the current state of displaying @value{GDBN} expression
11853debugging info.
11854@kindex set debug overload
11855@item set debug overload
11856Turns on or off display of @value{GDBN} C++ overload debugging
11857info. This includes info such as ranking of functions, etc. The default
11858is off.
11859@kindex show debug overload
11860@item show debug overload
11861Displays the current state of displaying @value{GDBN} C++ overload
11862debugging info.
11863@kindex set debug remote
11864@cindex packets, reporting on stdout
11865@cindex serial connections, debugging
11866@item set debug remote
11867Turns on or off display of reports on all packets sent back and forth across
11868the serial line to the remote machine. The info is printed on the
11869@value{GDBN} standard output stream. The default is off.
11870@kindex show debug remote
11871@item show debug remote
11872Displays the state of display of remote packets.
11873@kindex set debug serial
11874@item set debug serial
11875Turns on or off display of @value{GDBN} serial debugging info. The
11876default is off.
11877@kindex show debug serial
11878@item show debug serial
11879Displays the current state of displaying @value{GDBN} serial debugging
11880info.
11881@kindex set debug target
11882@item set debug target
11883Turns on or off display of @value{GDBN} target debugging info. This info
11884includes what is going on at the target level of GDB, as it happens. The
11885default is off.
11886@kindex show debug target
11887@item show debug target
11888Displays the current state of displaying @value{GDBN} target debugging
11889info.
11890@kindex set debug varobj
11891@item set debug varobj
11892Turns on or off display of @value{GDBN} variable object debugging
11893info. The default is off.
11894@kindex show debug varobj
11895@item show debug varobj
11896Displays the current state of displaying @value{GDBN} variable object
11897debugging info.
11898@end table
11899
6d2ebf8b 11900@node Sequences
c906108c
SS
11901@chapter Canned Sequences of Commands
11902
11903Aside from breakpoint commands (@pxref{Break Commands, ,Breakpoint
2df3850c
JM
11904command lists}), @value{GDBN} provides two ways to store sequences of
11905commands for execution as a unit: user-defined commands and command
11906files.
c906108c
SS
11907
11908@menu
11909* Define:: User-defined commands
11910* Hooks:: User-defined command hooks
11911* Command Files:: Command files
11912* Output:: Commands for controlled output
11913@end menu
11914
6d2ebf8b 11915@node Define
c906108c
SS
11916@section User-defined commands
11917
11918@cindex user-defined command
2df3850c
JM
11919A @dfn{user-defined command} is a sequence of @value{GDBN} commands to
11920which you assign a new name as a command. This is done with the
11921@code{define} command. User commands may accept up to 10 arguments
11922separated by whitespace. Arguments are accessed within the user command
11923via @var{$arg0@dots{}$arg9}. A trivial example:
c906108c
SS
11924
11925@smallexample
11926define adder
11927 print $arg0 + $arg1 + $arg2
11928@end smallexample
11929
d4f3574e
SS
11930@noindent
11931To execute the command use:
c906108c
SS
11932
11933@smallexample
11934adder 1 2 3
11935@end smallexample
11936
d4f3574e
SS
11937@noindent
11938This defines the command @code{adder}, which prints the sum of
5d161b24 11939its three arguments. Note the arguments are text substitutions, so they may
c906108c
SS
11940reference variables, use complex expressions, or even perform inferior
11941functions calls.
11942
11943@table @code
2df3850c 11944
c906108c
SS
11945@kindex define
11946@item define @var{commandname}
11947Define a command named @var{commandname}. If there is already a command
11948by that name, you are asked to confirm that you want to redefine it.
11949
11950The definition of the command is made up of other @value{GDBN} command lines,
11951which are given following the @code{define} command. The end of these
11952commands is marked by a line containing @code{end}.
11953
11954@kindex if
11955@kindex else
11956@item if
11957Takes a single argument, which is an expression to evaluate.
11958It is followed by a series of commands that are executed
11959only if the expression is true (nonzero).
11960There can then optionally be a line @code{else}, followed
11961by a series of commands that are only executed if the expression
11962was false. The end of the list is marked by a line containing @code{end}.
11963
11964@kindex while
11965@item while
11966The syntax is similar to @code{if}: the command takes a single argument,
11967which is an expression to evaluate, and must be followed by the commands to
11968execute, one per line, terminated by an @code{end}.
11969The commands are executed repeatedly as long as the expression
11970evaluates to true.
11971
11972@kindex document
11973@item document @var{commandname}
11974Document the user-defined command @var{commandname}, so that it can be
5d161b24
DB
11975accessed by @code{help}. The command @var{commandname} must already be
11976defined. This command reads lines of documentation just as @code{define}
11977reads the lines of the command definition, ending with @code{end}.
11978After the @code{document} command is finished, @code{help} on command
c906108c
SS
11979@var{commandname} displays the documentation you have written.
11980
11981You may use the @code{document} command again to change the
11982documentation of a command. Redefining the command with @code{define}
11983does not change the documentation.
11984
11985@kindex help user-defined
11986@item help user-defined
11987List all user-defined commands, with the first line of the documentation
11988(if any) for each.
11989
11990@kindex show user
11991@item show user
11992@itemx show user @var{commandname}
2df3850c
JM
11993Display the @value{GDBN} commands used to define @var{commandname} (but
11994not its documentation). If no @var{commandname} is given, display the
c906108c 11995definitions for all user-defined commands.
2df3850c 11996
c906108c
SS
11997@end table
11998
11999When user-defined commands are executed, the
12000commands of the definition are not printed. An error in any command
12001stops execution of the user-defined command.
12002
12003If used interactively, commands that would ask for confirmation proceed
5d161b24
DB
12004without asking when used inside a user-defined command. Many @value{GDBN}
12005commands that normally print messages to say what they are doing omit the
c906108c
SS
12006messages when used in a user-defined command.
12007
6d2ebf8b 12008@node Hooks
c906108c 12009@section User-defined command hooks
d4f3574e
SS
12010@cindex command hooks
12011@cindex hooks, for commands
c78b4128 12012@cindex hooks, pre-command
c906108c 12013
c78b4128
EZ
12014@kindex hook
12015@kindex hook-
12016You may define @dfn{hooks}, which are a special kind of user-defined
c906108c
SS
12017command. Whenever you run the command @samp{foo}, if the user-defined
12018command @samp{hook-foo} exists, it is executed (with no arguments)
12019before that command.
12020
c78b4128
EZ
12021@cindex hooks, post-command
12022@kindex hookpost
12023@kindex hookpost-
12024A hook may also be defined which is run after the command you executed.
12025Whenever you run the command @samp{foo}, if the user-defined command
12026@samp{hookpost-foo} exists, it is executed (with no arguments) after
12027that command. Post-execution hooks may exist simultaneously with
12028pre-execution hooks, for the same command.
12029
12030It is valid for a hook to call the command which it hooks. If this
12031occurs, the hook is not re-executed, thereby avoiding infinte recursion.
12032
12033@c It would be nice if hookpost could be passed a parameter indicating
12034@c if the command it hooks executed properly or not. FIXME!
12035
d4f3574e 12036@kindex stop@r{, a pseudo-command}
c906108c
SS
12037In addition, a pseudo-command, @samp{stop} exists. Defining
12038(@samp{hook-stop}) makes the associated commands execute every time
12039execution stops in your program: before breakpoint commands are run,
12040displays are printed, or the stack frame is printed.
12041
c906108c
SS
12042For example, to ignore @code{SIGALRM} signals while
12043single-stepping, but treat them normally during normal execution,
12044you could define:
12045
12046@example
12047define hook-stop
12048handle SIGALRM nopass
12049end
12050
12051define hook-run
12052handle SIGALRM pass
12053end
12054
12055define hook-continue
12056handle SIGLARM pass
12057end
12058@end example
c906108c 12059
c78b4128
EZ
12060As a further example, to hook at the begining and end of the @code{echo}
12061command, and to add extra text to the beginning and end of the message,
12062you could define:
12063
12064@example
12065define hook-echo
12066echo <<<---
12067end
12068
12069define hookpost-echo
12070echo --->>>\n
12071end
12072
12073(@value{GDBP}) echo Hello World
12074<<<---Hello World--->>>
12075(@value{GDBP})
12076
12077@end example
12078
c906108c
SS
12079You can define a hook for any single-word command in @value{GDBN}, but
12080not for command aliases; you should define a hook for the basic command
12081name, e.g. @code{backtrace} rather than @code{bt}.
12082@c FIXME! So how does Joe User discover whether a command is an alias
12083@c or not?
12084If an error occurs during the execution of your hook, execution of
12085@value{GDBN} commands stops and @value{GDBN} issues a prompt
12086(before the command that you actually typed had a chance to run).
12087
12088If you try to define a hook which does not match any known command, you
12089get a warning from the @code{define} command.
12090
6d2ebf8b 12091@node Command Files
c906108c
SS
12092@section Command files
12093
12094@cindex command files
5d161b24
DB
12095A command file for @value{GDBN} is a file of lines that are @value{GDBN}
12096commands. Comments (lines starting with @kbd{#}) may also be included.
12097An empty line in a command file does nothing; it does not mean to repeat
c906108c
SS
12098the last command, as it would from the terminal.
12099
12100@cindex init file
12101@cindex @file{.gdbinit}
d4f3574e 12102@cindex @file{gdb.ini}
c906108c 12103When you start @value{GDBN}, it automatically executes commands from its
bf0184be
ND
12104@dfn{init files}. These are files named @file{.gdbinit} on Unix and
12105@file{gdb.ini} on DOS/Windows. During startup, @value{GDBN} does the
12106following:
12107
12108@enumerate
12109@item
12110Reads the init file (if any) in your home directory@footnote{On
12111DOS/Windows systems, the home directory is the one pointed to by the
12112@code{HOME} environment variable.}.
12113
12114@item
12115Processes command line options and operands.
12116
12117@item
12118Reads the init file (if any) in the current working directory.
12119
12120@item
12121Reads command files specified by the @samp{-x} option.
12122@end enumerate
12123
12124The init file in your home directory can set options (such as @samp{set
12125complaints}) that affect subsequent processing of command line options
12126and operands. Init files are not executed if you use the @samp{-nx}
12127option (@pxref{Mode Options, ,Choosing modes}).
c906108c 12128
c906108c
SS
12129@cindex init file name
12130On some configurations of @value{GDBN}, the init file is known by a
12131different name (these are typically environments where a specialized
12132form of @value{GDBN} may need to coexist with other forms, hence a
12133different name for the specialized version's init file). These are the
12134environments with special init file names:
12135
00e4a2e4 12136@cindex @file{.vxgdbinit}
c906108c
SS
12137@itemize @bullet
12138@item
00e4a2e4 12139VxWorks (Wind River Systems real-time OS): @file{.vxgdbinit}
c906108c 12140
00e4a2e4 12141@cindex @file{.os68gdbinit}
c906108c 12142@item
00e4a2e4 12143OS68K (Enea Data Systems real-time OS): @file{.os68gdbinit}
c906108c 12144
00e4a2e4 12145@cindex @file{.esgdbinit}
c906108c 12146@item
00e4a2e4 12147ES-1800 (Ericsson Telecom AB M68000 emulator): @file{.esgdbinit}
c906108c 12148@end itemize
c906108c
SS
12149
12150You can also request the execution of a command file with the
12151@code{source} command:
12152
12153@table @code
12154@kindex source
12155@item source @var{filename}
12156Execute the command file @var{filename}.
12157@end table
12158
12159The lines in a command file are executed sequentially. They are not
12160printed as they are executed. An error in any command terminates execution
12161of the command file.
12162
12163Commands that would ask for confirmation if used interactively proceed
12164without asking when used in a command file. Many @value{GDBN} commands that
12165normally print messages to say what they are doing omit the messages
12166when called from command files.
12167
6d2ebf8b 12168@node Output
c906108c
SS
12169@section Commands for controlled output
12170
12171During the execution of a command file or a user-defined command, normal
12172@value{GDBN} output is suppressed; the only output that appears is what is
12173explicitly printed by the commands in the definition. This section
12174describes three commands useful for generating exactly the output you
12175want.
12176
12177@table @code
12178@kindex echo
12179@item echo @var{text}
12180@c I do not consider backslash-space a standard C escape sequence
12181@c because it is not in ANSI.
12182Print @var{text}. Nonprinting characters can be included in
12183@var{text} using C escape sequences, such as @samp{\n} to print a
12184newline. @strong{No newline is printed unless you specify one.}
12185In addition to the standard C escape sequences, a backslash followed
12186by a space stands for a space. This is useful for displaying a
12187string with spaces at the beginning or the end, since leading and
5d161b24 12188trailing spaces are otherwise trimmed from all arguments.
c906108c
SS
12189To print @samp{@w{ }and foo =@w{ }}, use the command
12190@samp{echo \@w{ }and foo = \@w{ }}.
12191
12192A backslash at the end of @var{text} can be used, as in C, to continue
12193the command onto subsequent lines. For example,
12194
12195@example
12196echo This is some text\n\
12197which is continued\n\
12198onto several lines.\n
12199@end example
12200
12201produces the same output as
12202
12203@example
12204echo This is some text\n
12205echo which is continued\n
12206echo onto several lines.\n
12207@end example
12208
12209@kindex output
12210@item output @var{expression}
12211Print the value of @var{expression} and nothing but that value: no
12212newlines, no @samp{$@var{nn} = }. The value is not entered in the
5d161b24 12213value history either. @xref{Expressions, ,Expressions}, for more information
c906108c
SS
12214on expressions.
12215
12216@item output/@var{fmt} @var{expression}
12217Print the value of @var{expression} in format @var{fmt}. You can use
12218the same formats as for @code{print}. @xref{Output Formats,,Output
12219formats}, for more information.
12220
12221@kindex printf
12222@item printf @var{string}, @var{expressions}@dots{}
12223Print the values of the @var{expressions} under the control of
12224@var{string}. The @var{expressions} are separated by commas and may be
12225either numbers or pointers. Their values are printed as specified by
12226@var{string}, exactly as if your program were to execute the C
12227subroutine
d4f3574e
SS
12228@c FIXME: the above implies that at least all ANSI C formats are
12229@c supported, but it isn't true: %E and %G don't work (or so it seems).
12230@c Either this is a bug, or the manual should document what formats are
12231@c supported.
c906108c
SS
12232
12233@example
12234printf (@var{string}, @var{expressions}@dots{});
12235@end example
12236
12237For example, you can print two values in hex like this:
12238
12239@smallexample
12240printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo
12241@end smallexample
12242
12243The only backslash-escape sequences that you can use in the format
12244string are the simple ones that consist of backslash followed by a
12245letter.
12246@end table
12247
6d2ebf8b 12248@node Emacs
c906108c
SS
12249@chapter Using @value{GDBN} under @sc{gnu} Emacs
12250
12251@cindex Emacs
12252@cindex @sc{gnu} Emacs
12253A special interface allows you to use @sc{gnu} Emacs to view (and
12254edit) the source files for the program you are debugging with
12255@value{GDBN}.
12256
12257To use this interface, use the command @kbd{M-x gdb} in Emacs. Give the
12258executable file you want to debug as an argument. This command starts
12259@value{GDBN} as a subprocess of Emacs, with input and output through a newly
12260created Emacs buffer.
53a5351d 12261@c (Do not use the @code{-tui} option to run @value{GDBN} from Emacs.)
c906108c
SS
12262
12263Using @value{GDBN} under Emacs is just like using @value{GDBN} normally except for two
12264things:
12265
12266@itemize @bullet
12267@item
12268All ``terminal'' input and output goes through the Emacs buffer.
12269@end itemize
12270
12271This applies both to @value{GDBN} commands and their output, and to the input
12272and output done by the program you are debugging.
12273
12274This is useful because it means that you can copy the text of previous
12275commands and input them again; you can even use parts of the output
12276in this way.
12277
12278All the facilities of Emacs' Shell mode are available for interacting
12279with your program. In particular, you can send signals the usual
12280way---for example, @kbd{C-c C-c} for an interrupt, @kbd{C-c C-z} for a
12281stop.
12282
12283@itemize @bullet
12284@item
12285@value{GDBN} displays source code through Emacs.
12286@end itemize
12287
12288Each time @value{GDBN} displays a stack frame, Emacs automatically finds the
12289source file for that frame and puts an arrow (@samp{=>}) at the
12290left margin of the current line. Emacs uses a separate buffer for
12291source display, and splits the screen to show both your @value{GDBN} session
12292and the source.
12293
12294Explicit @value{GDBN} @code{list} or search commands still produce output as
12295usual, but you probably have no reason to use them from Emacs.
12296
12297@quotation
12298@emph{Warning:} If the directory where your program resides is not your
12299current directory, it can be easy to confuse Emacs about the location of
12300the source files, in which case the auxiliary display buffer does not
12301appear to show your source. @value{GDBN} can find programs by searching your
12302environment's @code{PATH} variable, so the @value{GDBN} input and output
12303session proceeds normally; but Emacs does not get enough information
12304back from @value{GDBN} to locate the source files in this situation. To
12305avoid this problem, either start @value{GDBN} mode from the directory where
12306your program resides, or specify an absolute file name when prompted for the
12307@kbd{M-x gdb} argument.
12308
12309A similar confusion can result if you use the @value{GDBN} @code{file} command to
12310switch to debugging a program in some other location, from an existing
12311@value{GDBN} buffer in Emacs.
12312@end quotation
12313
12314By default, @kbd{M-x gdb} calls the program called @file{gdb}. If
12315you need to call @value{GDBN} by a different name (for example, if you keep
12316several configurations around, with different names) you can set the
12317Emacs variable @code{gdb-command-name}; for example,
12318
12319@example
12320(setq gdb-command-name "mygdb")
12321@end example
12322
12323@noindent
d4f3574e 12324(preceded by @kbd{M-:} or @kbd{ESC :}, or typed in the @code{*scratch*} buffer, or
c906108c
SS
12325in your @file{.emacs} file) makes Emacs call the program named
12326``@code{mygdb}'' instead.
12327
12328In the @value{GDBN} I/O buffer, you can use these special Emacs commands in
12329addition to the standard Shell mode commands:
12330
12331@table @kbd
12332@item C-h m
12333Describe the features of Emacs' @value{GDBN} Mode.
12334
12335@item M-s
12336Execute to another source line, like the @value{GDBN} @code{step} command; also
12337update the display window to show the current file and location.
12338
12339@item M-n
12340Execute to next source line in this function, skipping all function
12341calls, like the @value{GDBN} @code{next} command. Then update the display window
12342to show the current file and location.
12343
12344@item M-i
12345Execute one instruction, like the @value{GDBN} @code{stepi} command; update
12346display window accordingly.
12347
12348@item M-x gdb-nexti
12349Execute to next instruction, using the @value{GDBN} @code{nexti} command; update
12350display window accordingly.
12351
12352@item C-c C-f
12353Execute until exit from the selected stack frame, like the @value{GDBN}
12354@code{finish} command.
12355
12356@item M-c
12357Continue execution of your program, like the @value{GDBN} @code{continue}
12358command.
12359
12360@emph{Warning:} In Emacs v19, this command is @kbd{C-c C-p}.
12361
12362@item M-u
12363Go up the number of frames indicated by the numeric argument
12364(@pxref{Arguments, , Numeric Arguments, Emacs, The @sc{gnu} Emacs Manual}),
12365like the @value{GDBN} @code{up} command.
12366
12367@emph{Warning:} In Emacs v19, this command is @kbd{C-c C-u}.
12368
12369@item M-d
12370Go down the number of frames indicated by the numeric argument, like the
12371@value{GDBN} @code{down} command.
12372
12373@emph{Warning:} In Emacs v19, this command is @kbd{C-c C-d}.
12374
12375@item C-x &
12376Read the number where the cursor is positioned, and insert it at the end
12377of the @value{GDBN} I/O buffer. For example, if you wish to disassemble code
12378around an address that was displayed earlier, type @kbd{disassemble};
12379then move the cursor to the address display, and pick up the
12380argument for @code{disassemble} by typing @kbd{C-x &}.
12381
12382You can customize this further by defining elements of the list
12383@code{gdb-print-command}; once it is defined, you can format or
12384otherwise process numbers picked up by @kbd{C-x &} before they are
12385inserted. A numeric argument to @kbd{C-x &} indicates that you
12386wish special formatting, and also acts as an index to pick an element of the
12387list. If the list element is a string, the number to be inserted is
12388formatted using the Emacs function @code{format}; otherwise the number
12389is passed as an argument to the corresponding list element.
12390@end table
12391
12392In any source file, the Emacs command @kbd{C-x SPC} (@code{gdb-break})
12393tells @value{GDBN} to set a breakpoint on the source line point is on.
12394
12395If you accidentally delete the source-display buffer, an easy way to get
12396it back is to type the command @code{f} in the @value{GDBN} buffer, to
12397request a frame display; when you run under Emacs, this recreates
12398the source buffer if necessary to show you the context of the current
12399frame.
12400
12401The source files displayed in Emacs are in ordinary Emacs buffers
12402which are visiting the source files in the usual way. You can edit
12403the files with these buffers if you wish; but keep in mind that @value{GDBN}
12404communicates with Emacs in terms of line numbers. If you add or
12405delete lines from the text, the line numbers that @value{GDBN} knows cease
12406to correspond properly with the code.
12407
12408@c The following dropped because Epoch is nonstandard. Reactivate
12409@c if/when v19 does something similar. [email protected] 19dec1990
12410@ignore
12411@kindex Emacs Epoch environment
12412@kindex Epoch
12413@kindex inspect
12414
5d161b24 12415Version 18 of @sc{gnu} Emacs has a built-in window system
c906108c
SS
12416called the @code{epoch}
12417environment. Users of this environment can use a new command,
12418@code{inspect} which performs identically to @code{print} except that
12419each value is printed in its own window.
12420@end ignore
c906108c 12421
d700128c 12422@include annotate.texi
7162c0ca 12423@include gdbmi.texinfo
d700128c 12424
6d2ebf8b 12425@node GDB Bugs
c906108c
SS
12426@chapter Reporting Bugs in @value{GDBN}
12427@cindex bugs in @value{GDBN}
12428@cindex reporting bugs in @value{GDBN}
12429
12430Your bug reports play an essential role in making @value{GDBN} reliable.
12431
12432Reporting a bug may help you by bringing a solution to your problem, or it
12433may not. But in any case the principal function of a bug report is to help
12434the entire community by making the next version of @value{GDBN} work better. Bug
12435reports are your contribution to the maintenance of @value{GDBN}.
12436
12437In order for a bug report to serve its purpose, you must include the
12438information that enables us to fix the bug.
12439
12440@menu
12441* Bug Criteria:: Have you found a bug?
12442* Bug Reporting:: How to report bugs
12443@end menu
12444
6d2ebf8b 12445@node Bug Criteria
c906108c
SS
12446@section Have you found a bug?
12447@cindex bug criteria
12448
12449If you are not sure whether you have found a bug, here are some guidelines:
12450
12451@itemize @bullet
12452@cindex fatal signal
12453@cindex debugger crash
12454@cindex crash of debugger
12455@item
12456If the debugger gets a fatal signal, for any input whatever, that is a
12457@value{GDBN} bug. Reliable debuggers never crash.
12458
12459@cindex error on valid input
12460@item
12461If @value{GDBN} produces an error message for valid input, that is a
12462bug. (Note that if you're cross debugging, the problem may also be
12463somewhere in the connection to the target.)
12464
12465@cindex invalid input
12466@item
12467If @value{GDBN} does not produce an error message for invalid input,
12468that is a bug. However, you should note that your idea of
12469``invalid input'' might be our idea of ``an extension'' or ``support
12470for traditional practice''.
12471
12472@item
12473If you are an experienced user of debugging tools, your suggestions
12474for improvement of @value{GDBN} are welcome in any case.
12475@end itemize
12476
6d2ebf8b 12477@node Bug Reporting
c906108c
SS
12478@section How to report bugs
12479@cindex bug reports
12480@cindex @value{GDBN} bugs, reporting
12481
c906108c
SS
12482A number of companies and individuals offer support for @sc{gnu} products.
12483If you obtained @value{GDBN} from a support organization, we recommend you
12484contact that organization first.
12485
12486You can find contact information for many support companies and
12487individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs
12488distribution.
12489@c should add a web page ref...
12490
12491In any event, we also recommend that you send bug reports for
12492@value{GDBN} to this addresses:
12493
12494@example
d4f3574e 12495bug-gdb@@gnu.org
c906108c
SS
12496@end example
12497
12498@strong{Do not send bug reports to @samp{info-gdb}, or to
d4f3574e 12499@samp{help-gdb}, or to any newsgroups.} Most users of @value{GDBN} do
c906108c
SS
12500not want to receive bug reports. Those that do have arranged to receive
12501@samp{bug-gdb}.
12502
12503The mailing list @samp{bug-gdb} has a newsgroup @samp{gnu.gdb.bug} which
12504serves as a repeater. The mailing list and the newsgroup carry exactly
12505the same messages. Often people think of posting bug reports to the
12506newsgroup instead of mailing them. This appears to work, but it has one
12507problem which can be crucial: a newsgroup posting often lacks a mail
12508path back to the sender. Thus, if we need to ask for more information,
12509we may be unable to reach you. For this reason, it is better to send
12510bug reports to the mailing list.
12511
12512As a last resort, send bug reports on paper to:
12513
12514@example
12515@sc{gnu} Debugger Bugs
12516Free Software Foundation Inc.
1251759 Temple Place - Suite 330
12518Boston, MA 02111-1307
12519USA
12520@end example
c906108c
SS
12521
12522The fundamental principle of reporting bugs usefully is this:
12523@strong{report all the facts}. If you are not sure whether to state a
12524fact or leave it out, state it!
12525
12526Often people omit facts because they think they know what causes the
12527problem and assume that some details do not matter. Thus, you might
12528assume that the name of the variable you use in an example does not matter.
12529Well, probably it does not, but one cannot be sure. Perhaps the bug is a
12530stray memory reference which happens to fetch from the location where that
12531name is stored in memory; perhaps, if the name were different, the contents
12532of that location would fool the debugger into doing the right thing despite
12533the bug. Play it safe and give a specific, complete example. That is the
12534easiest thing for you to do, and the most helpful.
12535
12536Keep in mind that the purpose of a bug report is to enable us to fix the
12537bug. It may be that the bug has been reported previously, but neither
12538you nor we can know that unless your bug report is complete and
12539self-contained.
12540
12541Sometimes people give a few sketchy facts and ask, ``Does this ring a
12542bell?'' Those bug reports are useless, and we urge everyone to
12543@emph{refuse to respond to them} except to chide the sender to report
12544bugs properly.
12545
12546To enable us to fix the bug, you should include all these things:
12547
12548@itemize @bullet
12549@item
12550The version of @value{GDBN}. @value{GDBN} announces it if you start
12551with no arguments; you can also print it at any time using @code{show
12552version}.
12553
12554Without this, we will not know whether there is any point in looking for
12555the bug in the current version of @value{GDBN}.
12556
12557@item
12558The type of machine you are using, and the operating system name and
12559version number.
12560
c906108c
SS
12561@item
12562What compiler (and its version) was used to compile @value{GDBN}---e.g.
12563``@value{GCC}--2.8.1''.
c906108c
SS
12564
12565@item
12566What compiler (and its version) was used to compile the program you are
12567debugging---e.g. ``@value{GCC}--2.8.1'', or ``HP92453-01 A.10.32.03 HP
12568C Compiler''. For GCC, you can say @code{gcc --version} to get this
12569information; for other compilers, see the documentation for those
12570compilers.
12571
12572@item
12573The command arguments you gave the compiler to compile your example and
12574observe the bug. For example, did you use @samp{-O}? To guarantee
12575you will not omit something important, list them all. A copy of the
12576Makefile (or the output from make) is sufficient.
12577
12578If we were to try to guess the arguments, we would probably guess wrong
12579and then we might not encounter the bug.
12580
12581@item
12582A complete input script, and all necessary source files, that will
12583reproduce the bug.
12584
12585@item
12586A description of what behavior you observe that you believe is
12587incorrect. For example, ``It gets a fatal signal.''
12588
12589Of course, if the bug is that @value{GDBN} gets a fatal signal, then we
12590will certainly notice it. But if the bug is incorrect output, we might
12591not notice unless it is glaringly wrong. You might as well not give us
12592a chance to make a mistake.
12593
12594Even if the problem you experience is a fatal signal, you should still
12595say so explicitly. Suppose something strange is going on, such as, your
12596copy of @value{GDBN} is out of synch, or you have encountered a bug in
12597the C library on your system. (This has happened!) Your copy might
12598crash and ours would not. If you told us to expect a crash, then when
12599ours fails to crash, we would know that the bug was not happening for
12600us. If you had not told us to expect a crash, then we would not be able
12601to draw any conclusion from our observations.
12602
c906108c
SS
12603@item
12604If you wish to suggest changes to the @value{GDBN} source, send us context
12605diffs. If you even discuss something in the @value{GDBN} source, refer to
12606it by context, not by line number.
12607
12608The line numbers in our development sources will not match those in your
12609sources. Your line numbers would convey no useful information to us.
53a5351d 12610
c906108c
SS
12611@end itemize
12612
12613Here are some things that are not necessary:
12614
12615@itemize @bullet
12616@item
12617A description of the envelope of the bug.
12618
12619Often people who encounter a bug spend a lot of time investigating
12620which changes to the input file will make the bug go away and which
12621changes will not affect it.
12622
12623This is often time consuming and not very useful, because the way we
12624will find the bug is by running a single example under the debugger
12625with breakpoints, not by pure deduction from a series of examples.
12626We recommend that you save your time for something else.
12627
12628Of course, if you can find a simpler example to report @emph{instead}
12629of the original one, that is a convenience for us. Errors in the
12630output will be easier to spot, running under the debugger will take
12631less time, and so on.
12632
12633However, simplification is not vital; if you do not want to do this,
12634report the bug anyway and send us the entire test case you used.
12635
12636@item
12637A patch for the bug.
12638
12639A patch for the bug does help us if it is a good one. But do not omit
12640the necessary information, such as the test case, on the assumption that
12641a patch is all we need. We might see problems with your patch and decide
12642to fix the problem another way, or we might not understand it at all.
12643
12644Sometimes with a program as complicated as @value{GDBN} it is very hard to
12645construct an example that will make the program follow a certain path
12646through the code. If you do not send us the example, we will not be able
12647to construct one, so we will not be able to verify that the bug is fixed.
12648
12649And if we cannot understand what bug you are trying to fix, or why your
12650patch should be an improvement, we will not install it. A test case will
12651help us to understand.
12652
12653@item
12654A guess about what the bug is or what it depends on.
12655
12656Such guesses are usually wrong. Even we cannot guess right about such
12657things without first using the debugger to find the facts.
12658@end itemize
12659
5d161b24 12660@c The readline documentation is distributed with the readline code
c906108c
SS
12661@c and consists of the two following files:
12662@c rluser.texinfo
7be570e7 12663@c inc-hist.texinfo
c906108c
SS
12664@c Use -I with makeinfo to point to the appropriate directory,
12665@c environment var TEXINPUTS with TeX.
12666@include rluser.texinfo
7be570e7 12667@include inc-hist.texinfo
c906108c
SS
12668
12669
6d2ebf8b 12670@node Formatting Documentation
c906108c
SS
12671@appendix Formatting Documentation
12672
12673@cindex @value{GDBN} reference card
12674@cindex reference card
12675The @value{GDBN} 4 release includes an already-formatted reference card, ready
12676for printing with PostScript or Ghostscript, in the @file{gdb}
12677subdirectory of the main source directory@footnote{In
12678@file{gdb-@value{GDBVN}/gdb/refcard.ps} of the version @value{GDBVN}
12679release.}. If you can use PostScript or Ghostscript with your printer,
12680you can print the reference card immediately with @file{refcard.ps}.
12681
12682The release also includes the source for the reference card. You
12683can format it, using @TeX{}, by typing:
12684
12685@example
12686make refcard.dvi
12687@end example
12688
5d161b24
DB
12689The @value{GDBN} reference card is designed to print in @dfn{landscape}
12690mode on US ``letter'' size paper;
c906108c
SS
12691that is, on a sheet 11 inches wide by 8.5 inches
12692high. You will need to specify this form of printing as an option to
12693your @sc{dvi} output program.
12694
12695@cindex documentation
12696
12697All the documentation for @value{GDBN} comes as part of the machine-readable
12698distribution. The documentation is written in Texinfo format, which is
12699a documentation system that uses a single source file to produce both
12700on-line information and a printed manual. You can use one of the Info
12701formatting commands to create the on-line version of the documentation
12702and @TeX{} (or @code{texi2roff}) to typeset the printed version.
12703
12704@value{GDBN} includes an already formatted copy of the on-line Info
12705version of this manual in the @file{gdb} subdirectory. The main Info
12706file is @file{gdb-@value{GDBVN}/gdb/gdb.info}, and it refers to
12707subordinate files matching @samp{gdb.info*} in the same directory. If
12708necessary, you can print out these files, or read them with any editor;
12709but they are easier to read using the @code{info} subsystem in @sc{gnu}
12710Emacs or the standalone @code{info} program, available as part of the
12711@sc{gnu} Texinfo distribution.
12712
12713If you want to format these Info files yourself, you need one of the
12714Info formatting programs, such as @code{texinfo-format-buffer} or
12715@code{makeinfo}.
12716
12717If you have @code{makeinfo} installed, and are in the top level
12718@value{GDBN} source directory (@file{gdb-@value{GDBVN}}, in the case of
12719version @value{GDBVN}), you can make the Info file by typing:
12720
12721@example
12722cd gdb
12723make gdb.info
12724@end example
12725
12726If you want to typeset and print copies of this manual, you need @TeX{},
12727a program to print its @sc{dvi} output files, and @file{texinfo.tex}, the
12728Texinfo definitions file.
12729
12730@TeX{} is a typesetting program; it does not print files directly, but
12731produces output files called @sc{dvi} files. To print a typeset
12732document, you need a program to print @sc{dvi} files. If your system
12733has @TeX{} installed, chances are it has such a program. The precise
12734command to use depends on your system; @kbd{lpr -d} is common; another
12735(for PostScript devices) is @kbd{dvips}. The @sc{dvi} print command may
12736require a file name without any extension or a @samp{.dvi} extension.
12737
12738@TeX{} also requires a macro definitions file called
12739@file{texinfo.tex}. This file tells @TeX{} how to typeset a document
12740written in Texinfo format. On its own, @TeX{} cannot either read or
12741typeset a Texinfo file. @file{texinfo.tex} is distributed with GDB
12742and is located in the @file{gdb-@var{version-number}/texinfo}
12743directory.
12744
12745If you have @TeX{} and a @sc{dvi} printer program installed, you can
12746typeset and print this manual. First switch to the the @file{gdb}
12747subdirectory of the main source directory (for example, to
12748@file{gdb-@value{GDBVN}/gdb}) and type:
12749
12750@example
12751make gdb.dvi
12752@end example
12753
12754Then give @file{gdb.dvi} to your @sc{dvi} printing program.
c906108c 12755
6d2ebf8b 12756@node Installing GDB
c906108c
SS
12757@appendix Installing @value{GDBN}
12758@cindex configuring @value{GDBN}
12759@cindex installation
12760
c906108c
SS
12761@value{GDBN} comes with a @code{configure} script that automates the process
12762of preparing @value{GDBN} for installation; you can then use @code{make} to
12763build the @code{gdb} program.
12764@iftex
12765@c irrelevant in info file; it's as current as the code it lives with.
12766@footnote{If you have a more recent version of @value{GDBN} than @value{GDBVN},
12767look at the @file{README} file in the sources; we may have improved the
12768installation procedures since publishing this manual.}
12769@end iftex
12770
5d161b24
DB
12771The @value{GDBN} distribution includes all the source code you need for
12772@value{GDBN} in a single directory, whose name is usually composed by
c906108c
SS
12773appending the version number to @samp{gdb}.
12774
12775For example, the @value{GDBN} version @value{GDBVN} distribution is in the
12776@file{gdb-@value{GDBVN}} directory. That directory contains:
12777
12778@table @code
12779@item gdb-@value{GDBVN}/configure @r{(and supporting files)}
12780script for configuring @value{GDBN} and all its supporting libraries
12781
12782@item gdb-@value{GDBVN}/gdb
12783the source specific to @value{GDBN} itself
12784
12785@item gdb-@value{GDBVN}/bfd
12786source for the Binary File Descriptor library
12787
12788@item gdb-@value{GDBVN}/include
12789@sc{gnu} include files
12790
12791@item gdb-@value{GDBVN}/libiberty
12792source for the @samp{-liberty} free software library
12793
12794@item gdb-@value{GDBVN}/opcodes
12795source for the library of opcode tables and disassemblers
12796
12797@item gdb-@value{GDBVN}/readline
12798source for the @sc{gnu} command-line interface
12799
12800@item gdb-@value{GDBVN}/glob
12801source for the @sc{gnu} filename pattern-matching subroutine
12802
12803@item gdb-@value{GDBVN}/mmalloc
12804source for the @sc{gnu} memory-mapped malloc package
12805@end table
12806
12807The simplest way to configure and build @value{GDBN} is to run @code{configure}
12808from the @file{gdb-@var{version-number}} source directory, which in
12809this example is the @file{gdb-@value{GDBVN}} directory.
12810
12811First switch to the @file{gdb-@var{version-number}} source directory
12812if you are not already in it; then run @code{configure}. Pass the
12813identifier for the platform on which @value{GDBN} will run as an
12814argument.
12815
12816For example:
12817
12818@example
12819cd gdb-@value{GDBVN}
12820./configure @var{host}
12821make
12822@end example
12823
12824@noindent
12825where @var{host} is an identifier such as @samp{sun4} or
12826@samp{decstation}, that identifies the platform where @value{GDBN} will run.
12827(You can often leave off @var{host}; @code{configure} tries to guess the
12828correct value by examining your system.)
12829
12830Running @samp{configure @var{host}} and then running @code{make} builds the
12831@file{bfd}, @file{readline}, @file{mmalloc}, and @file{libiberty}
12832libraries, then @code{gdb} itself. The configured source files, and the
12833binaries, are left in the corresponding source directories.
12834
12835@need 750
12836@code{configure} is a Bourne-shell (@code{/bin/sh}) script; if your
12837system does not recognize this automatically when you run a different
12838shell, you may need to run @code{sh} on it explicitly:
12839
12840@example
12841sh configure @var{host}
12842@end example
12843
12844If you run @code{configure} from a directory that contains source
12845directories for multiple libraries or programs, such as the
12846@file{gdb-@value{GDBVN}} source directory for version @value{GDBVN}, @code{configure}
12847creates configuration files for every directory level underneath (unless
12848you tell it not to, with the @samp{--norecursion} option).
12849
12850You can run the @code{configure} script from any of the
12851subordinate directories in the @value{GDBN} distribution if you only want to
12852configure that subdirectory, but be sure to specify a path to it.
12853
12854For example, with version @value{GDBVN}, type the following to configure only
12855the @code{bfd} subdirectory:
12856
12857@example
12858@group
12859cd gdb-@value{GDBVN}/bfd
12860../configure @var{host}
12861@end group
12862@end example
12863
12864You can install @code{@value{GDBP}} anywhere; it has no hardwired paths.
12865However, you should make sure that the shell on your path (named by
12866the @samp{SHELL} environment variable) is publicly readable. Remember
12867that @value{GDBN} uses the shell to start your program---some systems refuse to
12868let @value{GDBN} debug child processes whose programs are not readable.
12869
12870@menu
12871* Separate Objdir:: Compiling @value{GDBN} in another directory
12872* Config Names:: Specifying names for hosts and targets
12873* Configure Options:: Summary of options for configure
12874@end menu
12875
6d2ebf8b 12876@node Separate Objdir
c906108c
SS
12877@section Compiling @value{GDBN} in another directory
12878
12879If you want to run @value{GDBN} versions for several host or target machines,
12880you need a different @code{gdb} compiled for each combination of
12881host and target. @code{configure} is designed to make this easy by
12882allowing you to generate each configuration in a separate subdirectory,
12883rather than in the source directory. If your @code{make} program
12884handles the @samp{VPATH} feature (@sc{gnu} @code{make} does), running
12885@code{make} in each of these directories builds the @code{gdb}
12886program specified there.
12887
12888To build @code{gdb} in a separate directory, run @code{configure}
12889with the @samp{--srcdir} option to specify where to find the source.
12890(You also need to specify a path to find @code{configure}
12891itself from your working directory. If the path to @code{configure}
12892would be the same as the argument to @samp{--srcdir}, you can leave out
12893the @samp{--srcdir} option; it is assumed.)
12894
5d161b24 12895For example, with version @value{GDBVN}, you can build @value{GDBN} in a
c906108c
SS
12896separate directory for a Sun 4 like this:
12897
12898@example
12899@group
12900cd gdb-@value{GDBVN}
12901mkdir ../gdb-sun4
12902cd ../gdb-sun4
12903../gdb-@value{GDBVN}/configure sun4
12904make
12905@end group
12906@end example
12907
12908When @code{configure} builds a configuration using a remote source
12909directory, it creates a tree for the binaries with the same structure
12910(and using the same names) as the tree under the source directory. In
12911the example, you'd find the Sun 4 library @file{libiberty.a} in the
12912directory @file{gdb-sun4/libiberty}, and @value{GDBN} itself in
12913@file{gdb-sun4/gdb}.
12914
12915One popular reason to build several @value{GDBN} configurations in separate
5d161b24
DB
12916directories is to configure @value{GDBN} for cross-compiling (where
12917@value{GDBN} runs on one machine---the @dfn{host}---while debugging
12918programs that run on another machine---the @dfn{target}).
c906108c
SS
12919You specify a cross-debugging target by
12920giving the @samp{--target=@var{target}} option to @code{configure}.
12921
12922When you run @code{make} to build a program or library, you must run
12923it in a configured directory---whatever directory you were in when you
12924called @code{configure} (or one of its subdirectories).
12925
12926The @code{Makefile} that @code{configure} generates in each source
12927directory also runs recursively. If you type @code{make} in a source
12928directory such as @file{gdb-@value{GDBVN}} (or in a separate configured
12929directory configured with @samp{--srcdir=@var{dirname}/gdb-@value{GDBVN}}), you
12930will build all the required libraries, and then build GDB.
12931
12932When you have multiple hosts or targets configured in separate
12933directories, you can run @code{make} on them in parallel (for example,
12934if they are NFS-mounted on each of the hosts); they will not interfere
12935with each other.
12936
6d2ebf8b 12937@node Config Names
c906108c
SS
12938@section Specifying names for hosts and targets
12939
12940The specifications used for hosts and targets in the @code{configure}
12941script are based on a three-part naming scheme, but some short predefined
12942aliases are also supported. The full naming scheme encodes three pieces
12943of information in the following pattern:
12944
12945@example
12946@var{architecture}-@var{vendor}-@var{os}
12947@end example
12948
12949For example, you can use the alias @code{sun4} as a @var{host} argument,
12950or as the value for @var{target} in a @code{--target=@var{target}}
12951option. The equivalent full name is @samp{sparc-sun-sunos4}.
12952
12953The @code{configure} script accompanying @value{GDBN} does not provide
12954any query facility to list all supported host and target names or
12955aliases. @code{configure} calls the Bourne shell script
12956@code{config.sub} to map abbreviations to full names; you can read the
12957script, if you wish, or you can use it to test your guesses on
12958abbreviations---for example:
12959
12960@smallexample
12961% sh config.sub i386-linux
12962i386-pc-linux-gnu
12963% sh config.sub alpha-linux
12964alpha-unknown-linux-gnu
12965% sh config.sub hp9k700
12966hppa1.1-hp-hpux
12967% sh config.sub sun4
12968sparc-sun-sunos4.1.1
12969% sh config.sub sun3
12970m68k-sun-sunos4.1.1
12971% sh config.sub i986v
12972Invalid configuration `i986v': machine `i986v' not recognized
12973@end smallexample
12974
12975@noindent
12976@code{config.sub} is also distributed in the @value{GDBN} source
12977directory (@file{gdb-@value{GDBVN}}, for version @value{GDBVN}).
12978
6d2ebf8b 12979@node Configure Options
c906108c
SS
12980@section @code{configure} options
12981
12982Here is a summary of the @code{configure} options and arguments that
12983are most often useful for building @value{GDBN}. @code{configure} also has
12984several other options not listed here. @inforef{What Configure
12985Does,,configure.info}, for a full explanation of @code{configure}.
12986
12987@example
12988configure @r{[}--help@r{]}
12989 @r{[}--prefix=@var{dir}@r{]}
12990 @r{[}--exec-prefix=@var{dir}@r{]}
12991 @r{[}--srcdir=@var{dirname}@r{]}
12992 @r{[}--norecursion@r{]} @r{[}--rm@r{]}
12993 @r{[}--target=@var{target}@r{]}
12994 @var{host}
12995@end example
12996
12997@noindent
12998You may introduce options with a single @samp{-} rather than
12999@samp{--} if you prefer; but you may abbreviate option names if you use
13000@samp{--}.
13001
13002@table @code
13003@item --help
13004Display a quick summary of how to invoke @code{configure}.
13005
13006@item --prefix=@var{dir}
13007Configure the source to install programs and files under directory
13008@file{@var{dir}}.
13009
13010@item --exec-prefix=@var{dir}
13011Configure the source to install programs under directory
13012@file{@var{dir}}.
13013
13014@c avoid splitting the warning from the explanation:
13015@need 2000
13016@item --srcdir=@var{dirname}
13017@strong{Warning: using this option requires @sc{gnu} @code{make}, or another
13018@code{make} that implements the @code{VPATH} feature.}@*
13019Use this option to make configurations in directories separate from the
13020@value{GDBN} source directories. Among other things, you can use this to
13021build (or maintain) several configurations simultaneously, in separate
13022directories. @code{configure} writes configuration specific files in
13023the current directory, but arranges for them to use the source in the
13024directory @var{dirname}. @code{configure} creates directories under
13025the working directory in parallel to the source directories below
13026@var{dirname}.
13027
13028@item --norecursion
13029Configure only the directory level where @code{configure} is executed; do not
13030propagate configuration to subdirectories.
13031
13032@item --target=@var{target}
13033Configure @value{GDBN} for cross-debugging programs running on the specified
13034@var{target}. Without this option, @value{GDBN} is configured to debug
13035programs that run on the same machine (@var{host}) as @value{GDBN} itself.
13036
13037There is no convenient way to generate a list of all available targets.
13038
13039@item @var{host} @dots{}
13040Configure @value{GDBN} to run on the specified @var{host}.
13041
13042There is no convenient way to generate a list of all available hosts.
13043@end table
13044
13045There are many other options available as well, but they are generally
13046needed for special purposes only.
5d161b24 13047
6d2ebf8b 13048@node Index
c906108c
SS
13049@unnumbered Index
13050
13051@printindex cp
13052
13053@tex
13054% I think something like @colophon should be in texinfo. In the
13055% meantime:
13056\long\def\colophon{\hbox to0pt{}\vfill
13057\centerline{The body of this manual is set in}
13058\centerline{\fontname\tenrm,}
13059\centerline{with headings in {\bf\fontname\tenbf}}
13060\centerline{and examples in {\tt\fontname\tentt}.}
13061\centerline{{\it\fontname\tenit\/},}
13062\centerline{{\bf\fontname\tenbf}, and}
13063\centerline{{\sl\fontname\tensl\/}}
13064\centerline{are used for emphasis.}\vfill}
13065\page\colophon
13066% Blame: [email protected], 1991.
13067@end tex
13068
449f3b6c
AC
13069@c TeX can handle the contents at the start but makeinfo 3.12 can not
13070@ifinfo
c906108c 13071@contents
449f3b6c
AC
13072@end ifinfo
13073@ifhtml
13074@contents
13075@end ifhtml
13076
c906108c 13077@bye
This page took 1.759809 seconds and 4 git commands to generate.