(debug_apply_rela_addends): Remove redundant %s from printf string.
[deliverable/binutils-gdb.git] / gdb / doc / gdb.texinfo
CommitLineData
c906108c 1\input texinfo @c -*-texinfo-*-
b6ba6518 2@c Copyright 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998,
7d51c7de 3@c 1999, 2000, 2001, 2002, 2003, 2004, 2005
c906108c
SS
4@c Free Software Foundation, Inc.
5@c
5d161b24 6@c %**start of header
c906108c
SS
7@c makeinfo ignores cmds prev to setfilename, so its arg cannot make use
8@c of @set vars. However, you can override filename with makeinfo -o.
9@setfilename gdb.info
10@c
11@include gdb-cfg.texi
12@c
c906108c 13@settitle Debugging with @value{GDBN}
c906108c
SS
14@setchapternewpage odd
15@c %**end of header
16
17@iftex
18@c @smallbook
19@c @cropmarks
20@end iftex
21
22@finalout
23@syncodeindex ky cp
24
41afff9a 25@c readline appendices use @vindex, @findex and @ftable,
48e934c6 26@c annotate.texi and gdbmi use @findex.
c906108c 27@syncodeindex vr cp
41afff9a 28@syncodeindex fn cp
c906108c
SS
29
30@c !!set GDB manual's edition---not the same as GDB version!
9fe8321b 31@c This is updated by GNU Press.
e9c75b65 32@set EDITION Ninth
c906108c 33
87885426
FN
34@c !!set GDB edit command default editor
35@set EDITOR /bin/ex
c906108c 36
6c0e9fb3 37@c THIS MANUAL REQUIRES TEXINFO 4.0 OR LATER.
c906108c 38
c906108c 39@c This is a dir.info fragment to support semi-automated addition of
6d2ebf8b 40@c manuals to an info tree.
03727ca6 41@dircategory Software development
96a2c332 42@direntry
03727ca6 43* Gdb: (gdb). The GNU debugger.
96a2c332
SS
44@end direntry
45
c906108c
SS
46@ifinfo
47This file documents the @sc{gnu} debugger @value{GDBN}.
48
49
9fe8321b
AC
50This is the @value{EDITION} Edition, of @cite{Debugging with
51@value{GDBN}: the @sc{gnu} Source-Level Debugger} for @value{GDBN}
52Version @value{GDBVN}.
c906108c 53
8a037dd7 54Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998,@*
7d51c7de
BR
55 1999, 2000, 2001, 2002, 2003, 2004, 2005@*
56 Free Software Foundation, Inc.
c906108c 57
e9c75b65
EZ
58Permission is granted to copy, distribute and/or modify this document
59under the terms of the GNU Free Documentation License, Version 1.1 or
60any later version published by the Free Software Foundation; with the
959acfd1
EZ
61Invariant Sections being ``Free Software'' and ``Free Software Needs
62Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,''
63and with the Back-Cover Texts as in (a) below.
c906108c 64
6826cf00
EZ
65(a) The Free Software Foundation's Back-Cover Text is: ``You have
66freedom to copy and modify this GNU Manual, like GNU software. Copies
67published by the Free Software Foundation raise funds for GNU
68development.''
c906108c
SS
69@end ifinfo
70
71@titlepage
72@title Debugging with @value{GDBN}
73@subtitle The @sc{gnu} Source-Level Debugger
c906108c 74@sp 1
c906108c 75@subtitle @value{EDITION} Edition, for @value{GDBN} version @value{GDBVN}
9e9c5ae7 76@author Richard Stallman, Roland Pesch, Stan Shebs, et al.
c906108c 77@page
c906108c
SS
78@tex
79{\parskip=0pt
53a5351d 80\hfill (Send bugs and comments on @value{GDBN} to bug-gdb\@gnu.org.)\par
c906108c
SS
81\hfill {\it Debugging with @value{GDBN}}\par
82\hfill \TeX{}info \texinfoversion\par
83}
84@end tex
53a5351d 85
c906108c 86@vskip 0pt plus 1filll
8a037dd7 87Copyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995,
7d51c7de
BR
881996, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005
89Free Software Foundation, Inc.
c906108c 90@sp 2
c906108c
SS
91Published by the Free Software Foundation @*
9259 Temple Place - Suite 330, @*
93Boston, MA 02111-1307 USA @*
6d2ebf8b 94ISBN 1-882114-77-9 @*
e9c75b65
EZ
95
96Permission is granted to copy, distribute and/or modify this document
97under the terms of the GNU Free Documentation License, Version 1.1 or
98any later version published by the Free Software Foundation; with the
959acfd1
EZ
99Invariant Sections being ``Free Software'' and ``Free Software Needs
100Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,''
101and with the Back-Cover Texts as in (a) below.
e9c75b65 102
6826cf00
EZ
103(a) The Free Software Foundation's Back-Cover Text is: ``You have
104freedom to copy and modify this GNU Manual, like GNU software. Copies
105published by the Free Software Foundation raise funds for GNU
106development.''
c906108c
SS
107@end titlepage
108@page
109
6c0e9fb3 110@ifnottex
6d2ebf8b
SS
111@node Top, Summary, (dir), (dir)
112
c906108c
SS
113@top Debugging with @value{GDBN}
114
115This file describes @value{GDBN}, the @sc{gnu} symbolic debugger.
116
9fe8321b 117This is the @value{EDITION} Edition, for @value{GDBN} Version
c906108c
SS
118@value{GDBVN}.
119
7d51c7de 120Copyright (C) 1988-2005 Free Software Foundation, Inc.
6d2ebf8b
SS
121
122@menu
123* Summary:: Summary of @value{GDBN}
124* Sample Session:: A sample @value{GDBN} session
125
126* Invocation:: Getting in and out of @value{GDBN}
127* Commands:: @value{GDBN} commands
128* Running:: Running programs under @value{GDBN}
129* Stopping:: Stopping and continuing
130* Stack:: Examining the stack
131* Source:: Examining source files
132* Data:: Examining data
e2e0bcd1 133* Macros:: Preprocessor Macros
b37052ae 134* Tracepoints:: Debugging remote targets non-intrusively
df0cd8c5 135* Overlays:: Debugging programs that use overlays
6d2ebf8b
SS
136
137* Languages:: Using @value{GDBN} with different languages
138
139* Symbols:: Examining the symbol table
140* Altering:: Altering execution
141* GDB Files:: @value{GDBN} files
142* Targets:: Specifying a debugging target
6b2f586d 143* Remote Debugging:: Debugging remote programs
6d2ebf8b
SS
144* Configurations:: Configuration-specific information
145* Controlling GDB:: Controlling @value{GDBN}
146* Sequences:: Canned sequences of commands
c4555f82 147* TUI:: @value{GDBN} Text User Interface
21c294e6 148* Interpreters:: Command Interpreters
6d2ebf8b
SS
149* Emacs:: Using @value{GDBN} under @sc{gnu} Emacs
150* Annotations:: @value{GDBN}'s annotation interface.
7162c0ca 151* GDB/MI:: @value{GDBN}'s Machine Interface.
6d2ebf8b
SS
152
153* GDB Bugs:: Reporting bugs in @value{GDBN}
154* Formatting Documentation:: How to format and print @value{GDBN} documentation
155
156* Command Line Editing:: Command Line Editing
157* Using History Interactively:: Using History Interactively
158* Installing GDB:: Installing GDB
eb12ee30 159* Maintenance Commands:: Maintenance Commands
e0ce93ac 160* Remote Protocol:: GDB Remote Serial Protocol
f418dd93 161* Agent Expressions:: The GDB Agent Expression Mechanism
aab4e0ec
AC
162* Copying:: GNU General Public License says
163 how you can copy and share GDB
6826cf00 164* GNU Free Documentation License:: The license for this documentation
6d2ebf8b
SS
165* Index:: Index
166@end menu
167
6c0e9fb3 168@end ifnottex
c906108c 169
449f3b6c 170@contents
449f3b6c 171
6d2ebf8b 172@node Summary
c906108c
SS
173@unnumbered Summary of @value{GDBN}
174
175The purpose of a debugger such as @value{GDBN} is to allow you to see what is
176going on ``inside'' another program while it executes---or what another
177program was doing at the moment it crashed.
178
179@value{GDBN} can do four main kinds of things (plus other things in support of
180these) to help you catch bugs in the act:
181
182@itemize @bullet
183@item
184Start your program, specifying anything that might affect its behavior.
185
186@item
187Make your program stop on specified conditions.
188
189@item
190Examine what has happened, when your program has stopped.
191
192@item
193Change things in your program, so you can experiment with correcting the
194effects of one bug and go on to learn about another.
195@end itemize
196
49efadf5 197You can use @value{GDBN} to debug programs written in C and C@t{++}.
9c16f35a 198For more information, see @ref{Supported languages,,Supported languages}.
c906108c
SS
199For more information, see @ref{C,,C and C++}.
200
cce74817 201@cindex Modula-2
e632838e
AC
202Support for Modula-2 is partial. For information on Modula-2, see
203@ref{Modula-2,,Modula-2}.
c906108c 204
cce74817
JM
205@cindex Pascal
206Debugging Pascal programs which use sets, subranges, file variables, or
207nested functions does not currently work. @value{GDBN} does not support
208entering expressions, printing values, or similar features using Pascal
209syntax.
c906108c 210
c906108c
SS
211@cindex Fortran
212@value{GDBN} can be used to debug programs written in Fortran, although
53a5351d 213it may be necessary to refer to some variables with a trailing
cce74817 214underscore.
c906108c 215
b37303ee
AF
216@value{GDBN} can be used to debug programs written in Objective-C,
217using either the Apple/NeXT or the GNU Objective-C runtime.
218
c906108c
SS
219@menu
220* Free Software:: Freely redistributable software
221* Contributors:: Contributors to GDB
222@end menu
223
6d2ebf8b 224@node Free Software
c906108c
SS
225@unnumberedsec Free software
226
5d161b24 227@value{GDBN} is @dfn{free software}, protected by the @sc{gnu}
c906108c
SS
228General Public License
229(GPL). The GPL gives you the freedom to copy or adapt a licensed
230program---but every person getting a copy also gets with it the
231freedom to modify that copy (which means that they must get access to
232the source code), and the freedom to distribute further copies.
233Typical software companies use copyrights to limit your freedoms; the
234Free Software Foundation uses the GPL to preserve these freedoms.
235
236Fundamentally, the General Public License is a license which says that
237you have these freedoms and that you cannot take these freedoms away
238from anyone else.
239
2666264b 240@unnumberedsec Free Software Needs Free Documentation
959acfd1
EZ
241
242The biggest deficiency in the free software community today is not in
243the software---it is the lack of good free documentation that we can
244include with the free software. Many of our most important
245programs do not come with free reference manuals and free introductory
246texts. Documentation is an essential part of any software package;
247when an important free software package does not come with a free
248manual and a free tutorial, that is a major gap. We have many such
249gaps today.
250
251Consider Perl, for instance. The tutorial manuals that people
252normally use are non-free. How did this come about? Because the
253authors of those manuals published them with restrictive terms---no
254copying, no modification, source files not available---which exclude
255them from the free software world.
256
257That wasn't the first time this sort of thing happened, and it was far
258from the last. Many times we have heard a GNU user eagerly describe a
259manual that he is writing, his intended contribution to the community,
260only to learn that he had ruined everything by signing a publication
261contract to make it non-free.
262
263Free documentation, like free software, is a matter of freedom, not
264price. The problem with the non-free manual is not that publishers
265charge a price for printed copies---that in itself is fine. (The Free
266Software Foundation sells printed copies of manuals, too.) The
267problem is the restrictions on the use of the manual. Free manuals
268are available in source code form, and give you permission to copy and
269modify. Non-free manuals do not allow this.
270
271The criteria of freedom for a free manual are roughly the same as for
272free software. Redistribution (including the normal kinds of
273commercial redistribution) must be permitted, so that the manual can
274accompany every copy of the program, both on-line and on paper.
275
276Permission for modification of the technical content is crucial too.
277When people modify the software, adding or changing features, if they
278are conscientious they will change the manual too---so they can
279provide accurate and clear documentation for the modified program. A
280manual that leaves you no choice but to write a new manual to document
281a changed version of the program is not really available to our
282community.
283
284Some kinds of limits on the way modification is handled are
285acceptable. For example, requirements to preserve the original
286author's copyright notice, the distribution terms, or the list of
287authors, are ok. It is also no problem to require modified versions
288to include notice that they were modified. Even entire sections that
289may not be deleted or changed are acceptable, as long as they deal
290with nontechnical topics (like this one). These kinds of restrictions
291are acceptable because they don't obstruct the community's normal use
292of the manual.
293
294However, it must be possible to modify all the @emph{technical}
295content of the manual, and then distribute the result in all the usual
296media, through all the usual channels. Otherwise, the restrictions
297obstruct the use of the manual, it is not free, and we need another
298manual to replace it.
299
300Please spread the word about this issue. Our community continues to
301lose manuals to proprietary publishing. If we spread the word that
302free software needs free reference manuals and free tutorials, perhaps
303the next person who wants to contribute by writing documentation will
304realize, before it is too late, that only free manuals contribute to
305the free software community.
306
307If you are writing documentation, please insist on publishing it under
308the GNU Free Documentation License or another free documentation
309license. Remember that this decision requires your approval---you
310don't have to let the publisher decide. Some commercial publishers
311will use a free license if you insist, but they will not propose the
312option; it is up to you to raise the issue and say firmly that this is
313what you want. If the publisher you are dealing with refuses, please
314try other publishers. If you're not sure whether a proposed license
42584a72 315is free, write to @email{licensing@@gnu.org}.
959acfd1
EZ
316
317You can encourage commercial publishers to sell more free, copylefted
318manuals and tutorials by buying them, and particularly by buying
319copies from the publishers that paid for their writing or for major
320improvements. Meanwhile, try to avoid buying non-free documentation
321at all. Check the distribution terms of a manual before you buy it,
322and insist that whoever seeks your business must respect your freedom.
72c9928d
EZ
323Check the history of the book, and try to reward the publishers that
324have paid or pay the authors to work on it.
959acfd1
EZ
325
326The Free Software Foundation maintains a list of free documentation
327published by other publishers, at
328@url{http://www.fsf.org/doc/other-free-books.html}.
329
6d2ebf8b 330@node Contributors
96a2c332
SS
331@unnumberedsec Contributors to @value{GDBN}
332
333Richard Stallman was the original author of @value{GDBN}, and of many
334other @sc{gnu} programs. Many others have contributed to its
335development. This section attempts to credit major contributors. One
336of the virtues of free software is that everyone is free to contribute
337to it; with regret, we cannot actually acknowledge everyone here. The
338file @file{ChangeLog} in the @value{GDBN} distribution approximates a
c906108c
SS
339blow-by-blow account.
340
341Changes much prior to version 2.0 are lost in the mists of time.
342
343@quotation
344@emph{Plea:} Additions to this section are particularly welcome. If you
345or your friends (or enemies, to be evenhanded) have been unfairly
346omitted from this list, we would like to add your names!
347@end quotation
348
349So that they may not regard their many labors as thankless, we
350particularly thank those who shepherded @value{GDBN} through major
351releases:
faae5abe 352Andrew Cagney (releases 6.1, 6.0, 5.3, 5.2, 5.1 and 5.0);
c906108c
SS
353Jim Blandy (release 4.18);
354Jason Molenda (release 4.17);
355Stan Shebs (release 4.14);
356Fred Fish (releases 4.16, 4.15, 4.13, 4.12, 4.11, 4.10, and 4.9);
357Stu Grossman and John Gilmore (releases 4.8, 4.7, 4.6, 4.5, and 4.4);
358John Gilmore (releases 4.3, 4.2, 4.1, 4.0, and 3.9);
359Jim Kingdon (releases 3.5, 3.4, and 3.3);
360and Randy Smith (releases 3.2, 3.1, and 3.0).
361
362Richard Stallman, assisted at various times by Peter TerMaat, Chris
363Hanson, and Richard Mlynarik, handled releases through 2.8.
364
b37052ae
EZ
365Michael Tiemann is the author of most of the @sc{gnu} C@t{++} support
366in @value{GDBN}, with significant additional contributions from Per
367Bothner and Daniel Berlin. James Clark wrote the @sc{gnu} C@t{++}
368demangler. Early work on C@t{++} was by Peter TerMaat (who also did
369much general update work leading to release 3.0).
c906108c 370
b37052ae 371@value{GDBN} uses the BFD subroutine library to examine multiple
c906108c
SS
372object-file formats; BFD was a joint project of David V.
373Henkel-Wallace, Rich Pixley, Steve Chamberlain, and John Gilmore.
374
375David Johnson wrote the original COFF support; Pace Willison did
376the original support for encapsulated COFF.
377
0179ffac 378Brent Benson of Harris Computer Systems contributed DWARF 2 support.
c906108c
SS
379
380Adam de Boor and Bradley Davis contributed the ISI Optimum V support.
381Per Bothner, Noboyuki Hikichi, and Alessandro Forin contributed MIPS
382support.
383Jean-Daniel Fekete contributed Sun 386i support.
384Chris Hanson improved the HP9000 support.
385Noboyuki Hikichi and Tomoyuki Hasei contributed Sony/News OS 3 support.
386David Johnson contributed Encore Umax support.
387Jyrki Kuoppala contributed Altos 3068 support.
388Jeff Law contributed HP PA and SOM support.
389Keith Packard contributed NS32K support.
390Doug Rabson contributed Acorn Risc Machine support.
391Bob Rusk contributed Harris Nighthawk CX-UX support.
392Chris Smith contributed Convex support (and Fortran debugging).
393Jonathan Stone contributed Pyramid support.
394Michael Tiemann contributed SPARC support.
395Tim Tucker contributed support for the Gould NP1 and Gould Powernode.
396Pace Willison contributed Intel 386 support.
397Jay Vosburgh contributed Symmetry support.
a37295f9 398Marko Mlinar contributed OpenRISC 1000 support.
c906108c 399
1104b9e7 400Andreas Schwab contributed M68K @sc{gnu}/Linux support.
c906108c
SS
401
402Rich Schaefer and Peter Schauer helped with support of SunOS shared
403libraries.
404
405Jay Fenlason and Roland McGrath ensured that @value{GDBN} and GAS agree
406about several machine instruction sets.
407
408Patrick Duval, Ted Goldstein, Vikram Koka and Glenn Engel helped develop
409remote debugging. Intel Corporation, Wind River Systems, AMD, and ARM
410contributed remote debugging modules for the i960, VxWorks, A29K UDI,
411and RDI targets, respectively.
412
413Brian Fox is the author of the readline libraries providing
414command-line editing and command history.
415
7a292a7a
SS
416Andrew Beers of SUNY Buffalo wrote the language-switching code, the
417Modula-2 support, and contributed the Languages chapter of this manual.
c906108c 418
5d161b24 419Fred Fish wrote most of the support for Unix System Vr4.
b37052ae 420He also enhanced the command-completion support to cover C@t{++} overloaded
c906108c 421symbols.
c906108c 422
f24c5e49
KI
423Hitachi America (now Renesas America), Ltd. sponsored the support for
424H8/300, H8/500, and Super-H processors.
c906108c
SS
425
426NEC sponsored the support for the v850, Vr4xxx, and Vr5xxx processors.
427
f24c5e49
KI
428Mitsubishi (now Renesas) sponsored the support for D10V, D30V, and M32R/D
429processors.
c906108c
SS
430
431Toshiba sponsored the support for the TX39 Mips processor.
432
433Matsushita sponsored the support for the MN10200 and MN10300 processors.
434
96a2c332 435Fujitsu sponsored the support for SPARClite and FR30 processors.
c906108c
SS
436
437Kung Hsu, Jeff Law, and Rick Sladkey added support for hardware
438watchpoints.
439
440Michael Snyder added support for tracepoints.
441
442Stu Grossman wrote gdbserver.
443
444Jim Kingdon, Peter Schauer, Ian Taylor, and Stu Grossman made
96a2c332 445nearly innumerable bug fixes and cleanups throughout @value{GDBN}.
c906108c
SS
446
447The following people at the Hewlett-Packard Company contributed
448support for the PA-RISC 2.0 architecture, HP-UX 10.20, 10.30, and 11.0
b37052ae 449(narrow mode), HP's implementation of kernel threads, HP's aC@t{++}
d0d5df6f
AC
450compiler, and the Text User Interface (nee Terminal User Interface):
451Ben Krepp, Richard Title, John Bishop, Susan Macchia, Kathy Mann,
452Satish Pai, India Paul, Steve Rehrauer, and Elena Zannoni. Kim Haase
453provided HP-specific information in this manual.
c906108c 454
b37052ae
EZ
455DJ Delorie ported @value{GDBN} to MS-DOS, for the DJGPP project.
456Robert Hoehne made significant contributions to the DJGPP port.
457
96a2c332
SS
458Cygnus Solutions has sponsored @value{GDBN} maintenance and much of its
459development since 1991. Cygnus engineers who have worked on @value{GDBN}
2df3850c
JM
460fulltime include Mark Alexander, Jim Blandy, Per Bothner, Kevin
461Buettner, Edith Epstein, Chris Faylor, Fred Fish, Martin Hunt, Jim
462Ingham, John Gilmore, Stu Grossman, Kung Hsu, Jim Kingdon, John Metzler,
463Fernando Nasser, Geoffrey Noer, Dawn Perchik, Rich Pixley, Zdenek
464Radouch, Keith Seitz, Stan Shebs, David Taylor, and Elena Zannoni. In
465addition, Dave Brolley, Ian Carmichael, Steve Chamberlain, Nick Clifton,
466JT Conklin, Stan Cox, DJ Delorie, Ulrich Drepper, Frank Eigler, Doug
467Evans, Sean Fagan, David Henkel-Wallace, Richard Henderson, Jeff
468Holcomb, Jeff Law, Jim Lemke, Tom Lord, Bob Manson, Michael Meissner,
469Jason Merrill, Catherine Moore, Drew Moseley, Ken Raeburn, Gavin
470Romig-Koch, Rob Savoye, Jamie Smith, Mike Stump, Ian Taylor, Angela
471Thomas, Michael Tiemann, Tom Tromey, Ron Unrau, Jim Wilson, and David
472Zuhn have made contributions both large and small.
c906108c 473
e2e0bcd1
JB
474Jim Blandy added support for preprocessor macros, while working for Red
475Hat.
c906108c 476
6d2ebf8b 477@node Sample Session
c906108c
SS
478@chapter A Sample @value{GDBN} Session
479
480You can use this manual at your leisure to read all about @value{GDBN}.
481However, a handful of commands are enough to get started using the
482debugger. This chapter illustrates those commands.
483
484@iftex
485In this sample session, we emphasize user input like this: @b{input},
486to make it easier to pick out from the surrounding output.
487@end iftex
488
489@c FIXME: this example may not be appropriate for some configs, where
490@c FIXME...primary interest is in remote use.
491
492One of the preliminary versions of @sc{gnu} @code{m4} (a generic macro
493processor) exhibits the following bug: sometimes, when we change its
494quote strings from the default, the commands used to capture one macro
495definition within another stop working. In the following short @code{m4}
496session, we define a macro @code{foo} which expands to @code{0000}; we
497then use the @code{m4} built-in @code{defn} to define @code{bar} as the
498same thing. However, when we change the open quote string to
499@code{<QUOTE>} and the close quote string to @code{<UNQUOTE>}, the same
500procedure fails to define a new synonym @code{baz}:
501
502@smallexample
503$ @b{cd gnu/m4}
504$ @b{./m4}
505@b{define(foo,0000)}
506
507@b{foo}
5080000
509@b{define(bar,defn(`foo'))}
510
511@b{bar}
5120000
513@b{changequote(<QUOTE>,<UNQUOTE>)}
514
515@b{define(baz,defn(<QUOTE>foo<UNQUOTE>))}
516@b{baz}
517@b{C-d}
518m4: End of input: 0: fatal error: EOF in string
519@end smallexample
520
521@noindent
522Let us use @value{GDBN} to try to see what is going on.
523
c906108c
SS
524@smallexample
525$ @b{@value{GDBP} m4}
526@c FIXME: this falsifies the exact text played out, to permit smallbook
527@c FIXME... format to come out better.
528@value{GDBN} is free software and you are welcome to distribute copies
5d161b24 529 of it under certain conditions; type "show copying" to see
c906108c 530 the conditions.
5d161b24 531There is absolutely no warranty for @value{GDBN}; type "show warranty"
c906108c
SS
532 for details.
533
534@value{GDBN} @value{GDBVN}, Copyright 1999 Free Software Foundation, Inc...
535(@value{GDBP})
536@end smallexample
c906108c
SS
537
538@noindent
539@value{GDBN} reads only enough symbol data to know where to find the
540rest when needed; as a result, the first prompt comes up very quickly.
541We now tell @value{GDBN} to use a narrower display width than usual, so
542that examples fit in this manual.
543
544@smallexample
545(@value{GDBP}) @b{set width 70}
546@end smallexample
547
548@noindent
549We need to see how the @code{m4} built-in @code{changequote} works.
550Having looked at the source, we know the relevant subroutine is
551@code{m4_changequote}, so we set a breakpoint there with the @value{GDBN}
552@code{break} command.
553
554@smallexample
555(@value{GDBP}) @b{break m4_changequote}
556Breakpoint 1 at 0x62f4: file builtin.c, line 879.
557@end smallexample
558
559@noindent
560Using the @code{run} command, we start @code{m4} running under @value{GDBN}
561control; as long as control does not reach the @code{m4_changequote}
562subroutine, the program runs as usual:
563
564@smallexample
565(@value{GDBP}) @b{run}
566Starting program: /work/Editorial/gdb/gnu/m4/m4
567@b{define(foo,0000)}
568
569@b{foo}
5700000
571@end smallexample
572
573@noindent
574To trigger the breakpoint, we call @code{changequote}. @value{GDBN}
575suspends execution of @code{m4}, displaying information about the
576context where it stops.
577
578@smallexample
579@b{changequote(<QUOTE>,<UNQUOTE>)}
580
5d161b24 581Breakpoint 1, m4_changequote (argc=3, argv=0x33c70)
c906108c
SS
582 at builtin.c:879
583879 if (bad_argc(TOKEN_DATA_TEXT(argv[0]),argc,1,3))
584@end smallexample
585
586@noindent
587Now we use the command @code{n} (@code{next}) to advance execution to
588the next line of the current function.
589
590@smallexample
591(@value{GDBP}) @b{n}
592882 set_quotes((argc >= 2) ? TOKEN_DATA_TEXT(argv[1])\
593 : nil,
594@end smallexample
595
596@noindent
597@code{set_quotes} looks like a promising subroutine. We can go into it
598by using the command @code{s} (@code{step}) instead of @code{next}.
599@code{step} goes to the next line to be executed in @emph{any}
600subroutine, so it steps into @code{set_quotes}.
601
602@smallexample
603(@value{GDBP}) @b{s}
604set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>")
605 at input.c:530
606530 if (lquote != def_lquote)
607@end smallexample
608
609@noindent
610The display that shows the subroutine where @code{m4} is now
611suspended (and its arguments) is called a stack frame display. It
612shows a summary of the stack. We can use the @code{backtrace}
613command (which can also be spelled @code{bt}), to see where we are
614in the stack as a whole: the @code{backtrace} command displays a
615stack frame for each active subroutine.
616
617@smallexample
618(@value{GDBP}) @b{bt}
619#0 set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>")
620 at input.c:530
5d161b24 621#1 0x6344 in m4_changequote (argc=3, argv=0x33c70)
c906108c
SS
622 at builtin.c:882
623#2 0x8174 in expand_macro (sym=0x33320) at macro.c:242
624#3 0x7a88 in expand_token (obs=0x0, t=209696, td=0xf7fffa30)
625 at macro.c:71
626#4 0x79dc in expand_input () at macro.c:40
627#5 0x2930 in main (argc=0, argv=0xf7fffb20) at m4.c:195
628@end smallexample
629
630@noindent
631We step through a few more lines to see what happens. The first two
632times, we can use @samp{s}; the next two times we use @code{n} to avoid
633falling into the @code{xstrdup} subroutine.
634
635@smallexample
636(@value{GDBP}) @b{s}
6370x3b5c 532 if (rquote != def_rquote)
638(@value{GDBP}) @b{s}
6390x3b80 535 lquote = (lq == nil || *lq == '\0') ? \
640def_lquote : xstrdup(lq);
641(@value{GDBP}) @b{n}
642536 rquote = (rq == nil || *rq == '\0') ? def_rquote\
643 : xstrdup(rq);
644(@value{GDBP}) @b{n}
645538 len_lquote = strlen(rquote);
646@end smallexample
647
648@noindent
649The last line displayed looks a little odd; we can examine the variables
650@code{lquote} and @code{rquote} to see if they are in fact the new left
651and right quotes we specified. We use the command @code{p}
652(@code{print}) to see their values.
653
654@smallexample
655(@value{GDBP}) @b{p lquote}
656$1 = 0x35d40 "<QUOTE>"
657(@value{GDBP}) @b{p rquote}
658$2 = 0x35d50 "<UNQUOTE>"
659@end smallexample
660
661@noindent
662@code{lquote} and @code{rquote} are indeed the new left and right quotes.
663To look at some context, we can display ten lines of source
664surrounding the current line with the @code{l} (@code{list}) command.
665
666@smallexample
667(@value{GDBP}) @b{l}
668533 xfree(rquote);
669534
670535 lquote = (lq == nil || *lq == '\0') ? def_lquote\
671 : xstrdup (lq);
672536 rquote = (rq == nil || *rq == '\0') ? def_rquote\
673 : xstrdup (rq);
674537
675538 len_lquote = strlen(rquote);
676539 len_rquote = strlen(lquote);
677540 @}
678541
679542 void
680@end smallexample
681
682@noindent
683Let us step past the two lines that set @code{len_lquote} and
684@code{len_rquote}, and then examine the values of those variables.
685
686@smallexample
687(@value{GDBP}) @b{n}
688539 len_rquote = strlen(lquote);
689(@value{GDBP}) @b{n}
690540 @}
691(@value{GDBP}) @b{p len_lquote}
692$3 = 9
693(@value{GDBP}) @b{p len_rquote}
694$4 = 7
695@end smallexample
696
697@noindent
698That certainly looks wrong, assuming @code{len_lquote} and
699@code{len_rquote} are meant to be the lengths of @code{lquote} and
700@code{rquote} respectively. We can set them to better values using
701the @code{p} command, since it can print the value of
702any expression---and that expression can include subroutine calls and
703assignments.
704
705@smallexample
706(@value{GDBP}) @b{p len_lquote=strlen(lquote)}
707$5 = 7
708(@value{GDBP}) @b{p len_rquote=strlen(rquote)}
709$6 = 9
710@end smallexample
711
712@noindent
713Is that enough to fix the problem of using the new quotes with the
714@code{m4} built-in @code{defn}? We can allow @code{m4} to continue
715executing with the @code{c} (@code{continue}) command, and then try the
716example that caused trouble initially:
717
718@smallexample
719(@value{GDBP}) @b{c}
720Continuing.
721
722@b{define(baz,defn(<QUOTE>foo<UNQUOTE>))}
723
724baz
7250000
726@end smallexample
727
728@noindent
729Success! The new quotes now work just as well as the default ones. The
730problem seems to have been just the two typos defining the wrong
731lengths. We allow @code{m4} exit by giving it an EOF as input:
732
733@smallexample
734@b{C-d}
735Program exited normally.
736@end smallexample
737
738@noindent
739The message @samp{Program exited normally.} is from @value{GDBN}; it
740indicates @code{m4} has finished executing. We can end our @value{GDBN}
741session with the @value{GDBN} @code{quit} command.
742
743@smallexample
744(@value{GDBP}) @b{quit}
745@end smallexample
c906108c 746
6d2ebf8b 747@node Invocation
c906108c
SS
748@chapter Getting In and Out of @value{GDBN}
749
750This chapter discusses how to start @value{GDBN}, and how to get out of it.
5d161b24 751The essentials are:
c906108c 752@itemize @bullet
5d161b24 753@item
53a5351d 754type @samp{@value{GDBP}} to start @value{GDBN}.
5d161b24 755@item
c906108c
SS
756type @kbd{quit} or @kbd{C-d} to exit.
757@end itemize
758
759@menu
760* Invoking GDB:: How to start @value{GDBN}
761* Quitting GDB:: How to quit @value{GDBN}
762* Shell Commands:: How to use shell commands inside @value{GDBN}
0fac0b41 763* Logging output:: How to log @value{GDBN}'s output to a file
c906108c
SS
764@end menu
765
6d2ebf8b 766@node Invoking GDB
c906108c
SS
767@section Invoking @value{GDBN}
768
c906108c
SS
769Invoke @value{GDBN} by running the program @code{@value{GDBP}}. Once started,
770@value{GDBN} reads commands from the terminal until you tell it to exit.
771
772You can also run @code{@value{GDBP}} with a variety of arguments and options,
773to specify more of your debugging environment at the outset.
774
c906108c
SS
775The command-line options described here are designed
776to cover a variety of situations; in some environments, some of these
5d161b24 777options may effectively be unavailable.
c906108c
SS
778
779The most usual way to start @value{GDBN} is with one argument,
780specifying an executable program:
781
474c8240 782@smallexample
c906108c 783@value{GDBP} @var{program}
474c8240 784@end smallexample
c906108c 785
c906108c
SS
786@noindent
787You can also start with both an executable program and a core file
788specified:
789
474c8240 790@smallexample
c906108c 791@value{GDBP} @var{program} @var{core}
474c8240 792@end smallexample
c906108c
SS
793
794You can, instead, specify a process ID as a second argument, if you want
795to debug a running process:
796
474c8240 797@smallexample
c906108c 798@value{GDBP} @var{program} 1234
474c8240 799@end smallexample
c906108c
SS
800
801@noindent
802would attach @value{GDBN} to process @code{1234} (unless you also have a file
803named @file{1234}; @value{GDBN} does check for a core file first).
804
c906108c 805Taking advantage of the second command-line argument requires a fairly
2df3850c
JM
806complete operating system; when you use @value{GDBN} as a remote
807debugger attached to a bare board, there may not be any notion of
808``process'', and there is often no way to get a core dump. @value{GDBN}
809will warn you if it is unable to attach or to read core dumps.
c906108c 810
aa26fa3a
TT
811You can optionally have @code{@value{GDBP}} pass any arguments after the
812executable file to the inferior using @code{--args}. This option stops
813option processing.
474c8240 814@smallexample
aa26fa3a 815gdb --args gcc -O2 -c foo.c
474c8240 816@end smallexample
aa26fa3a
TT
817This will cause @code{@value{GDBP}} to debug @code{gcc}, and to set
818@code{gcc}'s command-line arguments (@pxref{Arguments}) to @samp{-O2 -c foo.c}.
819
96a2c332 820You can run @code{@value{GDBP}} without printing the front material, which describes
c906108c
SS
821@value{GDBN}'s non-warranty, by specifying @code{-silent}:
822
823@smallexample
824@value{GDBP} -silent
825@end smallexample
826
827@noindent
828You can further control how @value{GDBN} starts up by using command-line
829options. @value{GDBN} itself can remind you of the options available.
830
831@noindent
832Type
833
474c8240 834@smallexample
c906108c 835@value{GDBP} -help
474c8240 836@end smallexample
c906108c
SS
837
838@noindent
839to display all available options and briefly describe their use
840(@samp{@value{GDBP} -h} is a shorter equivalent).
841
842All options and command line arguments you give are processed
843in sequential order. The order makes a difference when the
844@samp{-x} option is used.
845
846
847@menu
c906108c
SS
848* File Options:: Choosing files
849* Mode Options:: Choosing modes
850@end menu
851
6d2ebf8b 852@node File Options
c906108c
SS
853@subsection Choosing files
854
2df3850c 855When @value{GDBN} starts, it reads any arguments other than options as
c906108c
SS
856specifying an executable file and core file (or process ID). This is
857the same as if the arguments were specified by the @samp{-se} and
19837790
MS
858@samp{-c} (or @samp{-p} options respectively. (@value{GDBN} reads the
859first argument that does not have an associated option flag as
860equivalent to the @samp{-se} option followed by that argument; and the
861second argument that does not have an associated option flag, if any, as
862equivalent to the @samp{-c}/@samp{-p} option followed by that argument.)
863If the second argument begins with a decimal digit, @value{GDBN} will
864first attempt to attach to it as a process, and if that fails, attempt
865to open it as a corefile. If you have a corefile whose name begins with
b383017d 866a digit, you can prevent @value{GDBN} from treating it as a pid by
79f12247 867prefixing it with @file{./}, eg. @file{./12345}.
7a292a7a
SS
868
869If @value{GDBN} has not been configured to included core file support,
870such as for most embedded targets, then it will complain about a second
871argument and ignore it.
c906108c
SS
872
873Many options have both long and short forms; both are shown in the
874following list. @value{GDBN} also recognizes the long forms if you truncate
875them, so long as enough of the option is present to be unambiguous.
876(If you prefer, you can flag option arguments with @samp{--} rather
877than @samp{-}, though we illustrate the more usual convention.)
878
d700128c
EZ
879@c NOTE: the @cindex entries here use double dashes ON PURPOSE. This
880@c way, both those who look for -foo and --foo in the index, will find
881@c it.
882
c906108c
SS
883@table @code
884@item -symbols @var{file}
885@itemx -s @var{file}
d700128c
EZ
886@cindex @code{--symbols}
887@cindex @code{-s}
c906108c
SS
888Read symbol table from file @var{file}.
889
890@item -exec @var{file}
891@itemx -e @var{file}
d700128c
EZ
892@cindex @code{--exec}
893@cindex @code{-e}
7a292a7a
SS
894Use file @var{file} as the executable file to execute when appropriate,
895and for examining pure data in conjunction with a core dump.
c906108c
SS
896
897@item -se @var{file}
d700128c 898@cindex @code{--se}
c906108c
SS
899Read symbol table from file @var{file} and use it as the executable
900file.
901
c906108c
SS
902@item -core @var{file}
903@itemx -c @var{file}
d700128c
EZ
904@cindex @code{--core}
905@cindex @code{-c}
b383017d 906Use file @var{file} as a core dump to examine.
c906108c
SS
907
908@item -c @var{number}
19837790
MS
909@item -pid @var{number}
910@itemx -p @var{number}
911@cindex @code{--pid}
912@cindex @code{-p}
913Connect to process ID @var{number}, as with the @code{attach} command.
914If there is no such process, @value{GDBN} will attempt to open a core
915file named @var{number}.
c906108c
SS
916
917@item -command @var{file}
918@itemx -x @var{file}
d700128c
EZ
919@cindex @code{--command}
920@cindex @code{-x}
c906108c
SS
921Execute @value{GDBN} commands from file @var{file}. @xref{Command
922Files,, Command files}.
923
924@item -directory @var{directory}
925@itemx -d @var{directory}
d700128c
EZ
926@cindex @code{--directory}
927@cindex @code{-d}
c906108c
SS
928Add @var{directory} to the path to search for source files.
929
c906108c
SS
930@item -m
931@itemx -mapped
d700128c
EZ
932@cindex @code{--mapped}
933@cindex @code{-m}
c906108c
SS
934@emph{Warning: this option depends on operating system facilities that are not
935supported on all systems.}@*
936If memory-mapped files are available on your system through the @code{mmap}
5d161b24 937system call, you can use this option
c906108c
SS
938to have @value{GDBN} write the symbols from your
939program into a reusable file in the current directory. If the program you are debugging is
96a2c332 940called @file{/tmp/fred}, the mapped symbol file is @file{/tmp/fred.syms}.
c906108c
SS
941Future @value{GDBN} debugging sessions notice the presence of this file,
942and can quickly map in symbol information from it, rather than reading
943the symbol table from the executable program.
944
945The @file{.syms} file is specific to the host machine where @value{GDBN}
946is run. It holds an exact image of the internal @value{GDBN} symbol
947table. It cannot be shared across multiple host platforms.
c906108c 948
c906108c
SS
949@item -r
950@itemx -readnow
d700128c
EZ
951@cindex @code{--readnow}
952@cindex @code{-r}
c906108c
SS
953Read each symbol file's entire symbol table immediately, rather than
954the default, which is to read it incrementally as it is needed.
955This makes startup slower, but makes future operations faster.
53a5351d 956
c906108c
SS
957@end table
958
2df3850c 959You typically combine the @code{-mapped} and @code{-readnow} options in
c906108c 960order to build a @file{.syms} file that contains complete symbol
2df3850c
JM
961information. (@xref{Files,,Commands to specify files}, for information
962on @file{.syms} files.) A simple @value{GDBN} invocation to do nothing
963but build a @file{.syms} file for future use is:
c906108c 964
474c8240 965@smallexample
2df3850c 966gdb -batch -nx -mapped -readnow programname
474c8240 967@end smallexample
c906108c 968
6d2ebf8b 969@node Mode Options
c906108c
SS
970@subsection Choosing modes
971
972You can run @value{GDBN} in various alternative modes---for example, in
973batch mode or quiet mode.
974
975@table @code
976@item -nx
977@itemx -n
d700128c
EZ
978@cindex @code{--nx}
979@cindex @code{-n}
96565e91 980Do not execute commands found in any initialization files. Normally,
2df3850c
JM
981@value{GDBN} executes the commands in these files after all the command
982options and arguments have been processed. @xref{Command Files,,Command
983files}.
c906108c
SS
984
985@item -quiet
d700128c 986@itemx -silent
c906108c 987@itemx -q
d700128c
EZ
988@cindex @code{--quiet}
989@cindex @code{--silent}
990@cindex @code{-q}
c906108c
SS
991``Quiet''. Do not print the introductory and copyright messages. These
992messages are also suppressed in batch mode.
993
994@item -batch
d700128c 995@cindex @code{--batch}
c906108c
SS
996Run in batch mode. Exit with status @code{0} after processing all the
997command files specified with @samp{-x} (and all commands from
998initialization files, if not inhibited with @samp{-n}). Exit with
999nonzero status if an error occurs in executing the @value{GDBN} commands
1000in the command files.
1001
2df3850c
JM
1002Batch mode may be useful for running @value{GDBN} as a filter, for
1003example to download and run a program on another computer; in order to
1004make this more useful, the message
c906108c 1005
474c8240 1006@smallexample
c906108c 1007Program exited normally.
474c8240 1008@end smallexample
c906108c
SS
1009
1010@noindent
2df3850c
JM
1011(which is ordinarily issued whenever a program running under
1012@value{GDBN} control terminates) is not issued when running in batch
1013mode.
1014
1015@item -nowindows
1016@itemx -nw
d700128c
EZ
1017@cindex @code{--nowindows}
1018@cindex @code{-nw}
2df3850c 1019``No windows''. If @value{GDBN} comes with a graphical user interface
96a2c332 1020(GUI) built in, then this option tells @value{GDBN} to only use the command-line
2df3850c
JM
1021interface. If no GUI is available, this option has no effect.
1022
1023@item -windows
1024@itemx -w
d700128c
EZ
1025@cindex @code{--windows}
1026@cindex @code{-w}
2df3850c
JM
1027If @value{GDBN} includes a GUI, then this option requires it to be
1028used if possible.
c906108c
SS
1029
1030@item -cd @var{directory}
d700128c 1031@cindex @code{--cd}
c906108c
SS
1032Run @value{GDBN} using @var{directory} as its working directory,
1033instead of the current directory.
1034
c906108c
SS
1035@item -fullname
1036@itemx -f
d700128c
EZ
1037@cindex @code{--fullname}
1038@cindex @code{-f}
7a292a7a
SS
1039@sc{gnu} Emacs sets this option when it runs @value{GDBN} as a
1040subprocess. It tells @value{GDBN} to output the full file name and line
1041number in a standard, recognizable fashion each time a stack frame is
1042displayed (which includes each time your program stops). This
1043recognizable format looks like two @samp{\032} characters, followed by
1044the file name, line number and character position separated by colons,
1045and a newline. The Emacs-to-@value{GDBN} interface program uses the two
1046@samp{\032} characters as a signal to display the source code for the
1047frame.
c906108c 1048
d700128c
EZ
1049@item -epoch
1050@cindex @code{--epoch}
1051The Epoch Emacs-@value{GDBN} interface sets this option when it runs
1052@value{GDBN} as a subprocess. It tells @value{GDBN} to modify its print
1053routines so as to allow Epoch to display values of expressions in a
1054separate window.
1055
1056@item -annotate @var{level}
1057@cindex @code{--annotate}
1058This option sets the @dfn{annotation level} inside @value{GDBN}. Its
1059effect is identical to using @samp{set annotate @var{level}}
086432e2
AC
1060(@pxref{Annotations}). The annotation @var{level} controls how much
1061information @value{GDBN} prints together with its prompt, values of
1062expressions, source lines, and other types of output. Level 0 is the
1063normal, level 1 is for use when @value{GDBN} is run as a subprocess of
1064@sc{gnu} Emacs, level 3 is the maximum annotation suitable for programs
1065that control @value{GDBN}, and level 2 has been deprecated.
1066
1067The annotation mechanism has largely been superseeded by @sc{gdb/mi}
1068(@pxref{GDB/MI}).
d700128c 1069
aa26fa3a
TT
1070@item --args
1071@cindex @code{--args}
1072Change interpretation of command line so that arguments following the
1073executable file are passed as command line arguments to the inferior.
1074This option stops option processing.
1075
2df3850c
JM
1076@item -baud @var{bps}
1077@itemx -b @var{bps}
d700128c
EZ
1078@cindex @code{--baud}
1079@cindex @code{-b}
c906108c
SS
1080Set the line speed (baud rate or bits per second) of any serial
1081interface used by @value{GDBN} for remote debugging.
c906108c 1082
f47b1503
AS
1083@item -l @var{timeout}
1084@cindex @code{-l}
1085Set the timeout (in seconds) of any communication used by @value{GDBN}
1086for remote debugging.
1087
c906108c 1088@item -tty @var{device}
d700128c
EZ
1089@itemx -t @var{device}
1090@cindex @code{--tty}
1091@cindex @code{-t}
c906108c
SS
1092Run using @var{device} for your program's standard input and output.
1093@c FIXME: kingdon thinks there is more to -tty. Investigate.
c906108c 1094
53a5351d 1095@c resolve the situation of these eventually
c4555f82
SC
1096@item -tui
1097@cindex @code{--tui}
d0d5df6f
AC
1098Activate the @dfn{Text User Interface} when starting. The Text User
1099Interface manages several text windows on the terminal, showing
1100source, assembly, registers and @value{GDBN} command outputs
1101(@pxref{TUI, ,@value{GDBN} Text User Interface}). Alternatively, the
1102Text User Interface can be enabled by invoking the program
1103@samp{gdbtui}. Do not use this option if you run @value{GDBN} from
1104Emacs (@pxref{Emacs, ,Using @value{GDBN} under @sc{gnu} Emacs}).
53a5351d
JM
1105
1106@c @item -xdb
d700128c 1107@c @cindex @code{--xdb}
53a5351d
JM
1108@c Run in XDB compatibility mode, allowing the use of certain XDB commands.
1109@c For information, see the file @file{xdb_trans.html}, which is usually
1110@c installed in the directory @code{/opt/langtools/wdb/doc} on HP-UX
1111@c systems.
1112
d700128c
EZ
1113@item -interpreter @var{interp}
1114@cindex @code{--interpreter}
1115Use the interpreter @var{interp} for interface with the controlling
1116program or device. This option is meant to be set by programs which
94bbb2c0 1117communicate with @value{GDBN} using it as a back end.
21c294e6 1118@xref{Interpreters, , Command Interpreters}.
94bbb2c0 1119
da0f9dcd 1120@samp{--interpreter=mi} (or @samp{--interpreter=mi2}) causes
2fcf52f0 1121@value{GDBN} to use the @dfn{@sc{gdb/mi} interface} (@pxref{GDB/MI, ,
6c74ac8b
AC
1122The @sc{gdb/mi} Interface}) included since @var{GDBN} version 6.0. The
1123previous @sc{gdb/mi} interface, included in @value{GDBN} version 5.3 and
1124selected with @samp{--interpreter=mi1}, is deprecated. Earlier
1125@sc{gdb/mi} interfaces are no longer supported.
d700128c
EZ
1126
1127@item -write
1128@cindex @code{--write}
1129Open the executable and core files for both reading and writing. This
1130is equivalent to the @samp{set write on} command inside @value{GDBN}
1131(@pxref{Patching}).
1132
1133@item -statistics
1134@cindex @code{--statistics}
1135This option causes @value{GDBN} to print statistics about time and
1136memory usage after it completes each command and returns to the prompt.
1137
1138@item -version
1139@cindex @code{--version}
1140This option causes @value{GDBN} to print its version number and
1141no-warranty blurb, and exit.
1142
c906108c
SS
1143@end table
1144
6d2ebf8b 1145@node Quitting GDB
c906108c
SS
1146@section Quitting @value{GDBN}
1147@cindex exiting @value{GDBN}
1148@cindex leaving @value{GDBN}
1149
1150@table @code
1151@kindex quit @r{[}@var{expression}@r{]}
41afff9a 1152@kindex q @r{(@code{quit})}
96a2c332
SS
1153@item quit @r{[}@var{expression}@r{]}
1154@itemx q
1155To exit @value{GDBN}, use the @code{quit} command (abbreviated
1156@code{q}), or type an end-of-file character (usually @kbd{C-d}). If you
1157do not supply @var{expression}, @value{GDBN} will terminate normally;
1158otherwise it will terminate using the result of @var{expression} as the
1159error code.
c906108c
SS
1160@end table
1161
1162@cindex interrupt
1163An interrupt (often @kbd{C-c}) does not exit from @value{GDBN}, but rather
1164terminates the action of any @value{GDBN} command that is in progress and
1165returns to @value{GDBN} command level. It is safe to type the interrupt
1166character at any time because @value{GDBN} does not allow it to take effect
1167until a time when it is safe.
1168
c906108c
SS
1169If you have been using @value{GDBN} to control an attached process or
1170device, you can release it with the @code{detach} command
1171(@pxref{Attach, ,Debugging an already-running process}).
c906108c 1172
6d2ebf8b 1173@node Shell Commands
c906108c
SS
1174@section Shell commands
1175
1176If you need to execute occasional shell commands during your
1177debugging session, there is no need to leave or suspend @value{GDBN}; you can
1178just use the @code{shell} command.
1179
1180@table @code
1181@kindex shell
1182@cindex shell escape
1183@item shell @var{command string}
1184Invoke a standard shell to execute @var{command string}.
c906108c 1185If it exists, the environment variable @code{SHELL} determines which
d4f3574e
SS
1186shell to run. Otherwise @value{GDBN} uses the default shell
1187(@file{/bin/sh} on Unix systems, @file{COMMAND.COM} on MS-DOS, etc.).
c906108c
SS
1188@end table
1189
1190The utility @code{make} is often needed in development environments.
1191You do not have to use the @code{shell} command for this purpose in
1192@value{GDBN}:
1193
1194@table @code
1195@kindex make
1196@cindex calling make
1197@item make @var{make-args}
1198Execute the @code{make} program with the specified
1199arguments. This is equivalent to @samp{shell make @var{make-args}}.
1200@end table
1201
0fac0b41
DJ
1202@node Logging output
1203@section Logging output
1204@cindex logging @value{GDBN} output
9c16f35a 1205@cindex save @value{GDBN} output to a file
0fac0b41
DJ
1206
1207You may want to save the output of @value{GDBN} commands to a file.
1208There are several commands to control @value{GDBN}'s logging.
1209
1210@table @code
1211@kindex set logging
1212@item set logging on
1213Enable logging.
1214@item set logging off
1215Disable logging.
9c16f35a 1216@cindex logging file name
0fac0b41
DJ
1217@item set logging file @var{file}
1218Change the name of the current logfile. The default logfile is @file{gdb.txt}.
1219@item set logging overwrite [on|off]
1220By default, @value{GDBN} will append to the logfile. Set @code{overwrite} if
1221you want @code{set logging on} to overwrite the logfile instead.
1222@item set logging redirect [on|off]
1223By default, @value{GDBN} output will go to both the terminal and the logfile.
1224Set @code{redirect} if you want output to go only to the log file.
1225@kindex show logging
1226@item show logging
1227Show the current values of the logging settings.
1228@end table
1229
6d2ebf8b 1230@node Commands
c906108c
SS
1231@chapter @value{GDBN} Commands
1232
1233You can abbreviate a @value{GDBN} command to the first few letters of the command
1234name, if that abbreviation is unambiguous; and you can repeat certain
1235@value{GDBN} commands by typing just @key{RET}. You can also use the @key{TAB}
1236key to get @value{GDBN} to fill out the rest of a word in a command (or to
1237show you the alternatives available, if there is more than one possibility).
1238
1239@menu
1240* Command Syntax:: How to give commands to @value{GDBN}
1241* Completion:: Command completion
1242* Help:: How to ask @value{GDBN} for help
1243@end menu
1244
6d2ebf8b 1245@node Command Syntax
c906108c
SS
1246@section Command syntax
1247
1248A @value{GDBN} command is a single line of input. There is no limit on
1249how long it can be. It starts with a command name, which is followed by
1250arguments whose meaning depends on the command name. For example, the
1251command @code{step} accepts an argument which is the number of times to
1252step, as in @samp{step 5}. You can also use the @code{step} command
96a2c332 1253with no arguments. Some commands do not allow any arguments.
c906108c
SS
1254
1255@cindex abbreviation
1256@value{GDBN} command names may always be truncated if that abbreviation is
1257unambiguous. Other possible command abbreviations are listed in the
1258documentation for individual commands. In some cases, even ambiguous
1259abbreviations are allowed; for example, @code{s} is specially defined as
1260equivalent to @code{step} even though there are other commands whose
1261names start with @code{s}. You can test abbreviations by using them as
1262arguments to the @code{help} command.
1263
1264@cindex repeating commands
41afff9a 1265@kindex RET @r{(repeat last command)}
c906108c 1266A blank line as input to @value{GDBN} (typing just @key{RET}) means to
96a2c332 1267repeat the previous command. Certain commands (for example, @code{run})
c906108c
SS
1268will not repeat this way; these are commands whose unintentional
1269repetition might cause trouble and which you are unlikely to want to
1270repeat.
1271
1272The @code{list} and @code{x} commands, when you repeat them with
1273@key{RET}, construct new arguments rather than repeating
1274exactly as typed. This permits easy scanning of source or memory.
1275
1276@value{GDBN} can also use @key{RET} in another way: to partition lengthy
1277output, in a way similar to the common utility @code{more}
1278(@pxref{Screen Size,,Screen size}). Since it is easy to press one
1279@key{RET} too many in this situation, @value{GDBN} disables command
1280repetition after any command that generates this sort of display.
1281
41afff9a 1282@kindex # @r{(a comment)}
c906108c
SS
1283@cindex comment
1284Any text from a @kbd{#} to the end of the line is a comment; it does
1285nothing. This is useful mainly in command files (@pxref{Command
1286Files,,Command files}).
1287
88118b3a
TT
1288@cindex repeating command sequences
1289@kindex C-o @r{(operate-and-get-next)}
1290The @kbd{C-o} binding is useful for repeating a complex sequence of
1291commands. This command accepts the current line, like @kbd{RET}, and
1292then fetches the next line relative to the current line from the history
1293for editing.
1294
6d2ebf8b 1295@node Completion
c906108c
SS
1296@section Command completion
1297
1298@cindex completion
1299@cindex word completion
1300@value{GDBN} can fill in the rest of a word in a command for you, if there is
1301only one possibility; it can also show you what the valid possibilities
1302are for the next word in a command, at any time. This works for @value{GDBN}
1303commands, @value{GDBN} subcommands, and the names of symbols in your program.
1304
1305Press the @key{TAB} key whenever you want @value{GDBN} to fill out the rest
1306of a word. If there is only one possibility, @value{GDBN} fills in the
1307word, and waits for you to finish the command (or press @key{RET} to
1308enter it). For example, if you type
1309
1310@c FIXME "@key" does not distinguish its argument sufficiently to permit
1311@c complete accuracy in these examples; space introduced for clarity.
1312@c If texinfo enhancements make it unnecessary, it would be nice to
1313@c replace " @key" by "@key" in the following...
474c8240 1314@smallexample
c906108c 1315(@value{GDBP}) info bre @key{TAB}
474c8240 1316@end smallexample
c906108c
SS
1317
1318@noindent
1319@value{GDBN} fills in the rest of the word @samp{breakpoints}, since that is
1320the only @code{info} subcommand beginning with @samp{bre}:
1321
474c8240 1322@smallexample
c906108c 1323(@value{GDBP}) info breakpoints
474c8240 1324@end smallexample
c906108c
SS
1325
1326@noindent
1327You can either press @key{RET} at this point, to run the @code{info
1328breakpoints} command, or backspace and enter something else, if
1329@samp{breakpoints} does not look like the command you expected. (If you
1330were sure you wanted @code{info breakpoints} in the first place, you
1331might as well just type @key{RET} immediately after @samp{info bre},
1332to exploit command abbreviations rather than command completion).
1333
1334If there is more than one possibility for the next word when you press
1335@key{TAB}, @value{GDBN} sounds a bell. You can either supply more
1336characters and try again, or just press @key{TAB} a second time;
1337@value{GDBN} displays all the possible completions for that word. For
1338example, you might want to set a breakpoint on a subroutine whose name
1339begins with @samp{make_}, but when you type @kbd{b make_@key{TAB}} @value{GDBN}
1340just sounds the bell. Typing @key{TAB} again displays all the
1341function names in your program that begin with those characters, for
1342example:
1343
474c8240 1344@smallexample
c906108c
SS
1345(@value{GDBP}) b make_ @key{TAB}
1346@exdent @value{GDBN} sounds bell; press @key{TAB} again, to see:
5d161b24
DB
1347make_a_section_from_file make_environ
1348make_abs_section make_function_type
1349make_blockvector make_pointer_type
1350make_cleanup make_reference_type
c906108c
SS
1351make_command make_symbol_completion_list
1352(@value{GDBP}) b make_
474c8240 1353@end smallexample
c906108c
SS
1354
1355@noindent
1356After displaying the available possibilities, @value{GDBN} copies your
1357partial input (@samp{b make_} in the example) so you can finish the
1358command.
1359
1360If you just want to see the list of alternatives in the first place, you
b37052ae 1361can press @kbd{M-?} rather than pressing @key{TAB} twice. @kbd{M-?}
7a292a7a 1362means @kbd{@key{META} ?}. You can type this either by holding down a
c906108c 1363key designated as the @key{META} shift on your keyboard (if there is
7a292a7a 1364one) while typing @kbd{?}, or as @key{ESC} followed by @kbd{?}.
c906108c
SS
1365
1366@cindex quotes in commands
1367@cindex completion of quoted strings
1368Sometimes the string you need, while logically a ``word'', may contain
7a292a7a
SS
1369parentheses or other characters that @value{GDBN} normally excludes from
1370its notion of a word. To permit word completion to work in this
1371situation, you may enclose words in @code{'} (single quote marks) in
1372@value{GDBN} commands.
c906108c 1373
c906108c 1374The most likely situation where you might need this is in typing the
b37052ae
EZ
1375name of a C@t{++} function. This is because C@t{++} allows function
1376overloading (multiple definitions of the same function, distinguished
1377by argument type). For example, when you want to set a breakpoint you
1378may need to distinguish whether you mean the version of @code{name}
1379that takes an @code{int} parameter, @code{name(int)}, or the version
1380that takes a @code{float} parameter, @code{name(float)}. To use the
1381word-completion facilities in this situation, type a single quote
1382@code{'} at the beginning of the function name. This alerts
1383@value{GDBN} that it may need to consider more information than usual
1384when you press @key{TAB} or @kbd{M-?} to request word completion:
c906108c 1385
474c8240 1386@smallexample
96a2c332 1387(@value{GDBP}) b 'bubble( @kbd{M-?}
c906108c
SS
1388bubble(double,double) bubble(int,int)
1389(@value{GDBP}) b 'bubble(
474c8240 1390@end smallexample
c906108c
SS
1391
1392In some cases, @value{GDBN} can tell that completing a name requires using
1393quotes. When this happens, @value{GDBN} inserts the quote for you (while
1394completing as much as it can) if you do not type the quote in the first
1395place:
1396
474c8240 1397@smallexample
c906108c
SS
1398(@value{GDBP}) b bub @key{TAB}
1399@exdent @value{GDBN} alters your input line to the following, and rings a bell:
1400(@value{GDBP}) b 'bubble(
474c8240 1401@end smallexample
c906108c
SS
1402
1403@noindent
1404In general, @value{GDBN} can tell that a quote is needed (and inserts it) if
1405you have not yet started typing the argument list when you ask for
1406completion on an overloaded symbol.
1407
d4f3574e 1408For more information about overloaded functions, see @ref{C plus plus
b37052ae 1409expressions, ,C@t{++} expressions}. You can use the command @code{set
c906108c 1410overload-resolution off} to disable overload resolution;
b37052ae 1411see @ref{Debugging C plus plus, ,@value{GDBN} features for C@t{++}}.
c906108c
SS
1412
1413
6d2ebf8b 1414@node Help
c906108c
SS
1415@section Getting help
1416@cindex online documentation
1417@kindex help
1418
5d161b24 1419You can always ask @value{GDBN} itself for information on its commands,
c906108c
SS
1420using the command @code{help}.
1421
1422@table @code
41afff9a 1423@kindex h @r{(@code{help})}
c906108c
SS
1424@item help
1425@itemx h
1426You can use @code{help} (abbreviated @code{h}) with no arguments to
1427display a short list of named classes of commands:
1428
1429@smallexample
1430(@value{GDBP}) help
1431List of classes of commands:
1432
2df3850c 1433aliases -- Aliases of other commands
c906108c 1434breakpoints -- Making program stop at certain points
2df3850c 1435data -- Examining data
c906108c 1436files -- Specifying and examining files
2df3850c
JM
1437internals -- Maintenance commands
1438obscure -- Obscure features
1439running -- Running the program
1440stack -- Examining the stack
c906108c
SS
1441status -- Status inquiries
1442support -- Support facilities
96a2c332
SS
1443tracepoints -- Tracing of program execution without@*
1444 stopping the program
c906108c 1445user-defined -- User-defined commands
c906108c 1446
5d161b24 1447Type "help" followed by a class name for a list of
c906108c 1448commands in that class.
5d161b24 1449Type "help" followed by command name for full
c906108c
SS
1450documentation.
1451Command name abbreviations are allowed if unambiguous.
1452(@value{GDBP})
1453@end smallexample
96a2c332 1454@c the above line break eliminates huge line overfull...
c906108c
SS
1455
1456@item help @var{class}
1457Using one of the general help classes as an argument, you can get a
1458list of the individual commands in that class. For example, here is the
1459help display for the class @code{status}:
1460
1461@smallexample
1462(@value{GDBP}) help status
1463Status inquiries.
1464
1465List of commands:
1466
1467@c Line break in "show" line falsifies real output, but needed
1468@c to fit in smallbook page size.
2df3850c
JM
1469info -- Generic command for showing things
1470 about the program being debugged
1471show -- Generic command for showing things
1472 about the debugger
c906108c 1473
5d161b24 1474Type "help" followed by command name for full
c906108c
SS
1475documentation.
1476Command name abbreviations are allowed if unambiguous.
1477(@value{GDBP})
1478@end smallexample
1479
1480@item help @var{command}
1481With a command name as @code{help} argument, @value{GDBN} displays a
1482short paragraph on how to use that command.
1483
6837a0a2
DB
1484@kindex apropos
1485@item apropos @var{args}
09d4efe1 1486The @code{apropos} command searches through all of the @value{GDBN}
6837a0a2
DB
1487commands, and their documentation, for the regular expression specified in
1488@var{args}. It prints out all matches found. For example:
1489
1490@smallexample
1491apropos reload
1492@end smallexample
1493
b37052ae
EZ
1494@noindent
1495results in:
6837a0a2
DB
1496
1497@smallexample
6d2ebf8b
SS
1498@c @group
1499set symbol-reloading -- Set dynamic symbol table reloading
1500 multiple times in one run
1501show symbol-reloading -- Show dynamic symbol table reloading
1502 multiple times in one run
1503@c @end group
6837a0a2
DB
1504@end smallexample
1505
c906108c
SS
1506@kindex complete
1507@item complete @var{args}
1508The @code{complete @var{args}} command lists all the possible completions
1509for the beginning of a command. Use @var{args} to specify the beginning of the
1510command you want completed. For example:
1511
1512@smallexample
1513complete i
1514@end smallexample
1515
1516@noindent results in:
1517
1518@smallexample
1519@group
2df3850c
JM
1520if
1521ignore
c906108c
SS
1522info
1523inspect
c906108c
SS
1524@end group
1525@end smallexample
1526
1527@noindent This is intended for use by @sc{gnu} Emacs.
1528@end table
1529
1530In addition to @code{help}, you can use the @value{GDBN} commands @code{info}
1531and @code{show} to inquire about the state of your program, or the state
1532of @value{GDBN} itself. Each command supports many topics of inquiry; this
1533manual introduces each of them in the appropriate context. The listings
1534under @code{info} and under @code{show} in the Index point to
1535all the sub-commands. @xref{Index}.
1536
1537@c @group
1538@table @code
1539@kindex info
41afff9a 1540@kindex i @r{(@code{info})}
c906108c
SS
1541@item info
1542This command (abbreviated @code{i}) is for describing the state of your
1543program. For example, you can list the arguments given to your program
1544with @code{info args}, list the registers currently in use with @code{info
1545registers}, or list the breakpoints you have set with @code{info breakpoints}.
1546You can get a complete list of the @code{info} sub-commands with
1547@w{@code{help info}}.
1548
1549@kindex set
1550@item set
5d161b24 1551You can assign the result of an expression to an environment variable with
c906108c
SS
1552@code{set}. For example, you can set the @value{GDBN} prompt to a $-sign with
1553@code{set prompt $}.
1554
1555@kindex show
1556@item show
5d161b24 1557In contrast to @code{info}, @code{show} is for describing the state of
c906108c
SS
1558@value{GDBN} itself.
1559You can change most of the things you can @code{show}, by using the
1560related command @code{set}; for example, you can control what number
1561system is used for displays with @code{set radix}, or simply inquire
1562which is currently in use with @code{show radix}.
1563
1564@kindex info set
1565To display all the settable parameters and their current
1566values, you can use @code{show} with no arguments; you may also use
1567@code{info set}. Both commands produce the same display.
1568@c FIXME: "info set" violates the rule that "info" is for state of
1569@c FIXME...program. Ck w/ GNU: "info set" to be called something else,
1570@c FIXME...or change desc of rule---eg "state of prog and debugging session"?
1571@end table
1572@c @end group
1573
1574Here are three miscellaneous @code{show} subcommands, all of which are
1575exceptional in lacking corresponding @code{set} commands:
1576
1577@table @code
1578@kindex show version
9c16f35a 1579@cindex @value{GDBN} version number
c906108c
SS
1580@item show version
1581Show what version of @value{GDBN} is running. You should include this
2df3850c
JM
1582information in @value{GDBN} bug-reports. If multiple versions of
1583@value{GDBN} are in use at your site, you may need to determine which
1584version of @value{GDBN} you are running; as @value{GDBN} evolves, new
1585commands are introduced, and old ones may wither away. Also, many
1586system vendors ship variant versions of @value{GDBN}, and there are
96a2c332 1587variant versions of @value{GDBN} in @sc{gnu}/Linux distributions as well.
2df3850c
JM
1588The version number is the same as the one announced when you start
1589@value{GDBN}.
c906108c
SS
1590
1591@kindex show copying
09d4efe1 1592@kindex info copying
9c16f35a 1593@cindex display @value{GDBN} copyright
c906108c 1594@item show copying
09d4efe1 1595@itemx info copying
c906108c
SS
1596Display information about permission for copying @value{GDBN}.
1597
1598@kindex show warranty
09d4efe1 1599@kindex info warranty
c906108c 1600@item show warranty
09d4efe1 1601@itemx info warranty
2df3850c 1602Display the @sc{gnu} ``NO WARRANTY'' statement, or a warranty,
96a2c332 1603if your version of @value{GDBN} comes with one.
2df3850c 1604
c906108c
SS
1605@end table
1606
6d2ebf8b 1607@node Running
c906108c
SS
1608@chapter Running Programs Under @value{GDBN}
1609
1610When you run a program under @value{GDBN}, you must first generate
1611debugging information when you compile it.
7a292a7a
SS
1612
1613You may start @value{GDBN} with its arguments, if any, in an environment
1614of your choice. If you are doing native debugging, you may redirect
1615your program's input and output, debug an already running process, or
1616kill a child process.
c906108c
SS
1617
1618@menu
1619* Compilation:: Compiling for debugging
1620* Starting:: Starting your program
c906108c
SS
1621* Arguments:: Your program's arguments
1622* Environment:: Your program's environment
c906108c
SS
1623
1624* Working Directory:: Your program's working directory
1625* Input/Output:: Your program's input and output
1626* Attach:: Debugging an already-running process
1627* Kill Process:: Killing the child process
c906108c
SS
1628
1629* Threads:: Debugging programs with multiple threads
1630* Processes:: Debugging programs with multiple processes
1631@end menu
1632
6d2ebf8b 1633@node Compilation
c906108c
SS
1634@section Compiling for debugging
1635
1636In order to debug a program effectively, you need to generate
1637debugging information when you compile it. This debugging information
1638is stored in the object file; it describes the data type of each
1639variable or function and the correspondence between source line numbers
1640and addresses in the executable code.
1641
1642To request debugging information, specify the @samp{-g} option when you run
1643the compiler.
1644
e2e0bcd1
JB
1645Most compilers do not include information about preprocessor macros in
1646the debugging information if you specify the @option{-g} flag alone,
1647because this information is rather large. Version 3.1 of @value{NGCC},
1648the @sc{gnu} C compiler, provides macro information if you specify the
1649options @option{-gdwarf-2} and @option{-g3}; the former option requests
1650debugging information in the Dwarf 2 format, and the latter requests
1651``extra information''. In the future, we hope to find more compact ways
1652to represent macro information, so that it can be included with
1653@option{-g} alone.
1654
c906108c
SS
1655Many C compilers are unable to handle the @samp{-g} and @samp{-O}
1656options together. Using those compilers, you cannot generate optimized
1657executables containing debugging information.
1658
53a5351d
JM
1659@value{NGCC}, the @sc{gnu} C compiler, supports @samp{-g} with or
1660without @samp{-O}, making it possible to debug optimized code. We
1661recommend that you @emph{always} use @samp{-g} whenever you compile a
1662program. You may think your program is correct, but there is no sense
1663in pushing your luck.
c906108c
SS
1664
1665@cindex optimized code, debugging
1666@cindex debugging optimized code
1667When you debug a program compiled with @samp{-g -O}, remember that the
1668optimizer is rearranging your code; the debugger shows you what is
1669really there. Do not be too surprised when the execution path does not
1670exactly match your source file! An extreme example: if you define a
1671variable, but never use it, @value{GDBN} never sees that
1672variable---because the compiler optimizes it out of existence.
1673
1674Some things do not work as well with @samp{-g -O} as with just
1675@samp{-g}, particularly on machines with instruction scheduling. If in
1676doubt, recompile with @samp{-g} alone, and if this fixes the problem,
1677please report it to us as a bug (including a test case!).
15387254 1678@xref{Variables}, for more information about debugging optimized code.
c906108c
SS
1679
1680Older versions of the @sc{gnu} C compiler permitted a variant option
1681@w{@samp{-gg}} for debugging information. @value{GDBN} no longer supports this
1682format; if your @sc{gnu} C compiler has this option, do not use it.
1683
1684@need 2000
6d2ebf8b 1685@node Starting
c906108c
SS
1686@section Starting your program
1687@cindex starting
1688@cindex running
1689
1690@table @code
1691@kindex run
41afff9a 1692@kindex r @r{(@code{run})}
c906108c
SS
1693@item run
1694@itemx r
7a292a7a
SS
1695Use the @code{run} command to start your program under @value{GDBN}.
1696You must first specify the program name (except on VxWorks) with an
1697argument to @value{GDBN} (@pxref{Invocation, ,Getting In and Out of
1698@value{GDBN}}), or by using the @code{file} or @code{exec-file} command
1699(@pxref{Files, ,Commands to specify files}).
c906108c
SS
1700
1701@end table
1702
c906108c
SS
1703If you are running your program in an execution environment that
1704supports processes, @code{run} creates an inferior process and makes
1705that process run your program. (In environments without processes,
1706@code{run} jumps to the start of your program.)
1707
1708The execution of a program is affected by certain information it
1709receives from its superior. @value{GDBN} provides ways to specify this
1710information, which you must do @emph{before} starting your program. (You
1711can change it after starting your program, but such changes only affect
1712your program the next time you start it.) This information may be
1713divided into four categories:
1714
1715@table @asis
1716@item The @emph{arguments.}
1717Specify the arguments to give your program as the arguments of the
1718@code{run} command. If a shell is available on your target, the shell
1719is used to pass the arguments, so that you may use normal conventions
1720(such as wildcard expansion or variable substitution) in describing
1721the arguments.
1722In Unix systems, you can control which shell is used with the
1723@code{SHELL} environment variable.
1724@xref{Arguments, ,Your program's arguments}.
1725
1726@item The @emph{environment.}
1727Your program normally inherits its environment from @value{GDBN}, but you can
1728use the @value{GDBN} commands @code{set environment} and @code{unset
1729environment} to change parts of the environment that affect
1730your program. @xref{Environment, ,Your program's environment}.
1731
1732@item The @emph{working directory.}
1733Your program inherits its working directory from @value{GDBN}. You can set
1734the @value{GDBN} working directory with the @code{cd} command in @value{GDBN}.
1735@xref{Working Directory, ,Your program's working directory}.
1736
1737@item The @emph{standard input and output.}
1738Your program normally uses the same device for standard input and
1739standard output as @value{GDBN} is using. You can redirect input and output
1740in the @code{run} command line, or you can use the @code{tty} command to
1741set a different device for your program.
1742@xref{Input/Output, ,Your program's input and output}.
1743
1744@cindex pipes
1745@emph{Warning:} While input and output redirection work, you cannot use
1746pipes to pass the output of the program you are debugging to another
1747program; if you attempt this, @value{GDBN} is likely to wind up debugging the
1748wrong program.
1749@end table
c906108c
SS
1750
1751When you issue the @code{run} command, your program begins to execute
1752immediately. @xref{Stopping, ,Stopping and continuing}, for discussion
1753of how to arrange for your program to stop. Once your program has
1754stopped, you may call functions in your program, using the @code{print}
1755or @code{call} commands. @xref{Data, ,Examining Data}.
1756
1757If the modification time of your symbol file has changed since the last
1758time @value{GDBN} read its symbols, @value{GDBN} discards its symbol
1759table, and reads it again. When it does this, @value{GDBN} tries to retain
1760your current breakpoints.
1761
4e8b0763
JB
1762@table @code
1763@kindex start
1764@item start
1765@cindex run to main procedure
1766The name of the main procedure can vary from language to language.
1767With C or C@t{++}, the main procedure name is always @code{main}, but
1768other languages such as Ada do not require a specific name for their
1769main procedure. The debugger provides a convenient way to start the
1770execution of the program and to stop at the beginning of the main
1771procedure, depending on the language used.
1772
1773The @samp{start} command does the equivalent of setting a temporary
1774breakpoint at the beginning of the main procedure and then invoking
1775the @samp{run} command.
1776
f018e82f
EZ
1777@cindex elaboration phase
1778Some programs contain an @dfn{elaboration} phase where some startup code is
1779executed before the main procedure is called. This depends on the
1780languages used to write your program. In C@t{++}, for instance,
4e8b0763
JB
1781constructors for static and global objects are executed before
1782@code{main} is called. It is therefore possible that the debugger stops
1783before reaching the main procedure. However, the temporary breakpoint
1784will remain to halt execution.
1785
1786Specify the arguments to give to your program as arguments to the
1787@samp{start} command. These arguments will be given verbatim to the
1788underlying @samp{run} command. Note that the same arguments will be
1789reused if no argument is provided during subsequent calls to
1790@samp{start} or @samp{run}.
1791
1792It is sometimes necessary to debug the program during elaboration. In
1793these cases, using the @code{start} command would stop the execution of
1794your program too late, as the program would have already completed the
1795elaboration phase. Under these circumstances, insert breakpoints in your
1796elaboration code before running your program.
1797@end table
1798
6d2ebf8b 1799@node Arguments
c906108c
SS
1800@section Your program's arguments
1801
1802@cindex arguments (to your program)
1803The arguments to your program can be specified by the arguments of the
5d161b24 1804@code{run} command.
c906108c
SS
1805They are passed to a shell, which expands wildcard characters and
1806performs redirection of I/O, and thence to your program. Your
1807@code{SHELL} environment variable (if it exists) specifies what shell
1808@value{GDBN} uses. If you do not define @code{SHELL}, @value{GDBN} uses
d4f3574e
SS
1809the default shell (@file{/bin/sh} on Unix).
1810
1811On non-Unix systems, the program is usually invoked directly by
1812@value{GDBN}, which emulates I/O redirection via the appropriate system
1813calls, and the wildcard characters are expanded by the startup code of
1814the program, not by the shell.
c906108c
SS
1815
1816@code{run} with no arguments uses the same arguments used by the previous
1817@code{run}, or those set by the @code{set args} command.
1818
c906108c 1819@table @code
41afff9a 1820@kindex set args
c906108c
SS
1821@item set args
1822Specify the arguments to be used the next time your program is run. If
1823@code{set args} has no arguments, @code{run} executes your program
1824with no arguments. Once you have run your program with arguments,
1825using @code{set args} before the next @code{run} is the only way to run
1826it again without arguments.
1827
1828@kindex show args
1829@item show args
1830Show the arguments to give your program when it is started.
1831@end table
1832
6d2ebf8b 1833@node Environment
c906108c
SS
1834@section Your program's environment
1835
1836@cindex environment (of your program)
1837The @dfn{environment} consists of a set of environment variables and
1838their values. Environment variables conventionally record such things as
1839your user name, your home directory, your terminal type, and your search
1840path for programs to run. Usually you set up environment variables with
1841the shell and they are inherited by all the other programs you run. When
1842debugging, it can be useful to try running your program with a modified
1843environment without having to start @value{GDBN} over again.
1844
1845@table @code
1846@kindex path
1847@item path @var{directory}
1848Add @var{directory} to the front of the @code{PATH} environment variable
17cc6a06
EZ
1849(the search path for executables) that will be passed to your program.
1850The value of @code{PATH} used by @value{GDBN} does not change.
d4f3574e
SS
1851You may specify several directory names, separated by whitespace or by a
1852system-dependent separator character (@samp{:} on Unix, @samp{;} on
1853MS-DOS and MS-Windows). If @var{directory} is already in the path, it
1854is moved to the front, so it is searched sooner.
c906108c
SS
1855
1856You can use the string @samp{$cwd} to refer to whatever is the current
1857working directory at the time @value{GDBN} searches the path. If you
1858use @samp{.} instead, it refers to the directory where you executed the
1859@code{path} command. @value{GDBN} replaces @samp{.} in the
1860@var{directory} argument (with the current path) before adding
1861@var{directory} to the search path.
1862@c 'path' is explicitly nonrepeatable, but RMS points out it is silly to
1863@c document that, since repeating it would be a no-op.
1864
1865@kindex show paths
1866@item show paths
1867Display the list of search paths for executables (the @code{PATH}
1868environment variable).
1869
1870@kindex show environment
1871@item show environment @r{[}@var{varname}@r{]}
1872Print the value of environment variable @var{varname} to be given to
1873your program when it starts. If you do not supply @var{varname},
1874print the names and values of all environment variables to be given to
1875your program. You can abbreviate @code{environment} as @code{env}.
1876
1877@kindex set environment
53a5351d 1878@item set environment @var{varname} @r{[}=@var{value}@r{]}
c906108c
SS
1879Set environment variable @var{varname} to @var{value}. The value
1880changes for your program only, not for @value{GDBN} itself. @var{value} may
1881be any string; the values of environment variables are just strings, and
1882any interpretation is supplied by your program itself. The @var{value}
1883parameter is optional; if it is eliminated, the variable is set to a
1884null value.
1885@c "any string" here does not include leading, trailing
1886@c blanks. Gnu asks: does anyone care?
1887
1888For example, this command:
1889
474c8240 1890@smallexample
c906108c 1891set env USER = foo
474c8240 1892@end smallexample
c906108c
SS
1893
1894@noindent
d4f3574e 1895tells the debugged program, when subsequently run, that its user is named
c906108c
SS
1896@samp{foo}. (The spaces around @samp{=} are used for clarity here; they
1897are not actually required.)
1898
1899@kindex unset environment
1900@item unset environment @var{varname}
1901Remove variable @var{varname} from the environment to be passed to your
1902program. This is different from @samp{set env @var{varname} =};
1903@code{unset environment} removes the variable from the environment,
1904rather than assigning it an empty value.
1905@end table
1906
d4f3574e
SS
1907@emph{Warning:} On Unix systems, @value{GDBN} runs your program using
1908the shell indicated
c906108c
SS
1909by your @code{SHELL} environment variable if it exists (or
1910@code{/bin/sh} if not). If your @code{SHELL} variable names a shell
1911that runs an initialization file---such as @file{.cshrc} for C-shell, or
1912@file{.bashrc} for BASH---any variables you set in that file affect
1913your program. You may wish to move setting of environment variables to
1914files that are only run when you sign on, such as @file{.login} or
1915@file{.profile}.
1916
6d2ebf8b 1917@node Working Directory
c906108c
SS
1918@section Your program's working directory
1919
1920@cindex working directory (of your program)
1921Each time you start your program with @code{run}, it inherits its
1922working directory from the current working directory of @value{GDBN}.
1923The @value{GDBN} working directory is initially whatever it inherited
1924from its parent process (typically the shell), but you can specify a new
1925working directory in @value{GDBN} with the @code{cd} command.
1926
1927The @value{GDBN} working directory also serves as a default for the commands
1928that specify files for @value{GDBN} to operate on. @xref{Files, ,Commands to
1929specify files}.
1930
1931@table @code
1932@kindex cd
1933@item cd @var{directory}
1934Set the @value{GDBN} working directory to @var{directory}.
1935
1936@kindex pwd
1937@item pwd
1938Print the @value{GDBN} working directory.
1939@end table
1940
60bf7e09
EZ
1941It is generally impossible to find the current working directory of
1942the process being debugged (since a program can change its directory
1943during its run). If you work on a system where @value{GDBN} is
1944configured with the @file{/proc} support, you can use the @code{info
1945proc} command (@pxref{SVR4 Process Information}) to find out the
1946current working directory of the debuggee.
1947
6d2ebf8b 1948@node Input/Output
c906108c
SS
1949@section Your program's input and output
1950
1951@cindex redirection
1952@cindex i/o
1953@cindex terminal
1954By default, the program you run under @value{GDBN} does input and output to
5d161b24 1955the same terminal that @value{GDBN} uses. @value{GDBN} switches the terminal
c906108c
SS
1956to its own terminal modes to interact with you, but it records the terminal
1957modes your program was using and switches back to them when you continue
1958running your program.
1959
1960@table @code
1961@kindex info terminal
1962@item info terminal
1963Displays information recorded by @value{GDBN} about the terminal modes your
1964program is using.
1965@end table
1966
1967You can redirect your program's input and/or output using shell
1968redirection with the @code{run} command. For example,
1969
474c8240 1970@smallexample
c906108c 1971run > outfile
474c8240 1972@end smallexample
c906108c
SS
1973
1974@noindent
1975starts your program, diverting its output to the file @file{outfile}.
1976
1977@kindex tty
1978@cindex controlling terminal
1979Another way to specify where your program should do input and output is
1980with the @code{tty} command. This command accepts a file name as
1981argument, and causes this file to be the default for future @code{run}
1982commands. It also resets the controlling terminal for the child
1983process, for future @code{run} commands. For example,
1984
474c8240 1985@smallexample
c906108c 1986tty /dev/ttyb
474c8240 1987@end smallexample
c906108c
SS
1988
1989@noindent
1990directs that processes started with subsequent @code{run} commands
1991default to do input and output on the terminal @file{/dev/ttyb} and have
1992that as their controlling terminal.
1993
1994An explicit redirection in @code{run} overrides the @code{tty} command's
1995effect on the input/output device, but not its effect on the controlling
1996terminal.
1997
1998When you use the @code{tty} command or redirect input in the @code{run}
1999command, only the input @emph{for your program} is affected. The input
2000for @value{GDBN} still comes from your terminal.
2001
6d2ebf8b 2002@node Attach
c906108c
SS
2003@section Debugging an already-running process
2004@kindex attach
2005@cindex attach
2006
2007@table @code
2008@item attach @var{process-id}
2009This command attaches to a running process---one that was started
2010outside @value{GDBN}. (@code{info files} shows your active
2011targets.) The command takes as argument a process ID. The usual way to
09d4efe1 2012find out the @var{process-id} of a Unix process is with the @code{ps} utility,
c906108c
SS
2013or with the @samp{jobs -l} shell command.
2014
2015@code{attach} does not repeat if you press @key{RET} a second time after
2016executing the command.
2017@end table
2018
2019To use @code{attach}, your program must be running in an environment
2020which supports processes; for example, @code{attach} does not work for
2021programs on bare-board targets that lack an operating system. You must
2022also have permission to send the process a signal.
2023
2024When you use @code{attach}, the debugger finds the program running in
2025the process first by looking in the current working directory, then (if
2026the program is not found) by using the source file search path
2027(@pxref{Source Path, ,Specifying source directories}). You can also use
2028the @code{file} command to load the program. @xref{Files, ,Commands to
2029Specify Files}.
2030
2031The first thing @value{GDBN} does after arranging to debug the specified
2032process is to stop it. You can examine and modify an attached process
53a5351d
JM
2033with all the @value{GDBN} commands that are ordinarily available when
2034you start processes with @code{run}. You can insert breakpoints; you
2035can step and continue; you can modify storage. If you would rather the
2036process continue running, you may use the @code{continue} command after
c906108c
SS
2037attaching @value{GDBN} to the process.
2038
2039@table @code
2040@kindex detach
2041@item detach
2042When you have finished debugging the attached process, you can use the
2043@code{detach} command to release it from @value{GDBN} control. Detaching
2044the process continues its execution. After the @code{detach} command,
2045that process and @value{GDBN} become completely independent once more, and you
2046are ready to @code{attach} another process or start one with @code{run}.
2047@code{detach} does not repeat if you press @key{RET} again after
2048executing the command.
2049@end table
2050
2051If you exit @value{GDBN} or use the @code{run} command while you have an
2052attached process, you kill that process. By default, @value{GDBN} asks
2053for confirmation if you try to do either of these things; you can
2054control whether or not you need to confirm by using the @code{set
2055confirm} command (@pxref{Messages/Warnings, ,Optional warnings and
2056messages}).
2057
6d2ebf8b 2058@node Kill Process
c906108c 2059@section Killing the child process
c906108c
SS
2060
2061@table @code
2062@kindex kill
2063@item kill
2064Kill the child process in which your program is running under @value{GDBN}.
2065@end table
2066
2067This command is useful if you wish to debug a core dump instead of a
2068running process. @value{GDBN} ignores any core dump file while your program
2069is running.
2070
2071On some operating systems, a program cannot be executed outside @value{GDBN}
2072while you have breakpoints set on it inside @value{GDBN}. You can use the
2073@code{kill} command in this situation to permit running your program
2074outside the debugger.
2075
2076The @code{kill} command is also useful if you wish to recompile and
2077relink your program, since on many systems it is impossible to modify an
2078executable file while it is running in a process. In this case, when you
2079next type @code{run}, @value{GDBN} notices that the file has changed, and
2080reads the symbol table again (while trying to preserve your current
2081breakpoint settings).
2082
6d2ebf8b 2083@node Threads
c906108c 2084@section Debugging programs with multiple threads
c906108c
SS
2085
2086@cindex threads of execution
2087@cindex multiple threads
2088@cindex switching threads
2089In some operating systems, such as HP-UX and Solaris, a single program
2090may have more than one @dfn{thread} of execution. The precise semantics
2091of threads differ from one operating system to another, but in general
2092the threads of a single program are akin to multiple processes---except
2093that they share one address space (that is, they can all examine and
2094modify the same variables). On the other hand, each thread has its own
2095registers and execution stack, and perhaps private memory.
2096
2097@value{GDBN} provides these facilities for debugging multi-thread
2098programs:
2099
2100@itemize @bullet
2101@item automatic notification of new threads
2102@item @samp{thread @var{threadno}}, a command to switch among threads
2103@item @samp{info threads}, a command to inquire about existing threads
5d161b24 2104@item @samp{thread apply [@var{threadno}] [@var{all}] @var{args}},
c906108c
SS
2105a command to apply a command to a list of threads
2106@item thread-specific breakpoints
2107@end itemize
2108
c906108c
SS
2109@quotation
2110@emph{Warning:} These facilities are not yet available on every
2111@value{GDBN} configuration where the operating system supports threads.
2112If your @value{GDBN} does not support threads, these commands have no
2113effect. For example, a system without thread support shows no output
2114from @samp{info threads}, and always rejects the @code{thread} command,
2115like this:
2116
2117@smallexample
2118(@value{GDBP}) info threads
2119(@value{GDBP}) thread 1
2120Thread ID 1 not known. Use the "info threads" command to
2121see the IDs of currently known threads.
2122@end smallexample
2123@c FIXME to implementors: how hard would it be to say "sorry, this GDB
2124@c doesn't support threads"?
2125@end quotation
c906108c
SS
2126
2127@cindex focus of debugging
2128@cindex current thread
2129The @value{GDBN} thread debugging facility allows you to observe all
2130threads while your program runs---but whenever @value{GDBN} takes
2131control, one thread in particular is always the focus of debugging.
2132This thread is called the @dfn{current thread}. Debugging commands show
2133program information from the perspective of the current thread.
2134
41afff9a 2135@cindex @code{New} @var{systag} message
c906108c
SS
2136@cindex thread identifier (system)
2137@c FIXME-implementors!! It would be more helpful if the [New...] message
2138@c included GDB's numeric thread handle, so you could just go to that
2139@c thread without first checking `info threads'.
2140Whenever @value{GDBN} detects a new thread in your program, it displays
2141the target system's identification for the thread with a message in the
2142form @samp{[New @var{systag}]}. @var{systag} is a thread identifier
2143whose form varies depending on the particular system. For example, on
2144LynxOS, you might see
2145
474c8240 2146@smallexample
c906108c 2147[New process 35 thread 27]
474c8240 2148@end smallexample
c906108c
SS
2149
2150@noindent
2151when @value{GDBN} notices a new thread. In contrast, on an SGI system,
2152the @var{systag} is simply something like @samp{process 368}, with no
2153further qualifier.
2154
2155@c FIXME!! (1) Does the [New...] message appear even for the very first
2156@c thread of a program, or does it only appear for the
6ca652b0 2157@c second---i.e.@: when it becomes obvious we have a multithread
c906108c
SS
2158@c program?
2159@c (2) *Is* there necessarily a first thread always? Or do some
2160@c multithread systems permit starting a program with multiple
5d161b24 2161@c threads ab initio?
c906108c
SS
2162
2163@cindex thread number
2164@cindex thread identifier (GDB)
2165For debugging purposes, @value{GDBN} associates its own thread
2166number---always a single integer---with each thread in your program.
2167
2168@table @code
2169@kindex info threads
2170@item info threads
2171Display a summary of all threads currently in your
2172program. @value{GDBN} displays for each thread (in this order):
2173
2174@enumerate
09d4efe1
EZ
2175@item
2176the thread number assigned by @value{GDBN}
c906108c 2177
09d4efe1
EZ
2178@item
2179the target system's thread identifier (@var{systag})
c906108c 2180
09d4efe1
EZ
2181@item
2182the current stack frame summary for that thread
c906108c
SS
2183@end enumerate
2184
2185@noindent
2186An asterisk @samp{*} to the left of the @value{GDBN} thread number
2187indicates the current thread.
2188
5d161b24 2189For example,
c906108c
SS
2190@end table
2191@c end table here to get a little more width for example
2192
2193@smallexample
2194(@value{GDBP}) info threads
2195 3 process 35 thread 27 0x34e5 in sigpause ()
2196 2 process 35 thread 23 0x34e5 in sigpause ()
2197* 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8)
2198 at threadtest.c:68
2199@end smallexample
53a5351d
JM
2200
2201On HP-UX systems:
c906108c 2202
4644b6e3
EZ
2203@cindex debugging multithreaded programs (on HP-UX)
2204@cindex thread identifier (GDB), on HP-UX
c906108c
SS
2205For debugging purposes, @value{GDBN} associates its own thread
2206number---a small integer assigned in thread-creation order---with each
2207thread in your program.
2208
41afff9a
EZ
2209@cindex @code{New} @var{systag} message, on HP-UX
2210@cindex thread identifier (system), on HP-UX
c906108c
SS
2211@c FIXME-implementors!! It would be more helpful if the [New...] message
2212@c included GDB's numeric thread handle, so you could just go to that
2213@c thread without first checking `info threads'.
2214Whenever @value{GDBN} detects a new thread in your program, it displays
2215both @value{GDBN}'s thread number and the target system's identification for the thread with a message in the
2216form @samp{[New @var{systag}]}. @var{systag} is a thread identifier
2217whose form varies depending on the particular system. For example, on
2218HP-UX, you see
2219
474c8240 2220@smallexample
c906108c 2221[New thread 2 (system thread 26594)]
474c8240 2222@end smallexample
c906108c
SS
2223
2224@noindent
5d161b24 2225when @value{GDBN} notices a new thread.
c906108c
SS
2226
2227@table @code
4644b6e3 2228@kindex info threads (HP-UX)
c906108c
SS
2229@item info threads
2230Display a summary of all threads currently in your
2231program. @value{GDBN} displays for each thread (in this order):
2232
2233@enumerate
2234@item the thread number assigned by @value{GDBN}
2235
2236@item the target system's thread identifier (@var{systag})
2237
2238@item the current stack frame summary for that thread
2239@end enumerate
2240
2241@noindent
2242An asterisk @samp{*} to the left of the @value{GDBN} thread number
2243indicates the current thread.
2244
5d161b24 2245For example,
c906108c
SS
2246@end table
2247@c end table here to get a little more width for example
2248
474c8240 2249@smallexample
c906108c 2250(@value{GDBP}) info threads
6d2ebf8b
SS
2251 * 3 system thread 26607 worker (wptr=0x7b09c318 "@@") \@*
2252 at quicksort.c:137
2253 2 system thread 26606 0x7b0030d8 in __ksleep () \@*
2254 from /usr/lib/libc.2
2255 1 system thread 27905 0x7b003498 in _brk () \@*
2256 from /usr/lib/libc.2
474c8240 2257@end smallexample
c906108c
SS
2258
2259@table @code
2260@kindex thread @var{threadno}
2261@item thread @var{threadno}
2262Make thread number @var{threadno} the current thread. The command
2263argument @var{threadno} is the internal @value{GDBN} thread number, as
2264shown in the first field of the @samp{info threads} display.
2265@value{GDBN} responds by displaying the system identifier of the thread
2266you selected, and its current stack frame summary:
2267
2268@smallexample
2269@c FIXME!! This example made up; find a @value{GDBN} w/threads and get real one
2270(@value{GDBP}) thread 2
c906108c 2271[Switching to process 35 thread 23]
c906108c
SS
22720x34e5 in sigpause ()
2273@end smallexample
2274
2275@noindent
2276As with the @samp{[New @dots{}]} message, the form of the text after
2277@samp{Switching to} depends on your system's conventions for identifying
5d161b24 2278threads.
c906108c 2279
9c16f35a 2280@kindex thread apply
c906108c
SS
2281@item thread apply [@var{threadno}] [@var{all}] @var{args}
2282The @code{thread apply} command allows you to apply a command to one or
2283more threads. Specify the numbers of the threads that you want affected
2284with the command argument @var{threadno}. @var{threadno} is the internal
2285@value{GDBN} thread number, as shown in the first field of the @samp{info
5d161b24
DB
2286threads} display. To apply a command to all threads, use
2287@code{thread apply all} @var{args}.
c906108c
SS
2288@end table
2289
2290@cindex automatic thread selection
2291@cindex switching threads automatically
2292@cindex threads, automatic switching
2293Whenever @value{GDBN} stops your program, due to a breakpoint or a
2294signal, it automatically selects the thread where that breakpoint or
2295signal happened. @value{GDBN} alerts you to the context switch with a
2296message of the form @samp{[Switching to @var{systag}]} to identify the
2297thread.
2298
2299@xref{Thread Stops,,Stopping and starting multi-thread programs}, for
2300more information about how @value{GDBN} behaves when you stop and start
2301programs with multiple threads.
2302
2303@xref{Set Watchpoints,,Setting watchpoints}, for information about
2304watchpoints in programs with multiple threads.
c906108c 2305
6d2ebf8b 2306@node Processes
c906108c
SS
2307@section Debugging programs with multiple processes
2308
2309@cindex fork, debugging programs which call
2310@cindex multiple processes
2311@cindex processes, multiple
53a5351d
JM
2312On most systems, @value{GDBN} has no special support for debugging
2313programs which create additional processes using the @code{fork}
2314function. When a program forks, @value{GDBN} will continue to debug the
2315parent process and the child process will run unimpeded. If you have
2316set a breakpoint in any code which the child then executes, the child
2317will get a @code{SIGTRAP} signal which (unless it catches the signal)
2318will cause it to terminate.
c906108c
SS
2319
2320However, if you want to debug the child process there is a workaround
2321which isn't too painful. Put a call to @code{sleep} in the code which
2322the child process executes after the fork. It may be useful to sleep
2323only if a certain environment variable is set, or a certain file exists,
2324so that the delay need not occur when you don't want to run @value{GDBN}
2325on the child. While the child is sleeping, use the @code{ps} program to
2326get its process ID. Then tell @value{GDBN} (a new invocation of
2327@value{GDBN} if you are also debugging the parent process) to attach to
d4f3574e 2328the child process (@pxref{Attach}). From that point on you can debug
c906108c 2329the child process just like any other process which you attached to.
c906108c 2330
b51970ac
DJ
2331On some systems, @value{GDBN} provides support for debugging programs that
2332create additional processes using the @code{fork} or @code{vfork} functions.
2333Currently, the only platforms with this feature are HP-UX (11.x and later
2334only?) and GNU/Linux (kernel version 2.5.60 and later).
c906108c
SS
2335
2336By default, when a program forks, @value{GDBN} will continue to debug
2337the parent process and the child process will run unimpeded.
2338
2339If you want to follow the child process instead of the parent process,
2340use the command @w{@code{set follow-fork-mode}}.
2341
2342@table @code
2343@kindex set follow-fork-mode
2344@item set follow-fork-mode @var{mode}
2345Set the debugger response to a program call of @code{fork} or
2346@code{vfork}. A call to @code{fork} or @code{vfork} creates a new
9c16f35a 2347process. The @var{mode} argument can be:
c906108c
SS
2348
2349@table @code
2350@item parent
2351The original process is debugged after a fork. The child process runs
2df3850c 2352unimpeded. This is the default.
c906108c
SS
2353
2354@item child
2355The new process is debugged after a fork. The parent process runs
2356unimpeded.
2357
c906108c
SS
2358@end table
2359
9c16f35a 2360@kindex show follow-fork-mode
c906108c 2361@item show follow-fork-mode
2df3850c 2362Display the current debugger response to a @code{fork} or @code{vfork} call.
c906108c
SS
2363@end table
2364
2365If you ask to debug a child process and a @code{vfork} is followed by an
2366@code{exec}, @value{GDBN} executes the new target up to the first
2367breakpoint in the new target. If you have a breakpoint set on
2368@code{main} in your original program, the breakpoint will also be set on
2369the child process's @code{main}.
2370
2371When a child process is spawned by @code{vfork}, you cannot debug the
2372child or parent until an @code{exec} call completes.
2373
2374If you issue a @code{run} command to @value{GDBN} after an @code{exec}
2375call executes, the new target restarts. To restart the parent process,
2376use the @code{file} command with the parent executable name as its
2377argument.
2378
2379You can use the @code{catch} command to make @value{GDBN} stop whenever
2380a @code{fork}, @code{vfork}, or @code{exec} call is made. @xref{Set
2381Catchpoints, ,Setting catchpoints}.
c906108c 2382
6d2ebf8b 2383@node Stopping
c906108c
SS
2384@chapter Stopping and Continuing
2385
2386The principal purposes of using a debugger are so that you can stop your
2387program before it terminates; or so that, if your program runs into
2388trouble, you can investigate and find out why.
2389
7a292a7a
SS
2390Inside @value{GDBN}, your program may stop for any of several reasons,
2391such as a signal, a breakpoint, or reaching a new line after a
2392@value{GDBN} command such as @code{step}. You may then examine and
2393change variables, set new breakpoints or remove old ones, and then
2394continue execution. Usually, the messages shown by @value{GDBN} provide
2395ample explanation of the status of your program---but you can also
2396explicitly request this information at any time.
c906108c
SS
2397
2398@table @code
2399@kindex info program
2400@item info program
2401Display information about the status of your program: whether it is
7a292a7a 2402running or not, what process it is, and why it stopped.
c906108c
SS
2403@end table
2404
2405@menu
2406* Breakpoints:: Breakpoints, watchpoints, and catchpoints
2407* Continuing and Stepping:: Resuming execution
c906108c 2408* Signals:: Signals
c906108c 2409* Thread Stops:: Stopping and starting multi-thread programs
c906108c
SS
2410@end menu
2411
6d2ebf8b 2412@node Breakpoints
c906108c
SS
2413@section Breakpoints, watchpoints, and catchpoints
2414
2415@cindex breakpoints
2416A @dfn{breakpoint} makes your program stop whenever a certain point in
2417the program is reached. For each breakpoint, you can add conditions to
2418control in finer detail whether your program stops. You can set
2419breakpoints with the @code{break} command and its variants (@pxref{Set
2420Breaks, ,Setting breakpoints}), to specify the place where your program
2421should stop by line number, function name or exact address in the
2422program.
2423
09d4efe1
EZ
2424On some systems, you can set breakpoints in shared libraries before
2425the executable is run. There is a minor limitation on HP-UX systems:
2426you must wait until the executable is run in order to set breakpoints
2427in shared library routines that are not called directly by the program
2428(for example, routines that are arguments in a @code{pthread_create}
2429call).
c906108c
SS
2430
2431@cindex watchpoints
2432@cindex memory tracing
2433@cindex breakpoint on memory address
2434@cindex breakpoint on variable modification
2435A @dfn{watchpoint} is a special breakpoint that stops your program
2436when the value of an expression changes. You must use a different
2437command to set watchpoints (@pxref{Set Watchpoints, ,Setting
2438watchpoints}), but aside from that, you can manage a watchpoint like
2439any other breakpoint: you enable, disable, and delete both breakpoints
2440and watchpoints using the same commands.
2441
2442You can arrange to have values from your program displayed automatically
2443whenever @value{GDBN} stops at a breakpoint. @xref{Auto Display,,
2444Automatic display}.
2445
2446@cindex catchpoints
2447@cindex breakpoint on events
2448A @dfn{catchpoint} is another special breakpoint that stops your program
b37052ae 2449when a certain kind of event occurs, such as the throwing of a C@t{++}
c906108c
SS
2450exception or the loading of a library. As with watchpoints, you use a
2451different command to set a catchpoint (@pxref{Set Catchpoints, ,Setting
2452catchpoints}), but aside from that, you can manage a catchpoint like any
2453other breakpoint. (To stop when your program receives a signal, use the
d4f3574e 2454@code{handle} command; see @ref{Signals, ,Signals}.)
c906108c
SS
2455
2456@cindex breakpoint numbers
2457@cindex numbers for breakpoints
2458@value{GDBN} assigns a number to each breakpoint, watchpoint, or
2459catchpoint when you create it; these numbers are successive integers
2460starting with one. In many of the commands for controlling various
2461features of breakpoints you use the breakpoint number to say which
2462breakpoint you want to change. Each breakpoint may be @dfn{enabled} or
2463@dfn{disabled}; if disabled, it has no effect on your program until you
2464enable it again.
2465
c5394b80
JM
2466@cindex breakpoint ranges
2467@cindex ranges of breakpoints
2468Some @value{GDBN} commands accept a range of breakpoints on which to
2469operate. A breakpoint range is either a single breakpoint number, like
2470@samp{5}, or two such numbers, in increasing order, separated by a
2471hyphen, like @samp{5-7}. When a breakpoint range is given to a command,
2472all breakpoint in that range are operated on.
2473
c906108c
SS
2474@menu
2475* Set Breaks:: Setting breakpoints
2476* Set Watchpoints:: Setting watchpoints
2477* Set Catchpoints:: Setting catchpoints
2478* Delete Breaks:: Deleting breakpoints
2479* Disabling:: Disabling breakpoints
2480* Conditions:: Break conditions
2481* Break Commands:: Breakpoint command lists
c906108c 2482* Breakpoint Menus:: Breakpoint menus
d4f3574e 2483* Error in Breakpoints:: ``Cannot insert breakpoints''
e4d5f7e1 2484* Breakpoint related warnings:: ``Breakpoint address adjusted...''
c906108c
SS
2485@end menu
2486
6d2ebf8b 2487@node Set Breaks
c906108c
SS
2488@subsection Setting breakpoints
2489
5d161b24 2490@c FIXME LMB what does GDB do if no code on line of breakpt?
c906108c
SS
2491@c consider in particular declaration with/without initialization.
2492@c
2493@c FIXME 2 is there stuff on this already? break at fun start, already init?
2494
2495@kindex break
41afff9a
EZ
2496@kindex b @r{(@code{break})}
2497@vindex $bpnum@r{, convenience variable}
c906108c
SS
2498@cindex latest breakpoint
2499Breakpoints are set with the @code{break} command (abbreviated
5d161b24 2500@code{b}). The debugger convenience variable @samp{$bpnum} records the
f3b28801 2501number of the breakpoint you've set most recently; see @ref{Convenience
c906108c
SS
2502Vars,, Convenience variables}, for a discussion of what you can do with
2503convenience variables.
2504
2505You have several ways to say where the breakpoint should go.
2506
2507@table @code
2508@item break @var{function}
5d161b24 2509Set a breakpoint at entry to function @var{function}.
c906108c 2510When using source languages that permit overloading of symbols, such as
b37052ae 2511C@t{++}, @var{function} may refer to more than one possible place to break.
c906108c 2512@xref{Breakpoint Menus,,Breakpoint menus}, for a discussion of that situation.
c906108c
SS
2513
2514@item break +@var{offset}
2515@itemx break -@var{offset}
2516Set a breakpoint some number of lines forward or back from the position
d4f3574e 2517at which execution stopped in the currently selected @dfn{stack frame}.
2df3850c 2518(@xref{Frames, ,Frames}, for a description of stack frames.)
c906108c
SS
2519
2520@item break @var{linenum}
2521Set a breakpoint at line @var{linenum} in the current source file.
d4f3574e
SS
2522The current source file is the last file whose source text was printed.
2523The breakpoint will stop your program just before it executes any of the
c906108c
SS
2524code on that line.
2525
2526@item break @var{filename}:@var{linenum}
2527Set a breakpoint at line @var{linenum} in source file @var{filename}.
2528
2529@item break @var{filename}:@var{function}
2530Set a breakpoint at entry to function @var{function} found in file
2531@var{filename}. Specifying a file name as well as a function name is
2532superfluous except when multiple files contain similarly named
2533functions.
2534
2535@item break *@var{address}
2536Set a breakpoint at address @var{address}. You can use this to set
2537breakpoints in parts of your program which do not have debugging
2538information or source files.
2539
2540@item break
2541When called without any arguments, @code{break} sets a breakpoint at
2542the next instruction to be executed in the selected stack frame
2543(@pxref{Stack, ,Examining the Stack}). In any selected frame but the
2544innermost, this makes your program stop as soon as control
2545returns to that frame. This is similar to the effect of a
2546@code{finish} command in the frame inside the selected frame---except
2547that @code{finish} does not leave an active breakpoint. If you use
2548@code{break} without an argument in the innermost frame, @value{GDBN} stops
2549the next time it reaches the current location; this may be useful
2550inside loops.
2551
2552@value{GDBN} normally ignores breakpoints when it resumes execution, until at
2553least one instruction has been executed. If it did not do this, you
2554would be unable to proceed past a breakpoint without first disabling the
2555breakpoint. This rule applies whether or not the breakpoint already
2556existed when your program stopped.
2557
2558@item break @dots{} if @var{cond}
2559Set a breakpoint with condition @var{cond}; evaluate the expression
2560@var{cond} each time the breakpoint is reached, and stop only if the
2561value is nonzero---that is, if @var{cond} evaluates as true.
2562@samp{@dots{}} stands for one of the possible arguments described
2563above (or no argument) specifying where to break. @xref{Conditions,
2564,Break conditions}, for more information on breakpoint conditions.
2565
2566@kindex tbreak
2567@item tbreak @var{args}
2568Set a breakpoint enabled only for one stop. @var{args} are the
2569same as for the @code{break} command, and the breakpoint is set in the same
2570way, but the breakpoint is automatically deleted after the first time your
2571program stops there. @xref{Disabling, ,Disabling breakpoints}.
2572
c906108c
SS
2573@kindex hbreak
2574@item hbreak @var{args}
d4f3574e
SS
2575Set a hardware-assisted breakpoint. @var{args} are the same as for the
2576@code{break} command and the breakpoint is set in the same way, but the
c906108c
SS
2577breakpoint requires hardware support and some target hardware may not
2578have this support. The main purpose of this is EPROM/ROM code
d4f3574e
SS
2579debugging, so you can set a breakpoint at an instruction without
2580changing the instruction. This can be used with the new trap-generation
09d4efe1 2581provided by SPARClite DSU and most x86-based targets. These targets
d4f3574e
SS
2582will generate traps when a program accesses some data or instruction
2583address that is assigned to the debug registers. However the hardware
2584breakpoint registers can take a limited number of breakpoints. For
2585example, on the DSU, only two data breakpoints can be set at a time, and
2586@value{GDBN} will reject this command if more than two are used. Delete
2587or disable unused hardware breakpoints before setting new ones
2588(@pxref{Disabling, ,Disabling}). @xref{Conditions, ,Break conditions}.
9c16f35a
EZ
2589For remote targets, you can restrict the number of hardware
2590breakpoints @value{GDBN} will use, see @ref{set remote
2591hardware-breakpoint-limit}.
501eef12 2592
c906108c
SS
2593
2594@kindex thbreak
2595@item thbreak @var{args}
2596Set a hardware-assisted breakpoint enabled only for one stop. @var{args}
2597are the same as for the @code{hbreak} command and the breakpoint is set in
5d161b24 2598the same way. However, like the @code{tbreak} command,
c906108c
SS
2599the breakpoint is automatically deleted after the
2600first time your program stops there. Also, like the @code{hbreak}
5d161b24
DB
2601command, the breakpoint requires hardware support and some target hardware
2602may not have this support. @xref{Disabling, ,Disabling breakpoints}.
d4f3574e 2603See also @ref{Conditions, ,Break conditions}.
c906108c
SS
2604
2605@kindex rbreak
2606@cindex regular expression
2607@item rbreak @var{regex}
c906108c 2608Set breakpoints on all functions matching the regular expression
11cf8741
JM
2609@var{regex}. This command sets an unconditional breakpoint on all
2610matches, printing a list of all breakpoints it set. Once these
2611breakpoints are set, they are treated just like the breakpoints set with
2612the @code{break} command. You can delete them, disable them, or make
2613them conditional the same way as any other breakpoint.
2614
2615The syntax of the regular expression is the standard one used with tools
2616like @file{grep}. Note that this is different from the syntax used by
2617shells, so for instance @code{foo*} matches all functions that include
2618an @code{fo} followed by zero or more @code{o}s. There is an implicit
2619@code{.*} leading and trailing the regular expression you supply, so to
2620match only functions that begin with @code{foo}, use @code{^foo}.
c906108c 2621
f7dc1244 2622@cindex non-member C@t{++} functions, set breakpoint in
b37052ae 2623When debugging C@t{++} programs, @code{rbreak} is useful for setting
c906108c
SS
2624breakpoints on overloaded functions that are not members of any special
2625classes.
c906108c 2626
f7dc1244
EZ
2627@cindex set breakpoints on all functions
2628The @code{rbreak} command can be used to set breakpoints in
2629@strong{all} the functions in a program, like this:
2630
2631@smallexample
2632(@value{GDBP}) rbreak .
2633@end smallexample
2634
c906108c
SS
2635@kindex info breakpoints
2636@cindex @code{$_} and @code{info breakpoints}
2637@item info breakpoints @r{[}@var{n}@r{]}
2638@itemx info break @r{[}@var{n}@r{]}
2639@itemx info watchpoints @r{[}@var{n}@r{]}
2640Print a table of all breakpoints, watchpoints, and catchpoints set and
2641not deleted, with the following columns for each breakpoint:
2642
2643@table @emph
2644@item Breakpoint Numbers
2645@item Type
2646Breakpoint, watchpoint, or catchpoint.
2647@item Disposition
2648Whether the breakpoint is marked to be disabled or deleted when hit.
2649@item Enabled or Disabled
2650Enabled breakpoints are marked with @samp{y}. @samp{n} marks breakpoints
2651that are not enabled.
2652@item Address
2650777c
JJ
2653Where the breakpoint is in your program, as a memory address. If the
2654breakpoint is pending (see below for details) on a future load of a shared library, the address
2655will be listed as @samp{<PENDING>}.
c906108c
SS
2656@item What
2657Where the breakpoint is in the source for your program, as a file and
2650777c
JJ
2658line number. For a pending breakpoint, the original string passed to
2659the breakpoint command will be listed as it cannot be resolved until
2660the appropriate shared library is loaded in the future.
c906108c
SS
2661@end table
2662
2663@noindent
2664If a breakpoint is conditional, @code{info break} shows the condition on
2665the line following the affected breakpoint; breakpoint commands, if any,
2650777c
JJ
2666are listed after that. A pending breakpoint is allowed to have a condition
2667specified for it. The condition is not parsed for validity until a shared
2668library is loaded that allows the pending breakpoint to resolve to a
2669valid location.
c906108c
SS
2670
2671@noindent
2672@code{info break} with a breakpoint
2673number @var{n} as argument lists only that breakpoint. The
2674convenience variable @code{$_} and the default examining-address for
2675the @code{x} command are set to the address of the last breakpoint
5d161b24 2676listed (@pxref{Memory, ,Examining memory}).
c906108c
SS
2677
2678@noindent
2679@code{info break} displays a count of the number of times the breakpoint
2680has been hit. This is especially useful in conjunction with the
2681@code{ignore} command. You can ignore a large number of breakpoint
2682hits, look at the breakpoint info to see how many times the breakpoint
2683was hit, and then run again, ignoring one less than that number. This
2684will get you quickly to the last hit of that breakpoint.
2685@end table
2686
2687@value{GDBN} allows you to set any number of breakpoints at the same place in
2688your program. There is nothing silly or meaningless about this. When
2689the breakpoints are conditional, this is even useful
2690(@pxref{Conditions, ,Break conditions}).
2691
2650777c 2692@cindex pending breakpoints
dd79a6cf
JJ
2693If a specified breakpoint location cannot be found, it may be due to the fact
2694that the location is in a shared library that is yet to be loaded. In such
2695a case, you may want @value{GDBN} to create a special breakpoint (known as
2696a @dfn{pending breakpoint}) that
2697attempts to resolve itself in the future when an appropriate shared library
2698gets loaded.
2699
2700Pending breakpoints are useful to set at the start of your
2650777c
JJ
2701@value{GDBN} session for locations that you know will be dynamically loaded
2702later by the program being debugged. When shared libraries are loaded,
dd79a6cf
JJ
2703a check is made to see if the load resolves any pending breakpoint locations.
2704If a pending breakpoint location gets resolved,
2705a regular breakpoint is created and the original pending breakpoint is removed.
2706
2707@value{GDBN} provides some additional commands for controlling pending
2708breakpoint support:
2709
2710@kindex set breakpoint pending
2711@kindex show breakpoint pending
2712@table @code
2713@item set breakpoint pending auto
2714This is the default behavior. When @value{GDBN} cannot find the breakpoint
2715location, it queries you whether a pending breakpoint should be created.
2716
2717@item set breakpoint pending on
2718This indicates that an unrecognized breakpoint location should automatically
2719result in a pending breakpoint being created.
2720
2721@item set breakpoint pending off
2722This indicates that pending breakpoints are not to be created. Any
2723unrecognized breakpoint location results in an error. This setting does
2724not affect any pending breakpoints previously created.
2725
2726@item show breakpoint pending
2727Show the current behavior setting for creating pending breakpoints.
2728@end table
2650777c 2729
649e03f6
RM
2730@cindex operations allowed on pending breakpoints
2731Normal breakpoint operations apply to pending breakpoints as well. You may
2732specify a condition for a pending breakpoint and/or commands to run when the
2650777c
JJ
2733breakpoint is reached. You can also enable or disable
2734the pending breakpoint. When you specify a condition for a pending breakpoint,
2735the parsing of the condition will be deferred until the point where the
2736pending breakpoint location is resolved. Disabling a pending breakpoint
2737tells @value{GDBN} to not attempt to resolve the breakpoint on any subsequent
2738shared library load. When a pending breakpoint is re-enabled,
649e03f6 2739@value{GDBN} checks to see if the location is already resolved.
2650777c
JJ
2740This is done because any number of shared library loads could have
2741occurred since the time the breakpoint was disabled and one or more
2742of these loads could resolve the location.
2743
c906108c
SS
2744@cindex negative breakpoint numbers
2745@cindex internal @value{GDBN} breakpoints
eb12ee30
AC
2746@value{GDBN} itself sometimes sets breakpoints in your program for
2747special purposes, such as proper handling of @code{longjmp} (in C
2748programs). These internal breakpoints are assigned negative numbers,
2749starting with @code{-1}; @samp{info breakpoints} does not display them.
c906108c 2750You can see these breakpoints with the @value{GDBN} maintenance command
eb12ee30 2751@samp{maint info breakpoints} (@pxref{maint info breakpoints}).
c906108c
SS
2752
2753
6d2ebf8b 2754@node Set Watchpoints
c906108c
SS
2755@subsection Setting watchpoints
2756
2757@cindex setting watchpoints
c906108c
SS
2758You can use a watchpoint to stop execution whenever the value of an
2759expression changes, without having to predict a particular place where
2760this may happen.
2761
82f2d802
EZ
2762@cindex software watchpoints
2763@cindex hardware watchpoints
c906108c 2764Depending on your system, watchpoints may be implemented in software or
2df3850c 2765hardware. @value{GDBN} does software watchpointing by single-stepping your
c906108c
SS
2766program and testing the variable's value each time, which is hundreds of
2767times slower than normal execution. (But this may still be worth it, to
2768catch errors where you have no clue what part of your program is the
2769culprit.)
2770
82f2d802
EZ
2771On some systems, such as HP-UX, @sc{gnu}/Linux and most other
2772x86-based targets, @value{GDBN} includes support for hardware
2773watchpoints, which do not slow down the running of your program.
c906108c
SS
2774
2775@table @code
2776@kindex watch
2777@item watch @var{expr}
2778Set a watchpoint for an expression. @value{GDBN} will break when @var{expr}
2779is written into by the program and its value changes.
2780
2781@kindex rwatch
2782@item rwatch @var{expr}
09d4efe1
EZ
2783Set a watchpoint that will break when the value of @var{expr} is read
2784by the program.
c906108c
SS
2785
2786@kindex awatch
2787@item awatch @var{expr}
09d4efe1
EZ
2788Set a watchpoint that will break when @var{expr} is either read from
2789or written into by the program.
c906108c
SS
2790
2791@kindex info watchpoints
2792@item info watchpoints
2793This command prints a list of watchpoints, breakpoints, and catchpoints;
09d4efe1 2794it is the same as @code{info break} (@pxref{Set Breaks}).
c906108c
SS
2795@end table
2796
2797@value{GDBN} sets a @dfn{hardware watchpoint} if possible. Hardware
2798watchpoints execute very quickly, and the debugger reports a change in
2799value at the exact instruction where the change occurs. If @value{GDBN}
2800cannot set a hardware watchpoint, it sets a software watchpoint, which
2801executes more slowly and reports the change in value at the next
82f2d802
EZ
2802@emph{statement}, not the instruction, after the change occurs.
2803
2804@vindex can-use-hw-watchpoints
2805@cindex use only software watchpoints
2806You can force @value{GDBN} to use only software watchpoints with the
2807@kbd{set can-use-hw-watchpoints 0} command. With this variable set to
2808zero, @value{GDBN} will never try to use hardware watchpoints, even if
2809the underlying system supports them. (Note that hardware-assisted
2810watchpoints that were set @emph{before} setting
2811@code{can-use-hw-watchpoints} to zero will still use the hardware
2812mechanism of watching expressiion values.)
c906108c 2813
9c16f35a
EZ
2814@table @code
2815@item set can-use-hw-watchpoints
2816@kindex set can-use-hw-watchpoints
2817Set whether or not to use hardware watchpoints.
2818
2819@item show can-use-hw-watchpoints
2820@kindex show can-use-hw-watchpoints
2821Show the current mode of using hardware watchpoints.
2822@end table
2823
2824For remote targets, you can restrict the number of hardware
2825watchpoints @value{GDBN} will use, see @ref{set remote
2826hardware-breakpoint-limit}.
2827
c906108c
SS
2828When you issue the @code{watch} command, @value{GDBN} reports
2829
474c8240 2830@smallexample
c906108c 2831Hardware watchpoint @var{num}: @var{expr}
474c8240 2832@end smallexample
c906108c
SS
2833
2834@noindent
2835if it was able to set a hardware watchpoint.
2836
7be570e7
JM
2837Currently, the @code{awatch} and @code{rwatch} commands can only set
2838hardware watchpoints, because accesses to data that don't change the
2839value of the watched expression cannot be detected without examining
2840every instruction as it is being executed, and @value{GDBN} does not do
2841that currently. If @value{GDBN} finds that it is unable to set a
2842hardware breakpoint with the @code{awatch} or @code{rwatch} command, it
2843will print a message like this:
2844
2845@smallexample
2846Expression cannot be implemented with read/access watchpoint.
2847@end smallexample
2848
2849Sometimes, @value{GDBN} cannot set a hardware watchpoint because the
2850data type of the watched expression is wider than what a hardware
2851watchpoint on the target machine can handle. For example, some systems
2852can only watch regions that are up to 4 bytes wide; on such systems you
2853cannot set hardware watchpoints for an expression that yields a
2854double-precision floating-point number (which is typically 8 bytes
2855wide). As a work-around, it might be possible to break the large region
2856into a series of smaller ones and watch them with separate watchpoints.
2857
2858If you set too many hardware watchpoints, @value{GDBN} might be unable
2859to insert all of them when you resume the execution of your program.
2860Since the precise number of active watchpoints is unknown until such
2861time as the program is about to be resumed, @value{GDBN} might not be
2862able to warn you about this when you set the watchpoints, and the
2863warning will be printed only when the program is resumed:
2864
2865@smallexample
2866Hardware watchpoint @var{num}: Could not insert watchpoint
2867@end smallexample
2868
2869@noindent
2870If this happens, delete or disable some of the watchpoints.
2871
2872The SPARClite DSU will generate traps when a program accesses some data
2873or instruction address that is assigned to the debug registers. For the
2874data addresses, DSU facilitates the @code{watch} command. However the
2875hardware breakpoint registers can only take two data watchpoints, and
2876both watchpoints must be the same kind. For example, you can set two
2877watchpoints with @code{watch} commands, two with @code{rwatch} commands,
2878@strong{or} two with @code{awatch} commands, but you cannot set one
2879watchpoint with one command and the other with a different command.
c906108c
SS
2880@value{GDBN} will reject the command if you try to mix watchpoints.
2881Delete or disable unused watchpoint commands before setting new ones.
2882
2883If you call a function interactively using @code{print} or @code{call},
2df3850c 2884any watchpoints you have set will be inactive until @value{GDBN} reaches another
c906108c
SS
2885kind of breakpoint or the call completes.
2886
7be570e7
JM
2887@value{GDBN} automatically deletes watchpoints that watch local
2888(automatic) variables, or expressions that involve such variables, when
2889they go out of scope, that is, when the execution leaves the block in
2890which these variables were defined. In particular, when the program
2891being debugged terminates, @emph{all} local variables go out of scope,
2892and so only watchpoints that watch global variables remain set. If you
2893rerun the program, you will need to set all such watchpoints again. One
2894way of doing that would be to set a code breakpoint at the entry to the
2895@code{main} function and when it breaks, set all the watchpoints.
2896
c906108c
SS
2897@quotation
2898@cindex watchpoints and threads
2899@cindex threads and watchpoints
c906108c
SS
2900@emph{Warning:} In multi-thread programs, watchpoints have only limited
2901usefulness. With the current watchpoint implementation, @value{GDBN}
2902can only watch the value of an expression @emph{in a single thread}. If
2903you are confident that the expression can only change due to the current
2904thread's activity (and if you are also confident that no other thread
2905can become current), then you can use watchpoints as usual. However,
2906@value{GDBN} may not notice when a non-current thread's activity changes
2907the expression.
53a5351d 2908
d4f3574e 2909@c FIXME: this is almost identical to the previous paragraph.
53a5351d
JM
2910@emph{HP-UX Warning:} In multi-thread programs, software watchpoints
2911have only limited usefulness. If @value{GDBN} creates a software
2912watchpoint, it can only watch the value of an expression @emph{in a
2913single thread}. If you are confident that the expression can only
2914change due to the current thread's activity (and if you are also
2915confident that no other thread can become current), then you can use
2916software watchpoints as usual. However, @value{GDBN} may not notice
2917when a non-current thread's activity changes the expression. (Hardware
2918watchpoints, in contrast, watch an expression in all threads.)
c906108c 2919@end quotation
c906108c 2920
501eef12
AC
2921@xref{set remote hardware-watchpoint-limit}.
2922
6d2ebf8b 2923@node Set Catchpoints
c906108c 2924@subsection Setting catchpoints
d4f3574e 2925@cindex catchpoints, setting
c906108c
SS
2926@cindex exception handlers
2927@cindex event handling
2928
2929You can use @dfn{catchpoints} to cause the debugger to stop for certain
b37052ae 2930kinds of program events, such as C@t{++} exceptions or the loading of a
c906108c
SS
2931shared library. Use the @code{catch} command to set a catchpoint.
2932
2933@table @code
2934@kindex catch
2935@item catch @var{event}
2936Stop when @var{event} occurs. @var{event} can be any of the following:
2937@table @code
2938@item throw
4644b6e3 2939@cindex stop on C@t{++} exceptions
b37052ae 2940The throwing of a C@t{++} exception.
c906108c
SS
2941
2942@item catch
b37052ae 2943The catching of a C@t{++} exception.
c906108c
SS
2944
2945@item exec
4644b6e3 2946@cindex break on fork/exec
c906108c
SS
2947A call to @code{exec}. This is currently only available for HP-UX.
2948
2949@item fork
c906108c
SS
2950A call to @code{fork}. This is currently only available for HP-UX.
2951
2952@item vfork
c906108c
SS
2953A call to @code{vfork}. This is currently only available for HP-UX.
2954
2955@item load
2956@itemx load @var{libname}
4644b6e3 2957@cindex break on load/unload of shared library
c906108c
SS
2958The dynamic loading of any shared library, or the loading of the library
2959@var{libname}. This is currently only available for HP-UX.
2960
2961@item unload
2962@itemx unload @var{libname}
c906108c
SS
2963The unloading of any dynamically loaded shared library, or the unloading
2964of the library @var{libname}. This is currently only available for HP-UX.
2965@end table
2966
2967@item tcatch @var{event}
2968Set a catchpoint that is enabled only for one stop. The catchpoint is
2969automatically deleted after the first time the event is caught.
2970
2971@end table
2972
2973Use the @code{info break} command to list the current catchpoints.
2974
b37052ae 2975There are currently some limitations to C@t{++} exception handling
c906108c
SS
2976(@code{catch throw} and @code{catch catch}) in @value{GDBN}:
2977
2978@itemize @bullet
2979@item
2980If you call a function interactively, @value{GDBN} normally returns
2981control to you when the function has finished executing. If the call
2982raises an exception, however, the call may bypass the mechanism that
2983returns control to you and cause your program either to abort or to
2984simply continue running until it hits a breakpoint, catches a signal
2985that @value{GDBN} is listening for, or exits. This is the case even if
2986you set a catchpoint for the exception; catchpoints on exceptions are
2987disabled within interactive calls.
2988
2989@item
2990You cannot raise an exception interactively.
2991
2992@item
2993You cannot install an exception handler interactively.
2994@end itemize
2995
2996@cindex raise exceptions
2997Sometimes @code{catch} is not the best way to debug exception handling:
2998if you need to know exactly where an exception is raised, it is better to
2999stop @emph{before} the exception handler is called, since that way you
3000can see the stack before any unwinding takes place. If you set a
3001breakpoint in an exception handler instead, it may not be easy to find
3002out where the exception was raised.
3003
3004To stop just before an exception handler is called, you need some
b37052ae 3005knowledge of the implementation. In the case of @sc{gnu} C@t{++}, exceptions are
c906108c
SS
3006raised by calling a library function named @code{__raise_exception}
3007which has the following ANSI C interface:
3008
474c8240 3009@smallexample
c906108c 3010 /* @var{addr} is where the exception identifier is stored.
d4f3574e
SS
3011 @var{id} is the exception identifier. */
3012 void __raise_exception (void **addr, void *id);
474c8240 3013@end smallexample
c906108c
SS
3014
3015@noindent
3016To make the debugger catch all exceptions before any stack
3017unwinding takes place, set a breakpoint on @code{__raise_exception}
3018(@pxref{Breakpoints, ,Breakpoints; watchpoints; and exceptions}).
3019
3020With a conditional breakpoint (@pxref{Conditions, ,Break conditions})
3021that depends on the value of @var{id}, you can stop your program when
3022a specific exception is raised. You can use multiple conditional
3023breakpoints to stop your program when any of a number of exceptions are
3024raised.
3025
3026
6d2ebf8b 3027@node Delete Breaks
c906108c
SS
3028@subsection Deleting breakpoints
3029
3030@cindex clearing breakpoints, watchpoints, catchpoints
3031@cindex deleting breakpoints, watchpoints, catchpoints
3032It is often necessary to eliminate a breakpoint, watchpoint, or
3033catchpoint once it has done its job and you no longer want your program
3034to stop there. This is called @dfn{deleting} the breakpoint. A
3035breakpoint that has been deleted no longer exists; it is forgotten.
3036
3037With the @code{clear} command you can delete breakpoints according to
3038where they are in your program. With the @code{delete} command you can
3039delete individual breakpoints, watchpoints, or catchpoints by specifying
3040their breakpoint numbers.
3041
3042It is not necessary to delete a breakpoint to proceed past it. @value{GDBN}
3043automatically ignores breakpoints on the first instruction to be executed
3044when you continue execution without changing the execution address.
3045
3046@table @code
3047@kindex clear
3048@item clear
3049Delete any breakpoints at the next instruction to be executed in the
3050selected stack frame (@pxref{Selection, ,Selecting a frame}). When
3051the innermost frame is selected, this is a good way to delete a
3052breakpoint where your program just stopped.
3053
3054@item clear @var{function}
3055@itemx clear @var{filename}:@var{function}
09d4efe1 3056Delete any breakpoints set at entry to the named @var{function}.
c906108c
SS
3057
3058@item clear @var{linenum}
3059@itemx clear @var{filename}:@var{linenum}
09d4efe1
EZ
3060Delete any breakpoints set at or within the code of the specified
3061@var{linenum} of the specified @var{filename}.
c906108c
SS
3062
3063@cindex delete breakpoints
3064@kindex delete
41afff9a 3065@kindex d @r{(@code{delete})}
c5394b80
JM
3066@item delete @r{[}breakpoints@r{]} @r{[}@var{range}@dots{}@r{]}
3067Delete the breakpoints, watchpoints, or catchpoints of the breakpoint
3068ranges specified as arguments. If no argument is specified, delete all
c906108c
SS
3069breakpoints (@value{GDBN} asks confirmation, unless you have @code{set
3070confirm off}). You can abbreviate this command as @code{d}.
3071@end table
3072
6d2ebf8b 3073@node Disabling
c906108c
SS
3074@subsection Disabling breakpoints
3075
4644b6e3 3076@cindex enable/disable a breakpoint
c906108c
SS
3077Rather than deleting a breakpoint, watchpoint, or catchpoint, you might
3078prefer to @dfn{disable} it. This makes the breakpoint inoperative as if
3079it had been deleted, but remembers the information on the breakpoint so
3080that you can @dfn{enable} it again later.
3081
3082You disable and enable breakpoints, watchpoints, and catchpoints with
3083the @code{enable} and @code{disable} commands, optionally specifying one
3084or more breakpoint numbers as arguments. Use @code{info break} or
3085@code{info watch} to print a list of breakpoints, watchpoints, and
3086catchpoints if you do not know which numbers to use.
3087
3088A breakpoint, watchpoint, or catchpoint can have any of four different
3089states of enablement:
3090
3091@itemize @bullet
3092@item
3093Enabled. The breakpoint stops your program. A breakpoint set
3094with the @code{break} command starts out in this state.
3095@item
3096Disabled. The breakpoint has no effect on your program.
3097@item
3098Enabled once. The breakpoint stops your program, but then becomes
d4f3574e 3099disabled.
c906108c
SS
3100@item
3101Enabled for deletion. The breakpoint stops your program, but
d4f3574e
SS
3102immediately after it does so it is deleted permanently. A breakpoint
3103set with the @code{tbreak} command starts out in this state.
c906108c
SS
3104@end itemize
3105
3106You can use the following commands to enable or disable breakpoints,
3107watchpoints, and catchpoints:
3108
3109@table @code
c906108c 3110@kindex disable
41afff9a 3111@kindex dis @r{(@code{disable})}
c5394b80 3112@item disable @r{[}breakpoints@r{]} @r{[}@var{range}@dots{}@r{]}
c906108c
SS
3113Disable the specified breakpoints---or all breakpoints, if none are
3114listed. A disabled breakpoint has no effect but is not forgotten. All
3115options such as ignore-counts, conditions and commands are remembered in
3116case the breakpoint is enabled again later. You may abbreviate
3117@code{disable} as @code{dis}.
3118
c906108c 3119@kindex enable
c5394b80 3120@item enable @r{[}breakpoints@r{]} @r{[}@var{range}@dots{}@r{]}
c906108c
SS
3121Enable the specified breakpoints (or all defined breakpoints). They
3122become effective once again in stopping your program.
3123
c5394b80 3124@item enable @r{[}breakpoints@r{]} once @var{range}@dots{}
c906108c
SS
3125Enable the specified breakpoints temporarily. @value{GDBN} disables any
3126of these breakpoints immediately after stopping your program.
3127
c5394b80 3128@item enable @r{[}breakpoints@r{]} delete @var{range}@dots{}
c906108c
SS
3129Enable the specified breakpoints to work once, then die. @value{GDBN}
3130deletes any of these breakpoints as soon as your program stops there.
09d4efe1 3131Breakpoints set by the @code{tbreak} command start out in this state.
c906108c
SS
3132@end table
3133
d4f3574e
SS
3134@c FIXME: I think the following ``Except for [...] @code{tbreak}'' is
3135@c confusing: tbreak is also initially enabled.
c906108c
SS
3136Except for a breakpoint set with @code{tbreak} (@pxref{Set Breaks,
3137,Setting breakpoints}), breakpoints that you set are initially enabled;
3138subsequently, they become disabled or enabled only when you use one of
3139the commands above. (The command @code{until} can set and delete a
3140breakpoint of its own, but it does not change the state of your other
3141breakpoints; see @ref{Continuing and Stepping, ,Continuing and
3142stepping}.)
3143
6d2ebf8b 3144@node Conditions
c906108c
SS
3145@subsection Break conditions
3146@cindex conditional breakpoints
3147@cindex breakpoint conditions
3148
3149@c FIXME what is scope of break condition expr? Context where wanted?
5d161b24 3150@c in particular for a watchpoint?
c906108c
SS
3151The simplest sort of breakpoint breaks every time your program reaches a
3152specified place. You can also specify a @dfn{condition} for a
3153breakpoint. A condition is just a Boolean expression in your
3154programming language (@pxref{Expressions, ,Expressions}). A breakpoint with
3155a condition evaluates the expression each time your program reaches it,
3156and your program stops only if the condition is @emph{true}.
3157
3158This is the converse of using assertions for program validation; in that
3159situation, you want to stop when the assertion is violated---that is,
3160when the condition is false. In C, if you want to test an assertion expressed
3161by the condition @var{assert}, you should set the condition
3162@samp{! @var{assert}} on the appropriate breakpoint.
3163
3164Conditions are also accepted for watchpoints; you may not need them,
3165since a watchpoint is inspecting the value of an expression anyhow---but
3166it might be simpler, say, to just set a watchpoint on a variable name,
3167and specify a condition that tests whether the new value is an interesting
3168one.
3169
3170Break conditions can have side effects, and may even call functions in
3171your program. This can be useful, for example, to activate functions
3172that log program progress, or to use your own print functions to
3173format special data structures. The effects are completely predictable
3174unless there is another enabled breakpoint at the same address. (In
3175that case, @value{GDBN} might see the other breakpoint first and stop your
3176program without checking the condition of this one.) Note that
d4f3574e
SS
3177breakpoint commands are usually more convenient and flexible than break
3178conditions for the
c906108c
SS
3179purpose of performing side effects when a breakpoint is reached
3180(@pxref{Break Commands, ,Breakpoint command lists}).
3181
3182Break conditions can be specified when a breakpoint is set, by using
3183@samp{if} in the arguments to the @code{break} command. @xref{Set
3184Breaks, ,Setting breakpoints}. They can also be changed at any time
3185with the @code{condition} command.
53a5351d 3186
c906108c
SS
3187You can also use the @code{if} keyword with the @code{watch} command.
3188The @code{catch} command does not recognize the @code{if} keyword;
3189@code{condition} is the only way to impose a further condition on a
3190catchpoint.
c906108c
SS
3191
3192@table @code
3193@kindex condition
3194@item condition @var{bnum} @var{expression}
3195Specify @var{expression} as the break condition for breakpoint,
3196watchpoint, or catchpoint number @var{bnum}. After you set a condition,
3197breakpoint @var{bnum} stops your program only if the value of
3198@var{expression} is true (nonzero, in C). When you use
3199@code{condition}, @value{GDBN} checks @var{expression} immediately for
3200syntactic correctness, and to determine whether symbols in it have
d4f3574e
SS
3201referents in the context of your breakpoint. If @var{expression} uses
3202symbols not referenced in the context of the breakpoint, @value{GDBN}
3203prints an error message:
3204
474c8240 3205@smallexample
d4f3574e 3206No symbol "foo" in current context.
474c8240 3207@end smallexample
d4f3574e
SS
3208
3209@noindent
c906108c
SS
3210@value{GDBN} does
3211not actually evaluate @var{expression} at the time the @code{condition}
d4f3574e
SS
3212command (or a command that sets a breakpoint with a condition, like
3213@code{break if @dots{}}) is given, however. @xref{Expressions, ,Expressions}.
c906108c
SS
3214
3215@item condition @var{bnum}
3216Remove the condition from breakpoint number @var{bnum}. It becomes
3217an ordinary unconditional breakpoint.
3218@end table
3219
3220@cindex ignore count (of breakpoint)
3221A special case of a breakpoint condition is to stop only when the
3222breakpoint has been reached a certain number of times. This is so
3223useful that there is a special way to do it, using the @dfn{ignore
3224count} of the breakpoint. Every breakpoint has an ignore count, which
3225is an integer. Most of the time, the ignore count is zero, and
3226therefore has no effect. But if your program reaches a breakpoint whose
3227ignore count is positive, then instead of stopping, it just decrements
3228the ignore count by one and continues. As a result, if the ignore count
3229value is @var{n}, the breakpoint does not stop the next @var{n} times
3230your program reaches it.
3231
3232@table @code
3233@kindex ignore
3234@item ignore @var{bnum} @var{count}
3235Set the ignore count of breakpoint number @var{bnum} to @var{count}.
3236The next @var{count} times the breakpoint is reached, your program's
3237execution does not stop; other than to decrement the ignore count, @value{GDBN}
3238takes no action.
3239
3240To make the breakpoint stop the next time it is reached, specify
3241a count of zero.
3242
3243When you use @code{continue} to resume execution of your program from a
3244breakpoint, you can specify an ignore count directly as an argument to
3245@code{continue}, rather than using @code{ignore}. @xref{Continuing and
3246Stepping,,Continuing and stepping}.
3247
3248If a breakpoint has a positive ignore count and a condition, the
3249condition is not checked. Once the ignore count reaches zero,
3250@value{GDBN} resumes checking the condition.
3251
3252You could achieve the effect of the ignore count with a condition such
3253as @w{@samp{$foo-- <= 0}} using a debugger convenience variable that
3254is decremented each time. @xref{Convenience Vars, ,Convenience
3255variables}.
3256@end table
3257
3258Ignore counts apply to breakpoints, watchpoints, and catchpoints.
3259
3260
6d2ebf8b 3261@node Break Commands
c906108c
SS
3262@subsection Breakpoint command lists
3263
3264@cindex breakpoint commands
3265You can give any breakpoint (or watchpoint or catchpoint) a series of
3266commands to execute when your program stops due to that breakpoint. For
3267example, you might want to print the values of certain expressions, or
3268enable other breakpoints.
3269
3270@table @code
3271@kindex commands
3272@kindex end
3273@item commands @r{[}@var{bnum}@r{]}
3274@itemx @dots{} @var{command-list} @dots{}
3275@itemx end
3276Specify a list of commands for breakpoint number @var{bnum}. The commands
3277themselves appear on the following lines. Type a line containing just
3278@code{end} to terminate the commands.
3279
3280To remove all commands from a breakpoint, type @code{commands} and
3281follow it immediately with @code{end}; that is, give no commands.
3282
3283With no @var{bnum} argument, @code{commands} refers to the last
3284breakpoint, watchpoint, or catchpoint set (not to the breakpoint most
3285recently encountered).
3286@end table
3287
3288Pressing @key{RET} as a means of repeating the last @value{GDBN} command is
3289disabled within a @var{command-list}.
3290
3291You can use breakpoint commands to start your program up again. Simply
3292use the @code{continue} command, or @code{step}, or any other command
3293that resumes execution.
3294
3295Any other commands in the command list, after a command that resumes
3296execution, are ignored. This is because any time you resume execution
3297(even with a simple @code{next} or @code{step}), you may encounter
3298another breakpoint---which could have its own command list, leading to
3299ambiguities about which list to execute.
3300
3301@kindex silent
3302If the first command you specify in a command list is @code{silent}, the
3303usual message about stopping at a breakpoint is not printed. This may
3304be desirable for breakpoints that are to print a specific message and
3305then continue. If none of the remaining commands print anything, you
3306see no sign that the breakpoint was reached. @code{silent} is
3307meaningful only at the beginning of a breakpoint command list.
3308
3309The commands @code{echo}, @code{output}, and @code{printf} allow you to
3310print precisely controlled output, and are often useful in silent
3311breakpoints. @xref{Output, ,Commands for controlled output}.
3312
3313For example, here is how you could use breakpoint commands to print the
3314value of @code{x} at entry to @code{foo} whenever @code{x} is positive.
3315
474c8240 3316@smallexample
c906108c
SS
3317break foo if x>0
3318commands
3319silent
3320printf "x is %d\n",x
3321cont
3322end
474c8240 3323@end smallexample
c906108c
SS
3324
3325One application for breakpoint commands is to compensate for one bug so
3326you can test for another. Put a breakpoint just after the erroneous line
3327of code, give it a condition to detect the case in which something
3328erroneous has been done, and give it commands to assign correct values
3329to any variables that need them. End with the @code{continue} command
3330so that your program does not stop, and start with the @code{silent}
3331command so that no output is produced. Here is an example:
3332
474c8240 3333@smallexample
c906108c
SS
3334break 403
3335commands
3336silent
3337set x = y + 4
3338cont
3339end
474c8240 3340@end smallexample
c906108c 3341
6d2ebf8b 3342@node Breakpoint Menus
c906108c
SS
3343@subsection Breakpoint menus
3344@cindex overloading
3345@cindex symbol overloading
3346
b383017d 3347Some programming languages (notably C@t{++} and Objective-C) permit a
b37303ee 3348single function name
c906108c
SS
3349to be defined several times, for application in different contexts.
3350This is called @dfn{overloading}. When a function name is overloaded,
3351@samp{break @var{function}} is not enough to tell @value{GDBN} where you want
3352a breakpoint. If you realize this is a problem, you can use
3353something like @samp{break @var{function}(@var{types})} to specify which
3354particular version of the function you want. Otherwise, @value{GDBN} offers
3355you a menu of numbered choices for different possible breakpoints, and
3356waits for your selection with the prompt @samp{>}. The first two
3357options are always @samp{[0] cancel} and @samp{[1] all}. Typing @kbd{1}
3358sets a breakpoint at each definition of @var{function}, and typing
3359@kbd{0} aborts the @code{break} command without setting any new
3360breakpoints.
3361
3362For example, the following session excerpt shows an attempt to set a
3363breakpoint at the overloaded symbol @code{String::after}.
3364We choose three particular definitions of that function name:
3365
3366@c FIXME! This is likely to change to show arg type lists, at least
3367@smallexample
3368@group
3369(@value{GDBP}) b String::after
3370[0] cancel
3371[1] all
3372[2] file:String.cc; line number:867
3373[3] file:String.cc; line number:860
3374[4] file:String.cc; line number:875
3375[5] file:String.cc; line number:853
3376[6] file:String.cc; line number:846
3377[7] file:String.cc; line number:735
3378> 2 4 6
3379Breakpoint 1 at 0xb26c: file String.cc, line 867.
3380Breakpoint 2 at 0xb344: file String.cc, line 875.
3381Breakpoint 3 at 0xafcc: file String.cc, line 846.
3382Multiple breakpoints were set.
3383Use the "delete" command to delete unwanted
3384 breakpoints.
3385(@value{GDBP})
3386@end group
3387@end smallexample
c906108c
SS
3388
3389@c @ifclear BARETARGET
6d2ebf8b 3390@node Error in Breakpoints
d4f3574e 3391@subsection ``Cannot insert breakpoints''
c906108c
SS
3392@c
3393@c FIXME!! 14/6/95 Is there a real example of this? Let's use it.
3394@c
d4f3574e
SS
3395Under some operating systems, breakpoints cannot be used in a program if
3396any other process is running that program. In this situation,
5d161b24 3397attempting to run or continue a program with a breakpoint causes
d4f3574e
SS
3398@value{GDBN} to print an error message:
3399
474c8240 3400@smallexample
d4f3574e
SS
3401Cannot insert breakpoints.
3402The same program may be running in another process.
474c8240 3403@end smallexample
d4f3574e
SS
3404
3405When this happens, you have three ways to proceed:
3406
3407@enumerate
3408@item
3409Remove or disable the breakpoints, then continue.
3410
3411@item
5d161b24 3412Suspend @value{GDBN}, and copy the file containing your program to a new
d4f3574e 3413name. Resume @value{GDBN} and use the @code{exec-file} command to specify
5d161b24 3414that @value{GDBN} should run your program under that name.
d4f3574e
SS
3415Then start your program again.
3416
3417@item
3418Relink your program so that the text segment is nonsharable, using the
3419linker option @samp{-N}. The operating system limitation may not apply
3420to nonsharable executables.
3421@end enumerate
c906108c
SS
3422@c @end ifclear
3423
d4f3574e
SS
3424A similar message can be printed if you request too many active
3425hardware-assisted breakpoints and watchpoints:
3426
3427@c FIXME: the precise wording of this message may change; the relevant
3428@c source change is not committed yet (Sep 3, 1999).
3429@smallexample
3430Stopped; cannot insert breakpoints.
3431You may have requested too many hardware breakpoints and watchpoints.
3432@end smallexample
3433
3434@noindent
3435This message is printed when you attempt to resume the program, since
3436only then @value{GDBN} knows exactly how many hardware breakpoints and
3437watchpoints it needs to insert.
3438
3439When this message is printed, you need to disable or remove some of the
3440hardware-assisted breakpoints and watchpoints, and then continue.
3441
1485d690
KB
3442@node Breakpoint related warnings
3443@subsection ``Breakpoint address adjusted...''
3444@cindex breakpoint address adjusted
3445
3446Some processor architectures place constraints on the addresses at
3447which breakpoints may be placed. For architectures thus constrained,
3448@value{GDBN} will attempt to adjust the breakpoint's address to comply
3449with the constraints dictated by the architecture.
3450
3451One example of such an architecture is the Fujitsu FR-V. The FR-V is
3452a VLIW architecture in which a number of RISC-like instructions may be
3453bundled together for parallel execution. The FR-V architecture
3454constrains the location of a breakpoint instruction within such a
3455bundle to the instruction with the lowest address. @value{GDBN}
3456honors this constraint by adjusting a breakpoint's address to the
3457first in the bundle.
3458
3459It is not uncommon for optimized code to have bundles which contain
3460instructions from different source statements, thus it may happen that
3461a breakpoint's address will be adjusted from one source statement to
3462another. Since this adjustment may significantly alter @value{GDBN}'s
3463breakpoint related behavior from what the user expects, a warning is
3464printed when the breakpoint is first set and also when the breakpoint
3465is hit.
3466
3467A warning like the one below is printed when setting a breakpoint
3468that's been subject to address adjustment:
3469
3470@smallexample
3471warning: Breakpoint address adjusted from 0x00010414 to 0x00010410.
3472@end smallexample
3473
3474Such warnings are printed both for user settable and @value{GDBN}'s
3475internal breakpoints. If you see one of these warnings, you should
3476verify that a breakpoint set at the adjusted address will have the
3477desired affect. If not, the breakpoint in question may be removed and
b383017d 3478other breakpoints may be set which will have the desired behavior.
1485d690
KB
3479E.g., it may be sufficient to place the breakpoint at a later
3480instruction. A conditional breakpoint may also be useful in some
3481cases to prevent the breakpoint from triggering too often.
3482
3483@value{GDBN} will also issue a warning when stopping at one of these
3484adjusted breakpoints:
3485
3486@smallexample
3487warning: Breakpoint 1 address previously adjusted from 0x00010414
3488to 0x00010410.
3489@end smallexample
3490
3491When this warning is encountered, it may be too late to take remedial
3492action except in cases where the breakpoint is hit earlier or more
3493frequently than expected.
d4f3574e 3494
6d2ebf8b 3495@node Continuing and Stepping
c906108c
SS
3496@section Continuing and stepping
3497
3498@cindex stepping
3499@cindex continuing
3500@cindex resuming execution
3501@dfn{Continuing} means resuming program execution until your program
3502completes normally. In contrast, @dfn{stepping} means executing just
3503one more ``step'' of your program, where ``step'' may mean either one
3504line of source code, or one machine instruction (depending on what
7a292a7a
SS
3505particular command you use). Either when continuing or when stepping,
3506your program may stop even sooner, due to a breakpoint or a signal. (If
d4f3574e
SS
3507it stops due to a signal, you may want to use @code{handle}, or use
3508@samp{signal 0} to resume execution. @xref{Signals, ,Signals}.)
c906108c
SS
3509
3510@table @code
3511@kindex continue
41afff9a
EZ
3512@kindex c @r{(@code{continue})}
3513@kindex fg @r{(resume foreground execution)}
c906108c
SS
3514@item continue @r{[}@var{ignore-count}@r{]}
3515@itemx c @r{[}@var{ignore-count}@r{]}
3516@itemx fg @r{[}@var{ignore-count}@r{]}
3517Resume program execution, at the address where your program last stopped;
3518any breakpoints set at that address are bypassed. The optional argument
3519@var{ignore-count} allows you to specify a further number of times to
3520ignore a breakpoint at this location; its effect is like that of
3521@code{ignore} (@pxref{Conditions, ,Break conditions}).
3522
3523The argument @var{ignore-count} is meaningful only when your program
3524stopped due to a breakpoint. At other times, the argument to
3525@code{continue} is ignored.
3526
d4f3574e
SS
3527The synonyms @code{c} and @code{fg} (for @dfn{foreground}, as the
3528debugged program is deemed to be the foreground program) are provided
3529purely for convenience, and have exactly the same behavior as
3530@code{continue}.
c906108c
SS
3531@end table
3532
3533To resume execution at a different place, you can use @code{return}
3534(@pxref{Returning, ,Returning from a function}) to go back to the
3535calling function; or @code{jump} (@pxref{Jumping, ,Continuing at a
3536different address}) to go to an arbitrary location in your program.
3537
3538A typical technique for using stepping is to set a breakpoint
3539(@pxref{Breakpoints, ,Breakpoints; watchpoints; and catchpoints}) at the
3540beginning of the function or the section of your program where a problem
3541is believed to lie, run your program until it stops at that breakpoint,
3542and then step through the suspect area, examining the variables that are
3543interesting, until you see the problem happen.
3544
3545@table @code
3546@kindex step
41afff9a 3547@kindex s @r{(@code{step})}
c906108c
SS
3548@item step
3549Continue running your program until control reaches a different source
3550line, then stop it and return control to @value{GDBN}. This command is
3551abbreviated @code{s}.
3552
3553@quotation
3554@c "without debugging information" is imprecise; actually "without line
3555@c numbers in the debugging information". (gcc -g1 has debugging info but
3556@c not line numbers). But it seems complex to try to make that
3557@c distinction here.
3558@emph{Warning:} If you use the @code{step} command while control is
3559within a function that was compiled without debugging information,
3560execution proceeds until control reaches a function that does have
3561debugging information. Likewise, it will not step into a function which
3562is compiled without debugging information. To step through functions
3563without debugging information, use the @code{stepi} command, described
3564below.
3565@end quotation
3566
4a92d011
EZ
3567The @code{step} command only stops at the first instruction of a source
3568line. This prevents the multiple stops that could otherwise occur in
3569@code{switch} statements, @code{for} loops, etc. @code{step} continues
3570to stop if a function that has debugging information is called within
3571the line. In other words, @code{step} @emph{steps inside} any functions
3572called within the line.
c906108c 3573
d4f3574e
SS
3574Also, the @code{step} command only enters a function if there is line
3575number information for the function. Otherwise it acts like the
5d161b24 3576@code{next} command. This avoids problems when using @code{cc -gl}
c906108c 3577on MIPS machines. Previously, @code{step} entered subroutines if there
5d161b24 3578was any debugging information about the routine.
c906108c
SS
3579
3580@item step @var{count}
3581Continue running as in @code{step}, but do so @var{count} times. If a
7a292a7a
SS
3582breakpoint is reached, or a signal not related to stepping occurs before
3583@var{count} steps, stepping stops right away.
c906108c
SS
3584
3585@kindex next
41afff9a 3586@kindex n @r{(@code{next})}
c906108c
SS
3587@item next @r{[}@var{count}@r{]}
3588Continue to the next source line in the current (innermost) stack frame.
7a292a7a
SS
3589This is similar to @code{step}, but function calls that appear within
3590the line of code are executed without stopping. Execution stops when
3591control reaches a different line of code at the original stack level
3592that was executing when you gave the @code{next} command. This command
3593is abbreviated @code{n}.
c906108c
SS
3594
3595An argument @var{count} is a repeat count, as for @code{step}.
3596
3597
3598@c FIX ME!! Do we delete this, or is there a way it fits in with
3599@c the following paragraph? --- Vctoria
3600@c
3601@c @code{next} within a function that lacks debugging information acts like
3602@c @code{step}, but any function calls appearing within the code of the
3603@c function are executed without stopping.
3604
d4f3574e
SS
3605The @code{next} command only stops at the first instruction of a
3606source line. This prevents multiple stops that could otherwise occur in
4a92d011 3607@code{switch} statements, @code{for} loops, etc.
c906108c 3608
b90a5f51
CF
3609@kindex set step-mode
3610@item set step-mode
3611@cindex functions without line info, and stepping
3612@cindex stepping into functions with no line info
3613@itemx set step-mode on
4a92d011 3614The @code{set step-mode on} command causes the @code{step} command to
b90a5f51
CF
3615stop at the first instruction of a function which contains no debug line
3616information rather than stepping over it.
3617
4a92d011
EZ
3618This is useful in cases where you may be interested in inspecting the
3619machine instructions of a function which has no symbolic info and do not
3620want @value{GDBN} to automatically skip over this function.
b90a5f51
CF
3621
3622@item set step-mode off
4a92d011 3623Causes the @code{step} command to step over any functions which contains no
b90a5f51
CF
3624debug information. This is the default.
3625
9c16f35a
EZ
3626@item show step-mode
3627Show whether @value{GDBN} will stop in or step over functions without
3628source line debug information.
3629
c906108c
SS
3630@kindex finish
3631@item finish
3632Continue running until just after function in the selected stack frame
3633returns. Print the returned value (if any).
3634
3635Contrast this with the @code{return} command (@pxref{Returning,
3636,Returning from a function}).
3637
3638@kindex until
41afff9a 3639@kindex u @r{(@code{until})}
09d4efe1 3640@cindex run until specified location
c906108c
SS
3641@item until
3642@itemx u
3643Continue running until a source line past the current line, in the
3644current stack frame, is reached. This command is used to avoid single
3645stepping through a loop more than once. It is like the @code{next}
3646command, except that when @code{until} encounters a jump, it
3647automatically continues execution until the program counter is greater
3648than the address of the jump.
3649
3650This means that when you reach the end of a loop after single stepping
3651though it, @code{until} makes your program continue execution until it
3652exits the loop. In contrast, a @code{next} command at the end of a loop
3653simply steps back to the beginning of the loop, which forces you to step
3654through the next iteration.
3655
3656@code{until} always stops your program if it attempts to exit the current
3657stack frame.
3658
3659@code{until} may produce somewhat counterintuitive results if the order
3660of machine code does not match the order of the source lines. For
3661example, in the following excerpt from a debugging session, the @code{f}
3662(@code{frame}) command shows that execution is stopped at line
3663@code{206}; yet when we use @code{until}, we get to line @code{195}:
3664
474c8240 3665@smallexample
c906108c
SS
3666(@value{GDBP}) f
3667#0 main (argc=4, argv=0xf7fffae8) at m4.c:206
3668206 expand_input();
3669(@value{GDBP}) until
3670195 for ( ; argc > 0; NEXTARG) @{
474c8240 3671@end smallexample
c906108c
SS
3672
3673This happened because, for execution efficiency, the compiler had
3674generated code for the loop closure test at the end, rather than the
3675start, of the loop---even though the test in a C @code{for}-loop is
3676written before the body of the loop. The @code{until} command appeared
3677to step back to the beginning of the loop when it advanced to this
3678expression; however, it has not really gone to an earlier
3679statement---not in terms of the actual machine code.
3680
3681@code{until} with no argument works by means of single
3682instruction stepping, and hence is slower than @code{until} with an
3683argument.
3684
3685@item until @var{location}
3686@itemx u @var{location}
3687Continue running your program until either the specified location is
3688reached, or the current stack frame returns. @var{location} is any of
3689the forms of argument acceptable to @code{break} (@pxref{Set Breaks,
c60eb6f1
EZ
3690,Setting breakpoints}). This form of the command uses breakpoints, and
3691hence is quicker than @code{until} without an argument. The specified
3692location is actually reached only if it is in the current frame. This
3693implies that @code{until} can be used to skip over recursive function
3694invocations. For instance in the code below, if the current location is
3695line @code{96}, issuing @code{until 99} will execute the program up to
3696line @code{99} in the same invocation of factorial, i.e. after the inner
3697invocations have returned.
3698
3699@smallexample
370094 int factorial (int value)
370195 @{
370296 if (value > 1) @{
370397 value *= factorial (value - 1);
370498 @}
370599 return (value);
3706100 @}
3707@end smallexample
3708
3709
3710@kindex advance @var{location}
3711@itemx advance @var{location}
09d4efe1
EZ
3712Continue running the program up to the given @var{location}. An argument is
3713required, which should be of the same form as arguments for the @code{break}
c60eb6f1
EZ
3714command. Execution will also stop upon exit from the current stack
3715frame. This command is similar to @code{until}, but @code{advance} will
3716not skip over recursive function calls, and the target location doesn't
3717have to be in the same frame as the current one.
3718
c906108c
SS
3719
3720@kindex stepi
41afff9a 3721@kindex si @r{(@code{stepi})}
c906108c 3722@item stepi
96a2c332 3723@itemx stepi @var{arg}
c906108c
SS
3724@itemx si
3725Execute one machine instruction, then stop and return to the debugger.
3726
3727It is often useful to do @samp{display/i $pc} when stepping by machine
3728instructions. This makes @value{GDBN} automatically display the next
3729instruction to be executed, each time your program stops. @xref{Auto
3730Display,, Automatic display}.
3731
3732An argument is a repeat count, as in @code{step}.
3733
3734@need 750
3735@kindex nexti
41afff9a 3736@kindex ni @r{(@code{nexti})}
c906108c 3737@item nexti
96a2c332 3738@itemx nexti @var{arg}
c906108c
SS
3739@itemx ni
3740Execute one machine instruction, but if it is a function call,
3741proceed until the function returns.
3742
3743An argument is a repeat count, as in @code{next}.
3744@end table
3745
6d2ebf8b 3746@node Signals
c906108c
SS
3747@section Signals
3748@cindex signals
3749
3750A signal is an asynchronous event that can happen in a program. The
3751operating system defines the possible kinds of signals, and gives each
3752kind a name and a number. For example, in Unix @code{SIGINT} is the
d4f3574e 3753signal a program gets when you type an interrupt character (often @kbd{C-c});
c906108c
SS
3754@code{SIGSEGV} is the signal a program gets from referencing a place in
3755memory far away from all the areas in use; @code{SIGALRM} occurs when
3756the alarm clock timer goes off (which happens only if your program has
3757requested an alarm).
3758
3759@cindex fatal signals
3760Some signals, including @code{SIGALRM}, are a normal part of the
3761functioning of your program. Others, such as @code{SIGSEGV}, indicate
d4f3574e 3762errors; these signals are @dfn{fatal} (they kill your program immediately) if the
c906108c
SS
3763program has not specified in advance some other way to handle the signal.
3764@code{SIGINT} does not indicate an error in your program, but it is normally
3765fatal so it can carry out the purpose of the interrupt: to kill the program.
3766
3767@value{GDBN} has the ability to detect any occurrence of a signal in your
3768program. You can tell @value{GDBN} in advance what to do for each kind of
3769signal.
3770
3771@cindex handling signals
24f93129
EZ
3772Normally, @value{GDBN} is set up to let the non-erroneous signals like
3773@code{SIGALRM} be silently passed to your program
3774(so as not to interfere with their role in the program's functioning)
c906108c
SS
3775but to stop your program immediately whenever an error signal happens.
3776You can change these settings with the @code{handle} command.
3777
3778@table @code
3779@kindex info signals
09d4efe1 3780@kindex info handle
c906108c 3781@item info signals
96a2c332 3782@itemx info handle
c906108c
SS
3783Print a table of all the kinds of signals and how @value{GDBN} has been told to
3784handle each one. You can use this to see the signal numbers of all
3785the defined types of signals.
3786
d4f3574e 3787@code{info handle} is an alias for @code{info signals}.
c906108c
SS
3788
3789@kindex handle
3790@item handle @var{signal} @var{keywords}@dots{}
5ece1a18
EZ
3791Change the way @value{GDBN} handles signal @var{signal}. @var{signal}
3792can be the number of a signal or its name (with or without the
24f93129 3793@samp{SIG} at the beginning); a list of signal numbers of the form
5ece1a18
EZ
3794@samp{@var{low}-@var{high}}; or the word @samp{all}, meaning all the
3795known signals. The @var{keywords} say what change to make.
c906108c
SS
3796@end table
3797
3798@c @group
3799The keywords allowed by the @code{handle} command can be abbreviated.
3800Their full names are:
3801
3802@table @code
3803@item nostop
3804@value{GDBN} should not stop your program when this signal happens. It may
3805still print a message telling you that the signal has come in.
3806
3807@item stop
3808@value{GDBN} should stop your program when this signal happens. This implies
3809the @code{print} keyword as well.
3810
3811@item print
3812@value{GDBN} should print a message when this signal happens.
3813
3814@item noprint
3815@value{GDBN} should not mention the occurrence of the signal at all. This
3816implies the @code{nostop} keyword as well.
3817
3818@item pass
5ece1a18 3819@itemx noignore
c906108c
SS
3820@value{GDBN} should allow your program to see this signal; your program
3821can handle the signal, or else it may terminate if the signal is fatal
5ece1a18 3822and not handled. @code{pass} and @code{noignore} are synonyms.
c906108c
SS
3823
3824@item nopass
5ece1a18 3825@itemx ignore
c906108c 3826@value{GDBN} should not allow your program to see this signal.
5ece1a18 3827@code{nopass} and @code{ignore} are synonyms.
c906108c
SS
3828@end table
3829@c @end group
3830
d4f3574e
SS
3831When a signal stops your program, the signal is not visible to the
3832program until you
c906108c
SS
3833continue. Your program sees the signal then, if @code{pass} is in
3834effect for the signal in question @emph{at that time}. In other words,
3835after @value{GDBN} reports a signal, you can use the @code{handle}
3836command with @code{pass} or @code{nopass} to control whether your
3837program sees that signal when you continue.
3838
24f93129
EZ
3839The default is set to @code{nostop}, @code{noprint}, @code{pass} for
3840non-erroneous signals such as @code{SIGALRM}, @code{SIGWINCH} and
3841@code{SIGCHLD}, and to @code{stop}, @code{print}, @code{pass} for the
3842erroneous signals.
3843
c906108c
SS
3844You can also use the @code{signal} command to prevent your program from
3845seeing a signal, or cause it to see a signal it normally would not see,
3846or to give it any signal at any time. For example, if your program stopped
3847due to some sort of memory reference error, you might store correct
3848values into the erroneous variables and continue, hoping to see more
3849execution; but your program would probably terminate immediately as
3850a result of the fatal signal once it saw the signal. To prevent this,
3851you can continue with @samp{signal 0}. @xref{Signaling, ,Giving your
5d161b24 3852program a signal}.
c906108c 3853
6d2ebf8b 3854@node Thread Stops
c906108c
SS
3855@section Stopping and starting multi-thread programs
3856
3857When your program has multiple threads (@pxref{Threads,, Debugging
3858programs with multiple threads}), you can choose whether to set
3859breakpoints on all threads, or on a particular thread.
3860
3861@table @code
3862@cindex breakpoints and threads
3863@cindex thread breakpoints
3864@kindex break @dots{} thread @var{threadno}
3865@item break @var{linespec} thread @var{threadno}
3866@itemx break @var{linespec} thread @var{threadno} if @dots{}
3867@var{linespec} specifies source lines; there are several ways of
3868writing them, but the effect is always to specify some source line.
3869
3870Use the qualifier @samp{thread @var{threadno}} with a breakpoint command
3871to specify that you only want @value{GDBN} to stop the program when a
3872particular thread reaches this breakpoint. @var{threadno} is one of the
3873numeric thread identifiers assigned by @value{GDBN}, shown in the first
3874column of the @samp{info threads} display.
3875
3876If you do not specify @samp{thread @var{threadno}} when you set a
3877breakpoint, the breakpoint applies to @emph{all} threads of your
3878program.
3879
3880You can use the @code{thread} qualifier on conditional breakpoints as
3881well; in this case, place @samp{thread @var{threadno}} before the
3882breakpoint condition, like this:
3883
3884@smallexample
2df3850c 3885(@value{GDBP}) break frik.c:13 thread 28 if bartab > lim
c906108c
SS
3886@end smallexample
3887
3888@end table
3889
3890@cindex stopped threads
3891@cindex threads, stopped
3892Whenever your program stops under @value{GDBN} for any reason,
3893@emph{all} threads of execution stop, not just the current thread. This
3894allows you to examine the overall state of the program, including
3895switching between threads, without worrying that things may change
3896underfoot.
3897
36d86913
MC
3898@cindex thread breakpoints and system calls
3899@cindex system calls and thread breakpoints
3900@cindex premature return from system calls
3901There is an unfortunate side effect. If one thread stops for a
3902breakpoint, or for some other reason, and another thread is blocked in a
3903system call, then the system call may return prematurely. This is a
3904consequence of the interaction between multiple threads and the signals
3905that @value{GDBN} uses to implement breakpoints and other events that
3906stop execution.
3907
3908To handle this problem, your program should check the return value of
3909each system call and react appropriately. This is good programming
3910style anyways.
3911
3912For example, do not write code like this:
3913
3914@smallexample
3915 sleep (10);
3916@end smallexample
3917
3918The call to @code{sleep} will return early if a different thread stops
3919at a breakpoint or for some other reason.
3920
3921Instead, write this:
3922
3923@smallexample
3924 int unslept = 10;
3925 while (unslept > 0)
3926 unslept = sleep (unslept);
3927@end smallexample
3928
3929A system call is allowed to return early, so the system is still
3930conforming to its specification. But @value{GDBN} does cause your
3931multi-threaded program to behave differently than it would without
3932@value{GDBN}.
3933
3934Also, @value{GDBN} uses internal breakpoints in the thread library to
3935monitor certain events such as thread creation and thread destruction.
3936When such an event happens, a system call in another thread may return
3937prematurely, even though your program does not appear to stop.
3938
c906108c
SS
3939@cindex continuing threads
3940@cindex threads, continuing
3941Conversely, whenever you restart the program, @emph{all} threads start
3942executing. @emph{This is true even when single-stepping} with commands
5d161b24 3943like @code{step} or @code{next}.
c906108c
SS
3944
3945In particular, @value{GDBN} cannot single-step all threads in lockstep.
3946Since thread scheduling is up to your debugging target's operating
3947system (not controlled by @value{GDBN}), other threads may
3948execute more than one statement while the current thread completes a
3949single step. Moreover, in general other threads stop in the middle of a
3950statement, rather than at a clean statement boundary, when the program
3951stops.
3952
3953You might even find your program stopped in another thread after
3954continuing or even single-stepping. This happens whenever some other
3955thread runs into a breakpoint, a signal, or an exception before the
3956first thread completes whatever you requested.
3957
3958On some OSes, you can lock the OS scheduler and thus allow only a single
3959thread to run.
3960
3961@table @code
3962@item set scheduler-locking @var{mode}
9c16f35a
EZ
3963@cindex scheduler locking mode
3964@cindex lock scheduler
c906108c
SS
3965Set the scheduler locking mode. If it is @code{off}, then there is no
3966locking and any thread may run at any time. If @code{on}, then only the
3967current thread may run when the inferior is resumed. The @code{step}
3968mode optimizes for single-stepping. It stops other threads from
3969``seizing the prompt'' by preempting the current thread while you are
3970stepping. Other threads will only rarely (or never) get a chance to run
d4f3574e 3971when you step. They are more likely to run when you @samp{next} over a
c906108c 3972function call, and they are completely free to run when you use commands
d4f3574e 3973like @samp{continue}, @samp{until}, or @samp{finish}. However, unless another
c906108c 3974thread hits a breakpoint during its timeslice, they will never steal the
2df3850c 3975@value{GDBN} prompt away from the thread that you are debugging.
c906108c
SS
3976
3977@item show scheduler-locking
3978Display the current scheduler locking mode.
3979@end table
3980
c906108c 3981
6d2ebf8b 3982@node Stack
c906108c
SS
3983@chapter Examining the Stack
3984
3985When your program has stopped, the first thing you need to know is where it
3986stopped and how it got there.
3987
3988@cindex call stack
5d161b24
DB
3989Each time your program performs a function call, information about the call
3990is generated.
3991That information includes the location of the call in your program,
3992the arguments of the call,
c906108c 3993and the local variables of the function being called.
5d161b24 3994The information is saved in a block of data called a @dfn{stack frame}.
c906108c
SS
3995The stack frames are allocated in a region of memory called the @dfn{call
3996stack}.
3997
3998When your program stops, the @value{GDBN} commands for examining the
3999stack allow you to see all of this information.
4000
4001@cindex selected frame
4002One of the stack frames is @dfn{selected} by @value{GDBN} and many
4003@value{GDBN} commands refer implicitly to the selected frame. In
4004particular, whenever you ask @value{GDBN} for the value of a variable in
4005your program, the value is found in the selected frame. There are
4006special @value{GDBN} commands to select whichever frame you are
4007interested in. @xref{Selection, ,Selecting a frame}.
4008
4009When your program stops, @value{GDBN} automatically selects the
5d161b24 4010currently executing frame and describes it briefly, similar to the
c906108c
SS
4011@code{frame} command (@pxref{Frame Info, ,Information about a frame}).
4012
4013@menu
4014* Frames:: Stack frames
4015* Backtrace:: Backtraces
4016* Selection:: Selecting a frame
4017* Frame Info:: Information on a frame
c906108c
SS
4018
4019@end menu
4020
6d2ebf8b 4021@node Frames
c906108c
SS
4022@section Stack frames
4023
d4f3574e 4024@cindex frame, definition
c906108c
SS
4025@cindex stack frame
4026The call stack is divided up into contiguous pieces called @dfn{stack
4027frames}, or @dfn{frames} for short; each frame is the data associated
4028with one call to one function. The frame contains the arguments given
4029to the function, the function's local variables, and the address at
4030which the function is executing.
4031
4032@cindex initial frame
4033@cindex outermost frame
4034@cindex innermost frame
4035When your program is started, the stack has only one frame, that of the
4036function @code{main}. This is called the @dfn{initial} frame or the
4037@dfn{outermost} frame. Each time a function is called, a new frame is
4038made. Each time a function returns, the frame for that function invocation
4039is eliminated. If a function is recursive, there can be many frames for
4040the same function. The frame for the function in which execution is
4041actually occurring is called the @dfn{innermost} frame. This is the most
4042recently created of all the stack frames that still exist.
4043
4044@cindex frame pointer
4045Inside your program, stack frames are identified by their addresses. A
4046stack frame consists of many bytes, each of which has its own address; each
4047kind of computer has a convention for choosing one byte whose
4048address serves as the address of the frame. Usually this address is kept
4049in a register called the @dfn{frame pointer register} while execution is
4050going on in that frame.
4051
4052@cindex frame number
4053@value{GDBN} assigns numbers to all existing stack frames, starting with
4054zero for the innermost frame, one for the frame that called it,
4055and so on upward. These numbers do not really exist in your program;
4056they are assigned by @value{GDBN} to give you a way of designating stack
4057frames in @value{GDBN} commands.
4058
6d2ebf8b
SS
4059@c The -fomit-frame-pointer below perennially causes hbox overflow
4060@c underflow problems.
c906108c
SS
4061@cindex frameless execution
4062Some compilers provide a way to compile functions so that they operate
6d2ebf8b 4063without stack frames. (For example, the @value{GCC} option
474c8240 4064@smallexample
6d2ebf8b 4065@samp{-fomit-frame-pointer}
474c8240 4066@end smallexample
6d2ebf8b 4067generates functions without a frame.)
c906108c
SS
4068This is occasionally done with heavily used library functions to save
4069the frame setup time. @value{GDBN} has limited facilities for dealing
4070with these function invocations. If the innermost function invocation
4071has no stack frame, @value{GDBN} nevertheless regards it as though
4072it had a separate frame, which is numbered zero as usual, allowing
4073correct tracing of the function call chain. However, @value{GDBN} has
4074no provision for frameless functions elsewhere in the stack.
4075
4076@table @code
d4f3574e 4077@kindex frame@r{, command}
41afff9a 4078@cindex current stack frame
c906108c 4079@item frame @var{args}
5d161b24 4080The @code{frame} command allows you to move from one stack frame to another,
c906108c 4081and to print the stack frame you select. @var{args} may be either the
5d161b24
DB
4082address of the frame or the stack frame number. Without an argument,
4083@code{frame} prints the current stack frame.
c906108c
SS
4084
4085@kindex select-frame
41afff9a 4086@cindex selecting frame silently
c906108c
SS
4087@item select-frame
4088The @code{select-frame} command allows you to move from one stack frame
4089to another without printing the frame. This is the silent version of
4090@code{frame}.
4091@end table
4092
6d2ebf8b 4093@node Backtrace
c906108c
SS
4094@section Backtraces
4095
09d4efe1
EZ
4096@cindex traceback
4097@cindex call stack traces
c906108c
SS
4098A backtrace is a summary of how your program got where it is. It shows one
4099line per frame, for many frames, starting with the currently executing
4100frame (frame zero), followed by its caller (frame one), and on up the
4101stack.
4102
4103@table @code
4104@kindex backtrace
41afff9a 4105@kindex bt @r{(@code{backtrace})}
c906108c
SS
4106@item backtrace
4107@itemx bt
4108Print a backtrace of the entire stack: one line per frame for all
4109frames in the stack.
4110
4111You can stop the backtrace at any time by typing the system interrupt
4112character, normally @kbd{C-c}.
4113
4114@item backtrace @var{n}
4115@itemx bt @var{n}
4116Similar, but print only the innermost @var{n} frames.
4117
4118@item backtrace -@var{n}
4119@itemx bt -@var{n}
4120Similar, but print only the outermost @var{n} frames.
4121@end table
4122
4123@kindex where
4124@kindex info stack
c906108c
SS
4125The names @code{where} and @code{info stack} (abbreviated @code{info s})
4126are additional aliases for @code{backtrace}.
4127
4128Each line in the backtrace shows the frame number and the function name.
4129The program counter value is also shown---unless you use @code{set
4130print address off}. The backtrace also shows the source file name and
4131line number, as well as the arguments to the function. The program
4132counter value is omitted if it is at the beginning of the code for that
4133line number.
4134
4135Here is an example of a backtrace. It was made with the command
4136@samp{bt 3}, so it shows the innermost three frames.
4137
4138@smallexample
4139@group
5d161b24 4140#0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8)
c906108c
SS
4141 at builtin.c:993
4142#1 0x6e38 in expand_macro (sym=0x2b600) at macro.c:242
4143#2 0x6840 in expand_token (obs=0x0, t=177664, td=0xf7fffb08)
4144 at macro.c:71
4145(More stack frames follow...)
4146@end group
4147@end smallexample
4148
4149@noindent
4150The display for frame zero does not begin with a program counter
4151value, indicating that your program has stopped at the beginning of the
4152code for line @code{993} of @code{builtin.c}.
4153
a8f24a35
EZ
4154@cindex backtrace beyond @code{main} function
4155@cindex program entry point
4156@cindex startup code, and backtrace
25d29d70
AC
4157Most programs have a standard user entry point---a place where system
4158libraries and startup code transition into user code. For C this is
4159@code{main}. When @value{GDBN} finds the entry function in a backtrace
4160it will terminate the backtrace, to avoid tracing into highly
4161system-specific (and generally uninteresting) code.
4162
4163If you need to examine the startup code, or limit the number of levels
4164in a backtrace, you can change this behavior:
95f90d25
DJ
4165
4166@table @code
25d29d70
AC
4167@item set backtrace past-main
4168@itemx set backtrace past-main on
4644b6e3 4169@kindex set backtrace
25d29d70
AC
4170Backtraces will continue past the user entry point.
4171
4172@item set backtrace past-main off
95f90d25
DJ
4173Backtraces will stop when they encounter the user entry point. This is the
4174default.
4175
25d29d70 4176@item show backtrace past-main
4644b6e3 4177@kindex show backtrace
25d29d70
AC
4178Display the current user entry point backtrace policy.
4179
2315ffec
RC
4180@item set backtrace past-entry
4181@itemx set backtrace past-entry on
a8f24a35 4182Backtraces will continue past the internal entry point of an application.
2315ffec
RC
4183This entry point is encoded by the linker when the application is built,
4184and is likely before the user entry point @code{main} (or equivalent) is called.
4185
4186@item set backtrace past-entry off
4187Backtraces will stop when they encouter the internal entry point of an
4188application. This is the default.
4189
4190@item show backtrace past-entry
4191Display the current internal entry point backtrace policy.
4192
25d29d70
AC
4193@item set backtrace limit @var{n}
4194@itemx set backtrace limit 0
4195@cindex backtrace limit
4196Limit the backtrace to @var{n} levels. A value of zero means
4197unlimited.
95f90d25 4198
25d29d70
AC
4199@item show backtrace limit
4200Display the current limit on backtrace levels.
95f90d25
DJ
4201@end table
4202
6d2ebf8b 4203@node Selection
c906108c
SS
4204@section Selecting a frame
4205
4206Most commands for examining the stack and other data in your program work on
4207whichever stack frame is selected at the moment. Here are the commands for
4208selecting a stack frame; all of them finish by printing a brief description
4209of the stack frame just selected.
4210
4211@table @code
d4f3574e 4212@kindex frame@r{, selecting}
41afff9a 4213@kindex f @r{(@code{frame})}
c906108c
SS
4214@item frame @var{n}
4215@itemx f @var{n}
4216Select frame number @var{n}. Recall that frame zero is the innermost
4217(currently executing) frame, frame one is the frame that called the
4218innermost one, and so on. The highest-numbered frame is the one for
4219@code{main}.
4220
4221@item frame @var{addr}
4222@itemx f @var{addr}
4223Select the frame at address @var{addr}. This is useful mainly if the
4224chaining of stack frames has been damaged by a bug, making it
4225impossible for @value{GDBN} to assign numbers properly to all frames. In
4226addition, this can be useful when your program has multiple stacks and
4227switches between them.
4228
c906108c
SS
4229On the SPARC architecture, @code{frame} needs two addresses to
4230select an arbitrary frame: a frame pointer and a stack pointer.
4231
4232On the MIPS and Alpha architecture, it needs two addresses: a stack
4233pointer and a program counter.
4234
4235On the 29k architecture, it needs three addresses: a register stack
4236pointer, a program counter, and a memory stack pointer.
4237@c note to future updaters: this is conditioned on a flag
4238@c SETUP_ARBITRARY_FRAME in the tm-*.h files. The above is up to date
4239@c as of 27 Jan 1994.
c906108c
SS
4240
4241@kindex up
4242@item up @var{n}
4243Move @var{n} frames up the stack. For positive numbers @var{n}, this
4244advances toward the outermost frame, to higher frame numbers, to frames
4245that have existed longer. @var{n} defaults to one.
4246
4247@kindex down
41afff9a 4248@kindex do @r{(@code{down})}
c906108c
SS
4249@item down @var{n}
4250Move @var{n} frames down the stack. For positive numbers @var{n}, this
4251advances toward the innermost frame, to lower frame numbers, to frames
4252that were created more recently. @var{n} defaults to one. You may
4253abbreviate @code{down} as @code{do}.
4254@end table
4255
4256All of these commands end by printing two lines of output describing the
4257frame. The first line shows the frame number, the function name, the
4258arguments, and the source file and line number of execution in that
5d161b24 4259frame. The second line shows the text of that source line.
c906108c
SS
4260
4261@need 1000
4262For example:
4263
4264@smallexample
4265@group
4266(@value{GDBP}) up
4267#1 0x22f0 in main (argc=1, argv=0xf7fffbf4, env=0xf7fffbfc)
4268 at env.c:10
426910 read_input_file (argv[i]);
4270@end group
4271@end smallexample
4272
4273After such a printout, the @code{list} command with no arguments
4274prints ten lines centered on the point of execution in the frame.
87885426
FN
4275You can also edit the program at the point of execution with your favorite
4276editing program by typing @code{edit}.
4277@xref{List, ,Printing source lines},
4278for details.
c906108c
SS
4279
4280@table @code
4281@kindex down-silently
4282@kindex up-silently
4283@item up-silently @var{n}
4284@itemx down-silently @var{n}
4285These two commands are variants of @code{up} and @code{down},
4286respectively; they differ in that they do their work silently, without
4287causing display of the new frame. They are intended primarily for use
4288in @value{GDBN} command scripts, where the output might be unnecessary and
4289distracting.
4290@end table
4291
6d2ebf8b 4292@node Frame Info
c906108c
SS
4293@section Information about a frame
4294
4295There are several other commands to print information about the selected
4296stack frame.
4297
4298@table @code
4299@item frame
4300@itemx f
4301When used without any argument, this command does not change which
4302frame is selected, but prints a brief description of the currently
4303selected stack frame. It can be abbreviated @code{f}. With an
4304argument, this command is used to select a stack frame.
4305@xref{Selection, ,Selecting a frame}.
4306
4307@kindex info frame
41afff9a 4308@kindex info f @r{(@code{info frame})}
c906108c
SS
4309@item info frame
4310@itemx info f
4311This command prints a verbose description of the selected stack frame,
4312including:
4313
4314@itemize @bullet
5d161b24
DB
4315@item
4316the address of the frame
c906108c
SS
4317@item
4318the address of the next frame down (called by this frame)
4319@item
4320the address of the next frame up (caller of this frame)
4321@item
4322the language in which the source code corresponding to this frame is written
4323@item
4324the address of the frame's arguments
4325@item
d4f3574e
SS
4326the address of the frame's local variables
4327@item
c906108c
SS
4328the program counter saved in it (the address of execution in the caller frame)
4329@item
4330which registers were saved in the frame
4331@end itemize
4332
4333@noindent The verbose description is useful when
4334something has gone wrong that has made the stack format fail to fit
4335the usual conventions.
4336
4337@item info frame @var{addr}
4338@itemx info f @var{addr}
4339Print a verbose description of the frame at address @var{addr}, without
4340selecting that frame. The selected frame remains unchanged by this
4341command. This requires the same kind of address (more than one for some
4342architectures) that you specify in the @code{frame} command.
4343@xref{Selection, ,Selecting a frame}.
4344
4345@kindex info args
4346@item info args
4347Print the arguments of the selected frame, each on a separate line.
4348
4349@item info locals
4350@kindex info locals
4351Print the local variables of the selected frame, each on a separate
4352line. These are all variables (declared either static or automatic)
4353accessible at the point of execution of the selected frame.
4354
c906108c 4355@kindex info catch
d4f3574e
SS
4356@cindex catch exceptions, list active handlers
4357@cindex exception handlers, how to list
c906108c
SS
4358@item info catch
4359Print a list of all the exception handlers that are active in the
4360current stack frame at the current point of execution. To see other
4361exception handlers, visit the associated frame (using the @code{up},
4362@code{down}, or @code{frame} commands); then type @code{info catch}.
4363@xref{Set Catchpoints, , Setting catchpoints}.
53a5351d 4364
c906108c
SS
4365@end table
4366
c906108c 4367
6d2ebf8b 4368@node Source
c906108c
SS
4369@chapter Examining Source Files
4370
4371@value{GDBN} can print parts of your program's source, since the debugging
4372information recorded in the program tells @value{GDBN} what source files were
4373used to build it. When your program stops, @value{GDBN} spontaneously prints
4374the line where it stopped. Likewise, when you select a stack frame
4375(@pxref{Selection, ,Selecting a frame}), @value{GDBN} prints the line where
4376execution in that frame has stopped. You can print other portions of
4377source files by explicit command.
4378
7a292a7a 4379If you use @value{GDBN} through its @sc{gnu} Emacs interface, you may
d4f3574e 4380prefer to use Emacs facilities to view source; see @ref{Emacs, ,Using
7a292a7a 4381@value{GDBN} under @sc{gnu} Emacs}.
c906108c
SS
4382
4383@menu
4384* List:: Printing source lines
87885426 4385* Edit:: Editing source files
c906108c 4386* Search:: Searching source files
c906108c
SS
4387* Source Path:: Specifying source directories
4388* Machine Code:: Source and machine code
4389@end menu
4390
6d2ebf8b 4391@node List
c906108c
SS
4392@section Printing source lines
4393
4394@kindex list
41afff9a 4395@kindex l @r{(@code{list})}
c906108c 4396To print lines from a source file, use the @code{list} command
5d161b24 4397(abbreviated @code{l}). By default, ten lines are printed.
c906108c
SS
4398There are several ways to specify what part of the file you want to print.
4399
4400Here are the forms of the @code{list} command most commonly used:
4401
4402@table @code
4403@item list @var{linenum}
4404Print lines centered around line number @var{linenum} in the
4405current source file.
4406
4407@item list @var{function}
4408Print lines centered around the beginning of function
4409@var{function}.
4410
4411@item list
4412Print more lines. If the last lines printed were printed with a
4413@code{list} command, this prints lines following the last lines
4414printed; however, if the last line printed was a solitary line printed
4415as part of displaying a stack frame (@pxref{Stack, ,Examining the
4416Stack}), this prints lines centered around that line.
4417
4418@item list -
4419Print lines just before the lines last printed.
4420@end table
4421
9c16f35a 4422@cindex @code{list}, how many lines to display
c906108c
SS
4423By default, @value{GDBN} prints ten source lines with any of these forms of
4424the @code{list} command. You can change this using @code{set listsize}:
4425
4426@table @code
4427@kindex set listsize
4428@item set listsize @var{count}
4429Make the @code{list} command display @var{count} source lines (unless
4430the @code{list} argument explicitly specifies some other number).
4431
4432@kindex show listsize
4433@item show listsize
4434Display the number of lines that @code{list} prints.
4435@end table
4436
4437Repeating a @code{list} command with @key{RET} discards the argument,
4438so it is equivalent to typing just @code{list}. This is more useful
4439than listing the same lines again. An exception is made for an
4440argument of @samp{-}; that argument is preserved in repetition so that
4441each repetition moves up in the source file.
4442
4443@cindex linespec
4444In general, the @code{list} command expects you to supply zero, one or two
4445@dfn{linespecs}. Linespecs specify source lines; there are several ways
d4f3574e 4446of writing them, but the effect is always to specify some source line.
c906108c
SS
4447Here is a complete description of the possible arguments for @code{list}:
4448
4449@table @code
4450@item list @var{linespec}
4451Print lines centered around the line specified by @var{linespec}.
4452
4453@item list @var{first},@var{last}
4454Print lines from @var{first} to @var{last}. Both arguments are
4455linespecs.
4456
4457@item list ,@var{last}
4458Print lines ending with @var{last}.
4459
4460@item list @var{first},
4461Print lines starting with @var{first}.
4462
4463@item list +
4464Print lines just after the lines last printed.
4465
4466@item list -
4467Print lines just before the lines last printed.
4468
4469@item list
4470As described in the preceding table.
4471@end table
4472
4473Here are the ways of specifying a single source line---all the
4474kinds of linespec.
4475
4476@table @code
4477@item @var{number}
4478Specifies line @var{number} of the current source file.
4479When a @code{list} command has two linespecs, this refers to
4480the same source file as the first linespec.
4481
4482@item +@var{offset}
4483Specifies the line @var{offset} lines after the last line printed.
4484When used as the second linespec in a @code{list} command that has
4485two, this specifies the line @var{offset} lines down from the
4486first linespec.
4487
4488@item -@var{offset}
4489Specifies the line @var{offset} lines before the last line printed.
4490
4491@item @var{filename}:@var{number}
4492Specifies line @var{number} in the source file @var{filename}.
4493
4494@item @var{function}
4495Specifies the line that begins the body of the function @var{function}.
4496For example: in C, this is the line with the open brace.
4497
4498@item @var{filename}:@var{function}
4499Specifies the line of the open-brace that begins the body of the
4500function @var{function} in the file @var{filename}. You only need the
4501file name with a function name to avoid ambiguity when there are
4502identically named functions in different source files.
4503
4504@item *@var{address}
4505Specifies the line containing the program address @var{address}.
4506@var{address} may be any expression.
4507@end table
4508
87885426
FN
4509@node Edit
4510@section Editing source files
4511@cindex editing source files
4512
4513@kindex edit
4514@kindex e @r{(@code{edit})}
4515To edit the lines in a source file, use the @code{edit} command.
4516The editing program of your choice
4517is invoked with the current line set to
4518the active line in the program.
4519Alternatively, there are several ways to specify what part of the file you
4520want to print if you want to see other parts of the program.
4521
4522Here are the forms of the @code{edit} command most commonly used:
4523
4524@table @code
4525@item edit
4526Edit the current source file at the active line number in the program.
4527
4528@item edit @var{number}
4529Edit the current source file with @var{number} as the active line number.
4530
4531@item edit @var{function}
4532Edit the file containing @var{function} at the beginning of its definition.
4533
4534@item edit @var{filename}:@var{number}
4535Specifies line @var{number} in the source file @var{filename}.
4536
4537@item edit @var{filename}:@var{function}
4538Specifies the line that begins the body of the
4539function @var{function} in the file @var{filename}. You only need the
4540file name with a function name to avoid ambiguity when there are
4541identically named functions in different source files.
4542
4543@item edit *@var{address}
4544Specifies the line containing the program address @var{address}.
4545@var{address} may be any expression.
4546@end table
4547
4548@subsection Choosing your editor
4549You can customize @value{GDBN} to use any editor you want
4550@footnote{
4551The only restriction is that your editor (say @code{ex}), recognizes the
4552following command-line syntax:
10998722 4553@smallexample
87885426 4554ex +@var{number} file
10998722 4555@end smallexample
15387254
EZ
4556The optional numeric value +@var{number} specifies the number of the line in
4557the file where to start editing.}.
4558By default, it is @file{@value{EDITOR}}, but you can change this
10998722
AC
4559by setting the environment variable @code{EDITOR} before using
4560@value{GDBN}. For example, to configure @value{GDBN} to use the
4561@code{vi} editor, you could use these commands with the @code{sh} shell:
4562@smallexample
87885426
FN
4563EDITOR=/usr/bin/vi
4564export EDITOR
15387254 4565gdb @dots{}
10998722 4566@end smallexample
87885426 4567or in the @code{csh} shell,
10998722 4568@smallexample
87885426 4569setenv EDITOR /usr/bin/vi
15387254 4570gdb @dots{}
10998722 4571@end smallexample
87885426 4572
6d2ebf8b 4573@node Search
c906108c 4574@section Searching source files
15387254 4575@cindex searching source files
c906108c
SS
4576
4577There are two commands for searching through the current source file for a
4578regular expression.
4579
4580@table @code
4581@kindex search
4582@kindex forward-search
4583@item forward-search @var{regexp}
4584@itemx search @var{regexp}
4585The command @samp{forward-search @var{regexp}} checks each line,
4586starting with the one following the last line listed, for a match for
5d161b24 4587@var{regexp}. It lists the line that is found. You can use the
c906108c
SS
4588synonym @samp{search @var{regexp}} or abbreviate the command name as
4589@code{fo}.
4590
09d4efe1 4591@kindex reverse-search
c906108c
SS
4592@item reverse-search @var{regexp}
4593The command @samp{reverse-search @var{regexp}} checks each line, starting
4594with the one before the last line listed and going backward, for a match
4595for @var{regexp}. It lists the line that is found. You can abbreviate
4596this command as @code{rev}.
4597@end table
c906108c 4598
6d2ebf8b 4599@node Source Path
c906108c
SS
4600@section Specifying source directories
4601
4602@cindex source path
4603@cindex directories for source files
4604Executable programs sometimes do not record the directories of the source
4605files from which they were compiled, just the names. Even when they do,
4606the directories could be moved between the compilation and your debugging
4607session. @value{GDBN} has a list of directories to search for source files;
4608this is called the @dfn{source path}. Each time @value{GDBN} wants a source file,
4609it tries all the directories in the list, in the order they are present
0b66e38c
EZ
4610in the list, until it finds a file with the desired name.
4611
4612For example, suppose an executable references the file
4613@file{/usr/src/foo-1.0/lib/foo.c}, and our source path is
4614@file{/mnt/cross}. The file is first looked up literally; if this
4615fails, @file{/mnt/cross/usr/src/foo-1.0/lib/foo.c} is tried; if this
4616fails, @file{/mnt/cross/foo.c} is opened; if this fails, an error
4617message is printed. @value{GDBN} does not look up the parts of the
4618source file name, such as @file{/mnt/cross/src/foo-1.0/lib/foo.c}.
4619Likewise, the subdirectories of the source path are not searched: if
4620the source path is @file{/mnt/cross}, and the binary refers to
4621@file{foo.c}, @value{GDBN} would not find it under
4622@file{/mnt/cross/usr/src/foo-1.0/lib}.
4623
4624Plain file names, relative file names with leading directories, file
4625names containing dots, etc.@: are all treated as described above; for
4626instance, if the source path is @file{/mnt/cross}, and the source file
4627is recorded as @file{../lib/foo.c}, @value{GDBN} would first try
4628@file{../lib/foo.c}, then @file{/mnt/cross/../lib/foo.c}, and after
4629that---@file{/mnt/cross/foo.c}.
4630
4631Note that the executable search path is @emph{not} used to locate the
4632source files. Neither is the current working directory, unless it
4633happens to be in the source path.
c906108c
SS
4634
4635Whenever you reset or rearrange the source path, @value{GDBN} clears out
4636any information it has cached about where source files are found and where
4637each line is in the file.
4638
4639@kindex directory
4640@kindex dir
d4f3574e
SS
4641When you start @value{GDBN}, its source path includes only @samp{cdir}
4642and @samp{cwd}, in that order.
c906108c
SS
4643To add other directories, use the @code{directory} command.
4644
4645@table @code
4646@item directory @var{dirname} @dots{}
4647@item dir @var{dirname} @dots{}
4648Add directory @var{dirname} to the front of the source path. Several
d4f3574e
SS
4649directory names may be given to this command, separated by @samp{:}
4650(@samp{;} on MS-DOS and MS-Windows, where @samp{:} usually appears as
4651part of absolute file names) or
c906108c
SS
4652whitespace. You may specify a directory that is already in the source
4653path; this moves it forward, so @value{GDBN} searches it sooner.
4654
4655@kindex cdir
4656@kindex cwd
41afff9a
EZ
4657@vindex $cdir@r{, convenience variable}
4658@vindex $cwdr@r{, convenience variable}
c906108c
SS
4659@cindex compilation directory
4660@cindex current directory
4661@cindex working directory
4662@cindex directory, current
4663@cindex directory, compilation
4664You can use the string @samp{$cdir} to refer to the compilation
4665directory (if one is recorded), and @samp{$cwd} to refer to the current
4666working directory. @samp{$cwd} is not the same as @samp{.}---the former
4667tracks the current working directory as it changes during your @value{GDBN}
4668session, while the latter is immediately expanded to the current
4669directory at the time you add an entry to the source path.
4670
4671@item directory
4672Reset the source path to empty again. This requires confirmation.
4673
4674@c RET-repeat for @code{directory} is explicitly disabled, but since
4675@c repeating it would be a no-op we do not say that. (thanks to RMS)
4676
4677@item show directories
4678@kindex show directories
4679Print the source path: show which directories it contains.
4680@end table
4681
4682If your source path is cluttered with directories that are no longer of
4683interest, @value{GDBN} may sometimes cause confusion by finding the wrong
4684versions of source. You can correct the situation as follows:
4685
4686@enumerate
4687@item
4688Use @code{directory} with no argument to reset the source path to empty.
4689
4690@item
4691Use @code{directory} with suitable arguments to reinstall the
4692directories you want in the source path. You can add all the
4693directories in one command.
4694@end enumerate
4695
6d2ebf8b 4696@node Machine Code
c906108c 4697@section Source and machine code
15387254 4698@cindex source line and its code address
c906108c
SS
4699
4700You can use the command @code{info line} to map source lines to program
4701addresses (and vice versa), and the command @code{disassemble} to display
4702a range of addresses as machine instructions. When run under @sc{gnu} Emacs
d4f3574e 4703mode, the @code{info line} command causes the arrow to point to the
5d161b24 4704line specified. Also, @code{info line} prints addresses in symbolic form as
c906108c
SS
4705well as hex.
4706
4707@table @code
4708@kindex info line
4709@item info line @var{linespec}
4710Print the starting and ending addresses of the compiled code for
4711source line @var{linespec}. You can specify source lines in any of
4712the ways understood by the @code{list} command (@pxref{List, ,Printing
4713source lines}).
4714@end table
4715
4716For example, we can use @code{info line} to discover the location of
4717the object code for the first line of function
4718@code{m4_changequote}:
4719
d4f3574e
SS
4720@c FIXME: I think this example should also show the addresses in
4721@c symbolic form, as they usually would be displayed.
c906108c 4722@smallexample
96a2c332 4723(@value{GDBP}) info line m4_changequote
c906108c
SS
4724Line 895 of "builtin.c" starts at pc 0x634c and ends at 0x6350.
4725@end smallexample
4726
4727@noindent
15387254 4728@cindex code address and its source line
c906108c
SS
4729We can also inquire (using @code{*@var{addr}} as the form for
4730@var{linespec}) what source line covers a particular address:
4731@smallexample
4732(@value{GDBP}) info line *0x63ff
4733Line 926 of "builtin.c" starts at pc 0x63e4 and ends at 0x6404.
4734@end smallexample
4735
4736@cindex @code{$_} and @code{info line}
15387254 4737@cindex @code{x} command, default address
41afff9a 4738@kindex x@r{(examine), and} info line
c906108c
SS
4739After @code{info line}, the default address for the @code{x} command
4740is changed to the starting address of the line, so that @samp{x/i} is
4741sufficient to begin examining the machine code (@pxref{Memory,
4742,Examining memory}). Also, this address is saved as the value of the
4743convenience variable @code{$_} (@pxref{Convenience Vars, ,Convenience
4744variables}).
4745
4746@table @code
4747@kindex disassemble
4748@cindex assembly instructions
4749@cindex instructions, assembly
4750@cindex machine instructions
4751@cindex listing machine instructions
4752@item disassemble
4753This specialized command dumps a range of memory as machine
4754instructions. The default memory range is the function surrounding the
4755program counter of the selected frame. A single argument to this
4756command is a program counter value; @value{GDBN} dumps the function
4757surrounding this value. Two arguments specify a range of addresses
4758(first inclusive, second exclusive) to dump.
4759@end table
4760
c906108c
SS
4761The following example shows the disassembly of a range of addresses of
4762HP PA-RISC 2.0 code:
4763
4764@smallexample
4765(@value{GDBP}) disas 0x32c4 0x32e4
4766Dump of assembler code from 0x32c4 to 0x32e4:
47670x32c4 <main+204>: addil 0,dp
47680x32c8 <main+208>: ldw 0x22c(sr0,r1),r26
47690x32cc <main+212>: ldil 0x3000,r31
47700x32d0 <main+216>: ble 0x3f8(sr4,r31)
47710x32d4 <main+220>: ldo 0(r31),rp
47720x32d8 <main+224>: addil -0x800,dp
47730x32dc <main+228>: ldo 0x588(r1),r26
47740x32e0 <main+232>: ldil 0x3000,r31
4775End of assembler dump.
4776@end smallexample
c906108c
SS
4777
4778Some architectures have more than one commonly-used set of instruction
4779mnemonics or other syntax.
4780
4781@table @code
d4f3574e 4782@kindex set disassembly-flavor
d4f3574e
SS
4783@cindex Intel disassembly flavor
4784@cindex AT&T disassembly flavor
4785@item set disassembly-flavor @var{instruction-set}
c906108c
SS
4786Select the instruction set to use when disassembling the
4787program via the @code{disassemble} or @code{x/i} commands.
4788
4789Currently this command is only defined for the Intel x86 family. You
d4f3574e
SS
4790can set @var{instruction-set} to either @code{intel} or @code{att}.
4791The default is @code{att}, the AT&T flavor used by default by Unix
4792assemblers for x86-based targets.
9c16f35a
EZ
4793
4794@kindex show disassembly-flavor
4795@item show disassembly-flavor
4796Show the current setting of the disassembly flavor.
c906108c
SS
4797@end table
4798
4799
6d2ebf8b 4800@node Data
c906108c
SS
4801@chapter Examining Data
4802
4803@cindex printing data
4804@cindex examining data
4805@kindex print
4806@kindex inspect
4807@c "inspect" is not quite a synonym if you are using Epoch, which we do not
4808@c document because it is nonstandard... Under Epoch it displays in a
4809@c different window or something like that.
4810The usual way to examine data in your program is with the @code{print}
7a292a7a
SS
4811command (abbreviated @code{p}), or its synonym @code{inspect}. It
4812evaluates and prints the value of an expression of the language your
4813program is written in (@pxref{Languages, ,Using @value{GDBN} with
4814Different Languages}).
c906108c
SS
4815
4816@table @code
d4f3574e
SS
4817@item print @var{expr}
4818@itemx print /@var{f} @var{expr}
4819@var{expr} is an expression (in the source language). By default the
4820value of @var{expr} is printed in a format appropriate to its data type;
c906108c 4821you can choose a different format by specifying @samp{/@var{f}}, where
d4f3574e 4822@var{f} is a letter specifying the format; see @ref{Output Formats,,Output
c906108c
SS
4823formats}.
4824
4825@item print
4826@itemx print /@var{f}
15387254 4827@cindex reprint the last value
d4f3574e 4828If you omit @var{expr}, @value{GDBN} displays the last value again (from the
c906108c
SS
4829@dfn{value history}; @pxref{Value History, ,Value history}). This allows you to
4830conveniently inspect the same value in an alternative format.
4831@end table
4832
4833A more low-level way of examining data is with the @code{x} command.
4834It examines data in memory at a specified address and prints it in a
4835specified format. @xref{Memory, ,Examining memory}.
4836
7a292a7a 4837If you are interested in information about types, or about how the
d4f3574e
SS
4838fields of a struct or a class are declared, use the @code{ptype @var{exp}}
4839command rather than @code{print}. @xref{Symbols, ,Examining the Symbol
7a292a7a 4840Table}.
c906108c
SS
4841
4842@menu
4843* Expressions:: Expressions
4844* Variables:: Program variables
4845* Arrays:: Artificial arrays
4846* Output Formats:: Output formats
4847* Memory:: Examining memory
4848* Auto Display:: Automatic display
4849* Print Settings:: Print settings
4850* Value History:: Value history
4851* Convenience Vars:: Convenience variables
4852* Registers:: Registers
c906108c 4853* Floating Point Hardware:: Floating point hardware
53c69bd7 4854* Vector Unit:: Vector Unit
b383017d 4855* Auxiliary Vector:: Auxiliary data provided by operating system
29e57380 4856* Memory Region Attributes:: Memory region attributes
16d9dec6 4857* Dump/Restore Files:: Copy between memory and a file
384ee23f 4858* Core File Generation:: Cause a program dump its core
a0eb71c5
KB
4859* Character Sets:: Debugging programs that use a different
4860 character set than GDB does
09d4efe1 4861* Caching Remote Data:: Data caching for remote targets
c906108c
SS
4862@end menu
4863
6d2ebf8b 4864@node Expressions
c906108c
SS
4865@section Expressions
4866
4867@cindex expressions
4868@code{print} and many other @value{GDBN} commands accept an expression and
4869compute its value. Any kind of constant, variable or operator defined
4870by the programming language you are using is valid in an expression in
e2e0bcd1
JB
4871@value{GDBN}. This includes conditional expressions, function calls,
4872casts, and string constants. It also includes preprocessor macros, if
4873you compiled your program to include this information; see
4874@ref{Compilation}.
c906108c 4875
15387254 4876@cindex arrays in expressions
d4f3574e
SS
4877@value{GDBN} supports array constants in expressions input by
4878the user. The syntax is @{@var{element}, @var{element}@dots{}@}. For example,
5d161b24 4879you can use the command @code{print @{1, 2, 3@}} to build up an array in
d4f3574e 4880memory that is @code{malloc}ed in the target program.
c906108c 4881
c906108c
SS
4882Because C is so widespread, most of the expressions shown in examples in
4883this manual are in C. @xref{Languages, , Using @value{GDBN} with Different
4884Languages}, for information on how to use expressions in other
4885languages.
4886
4887In this section, we discuss operators that you can use in @value{GDBN}
4888expressions regardless of your programming language.
4889
15387254 4890@cindex casts, in expressions
c906108c
SS
4891Casts are supported in all languages, not just in C, because it is so
4892useful to cast a number into a pointer in order to examine a structure
4893at that address in memory.
4894@c FIXME: casts supported---Mod2 true?
c906108c
SS
4895
4896@value{GDBN} supports these operators, in addition to those common
4897to programming languages:
4898
4899@table @code
4900@item @@
4901@samp{@@} is a binary operator for treating parts of memory as arrays.
4902@xref{Arrays, ,Artificial arrays}, for more information.
4903
4904@item ::
4905@samp{::} allows you to specify a variable in terms of the file or
4906function where it is defined. @xref{Variables, ,Program variables}.
4907
4908@cindex @{@var{type}@}
4909@cindex type casting memory
4910@cindex memory, viewing as typed object
4911@cindex casts, to view memory
4912@item @{@var{type}@} @var{addr}
4913Refers to an object of type @var{type} stored at address @var{addr} in
4914memory. @var{addr} may be any expression whose value is an integer or
4915pointer (but parentheses are required around binary operators, just as in
4916a cast). This construct is allowed regardless of what kind of data is
4917normally supposed to reside at @var{addr}.
4918@end table
4919
6d2ebf8b 4920@node Variables
c906108c
SS
4921@section Program variables
4922
4923The most common kind of expression to use is the name of a variable
4924in your program.
4925
4926Variables in expressions are understood in the selected stack frame
4927(@pxref{Selection, ,Selecting a frame}); they must be either:
4928
4929@itemize @bullet
4930@item
4931global (or file-static)
4932@end itemize
4933
5d161b24 4934@noindent or
c906108c
SS
4935
4936@itemize @bullet
4937@item
4938visible according to the scope rules of the
4939programming language from the point of execution in that frame
5d161b24 4940@end itemize
c906108c
SS
4941
4942@noindent This means that in the function
4943
474c8240 4944@smallexample
c906108c
SS
4945foo (a)
4946 int a;
4947@{
4948 bar (a);
4949 @{
4950 int b = test ();
4951 bar (b);
4952 @}
4953@}
474c8240 4954@end smallexample
c906108c
SS
4955
4956@noindent
4957you can examine and use the variable @code{a} whenever your program is
4958executing within the function @code{foo}, but you can only use or
4959examine the variable @code{b} while your program is executing inside
4960the block where @code{b} is declared.
4961
4962@cindex variable name conflict
4963There is an exception: you can refer to a variable or function whose
4964scope is a single source file even if the current execution point is not
4965in this file. But it is possible to have more than one such variable or
4966function with the same name (in different source files). If that
4967happens, referring to that name has unpredictable effects. If you wish,
4968you can specify a static variable in a particular function or file,
15387254 4969using the colon-colon (@code{::}) notation:
c906108c 4970
d4f3574e 4971@cindex colon-colon, context for variables/functions
c906108c
SS
4972@iftex
4973@c info cannot cope with a :: index entry, but why deprive hard copy readers?
41afff9a 4974@cindex @code{::}, context for variables/functions
c906108c 4975@end iftex
474c8240 4976@smallexample
c906108c
SS
4977@var{file}::@var{variable}
4978@var{function}::@var{variable}
474c8240 4979@end smallexample
c906108c
SS
4980
4981@noindent
4982Here @var{file} or @var{function} is the name of the context for the
4983static @var{variable}. In the case of file names, you can use quotes to
4984make sure @value{GDBN} parses the file name as a single word---for example,
4985to print a global value of @code{x} defined in @file{f2.c}:
4986
474c8240 4987@smallexample
c906108c 4988(@value{GDBP}) p 'f2.c'::x
474c8240 4989@end smallexample
c906108c 4990
b37052ae 4991@cindex C@t{++} scope resolution
c906108c 4992This use of @samp{::} is very rarely in conflict with the very similar
b37052ae 4993use of the same notation in C@t{++}. @value{GDBN} also supports use of the C@t{++}
c906108c
SS
4994scope resolution operator in @value{GDBN} expressions.
4995@c FIXME: Um, so what happens in one of those rare cases where it's in
4996@c conflict?? --mew
c906108c
SS
4997
4998@cindex wrong values
4999@cindex variable values, wrong
15387254
EZ
5000@cindex function entry/exit, wrong values of variables
5001@cindex optimized code, wrong values of variables
c906108c
SS
5002@quotation
5003@emph{Warning:} Occasionally, a local variable may appear to have the
5004wrong value at certain points in a function---just after entry to a new
5005scope, and just before exit.
5006@end quotation
5007You may see this problem when you are stepping by machine instructions.
5008This is because, on most machines, it takes more than one instruction to
5009set up a stack frame (including local variable definitions); if you are
5010stepping by machine instructions, variables may appear to have the wrong
5011values until the stack frame is completely built. On exit, it usually
5012also takes more than one machine instruction to destroy a stack frame;
5013after you begin stepping through that group of instructions, local
5014variable definitions may be gone.
5015
5016This may also happen when the compiler does significant optimizations.
5017To be sure of always seeing accurate values, turn off all optimization
5018when compiling.
5019
d4f3574e
SS
5020@cindex ``No symbol "foo" in current context''
5021Another possible effect of compiler optimizations is to optimize
5022unused variables out of existence, or assign variables to registers (as
5023opposed to memory addresses). Depending on the support for such cases
5024offered by the debug info format used by the compiler, @value{GDBN}
5025might not be able to display values for such local variables. If that
5026happens, @value{GDBN} will print a message like this:
5027
474c8240 5028@smallexample
d4f3574e 5029No symbol "foo" in current context.
474c8240 5030@end smallexample
d4f3574e
SS
5031
5032To solve such problems, either recompile without optimizations, or use a
5033different debug info format, if the compiler supports several such
15387254 5034formats. For example, @value{NGCC}, the @sc{gnu} C/C@t{++} compiler,
0179ffac
DC
5035usually supports the @option{-gstabs+} option. @option{-gstabs+}
5036produces debug info in a format that is superior to formats such as
5037COFF. You may be able to use DWARF 2 (@option{-gdwarf-2}), which is also
5038an effective form for debug info. @xref{Debugging Options,,Options
5039for Debugging Your Program or @sc{gnu} CC, gcc.info, Using @sc{gnu} CC}.
15387254
EZ
5040@xref{C, , Debugging C++}, for more info about debug info formats
5041that are best suited to C@t{++} programs.
d4f3574e 5042
6d2ebf8b 5043@node Arrays
c906108c
SS
5044@section Artificial arrays
5045
5046@cindex artificial array
15387254 5047@cindex arrays
41afff9a 5048@kindex @@@r{, referencing memory as an array}
c906108c
SS
5049It is often useful to print out several successive objects of the
5050same type in memory; a section of an array, or an array of
5051dynamically determined size for which only a pointer exists in the
5052program.
5053
5054You can do this by referring to a contiguous span of memory as an
5055@dfn{artificial array}, using the binary operator @samp{@@}. The left
5056operand of @samp{@@} should be the first element of the desired array
5057and be an individual object. The right operand should be the desired length
5058of the array. The result is an array value whose elements are all of
5059the type of the left argument. The first element is actually the left
5060argument; the second element comes from bytes of memory immediately
5061following those that hold the first element, and so on. Here is an
5062example. If a program says
5063
474c8240 5064@smallexample
c906108c 5065int *array = (int *) malloc (len * sizeof (int));
474c8240 5066@end smallexample
c906108c
SS
5067
5068@noindent
5069you can print the contents of @code{array} with
5070
474c8240 5071@smallexample
c906108c 5072p *array@@len
474c8240 5073@end smallexample
c906108c
SS
5074
5075The left operand of @samp{@@} must reside in memory. Array values made
5076with @samp{@@} in this way behave just like other arrays in terms of
5077subscripting, and are coerced to pointers when used in expressions.
5078Artificial arrays most often appear in expressions via the value history
5079(@pxref{Value History, ,Value history}), after printing one out.
5080
5081Another way to create an artificial array is to use a cast.
5082This re-interprets a value as if it were an array.
5083The value need not be in memory:
474c8240 5084@smallexample
c906108c
SS
5085(@value{GDBP}) p/x (short[2])0x12345678
5086$1 = @{0x1234, 0x5678@}
474c8240 5087@end smallexample
c906108c
SS
5088
5089As a convenience, if you leave the array length out (as in
c3f6f71d 5090@samp{(@var{type}[])@var{value}}) @value{GDBN} calculates the size to fill
c906108c 5091the value (as @samp{sizeof(@var{value})/sizeof(@var{type})}:
474c8240 5092@smallexample
c906108c
SS
5093(@value{GDBP}) p/x (short[])0x12345678
5094$2 = @{0x1234, 0x5678@}
474c8240 5095@end smallexample
c906108c
SS
5096
5097Sometimes the artificial array mechanism is not quite enough; in
5098moderately complex data structures, the elements of interest may not
5099actually be adjacent---for example, if you are interested in the values
5100of pointers in an array. One useful work-around in this situation is
5101to use a convenience variable (@pxref{Convenience Vars, ,Convenience
5102variables}) as a counter in an expression that prints the first
5103interesting value, and then repeat that expression via @key{RET}. For
5104instance, suppose you have an array @code{dtab} of pointers to
5105structures, and you are interested in the values of a field @code{fv}
5106in each structure. Here is an example of what you might type:
5107
474c8240 5108@smallexample
c906108c
SS
5109set $i = 0
5110p dtab[$i++]->fv
5111@key{RET}
5112@key{RET}
5113@dots{}
474c8240 5114@end smallexample
c906108c 5115
6d2ebf8b 5116@node Output Formats
c906108c
SS
5117@section Output formats
5118
5119@cindex formatted output
5120@cindex output formats
5121By default, @value{GDBN} prints a value according to its data type. Sometimes
5122this is not what you want. For example, you might want to print a number
5123in hex, or a pointer in decimal. Or you might want to view data in memory
5124at a certain address as a character string or as an instruction. To do
5125these things, specify an @dfn{output format} when you print a value.
5126
5127The simplest use of output formats is to say how to print a value
5128already computed. This is done by starting the arguments of the
5129@code{print} command with a slash and a format letter. The format
5130letters supported are:
5131
5132@table @code
5133@item x
5134Regard the bits of the value as an integer, and print the integer in
5135hexadecimal.
5136
5137@item d
5138Print as integer in signed decimal.
5139
5140@item u
5141Print as integer in unsigned decimal.
5142
5143@item o
5144Print as integer in octal.
5145
5146@item t
5147Print as integer in binary. The letter @samp{t} stands for ``two''.
5148@footnote{@samp{b} cannot be used because these format letters are also
5149used with the @code{x} command, where @samp{b} stands for ``byte'';
d4f3574e 5150see @ref{Memory,,Examining memory}.}
c906108c
SS
5151
5152@item a
5153@cindex unknown address, locating
3d67e040 5154@cindex locate address
c906108c
SS
5155Print as an address, both absolute in hexadecimal and as an offset from
5156the nearest preceding symbol. You can use this format used to discover
5157where (in what function) an unknown address is located:
5158
474c8240 5159@smallexample
c906108c
SS
5160(@value{GDBP}) p/a 0x54320
5161$3 = 0x54320 <_initialize_vx+396>
474c8240 5162@end smallexample
c906108c 5163
3d67e040
EZ
5164@noindent
5165The command @code{info symbol 0x54320} yields similar results.
5166@xref{Symbols, info symbol}.
5167
c906108c
SS
5168@item c
5169Regard as an integer and print it as a character constant.
5170
5171@item f
5172Regard the bits of the value as a floating point number and print
5173using typical floating point syntax.
5174@end table
5175
5176For example, to print the program counter in hex (@pxref{Registers}), type
5177
474c8240 5178@smallexample
c906108c 5179p/x $pc
474c8240 5180@end smallexample
c906108c
SS
5181
5182@noindent
5183Note that no space is required before the slash; this is because command
5184names in @value{GDBN} cannot contain a slash.
5185
5186To reprint the last value in the value history with a different format,
5187you can use the @code{print} command with just a format and no
5188expression. For example, @samp{p/x} reprints the last value in hex.
5189
6d2ebf8b 5190@node Memory
c906108c
SS
5191@section Examining memory
5192
5193You can use the command @code{x} (for ``examine'') to examine memory in
5194any of several formats, independently of your program's data types.
5195
5196@cindex examining memory
5197@table @code
41afff9a 5198@kindex x @r{(examine memory)}
c906108c
SS
5199@item x/@var{nfu} @var{addr}
5200@itemx x @var{addr}
5201@itemx x
5202Use the @code{x} command to examine memory.
5203@end table
5204
5205@var{n}, @var{f}, and @var{u} are all optional parameters that specify how
5206much memory to display and how to format it; @var{addr} is an
5207expression giving the address where you want to start displaying memory.
5208If you use defaults for @var{nfu}, you need not type the slash @samp{/}.
5209Several commands set convenient defaults for @var{addr}.
5210
5211@table @r
5212@item @var{n}, the repeat count
5213The repeat count is a decimal integer; the default is 1. It specifies
5214how much memory (counting by units @var{u}) to display.
5215@c This really is **decimal**; unaffected by 'set radix' as of GDB
5216@c 4.1.2.
5217
5218@item @var{f}, the display format
5219The display format is one of the formats used by @code{print},
5220@samp{s} (null-terminated string), or @samp{i} (machine instruction).
5221The default is @samp{x} (hexadecimal) initially.
5222The default changes each time you use either @code{x} or @code{print}.
5223
5224@item @var{u}, the unit size
5225The unit size is any of
5226
5227@table @code
5228@item b
5229Bytes.
5230@item h
5231Halfwords (two bytes).
5232@item w
5233Words (four bytes). This is the initial default.
5234@item g
5235Giant words (eight bytes).
5236@end table
5237
5238Each time you specify a unit size with @code{x}, that size becomes the
5239default unit the next time you use @code{x}. (For the @samp{s} and
5240@samp{i} formats, the unit size is ignored and is normally not written.)
5241
5242@item @var{addr}, starting display address
5243@var{addr} is the address where you want @value{GDBN} to begin displaying
5244memory. The expression need not have a pointer value (though it may);
5245it is always interpreted as an integer address of a byte of memory.
5246@xref{Expressions, ,Expressions}, for more information on expressions. The default for
5247@var{addr} is usually just after the last address examined---but several
5248other commands also set the default address: @code{info breakpoints} (to
5249the address of the last breakpoint listed), @code{info line} (to the
5250starting address of a line), and @code{print} (if you use it to display
5251a value from memory).
5252@end table
5253
5254For example, @samp{x/3uh 0x54320} is a request to display three halfwords
5255(@code{h}) of memory, formatted as unsigned decimal integers (@samp{u}),
5256starting at address @code{0x54320}. @samp{x/4xw $sp} prints the four
5257words (@samp{w}) of memory above the stack pointer (here, @samp{$sp};
d4f3574e 5258@pxref{Registers, ,Registers}) in hexadecimal (@samp{x}).
c906108c
SS
5259
5260Since the letters indicating unit sizes are all distinct from the
5261letters specifying output formats, you do not have to remember whether
5262unit size or format comes first; either order works. The output
5263specifications @samp{4xw} and @samp{4wx} mean exactly the same thing.
5264(However, the count @var{n} must come first; @samp{wx4} does not work.)
5265
5266Even though the unit size @var{u} is ignored for the formats @samp{s}
5267and @samp{i}, you might still want to use a count @var{n}; for example,
5268@samp{3i} specifies that you want to see three machine instructions,
5269including any operands. The command @code{disassemble} gives an
d4f3574e 5270alternative way of inspecting machine instructions; see @ref{Machine
c906108c
SS
5271Code,,Source and machine code}.
5272
5273All the defaults for the arguments to @code{x} are designed to make it
5274easy to continue scanning memory with minimal specifications each time
5275you use @code{x}. For example, after you have inspected three machine
5276instructions with @samp{x/3i @var{addr}}, you can inspect the next seven
5277with just @samp{x/7}. If you use @key{RET} to repeat the @code{x} command,
5278the repeat count @var{n} is used again; the other arguments default as
5279for successive uses of @code{x}.
5280
5281@cindex @code{$_}, @code{$__}, and value history
5282The addresses and contents printed by the @code{x} command are not saved
5283in the value history because there is often too much of them and they
5284would get in the way. Instead, @value{GDBN} makes these values available for
5285subsequent use in expressions as values of the convenience variables
5286@code{$_} and @code{$__}. After an @code{x} command, the last address
5287examined is available for use in expressions in the convenience variable
5288@code{$_}. The contents of that address, as examined, are available in
5289the convenience variable @code{$__}.
5290
5291If the @code{x} command has a repeat count, the address and contents saved
5292are from the last memory unit printed; this is not the same as the last
5293address printed if several units were printed on the last line of output.
5294
09d4efe1
EZ
5295@cindex remote memory comparison
5296@cindex verify remote memory image
5297When you are debugging a program running on a remote target machine
5298(@pxref{Remote}), you may wish to verify the program's image in the
5299remote machine's memory against the executable file you downloaded to
5300the target. The @code{compare-sections} command is provided for such
5301situations.
5302
5303@table @code
5304@kindex compare-sections
5305@item compare-sections @r{[}@var{section-name}@r{]}
5306Compare the data of a loadable section @var{section-name} in the
5307executable file of the program being debugged with the same section in
5308the remote machine's memory, and report any mismatches. With no
5309arguments, compares all loadable sections. This command's
5310availability depends on the target's support for the @code{"qCRC"}
5311remote request.
5312@end table
5313
6d2ebf8b 5314@node Auto Display
c906108c
SS
5315@section Automatic display
5316@cindex automatic display
5317@cindex display of expressions
5318
5319If you find that you want to print the value of an expression frequently
5320(to see how it changes), you might want to add it to the @dfn{automatic
5321display list} so that @value{GDBN} prints its value each time your program stops.
5322Each expression added to the list is given a number to identify it;
5323to remove an expression from the list, you specify that number.
5324The automatic display looks like this:
5325
474c8240 5326@smallexample
c906108c
SS
53272: foo = 38
53283: bar[5] = (struct hack *) 0x3804
474c8240 5329@end smallexample
c906108c
SS
5330
5331@noindent
5332This display shows item numbers, expressions and their current values. As with
5333displays you request manually using @code{x} or @code{print}, you can
5334specify the output format you prefer; in fact, @code{display} decides
5335whether to use @code{print} or @code{x} depending on how elaborate your
5336format specification is---it uses @code{x} if you specify a unit size,
5337or one of the two formats (@samp{i} and @samp{s}) that are only
5338supported by @code{x}; otherwise it uses @code{print}.
5339
5340@table @code
5341@kindex display
d4f3574e
SS
5342@item display @var{expr}
5343Add the expression @var{expr} to the list of expressions to display
c906108c
SS
5344each time your program stops. @xref{Expressions, ,Expressions}.
5345
5346@code{display} does not repeat if you press @key{RET} again after using it.
5347
d4f3574e 5348@item display/@var{fmt} @var{expr}
c906108c 5349For @var{fmt} specifying only a display format and not a size or
d4f3574e 5350count, add the expression @var{expr} to the auto-display list but
c906108c
SS
5351arrange to display it each time in the specified format @var{fmt}.
5352@xref{Output Formats,,Output formats}.
5353
5354@item display/@var{fmt} @var{addr}
5355For @var{fmt} @samp{i} or @samp{s}, or including a unit-size or a
5356number of units, add the expression @var{addr} as a memory address to
5357be examined each time your program stops. Examining means in effect
5358doing @samp{x/@var{fmt} @var{addr}}. @xref{Memory, ,Examining memory}.
5359@end table
5360
5361For example, @samp{display/i $pc} can be helpful, to see the machine
5362instruction about to be executed each time execution stops (@samp{$pc}
d4f3574e 5363is a common name for the program counter; @pxref{Registers, ,Registers}).
c906108c
SS
5364
5365@table @code
5366@kindex delete display
5367@kindex undisplay
5368@item undisplay @var{dnums}@dots{}
5369@itemx delete display @var{dnums}@dots{}
5370Remove item numbers @var{dnums} from the list of expressions to display.
5371
5372@code{undisplay} does not repeat if you press @key{RET} after using it.
5373(Otherwise you would just get the error @samp{No display number @dots{}}.)
5374
5375@kindex disable display
5376@item disable display @var{dnums}@dots{}
5377Disable the display of item numbers @var{dnums}. A disabled display
5378item is not printed automatically, but is not forgotten. It may be
5379enabled again later.
5380
5381@kindex enable display
5382@item enable display @var{dnums}@dots{}
5383Enable display of item numbers @var{dnums}. It becomes effective once
5384again in auto display of its expression, until you specify otherwise.
5385
5386@item display
5387Display the current values of the expressions on the list, just as is
5388done when your program stops.
5389
5390@kindex info display
5391@item info display
5392Print the list of expressions previously set up to display
5393automatically, each one with its item number, but without showing the
5394values. This includes disabled expressions, which are marked as such.
5395It also includes expressions which would not be displayed right now
5396because they refer to automatic variables not currently available.
5397@end table
5398
15387254 5399@cindex display disabled out of scope
c906108c
SS
5400If a display expression refers to local variables, then it does not make
5401sense outside the lexical context for which it was set up. Such an
5402expression is disabled when execution enters a context where one of its
5403variables is not defined. For example, if you give the command
5404@code{display last_char} while inside a function with an argument
5405@code{last_char}, @value{GDBN} displays this argument while your program
5406continues to stop inside that function. When it stops elsewhere---where
5407there is no variable @code{last_char}---the display is disabled
5408automatically. The next time your program stops where @code{last_char}
5409is meaningful, you can enable the display expression once again.
5410
6d2ebf8b 5411@node Print Settings
c906108c
SS
5412@section Print settings
5413
5414@cindex format options
5415@cindex print settings
5416@value{GDBN} provides the following ways to control how arrays, structures,
5417and symbols are printed.
5418
5419@noindent
5420These settings are useful for debugging programs in any language:
5421
5422@table @code
4644b6e3 5423@kindex set print
c906108c
SS
5424@item set print address
5425@itemx set print address on
4644b6e3 5426@cindex print/don't print memory addresses
c906108c
SS
5427@value{GDBN} prints memory addresses showing the location of stack
5428traces, structure values, pointer values, breakpoints, and so forth,
5429even when it also displays the contents of those addresses. The default
5430is @code{on}. For example, this is what a stack frame display looks like with
5431@code{set print address on}:
5432
5433@smallexample
5434@group
5435(@value{GDBP}) f
5436#0 set_quotes (lq=0x34c78 "<<", rq=0x34c88 ">>")
5437 at input.c:530
5438530 if (lquote != def_lquote)
5439@end group
5440@end smallexample
5441
5442@item set print address off
5443Do not print addresses when displaying their contents. For example,
5444this is the same stack frame displayed with @code{set print address off}:
5445
5446@smallexample
5447@group
5448(@value{GDBP}) set print addr off
5449(@value{GDBP}) f
5450#0 set_quotes (lq="<<", rq=">>") at input.c:530
5451530 if (lquote != def_lquote)
5452@end group
5453@end smallexample
5454
5455You can use @samp{set print address off} to eliminate all machine
5456dependent displays from the @value{GDBN} interface. For example, with
5457@code{print address off}, you should get the same text for backtraces on
5458all machines---whether or not they involve pointer arguments.
5459
4644b6e3 5460@kindex show print
c906108c
SS
5461@item show print address
5462Show whether or not addresses are to be printed.
5463@end table
5464
5465When @value{GDBN} prints a symbolic address, it normally prints the
5466closest earlier symbol plus an offset. If that symbol does not uniquely
5467identify the address (for example, it is a name whose scope is a single
5468source file), you may need to clarify. One way to do this is with
5469@code{info line}, for example @samp{info line *0x4537}. Alternately,
5470you can set @value{GDBN} to print the source file and line number when
5471it prints a symbolic address:
5472
5473@table @code
c906108c 5474@item set print symbol-filename on
9c16f35a
EZ
5475@cindex source file and line of a symbol
5476@cindex symbol, source file and line
c906108c
SS
5477Tell @value{GDBN} to print the source file name and line number of a
5478symbol in the symbolic form of an address.
5479
5480@item set print symbol-filename off
5481Do not print source file name and line number of a symbol. This is the
5482default.
5483
c906108c
SS
5484@item show print symbol-filename
5485Show whether or not @value{GDBN} will print the source file name and
5486line number of a symbol in the symbolic form of an address.
5487@end table
5488
5489Another situation where it is helpful to show symbol filenames and line
5490numbers is when disassembling code; @value{GDBN} shows you the line
5491number and source file that corresponds to each instruction.
5492
5493Also, you may wish to see the symbolic form only if the address being
5494printed is reasonably close to the closest earlier symbol:
5495
5496@table @code
c906108c 5497@item set print max-symbolic-offset @var{max-offset}
4644b6e3 5498@cindex maximum value for offset of closest symbol
c906108c
SS
5499Tell @value{GDBN} to only display the symbolic form of an address if the
5500offset between the closest earlier symbol and the address is less than
5d161b24 5501@var{max-offset}. The default is 0, which tells @value{GDBN}
c906108c
SS
5502to always print the symbolic form of an address if any symbol precedes it.
5503
c906108c
SS
5504@item show print max-symbolic-offset
5505Ask how large the maximum offset is that @value{GDBN} prints in a
5506symbolic address.
5507@end table
5508
5509@cindex wild pointer, interpreting
5510@cindex pointer, finding referent
5511If you have a pointer and you are not sure where it points, try
5512@samp{set print symbol-filename on}. Then you can determine the name
5513and source file location of the variable where it points, using
5514@samp{p/a @var{pointer}}. This interprets the address in symbolic form.
5515For example, here @value{GDBN} shows that a variable @code{ptt} points
5516at another variable @code{t}, defined in @file{hi2.c}:
5517
474c8240 5518@smallexample
c906108c
SS
5519(@value{GDBP}) set print symbol-filename on
5520(@value{GDBP}) p/a ptt
5521$4 = 0xe008 <t in hi2.c>
474c8240 5522@end smallexample
c906108c
SS
5523
5524@quotation
5525@emph{Warning:} For pointers that point to a local variable, @samp{p/a}
5526does not show the symbol name and filename of the referent, even with
5527the appropriate @code{set print} options turned on.
5528@end quotation
5529
5530Other settings control how different kinds of objects are printed:
5531
5532@table @code
c906108c
SS
5533@item set print array
5534@itemx set print array on
4644b6e3 5535@cindex pretty print arrays
c906108c
SS
5536Pretty print arrays. This format is more convenient to read,
5537but uses more space. The default is off.
5538
5539@item set print array off
5540Return to compressed format for arrays.
5541
c906108c
SS
5542@item show print array
5543Show whether compressed or pretty format is selected for displaying
5544arrays.
5545
c906108c 5546@item set print elements @var{number-of-elements}
4644b6e3 5547@cindex number of array elements to print
9c16f35a 5548@cindex limit on number of printed array elements
c906108c
SS
5549Set a limit on how many elements of an array @value{GDBN} will print.
5550If @value{GDBN} is printing a large array, it stops printing after it has
5551printed the number of elements set by the @code{set print elements} command.
5552This limit also applies to the display of strings.
d4f3574e 5553When @value{GDBN} starts, this limit is set to 200.
c906108c
SS
5554Setting @var{number-of-elements} to zero means that the printing is unlimited.
5555
c906108c
SS
5556@item show print elements
5557Display the number of elements of a large array that @value{GDBN} will print.
5558If the number is 0, then the printing is unlimited.
5559
9c16f35a
EZ
5560@item set print repeats
5561@cindex repeated array elements
5562Set the threshold for suppressing display of repeated array
5563elelments. When the number of consecutive identical elements of an
5564array exceeds the threshold, @value{GDBN} prints the string
5565@code{"<repeats @var{n} times>"}, where @var{n} is the number of
5566identical repetitions, instead of displaying the identical elements
5567themselves. Setting the threshold to zero will cause all elements to
5568be individually printed. The default threshold is 10.
5569
5570@item show print repeats
5571Display the current threshold for printing repeated identical
5572elements.
5573
c906108c 5574@item set print null-stop
4644b6e3 5575@cindex @sc{null} elements in arrays
c906108c 5576Cause @value{GDBN} to stop printing the characters of an array when the first
d4f3574e 5577@sc{null} is encountered. This is useful when large arrays actually
c906108c 5578contain only short strings.
d4f3574e 5579The default is off.
c906108c 5580
9c16f35a
EZ
5581@item show print null-stop
5582Show whether @value{GDBN} stops printing an array on the first
5583@sc{null} character.
5584
c906108c 5585@item set print pretty on
9c16f35a
EZ
5586@cindex print structures in indented form
5587@cindex indentation in structure display
5d161b24 5588Cause @value{GDBN} to print structures in an indented format with one member
c906108c
SS
5589per line, like this:
5590
5591@smallexample
5592@group
5593$1 = @{
5594 next = 0x0,
5595 flags = @{
5596 sweet = 1,
5597 sour = 1
5598 @},
5599 meat = 0x54 "Pork"
5600@}
5601@end group
5602@end smallexample
5603
5604@item set print pretty off
5605Cause @value{GDBN} to print structures in a compact format, like this:
5606
5607@smallexample
5608@group
5609$1 = @{next = 0x0, flags = @{sweet = 1, sour = 1@}, \
5610meat = 0x54 "Pork"@}
5611@end group
5612@end smallexample
5613
5614@noindent
5615This is the default format.
5616
c906108c
SS
5617@item show print pretty
5618Show which format @value{GDBN} is using to print structures.
5619
c906108c 5620@item set print sevenbit-strings on
4644b6e3
EZ
5621@cindex eight-bit characters in strings
5622@cindex octal escapes in strings
c906108c
SS
5623Print using only seven-bit characters; if this option is set,
5624@value{GDBN} displays any eight-bit characters (in strings or
5625character values) using the notation @code{\}@var{nnn}. This setting is
5626best if you are working in English (@sc{ascii}) and you use the
5627high-order bit of characters as a marker or ``meta'' bit.
5628
5629@item set print sevenbit-strings off
5630Print full eight-bit characters. This allows the use of more
5631international character sets, and is the default.
5632
c906108c
SS
5633@item show print sevenbit-strings
5634Show whether or not @value{GDBN} is printing only seven-bit characters.
5635
c906108c 5636@item set print union on
4644b6e3 5637@cindex unions in structures, printing
9c16f35a
EZ
5638Tell @value{GDBN} to print unions which are contained in structures
5639and other unions. This is the default setting.
c906108c
SS
5640
5641@item set print union off
9c16f35a
EZ
5642Tell @value{GDBN} not to print unions which are contained in
5643structures and other unions. @value{GDBN} will print @code{"@{...@}"}
5644instead.
c906108c 5645
c906108c
SS
5646@item show print union
5647Ask @value{GDBN} whether or not it will print unions which are contained in
9c16f35a 5648structures and other unions.
c906108c
SS
5649
5650For example, given the declarations
5651
5652@smallexample
5653typedef enum @{Tree, Bug@} Species;
5654typedef enum @{Big_tree, Acorn, Seedling@} Tree_forms;
5d161b24 5655typedef enum @{Caterpillar, Cocoon, Butterfly@}
c906108c
SS
5656 Bug_forms;
5657
5658struct thing @{
5659 Species it;
5660 union @{
5661 Tree_forms tree;
5662 Bug_forms bug;
5663 @} form;
5664@};
5665
5666struct thing foo = @{Tree, @{Acorn@}@};
5667@end smallexample
5668
5669@noindent
5670with @code{set print union on} in effect @samp{p foo} would print
5671
5672@smallexample
5673$1 = @{it = Tree, form = @{tree = Acorn, bug = Cocoon@}@}
5674@end smallexample
5675
5676@noindent
5677and with @code{set print union off} in effect it would print
5678
5679@smallexample
5680$1 = @{it = Tree, form = @{...@}@}
5681@end smallexample
9c16f35a
EZ
5682
5683@noindent
5684@code{set print union} affects programs written in C-like languages
5685and in Pascal.
c906108c
SS
5686@end table
5687
c906108c
SS
5688@need 1000
5689@noindent
b37052ae 5690These settings are of interest when debugging C@t{++} programs:
c906108c
SS
5691
5692@table @code
4644b6e3 5693@cindex demangling C@t{++} names
c906108c
SS
5694@item set print demangle
5695@itemx set print demangle on
b37052ae 5696Print C@t{++} names in their source form rather than in the encoded
c906108c 5697(``mangled'') form passed to the assembler and linker for type-safe
d4f3574e 5698linkage. The default is on.
c906108c 5699
c906108c 5700@item show print demangle
b37052ae 5701Show whether C@t{++} names are printed in mangled or demangled form.
c906108c 5702
c906108c
SS
5703@item set print asm-demangle
5704@itemx set print asm-demangle on
b37052ae 5705Print C@t{++} names in their source form rather than their mangled form, even
c906108c
SS
5706in assembler code printouts such as instruction disassemblies.
5707The default is off.
5708
c906108c 5709@item show print asm-demangle
b37052ae 5710Show whether C@t{++} names in assembly listings are printed in mangled
c906108c
SS
5711or demangled form.
5712
b37052ae
EZ
5713@cindex C@t{++} symbol decoding style
5714@cindex symbol decoding style, C@t{++}
a8f24a35 5715@kindex set demangle-style
c906108c
SS
5716@item set demangle-style @var{style}
5717Choose among several encoding schemes used by different compilers to
b37052ae 5718represent C@t{++} names. The choices for @var{style} are currently:
c906108c
SS
5719
5720@table @code
5721@item auto
5722Allow @value{GDBN} to choose a decoding style by inspecting your program.
5723
5724@item gnu
b37052ae 5725Decode based on the @sc{gnu} C@t{++} compiler (@code{g++}) encoding algorithm.
c906108c 5726This is the default.
c906108c
SS
5727
5728@item hp
b37052ae 5729Decode based on the HP ANSI C@t{++} (@code{aCC}) encoding algorithm.
c906108c
SS
5730
5731@item lucid
b37052ae 5732Decode based on the Lucid C@t{++} compiler (@code{lcc}) encoding algorithm.
c906108c
SS
5733
5734@item arm
b37052ae 5735Decode using the algorithm in the @cite{C@t{++} Annotated Reference Manual}.
c906108c
SS
5736@strong{Warning:} this setting alone is not sufficient to allow
5737debugging @code{cfront}-generated executables. @value{GDBN} would
5738require further enhancement to permit that.
5739
5740@end table
5741If you omit @var{style}, you will see a list of possible formats.
5742
c906108c 5743@item show demangle-style
b37052ae 5744Display the encoding style currently in use for decoding C@t{++} symbols.
c906108c 5745
c906108c
SS
5746@item set print object
5747@itemx set print object on
4644b6e3 5748@cindex derived type of an object, printing
9c16f35a 5749@cindex display derived types
c906108c
SS
5750When displaying a pointer to an object, identify the @emph{actual}
5751(derived) type of the object rather than the @emph{declared} type, using
5752the virtual function table.
5753
5754@item set print object off
5755Display only the declared type of objects, without reference to the
5756virtual function table. This is the default setting.
5757
c906108c
SS
5758@item show print object
5759Show whether actual, or declared, object types are displayed.
5760
c906108c
SS
5761@item set print static-members
5762@itemx set print static-members on
4644b6e3 5763@cindex static members of C@t{++} objects
b37052ae 5764Print static members when displaying a C@t{++} object. The default is on.
c906108c
SS
5765
5766@item set print static-members off
b37052ae 5767Do not print static members when displaying a C@t{++} object.
c906108c 5768
c906108c 5769@item show print static-members
9c16f35a
EZ
5770Show whether C@t{++} static members are printed or not.
5771
5772@item set print pascal_static-members
5773@itemx set print pascal_static-members on
5774@cindex static members of Pacal objects
5775@cindex Pacal objects, static members display
5776Print static members when displaying a Pascal object. The default is on.
5777
5778@item set print pascal_static-members off
5779Do not print static members when displaying a Pascal object.
5780
5781@item show print pascal_static-members
5782Show whether Pascal static members are printed or not.
c906108c
SS
5783
5784@c These don't work with HP ANSI C++ yet.
c906108c
SS
5785@item set print vtbl
5786@itemx set print vtbl on
4644b6e3 5787@cindex pretty print C@t{++} virtual function tables
9c16f35a
EZ
5788@cindex virtual functions (C@t{++}) display
5789@cindex VTBL display
b37052ae 5790Pretty print C@t{++} virtual function tables. The default is off.
c906108c 5791(The @code{vtbl} commands do not work on programs compiled with the HP
b37052ae 5792ANSI C@t{++} compiler (@code{aCC}).)
c906108c
SS
5793
5794@item set print vtbl off
b37052ae 5795Do not pretty print C@t{++} virtual function tables.
c906108c 5796
c906108c 5797@item show print vtbl
b37052ae 5798Show whether C@t{++} virtual function tables are pretty printed, or not.
c906108c 5799@end table
c906108c 5800
6d2ebf8b 5801@node Value History
c906108c
SS
5802@section Value history
5803
5804@cindex value history
9c16f35a 5805@cindex history of values printed by @value{GDBN}
5d161b24
DB
5806Values printed by the @code{print} command are saved in the @value{GDBN}
5807@dfn{value history}. This allows you to refer to them in other expressions.
5808Values are kept until the symbol table is re-read or discarded
5809(for example with the @code{file} or @code{symbol-file} commands).
5810When the symbol table changes, the value history is discarded,
5811since the values may contain pointers back to the types defined in the
c906108c
SS
5812symbol table.
5813
5814@cindex @code{$}
5815@cindex @code{$$}
5816@cindex history number
5817The values printed are given @dfn{history numbers} by which you can
5818refer to them. These are successive integers starting with one.
5819@code{print} shows you the history number assigned to a value by
5820printing @samp{$@var{num} = } before the value; here @var{num} is the
5821history number.
5822
5823To refer to any previous value, use @samp{$} followed by the value's
5824history number. The way @code{print} labels its output is designed to
5825remind you of this. Just @code{$} refers to the most recent value in
5826the history, and @code{$$} refers to the value before that.
5827@code{$$@var{n}} refers to the @var{n}th value from the end; @code{$$2}
5828is the value just prior to @code{$$}, @code{$$1} is equivalent to
5829@code{$$}, and @code{$$0} is equivalent to @code{$}.
5830
5831For example, suppose you have just printed a pointer to a structure and
5832want to see the contents of the structure. It suffices to type
5833
474c8240 5834@smallexample
c906108c 5835p *$
474c8240 5836@end smallexample
c906108c
SS
5837
5838If you have a chain of structures where the component @code{next} points
5839to the next one, you can print the contents of the next one with this:
5840
474c8240 5841@smallexample
c906108c 5842p *$.next
474c8240 5843@end smallexample
c906108c
SS
5844
5845@noindent
5846You can print successive links in the chain by repeating this
5847command---which you can do by just typing @key{RET}.
5848
5849Note that the history records values, not expressions. If the value of
5850@code{x} is 4 and you type these commands:
5851
474c8240 5852@smallexample
c906108c
SS
5853print x
5854set x=5
474c8240 5855@end smallexample
c906108c
SS
5856
5857@noindent
5858then the value recorded in the value history by the @code{print} command
5859remains 4 even though the value of @code{x} has changed.
5860
5861@table @code
5862@kindex show values
5863@item show values
5864Print the last ten values in the value history, with their item numbers.
5865This is like @samp{p@ $$9} repeated ten times, except that @code{show
5866values} does not change the history.
5867
5868@item show values @var{n}
5869Print ten history values centered on history item number @var{n}.
5870
5871@item show values +
5872Print ten history values just after the values last printed. If no more
5873values are available, @code{show values +} produces no display.
5874@end table
5875
5876Pressing @key{RET} to repeat @code{show values @var{n}} has exactly the
5877same effect as @samp{show values +}.
5878
6d2ebf8b 5879@node Convenience Vars
c906108c
SS
5880@section Convenience variables
5881
5882@cindex convenience variables
9c16f35a 5883@cindex user-defined variables
c906108c
SS
5884@value{GDBN} provides @dfn{convenience variables} that you can use within
5885@value{GDBN} to hold on to a value and refer to it later. These variables
5886exist entirely within @value{GDBN}; they are not part of your program, and
5887setting a convenience variable has no direct effect on further execution
5888of your program. That is why you can use them freely.
5889
5890Convenience variables are prefixed with @samp{$}. Any name preceded by
5891@samp{$} can be used for a convenience variable, unless it is one of
d4f3574e 5892the predefined machine-specific register names (@pxref{Registers, ,Registers}).
c906108c
SS
5893(Value history references, in contrast, are @emph{numbers} preceded
5894by @samp{$}. @xref{Value History, ,Value history}.)
5895
5896You can save a value in a convenience variable with an assignment
5897expression, just as you would set a variable in your program.
5898For example:
5899
474c8240 5900@smallexample
c906108c 5901set $foo = *object_ptr
474c8240 5902@end smallexample
c906108c
SS
5903
5904@noindent
5905would save in @code{$foo} the value contained in the object pointed to by
5906@code{object_ptr}.
5907
5908Using a convenience variable for the first time creates it, but its
5909value is @code{void} until you assign a new value. You can alter the
5910value with another assignment at any time.
5911
5912Convenience variables have no fixed types. You can assign a convenience
5913variable any type of value, including structures and arrays, even if
5914that variable already has a value of a different type. The convenience
5915variable, when used as an expression, has the type of its current value.
5916
5917@table @code
5918@kindex show convenience
9c16f35a 5919@cindex show all user variables
c906108c
SS
5920@item show convenience
5921Print a list of convenience variables used so far, and their values.
d4f3574e 5922Abbreviated @code{show conv}.
c906108c
SS
5923@end table
5924
5925One of the ways to use a convenience variable is as a counter to be
5926incremented or a pointer to be advanced. For example, to print
5927a field from successive elements of an array of structures:
5928
474c8240 5929@smallexample
c906108c
SS
5930set $i = 0
5931print bar[$i++]->contents
474c8240 5932@end smallexample
c906108c 5933
d4f3574e
SS
5934@noindent
5935Repeat that command by typing @key{RET}.
c906108c
SS
5936
5937Some convenience variables are created automatically by @value{GDBN} and given
5938values likely to be useful.
5939
5940@table @code
41afff9a 5941@vindex $_@r{, convenience variable}
c906108c
SS
5942@item $_
5943The variable @code{$_} is automatically set by the @code{x} command to
5944the last address examined (@pxref{Memory, ,Examining memory}). Other
5945commands which provide a default address for @code{x} to examine also
5946set @code{$_} to that address; these commands include @code{info line}
5947and @code{info breakpoint}. The type of @code{$_} is @code{void *}
5948except when set by the @code{x} command, in which case it is a pointer
5949to the type of @code{$__}.
5950
41afff9a 5951@vindex $__@r{, convenience variable}
c906108c
SS
5952@item $__
5953The variable @code{$__} is automatically set by the @code{x} command
5954to the value found in the last address examined. Its type is chosen
5955to match the format in which the data was printed.
5956
5957@item $_exitcode
41afff9a 5958@vindex $_exitcode@r{, convenience variable}
c906108c
SS
5959The variable @code{$_exitcode} is automatically set to the exit code when
5960the program being debugged terminates.
5961@end table
5962
53a5351d
JM
5963On HP-UX systems, if you refer to a function or variable name that
5964begins with a dollar sign, @value{GDBN} searches for a user or system
5965name first, before it searches for a convenience variable.
c906108c 5966
6d2ebf8b 5967@node Registers
c906108c
SS
5968@section Registers
5969
5970@cindex registers
5971You can refer to machine register contents, in expressions, as variables
5972with names starting with @samp{$}. The names of registers are different
5973for each machine; use @code{info registers} to see the names used on
5974your machine.
5975
5976@table @code
5977@kindex info registers
5978@item info registers
5979Print the names and values of all registers except floating-point
c85508ee 5980and vector registers (in the selected stack frame).
c906108c
SS
5981
5982@kindex info all-registers
5983@cindex floating point registers
5984@item info all-registers
5985Print the names and values of all registers, including floating-point
c85508ee 5986and vector registers (in the selected stack frame).
c906108c
SS
5987
5988@item info registers @var{regname} @dots{}
5989Print the @dfn{relativized} value of each specified register @var{regname}.
5d161b24
DB
5990As discussed in detail below, register values are normally relative to
5991the selected stack frame. @var{regname} may be any register name valid on
c906108c
SS
5992the machine you are using, with or without the initial @samp{$}.
5993@end table
5994
5995@value{GDBN} has four ``standard'' register names that are available (in
5996expressions) on most machines---whenever they do not conflict with an
5997architecture's canonical mnemonics for registers. The register names
5998@code{$pc} and @code{$sp} are used for the program counter register and
5999the stack pointer. @code{$fp} is used for a register that contains a
6000pointer to the current stack frame, and @code{$ps} is used for a
6001register that contains the processor status. For example,
6002you could print the program counter in hex with
6003
474c8240 6004@smallexample
c906108c 6005p/x $pc
474c8240 6006@end smallexample
c906108c
SS
6007
6008@noindent
6009or print the instruction to be executed next with
6010
474c8240 6011@smallexample
c906108c 6012x/i $pc
474c8240 6013@end smallexample
c906108c
SS
6014
6015@noindent
6016or add four to the stack pointer@footnote{This is a way of removing
6017one word from the stack, on machines where stacks grow downward in
6018memory (most machines, nowadays). This assumes that the innermost
6019stack frame is selected; setting @code{$sp} is not allowed when other
6020stack frames are selected. To pop entire frames off the stack,
6021regardless of machine architecture, use @code{return};
d4f3574e 6022see @ref{Returning, ,Returning from a function}.} with
c906108c 6023
474c8240 6024@smallexample
c906108c 6025set $sp += 4
474c8240 6026@end smallexample
c906108c
SS
6027
6028Whenever possible, these four standard register names are available on
6029your machine even though the machine has different canonical mnemonics,
6030so long as there is no conflict. The @code{info registers} command
6031shows the canonical names. For example, on the SPARC, @code{info
6032registers} displays the processor status register as @code{$psr} but you
d4f3574e
SS
6033can also refer to it as @code{$ps}; and on x86-based machines @code{$ps}
6034is an alias for the @sc{eflags} register.
c906108c
SS
6035
6036@value{GDBN} always considers the contents of an ordinary register as an
6037integer when the register is examined in this way. Some machines have
6038special registers which can hold nothing but floating point; these
6039registers are considered to have floating point values. There is no way
6040to refer to the contents of an ordinary register as floating point value
6041(although you can @emph{print} it as a floating point value with
6042@samp{print/f $@var{regname}}).
6043
6044Some registers have distinct ``raw'' and ``virtual'' data formats. This
6045means that the data format in which the register contents are saved by
6046the operating system is not the same one that your program normally
6047sees. For example, the registers of the 68881 floating point
6048coprocessor are always saved in ``extended'' (raw) format, but all C
6049programs expect to work with ``double'' (virtual) format. In such
5d161b24 6050cases, @value{GDBN} normally works with the virtual format only (the format
c906108c
SS
6051that makes sense for your program), but the @code{info registers} command
6052prints the data in both formats.
6053
6054Normally, register values are relative to the selected stack frame
6055(@pxref{Selection, ,Selecting a frame}). This means that you get the
6056value that the register would contain if all stack frames farther in
6057were exited and their saved registers restored. In order to see the
6058true contents of hardware registers, you must select the innermost
6059frame (with @samp{frame 0}).
6060
6061However, @value{GDBN} must deduce where registers are saved, from the machine
6062code generated by your compiler. If some registers are not saved, or if
6063@value{GDBN} is unable to locate the saved registers, the selected stack
6064frame makes no difference.
6065
6d2ebf8b 6066@node Floating Point Hardware
c906108c
SS
6067@section Floating point hardware
6068@cindex floating point
6069
6070Depending on the configuration, @value{GDBN} may be able to give
6071you more information about the status of the floating point hardware.
6072
6073@table @code
6074@kindex info float
6075@item info float
6076Display hardware-dependent information about the floating
6077point unit. The exact contents and layout vary depending on the
6078floating point chip. Currently, @samp{info float} is supported on
6079the ARM and x86 machines.
6080@end table
c906108c 6081
e76f1f2e
AC
6082@node Vector Unit
6083@section Vector Unit
6084@cindex vector unit
6085
6086Depending on the configuration, @value{GDBN} may be able to give you
6087more information about the status of the vector unit.
6088
6089@table @code
6090@kindex info vector
6091@item info vector
6092Display information about the vector unit. The exact contents and
6093layout vary depending on the hardware.
6094@end table
6095
b383017d
RM
6096@node Auxiliary Vector
6097@section Operating system auxiliary vector
6098@cindex auxiliary vector
6099@cindex vector, auxiliary
6100
6101Some operating systems supply an @dfn{auxiliary vector} to programs at
6102startup. This is akin to the arguments and environment that you
6103specify for a program, but contains a system-dependent variety of
6104binary values that tell system libraries important details about the
6105hardware, operating system, and process. Each value's purpose is
6106identified by an integer tag; the meanings are well-known but system-specific.
6107Depending on the configuration and operating system facilities,
9c16f35a
EZ
6108@value{GDBN} may be able to show you this information. For remote
6109targets, this functionality may further depend on the remote stub's
6110support of the @samp{qPart:auxv:read} packet, see @ref{Remote
6111configuration, auxiliary vector}.
b383017d
RM
6112
6113@table @code
6114@kindex info auxv
6115@item info auxv
6116Display the auxiliary vector of the inferior, which can be either a
e4937fc1 6117live process or a core dump file. @value{GDBN} prints each tag value
b383017d
RM
6118numerically, and also shows names and text descriptions for recognized
6119tags. Some values in the vector are numbers, some bit masks, and some
e4937fc1 6120pointers to strings or other data. @value{GDBN} displays each value in the
b383017d
RM
6121most appropriate form for a recognized tag, and in hexadecimal for
6122an unrecognized tag.
6123@end table
6124
29e57380 6125@node Memory Region Attributes
b383017d 6126@section Memory region attributes
29e57380
C
6127@cindex memory region attributes
6128
b383017d
RM
6129@dfn{Memory region attributes} allow you to describe special handling
6130required by regions of your target's memory. @value{GDBN} uses attributes
29e57380
C
6131to determine whether to allow certain types of memory accesses; whether to
6132use specific width accesses; and whether to cache target memory.
6133
6134Defined memory regions can be individually enabled and disabled. When a
6135memory region is disabled, @value{GDBN} uses the default attributes when
6136accessing memory in that region. Similarly, if no memory regions have
6137been defined, @value{GDBN} uses the default attributes when accessing
6138all memory.
6139
b383017d 6140When a memory region is defined, it is given a number to identify it;
29e57380
C
6141to enable, disable, or remove a memory region, you specify that number.
6142
6143@table @code
6144@kindex mem
bfac230e 6145@item mem @var{lower} @var{upper} @var{attributes}@dots{}
09d4efe1
EZ
6146Define a memory region bounded by @var{lower} and @var{upper} with
6147attributes @var{attributes}@dots{}, and add it to the list of regions
6148monitored by @value{GDBN}. Note that @var{upper} == 0 is a special
6149case: it is treated as the the target's maximum memory address.
bfac230e 6150(0xffff on 16 bit targets, 0xffffffff on 32 bit targets, etc.)
29e57380
C
6151
6152@kindex delete mem
6153@item delete mem @var{nums}@dots{}
09d4efe1
EZ
6154Remove memory regions @var{nums}@dots{} from the list of regions
6155monitored by @value{GDBN}.
29e57380
C
6156
6157@kindex disable mem
6158@item disable mem @var{nums}@dots{}
09d4efe1 6159Disable monitoring of memory regions @var{nums}@dots{}.
b383017d 6160A disabled memory region is not forgotten.
29e57380
C
6161It may be enabled again later.
6162
6163@kindex enable mem
6164@item enable mem @var{nums}@dots{}
09d4efe1 6165Enable monitoring of memory regions @var{nums}@dots{}.
29e57380
C
6166
6167@kindex info mem
6168@item info mem
6169Print a table of all defined memory regions, with the following columns
09d4efe1 6170for each region:
29e57380
C
6171
6172@table @emph
6173@item Memory Region Number
6174@item Enabled or Disabled.
b383017d 6175Enabled memory regions are marked with @samp{y}.
29e57380
C
6176Disabled memory regions are marked with @samp{n}.
6177
6178@item Lo Address
6179The address defining the inclusive lower bound of the memory region.
6180
6181@item Hi Address
6182The address defining the exclusive upper bound of the memory region.
6183
6184@item Attributes
6185The list of attributes set for this memory region.
6186@end table
6187@end table
6188
6189
6190@subsection Attributes
6191
b383017d 6192@subsubsection Memory Access Mode
29e57380
C
6193The access mode attributes set whether @value{GDBN} may make read or
6194write accesses to a memory region.
6195
6196While these attributes prevent @value{GDBN} from performing invalid
6197memory accesses, they do nothing to prevent the target system, I/O DMA,
6198etc. from accessing memory.
6199
6200@table @code
6201@item ro
6202Memory is read only.
6203@item wo
6204Memory is write only.
6205@item rw
6ca652b0 6206Memory is read/write. This is the default.
29e57380
C
6207@end table
6208
6209@subsubsection Memory Access Size
6210The acccess size attributes tells @value{GDBN} to use specific sized
6211accesses in the memory region. Often memory mapped device registers
6212require specific sized accesses. If no access size attribute is
6213specified, @value{GDBN} may use accesses of any size.
6214
6215@table @code
6216@item 8
6217Use 8 bit memory accesses.
6218@item 16
6219Use 16 bit memory accesses.
6220@item 32
6221Use 32 bit memory accesses.
6222@item 64
6223Use 64 bit memory accesses.
6224@end table
6225
6226@c @subsubsection Hardware/Software Breakpoints
6227@c The hardware/software breakpoint attributes set whether @value{GDBN}
6228@c will use hardware or software breakpoints for the internal breakpoints
6229@c used by the step, next, finish, until, etc. commands.
6230@c
6231@c @table @code
6232@c @item hwbreak
b383017d 6233@c Always use hardware breakpoints
29e57380
C
6234@c @item swbreak (default)
6235@c @end table
6236
6237@subsubsection Data Cache
6238The data cache attributes set whether @value{GDBN} will cache target
6239memory. While this generally improves performance by reducing debug
6240protocol overhead, it can lead to incorrect results because @value{GDBN}
6241does not know about volatile variables or memory mapped device
6242registers.
6243
6244@table @code
6245@item cache
b383017d 6246Enable @value{GDBN} to cache target memory.
6ca652b0
EZ
6247@item nocache
6248Disable @value{GDBN} from caching target memory. This is the default.
29e57380
C
6249@end table
6250
6251@c @subsubsection Memory Write Verification
b383017d 6252@c The memory write verification attributes set whether @value{GDBN}
29e57380
C
6253@c will re-reads data after each write to verify the write was successful.
6254@c
6255@c @table @code
6256@c @item verify
6257@c @item noverify (default)
6258@c @end table
6259
16d9dec6
MS
6260@node Dump/Restore Files
6261@section Copy between memory and a file
6262@cindex dump/restore files
6263@cindex append data to a file
6264@cindex dump data to a file
6265@cindex restore data from a file
16d9dec6 6266
df5215a6
JB
6267You can use the commands @code{dump}, @code{append}, and
6268@code{restore} to copy data between target memory and a file. The
6269@code{dump} and @code{append} commands write data to a file, and the
6270@code{restore} command reads data from a file back into the inferior's
6271memory. Files may be in binary, Motorola S-record, Intel hex, or
6272Tektronix Hex format; however, @value{GDBN} can only append to binary
6273files.
6274
6275@table @code
6276
6277@kindex dump
6278@item dump @r{[}@var{format}@r{]} memory @var{filename} @var{start_addr} @var{end_addr}
6279@itemx dump @r{[}@var{format}@r{]} value @var{filename} @var{expr}
6280Dump the contents of memory from @var{start_addr} to @var{end_addr},
6281or the value of @var{expr}, to @var{filename} in the given format.
16d9dec6 6282
df5215a6 6283The @var{format} parameter may be any one of:
16d9dec6 6284@table @code
df5215a6
JB
6285@item binary
6286Raw binary form.
6287@item ihex
6288Intel hex format.
6289@item srec
6290Motorola S-record format.
6291@item tekhex
6292Tektronix Hex format.
6293@end table
6294
6295@value{GDBN} uses the same definitions of these formats as the
6296@sc{gnu} binary utilities, like @samp{objdump} and @samp{objcopy}. If
6297@var{format} is omitted, @value{GDBN} dumps the data in raw binary
6298form.
6299
6300@kindex append
6301@item append @r{[}binary@r{]} memory @var{filename} @var{start_addr} @var{end_addr}
6302@itemx append @r{[}binary@r{]} value @var{filename} @var{expr}
6303Append the contents of memory from @var{start_addr} to @var{end_addr},
09d4efe1 6304or the value of @var{expr}, to the file @var{filename}, in raw binary form.
df5215a6
JB
6305(@value{GDBN} can only append data to files in raw binary form.)
6306
6307@kindex restore
6308@item restore @var{filename} @r{[}binary@r{]} @var{bias} @var{start} @var{end}
6309Restore the contents of file @var{filename} into memory. The
6310@code{restore} command can automatically recognize any known @sc{bfd}
6311file format, except for raw binary. To restore a raw binary file you
6312must specify the optional keyword @code{binary} after the filename.
16d9dec6 6313
b383017d 6314If @var{bias} is non-zero, its value will be added to the addresses
16d9dec6
MS
6315contained in the file. Binary files always start at address zero, so
6316they will be restored at address @var{bias}. Other bfd files have
6317a built-in location; they will be restored at offset @var{bias}
6318from that location.
6319
6320If @var{start} and/or @var{end} are non-zero, then only data between
6321file offset @var{start} and file offset @var{end} will be restored.
b383017d 6322These offsets are relative to the addresses in the file, before
16d9dec6
MS
6323the @var{bias} argument is applied.
6324
6325@end table
6326
384ee23f
EZ
6327@node Core File Generation
6328@section How to Produce a Core File from Your Program
6329@cindex dump core from inferior
6330
6331A @dfn{core file} or @dfn{core dump} is a file that records the memory
6332image of a running process and its process status (register values
6333etc.). Its primary use is post-mortem debugging of a program that
6334crashed while it ran outside a debugger. A program that crashes
6335automatically produces a core file, unless this feature is disabled by
6336the user. @xref{Files}, for information on invoking @value{GDBN} in
6337the post-mortem debugging mode.
6338
6339Occasionally, you may wish to produce a core file of the program you
6340are debugging in order to preserve a snapshot of its state.
6341@value{GDBN} has a special command for that.
6342
6343@table @code
6344@kindex gcore
6345@kindex generate-core-file
6346@item generate-core-file [@var{file}]
6347@itemx gcore [@var{file}]
6348Produce a core dump of the inferior process. The optional argument
6349@var{file} specifies the file name where to put the core dump. If not
6350specified, the file name defaults to @file{core.@var{pid}}, where
6351@var{pid} is the inferior process ID.
6352
6353Note that this command is implemented only for some systems (as of
6354this writing, @sc{gnu}/Linux, FreeBSD, Solaris, Unixware, and S390).
6355@end table
6356
a0eb71c5
KB
6357@node Character Sets
6358@section Character Sets
6359@cindex character sets
6360@cindex charset
6361@cindex translating between character sets
6362@cindex host character set
6363@cindex target character set
6364
6365If the program you are debugging uses a different character set to
6366represent characters and strings than the one @value{GDBN} uses itself,
6367@value{GDBN} can automatically translate between the character sets for
6368you. The character set @value{GDBN} uses we call the @dfn{host
6369character set}; the one the inferior program uses we call the
6370@dfn{target character set}.
6371
6372For example, if you are running @value{GDBN} on a @sc{gnu}/Linux system, which
6373uses the ISO Latin 1 character set, but you are using @value{GDBN}'s
6374remote protocol (@pxref{Remote,Remote Debugging}) to debug a program
6375running on an IBM mainframe, which uses the @sc{ebcdic} character set,
6376then the host character set is Latin-1, and the target character set is
6377@sc{ebcdic}. If you give @value{GDBN} the command @code{set
e33d66ec 6378target-charset EBCDIC-US}, then @value{GDBN} translates between
a0eb71c5
KB
6379@sc{ebcdic} and Latin 1 as you print character or string values, or use
6380character and string literals in expressions.
6381
6382@value{GDBN} has no way to automatically recognize which character set
6383the inferior program uses; you must tell it, using the @code{set
6384target-charset} command, described below.
6385
6386Here are the commands for controlling @value{GDBN}'s character set
6387support:
6388
6389@table @code
6390@item set target-charset @var{charset}
6391@kindex set target-charset
6392Set the current target character set to @var{charset}. We list the
e33d66ec
EZ
6393character set names @value{GDBN} recognizes below, but if you type
6394@code{set target-charset} followed by @key{TAB}@key{TAB}, @value{GDBN} will
6395list the target character sets it supports.
a0eb71c5
KB
6396@end table
6397
6398@table @code
6399@item set host-charset @var{charset}
6400@kindex set host-charset
6401Set the current host character set to @var{charset}.
6402
6403By default, @value{GDBN} uses a host character set appropriate to the
6404system it is running on; you can override that default using the
6405@code{set host-charset} command.
6406
6407@value{GDBN} can only use certain character sets as its host character
6408set. We list the character set names @value{GDBN} recognizes below, and
e33d66ec
EZ
6409indicate which can be host character sets, but if you type
6410@code{set target-charset} followed by @key{TAB}@key{TAB}, @value{GDBN} will
6411list the host character sets it supports.
a0eb71c5
KB
6412
6413@item set charset @var{charset}
6414@kindex set charset
e33d66ec
EZ
6415Set the current host and target character sets to @var{charset}. As
6416above, if you type @code{set charset} followed by @key{TAB}@key{TAB},
6417@value{GDBN} will list the name of the character sets that can be used
6418for both host and target.
6419
a0eb71c5
KB
6420
6421@item show charset
a0eb71c5 6422@kindex show charset
b383017d 6423Show the names of the current host and target charsets.
e33d66ec
EZ
6424
6425@itemx show host-charset
a0eb71c5 6426@kindex show host-charset
b383017d 6427Show the name of the current host charset.
e33d66ec
EZ
6428
6429@itemx show target-charset
a0eb71c5 6430@kindex show target-charset
b383017d 6431Show the name of the current target charset.
a0eb71c5
KB
6432
6433@end table
6434
6435@value{GDBN} currently includes support for the following character
6436sets:
6437
6438@table @code
6439
6440@item ASCII
6441@cindex ASCII character set
6442Seven-bit U.S. @sc{ascii}. @value{GDBN} can use this as its host
6443character set.
6444
6445@item ISO-8859-1
6446@cindex ISO 8859-1 character set
6447@cindex ISO Latin 1 character set
e33d66ec 6448The ISO Latin 1 character set. This extends @sc{ascii} with accented
a0eb71c5
KB
6449characters needed for French, German, and Spanish. @value{GDBN} can use
6450this as its host character set.
6451
6452@item EBCDIC-US
6453@itemx IBM1047
6454@cindex EBCDIC character set
6455@cindex IBM1047 character set
6456Variants of the @sc{ebcdic} character set, used on some of IBM's
6457mainframe operating systems. (@sc{gnu}/Linux on the S/390 uses U.S. @sc{ascii}.)
6458@value{GDBN} cannot use these as its host character set.
6459
6460@end table
6461
6462Note that these are all single-byte character sets. More work inside
6463GDB is needed to support multi-byte or variable-width character
6464encodings, like the UTF-8 and UCS-2 encodings of Unicode.
6465
6466Here is an example of @value{GDBN}'s character set support in action.
6467Assume that the following source code has been placed in the file
6468@file{charset-test.c}:
6469
6470@smallexample
6471#include <stdio.h>
6472
6473char ascii_hello[]
6474 = @{72, 101, 108, 108, 111, 44, 32, 119,
6475 111, 114, 108, 100, 33, 10, 0@};
6476char ibm1047_hello[]
6477 = @{200, 133, 147, 147, 150, 107, 64, 166,
6478 150, 153, 147, 132, 90, 37, 0@};
6479
6480main ()
6481@{
6482 printf ("Hello, world!\n");
6483@}
10998722 6484@end smallexample
a0eb71c5
KB
6485
6486In this program, @code{ascii_hello} and @code{ibm1047_hello} are arrays
6487containing the string @samp{Hello, world!} followed by a newline,
6488encoded in the @sc{ascii} and @sc{ibm1047} character sets.
6489
6490We compile the program, and invoke the debugger on it:
6491
6492@smallexample
6493$ gcc -g charset-test.c -o charset-test
6494$ gdb -nw charset-test
6495GNU gdb 2001-12-19-cvs
6496Copyright 2001 Free Software Foundation, Inc.
6497@dots{}
f7dc1244 6498(@value{GDBP})
10998722 6499@end smallexample
a0eb71c5
KB
6500
6501We can use the @code{show charset} command to see what character sets
6502@value{GDBN} is currently using to interpret and display characters and
6503strings:
6504
6505@smallexample
f7dc1244 6506(@value{GDBP}) show charset
e33d66ec 6507The current host and target character set is `ISO-8859-1'.
f7dc1244 6508(@value{GDBP})
10998722 6509@end smallexample
a0eb71c5
KB
6510
6511For the sake of printing this manual, let's use @sc{ascii} as our
6512initial character set:
6513@smallexample
f7dc1244
EZ
6514(@value{GDBP}) set charset ASCII
6515(@value{GDBP}) show charset
e33d66ec 6516The current host and target character set is `ASCII'.
f7dc1244 6517(@value{GDBP})
10998722 6518@end smallexample
a0eb71c5
KB
6519
6520Let's assume that @sc{ascii} is indeed the correct character set for our
6521host system --- in other words, let's assume that if @value{GDBN} prints
6522characters using the @sc{ascii} character set, our terminal will display
6523them properly. Since our current target character set is also
6524@sc{ascii}, the contents of @code{ascii_hello} print legibly:
6525
6526@smallexample
f7dc1244 6527(@value{GDBP}) print ascii_hello
a0eb71c5 6528$1 = 0x401698 "Hello, world!\n"
f7dc1244 6529(@value{GDBP}) print ascii_hello[0]
a0eb71c5 6530$2 = 72 'H'
f7dc1244 6531(@value{GDBP})
10998722 6532@end smallexample
a0eb71c5
KB
6533
6534@value{GDBN} uses the target character set for character and string
6535literals you use in expressions:
6536
6537@smallexample
f7dc1244 6538(@value{GDBP}) print '+'
a0eb71c5 6539$3 = 43 '+'
f7dc1244 6540(@value{GDBP})
10998722 6541@end smallexample
a0eb71c5
KB
6542
6543The @sc{ascii} character set uses the number 43 to encode the @samp{+}
6544character.
6545
6546@value{GDBN} relies on the user to tell it which character set the
6547target program uses. If we print @code{ibm1047_hello} while our target
6548character set is still @sc{ascii}, we get jibberish:
6549
6550@smallexample
f7dc1244 6551(@value{GDBP}) print ibm1047_hello
a0eb71c5 6552$4 = 0x4016a8 "\310\205\223\223\226k@@\246\226\231\223\204Z%"
f7dc1244 6553(@value{GDBP}) print ibm1047_hello[0]
a0eb71c5 6554$5 = 200 '\310'
f7dc1244 6555(@value{GDBP})
10998722 6556@end smallexample
a0eb71c5 6557
e33d66ec 6558If we invoke the @code{set target-charset} followed by @key{TAB}@key{TAB},
a0eb71c5
KB
6559@value{GDBN} tells us the character sets it supports:
6560
6561@smallexample
f7dc1244 6562(@value{GDBP}) set target-charset
b383017d 6563ASCII EBCDIC-US IBM1047 ISO-8859-1
f7dc1244 6564(@value{GDBP}) set target-charset
10998722 6565@end smallexample
a0eb71c5
KB
6566
6567We can select @sc{ibm1047} as our target character set, and examine the
6568program's strings again. Now the @sc{ascii} string is wrong, but
6569@value{GDBN} translates the contents of @code{ibm1047_hello} from the
6570target character set, @sc{ibm1047}, to the host character set,
6571@sc{ascii}, and they display correctly:
6572
6573@smallexample
f7dc1244
EZ
6574(@value{GDBP}) set target-charset IBM1047
6575(@value{GDBP}) show charset
e33d66ec
EZ
6576The current host character set is `ASCII'.
6577The current target character set is `IBM1047'.
f7dc1244 6578(@value{GDBP}) print ascii_hello
a0eb71c5 6579$6 = 0x401698 "\110\145%%?\054\040\167?\162%\144\041\012"
f7dc1244 6580(@value{GDBP}) print ascii_hello[0]
a0eb71c5 6581$7 = 72 '\110'
f7dc1244 6582(@value{GDBP}) print ibm1047_hello
a0eb71c5 6583$8 = 0x4016a8 "Hello, world!\n"
f7dc1244 6584(@value{GDBP}) print ibm1047_hello[0]
a0eb71c5 6585$9 = 200 'H'
f7dc1244 6586(@value{GDBP})
10998722 6587@end smallexample
a0eb71c5
KB
6588
6589As above, @value{GDBN} uses the target character set for character and
6590string literals you use in expressions:
6591
6592@smallexample
f7dc1244 6593(@value{GDBP}) print '+'
a0eb71c5 6594$10 = 78 '+'
f7dc1244 6595(@value{GDBP})
10998722 6596@end smallexample
a0eb71c5 6597
e33d66ec 6598The @sc{ibm1047} character set uses the number 78 to encode the @samp{+}
a0eb71c5
KB
6599character.
6600
09d4efe1
EZ
6601@node Caching Remote Data
6602@section Caching Data of Remote Targets
6603@cindex caching data of remote targets
6604
6605@value{GDBN} can cache data exchanged between the debugger and a
6606remote target (@pxref{Remote}). Such caching generally improves
6607performance, because it reduces the overhead of the remote protocol by
6608bundling memory reads and writes into large chunks. Unfortunately,
6609@value{GDBN} does not currently know anything about volatile
6610registers, and thus data caching will produce incorrect results when
6611volatile registers are in use.
6612
6613@table @code
6614@kindex set remotecache
6615@item set remotecache on
6616@itemx set remotecache off
6617Set caching state for remote targets. When @code{ON}, use data
6618caching. By default, this option is @code{OFF}.
6619
6620@kindex show remotecache
6621@item show remotecache
6622Show the current state of data caching for remote targets.
6623
6624@kindex info dcache
6625@item info dcache
6626Print the information about the data cache performance. The
6627information displayed includes: the dcache width and depth; and for
6628each cache line, how many times it was referenced, and its data and
6629state (dirty, bad, ok, etc.). This command is useful for debugging
6630the data cache operation.
6631@end table
6632
a0eb71c5 6633
e2e0bcd1
JB
6634@node Macros
6635@chapter C Preprocessor Macros
6636
49efadf5 6637Some languages, such as C and C@t{++}, provide a way to define and invoke
e2e0bcd1
JB
6638``preprocessor macros'' which expand into strings of tokens.
6639@value{GDBN} can evaluate expressions containing macro invocations, show
6640the result of macro expansion, and show a macro's definition, including
6641where it was defined.
6642
6643You may need to compile your program specially to provide @value{GDBN}
6644with information about preprocessor macros. Most compilers do not
6645include macros in their debugging information, even when you compile
6646with the @option{-g} flag. @xref{Compilation}.
6647
6648A program may define a macro at one point, remove that definition later,
6649and then provide a different definition after that. Thus, at different
6650points in the program, a macro may have different definitions, or have
6651no definition at all. If there is a current stack frame, @value{GDBN}
6652uses the macros in scope at that frame's source code line. Otherwise,
6653@value{GDBN} uses the macros in scope at the current listing location;
6654see @ref{List}.
6655
6656At the moment, @value{GDBN} does not support the @code{##}
6657token-splicing operator, the @code{#} stringification operator, or
6658variable-arity macros.
6659
6660Whenever @value{GDBN} evaluates an expression, it always expands any
6661macro invocations present in the expression. @value{GDBN} also provides
6662the following commands for working with macros explicitly.
6663
6664@table @code
6665
6666@kindex macro expand
6667@cindex macro expansion, showing the results of preprocessor
6668@cindex preprocessor macro expansion, showing the results of
6669@cindex expanding preprocessor macros
6670@item macro expand @var{expression}
6671@itemx macro exp @var{expression}
6672Show the results of expanding all preprocessor macro invocations in
6673@var{expression}. Since @value{GDBN} simply expands macros, but does
6674not parse the result, @var{expression} need not be a valid expression;
6675it can be any string of tokens.
6676
09d4efe1 6677@kindex macro exp1
e2e0bcd1
JB
6678@item macro expand-once @var{expression}
6679@itemx macro exp1 @var{expression}
4644b6e3 6680@cindex expand macro once
e2e0bcd1
JB
6681@i{(This command is not yet implemented.)} Show the results of
6682expanding those preprocessor macro invocations that appear explicitly in
6683@var{expression}. Macro invocations appearing in that expansion are
6684left unchanged. This command allows you to see the effect of a
6685particular macro more clearly, without being confused by further
6686expansions. Since @value{GDBN} simply expands macros, but does not
6687parse the result, @var{expression} need not be a valid expression; it
6688can be any string of tokens.
6689
475b0867 6690@kindex info macro
e2e0bcd1
JB
6691@cindex macro definition, showing
6692@cindex definition, showing a macro's
475b0867 6693@item info macro @var{macro}
e2e0bcd1
JB
6694Show the definition of the macro named @var{macro}, and describe the
6695source location where that definition was established.
6696
6697@kindex macro define
6698@cindex user-defined macros
6699@cindex defining macros interactively
6700@cindex macros, user-defined
6701@item macro define @var{macro} @var{replacement-list}
6702@itemx macro define @var{macro}(@var{arglist}) @var{replacement-list}
6703@i{(This command is not yet implemented.)} Introduce a definition for a
6704preprocessor macro named @var{macro}, invocations of which are replaced
6705by the tokens given in @var{replacement-list}. The first form of this
6706command defines an ``object-like'' macro, which takes no arguments; the
6707second form defines a ``function-like'' macro, which takes the arguments
6708given in @var{arglist}.
6709
6710A definition introduced by this command is in scope in every expression
6711evaluated in @value{GDBN}, until it is removed with the @command{macro
6712undef} command, described below. The definition overrides all
6713definitions for @var{macro} present in the program being debugged, as
6714well as any previous user-supplied definition.
6715
6716@kindex macro undef
6717@item macro undef @var{macro}
6718@i{(This command is not yet implemented.)} Remove any user-supplied
6719definition for the macro named @var{macro}. This command only affects
6720definitions provided with the @command{macro define} command, described
6721above; it cannot remove definitions present in the program being
6722debugged.
6723
09d4efe1
EZ
6724@kindex macro list
6725@item macro list
6726@i{(This command is not yet implemented.)} List all the macros
6727defined using the @code{macro define} command.
e2e0bcd1
JB
6728@end table
6729
6730@cindex macros, example of debugging with
6731Here is a transcript showing the above commands in action. First, we
6732show our source files:
6733
6734@smallexample
6735$ cat sample.c
6736#include <stdio.h>
6737#include "sample.h"
6738
6739#define M 42
6740#define ADD(x) (M + x)
6741
6742main ()
6743@{
6744#define N 28
6745 printf ("Hello, world!\n");
6746#undef N
6747 printf ("We're so creative.\n");
6748#define N 1729
6749 printf ("Goodbye, world!\n");
6750@}
6751$ cat sample.h
6752#define Q <
6753$
6754@end smallexample
6755
6756Now, we compile the program using the @sc{gnu} C compiler, @value{NGCC}.
6757We pass the @option{-gdwarf-2} and @option{-g3} flags to ensure the
6758compiler includes information about preprocessor macros in the debugging
6759information.
6760
6761@smallexample
6762$ gcc -gdwarf-2 -g3 sample.c -o sample
6763$
6764@end smallexample
6765
6766Now, we start @value{GDBN} on our sample program:
6767
6768@smallexample
6769$ gdb -nw sample
6770GNU gdb 2002-05-06-cvs
6771Copyright 2002 Free Software Foundation, Inc.
6772GDB is free software, @dots{}
f7dc1244 6773(@value{GDBP})
e2e0bcd1
JB
6774@end smallexample
6775
6776We can expand macros and examine their definitions, even when the
6777program is not running. @value{GDBN} uses the current listing position
6778to decide which macro definitions are in scope:
6779
6780@smallexample
f7dc1244 6781(@value{GDBP}) list main
e2e0bcd1
JB
67823
67834 #define M 42
67845 #define ADD(x) (M + x)
67856
67867 main ()
67878 @{
67889 #define N 28
678910 printf ("Hello, world!\n");
679011 #undef N
679112 printf ("We're so creative.\n");
f7dc1244 6792(@value{GDBP}) info macro ADD
e2e0bcd1
JB
6793Defined at /home/jimb/gdb/macros/play/sample.c:5
6794#define ADD(x) (M + x)
f7dc1244 6795(@value{GDBP}) info macro Q
e2e0bcd1
JB
6796Defined at /home/jimb/gdb/macros/play/sample.h:1
6797 included at /home/jimb/gdb/macros/play/sample.c:2
6798#define Q <
f7dc1244 6799(@value{GDBP}) macro expand ADD(1)
e2e0bcd1 6800expands to: (42 + 1)
f7dc1244 6801(@value{GDBP}) macro expand-once ADD(1)
e2e0bcd1 6802expands to: once (M + 1)
f7dc1244 6803(@value{GDBP})
e2e0bcd1
JB
6804@end smallexample
6805
6806In the example above, note that @command{macro expand-once} expands only
6807the macro invocation explicit in the original text --- the invocation of
6808@code{ADD} --- but does not expand the invocation of the macro @code{M},
6809which was introduced by @code{ADD}.
6810
6811Once the program is running, GDB uses the macro definitions in force at
6812the source line of the current stack frame:
6813
6814@smallexample
f7dc1244 6815(@value{GDBP}) break main
e2e0bcd1 6816Breakpoint 1 at 0x8048370: file sample.c, line 10.
f7dc1244 6817(@value{GDBP}) run
b383017d 6818Starting program: /home/jimb/gdb/macros/play/sample
e2e0bcd1
JB
6819
6820Breakpoint 1, main () at sample.c:10
682110 printf ("Hello, world!\n");
f7dc1244 6822(@value{GDBP})
e2e0bcd1
JB
6823@end smallexample
6824
6825At line 10, the definition of the macro @code{N} at line 9 is in force:
6826
6827@smallexample
f7dc1244 6828(@value{GDBP}) info macro N
e2e0bcd1
JB
6829Defined at /home/jimb/gdb/macros/play/sample.c:9
6830#define N 28
f7dc1244 6831(@value{GDBP}) macro expand N Q M
e2e0bcd1 6832expands to: 28 < 42
f7dc1244 6833(@value{GDBP}) print N Q M
e2e0bcd1 6834$1 = 1
f7dc1244 6835(@value{GDBP})
e2e0bcd1
JB
6836@end smallexample
6837
6838As we step over directives that remove @code{N}'s definition, and then
6839give it a new definition, @value{GDBN} finds the definition (or lack
6840thereof) in force at each point:
6841
6842@smallexample
f7dc1244 6843(@value{GDBP}) next
e2e0bcd1
JB
6844Hello, world!
684512 printf ("We're so creative.\n");
f7dc1244 6846(@value{GDBP}) info macro N
e2e0bcd1
JB
6847The symbol `N' has no definition as a C/C++ preprocessor macro
6848at /home/jimb/gdb/macros/play/sample.c:12
f7dc1244 6849(@value{GDBP}) next
e2e0bcd1
JB
6850We're so creative.
685114 printf ("Goodbye, world!\n");
f7dc1244 6852(@value{GDBP}) info macro N
e2e0bcd1
JB
6853Defined at /home/jimb/gdb/macros/play/sample.c:13
6854#define N 1729
f7dc1244 6855(@value{GDBP}) macro expand N Q M
e2e0bcd1 6856expands to: 1729 < 42
f7dc1244 6857(@value{GDBP}) print N Q M
e2e0bcd1 6858$2 = 0
f7dc1244 6859(@value{GDBP})
e2e0bcd1
JB
6860@end smallexample
6861
6862
b37052ae
EZ
6863@node Tracepoints
6864@chapter Tracepoints
6865@c This chapter is based on the documentation written by Michael
6866@c Snyder, David Taylor, Jim Blandy, and Elena Zannoni.
6867
6868@cindex tracepoints
6869In some applications, it is not feasible for the debugger to interrupt
6870the program's execution long enough for the developer to learn
6871anything helpful about its behavior. If the program's correctness
6872depends on its real-time behavior, delays introduced by a debugger
6873might cause the program to change its behavior drastically, or perhaps
6874fail, even when the code itself is correct. It is useful to be able
6875to observe the program's behavior without interrupting it.
6876
6877Using @value{GDBN}'s @code{trace} and @code{collect} commands, you can
6878specify locations in the program, called @dfn{tracepoints}, and
6879arbitrary expressions to evaluate when those tracepoints are reached.
6880Later, using the @code{tfind} command, you can examine the values
6881those expressions had when the program hit the tracepoints. The
6882expressions may also denote objects in memory---structures or arrays,
6883for example---whose values @value{GDBN} should record; while visiting
6884a particular tracepoint, you may inspect those objects as if they were
6885in memory at that moment. However, because @value{GDBN} records these
6886values without interacting with you, it can do so quickly and
6887unobtrusively, hopefully not disturbing the program's behavior.
6888
6889The tracepoint facility is currently available only for remote
2c0069bb
EZ
6890targets. @xref{Targets}. In addition, your remote target must know how
6891to collect trace data. This functionality is implemented in the remote
6892stub; however, none of the stubs distributed with @value{GDBN} support
6893tracepoints as of this writing.
b37052ae
EZ
6894
6895This chapter describes the tracepoint commands and features.
6896
6897@menu
b383017d
RM
6898* Set Tracepoints::
6899* Analyze Collected Data::
6900* Tracepoint Variables::
b37052ae
EZ
6901@end menu
6902
6903@node Set Tracepoints
6904@section Commands to Set Tracepoints
6905
6906Before running such a @dfn{trace experiment}, an arbitrary number of
6907tracepoints can be set. Like a breakpoint (@pxref{Set Breaks}), a
6908tracepoint has a number assigned to it by @value{GDBN}. Like with
6909breakpoints, tracepoint numbers are successive integers starting from
6910one. Many of the commands associated with tracepoints take the
6911tracepoint number as their argument, to identify which tracepoint to
6912work on.
6913
6914For each tracepoint, you can specify, in advance, some arbitrary set
6915of data that you want the target to collect in the trace buffer when
6916it hits that tracepoint. The collected data can include registers,
6917local variables, or global data. Later, you can use @value{GDBN}
6918commands to examine the values these data had at the time the
6919tracepoint was hit.
6920
6921This section describes commands to set tracepoints and associated
6922conditions and actions.
6923
6924@menu
b383017d
RM
6925* Create and Delete Tracepoints::
6926* Enable and Disable Tracepoints::
6927* Tracepoint Passcounts::
6928* Tracepoint Actions::
6929* Listing Tracepoints::
6930* Starting and Stopping Trace Experiment::
b37052ae
EZ
6931@end menu
6932
6933@node Create and Delete Tracepoints
6934@subsection Create and Delete Tracepoints
6935
6936@table @code
6937@cindex set tracepoint
6938@kindex trace
6939@item trace
6940The @code{trace} command is very similar to the @code{break} command.
6941Its argument can be a source line, a function name, or an address in
6942the target program. @xref{Set Breaks}. The @code{trace} command
6943defines a tracepoint, which is a point in the target program where the
6944debugger will briefly stop, collect some data, and then allow the
6945program to continue. Setting a tracepoint or changing its commands
6946doesn't take effect until the next @code{tstart} command; thus, you
6947cannot change the tracepoint attributes once a trace experiment is
6948running.
6949
6950Here are some examples of using the @code{trace} command:
6951
6952@smallexample
6953(@value{GDBP}) @b{trace foo.c:121} // a source file and line number
6954
6955(@value{GDBP}) @b{trace +2} // 2 lines forward
6956
6957(@value{GDBP}) @b{trace my_function} // first source line of function
6958
6959(@value{GDBP}) @b{trace *my_function} // EXACT start address of function
6960
6961(@value{GDBP}) @b{trace *0x2117c4} // an address
6962@end smallexample
6963
6964@noindent
6965You can abbreviate @code{trace} as @code{tr}.
6966
6967@vindex $tpnum
6968@cindex last tracepoint number
6969@cindex recent tracepoint number
6970@cindex tracepoint number
6971The convenience variable @code{$tpnum} records the tracepoint number
6972of the most recently set tracepoint.
6973
6974@kindex delete tracepoint
6975@cindex tracepoint deletion
6976@item delete tracepoint @r{[}@var{num}@r{]}
6977Permanently delete one or more tracepoints. With no argument, the
6978default is to delete all tracepoints.
6979
6980Examples:
6981
6982@smallexample
6983(@value{GDBP}) @b{delete trace 1 2 3} // remove three tracepoints
6984
6985(@value{GDBP}) @b{delete trace} // remove all tracepoints
6986@end smallexample
6987
6988@noindent
6989You can abbreviate this command as @code{del tr}.
6990@end table
6991
6992@node Enable and Disable Tracepoints
6993@subsection Enable and Disable Tracepoints
6994
6995@table @code
6996@kindex disable tracepoint
6997@item disable tracepoint @r{[}@var{num}@r{]}
6998Disable tracepoint @var{num}, or all tracepoints if no argument
6999@var{num} is given. A disabled tracepoint will have no effect during
7000the next trace experiment, but it is not forgotten. You can re-enable
7001a disabled tracepoint using the @code{enable tracepoint} command.
7002
7003@kindex enable tracepoint
7004@item enable tracepoint @r{[}@var{num}@r{]}
7005Enable tracepoint @var{num}, or all tracepoints. The enabled
7006tracepoints will become effective the next time a trace experiment is
7007run.
7008@end table
7009
7010@node Tracepoint Passcounts
7011@subsection Tracepoint Passcounts
7012
7013@table @code
7014@kindex passcount
7015@cindex tracepoint pass count
7016@item passcount @r{[}@var{n} @r{[}@var{num}@r{]]}
7017Set the @dfn{passcount} of a tracepoint. The passcount is a way to
7018automatically stop a trace experiment. If a tracepoint's passcount is
7019@var{n}, then the trace experiment will be automatically stopped on
7020the @var{n}'th time that tracepoint is hit. If the tracepoint number
7021@var{num} is not specified, the @code{passcount} command sets the
7022passcount of the most recently defined tracepoint. If no passcount is
7023given, the trace experiment will run until stopped explicitly by the
7024user.
7025
7026Examples:
7027
7028@smallexample
b383017d 7029(@value{GDBP}) @b{passcount 5 2} // Stop on the 5th execution of
6826cf00 7030@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// tracepoint 2}
b37052ae
EZ
7031
7032(@value{GDBP}) @b{passcount 12} // Stop on the 12th execution of the
6826cf00 7033@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// most recently defined tracepoint.}
b37052ae
EZ
7034(@value{GDBP}) @b{trace foo}
7035(@value{GDBP}) @b{pass 3}
7036(@value{GDBP}) @b{trace bar}
7037(@value{GDBP}) @b{pass 2}
7038(@value{GDBP}) @b{trace baz}
7039(@value{GDBP}) @b{pass 1} // Stop tracing when foo has been
6826cf00
EZ
7040@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// executed 3 times OR when bar has}
7041@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// been executed 2 times}
7042@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// OR when baz has been executed 1 time.}
b37052ae
EZ
7043@end smallexample
7044@end table
7045
7046@node Tracepoint Actions
7047@subsection Tracepoint Action Lists
7048
7049@table @code
7050@kindex actions
7051@cindex tracepoint actions
7052@item actions @r{[}@var{num}@r{]}
7053This command will prompt for a list of actions to be taken when the
7054tracepoint is hit. If the tracepoint number @var{num} is not
7055specified, this command sets the actions for the one that was most
7056recently defined (so that you can define a tracepoint and then say
7057@code{actions} without bothering about its number). You specify the
7058actions themselves on the following lines, one action at a time, and
7059terminate the actions list with a line containing just @code{end}. So
7060far, the only defined actions are @code{collect} and
7061@code{while-stepping}.
7062
7063@cindex remove actions from a tracepoint
7064To remove all actions from a tracepoint, type @samp{actions @var{num}}
7065and follow it immediately with @samp{end}.
7066
7067@smallexample
7068(@value{GDBP}) @b{collect @var{data}} // collect some data
7069
6826cf00 7070(@value{GDBP}) @b{while-stepping 5} // single-step 5 times, collect data
b37052ae 7071
6826cf00 7072(@value{GDBP}) @b{end} // signals the end of actions.
b37052ae
EZ
7073@end smallexample
7074
7075In the following example, the action list begins with @code{collect}
7076commands indicating the things to be collected when the tracepoint is
7077hit. Then, in order to single-step and collect additional data
7078following the tracepoint, a @code{while-stepping} command is used,
7079followed by the list of things to be collected while stepping. The
7080@code{while-stepping} command is terminated by its own separate
7081@code{end} command. Lastly, the action list is terminated by an
7082@code{end} command.
7083
7084@smallexample
7085(@value{GDBP}) @b{trace foo}
7086(@value{GDBP}) @b{actions}
7087Enter actions for tracepoint 1, one per line:
7088> collect bar,baz
7089> collect $regs
7090> while-stepping 12
7091 > collect $fp, $sp
7092 > end
7093end
7094@end smallexample
7095
7096@kindex collect @r{(tracepoints)}
7097@item collect @var{expr1}, @var{expr2}, @dots{}
7098Collect values of the given expressions when the tracepoint is hit.
7099This command accepts a comma-separated list of any valid expressions.
7100In addition to global, static, or local variables, the following
7101special arguments are supported:
7102
7103@table @code
7104@item $regs
7105collect all registers
7106
7107@item $args
7108collect all function arguments
7109
7110@item $locals
7111collect all local variables.
7112@end table
7113
7114You can give several consecutive @code{collect} commands, each one
7115with a single argument, or one @code{collect} command with several
7116arguments separated by commas: the effect is the same.
7117
f5c37c66
EZ
7118The command @code{info scope} (@pxref{Symbols, info scope}) is
7119particularly useful for figuring out what data to collect.
7120
b37052ae
EZ
7121@kindex while-stepping @r{(tracepoints)}
7122@item while-stepping @var{n}
7123Perform @var{n} single-step traces after the tracepoint, collecting
7124new data at each step. The @code{while-stepping} command is
7125followed by the list of what to collect while stepping (followed by
7126its own @code{end} command):
7127
7128@smallexample
7129> while-stepping 12
7130 > collect $regs, myglobal
7131 > end
7132>
7133@end smallexample
7134
7135@noindent
7136You may abbreviate @code{while-stepping} as @code{ws} or
7137@code{stepping}.
7138@end table
7139
7140@node Listing Tracepoints
7141@subsection Listing Tracepoints
7142
7143@table @code
7144@kindex info tracepoints
09d4efe1 7145@kindex info tp
b37052ae
EZ
7146@cindex information about tracepoints
7147@item info tracepoints @r{[}@var{num}@r{]}
8a037dd7 7148Display information about the tracepoint @var{num}. If you don't specify
798c8bc6 7149a tracepoint number, displays information about all the tracepoints
b37052ae
EZ
7150defined so far. For each tracepoint, the following information is
7151shown:
7152
7153@itemize @bullet
7154@item
7155its number
7156@item
7157whether it is enabled or disabled
7158@item
7159its address
7160@item
7161its passcount as given by the @code{passcount @var{n}} command
7162@item
7163its step count as given by the @code{while-stepping @var{n}} command
7164@item
7165where in the source files is the tracepoint set
7166@item
7167its action list as given by the @code{actions} command
7168@end itemize
7169
7170@smallexample
7171(@value{GDBP}) @b{info trace}
7172Num Enb Address PassC StepC What
71731 y 0x002117c4 0 0 <gdb_asm>
6826cf00
EZ
71742 y 0x0020dc64 0 0 in g_test at g_test.c:1375
71753 y 0x0020b1f4 0 0 in get_data at ../foo.c:41
b37052ae
EZ
7176(@value{GDBP})
7177@end smallexample
7178
7179@noindent
7180This command can be abbreviated @code{info tp}.
7181@end table
7182
7183@node Starting and Stopping Trace Experiment
7184@subsection Starting and Stopping Trace Experiment
7185
7186@table @code
7187@kindex tstart
7188@cindex start a new trace experiment
7189@cindex collected data discarded
7190@item tstart
7191This command takes no arguments. It starts the trace experiment, and
7192begins collecting data. This has the side effect of discarding all
7193the data collected in the trace buffer during the previous trace
7194experiment.
7195
7196@kindex tstop
7197@cindex stop a running trace experiment
7198@item tstop
7199This command takes no arguments. It ends the trace experiment, and
7200stops collecting data.
7201
68c71a2e 7202@strong{Note}: a trace experiment and data collection may stop
b37052ae
EZ
7203automatically if any tracepoint's passcount is reached
7204(@pxref{Tracepoint Passcounts}), or if the trace buffer becomes full.
7205
7206@kindex tstatus
7207@cindex status of trace data collection
7208@cindex trace experiment, status of
7209@item tstatus
7210This command displays the status of the current trace data
7211collection.
7212@end table
7213
7214Here is an example of the commands we described so far:
7215
7216@smallexample
7217(@value{GDBP}) @b{trace gdb_c_test}
7218(@value{GDBP}) @b{actions}
7219Enter actions for tracepoint #1, one per line.
7220> collect $regs,$locals,$args
7221> while-stepping 11
7222 > collect $regs
7223 > end
7224> end
7225(@value{GDBP}) @b{tstart}
7226 [time passes @dots{}]
7227(@value{GDBP}) @b{tstop}
7228@end smallexample
7229
7230
7231@node Analyze Collected Data
7232@section Using the collected data
7233
7234After the tracepoint experiment ends, you use @value{GDBN} commands
7235for examining the trace data. The basic idea is that each tracepoint
7236collects a trace @dfn{snapshot} every time it is hit and another
7237snapshot every time it single-steps. All these snapshots are
7238consecutively numbered from zero and go into a buffer, and you can
7239examine them later. The way you examine them is to @dfn{focus} on a
7240specific trace snapshot. When the remote stub is focused on a trace
7241snapshot, it will respond to all @value{GDBN} requests for memory and
7242registers by reading from the buffer which belongs to that snapshot,
7243rather than from @emph{real} memory or registers of the program being
7244debugged. This means that @strong{all} @value{GDBN} commands
7245(@code{print}, @code{info registers}, @code{backtrace}, etc.) will
7246behave as if we were currently debugging the program state as it was
7247when the tracepoint occurred. Any requests for data that are not in
7248the buffer will fail.
7249
7250@menu
7251* tfind:: How to select a trace snapshot
7252* tdump:: How to display all data for a snapshot
7253* save-tracepoints:: How to save tracepoints for a future run
7254@end menu
7255
7256@node tfind
7257@subsection @code{tfind @var{n}}
7258
7259@kindex tfind
7260@cindex select trace snapshot
7261@cindex find trace snapshot
7262The basic command for selecting a trace snapshot from the buffer is
7263@code{tfind @var{n}}, which finds trace snapshot number @var{n},
7264counting from zero. If no argument @var{n} is given, the next
7265snapshot is selected.
7266
7267Here are the various forms of using the @code{tfind} command.
7268
7269@table @code
7270@item tfind start
7271Find the first snapshot in the buffer. This is a synonym for
7272@code{tfind 0} (since 0 is the number of the first snapshot).
7273
7274@item tfind none
7275Stop debugging trace snapshots, resume @emph{live} debugging.
7276
7277@item tfind end
7278Same as @samp{tfind none}.
7279
7280@item tfind
7281No argument means find the next trace snapshot.
7282
7283@item tfind -
7284Find the previous trace snapshot before the current one. This permits
7285retracing earlier steps.
7286
7287@item tfind tracepoint @var{num}
7288Find the next snapshot associated with tracepoint @var{num}. Search
7289proceeds forward from the last examined trace snapshot. If no
7290argument @var{num} is given, it means find the next snapshot collected
7291for the same tracepoint as the current snapshot.
7292
7293@item tfind pc @var{addr}
7294Find the next snapshot associated with the value @var{addr} of the
7295program counter. Search proceeds forward from the last examined trace
7296snapshot. If no argument @var{addr} is given, it means find the next
7297snapshot with the same value of PC as the current snapshot.
7298
7299@item tfind outside @var{addr1}, @var{addr2}
7300Find the next snapshot whose PC is outside the given range of
7301addresses.
7302
7303@item tfind range @var{addr1}, @var{addr2}
7304Find the next snapshot whose PC is between @var{addr1} and
7305@var{addr2}. @c FIXME: Is the range inclusive or exclusive?
7306
7307@item tfind line @r{[}@var{file}:@r{]}@var{n}
7308Find the next snapshot associated with the source line @var{n}. If
7309the optional argument @var{file} is given, refer to line @var{n} in
7310that source file. Search proceeds forward from the last examined
7311trace snapshot. If no argument @var{n} is given, it means find the
7312next line other than the one currently being examined; thus saying
7313@code{tfind line} repeatedly can appear to have the same effect as
7314stepping from line to line in a @emph{live} debugging session.
7315@end table
7316
7317The default arguments for the @code{tfind} commands are specifically
7318designed to make it easy to scan through the trace buffer. For
7319instance, @code{tfind} with no argument selects the next trace
7320snapshot, and @code{tfind -} with no argument selects the previous
7321trace snapshot. So, by giving one @code{tfind} command, and then
7322simply hitting @key{RET} repeatedly you can examine all the trace
7323snapshots in order. Or, by saying @code{tfind -} and then hitting
7324@key{RET} repeatedly you can examine the snapshots in reverse order.
7325The @code{tfind line} command with no argument selects the snapshot
7326for the next source line executed. The @code{tfind pc} command with
7327no argument selects the next snapshot with the same program counter
7328(PC) as the current frame. The @code{tfind tracepoint} command with
7329no argument selects the next trace snapshot collected by the same
7330tracepoint as the current one.
7331
7332In addition to letting you scan through the trace buffer manually,
7333these commands make it easy to construct @value{GDBN} scripts that
7334scan through the trace buffer and print out whatever collected data
7335you are interested in. Thus, if we want to examine the PC, FP, and SP
7336registers from each trace frame in the buffer, we can say this:
7337
7338@smallexample
7339(@value{GDBP}) @b{tfind start}
7340(@value{GDBP}) @b{while ($trace_frame != -1)}
7341> printf "Frame %d, PC = %08X, SP = %08X, FP = %08X\n", \
7342 $trace_frame, $pc, $sp, $fp
7343> tfind
7344> end
7345
7346Frame 0, PC = 0020DC64, SP = 0030BF3C, FP = 0030BF44
7347Frame 1, PC = 0020DC6C, SP = 0030BF38, FP = 0030BF44
7348Frame 2, PC = 0020DC70, SP = 0030BF34, FP = 0030BF44
7349Frame 3, PC = 0020DC74, SP = 0030BF30, FP = 0030BF44
7350Frame 4, PC = 0020DC78, SP = 0030BF2C, FP = 0030BF44
7351Frame 5, PC = 0020DC7C, SP = 0030BF28, FP = 0030BF44
7352Frame 6, PC = 0020DC80, SP = 0030BF24, FP = 0030BF44
7353Frame 7, PC = 0020DC84, SP = 0030BF20, FP = 0030BF44
7354Frame 8, PC = 0020DC88, SP = 0030BF1C, FP = 0030BF44
7355Frame 9, PC = 0020DC8E, SP = 0030BF18, FP = 0030BF44
7356Frame 10, PC = 00203F6C, SP = 0030BE3C, FP = 0030BF14
7357@end smallexample
7358
7359Or, if we want to examine the variable @code{X} at each source line in
7360the buffer:
7361
7362@smallexample
7363(@value{GDBP}) @b{tfind start}
7364(@value{GDBP}) @b{while ($trace_frame != -1)}
7365> printf "Frame %d, X == %d\n", $trace_frame, X
7366> tfind line
7367> end
7368
7369Frame 0, X = 1
7370Frame 7, X = 2
7371Frame 13, X = 255
7372@end smallexample
7373
7374@node tdump
7375@subsection @code{tdump}
7376@kindex tdump
7377@cindex dump all data collected at tracepoint
7378@cindex tracepoint data, display
7379
7380This command takes no arguments. It prints all the data collected at
7381the current trace snapshot.
7382
7383@smallexample
7384(@value{GDBP}) @b{trace 444}
7385(@value{GDBP}) @b{actions}
7386Enter actions for tracepoint #2, one per line:
7387> collect $regs, $locals, $args, gdb_long_test
7388> end
7389
7390(@value{GDBP}) @b{tstart}
7391
7392(@value{GDBP}) @b{tfind line 444}
7393#0 gdb_test (p1=0x11, p2=0x22, p3=0x33, p4=0x44, p5=0x55, p6=0x66)
7394at gdb_test.c:444
7395444 printp( "%s: arguments = 0x%X 0x%X 0x%X 0x%X 0x%X 0x%X\n", )
7396
7397(@value{GDBP}) @b{tdump}
7398Data collected at tracepoint 2, trace frame 1:
7399d0 0xc4aa0085 -995491707
7400d1 0x18 24
7401d2 0x80 128
7402d3 0x33 51
7403d4 0x71aea3d 119204413
7404d5 0x22 34
7405d6 0xe0 224
7406d7 0x380035 3670069
7407a0 0x19e24a 1696330
7408a1 0x3000668 50333288
7409a2 0x100 256
7410a3 0x322000 3284992
7411a4 0x3000698 50333336
7412a5 0x1ad3cc 1758156
7413fp 0x30bf3c 0x30bf3c
7414sp 0x30bf34 0x30bf34
7415ps 0x0 0
7416pc 0x20b2c8 0x20b2c8
7417fpcontrol 0x0 0
7418fpstatus 0x0 0
7419fpiaddr 0x0 0
7420p = 0x20e5b4 "gdb-test"
7421p1 = (void *) 0x11
7422p2 = (void *) 0x22
7423p3 = (void *) 0x33
7424p4 = (void *) 0x44
7425p5 = (void *) 0x55
7426p6 = (void *) 0x66
7427gdb_long_test = 17 '\021'
7428
7429(@value{GDBP})
7430@end smallexample
7431
7432@node save-tracepoints
7433@subsection @code{save-tracepoints @var{filename}}
7434@kindex save-tracepoints
7435@cindex save tracepoints for future sessions
7436
7437This command saves all current tracepoint definitions together with
7438their actions and passcounts, into a file @file{@var{filename}}
7439suitable for use in a later debugging session. To read the saved
7440tracepoint definitions, use the @code{source} command (@pxref{Command
7441Files}).
7442
7443@node Tracepoint Variables
7444@section Convenience Variables for Tracepoints
7445@cindex tracepoint variables
7446@cindex convenience variables for tracepoints
7447
7448@table @code
7449@vindex $trace_frame
7450@item (int) $trace_frame
7451The current trace snapshot (a.k.a.@: @dfn{frame}) number, or -1 if no
7452snapshot is selected.
7453
7454@vindex $tracepoint
7455@item (int) $tracepoint
7456The tracepoint for the current trace snapshot.
7457
7458@vindex $trace_line
7459@item (int) $trace_line
7460The line number for the current trace snapshot.
7461
7462@vindex $trace_file
7463@item (char []) $trace_file
7464The source file for the current trace snapshot.
7465
7466@vindex $trace_func
7467@item (char []) $trace_func
7468The name of the function containing @code{$tracepoint}.
7469@end table
7470
7471Note: @code{$trace_file} is not suitable for use in @code{printf},
7472use @code{output} instead.
7473
7474Here's a simple example of using these convenience variables for
7475stepping through all the trace snapshots and printing some of their
7476data.
7477
7478@smallexample
7479(@value{GDBP}) @b{tfind start}
7480
7481(@value{GDBP}) @b{while $trace_frame != -1}
7482> output $trace_file
7483> printf ", line %d (tracepoint #%d)\n", $trace_line, $tracepoint
7484> tfind
7485> end
7486@end smallexample
7487
df0cd8c5
JB
7488@node Overlays
7489@chapter Debugging Programs That Use Overlays
7490@cindex overlays
7491
7492If your program is too large to fit completely in your target system's
7493memory, you can sometimes use @dfn{overlays} to work around this
7494problem. @value{GDBN} provides some support for debugging programs that
7495use overlays.
7496
7497@menu
7498* How Overlays Work:: A general explanation of overlays.
7499* Overlay Commands:: Managing overlays in @value{GDBN}.
7500* Automatic Overlay Debugging:: @value{GDBN} can find out which overlays are
7501 mapped by asking the inferior.
7502* Overlay Sample Program:: A sample program using overlays.
7503@end menu
7504
7505@node How Overlays Work
7506@section How Overlays Work
7507@cindex mapped overlays
7508@cindex unmapped overlays
7509@cindex load address, overlay's
7510@cindex mapped address
7511@cindex overlay area
7512
7513Suppose you have a computer whose instruction address space is only 64
7514kilobytes long, but which has much more memory which can be accessed by
7515other means: special instructions, segment registers, or memory
7516management hardware, for example. Suppose further that you want to
7517adapt a program which is larger than 64 kilobytes to run on this system.
7518
7519One solution is to identify modules of your program which are relatively
7520independent, and need not call each other directly; call these modules
7521@dfn{overlays}. Separate the overlays from the main program, and place
7522their machine code in the larger memory. Place your main program in
7523instruction memory, but leave at least enough space there to hold the
7524largest overlay as well.
7525
7526Now, to call a function located in an overlay, you must first copy that
7527overlay's machine code from the large memory into the space set aside
7528for it in the instruction memory, and then jump to its entry point
7529there.
7530
c928edc0
AC
7531@c NB: In the below the mapped area's size is greater or equal to the
7532@c size of all overlays. This is intentional to remind the developer
7533@c that overlays don't necessarily need to be the same size.
7534
474c8240 7535@smallexample
df0cd8c5 7536@group
c928edc0
AC
7537 Data Instruction Larger
7538Address Space Address Space Address Space
7539+-----------+ +-----------+ +-----------+
7540| | | | | |
7541+-----------+ +-----------+ +-----------+<-- overlay 1
7542| program | | main | .----| overlay 1 | load address
7543| variables | | program | | +-----------+
7544| and heap | | | | | |
7545+-----------+ | | | +-----------+<-- overlay 2
7546| | +-----------+ | | | load address
7547+-----------+ | | | .-| overlay 2 |
7548 | | | | | |
7549 mapped --->+-----------+ | | +-----------+
7550 address | | | | | |
7551 | overlay | <-' | | |
7552 | area | <---' +-----------+<-- overlay 3
7553 | | <---. | | load address
7554 +-----------+ `--| overlay 3 |
7555 | | | |
7556 +-----------+ | |
7557 +-----------+
7558 | |
7559 +-----------+
7560
7561 @anchor{A code overlay}A code overlay
df0cd8c5 7562@end group
474c8240 7563@end smallexample
df0cd8c5 7564
c928edc0
AC
7565The diagram (@pxref{A code overlay}) shows a system with separate data
7566and instruction address spaces. To map an overlay, the program copies
7567its code from the larger address space to the instruction address space.
7568Since the overlays shown here all use the same mapped address, only one
7569may be mapped at a time. For a system with a single address space for
7570data and instructions, the diagram would be similar, except that the
7571program variables and heap would share an address space with the main
7572program and the overlay area.
df0cd8c5
JB
7573
7574An overlay loaded into instruction memory and ready for use is called a
7575@dfn{mapped} overlay; its @dfn{mapped address} is its address in the
7576instruction memory. An overlay not present (or only partially present)
7577in instruction memory is called @dfn{unmapped}; its @dfn{load address}
7578is its address in the larger memory. The mapped address is also called
7579the @dfn{virtual memory address}, or @dfn{VMA}; the load address is also
7580called the @dfn{load memory address}, or @dfn{LMA}.
7581
7582Unfortunately, overlays are not a completely transparent way to adapt a
7583program to limited instruction memory. They introduce a new set of
7584global constraints you must keep in mind as you design your program:
7585
7586@itemize @bullet
7587
7588@item
7589Before calling or returning to a function in an overlay, your program
7590must make sure that overlay is actually mapped. Otherwise, the call or
7591return will transfer control to the right address, but in the wrong
7592overlay, and your program will probably crash.
7593
7594@item
7595If the process of mapping an overlay is expensive on your system, you
7596will need to choose your overlays carefully to minimize their effect on
7597your program's performance.
7598
7599@item
7600The executable file you load onto your system must contain each
7601overlay's instructions, appearing at the overlay's load address, not its
7602mapped address. However, each overlay's instructions must be relocated
7603and its symbols defined as if the overlay were at its mapped address.
7604You can use GNU linker scripts to specify different load and relocation
7605addresses for pieces of your program; see @ref{Overlay Description,,,
7606ld.info, Using ld: the GNU linker}.
7607
7608@item
7609The procedure for loading executable files onto your system must be able
7610to load their contents into the larger address space as well as the
7611instruction and data spaces.
7612
7613@end itemize
7614
7615The overlay system described above is rather simple, and could be
7616improved in many ways:
7617
7618@itemize @bullet
7619
7620@item
7621If your system has suitable bank switch registers or memory management
7622hardware, you could use those facilities to make an overlay's load area
7623contents simply appear at their mapped address in instruction space.
7624This would probably be faster than copying the overlay to its mapped
7625area in the usual way.
7626
7627@item
7628If your overlays are small enough, you could set aside more than one
7629overlay area, and have more than one overlay mapped at a time.
7630
7631@item
7632You can use overlays to manage data, as well as instructions. In
7633general, data overlays are even less transparent to your design than
7634code overlays: whereas code overlays only require care when you call or
7635return to functions, data overlays require care every time you access
7636the data. Also, if you change the contents of a data overlay, you
7637must copy its contents back out to its load address before you can copy a
7638different data overlay into the same mapped area.
7639
7640@end itemize
7641
7642
7643@node Overlay Commands
7644@section Overlay Commands
7645
7646To use @value{GDBN}'s overlay support, each overlay in your program must
7647correspond to a separate section of the executable file. The section's
7648virtual memory address and load memory address must be the overlay's
7649mapped and load addresses. Identifying overlays with sections allows
7650@value{GDBN} to determine the appropriate address of a function or
7651variable, depending on whether the overlay is mapped or not.
7652
7653@value{GDBN}'s overlay commands all start with the word @code{overlay};
7654you can abbreviate this as @code{ov} or @code{ovly}. The commands are:
7655
7656@table @code
7657@item overlay off
4644b6e3 7658@kindex overlay
df0cd8c5
JB
7659Disable @value{GDBN}'s overlay support. When overlay support is
7660disabled, @value{GDBN} assumes that all functions and variables are
7661always present at their mapped addresses. By default, @value{GDBN}'s
7662overlay support is disabled.
7663
7664@item overlay manual
df0cd8c5
JB
7665@cindex manual overlay debugging
7666Enable @dfn{manual} overlay debugging. In this mode, @value{GDBN}
7667relies on you to tell it which overlays are mapped, and which are not,
7668using the @code{overlay map-overlay} and @code{overlay unmap-overlay}
7669commands described below.
7670
7671@item overlay map-overlay @var{overlay}
7672@itemx overlay map @var{overlay}
df0cd8c5
JB
7673@cindex map an overlay
7674Tell @value{GDBN} that @var{overlay} is now mapped; @var{overlay} must
7675be the name of the object file section containing the overlay. When an
7676overlay is mapped, @value{GDBN} assumes it can find the overlay's
7677functions and variables at their mapped addresses. @value{GDBN} assumes
7678that any other overlays whose mapped ranges overlap that of
7679@var{overlay} are now unmapped.
7680
7681@item overlay unmap-overlay @var{overlay}
7682@itemx overlay unmap @var{overlay}
df0cd8c5
JB
7683@cindex unmap an overlay
7684Tell @value{GDBN} that @var{overlay} is no longer mapped; @var{overlay}
7685must be the name of the object file section containing the overlay.
7686When an overlay is unmapped, @value{GDBN} assumes it can find the
7687overlay's functions and variables at their load addresses.
7688
7689@item overlay auto
df0cd8c5
JB
7690Enable @dfn{automatic} overlay debugging. In this mode, @value{GDBN}
7691consults a data structure the overlay manager maintains in the inferior
7692to see which overlays are mapped. For details, see @ref{Automatic
7693Overlay Debugging}.
7694
7695@item overlay load-target
7696@itemx overlay load
df0cd8c5
JB
7697@cindex reloading the overlay table
7698Re-read the overlay table from the inferior. Normally, @value{GDBN}
7699re-reads the table @value{GDBN} automatically each time the inferior
7700stops, so this command should only be necessary if you have changed the
7701overlay mapping yourself using @value{GDBN}. This command is only
7702useful when using automatic overlay debugging.
7703
7704@item overlay list-overlays
7705@itemx overlay list
7706@cindex listing mapped overlays
7707Display a list of the overlays currently mapped, along with their mapped
7708addresses, load addresses, and sizes.
7709
7710@end table
7711
7712Normally, when @value{GDBN} prints a code address, it includes the name
7713of the function the address falls in:
7714
474c8240 7715@smallexample
f7dc1244 7716(@value{GDBP}) print main
df0cd8c5 7717$3 = @{int ()@} 0x11a0 <main>
474c8240 7718@end smallexample
df0cd8c5
JB
7719@noindent
7720When overlay debugging is enabled, @value{GDBN} recognizes code in
7721unmapped overlays, and prints the names of unmapped functions with
7722asterisks around them. For example, if @code{foo} is a function in an
7723unmapped overlay, @value{GDBN} prints it this way:
7724
474c8240 7725@smallexample
f7dc1244 7726(@value{GDBP}) overlay list
df0cd8c5 7727No sections are mapped.
f7dc1244 7728(@value{GDBP}) print foo
df0cd8c5 7729$5 = @{int (int)@} 0x100000 <*foo*>
474c8240 7730@end smallexample
df0cd8c5
JB
7731@noindent
7732When @code{foo}'s overlay is mapped, @value{GDBN} prints the function's
7733name normally:
7734
474c8240 7735@smallexample
f7dc1244 7736(@value{GDBP}) overlay list
b383017d 7737Section .ov.foo.text, loaded at 0x100000 - 0x100034,
df0cd8c5 7738 mapped at 0x1016 - 0x104a
f7dc1244 7739(@value{GDBP}) print foo
df0cd8c5 7740$6 = @{int (int)@} 0x1016 <foo>
474c8240 7741@end smallexample
df0cd8c5
JB
7742
7743When overlay debugging is enabled, @value{GDBN} can find the correct
7744address for functions and variables in an overlay, whether or not the
7745overlay is mapped. This allows most @value{GDBN} commands, like
7746@code{break} and @code{disassemble}, to work normally, even on unmapped
7747code. However, @value{GDBN}'s breakpoint support has some limitations:
7748
7749@itemize @bullet
7750@item
7751@cindex breakpoints in overlays
7752@cindex overlays, setting breakpoints in
7753You can set breakpoints in functions in unmapped overlays, as long as
7754@value{GDBN} can write to the overlay at its load address.
7755@item
7756@value{GDBN} can not set hardware or simulator-based breakpoints in
7757unmapped overlays. However, if you set a breakpoint at the end of your
7758overlay manager (and tell @value{GDBN} which overlays are now mapped, if
7759you are using manual overlay management), @value{GDBN} will re-set its
7760breakpoints properly.
7761@end itemize
7762
7763
7764@node Automatic Overlay Debugging
7765@section Automatic Overlay Debugging
7766@cindex automatic overlay debugging
7767
7768@value{GDBN} can automatically track which overlays are mapped and which
7769are not, given some simple co-operation from the overlay manager in the
7770inferior. If you enable automatic overlay debugging with the
7771@code{overlay auto} command (@pxref{Overlay Commands}), @value{GDBN}
7772looks in the inferior's memory for certain variables describing the
7773current state of the overlays.
7774
7775Here are the variables your overlay manager must define to support
7776@value{GDBN}'s automatic overlay debugging:
7777
7778@table @asis
7779
7780@item @code{_ovly_table}:
7781This variable must be an array of the following structures:
7782
474c8240 7783@smallexample
df0cd8c5
JB
7784struct
7785@{
7786 /* The overlay's mapped address. */
7787 unsigned long vma;
7788
7789 /* The size of the overlay, in bytes. */
7790 unsigned long size;
7791
7792 /* The overlay's load address. */
7793 unsigned long lma;
7794
7795 /* Non-zero if the overlay is currently mapped;
7796 zero otherwise. */
7797 unsigned long mapped;
7798@}
474c8240 7799@end smallexample
df0cd8c5
JB
7800
7801@item @code{_novlys}:
7802This variable must be a four-byte signed integer, holding the total
7803number of elements in @code{_ovly_table}.
7804
7805@end table
7806
7807To decide whether a particular overlay is mapped or not, @value{GDBN}
7808looks for an entry in @w{@code{_ovly_table}} whose @code{vma} and
7809@code{lma} members equal the VMA and LMA of the overlay's section in the
7810executable file. When @value{GDBN} finds a matching entry, it consults
7811the entry's @code{mapped} member to determine whether the overlay is
7812currently mapped.
7813
81d46470 7814In addition, your overlay manager may define a function called
def71bfa 7815@code{_ovly_debug_event}. If this function is defined, @value{GDBN}
81d46470
MS
7816will silently set a breakpoint there. If the overlay manager then
7817calls this function whenever it has changed the overlay table, this
7818will enable @value{GDBN} to accurately keep track of which overlays
7819are in program memory, and update any breakpoints that may be set
b383017d 7820in overlays. This will allow breakpoints to work even if the
81d46470
MS
7821overlays are kept in ROM or other non-writable memory while they
7822are not being executed.
df0cd8c5
JB
7823
7824@node Overlay Sample Program
7825@section Overlay Sample Program
7826@cindex overlay example program
7827
7828When linking a program which uses overlays, you must place the overlays
7829at their load addresses, while relocating them to run at their mapped
7830addresses. To do this, you must write a linker script (@pxref{Overlay
7831Description,,, ld.info, Using ld: the GNU linker}). Unfortunately,
7832since linker scripts are specific to a particular host system, target
7833architecture, and target memory layout, this manual cannot provide
7834portable sample code demonstrating @value{GDBN}'s overlay support.
7835
7836However, the @value{GDBN} source distribution does contain an overlaid
7837program, with linker scripts for a few systems, as part of its test
7838suite. The program consists of the following files from
7839@file{gdb/testsuite/gdb.base}:
7840
7841@table @file
7842@item overlays.c
7843The main program file.
7844@item ovlymgr.c
7845A simple overlay manager, used by @file{overlays.c}.
7846@item foo.c
7847@itemx bar.c
7848@itemx baz.c
7849@itemx grbx.c
7850Overlay modules, loaded and used by @file{overlays.c}.
7851@item d10v.ld
7852@itemx m32r.ld
7853Linker scripts for linking the test program on the @code{d10v-elf}
7854and @code{m32r-elf} targets.
7855@end table
7856
7857You can build the test program using the @code{d10v-elf} GCC
7858cross-compiler like this:
7859
474c8240 7860@smallexample
df0cd8c5
JB
7861$ d10v-elf-gcc -g -c overlays.c
7862$ d10v-elf-gcc -g -c ovlymgr.c
7863$ d10v-elf-gcc -g -c foo.c
7864$ d10v-elf-gcc -g -c bar.c
7865$ d10v-elf-gcc -g -c baz.c
7866$ d10v-elf-gcc -g -c grbx.c
7867$ d10v-elf-gcc -g overlays.o ovlymgr.o foo.o bar.o \
7868 baz.o grbx.o -Wl,-Td10v.ld -o overlays
474c8240 7869@end smallexample
df0cd8c5
JB
7870
7871The build process is identical for any other architecture, except that
7872you must substitute the appropriate compiler and linker script for the
7873target system for @code{d10v-elf-gcc} and @code{d10v.ld}.
7874
7875
6d2ebf8b 7876@node Languages
c906108c
SS
7877@chapter Using @value{GDBN} with Different Languages
7878@cindex languages
7879
c906108c
SS
7880Although programming languages generally have common aspects, they are
7881rarely expressed in the same manner. For instance, in ANSI C,
7882dereferencing a pointer @code{p} is accomplished by @code{*p}, but in
7883Modula-2, it is accomplished by @code{p^}. Values can also be
5d161b24 7884represented (and displayed) differently. Hex numbers in C appear as
c906108c 7885@samp{0x1ae}, while in Modula-2 they appear as @samp{1AEH}.
c906108c
SS
7886
7887@cindex working language
7888Language-specific information is built into @value{GDBN} for some languages,
7889allowing you to express operations like the above in your program's
7890native language, and allowing @value{GDBN} to output values in a manner
7891consistent with the syntax of your program's native language. The
7892language you use to build expressions is called the @dfn{working
7893language}.
7894
7895@menu
7896* Setting:: Switching between source languages
7897* Show:: Displaying the language
c906108c 7898* Checks:: Type and range checks
9c16f35a 7899* Supported languages:: Supported languages
4e562065 7900* Unsupported languages:: Unsupported languages
c906108c
SS
7901@end menu
7902
6d2ebf8b 7903@node Setting
c906108c
SS
7904@section Switching between source languages
7905
7906There are two ways to control the working language---either have @value{GDBN}
7907set it automatically, or select it manually yourself. You can use the
7908@code{set language} command for either purpose. On startup, @value{GDBN}
7909defaults to setting the language automatically. The working language is
7910used to determine how expressions you type are interpreted, how values
7911are printed, etc.
7912
7913In addition to the working language, every source file that
7914@value{GDBN} knows about has its own working language. For some object
7915file formats, the compiler might indicate which language a particular
7916source file is in. However, most of the time @value{GDBN} infers the
7917language from the name of the file. The language of a source file
b37052ae 7918controls whether C@t{++} names are demangled---this way @code{backtrace} can
c906108c 7919show each frame appropriately for its own language. There is no way to
d4f3574e
SS
7920set the language of a source file from within @value{GDBN}, but you can
7921set the language associated with a filename extension. @xref{Show, ,
7922Displaying the language}.
c906108c
SS
7923
7924This is most commonly a problem when you use a program, such
5d161b24 7925as @code{cfront} or @code{f2c}, that generates C but is written in
c906108c
SS
7926another language. In that case, make the
7927program use @code{#line} directives in its C output; that way
7928@value{GDBN} will know the correct language of the source code of the original
7929program, and will display that source code, not the generated C code.
7930
7931@menu
7932* Filenames:: Filename extensions and languages.
7933* Manually:: Setting the working language manually
7934* Automatically:: Having @value{GDBN} infer the source language
7935@end menu
7936
6d2ebf8b 7937@node Filenames
c906108c
SS
7938@subsection List of filename extensions and languages
7939
7940If a source file name ends in one of the following extensions, then
7941@value{GDBN} infers that its language is the one indicated.
7942
7943@table @file
e07c999f
PH
7944@item .ada
7945@itemx .ads
7946@itemx .adb
7947@itemx .a
7948Ada source file.
c906108c
SS
7949
7950@item .c
7951C source file
7952
7953@item .C
7954@itemx .cc
7955@itemx .cp
7956@itemx .cpp
7957@itemx .cxx
7958@itemx .c++
b37052ae 7959C@t{++} source file
c906108c 7960
b37303ee
AF
7961@item .m
7962Objective-C source file
7963
c906108c
SS
7964@item .f
7965@itemx .F
7966Fortran source file
7967
c906108c
SS
7968@item .mod
7969Modula-2 source file
c906108c
SS
7970
7971@item .s
7972@itemx .S
7973Assembler source file. This actually behaves almost like C, but
7974@value{GDBN} does not skip over function prologues when stepping.
7975@end table
7976
7977In addition, you may set the language associated with a filename
7978extension. @xref{Show, , Displaying the language}.
7979
6d2ebf8b 7980@node Manually
c906108c
SS
7981@subsection Setting the working language
7982
7983If you allow @value{GDBN} to set the language automatically,
7984expressions are interpreted the same way in your debugging session and
7985your program.
7986
7987@kindex set language
7988If you wish, you may set the language manually. To do this, issue the
7989command @samp{set language @var{lang}}, where @var{lang} is the name of
5d161b24 7990a language, such as
c906108c 7991@code{c} or @code{modula-2}.
c906108c
SS
7992For a list of the supported languages, type @samp{set language}.
7993
c906108c
SS
7994Setting the language manually prevents @value{GDBN} from updating the working
7995language automatically. This can lead to confusion if you try
7996to debug a program when the working language is not the same as the
7997source language, when an expression is acceptable to both
7998languages---but means different things. For instance, if the current
7999source file were written in C, and @value{GDBN} was parsing Modula-2, a
8000command such as:
8001
474c8240 8002@smallexample
c906108c 8003print a = b + c
474c8240 8004@end smallexample
c906108c
SS
8005
8006@noindent
8007might not have the effect you intended. In C, this means to add
8008@code{b} and @code{c} and place the result in @code{a}. The result
8009printed would be the value of @code{a}. In Modula-2, this means to compare
8010@code{a} to the result of @code{b+c}, yielding a @code{BOOLEAN} value.
c906108c 8011
6d2ebf8b 8012@node Automatically
c906108c
SS
8013@subsection Having @value{GDBN} infer the source language
8014
8015To have @value{GDBN} set the working language automatically, use
8016@samp{set language local} or @samp{set language auto}. @value{GDBN}
8017then infers the working language. That is, when your program stops in a
8018frame (usually by encountering a breakpoint), @value{GDBN} sets the
8019working language to the language recorded for the function in that
8020frame. If the language for a frame is unknown (that is, if the function
8021or block corresponding to the frame was defined in a source file that
8022does not have a recognized extension), the current working language is
8023not changed, and @value{GDBN} issues a warning.
8024
8025This may not seem necessary for most programs, which are written
8026entirely in one source language. However, program modules and libraries
8027written in one source language can be used by a main program written in
8028a different source language. Using @samp{set language auto} in this
8029case frees you from having to set the working language manually.
8030
6d2ebf8b 8031@node Show
c906108c 8032@section Displaying the language
c906108c
SS
8033
8034The following commands help you find out which language is the
8035working language, and also what language source files were written in.
8036
c906108c
SS
8037@table @code
8038@item show language
9c16f35a 8039@kindex show language
c906108c
SS
8040Display the current working language. This is the
8041language you can use with commands such as @code{print} to
8042build and compute expressions that may involve variables in your program.
8043
8044@item info frame
4644b6e3 8045@kindex info frame@r{, show the source language}
5d161b24 8046Display the source language for this frame. This language becomes the
c906108c 8047working language if you use an identifier from this frame.
5d161b24 8048@xref{Frame Info, ,Information about a frame}, to identify the other
c906108c
SS
8049information listed here.
8050
8051@item info source
4644b6e3 8052@kindex info source@r{, show the source language}
c906108c 8053Display the source language of this source file.
5d161b24 8054@xref{Symbols, ,Examining the Symbol Table}, to identify the other
c906108c
SS
8055information listed here.
8056@end table
8057
8058In unusual circumstances, you may have source files with extensions
8059not in the standard list. You can then set the extension associated
8060with a language explicitly:
8061
c906108c 8062@table @code
09d4efe1 8063@item set extension-language @var{ext} @var{language}
9c16f35a 8064@kindex set extension-language
09d4efe1
EZ
8065Tell @value{GDBN} that source files with extension @var{ext} are to be
8066assumed as written in the source language @var{language}.
c906108c
SS
8067
8068@item info extensions
9c16f35a 8069@kindex info extensions
c906108c
SS
8070List all the filename extensions and the associated languages.
8071@end table
8072
6d2ebf8b 8073@node Checks
c906108c
SS
8074@section Type and range checking
8075
8076@quotation
8077@emph{Warning:} In this release, the @value{GDBN} commands for type and range
8078checking are included, but they do not yet have any effect. This
8079section documents the intended facilities.
8080@end quotation
8081@c FIXME remove warning when type/range code added
8082
8083Some languages are designed to guard you against making seemingly common
8084errors through a series of compile- and run-time checks. These include
8085checking the type of arguments to functions and operators, and making
8086sure mathematical overflows are caught at run time. Checks such as
8087these help to ensure a program's correctness once it has been compiled
8088by eliminating type mismatches, and providing active checks for range
8089errors when your program is running.
8090
8091@value{GDBN} can check for conditions like the above if you wish.
9c16f35a
EZ
8092Although @value{GDBN} does not check the statements in your program,
8093it can check expressions entered directly into @value{GDBN} for
8094evaluation via the @code{print} command, for example. As with the
8095working language, @value{GDBN} can also decide whether or not to check
8096automatically based on your program's source language.
8097@xref{Supported languages, ,Supported languages}, for the default
8098settings of supported languages.
c906108c
SS
8099
8100@menu
8101* Type Checking:: An overview of type checking
8102* Range Checking:: An overview of range checking
8103@end menu
8104
8105@cindex type checking
8106@cindex checks, type
6d2ebf8b 8107@node Type Checking
c906108c
SS
8108@subsection An overview of type checking
8109
8110Some languages, such as Modula-2, are strongly typed, meaning that the
8111arguments to operators and functions have to be of the correct type,
8112otherwise an error occurs. These checks prevent type mismatch
8113errors from ever causing any run-time problems. For example,
8114
8115@smallexample
81161 + 2 @result{} 3
8117@exdent but
8118@error{} 1 + 2.3
8119@end smallexample
8120
8121The second example fails because the @code{CARDINAL} 1 is not
8122type-compatible with the @code{REAL} 2.3.
8123
5d161b24
DB
8124For the expressions you use in @value{GDBN} commands, you can tell the
8125@value{GDBN} type checker to skip checking;
8126to treat any mismatches as errors and abandon the expression;
8127or to only issue warnings when type mismatches occur,
c906108c
SS
8128but evaluate the expression anyway. When you choose the last of
8129these, @value{GDBN} evaluates expressions like the second example above, but
8130also issues a warning.
8131
5d161b24
DB
8132Even if you turn type checking off, there may be other reasons
8133related to type that prevent @value{GDBN} from evaluating an expression.
8134For instance, @value{GDBN} does not know how to add an @code{int} and
8135a @code{struct foo}. These particular type errors have nothing to do
8136with the language in use, and usually arise from expressions, such as
c906108c
SS
8137the one described above, which make little sense to evaluate anyway.
8138
8139Each language defines to what degree it is strict about type. For
8140instance, both Modula-2 and C require the arguments to arithmetical
8141operators to be numbers. In C, enumerated types and pointers can be
8142represented as numbers, so that they are valid arguments to mathematical
9c16f35a 8143operators. @xref{Supported languages, ,Supported languages}, for further
c906108c
SS
8144details on specific languages.
8145
8146@value{GDBN} provides some additional commands for controlling the type checker:
8147
c906108c
SS
8148@kindex set check type
8149@kindex show check type
8150@table @code
8151@item set check type auto
8152Set type checking on or off based on the current working language.
9c16f35a 8153@xref{Supported languages, ,Supported languages}, for the default settings for
c906108c
SS
8154each language.
8155
8156@item set check type on
8157@itemx set check type off
8158Set type checking on or off, overriding the default setting for the
8159current working language. Issue a warning if the setting does not
8160match the language default. If any type mismatches occur in
d4f3574e 8161evaluating an expression while type checking is on, @value{GDBN} prints a
c906108c
SS
8162message and aborts evaluation of the expression.
8163
8164@item set check type warn
8165Cause the type checker to issue warnings, but to always attempt to
8166evaluate the expression. Evaluating the expression may still
8167be impossible for other reasons. For example, @value{GDBN} cannot add
8168numbers and structures.
8169
8170@item show type
5d161b24 8171Show the current setting of the type checker, and whether or not @value{GDBN}
c906108c
SS
8172is setting it automatically.
8173@end table
8174
8175@cindex range checking
8176@cindex checks, range
6d2ebf8b 8177@node Range Checking
c906108c
SS
8178@subsection An overview of range checking
8179
8180In some languages (such as Modula-2), it is an error to exceed the
8181bounds of a type; this is enforced with run-time checks. Such range
8182checking is meant to ensure program correctness by making sure
8183computations do not overflow, or indices on an array element access do
8184not exceed the bounds of the array.
8185
8186For expressions you use in @value{GDBN} commands, you can tell
8187@value{GDBN} to treat range errors in one of three ways: ignore them,
8188always treat them as errors and abandon the expression, or issue
8189warnings but evaluate the expression anyway.
8190
8191A range error can result from numerical overflow, from exceeding an
8192array index bound, or when you type a constant that is not a member
8193of any type. Some languages, however, do not treat overflows as an
8194error. In many implementations of C, mathematical overflow causes the
8195result to ``wrap around'' to lower values---for example, if @var{m} is
8196the largest integer value, and @var{s} is the smallest, then
8197
474c8240 8198@smallexample
c906108c 8199@var{m} + 1 @result{} @var{s}
474c8240 8200@end smallexample
c906108c
SS
8201
8202This, too, is specific to individual languages, and in some cases
9c16f35a 8203specific to individual compilers or machines. @xref{Supported languages, ,
c906108c
SS
8204Supported languages}, for further details on specific languages.
8205
8206@value{GDBN} provides some additional commands for controlling the range checker:
8207
c906108c
SS
8208@kindex set check range
8209@kindex show check range
8210@table @code
8211@item set check range auto
8212Set range checking on or off based on the current working language.
9c16f35a 8213@xref{Supported languages, ,Supported languages}, for the default settings for
c906108c
SS
8214each language.
8215
8216@item set check range on
8217@itemx set check range off
8218Set range checking on or off, overriding the default setting for the
8219current working language. A warning is issued if the setting does not
c3f6f71d
JM
8220match the language default. If a range error occurs and range checking is on,
8221then a message is printed and evaluation of the expression is aborted.
c906108c
SS
8222
8223@item set check range warn
8224Output messages when the @value{GDBN} range checker detects a range error,
8225but attempt to evaluate the expression anyway. Evaluating the
8226expression may still be impossible for other reasons, such as accessing
8227memory that the process does not own (a typical example from many Unix
8228systems).
8229
8230@item show range
8231Show the current setting of the range checker, and whether or not it is
8232being set automatically by @value{GDBN}.
8233@end table
c906108c 8234
9c16f35a 8235@node Supported languages
c906108c 8236@section Supported languages
c906108c 8237
9c16f35a
EZ
8238@value{GDBN} supports C, C@t{++}, Objective-C, Fortran, Java, Pascal,
8239assembly, Modula-2, and Ada.
cce74817 8240@c This is false ...
c906108c
SS
8241Some @value{GDBN} features may be used in expressions regardless of the
8242language you use: the @value{GDBN} @code{@@} and @code{::} operators,
8243and the @samp{@{type@}addr} construct (@pxref{Expressions,
8244,Expressions}) can be used with the constructs of any supported
8245language.
8246
8247The following sections detail to what degree each source language is
8248supported by @value{GDBN}. These sections are not meant to be language
8249tutorials or references, but serve only as a reference guide to what the
8250@value{GDBN} expression parser accepts, and what input and output
8251formats should look like for different languages. There are many good
8252books written on each of these languages; please look to these for a
8253language reference or tutorial.
8254
c906108c 8255@menu
b37303ee 8256* C:: C and C@t{++}
b383017d 8257* Objective-C:: Objective-C
09d4efe1 8258* Fortran:: Fortran
9c16f35a 8259* Pascal:: Pascal
b37303ee 8260* Modula-2:: Modula-2
e07c999f 8261* Ada:: Ada
c906108c
SS
8262@end menu
8263
6d2ebf8b 8264@node C
b37052ae 8265@subsection C and C@t{++}
7a292a7a 8266
b37052ae
EZ
8267@cindex C and C@t{++}
8268@cindex expressions in C or C@t{++}
c906108c 8269
b37052ae 8270Since C and C@t{++} are so closely related, many features of @value{GDBN} apply
c906108c
SS
8271to both languages. Whenever this is the case, we discuss those languages
8272together.
8273
41afff9a
EZ
8274@cindex C@t{++}
8275@cindex @code{g++}, @sc{gnu} C@t{++} compiler
b37052ae
EZ
8276@cindex @sc{gnu} C@t{++}
8277The C@t{++} debugging facilities are jointly implemented by the C@t{++}
8278compiler and @value{GDBN}. Therefore, to debug your C@t{++} code
8279effectively, you must compile your C@t{++} programs with a supported
8280C@t{++} compiler, such as @sc{gnu} @code{g++}, or the HP ANSI C@t{++}
c906108c
SS
8281compiler (@code{aCC}).
8282
0179ffac
DC
8283For best results when using @sc{gnu} C@t{++}, use the DWARF 2 debugging
8284format; if it doesn't work on your system, try the stabs+ debugging
8285format. You can select those formats explicitly with the @code{g++}
8286command-line options @option{-gdwarf-2} and @option{-gstabs+}.
8287@xref{Debugging Options,,Options for Debugging Your Program or @sc{gnu}
8288CC, gcc.info, Using @sc{gnu} CC}.
c906108c 8289
c906108c 8290@menu
b37052ae
EZ
8291* C Operators:: C and C@t{++} operators
8292* C Constants:: C and C@t{++} constants
8293* C plus plus expressions:: C@t{++} expressions
8294* C Defaults:: Default settings for C and C@t{++}
8295* C Checks:: C and C@t{++} type and range checks
c906108c 8296* Debugging C:: @value{GDBN} and C
b37052ae 8297* Debugging C plus plus:: @value{GDBN} features for C@t{++}
c906108c 8298@end menu
c906108c 8299
6d2ebf8b 8300@node C Operators
b37052ae 8301@subsubsection C and C@t{++} operators
7a292a7a 8302
b37052ae 8303@cindex C and C@t{++} operators
c906108c
SS
8304
8305Operators must be defined on values of specific types. For instance,
8306@code{+} is defined on numbers, but not on structures. Operators are
5d161b24 8307often defined on groups of types.
c906108c 8308
b37052ae 8309For the purposes of C and C@t{++}, the following definitions hold:
c906108c
SS
8310
8311@itemize @bullet
53a5351d 8312
c906108c 8313@item
c906108c 8314@emph{Integral types} include @code{int} with any of its storage-class
b37052ae 8315specifiers; @code{char}; @code{enum}; and, for C@t{++}, @code{bool}.
c906108c
SS
8316
8317@item
d4f3574e
SS
8318@emph{Floating-point types} include @code{float}, @code{double}, and
8319@code{long double} (if supported by the target platform).
c906108c
SS
8320
8321@item
53a5351d 8322@emph{Pointer types} include all types defined as @code{(@var{type} *)}.
c906108c
SS
8323
8324@item
8325@emph{Scalar types} include all of the above.
53a5351d 8326
c906108c
SS
8327@end itemize
8328
8329@noindent
8330The following operators are supported. They are listed here
8331in order of increasing precedence:
8332
8333@table @code
8334@item ,
8335The comma or sequencing operator. Expressions in a comma-separated list
8336are evaluated from left to right, with the result of the entire
8337expression being the last expression evaluated.
8338
8339@item =
8340Assignment. The value of an assignment expression is the value
8341assigned. Defined on scalar types.
8342
8343@item @var{op}=
8344Used in an expression of the form @w{@code{@var{a} @var{op}= @var{b}}},
8345and translated to @w{@code{@var{a} = @var{a op b}}}.
d4f3574e 8346@w{@code{@var{op}=}} and @code{=} have the same precedence.
c906108c
SS
8347@var{op} is any one of the operators @code{|}, @code{^}, @code{&},
8348@code{<<}, @code{>>}, @code{+}, @code{-}, @code{*}, @code{/}, @code{%}.
8349
8350@item ?:
8351The ternary operator. @code{@var{a} ? @var{b} : @var{c}} can be thought
8352of as: if @var{a} then @var{b} else @var{c}. @var{a} should be of an
8353integral type.
8354
8355@item ||
8356Logical @sc{or}. Defined on integral types.
8357
8358@item &&
8359Logical @sc{and}. Defined on integral types.
8360
8361@item |
8362Bitwise @sc{or}. Defined on integral types.
8363
8364@item ^
8365Bitwise exclusive-@sc{or}. Defined on integral types.
8366
8367@item &
8368Bitwise @sc{and}. Defined on integral types.
8369
8370@item ==@r{, }!=
8371Equality and inequality. Defined on scalar types. The value of these
8372expressions is 0 for false and non-zero for true.
8373
8374@item <@r{, }>@r{, }<=@r{, }>=
8375Less than, greater than, less than or equal, greater than or equal.
8376Defined on scalar types. The value of these expressions is 0 for false
8377and non-zero for true.
8378
8379@item <<@r{, }>>
8380left shift, and right shift. Defined on integral types.
8381
8382@item @@
8383The @value{GDBN} ``artificial array'' operator (@pxref{Expressions, ,Expressions}).
8384
8385@item +@r{, }-
8386Addition and subtraction. Defined on integral types, floating-point types and
8387pointer types.
8388
8389@item *@r{, }/@r{, }%
8390Multiplication, division, and modulus. Multiplication and division are
8391defined on integral and floating-point types. Modulus is defined on
8392integral types.
8393
8394@item ++@r{, }--
8395Increment and decrement. When appearing before a variable, the
8396operation is performed before the variable is used in an expression;
8397when appearing after it, the variable's value is used before the
8398operation takes place.
8399
8400@item *
8401Pointer dereferencing. Defined on pointer types. Same precedence as
8402@code{++}.
8403
8404@item &
8405Address operator. Defined on variables. Same precedence as @code{++}.
8406
b37052ae
EZ
8407For debugging C@t{++}, @value{GDBN} implements a use of @samp{&} beyond what is
8408allowed in the C@t{++} language itself: you can use @samp{&(&@var{ref})}
c906108c 8409(or, if you prefer, simply @samp{&&@var{ref}}) to examine the address
b37052ae 8410where a C@t{++} reference variable (declared with @samp{&@var{ref}}) is
c906108c 8411stored.
c906108c
SS
8412
8413@item -
8414Negative. Defined on integral and floating-point types. Same
8415precedence as @code{++}.
8416
8417@item !
8418Logical negation. Defined on integral types. Same precedence as
8419@code{++}.
8420
8421@item ~
8422Bitwise complement operator. Defined on integral types. Same precedence as
8423@code{++}.
8424
8425
8426@item .@r{, }->
8427Structure member, and pointer-to-structure member. For convenience,
8428@value{GDBN} regards the two as equivalent, choosing whether to dereference a
8429pointer based on the stored type information.
8430Defined on @code{struct} and @code{union} data.
8431
c906108c
SS
8432@item .*@r{, }->*
8433Dereferences of pointers to members.
c906108c
SS
8434
8435@item []
8436Array indexing. @code{@var{a}[@var{i}]} is defined as
8437@code{*(@var{a}+@var{i})}. Same precedence as @code{->}.
8438
8439@item ()
8440Function parameter list. Same precedence as @code{->}.
8441
c906108c 8442@item ::
b37052ae 8443C@t{++} scope resolution operator. Defined on @code{struct}, @code{union},
7a292a7a 8444and @code{class} types.
c906108c
SS
8445
8446@item ::
7a292a7a
SS
8447Doubled colons also represent the @value{GDBN} scope operator
8448(@pxref{Expressions, ,Expressions}). Same precedence as @code{::},
8449above.
c906108c
SS
8450@end table
8451
c906108c
SS
8452If an operator is redefined in the user code, @value{GDBN} usually
8453attempts to invoke the redefined version instead of using the operator's
8454predefined meaning.
c906108c 8455
c906108c 8456@menu
5d161b24 8457* C Constants::
c906108c
SS
8458@end menu
8459
6d2ebf8b 8460@node C Constants
b37052ae 8461@subsubsection C and C@t{++} constants
c906108c 8462
b37052ae 8463@cindex C and C@t{++} constants
c906108c 8464
b37052ae 8465@value{GDBN} allows you to express the constants of C and C@t{++} in the
c906108c 8466following ways:
c906108c
SS
8467
8468@itemize @bullet
8469@item
8470Integer constants are a sequence of digits. Octal constants are
6ca652b0
EZ
8471specified by a leading @samp{0} (i.e.@: zero), and hexadecimal constants
8472by a leading @samp{0x} or @samp{0X}. Constants may also end with a letter
c906108c
SS
8473@samp{l}, specifying that the constant should be treated as a
8474@code{long} value.
8475
8476@item
8477Floating point constants are a sequence of digits, followed by a decimal
8478point, followed by a sequence of digits, and optionally followed by an
8479exponent. An exponent is of the form:
8480@samp{@w{e@r{[[}+@r{]|}-@r{]}@var{nnn}}}, where @var{nnn} is another
8481sequence of digits. The @samp{+} is optional for positive exponents.
d4f3574e
SS
8482A floating-point constant may also end with a letter @samp{f} or
8483@samp{F}, specifying that the constant should be treated as being of
8484the @code{float} (as opposed to the default @code{double}) type; or with
8485a letter @samp{l} or @samp{L}, which specifies a @code{long double}
8486constant.
c906108c
SS
8487
8488@item
8489Enumerated constants consist of enumerated identifiers, or their
8490integral equivalents.
8491
8492@item
8493Character constants are a single character surrounded by single quotes
8494(@code{'}), or a number---the ordinal value of the corresponding character
d4f3574e 8495(usually its @sc{ascii} value). Within quotes, the single character may
c906108c
SS
8496be represented by a letter or by @dfn{escape sequences}, which are of
8497the form @samp{\@var{nnn}}, where @var{nnn} is the octal representation
8498of the character's ordinal value; or of the form @samp{\@var{x}}, where
8499@samp{@var{x}} is a predefined special character---for example,
8500@samp{\n} for newline.
8501
8502@item
96a2c332
SS
8503String constants are a sequence of character constants surrounded by
8504double quotes (@code{"}). Any valid character constant (as described
8505above) may appear. Double quotes within the string must be preceded by
8506a backslash, so for instance @samp{"a\"b'c"} is a string of five
8507characters.
c906108c
SS
8508
8509@item
8510Pointer constants are an integral value. You can also write pointers
8511to constants using the C operator @samp{&}.
8512
8513@item
8514Array constants are comma-separated lists surrounded by braces @samp{@{}
8515and @samp{@}}; for example, @samp{@{1,2,3@}} is a three-element array of
8516integers, @samp{@{@{1,2@}, @{3,4@}, @{5,6@}@}} is a three-by-two array,
8517and @samp{@{&"hi", &"there", &"fred"@}} is a three-element array of pointers.
8518@end itemize
8519
c906108c 8520@menu
5d161b24
DB
8521* C plus plus expressions::
8522* C Defaults::
8523* C Checks::
c906108c 8524
5d161b24 8525* Debugging C::
c906108c
SS
8526@end menu
8527
6d2ebf8b 8528@node C plus plus expressions
b37052ae
EZ
8529@subsubsection C@t{++} expressions
8530
8531@cindex expressions in C@t{++}
8532@value{GDBN} expression handling can interpret most C@t{++} expressions.
8533
0179ffac
DC
8534@cindex debugging C@t{++} programs
8535@cindex C@t{++} compilers
8536@cindex debug formats and C@t{++}
8537@cindex @value{NGCC} and C@t{++}
c906108c 8538@quotation
b37052ae 8539@emph{Warning:} @value{GDBN} can only debug C@t{++} code if you use the
0179ffac
DC
8540proper compiler and the proper debug format. Currently, @value{GDBN}
8541works best when debugging C@t{++} code that is compiled with
8542@value{NGCC} 2.95.3 or with @value{NGCC} 3.1 or newer, using the options
8543@option{-gdwarf-2} or @option{-gstabs+}. DWARF 2 is preferred over
8544stabs+. Most configurations of @value{NGCC} emit either DWARF 2 or
8545stabs+ as their default debug format, so you usually don't need to
8546specify a debug format explicitly. Other compilers and/or debug formats
8547are likely to work badly or not at all when using @value{GDBN} to debug
8548C@t{++} code.
c906108c 8549@end quotation
c906108c
SS
8550
8551@enumerate
8552
8553@cindex member functions
8554@item
8555Member function calls are allowed; you can use expressions like
8556
474c8240 8557@smallexample
c906108c 8558count = aml->GetOriginal(x, y)
474c8240 8559@end smallexample
c906108c 8560
41afff9a 8561@vindex this@r{, inside C@t{++} member functions}
b37052ae 8562@cindex namespace in C@t{++}
c906108c
SS
8563@item
8564While a member function is active (in the selected stack frame), your
8565expressions have the same namespace available as the member function;
8566that is, @value{GDBN} allows implicit references to the class instance
b37052ae 8567pointer @code{this} following the same rules as C@t{++}.
c906108c 8568
c906108c 8569@cindex call overloaded functions
d4f3574e 8570@cindex overloaded functions, calling
b37052ae 8571@cindex type conversions in C@t{++}
c906108c
SS
8572@item
8573You can call overloaded functions; @value{GDBN} resolves the function
d4f3574e 8574call to the right definition, with some restrictions. @value{GDBN} does not
c906108c
SS
8575perform overload resolution involving user-defined type conversions,
8576calls to constructors, or instantiations of templates that do not exist
8577in the program. It also cannot handle ellipsis argument lists or
8578default arguments.
8579
8580It does perform integral conversions and promotions, floating-point
8581promotions, arithmetic conversions, pointer conversions, conversions of
8582class objects to base classes, and standard conversions such as those of
8583functions or arrays to pointers; it requires an exact match on the
8584number of function arguments.
8585
8586Overload resolution is always performed, unless you have specified
8587@code{set overload-resolution off}. @xref{Debugging C plus plus,
b37052ae 8588,@value{GDBN} features for C@t{++}}.
c906108c 8589
d4f3574e 8590You must specify @code{set overload-resolution off} in order to use an
c906108c
SS
8591explicit function signature to call an overloaded function, as in
8592@smallexample
8593p 'foo(char,int)'('x', 13)
8594@end smallexample
d4f3574e 8595
c906108c 8596The @value{GDBN} command-completion facility can simplify this;
d4f3574e 8597see @ref{Completion, ,Command completion}.
c906108c 8598
c906108c
SS
8599@cindex reference declarations
8600@item
b37052ae
EZ
8601@value{GDBN} understands variables declared as C@t{++} references; you can use
8602them in expressions just as you do in C@t{++} source---they are automatically
c906108c
SS
8603dereferenced.
8604
8605In the parameter list shown when @value{GDBN} displays a frame, the values of
8606reference variables are not displayed (unlike other variables); this
8607avoids clutter, since references are often used for large structures.
8608The @emph{address} of a reference variable is always shown, unless
8609you have specified @samp{set print address off}.
8610
8611@item
b37052ae 8612@value{GDBN} supports the C@t{++} name resolution operator @code{::}---your
c906108c
SS
8613expressions can use it just as expressions in your program do. Since
8614one scope may be defined in another, you can use @code{::} repeatedly if
8615necessary, for example in an expression like
8616@samp{@var{scope1}::@var{scope2}::@var{name}}. @value{GDBN} also allows
b37052ae 8617resolving name scope by reference to source files, in both C and C@t{++}
c906108c
SS
8618debugging (@pxref{Variables, ,Program variables}).
8619@end enumerate
8620
b37052ae 8621In addition, when used with HP's C@t{++} compiler, @value{GDBN} supports
53a5351d
JM
8622calling virtual functions correctly, printing out virtual bases of
8623objects, calling functions in a base subobject, casting objects, and
8624invoking user-defined operators.
c906108c 8625
6d2ebf8b 8626@node C Defaults
b37052ae 8627@subsubsection C and C@t{++} defaults
7a292a7a 8628
b37052ae 8629@cindex C and C@t{++} defaults
c906108c 8630
c906108c
SS
8631If you allow @value{GDBN} to set type and range checking automatically, they
8632both default to @code{off} whenever the working language changes to
b37052ae 8633C or C@t{++}. This happens regardless of whether you or @value{GDBN}
c906108c 8634selects the working language.
c906108c
SS
8635
8636If you allow @value{GDBN} to set the language automatically, it
8637recognizes source files whose names end with @file{.c}, @file{.C}, or
8638@file{.cc}, etc, and when @value{GDBN} enters code compiled from one of
b37052ae 8639these files, it sets the working language to C or C@t{++}.
c906108c
SS
8640@xref{Automatically, ,Having @value{GDBN} infer the source language},
8641for further details.
8642
c906108c
SS
8643@c Type checking is (a) primarily motivated by Modula-2, and (b)
8644@c unimplemented. If (b) changes, it might make sense to let this node
8645@c appear even if Mod-2 does not, but meanwhile ignore it. roland 16jul93.
7a292a7a 8646
6d2ebf8b 8647@node C Checks
b37052ae 8648@subsubsection C and C@t{++} type and range checks
7a292a7a 8649
b37052ae 8650@cindex C and C@t{++} checks
c906108c 8651
b37052ae 8652By default, when @value{GDBN} parses C or C@t{++} expressions, type checking
c906108c
SS
8653is not used. However, if you turn type checking on, @value{GDBN}
8654considers two variables type equivalent if:
8655
8656@itemize @bullet
8657@item
8658The two variables are structured and have the same structure, union, or
8659enumerated tag.
8660
8661@item
8662The two variables have the same type name, or types that have been
8663declared equivalent through @code{typedef}.
8664
8665@ignore
8666@c leaving this out because neither J Gilmore nor R Pesch understand it.
8667@c FIXME--beers?
8668@item
8669The two @code{struct}, @code{union}, or @code{enum} variables are
8670declared in the same declaration. (Note: this may not be true for all C
8671compilers.)
8672@end ignore
8673@end itemize
8674
8675Range checking, if turned on, is done on mathematical operations. Array
8676indices are not checked, since they are often used to index a pointer
8677that is not itself an array.
c906108c 8678
6d2ebf8b 8679@node Debugging C
c906108c 8680@subsubsection @value{GDBN} and C
c906108c
SS
8681
8682The @code{set print union} and @code{show print union} commands apply to
8683the @code{union} type. When set to @samp{on}, any @code{union} that is
7a292a7a
SS
8684inside a @code{struct} or @code{class} is also printed. Otherwise, it
8685appears as @samp{@{...@}}.
c906108c
SS
8686
8687The @code{@@} operator aids in the debugging of dynamic arrays, formed
8688with pointers and a memory allocation function. @xref{Expressions,
8689,Expressions}.
8690
c906108c 8691@menu
5d161b24 8692* Debugging C plus plus::
c906108c
SS
8693@end menu
8694
6d2ebf8b 8695@node Debugging C plus plus
b37052ae 8696@subsubsection @value{GDBN} features for C@t{++}
c906108c 8697
b37052ae 8698@cindex commands for C@t{++}
7a292a7a 8699
b37052ae
EZ
8700Some @value{GDBN} commands are particularly useful with C@t{++}, and some are
8701designed specifically for use with C@t{++}. Here is a summary:
c906108c
SS
8702
8703@table @code
8704@cindex break in overloaded functions
8705@item @r{breakpoint menus}
8706When you want a breakpoint in a function whose name is overloaded,
8707@value{GDBN} breakpoint menus help you specify which function definition
8708you want. @xref{Breakpoint Menus,,Breakpoint menus}.
8709
b37052ae 8710@cindex overloading in C@t{++}
c906108c
SS
8711@item rbreak @var{regex}
8712Setting breakpoints using regular expressions is helpful for setting
8713breakpoints on overloaded functions that are not members of any special
8714classes.
8715@xref{Set Breaks, ,Setting breakpoints}.
8716
b37052ae 8717@cindex C@t{++} exception handling
c906108c
SS
8718@item catch throw
8719@itemx catch catch
b37052ae 8720Debug C@t{++} exception handling using these commands. @xref{Set
c906108c
SS
8721Catchpoints, , Setting catchpoints}.
8722
8723@cindex inheritance
8724@item ptype @var{typename}
8725Print inheritance relationships as well as other information for type
8726@var{typename}.
8727@xref{Symbols, ,Examining the Symbol Table}.
8728
b37052ae 8729@cindex C@t{++} symbol display
c906108c
SS
8730@item set print demangle
8731@itemx show print demangle
8732@itemx set print asm-demangle
8733@itemx show print asm-demangle
b37052ae
EZ
8734Control whether C@t{++} symbols display in their source form, both when
8735displaying code as C@t{++} source and when displaying disassemblies.
c906108c
SS
8736@xref{Print Settings, ,Print settings}.
8737
8738@item set print object
8739@itemx show print object
8740Choose whether to print derived (actual) or declared types of objects.
8741@xref{Print Settings, ,Print settings}.
8742
8743@item set print vtbl
8744@itemx show print vtbl
8745Control the format for printing virtual function tables.
8746@xref{Print Settings, ,Print settings}.
c906108c 8747(The @code{vtbl} commands do not work on programs compiled with the HP
b37052ae 8748ANSI C@t{++} compiler (@code{aCC}).)
c906108c
SS
8749
8750@kindex set overload-resolution
d4f3574e 8751@cindex overloaded functions, overload resolution
c906108c 8752@item set overload-resolution on
b37052ae 8753Enable overload resolution for C@t{++} expression evaluation. The default
c906108c
SS
8754is on. For overloaded functions, @value{GDBN} evaluates the arguments
8755and searches for a function whose signature matches the argument types,
b37052ae 8756using the standard C@t{++} conversion rules (see @ref{C plus plus expressions, ,C@t{++}
d4f3574e 8757expressions}, for details). If it cannot find a match, it emits a
c906108c
SS
8758message.
8759
8760@item set overload-resolution off
b37052ae 8761Disable overload resolution for C@t{++} expression evaluation. For
c906108c
SS
8762overloaded functions that are not class member functions, @value{GDBN}
8763chooses the first function of the specified name that it finds in the
8764symbol table, whether or not its arguments are of the correct type. For
8765overloaded functions that are class member functions, @value{GDBN}
8766searches for a function whose signature @emph{exactly} matches the
8767argument types.
c906108c 8768
9c16f35a
EZ
8769@kindex show overload-resolution
8770@item show overload-resolution
8771Show the current setting of overload resolution.
8772
c906108c
SS
8773@item @r{Overloaded symbol names}
8774You can specify a particular definition of an overloaded symbol, using
b37052ae 8775the same notation that is used to declare such symbols in C@t{++}: type
c906108c
SS
8776@code{@var{symbol}(@var{types})} rather than just @var{symbol}. You can
8777also use the @value{GDBN} command-line word completion facilities to list the
8778available choices, or to finish the type list for you.
8779@xref{Completion,, Command completion}, for details on how to do this.
8780@end table
c906108c 8781
b37303ee
AF
8782@node Objective-C
8783@subsection Objective-C
8784
8785@cindex Objective-C
8786This section provides information about some commands and command
8787options that are useful for debugging Objective-C code.
8788
8789@menu
b383017d
RM
8790* Method Names in Commands::
8791* The Print Command with Objective-C::
b37303ee
AF
8792@end menu
8793
8794@node Method Names in Commands, The Print Command with Objective-C, Objective-C, Objective-C
8795@subsubsection Method Names in Commands
8796
8797The following commands have been extended to accept Objective-C method
8798names as line specifications:
8799
8800@kindex clear@r{, and Objective-C}
8801@kindex break@r{, and Objective-C}
8802@kindex info line@r{, and Objective-C}
8803@kindex jump@r{, and Objective-C}
8804@kindex list@r{, and Objective-C}
8805@itemize
8806@item @code{clear}
8807@item @code{break}
8808@item @code{info line}
8809@item @code{jump}
8810@item @code{list}
8811@end itemize
8812
8813A fully qualified Objective-C method name is specified as
8814
8815@smallexample
8816-[@var{Class} @var{methodName}]
8817@end smallexample
8818
c552b3bb
JM
8819where the minus sign is used to indicate an instance method and a
8820plus sign (not shown) is used to indicate a class method. The class
8821name @var{Class} and method name @var{methodName} are enclosed in
8822brackets, similar to the way messages are specified in Objective-C
8823source code. For example, to set a breakpoint at the @code{create}
8824instance method of class @code{Fruit} in the program currently being
8825debugged, enter:
b37303ee
AF
8826
8827@smallexample
8828break -[Fruit create]
8829@end smallexample
8830
8831To list ten program lines around the @code{initialize} class method,
8832enter:
8833
8834@smallexample
8835list +[NSText initialize]
8836@end smallexample
8837
c552b3bb
JM
8838In the current version of @value{GDBN}, the plus or minus sign is
8839required. In future versions of @value{GDBN}, the plus or minus
8840sign will be optional, but you can use it to narrow the search. It
8841is also possible to specify just a method name:
b37303ee
AF
8842
8843@smallexample
8844break create
8845@end smallexample
8846
8847You must specify the complete method name, including any colons. If
8848your program's source files contain more than one @code{create} method,
8849you'll be presented with a numbered list of classes that implement that
8850method. Indicate your choice by number, or type @samp{0} to exit if
8851none apply.
8852
8853As another example, to clear a breakpoint established at the
8854@code{makeKeyAndOrderFront:} method of the @code{NSWindow} class, enter:
8855
8856@smallexample
8857clear -[NSWindow makeKeyAndOrderFront:]
8858@end smallexample
8859
8860@node The Print Command with Objective-C
8861@subsubsection The Print Command With Objective-C
c552b3bb
JM
8862@kindex print-object
8863@kindex po @r{(@code{print-object})}
b37303ee 8864
c552b3bb 8865The print command has also been extended to accept methods. For example:
b37303ee
AF
8866
8867@smallexample
c552b3bb 8868print -[@var{object} hash]
b37303ee
AF
8869@end smallexample
8870
8871@cindex print an Objective-C object description
c552b3bb
JM
8872@cindex @code{_NSPrintForDebugger}, and printing Objective-C objects
8873@noindent
8874will tell @value{GDBN} to send the @code{hash} message to @var{object}
8875and print the result. Also, an additional command has been added,
8876@code{print-object} or @code{po} for short, which is meant to print
8877the description of an object. However, this command may only work
8878with certain Objective-C libraries that have a particular hook
8879function, @code{_NSPrintForDebugger}, defined.
b37303ee 8880
09d4efe1
EZ
8881@node Fortran
8882@subsection Fortran
8883@cindex Fortran-specific support in @value{GDBN}
8884
8885@table @code
8886@cindex @code{COMMON} blocks, Fortran
8887@kindex info common
8888@item info common @r{[}@var{common-name}@r{]}
8889This command prints the values contained in the Fortran @code{COMMON}
8890block whose name is @var{common-name}. With no argument, the names of
8891all @code{COMMON} blocks visible at current program location are
8892printed.
8893@end table
8894
a8f24a35
EZ
8895Fortran symbols are usually case-insensitive, so @value{GDBN} by
8896default uses case-insensitive matches for Fortran symbols. You can
8897change that with the @samp{set case-insensitive} command, see
8898@ref{Symbols}, for the details.
8899
9c16f35a
EZ
8900@node Pascal
8901@subsection Pascal
8902
8903@cindex Pascal support in @value{GDBN}, limitations
8904Debugging Pascal programs which use sets, subranges, file variables, or
8905nested functions does not currently work. @value{GDBN} does not support
8906entering expressions, printing values, or similar features using Pascal
8907syntax.
8908
8909The Pascal-specific command @code{set print pascal_static-members}
8910controls whether static members of Pascal objects are displayed.
8911@xref{Print Settings, pascal_static-members}.
8912
09d4efe1 8913@node Modula-2
c906108c 8914@subsection Modula-2
7a292a7a 8915
d4f3574e 8916@cindex Modula-2, @value{GDBN} support
c906108c
SS
8917
8918The extensions made to @value{GDBN} to support Modula-2 only support
8919output from the @sc{gnu} Modula-2 compiler (which is currently being
8920developed). Other Modula-2 compilers are not currently supported, and
8921attempting to debug executables produced by them is most likely
8922to give an error as @value{GDBN} reads in the executable's symbol
8923table.
8924
8925@cindex expressions in Modula-2
8926@menu
8927* M2 Operators:: Built-in operators
8928* Built-In Func/Proc:: Built-in functions and procedures
8929* M2 Constants:: Modula-2 constants
8930* M2 Defaults:: Default settings for Modula-2
8931* Deviations:: Deviations from standard Modula-2
8932* M2 Checks:: Modula-2 type and range checks
8933* M2 Scope:: The scope operators @code{::} and @code{.}
8934* GDB/M2:: @value{GDBN} and Modula-2
8935@end menu
8936
6d2ebf8b 8937@node M2 Operators
c906108c
SS
8938@subsubsection Operators
8939@cindex Modula-2 operators
8940
8941Operators must be defined on values of specific types. For instance,
8942@code{+} is defined on numbers, but not on structures. Operators are
8943often defined on groups of types. For the purposes of Modula-2, the
8944following definitions hold:
8945
8946@itemize @bullet
8947
8948@item
8949@emph{Integral types} consist of @code{INTEGER}, @code{CARDINAL}, and
8950their subranges.
8951
8952@item
8953@emph{Character types} consist of @code{CHAR} and its subranges.
8954
8955@item
8956@emph{Floating-point types} consist of @code{REAL}.
8957
8958@item
8959@emph{Pointer types} consist of anything declared as @code{POINTER TO
8960@var{type}}.
8961
8962@item
8963@emph{Scalar types} consist of all of the above.
8964
8965@item
8966@emph{Set types} consist of @code{SET} and @code{BITSET} types.
8967
8968@item
8969@emph{Boolean types} consist of @code{BOOLEAN}.
8970@end itemize
8971
8972@noindent
8973The following operators are supported, and appear in order of
8974increasing precedence:
8975
8976@table @code
8977@item ,
8978Function argument or array index separator.
8979
8980@item :=
8981Assignment. The value of @var{var} @code{:=} @var{value} is
8982@var{value}.
8983
8984@item <@r{, }>
8985Less than, greater than on integral, floating-point, or enumerated
8986types.
8987
8988@item <=@r{, }>=
96a2c332 8989Less than or equal to, greater than or equal to
c906108c
SS
8990on integral, floating-point and enumerated types, or set inclusion on
8991set types. Same precedence as @code{<}.
8992
8993@item =@r{, }<>@r{, }#
8994Equality and two ways of expressing inequality, valid on scalar types.
8995Same precedence as @code{<}. In @value{GDBN} scripts, only @code{<>} is
8996available for inequality, since @code{#} conflicts with the script
8997comment character.
8998
8999@item IN
9000Set membership. Defined on set types and the types of their members.
9001Same precedence as @code{<}.
9002
9003@item OR
9004Boolean disjunction. Defined on boolean types.
9005
9006@item AND@r{, }&
d4f3574e 9007Boolean conjunction. Defined on boolean types.
c906108c
SS
9008
9009@item @@
9010The @value{GDBN} ``artificial array'' operator (@pxref{Expressions, ,Expressions}).
9011
9012@item +@r{, }-
9013Addition and subtraction on integral and floating-point types, or union
9014and difference on set types.
9015
9016@item *
9017Multiplication on integral and floating-point types, or set intersection
9018on set types.
9019
9020@item /
9021Division on floating-point types, or symmetric set difference on set
9022types. Same precedence as @code{*}.
9023
9024@item DIV@r{, }MOD
9025Integer division and remainder. Defined on integral types. Same
9026precedence as @code{*}.
9027
9028@item -
9029Negative. Defined on @code{INTEGER} and @code{REAL} data.
9030
9031@item ^
9032Pointer dereferencing. Defined on pointer types.
9033
9034@item NOT
9035Boolean negation. Defined on boolean types. Same precedence as
9036@code{^}.
9037
9038@item .
9039@code{RECORD} field selector. Defined on @code{RECORD} data. Same
9040precedence as @code{^}.
9041
9042@item []
9043Array indexing. Defined on @code{ARRAY} data. Same precedence as @code{^}.
9044
9045@item ()
9046Procedure argument list. Defined on @code{PROCEDURE} objects. Same precedence
9047as @code{^}.
9048
9049@item ::@r{, }.
9050@value{GDBN} and Modula-2 scope operators.
9051@end table
9052
9053@quotation
9054@emph{Warning:} Sets and their operations are not yet supported, so @value{GDBN}
9055treats the use of the operator @code{IN}, or the use of operators
9056@code{+}, @code{-}, @code{*}, @code{/}, @code{=}, , @code{<>}, @code{#},
9057@code{<=}, and @code{>=} on sets as an error.
9058@end quotation
9059
cb51c4e0 9060
6d2ebf8b 9061@node Built-In Func/Proc
c906108c 9062@subsubsection Built-in functions and procedures
cb51c4e0 9063@cindex Modula-2 built-ins
c906108c
SS
9064
9065Modula-2 also makes available several built-in procedures and functions.
9066In describing these, the following metavariables are used:
9067
9068@table @var
9069
9070@item a
9071represents an @code{ARRAY} variable.
9072
9073@item c
9074represents a @code{CHAR} constant or variable.
9075
9076@item i
9077represents a variable or constant of integral type.
9078
9079@item m
9080represents an identifier that belongs to a set. Generally used in the
9081same function with the metavariable @var{s}. The type of @var{s} should
9082be @code{SET OF @var{mtype}} (where @var{mtype} is the type of @var{m}).
9083
9084@item n
9085represents a variable or constant of integral or floating-point type.
9086
9087@item r
9088represents a variable or constant of floating-point type.
9089
9090@item t
9091represents a type.
9092
9093@item v
9094represents a variable.
9095
9096@item x
9097represents a variable or constant of one of many types. See the
9098explanation of the function for details.
9099@end table
9100
9101All Modula-2 built-in procedures also return a result, described below.
9102
9103@table @code
9104@item ABS(@var{n})
9105Returns the absolute value of @var{n}.
9106
9107@item CAP(@var{c})
9108If @var{c} is a lower case letter, it returns its upper case
c3f6f71d 9109equivalent, otherwise it returns its argument.
c906108c
SS
9110
9111@item CHR(@var{i})
9112Returns the character whose ordinal value is @var{i}.
9113
9114@item DEC(@var{v})
c3f6f71d 9115Decrements the value in the variable @var{v} by one. Returns the new value.
c906108c
SS
9116
9117@item DEC(@var{v},@var{i})
9118Decrements the value in the variable @var{v} by @var{i}. Returns the
9119new value.
9120
9121@item EXCL(@var{m},@var{s})
9122Removes the element @var{m} from the set @var{s}. Returns the new
9123set.
9124
9125@item FLOAT(@var{i})
9126Returns the floating point equivalent of the integer @var{i}.
9127
9128@item HIGH(@var{a})
9129Returns the index of the last member of @var{a}.
9130
9131@item INC(@var{v})
c3f6f71d 9132Increments the value in the variable @var{v} by one. Returns the new value.
c906108c
SS
9133
9134@item INC(@var{v},@var{i})
9135Increments the value in the variable @var{v} by @var{i}. Returns the
9136new value.
9137
9138@item INCL(@var{m},@var{s})
9139Adds the element @var{m} to the set @var{s} if it is not already
9140there. Returns the new set.
9141
9142@item MAX(@var{t})
9143Returns the maximum value of the type @var{t}.
9144
9145@item MIN(@var{t})
9146Returns the minimum value of the type @var{t}.
9147
9148@item ODD(@var{i})
9149Returns boolean TRUE if @var{i} is an odd number.
9150
9151@item ORD(@var{x})
9152Returns the ordinal value of its argument. For example, the ordinal
c3f6f71d
JM
9153value of a character is its @sc{ascii} value (on machines supporting the
9154@sc{ascii} character set). @var{x} must be of an ordered type, which include
c906108c
SS
9155integral, character and enumerated types.
9156
9157@item SIZE(@var{x})
9158Returns the size of its argument. @var{x} can be a variable or a type.
9159
9160@item TRUNC(@var{r})
9161Returns the integral part of @var{r}.
9162
9163@item VAL(@var{t},@var{i})
9164Returns the member of the type @var{t} whose ordinal value is @var{i}.
9165@end table
9166
9167@quotation
9168@emph{Warning:} Sets and their operations are not yet supported, so
9169@value{GDBN} treats the use of procedures @code{INCL} and @code{EXCL} as
9170an error.
9171@end quotation
9172
9173@cindex Modula-2 constants
6d2ebf8b 9174@node M2 Constants
c906108c
SS
9175@subsubsection Constants
9176
9177@value{GDBN} allows you to express the constants of Modula-2 in the following
9178ways:
9179
9180@itemize @bullet
9181
9182@item
9183Integer constants are simply a sequence of digits. When used in an
9184expression, a constant is interpreted to be type-compatible with the
9185rest of the expression. Hexadecimal integers are specified by a
9186trailing @samp{H}, and octal integers by a trailing @samp{B}.
9187
9188@item
9189Floating point constants appear as a sequence of digits, followed by a
9190decimal point and another sequence of digits. An optional exponent can
9191then be specified, in the form @samp{E@r{[}+@r{|}-@r{]}@var{nnn}}, where
9192@samp{@r{[}+@r{|}-@r{]}@var{nnn}} is the desired exponent. All of the
9193digits of the floating point constant must be valid decimal (base 10)
9194digits.
9195
9196@item
9197Character constants consist of a single character enclosed by a pair of
9198like quotes, either single (@code{'}) or double (@code{"}). They may
c3f6f71d 9199also be expressed by their ordinal value (their @sc{ascii} value, usually)
c906108c
SS
9200followed by a @samp{C}.
9201
9202@item
9203String constants consist of a sequence of characters enclosed by a
9204pair of like quotes, either single (@code{'}) or double (@code{"}).
9205Escape sequences in the style of C are also allowed. @xref{C
b37052ae 9206Constants, ,C and C@t{++} constants}, for a brief explanation of escape
c906108c
SS
9207sequences.
9208
9209@item
9210Enumerated constants consist of an enumerated identifier.
9211
9212@item
9213Boolean constants consist of the identifiers @code{TRUE} and
9214@code{FALSE}.
9215
9216@item
9217Pointer constants consist of integral values only.
9218
9219@item
9220Set constants are not yet supported.
9221@end itemize
9222
6d2ebf8b 9223@node M2 Defaults
c906108c
SS
9224@subsubsection Modula-2 defaults
9225@cindex Modula-2 defaults
9226
9227If type and range checking are set automatically by @value{GDBN}, they
9228both default to @code{on} whenever the working language changes to
d4f3574e 9229Modula-2. This happens regardless of whether you or @value{GDBN}
c906108c
SS
9230selected the working language.
9231
9232If you allow @value{GDBN} to set the language automatically, then entering
9233code compiled from a file whose name ends with @file{.mod} sets the
d4f3574e 9234working language to Modula-2. @xref{Automatically, ,Having @value{GDBN} set
c906108c
SS
9235the language automatically}, for further details.
9236
6d2ebf8b 9237@node Deviations
c906108c
SS
9238@subsubsection Deviations from standard Modula-2
9239@cindex Modula-2, deviations from
9240
9241A few changes have been made to make Modula-2 programs easier to debug.
9242This is done primarily via loosening its type strictness:
9243
9244@itemize @bullet
9245@item
9246Unlike in standard Modula-2, pointer constants can be formed by
9247integers. This allows you to modify pointer variables during
9248debugging. (In standard Modula-2, the actual address contained in a
9249pointer variable is hidden from you; it can only be modified
9250through direct assignment to another pointer variable or expression that
9251returned a pointer.)
9252
9253@item
9254C escape sequences can be used in strings and characters to represent
9255non-printable characters. @value{GDBN} prints out strings with these
9256escape sequences embedded. Single non-printable characters are
9257printed using the @samp{CHR(@var{nnn})} format.
9258
9259@item
9260The assignment operator (@code{:=}) returns the value of its right-hand
9261argument.
9262
9263@item
9264All built-in procedures both modify @emph{and} return their argument.
9265@end itemize
9266
6d2ebf8b 9267@node M2 Checks
c906108c
SS
9268@subsubsection Modula-2 type and range checks
9269@cindex Modula-2 checks
9270
9271@quotation
9272@emph{Warning:} in this release, @value{GDBN} does not yet perform type or
9273range checking.
9274@end quotation
9275@c FIXME remove warning when type/range checks added
9276
9277@value{GDBN} considers two Modula-2 variables type equivalent if:
9278
9279@itemize @bullet
9280@item
9281They are of types that have been declared equivalent via a @code{TYPE
9282@var{t1} = @var{t2}} statement
9283
9284@item
9285They have been declared on the same line. (Note: This is true of the
9286@sc{gnu} Modula-2 compiler, but it may not be true of other compilers.)
9287@end itemize
9288
9289As long as type checking is enabled, any attempt to combine variables
9290whose types are not equivalent is an error.
9291
9292Range checking is done on all mathematical operations, assignment, array
9293index bounds, and all built-in functions and procedures.
9294
6d2ebf8b 9295@node M2 Scope
c906108c
SS
9296@subsubsection The scope operators @code{::} and @code{.}
9297@cindex scope
41afff9a 9298@cindex @code{.}, Modula-2 scope operator
c906108c
SS
9299@cindex colon, doubled as scope operator
9300@ifinfo
41afff9a 9301@vindex colon-colon@r{, in Modula-2}
c906108c
SS
9302@c Info cannot handle :: but TeX can.
9303@end ifinfo
9304@iftex
41afff9a 9305@vindex ::@r{, in Modula-2}
c906108c
SS
9306@end iftex
9307
9308There are a few subtle differences between the Modula-2 scope operator
9309(@code{.}) and the @value{GDBN} scope operator (@code{::}). The two have
9310similar syntax:
9311
474c8240 9312@smallexample
c906108c
SS
9313
9314@var{module} . @var{id}
9315@var{scope} :: @var{id}
474c8240 9316@end smallexample
c906108c
SS
9317
9318@noindent
9319where @var{scope} is the name of a module or a procedure,
9320@var{module} the name of a module, and @var{id} is any declared
9321identifier within your program, except another module.
9322
9323Using the @code{::} operator makes @value{GDBN} search the scope
9324specified by @var{scope} for the identifier @var{id}. If it is not
9325found in the specified scope, then @value{GDBN} searches all scopes
9326enclosing the one specified by @var{scope}.
9327
9328Using the @code{.} operator makes @value{GDBN} search the current scope for
9329the identifier specified by @var{id} that was imported from the
9330definition module specified by @var{module}. With this operator, it is
9331an error if the identifier @var{id} was not imported from definition
9332module @var{module}, or if @var{id} is not an identifier in
9333@var{module}.
9334
6d2ebf8b 9335@node GDB/M2
c906108c
SS
9336@subsubsection @value{GDBN} and Modula-2
9337
9338Some @value{GDBN} commands have little use when debugging Modula-2 programs.
9339Five subcommands of @code{set print} and @code{show print} apply
b37052ae 9340specifically to C and C@t{++}: @samp{vtbl}, @samp{demangle},
c906108c 9341@samp{asm-demangle}, @samp{object}, and @samp{union}. The first four
b37052ae 9342apply to C@t{++}, and the last to the C @code{union} type, which has no direct
c906108c
SS
9343analogue in Modula-2.
9344
9345The @code{@@} operator (@pxref{Expressions, ,Expressions}), while available
d4f3574e 9346with any language, is not useful with Modula-2. Its
c906108c 9347intent is to aid the debugging of @dfn{dynamic arrays}, which cannot be
b37052ae 9348created in Modula-2 as they can in C or C@t{++}. However, because an
c906108c 9349address can be specified by an integral constant, the construct
d4f3574e 9350@samp{@{@var{type}@}@var{adrexp}} is still useful.
c906108c
SS
9351
9352@cindex @code{#} in Modula-2
9353In @value{GDBN} scripts, the Modula-2 inequality operator @code{#} is
9354interpreted as the beginning of a comment. Use @code{<>} instead.
c906108c 9355
e07c999f
PH
9356@node Ada
9357@subsection Ada
9358@cindex Ada
9359
9360The extensions made to @value{GDBN} for Ada only support
9361output from the @sc{gnu} Ada (GNAT) compiler.
9362Other Ada compilers are not currently supported, and
9363attempting to debug executables produced by them is most likely
9364to be difficult.
9365
9366
9367@cindex expressions in Ada
9368@menu
9369* Ada Mode Intro:: General remarks on the Ada syntax
9370 and semantics supported by Ada mode
9371 in @value{GDBN}.
9372* Omissions from Ada:: Restrictions on the Ada expression syntax.
9373* Additions to Ada:: Extensions of the Ada expression syntax.
9374* Stopping Before Main Program:: Debugging the program during elaboration.
9375* Ada Glitches:: Known peculiarities of Ada mode.
9376@end menu
9377
9378@node Ada Mode Intro
9379@subsubsection Introduction
9380@cindex Ada mode, general
9381
9382The Ada mode of @value{GDBN} supports a fairly large subset of Ada expression
9383syntax, with some extensions.
9384The philosophy behind the design of this subset is
9385
9386@itemize @bullet
9387@item
9388That @value{GDBN} should provide basic literals and access to operations for
9389arithmetic, dereferencing, field selection, indexing, and subprogram calls,
9390leaving more sophisticated computations to subprograms written into the
9391program (which therefore may be called from @value{GDBN}).
9392
9393@item
9394That type safety and strict adherence to Ada language restrictions
9395are not particularly important to the @value{GDBN} user.
9396
9397@item
9398That brevity is important to the @value{GDBN} user.
9399@end itemize
9400
9401Thus, for brevity, the debugger acts as if there were
9402implicit @code{with} and @code{use} clauses in effect for all user-written
9403packages, making it unnecessary to fully qualify most names with
9404their packages, regardless of context. Where this causes ambiguity,
9405@value{GDBN} asks the user's intent.
9406
9407The debugger will start in Ada mode if it detects an Ada main program.
9408As for other languages, it will enter Ada mode when stopped in a program that
9409was translated from an Ada source file.
9410
9411While in Ada mode, you may use `@t{--}' for comments. This is useful
9412mostly for documenting command files. The standard @value{GDBN} comment
9413(@samp{#}) still works at the beginning of a line in Ada mode, but not in the
9414middle (to allow based literals).
9415
9416The debugger supports limited overloading. Given a subprogram call in which
9417the function symbol has multiple definitions, it will use the number of
9418actual parameters and some information about their types to attempt to narrow
9419the set of definitions. It also makes very limited use of context, preferring
9420procedures to functions in the context of the @code{call} command, and
9421functions to procedures elsewhere.
9422
9423@node Omissions from Ada
9424@subsubsection Omissions from Ada
9425@cindex Ada, omissions from
9426
9427Here are the notable omissions from the subset:
9428
9429@itemize @bullet
9430@item
9431Only a subset of the attributes are supported:
9432
9433@itemize @minus
9434@item
9435@t{'First}, @t{'Last}, and @t{'Length}
9436 on array objects (not on types and subtypes).
9437
9438@item
9439@t{'Min} and @t{'Max}.
9440
9441@item
9442@t{'Pos} and @t{'Val}.
9443
9444@item
9445@t{'Tag}.
9446
9447@item
9448@t{'Range} on array objects (not subtypes), but only as the right
9449operand of the membership (@code{in}) operator.
9450
9451@item
9452@t{'Access}, @t{'Unchecked_Access}, and
9453@t{'Unrestricted_Access} (a GNAT extension).
9454
9455@item
9456@t{'Address}.
9457@end itemize
9458
9459@item
9460The names in
9461@code{Characters.Latin_1} are not available and
9462concatenation is not implemented. Thus, escape characters in strings are
9463not currently available.
9464
9465@item
9466Equality tests (@samp{=} and @samp{/=}) on arrays test for bitwise
9467equality of representations. They will generally work correctly
9468for strings and arrays whose elements have integer or enumeration types.
9469They may not work correctly for arrays whose element
9470types have user-defined equality, for arrays of real values
9471(in particular, IEEE-conformant floating point, because of negative
9472zeroes and NaNs), and for arrays whose elements contain unused bits with
9473indeterminate values.
9474
9475@item
9476The other component-by-component array operations (@code{and}, @code{or},
9477@code{xor}, @code{not}, and relational tests other than equality)
9478are not implemented.
9479
9480@item
9481There are no record or array aggregates.
9482
9483@item
9484Calls to dispatching subprograms are not implemented.
9485
9486@item
9487The overloading algorithm is much more limited (i.e., less selective)
9488than that of real Ada. It makes only limited use of the context in which a subexpression
9489appears to resolve its meaning, and it is much looser in its rules for allowing
9490type matches. As a result, some function calls will be ambiguous, and the user
9491will be asked to choose the proper resolution.
9492
9493@item
9494The @code{new} operator is not implemented.
9495
9496@item
9497Entry calls are not implemented.
9498
9499@item
9500Aside from printing, arithmetic operations on the native VAX floating-point
9501formats are not supported.
9502
9503@item
9504It is not possible to slice a packed array.
9505@end itemize
9506
9507@node Additions to Ada
9508@subsubsection Additions to Ada
9509@cindex Ada, deviations from
9510
9511As it does for other languages, @value{GDBN} makes certain generic
9512extensions to Ada (@pxref{Expressions}):
9513
9514@itemize @bullet
9515@item
9516If the expression @var{E} is a variable residing in memory
9517(typically a local variable or array element) and @var{N} is
9518a positive integer, then @code{@var{E}@@@var{N}} displays the values of
9519@var{E} and the @var{N}-1 adjacent variables following it in memory as an array.
9520In Ada, this operator is generally not necessary, since its prime use
9521is in displaying parts of an array, and slicing will usually do this in Ada.
9522However, there are occasional uses when debugging programs
9523in which certain debugging information has been optimized away.
9524
9525@item
9526@code{@var{B}::@var{var}} means ``the variable named @var{var} that appears
9527in function or file @var{B}.'' When @var{B} is a file name, you must typically
9528surround it in single quotes.
9529
9530@item
9531The expression @code{@{@var{type}@} @var{addr}} means ``the variable of type
9532@var{type} that appears at address @var{addr}.''
9533
9534@item
9535A name starting with @samp{$} is a convenience variable
9536(@pxref{Convenience Vars}) or a machine register (@pxref{Registers}).
9537@end itemize
9538
9539In addition, @value{GDBN} provides a few other shortcuts and outright additions specific
9540to Ada:
9541
9542@itemize @bullet
9543@item
9544The assignment statement is allowed as an expression, returning
9545its right-hand operand as its value. Thus, you may enter
9546
9547@smallexample
9548set x := y + 3
9549print A(tmp := y + 1)
9550@end smallexample
9551
9552@item
9553The semicolon is allowed as an ``operator,'' returning as its value
9554the value of its right-hand operand.
9555This allows, for example,
9556complex conditional breaks:
9557
9558@smallexample
9559break f
9560condition 1 (report(i); k += 1; A(k) > 100)
9561@end smallexample
9562
9563@item
9564Rather than use catenation and symbolic character names to introduce special
9565characters into strings, one may instead use a special bracket notation,
9566which is also used to print strings. A sequence of characters of the form
9567@samp{["@var{XX}"]} within a string or character literal denotes the
9568(single) character whose numeric encoding is @var{XX} in hexadecimal. The
9569sequence of characters @samp{["""]} also denotes a single quotation mark
9570in strings. For example,
9571@smallexample
9572 "One line.["0a"]Next line.["0a"]"
9573@end smallexample
9574@noindent
9575contains an ASCII newline character (@code{Ada.Characters.Latin_1.LF}) after each
9576period.
9577
9578@item
9579The subtype used as a prefix for the attributes @t{'Pos}, @t{'Min}, and
9580@t{'Max} is optional (and is ignored in any case). For example, it is valid
9581to write
9582
9583@smallexample
9584print 'max(x, y)
9585@end smallexample
9586
9587@item
9588When printing arrays, @value{GDBN} uses positional notation when the
9589array has a lower bound of 1, and uses a modified named notation otherwise.
9590For example, a one-dimensional array of three integers with a lower bound of 3 might print as
9591
9592@smallexample
9593(3 => 10, 17, 1)
9594@end smallexample
9595
9596@noindent
9597That is, in contrast to valid Ada, only the first component has a @code{=>}
9598clause.
9599
9600@item
9601You may abbreviate attributes in expressions with any unique,
9602multi-character subsequence of
9603their names (an exact match gets preference).
9604For example, you may use @t{a'len}, @t{a'gth}, or @t{a'lh}
9605in place of @t{a'length}.
9606
9607@item
9608@cindex quoting Ada internal identifiers
9609Since Ada is case-insensitive, the debugger normally maps identifiers you type
9610to lower case. The GNAT compiler uses upper-case characters for
9611some of its internal identifiers, which are normally of no interest to users.
9612For the rare occasions when you actually have to look at them,
9613enclose them in angle brackets to avoid the lower-case mapping.
9614For example,
9615@smallexample
9616@value{GDBP} print <JMPBUF_SAVE>[0]
9617@end smallexample
9618
9619@item
9620Printing an object of class-wide type or dereferencing an
9621access-to-class-wide value will display all the components of the object's
9622specific type (as indicated by its run-time tag). Likewise, component
9623selection on such a value will operate on the specific type of the
9624object.
9625
9626@end itemize
9627
9628@node Stopping Before Main Program
9629@subsubsection Stopping at the Very Beginning
9630
9631@cindex breakpointing Ada elaboration code
9632It is sometimes necessary to debug the program during elaboration, and
9633before reaching the main procedure.
9634As defined in the Ada Reference
9635Manual, the elaboration code is invoked from a procedure called
9636@code{adainit}. To run your program up to the beginning of
9637elaboration, simply use the following two commands:
9638@code{tbreak adainit} and @code{run}.
9639
9640@node Ada Glitches
9641@subsubsection Known Peculiarities of Ada Mode
9642@cindex Ada, problems
9643
9644Besides the omissions listed previously (@pxref{Omissions from Ada}),
9645we know of several problems with and limitations of Ada mode in
9646@value{GDBN},
9647some of which will be fixed with planned future releases of the debugger
9648and the GNU Ada compiler.
9649
9650@itemize @bullet
9651@item
9652Currently, the debugger
9653has insufficient information to determine whether certain pointers represent
9654pointers to objects or the objects themselves.
9655Thus, the user may have to tack an extra @code{.all} after an expression
9656to get it printed properly.
9657
9658@item
9659Static constants that the compiler chooses not to materialize as objects in
9660storage are invisible to the debugger.
9661
9662@item
9663Named parameter associations in function argument lists are ignored (the
9664argument lists are treated as positional).
9665
9666@item
9667Many useful library packages are currently invisible to the debugger.
9668
9669@item
9670Fixed-point arithmetic, conversions, input, and output is carried out using
9671floating-point arithmetic, and may give results that only approximate those on
9672the host machine.
9673
9674@item
9675The type of the @t{'Address} attribute may not be @code{System.Address}.
9676
9677@item
9678The GNAT compiler never generates the prefix @code{Standard} for any of
9679the standard symbols defined by the Ada language. @value{GDBN} knows about
9680this: it will strip the prefix from names when you use it, and will never
9681look for a name you have so qualified among local symbols, nor match against
9682symbols in other packages or subprograms. If you have
9683defined entities anywhere in your program other than parameters and
9684local variables whose simple names match names in @code{Standard},
9685GNAT's lack of qualification here can cause confusion. When this happens,
9686you can usually resolve the confusion
9687by qualifying the problematic names with package
9688@code{Standard} explicitly.
9689@end itemize
9690
4e562065
JB
9691@node Unsupported languages
9692@section Unsupported languages
9693
9694@cindex unsupported languages
9695@cindex minimal language
9696In addition to the other fully-supported programming languages,
9697@value{GDBN} also provides a pseudo-language, called @code{minimal}.
9698It does not represent a real programming language, but provides a set
9699of capabilities close to what the C or assembly languages provide.
9700This should allow most simple operations to be performed while debugging
9701an application that uses a language currently not supported by @value{GDBN}.
9702
9703If the language is set to @code{auto}, @value{GDBN} will automatically
9704select this language if the current frame corresponds to an unsupported
9705language.
9706
6d2ebf8b 9707@node Symbols
c906108c
SS
9708@chapter Examining the Symbol Table
9709
d4f3574e 9710The commands described in this chapter allow you to inquire about the
c906108c
SS
9711symbols (names of variables, functions and types) defined in your
9712program. This information is inherent in the text of your program and
9713does not change as your program executes. @value{GDBN} finds it in your
9714program's symbol table, in the file indicated when you started @value{GDBN}
9715(@pxref{File Options, ,Choosing files}), or by one of the
9716file-management commands (@pxref{Files, ,Commands to specify files}).
9717
9718@cindex symbol names
9719@cindex names of symbols
9720@cindex quoting names
9721Occasionally, you may need to refer to symbols that contain unusual
9722characters, which @value{GDBN} ordinarily treats as word delimiters. The
9723most frequent case is in referring to static variables in other
9724source files (@pxref{Variables,,Program variables}). File names
9725are recorded in object files as debugging symbols, but @value{GDBN} would
9726ordinarily parse a typical file name, like @file{foo.c}, as the three words
9727@samp{foo} @samp{.} @samp{c}. To allow @value{GDBN} to recognize
9728@samp{foo.c} as a single symbol, enclose it in single quotes; for example,
9729
474c8240 9730@smallexample
c906108c 9731p 'foo.c'::x
474c8240 9732@end smallexample
c906108c
SS
9733
9734@noindent
9735looks up the value of @code{x} in the scope of the file @file{foo.c}.
9736
9737@table @code
a8f24a35
EZ
9738@cindex case-insensitive symbol names
9739@cindex case sensitivity in symbol names
9740@kindex set case-sensitive
9741@item set case-sensitive on
9742@itemx set case-sensitive off
9743@itemx set case-sensitive auto
9744Normally, when @value{GDBN} looks up symbols, it matches their names
9745with case sensitivity determined by the current source language.
9746Occasionally, you may wish to control that. The command @code{set
9747case-sensitive} lets you do that by specifying @code{on} for
9748case-sensitive matches or @code{off} for case-insensitive ones. If
9749you specify @code{auto}, case sensitivity is reset to the default
9750suitable for the source language. The default is case-sensitive
9751matches for all languages except for Fortran, for which the default is
9752case-insensitive matches.
9753
9c16f35a
EZ
9754@kindex show case-sensitive
9755@item show case-sensitive
a8f24a35
EZ
9756This command shows the current setting of case sensitivity for symbols
9757lookups.
9758
c906108c 9759@kindex info address
b37052ae 9760@cindex address of a symbol
c906108c
SS
9761@item info address @var{symbol}
9762Describe where the data for @var{symbol} is stored. For a register
9763variable, this says which register it is kept in. For a non-register
9764local variable, this prints the stack-frame offset at which the variable
9765is always stored.
9766
9767Note the contrast with @samp{print &@var{symbol}}, which does not work
9768at all for a register variable, and for a stack local variable prints
9769the exact address of the current instantiation of the variable.
9770
3d67e040 9771@kindex info symbol
b37052ae 9772@cindex symbol from address
9c16f35a 9773@cindex closest symbol and offset for an address
3d67e040
EZ
9774@item info symbol @var{addr}
9775Print the name of a symbol which is stored at the address @var{addr}.
9776If no symbol is stored exactly at @var{addr}, @value{GDBN} prints the
9777nearest symbol and an offset from it:
9778
474c8240 9779@smallexample
3d67e040
EZ
9780(@value{GDBP}) info symbol 0x54320
9781_initialize_vx + 396 in section .text
474c8240 9782@end smallexample
3d67e040
EZ
9783
9784@noindent
9785This is the opposite of the @code{info address} command. You can use
9786it to find out the name of a variable or a function given its address.
9787
c906108c 9788@kindex whatis
d4f3574e
SS
9789@item whatis @var{expr}
9790Print the data type of expression @var{expr}. @var{expr} is not
c906108c
SS
9791actually evaluated, and any side-effecting operations (such as
9792assignments or function calls) inside it do not take place.
9793@xref{Expressions, ,Expressions}.
9794
9795@item whatis
9796Print the data type of @code{$}, the last value in the value history.
9797
9798@kindex ptype
9799@item ptype @var{typename}
9800Print a description of data type @var{typename}. @var{typename} may be
7a292a7a
SS
9801the name of a type, or for C code it may have the form @samp{class
9802@var{class-name}}, @samp{struct @var{struct-tag}}, @samp{union
9803@var{union-tag}} or @samp{enum @var{enum-tag}}.
c906108c 9804
d4f3574e 9805@item ptype @var{expr}
c906108c 9806@itemx ptype
d4f3574e 9807Print a description of the type of expression @var{expr}. @code{ptype}
c906108c
SS
9808differs from @code{whatis} by printing a detailed description, instead
9809of just the name of the type.
9810
9811For example, for this variable declaration:
9812
474c8240 9813@smallexample
c906108c 9814struct complex @{double real; double imag;@} v;
474c8240 9815@end smallexample
c906108c
SS
9816
9817@noindent
9818the two commands give this output:
9819
474c8240 9820@smallexample
c906108c
SS
9821@group
9822(@value{GDBP}) whatis v
9823type = struct complex
9824(@value{GDBP}) ptype v
9825type = struct complex @{
9826 double real;
9827 double imag;
9828@}
9829@end group
474c8240 9830@end smallexample
c906108c
SS
9831
9832@noindent
9833As with @code{whatis}, using @code{ptype} without an argument refers to
9834the type of @code{$}, the last value in the value history.
9835
9836@kindex info types
9837@item info types @var{regexp}
9838@itemx info types
09d4efe1
EZ
9839Print a brief description of all types whose names match the regular
9840expression @var{regexp} (or all types in your program, if you supply
9841no argument). Each complete typename is matched as though it were a
9842complete line; thus, @samp{i type value} gives information on all
9843types in your program whose names include the string @code{value}, but
9844@samp{i type ^value$} gives information only on types whose complete
9845name is @code{value}.
c906108c
SS
9846
9847This command differs from @code{ptype} in two ways: first, like
9848@code{whatis}, it does not print a detailed description; second, it
9849lists all source files where a type is defined.
9850
b37052ae
EZ
9851@kindex info scope
9852@cindex local variables
09d4efe1 9853@item info scope @var{location}
b37052ae 9854List all the variables local to a particular scope. This command
09d4efe1
EZ
9855accepts a @var{location} argument---a function name, a source line, or
9856an address preceded by a @samp{*}, and prints all the variables local
9857to the scope defined by that location. For example:
b37052ae
EZ
9858
9859@smallexample
9860(@value{GDBP}) @b{info scope command_line_handler}
9861Scope for command_line_handler:
9862Symbol rl is an argument at stack/frame offset 8, length 4.
9863Symbol linebuffer is in static storage at address 0x150a18, length 4.
9864Symbol linelength is in static storage at address 0x150a1c, length 4.
9865Symbol p is a local variable in register $esi, length 4.
9866Symbol p1 is a local variable in register $ebx, length 4.
9867Symbol nline is a local variable in register $edx, length 4.
9868Symbol repeat is a local variable at frame offset -8, length 4.
9869@end smallexample
9870
f5c37c66
EZ
9871@noindent
9872This command is especially useful for determining what data to collect
9873during a @dfn{trace experiment}, see @ref{Tracepoint Actions,
9874collect}.
9875
c906108c
SS
9876@kindex info source
9877@item info source
919d772c
JB
9878Show information about the current source file---that is, the source file for
9879the function containing the current point of execution:
9880@itemize @bullet
9881@item
9882the name of the source file, and the directory containing it,
9883@item
9884the directory it was compiled in,
9885@item
9886its length, in lines,
9887@item
9888which programming language it is written in,
9889@item
9890whether the executable includes debugging information for that file, and
9891if so, what format the information is in (e.g., STABS, Dwarf 2, etc.), and
9892@item
9893whether the debugging information includes information about
9894preprocessor macros.
9895@end itemize
9896
c906108c
SS
9897
9898@kindex info sources
9899@item info sources
9900Print the names of all source files in your program for which there is
9901debugging information, organized into two lists: files whose symbols
9902have already been read, and files whose symbols will be read when needed.
9903
9904@kindex info functions
9905@item info functions
9906Print the names and data types of all defined functions.
9907
9908@item info functions @var{regexp}
9909Print the names and data types of all defined functions
9910whose names contain a match for regular expression @var{regexp}.
9911Thus, @samp{info fun step} finds all functions whose names
9912include @code{step}; @samp{info fun ^step} finds those whose names
b383017d
RM
9913start with @code{step}. If a function name contains characters
9914that conflict with the regular expression language (eg.
1c5dfdad 9915@samp{operator*()}), they may be quoted with a backslash.
c906108c
SS
9916
9917@kindex info variables
9918@item info variables
9919Print the names and data types of all variables that are declared
6ca652b0 9920outside of functions (i.e.@: excluding local variables).
c906108c
SS
9921
9922@item info variables @var{regexp}
9923Print the names and data types of all variables (except for local
9924variables) whose names contain a match for regular expression
9925@var{regexp}.
9926
b37303ee
AF
9927@kindex info classes
9928@item info classes
9929@itemx info classes @var{regexp}
9930Display all Objective-C classes in your program, or
9931(with the @var{regexp} argument) all those matching a particular regular
9932expression.
9933
9934@kindex info selectors
9935@item info selectors
9936@itemx info selectors @var{regexp}
9937Display all Objective-C selectors in your program, or
9938(with the @var{regexp} argument) all those matching a particular regular
9939expression.
9940
c906108c
SS
9941@ignore
9942This was never implemented.
9943@kindex info methods
9944@item info methods
9945@itemx info methods @var{regexp}
9946The @code{info methods} command permits the user to examine all defined
b37052ae
EZ
9947methods within C@t{++} program, or (with the @var{regexp} argument) a
9948specific set of methods found in the various C@t{++} classes. Many
9949C@t{++} classes provide a large number of methods. Thus, the output
c906108c
SS
9950from the @code{ptype} command can be overwhelming and hard to use. The
9951@code{info-methods} command filters the methods, printing only those
9952which match the regular-expression @var{regexp}.
9953@end ignore
9954
c906108c
SS
9955@cindex reloading symbols
9956Some systems allow individual object files that make up your program to
7a292a7a
SS
9957be replaced without stopping and restarting your program. For example,
9958in VxWorks you can simply recompile a defective object file and keep on
9959running. If you are running on one of these systems, you can allow
9960@value{GDBN} to reload the symbols for automatically relinked modules:
c906108c
SS
9961
9962@table @code
9963@kindex set symbol-reloading
9964@item set symbol-reloading on
9965Replace symbol definitions for the corresponding source file when an
9966object file with a particular name is seen again.
9967
9968@item set symbol-reloading off
6d2ebf8b
SS
9969Do not replace symbol definitions when encountering object files of the
9970same name more than once. This is the default state; if you are not
9971running on a system that permits automatic relinking of modules, you
9972should leave @code{symbol-reloading} off, since otherwise @value{GDBN}
9973may discard symbols when linking large programs, that may contain
9974several modules (from different directories or libraries) with the same
9975name.
c906108c
SS
9976
9977@kindex show symbol-reloading
9978@item show symbol-reloading
9979Show the current @code{on} or @code{off} setting.
9980@end table
c906108c 9981
9c16f35a 9982@cindex opaque data types
c906108c
SS
9983@kindex set opaque-type-resolution
9984@item set opaque-type-resolution on
9985Tell @value{GDBN} to resolve opaque types. An opaque type is a type
9986declared as a pointer to a @code{struct}, @code{class}, or
9987@code{union}---for example, @code{struct MyType *}---that is used in one
9988source file although the full declaration of @code{struct MyType} is in
9989another source file. The default is on.
9990
9991A change in the setting of this subcommand will not take effect until
9992the next time symbols for a file are loaded.
9993
9994@item set opaque-type-resolution off
9995Tell @value{GDBN} not to resolve opaque types. In this case, the type
9996is printed as follows:
9997@smallexample
9998@{<no data fields>@}
9999@end smallexample
10000
10001@kindex show opaque-type-resolution
10002@item show opaque-type-resolution
10003Show whether opaque types are resolved or not.
c906108c
SS
10004
10005@kindex maint print symbols
10006@cindex symbol dump
10007@kindex maint print psymbols
10008@cindex partial symbol dump
10009@item maint print symbols @var{filename}
10010@itemx maint print psymbols @var{filename}
10011@itemx maint print msymbols @var{filename}
10012Write a dump of debugging symbol data into the file @var{filename}.
10013These commands are used to debug the @value{GDBN} symbol-reading code. Only
10014symbols with debugging data are included. If you use @samp{maint print
10015symbols}, @value{GDBN} includes all the symbols for which it has already
10016collected full details: that is, @var{filename} reflects symbols for
10017only those files whose symbols @value{GDBN} has read. You can use the
10018command @code{info sources} to find out which files these are. If you
10019use @samp{maint print psymbols} instead, the dump shows information about
10020symbols that @value{GDBN} only knows partially---that is, symbols defined in
10021files that @value{GDBN} has skimmed, but not yet read completely. Finally,
10022@samp{maint print msymbols} dumps just the minimal symbol information
10023required for each object file from which @value{GDBN} has read some symbols.
10024@xref{Files, ,Commands to specify files}, for a discussion of how
10025@value{GDBN} reads symbols (in the description of @code{symbol-file}).
44ea7b70 10026
5e7b2f39
JB
10027@kindex maint info symtabs
10028@kindex maint info psymtabs
44ea7b70
JB
10029@cindex listing @value{GDBN}'s internal symbol tables
10030@cindex symbol tables, listing @value{GDBN}'s internal
10031@cindex full symbol tables, listing @value{GDBN}'s internal
10032@cindex partial symbol tables, listing @value{GDBN}'s internal
5e7b2f39
JB
10033@item maint info symtabs @r{[} @var{regexp} @r{]}
10034@itemx maint info psymtabs @r{[} @var{regexp} @r{]}
44ea7b70
JB
10035
10036List the @code{struct symtab} or @code{struct partial_symtab}
10037structures whose names match @var{regexp}. If @var{regexp} is not
10038given, list them all. The output includes expressions which you can
10039copy into a @value{GDBN} debugging this one to examine a particular
10040structure in more detail. For example:
10041
10042@smallexample
5e7b2f39 10043(@value{GDBP}) maint info psymtabs dwarf2read
44ea7b70
JB
10044@{ objfile /home/gnu/build/gdb/gdb
10045 ((struct objfile *) 0x82e69d0)
b383017d 10046 @{ psymtab /home/gnu/src/gdb/dwarf2read.c
44ea7b70
JB
10047 ((struct partial_symtab *) 0x8474b10)
10048 readin no
10049 fullname (null)
10050 text addresses 0x814d3c8 -- 0x8158074
10051 globals (* (struct partial_symbol **) 0x8507a08 @@ 9)
10052 statics (* (struct partial_symbol **) 0x40e95b78 @@ 2882)
10053 dependencies (none)
10054 @}
10055@}
5e7b2f39 10056(@value{GDBP}) maint info symtabs
44ea7b70
JB
10057(@value{GDBP})
10058@end smallexample
10059@noindent
10060We see that there is one partial symbol table whose filename contains
10061the string @samp{dwarf2read}, belonging to the @samp{gdb} executable;
10062and we see that @value{GDBN} has not read in any symtabs yet at all.
10063If we set a breakpoint on a function, that will cause @value{GDBN} to
10064read the symtab for the compilation unit containing that function:
10065
10066@smallexample
10067(@value{GDBP}) break dwarf2_psymtab_to_symtab
10068Breakpoint 1 at 0x814e5da: file /home/gnu/src/gdb/dwarf2read.c,
10069line 1574.
5e7b2f39 10070(@value{GDBP}) maint info symtabs
b383017d 10071@{ objfile /home/gnu/build/gdb/gdb
44ea7b70 10072 ((struct objfile *) 0x82e69d0)
b383017d 10073 @{ symtab /home/gnu/src/gdb/dwarf2read.c
44ea7b70
JB
10074 ((struct symtab *) 0x86c1f38)
10075 dirname (null)
10076 fullname (null)
10077 blockvector ((struct blockvector *) 0x86c1bd0) (primary)
10078 debugformat DWARF 2
10079 @}
10080@}
b383017d 10081(@value{GDBP})
44ea7b70 10082@end smallexample
c906108c
SS
10083@end table
10084
44ea7b70 10085
6d2ebf8b 10086@node Altering
c906108c
SS
10087@chapter Altering Execution
10088
10089Once you think you have found an error in your program, you might want to
10090find out for certain whether correcting the apparent error would lead to
10091correct results in the rest of the run. You can find the answer by
10092experiment, using the @value{GDBN} features for altering execution of the
10093program.
10094
10095For example, you can store new values into variables or memory
7a292a7a
SS
10096locations, give your program a signal, restart it at a different
10097address, or even return prematurely from a function.
c906108c
SS
10098
10099@menu
10100* Assignment:: Assignment to variables
10101* Jumping:: Continuing at a different address
c906108c 10102* Signaling:: Giving your program a signal
c906108c
SS
10103* Returning:: Returning from a function
10104* Calling:: Calling your program's functions
10105* Patching:: Patching your program
10106@end menu
10107
6d2ebf8b 10108@node Assignment
c906108c
SS
10109@section Assignment to variables
10110
10111@cindex assignment
10112@cindex setting variables
10113To alter the value of a variable, evaluate an assignment expression.
10114@xref{Expressions, ,Expressions}. For example,
10115
474c8240 10116@smallexample
c906108c 10117print x=4
474c8240 10118@end smallexample
c906108c
SS
10119
10120@noindent
10121stores the value 4 into the variable @code{x}, and then prints the
5d161b24 10122value of the assignment expression (which is 4).
c906108c
SS
10123@xref{Languages, ,Using @value{GDBN} with Different Languages}, for more
10124information on operators in supported languages.
c906108c
SS
10125
10126@kindex set variable
10127@cindex variables, setting
10128If you are not interested in seeing the value of the assignment, use the
10129@code{set} command instead of the @code{print} command. @code{set} is
10130really the same as @code{print} except that the expression's value is
10131not printed and is not put in the value history (@pxref{Value History,
10132,Value history}). The expression is evaluated only for its effects.
10133
c906108c
SS
10134If the beginning of the argument string of the @code{set} command
10135appears identical to a @code{set} subcommand, use the @code{set
10136variable} command instead of just @code{set}. This command is identical
10137to @code{set} except for its lack of subcommands. For example, if your
10138program has a variable @code{width}, you get an error if you try to set
10139a new value with just @samp{set width=13}, because @value{GDBN} has the
10140command @code{set width}:
10141
474c8240 10142@smallexample
c906108c
SS
10143(@value{GDBP}) whatis width
10144type = double
10145(@value{GDBP}) p width
10146$4 = 13
10147(@value{GDBP}) set width=47
10148Invalid syntax in expression.
474c8240 10149@end smallexample
c906108c
SS
10150
10151@noindent
10152The invalid expression, of course, is @samp{=47}. In
10153order to actually set the program's variable @code{width}, use
10154
474c8240 10155@smallexample
c906108c 10156(@value{GDBP}) set var width=47
474c8240 10157@end smallexample
53a5351d 10158
c906108c
SS
10159Because the @code{set} command has many subcommands that can conflict
10160with the names of program variables, it is a good idea to use the
10161@code{set variable} command instead of just @code{set}. For example, if
10162your program has a variable @code{g}, you run into problems if you try
10163to set a new value with just @samp{set g=4}, because @value{GDBN} has
10164the command @code{set gnutarget}, abbreviated @code{set g}:
10165
474c8240 10166@smallexample
c906108c
SS
10167@group
10168(@value{GDBP}) whatis g
10169type = double
10170(@value{GDBP}) p g
10171$1 = 1
10172(@value{GDBP}) set g=4
2df3850c 10173(@value{GDBP}) p g
c906108c
SS
10174$2 = 1
10175(@value{GDBP}) r
10176The program being debugged has been started already.
10177Start it from the beginning? (y or n) y
10178Starting program: /home/smith/cc_progs/a.out
6d2ebf8b
SS
10179"/home/smith/cc_progs/a.out": can't open to read symbols:
10180 Invalid bfd target.
c906108c
SS
10181(@value{GDBP}) show g
10182The current BFD target is "=4".
10183@end group
474c8240 10184@end smallexample
c906108c
SS
10185
10186@noindent
10187The program variable @code{g} did not change, and you silently set the
10188@code{gnutarget} to an invalid value. In order to set the variable
10189@code{g}, use
10190
474c8240 10191@smallexample
c906108c 10192(@value{GDBP}) set var g=4
474c8240 10193@end smallexample
c906108c
SS
10194
10195@value{GDBN} allows more implicit conversions in assignments than C; you can
10196freely store an integer value into a pointer variable or vice versa,
10197and you can convert any structure to any other structure that is the
10198same length or shorter.
10199@comment FIXME: how do structs align/pad in these conversions?
10200@comment /doc@cygnus.com 18dec1990
10201
10202To store values into arbitrary places in memory, use the @samp{@{@dots{}@}}
10203construct to generate a value of specified type at a specified address
10204(@pxref{Expressions, ,Expressions}). For example, @code{@{int@}0x83040} refers
10205to memory location @code{0x83040} as an integer (which implies a certain size
10206and representation in memory), and
10207
474c8240 10208@smallexample
c906108c 10209set @{int@}0x83040 = 4
474c8240 10210@end smallexample
c906108c
SS
10211
10212@noindent
10213stores the value 4 into that memory location.
10214
6d2ebf8b 10215@node Jumping
c906108c
SS
10216@section Continuing at a different address
10217
10218Ordinarily, when you continue your program, you do so at the place where
10219it stopped, with the @code{continue} command. You can instead continue at
10220an address of your own choosing, with the following commands:
10221
10222@table @code
10223@kindex jump
10224@item jump @var{linespec}
10225Resume execution at line @var{linespec}. Execution stops again
10226immediately if there is a breakpoint there. @xref{List, ,Printing
10227source lines}, for a description of the different forms of
10228@var{linespec}. It is common practice to use the @code{tbreak} command
10229in conjunction with @code{jump}. @xref{Set Breaks, ,Setting
10230breakpoints}.
10231
10232The @code{jump} command does not change the current stack frame, or
10233the stack pointer, or the contents of any memory location or any
10234register other than the program counter. If line @var{linespec} is in
10235a different function from the one currently executing, the results may
10236be bizarre if the two functions expect different patterns of arguments or
10237of local variables. For this reason, the @code{jump} command requests
10238confirmation if the specified line is not in the function currently
10239executing. However, even bizarre results are predictable if you are
10240well acquainted with the machine-language code of your program.
10241
10242@item jump *@var{address}
10243Resume execution at the instruction at address @var{address}.
10244@end table
10245
c906108c 10246@c Doesn't work on HP-UX; have to set $pcoqh and $pcoqt.
53a5351d
JM
10247On many systems, you can get much the same effect as the @code{jump}
10248command by storing a new value into the register @code{$pc}. The
10249difference is that this does not start your program running; it only
10250changes the address of where it @emph{will} run when you continue. For
10251example,
c906108c 10252
474c8240 10253@smallexample
c906108c 10254set $pc = 0x485
474c8240 10255@end smallexample
c906108c
SS
10256
10257@noindent
10258makes the next @code{continue} command or stepping command execute at
10259address @code{0x485}, rather than at the address where your program stopped.
10260@xref{Continuing and Stepping, ,Continuing and stepping}.
c906108c
SS
10261
10262The most common occasion to use the @code{jump} command is to back
10263up---perhaps with more breakpoints set---over a portion of a program
10264that has already executed, in order to examine its execution in more
10265detail.
10266
c906108c 10267@c @group
6d2ebf8b 10268@node Signaling
c906108c 10269@section Giving your program a signal
9c16f35a 10270@cindex deliver a signal to a program
c906108c
SS
10271
10272@table @code
10273@kindex signal
10274@item signal @var{signal}
10275Resume execution where your program stopped, but immediately give it the
10276signal @var{signal}. @var{signal} can be the name or the number of a
10277signal. For example, on many systems @code{signal 2} and @code{signal
10278SIGINT} are both ways of sending an interrupt signal.
10279
10280Alternatively, if @var{signal} is zero, continue execution without
10281giving a signal. This is useful when your program stopped on account of
10282a signal and would ordinary see the signal when resumed with the
10283@code{continue} command; @samp{signal 0} causes it to resume without a
10284signal.
10285
10286@code{signal} does not repeat when you press @key{RET} a second time
10287after executing the command.
10288@end table
10289@c @end group
10290
10291Invoking the @code{signal} command is not the same as invoking the
10292@code{kill} utility from the shell. Sending a signal with @code{kill}
10293causes @value{GDBN} to decide what to do with the signal depending on
10294the signal handling tables (@pxref{Signals}). The @code{signal} command
10295passes the signal directly to your program.
10296
c906108c 10297
6d2ebf8b 10298@node Returning
c906108c
SS
10299@section Returning from a function
10300
10301@table @code
10302@cindex returning from a function
10303@kindex return
10304@item return
10305@itemx return @var{expression}
10306You can cancel execution of a function call with the @code{return}
10307command. If you give an
10308@var{expression} argument, its value is used as the function's return
10309value.
10310@end table
10311
10312When you use @code{return}, @value{GDBN} discards the selected stack frame
10313(and all frames within it). You can think of this as making the
10314discarded frame return prematurely. If you wish to specify a value to
10315be returned, give that value as the argument to @code{return}.
10316
10317This pops the selected stack frame (@pxref{Selection, ,Selecting a
10318frame}), and any other frames inside of it, leaving its caller as the
10319innermost remaining frame. That frame becomes selected. The
10320specified value is stored in the registers used for returning values
10321of functions.
10322
10323The @code{return} command does not resume execution; it leaves the
10324program stopped in the state that would exist if the function had just
10325returned. In contrast, the @code{finish} command (@pxref{Continuing
10326and Stepping, ,Continuing and stepping}) resumes execution until the
10327selected stack frame returns naturally.
10328
6d2ebf8b 10329@node Calling
c906108c
SS
10330@section Calling program functions
10331
f8568604 10332@table @code
c906108c 10333@cindex calling functions
f8568604
EZ
10334@cindex inferior functions, calling
10335@item print @var{expr}
9c16f35a 10336Evaluate the expression @var{expr} and display the resuling value.
f8568604
EZ
10337@var{expr} may include calls to functions in the program being
10338debugged.
10339
c906108c 10340@kindex call
c906108c
SS
10341@item call @var{expr}
10342Evaluate the expression @var{expr} without displaying @code{void}
10343returned values.
c906108c
SS
10344
10345You can use this variant of the @code{print} command if you want to
f8568604
EZ
10346execute a function from your program that does not return anything
10347(a.k.a.@: @dfn{a void function}), but without cluttering the output
10348with @code{void} returned values that @value{GDBN} will otherwise
10349print. If the result is not void, it is printed and saved in the
10350value history.
10351@end table
10352
9c16f35a
EZ
10353It is possible for the function you call via the @code{print} or
10354@code{call} command to generate a signal (e.g., if there's a bug in
10355the function, or if you passed it incorrect arguments). What happens
10356in that case is controlled by the @code{set unwindonsignal} command.
10357
10358@table @code
10359@item set unwindonsignal
10360@kindex set unwindonsignal
10361@cindex unwind stack in called functions
10362@cindex call dummy stack unwinding
10363Set unwinding of the stack if a signal is received while in a function
10364that @value{GDBN} called in the program being debugged. If set to on,
10365@value{GDBN} unwinds the stack it created for the call and restores
10366the context to what it was before the call. If set to off (the
10367default), @value{GDBN} stops in the frame where the signal was
10368received.
10369
10370@item show unwindonsignal
10371@kindex show unwindonsignal
10372Show the current setting of stack unwinding in the functions called by
10373@value{GDBN}.
10374@end table
10375
f8568604
EZ
10376@cindex weak alias functions
10377Sometimes, a function you wish to call is actually a @dfn{weak alias}
10378for another function. In such case, @value{GDBN} might not pick up
10379the type information, including the types of the function arguments,
10380which causes @value{GDBN} to call the inferior function incorrectly.
10381As a result, the called function will function erroneously and may
10382even crash. A solution to that is to use the name of the aliased
10383function instead.
c906108c 10384
6d2ebf8b 10385@node Patching
c906108c 10386@section Patching programs
7a292a7a 10387
c906108c
SS
10388@cindex patching binaries
10389@cindex writing into executables
c906108c 10390@cindex writing into corefiles
c906108c 10391
7a292a7a
SS
10392By default, @value{GDBN} opens the file containing your program's
10393executable code (or the corefile) read-only. This prevents accidental
10394alterations to machine code; but it also prevents you from intentionally
10395patching your program's binary.
c906108c
SS
10396
10397If you'd like to be able to patch the binary, you can specify that
10398explicitly with the @code{set write} command. For example, you might
10399want to turn on internal debugging flags, or even to make emergency
10400repairs.
10401
10402@table @code
10403@kindex set write
10404@item set write on
10405@itemx set write off
7a292a7a
SS
10406If you specify @samp{set write on}, @value{GDBN} opens executable and
10407core files for both reading and writing; if you specify @samp{set write
c906108c
SS
10408off} (the default), @value{GDBN} opens them read-only.
10409
10410If you have already loaded a file, you must load it again (using the
7a292a7a
SS
10411@code{exec-file} or @code{core-file} command) after changing @code{set
10412write}, for your new setting to take effect.
c906108c
SS
10413
10414@item show write
10415@kindex show write
7a292a7a
SS
10416Display whether executable files and core files are opened for writing
10417as well as reading.
c906108c
SS
10418@end table
10419
6d2ebf8b 10420@node GDB Files
c906108c
SS
10421@chapter @value{GDBN} Files
10422
7a292a7a
SS
10423@value{GDBN} needs to know the file name of the program to be debugged,
10424both in order to read its symbol table and in order to start your
10425program. To debug a core dump of a previous run, you must also tell
10426@value{GDBN} the name of the core dump file.
c906108c
SS
10427
10428@menu
10429* Files:: Commands to specify files
5b5d99cf 10430* Separate Debug Files:: Debugging information in separate files
c906108c
SS
10431* Symbol Errors:: Errors reading symbol files
10432@end menu
10433
6d2ebf8b 10434@node Files
c906108c 10435@section Commands to specify files
c906108c 10436
7a292a7a 10437@cindex symbol table
c906108c 10438@cindex core dump file
7a292a7a
SS
10439
10440You may want to specify executable and core dump file names. The usual
10441way to do this is at start-up time, using the arguments to
10442@value{GDBN}'s start-up commands (@pxref{Invocation, , Getting In and
10443Out of @value{GDBN}}).
c906108c
SS
10444
10445Occasionally it is necessary to change to a different file during a
10446@value{GDBN} session. Or you may run @value{GDBN} and forget to specify
10447a file you want to use. In these situations the @value{GDBN} commands
10448to specify new files are useful.
10449
10450@table @code
10451@cindex executable file
10452@kindex file
10453@item file @var{filename}
10454Use @var{filename} as the program to be debugged. It is read for its
10455symbols and for the contents of pure memory. It is also the program
10456executed when you use the @code{run} command. If you do not specify a
5d161b24
DB
10457directory and the file is not found in the @value{GDBN} working directory,
10458@value{GDBN} uses the environment variable @code{PATH} as a list of
10459directories to search, just as the shell does when looking for a program
10460to run. You can change the value of this variable, for both @value{GDBN}
c906108c
SS
10461and your program, using the @code{path} command.
10462
6d2ebf8b 10463On systems with memory-mapped files, an auxiliary file named
c906108c
SS
10464@file{@var{filename}.syms} may hold symbol table information for
10465@var{filename}. If so, @value{GDBN} maps in the symbol table from
10466@file{@var{filename}.syms}, starting up more quickly. See the
10467descriptions of the file options @samp{-mapped} and @samp{-readnow}
7b5ba0cc
EZ
10468(available on the command line, see @ref{File Options, , -readnow},
10469and with the commands @code{file}, @code{symbol-file}, or
10470@code{add-symbol-file}, described below), for more information.
c906108c
SS
10471
10472@item file
10473@code{file} with no argument makes @value{GDBN} discard any information it
10474has on both executable file and the symbol table.
10475
10476@kindex exec-file
10477@item exec-file @r{[} @var{filename} @r{]}
10478Specify that the program to be run (but not the symbol table) is found
10479in @var{filename}. @value{GDBN} searches the environment variable @code{PATH}
10480if necessary to locate your program. Omitting @var{filename} means to
10481discard information on the executable file.
10482
10483@kindex symbol-file
10484@item symbol-file @r{[} @var{filename} @r{]}
10485Read symbol table information from file @var{filename}. @code{PATH} is
10486searched when necessary. Use the @code{file} command to get both symbol
10487table and program to run from the same file.
10488
10489@code{symbol-file} with no argument clears out @value{GDBN} information on your
10490program's symbol table.
10491
5d161b24 10492The @code{symbol-file} command causes @value{GDBN} to forget the contents
c906108c
SS
10493of its convenience variables, the value history, and all breakpoints and
10494auto-display expressions. This is because they may contain pointers to
10495the internal data recording symbols and data types, which are part of
10496the old symbol table data being discarded inside @value{GDBN}.
10497
10498@code{symbol-file} does not repeat if you press @key{RET} again after
10499executing it once.
10500
10501When @value{GDBN} is configured for a particular environment, it
10502understands debugging information in whatever format is the standard
10503generated for that environment; you may use either a @sc{gnu} compiler, or
10504other compilers that adhere to the local conventions.
c906108c
SS
10505Best results are usually obtained from @sc{gnu} compilers; for example,
10506using @code{@value{GCC}} you can generate debugging information for
10507optimized code.
c906108c
SS
10508
10509For most kinds of object files, with the exception of old SVR3 systems
10510using COFF, the @code{symbol-file} command does not normally read the
10511symbol table in full right away. Instead, it scans the symbol table
10512quickly to find which source files and which symbols are present. The
10513details are read later, one source file at a time, as they are needed.
10514
10515The purpose of this two-stage reading strategy is to make @value{GDBN}
10516start up faster. For the most part, it is invisible except for
10517occasional pauses while the symbol table details for a particular source
10518file are being read. (The @code{set verbose} command can turn these
10519pauses into messages if desired. @xref{Messages/Warnings, ,Optional
10520warnings and messages}.)
10521
c906108c
SS
10522We have not implemented the two-stage strategy for COFF yet. When the
10523symbol table is stored in COFF format, @code{symbol-file} reads the
10524symbol table data in full right away. Note that ``stabs-in-COFF''
10525still does the two-stage strategy, since the debug info is actually
10526in stabs format.
10527
10528@kindex readnow
10529@cindex reading symbols immediately
10530@cindex symbols, reading immediately
10531@kindex mapped
10532@cindex memory-mapped symbol file
10533@cindex saving symbol table
10534@item symbol-file @var{filename} @r{[} -readnow @r{]} @r{[} -mapped @r{]}
10535@itemx file @var{filename} @r{[} -readnow @r{]} @r{[} -mapped @r{]}
10536You can override the @value{GDBN} two-stage strategy for reading symbol
10537tables by using the @samp{-readnow} option with any of the commands that
10538load symbol table information, if you want to be sure @value{GDBN} has the
5d161b24 10539entire symbol table available.
c906108c 10540
c906108c
SS
10541If memory-mapped files are available on your system through the
10542@code{mmap} system call, you can use another option, @samp{-mapped}, to
10543cause @value{GDBN} to write the symbols for your program into a reusable
10544file. Future @value{GDBN} debugging sessions map in symbol information
10545from this auxiliary symbol file (if the program has not changed), rather
10546than spending time reading the symbol table from the executable
10547program. Using the @samp{-mapped} option has the same effect as
10548starting @value{GDBN} with the @samp{-mapped} command-line option.
10549
10550You can use both options together, to make sure the auxiliary symbol
10551file has all the symbol information for your program.
10552
10553The auxiliary symbol file for a program called @var{myprog} is called
10554@samp{@var{myprog}.syms}. Once this file exists (so long as it is newer
10555than the corresponding executable), @value{GDBN} always attempts to use
10556it when you debug @var{myprog}; no special options or commands are
10557needed.
10558
10559The @file{.syms} file is specific to the host machine where you run
10560@value{GDBN}. It holds an exact image of the internal @value{GDBN}
10561symbol table. It cannot be shared across multiple host platforms.
c906108c
SS
10562
10563@c FIXME: for now no mention of directories, since this seems to be in
10564@c flux. 13mar1992 status is that in theory GDB would look either in
10565@c current dir or in same dir as myprog; but issues like competing
10566@c GDB's, or clutter in system dirs, mean that in practice right now
10567@c only current dir is used. FFish says maybe a special GDB hierarchy
10568@c (eg rooted in val of env var GDBSYMS) could exist for mappable symbol
10569@c files.
10570
c906108c 10571@kindex core-file
09d4efe1 10572@item core-file @r{[}@var{filename}@r{]}
4644b6e3 10573@itemx core
c906108c
SS
10574Specify the whereabouts of a core dump file to be used as the ``contents
10575of memory''. Traditionally, core files contain only some parts of the
10576address space of the process that generated them; @value{GDBN} can access the
10577executable file itself for other parts.
10578
10579@code{core-file} with no argument specifies that no core file is
10580to be used.
10581
10582Note that the core file is ignored when your program is actually running
7a292a7a
SS
10583under @value{GDBN}. So, if you have been running your program and you
10584wish to debug a core file instead, you must kill the subprocess in which
10585the program is running. To do this, use the @code{kill} command
c906108c 10586(@pxref{Kill Process, ,Killing the child process}).
c906108c 10587
c906108c
SS
10588@kindex add-symbol-file
10589@cindex dynamic linking
10590@item add-symbol-file @var{filename} @var{address}
10591@itemx add-symbol-file @var{filename} @var{address} @r{[} -readnow @r{]} @r{[} -mapped @r{]}
17d9d558 10592@itemx add-symbol-file @var{filename} @r{-s}@var{section} @var{address} @dots{}
96a2c332
SS
10593The @code{add-symbol-file} command reads additional symbol table
10594information from the file @var{filename}. You would use this command
10595when @var{filename} has been dynamically loaded (by some other means)
10596into the program that is running. @var{address} should be the memory
10597address at which the file has been loaded; @value{GDBN} cannot figure
d167840f
EZ
10598this out for itself. You can additionally specify an arbitrary number
10599of @samp{@r{-s}@var{section} @var{address}} pairs, to give an explicit
10600section name and base address for that section. You can specify any
10601@var{address} as an expression.
c906108c
SS
10602
10603The symbol table of the file @var{filename} is added to the symbol table
10604originally read with the @code{symbol-file} command. You can use the
96a2c332
SS
10605@code{add-symbol-file} command any number of times; the new symbol data
10606thus read keeps adding to the old. To discard all old symbol data
10607instead, use the @code{symbol-file} command without any arguments.
c906108c 10608
17d9d558
JB
10609@cindex relocatable object files, reading symbols from
10610@cindex object files, relocatable, reading symbols from
10611@cindex reading symbols from relocatable object files
10612@cindex symbols, reading from relocatable object files
10613@cindex @file{.o} files, reading symbols from
10614Although @var{filename} is typically a shared library file, an
10615executable file, or some other object file which has been fully
10616relocated for loading into a process, you can also load symbolic
10617information from relocatable @file{.o} files, as long as:
10618
10619@itemize @bullet
10620@item
10621the file's symbolic information refers only to linker symbols defined in
10622that file, not to symbols defined by other object files,
10623@item
10624every section the file's symbolic information refers to has actually
10625been loaded into the inferior, as it appears in the file, and
10626@item
10627you can determine the address at which every section was loaded, and
10628provide these to the @code{add-symbol-file} command.
10629@end itemize
10630
10631@noindent
10632Some embedded operating systems, like Sun Chorus and VxWorks, can load
10633relocatable files into an already running program; such systems
10634typically make the requirements above easy to meet. However, it's
10635important to recognize that many native systems use complex link
49efadf5 10636procedures (@code{.linkonce} section factoring and C@t{++} constructor table
17d9d558
JB
10637assembly, for example) that make the requirements difficult to meet. In
10638general, one cannot assume that using @code{add-symbol-file} to read a
10639relocatable object file's symbolic information will have the same effect
10640as linking the relocatable object file into the program in the normal
10641way.
10642
c906108c
SS
10643@code{add-symbol-file} does not repeat if you press @key{RET} after using it.
10644
10645You can use the @samp{-mapped} and @samp{-readnow} options just as with
10646the @code{symbol-file} command, to change how @value{GDBN} manages the symbol
10647table information for @var{filename}.
10648
09d4efe1
EZ
10649@kindex add-shared-symbol-files
10650@kindex assf
10651@item add-shared-symbol-files @var{library-file}
10652@itemx assf @var{library-file}
10653The @code{add-shared-symbol-files} command can currently be used only
10654in the Cygwin build of @value{GDBN} on MS-Windows OS, where it is an
10655alias for the @code{dll-symbols} command (@pxref{Cygwin Native}).
10656@value{GDBN} automatically looks for shared libraries, however if
10657@value{GDBN} does not find yours, you can invoke
10658@code{add-shared-symbol-files}. It takes one argument: the shared
10659library's file name. @code{assf} is a shorthand alias for
10660@code{add-shared-symbol-files}.
c906108c 10661
c906108c 10662@kindex section
09d4efe1
EZ
10663@item section @var{section} @var{addr}
10664The @code{section} command changes the base address of the named
10665@var{section} of the exec file to @var{addr}. This can be used if the
10666exec file does not contain section addresses, (such as in the
10667@code{a.out} format), or when the addresses specified in the file
10668itself are wrong. Each section must be changed separately. The
10669@code{info files} command, described below, lists all the sections and
10670their addresses.
c906108c
SS
10671
10672@kindex info files
10673@kindex info target
10674@item info files
10675@itemx info target
7a292a7a
SS
10676@code{info files} and @code{info target} are synonymous; both print the
10677current target (@pxref{Targets, ,Specifying a Debugging Target}),
10678including the names of the executable and core dump files currently in
10679use by @value{GDBN}, and the files from which symbols were loaded. The
10680command @code{help target} lists all possible targets rather than
10681current ones.
10682
fe95c787
MS
10683@kindex maint info sections
10684@item maint info sections
10685Another command that can give you extra information about program sections
10686is @code{maint info sections}. In addition to the section information
10687displayed by @code{info files}, this command displays the flags and file
10688offset of each section in the executable and core dump files. In addition,
10689@code{maint info sections} provides the following command options (which
10690may be arbitrarily combined):
10691
10692@table @code
10693@item ALLOBJ
10694Display sections for all loaded object files, including shared libraries.
10695@item @var{sections}
6600abed 10696Display info only for named @var{sections}.
fe95c787
MS
10697@item @var{section-flags}
10698Display info only for sections for which @var{section-flags} are true.
10699The section flags that @value{GDBN} currently knows about are:
10700@table @code
10701@item ALLOC
10702Section will have space allocated in the process when loaded.
10703Set for all sections except those containing debug information.
10704@item LOAD
10705Section will be loaded from the file into the child process memory.
10706Set for pre-initialized code and data, clear for @code{.bss} sections.
10707@item RELOC
10708Section needs to be relocated before loading.
10709@item READONLY
10710Section cannot be modified by the child process.
10711@item CODE
10712Section contains executable code only.
6600abed 10713@item DATA
fe95c787
MS
10714Section contains data only (no executable code).
10715@item ROM
10716Section will reside in ROM.
10717@item CONSTRUCTOR
10718Section contains data for constructor/destructor lists.
10719@item HAS_CONTENTS
10720Section is not empty.
10721@item NEVER_LOAD
10722An instruction to the linker to not output the section.
10723@item COFF_SHARED_LIBRARY
10724A notification to the linker that the section contains
10725COFF shared library information.
10726@item IS_COMMON
10727Section contains common symbols.
10728@end table
10729@end table
6763aef9 10730@kindex set trust-readonly-sections
9c16f35a 10731@cindex read-only sections
6763aef9
MS
10732@item set trust-readonly-sections on
10733Tell @value{GDBN} that readonly sections in your object file
6ca652b0 10734really are read-only (i.e.@: that their contents will not change).
6763aef9
MS
10735In that case, @value{GDBN} can fetch values from these sections
10736out of the object file, rather than from the target program.
10737For some targets (notably embedded ones), this can be a significant
10738enhancement to debugging performance.
10739
10740The default is off.
10741
10742@item set trust-readonly-sections off
15110bc3 10743Tell @value{GDBN} not to trust readonly sections. This means that
6763aef9
MS
10744the contents of the section might change while the program is running,
10745and must therefore be fetched from the target when needed.
9c16f35a
EZ
10746
10747@item show trust-readonly-sections
10748Show the current setting of trusting readonly sections.
c906108c
SS
10749@end table
10750
10751All file-specifying commands allow both absolute and relative file names
10752as arguments. @value{GDBN} always converts the file name to an absolute file
10753name and remembers it that way.
10754
c906108c 10755@cindex shared libraries
9c16f35a
EZ
10756@value{GDBN} supports GNU/Linux, MS-Windows, HP-UX, SunOS, SVr4, Irix,
10757and IBM RS/6000 AIX shared libraries.
53a5351d 10758
c906108c
SS
10759@value{GDBN} automatically loads symbol definitions from shared libraries
10760when you use the @code{run} command, or when you examine a core file.
10761(Before you issue the @code{run} command, @value{GDBN} does not understand
10762references to a function in a shared library, however---unless you are
10763debugging a core file).
53a5351d
JM
10764
10765On HP-UX, if the program loads a library explicitly, @value{GDBN}
10766automatically loads the symbols at the time of the @code{shl_load} call.
10767
c906108c
SS
10768@c FIXME: some @value{GDBN} release may permit some refs to undef
10769@c FIXME...symbols---eg in a break cmd---assuming they are from a shared
10770@c FIXME...lib; check this from time to time when updating manual
10771
b7209cb4
FF
10772There are times, however, when you may wish to not automatically load
10773symbol definitions from shared libraries, such as when they are
10774particularly large or there are many of them.
10775
10776To control the automatic loading of shared library symbols, use the
10777commands:
10778
10779@table @code
10780@kindex set auto-solib-add
10781@item set auto-solib-add @var{mode}
10782If @var{mode} is @code{on}, symbols from all shared object libraries
10783will be loaded automatically when the inferior begins execution, you
10784attach to an independently started inferior, or when the dynamic linker
10785informs @value{GDBN} that a new library has been loaded. If @var{mode}
10786is @code{off}, symbols must be loaded manually, using the
10787@code{sharedlibrary} command. The default value is @code{on}.
10788
dcaf7c2c
EZ
10789@cindex memory used for symbol tables
10790If your program uses lots of shared libraries with debug info that
10791takes large amounts of memory, you can decrease the @value{GDBN}
10792memory footprint by preventing it from automatically loading the
10793symbols from shared libraries. To that end, type @kbd{set
10794auto-solib-add off} before running the inferior, then load each
10795library whose debug symbols you do need with @kbd{sharedlibrary
10796@var{regexp}}, where @var{regexp} is a regular expresion that matches
10797the libraries whose symbols you want to be loaded.
10798
b7209cb4
FF
10799@kindex show auto-solib-add
10800@item show auto-solib-add
10801Display the current autoloading mode.
10802@end table
10803
10804To explicitly load shared library symbols, use the @code{sharedlibrary}
10805command:
10806
c906108c
SS
10807@table @code
10808@kindex info sharedlibrary
10809@kindex info share
10810@item info share
10811@itemx info sharedlibrary
10812Print the names of the shared libraries which are currently loaded.
10813
10814@kindex sharedlibrary
10815@kindex share
10816@item sharedlibrary @var{regex}
10817@itemx share @var{regex}
c906108c
SS
10818Load shared object library symbols for files matching a
10819Unix regular expression.
10820As with files loaded automatically, it only loads shared libraries
10821required by your program for a core file or after typing @code{run}. If
10822@var{regex} is omitted all shared libraries required by your program are
10823loaded.
10824@end table
10825
b7209cb4
FF
10826On some systems, such as HP-UX systems, @value{GDBN} supports
10827autoloading shared library symbols until a limiting threshold size is
10828reached. This provides the benefit of allowing autoloading to remain on
10829by default, but avoids autoloading excessively large shared libraries,
10830up to a threshold that is initially set, but which you can modify if you
10831wish.
c906108c
SS
10832
10833Beyond that threshold, symbols from shared libraries must be explicitly
d4f3574e
SS
10834loaded. To load these symbols, use the command @code{sharedlibrary
10835@var{filename}}. The base address of the shared library is determined
c906108c
SS
10836automatically by @value{GDBN} and need not be specified.
10837
10838To display or set the threshold, use the commands:
10839
10840@table @code
b7209cb4
FF
10841@kindex set auto-solib-limit
10842@item set auto-solib-limit @var{threshold}
10843Set the autoloading size threshold, in an integral number of megabytes.
10844If @var{threshold} is nonzero and shared library autoloading is enabled,
10845symbols from all shared object libraries will be loaded until the total
10846size of the loaded shared library symbols exceeds this threshold.
c906108c 10847Otherwise, symbols must be loaded manually, using the
6ca652b0 10848@code{sharedlibrary} command. The default threshold is 100 (i.e.@: 100
b7209cb4 10849Mb).
c906108c 10850
b7209cb4
FF
10851@kindex show auto-solib-limit
10852@item show auto-solib-limit
c906108c
SS
10853Display the current autoloading size threshold, in megabytes.
10854@end table
c906108c 10855
f5ebfba0
DJ
10856Shared libraries are also supported in many cross or remote debugging
10857configurations. A copy of the target's libraries need to be present on the
10858host system; they need to be the same as the target libraries, although the
10859copies on the target can be stripped as long as the copies on the host are
10860not.
10861
10862You need to tell @value{GDBN} where the target libraries are, so that it can
10863load the correct copies---otherwise, it may try to load the host's libraries.
10864@value{GDBN} has two variables to specify the search directories for target
10865libraries.
10866
10867@table @code
10868@kindex set solib-absolute-prefix
10869@item set solib-absolute-prefix @var{path}
10870If this variable is set, @var{path} will be used as a prefix for any
10871absolute shared library paths; many runtime loaders store the absolute
10872paths to the shared library in the target program's memory. If you use
10873@samp{solib-absolute-prefix} to find shared libraries, they need to be laid
10874out in the same way that they are on the target, with e.g.@: a
10875@file{/usr/lib} hierarchy under @var{path}.
10876
10877You can set the default value of @samp{solib-absolute-prefix} by using the
10878configure-time @samp{--with-sysroot} option.
10879
10880@kindex show solib-absolute-prefix
10881@item show solib-absolute-prefix
10882Display the current shared library prefix.
10883
10884@kindex set solib-search-path
10885@item set solib-search-path @var{path}
10886If this variable is set, @var{path} is a colon-separated list of directories
10887to search for shared libraries. @samp{solib-search-path} is used after
10888@samp{solib-absolute-prefix} fails to locate the library, or if the path to
10889the library is relative instead of absolute. If you want to use
10890@samp{solib-search-path} instead of @samp{solib-absolute-prefix}, be sure to
10891set @samp{solib-absolute-prefix} to a nonexistant directory to prevent
10892@value{GDBN} from finding your host's libraries.
10893
10894@kindex show solib-search-path
10895@item show solib-search-path
10896Display the current shared library search path.
10897@end table
10898
5b5d99cf
JB
10899
10900@node Separate Debug Files
10901@section Debugging Information in Separate Files
10902@cindex separate debugging information files
10903@cindex debugging information in separate files
10904@cindex @file{.debug} subdirectories
10905@cindex debugging information directory, global
10906@cindex global debugging information directory
10907
10908@value{GDBN} allows you to put a program's debugging information in a
10909file separate from the executable itself, in a way that allows
10910@value{GDBN} to find and load the debugging information automatically.
10911Since debugging information can be very large --- sometimes larger
10912than the executable code itself --- some systems distribute debugging
10913information for their executables in separate files, which users can
10914install only when they need to debug a problem.
10915
10916If an executable's debugging information has been extracted to a
10917separate file, the executable should contain a @dfn{debug link} giving
10918the name of the debugging information file (with no directory
10919components), and a checksum of its contents. (The exact form of a
10920debug link is described below.) If the full name of the directory
10921containing the executable is @var{execdir}, and the executable has a
10922debug link that specifies the name @var{debugfile}, then @value{GDBN}
10923will automatically search for the debugging information file in three
10924places:
10925
10926@itemize @bullet
10927@item
10928the directory containing the executable file (that is, it will look
10929for a file named @file{@var{execdir}/@var{debugfile}},
10930@item
10931a subdirectory of that directory named @file{.debug} (that is, the
10932file @file{@var{execdir}/.debug/@var{debugfile}}, and
10933@item
10934a subdirectory of the global debug file directory that includes the
10935executable's full path, and the name from the link (that is, the file
10936@file{@var{globaldebugdir}/@var{execdir}/@var{debugfile}}, where
10937@var{globaldebugdir} is the global debug file directory, and
10938@var{execdir} has been turned into a relative path).
10939@end itemize
10940@noindent
10941@value{GDBN} checks under each of these names for a debugging
10942information file whose checksum matches that given in the link, and
10943reads the debugging information from the first one it finds.
10944
10945So, for example, if you ask @value{GDBN} to debug @file{/usr/bin/ls},
10946which has a link containing the name @file{ls.debug}, and the global
10947debug directory is @file{/usr/lib/debug}, then @value{GDBN} will look
10948for debug information in @file{/usr/bin/ls.debug},
10949@file{/usr/bin/.debug/ls.debug}, and
10950@file{/usr/lib/debug/usr/bin/ls.debug}.
10951
10952You can set the global debugging info directory's name, and view the
10953name @value{GDBN} is currently using.
10954
10955@table @code
10956
10957@kindex set debug-file-directory
10958@item set debug-file-directory @var{directory}
10959Set the directory which @value{GDBN} searches for separate debugging
10960information files to @var{directory}.
10961
10962@kindex show debug-file-directory
10963@item show debug-file-directory
10964Show the directory @value{GDBN} searches for separate debugging
10965information files.
10966
10967@end table
10968
10969@cindex @code{.gnu_debuglink} sections
10970@cindex debug links
10971A debug link is a special section of the executable file named
10972@code{.gnu_debuglink}. The section must contain:
10973
10974@itemize
10975@item
10976A filename, with any leading directory components removed, followed by
10977a zero byte,
10978@item
10979zero to three bytes of padding, as needed to reach the next four-byte
10980boundary within the section, and
10981@item
10982a four-byte CRC checksum, stored in the same endianness used for the
10983executable file itself. The checksum is computed on the debugging
10984information file's full contents by the function given below, passing
10985zero as the @var{crc} argument.
10986@end itemize
10987
10988Any executable file format can carry a debug link, as long as it can
10989contain a section named @code{.gnu_debuglink} with the contents
10990described above.
10991
10992The debugging information file itself should be an ordinary
10993executable, containing a full set of linker symbols, sections, and
10994debugging information. The sections of the debugging information file
10995should have the same names, addresses and sizes as the original file,
10996but they need not contain any data --- much like a @code{.bss} section
10997in an ordinary executable.
10998
10999As of December 2002, there is no standard GNU utility to produce
11000separated executable / debugging information file pairs. Ulrich
11001Drepper's @file{elfutils} package, starting with version 0.53,
11002contains a version of the @code{strip} command such that the command
11003@kbd{strip foo -f foo.debug} removes the debugging information from
11004the executable file @file{foo}, places it in the file
11005@file{foo.debug}, and leaves behind a debug link in @file{foo}.
11006
11007Since there are many different ways to compute CRC's (different
11008polynomials, reversals, byte ordering, etc.), the simplest way to
11009describe the CRC used in @code{.gnu_debuglink} sections is to give the
11010complete code for a function that computes it:
11011
4644b6e3 11012@kindex gnu_debuglink_crc32
5b5d99cf
JB
11013@smallexample
11014unsigned long
11015gnu_debuglink_crc32 (unsigned long crc,
11016 unsigned char *buf, size_t len)
11017@{
11018 static const unsigned long crc32_table[256] =
11019 @{
11020 0x00000000, 0x77073096, 0xee0e612c, 0x990951ba, 0x076dc419,
11021 0x706af48f, 0xe963a535, 0x9e6495a3, 0x0edb8832, 0x79dcb8a4,
11022 0xe0d5e91e, 0x97d2d988, 0x09b64c2b, 0x7eb17cbd, 0xe7b82d07,
11023 0x90bf1d91, 0x1db71064, 0x6ab020f2, 0xf3b97148, 0x84be41de,
11024 0x1adad47d, 0x6ddde4eb, 0xf4d4b551, 0x83d385c7, 0x136c9856,
11025 0x646ba8c0, 0xfd62f97a, 0x8a65c9ec, 0x14015c4f, 0x63066cd9,
11026 0xfa0f3d63, 0x8d080df5, 0x3b6e20c8, 0x4c69105e, 0xd56041e4,
11027 0xa2677172, 0x3c03e4d1, 0x4b04d447, 0xd20d85fd, 0xa50ab56b,
11028 0x35b5a8fa, 0x42b2986c, 0xdbbbc9d6, 0xacbcf940, 0x32d86ce3,
11029 0x45df5c75, 0xdcd60dcf, 0xabd13d59, 0x26d930ac, 0x51de003a,
11030 0xc8d75180, 0xbfd06116, 0x21b4f4b5, 0x56b3c423, 0xcfba9599,
11031 0xb8bda50f, 0x2802b89e, 0x5f058808, 0xc60cd9b2, 0xb10be924,
11032 0x2f6f7c87, 0x58684c11, 0xc1611dab, 0xb6662d3d, 0x76dc4190,
11033 0x01db7106, 0x98d220bc, 0xefd5102a, 0x71b18589, 0x06b6b51f,
11034 0x9fbfe4a5, 0xe8b8d433, 0x7807c9a2, 0x0f00f934, 0x9609a88e,
11035 0xe10e9818, 0x7f6a0dbb, 0x086d3d2d, 0x91646c97, 0xe6635c01,
11036 0x6b6b51f4, 0x1c6c6162, 0x856530d8, 0xf262004e, 0x6c0695ed,
11037 0x1b01a57b, 0x8208f4c1, 0xf50fc457, 0x65b0d9c6, 0x12b7e950,
11038 0x8bbeb8ea, 0xfcb9887c, 0x62dd1ddf, 0x15da2d49, 0x8cd37cf3,
11039 0xfbd44c65, 0x4db26158, 0x3ab551ce, 0xa3bc0074, 0xd4bb30e2,
11040 0x4adfa541, 0x3dd895d7, 0xa4d1c46d, 0xd3d6f4fb, 0x4369e96a,
11041 0x346ed9fc, 0xad678846, 0xda60b8d0, 0x44042d73, 0x33031de5,
11042 0xaa0a4c5f, 0xdd0d7cc9, 0x5005713c, 0x270241aa, 0xbe0b1010,
11043 0xc90c2086, 0x5768b525, 0x206f85b3, 0xb966d409, 0xce61e49f,
11044 0x5edef90e, 0x29d9c998, 0xb0d09822, 0xc7d7a8b4, 0x59b33d17,
11045 0x2eb40d81, 0xb7bd5c3b, 0xc0ba6cad, 0xedb88320, 0x9abfb3b6,
11046 0x03b6e20c, 0x74b1d29a, 0xead54739, 0x9dd277af, 0x04db2615,
11047 0x73dc1683, 0xe3630b12, 0x94643b84, 0x0d6d6a3e, 0x7a6a5aa8,
11048 0xe40ecf0b, 0x9309ff9d, 0x0a00ae27, 0x7d079eb1, 0xf00f9344,
11049 0x8708a3d2, 0x1e01f268, 0x6906c2fe, 0xf762575d, 0x806567cb,
11050 0x196c3671, 0x6e6b06e7, 0xfed41b76, 0x89d32be0, 0x10da7a5a,
11051 0x67dd4acc, 0xf9b9df6f, 0x8ebeeff9, 0x17b7be43, 0x60b08ed5,
11052 0xd6d6a3e8, 0xa1d1937e, 0x38d8c2c4, 0x4fdff252, 0xd1bb67f1,
11053 0xa6bc5767, 0x3fb506dd, 0x48b2364b, 0xd80d2bda, 0xaf0a1b4c,
11054 0x36034af6, 0x41047a60, 0xdf60efc3, 0xa867df55, 0x316e8eef,
11055 0x4669be79, 0xcb61b38c, 0xbc66831a, 0x256fd2a0, 0x5268e236,
11056 0xcc0c7795, 0xbb0b4703, 0x220216b9, 0x5505262f, 0xc5ba3bbe,
11057 0xb2bd0b28, 0x2bb45a92, 0x5cb36a04, 0xc2d7ffa7, 0xb5d0cf31,
11058 0x2cd99e8b, 0x5bdeae1d, 0x9b64c2b0, 0xec63f226, 0x756aa39c,
11059 0x026d930a, 0x9c0906a9, 0xeb0e363f, 0x72076785, 0x05005713,
11060 0x95bf4a82, 0xe2b87a14, 0x7bb12bae, 0x0cb61b38, 0x92d28e9b,
11061 0xe5d5be0d, 0x7cdcefb7, 0x0bdbdf21, 0x86d3d2d4, 0xf1d4e242,
11062 0x68ddb3f8, 0x1fda836e, 0x81be16cd, 0xf6b9265b, 0x6fb077e1,
11063 0x18b74777, 0x88085ae6, 0xff0f6a70, 0x66063bca, 0x11010b5c,
11064 0x8f659eff, 0xf862ae69, 0x616bffd3, 0x166ccf45, 0xa00ae278,
11065 0xd70dd2ee, 0x4e048354, 0x3903b3c2, 0xa7672661, 0xd06016f7,
11066 0x4969474d, 0x3e6e77db, 0xaed16a4a, 0xd9d65adc, 0x40df0b66,
11067 0x37d83bf0, 0xa9bcae53, 0xdebb9ec5, 0x47b2cf7f, 0x30b5ffe9,
11068 0xbdbdf21c, 0xcabac28a, 0x53b39330, 0x24b4a3a6, 0xbad03605,
11069 0xcdd70693, 0x54de5729, 0x23d967bf, 0xb3667a2e, 0xc4614ab8,
11070 0x5d681b02, 0x2a6f2b94, 0xb40bbe37, 0xc30c8ea1, 0x5a05df1b,
11071 0x2d02ef8d
11072 @};
11073 unsigned char *end;
11074
11075 crc = ~crc & 0xffffffff;
11076 for (end = buf + len; buf < end; ++buf)
11077 crc = crc32_table[(crc ^ *buf) & 0xff] ^ (crc >> 8);
e7a3abfc 11078 return ~crc & 0xffffffff;
5b5d99cf
JB
11079@}
11080@end smallexample
11081
11082
6d2ebf8b 11083@node Symbol Errors
c906108c
SS
11084@section Errors reading symbol files
11085
11086While reading a symbol file, @value{GDBN} occasionally encounters problems,
11087such as symbol types it does not recognize, or known bugs in compiler
11088output. By default, @value{GDBN} does not notify you of such problems, since
11089they are relatively common and primarily of interest to people
11090debugging compilers. If you are interested in seeing information
11091about ill-constructed symbol tables, you can either ask @value{GDBN} to print
11092only one message about each such type of problem, no matter how many
11093times the problem occurs; or you can ask @value{GDBN} to print more messages,
11094to see how many times the problems occur, with the @code{set
11095complaints} command (@pxref{Messages/Warnings, ,Optional warnings and
11096messages}).
11097
11098The messages currently printed, and their meanings, include:
11099
11100@table @code
11101@item inner block not inside outer block in @var{symbol}
11102
11103The symbol information shows where symbol scopes begin and end
11104(such as at the start of a function or a block of statements). This
11105error indicates that an inner scope block is not fully contained
11106in its outer scope blocks.
11107
11108@value{GDBN} circumvents the problem by treating the inner block as if it had
11109the same scope as the outer block. In the error message, @var{symbol}
11110may be shown as ``@code{(don't know)}'' if the outer block is not a
11111function.
11112
11113@item block at @var{address} out of order
11114
11115The symbol information for symbol scope blocks should occur in
11116order of increasing addresses. This error indicates that it does not
11117do so.
11118
11119@value{GDBN} does not circumvent this problem, and has trouble
11120locating symbols in the source file whose symbols it is reading. (You
11121can often determine what source file is affected by specifying
11122@code{set verbose on}. @xref{Messages/Warnings, ,Optional warnings and
11123messages}.)
11124
11125@item bad block start address patched
11126
11127The symbol information for a symbol scope block has a start address
11128smaller than the address of the preceding source line. This is known
11129to occur in the SunOS 4.1.1 (and earlier) C compiler.
11130
11131@value{GDBN} circumvents the problem by treating the symbol scope block as
11132starting on the previous source line.
11133
11134@item bad string table offset in symbol @var{n}
11135
11136@cindex foo
11137Symbol number @var{n} contains a pointer into the string table which is
11138larger than the size of the string table.
11139
11140@value{GDBN} circumvents the problem by considering the symbol to have the
11141name @code{foo}, which may cause other problems if many symbols end up
11142with this name.
11143
11144@item unknown symbol type @code{0x@var{nn}}
11145
7a292a7a
SS
11146The symbol information contains new data types that @value{GDBN} does
11147not yet know how to read. @code{0x@var{nn}} is the symbol type of the
d4f3574e 11148uncomprehended information, in hexadecimal.
c906108c 11149
7a292a7a
SS
11150@value{GDBN} circumvents the error by ignoring this symbol information.
11151This usually allows you to debug your program, though certain symbols
c906108c 11152are not accessible. If you encounter such a problem and feel like
7a292a7a
SS
11153debugging it, you can debug @code{@value{GDBP}} with itself, breakpoint
11154on @code{complain}, then go up to the function @code{read_dbx_symtab}
11155and examine @code{*bufp} to see the symbol.
c906108c
SS
11156
11157@item stub type has NULL name
c906108c 11158
7a292a7a 11159@value{GDBN} could not find the full definition for a struct or class.
c906108c 11160
7a292a7a 11161@item const/volatile indicator missing (ok if using g++ v1.x), got@dots{}
b37052ae 11162The symbol information for a C@t{++} member function is missing some
7a292a7a
SS
11163information that recent versions of the compiler should have output for
11164it.
c906108c
SS
11165
11166@item info mismatch between compiler and debugger
11167
11168@value{GDBN} could not parse a type specification output by the compiler.
7a292a7a 11169
c906108c
SS
11170@end table
11171
6d2ebf8b 11172@node Targets
c906108c 11173@chapter Specifying a Debugging Target
7a292a7a 11174
c906108c 11175@cindex debugging target
c906108c 11176A @dfn{target} is the execution environment occupied by your program.
53a5351d
JM
11177
11178Often, @value{GDBN} runs in the same host environment as your program;
11179in that case, the debugging target is specified as a side effect when
11180you use the @code{file} or @code{core} commands. When you need more
c906108c
SS
11181flexibility---for example, running @value{GDBN} on a physically separate
11182host, or controlling a standalone system over a serial port or a
53a5351d
JM
11183realtime system over a TCP/IP connection---you can use the @code{target}
11184command to specify one of the target types configured for @value{GDBN}
11185(@pxref{Target Commands, ,Commands for managing targets}).
c906108c 11186
a8f24a35
EZ
11187@cindex target architecture
11188It is possible to build @value{GDBN} for several different @dfn{target
11189architectures}. When @value{GDBN} is built like that, you can choose
11190one of the available architectures with the @kbd{set architecture}
11191command.
11192
11193@table @code
11194@kindex set architecture
11195@kindex show architecture
11196@item set architecture @var{arch}
11197This command sets the current target architecture to @var{arch}. The
11198value of @var{arch} can be @code{"auto"}, in addition to one of the
11199supported architectures.
11200
11201@item show architecture
11202Show the current target architecture.
9c16f35a
EZ
11203
11204@item set processor
11205@itemx processor
11206@kindex set processor
11207@kindex show processor
11208These are alias commands for, respectively, @code{set architecture}
11209and @code{show architecture}.
a8f24a35
EZ
11210@end table
11211
c906108c
SS
11212@menu
11213* Active Targets:: Active targets
11214* Target Commands:: Commands for managing targets
c906108c
SS
11215* Byte Order:: Choosing target byte order
11216* Remote:: Remote debugging
96baa820 11217* KOD:: Kernel Object Display
c906108c
SS
11218
11219@end menu
11220
6d2ebf8b 11221@node Active Targets
c906108c 11222@section Active targets
7a292a7a 11223
c906108c
SS
11224@cindex stacking targets
11225@cindex active targets
11226@cindex multiple targets
11227
c906108c 11228There are three classes of targets: processes, core files, and
7a292a7a
SS
11229executable files. @value{GDBN} can work concurrently on up to three
11230active targets, one in each class. This allows you to (for example)
11231start a process and inspect its activity without abandoning your work on
11232a core file.
c906108c
SS
11233
11234For example, if you execute @samp{gdb a.out}, then the executable file
11235@code{a.out} is the only active target. If you designate a core file as
11236well---presumably from a prior run that crashed and coredumped---then
11237@value{GDBN} has two active targets and uses them in tandem, looking
11238first in the corefile target, then in the executable file, to satisfy
11239requests for memory addresses. (Typically, these two classes of target
11240are complementary, since core files contain only a program's
11241read-write memory---variables and so on---plus machine status, while
11242executable files contain only the program text and initialized data.)
c906108c
SS
11243
11244When you type @code{run}, your executable file becomes an active process
7a292a7a
SS
11245target as well. When a process target is active, all @value{GDBN}
11246commands requesting memory addresses refer to that target; addresses in
11247an active core file or executable file target are obscured while the
11248process target is active.
c906108c 11249
7a292a7a
SS
11250Use the @code{core-file} and @code{exec-file} commands to select a new
11251core file or executable target (@pxref{Files, ,Commands to specify
c906108c 11252files}). To specify as a target a process that is already running, use
7a292a7a
SS
11253the @code{attach} command (@pxref{Attach, ,Debugging an already-running
11254process}).
c906108c 11255
6d2ebf8b 11256@node Target Commands
c906108c
SS
11257@section Commands for managing targets
11258
11259@table @code
11260@item target @var{type} @var{parameters}
7a292a7a
SS
11261Connects the @value{GDBN} host environment to a target machine or
11262process. A target is typically a protocol for talking to debugging
11263facilities. You use the argument @var{type} to specify the type or
11264protocol of the target machine.
c906108c
SS
11265
11266Further @var{parameters} are interpreted by the target protocol, but
11267typically include things like device names or host names to connect
11268with, process numbers, and baud rates.
c906108c
SS
11269
11270The @code{target} command does not repeat if you press @key{RET} again
11271after executing the command.
11272
11273@kindex help target
11274@item help target
11275Displays the names of all targets available. To display targets
11276currently selected, use either @code{info target} or @code{info files}
11277(@pxref{Files, ,Commands to specify files}).
11278
11279@item help target @var{name}
11280Describe a particular target, including any parameters necessary to
11281select it.
11282
11283@kindex set gnutarget
11284@item set gnutarget @var{args}
5d161b24 11285@value{GDBN} uses its own library BFD to read your files. @value{GDBN}
c906108c 11286knows whether it is reading an @dfn{executable},
5d161b24
DB
11287a @dfn{core}, or a @dfn{.o} file; however, you can specify the file format
11288with the @code{set gnutarget} command. Unlike most @code{target} commands,
c906108c
SS
11289with @code{gnutarget} the @code{target} refers to a program, not a machine.
11290
d4f3574e 11291@quotation
c906108c
SS
11292@emph{Warning:} To specify a file format with @code{set gnutarget},
11293you must know the actual BFD name.
d4f3574e 11294@end quotation
c906108c 11295
d4f3574e
SS
11296@noindent
11297@xref{Files, , Commands to specify files}.
c906108c 11298
5d161b24 11299@kindex show gnutarget
c906108c
SS
11300@item show gnutarget
11301Use the @code{show gnutarget} command to display what file format
11302@code{gnutarget} is set to read. If you have not set @code{gnutarget},
11303@value{GDBN} will determine the file format for each file automatically,
11304and @code{show gnutarget} displays @samp{The current BDF target is "auto"}.
11305@end table
11306
4644b6e3 11307@cindex common targets
c906108c
SS
11308Here are some common targets (available, or not, depending on the GDB
11309configuration):
c906108c
SS
11310
11311@table @code
4644b6e3 11312@kindex target
c906108c 11313@item target exec @var{program}
4644b6e3 11314@cindex executable file target
c906108c
SS
11315An executable file. @samp{target exec @var{program}} is the same as
11316@samp{exec-file @var{program}}.
11317
c906108c 11318@item target core @var{filename}
4644b6e3 11319@cindex core dump file target
c906108c
SS
11320A core dump file. @samp{target core @var{filename}} is the same as
11321@samp{core-file @var{filename}}.
c906108c 11322
c906108c 11323@item target remote @var{dev}
4644b6e3 11324@cindex remote target
c906108c
SS
11325Remote serial target in GDB-specific protocol. The argument @var{dev}
11326specifies what serial device to use for the connection (e.g.
11327@file{/dev/ttya}). @xref{Remote, ,Remote debugging}. @code{target remote}
d4f3574e 11328supports the @code{load} command. This is only useful if you have
c906108c
SS
11329some other way of getting the stub to the target system, and you can put
11330it somewhere in memory where it won't get clobbered by the download.
11331
c906108c 11332@item target sim
4644b6e3 11333@cindex built-in simulator target
2df3850c 11334Builtin CPU simulator. @value{GDBN} includes simulators for most architectures.
104c1213 11335In general,
474c8240 11336@smallexample
104c1213
JM
11337 target sim
11338 load
11339 run
474c8240 11340@end smallexample
d4f3574e 11341@noindent
104c1213 11342works; however, you cannot assume that a specific memory map, device
d4f3574e 11343drivers, or even basic I/O is available, although some simulators do
104c1213
JM
11344provide these. For info about any processor-specific simulator details,
11345see the appropriate section in @ref{Embedded Processors, ,Embedded
11346Processors}.
11347
c906108c
SS
11348@end table
11349
104c1213 11350Some configurations may include these targets as well:
c906108c
SS
11351
11352@table @code
11353
c906108c 11354@item target nrom @var{dev}
4644b6e3 11355@cindex NetROM ROM emulator target
c906108c
SS
11356NetROM ROM emulator. This target only supports downloading.
11357
c906108c
SS
11358@end table
11359
5d161b24 11360Different targets are available on different configurations of @value{GDBN};
c906108c 11361your configuration may have more or fewer targets.
c906108c
SS
11362
11363Many remote targets require you to download the executable's code
a8f24a35
EZ
11364once you've successfully established a connection. You may wish to
11365control the size of the data chunks used by @value{GDBN} to download
11366program parts to the remote target.
11367
11368@table @code
11369@kindex set download-write-size
11370@item set download-write-size @var{size}
11371Set the write size used when downloading a program. Only used when
11372downloading a program onto a remote target. Specify zero or a
11373negative value to disable blocked writes. The actual size of each
11374transfer is also limited by the size of the target packet and the
11375memory cache.
11376
11377@kindex show download-write-size
11378@item show download-write-size
11379Show the current value of the write size.
11380@end table
c906108c
SS
11381
11382@table @code
11383
11384@kindex load @var{filename}
11385@item load @var{filename}
c906108c
SS
11386Depending on what remote debugging facilities are configured into
11387@value{GDBN}, the @code{load} command may be available. Where it exists, it
11388is meant to make @var{filename} (an executable) available for debugging
11389on the remote system---by downloading, or dynamic linking, for example.
11390@code{load} also records the @var{filename} symbol table in @value{GDBN}, like
11391the @code{add-symbol-file} command.
11392
11393If your @value{GDBN} does not have a @code{load} command, attempting to
11394execute it gets the error message ``@code{You can't do that when your
11395target is @dots{}}''
c906108c
SS
11396
11397The file is loaded at whatever address is specified in the executable.
11398For some object file formats, you can specify the load address when you
11399link the program; for other formats, like a.out, the object file format
11400specifies a fixed address.
11401@c FIXME! This would be a good place for an xref to the GNU linker doc.
11402
c906108c
SS
11403@code{load} does not repeat if you press @key{RET} again after using it.
11404@end table
11405
6d2ebf8b 11406@node Byte Order
c906108c 11407@section Choosing target byte order
7a292a7a 11408
c906108c
SS
11409@cindex choosing target byte order
11410@cindex target byte order
c906108c 11411
172c2a43 11412Some types of processors, such as the MIPS, PowerPC, and Renesas SH,
c906108c
SS
11413offer the ability to run either big-endian or little-endian byte
11414orders. Usually the executable or symbol will include a bit to
11415designate the endian-ness, and you will not need to worry about
11416which to use. However, you may still find it useful to adjust
d4f3574e 11417@value{GDBN}'s idea of processor endian-ness manually.
c906108c
SS
11418
11419@table @code
4644b6e3 11420@kindex set endian
c906108c
SS
11421@item set endian big
11422Instruct @value{GDBN} to assume the target is big-endian.
11423
c906108c
SS
11424@item set endian little
11425Instruct @value{GDBN} to assume the target is little-endian.
11426
c906108c
SS
11427@item set endian auto
11428Instruct @value{GDBN} to use the byte order associated with the
11429executable.
11430
11431@item show endian
11432Display @value{GDBN}'s current idea of the target byte order.
11433
11434@end table
11435
11436Note that these commands merely adjust interpretation of symbolic
11437data on the host, and that they have absolutely no effect on the
11438target system.
11439
6d2ebf8b 11440@node Remote
c906108c
SS
11441@section Remote debugging
11442@cindex remote debugging
11443
11444If you are trying to debug a program running on a machine that cannot run
5d161b24
DB
11445@value{GDBN} in the usual way, it is often useful to use remote debugging.
11446For example, you might use remote debugging on an operating system kernel,
c906108c
SS
11447or on a small system which does not have a general purpose operating system
11448powerful enough to run a full-featured debugger.
11449
11450Some configurations of @value{GDBN} have special serial or TCP/IP interfaces
11451to make this work with particular debugging targets. In addition,
5d161b24 11452@value{GDBN} comes with a generic serial protocol (specific to @value{GDBN},
c906108c
SS
11453but not specific to any particular target system) which you can use if you
11454write the remote stubs---the code that runs on the remote system to
11455communicate with @value{GDBN}.
11456
11457Other remote targets may be available in your
11458configuration of @value{GDBN}; use @code{help target} to list them.
c906108c 11459
6f05cf9f
AC
11460@node KOD
11461@section Kernel Object Display
6f05cf9f 11462@cindex kernel object display
6f05cf9f
AC
11463@cindex KOD
11464
11465Some targets support kernel object display. Using this facility,
11466@value{GDBN} communicates specially with the underlying operating system
11467and can display information about operating system-level objects such as
11468mutexes and other synchronization objects. Exactly which objects can be
11469displayed is determined on a per-OS basis.
11470
3bbe9696 11471@kindex set os
6f05cf9f
AC
11472Use the @code{set os} command to set the operating system. This tells
11473@value{GDBN} which kernel object display module to initialize:
11474
474c8240 11475@smallexample
6f05cf9f 11476(@value{GDBP}) set os cisco
474c8240 11477@end smallexample
6f05cf9f 11478
3bbe9696
EZ
11479@kindex show os
11480The associated command @code{show os} displays the operating system
11481set with the @code{set os} command; if no operating system has been
11482set, @code{show os} will display an empty string @samp{""}.
11483
6f05cf9f
AC
11484If @code{set os} succeeds, @value{GDBN} will display some information
11485about the operating system, and will create a new @code{info} command
11486which can be used to query the target. The @code{info} command is named
11487after the operating system:
c906108c 11488
3bbe9696 11489@kindex info cisco
474c8240 11490@smallexample
6f05cf9f
AC
11491(@value{GDBP}) info cisco
11492List of Cisco Kernel Objects
11493Object Description
11494any Any and all objects
474c8240 11495@end smallexample
6f05cf9f
AC
11496
11497Further subcommands can be used to query about particular objects known
11498by the kernel.
11499
3bbe9696
EZ
11500There is currently no way to determine whether a given operating
11501system is supported other than to try setting it with @kbd{set os
11502@var{name}}, where @var{name} is the name of the operating system you
11503want to try.
6f05cf9f
AC
11504
11505
11506@node Remote Debugging
11507@chapter Debugging remote programs
11508
6b2f586d 11509@menu
07f31aa6 11510* Connecting:: Connecting to a remote target
6b2f586d
AC
11511* Server:: Using the gdbserver program
11512* NetWare:: Using the gdbserve.nlm program
501eef12 11513* Remote configuration:: Remote configuration
6b2f586d 11514* remote stub:: Implementing a remote stub
6b2f586d
AC
11515@end menu
11516
07f31aa6
DJ
11517@node Connecting
11518@section Connecting to a remote target
11519
11520On the @value{GDBN} host machine, you will need an unstripped copy of
11521your program, since @value{GDBN} needs symobl and debugging information.
11522Start up @value{GDBN} as usual, using the name of the local copy of your
11523program as the first argument.
11524
11525@cindex serial line, @code{target remote}
11526If you're using a serial line, you may want to give @value{GDBN} the
11527@w{@samp{--baud}} option, or use the @code{set remotebaud} command
9c16f35a
EZ
11528(@pxref{Remote configuration, set remotebaud}) before the
11529@code{target} command.
07f31aa6
DJ
11530
11531After that, use @code{target remote} to establish communications with
11532the target machine. Its argument specifies how to communicate---either
11533via a devicename attached to a direct serial line, or a TCP or UDP port
11534(possibly to a terminal server which in turn has a serial line to the
11535target). For example, to use a serial line connected to the device
11536named @file{/dev/ttyb}:
11537
11538@smallexample
11539target remote /dev/ttyb
11540@end smallexample
11541
11542@cindex TCP port, @code{target remote}
11543To use a TCP connection, use an argument of the form
11544@code{@var{host}:@var{port}} or @code{tcp:@var{host}:@var{port}}.
11545For example, to connect to port 2828 on a
11546terminal server named @code{manyfarms}:
11547
11548@smallexample
11549target remote manyfarms:2828
11550@end smallexample
11551
11552If your remote target is actually running on the same machine as
11553your debugger session (e.g.@: a simulator of your target running on
11554the same host), you can omit the hostname. For example, to connect
11555to port 1234 on your local machine:
11556
11557@smallexample
11558target remote :1234
11559@end smallexample
11560@noindent
11561
11562Note that the colon is still required here.
11563
11564@cindex UDP port, @code{target remote}
11565To use a UDP connection, use an argument of the form
11566@code{udp:@var{host}:@var{port}}. For example, to connect to UDP port 2828
11567on a terminal server named @code{manyfarms}:
11568
11569@smallexample
11570target remote udp:manyfarms:2828
11571@end smallexample
11572
11573When using a UDP connection for remote debugging, you should keep in mind
11574that the `U' stands for ``Unreliable''. UDP can silently drop packets on
11575busy or unreliable networks, which will cause havoc with your debugging
11576session.
11577
11578Now you can use all the usual commands to examine and change data and to
11579step and continue the remote program.
11580
11581@cindex interrupting remote programs
11582@cindex remote programs, interrupting
11583Whenever @value{GDBN} is waiting for the remote program, if you type the
11584interrupt character (often @key{C-C}), @value{GDBN} attempts to stop the
11585program. This may or may not succeed, depending in part on the hardware
11586and the serial drivers the remote system uses. If you type the
11587interrupt character once again, @value{GDBN} displays this prompt:
11588
11589@smallexample
11590Interrupted while waiting for the program.
11591Give up (and stop debugging it)? (y or n)
11592@end smallexample
11593
11594If you type @kbd{y}, @value{GDBN} abandons the remote debugging session.
11595(If you decide you want to try again later, you can use @samp{target
11596remote} again to connect once more.) If you type @kbd{n}, @value{GDBN}
11597goes back to waiting.
11598
11599@table @code
11600@kindex detach (remote)
11601@item detach
11602When you have finished debugging the remote program, you can use the
11603@code{detach} command to release it from @value{GDBN} control.
11604Detaching from the target normally resumes its execution, but the results
11605will depend on your particular remote stub. After the @code{detach}
11606command, @value{GDBN} is free to connect to another target.
11607
11608@kindex disconnect
11609@item disconnect
11610The @code{disconnect} command behaves like @code{detach}, except that
11611the target is generally not resumed. It will wait for @value{GDBN}
11612(this instance or another one) to connect and continue debugging. After
11613the @code{disconnect} command, @value{GDBN} is again free to connect to
11614another target.
09d4efe1
EZ
11615
11616@cindex send command to remote monitor
11617@kindex monitor
11618@item monitor @var{cmd}
11619This command allows you to send commands directly to the remote
11620monitor.
07f31aa6
DJ
11621@end table
11622
6f05cf9f
AC
11623@node Server
11624@section Using the @code{gdbserver} program
11625
11626@kindex gdbserver
11627@cindex remote connection without stubs
11628@code{gdbserver} is a control program for Unix-like systems, which
11629allows you to connect your program with a remote @value{GDBN} via
11630@code{target remote}---but without linking in the usual debugging stub.
11631
11632@code{gdbserver} is not a complete replacement for the debugging stubs,
11633because it requires essentially the same operating-system facilities
11634that @value{GDBN} itself does. In fact, a system that can run
11635@code{gdbserver} to connect to a remote @value{GDBN} could also run
11636@value{GDBN} locally! @code{gdbserver} is sometimes useful nevertheless,
11637because it is a much smaller program than @value{GDBN} itself. It is
11638also easier to port than all of @value{GDBN}, so you may be able to get
11639started more quickly on a new system by using @code{gdbserver}.
11640Finally, if you develop code for real-time systems, you may find that
11641the tradeoffs involved in real-time operation make it more convenient to
11642do as much development work as possible on another system, for example
11643by cross-compiling. You can use @code{gdbserver} to make a similar
11644choice for debugging.
11645
11646@value{GDBN} and @code{gdbserver} communicate via either a serial line
11647or a TCP connection, using the standard @value{GDBN} remote serial
11648protocol.
11649
11650@table @emph
11651@item On the target machine,
11652you need to have a copy of the program you want to debug.
11653@code{gdbserver} does not need your program's symbol table, so you can
11654strip the program if necessary to save space. @value{GDBN} on the host
11655system does all the symbol handling.
11656
11657To use the server, you must tell it how to communicate with @value{GDBN};
56460a61 11658the name of your program; and the arguments for your program. The usual
6f05cf9f
AC
11659syntax is:
11660
11661@smallexample
11662target> gdbserver @var{comm} @var{program} [ @var{args} @dots{} ]
11663@end smallexample
11664
11665@var{comm} is either a device name (to use a serial line) or a TCP
11666hostname and portnumber. For example, to debug Emacs with the argument
11667@samp{foo.txt} and communicate with @value{GDBN} over the serial port
11668@file{/dev/com1}:
11669
11670@smallexample
11671target> gdbserver /dev/com1 emacs foo.txt
11672@end smallexample
11673
11674@code{gdbserver} waits passively for the host @value{GDBN} to communicate
11675with it.
11676
11677To use a TCP connection instead of a serial line:
11678
11679@smallexample
11680target> gdbserver host:2345 emacs foo.txt
11681@end smallexample
11682
11683The only difference from the previous example is the first argument,
11684specifying that you are communicating with the host @value{GDBN} via
11685TCP. The @samp{host:2345} argument means that @code{gdbserver} is to
11686expect a TCP connection from machine @samp{host} to local TCP port 2345.
11687(Currently, the @samp{host} part is ignored.) You can choose any number
11688you want for the port number as long as it does not conflict with any
11689TCP ports already in use on the target system (for example, @code{23} is
11690reserved for @code{telnet}).@footnote{If you choose a port number that
11691conflicts with another service, @code{gdbserver} prints an error message
11692and exits.} You must use the same port number with the host @value{GDBN}
11693@code{target remote} command.
11694
56460a61
DJ
11695On some targets, @code{gdbserver} can also attach to running programs.
11696This is accomplished via the @code{--attach} argument. The syntax is:
11697
11698@smallexample
11699target> gdbserver @var{comm} --attach @var{pid}
11700@end smallexample
11701
11702@var{pid} is the process ID of a currently running process. It isn't necessary
11703to point @code{gdbserver} at a binary for the running process.
11704
b1fe9455
DJ
11705@pindex pidof
11706@cindex attach to a program by name
11707You can debug processes by name instead of process ID if your target has the
11708@code{pidof} utility:
11709
11710@smallexample
11711target> gdbserver @var{comm} --attach `pidof @var{PROGRAM}`
11712@end smallexample
11713
11714In case more than one copy of @var{PROGRAM} is running, or @var{PROGRAM}
11715has multiple threads, most versions of @code{pidof} support the
11716@code{-s} option to only return the first process ID.
11717
07f31aa6
DJ
11718@item On the host machine,
11719connect to your target (@pxref{Connecting,,Connecting to a remote target}).
6f05cf9f
AC
11720For TCP connections, you must start up @code{gdbserver} prior to using
11721the @code{target remote} command. Otherwise you may get an error whose
11722text depends on the host system, but which usually looks something like
07f31aa6
DJ
11723@samp{Connection refused}. You don't need to use the @code{load}
11724command in @value{GDBN} when using gdbserver, since the program is
11725already on the target.
11726
6f05cf9f
AC
11727@end table
11728
11729@node NetWare
11730@section Using the @code{gdbserve.nlm} program
11731
11732@kindex gdbserve.nlm
11733@code{gdbserve.nlm} is a control program for NetWare systems, which
11734allows you to connect your program with a remote @value{GDBN} via
11735@code{target remote}.
11736
11737@value{GDBN} and @code{gdbserve.nlm} communicate via a serial line,
11738using the standard @value{GDBN} remote serial protocol.
11739
11740@table @emph
11741@item On the target machine,
11742you need to have a copy of the program you want to debug.
11743@code{gdbserve.nlm} does not need your program's symbol table, so you
11744can strip the program if necessary to save space. @value{GDBN} on the
11745host system does all the symbol handling.
11746
11747To use the server, you must tell it how to communicate with
11748@value{GDBN}; the name of your program; and the arguments for your
11749program. The syntax is:
11750
11751@smallexample
11752load gdbserve [ BOARD=@var{board} ] [ PORT=@var{port} ]
11753 [ BAUD=@var{baud} ] @var{program} [ @var{args} @dots{} ]
11754@end smallexample
11755
11756@var{board} and @var{port} specify the serial line; @var{baud} specifies
11757the baud rate used by the connection. @var{port} and @var{node} default
11758to 0, @var{baud} defaults to 9600@dmn{bps}.
11759
11760For example, to debug Emacs with the argument @samp{foo.txt}and
11761communicate with @value{GDBN} over serial port number 2 or board 1
11762using a 19200@dmn{bps} connection:
11763
11764@smallexample
11765load gdbserve BOARD=1 PORT=2 BAUD=19200 emacs foo.txt
11766@end smallexample
11767
07f31aa6
DJ
11768@item
11769On the @value{GDBN} host machine, connect to your target (@pxref{Connecting,,
11770Connecting to a remote target}).
6f05cf9f 11771
6f05cf9f
AC
11772@end table
11773
501eef12
AC
11774@node Remote configuration
11775@section Remote configuration
11776
9c16f35a
EZ
11777@kindex set remote
11778@kindex show remote
11779This section documents the configuration options available when
11780debugging remote programs. For the options related to the File I/O
11781extensions of the remote protocol, see @ref{The system call,
11782system-call-allowed}.
501eef12
AC
11783
11784@table @code
9c16f35a
EZ
11785@item set remoteaddresssize @var{bits}
11786@cindex adress size for remote targets
11787@cindex bits in remote address
11788Set the maximum size of address in a memory packet to the specified
11789number of bits. @value{GDBN} will mask off the address bits above
11790that number, when it passes addresses to the remote target. The
11791default value is the number of bits in the target's address.
11792
11793@item show remoteaddresssize
11794Show the current value of remote address size in bits.
11795
11796@item set remotebaud @var{n}
11797@cindex baud rate for remote targets
11798Set the baud rate for the remote serial I/O to @var{n} baud. The
11799value is used to set the speed of the serial port used for debugging
11800remote targets.
11801
11802@item show remotebaud
11803Show the current speed of the remote connection.
11804
11805@item set remotebreak
11806@cindex interrupt remote programs
11807@cindex BREAK signal instead of Ctrl-C
11808If set to on, @value{GDBN} sends a @code{BREAK} signal to the remote
11809when you press the @key{Ctrl-C} key to interrupt the program running
11810on the remote. If set to off, @value{GDBN} sends the @samp{Strl-C}
11811character instead. The default is off, since most remote systems
11812expect to see @samp{Ctrl-C} as the interrupt signal.
11813
11814@item show remotebreak
11815Show whether @value{GDBN} sends @code{BREAK} or @samp{Ctrl-C} to
11816interrupt the remote program.
11817
11818@item set remotedebug
11819@cindex debug remote protocol
11820@cindex remote protocol debugging
11821@cindex display remote packets
11822Control the debugging of the remote protocol. When enabled, each
11823packet sent to or received from the remote target is displayed. The
11824defaults is off.
11825
11826@item show remotedebug
11827Show the current setting of the remote protocol debugging.
11828
11829@item set remotedevice @var{device}
11830@cindex serial port name
11831Set the name of the serial port through which to communicate to the
11832remote target to @var{device}. This is the device used by
11833@value{GDBN} to open the serial communications line to the remote
11834target. There's no default, so you must set a valid port name for the
11835remote serial communications to work. (Some varieties of the
11836@code{target} command accept the port name as part of their
11837arguments.)
11838
11839@item show remotedevice
11840Show the current name of the serial port.
11841
11842@item set remotelogbase @var{base}
11843Set the base (a.k.a.@: radix) of logging serial protocol
11844communications to @var{base}. Supported values of @var{base} are:
11845@code{ascii}, @code{octal}, and @code{hex}. The default is
11846@code{ascii}.
11847
11848@item show remotelogbase
11849Show the current setting of the radix for logging remote serial
11850protocol.
11851
11852@item set remotelogfile @var{file}
11853@cindex record serial communications on file
11854Record remote serial communications on the named @var{file}. The
11855default is not to record at all.
11856
11857@item show remotelogfile.
11858Show the current setting of the file name on which to record the
11859serial communications.
11860
11861@item set remotetimeout @var{num}
11862@cindex timeout for serial communications
11863@cindex remote timeout
11864Set the timeout limit to wait for the remote target to respond to
11865@var{num} seconds. The default is 2 seconds.
11866
11867@item show remotetimeout
11868Show the current number of seconds to wait for the remote target
11869responses.
11870
11871@cindex limit hardware breakpoints and watchpoints
11872@cindex remote target, limit break- and watchpoints
501eef12
AC
11873@anchor{set remote hardware-watchpoint-limit}
11874@anchor{set remote hardware-breakpoint-limit}
11875@item set remote hardware-watchpoint-limit @var{limit}
11876@itemx set remote hardware-breakpoint-limit @var{limit}
11877Restrict @value{GDBN} to using @var{limit} remote hardware breakpoint or
11878watchpoints. A limit of -1, the default, is treated as unlimited.
9c16f35a
EZ
11879
11880@item set remote fetch-register-packet
11881@itemx set remote set-register-packet
11882@itemx set remote P-packet
11883@itemx set remote p-packet
11884@cindex P-packet
11885@cindex fetch registers from remote targets
11886@cindex set registers in remote targets
11887Determine whether @value{GDBN} can set and fetch registers from the
11888remote target using the @samp{P} packets. The default depends on the
11889remote stub's support of the @samp{P} packets (@value{GDBN} queries
11890the stub when this packet is first required).
11891
11892@item show remote fetch-register-packet
11893@itemx show remote set-register-packet
11894@itemx show remote P-packet
11895@itemx show remote p-packet
11896Show the current setting of using the @samp{P} packets for setting and
11897fetching registers from the remote target.
11898
11899@cindex binary downloads
11900@cindex X-packet
11901@item set remote binary-download-packet
11902@itemx set remote X-packet
11903Determine whether @value{GDBN} sends downloads in binary mode using
11904the @samp{X} packets. The default is on.
11905
11906@item show remote binary-download-packet
11907@itemx show remote X-packet
11908Show the current setting of using the @samp{X} packets for binary
11909downloads.
11910
11911@item set remote read-aux-vector-packet
11912@cindex auxiliary vector of remote target
11913@cindex @code{auxv}, and remote targets
11914Set the use of the remote protocol's @samp{qPart:auxv:read} (target
11915auxiliary vector read) request. This request is used to fetch the
11916remote target's @dfn{auxiliary vector}, see @ref{Auxiliary Vector}.
11917The default setting depends on the remote stub's support of this
11918request (@value{GDBN} queries the stub when this request is first
11919required). @xref{General Query Packets, qPart}, for more information
11920about this request.
11921
11922@item show remote read-aux-vector-packet
11923Show the current setting of use of the @samp{qPart:auxv:read} request.
11924
11925@item set remote symbol-lookup-packet
11926@cindex remote symbol lookup request
11927Set the use of the remote protocol's @samp{qSymbol} (target symbol
11928lookup) request. This request is used to communicate symbol
11929information to the remote target, e.g., whenever a new shared library
11930is loaded by the remote (@pxref{Files, shared libraries}). The
11931default setting depends on the remote stub's support of this request
11932(@value{GDBN} queries the stub when this request is first required).
11933@xref{General Query Packets, qSymbol}, for more information about this
11934request.
11935
11936@item show remote symbol-lookup-packet
11937Show the current setting of use of the @samp{qSymbol} request.
11938
11939@item set remote verbose-resume-packet
11940@cindex resume remote target
11941@cindex signal thread, and remote targets
11942@cindex single-step thread, and remote targets
11943@cindex thread-specific operations on remote targets
11944Set the use of the remote protocol's @samp{vCont} (descriptive resume)
11945request. This request is used to resume specific threads in the
11946remote target, and to single-step or signal them. The default setting
11947depends on the remote stub's support of this request (@value{GDBN}
11948queries the stub when this request is first required). This setting
11949affects debugging of multithreaded programs: if @samp{vCont} cannot be
11950used, @value{GDBN} might be unable to single-step a specific thread,
11951especially under @code{set scheduler-locking off}; it is also
11952impossible to pause a specific thread. @xref{Packets, vCont}, for
11953more details.
11954
11955@item show remote verbose-resume-packet
11956Show the current setting of use of the @samp{vCont} request
11957
11958@item set remote software-breakpoint-packet
11959@itemx set remote hardware-breakpoint-packet
11960@itemx set remote write-watchpoint-packet
11961@itemx set remote read-watchpoint-packet
11962@itemx set remote access-watchpoint-packet
11963@itemx set remote Z-packet
11964@cindex Z-packet
11965@cindex remote hardware breakpoints and watchpoints
11966These commands enable or disable the use of @samp{Z} packets for
11967setting breakpoints and watchpoints in the remote target. The default
11968depends on the remote stub's support of the @samp{Z} packets
11969(@value{GDBN} queries the stub when each packet is first required).
11970The command @code{set remote Z-packet}, kept for back-compatibility,
11971turns on or off all the features that require the use of @samp{Z}
11972packets.
11973
11974@item show remote software-breakpoint-packet
11975@itemx show remote hardware-breakpoint-packet
11976@itemx show remote write-watchpoint-packet
11977@itemx show remote read-watchpoint-packet
11978@itemx show remote access-watchpoint-packet
11979@itemx show remote Z-packet
11980Show the current setting of @samp{Z} packets usage.
501eef12
AC
11981@end table
11982
6f05cf9f
AC
11983@node remote stub
11984@section Implementing a remote stub
7a292a7a 11985
8e04817f
AC
11986@cindex debugging stub, example
11987@cindex remote stub, example
11988@cindex stub example, remote debugging
11989The stub files provided with @value{GDBN} implement the target side of the
11990communication protocol, and the @value{GDBN} side is implemented in the
11991@value{GDBN} source file @file{remote.c}. Normally, you can simply allow
11992these subroutines to communicate, and ignore the details. (If you're
11993implementing your own stub file, you can still ignore the details: start
11994with one of the existing stub files. @file{sparc-stub.c} is the best
11995organized, and therefore the easiest to read.)
11996
104c1213
JM
11997@cindex remote serial debugging, overview
11998To debug a program running on another machine (the debugging
11999@dfn{target} machine), you must first arrange for all the usual
12000prerequisites for the program to run by itself. For example, for a C
12001program, you need:
c906108c 12002
104c1213
JM
12003@enumerate
12004@item
12005A startup routine to set up the C runtime environment; these usually
12006have a name like @file{crt0}. The startup routine may be supplied by
12007your hardware supplier, or you may have to write your own.
96baa820 12008
5d161b24 12009@item
d4f3574e 12010A C subroutine library to support your program's
104c1213 12011subroutine calls, notably managing input and output.
96baa820 12012
104c1213
JM
12013@item
12014A way of getting your program to the other machine---for example, a
12015download program. These are often supplied by the hardware
12016manufacturer, but you may have to write your own from hardware
12017documentation.
12018@end enumerate
96baa820 12019
104c1213
JM
12020The next step is to arrange for your program to use a serial port to
12021communicate with the machine where @value{GDBN} is running (the @dfn{host}
12022machine). In general terms, the scheme looks like this:
96baa820 12023
104c1213
JM
12024@table @emph
12025@item On the host,
12026@value{GDBN} already understands how to use this protocol; when everything
12027else is set up, you can simply use the @samp{target remote} command
12028(@pxref{Targets,,Specifying a Debugging Target}).
12029
12030@item On the target,
12031you must link with your program a few special-purpose subroutines that
12032implement the @value{GDBN} remote serial protocol. The file containing these
12033subroutines is called a @dfn{debugging stub}.
12034
12035On certain remote targets, you can use an auxiliary program
12036@code{gdbserver} instead of linking a stub into your program.
12037@xref{Server,,Using the @code{gdbserver} program}, for details.
12038@end table
96baa820 12039
104c1213
JM
12040The debugging stub is specific to the architecture of the remote
12041machine; for example, use @file{sparc-stub.c} to debug programs on
12042@sc{sparc} boards.
96baa820 12043
104c1213
JM
12044@cindex remote serial stub list
12045These working remote stubs are distributed with @value{GDBN}:
96baa820 12046
104c1213
JM
12047@table @code
12048
12049@item i386-stub.c
41afff9a 12050@cindex @file{i386-stub.c}
104c1213
JM
12051@cindex Intel
12052@cindex i386
12053For Intel 386 and compatible architectures.
12054
12055@item m68k-stub.c
41afff9a 12056@cindex @file{m68k-stub.c}
104c1213
JM
12057@cindex Motorola 680x0
12058@cindex m680x0
12059For Motorola 680x0 architectures.
12060
12061@item sh-stub.c
41afff9a 12062@cindex @file{sh-stub.c}
172c2a43 12063@cindex Renesas
104c1213 12064@cindex SH
172c2a43 12065For Renesas SH architectures.
104c1213
JM
12066
12067@item sparc-stub.c
41afff9a 12068@cindex @file{sparc-stub.c}
104c1213
JM
12069@cindex Sparc
12070For @sc{sparc} architectures.
12071
12072@item sparcl-stub.c
41afff9a 12073@cindex @file{sparcl-stub.c}
104c1213
JM
12074@cindex Fujitsu
12075@cindex SparcLite
12076For Fujitsu @sc{sparclite} architectures.
12077
12078@end table
12079
12080The @file{README} file in the @value{GDBN} distribution may list other
12081recently added stubs.
12082
12083@menu
12084* Stub Contents:: What the stub can do for you
12085* Bootstrapping:: What you must do for the stub
12086* Debug Session:: Putting it all together
104c1213
JM
12087@end menu
12088
6d2ebf8b 12089@node Stub Contents
6f05cf9f 12090@subsection What the stub can do for you
104c1213
JM
12091
12092@cindex remote serial stub
12093The debugging stub for your architecture supplies these three
12094subroutines:
12095
12096@table @code
12097@item set_debug_traps
4644b6e3 12098@findex set_debug_traps
104c1213
JM
12099@cindex remote serial stub, initialization
12100This routine arranges for @code{handle_exception} to run when your
12101program stops. You must call this subroutine explicitly near the
12102beginning of your program.
12103
12104@item handle_exception
4644b6e3 12105@findex handle_exception
104c1213
JM
12106@cindex remote serial stub, main routine
12107This is the central workhorse, but your program never calls it
12108explicitly---the setup code arranges for @code{handle_exception} to
12109run when a trap is triggered.
12110
12111@code{handle_exception} takes control when your program stops during
12112execution (for example, on a breakpoint), and mediates communications
12113with @value{GDBN} on the host machine. This is where the communications
12114protocol is implemented; @code{handle_exception} acts as the @value{GDBN}
d4f3574e 12115representative on the target machine. It begins by sending summary
104c1213
JM
12116information on the state of your program, then continues to execute,
12117retrieving and transmitting any information @value{GDBN} needs, until you
12118execute a @value{GDBN} command that makes your program resume; at that point,
12119@code{handle_exception} returns control to your own code on the target
5d161b24 12120machine.
104c1213
JM
12121
12122@item breakpoint
12123@cindex @code{breakpoint} subroutine, remote
12124Use this auxiliary subroutine to make your program contain a
12125breakpoint. Depending on the particular situation, this may be the only
12126way for @value{GDBN} to get control. For instance, if your target
12127machine has some sort of interrupt button, you won't need to call this;
12128pressing the interrupt button transfers control to
12129@code{handle_exception}---in effect, to @value{GDBN}. On some machines,
12130simply receiving characters on the serial port may also trigger a trap;
12131again, in that situation, you don't need to call @code{breakpoint} from
12132your own program---simply running @samp{target remote} from the host
5d161b24 12133@value{GDBN} session gets control.
104c1213
JM
12134
12135Call @code{breakpoint} if none of these is true, or if you simply want
12136to make certain your program stops at a predetermined point for the
12137start of your debugging session.
12138@end table
12139
6d2ebf8b 12140@node Bootstrapping
6f05cf9f 12141@subsection What you must do for the stub
104c1213
JM
12142
12143@cindex remote stub, support routines
12144The debugging stubs that come with @value{GDBN} are set up for a particular
12145chip architecture, but they have no information about the rest of your
12146debugging target machine.
12147
12148First of all you need to tell the stub how to communicate with the
12149serial port.
12150
12151@table @code
12152@item int getDebugChar()
4644b6e3 12153@findex getDebugChar
104c1213
JM
12154Write this subroutine to read a single character from the serial port.
12155It may be identical to @code{getchar} for your target system; a
12156different name is used to allow you to distinguish the two if you wish.
12157
12158@item void putDebugChar(int)
4644b6e3 12159@findex putDebugChar
104c1213 12160Write this subroutine to write a single character to the serial port.
5d161b24 12161It may be identical to @code{putchar} for your target system; a
104c1213
JM
12162different name is used to allow you to distinguish the two if you wish.
12163@end table
12164
12165@cindex control C, and remote debugging
12166@cindex interrupting remote targets
12167If you want @value{GDBN} to be able to stop your program while it is
12168running, you need to use an interrupt-driven serial driver, and arrange
12169for it to stop when it receives a @code{^C} (@samp{\003}, the control-C
12170character). That is the character which @value{GDBN} uses to tell the
12171remote system to stop.
12172
12173Getting the debugging target to return the proper status to @value{GDBN}
12174probably requires changes to the standard stub; one quick and dirty way
12175is to just execute a breakpoint instruction (the ``dirty'' part is that
12176@value{GDBN} reports a @code{SIGTRAP} instead of a @code{SIGINT}).
12177
12178Other routines you need to supply are:
12179
12180@table @code
12181@item void exceptionHandler (int @var{exception_number}, void *@var{exception_address})
4644b6e3 12182@findex exceptionHandler
104c1213
JM
12183Write this function to install @var{exception_address} in the exception
12184handling tables. You need to do this because the stub does not have any
12185way of knowing what the exception handling tables on your target system
12186are like (for example, the processor's table might be in @sc{rom},
12187containing entries which point to a table in @sc{ram}).
12188@var{exception_number} is the exception number which should be changed;
12189its meaning is architecture-dependent (for example, different numbers
12190might represent divide by zero, misaligned access, etc). When this
12191exception occurs, control should be transferred directly to
12192@var{exception_address}, and the processor state (stack, registers,
12193and so on) should be just as it is when a processor exception occurs. So if
12194you want to use a jump instruction to reach @var{exception_address}, it
12195should be a simple jump, not a jump to subroutine.
12196
12197For the 386, @var{exception_address} should be installed as an interrupt
12198gate so that interrupts are masked while the handler runs. The gate
12199should be at privilege level 0 (the most privileged level). The
12200@sc{sparc} and 68k stubs are able to mask interrupts themselves without
12201help from @code{exceptionHandler}.
12202
12203@item void flush_i_cache()
4644b6e3 12204@findex flush_i_cache
d4f3574e 12205On @sc{sparc} and @sc{sparclite} only, write this subroutine to flush the
104c1213
JM
12206instruction cache, if any, on your target machine. If there is no
12207instruction cache, this subroutine may be a no-op.
12208
12209On target machines that have instruction caches, @value{GDBN} requires this
12210function to make certain that the state of your program is stable.
12211@end table
12212
12213@noindent
12214You must also make sure this library routine is available:
12215
12216@table @code
12217@item void *memset(void *, int, int)
4644b6e3 12218@findex memset
104c1213
JM
12219This is the standard library function @code{memset} that sets an area of
12220memory to a known value. If you have one of the free versions of
12221@code{libc.a}, @code{memset} can be found there; otherwise, you must
12222either obtain it from your hardware manufacturer, or write your own.
12223@end table
12224
12225If you do not use the GNU C compiler, you may need other standard
12226library subroutines as well; this varies from one stub to another,
12227but in general the stubs are likely to use any of the common library
d4f3574e 12228subroutines which @code{@value{GCC}} generates as inline code.
104c1213
JM
12229
12230
6d2ebf8b 12231@node Debug Session
6f05cf9f 12232@subsection Putting it all together
104c1213
JM
12233
12234@cindex remote serial debugging summary
12235In summary, when your program is ready to debug, you must follow these
12236steps.
12237
12238@enumerate
12239@item
6d2ebf8b 12240Make sure you have defined the supporting low-level routines
104c1213
JM
12241(@pxref{Bootstrapping,,What you must do for the stub}):
12242@display
12243@code{getDebugChar}, @code{putDebugChar},
12244@code{flush_i_cache}, @code{memset}, @code{exceptionHandler}.
12245@end display
12246
12247@item
12248Insert these lines near the top of your program:
12249
474c8240 12250@smallexample
104c1213
JM
12251set_debug_traps();
12252breakpoint();
474c8240 12253@end smallexample
104c1213
JM
12254
12255@item
12256For the 680x0 stub only, you need to provide a variable called
12257@code{exceptionHook}. Normally you just use:
12258
474c8240 12259@smallexample
104c1213 12260void (*exceptionHook)() = 0;
474c8240 12261@end smallexample
104c1213 12262
d4f3574e 12263@noindent
104c1213 12264but if before calling @code{set_debug_traps}, you set it to point to a
598ca718 12265function in your program, that function is called when
104c1213
JM
12266@code{@value{GDBN}} continues after stopping on a trap (for example, bus
12267error). The function indicated by @code{exceptionHook} is called with
12268one parameter: an @code{int} which is the exception number.
12269
12270@item
12271Compile and link together: your program, the @value{GDBN} debugging stub for
12272your target architecture, and the supporting subroutines.
12273
12274@item
12275Make sure you have a serial connection between your target machine and
12276the @value{GDBN} host, and identify the serial port on the host.
12277
12278@item
12279@c The "remote" target now provides a `load' command, so we should
12280@c document that. FIXME.
12281Download your program to your target machine (or get it there by
12282whatever means the manufacturer provides), and start it.
12283
12284@item
07f31aa6
DJ
12285Start @value{GDBN} on the host, and connect to the target
12286(@pxref{Connecting,,Connecting to a remote target}).
9db8d71f 12287
104c1213
JM
12288@end enumerate
12289
8e04817f
AC
12290@node Configurations
12291@chapter Configuration-Specific Information
104c1213 12292
8e04817f
AC
12293While nearly all @value{GDBN} commands are available for all native and
12294cross versions of the debugger, there are some exceptions. This chapter
12295describes things that are only available in certain configurations.
104c1213 12296
8e04817f
AC
12297There are three major categories of configurations: native
12298configurations, where the host and target are the same, embedded
12299operating system configurations, which are usually the same for several
12300different processor architectures, and bare embedded processors, which
12301are quite different from each other.
104c1213 12302
8e04817f
AC
12303@menu
12304* Native::
12305* Embedded OS::
12306* Embedded Processors::
12307* Architectures::
12308@end menu
104c1213 12309
8e04817f
AC
12310@node Native
12311@section Native
104c1213 12312
8e04817f
AC
12313This section describes details specific to particular native
12314configurations.
6cf7e474 12315
8e04817f
AC
12316@menu
12317* HP-UX:: HP-UX
7561d450 12318* BSD libkvm Interface:: Debugging BSD kernel memory images
8e04817f
AC
12319* SVR4 Process Information:: SVR4 process information
12320* DJGPP Native:: Features specific to the DJGPP port
78c47bea 12321* Cygwin Native:: Features specific to the Cygwin port
14d6dd68 12322* Hurd Native:: Features specific to @sc{gnu} Hurd
a64548ea 12323* Neutrino:: Features specific to QNX Neutrino
8e04817f 12324@end menu
6cf7e474 12325
8e04817f
AC
12326@node HP-UX
12327@subsection HP-UX
104c1213 12328
8e04817f
AC
12329On HP-UX systems, if you refer to a function or variable name that
12330begins with a dollar sign, @value{GDBN} searches for a user or system
12331name first, before it searches for a convenience variable.
104c1213 12332
9c16f35a 12333
7561d450
MK
12334@node BSD libkvm Interface
12335@subsection BSD libkvm Interface
12336
12337@cindex libkvm
12338@cindex kernel memory image
12339@cindex kernel crash dump
12340
12341BSD-derived systems (FreeBSD/NetBSD/OpenBSD) have a kernel memory
12342interface that provides a uniform interface for accessing kernel virtual
12343memory images, including live systems and crash dumps. @value{GDBN}
12344uses this interface to allow you to debug live kernels and kernel crash
12345dumps on many native BSD configurations. This is implemented as a
12346special @code{kvm} debugging target. For debugging a live system, load
12347the currently running kernel into @value{GDBN} and connect to the
12348@code{kvm} target:
12349
12350@smallexample
12351(@value{GDBP}) @b{target kvm}
12352@end smallexample
12353
12354For debugging crash dumps, provide the file name of the crash dump as an
12355argument:
12356
12357@smallexample
12358(@value{GDBP}) @b{target kvm /var/crash/bsd.0}
12359@end smallexample
12360
12361Once connected to the @code{kvm} target, the following commands are
12362available:
12363
12364@table @code
12365@kindex kvm
12366@item kvm pcb
12367Set current context from pcb address.
12368
12369@item kvm proc
12370Set current context from proc address. This command isn't available on
12371modern FreeBSD systems.
12372@end table
12373
8e04817f
AC
12374@node SVR4 Process Information
12375@subsection SVR4 process information
60bf7e09
EZ
12376@cindex /proc
12377@cindex examine process image
12378@cindex process info via @file{/proc}
104c1213 12379
60bf7e09
EZ
12380Many versions of SVR4 and compatible systems provide a facility called
12381@samp{/proc} that can be used to examine the image of a running
12382process using file-system subroutines. If @value{GDBN} is configured
12383for an operating system with this facility, the command @code{info
12384proc} is available to report information about the process running
12385your program, or about any process running on your system. @code{info
12386proc} works only on SVR4 systems that include the @code{procfs} code.
12387This includes, as of this writing, @sc{gnu}/Linux, OSF/1 (Digital
12388Unix), Solaris, Irix, and Unixware, but not HP-UX, for example.
104c1213 12389
8e04817f
AC
12390@table @code
12391@kindex info proc
60bf7e09 12392@cindex process ID
8e04817f 12393@item info proc
60bf7e09
EZ
12394@itemx info proc @var{process-id}
12395Summarize available information about any running process. If a
12396process ID is specified by @var{process-id}, display information about
12397that process; otherwise display information about the program being
12398debugged. The summary includes the debugged process ID, the command
12399line used to invoke it, its current working directory, and its
12400executable file's absolute file name.
12401
12402On some systems, @var{process-id} can be of the form
12403@samp{[@var{pid}]/@var{tid}} which specifies a certain thread ID
12404within a process. If the optional @var{pid} part is missing, it means
12405a thread from the process being debugged (the leading @samp{/} still
12406needs to be present, or else @value{GDBN} will interpret the number as
12407a process ID rather than a thread ID).
6cf7e474 12408
8e04817f 12409@item info proc mappings
60bf7e09
EZ
12410@cindex memory address space mappings
12411Report the memory address space ranges accessible in the program, with
12412information on whether the process has read, write, or execute access
12413rights to each range. On @sc{gnu}/Linux systems, each memory range
12414includes the object file which is mapped to that range, instead of the
12415memory access rights to that range.
12416
12417@item info proc stat
12418@itemx info proc status
12419@cindex process detailed status information
12420These subcommands are specific to @sc{gnu}/Linux systems. They show
12421the process-related information, including the user ID and group ID;
12422how many threads are there in the process; its virtual memory usage;
12423the signals that are pending, blocked, and ignored; its TTY; its
12424consumption of system and user time; its stack size; its @samp{nice}
12425value; etc. For more information, see the @samp{proc(5)} man page
12426(type @kbd{man 5 proc} from your shell prompt).
12427
12428@item info proc all
12429Show all the information about the process described under all of the
12430above @code{info proc} subcommands.
12431
8e04817f
AC
12432@ignore
12433@comment These sub-options of 'info proc' were not included when
12434@comment procfs.c was re-written. Keep their descriptions around
12435@comment against the day when someone finds the time to put them back in.
12436@kindex info proc times
12437@item info proc times
12438Starting time, user CPU time, and system CPU time for your program and
12439its children.
6cf7e474 12440
8e04817f
AC
12441@kindex info proc id
12442@item info proc id
12443Report on the process IDs related to your program: its own process ID,
12444the ID of its parent, the process group ID, and the session ID.
8e04817f
AC
12445@end ignore
12446@end table
104c1213 12447
8e04817f
AC
12448@node DJGPP Native
12449@subsection Features for Debugging @sc{djgpp} Programs
12450@cindex @sc{djgpp} debugging
12451@cindex native @sc{djgpp} debugging
12452@cindex MS-DOS-specific commands
104c1213 12453
8e04817f
AC
12454@sc{djgpp} is the port of @sc{gnu} development tools to MS-DOS and
12455MS-Windows. @sc{djgpp} programs are 32-bit protected-mode programs
12456that use the @dfn{DPMI} (DOS Protected-Mode Interface) API to run on
12457top of real-mode DOS systems and their emulations.
104c1213 12458
8e04817f
AC
12459@value{GDBN} supports native debugging of @sc{djgpp} programs, and
12460defines a few commands specific to the @sc{djgpp} port. This
12461subsection describes those commands.
104c1213 12462
8e04817f
AC
12463@table @code
12464@kindex info dos
12465@item info dos
12466This is a prefix of @sc{djgpp}-specific commands which print
12467information about the target system and important OS structures.
f1251bdd 12468
8e04817f
AC
12469@kindex sysinfo
12470@cindex MS-DOS system info
12471@cindex free memory information (MS-DOS)
12472@item info dos sysinfo
12473This command displays assorted information about the underlying
12474platform: the CPU type and features, the OS version and flavor, the
12475DPMI version, and the available conventional and DPMI memory.
104c1213 12476
8e04817f
AC
12477@cindex GDT
12478@cindex LDT
12479@cindex IDT
12480@cindex segment descriptor tables
12481@cindex descriptor tables display
12482@item info dos gdt
12483@itemx info dos ldt
12484@itemx info dos idt
12485These 3 commands display entries from, respectively, Global, Local,
12486and Interrupt Descriptor Tables (GDT, LDT, and IDT). The descriptor
12487tables are data structures which store a descriptor for each segment
12488that is currently in use. The segment's selector is an index into a
12489descriptor table; the table entry for that index holds the
12490descriptor's base address and limit, and its attributes and access
12491rights.
104c1213 12492
8e04817f
AC
12493A typical @sc{djgpp} program uses 3 segments: a code segment, a data
12494segment (used for both data and the stack), and a DOS segment (which
12495allows access to DOS/BIOS data structures and absolute addresses in
12496conventional memory). However, the DPMI host will usually define
12497additional segments in order to support the DPMI environment.
d4f3574e 12498
8e04817f
AC
12499@cindex garbled pointers
12500These commands allow to display entries from the descriptor tables.
12501Without an argument, all entries from the specified table are
12502displayed. An argument, which should be an integer expression, means
12503display a single entry whose index is given by the argument. For
12504example, here's a convenient way to display information about the
12505debugged program's data segment:
104c1213 12506
8e04817f
AC
12507@smallexample
12508@exdent @code{(@value{GDBP}) info dos ldt $ds}
12509@exdent @code{0x13f: base=0x11970000 limit=0x0009ffff 32-Bit Data (Read/Write, Exp-up)}
12510@end smallexample
104c1213 12511
8e04817f
AC
12512@noindent
12513This comes in handy when you want to see whether a pointer is outside
12514the data segment's limit (i.e.@: @dfn{garbled}).
104c1213 12515
8e04817f
AC
12516@cindex page tables display (MS-DOS)
12517@item info dos pde
12518@itemx info dos pte
12519These two commands display entries from, respectively, the Page
12520Directory and the Page Tables. Page Directories and Page Tables are
12521data structures which control how virtual memory addresses are mapped
12522into physical addresses. A Page Table includes an entry for every
12523page of memory that is mapped into the program's address space; there
12524may be several Page Tables, each one holding up to 4096 entries. A
12525Page Directory has up to 4096 entries, one each for every Page Table
12526that is currently in use.
104c1213 12527
8e04817f
AC
12528Without an argument, @kbd{info dos pde} displays the entire Page
12529Directory, and @kbd{info dos pte} displays all the entries in all of
12530the Page Tables. An argument, an integer expression, given to the
12531@kbd{info dos pde} command means display only that entry from the Page
12532Directory table. An argument given to the @kbd{info dos pte} command
12533means display entries from a single Page Table, the one pointed to by
12534the specified entry in the Page Directory.
104c1213 12535
8e04817f
AC
12536@cindex direct memory access (DMA) on MS-DOS
12537These commands are useful when your program uses @dfn{DMA} (Direct
12538Memory Access), which needs physical addresses to program the DMA
12539controller.
104c1213 12540
8e04817f 12541These commands are supported only with some DPMI servers.
104c1213 12542
8e04817f
AC
12543@cindex physical address from linear address
12544@item info dos address-pte @var{addr}
12545This command displays the Page Table entry for a specified linear
12546address. The argument linear address @var{addr} should already have the
12547appropriate segment's base address added to it, because this command
12548accepts addresses which may belong to @emph{any} segment. For
12549example, here's how to display the Page Table entry for the page where
12550the variable @code{i} is stored:
104c1213 12551
b383017d 12552@smallexample
8e04817f
AC
12553@exdent @code{(@value{GDBP}) info dos address-pte __djgpp_base_address + (char *)&i}
12554@exdent @code{Page Table entry for address 0x11a00d30:}
b383017d 12555@exdent @code{Base=0x02698000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0xd30}
8e04817f 12556@end smallexample
104c1213 12557
8e04817f
AC
12558@noindent
12559This says that @code{i} is stored at offset @code{0xd30} from the page
12560whose physical base address is @code{0x02698000}, and prints all the
12561attributes of that page.
104c1213 12562
8e04817f
AC
12563Note that you must cast the addresses of variables to a @code{char *},
12564since otherwise the value of @code{__djgpp_base_address}, the base
12565address of all variables and functions in a @sc{djgpp} program, will
12566be added using the rules of C pointer arithmetics: if @code{i} is
12567declared an @code{int}, @value{GDBN} will add 4 times the value of
12568@code{__djgpp_base_address} to the address of @code{i}.
104c1213 12569
8e04817f
AC
12570Here's another example, it displays the Page Table entry for the
12571transfer buffer:
104c1213 12572
8e04817f
AC
12573@smallexample
12574@exdent @code{(@value{GDBP}) info dos address-pte *((unsigned *)&_go32_info_block + 3)}
12575@exdent @code{Page Table entry for address 0x29110:}
12576@exdent @code{Base=0x00029000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0x110}
12577@end smallexample
104c1213 12578
8e04817f
AC
12579@noindent
12580(The @code{+ 3} offset is because the transfer buffer's address is the
125813rd member of the @code{_go32_info_block} structure.) The output of
12582this command clearly shows that addresses in conventional memory are
12583mapped 1:1, i.e.@: the physical and linear addresses are identical.
104c1213 12584
8e04817f
AC
12585This command is supported only with some DPMI servers.
12586@end table
104c1213 12587
a8f24a35
EZ
12588In addition to native debugging, the DJGPP port supports remote
12589debugging via a serial data link. The following commands are specific
12590to remote serial debugging in the DJGPP port of @value{GDBN}.
12591
12592@table @code
12593@kindex set com1base
12594@kindex set com1irq
12595@kindex set com2base
12596@kindex set com2irq
12597@kindex set com3base
12598@kindex set com3irq
12599@kindex set com4base
12600@kindex set com4irq
12601@item set com1base @var{addr}
12602This command sets the base I/O port address of the @file{COM1} serial
12603port.
12604
12605@item set com1irq @var{irq}
12606This command sets the @dfn{Interrupt Request} (@code{IRQ}) line to use
12607for the @file{COM1} serial port.
12608
12609There are similar commands @samp{set com2base}, @samp{set com3irq},
12610etc.@: for setting the port address and the @code{IRQ} lines for the
12611other 3 COM ports.
12612
12613@kindex show com1base
12614@kindex show com1irq
12615@kindex show com2base
12616@kindex show com2irq
12617@kindex show com3base
12618@kindex show com3irq
12619@kindex show com4base
12620@kindex show com4irq
12621The related commands @samp{show com1base}, @samp{show com1irq} etc.@:
12622display the current settings of the base address and the @code{IRQ}
12623lines used by the COM ports.
12624@end table
12625
12626
78c47bea
PM
12627@node Cygwin Native
12628@subsection Features for Debugging MS Windows PE executables
12629@cindex MS Windows debugging
12630@cindex native Cygwin debugging
12631@cindex Cygwin-specific commands
12632
be448670
CF
12633@value{GDBN} supports native debugging of MS Windows programs, including
12634DLLs with and without symbolic debugging information. There are various
12635additional Cygwin-specific commands, described in this subsection. The
12636subsubsection @pxref{Non-debug DLL symbols} describes working with DLLs
12637that have no debugging symbols.
12638
78c47bea
PM
12639
12640@table @code
12641@kindex info w32
12642@item info w32
12643This is a prefix of MS Windows specific commands which print
12644information about the target system and important OS structures.
12645
12646@item info w32 selector
12647This command displays information returned by
12648the Win32 API @code{GetThreadSelectorEntry} function.
12649It takes an optional argument that is evaluated to
12650a long value to give the information about this given selector.
12651Without argument, this command displays information
12652about the the six segment registers.
12653
12654@kindex info dll
12655@item info dll
12656This is a Cygwin specific alias of info shared.
12657
12658@kindex dll-symbols
12659@item dll-symbols
12660This command loads symbols from a dll similarly to
12661add-sym command but without the need to specify a base address.
12662
b383017d 12663@kindex set new-console
78c47bea 12664@item set new-console @var{mode}
b383017d 12665If @var{mode} is @code{on} the debuggee will
78c47bea
PM
12666be started in a new console on next start.
12667If @var{mode} is @code{off}i, the debuggee will
12668be started in the same console as the debugger.
12669
12670@kindex show new-console
12671@item show new-console
12672Displays whether a new console is used
12673when the debuggee is started.
12674
12675@kindex set new-group
12676@item set new-group @var{mode}
12677This boolean value controls whether the debuggee should
12678start a new group or stay in the same group as the debugger.
12679This affects the way the Windows OS handles
12680Ctrl-C.
12681
12682@kindex show new-group
12683@item show new-group
12684Displays current value of new-group boolean.
12685
12686@kindex set debugevents
12687@item set debugevents
12688This boolean value adds debug output concerning events seen by the debugger.
12689
12690@kindex set debugexec
12691@item set debugexec
b383017d 12692This boolean value adds debug output concerning execute events
78c47bea
PM
12693seen by the debugger.
12694
12695@kindex set debugexceptions
12696@item set debugexceptions
b383017d 12697This boolean value adds debug ouptut concerning exception events
78c47bea
PM
12698seen by the debugger.
12699
12700@kindex set debugmemory
12701@item set debugmemory
b383017d 12702This boolean value adds debug ouptut concerning memory events
78c47bea
PM
12703seen by the debugger.
12704
12705@kindex set shell
12706@item set shell
12707This boolean values specifies whether the debuggee is called
12708via a shell or directly (default value is on).
12709
12710@kindex show shell
12711@item show shell
12712Displays if the debuggee will be started with a shell.
12713
12714@end table
12715
be448670
CF
12716@menu
12717* Non-debug DLL symbols:: Support for DLLs without debugging symbols
12718@end menu
12719
12720@node Non-debug DLL symbols
12721@subsubsection Support for DLLs without debugging symbols
12722@cindex DLLs with no debugging symbols
12723@cindex Minimal symbols and DLLs
12724
12725Very often on windows, some of the DLLs that your program relies on do
12726not include symbolic debugging information (for example,
12727@file{kernel32.dll}). When @value{GDBN} doesn't recognize any debugging
12728symbols in a DLL, it relies on the minimal amount of symbolic
12729information contained in the DLL's export table. This subsubsection
12730describes working with such symbols, known internally to @value{GDBN} as
12731``minimal symbols''.
12732
12733Note that before the debugged program has started execution, no DLLs
12734will have been loaded. The easiest way around this problem is simply to
12735start the program --- either by setting a breakpoint or letting the
12736program run once to completion. It is also possible to force
12737@value{GDBN} to load a particular DLL before starting the executable ---
12738see the shared library information in @pxref{Files} or the
12739@code{dll-symbols} command in @pxref{Cygwin Native}. Currently,
12740explicitly loading symbols from a DLL with no debugging information will
12741cause the symbol names to be duplicated in @value{GDBN}'s lookup table,
12742which may adversely affect symbol lookup performance.
12743
12744@subsubsection DLL name prefixes
12745
12746In keeping with the naming conventions used by the Microsoft debugging
12747tools, DLL export symbols are made available with a prefix based on the
12748DLL name, for instance @code{KERNEL32!CreateFileA}. The plain name is
12749also entered into the symbol table, so @code{CreateFileA} is often
12750sufficient. In some cases there will be name clashes within a program
12751(particularly if the executable itself includes full debugging symbols)
12752necessitating the use of the fully qualified name when referring to the
12753contents of the DLL. Use single-quotes around the name to avoid the
12754exclamation mark (``!'') being interpreted as a language operator.
12755
12756Note that the internal name of the DLL may be all upper-case, even
12757though the file name of the DLL is lower-case, or vice-versa. Since
12758symbols within @value{GDBN} are @emph{case-sensitive} this may cause
12759some confusion. If in doubt, try the @code{info functions} and
12760@code{info variables} commands or even @code{maint print msymbols} (see
12761@pxref{Symbols}). Here's an example:
12762
12763@smallexample
f7dc1244 12764(@value{GDBP}) info function CreateFileA
be448670
CF
12765All functions matching regular expression "CreateFileA":
12766
12767Non-debugging symbols:
127680x77e885f4 CreateFileA
127690x77e885f4 KERNEL32!CreateFileA
12770@end smallexample
12771
12772@smallexample
f7dc1244 12773(@value{GDBP}) info function !
be448670
CF
12774All functions matching regular expression "!":
12775
12776Non-debugging symbols:
127770x6100114c cygwin1!__assert
127780x61004034 cygwin1!_dll_crt0@@0
127790x61004240 cygwin1!dll_crt0(per_process *)
12780[etc...]
12781@end smallexample
12782
12783@subsubsection Working with minimal symbols
12784
12785Symbols extracted from a DLL's export table do not contain very much
12786type information. All that @value{GDBN} can do is guess whether a symbol
12787refers to a function or variable depending on the linker section that
12788contains the symbol. Also note that the actual contents of the memory
12789contained in a DLL are not available unless the program is running. This
12790means that you cannot examine the contents of a variable or disassemble
12791a function within a DLL without a running program.
12792
12793Variables are generally treated as pointers and dereferenced
12794automatically. For this reason, it is often necessary to prefix a
12795variable name with the address-of operator (``&'') and provide explicit
12796type information in the command. Here's an example of the type of
12797problem:
12798
12799@smallexample
f7dc1244 12800(@value{GDBP}) print 'cygwin1!__argv'
be448670
CF
12801$1 = 268572168
12802@end smallexample
12803
12804@smallexample
f7dc1244 12805(@value{GDBP}) x 'cygwin1!__argv'
be448670
CF
128060x10021610: "\230y\""
12807@end smallexample
12808
12809And two possible solutions:
12810
12811@smallexample
f7dc1244 12812(@value{GDBP}) print ((char **)'cygwin1!__argv')[0]
be448670
CF
12813$2 = 0x22fd98 "/cygdrive/c/mydirectory/myprogram"
12814@end smallexample
12815
12816@smallexample
f7dc1244 12817(@value{GDBP}) x/2x &'cygwin1!__argv'
be448670 128180x610c0aa8 <cygwin1!__argv>: 0x10021608 0x00000000
f7dc1244 12819(@value{GDBP}) x/x 0x10021608
be448670 128200x10021608: 0x0022fd98
f7dc1244 12821(@value{GDBP}) x/s 0x0022fd98
be448670
CF
128220x22fd98: "/cygdrive/c/mydirectory/myprogram"
12823@end smallexample
12824
12825Setting a break point within a DLL is possible even before the program
12826starts execution. However, under these circumstances, @value{GDBN} can't
12827examine the initial instructions of the function in order to skip the
12828function's frame set-up code. You can work around this by using ``*&''
12829to set the breakpoint at a raw memory address:
12830
12831@smallexample
f7dc1244 12832(@value{GDBP}) break *&'python22!PyOS_Readline'
be448670
CF
12833Breakpoint 1 at 0x1e04eff0
12834@end smallexample
12835
12836The author of these extensions is not entirely convinced that setting a
12837break point within a shared DLL like @file{kernel32.dll} is completely
12838safe.
12839
14d6dd68
EZ
12840@node Hurd Native
12841@subsection Commands specific to @sc{gnu} Hurd systems
12842@cindex @sc{gnu} Hurd debugging
12843
12844This subsection describes @value{GDBN} commands specific to the
12845@sc{gnu} Hurd native debugging.
12846
12847@table @code
12848@item set signals
12849@itemx set sigs
12850@kindex set signals@r{, Hurd command}
12851@kindex set sigs@r{, Hurd command}
12852This command toggles the state of inferior signal interception by
12853@value{GDBN}. Mach exceptions, such as breakpoint traps, are not
12854affected by this command. @code{sigs} is a shorthand alias for
12855@code{signals}.
12856
12857@item show signals
12858@itemx show sigs
12859@kindex show signals@r{, Hurd command}
12860@kindex show sigs@r{, Hurd command}
12861Show the current state of intercepting inferior's signals.
12862
12863@item set signal-thread
12864@itemx set sigthread
12865@kindex set signal-thread
12866@kindex set sigthread
12867This command tells @value{GDBN} which thread is the @code{libc} signal
12868thread. That thread is run when a signal is delivered to a running
12869process. @code{set sigthread} is the shorthand alias of @code{set
12870signal-thread}.
12871
12872@item show signal-thread
12873@itemx show sigthread
12874@kindex show signal-thread
12875@kindex show sigthread
12876These two commands show which thread will run when the inferior is
12877delivered a signal.
12878
12879@item set stopped
12880@kindex set stopped@r{, Hurd command}
12881This commands tells @value{GDBN} that the inferior process is stopped,
12882as with the @code{SIGSTOP} signal. The stopped process can be
12883continued by delivering a signal to it.
12884
12885@item show stopped
12886@kindex show stopped@r{, Hurd command}
12887This command shows whether @value{GDBN} thinks the debuggee is
12888stopped.
12889
12890@item set exceptions
12891@kindex set exceptions@r{, Hurd command}
12892Use this command to turn off trapping of exceptions in the inferior.
12893When exception trapping is off, neither breakpoints nor
12894single-stepping will work. To restore the default, set exception
12895trapping on.
12896
12897@item show exceptions
12898@kindex show exceptions@r{, Hurd command}
12899Show the current state of trapping exceptions in the inferior.
12900
12901@item set task pause
12902@kindex set task@r{, Hurd commands}
12903@cindex task attributes (@sc{gnu} Hurd)
12904@cindex pause current task (@sc{gnu} Hurd)
12905This command toggles task suspension when @value{GDBN} has control.
12906Setting it to on takes effect immediately, and the task is suspended
12907whenever @value{GDBN} gets control. Setting it to off will take
12908effect the next time the inferior is continued. If this option is set
12909to off, you can use @code{set thread default pause on} or @code{set
12910thread pause on} (see below) to pause individual threads.
12911
12912@item show task pause
12913@kindex show task@r{, Hurd commands}
12914Show the current state of task suspension.
12915
12916@item set task detach-suspend-count
12917@cindex task suspend count
12918@cindex detach from task, @sc{gnu} Hurd
12919This command sets the suspend count the task will be left with when
12920@value{GDBN} detaches from it.
12921
12922@item show task detach-suspend-count
12923Show the suspend count the task will be left with when detaching.
12924
12925@item set task exception-port
12926@itemx set task excp
12927@cindex task exception port, @sc{gnu} Hurd
12928This command sets the task exception port to which @value{GDBN} will
12929forward exceptions. The argument should be the value of the @dfn{send
12930rights} of the task. @code{set task excp} is a shorthand alias.
12931
12932@item set noninvasive
12933@cindex noninvasive task options
12934This command switches @value{GDBN} to a mode that is the least
12935invasive as far as interfering with the inferior is concerned. This
12936is the same as using @code{set task pause}, @code{set exceptions}, and
12937@code{set signals} to values opposite to the defaults.
12938
12939@item info send-rights
12940@itemx info receive-rights
12941@itemx info port-rights
12942@itemx info port-sets
12943@itemx info dead-names
12944@itemx info ports
12945@itemx info psets
12946@cindex send rights, @sc{gnu} Hurd
12947@cindex receive rights, @sc{gnu} Hurd
12948@cindex port rights, @sc{gnu} Hurd
12949@cindex port sets, @sc{gnu} Hurd
12950@cindex dead names, @sc{gnu} Hurd
12951These commands display information about, respectively, send rights,
12952receive rights, port rights, port sets, and dead names of a task.
12953There are also shorthand aliases: @code{info ports} for @code{info
12954port-rights} and @code{info psets} for @code{info port-sets}.
12955
12956@item set thread pause
12957@kindex set thread@r{, Hurd command}
12958@cindex thread properties, @sc{gnu} Hurd
12959@cindex pause current thread (@sc{gnu} Hurd)
12960This command toggles current thread suspension when @value{GDBN} has
12961control. Setting it to on takes effect immediately, and the current
12962thread is suspended whenever @value{GDBN} gets control. Setting it to
12963off will take effect the next time the inferior is continued.
12964Normally, this command has no effect, since when @value{GDBN} has
12965control, the whole task is suspended. However, if you used @code{set
12966task pause off} (see above), this command comes in handy to suspend
12967only the current thread.
12968
12969@item show thread pause
12970@kindex show thread@r{, Hurd command}
12971This command shows the state of current thread suspension.
12972
12973@item set thread run
12974This comamnd sets whether the current thread is allowed to run.
12975
12976@item show thread run
12977Show whether the current thread is allowed to run.
12978
12979@item set thread detach-suspend-count
12980@cindex thread suspend count, @sc{gnu} Hurd
12981@cindex detach from thread, @sc{gnu} Hurd
12982This command sets the suspend count @value{GDBN} will leave on a
12983thread when detaching. This number is relative to the suspend count
12984found by @value{GDBN} when it notices the thread; use @code{set thread
12985takeover-suspend-count} to force it to an absolute value.
12986
12987@item show thread detach-suspend-count
12988Show the suspend count @value{GDBN} will leave on the thread when
12989detaching.
12990
12991@item set thread exception-port
12992@itemx set thread excp
12993Set the thread exception port to which to forward exceptions. This
12994overrides the port set by @code{set task exception-port} (see above).
12995@code{set thread excp} is the shorthand alias.
12996
12997@item set thread takeover-suspend-count
12998Normally, @value{GDBN}'s thread suspend counts are relative to the
12999value @value{GDBN} finds when it notices each thread. This command
13000changes the suspend counts to be absolute instead.
13001
13002@item set thread default
13003@itemx show thread default
13004@cindex thread default settings, @sc{gnu} Hurd
13005Each of the above @code{set thread} commands has a @code{set thread
13006default} counterpart (e.g., @code{set thread default pause}, @code{set
13007thread default exception-port}, etc.). The @code{thread default}
13008variety of commands sets the default thread properties for all
13009threads; you can then change the properties of individual threads with
13010the non-default commands.
13011@end table
13012
13013
a64548ea
EZ
13014@node Neutrino
13015@subsection QNX Neutrino
13016@cindex QNX Neutrino
13017
13018@value{GDBN} provides the following commands specific to the QNX
13019Neutrino target:
13020
13021@table @code
13022@item set debug nto-debug
13023@kindex set debug nto-debug
13024When set to on, enables debugging messages specific to the QNX
13025Neutrino support.
13026
13027@item show debug nto-debug
13028@kindex show debug nto-debug
13029Show the current state of QNX Neutrino messages.
13030@end table
13031
13032
8e04817f
AC
13033@node Embedded OS
13034@section Embedded Operating Systems
104c1213 13035
8e04817f
AC
13036This section describes configurations involving the debugging of
13037embedded operating systems that are available for several different
13038architectures.
d4f3574e 13039
8e04817f
AC
13040@menu
13041* VxWorks:: Using @value{GDBN} with VxWorks
13042@end menu
104c1213 13043
8e04817f
AC
13044@value{GDBN} includes the ability to debug programs running on
13045various real-time operating systems.
104c1213 13046
8e04817f
AC
13047@node VxWorks
13048@subsection Using @value{GDBN} with VxWorks
104c1213 13049
8e04817f 13050@cindex VxWorks
104c1213 13051
8e04817f 13052@table @code
104c1213 13053
8e04817f
AC
13054@kindex target vxworks
13055@item target vxworks @var{machinename}
13056A VxWorks system, attached via TCP/IP. The argument @var{machinename}
13057is the target system's machine name or IP address.
104c1213 13058
8e04817f 13059@end table
104c1213 13060
8e04817f
AC
13061On VxWorks, @code{load} links @var{filename} dynamically on the
13062current target system as well as adding its symbols in @value{GDBN}.
104c1213 13063
8e04817f
AC
13064@value{GDBN} enables developers to spawn and debug tasks running on networked
13065VxWorks targets from a Unix host. Already-running tasks spawned from
13066the VxWorks shell can also be debugged. @value{GDBN} uses code that runs on
13067both the Unix host and on the VxWorks target. The program
13068@code{@value{GDBP}} is installed and executed on the Unix host. (It may be
13069installed with the name @code{vxgdb}, to distinguish it from a
13070@value{GDBN} for debugging programs on the host itself.)
104c1213 13071
8e04817f
AC
13072@table @code
13073@item VxWorks-timeout @var{args}
13074@kindex vxworks-timeout
13075All VxWorks-based targets now support the option @code{vxworks-timeout}.
13076This option is set by the user, and @var{args} represents the number of
13077seconds @value{GDBN} waits for responses to rpc's. You might use this if
13078your VxWorks target is a slow software simulator or is on the far side
13079of a thin network line.
13080@end table
104c1213 13081
8e04817f
AC
13082The following information on connecting to VxWorks was current when
13083this manual was produced; newer releases of VxWorks may use revised
13084procedures.
104c1213 13085
4644b6e3 13086@findex INCLUDE_RDB
8e04817f
AC
13087To use @value{GDBN} with VxWorks, you must rebuild your VxWorks kernel
13088to include the remote debugging interface routines in the VxWorks
13089library @file{rdb.a}. To do this, define @code{INCLUDE_RDB} in the
13090VxWorks configuration file @file{configAll.h} and rebuild your VxWorks
13091kernel. The resulting kernel contains @file{rdb.a}, and spawns the
13092source debugging task @code{tRdbTask} when VxWorks is booted. For more
13093information on configuring and remaking VxWorks, see the manufacturer's
13094manual.
13095@c VxWorks, see the @cite{VxWorks Programmer's Guide}.
104c1213 13096
8e04817f
AC
13097Once you have included @file{rdb.a} in your VxWorks system image and set
13098your Unix execution search path to find @value{GDBN}, you are ready to
13099run @value{GDBN}. From your Unix host, run @code{@value{GDBP}} (or
13100@code{vxgdb}, depending on your installation).
104c1213 13101
8e04817f 13102@value{GDBN} comes up showing the prompt:
104c1213 13103
474c8240 13104@smallexample
8e04817f 13105(vxgdb)
474c8240 13106@end smallexample
104c1213 13107
8e04817f
AC
13108@menu
13109* VxWorks Connection:: Connecting to VxWorks
13110* VxWorks Download:: VxWorks download
13111* VxWorks Attach:: Running tasks
13112@end menu
104c1213 13113
8e04817f
AC
13114@node VxWorks Connection
13115@subsubsection Connecting to VxWorks
104c1213 13116
8e04817f
AC
13117The @value{GDBN} command @code{target} lets you connect to a VxWorks target on the
13118network. To connect to a target whose host name is ``@code{tt}'', type:
104c1213 13119
474c8240 13120@smallexample
8e04817f 13121(vxgdb) target vxworks tt
474c8240 13122@end smallexample
104c1213 13123
8e04817f
AC
13124@need 750
13125@value{GDBN} displays messages like these:
104c1213 13126
8e04817f
AC
13127@smallexample
13128Attaching remote machine across net...
13129Connected to tt.
13130@end smallexample
104c1213 13131
8e04817f
AC
13132@need 1000
13133@value{GDBN} then attempts to read the symbol tables of any object modules
13134loaded into the VxWorks target since it was last booted. @value{GDBN} locates
13135these files by searching the directories listed in the command search
13136path (@pxref{Environment, ,Your program's environment}); if it fails
13137to find an object file, it displays a message such as:
5d161b24 13138
474c8240 13139@smallexample
8e04817f 13140prog.o: No such file or directory.
474c8240 13141@end smallexample
104c1213 13142
8e04817f
AC
13143When this happens, add the appropriate directory to the search path with
13144the @value{GDBN} command @code{path}, and execute the @code{target}
13145command again.
104c1213 13146
8e04817f
AC
13147@node VxWorks Download
13148@subsubsection VxWorks download
104c1213 13149
8e04817f
AC
13150@cindex download to VxWorks
13151If you have connected to the VxWorks target and you want to debug an
13152object that has not yet been loaded, you can use the @value{GDBN}
13153@code{load} command to download a file from Unix to VxWorks
13154incrementally. The object file given as an argument to the @code{load}
13155command is actually opened twice: first by the VxWorks target in order
13156to download the code, then by @value{GDBN} in order to read the symbol
13157table. This can lead to problems if the current working directories on
13158the two systems differ. If both systems have NFS mounted the same
13159filesystems, you can avoid these problems by using absolute paths.
13160Otherwise, it is simplest to set the working directory on both systems
13161to the directory in which the object file resides, and then to reference
13162the file by its name, without any path. For instance, a program
13163@file{prog.o} may reside in @file{@var{vxpath}/vw/demo/rdb} in VxWorks
13164and in @file{@var{hostpath}/vw/demo/rdb} on the host. To load this
13165program, type this on VxWorks:
104c1213 13166
474c8240 13167@smallexample
8e04817f 13168-> cd "@var{vxpath}/vw/demo/rdb"
474c8240 13169@end smallexample
104c1213 13170
8e04817f
AC
13171@noindent
13172Then, in @value{GDBN}, type:
104c1213 13173
474c8240 13174@smallexample
8e04817f
AC
13175(vxgdb) cd @var{hostpath}/vw/demo/rdb
13176(vxgdb) load prog.o
474c8240 13177@end smallexample
104c1213 13178
8e04817f 13179@value{GDBN} displays a response similar to this:
104c1213 13180
8e04817f
AC
13181@smallexample
13182Reading symbol data from wherever/vw/demo/rdb/prog.o... done.
13183@end smallexample
104c1213 13184
8e04817f
AC
13185You can also use the @code{load} command to reload an object module
13186after editing and recompiling the corresponding source file. Note that
13187this makes @value{GDBN} delete all currently-defined breakpoints,
13188auto-displays, and convenience variables, and to clear the value
13189history. (This is necessary in order to preserve the integrity of
13190debugger's data structures that reference the target system's symbol
13191table.)
104c1213 13192
8e04817f
AC
13193@node VxWorks Attach
13194@subsubsection Running tasks
104c1213
JM
13195
13196@cindex running VxWorks tasks
13197You can also attach to an existing task using the @code{attach} command as
13198follows:
13199
474c8240 13200@smallexample
104c1213 13201(vxgdb) attach @var{task}
474c8240 13202@end smallexample
104c1213
JM
13203
13204@noindent
13205where @var{task} is the VxWorks hexadecimal task ID. The task can be running
13206or suspended when you attach to it. Running tasks are suspended at
13207the time of attachment.
13208
6d2ebf8b 13209@node Embedded Processors
104c1213
JM
13210@section Embedded Processors
13211
13212This section goes into details specific to particular embedded
13213configurations.
13214
7d86b5d5 13215
104c1213 13216@menu
104c1213 13217* ARM:: ARM
172c2a43
KI
13218* H8/300:: Renesas H8/300
13219* H8/500:: Renesas H8/500
13220* M32R/D:: Renesas M32R/D
104c1213 13221* M68K:: Motorola M68K
104c1213 13222* MIPS Embedded:: MIPS Embedded
a37295f9 13223* OpenRISC 1000:: OpenRisc 1000
104c1213
JM
13224* PA:: HP PA Embedded
13225* PowerPC: PowerPC
172c2a43 13226* SH:: Renesas SH
104c1213
JM
13227* Sparclet:: Tsqware Sparclet
13228* Sparclite:: Fujitsu Sparclite
13229* ST2000:: Tandem ST2000
13230* Z8000:: Zilog Z8000
a64548ea
EZ
13231* AVR:: Atmel AVR
13232* CRIS:: CRIS
13233* Super-H:: Renesas Super-H
104c1213
JM
13234@end menu
13235
6d2ebf8b 13236@node ARM
104c1213
JM
13237@subsection ARM
13238
13239@table @code
13240
8e04817f
AC
13241@kindex target rdi
13242@item target rdi @var{dev}
13243ARM Angel monitor, via RDI library interface to ADP protocol. You may
13244use this target to communicate with both boards running the Angel
13245monitor, or with the EmbeddedICE JTAG debug device.
13246
13247@kindex target rdp
13248@item target rdp @var{dev}
13249ARM Demon monitor.
13250
13251@end table
13252
e2f4edfd
EZ
13253@value{GDBN} provides the following ARM-specific commands:
13254
13255@table @code
13256@item set arm disassembler
13257@kindex set arm
13258This commands selects from a list of disassembly styles. The
13259@code{"std"} style is the standard style.
13260
13261@item show arm disassembler
13262@kindex show arm
13263Show the current disassembly style.
13264
13265@item set arm apcs32
13266@cindex ARM 32-bit mode
13267This command toggles ARM operation mode between 32-bit and 26-bit.
13268
13269@item show arm apcs32
13270Display the current usage of the ARM 32-bit mode.
13271
13272@item set arm fpu @var{fputype}
13273This command sets the ARM floating-point unit (FPU) type. The
13274argument @var{fputype} can be one of these:
13275
13276@table @code
13277@item auto
13278Determine the FPU type by querying the OS ABI.
13279@item softfpa
13280Software FPU, with mixed-endian doubles on little-endian ARM
13281processors.
13282@item fpa
13283GCC-compiled FPA co-processor.
13284@item softvfp
13285Software FPU with pure-endian doubles.
13286@item vfp
13287VFP co-processor.
13288@end table
13289
13290@item show arm fpu
13291Show the current type of the FPU.
13292
13293@item set arm abi
13294This command forces @value{GDBN} to use the specified ABI.
13295
13296@item show arm abi
13297Show the currently used ABI.
13298
13299@item set debug arm
13300Toggle whether to display ARM-specific debugging messages from the ARM
13301target support subsystem.
13302
13303@item show debug arm
13304Show whether ARM-specific debugging messages are enabled.
13305@end table
13306
13307
8e04817f 13308@node H8/300
172c2a43 13309@subsection Renesas H8/300
8e04817f
AC
13310
13311@table @code
13312
13313@kindex target hms@r{, with H8/300}
13314@item target hms @var{dev}
172c2a43 13315A Renesas SH, H8/300, or H8/500 board, attached via serial line to your host.
8e04817f
AC
13316Use special commands @code{device} and @code{speed} to control the serial
13317line and the communications speed used.
13318
13319@kindex target e7000@r{, with H8/300}
13320@item target e7000 @var{dev}
172c2a43 13321E7000 emulator for Renesas H8 and SH.
8e04817f
AC
13322
13323@kindex target sh3@r{, with H8/300}
13324@kindex target sh3e@r{, with H8/300}
13325@item target sh3 @var{dev}
13326@itemx target sh3e @var{dev}
172c2a43 13327Renesas SH-3 and SH-3E target systems.
8e04817f
AC
13328
13329@end table
13330
13331@cindex download to H8/300 or H8/500
13332@cindex H8/300 or H8/500 download
172c2a43
KI
13333@cindex download to Renesas SH
13334@cindex Renesas SH download
13335When you select remote debugging to a Renesas SH, H8/300, or H8/500
13336board, the @code{load} command downloads your program to the Renesas
8e04817f
AC
13337board and also opens it as the current executable target for
13338@value{GDBN} on your host (like the @code{file} command).
13339
13340@value{GDBN} needs to know these things to talk to your
172c2a43 13341Renesas SH, H8/300, or H8/500:
8e04817f
AC
13342
13343@enumerate
13344@item
13345that you want to use @samp{target hms}, the remote debugging interface
172c2a43
KI
13346for Renesas microprocessors, or @samp{target e7000}, the in-circuit
13347emulator for the Renesas SH and the Renesas 300H. (@samp{target hms} is
13348the default when @value{GDBN} is configured specifically for the Renesas SH,
8e04817f
AC
13349H8/300, or H8/500.)
13350
13351@item
172c2a43 13352what serial device connects your host to your Renesas board (the first
8e04817f
AC
13353serial device available on your host is the default).
13354
13355@item
13356what speed to use over the serial device.
13357@end enumerate
13358
13359@menu
172c2a43
KI
13360* Renesas Boards:: Connecting to Renesas boards.
13361* Renesas ICE:: Using the E7000 In-Circuit Emulator.
13362* Renesas Special:: Special @value{GDBN} commands for Renesas micros.
8e04817f
AC
13363@end menu
13364
172c2a43
KI
13365@node Renesas Boards
13366@subsubsection Connecting to Renesas boards
8e04817f
AC
13367
13368@c only for Unix hosts
13369@kindex device
172c2a43 13370@cindex serial device, Renesas micros
8e04817f
AC
13371Use the special @code{@value{GDBN}} command @samp{device @var{port}} if you
13372need to explicitly set the serial device. The default @var{port} is the
13373first available port on your host. This is only necessary on Unix
13374hosts, where it is typically something like @file{/dev/ttya}.
13375
13376@kindex speed
172c2a43 13377@cindex serial line speed, Renesas micros
8e04817f
AC
13378@code{@value{GDBN}} has another special command to set the communications
13379speed: @samp{speed @var{bps}}. This command also is only used from Unix
13380hosts; on DOS hosts, set the line speed as usual from outside @value{GDBN} with
13381the DOS @code{mode} command (for instance,
13382@w{@kbd{mode com2:9600,n,8,1,p}} for a 9600@dmn{bps} connection).
13383
13384The @samp{device} and @samp{speed} commands are available only when you
172c2a43 13385use a Unix host to debug your Renesas microprocessor programs. If you
8e04817f
AC
13386use a DOS host,
13387@value{GDBN} depends on an auxiliary terminate-and-stay-resident program
13388called @code{asynctsr} to communicate with the development board
13389through a PC serial port. You must also use the DOS @code{mode} command
13390to set up the serial port on the DOS side.
13391
13392The following sample session illustrates the steps needed to start a
13393program under @value{GDBN} control on an H8/300. The example uses a
13394sample H8/300 program called @file{t.x}. The procedure is the same for
172c2a43 13395the Renesas SH and the H8/500.
8e04817f
AC
13396
13397First hook up your development board. In this example, we use a
13398board attached to serial port @code{COM2}; if you use a different serial
13399port, substitute its name in the argument of the @code{mode} command.
13400When you call @code{asynctsr}, the auxiliary comms program used by the
13401debugger, you give it just the numeric part of the serial port's name;
13402for example, @samp{asyncstr 2} below runs @code{asyncstr} on
13403@code{COM2}.
13404
474c8240 13405@smallexample
8e04817f
AC
13406C:\H8300\TEST> asynctsr 2
13407C:\H8300\TEST> mode com2:9600,n,8,1,p
13408
13409Resident portion of MODE loaded
13410
13411COM2: 9600, n, 8, 1, p
13412
474c8240 13413@end smallexample
8e04817f
AC
13414
13415@quotation
13416@emph{Warning:} We have noticed a bug in PC-NFS that conflicts with
13417@code{asynctsr}. If you also run PC-NFS on your DOS host, you may need to
13418disable it, or even boot without it, to use @code{asynctsr} to control
13419your development board.
13420@end quotation
13421
13422@kindex target hms@r{, and serial protocol}
13423Now that serial communications are set up, and the development board is
9c16f35a 13424connected, you can start up @value{GDBN}. Call @code{@value{GDBN}} with
8e04817f
AC
13425the name of your program as the argument. @code{@value{GDBN}} prompts
13426you, as usual, with the prompt @samp{(@value{GDBP})}. Use two special
13427commands to begin your debugging session: @samp{target hms} to specify
172c2a43 13428cross-debugging to the Renesas board, and the @code{load} command to
8e04817f
AC
13429download your program to the board. @code{load} displays the names of
13430the program's sections, and a @samp{*} for each 2K of data downloaded.
13431(If you want to refresh @value{GDBN} data on symbols or on the
13432executable file without downloading, use the @value{GDBN} commands
13433@code{file} or @code{symbol-file}. These commands, and @code{load}
13434itself, are described in @ref{Files,,Commands to specify files}.)
13435
13436@smallexample
13437(eg-C:\H8300\TEST) @value{GDBP} t.x
13438@value{GDBN} is free software and you are welcome to distribute copies
13439 of it under certain conditions; type "show copying" to see
13440 the conditions.
13441There is absolutely no warranty for @value{GDBN}; type "show warranty"
13442for details.
13443@value{GDBN} @value{GDBVN}, Copyright 1992 Free Software Foundation, Inc...
13444(@value{GDBP}) target hms
13445Connected to remote H8/300 HMS system.
13446(@value{GDBP}) load t.x
13447.text : 0x8000 .. 0xabde ***********
13448.data : 0xabde .. 0xad30 *
13449.stack : 0xf000 .. 0xf014 *
13450@end smallexample
13451
13452At this point, you're ready to run or debug your program. From here on,
13453you can use all the usual @value{GDBN} commands. The @code{break} command
13454sets breakpoints; the @code{run} command starts your program;
13455@code{print} or @code{x} display data; the @code{continue} command
13456resumes execution after stopping at a breakpoint. You can use the
13457@code{help} command at any time to find out more about @value{GDBN} commands.
13458
13459Remember, however, that @emph{operating system} facilities aren't
13460available on your development board; for example, if your program hangs,
13461you can't send an interrupt---but you can press the @sc{reset} switch!
13462
13463Use the @sc{reset} button on the development board
13464@itemize @bullet
13465@item
13466to interrupt your program (don't use @kbd{ctl-C} on the DOS host---it has
13467no way to pass an interrupt signal to the development board); and
13468
13469@item
13470to return to the @value{GDBN} command prompt after your program finishes
13471normally. The communications protocol provides no other way for @value{GDBN}
13472to detect program completion.
13473@end itemize
13474
13475In either case, @value{GDBN} sees the effect of a @sc{reset} on the
13476development board as a ``normal exit'' of your program.
13477
172c2a43 13478@node Renesas ICE
8e04817f
AC
13479@subsubsection Using the E7000 in-circuit emulator
13480
172c2a43 13481@kindex target e7000@r{, with Renesas ICE}
8e04817f 13482You can use the E7000 in-circuit emulator to develop code for either the
172c2a43 13483Renesas SH or the H8/300H. Use one of these forms of the @samp{target
8e04817f
AC
13484e7000} command to connect @value{GDBN} to your E7000:
13485
13486@table @code
13487@item target e7000 @var{port} @var{speed}
13488Use this form if your E7000 is connected to a serial port. The
13489@var{port} argument identifies what serial port to use (for example,
13490@samp{com2}). The third argument is the line speed in bits per second
13491(for example, @samp{9600}).
13492
13493@item target e7000 @var{hostname}
13494If your E7000 is installed as a host on a TCP/IP network, you can just
13495specify its hostname; @value{GDBN} uses @code{telnet} to connect.
13496@end table
13497
172c2a43
KI
13498@node Renesas Special
13499@subsubsection Special @value{GDBN} commands for Renesas micros
8e04817f
AC
13500
13501Some @value{GDBN} commands are available only for the H8/300:
13502
13503@table @code
13504
13505@kindex set machine
13506@kindex show machine
13507@item set machine h8300
13508@itemx set machine h8300h
13509Condition @value{GDBN} for one of the two variants of the H8/300
13510architecture with @samp{set machine}. You can use @samp{show machine}
13511to check which variant is currently in effect.
104c1213
JM
13512
13513@end table
13514
8e04817f
AC
13515@node H8/500
13516@subsection H8/500
104c1213
JM
13517
13518@table @code
13519
8e04817f
AC
13520@kindex set memory @var{mod}
13521@cindex memory models, H8/500
13522@item set memory @var{mod}
13523@itemx show memory
13524Specify which H8/500 memory model (@var{mod}) you are using with
13525@samp{set memory}; check which memory model is in effect with @samp{show
13526memory}. The accepted values for @var{mod} are @code{small},
13527@code{big}, @code{medium}, and @code{compact}.
104c1213 13528
8e04817f 13529@end table
104c1213 13530
8e04817f 13531@node M32R/D
172c2a43 13532@subsection Renesas M32R/D
8e04817f
AC
13533
13534@table @code
13535
13536@kindex target m32r
13537@item target m32r @var{dev}
172c2a43 13538Renesas M32R/D ROM monitor.
8e04817f 13539
fb3e19c0
KI
13540@kindex target m32rsdi
13541@item target m32rsdi @var{dev}
13542Renesas M32R SDI server, connected via parallel port to the board.
13543
8e04817f
AC
13544@end table
13545
13546@node M68K
13547@subsection M68k
13548
13549The Motorola m68k configuration includes ColdFire support, and
13550target command for the following ROM monitors.
13551
13552@table @code
13553
13554@kindex target abug
13555@item target abug @var{dev}
13556ABug ROM monitor for M68K.
13557
13558@kindex target cpu32bug
13559@item target cpu32bug @var{dev}
13560CPU32BUG monitor, running on a CPU32 (M68K) board.
13561
13562@kindex target dbug
13563@item target dbug @var{dev}
13564dBUG ROM monitor for Motorola ColdFire.
13565
13566@kindex target est
13567@item target est @var{dev}
13568EST-300 ICE monitor, running on a CPU32 (M68K) board.
13569
13570@kindex target rom68k
13571@item target rom68k @var{dev}
13572ROM 68K monitor, running on an M68K IDP board.
13573
13574@end table
13575
8e04817f
AC
13576@table @code
13577
13578@kindex target rombug
13579@item target rombug @var{dev}
13580ROMBUG ROM monitor for OS/9000.
13581
13582@end table
13583
8e04817f
AC
13584@node MIPS Embedded
13585@subsection MIPS Embedded
13586
13587@cindex MIPS boards
13588@value{GDBN} can use the MIPS remote debugging protocol to talk to a
13589MIPS board attached to a serial line. This is available when
13590you configure @value{GDBN} with @samp{--target=mips-idt-ecoff}.
104c1213 13591
8e04817f
AC
13592@need 1000
13593Use these @value{GDBN} commands to specify the connection to your target board:
104c1213 13594
8e04817f
AC
13595@table @code
13596@item target mips @var{port}
13597@kindex target mips @var{port}
13598To run a program on the board, start up @code{@value{GDBP}} with the
13599name of your program as the argument. To connect to the board, use the
13600command @samp{target mips @var{port}}, where @var{port} is the name of
13601the serial port connected to the board. If the program has not already
13602been downloaded to the board, you may use the @code{load} command to
13603download it. You can then use all the usual @value{GDBN} commands.
104c1213 13604
8e04817f
AC
13605For example, this sequence connects to the target board through a serial
13606port, and loads and runs a program called @var{prog} through the
13607debugger:
104c1213 13608
474c8240 13609@smallexample
8e04817f
AC
13610host$ @value{GDBP} @var{prog}
13611@value{GDBN} is free software and @dots{}
13612(@value{GDBP}) target mips /dev/ttyb
13613(@value{GDBP}) load @var{prog}
13614(@value{GDBP}) run
474c8240 13615@end smallexample
104c1213 13616
8e04817f
AC
13617@item target mips @var{hostname}:@var{portnumber}
13618On some @value{GDBN} host configurations, you can specify a TCP
13619connection (for instance, to a serial line managed by a terminal
13620concentrator) instead of a serial port, using the syntax
13621@samp{@var{hostname}:@var{portnumber}}.
104c1213 13622
8e04817f
AC
13623@item target pmon @var{port}
13624@kindex target pmon @var{port}
13625PMON ROM monitor.
104c1213 13626
8e04817f
AC
13627@item target ddb @var{port}
13628@kindex target ddb @var{port}
13629NEC's DDB variant of PMON for Vr4300.
104c1213 13630
8e04817f
AC
13631@item target lsi @var{port}
13632@kindex target lsi @var{port}
13633LSI variant of PMON.
104c1213 13634
8e04817f
AC
13635@kindex target r3900
13636@item target r3900 @var{dev}
13637Densan DVE-R3900 ROM monitor for Toshiba R3900 Mips.
104c1213 13638
8e04817f
AC
13639@kindex target array
13640@item target array @var{dev}
13641Array Tech LSI33K RAID controller board.
104c1213 13642
8e04817f 13643@end table
104c1213 13644
104c1213 13645
8e04817f
AC
13646@noindent
13647@value{GDBN} also supports these special commands for MIPS targets:
104c1213 13648
8e04817f 13649@table @code
8e04817f
AC
13650@item set mipsfpu double
13651@itemx set mipsfpu single
13652@itemx set mipsfpu none
a64548ea 13653@itemx set mipsfpu auto
8e04817f
AC
13654@itemx show mipsfpu
13655@kindex set mipsfpu
13656@kindex show mipsfpu
13657@cindex MIPS remote floating point
13658@cindex floating point, MIPS remote
13659If your target board does not support the MIPS floating point
13660coprocessor, you should use the command @samp{set mipsfpu none} (if you
13661need this, you may wish to put the command in your @value{GDBN} init
13662file). This tells @value{GDBN} how to find the return value of
13663functions which return floating point values. It also allows
13664@value{GDBN} to avoid saving the floating point registers when calling
13665functions on the board. If you are using a floating point coprocessor
13666with only single precision floating point support, as on the @sc{r4650}
13667processor, use the command @samp{set mipsfpu single}. The default
13668double precision floating point coprocessor may be selected using
13669@samp{set mipsfpu double}.
104c1213 13670
8e04817f
AC
13671In previous versions the only choices were double precision or no
13672floating point, so @samp{set mipsfpu on} will select double precision
13673and @samp{set mipsfpu off} will select no floating point.
104c1213 13674
8e04817f
AC
13675As usual, you can inquire about the @code{mipsfpu} variable with
13676@samp{show mipsfpu}.
104c1213 13677
8e04817f
AC
13678@item set timeout @var{seconds}
13679@itemx set retransmit-timeout @var{seconds}
13680@itemx show timeout
13681@itemx show retransmit-timeout
13682@cindex @code{timeout}, MIPS protocol
13683@cindex @code{retransmit-timeout}, MIPS protocol
13684@kindex set timeout
13685@kindex show timeout
13686@kindex set retransmit-timeout
13687@kindex show retransmit-timeout
13688You can control the timeout used while waiting for a packet, in the MIPS
13689remote protocol, with the @code{set timeout @var{seconds}} command. The
13690default is 5 seconds. Similarly, you can control the timeout used while
13691waiting for an acknowledgement of a packet with the @code{set
13692retransmit-timeout @var{seconds}} command. The default is 3 seconds.
13693You can inspect both values with @code{show timeout} and @code{show
13694retransmit-timeout}. (These commands are @emph{only} available when
13695@value{GDBN} is configured for @samp{--target=mips-idt-ecoff}.)
104c1213 13696
8e04817f
AC
13697The timeout set by @code{set timeout} does not apply when @value{GDBN}
13698is waiting for your program to stop. In that case, @value{GDBN} waits
13699forever because it has no way of knowing how long the program is going
13700to run before stopping.
13701@end table
104c1213 13702
a37295f9
MM
13703@node OpenRISC 1000
13704@subsection OpenRISC 1000
13705@cindex OpenRISC 1000
13706
13707@cindex or1k boards
13708See OR1k Architecture document (@uref{www.opencores.org}) for more information
13709about platform and commands.
13710
13711@table @code
13712
13713@kindex target jtag
13714@item target jtag jtag://@var{host}:@var{port}
13715
13716Connects to remote JTAG server.
13717JTAG remote server can be either an or1ksim or JTAG server,
13718connected via parallel port to the board.
13719
13720Example: @code{target jtag jtag://localhost:9999}
13721
13722@kindex or1ksim
13723@item or1ksim @var{command}
13724If connected to @code{or1ksim} OpenRISC 1000 Architectural
13725Simulator, proprietary commands can be executed.
13726
13727@kindex info or1k spr
13728@item info or1k spr
13729Displays spr groups.
13730
13731@item info or1k spr @var{group}
13732@itemx info or1k spr @var{groupno}
13733Displays register names in selected group.
13734
13735@item info or1k spr @var{group} @var{register}
13736@itemx info or1k spr @var{register}
13737@itemx info or1k spr @var{groupno} @var{registerno}
13738@itemx info or1k spr @var{registerno}
13739Shows information about specified spr register.
13740
13741@kindex spr
13742@item spr @var{group} @var{register} @var{value}
13743@itemx spr @var{register @var{value}}
13744@itemx spr @var{groupno} @var{registerno @var{value}}
13745@itemx spr @var{registerno @var{value}}
13746Writes @var{value} to specified spr register.
13747@end table
13748
13749Some implementations of OpenRISC 1000 Architecture also have hardware trace.
13750It is very similar to @value{GDBN} trace, except it does not interfere with normal
13751program execution and is thus much faster. Hardware breakpoints/watchpoint
13752triggers can be set using:
13753@table @code
13754@item $LEA/$LDATA
13755Load effective address/data
13756@item $SEA/$SDATA
13757Store effective address/data
13758@item $AEA/$ADATA
13759Access effective address ($SEA or $LEA) or data ($SDATA/$LDATA)
13760@item $FETCH
13761Fetch data
13762@end table
13763
13764When triggered, it can capture low level data, like: @code{PC}, @code{LSEA},
13765@code{LDATA}, @code{SDATA}, @code{READSPR}, @code{WRITESPR}, @code{INSTR}.
13766
13767@code{htrace} commands:
13768@cindex OpenRISC 1000 htrace
13769@table @code
13770@kindex hwatch
13771@item hwatch @var{conditional}
13772Set hardware watchpoint on combination of Load/Store Effecive Address(es)
13773or Data. For example:
13774
13775@code{hwatch ($LEA == my_var) && ($LDATA < 50) || ($SEA == my_var) && ($SDATA >= 50)}
13776
13777@code{hwatch ($LEA == my_var) && ($LDATA < 50) || ($SEA == my_var) && ($SDATA >= 50)}
13778
4644b6e3 13779@kindex htrace
a37295f9
MM
13780@item htrace info
13781Display information about current HW trace configuration.
13782
a37295f9
MM
13783@item htrace trigger @var{conditional}
13784Set starting criteria for HW trace.
13785
a37295f9
MM
13786@item htrace qualifier @var{conditional}
13787Set acquisition qualifier for HW trace.
13788
a37295f9
MM
13789@item htrace stop @var{conditional}
13790Set HW trace stopping criteria.
13791
f153cc92 13792@item htrace record [@var{data}]*
a37295f9
MM
13793Selects the data to be recorded, when qualifier is met and HW trace was
13794triggered.
13795
a37295f9 13796@item htrace enable
a37295f9
MM
13797@itemx htrace disable
13798Enables/disables the HW trace.
13799
f153cc92 13800@item htrace rewind [@var{filename}]
a37295f9
MM
13801Clears currently recorded trace data.
13802
13803If filename is specified, new trace file is made and any newly collected data
13804will be written there.
13805
f153cc92 13806@item htrace print [@var{start} [@var{len}]]
a37295f9
MM
13807Prints trace buffer, using current record configuration.
13808
a37295f9
MM
13809@item htrace mode continuous
13810Set continuous trace mode.
13811
a37295f9
MM
13812@item htrace mode suspend
13813Set suspend trace mode.
13814
13815@end table
13816
8e04817f
AC
13817@node PowerPC
13818@subsection PowerPC
104c1213
JM
13819
13820@table @code
104c1213 13821
8e04817f
AC
13822@kindex target dink32
13823@item target dink32 @var{dev}
13824DINK32 ROM monitor.
104c1213 13825
8e04817f
AC
13826@kindex target ppcbug
13827@item target ppcbug @var{dev}
13828@kindex target ppcbug1
13829@item target ppcbug1 @var{dev}
13830PPCBUG ROM monitor for PowerPC.
104c1213 13831
8e04817f
AC
13832@kindex target sds
13833@item target sds @var{dev}
13834SDS monitor, running on a PowerPC board (such as Motorola's ADS).
13835
13836@end table
13837
13838@node PA
13839@subsection HP PA Embedded
104c1213
JM
13840
13841@table @code
13842
8e04817f
AC
13843@kindex target op50n
13844@item target op50n @var{dev}
13845OP50N monitor, running on an OKI HPPA board.
13846
13847@kindex target w89k
13848@item target w89k @var{dev}
13849W89K monitor, running on a Winbond HPPA board.
104c1213
JM
13850
13851@end table
13852
8e04817f 13853@node SH
172c2a43 13854@subsection Renesas SH
104c1213
JM
13855
13856@table @code
13857
172c2a43 13858@kindex target hms@r{, with Renesas SH}
8e04817f 13859@item target hms @var{dev}
172c2a43 13860A Renesas SH board attached via serial line to your host. Use special
8e04817f
AC
13861commands @code{device} and @code{speed} to control the serial line and
13862the communications speed used.
104c1213 13863
172c2a43 13864@kindex target e7000@r{, with Renesas SH}
8e04817f 13865@item target e7000 @var{dev}
172c2a43 13866E7000 emulator for Renesas SH.
104c1213 13867
8e04817f
AC
13868@kindex target sh3@r{, with SH}
13869@kindex target sh3e@r{, with SH}
13870@item target sh3 @var{dev}
13871@item target sh3e @var{dev}
172c2a43 13872Renesas SH-3 and SH-3E target systems.
104c1213 13873
8e04817f 13874@end table
104c1213 13875
8e04817f
AC
13876@node Sparclet
13877@subsection Tsqware Sparclet
104c1213 13878
8e04817f
AC
13879@cindex Sparclet
13880
13881@value{GDBN} enables developers to debug tasks running on
13882Sparclet targets from a Unix host.
13883@value{GDBN} uses code that runs on
13884both the Unix host and on the Sparclet target. The program
13885@code{@value{GDBP}} is installed and executed on the Unix host.
104c1213 13886
8e04817f
AC
13887@table @code
13888@item remotetimeout @var{args}
13889@kindex remotetimeout
13890@value{GDBN} supports the option @code{remotetimeout}.
13891This option is set by the user, and @var{args} represents the number of
13892seconds @value{GDBN} waits for responses.
104c1213
JM
13893@end table
13894
8e04817f
AC
13895@cindex compiling, on Sparclet
13896When compiling for debugging, include the options @samp{-g} to get debug
13897information and @samp{-Ttext} to relocate the program to where you wish to
13898load it on the target. You may also want to add the options @samp{-n} or
13899@samp{-N} in order to reduce the size of the sections. Example:
104c1213 13900
474c8240 13901@smallexample
8e04817f 13902sparclet-aout-gcc prog.c -Ttext 0x12010000 -g -o prog -N
474c8240 13903@end smallexample
104c1213 13904
8e04817f 13905You can use @code{objdump} to verify that the addresses are what you intended:
104c1213 13906
474c8240 13907@smallexample
8e04817f 13908sparclet-aout-objdump --headers --syms prog
474c8240 13909@end smallexample
104c1213 13910
8e04817f
AC
13911@cindex running, on Sparclet
13912Once you have set
13913your Unix execution search path to find @value{GDBN}, you are ready to
13914run @value{GDBN}. From your Unix host, run @code{@value{GDBP}}
13915(or @code{sparclet-aout-gdb}, depending on your installation).
104c1213 13916
8e04817f
AC
13917@value{GDBN} comes up showing the prompt:
13918
474c8240 13919@smallexample
8e04817f 13920(gdbslet)
474c8240 13921@end smallexample
104c1213
JM
13922
13923@menu
8e04817f
AC
13924* Sparclet File:: Setting the file to debug
13925* Sparclet Connection:: Connecting to Sparclet
13926* Sparclet Download:: Sparclet download
13927* Sparclet Execution:: Running and debugging
104c1213
JM
13928@end menu
13929
8e04817f
AC
13930@node Sparclet File
13931@subsubsection Setting file to debug
104c1213 13932
8e04817f 13933The @value{GDBN} command @code{file} lets you choose with program to debug.
104c1213 13934
474c8240 13935@smallexample
8e04817f 13936(gdbslet) file prog
474c8240 13937@end smallexample
104c1213 13938
8e04817f
AC
13939@need 1000
13940@value{GDBN} then attempts to read the symbol table of @file{prog}.
13941@value{GDBN} locates
13942the file by searching the directories listed in the command search
13943path.
13944If the file was compiled with debug information (option "-g"), source
13945files will be searched as well.
13946@value{GDBN} locates
13947the source files by searching the directories listed in the directory search
13948path (@pxref{Environment, ,Your program's environment}).
13949If it fails
13950to find a file, it displays a message such as:
104c1213 13951
474c8240 13952@smallexample
8e04817f 13953prog: No such file or directory.
474c8240 13954@end smallexample
104c1213 13955
8e04817f
AC
13956When this happens, add the appropriate directories to the search paths with
13957the @value{GDBN} commands @code{path} and @code{dir}, and execute the
13958@code{target} command again.
104c1213 13959
8e04817f
AC
13960@node Sparclet Connection
13961@subsubsection Connecting to Sparclet
104c1213 13962
8e04817f
AC
13963The @value{GDBN} command @code{target} lets you connect to a Sparclet target.
13964To connect to a target on serial port ``@code{ttya}'', type:
104c1213 13965
474c8240 13966@smallexample
8e04817f
AC
13967(gdbslet) target sparclet /dev/ttya
13968Remote target sparclet connected to /dev/ttya
13969main () at ../prog.c:3
474c8240 13970@end smallexample
104c1213 13971
8e04817f
AC
13972@need 750
13973@value{GDBN} displays messages like these:
104c1213 13974
474c8240 13975@smallexample
8e04817f 13976Connected to ttya.
474c8240 13977@end smallexample
104c1213 13978
8e04817f
AC
13979@node Sparclet Download
13980@subsubsection Sparclet download
104c1213 13981
8e04817f
AC
13982@cindex download to Sparclet
13983Once connected to the Sparclet target,
13984you can use the @value{GDBN}
13985@code{load} command to download the file from the host to the target.
13986The file name and load offset should be given as arguments to the @code{load}
13987command.
13988Since the file format is aout, the program must be loaded to the starting
13989address. You can use @code{objdump} to find out what this value is. The load
13990offset is an offset which is added to the VMA (virtual memory address)
13991of each of the file's sections.
13992For instance, if the program
13993@file{prog} was linked to text address 0x1201000, with data at 0x12010160
13994and bss at 0x12010170, in @value{GDBN}, type:
104c1213 13995
474c8240 13996@smallexample
8e04817f
AC
13997(gdbslet) load prog 0x12010000
13998Loading section .text, size 0xdb0 vma 0x12010000
474c8240 13999@end smallexample
104c1213 14000
8e04817f
AC
14001If the code is loaded at a different address then what the program was linked
14002to, you may need to use the @code{section} and @code{add-symbol-file} commands
14003to tell @value{GDBN} where to map the symbol table.
14004
14005@node Sparclet Execution
14006@subsubsection Running and debugging
14007
14008@cindex running and debugging Sparclet programs
14009You can now begin debugging the task using @value{GDBN}'s execution control
14010commands, @code{b}, @code{step}, @code{run}, etc. See the @value{GDBN}
14011manual for the list of commands.
14012
474c8240 14013@smallexample
8e04817f
AC
14014(gdbslet) b main
14015Breakpoint 1 at 0x12010000: file prog.c, line 3.
14016(gdbslet) run
14017Starting program: prog
14018Breakpoint 1, main (argc=1, argv=0xeffff21c) at prog.c:3
140193 char *symarg = 0;
14020(gdbslet) step
140214 char *execarg = "hello!";
14022(gdbslet)
474c8240 14023@end smallexample
8e04817f
AC
14024
14025@node Sparclite
14026@subsection Fujitsu Sparclite
104c1213
JM
14027
14028@table @code
14029
8e04817f
AC
14030@kindex target sparclite
14031@item target sparclite @var{dev}
14032Fujitsu sparclite boards, used only for the purpose of loading.
14033You must use an additional command to debug the program.
14034For example: target remote @var{dev} using @value{GDBN} standard
14035remote protocol.
104c1213
JM
14036
14037@end table
14038
8e04817f
AC
14039@node ST2000
14040@subsection Tandem ST2000
104c1213 14041
8e04817f
AC
14042@value{GDBN} may be used with a Tandem ST2000 phone switch, running Tandem's
14043STDBUG protocol.
104c1213 14044
8e04817f
AC
14045To connect your ST2000 to the host system, see the manufacturer's
14046manual. Once the ST2000 is physically attached, you can run:
104c1213 14047
474c8240 14048@smallexample
8e04817f 14049target st2000 @var{dev} @var{speed}
474c8240 14050@end smallexample
104c1213 14051
8e04817f
AC
14052@noindent
14053to establish it as your debugging environment. @var{dev} is normally
14054the name of a serial device, such as @file{/dev/ttya}, connected to the
14055ST2000 via a serial line. You can instead specify @var{dev} as a TCP
14056connection (for example, to a serial line attached via a terminal
14057concentrator) using the syntax @code{@var{hostname}:@var{portnumber}}.
104c1213 14058
8e04817f
AC
14059The @code{load} and @code{attach} commands are @emph{not} defined for
14060this target; you must load your program into the ST2000 as you normally
14061would for standalone operation. @value{GDBN} reads debugging information
14062(such as symbols) from a separate, debugging version of the program
14063available on your host computer.
14064@c FIXME!! This is terribly vague; what little content is here is
14065@c basically hearsay.
104c1213 14066
8e04817f
AC
14067@cindex ST2000 auxiliary commands
14068These auxiliary @value{GDBN} commands are available to help you with the ST2000
14069environment:
104c1213 14070
8e04817f
AC
14071@table @code
14072@item st2000 @var{command}
14073@kindex st2000 @var{cmd}
14074@cindex STDBUG commands (ST2000)
14075@cindex commands to STDBUG (ST2000)
14076Send a @var{command} to the STDBUG monitor. See the manufacturer's
14077manual for available commands.
104c1213 14078
8e04817f
AC
14079@item connect
14080@cindex connect (to STDBUG)
14081Connect the controlling terminal to the STDBUG command monitor. When
14082you are done interacting with STDBUG, typing either of two character
14083sequences gets you back to the @value{GDBN} command prompt:
14084@kbd{@key{RET}~.} (Return, followed by tilde and period) or
14085@kbd{@key{RET}~@key{C-d}} (Return, followed by tilde and control-D).
104c1213
JM
14086@end table
14087
8e04817f
AC
14088@node Z8000
14089@subsection Zilog Z8000
104c1213 14090
8e04817f
AC
14091@cindex Z8000
14092@cindex simulator, Z8000
14093@cindex Zilog Z8000 simulator
104c1213 14094
8e04817f
AC
14095When configured for debugging Zilog Z8000 targets, @value{GDBN} includes
14096a Z8000 simulator.
14097
14098For the Z8000 family, @samp{target sim} simulates either the Z8002 (the
14099unsegmented variant of the Z8000 architecture) or the Z8001 (the
14100segmented variant). The simulator recognizes which architecture is
14101appropriate by inspecting the object code.
104c1213 14102
8e04817f
AC
14103@table @code
14104@item target sim @var{args}
14105@kindex sim
14106@kindex target sim@r{, with Z8000}
14107Debug programs on a simulated CPU. If the simulator supports setup
14108options, specify them via @var{args}.
104c1213
JM
14109@end table
14110
8e04817f
AC
14111@noindent
14112After specifying this target, you can debug programs for the simulated
14113CPU in the same style as programs for your host computer; use the
14114@code{file} command to load a new program image, the @code{run} command
14115to run your program, and so on.
14116
14117As well as making available all the usual machine registers
14118(@pxref{Registers, ,Registers}), the Z8000 simulator provides three
14119additional items of information as specially named registers:
104c1213
JM
14120
14121@table @code
14122
8e04817f
AC
14123@item cycles
14124Counts clock-ticks in the simulator.
104c1213 14125
8e04817f
AC
14126@item insts
14127Counts instructions run in the simulator.
104c1213 14128
8e04817f
AC
14129@item time
14130Execution time in 60ths of a second.
104c1213 14131
8e04817f 14132@end table
104c1213 14133
8e04817f
AC
14134You can refer to these values in @value{GDBN} expressions with the usual
14135conventions; for example, @w{@samp{b fputc if $cycles>5000}} sets a
14136conditional breakpoint that suspends only after at least 5000
14137simulated clock ticks.
104c1213 14138
a64548ea
EZ
14139@node AVR
14140@subsection Atmel AVR
14141@cindex AVR
14142
14143When configured for debugging the Atmel AVR, @value{GDBN} supports the
14144following AVR-specific commands:
14145
14146@table @code
14147@item info io_registers
14148@kindex info io_registers@r{, AVR}
14149@cindex I/O registers (Atmel AVR)
14150This command displays information about the AVR I/O registers. For
14151each register, @value{GDBN} prints its number and value.
14152@end table
14153
14154@node CRIS
14155@subsection CRIS
14156@cindex CRIS
14157
14158When configured for debugging CRIS, @value{GDBN} provides the
14159following CRIS-specific commands:
14160
14161@table @code
14162@item set cris-version @var{ver}
14163@cindex CRIS version
14164Set the current CRIS version to @var{ver}. The CRIS version affects
14165register names and sizes. This command is useful in case
14166autodetection of the CRIS version fails.
14167
14168@item show cris-version
14169Show the current CRIS version.
14170
14171@item set cris-dwarf2-cfi
14172@cindex DWARF-2 CFI and CRIS
14173Set the usage of DWARF-2 CFI for CRIS debugging. The default is off
14174if using @code{gcc-cris} whose version is below @code{R59}, otherwise
14175on.
14176
14177@item show cris-dwarf2-cfi
14178Show the current state of using DWARF-2 CFI.
14179@end table
14180
14181@node Super-H
14182@subsection Renesas Super-H
14183@cindex Super-H
14184
14185For the Renesas Super-H processor, @value{GDBN} provides these
14186commands:
14187
14188@table @code
14189@item regs
14190@kindex regs@r{, Super-H}
14191Show the values of all Super-H registers.
14192@end table
14193
14194
8e04817f
AC
14195@node Architectures
14196@section Architectures
104c1213 14197
8e04817f
AC
14198This section describes characteristics of architectures that affect
14199all uses of @value{GDBN} with the architecture, both native and cross.
104c1213 14200
8e04817f 14201@menu
9c16f35a 14202* i386::
8e04817f
AC
14203* A29K::
14204* Alpha::
14205* MIPS::
a64548ea 14206* HPPA:: HP PA architecture
8e04817f 14207@end menu
104c1213 14208
9c16f35a
EZ
14209@node i386
14210@subsection x86 Architecture-specific issues.
14211
14212@table @code
14213@item set struct-convention @var{mode}
14214@kindex set struct-convention
14215@cindex struct return convention
14216@cindex struct/union returned in registers
14217Set the convention used by the inferior to return @code{struct}s and
14218@code{union}s from functions to @var{mode}. Possible values of
14219@var{mode} are @code{"pcc"}, @code{"reg"}, and @code{"default"} (the
14220default). @code{"default"} or @code{"pcc"} means that @code{struct}s
14221are returned on the stack, while @code{"reg"} means that a
14222@code{struct} or a @code{union} whose size is 1, 2, 4, or 8 bytes will
14223be returned in a register.
14224
14225@item show struct-convention
14226@kindex show struct-convention
14227Show the current setting of the convention to return @code{struct}s
14228from functions.
14229@end table
14230
8e04817f
AC
14231@node A29K
14232@subsection A29K
104c1213
JM
14233
14234@table @code
104c1213 14235
8e04817f
AC
14236@kindex set rstack_high_address
14237@cindex AMD 29K register stack
14238@cindex register stack, AMD29K
14239@item set rstack_high_address @var{address}
14240On AMD 29000 family processors, registers are saved in a separate
14241@dfn{register stack}. There is no way for @value{GDBN} to determine the
14242extent of this stack. Normally, @value{GDBN} just assumes that the
14243stack is ``large enough''. This may result in @value{GDBN} referencing
14244memory locations that do not exist. If necessary, you can get around
14245this problem by specifying the ending address of the register stack with
14246the @code{set rstack_high_address} command. The argument should be an
14247address, which you probably want to precede with @samp{0x} to specify in
14248hexadecimal.
104c1213 14249
8e04817f
AC
14250@kindex show rstack_high_address
14251@item show rstack_high_address
14252Display the current limit of the register stack, on AMD 29000 family
14253processors.
104c1213 14254
8e04817f 14255@end table
104c1213 14256
8e04817f
AC
14257@node Alpha
14258@subsection Alpha
104c1213 14259
8e04817f 14260See the following section.
104c1213 14261
8e04817f
AC
14262@node MIPS
14263@subsection MIPS
104c1213 14264
8e04817f
AC
14265@cindex stack on Alpha
14266@cindex stack on MIPS
14267@cindex Alpha stack
14268@cindex MIPS stack
14269Alpha- and MIPS-based computers use an unusual stack frame, which
14270sometimes requires @value{GDBN} to search backward in the object code to
14271find the beginning of a function.
104c1213 14272
8e04817f
AC
14273@cindex response time, MIPS debugging
14274To improve response time (especially for embedded applications, where
14275@value{GDBN} may be restricted to a slow serial line for this search)
14276you may want to limit the size of this search, using one of these
14277commands:
104c1213 14278
8e04817f
AC
14279@table @code
14280@cindex @code{heuristic-fence-post} (Alpha, MIPS)
14281@item set heuristic-fence-post @var{limit}
14282Restrict @value{GDBN} to examining at most @var{limit} bytes in its
14283search for the beginning of a function. A value of @var{0} (the
14284default) means there is no limit. However, except for @var{0}, the
14285larger the limit the more bytes @code{heuristic-fence-post} must search
e2f4edfd
EZ
14286and therefore the longer it takes to run. You should only need to use
14287this command when debugging a stripped executable.
104c1213 14288
8e04817f
AC
14289@item show heuristic-fence-post
14290Display the current limit.
14291@end table
104c1213
JM
14292
14293@noindent
8e04817f
AC
14294These commands are available @emph{only} when @value{GDBN} is configured
14295for debugging programs on Alpha or MIPS processors.
104c1213 14296
a64548ea
EZ
14297Several MIPS-specific commands are available when debugging MIPS
14298programs:
14299
14300@table @code
14301@item set mips saved-gpreg-size @var{size}
14302@kindex set mips saved-gpreg-size
14303@cindex MIPS GP register size on stack
14304Set the size of MIPS general-purpose registers saved on the stack.
14305The argument @var{size} can be one of the following:
14306
14307@table @samp
14308@item 32
1430932-bit GP registers
14310@item 64
1431164-bit GP registers
14312@item auto
14313Use the target's default setting or autodetect the saved size from the
14314information contained in the executable. This is the default
14315@end table
14316
14317@item show mips saved-gpreg-size
14318@kindex show mips saved-gpreg-size
14319Show the current size of MIPS GP registers on the stack.
14320
14321@item set mips stack-arg-size @var{size}
14322@kindex set mips stack-arg-size
14323@cindex MIPS stack space for arguments
14324Set the amount of stack space reserved for arguments to functions.
14325The argument can be one of @code{"32"}, @code{"64"} or @code{"auto"}
14326(the default).
14327
14328@item set mips abi @var{arg}
14329@kindex set mips abi
14330@cindex set ABI for MIPS
14331Tell @value{GDBN} which MIPS ABI is used by the inferior. Possible
14332values of @var{arg} are:
14333
14334@table @samp
14335@item auto
14336The default ABI associated with the current binary (this is the
14337default).
14338@item o32
14339@item o64
14340@item n32
14341@item n64
14342@item eabi32
14343@item eabi64
14344@item auto
14345@end table
14346
14347@item show mips abi
14348@kindex show mips abi
14349Show the MIPS ABI used by @value{GDBN} to debug the inferior.
14350
14351@item set mipsfpu
14352@itemx show mipsfpu
14353@xref{MIPS Embedded, set mipsfpu}.
14354
14355@item set mips mask-address @var{arg}
14356@kindex set mips mask-address
14357@cindex MIPS addresses, masking
14358This command determines whether the most-significant 32 bits of 64-bit
14359MIPS addresses are masked off. The argument @var{arg} can be
14360@samp{on}, @samp{off}, or @samp{auto}. The latter is the default
14361setting, which lets @value{GDBN} determine the correct value.
14362
14363@item show mips mask-address
14364@kindex show mips mask-address
14365Show whether the upper 32 bits of MIPS addresses are masked off or
14366not.
14367
14368@item set remote-mips64-transfers-32bit-regs
14369@kindex set remote-mips64-transfers-32bit-regs
14370This command controls compatibility with 64-bit MIPS targets that
14371transfer data in 32-bit quantities. If you have an old MIPS 64 target
14372that transfers 32 bits for some registers, like @sc{sr} and @sc{fsr},
14373and 64 bits for other registers, set this option to @samp{on}.
14374
14375@item show remote-mips64-transfers-32bit-regs
14376@kindex show remote-mips64-transfers-32bit-regs
14377Show the current setting of compatibility with older MIPS 64 targets.
14378
14379@item set debug mips
14380@kindex set debug mips
14381This command turns on and off debugging messages for the MIPS-specific
14382target code in @value{GDBN}.
14383
14384@item show debug mips
14385@kindex show debug mips
14386Show the current setting of MIPS debugging messages.
14387@end table
14388
14389
14390@node HPPA
14391@subsection HPPA
14392@cindex HPPA support
14393
14394When @value{GDBN} is debugging te HP PA architecture, it provides the
14395following special commands:
14396
14397@table @code
14398@item set debug hppa
14399@kindex set debug hppa
14400THis command determines whether HPPA architecture specific debugging
14401messages are to be displayed.
14402
14403@item show debug hppa
14404Show whether HPPA debugging messages are displayed.
14405
14406@item maint print unwind @var{address}
14407@kindex maint print unwind@r{, HPPA}
14408This command displays the contents of the unwind table entry at the
14409given @var{address}.
14410
14411@end table
14412
104c1213 14413
8e04817f
AC
14414@node Controlling GDB
14415@chapter Controlling @value{GDBN}
14416
14417You can alter the way @value{GDBN} interacts with you by using the
14418@code{set} command. For commands controlling how @value{GDBN} displays
14419data, see @ref{Print Settings, ,Print settings}. Other settings are
14420described here.
14421
14422@menu
14423* Prompt:: Prompt
14424* Editing:: Command editing
14425* History:: Command history
14426* Screen Size:: Screen size
14427* Numbers:: Numbers
1e698235 14428* ABI:: Configuring the current ABI
8e04817f
AC
14429* Messages/Warnings:: Optional warnings and messages
14430* Debugging Output:: Optional messages about internal happenings
14431@end menu
14432
14433@node Prompt
14434@section Prompt
104c1213 14435
8e04817f 14436@cindex prompt
104c1213 14437
8e04817f
AC
14438@value{GDBN} indicates its readiness to read a command by printing a string
14439called the @dfn{prompt}. This string is normally @samp{(@value{GDBP})}. You
14440can change the prompt string with the @code{set prompt} command. For
14441instance, when debugging @value{GDBN} with @value{GDBN}, it is useful to change
14442the prompt in one of the @value{GDBN} sessions so that you can always tell
14443which one you are talking to.
104c1213 14444
8e04817f
AC
14445@emph{Note:} @code{set prompt} does not add a space for you after the
14446prompt you set. This allows you to set a prompt which ends in a space
14447or a prompt that does not.
104c1213 14448
8e04817f
AC
14449@table @code
14450@kindex set prompt
14451@item set prompt @var{newprompt}
14452Directs @value{GDBN} to use @var{newprompt} as its prompt string henceforth.
104c1213 14453
8e04817f
AC
14454@kindex show prompt
14455@item show prompt
14456Prints a line of the form: @samp{Gdb's prompt is: @var{your-prompt}}
104c1213
JM
14457@end table
14458
8e04817f
AC
14459@node Editing
14460@section Command editing
14461@cindex readline
14462@cindex command line editing
104c1213 14463
703663ab 14464@value{GDBN} reads its input commands via the @dfn{Readline} interface. This
8e04817f
AC
14465@sc{gnu} library provides consistent behavior for programs which provide a
14466command line interface to the user. Advantages are @sc{gnu} Emacs-style
14467or @dfn{vi}-style inline editing of commands, @code{csh}-like history
14468substitution, and a storage and recall of command history across
14469debugging sessions.
104c1213 14470
8e04817f
AC
14471You may control the behavior of command line editing in @value{GDBN} with the
14472command @code{set}.
104c1213 14473
8e04817f
AC
14474@table @code
14475@kindex set editing
14476@cindex editing
14477@item set editing
14478@itemx set editing on
14479Enable command line editing (enabled by default).
104c1213 14480
8e04817f
AC
14481@item set editing off
14482Disable command line editing.
104c1213 14483
8e04817f
AC
14484@kindex show editing
14485@item show editing
14486Show whether command line editing is enabled.
104c1213
JM
14487@end table
14488
703663ab
EZ
14489@xref{Command Line Editing}, for more details about the Readline
14490interface. Users unfamiliar with @sc{gnu} Emacs or @code{vi} are
14491encouraged to read that chapter.
14492
8e04817f
AC
14493@node History
14494@section Command history
703663ab 14495@cindex command history
8e04817f
AC
14496
14497@value{GDBN} can keep track of the commands you type during your
14498debugging sessions, so that you can be certain of precisely what
14499happened. Use these commands to manage the @value{GDBN} command
14500history facility.
104c1213 14501
703663ab
EZ
14502@value{GDBN} uses the @sc{gnu} History library, a part of the Readline
14503package, to provide the history facility. @xref{Using History
14504Interactively}, for the detailed description of the History library.
14505
14506Here is the description of @value{GDBN} commands related to command
14507history.
14508
104c1213 14509@table @code
8e04817f
AC
14510@cindex history substitution
14511@cindex history file
14512@kindex set history filename
4644b6e3 14513@cindex @env{GDBHISTFILE}, environment variable
8e04817f
AC
14514@item set history filename @var{fname}
14515Set the name of the @value{GDBN} command history file to @var{fname}.
14516This is the file where @value{GDBN} reads an initial command history
14517list, and where it writes the command history from this session when it
14518exits. You can access this list through history expansion or through
14519the history command editing characters listed below. This file defaults
14520to the value of the environment variable @code{GDBHISTFILE}, or to
14521@file{./.gdb_history} (@file{./_gdb_history} on MS-DOS) if this variable
14522is not set.
104c1213 14523
9c16f35a
EZ
14524@cindex save command history
14525@kindex set history save
8e04817f
AC
14526@item set history save
14527@itemx set history save on
14528Record command history in a file, whose name may be specified with the
14529@code{set history filename} command. By default, this option is disabled.
104c1213 14530
8e04817f
AC
14531@item set history save off
14532Stop recording command history in a file.
104c1213 14533
8e04817f 14534@cindex history size
9c16f35a 14535@kindex set history size
8e04817f
AC
14536@item set history size @var{size}
14537Set the number of commands which @value{GDBN} keeps in its history list.
14538This defaults to the value of the environment variable
14539@code{HISTSIZE}, or to 256 if this variable is not set.
104c1213
JM
14540@end table
14541
8e04817f 14542History expansion assigns special meaning to the character @kbd{!}.
703663ab 14543@xref{Event Designators}, for more details.
8e04817f 14544
703663ab 14545@cindex history expansion, turn on/off
8e04817f
AC
14546Since @kbd{!} is also the logical not operator in C, history expansion
14547is off by default. If you decide to enable history expansion with the
14548@code{set history expansion on} command, you may sometimes need to
14549follow @kbd{!} (when it is used as logical not, in an expression) with
14550a space or a tab to prevent it from being expanded. The readline
14551history facilities do not attempt substitution on the strings
14552@kbd{!=} and @kbd{!(}, even when history expansion is enabled.
14553
14554The commands to control history expansion are:
104c1213
JM
14555
14556@table @code
8e04817f
AC
14557@item set history expansion on
14558@itemx set history expansion
703663ab 14559@kindex set history expansion
8e04817f 14560Enable history expansion. History expansion is off by default.
104c1213 14561
8e04817f
AC
14562@item set history expansion off
14563Disable history expansion.
104c1213 14564
8e04817f
AC
14565@c @group
14566@kindex show history
14567@item show history
14568@itemx show history filename
14569@itemx show history save
14570@itemx show history size
14571@itemx show history expansion
14572These commands display the state of the @value{GDBN} history parameters.
14573@code{show history} by itself displays all four states.
14574@c @end group
14575@end table
14576
14577@table @code
9c16f35a
EZ
14578@kindex show commands
14579@cindex show last commands
14580@cindex display command history
8e04817f
AC
14581@item show commands
14582Display the last ten commands in the command history.
104c1213 14583
8e04817f
AC
14584@item show commands @var{n}
14585Print ten commands centered on command number @var{n}.
14586
14587@item show commands +
14588Print ten commands just after the commands last printed.
104c1213
JM
14589@end table
14590
8e04817f
AC
14591@node Screen Size
14592@section Screen size
14593@cindex size of screen
14594@cindex pauses in output
104c1213 14595
8e04817f
AC
14596Certain commands to @value{GDBN} may produce large amounts of
14597information output to the screen. To help you read all of it,
14598@value{GDBN} pauses and asks you for input at the end of each page of
14599output. Type @key{RET} when you want to continue the output, or @kbd{q}
14600to discard the remaining output. Also, the screen width setting
14601determines when to wrap lines of output. Depending on what is being
14602printed, @value{GDBN} tries to break the line at a readable place,
14603rather than simply letting it overflow onto the following line.
14604
14605Normally @value{GDBN} knows the size of the screen from the terminal
14606driver software. For example, on Unix @value{GDBN} uses the termcap data base
14607together with the value of the @code{TERM} environment variable and the
14608@code{stty rows} and @code{stty cols} settings. If this is not correct,
14609you can override it with the @code{set height} and @code{set
14610width} commands:
14611
14612@table @code
14613@kindex set height
14614@kindex set width
14615@kindex show width
14616@kindex show height
14617@item set height @var{lpp}
14618@itemx show height
14619@itemx set width @var{cpl}
14620@itemx show width
14621These @code{set} commands specify a screen height of @var{lpp} lines and
14622a screen width of @var{cpl} characters. The associated @code{show}
14623commands display the current settings.
104c1213 14624
8e04817f
AC
14625If you specify a height of zero lines, @value{GDBN} does not pause during
14626output no matter how long the output is. This is useful if output is to a
14627file or to an editor buffer.
104c1213 14628
8e04817f
AC
14629Likewise, you can specify @samp{set width 0} to prevent @value{GDBN}
14630from wrapping its output.
9c16f35a
EZ
14631
14632@item set pagination on
14633@itemx set pagination off
14634@kindex set pagination
14635Turn the output pagination on or off; the default is on. Turning
14636pagination off is the alternative to @code{set height 0}.
14637
14638@item show pagination
14639@kindex show pagination
14640Show the current pagination mode.
104c1213
JM
14641@end table
14642
8e04817f
AC
14643@node Numbers
14644@section Numbers
14645@cindex number representation
14646@cindex entering numbers
104c1213 14647
8e04817f
AC
14648You can always enter numbers in octal, decimal, or hexadecimal in
14649@value{GDBN} by the usual conventions: octal numbers begin with
14650@samp{0}, decimal numbers end with @samp{.}, and hexadecimal numbers
14651begin with @samp{0x}. Numbers that begin with none of these are, by
14652default, entered in base 10; likewise, the default display for
14653numbers---when no particular format is specified---is base 10. You can
14654change the default base for both input and output with the @code{set
14655radix} command.
104c1213 14656
8e04817f
AC
14657@table @code
14658@kindex set input-radix
14659@item set input-radix @var{base}
14660Set the default base for numeric input. Supported choices
14661for @var{base} are decimal 8, 10, or 16. @var{base} must itself be
14662specified either unambiguously or using the current default radix; for
14663example, any of
104c1213 14664
8e04817f 14665@smallexample
9c16f35a
EZ
14666set input-radix 012
14667set input-radix 10.
14668set input-radix 0xa
8e04817f 14669@end smallexample
104c1213 14670
8e04817f 14671@noindent
9c16f35a
EZ
14672sets the input base to decimal. On the other hand, @samp{set input-radix 10}
14673leaves the input radix unchanged, no matter what it was.
104c1213 14674
8e04817f
AC
14675@kindex set output-radix
14676@item set output-radix @var{base}
14677Set the default base for numeric display. Supported choices
14678for @var{base} are decimal 8, 10, or 16. @var{base} must itself be
14679specified either unambiguously or using the current default radix.
104c1213 14680
8e04817f
AC
14681@kindex show input-radix
14682@item show input-radix
14683Display the current default base for numeric input.
104c1213 14684
8e04817f
AC
14685@kindex show output-radix
14686@item show output-radix
14687Display the current default base for numeric display.
9c16f35a
EZ
14688
14689@item set radix @r{[}@var{base}@r{]}
14690@itemx show radix
14691@kindex set radix
14692@kindex show radix
14693These commands set and show the default base for both input and output
14694of numbers. @code{set radix} sets the radix of input and output to
14695the same base; without an argument, it resets the radix back to its
14696default value of 10.
14697
8e04817f 14698@end table
104c1213 14699
1e698235
DJ
14700@node ABI
14701@section Configuring the current ABI
14702
14703@value{GDBN} can determine the @dfn{ABI} (Application Binary Interface) of your
14704application automatically. However, sometimes you need to override its
14705conclusions. Use these commands to manage @value{GDBN}'s view of the
14706current ABI.
14707
98b45e30
DJ
14708@cindex OS ABI
14709@kindex set osabi
b4e9345d 14710@kindex show osabi
98b45e30
DJ
14711
14712One @value{GDBN} configuration can debug binaries for multiple operating
b383017d 14713system targets, either via remote debugging or native emulation.
98b45e30
DJ
14714@value{GDBN} will autodetect the @dfn{OS ABI} (Operating System ABI) in use,
14715but you can override its conclusion using the @code{set osabi} command.
14716One example where this is useful is in debugging of binaries which use
14717an alternate C library (e.g.@: @sc{uClibc} for @sc{gnu}/Linux) which does
14718not have the same identifying marks that the standard C library for your
14719platform provides.
14720
14721@table @code
14722@item show osabi
14723Show the OS ABI currently in use.
14724
14725@item set osabi
14726With no argument, show the list of registered available OS ABI's.
14727
14728@item set osabi @var{abi}
14729Set the current OS ABI to @var{abi}.
14730@end table
14731
1e698235 14732@cindex float promotion
1e698235
DJ
14733
14734Generally, the way that an argument of type @code{float} is passed to a
14735function depends on whether the function is prototyped. For a prototyped
14736(i.e.@: ANSI/ISO style) function, @code{float} arguments are passed unchanged,
14737according to the architecture's convention for @code{float}. For unprototyped
14738(i.e.@: K&R style) functions, @code{float} arguments are first promoted to type
14739@code{double} and then passed.
14740
14741Unfortunately, some forms of debug information do not reliably indicate whether
14742a function is prototyped. If @value{GDBN} calls a function that is not marked
14743as prototyped, it consults @kbd{set coerce-float-to-double}.
14744
14745@table @code
a8f24a35 14746@kindex set coerce-float-to-double
1e698235
DJ
14747@item set coerce-float-to-double
14748@itemx set coerce-float-to-double on
14749Arguments of type @code{float} will be promoted to @code{double} when passed
14750to an unprototyped function. This is the default setting.
14751
14752@item set coerce-float-to-double off
14753Arguments of type @code{float} will be passed directly to unprototyped
14754functions.
9c16f35a
EZ
14755
14756@kindex show coerce-float-to-double
14757@item show coerce-float-to-double
14758Show the current setting of promoting @code{float} to @code{double}.
1e698235
DJ
14759@end table
14760
f1212245
DJ
14761@kindex set cp-abi
14762@kindex show cp-abi
14763@value{GDBN} needs to know the ABI used for your program's C@t{++}
14764objects. The correct C@t{++} ABI depends on which C@t{++} compiler was
14765used to build your application. @value{GDBN} only fully supports
14766programs with a single C@t{++} ABI; if your program contains code using
14767multiple C@t{++} ABI's or if @value{GDBN} can not identify your
14768program's ABI correctly, you can tell @value{GDBN} which ABI to use.
14769Currently supported ABI's include ``gnu-v2'', for @code{g++} versions
14770before 3.0, ``gnu-v3'', for @code{g++} versions 3.0 and later, and
14771``hpaCC'' for the HP ANSI C@t{++} compiler. Other C@t{++} compilers may
14772use the ``gnu-v2'' or ``gnu-v3'' ABI's as well. The default setting is
14773``auto''.
14774
14775@table @code
14776@item show cp-abi
14777Show the C@t{++} ABI currently in use.
14778
14779@item set cp-abi
14780With no argument, show the list of supported C@t{++} ABI's.
14781
14782@item set cp-abi @var{abi}
14783@itemx set cp-abi auto
14784Set the current C@t{++} ABI to @var{abi}, or return to automatic detection.
14785@end table
14786
8e04817f
AC
14787@node Messages/Warnings
14788@section Optional warnings and messages
104c1213 14789
9c16f35a
EZ
14790@cindex verbose operation
14791@cindex optional warnings
8e04817f
AC
14792By default, @value{GDBN} is silent about its inner workings. If you are
14793running on a slow machine, you may want to use the @code{set verbose}
14794command. This makes @value{GDBN} tell you when it does a lengthy
14795internal operation, so you will not think it has crashed.
104c1213 14796
8e04817f
AC
14797Currently, the messages controlled by @code{set verbose} are those
14798which announce that the symbol table for a source file is being read;
14799see @code{symbol-file} in @ref{Files, ,Commands to specify files}.
104c1213 14800
8e04817f
AC
14801@table @code
14802@kindex set verbose
14803@item set verbose on
14804Enables @value{GDBN} output of certain informational messages.
104c1213 14805
8e04817f
AC
14806@item set verbose off
14807Disables @value{GDBN} output of certain informational messages.
104c1213 14808
8e04817f
AC
14809@kindex show verbose
14810@item show verbose
14811Displays whether @code{set verbose} is on or off.
14812@end table
104c1213 14813
8e04817f
AC
14814By default, if @value{GDBN} encounters bugs in the symbol table of an
14815object file, it is silent; but if you are debugging a compiler, you may
14816find this information useful (@pxref{Symbol Errors, ,Errors reading
14817symbol files}).
104c1213 14818
8e04817f 14819@table @code
104c1213 14820
8e04817f
AC
14821@kindex set complaints
14822@item set complaints @var{limit}
14823Permits @value{GDBN} to output @var{limit} complaints about each type of
14824unusual symbols before becoming silent about the problem. Set
14825@var{limit} to zero to suppress all complaints; set it to a large number
14826to prevent complaints from being suppressed.
104c1213 14827
8e04817f
AC
14828@kindex show complaints
14829@item show complaints
14830Displays how many symbol complaints @value{GDBN} is permitted to produce.
104c1213 14831
8e04817f 14832@end table
104c1213 14833
8e04817f
AC
14834By default, @value{GDBN} is cautious, and asks what sometimes seems to be a
14835lot of stupid questions to confirm certain commands. For example, if
14836you try to run a program which is already running:
104c1213 14837
474c8240 14838@smallexample
8e04817f
AC
14839(@value{GDBP}) run
14840The program being debugged has been started already.
14841Start it from the beginning? (y or n)
474c8240 14842@end smallexample
104c1213 14843
8e04817f
AC
14844If you are willing to unflinchingly face the consequences of your own
14845commands, you can disable this ``feature'':
104c1213 14846
8e04817f 14847@table @code
104c1213 14848
8e04817f
AC
14849@kindex set confirm
14850@cindex flinching
14851@cindex confirmation
14852@cindex stupid questions
14853@item set confirm off
14854Disables confirmation requests.
104c1213 14855
8e04817f
AC
14856@item set confirm on
14857Enables confirmation requests (the default).
104c1213 14858
8e04817f
AC
14859@kindex show confirm
14860@item show confirm
14861Displays state of confirmation requests.
14862
14863@end table
104c1213 14864
8e04817f
AC
14865@node Debugging Output
14866@section Optional messages about internal happenings
4644b6e3
EZ
14867@cindex optional debugging messages
14868
da316a69
EZ
14869@value{GDBN} has commands that enable optional debugging messages from
14870various @value{GDBN} subsystems; normally these commands are of
14871interest to @value{GDBN} maintainers, or when reporting a bug. This
14872section documents those commands.
14873
104c1213 14874@table @code
a8f24a35
EZ
14875@kindex set exec-done-display
14876@item set exec-done-display
14877Turns on or off the notification of asynchronous commands'
14878completion. When on, @value{GDBN} will print a message when an
14879asynchronous command finishes its execution. The default is off.
14880@kindex show exec-done-display
14881@item show exec-done-display
14882Displays the current setting of asynchronous command completion
14883notification.
4644b6e3
EZ
14884@kindex set debug
14885@cindex gdbarch debugging info
a8f24a35 14886@cindex architecture debugging info
8e04817f 14887@item set debug arch
a8f24a35 14888Turns on or off display of gdbarch debugging info. The default is off
4644b6e3 14889@kindex show debug
8e04817f
AC
14890@item show debug arch
14891Displays the current state of displaying gdbarch debugging info.
8e04817f 14892@item set debug event
4644b6e3 14893@cindex event debugging info
a8f24a35 14894Turns on or off display of @value{GDBN} event debugging info. The
8e04817f 14895default is off.
8e04817f
AC
14896@item show debug event
14897Displays the current state of displaying @value{GDBN} event debugging
14898info.
8e04817f 14899@item set debug expression
4644b6e3 14900@cindex expression debugging info
a8f24a35 14901Turns on or off display of @value{GDBN} expression debugging info. The
8e04817f 14902default is off.
8e04817f
AC
14903@item show debug expression
14904Displays the current state of displaying @value{GDBN} expression
14905debugging info.
7453dc06 14906@item set debug frame
4644b6e3 14907@cindex frame debugging info
7453dc06
AC
14908Turns on or off display of @value{GDBN} frame debugging info. The
14909default is off.
7453dc06
AC
14910@item show debug frame
14911Displays the current state of displaying @value{GDBN} frame debugging
14912info.
30e91e0b
RC
14913@item set debug infrun
14914@cindex inferior debugging info
14915Turns on or off display of @value{GDBN} debugging info for running the inferior.
14916The default is off. @file{infrun.c} contains GDB's runtime state machine used
14917for implementing operations such as single-stepping the inferior.
14918@item show debug infrun
14919Displays the current state of @value{GDBN} inferior debugging.
da316a69
EZ
14920@item set debug lin-lwp
14921@cindex @sc{gnu}/Linux LWP debug messages
14922@cindex Linux lightweight processes
14923Turns on or off debugging messages from the LWP debug support.
14924@item show debug lin-lwp
14925Show the current state of Linux LWP debugging messages.
2b4855ab 14926@item set debug observer
4644b6e3 14927@cindex observer debugging info
2b4855ab
AC
14928Turns on or off display of @value{GDBN} observer debugging. This
14929includes info such as the notification of observable events.
2b4855ab
AC
14930@item show debug observer
14931Displays the current state of observer debugging.
8e04817f 14932@item set debug overload
4644b6e3 14933@cindex C@t{++} overload debugging info
8e04817f
AC
14934Turns on or off display of @value{GDBN} C@t{++} overload debugging
14935info. This includes info such as ranking of functions, etc. The default
14936is off.
8e04817f
AC
14937@item show debug overload
14938Displays the current state of displaying @value{GDBN} C@t{++} overload
14939debugging info.
8e04817f
AC
14940@cindex packets, reporting on stdout
14941@cindex serial connections, debugging
14942@item set debug remote
14943Turns on or off display of reports on all packets sent back and forth across
14944the serial line to the remote machine. The info is printed on the
14945@value{GDBN} standard output stream. The default is off.
8e04817f
AC
14946@item show debug remote
14947Displays the state of display of remote packets.
8e04817f
AC
14948@item set debug serial
14949Turns on or off display of @value{GDBN} serial debugging info. The
14950default is off.
8e04817f
AC
14951@item show debug serial
14952Displays the current state of displaying @value{GDBN} serial debugging
14953info.
8e04817f 14954@item set debug target
4644b6e3 14955@cindex target debugging info
8e04817f
AC
14956Turns on or off display of @value{GDBN} target debugging info. This info
14957includes what is going on at the target level of GDB, as it happens. The
701b08bb
DJ
14958default is 0. Set it to 1 to track events, and to 2 to also track the
14959value of large memory transfers. Changes to this flag do not take effect
14960until the next time you connect to a target or use the @code{run} command.
8e04817f
AC
14961@item show debug target
14962Displays the current state of displaying @value{GDBN} target debugging
14963info.
8e04817f 14964@item set debug varobj
4644b6e3 14965@cindex variable object debugging info
8e04817f
AC
14966Turns on or off display of @value{GDBN} variable object debugging
14967info. The default is off.
8e04817f
AC
14968@item show debug varobj
14969Displays the current state of displaying @value{GDBN} variable object
14970debugging info.
14971@end table
104c1213 14972
8e04817f
AC
14973@node Sequences
14974@chapter Canned Sequences of Commands
104c1213 14975
8e04817f
AC
14976Aside from breakpoint commands (@pxref{Break Commands, ,Breakpoint
14977command lists}), @value{GDBN} provides two ways to store sequences of
14978commands for execution as a unit: user-defined commands and command
14979files.
104c1213 14980
8e04817f
AC
14981@menu
14982* Define:: User-defined commands
14983* Hooks:: User-defined command hooks
14984* Command Files:: Command files
14985* Output:: Commands for controlled output
14986@end menu
104c1213 14987
8e04817f
AC
14988@node Define
14989@section User-defined commands
104c1213 14990
8e04817f
AC
14991@cindex user-defined command
14992A @dfn{user-defined command} is a sequence of @value{GDBN} commands to
14993which you assign a new name as a command. This is done with the
14994@code{define} command. User commands may accept up to 10 arguments
14995separated by whitespace. Arguments are accessed within the user command
14996via @var{$arg0@dots{}$arg9}. A trivial example:
104c1213 14997
8e04817f
AC
14998@smallexample
14999define adder
15000 print $arg0 + $arg1 + $arg2
15001@end smallexample
104c1213
JM
15002
15003@noindent
8e04817f 15004To execute the command use:
104c1213 15005
8e04817f
AC
15006@smallexample
15007adder 1 2 3
15008@end smallexample
104c1213 15009
8e04817f
AC
15010@noindent
15011This defines the command @code{adder}, which prints the sum of
15012its three arguments. Note the arguments are text substitutions, so they may
15013reference variables, use complex expressions, or even perform inferior
15014functions calls.
104c1213
JM
15015
15016@table @code
104c1213 15017
8e04817f
AC
15018@kindex define
15019@item define @var{commandname}
15020Define a command named @var{commandname}. If there is already a command
15021by that name, you are asked to confirm that you want to redefine it.
104c1213 15022
8e04817f
AC
15023The definition of the command is made up of other @value{GDBN} command lines,
15024which are given following the @code{define} command. The end of these
15025commands is marked by a line containing @code{end}.
104c1213 15026
8e04817f
AC
15027@kindex if
15028@kindex else
15029@item if
09d4efe1 15030@itemx else
8e04817f
AC
15031Takes a single argument, which is an expression to evaluate.
15032It is followed by a series of commands that are executed
15033only if the expression is true (nonzero).
15034There can then optionally be a line @code{else}, followed
15035by a series of commands that are only executed if the expression
15036was false. The end of the list is marked by a line containing @code{end}.
104c1213 15037
8e04817f
AC
15038@kindex while
15039@item while
15040The syntax is similar to @code{if}: the command takes a single argument,
15041which is an expression to evaluate, and must be followed by the commands to
15042execute, one per line, terminated by an @code{end}.
15043The commands are executed repeatedly as long as the expression
15044evaluates to true.
104c1213 15045
8e04817f
AC
15046@kindex document
15047@item document @var{commandname}
15048Document the user-defined command @var{commandname}, so that it can be
15049accessed by @code{help}. The command @var{commandname} must already be
15050defined. This command reads lines of documentation just as @code{define}
15051reads the lines of the command definition, ending with @code{end}.
15052After the @code{document} command is finished, @code{help} on command
15053@var{commandname} displays the documentation you have written.
104c1213 15054
8e04817f
AC
15055You may use the @code{document} command again to change the
15056documentation of a command. Redefining the command with @code{define}
15057does not change the documentation.
104c1213 15058
8e04817f
AC
15059@kindex help user-defined
15060@item help user-defined
15061List all user-defined commands, with the first line of the documentation
15062(if any) for each.
104c1213 15063
8e04817f
AC
15064@kindex show user
15065@item show user
15066@itemx show user @var{commandname}
15067Display the @value{GDBN} commands used to define @var{commandname} (but
15068not its documentation). If no @var{commandname} is given, display the
15069definitions for all user-defined commands.
104c1213 15070
9c16f35a 15071@cindex infinite recusrion in user-defined commands
20f01a46
DH
15072@kindex show max-user-call-depth
15073@kindex set max-user-call-depth
15074@item show max-user-call-depth
5ca0cb28
DH
15075@itemx set max-user-call-depth
15076The value of @code{max-user-call-depth} controls how many recursion
15077levels are allowed in user-defined commands before GDB suspects an
15078infinite recursion and aborts the command.
20f01a46 15079
104c1213
JM
15080@end table
15081
8e04817f
AC
15082When user-defined commands are executed, the
15083commands of the definition are not printed. An error in any command
15084stops execution of the user-defined command.
104c1213 15085
8e04817f
AC
15086If used interactively, commands that would ask for confirmation proceed
15087without asking when used inside a user-defined command. Many @value{GDBN}
15088commands that normally print messages to say what they are doing omit the
15089messages when used in a user-defined command.
104c1213 15090
8e04817f
AC
15091@node Hooks
15092@section User-defined command hooks
15093@cindex command hooks
15094@cindex hooks, for commands
15095@cindex hooks, pre-command
104c1213 15096
8e04817f 15097@kindex hook
8e04817f
AC
15098You may define @dfn{hooks}, which are a special kind of user-defined
15099command. Whenever you run the command @samp{foo}, if the user-defined
15100command @samp{hook-foo} exists, it is executed (with no arguments)
15101before that command.
104c1213 15102
8e04817f
AC
15103@cindex hooks, post-command
15104@kindex hookpost
8e04817f
AC
15105A hook may also be defined which is run after the command you executed.
15106Whenever you run the command @samp{foo}, if the user-defined command
15107@samp{hookpost-foo} exists, it is executed (with no arguments) after
15108that command. Post-execution hooks may exist simultaneously with
15109pre-execution hooks, for the same command.
104c1213 15110
8e04817f 15111It is valid for a hook to call the command which it hooks. If this
9f1c6395 15112occurs, the hook is not re-executed, thereby avoiding infinite recursion.
104c1213 15113
8e04817f
AC
15114@c It would be nice if hookpost could be passed a parameter indicating
15115@c if the command it hooks executed properly or not. FIXME!
104c1213 15116
8e04817f
AC
15117@kindex stop@r{, a pseudo-command}
15118In addition, a pseudo-command, @samp{stop} exists. Defining
15119(@samp{hook-stop}) makes the associated commands execute every time
15120execution stops in your program: before breakpoint commands are run,
15121displays are printed, or the stack frame is printed.
104c1213 15122
8e04817f
AC
15123For example, to ignore @code{SIGALRM} signals while
15124single-stepping, but treat them normally during normal execution,
15125you could define:
104c1213 15126
474c8240 15127@smallexample
8e04817f
AC
15128define hook-stop
15129handle SIGALRM nopass
15130end
104c1213 15131
8e04817f
AC
15132define hook-run
15133handle SIGALRM pass
15134end
104c1213 15135
8e04817f
AC
15136define hook-continue
15137handle SIGLARM pass
15138end
474c8240 15139@end smallexample
104c1213 15140
8e04817f 15141As a further example, to hook at the begining and end of the @code{echo}
b383017d 15142command, and to add extra text to the beginning and end of the message,
8e04817f 15143you could define:
104c1213 15144
474c8240 15145@smallexample
8e04817f
AC
15146define hook-echo
15147echo <<<---
15148end
104c1213 15149
8e04817f
AC
15150define hookpost-echo
15151echo --->>>\n
15152end
104c1213 15153
8e04817f
AC
15154(@value{GDBP}) echo Hello World
15155<<<---Hello World--->>>
15156(@value{GDBP})
104c1213 15157
474c8240 15158@end smallexample
104c1213 15159
8e04817f
AC
15160You can define a hook for any single-word command in @value{GDBN}, but
15161not for command aliases; you should define a hook for the basic command
15162name, e.g. @code{backtrace} rather than @code{bt}.
15163@c FIXME! So how does Joe User discover whether a command is an alias
15164@c or not?
15165If an error occurs during the execution of your hook, execution of
15166@value{GDBN} commands stops and @value{GDBN} issues a prompt
15167(before the command that you actually typed had a chance to run).
104c1213 15168
8e04817f
AC
15169If you try to define a hook which does not match any known command, you
15170get a warning from the @code{define} command.
c906108c 15171
8e04817f
AC
15172@node Command Files
15173@section Command files
c906108c 15174
8e04817f
AC
15175@cindex command files
15176A command file for @value{GDBN} is a file of lines that are @value{GDBN}
15177commands. Comments (lines starting with @kbd{#}) may also be included.
15178An empty line in a command file does nothing; it does not mean to repeat
15179the last command, as it would from the terminal.
c906108c 15180
8e04817f
AC
15181@cindex init file
15182@cindex @file{.gdbinit}
15183@cindex @file{gdb.ini}
15184When you start @value{GDBN}, it automatically executes commands from its
15185@dfn{init files}, normally called @file{.gdbinit}@footnote{The DJGPP
15186port of @value{GDBN} uses the name @file{gdb.ini} instead, due to the
15187limitations of file names imposed by DOS filesystems.}.
15188During startup, @value{GDBN} does the following:
c906108c 15189
8e04817f
AC
15190@enumerate
15191@item
15192Reads the init file (if any) in your home directory@footnote{On
15193DOS/Windows systems, the home directory is the one pointed to by the
15194@code{HOME} environment variable.}.
c906108c 15195
8e04817f
AC
15196@item
15197Processes command line options and operands.
c906108c 15198
8e04817f
AC
15199@item
15200Reads the init file (if any) in the current working directory.
c906108c 15201
8e04817f
AC
15202@item
15203Reads command files specified by the @samp{-x} option.
15204@end enumerate
c906108c 15205
8e04817f
AC
15206The init file in your home directory can set options (such as @samp{set
15207complaints}) that affect subsequent processing of command line options
15208and operands. Init files are not executed if you use the @samp{-nx}
15209option (@pxref{Mode Options, ,Choosing modes}).
c906108c 15210
8e04817f
AC
15211@cindex init file name
15212On some configurations of @value{GDBN}, the init file is known by a
15213different name (these are typically environments where a specialized
15214form of @value{GDBN} may need to coexist with other forms, hence a
15215different name for the specialized version's init file). These are the
15216environments with special init file names:
c906108c 15217
8e04817f
AC
15218@cindex @file{.vxgdbinit}
15219@itemize @bullet
15220@item
15221VxWorks (Wind River Systems real-time OS): @file{.vxgdbinit}
c906108c 15222
8e04817f
AC
15223@cindex @file{.os68gdbinit}
15224@item
15225OS68K (Enea Data Systems real-time OS): @file{.os68gdbinit}
c906108c 15226
8e04817f
AC
15227@cindex @file{.esgdbinit}
15228@item
15229ES-1800 (Ericsson Telecom AB M68000 emulator): @file{.esgdbinit}
15230@end itemize
c906108c 15231
8e04817f
AC
15232You can also request the execution of a command file with the
15233@code{source} command:
c906108c 15234
8e04817f
AC
15235@table @code
15236@kindex source
15237@item source @var{filename}
15238Execute the command file @var{filename}.
c906108c
SS
15239@end table
15240
8e04817f 15241The lines in a command file are executed sequentially. They are not
a71ec265
DH
15242printed as they are executed. An error in any command terminates
15243execution of the command file and control is returned to the console.
c906108c 15244
8e04817f
AC
15245Commands that would ask for confirmation if used interactively proceed
15246without asking when used in a command file. Many @value{GDBN} commands that
15247normally print messages to say what they are doing omit the messages
15248when called from command files.
c906108c 15249
8e04817f
AC
15250@value{GDBN} also accepts command input from standard input. In this
15251mode, normal output goes to standard output and error output goes to
15252standard error. Errors in a command file supplied on standard input do
15253not terminate execution of the command file --- execution continues with
15254the next command.
c906108c 15255
474c8240 15256@smallexample
8e04817f 15257gdb < cmds > log 2>&1
474c8240 15258@end smallexample
c906108c 15259
8e04817f
AC
15260(The syntax above will vary depending on the shell used.) This example
15261will execute commands from the file @file{cmds}. All output and errors
15262would be directed to @file{log}.
c906108c 15263
8e04817f
AC
15264@node Output
15265@section Commands for controlled output
c906108c 15266
8e04817f
AC
15267During the execution of a command file or a user-defined command, normal
15268@value{GDBN} output is suppressed; the only output that appears is what is
15269explicitly printed by the commands in the definition. This section
15270describes three commands useful for generating exactly the output you
15271want.
c906108c
SS
15272
15273@table @code
8e04817f
AC
15274@kindex echo
15275@item echo @var{text}
15276@c I do not consider backslash-space a standard C escape sequence
15277@c because it is not in ANSI.
15278Print @var{text}. Nonprinting characters can be included in
15279@var{text} using C escape sequences, such as @samp{\n} to print a
15280newline. @strong{No newline is printed unless you specify one.}
15281In addition to the standard C escape sequences, a backslash followed
15282by a space stands for a space. This is useful for displaying a
15283string with spaces at the beginning or the end, since leading and
15284trailing spaces are otherwise trimmed from all arguments.
15285To print @samp{@w{ }and foo =@w{ }}, use the command
15286@samp{echo \@w{ }and foo = \@w{ }}.
c906108c 15287
8e04817f
AC
15288A backslash at the end of @var{text} can be used, as in C, to continue
15289the command onto subsequent lines. For example,
c906108c 15290
474c8240 15291@smallexample
8e04817f
AC
15292echo This is some text\n\
15293which is continued\n\
15294onto several lines.\n
474c8240 15295@end smallexample
c906108c 15296
8e04817f 15297produces the same output as
c906108c 15298
474c8240 15299@smallexample
8e04817f
AC
15300echo This is some text\n
15301echo which is continued\n
15302echo onto several lines.\n
474c8240 15303@end smallexample
c906108c 15304
8e04817f
AC
15305@kindex output
15306@item output @var{expression}
15307Print the value of @var{expression} and nothing but that value: no
15308newlines, no @samp{$@var{nn} = }. The value is not entered in the
15309value history either. @xref{Expressions, ,Expressions}, for more information
15310on expressions.
c906108c 15311
8e04817f
AC
15312@item output/@var{fmt} @var{expression}
15313Print the value of @var{expression} in format @var{fmt}. You can use
15314the same formats as for @code{print}. @xref{Output Formats,,Output
15315formats}, for more information.
c906108c 15316
8e04817f
AC
15317@kindex printf
15318@item printf @var{string}, @var{expressions}@dots{}
15319Print the values of the @var{expressions} under the control of
15320@var{string}. The @var{expressions} are separated by commas and may be
15321either numbers or pointers. Their values are printed as specified by
15322@var{string}, exactly as if your program were to execute the C
15323subroutine
15324@c FIXME: the above implies that at least all ANSI C formats are
15325@c supported, but it isn't true: %E and %G don't work (or so it seems).
15326@c Either this is a bug, or the manual should document what formats are
15327@c supported.
c906108c 15328
474c8240 15329@smallexample
8e04817f 15330printf (@var{string}, @var{expressions}@dots{});
474c8240 15331@end smallexample
c906108c 15332
8e04817f 15333For example, you can print two values in hex like this:
c906108c 15334
8e04817f
AC
15335@smallexample
15336printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo
15337@end smallexample
c906108c 15338
8e04817f
AC
15339The only backslash-escape sequences that you can use in the format
15340string are the simple ones that consist of backslash followed by a
15341letter.
c906108c
SS
15342@end table
15343
21c294e6
AC
15344@node Interpreters
15345@chapter Command Interpreters
15346@cindex command interpreters
15347
15348@value{GDBN} supports multiple command interpreters, and some command
15349infrastructure to allow users or user interface writers to switch
15350between interpreters or run commands in other interpreters.
15351
15352@value{GDBN} currently supports two command interpreters, the console
15353interpreter (sometimes called the command-line interpreter or @sc{cli})
15354and the machine interface interpreter (or @sc{gdb/mi}). This manual
15355describes both of these interfaces in great detail.
15356
15357By default, @value{GDBN} will start with the console interpreter.
15358However, the user may choose to start @value{GDBN} with another
15359interpreter by specifying the @option{-i} or @option{--interpreter}
15360startup options. Defined interpreters include:
15361
15362@table @code
15363@item console
15364@cindex console interpreter
15365The traditional console or command-line interpreter. This is the most often
15366used interpreter with @value{GDBN}. With no interpreter specified at runtime,
15367@value{GDBN} will use this interpreter.
15368
15369@item mi
15370@cindex mi interpreter
15371The newest @sc{gdb/mi} interface (currently @code{mi2}). Used primarily
15372by programs wishing to use @value{GDBN} as a backend for a debugger GUI
15373or an IDE. For more information, see @ref{GDB/MI, ,The @sc{gdb/mi}
15374Interface}.
15375
15376@item mi2
15377@cindex mi2 interpreter
15378The current @sc{gdb/mi} interface.
15379
15380@item mi1
15381@cindex mi1 interpreter
15382The @sc{gdb/mi} interface included in @value{GDBN} 5.1, 5.2, and 5.3.
15383
15384@end table
15385
15386@cindex invoke another interpreter
15387The interpreter being used by @value{GDBN} may not be dynamically
15388switched at runtime. Although possible, this could lead to a very
15389precarious situation. Consider an IDE using @sc{gdb/mi}. If a user
15390enters the command "interpreter-set console" in a console view,
15391@value{GDBN} would switch to using the console interpreter, rendering
15392the IDE inoperable!
15393
15394@kindex interpreter-exec
15395Although you may only choose a single interpreter at startup, you may execute
15396commands in any interpreter from the current interpreter using the appropriate
15397command. If you are running the console interpreter, simply use the
15398@code{interpreter-exec} command:
15399
15400@smallexample
15401interpreter-exec mi "-data-list-register-names"
15402@end smallexample
15403
15404@sc{gdb/mi} has a similar command, although it is only available in versions of
15405@value{GDBN} which support @sc{gdb/mi} version 2 (or greater).
15406
8e04817f
AC
15407@node TUI
15408@chapter @value{GDBN} Text User Interface
15409@cindex TUI
d0d5df6f 15410@cindex Text User Interface
c906108c 15411
8e04817f
AC
15412@menu
15413* TUI Overview:: TUI overview
15414* TUI Keys:: TUI key bindings
7cf36c78 15415* TUI Single Key Mode:: TUI single key mode
8e04817f
AC
15416* TUI Commands:: TUI specific commands
15417* TUI Configuration:: TUI configuration variables
15418@end menu
c906108c 15419
d0d5df6f
AC
15420The @value{GDBN} Text User Interface, TUI in short, is a terminal
15421interface which uses the @code{curses} library to show the source
15422file, the assembly output, the program registers and @value{GDBN}
15423commands in separate text windows.
15424
15425The TUI is enabled by invoking @value{GDBN} using either
15426@pindex gdbtui
15427@samp{gdbtui} or @samp{gdb -tui}.
c906108c 15428
8e04817f
AC
15429@node TUI Overview
15430@section TUI overview
c906108c 15431
8e04817f
AC
15432The TUI has two display modes that can be switched while
15433@value{GDBN} runs:
c906108c 15434
8e04817f
AC
15435@itemize @bullet
15436@item
15437A curses (or TUI) mode in which it displays several text
15438windows on the terminal.
c906108c 15439
8e04817f
AC
15440@item
15441A standard mode which corresponds to the @value{GDBN} configured without
15442the TUI.
15443@end itemize
c906108c 15444
8e04817f
AC
15445In the TUI mode, @value{GDBN} can display several text window
15446on the terminal:
c906108c 15447
8e04817f
AC
15448@table @emph
15449@item command
15450This window is the @value{GDBN} command window with the @value{GDBN}
15451prompt and the @value{GDBN} outputs. The @value{GDBN} input is still
15452managed using readline but through the TUI. The @emph{command}
15453window is always visible.
c906108c 15454
8e04817f
AC
15455@item source
15456The source window shows the source file of the program. The current
15457line as well as active breakpoints are displayed in this window.
c906108c 15458
8e04817f
AC
15459@item assembly
15460The assembly window shows the disassembly output of the program.
c906108c 15461
8e04817f
AC
15462@item register
15463This window shows the processor registers. It detects when
15464a register is changed and when this is the case, registers that have
6a1b180d 15465changed are highlighted.
c906108c 15466
c906108c
SS
15467@end table
15468
269c21fe
SC
15469The source and assembly windows show the current program position
15470by highlighting the current line and marking them with the @samp{>} marker.
15471Breakpoints are also indicated with two markers. A first one
15472indicates the breakpoint type:
15473
15474@table @code
15475@item B
15476Breakpoint which was hit at least once.
15477
15478@item b
15479Breakpoint which was never hit.
15480
15481@item H
15482Hardware breakpoint which was hit at least once.
15483
15484@item h
15485Hardware breakpoint which was never hit.
15486
15487@end table
15488
15489The second marker indicates whether the breakpoint is enabled or not:
15490
15491@table @code
15492@item +
15493Breakpoint is enabled.
15494
15495@item -
15496Breakpoint is disabled.
15497
15498@end table
15499
8e04817f
AC
15500The source, assembly and register windows are attached to the thread
15501and the frame position. They are updated when the current thread
15502changes, when the frame changes or when the program counter changes.
15503These three windows are arranged by the TUI according to several
15504layouts. The layout defines which of these three windows are visible.
15505The following layouts are available:
c906108c 15506
8e04817f
AC
15507@itemize @bullet
15508@item
15509source
2df3850c 15510
8e04817f
AC
15511@item
15512assembly
15513
15514@item
15515source and assembly
15516
15517@item
15518source and registers
c906108c 15519
8e04817f
AC
15520@item
15521assembly and registers
2df3850c 15522
8e04817f 15523@end itemize
c906108c 15524
b7bb15bc
SC
15525On top of the command window a status line gives various information
15526concerning the current process begin debugged. The status line is
15527updated when the information it shows changes. The following fields
15528are displayed:
15529
15530@table @emph
15531@item target
15532Indicates the current gdb target
15533(@pxref{Targets, ,Specifying a Debugging Target}).
15534
15535@item process
15536Gives information about the current process or thread number.
15537When no process is being debugged, this field is set to @code{No process}.
15538
15539@item function
15540Gives the current function name for the selected frame.
15541The name is demangled if demangling is turned on (@pxref{Print Settings}).
15542When there is no symbol corresponding to the current program counter
15543the string @code{??} is displayed.
15544
15545@item line
15546Indicates the current line number for the selected frame.
15547When the current line number is not known the string @code{??} is displayed.
15548
15549@item pc
15550Indicates the current program counter address.
15551
15552@end table
15553
8e04817f
AC
15554@node TUI Keys
15555@section TUI Key Bindings
15556@cindex TUI key bindings
c906108c 15557
8e04817f
AC
15558The TUI installs several key bindings in the readline keymaps
15559(@pxref{Command Line Editing}).
15560They allow to leave or enter in the TUI mode or they operate
7cf36c78
SC
15561directly on the TUI layout and windows. The TUI also provides
15562a @emph{SingleKey} keymap which binds several keys directly to
15563@value{GDBN} commands. The following key bindings
8e04817f 15564are installed for both TUI mode and the @value{GDBN} standard mode.
c906108c 15565
8e04817f
AC
15566@table @kbd
15567@kindex C-x C-a
15568@item C-x C-a
15569@kindex C-x a
15570@itemx C-x a
15571@kindex C-x A
15572@itemx C-x A
15573Enter or leave the TUI mode. When the TUI mode is left,
15574the curses window management is left and @value{GDBN} operates using
15575its standard mode writing on the terminal directly. When the TUI
15576mode is entered, the control is given back to the curses windows.
15577The screen is then refreshed.
c906108c 15578
8e04817f
AC
15579@kindex C-x 1
15580@item C-x 1
15581Use a TUI layout with only one window. The layout will
15582either be @samp{source} or @samp{assembly}. When the TUI mode
15583is not active, it will switch to the TUI mode.
2df3850c 15584
8e04817f 15585Think of this key binding as the Emacs @kbd{C-x 1} binding.
c906108c 15586
8e04817f
AC
15587@kindex C-x 2
15588@item C-x 2
15589Use a TUI layout with at least two windows. When the current
15590layout shows already two windows, a next layout with two windows is used.
15591When a new layout is chosen, one window will always be common to the
15592previous layout and the new one.
c906108c 15593
8e04817f 15594Think of it as the Emacs @kbd{C-x 2} binding.
2df3850c 15595
72ffddc9
SC
15596@kindex C-x o
15597@item C-x o
15598Change the active window. The TUI associates several key bindings
15599(like scrolling and arrow keys) to the active window. This command
15600gives the focus to the next TUI window.
15601
15602Think of it as the Emacs @kbd{C-x o} binding.
15603
7cf36c78
SC
15604@kindex C-x s
15605@item C-x s
15606Use the TUI @emph{SingleKey} keymap that binds single key to gdb commands
15607(@pxref{TUI Single Key Mode}).
15608
c906108c
SS
15609@end table
15610
8e04817f 15611The following key bindings are handled only by the TUI mode:
5d161b24 15612
8e04817f
AC
15613@table @key
15614@kindex PgUp
15615@item PgUp
15616Scroll the active window one page up.
c906108c 15617
8e04817f
AC
15618@kindex PgDn
15619@item PgDn
15620Scroll the active window one page down.
c906108c 15621
8e04817f
AC
15622@kindex Up
15623@item Up
15624Scroll the active window one line up.
c906108c 15625
8e04817f
AC
15626@kindex Down
15627@item Down
15628Scroll the active window one line down.
c906108c 15629
8e04817f
AC
15630@kindex Left
15631@item Left
15632Scroll the active window one column left.
c906108c 15633
8e04817f
AC
15634@kindex Right
15635@item Right
15636Scroll the active window one column right.
c906108c 15637
8e04817f
AC
15638@kindex C-L
15639@item C-L
15640Refresh the screen.
c906108c 15641
8e04817f 15642@end table
c906108c 15643
8e04817f 15644In the TUI mode, the arrow keys are used by the active window
72ffddc9
SC
15645for scrolling. This means they are available for readline when the
15646active window is the command window. When the command window
15647does not have the focus, it is necessary to use other readline
15648key bindings such as @key{C-p}, @key{C-n}, @key{C-b} and @key{C-f}.
8e04817f 15649
7cf36c78
SC
15650@node TUI Single Key Mode
15651@section TUI Single Key Mode
15652@cindex TUI single key mode
15653
15654The TUI provides a @emph{SingleKey} mode in which it installs a particular
15655key binding in the readline keymaps to connect single keys to
b383017d 15656some gdb commands.
7cf36c78
SC
15657
15658@table @kbd
15659@kindex c @r{(SingleKey TUI key)}
15660@item c
15661continue
15662
15663@kindex d @r{(SingleKey TUI key)}
15664@item d
15665down
15666
15667@kindex f @r{(SingleKey TUI key)}
15668@item f
15669finish
15670
15671@kindex n @r{(SingleKey TUI key)}
15672@item n
15673next
15674
15675@kindex q @r{(SingleKey TUI key)}
15676@item q
15677exit the @emph{SingleKey} mode.
15678
15679@kindex r @r{(SingleKey TUI key)}
15680@item r
15681run
15682
15683@kindex s @r{(SingleKey TUI key)}
15684@item s
15685step
15686
15687@kindex u @r{(SingleKey TUI key)}
15688@item u
15689up
15690
15691@kindex v @r{(SingleKey TUI key)}
15692@item v
15693info locals
15694
15695@kindex w @r{(SingleKey TUI key)}
15696@item w
15697where
15698
15699@end table
15700
15701Other keys temporarily switch to the @value{GDBN} command prompt.
15702The key that was pressed is inserted in the editing buffer so that
15703it is possible to type most @value{GDBN} commands without interaction
15704with the TUI @emph{SingleKey} mode. Once the command is entered the TUI
15705@emph{SingleKey} mode is restored. The only way to permanently leave
15706this mode is by hitting @key{q} or @samp{@key{C-x} @key{s}}.
15707
15708
8e04817f
AC
15709@node TUI Commands
15710@section TUI specific commands
15711@cindex TUI commands
15712
15713The TUI has specific commands to control the text windows.
15714These commands are always available, that is they do not depend on
15715the current terminal mode in which @value{GDBN} runs. When @value{GDBN}
15716is in the standard mode, using these commands will automatically switch
15717in the TUI mode.
c906108c
SS
15718
15719@table @code
3d757584
SC
15720@item info win
15721@kindex info win
15722List and give the size of all displayed windows.
15723
8e04817f 15724@item layout next
4644b6e3 15725@kindex layout
8e04817f 15726Display the next layout.
2df3850c 15727
8e04817f 15728@item layout prev
8e04817f 15729Display the previous layout.
c906108c 15730
8e04817f 15731@item layout src
8e04817f 15732Display the source window only.
c906108c 15733
8e04817f 15734@item layout asm
8e04817f 15735Display the assembly window only.
c906108c 15736
8e04817f 15737@item layout split
8e04817f 15738Display the source and assembly window.
c906108c 15739
8e04817f 15740@item layout regs
8e04817f
AC
15741Display the register window together with the source or assembly window.
15742
15743@item focus next | prev | src | asm | regs | split
15744@kindex focus
15745Set the focus to the named window.
15746This command allows to change the active window so that scrolling keys
15747can be affected to another window.
c906108c 15748
8e04817f
AC
15749@item refresh
15750@kindex refresh
15751Refresh the screen. This is similar to using @key{C-L} key.
c906108c 15752
6a1b180d
SC
15753@item tui reg float
15754@kindex tui reg
15755Show the floating point registers in the register window.
15756
15757@item tui reg general
15758Show the general registers in the register window.
15759
15760@item tui reg next
15761Show the next register group. The list of register groups as well as
15762their order is target specific. The predefined register groups are the
15763following: @code{general}, @code{float}, @code{system}, @code{vector},
15764@code{all}, @code{save}, @code{restore}.
15765
15766@item tui reg system
15767Show the system registers in the register window.
15768
8e04817f
AC
15769@item update
15770@kindex update
15771Update the source window and the current execution point.
c906108c 15772
8e04817f
AC
15773@item winheight @var{name} +@var{count}
15774@itemx winheight @var{name} -@var{count}
15775@kindex winheight
15776Change the height of the window @var{name} by @var{count}
15777lines. Positive counts increase the height, while negative counts
15778decrease it.
2df3850c 15779
c906108c
SS
15780@end table
15781
8e04817f
AC
15782@node TUI Configuration
15783@section TUI configuration variables
15784@cindex TUI configuration variables
c906108c 15785
8e04817f
AC
15786The TUI has several configuration variables that control the
15787appearance of windows on the terminal.
c906108c 15788
8e04817f
AC
15789@table @code
15790@item set tui border-kind @var{kind}
15791@kindex set tui border-kind
15792Select the border appearance for the source, assembly and register windows.
15793The possible values are the following:
15794@table @code
15795@item space
15796Use a space character to draw the border.
c906108c 15797
8e04817f
AC
15798@item ascii
15799Use ascii characters + - and | to draw the border.
c906108c 15800
8e04817f
AC
15801@item acs
15802Use the Alternate Character Set to draw the border. The border is
15803drawn using character line graphics if the terminal supports them.
c78b4128 15804
8e04817f 15805@end table
c78b4128 15806
8e04817f
AC
15807@item set tui active-border-mode @var{mode}
15808@kindex set tui active-border-mode
15809Select the attributes to display the border of the active window.
15810The possible values are @code{normal}, @code{standout}, @code{reverse},
15811@code{half}, @code{half-standout}, @code{bold} and @code{bold-standout}.
c78b4128 15812
8e04817f
AC
15813@item set tui border-mode @var{mode}
15814@kindex set tui border-mode
15815Select the attributes to display the border of other windows.
15816The @var{mode} can be one of the following:
15817@table @code
15818@item normal
15819Use normal attributes to display the border.
c906108c 15820
8e04817f
AC
15821@item standout
15822Use standout mode.
c906108c 15823
8e04817f
AC
15824@item reverse
15825Use reverse video mode.
c906108c 15826
8e04817f
AC
15827@item half
15828Use half bright mode.
c906108c 15829
8e04817f
AC
15830@item half-standout
15831Use half bright and standout mode.
c906108c 15832
8e04817f
AC
15833@item bold
15834Use extra bright or bold mode.
c78b4128 15835
8e04817f
AC
15836@item bold-standout
15837Use extra bright or bold and standout mode.
c78b4128 15838
8e04817f 15839@end table
c78b4128 15840
8e04817f 15841@end table
c78b4128 15842
8e04817f
AC
15843@node Emacs
15844@chapter Using @value{GDBN} under @sc{gnu} Emacs
c78b4128 15845
8e04817f
AC
15846@cindex Emacs
15847@cindex @sc{gnu} Emacs
15848A special interface allows you to use @sc{gnu} Emacs to view (and
15849edit) the source files for the program you are debugging with
15850@value{GDBN}.
c906108c 15851
8e04817f
AC
15852To use this interface, use the command @kbd{M-x gdb} in Emacs. Give the
15853executable file you want to debug as an argument. This command starts
15854@value{GDBN} as a subprocess of Emacs, with input and output through a newly
15855created Emacs buffer.
15856@c (Do not use the @code{-tui} option to run @value{GDBN} from Emacs.)
c906108c 15857
8e04817f
AC
15858Using @value{GDBN} under Emacs is just like using @value{GDBN} normally except for two
15859things:
c906108c 15860
8e04817f
AC
15861@itemize @bullet
15862@item
15863All ``terminal'' input and output goes through the Emacs buffer.
15864@end itemize
c906108c 15865
8e04817f
AC
15866This applies both to @value{GDBN} commands and their output, and to the input
15867and output done by the program you are debugging.
bf0184be 15868
8e04817f
AC
15869This is useful because it means that you can copy the text of previous
15870commands and input them again; you can even use parts of the output
15871in this way.
bf0184be 15872
8e04817f
AC
15873All the facilities of Emacs' Shell mode are available for interacting
15874with your program. In particular, you can send signals the usual
15875way---for example, @kbd{C-c C-c} for an interrupt, @kbd{C-c C-z} for a
15876stop.
bf0184be 15877
8e04817f 15878@itemize @bullet
bf0184be 15879@item
8e04817f
AC
15880@value{GDBN} displays source code through Emacs.
15881@end itemize
bf0184be 15882
8e04817f
AC
15883Each time @value{GDBN} displays a stack frame, Emacs automatically finds the
15884source file for that frame and puts an arrow (@samp{=>}) at the
15885left margin of the current line. Emacs uses a separate buffer for
15886source display, and splits the screen to show both your @value{GDBN} session
15887and the source.
bf0184be 15888
8e04817f
AC
15889Explicit @value{GDBN} @code{list} or search commands still produce output as
15890usual, but you probably have no reason to use them from Emacs.
c906108c 15891
64fabec2
AC
15892If you specify an absolute file name when prompted for the @kbd{M-x
15893gdb} argument, then Emacs sets your current working directory to where
15894your program resides. If you only specify the file name, then Emacs
15895sets your current working directory to to the directory associated
15896with the previous buffer. In this case, @value{GDBN} may find your
15897program by searching your environment's @code{PATH} variable, but on
15898some operating systems it might not find the source. So, although the
15899@value{GDBN} input and output session proceeds normally, the auxiliary
15900buffer does not display the current source and line of execution.
15901
15902The initial working directory of @value{GDBN} is printed on the top
15903line of the @value{GDBN} I/O buffer and this serves as a default for
15904the commands that specify files for @value{GDBN} to operate
15905on. @xref{Files, ,Commands to specify files}.
15906
15907By default, @kbd{M-x gdb} calls the program called @file{gdb}. If you
15908need to call @value{GDBN} by a different name (for example, if you
15909keep several configurations around, with different names) you can
15910customize the Emacs variable @code{gud-gdb-command-name} to run the
15911one you want.
8e04817f
AC
15912
15913In the @value{GDBN} I/O buffer, you can use these special Emacs commands in
15914addition to the standard Shell mode commands:
c906108c 15915
8e04817f
AC
15916@table @kbd
15917@item C-h m
15918Describe the features of Emacs' @value{GDBN} Mode.
c906108c 15919
64fabec2 15920@item C-c C-s
8e04817f
AC
15921Execute to another source line, like the @value{GDBN} @code{step} command; also
15922update the display window to show the current file and location.
c906108c 15923
64fabec2 15924@item C-c C-n
8e04817f
AC
15925Execute to next source line in this function, skipping all function
15926calls, like the @value{GDBN} @code{next} command. Then update the display window
15927to show the current file and location.
c906108c 15928
64fabec2 15929@item C-c C-i
8e04817f
AC
15930Execute one instruction, like the @value{GDBN} @code{stepi} command; update
15931display window accordingly.
c906108c 15932
8e04817f
AC
15933@item C-c C-f
15934Execute until exit from the selected stack frame, like the @value{GDBN}
15935@code{finish} command.
c906108c 15936
64fabec2 15937@item C-c C-r
8e04817f
AC
15938Continue execution of your program, like the @value{GDBN} @code{continue}
15939command.
b433d00b 15940
64fabec2 15941@item C-c <
8e04817f
AC
15942Go up the number of frames indicated by the numeric argument
15943(@pxref{Arguments, , Numeric Arguments, Emacs, The @sc{gnu} Emacs Manual}),
15944like the @value{GDBN} @code{up} command.
b433d00b 15945
64fabec2 15946@item C-c >
8e04817f
AC
15947Go down the number of frames indicated by the numeric argument, like the
15948@value{GDBN} @code{down} command.
8e04817f 15949@end table
c906108c 15950
64fabec2 15951In any source file, the Emacs command @kbd{C-x SPC} (@code{gud-break})
8e04817f 15952tells @value{GDBN} to set a breakpoint on the source line point is on.
c906108c 15953
64fabec2
AC
15954If you type @kbd{M-x speedbar}, then Emacs displays a separate frame which
15955shows a backtrace when the @value{GDBN} I/O buffer is current. Move
15956point to any frame in the stack and type @key{RET} to make it become the
15957current frame and display the associated source in the source buffer.
15958Alternatively, click @kbd{Mouse-2} to make the selected frame become the
15959current one.
15960
8e04817f
AC
15961If you accidentally delete the source-display buffer, an easy way to get
15962it back is to type the command @code{f} in the @value{GDBN} buffer, to
15963request a frame display; when you run under Emacs, this recreates
15964the source buffer if necessary to show you the context of the current
15965frame.
c906108c 15966
8e04817f
AC
15967The source files displayed in Emacs are in ordinary Emacs buffers
15968which are visiting the source files in the usual way. You can edit
15969the files with these buffers if you wish; but keep in mind that @value{GDBN}
15970communicates with Emacs in terms of line numbers. If you add or
15971delete lines from the text, the line numbers that @value{GDBN} knows cease
15972to correspond properly with the code.
b383017d 15973
64fabec2
AC
15974The description given here is for GNU Emacs version 21.3 and a more
15975detailed description of its interaction with @value{GDBN} is given in
15976the Emacs manual (@pxref{Debuggers,,, Emacs, The @sc{gnu} Emacs Manual}).
c906108c 15977
8e04817f
AC
15978@c The following dropped because Epoch is nonstandard. Reactivate
15979@c if/when v19 does something similar. ---doc@cygnus.com 19dec1990
15980@ignore
15981@kindex Emacs Epoch environment
15982@kindex Epoch
15983@kindex inspect
c906108c 15984
8e04817f
AC
15985Version 18 of @sc{gnu} Emacs has a built-in window system
15986called the @code{epoch}
15987environment. Users of this environment can use a new command,
15988@code{inspect} which performs identically to @code{print} except that
15989each value is printed in its own window.
15990@end ignore
c906108c 15991
922fbb7b
AC
15992
15993@node GDB/MI
15994@chapter The @sc{gdb/mi} Interface
15995
15996@unnumberedsec Function and Purpose
15997
15998@cindex @sc{gdb/mi}, its purpose
15999@sc{gdb/mi} is a line based machine oriented text interface to @value{GDBN}. It is
16000specifically intended to support the development of systems which use
16001the debugger as just one small component of a larger system.
16002
16003This chapter is a specification of the @sc{gdb/mi} interface. It is written
16004in the form of a reference manual.
16005
16006Note that @sc{gdb/mi} is still under construction, so some of the
16007features described below are incomplete and subject to change.
16008
16009@unnumberedsec Notation and Terminology
16010
16011@cindex notational conventions, for @sc{gdb/mi}
16012This chapter uses the following notation:
16013
16014@itemize @bullet
16015@item
16016@code{|} separates two alternatives.
16017
16018@item
16019@code{[ @var{something} ]} indicates that @var{something} is optional:
16020it may or may not be given.
16021
16022@item
16023@code{( @var{group} )*} means that @var{group} inside the parentheses
16024may repeat zero or more times.
16025
16026@item
16027@code{( @var{group} )+} means that @var{group} inside the parentheses
16028may repeat one or more times.
16029
16030@item
16031@code{"@var{string}"} means a literal @var{string}.
16032@end itemize
16033
16034@ignore
16035@heading Dependencies
16036@end ignore
16037
16038@heading Acknowledgments
16039
16040In alphabetic order: Andrew Cagney, Fernando Nasser, Stan Shebs and
16041Elena Zannoni.
16042
16043@menu
16044* GDB/MI Command Syntax::
16045* GDB/MI Compatibility with CLI::
16046* GDB/MI Output Records::
16047* GDB/MI Command Description Format::
16048* GDB/MI Breakpoint Table Commands::
16049* GDB/MI Data Manipulation::
16050* GDB/MI Program Control::
16051* GDB/MI Miscellaneous Commands::
16052@ignore
16053* GDB/MI Kod Commands::
16054* GDB/MI Memory Overlay Commands::
16055* GDB/MI Signal Handling Commands::
16056@end ignore
16057* GDB/MI Stack Manipulation::
16058* GDB/MI Symbol Query::
16059* GDB/MI Target Manipulation::
16060* GDB/MI Thread Commands::
16061* GDB/MI Tracepoint Commands::
16062* GDB/MI Variable Objects::
16063@end menu
16064
16065@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
16066@node GDB/MI Command Syntax
16067@section @sc{gdb/mi} Command Syntax
16068
16069@menu
16070* GDB/MI Input Syntax::
16071* GDB/MI Output Syntax::
16072* GDB/MI Simple Examples::
16073@end menu
16074
16075@node GDB/MI Input Syntax
16076@subsection @sc{gdb/mi} Input Syntax
16077
16078@cindex input syntax for @sc{gdb/mi}
16079@cindex @sc{gdb/mi}, input syntax
16080@table @code
16081@item @var{command} @expansion{}
16082@code{@var{cli-command} | @var{mi-command}}
16083
16084@item @var{cli-command} @expansion{}
16085@code{[ @var{token} ] @var{cli-command} @var{nl}}, where
16086@var{cli-command} is any existing @value{GDBN} CLI command.
16087
16088@item @var{mi-command} @expansion{}
16089@code{[ @var{token} ] "-" @var{operation} ( " " @var{option} )*
16090@code{[} " --" @code{]} ( " " @var{parameter} )* @var{nl}}
16091
16092@item @var{token} @expansion{}
16093"any sequence of digits"
16094
16095@item @var{option} @expansion{}
16096@code{"-" @var{parameter} [ " " @var{parameter} ]}
16097
16098@item @var{parameter} @expansion{}
16099@code{@var{non-blank-sequence} | @var{c-string}}
16100
16101@item @var{operation} @expansion{}
16102@emph{any of the operations described in this chapter}
16103
16104@item @var{non-blank-sequence} @expansion{}
16105@emph{anything, provided it doesn't contain special characters such as
16106"-", @var{nl}, """ and of course " "}
16107
16108@item @var{c-string} @expansion{}
16109@code{""" @var{seven-bit-iso-c-string-content} """}
16110
16111@item @var{nl} @expansion{}
16112@code{CR | CR-LF}
16113@end table
16114
16115@noindent
16116Notes:
16117
16118@itemize @bullet
16119@item
16120The CLI commands are still handled by the @sc{mi} interpreter; their
16121output is described below.
16122
16123@item
16124The @code{@var{token}}, when present, is passed back when the command
16125finishes.
16126
16127@item
16128Some @sc{mi} commands accept optional arguments as part of the parameter
16129list. Each option is identified by a leading @samp{-} (dash) and may be
16130followed by an optional argument parameter. Options occur first in the
16131parameter list and can be delimited from normal parameters using
16132@samp{--} (this is useful when some parameters begin with a dash).
16133@end itemize
16134
16135Pragmatics:
16136
16137@itemize @bullet
16138@item
16139We want easy access to the existing CLI syntax (for debugging).
16140
16141@item
16142We want it to be easy to spot a @sc{mi} operation.
16143@end itemize
16144
16145@node GDB/MI Output Syntax
16146@subsection @sc{gdb/mi} Output Syntax
16147
16148@cindex output syntax of @sc{gdb/mi}
16149@cindex @sc{gdb/mi}, output syntax
16150The output from @sc{gdb/mi} consists of zero or more out-of-band records
16151followed, optionally, by a single result record. This result record
16152is for the most recent command. The sequence of output records is
16153terminated by @samp{(@value{GDBP})}.
16154
16155If an input command was prefixed with a @code{@var{token}} then the
16156corresponding output for that command will also be prefixed by that same
16157@var{token}.
16158
16159@table @code
16160@item @var{output} @expansion{}
f7dc1244 16161@code{( @var{out-of-band-record} )* [ @var{result-record} ] "(@value{GDBP})" @var{nl}}
922fbb7b
AC
16162
16163@item @var{result-record} @expansion{}
16164@code{ [ @var{token} ] "^" @var{result-class} ( "," @var{result} )* @var{nl}}
16165
16166@item @var{out-of-band-record} @expansion{}
16167@code{@var{async-record} | @var{stream-record}}
16168
16169@item @var{async-record} @expansion{}
16170@code{@var{exec-async-output} | @var{status-async-output} | @var{notify-async-output}}
16171
16172@item @var{exec-async-output} @expansion{}
16173@code{[ @var{token} ] "*" @var{async-output}}
16174
16175@item @var{status-async-output} @expansion{}
16176@code{[ @var{token} ] "+" @var{async-output}}
16177
16178@item @var{notify-async-output} @expansion{}
16179@code{[ @var{token} ] "=" @var{async-output}}
16180
16181@item @var{async-output} @expansion{}
16182@code{@var{async-class} ( "," @var{result} )* @var{nl}}
16183
16184@item @var{result-class} @expansion{}
16185@code{"done" | "running" | "connected" | "error" | "exit"}
16186
16187@item @var{async-class} @expansion{}
16188@code{"stopped" | @var{others}} (where @var{others} will be added
16189depending on the needs---this is still in development).
16190
16191@item @var{result} @expansion{}
16192@code{ @var{variable} "=" @var{value}}
16193
16194@item @var{variable} @expansion{}
16195@code{ @var{string} }
16196
16197@item @var{value} @expansion{}
16198@code{ @var{const} | @var{tuple} | @var{list} }
16199
16200@item @var{const} @expansion{}
16201@code{@var{c-string}}
16202
16203@item @var{tuple} @expansion{}
16204@code{ "@{@}" | "@{" @var{result} ( "," @var{result} )* "@}" }
16205
16206@item @var{list} @expansion{}
16207@code{ "[]" | "[" @var{value} ( "," @var{value} )* "]" | "["
16208@var{result} ( "," @var{result} )* "]" }
16209
16210@item @var{stream-record} @expansion{}
16211@code{@var{console-stream-output} | @var{target-stream-output} | @var{log-stream-output}}
16212
16213@item @var{console-stream-output} @expansion{}
16214@code{"~" @var{c-string}}
16215
16216@item @var{target-stream-output} @expansion{}
16217@code{"@@" @var{c-string}}
16218
16219@item @var{log-stream-output} @expansion{}
16220@code{"&" @var{c-string}}
16221
16222@item @var{nl} @expansion{}
16223@code{CR | CR-LF}
16224
16225@item @var{token} @expansion{}
16226@emph{any sequence of digits}.
16227@end table
16228
16229@noindent
16230Notes:
16231
16232@itemize @bullet
16233@item
16234All output sequences end in a single line containing a period.
16235
16236@item
16237The @code{@var{token}} is from the corresponding request. If an execution
16238command is interrupted by the @samp{-exec-interrupt} command, the
16239@var{token} associated with the @samp{*stopped} message is the one of the
16240original execution command, not the one of the interrupt command.
16241
16242@item
16243@cindex status output in @sc{gdb/mi}
16244@var{status-async-output} contains on-going status information about the
16245progress of a slow operation. It can be discarded. All status output is
16246prefixed by @samp{+}.
16247
16248@item
16249@cindex async output in @sc{gdb/mi}
16250@var{exec-async-output} contains asynchronous state change on the target
16251(stopped, started, disappeared). All async output is prefixed by
16252@samp{*}.
16253
16254@item
16255@cindex notify output in @sc{gdb/mi}
16256@var{notify-async-output} contains supplementary information that the
16257client should handle (e.g., a new breakpoint information). All notify
16258output is prefixed by @samp{=}.
16259
16260@item
16261@cindex console output in @sc{gdb/mi}
16262@var{console-stream-output} is output that should be displayed as is in the
16263console. It is the textual response to a CLI command. All the console
16264output is prefixed by @samp{~}.
16265
16266@item
16267@cindex target output in @sc{gdb/mi}
16268@var{target-stream-output} is the output produced by the target program.
16269All the target output is prefixed by @samp{@@}.
16270
16271@item
16272@cindex log output in @sc{gdb/mi}
16273@var{log-stream-output} is output text coming from @value{GDBN}'s internals, for
16274instance messages that should be displayed as part of an error log. All
16275the log output is prefixed by @samp{&}.
16276
16277@item
16278@cindex list output in @sc{gdb/mi}
16279New @sc{gdb/mi} commands should only output @var{lists} containing
16280@var{values}.
16281
16282
16283@end itemize
16284
16285@xref{GDB/MI Stream Records, , @sc{gdb/mi} Stream Records}, for more
16286details about the various output records.
16287
16288@node GDB/MI Simple Examples
16289@subsection Simple Examples of @sc{gdb/mi} Interaction
16290@cindex @sc{gdb/mi}, simple examples
16291
16292This subsection presents several simple examples of interaction using
16293the @sc{gdb/mi} interface. In these examples, @samp{->} means that the
16294following line is passed to @sc{gdb/mi} as input, while @samp{<-} means
16295the output received from @sc{gdb/mi}.
16296
16297@subsubheading Target Stop
16298@c Ummm... There is no "-stop" command. This assumes async, no?
16299Here's an example of stopping the inferior process:
16300
16301@smallexample
16302-> -stop
16303<- (@value{GDBP})
16304@end smallexample
16305
16306@noindent
16307and later:
16308
16309@smallexample
16310<- *stop,reason="stop",address="0x123",source="a.c:123"
16311<- (@value{GDBP})
16312@end smallexample
16313
16314@subsubheading Simple CLI Command
16315
16316Here's an example of a simple CLI command being passed through
16317@sc{gdb/mi} and on to the CLI.
16318
16319@smallexample
16320-> print 1+2
16321<- &"print 1+2\n"
16322<- ~"$1 = 3\n"
16323<- ^done
16324<- (@value{GDBP})
16325@end smallexample
16326
16327@subsubheading Command With Side Effects
16328
16329@smallexample
16330-> -symbol-file xyz.exe
16331<- *breakpoint,nr="3",address="0x123",source="a.c:123"
16332<- (@value{GDBP})
16333@end smallexample
16334
16335@subsubheading A Bad Command
16336
16337Here's what happens if you pass a non-existent command:
16338
16339@smallexample
16340-> -rubbish
16341<- ^error,msg="Undefined MI command: rubbish"
16342<- (@value{GDBP})
16343@end smallexample
16344
16345@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
16346@node GDB/MI Compatibility with CLI
16347@section @sc{gdb/mi} Compatibility with CLI
16348
16349@cindex compatibility, @sc{gdb/mi} and CLI
16350@cindex @sc{gdb/mi}, compatibility with CLI
16351To help users familiar with @value{GDBN}'s existing CLI interface, @sc{gdb/mi}
16352accepts existing CLI commands. As specified by the syntax, such
16353commands can be directly entered into the @sc{gdb/mi} interface and @value{GDBN} will
16354respond.
16355
16356This mechanism is provided as an aid to developers of @sc{gdb/mi}
16357clients and not as a reliable interface into the CLI. Since the command
16358is being interpreteted in an environment that assumes @sc{gdb/mi}
16359behaviour, the exact output of such commands is likely to end up being
16360an un-supported hybrid of @sc{gdb/mi} and CLI output.
16361
16362@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
16363@node GDB/MI Output Records
16364@section @sc{gdb/mi} Output Records
16365
16366@menu
16367* GDB/MI Result Records::
16368* GDB/MI Stream Records::
16369* GDB/MI Out-of-band Records::
16370@end menu
16371
16372@node GDB/MI Result Records
16373@subsection @sc{gdb/mi} Result Records
16374
16375@cindex result records in @sc{gdb/mi}
16376@cindex @sc{gdb/mi}, result records
16377In addition to a number of out-of-band notifications, the response to a
16378@sc{gdb/mi} command includes one of the following result indications:
16379
16380@table @code
16381@findex ^done
16382@item "^done" [ "," @var{results} ]
16383The synchronous operation was successful, @code{@var{results}} are the return
16384values.
16385
16386@item "^running"
16387@findex ^running
16388@c Is this one correct? Should it be an out-of-band notification?
16389The asynchronous operation was successfully started. The target is
16390running.
16391
16392@item "^error" "," @var{c-string}
16393@findex ^error
16394The operation failed. The @code{@var{c-string}} contains the corresponding
16395error message.
16396@end table
16397
16398@node GDB/MI Stream Records
16399@subsection @sc{gdb/mi} Stream Records
16400
16401@cindex @sc{gdb/mi}, stream records
16402@cindex stream records in @sc{gdb/mi}
16403@value{GDBN} internally maintains a number of output streams: the console, the
16404target, and the log. The output intended for each of these streams is
16405funneled through the @sc{gdb/mi} interface using @dfn{stream records}.
16406
16407Each stream record begins with a unique @dfn{prefix character} which
16408identifies its stream (@pxref{GDB/MI Output Syntax, , @sc{gdb/mi} Output
16409Syntax}). In addition to the prefix, each stream record contains a
16410@code{@var{string-output}}. This is either raw text (with an implicit new
16411line) or a quoted C string (which does not contain an implicit newline).
16412
16413@table @code
16414@item "~" @var{string-output}
16415The console output stream contains text that should be displayed in the
16416CLI console window. It contains the textual responses to CLI commands.
16417
16418@item "@@" @var{string-output}
16419The target output stream contains any textual output from the running
16420target.
16421
16422@item "&" @var{string-output}
16423The log stream contains debugging messages being produced by @value{GDBN}'s
16424internals.
16425@end table
16426
16427@node GDB/MI Out-of-band Records
16428@subsection @sc{gdb/mi} Out-of-band Records
16429
16430@cindex out-of-band records in @sc{gdb/mi}
16431@cindex @sc{gdb/mi}, out-of-band records
16432@dfn{Out-of-band} records are used to notify the @sc{gdb/mi} client of
16433additional changes that have occurred. Those changes can either be a
16434consequence of @sc{gdb/mi} (e.g., a breakpoint modified) or a result of
16435target activity (e.g., target stopped).
16436
16437The following is a preliminary list of possible out-of-band records.
16438
16439@table @code
16440@item "*" "stop"
16441@end table
16442
16443
16444@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
16445@node GDB/MI Command Description Format
16446@section @sc{gdb/mi} Command Description Format
16447
16448The remaining sections describe blocks of commands. Each block of
16449commands is laid out in a fashion similar to this section.
16450
16451Note the the line breaks shown in the examples are here only for
16452readability. They don't appear in the real output.
16453Also note that the commands with a non-available example (N.A.@:) are
16454not yet implemented.
16455
16456@subheading Motivation
16457
16458The motivation for this collection of commands.
16459
16460@subheading Introduction
16461
16462A brief introduction to this collection of commands as a whole.
16463
16464@subheading Commands
16465
16466For each command in the block, the following is described:
16467
16468@subsubheading Synopsis
16469
16470@smallexample
16471 -command @var{args}@dots{}
16472@end smallexample
16473
16474@subsubheading @value{GDBN} Command
16475
16476The corresponding @value{GDBN} CLI command.
16477
16478@subsubheading Result
16479
16480@subsubheading Out-of-band
16481
16482@subsubheading Notes
16483
16484@subsubheading Example
16485
16486
16487@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
16488@node GDB/MI Breakpoint Table Commands
16489@section @sc{gdb/mi} Breakpoint table commands
16490
16491@cindex breakpoint commands for @sc{gdb/mi}
16492@cindex @sc{gdb/mi}, breakpoint commands
16493This section documents @sc{gdb/mi} commands for manipulating
16494breakpoints.
16495
16496@subheading The @code{-break-after} Command
16497@findex -break-after
16498
16499@subsubheading Synopsis
16500
16501@smallexample
16502 -break-after @var{number} @var{count}
16503@end smallexample
16504
16505The breakpoint number @var{number} is not in effect until it has been
16506hit @var{count} times. To see how this is reflected in the output of
16507the @samp{-break-list} command, see the description of the
16508@samp{-break-list} command below.
16509
16510@subsubheading @value{GDBN} Command
16511
16512The corresponding @value{GDBN} command is @samp{ignore}.
16513
16514@subsubheading Example
16515
16516@smallexample
16517(@value{GDBP})
16518-break-insert main
16519^done,bkpt=@{number="1",addr="0x000100d0",file="hello.c",line="5"@}
16520(@value{GDBP})
16521-break-after 1 3
16522~
16523^done
16524(@value{GDBP})
16525-break-list
16526^done,BreakpointTable=@{nr_rows="1",nr_cols="6",
16527hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
16528@{width="14",alignment="-1",col_name="type",colhdr="Type"@},
16529@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
16530@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
16531@{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
16532@{width="40",alignment="2",col_name="what",colhdr="What"@}],
16533body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
16534addr="0x000100d0",func="main",file="hello.c",line="5",times="0",
16535ignore="3"@}]@}
16536(@value{GDBP})
16537@end smallexample
16538
16539@ignore
16540@subheading The @code{-break-catch} Command
16541@findex -break-catch
16542
16543@subheading The @code{-break-commands} Command
16544@findex -break-commands
16545@end ignore
16546
16547
16548@subheading The @code{-break-condition} Command
16549@findex -break-condition
16550
16551@subsubheading Synopsis
16552
16553@smallexample
16554 -break-condition @var{number} @var{expr}
16555@end smallexample
16556
16557Breakpoint @var{number} will stop the program only if the condition in
16558@var{expr} is true. The condition becomes part of the
16559@samp{-break-list} output (see the description of the @samp{-break-list}
16560command below).
16561
16562@subsubheading @value{GDBN} Command
16563
16564The corresponding @value{GDBN} command is @samp{condition}.
16565
16566@subsubheading Example
16567
16568@smallexample
16569(@value{GDBP})
16570-break-condition 1 1
16571^done
16572(@value{GDBP})
16573-break-list
16574^done,BreakpointTable=@{nr_rows="1",nr_cols="6",
16575hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
16576@{width="14",alignment="-1",col_name="type",colhdr="Type"@},
16577@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
16578@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
16579@{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
16580@{width="40",alignment="2",col_name="what",colhdr="What"@}],
16581body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
16582addr="0x000100d0",func="main",file="hello.c",line="5",cond="1",
16583times="0",ignore="3"@}]@}
16584(@value{GDBP})
16585@end smallexample
16586
16587@subheading The @code{-break-delete} Command
16588@findex -break-delete
16589
16590@subsubheading Synopsis
16591
16592@smallexample
16593 -break-delete ( @var{breakpoint} )+
16594@end smallexample
16595
16596Delete the breakpoint(s) whose number(s) are specified in the argument
16597list. This is obviously reflected in the breakpoint list.
16598
16599@subsubheading @value{GDBN} command
16600
16601The corresponding @value{GDBN} command is @samp{delete}.
16602
16603@subsubheading Example
16604
16605@smallexample
16606(@value{GDBP})
16607-break-delete 1
16608^done
16609(@value{GDBP})
16610-break-list
16611^done,BreakpointTable=@{nr_rows="0",nr_cols="6",
16612hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
16613@{width="14",alignment="-1",col_name="type",colhdr="Type"@},
16614@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
16615@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
16616@{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
16617@{width="40",alignment="2",col_name="what",colhdr="What"@}],
16618body=[]@}
16619(@value{GDBP})
16620@end smallexample
16621
16622@subheading The @code{-break-disable} Command
16623@findex -break-disable
16624
16625@subsubheading Synopsis
16626
16627@smallexample
16628 -break-disable ( @var{breakpoint} )+
16629@end smallexample
16630
16631Disable the named @var{breakpoint}(s). The field @samp{enabled} in the
16632break list is now set to @samp{n} for the named @var{breakpoint}(s).
16633
16634@subsubheading @value{GDBN} Command
16635
16636The corresponding @value{GDBN} command is @samp{disable}.
16637
16638@subsubheading Example
16639
16640@smallexample
16641(@value{GDBP})
16642-break-disable 2
16643^done
16644(@value{GDBP})
16645-break-list
16646^done,BreakpointTable=@{nr_rows="1",nr_cols="6",
16647hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
16648@{width="14",alignment="-1",col_name="type",colhdr="Type"@},
16649@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
16650@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
16651@{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
16652@{width="40",alignment="2",col_name="what",colhdr="What"@}],
16653body=[bkpt=@{number="2",type="breakpoint",disp="keep",enabled="n",
16654addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@}]@}
16655(@value{GDBP})
16656@end smallexample
16657
16658@subheading The @code{-break-enable} Command
16659@findex -break-enable
16660
16661@subsubheading Synopsis
16662
16663@smallexample
16664 -break-enable ( @var{breakpoint} )+
16665@end smallexample
16666
16667Enable (previously disabled) @var{breakpoint}(s).
16668
16669@subsubheading @value{GDBN} Command
16670
16671The corresponding @value{GDBN} command is @samp{enable}.
16672
16673@subsubheading Example
16674
16675@smallexample
16676(@value{GDBP})
16677-break-enable 2
16678^done
16679(@value{GDBP})
16680-break-list
16681^done,BreakpointTable=@{nr_rows="1",nr_cols="6",
16682hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
16683@{width="14",alignment="-1",col_name="type",colhdr="Type"@},
16684@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
16685@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
16686@{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
16687@{width="40",alignment="2",col_name="what",colhdr="What"@}],
16688body=[bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y",
16689addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@}]@}
16690(@value{GDBP})
16691@end smallexample
16692
16693@subheading The @code{-break-info} Command
16694@findex -break-info
16695
16696@subsubheading Synopsis
16697
16698@smallexample
16699 -break-info @var{breakpoint}
16700@end smallexample
16701
16702@c REDUNDANT???
16703Get information about a single breakpoint.
16704
16705@subsubheading @value{GDBN} command
16706
16707The corresponding @value{GDBN} command is @samp{info break @var{breakpoint}}.
16708
16709@subsubheading Example
16710N.A.
16711
16712@subheading The @code{-break-insert} Command
16713@findex -break-insert
16714
16715@subsubheading Synopsis
16716
16717@smallexample
16718 -break-insert [ -t ] [ -h ] [ -r ]
16719 [ -c @var{condition} ] [ -i @var{ignore-count} ]
16720 [ -p @var{thread} ] [ @var{line} | @var{addr} ]
16721@end smallexample
16722
16723@noindent
16724If specified, @var{line}, can be one of:
16725
16726@itemize @bullet
16727@item function
16728@c @item +offset
16729@c @item -offset
16730@c @item linenum
16731@item filename:linenum
16732@item filename:function
16733@item *address
16734@end itemize
16735
16736The possible optional parameters of this command are:
16737
16738@table @samp
16739@item -t
16740Insert a tempoary breakpoint.
16741@item -h
16742Insert a hardware breakpoint.
16743@item -c @var{condition}
16744Make the breakpoint conditional on @var{condition}.
16745@item -i @var{ignore-count}
16746Initialize the @var{ignore-count}.
16747@item -r
16748Insert a regular breakpoint in all the functions whose names match the
16749given regular expression. Other flags are not applicable to regular
16750expresson.
16751@end table
16752
16753@subsubheading Result
16754
16755The result is in the form:
16756
16757@smallexample
16758 ^done,bkptno="@var{number}",func="@var{funcname}",
16759 file="@var{filename}",line="@var{lineno}"
16760@end smallexample
16761
16762@noindent
16763where @var{number} is the @value{GDBN} number for this breakpoint, @var{funcname}
16764is the name of the function where the breakpoint was inserted,
16765@var{filename} is the name of the source file which contains this
16766function, and @var{lineno} is the source line number within that file.
16767
16768Note: this format is open to change.
16769@c An out-of-band breakpoint instead of part of the result?
16770
16771@subsubheading @value{GDBN} Command
16772
16773The corresponding @value{GDBN} commands are @samp{break}, @samp{tbreak},
16774@samp{hbreak}, @samp{thbreak}, and @samp{rbreak}.
16775
16776@subsubheading Example
16777
16778@smallexample
16779(@value{GDBP})
16780-break-insert main
16781^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",line="4"@}
16782(@value{GDBP})
16783-break-insert -t foo
16784^done,bkpt=@{number="2",addr="0x00010774",file="recursive2.c",line="11"@}
16785(@value{GDBP})
16786-break-list
16787^done,BreakpointTable=@{nr_rows="2",nr_cols="6",
16788hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
16789@{width="14",alignment="-1",col_name="type",colhdr="Type"@},
16790@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
16791@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
16792@{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
16793@{width="40",alignment="2",col_name="what",colhdr="What"@}],
16794body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
16795addr="0x0001072c", func="main",file="recursive2.c",line="4",times="0"@},
16796bkpt=@{number="2",type="breakpoint",disp="del",enabled="y",
16797addr="0x00010774",func="foo",file="recursive2.c",line="11",times="0"@}]@}
16798(@value{GDBP})
16799-break-insert -r foo.*
16800~int foo(int, int);
16801^done,bkpt=@{number="3",addr="0x00010774",file="recursive2.c",line="11"@}
16802(@value{GDBP})
16803@end smallexample
16804
16805@subheading The @code{-break-list} Command
16806@findex -break-list
16807
16808@subsubheading Synopsis
16809
16810@smallexample
16811 -break-list
16812@end smallexample
16813
16814Displays the list of inserted breakpoints, showing the following fields:
16815
16816@table @samp
16817@item Number
16818number of the breakpoint
16819@item Type
16820type of the breakpoint: @samp{breakpoint} or @samp{watchpoint}
16821@item Disposition
16822should the breakpoint be deleted or disabled when it is hit: @samp{keep}
16823or @samp{nokeep}
16824@item Enabled
16825is the breakpoint enabled or no: @samp{y} or @samp{n}
16826@item Address
16827memory location at which the breakpoint is set
16828@item What
16829logical location of the breakpoint, expressed by function name, file
16830name, line number
16831@item Times
16832number of times the breakpoint has been hit
16833@end table
16834
16835If there are no breakpoints or watchpoints, the @code{BreakpointTable}
16836@code{body} field is an empty list.
16837
16838@subsubheading @value{GDBN} Command
16839
16840The corresponding @value{GDBN} command is @samp{info break}.
16841
16842@subsubheading Example
16843
16844@smallexample
16845(@value{GDBP})
16846-break-list
16847^done,BreakpointTable=@{nr_rows="2",nr_cols="6",
16848hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
16849@{width="14",alignment="-1",col_name="type",colhdr="Type"@},
16850@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
16851@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
16852@{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
16853@{width="40",alignment="2",col_name="what",colhdr="What"@}],
16854body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
16855addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@},
16856bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y",
16857addr="0x00010114",func="foo",file="hello.c",line="13",times="0"@}]@}
16858(@value{GDBP})
16859@end smallexample
16860
16861Here's an example of the result when there are no breakpoints:
16862
16863@smallexample
16864(@value{GDBP})
16865-break-list
16866^done,BreakpointTable=@{nr_rows="0",nr_cols="6",
16867hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
16868@{width="14",alignment="-1",col_name="type",colhdr="Type"@},
16869@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
16870@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
16871@{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
16872@{width="40",alignment="2",col_name="what",colhdr="What"@}],
16873body=[]@}
16874(@value{GDBP})
16875@end smallexample
16876
16877@subheading The @code{-break-watch} Command
16878@findex -break-watch
16879
16880@subsubheading Synopsis
16881
16882@smallexample
16883 -break-watch [ -a | -r ]
16884@end smallexample
16885
16886Create a watchpoint. With the @samp{-a} option it will create an
16887@dfn{access} watchpoint, i.e. a watchpoint that triggers either on a
16888read from or on a write to the memory location. With the @samp{-r}
16889option, the watchpoint created is a @dfn{read} watchpoint, i.e. it will
16890trigger only when the memory location is accessed for reading. Without
16891either of the options, the watchpoint created is a regular watchpoint,
16892i.e. it will trigger when the memory location is accessed for writing.
16893@xref{Set Watchpoints, , Setting watchpoints}.
16894
16895Note that @samp{-break-list} will report a single list of watchpoints and
16896breakpoints inserted.
16897
16898@subsubheading @value{GDBN} Command
16899
16900The corresponding @value{GDBN} commands are @samp{watch}, @samp{awatch}, and
16901@samp{rwatch}.
16902
16903@subsubheading Example
16904
16905Setting a watchpoint on a variable in the @code{main} function:
16906
16907@smallexample
16908(@value{GDBP})
16909-break-watch x
16910^done,wpt=@{number="2",exp="x"@}
16911(@value{GDBP})
16912-exec-continue
16913^running
16914^done,reason="watchpoint-trigger",wpt=@{number="2",exp="x"@},
16915value=@{old="-268439212",new="55"@},
16916frame=@{func="main",args=[],file="recursive2.c",line="5"@}
16917(@value{GDBP})
16918@end smallexample
16919
16920Setting a watchpoint on a variable local to a function. @value{GDBN} will stop
16921the program execution twice: first for the variable changing value, then
16922for the watchpoint going out of scope.
16923
16924@smallexample
16925(@value{GDBP})
16926-break-watch C
16927^done,wpt=@{number="5",exp="C"@}
16928(@value{GDBP})
16929-exec-continue
16930^running
16931^done,reason="watchpoint-trigger",
16932wpt=@{number="5",exp="C"@},value=@{old="-276895068",new="3"@},
16933frame=@{func="callee4",args=[],
16934file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="13"@}
16935(@value{GDBP})
16936-exec-continue
16937^running
16938^done,reason="watchpoint-scope",wpnum="5",
16939frame=@{func="callee3",args=[@{name="strarg",
16940value="0x11940 \"A string argument.\""@}],
16941file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
16942(@value{GDBP})
16943@end smallexample
16944
16945Listing breakpoints and watchpoints, at different points in the program
16946execution. Note that once the watchpoint goes out of scope, it is
16947deleted.
16948
16949@smallexample
16950(@value{GDBP})
16951-break-watch C
16952^done,wpt=@{number="2",exp="C"@}
16953(@value{GDBP})
16954-break-list
16955^done,BreakpointTable=@{nr_rows="2",nr_cols="6",
16956hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
16957@{width="14",alignment="-1",col_name="type",colhdr="Type"@},
16958@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
16959@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
16960@{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
16961@{width="40",alignment="2",col_name="what",colhdr="What"@}],
16962body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
16963addr="0x00010734",func="callee4",
16964file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"@},
16965bkpt=@{number="2",type="watchpoint",disp="keep",
16966enabled="y",addr="",what="C",times="0"@}]@}
16967(@value{GDBP})
16968-exec-continue
16969^running
16970^done,reason="watchpoint-trigger",wpt=@{number="2",exp="C"@},
16971value=@{old="-276895068",new="3"@},
16972frame=@{func="callee4",args=[],
16973file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="13"@}
16974(@value{GDBP})
16975-break-list
16976^done,BreakpointTable=@{nr_rows="2",nr_cols="6",
16977hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
16978@{width="14",alignment="-1",col_name="type",colhdr="Type"@},
16979@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
16980@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
16981@{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
16982@{width="40",alignment="2",col_name="what",colhdr="What"@}],
16983body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
16984addr="0x00010734",func="callee4",
16985file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"@},
16986bkpt=@{number="2",type="watchpoint",disp="keep",
16987enabled="y",addr="",what="C",times="-5"@}]@}
16988(@value{GDBP})
16989-exec-continue
16990^running
16991^done,reason="watchpoint-scope",wpnum="2",
16992frame=@{func="callee3",args=[@{name="strarg",
16993value="0x11940 \"A string argument.\""@}],
16994file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
16995(@value{GDBP})
16996-break-list
16997^done,BreakpointTable=@{nr_rows="1",nr_cols="6",
16998hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
16999@{width="14",alignment="-1",col_name="type",colhdr="Type"@},
17000@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
17001@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
17002@{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
17003@{width="40",alignment="2",col_name="what",colhdr="What"@}],
17004body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
17005addr="0x00010734",func="callee4",
17006file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"@}]@}
17007(@value{GDBP})
17008@end smallexample
17009
17010@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
17011@node GDB/MI Data Manipulation
17012@section @sc{gdb/mi} Data Manipulation
17013
17014@cindex data manipulation, in @sc{gdb/mi}
17015@cindex @sc{gdb/mi}, data manipulation
17016This section describes the @sc{gdb/mi} commands that manipulate data:
17017examine memory and registers, evaluate expressions, etc.
17018
17019@c REMOVED FROM THE INTERFACE.
17020@c @subheading -data-assign
17021@c Change the value of a program variable. Plenty of side effects.
17022@c @subsubheading GDB command
17023@c set variable
17024@c @subsubheading Example
17025@c N.A.
17026
17027@subheading The @code{-data-disassemble} Command
17028@findex -data-disassemble
17029
17030@subsubheading Synopsis
17031
17032@smallexample
17033 -data-disassemble
17034 [ -s @var{start-addr} -e @var{end-addr} ]
17035 | [ -f @var{filename} -l @var{linenum} [ -n @var{lines} ] ]
17036 -- @var{mode}
17037@end smallexample
17038
17039@noindent
17040Where:
17041
17042@table @samp
17043@item @var{start-addr}
17044is the beginning address (or @code{$pc})
17045@item @var{end-addr}
17046is the end address
17047@item @var{filename}
17048is the name of the file to disassemble
17049@item @var{linenum}
17050is the line number to disassemble around
17051@item @var{lines}
17052is the the number of disassembly lines to be produced. If it is -1,
17053the whole function will be disassembled, in case no @var{end-addr} is
17054specified. If @var{end-addr} is specified as a non-zero value, and
17055@var{lines} is lower than the number of disassembly lines between
17056@var{start-addr} and @var{end-addr}, only @var{lines} lines are
17057displayed; if @var{lines} is higher than the number of lines between
17058@var{start-addr} and @var{end-addr}, only the lines up to @var{end-addr}
17059are displayed.
17060@item @var{mode}
17061is either 0 (meaning only disassembly) or 1 (meaning mixed source and
17062disassembly).
17063@end table
17064
17065@subsubheading Result
17066
17067The output for each instruction is composed of four fields:
17068
17069@itemize @bullet
17070@item Address
17071@item Func-name
17072@item Offset
17073@item Instruction
17074@end itemize
17075
17076Note that whatever included in the instruction field, is not manipulated
17077directely by @sc{gdb/mi}, i.e. it is not possible to adjust its format.
17078
17079@subsubheading @value{GDBN} Command
17080
17081There's no direct mapping from this command to the CLI.
17082
17083@subsubheading Example
17084
17085Disassemble from the current value of @code{$pc} to @code{$pc + 20}:
17086
17087@smallexample
17088(@value{GDBP})
17089-data-disassemble -s $pc -e "$pc + 20" -- 0
17090^done,
17091asm_insns=[
17092@{address="0x000107c0",func-name="main",offset="4",
17093inst="mov 2, %o0"@},
17094@{address="0x000107c4",func-name="main",offset="8",
17095inst="sethi %hi(0x11800), %o2"@},
17096@{address="0x000107c8",func-name="main",offset="12",
17097inst="or %o2, 0x140, %o1\t! 0x11940 <_lib_version+8>"@},
17098@{address="0x000107cc",func-name="main",offset="16",
17099inst="sethi %hi(0x11800), %o2"@},
17100@{address="0x000107d0",func-name="main",offset="20",
17101inst="or %o2, 0x168, %o4\t! 0x11968 <_lib_version+48>"@}]
17102(@value{GDBP})
17103@end smallexample
17104
17105Disassemble the whole @code{main} function. Line 32 is part of
17106@code{main}.
17107
17108@smallexample
17109-data-disassemble -f basics.c -l 32 -- 0
17110^done,asm_insns=[
17111@{address="0x000107bc",func-name="main",offset="0",
17112inst="save %sp, -112, %sp"@},
17113@{address="0x000107c0",func-name="main",offset="4",
17114inst="mov 2, %o0"@},
17115@{address="0x000107c4",func-name="main",offset="8",
17116inst="sethi %hi(0x11800), %o2"@},
17117[@dots{}]
17118@{address="0x0001081c",func-name="main",offset="96",inst="ret "@},
17119@{address="0x00010820",func-name="main",offset="100",inst="restore "@}]
17120(@value{GDBP})
17121@end smallexample
17122
17123Disassemble 3 instructions from the start of @code{main}:
17124
17125@smallexample
17126(@value{GDBP})
17127-data-disassemble -f basics.c -l 32 -n 3 -- 0
17128^done,asm_insns=[
17129@{address="0x000107bc",func-name="main",offset="0",
17130inst="save %sp, -112, %sp"@},
17131@{address="0x000107c0",func-name="main",offset="4",
17132inst="mov 2, %o0"@},
17133@{address="0x000107c4",func-name="main",offset="8",
17134inst="sethi %hi(0x11800), %o2"@}]
17135(@value{GDBP})
17136@end smallexample
17137
17138Disassemble 3 instructions from the start of @code{main} in mixed mode:
17139
17140@smallexample
17141(@value{GDBP})
17142-data-disassemble -f basics.c -l 32 -n 3 -- 1
17143^done,asm_insns=[
17144src_and_asm_line=@{line="31",
17145file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \
17146 testsuite/gdb.mi/basics.c",line_asm_insn=[
17147@{address="0x000107bc",func-name="main",offset="0",
17148inst="save %sp, -112, %sp"@}]@},
17149src_and_asm_line=@{line="32",
17150file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \
17151 testsuite/gdb.mi/basics.c",line_asm_insn=[
17152@{address="0x000107c0",func-name="main",offset="4",
17153inst="mov 2, %o0"@},
17154@{address="0x000107c4",func-name="main",offset="8",
17155inst="sethi %hi(0x11800), %o2"@}]@}]
17156(@value{GDBP})
17157@end smallexample
17158
17159
17160@subheading The @code{-data-evaluate-expression} Command
17161@findex -data-evaluate-expression
17162
17163@subsubheading Synopsis
17164
17165@smallexample
17166 -data-evaluate-expression @var{expr}
17167@end smallexample
17168
17169Evaluate @var{expr} as an expression. The expression could contain an
17170inferior function call. The function call will execute synchronously.
17171If the expression contains spaces, it must be enclosed in double quotes.
17172
17173@subsubheading @value{GDBN} Command
17174
17175The corresponding @value{GDBN} commands are @samp{print}, @samp{output}, and
17176@samp{call}. In @code{gdbtk} only, there's a corresponding
17177@samp{gdb_eval} command.
17178
17179@subsubheading Example
17180
17181In the following example, the numbers that precede the commands are the
17182@dfn{tokens} described in @ref{GDB/MI Command Syntax, ,@sc{gdb/mi}
17183Command Syntax}. Notice how @sc{gdb/mi} returns the same tokens in its
17184output.
17185
17186@smallexample
17187211-data-evaluate-expression A
17188211^done,value="1"
17189(@value{GDBP})
17190311-data-evaluate-expression &A
17191311^done,value="0xefffeb7c"
17192(@value{GDBP})
17193411-data-evaluate-expression A+3
17194411^done,value="4"
17195(@value{GDBP})
17196511-data-evaluate-expression "A + 3"
17197511^done,value="4"
17198(@value{GDBP})
17199@end smallexample
17200
17201
17202@subheading The @code{-data-list-changed-registers} Command
17203@findex -data-list-changed-registers
17204
17205@subsubheading Synopsis
17206
17207@smallexample
17208 -data-list-changed-registers
17209@end smallexample
17210
17211Display a list of the registers that have changed.
17212
17213@subsubheading @value{GDBN} Command
17214
17215@value{GDBN} doesn't have a direct analog for this command; @code{gdbtk}
17216has the corresponding command @samp{gdb_changed_register_list}.
17217
17218@subsubheading Example
17219
17220On a PPC MBX board:
17221
17222@smallexample
17223(@value{GDBP})
17224-exec-continue
17225^running
17226
17227(@value{GDBP})
17228*stopped,reason="breakpoint-hit",bkptno="1",frame=@{func="main",
17229args=[],file="try.c",line="5"@}
17230(@value{GDBP})
17231-data-list-changed-registers
17232^done,changed-registers=["0","1","2","4","5","6","7","8","9",
17233"10","11","13","14","15","16","17","18","19","20","21","22","23",
17234"24","25","26","27","28","30","31","64","65","66","67","69"]
17235(@value{GDBP})
17236@end smallexample
17237
17238
17239@subheading The @code{-data-list-register-names} Command
17240@findex -data-list-register-names
17241
17242@subsubheading Synopsis
17243
17244@smallexample
17245 -data-list-register-names [ ( @var{regno} )+ ]
17246@end smallexample
17247
17248Show a list of register names for the current target. If no arguments
17249are given, it shows a list of the names of all the registers. If
17250integer numbers are given as arguments, it will print a list of the
17251names of the registers corresponding to the arguments. To ensure
17252consistency between a register name and its number, the output list may
17253include empty register names.
17254
17255@subsubheading @value{GDBN} Command
17256
17257@value{GDBN} does not have a command which corresponds to
17258@samp{-data-list-register-names}. In @code{gdbtk} there is a
17259corresponding command @samp{gdb_regnames}.
17260
17261@subsubheading Example
17262
17263For the PPC MBX board:
17264@smallexample
17265(@value{GDBP})
17266-data-list-register-names
17267^done,register-names=["r0","r1","r2","r3","r4","r5","r6","r7",
17268"r8","r9","r10","r11","r12","r13","r14","r15","r16","r17","r18",
17269"r19","r20","r21","r22","r23","r24","r25","r26","r27","r28","r29",
17270"r30","r31","f0","f1","f2","f3","f4","f5","f6","f7","f8","f9",
17271"f10","f11","f12","f13","f14","f15","f16","f17","f18","f19","f20",
17272"f21","f22","f23","f24","f25","f26","f27","f28","f29","f30","f31",
17273"", "pc","ps","cr","lr","ctr","xer"]
17274(@value{GDBP})
17275-data-list-register-names 1 2 3
17276^done,register-names=["r1","r2","r3"]
17277(@value{GDBP})
17278@end smallexample
17279
17280@subheading The @code{-data-list-register-values} Command
17281@findex -data-list-register-values
17282
17283@subsubheading Synopsis
17284
17285@smallexample
17286 -data-list-register-values @var{fmt} [ ( @var{regno} )*]
17287@end smallexample
17288
17289Display the registers' contents. @var{fmt} is the format according to
17290which the registers' contents are to be returned, followed by an optional
17291list of numbers specifying the registers to display. A missing list of
17292numbers indicates that the contents of all the registers must be returned.
17293
17294Allowed formats for @var{fmt} are:
17295
17296@table @code
17297@item x
17298Hexadecimal
17299@item o
17300Octal
17301@item t
17302Binary
17303@item d
17304Decimal
17305@item r
17306Raw
17307@item N
17308Natural
17309@end table
17310
17311@subsubheading @value{GDBN} Command
17312
17313The corresponding @value{GDBN} commands are @samp{info reg}, @samp{info
17314all-reg}, and (in @code{gdbtk}) @samp{gdb_fetch_registers}.
17315
17316@subsubheading Example
17317
17318For a PPC MBX board (note: line breaks are for readability only, they
17319don't appear in the actual output):
17320
17321@smallexample
17322(@value{GDBP})
17323-data-list-register-values r 64 65
17324^done,register-values=[@{number="64",value="0xfe00a300"@},
17325@{number="65",value="0x00029002"@}]
17326(@value{GDBP})
17327-data-list-register-values x
17328^done,register-values=[@{number="0",value="0xfe0043c8"@},
17329@{number="1",value="0x3fff88"@},@{number="2",value="0xfffffffe"@},
17330@{number="3",value="0x0"@},@{number="4",value="0xa"@},
17331@{number="5",value="0x3fff68"@},@{number="6",value="0x3fff58"@},
17332@{number="7",value="0xfe011e98"@},@{number="8",value="0x2"@},
17333@{number="9",value="0xfa202820"@},@{number="10",value="0xfa202808"@},
17334@{number="11",value="0x1"@},@{number="12",value="0x0"@},
17335@{number="13",value="0x4544"@},@{number="14",value="0xffdfffff"@},
17336@{number="15",value="0xffffffff"@},@{number="16",value="0xfffffeff"@},
17337@{number="17",value="0xefffffed"@},@{number="18",value="0xfffffffe"@},
17338@{number="19",value="0xffffffff"@},@{number="20",value="0xffffffff"@},
17339@{number="21",value="0xffffffff"@},@{number="22",value="0xfffffff7"@},
17340@{number="23",value="0xffffffff"@},@{number="24",value="0xffffffff"@},
17341@{number="25",value="0xffffffff"@},@{number="26",value="0xfffffffb"@},
17342@{number="27",value="0xffffffff"@},@{number="28",value="0xf7bfffff"@},
17343@{number="29",value="0x0"@},@{number="30",value="0xfe010000"@},
17344@{number="31",value="0x0"@},@{number="32",value="0x0"@},
17345@{number="33",value="0x0"@},@{number="34",value="0x0"@},
17346@{number="35",value="0x0"@},@{number="36",value="0x0"@},
17347@{number="37",value="0x0"@},@{number="38",value="0x0"@},
17348@{number="39",value="0x0"@},@{number="40",value="0x0"@},
17349@{number="41",value="0x0"@},@{number="42",value="0x0"@},
17350@{number="43",value="0x0"@},@{number="44",value="0x0"@},
17351@{number="45",value="0x0"@},@{number="46",value="0x0"@},
17352@{number="47",value="0x0"@},@{number="48",value="0x0"@},
17353@{number="49",value="0x0"@},@{number="50",value="0x0"@},
17354@{number="51",value="0x0"@},@{number="52",value="0x0"@},
17355@{number="53",value="0x0"@},@{number="54",value="0x0"@},
17356@{number="55",value="0x0"@},@{number="56",value="0x0"@},
17357@{number="57",value="0x0"@},@{number="58",value="0x0"@},
17358@{number="59",value="0x0"@},@{number="60",value="0x0"@},
17359@{number="61",value="0x0"@},@{number="62",value="0x0"@},
17360@{number="63",value="0x0"@},@{number="64",value="0xfe00a300"@},
17361@{number="65",value="0x29002"@},@{number="66",value="0x202f04b5"@},
17362@{number="67",value="0xfe0043b0"@},@{number="68",value="0xfe00b3e4"@},
17363@{number="69",value="0x20002b03"@}]
17364(@value{GDBP})
17365@end smallexample
17366
17367
17368@subheading The @code{-data-read-memory} Command
17369@findex -data-read-memory
17370
17371@subsubheading Synopsis
17372
17373@smallexample
17374 -data-read-memory [ -o @var{byte-offset} ]
17375 @var{address} @var{word-format} @var{word-size}
17376 @var{nr-rows} @var{nr-cols} [ @var{aschar} ]
17377@end smallexample
17378
17379@noindent
17380where:
17381
17382@table @samp
17383@item @var{address}
17384An expression specifying the address of the first memory word to be
17385read. Complex expressions containing embedded white space should be
17386quoted using the C convention.
17387
17388@item @var{word-format}
17389The format to be used to print the memory words. The notation is the
17390same as for @value{GDBN}'s @code{print} command (@pxref{Output Formats,
17391,Output formats}).
17392
17393@item @var{word-size}
17394The size of each memory word in bytes.
17395
17396@item @var{nr-rows}
17397The number of rows in the output table.
17398
17399@item @var{nr-cols}
17400The number of columns in the output table.
17401
17402@item @var{aschar}
17403If present, indicates that each row should include an @sc{ascii} dump. The
17404value of @var{aschar} is used as a padding character when a byte is not a
17405member of the printable @sc{ascii} character set (printable @sc{ascii}
17406characters are those whose code is between 32 and 126, inclusively).
17407
17408@item @var{byte-offset}
17409An offset to add to the @var{address} before fetching memory.
17410@end table
17411
17412This command displays memory contents as a table of @var{nr-rows} by
17413@var{nr-cols} words, each word being @var{word-size} bytes. In total,
17414@code{@var{nr-rows} * @var{nr-cols} * @var{word-size}} bytes are read
17415(returned as @samp{total-bytes}). Should less than the requested number
17416of bytes be returned by the target, the missing words are identified
17417using @samp{N/A}. The number of bytes read from the target is returned
17418in @samp{nr-bytes} and the starting address used to read memory in
17419@samp{addr}.
17420
17421The address of the next/previous row or page is available in
17422@samp{next-row} and @samp{prev-row}, @samp{next-page} and
17423@samp{prev-page}.
17424
17425@subsubheading @value{GDBN} Command
17426
17427The corresponding @value{GDBN} command is @samp{x}. @code{gdbtk} has
17428@samp{gdb_get_mem} memory read command.
17429
17430@subsubheading Example
17431
17432Read six bytes of memory starting at @code{bytes+6} but then offset by
17433@code{-6} bytes. Format as three rows of two columns. One byte per
17434word. Display each word in hex.
17435
17436@smallexample
17437(@value{GDBP})
174389-data-read-memory -o -6 -- bytes+6 x 1 3 2
174399^done,addr="0x00001390",nr-bytes="6",total-bytes="6",
17440next-row="0x00001396",prev-row="0x0000138e",next-page="0x00001396",
17441prev-page="0x0000138a",memory=[
17442@{addr="0x00001390",data=["0x00","0x01"]@},
17443@{addr="0x00001392",data=["0x02","0x03"]@},
17444@{addr="0x00001394",data=["0x04","0x05"]@}]
17445(@value{GDBP})
17446@end smallexample
17447
17448Read two bytes of memory starting at address @code{shorts + 64} and
17449display as a single word formatted in decimal.
17450
17451@smallexample
17452(@value{GDBP})
174535-data-read-memory shorts+64 d 2 1 1
174545^done,addr="0x00001510",nr-bytes="2",total-bytes="2",
17455next-row="0x00001512",prev-row="0x0000150e",
17456next-page="0x00001512",prev-page="0x0000150e",memory=[
17457@{addr="0x00001510",data=["128"]@}]
17458(@value{GDBP})
17459@end smallexample
17460
17461Read thirty two bytes of memory starting at @code{bytes+16} and format
17462as eight rows of four columns. Include a string encoding with @samp{x}
17463used as the non-printable character.
17464
17465@smallexample
17466(@value{GDBP})
174674-data-read-memory bytes+16 x 1 8 4 x
174684^done,addr="0x000013a0",nr-bytes="32",total-bytes="32",
17469next-row="0x000013c0",prev-row="0x0000139c",
17470next-page="0x000013c0",prev-page="0x00001380",memory=[
17471@{addr="0x000013a0",data=["0x10","0x11","0x12","0x13"],ascii="xxxx"@},
17472@{addr="0x000013a4",data=["0x14","0x15","0x16","0x17"],ascii="xxxx"@},
17473@{addr="0x000013a8",data=["0x18","0x19","0x1a","0x1b"],ascii="xxxx"@},
17474@{addr="0x000013ac",data=["0x1c","0x1d","0x1e","0x1f"],ascii="xxxx"@},
17475@{addr="0x000013b0",data=["0x20","0x21","0x22","0x23"],ascii=" !\"#"@},
17476@{addr="0x000013b4",data=["0x24","0x25","0x26","0x27"],ascii="$%&'"@},
17477@{addr="0x000013b8",data=["0x28","0x29","0x2a","0x2b"],ascii="()*+"@},
17478@{addr="0x000013bc",data=["0x2c","0x2d","0x2e","0x2f"],ascii=",-./"@}]
17479(@value{GDBP})
17480@end smallexample
17481
17482@subheading The @code{-display-delete} Command
17483@findex -display-delete
17484
17485@subsubheading Synopsis
17486
17487@smallexample
17488 -display-delete @var{number}
17489@end smallexample
17490
17491Delete the display @var{number}.
17492
17493@subsubheading @value{GDBN} Command
17494
17495The corresponding @value{GDBN} command is @samp{delete display}.
17496
17497@subsubheading Example
17498N.A.
17499
17500
17501@subheading The @code{-display-disable} Command
17502@findex -display-disable
17503
17504@subsubheading Synopsis
17505
17506@smallexample
17507 -display-disable @var{number}
17508@end smallexample
17509
17510Disable display @var{number}.
17511
17512@subsubheading @value{GDBN} Command
17513
17514The corresponding @value{GDBN} command is @samp{disable display}.
17515
17516@subsubheading Example
17517N.A.
17518
17519
17520@subheading The @code{-display-enable} Command
17521@findex -display-enable
17522
17523@subsubheading Synopsis
17524
17525@smallexample
17526 -display-enable @var{number}
17527@end smallexample
17528
17529Enable display @var{number}.
17530
17531@subsubheading @value{GDBN} Command
17532
17533The corresponding @value{GDBN} command is @samp{enable display}.
17534
17535@subsubheading Example
17536N.A.
17537
17538
17539@subheading The @code{-display-insert} Command
17540@findex -display-insert
17541
17542@subsubheading Synopsis
17543
17544@smallexample
17545 -display-insert @var{expression}
17546@end smallexample
17547
17548Display @var{expression} every time the program stops.
17549
17550@subsubheading @value{GDBN} Command
17551
17552The corresponding @value{GDBN} command is @samp{display}.
17553
17554@subsubheading Example
17555N.A.
17556
17557
17558@subheading The @code{-display-list} Command
17559@findex -display-list
17560
17561@subsubheading Synopsis
17562
17563@smallexample
17564 -display-list
17565@end smallexample
17566
17567List the displays. Do not show the current values.
17568
17569@subsubheading @value{GDBN} Command
17570
17571The corresponding @value{GDBN} command is @samp{info display}.
17572
17573@subsubheading Example
17574N.A.
17575
17576
17577@subheading The @code{-environment-cd} Command
17578@findex -environment-cd
17579
17580@subsubheading Synopsis
17581
17582@smallexample
17583 -environment-cd @var{pathdir}
17584@end smallexample
17585
17586Set @value{GDBN}'s working directory.
17587
17588@subsubheading @value{GDBN} Command
17589
17590The corresponding @value{GDBN} command is @samp{cd}.
17591
17592@subsubheading Example
17593
17594@smallexample
17595(@value{GDBP})
17596-environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
17597^done
17598(@value{GDBP})
17599@end smallexample
17600
17601
17602@subheading The @code{-environment-directory} Command
17603@findex -environment-directory
17604
17605@subsubheading Synopsis
17606
17607@smallexample
17608 -environment-directory [ -r ] [ @var{pathdir} ]+
17609@end smallexample
17610
17611Add directories @var{pathdir} to beginning of search path for source files.
17612If the @samp{-r} option is used, the search path is reset to the default
b383017d 17613search path. If directories @var{pathdir} are supplied in addition to the
922fbb7b
AC
17614@samp{-r} option, the search path is first reset and then addition
17615occurs as normal.
b383017d 17616Multiple directories may be specified, separated by blanks. Specifying
922fbb7b
AC
17617multiple directories in a single command
17618results in the directories added to the beginning of the
17619search path in the same order they were presented in the command.
17620If blanks are needed as
17621part of a directory name, double-quotes should be used around
17622the name. In the command output, the path will show up separated
b383017d 17623by the system directory-separator character. The directory-seperator
922fbb7b
AC
17624character must not be used
17625in any directory name.
17626If no directories are specified, the current search path is displayed.
17627
17628@subsubheading @value{GDBN} Command
17629
17630The corresponding @value{GDBN} command is @samp{dir}.
17631
17632@subsubheading Example
17633
17634@smallexample
17635(@value{GDBP})
17636-environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
17637^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd"
17638(@value{GDBP})
17639-environment-directory ""
17640^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd"
17641(@value{GDBP})
17642-environment-directory -r /home/jjohnstn/src/gdb /usr/src
17643^done,source-path="/home/jjohnstn/src/gdb:/usr/src:$cdir:$cwd"
17644(@value{GDBP})
17645-environment-directory -r
17646^done,source-path="$cdir:$cwd"
17647(@value{GDBP})
17648@end smallexample
17649
17650
17651@subheading The @code{-environment-path} Command
17652@findex -environment-path
17653
17654@subsubheading Synopsis
17655
17656@smallexample
17657 -environment-path [ -r ] [ @var{pathdir} ]+
17658@end smallexample
17659
17660Add directories @var{pathdir} to beginning of search path for object files.
17661If the @samp{-r} option is used, the search path is reset to the original
b383017d
RM
17662search path that existed at gdb start-up. If directories @var{pathdir} are
17663supplied in addition to the
922fbb7b
AC
17664@samp{-r} option, the search path is first reset and then addition
17665occurs as normal.
b383017d 17666Multiple directories may be specified, separated by blanks. Specifying
922fbb7b
AC
17667multiple directories in a single command
17668results in the directories added to the beginning of the
17669search path in the same order they were presented in the command.
17670If blanks are needed as
17671part of a directory name, double-quotes should be used around
17672the name. In the command output, the path will show up separated
b383017d 17673by the system directory-separator character. The directory-seperator
922fbb7b
AC
17674character must not be used
17675in any directory name.
17676If no directories are specified, the current path is displayed.
17677
17678
17679@subsubheading @value{GDBN} Command
17680
17681The corresponding @value{GDBN} command is @samp{path}.
17682
17683@subsubheading Example
17684
17685@smallexample
17686(@value{GDBP})
b383017d 17687-environment-path
922fbb7b
AC
17688^done,path="/usr/bin"
17689(@value{GDBP})
17690-environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb /bin
17691^done,path="/kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb:/bin:/usr/bin"
17692(@value{GDBP})
17693-environment-path -r /usr/local/bin
17694^done,path="/usr/local/bin:/usr/bin"
17695(@value{GDBP})
17696@end smallexample
17697
17698
17699@subheading The @code{-environment-pwd} Command
17700@findex -environment-pwd
17701
17702@subsubheading Synopsis
17703
17704@smallexample
17705 -environment-pwd
17706@end smallexample
17707
17708Show the current working directory.
17709
17710@subsubheading @value{GDBN} command
17711
17712The corresponding @value{GDBN} command is @samp{pwd}.
17713
17714@subsubheading Example
17715
17716@smallexample
17717(@value{GDBP})
17718-environment-pwd
17719^done,cwd="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb"
17720(@value{GDBP})
17721@end smallexample
17722
17723@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
17724@node GDB/MI Program Control
17725@section @sc{gdb/mi} Program control
17726
17727@subsubheading Program termination
17728
17729As a result of execution, the inferior program can run to completion, if
17730it doesn't encounter any breakpoints. In this case the output will
17731include an exit code, if the program has exited exceptionally.
17732
17733@subsubheading Examples
17734
17735@noindent
17736Program exited normally:
17737
17738@smallexample
17739(@value{GDBP})
17740-exec-run
17741^running
17742(@value{GDBP})
17743x = 55
17744*stopped,reason="exited-normally"
17745(@value{GDBP})
17746@end smallexample
17747
17748@noindent
17749Program exited exceptionally:
17750
17751@smallexample
17752(@value{GDBP})
17753-exec-run
17754^running
17755(@value{GDBP})
17756x = 55
17757*stopped,reason="exited",exit-code="01"
17758(@value{GDBP})
17759@end smallexample
17760
17761Another way the program can terminate is if it receives a signal such as
17762@code{SIGINT}. In this case, @sc{gdb/mi} displays this:
17763
17764@smallexample
17765(@value{GDBP})
17766*stopped,reason="exited-signalled",signal-name="SIGINT",
17767signal-meaning="Interrupt"
17768@end smallexample
17769
17770
17771@subheading The @code{-exec-abort} Command
17772@findex -exec-abort
17773
17774@subsubheading Synopsis
17775
17776@smallexample
17777 -exec-abort
17778@end smallexample
17779
17780Kill the inferior running program.
17781
17782@subsubheading @value{GDBN} Command
17783
17784The corresponding @value{GDBN} command is @samp{kill}.
17785
17786@subsubheading Example
17787N.A.
17788
17789
17790@subheading The @code{-exec-arguments} Command
17791@findex -exec-arguments
17792
17793@subsubheading Synopsis
17794
17795@smallexample
17796 -exec-arguments @var{args}
17797@end smallexample
17798
17799Set the inferior program arguments, to be used in the next
17800@samp{-exec-run}.
17801
17802@subsubheading @value{GDBN} Command
17803
17804The corresponding @value{GDBN} command is @samp{set args}.
17805
17806@subsubheading Example
17807
17808@c FIXME!
17809Don't have one around.
17810
17811
17812@subheading The @code{-exec-continue} Command
17813@findex -exec-continue
17814
17815@subsubheading Synopsis
17816
17817@smallexample
17818 -exec-continue
17819@end smallexample
17820
17821Asynchronous command. Resumes the execution of the inferior program
17822until a breakpoint is encountered, or until the inferior exits.
17823
17824@subsubheading @value{GDBN} Command
17825
17826The corresponding @value{GDBN} corresponding is @samp{continue}.
17827
17828@subsubheading Example
17829
17830@smallexample
17831-exec-continue
17832^running
17833(@value{GDBP})
17834@@Hello world
17835*stopped,reason="breakpoint-hit",bkptno="2",frame=@{func="foo",args=[],
17836file="hello.c",line="13"@}
17837(@value{GDBP})
17838@end smallexample
17839
17840
17841@subheading The @code{-exec-finish} Command
17842@findex -exec-finish
17843
17844@subsubheading Synopsis
17845
17846@smallexample
17847 -exec-finish
17848@end smallexample
17849
17850Asynchronous command. Resumes the execution of the inferior program
17851until the current function is exited. Displays the results returned by
17852the function.
17853
17854@subsubheading @value{GDBN} Command
17855
17856The corresponding @value{GDBN} command is @samp{finish}.
17857
17858@subsubheading Example
17859
17860Function returning @code{void}.
17861
17862@smallexample
17863-exec-finish
17864^running
17865(@value{GDBP})
17866@@hello from foo
17867*stopped,reason="function-finished",frame=@{func="main",args=[],
17868file="hello.c",line="7"@}
17869(@value{GDBP})
17870@end smallexample
17871
17872Function returning other than @code{void}. The name of the internal
17873@value{GDBN} variable storing the result is printed, together with the
17874value itself.
17875
17876@smallexample
17877-exec-finish
17878^running
17879(@value{GDBP})
17880*stopped,reason="function-finished",frame=@{addr="0x000107b0",func="foo",
17881args=[@{name="a",value="1"],@{name="b",value="9"@}@},
17882file="recursive2.c",line="14"@},
17883gdb-result-var="$1",return-value="0"
17884(@value{GDBP})
17885@end smallexample
17886
17887
17888@subheading The @code{-exec-interrupt} Command
17889@findex -exec-interrupt
17890
17891@subsubheading Synopsis
17892
17893@smallexample
17894 -exec-interrupt
17895@end smallexample
17896
17897Asynchronous command. Interrupts the background execution of the target.
17898Note how the token associated with the stop message is the one for the
17899execution command that has been interrupted. The token for the interrupt
17900itself only appears in the @samp{^done} output. If the user is trying to
17901interrupt a non-running program, an error message will be printed.
17902
17903@subsubheading @value{GDBN} Command
17904
17905The corresponding @value{GDBN} command is @samp{interrupt}.
17906
17907@subsubheading Example
17908
17909@smallexample
17910(@value{GDBP})
17911111-exec-continue
17912111^running
17913
17914(@value{GDBP})
17915222-exec-interrupt
17916222^done
17917(@value{GDBP})
17918111*stopped,signal-name="SIGINT",signal-meaning="Interrupt",
17919frame=@{addr="0x00010140",func="foo",args=[],file="try.c",line="13"@}
17920(@value{GDBP})
17921
17922(@value{GDBP})
17923-exec-interrupt
17924^error,msg="mi_cmd_exec_interrupt: Inferior not executing."
17925(@value{GDBP})
17926@end smallexample
17927
17928
17929@subheading The @code{-exec-next} Command
17930@findex -exec-next
17931
17932@subsubheading Synopsis
17933
17934@smallexample
17935 -exec-next
17936@end smallexample
17937
17938Asynchronous command. Resumes execution of the inferior program, stopping
17939when the beginning of the next source line is reached.
17940
17941@subsubheading @value{GDBN} Command
17942
17943The corresponding @value{GDBN} command is @samp{next}.
17944
17945@subsubheading Example
17946
17947@smallexample
17948-exec-next
17949^running
17950(@value{GDBP})
17951*stopped,reason="end-stepping-range",line="8",file="hello.c"
17952(@value{GDBP})
17953@end smallexample
17954
17955
17956@subheading The @code{-exec-next-instruction} Command
17957@findex -exec-next-instruction
17958
17959@subsubheading Synopsis
17960
17961@smallexample
17962 -exec-next-instruction
17963@end smallexample
17964
17965Asynchronous command. Executes one machine instruction. If the
17966instruction is a function call continues until the function returns. If
17967the program stops at an instruction in the middle of a source line, the
17968address will be printed as well.
17969
17970@subsubheading @value{GDBN} Command
17971
17972The corresponding @value{GDBN} command is @samp{nexti}.
17973
17974@subsubheading Example
17975
17976@smallexample
17977(@value{GDBP})
17978-exec-next-instruction
17979^running
17980
17981(@value{GDBP})
17982*stopped,reason="end-stepping-range",
17983addr="0x000100d4",line="5",file="hello.c"
17984(@value{GDBP})
17985@end smallexample
17986
17987
17988@subheading The @code{-exec-return} Command
17989@findex -exec-return
17990
17991@subsubheading Synopsis
17992
17993@smallexample
17994 -exec-return
17995@end smallexample
17996
17997Makes current function return immediately. Doesn't execute the inferior.
17998Displays the new current frame.
17999
18000@subsubheading @value{GDBN} Command
18001
18002The corresponding @value{GDBN} command is @samp{return}.
18003
18004@subsubheading Example
18005
18006@smallexample
18007(@value{GDBP})
18008200-break-insert callee4
18009200^done,bkpt=@{number="1",addr="0x00010734",
18010file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@}
18011(@value{GDBP})
18012000-exec-run
18013000^running
18014(@value{GDBP})
18015000*stopped,reason="breakpoint-hit",bkptno="1",
18016frame=@{func="callee4",args=[],
18017file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@}
18018(@value{GDBP})
18019205-break-delete
18020205^done
18021(@value{GDBP})
18022111-exec-return
18023111^done,frame=@{level="0",func="callee3",
18024args=[@{name="strarg",
18025value="0x11940 \"A string argument.\""@}],
18026file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
18027(@value{GDBP})
18028@end smallexample
18029
18030
18031@subheading The @code{-exec-run} Command
18032@findex -exec-run
18033
18034@subsubheading Synopsis
18035
18036@smallexample
18037 -exec-run
18038@end smallexample
18039
18040Asynchronous command. Starts execution of the inferior from the
18041beginning. The inferior executes until either a breakpoint is
18042encountered or the program exits.
18043
18044@subsubheading @value{GDBN} Command
18045
18046The corresponding @value{GDBN} command is @samp{run}.
18047
18048@subsubheading Example
18049
18050@smallexample
18051(@value{GDBP})
18052-break-insert main
18053^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",line="4"@}
18054(@value{GDBP})
18055-exec-run
18056^running
18057(@value{GDBP})
18058*stopped,reason="breakpoint-hit",bkptno="1",
18059frame=@{func="main",args=[],file="recursive2.c",line="4"@}
18060(@value{GDBP})
18061@end smallexample
18062
18063
18064@subheading The @code{-exec-show-arguments} Command
18065@findex -exec-show-arguments
18066
18067@subsubheading Synopsis
18068
18069@smallexample
18070 -exec-show-arguments
18071@end smallexample
18072
18073Print the arguments of the program.
18074
18075@subsubheading @value{GDBN} Command
18076
18077The corresponding @value{GDBN} command is @samp{show args}.
18078
18079@subsubheading Example
18080N.A.
18081
18082@c @subheading -exec-signal
18083
18084@subheading The @code{-exec-step} Command
18085@findex -exec-step
18086
18087@subsubheading Synopsis
18088
18089@smallexample
18090 -exec-step
18091@end smallexample
18092
18093Asynchronous command. Resumes execution of the inferior program, stopping
18094when the beginning of the next source line is reached, if the next
18095source line is not a function call. If it is, stop at the first
18096instruction of the called function.
18097
18098@subsubheading @value{GDBN} Command
18099
18100The corresponding @value{GDBN} command is @samp{step}.
18101
18102@subsubheading Example
18103
18104Stepping into a function:
18105
18106@smallexample
18107-exec-step
18108^running
18109(@value{GDBP})
18110*stopped,reason="end-stepping-range",
18111frame=@{func="foo",args=[@{name="a",value="10"@},
18112@{name="b",value="0"@}],file="recursive2.c",line="11"@}
18113(@value{GDBP})
18114@end smallexample
18115
18116Regular stepping:
18117
18118@smallexample
18119-exec-step
18120^running
18121(@value{GDBP})
18122*stopped,reason="end-stepping-range",line="14",file="recursive2.c"
18123(@value{GDBP})
18124@end smallexample
18125
18126
18127@subheading The @code{-exec-step-instruction} Command
18128@findex -exec-step-instruction
18129
18130@subsubheading Synopsis
18131
18132@smallexample
18133 -exec-step-instruction
18134@end smallexample
18135
18136Asynchronous command. Resumes the inferior which executes one machine
18137instruction. The output, once @value{GDBN} has stopped, will vary depending on
18138whether we have stopped in the middle of a source line or not. In the
18139former case, the address at which the program stopped will be printed as
18140well.
18141
18142@subsubheading @value{GDBN} Command
18143
18144The corresponding @value{GDBN} command is @samp{stepi}.
18145
18146@subsubheading Example
18147
18148@smallexample
18149(@value{GDBP})
18150-exec-step-instruction
18151^running
18152
18153(@value{GDBP})
18154*stopped,reason="end-stepping-range",
18155frame=@{func="foo",args=[],file="try.c",line="10"@}
18156(@value{GDBP})
18157-exec-step-instruction
18158^running
18159
18160(@value{GDBP})
18161*stopped,reason="end-stepping-range",
18162frame=@{addr="0x000100f4",func="foo",args=[],file="try.c",line="10"@}
18163(@value{GDBP})
18164@end smallexample
18165
18166
18167@subheading The @code{-exec-until} Command
18168@findex -exec-until
18169
18170@subsubheading Synopsis
18171
18172@smallexample
18173 -exec-until [ @var{location} ]
18174@end smallexample
18175
18176Asynchronous command. Executes the inferior until the @var{location}
18177specified in the argument is reached. If there is no argument, the inferior
18178executes until a source line greater than the current one is reached.
18179The reason for stopping in this case will be @samp{location-reached}.
18180
18181@subsubheading @value{GDBN} Command
18182
18183The corresponding @value{GDBN} command is @samp{until}.
18184
18185@subsubheading Example
18186
18187@smallexample
18188(@value{GDBP})
18189-exec-until recursive2.c:6
18190^running
18191(@value{GDBP})
18192x = 55
18193*stopped,reason="location-reached",frame=@{func="main",args=[],
18194file="recursive2.c",line="6"@}
18195(@value{GDBP})
18196@end smallexample
18197
18198@ignore
18199@subheading -file-clear
18200Is this going away????
18201@end ignore
18202
18203
18204@subheading The @code{-file-exec-and-symbols} Command
18205@findex -file-exec-and-symbols
18206
18207@subsubheading Synopsis
18208
18209@smallexample
18210 -file-exec-and-symbols @var{file}
18211@end smallexample
18212
18213Specify the executable file to be debugged. This file is the one from
18214which the symbol table is also read. If no file is specified, the
18215command clears the executable and symbol information. If breakpoints
18216are set when using this command with no arguments, @value{GDBN} will produce
18217error messages. Otherwise, no output is produced, except a completion
18218notification.
18219
18220@subsubheading @value{GDBN} Command
18221
18222The corresponding @value{GDBN} command is @samp{file}.
18223
18224@subsubheading Example
18225
18226@smallexample
18227(@value{GDBP})
18228-file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
18229^done
18230(@value{GDBP})
18231@end smallexample
18232
18233
18234@subheading The @code{-file-exec-file} Command
18235@findex -file-exec-file
18236
18237@subsubheading Synopsis
18238
18239@smallexample
18240 -file-exec-file @var{file}
18241@end smallexample
18242
18243Specify the executable file to be debugged. Unlike
18244@samp{-file-exec-and-symbols}, the symbol table is @emph{not} read
18245from this file. If used without argument, @value{GDBN} clears the information
18246about the executable file. No output is produced, except a completion
18247notification.
18248
18249@subsubheading @value{GDBN} Command
18250
18251The corresponding @value{GDBN} command is @samp{exec-file}.
18252
18253@subsubheading Example
18254
18255@smallexample
18256(@value{GDBP})
18257-file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
18258^done
18259(@value{GDBP})
18260@end smallexample
18261
18262
18263@subheading The @code{-file-list-exec-sections} Command
18264@findex -file-list-exec-sections
18265
18266@subsubheading Synopsis
18267
18268@smallexample
18269 -file-list-exec-sections
18270@end smallexample
18271
18272List the sections of the current executable file.
18273
18274@subsubheading @value{GDBN} Command
18275
18276The @value{GDBN} command @samp{info file} shows, among the rest, the same
18277information as this command. @code{gdbtk} has a corresponding command
18278@samp{gdb_load_info}.
18279
18280@subsubheading Example
18281N.A.
18282
18283
1abaf70c
BR
18284@subheading The @code{-file-list-exec-source-file} Command
18285@findex -file-list-exec-source-file
18286
18287@subsubheading Synopsis
18288
18289@smallexample
18290 -file-list-exec-source-file
18291@end smallexample
18292
b383017d 18293List the line number, the current source file, and the absolute path
1abaf70c
BR
18294to the current source file for the current executable.
18295
18296@subsubheading @value{GDBN} Command
18297
18298There's no @value{GDBN} command which directly corresponds to this one.
18299
18300@subsubheading Example
18301
18302@smallexample
18303(@value{GDBP})
18304123-file-list-exec-source-file
18305123^done,line="1",file="foo.c",fullname="/home/bar/foo.c"
18306(@value{GDBP})
18307@end smallexample
18308
18309
922fbb7b
AC
18310@subheading The @code{-file-list-exec-source-files} Command
18311@findex -file-list-exec-source-files
18312
18313@subsubheading Synopsis
18314
18315@smallexample
18316 -file-list-exec-source-files
18317@end smallexample
18318
18319List the source files for the current executable.
18320
57c22c6c
BR
18321It will always output the filename, but only when GDB can find the absolute
18322file name of a source file, will it output the fullname.
18323
922fbb7b
AC
18324@subsubheading @value{GDBN} Command
18325
18326There's no @value{GDBN} command which directly corresponds to this one.
18327@code{gdbtk} has an analogous command @samp{gdb_listfiles}.
18328
18329@subsubheading Example
57c22c6c
BR
18330@smallexample
18331(@value{GDBP})
18332-file-list-exec-source-files
18333^done,files=[
18334@{file=foo.c,fullname=/home/foo.c@},
18335@{file=/home/bar.c,fullname=/home/bar.c@},
18336@{file=gdb_could_not_find_fullpath.c@}]
18337(@value{GDBP})
18338@end smallexample
922fbb7b
AC
18339
18340@subheading The @code{-file-list-shared-libraries} Command
18341@findex -file-list-shared-libraries
18342
18343@subsubheading Synopsis
18344
18345@smallexample
18346 -file-list-shared-libraries
18347@end smallexample
18348
18349List the shared libraries in the program.
18350
18351@subsubheading @value{GDBN} Command
18352
18353The corresponding @value{GDBN} command is @samp{info shared}.
18354
18355@subsubheading Example
18356N.A.
18357
18358
18359@subheading The @code{-file-list-symbol-files} Command
18360@findex -file-list-symbol-files
18361
18362@subsubheading Synopsis
18363
18364@smallexample
18365 -file-list-symbol-files
18366@end smallexample
18367
18368List symbol files.
18369
18370@subsubheading @value{GDBN} Command
18371
18372The corresponding @value{GDBN} command is @samp{info file} (part of it).
18373
18374@subsubheading Example
18375N.A.
18376
18377
18378@subheading The @code{-file-symbol-file} Command
18379@findex -file-symbol-file
18380
18381@subsubheading Synopsis
18382
18383@smallexample
18384 -file-symbol-file @var{file}
18385@end smallexample
18386
18387Read symbol table info from the specified @var{file} argument. When
18388used without arguments, clears @value{GDBN}'s symbol table info. No output is
18389produced, except for a completion notification.
18390
18391@subsubheading @value{GDBN} Command
18392
18393The corresponding @value{GDBN} command is @samp{symbol-file}.
18394
18395@subsubheading Example
18396
18397@smallexample
18398(@value{GDBP})
18399-file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
18400^done
18401(@value{GDBP})
18402@end smallexample
18403
18404@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
18405@node GDB/MI Miscellaneous Commands
18406@section Miscellaneous @value{GDBN} commands in @sc{gdb/mi}
18407
18408@c @subheading -gdb-complete
18409
18410@subheading The @code{-gdb-exit} Command
18411@findex -gdb-exit
18412
18413@subsubheading Synopsis
18414
18415@smallexample
18416 -gdb-exit
18417@end smallexample
18418
18419Exit @value{GDBN} immediately.
18420
18421@subsubheading @value{GDBN} Command
18422
18423Approximately corresponds to @samp{quit}.
18424
18425@subsubheading Example
18426
18427@smallexample
18428(@value{GDBP})
18429-gdb-exit
18430@end smallexample
18431
18432@subheading The @code{-gdb-set} Command
18433@findex -gdb-set
18434
18435@subsubheading Synopsis
18436
18437@smallexample
18438 -gdb-set
18439@end smallexample
18440
18441Set an internal @value{GDBN} variable.
18442@c IS THIS A DOLLAR VARIABLE? OR SOMETHING LIKE ANNOTATE ?????
18443
18444@subsubheading @value{GDBN} Command
18445
18446The corresponding @value{GDBN} command is @samp{set}.
18447
18448@subsubheading Example
18449
18450@smallexample
18451(@value{GDBP})
18452-gdb-set $foo=3
18453^done
18454(@value{GDBP})
18455@end smallexample
18456
18457
18458@subheading The @code{-gdb-show} Command
18459@findex -gdb-show
18460
18461@subsubheading Synopsis
18462
18463@smallexample
18464 -gdb-show
18465@end smallexample
18466
18467Show the current value of a @value{GDBN} variable.
18468
18469@subsubheading @value{GDBN} command
18470
18471The corresponding @value{GDBN} command is @samp{show}.
18472
18473@subsubheading Example
18474
18475@smallexample
18476(@value{GDBP})
18477-gdb-show annotate
18478^done,value="0"
18479(@value{GDBP})
18480@end smallexample
18481
18482@c @subheading -gdb-source
18483
18484
18485@subheading The @code{-gdb-version} Command
18486@findex -gdb-version
18487
18488@subsubheading Synopsis
18489
18490@smallexample
18491 -gdb-version
18492@end smallexample
18493
18494Show version information for @value{GDBN}. Used mostly in testing.
18495
18496@subsubheading @value{GDBN} Command
18497
18498There's no equivalent @value{GDBN} command. @value{GDBN} by default shows this
18499information when you start an interactive session.
18500
18501@subsubheading Example
18502
18503@c This example modifies the actual output from GDB to avoid overfull
18504@c box in TeX.
18505@smallexample
18506(@value{GDBP})
18507-gdb-version
18508~GNU gdb 5.2.1
18509~Copyright 2000 Free Software Foundation, Inc.
18510~GDB is free software, covered by the GNU General Public License, and
18511~you are welcome to change it and/or distribute copies of it under
18512~ certain conditions.
18513~Type "show copying" to see the conditions.
18514~There is absolutely no warranty for GDB. Type "show warranty" for
18515~ details.
b383017d 18516~This GDB was configured as
922fbb7b
AC
18517 "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi".
18518^done
18519(@value{GDBP})
18520@end smallexample
18521
18522@subheading The @code{-interpreter-exec} Command
18523@findex -interpreter-exec
18524
18525@subheading Synopsis
18526
18527@smallexample
18528-interpreter-exec @var{interpreter} @var{command}
18529@end smallexample
18530
18531Execute the specified @var{command} in the given @var{interpreter}.
18532
18533@subheading @value{GDBN} Command
18534
18535The corresponding @value{GDBN} command is @samp{interpreter-exec}.
18536
18537@subheading Example
18538
18539@smallexample
18540(@value{GDBP})
18541-interpreter-exec console "break main"
18542&"During symbol reading, couldn't parse type; debugger out of date?.\n"
18543&"During symbol reading, bad structure-type format.\n"
18544~"Breakpoint 1 at 0x8074fc6: file ../../src/gdb/main.c, line 743.\n"
18545^done
18546(@value{GDBP})
18547@end smallexample
18548
18549@ignore
18550@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
18551@node GDB/MI Kod Commands
18552@section @sc{gdb/mi} Kod Commands
18553
18554The Kod commands are not implemented.
18555
18556@c @subheading -kod-info
18557
18558@c @subheading -kod-list
18559
18560@c @subheading -kod-list-object-types
18561
18562@c @subheading -kod-show
18563
18564@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
18565@node GDB/MI Memory Overlay Commands
18566@section @sc{gdb/mi} Memory Overlay Commands
18567
18568The memory overlay commands are not implemented.
18569
18570@c @subheading -overlay-auto
18571
18572@c @subheading -overlay-list-mapping-state
18573
18574@c @subheading -overlay-list-overlays
18575
18576@c @subheading -overlay-map
18577
18578@c @subheading -overlay-off
18579
18580@c @subheading -overlay-on
18581
18582@c @subheading -overlay-unmap
18583
18584@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
18585@node GDB/MI Signal Handling Commands
18586@section @sc{gdb/mi} Signal Handling Commands
18587
18588Signal handling commands are not implemented.
18589
18590@c @subheading -signal-handle
18591
18592@c @subheading -signal-list-handle-actions
18593
18594@c @subheading -signal-list-signal-types
18595@end ignore
18596
18597
18598@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
18599@node GDB/MI Stack Manipulation
18600@section @sc{gdb/mi} Stack Manipulation Commands
18601
18602
18603@subheading The @code{-stack-info-frame} Command
18604@findex -stack-info-frame
18605
18606@subsubheading Synopsis
18607
18608@smallexample
18609 -stack-info-frame
18610@end smallexample
18611
18612Get info on the current frame.
18613
18614@subsubheading @value{GDBN} Command
18615
18616The corresponding @value{GDBN} command is @samp{info frame} or @samp{frame}
18617(without arguments).
18618
18619@subsubheading Example
18620N.A.
18621
18622@subheading The @code{-stack-info-depth} Command
18623@findex -stack-info-depth
18624
18625@subsubheading Synopsis
18626
18627@smallexample
18628 -stack-info-depth [ @var{max-depth} ]
18629@end smallexample
18630
18631Return the depth of the stack. If the integer argument @var{max-depth}
18632is specified, do not count beyond @var{max-depth} frames.
18633
18634@subsubheading @value{GDBN} Command
18635
18636There's no equivalent @value{GDBN} command.
18637
18638@subsubheading Example
18639
18640For a stack with frame levels 0 through 11:
18641
18642@smallexample
18643(@value{GDBP})
18644-stack-info-depth
18645^done,depth="12"
18646(@value{GDBP})
18647-stack-info-depth 4
18648^done,depth="4"
18649(@value{GDBP})
18650-stack-info-depth 12
18651^done,depth="12"
18652(@value{GDBP})
18653-stack-info-depth 11
18654^done,depth="11"
18655(@value{GDBP})
18656-stack-info-depth 13
18657^done,depth="12"
18658(@value{GDBP})
18659@end smallexample
18660
18661@subheading The @code{-stack-list-arguments} Command
18662@findex -stack-list-arguments
18663
18664@subsubheading Synopsis
18665
18666@smallexample
18667 -stack-list-arguments @var{show-values}
18668 [ @var{low-frame} @var{high-frame} ]
18669@end smallexample
18670
18671Display a list of the arguments for the frames between @var{low-frame}
18672and @var{high-frame} (inclusive). If @var{low-frame} and
18673@var{high-frame} are not provided, list the arguments for the whole call
18674stack.
18675
18676The @var{show-values} argument must have a value of 0 or 1. A value of
186770 means that only the names of the arguments are listed, a value of 1
18678means that both names and values of the arguments are printed.
18679
18680@subsubheading @value{GDBN} Command
18681
18682@value{GDBN} does not have an equivalent command. @code{gdbtk} has a
18683@samp{gdb_get_args} command which partially overlaps with the
18684functionality of @samp{-stack-list-arguments}.
18685
18686@subsubheading Example
18687
18688@smallexample
18689(@value{GDBP})
18690-stack-list-frames
18691^done,
18692stack=[
18693frame=@{level="0",addr="0x00010734",func="callee4",
18694file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@},
18695frame=@{level="1",addr="0x0001076c",func="callee3",
18696file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="17"@},
18697frame=@{level="2",addr="0x0001078c",func="callee2",
18698file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="22"@},
18699frame=@{level="3",addr="0x000107b4",func="callee1",
18700file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="27"@},
18701frame=@{level="4",addr="0x000107e0",func="main",
18702file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="32"@}]
18703(@value{GDBP})
18704-stack-list-arguments 0
18705^done,
18706stack-args=[
18707frame=@{level="0",args=[]@},
18708frame=@{level="1",args=[name="strarg"]@},
18709frame=@{level="2",args=[name="intarg",name="strarg"]@},
18710frame=@{level="3",args=[name="intarg",name="strarg",name="fltarg"]@},
18711frame=@{level="4",args=[]@}]
18712(@value{GDBP})
18713-stack-list-arguments 1
18714^done,
18715stack-args=[
18716frame=@{level="0",args=[]@},
18717frame=@{level="1",
18718 args=[@{name="strarg",value="0x11940 \"A string argument.\""@}]@},
18719frame=@{level="2",args=[
18720@{name="intarg",value="2"@},
18721@{name="strarg",value="0x11940 \"A string argument.\""@}]@},
18722@{frame=@{level="3",args=[
18723@{name="intarg",value="2"@},
18724@{name="strarg",value="0x11940 \"A string argument.\""@},
18725@{name="fltarg",value="3.5"@}]@},
18726frame=@{level="4",args=[]@}]
18727(@value{GDBP})
18728-stack-list-arguments 0 2 2
18729^done,stack-args=[frame=@{level="2",args=[name="intarg",name="strarg"]@}]
18730(@value{GDBP})
18731-stack-list-arguments 1 2 2
18732^done,stack-args=[frame=@{level="2",
18733args=[@{name="intarg",value="2"@},
18734@{name="strarg",value="0x11940 \"A string argument.\""@}]@}]
18735(@value{GDBP})
18736@end smallexample
18737
18738@c @subheading -stack-list-exception-handlers
18739
18740
18741@subheading The @code{-stack-list-frames} Command
18742@findex -stack-list-frames
18743
18744@subsubheading Synopsis
18745
18746@smallexample
18747 -stack-list-frames [ @var{low-frame} @var{high-frame} ]
18748@end smallexample
18749
18750List the frames currently on the stack. For each frame it displays the
18751following info:
18752
18753@table @samp
18754@item @var{level}
18755The frame number, 0 being the topmost frame, i.e. the innermost function.
18756@item @var{addr}
18757The @code{$pc} value for that frame.
18758@item @var{func}
18759Function name.
18760@item @var{file}
18761File name of the source file where the function lives.
18762@item @var{line}
18763Line number corresponding to the @code{$pc}.
18764@end table
18765
18766If invoked without arguments, this command prints a backtrace for the
18767whole stack. If given two integer arguments, it shows the frames whose
18768levels are between the two arguments (inclusive). If the two arguments
18769are equal, it shows the single frame at the corresponding level.
18770
18771@subsubheading @value{GDBN} Command
18772
18773The corresponding @value{GDBN} commands are @samp{backtrace} and @samp{where}.
18774
18775@subsubheading Example
18776
18777Full stack backtrace:
18778
18779@smallexample
18780(@value{GDBP})
18781-stack-list-frames
18782^done,stack=
18783[frame=@{level="0",addr="0x0001076c",func="foo",
18784 file="recursive2.c",line="11"@},
18785frame=@{level="1",addr="0x000107a4",func="foo",
18786 file="recursive2.c",line="14"@},
18787frame=@{level="2",addr="0x000107a4",func="foo",
18788 file="recursive2.c",line="14"@},
18789frame=@{level="3",addr="0x000107a4",func="foo",
18790 file="recursive2.c",line="14"@},
18791frame=@{level="4",addr="0x000107a4",func="foo",
18792 file="recursive2.c",line="14"@},
18793frame=@{level="5",addr="0x000107a4",func="foo",
18794 file="recursive2.c",line="14"@},
18795frame=@{level="6",addr="0x000107a4",func="foo",
18796 file="recursive2.c",line="14"@},
18797frame=@{level="7",addr="0x000107a4",func="foo",
18798 file="recursive2.c",line="14"@},
18799frame=@{level="8",addr="0x000107a4",func="foo",
18800 file="recursive2.c",line="14"@},
18801frame=@{level="9",addr="0x000107a4",func="foo",
18802 file="recursive2.c",line="14"@},
18803frame=@{level="10",addr="0x000107a4",func="foo",
18804 file="recursive2.c",line="14"@},
18805frame=@{level="11",addr="0x00010738",func="main",
18806 file="recursive2.c",line="4"@}]
18807(@value{GDBP})
18808@end smallexample
18809
18810Show frames between @var{low_frame} and @var{high_frame}:
18811
18812@smallexample
18813(@value{GDBP})
18814-stack-list-frames 3 5
18815^done,stack=
18816[frame=@{level="3",addr="0x000107a4",func="foo",
18817 file="recursive2.c",line="14"@},
18818frame=@{level="4",addr="0x000107a4",func="foo",
18819 file="recursive2.c",line="14"@},
18820frame=@{level="5",addr="0x000107a4",func="foo",
18821 file="recursive2.c",line="14"@}]
18822(@value{GDBP})
18823@end smallexample
18824
18825Show a single frame:
18826
18827@smallexample
18828(@value{GDBP})
18829-stack-list-frames 3 3
18830^done,stack=
18831[frame=@{level="3",addr="0x000107a4",func="foo",
18832 file="recursive2.c",line="14"@}]
18833(@value{GDBP})
18834@end smallexample
18835
18836
18837@subheading The @code{-stack-list-locals} Command
18838@findex -stack-list-locals
18839
18840@subsubheading Synopsis
18841
18842@smallexample
18843 -stack-list-locals @var{print-values}
18844@end smallexample
18845
18846Display the local variable names for the current frame. With an
bc8ced35
NR
18847argument of 0 or @code{--no-values}, prints only the names of the variables.
18848With argument of 1 or @code{--all-values}, prints also their values. With
18849argument of 2 or @code{--simple-values}, prints the name, type and value for
18850simple data types and the name and type for arrays, structures and
18851unions. In this last case, the idea is that the user can see the
18852value of simple data types immediately and he can create variable
18853objects for other data types if he wishes to explore their values in
18854more detail.
922fbb7b
AC
18855
18856@subsubheading @value{GDBN} Command
18857
18858@samp{info locals} in @value{GDBN}, @samp{gdb_get_locals} in @code{gdbtk}.
18859
18860@subsubheading Example
18861
18862@smallexample
18863(@value{GDBP})
18864-stack-list-locals 0
18865^done,locals=[name="A",name="B",name="C"]
18866(@value{GDBP})
bc8ced35 18867-stack-list-locals --all-values
922fbb7b 18868^done,locals=[@{name="A",value="1"@},@{name="B",value="2"@},
bc8ced35
NR
18869 @{name="C",value="@{1, 2, 3@}"@}]
18870-stack-list-locals --simple-values
18871^done,locals=[@{name="A",type="int",value="1"@},
18872 @{name="B",type="int",value="2"@},@{name="C",type="int [3]"@}]
922fbb7b
AC
18873(@value{GDBP})
18874@end smallexample
18875
18876
18877@subheading The @code{-stack-select-frame} Command
18878@findex -stack-select-frame
18879
18880@subsubheading Synopsis
18881
18882@smallexample
18883 -stack-select-frame @var{framenum}
18884@end smallexample
18885
18886Change the current frame. Select a different frame @var{framenum} on
18887the stack.
18888
18889@subsubheading @value{GDBN} Command
18890
18891The corresponding @value{GDBN} commands are @samp{frame}, @samp{up},
18892@samp{down}, @samp{select-frame}, @samp{up-silent}, and @samp{down-silent}.
18893
18894@subsubheading Example
18895
18896@smallexample
18897(@value{GDBP})
18898-stack-select-frame 2
18899^done
18900(@value{GDBP})
18901@end smallexample
18902
18903@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
18904@node GDB/MI Symbol Query
18905@section @sc{gdb/mi} Symbol Query Commands
18906
18907
18908@subheading The @code{-symbol-info-address} Command
18909@findex -symbol-info-address
18910
18911@subsubheading Synopsis
18912
18913@smallexample
18914 -symbol-info-address @var{symbol}
18915@end smallexample
18916
18917Describe where @var{symbol} is stored.
18918
18919@subsubheading @value{GDBN} Command
18920
18921The corresponding @value{GDBN} command is @samp{info address}.
18922
18923@subsubheading Example
18924N.A.
18925
18926
18927@subheading The @code{-symbol-info-file} Command
18928@findex -symbol-info-file
18929
18930@subsubheading Synopsis
18931
18932@smallexample
18933 -symbol-info-file
18934@end smallexample
18935
18936Show the file for the symbol.
18937
18938@subsubheading @value{GDBN} Command
18939
18940There's no equivalent @value{GDBN} command. @code{gdbtk} has
18941@samp{gdb_find_file}.
18942
18943@subsubheading Example
18944N.A.
18945
18946
18947@subheading The @code{-symbol-info-function} Command
18948@findex -symbol-info-function
18949
18950@subsubheading Synopsis
18951
18952@smallexample
18953 -symbol-info-function
18954@end smallexample
18955
18956Show which function the symbol lives in.
18957
18958@subsubheading @value{GDBN} Command
18959
18960@samp{gdb_get_function} in @code{gdbtk}.
18961
18962@subsubheading Example
18963N.A.
18964
18965
18966@subheading The @code{-symbol-info-line} Command
18967@findex -symbol-info-line
18968
18969@subsubheading Synopsis
18970
18971@smallexample
18972 -symbol-info-line
18973@end smallexample
18974
18975Show the core addresses of the code for a source line.
18976
18977@subsubheading @value{GDBN} Command
18978
71952f4c 18979The corresponding @value{GDBN} command is @samp{info line}.
922fbb7b
AC
18980@code{gdbtk} has the @samp{gdb_get_line} and @samp{gdb_get_file} commands.
18981
18982@subsubheading Example
18983N.A.
18984
18985
18986@subheading The @code{-symbol-info-symbol} Command
18987@findex -symbol-info-symbol
18988
18989@subsubheading Synopsis
18990
18991@smallexample
18992 -symbol-info-symbol @var{addr}
18993@end smallexample
18994
18995Describe what symbol is at location @var{addr}.
18996
18997@subsubheading @value{GDBN} Command
18998
18999The corresponding @value{GDBN} command is @samp{info symbol}.
19000
19001@subsubheading Example
19002N.A.
19003
19004
19005@subheading The @code{-symbol-list-functions} Command
19006@findex -symbol-list-functions
19007
19008@subsubheading Synopsis
19009
19010@smallexample
19011 -symbol-list-functions
19012@end smallexample
19013
19014List the functions in the executable.
19015
19016@subsubheading @value{GDBN} Command
19017
19018@samp{info functions} in @value{GDBN}, @samp{gdb_listfunc} and
19019@samp{gdb_search} in @code{gdbtk}.
19020
19021@subsubheading Example
19022N.A.
19023
19024
32e7087d
JB
19025@subheading The @code{-symbol-list-lines} Command
19026@findex -symbol-list-lines
19027
19028@subsubheading Synopsis
19029
19030@smallexample
19031 -symbol-list-lines @var{filename}
19032@end smallexample
19033
19034Print the list of lines that contain code and their associated program
19035addresses for the given source filename. The entries are sorted in
19036ascending PC order.
19037
19038@subsubheading @value{GDBN} Command
19039
19040There is no corresponding @value{GDBN} command.
19041
19042@subsubheading Example
19043@smallexample
19044(@value{GDBP})
19045-symbol-list-lines basics.c
54ff5908 19046^done,lines=[@{pc="0x08048554",line="7"@},@{pc="0x0804855a",line="8"@}]
32e7087d
JB
19047(@value{GDBP})
19048@end smallexample
19049
19050
922fbb7b
AC
19051@subheading The @code{-symbol-list-types} Command
19052@findex -symbol-list-types
19053
19054@subsubheading Synopsis
19055
19056@smallexample
19057 -symbol-list-types
19058@end smallexample
19059
19060List all the type names.
19061
19062@subsubheading @value{GDBN} Command
19063
19064The corresponding commands are @samp{info types} in @value{GDBN},
19065@samp{gdb_search} in @code{gdbtk}.
19066
19067@subsubheading Example
19068N.A.
19069
19070
19071@subheading The @code{-symbol-list-variables} Command
19072@findex -symbol-list-variables
19073
19074@subsubheading Synopsis
19075
19076@smallexample
19077 -symbol-list-variables
19078@end smallexample
19079
19080List all the global and static variable names.
19081
19082@subsubheading @value{GDBN} Command
19083
19084@samp{info variables} in @value{GDBN}, @samp{gdb_search} in @code{gdbtk}.
19085
19086@subsubheading Example
19087N.A.
19088
19089
19090@subheading The @code{-symbol-locate} Command
19091@findex -symbol-locate
19092
19093@subsubheading Synopsis
19094
19095@smallexample
19096 -symbol-locate
19097@end smallexample
19098
19099@subsubheading @value{GDBN} Command
19100
19101@samp{gdb_loc} in @code{gdbtk}.
19102
19103@subsubheading Example
19104N.A.
19105
19106
19107@subheading The @code{-symbol-type} Command
19108@findex -symbol-type
19109
19110@subsubheading Synopsis
19111
19112@smallexample
19113 -symbol-type @var{variable}
19114@end smallexample
19115
19116Show type of @var{variable}.
19117
19118@subsubheading @value{GDBN} Command
19119
19120The corresponding @value{GDBN} command is @samp{ptype}, @code{gdbtk} has
19121@samp{gdb_obj_variable}.
19122
19123@subsubheading Example
19124N.A.
19125
19126
19127@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
19128@node GDB/MI Target Manipulation
19129@section @sc{gdb/mi} Target Manipulation Commands
19130
19131
19132@subheading The @code{-target-attach} Command
19133@findex -target-attach
19134
19135@subsubheading Synopsis
19136
19137@smallexample
19138 -target-attach @var{pid} | @var{file}
19139@end smallexample
19140
19141Attach to a process @var{pid} or a file @var{file} outside of @value{GDBN}.
19142
19143@subsubheading @value{GDBN} command
19144
19145The corresponding @value{GDBN} command is @samp{attach}.
19146
19147@subsubheading Example
19148N.A.
19149
19150
19151@subheading The @code{-target-compare-sections} Command
19152@findex -target-compare-sections
19153
19154@subsubheading Synopsis
19155
19156@smallexample
19157 -target-compare-sections [ @var{section} ]
19158@end smallexample
19159
19160Compare data of section @var{section} on target to the exec file.
19161Without the argument, all sections are compared.
19162
19163@subsubheading @value{GDBN} Command
19164
19165The @value{GDBN} equivalent is @samp{compare-sections}.
19166
19167@subsubheading Example
19168N.A.
19169
19170
19171@subheading The @code{-target-detach} Command
19172@findex -target-detach
19173
19174@subsubheading Synopsis
19175
19176@smallexample
19177 -target-detach
19178@end smallexample
19179
19180Disconnect from the remote target. There's no output.
19181
19182@subsubheading @value{GDBN} command
19183
19184The corresponding @value{GDBN} command is @samp{detach}.
19185
19186@subsubheading Example
19187
19188@smallexample
19189(@value{GDBP})
19190-target-detach
19191^done
19192(@value{GDBP})
19193@end smallexample
19194
19195
07f31aa6
DJ
19196@subheading The @code{-target-disconnect} Command
19197@findex -target-disconnect
19198
19199@subsubheading Synopsis
19200
19201@example
19202 -target-disconnect
19203@end example
19204
19205Disconnect from the remote target. There's no output.
19206
19207@subsubheading @value{GDBN} command
19208
19209The corresponding @value{GDBN} command is @samp{disconnect}.
19210
19211@subsubheading Example
19212
19213@smallexample
19214(@value{GDBP})
19215-target-disconnect
19216^done
19217(@value{GDBP})
19218@end smallexample
19219
19220
922fbb7b
AC
19221@subheading The @code{-target-download} Command
19222@findex -target-download
19223
19224@subsubheading Synopsis
19225
19226@smallexample
19227 -target-download
19228@end smallexample
19229
19230Loads the executable onto the remote target.
19231It prints out an update message every half second, which includes the fields:
19232
19233@table @samp
19234@item section
19235The name of the section.
19236@item section-sent
19237The size of what has been sent so far for that section.
19238@item section-size
19239The size of the section.
19240@item total-sent
19241The total size of what was sent so far (the current and the previous sections).
19242@item total-size
19243The size of the overall executable to download.
19244@end table
19245
19246@noindent
19247Each message is sent as status record (@pxref{GDB/MI Output Syntax, ,
19248@sc{gdb/mi} Output Syntax}).
19249
19250In addition, it prints the name and size of the sections, as they are
19251downloaded. These messages include the following fields:
19252
19253@table @samp
19254@item section
19255The name of the section.
19256@item section-size
19257The size of the section.
19258@item total-size
19259The size of the overall executable to download.
19260@end table
19261
19262@noindent
19263At the end, a summary is printed.
19264
19265@subsubheading @value{GDBN} Command
19266
19267The corresponding @value{GDBN} command is @samp{load}.
19268
19269@subsubheading Example
19270
19271Note: each status message appears on a single line. Here the messages
19272have been broken down so that they can fit onto a page.
19273
19274@smallexample
19275(@value{GDBP})
19276-target-download
19277+download,@{section=".text",section-size="6668",total-size="9880"@}
19278+download,@{section=".text",section-sent="512",section-size="6668",
19279total-sent="512",total-size="9880"@}
19280+download,@{section=".text",section-sent="1024",section-size="6668",
19281total-sent="1024",total-size="9880"@}
19282+download,@{section=".text",section-sent="1536",section-size="6668",
19283total-sent="1536",total-size="9880"@}
19284+download,@{section=".text",section-sent="2048",section-size="6668",
19285total-sent="2048",total-size="9880"@}
19286+download,@{section=".text",section-sent="2560",section-size="6668",
19287total-sent="2560",total-size="9880"@}
19288+download,@{section=".text",section-sent="3072",section-size="6668",
19289total-sent="3072",total-size="9880"@}
19290+download,@{section=".text",section-sent="3584",section-size="6668",
19291total-sent="3584",total-size="9880"@}
19292+download,@{section=".text",section-sent="4096",section-size="6668",
19293total-sent="4096",total-size="9880"@}
19294+download,@{section=".text",section-sent="4608",section-size="6668",
19295total-sent="4608",total-size="9880"@}
19296+download,@{section=".text",section-sent="5120",section-size="6668",
19297total-sent="5120",total-size="9880"@}
19298+download,@{section=".text",section-sent="5632",section-size="6668",
19299total-sent="5632",total-size="9880"@}
19300+download,@{section=".text",section-sent="6144",section-size="6668",
19301total-sent="6144",total-size="9880"@}
19302+download,@{section=".text",section-sent="6656",section-size="6668",
19303total-sent="6656",total-size="9880"@}
19304+download,@{section=".init",section-size="28",total-size="9880"@}
19305+download,@{section=".fini",section-size="28",total-size="9880"@}
19306+download,@{section=".data",section-size="3156",total-size="9880"@}
19307+download,@{section=".data",section-sent="512",section-size="3156",
19308total-sent="7236",total-size="9880"@}
19309+download,@{section=".data",section-sent="1024",section-size="3156",
19310total-sent="7748",total-size="9880"@}
19311+download,@{section=".data",section-sent="1536",section-size="3156",
19312total-sent="8260",total-size="9880"@}
19313+download,@{section=".data",section-sent="2048",section-size="3156",
19314total-sent="8772",total-size="9880"@}
19315+download,@{section=".data",section-sent="2560",section-size="3156",
19316total-sent="9284",total-size="9880"@}
19317+download,@{section=".data",section-sent="3072",section-size="3156",
19318total-sent="9796",total-size="9880"@}
19319^done,address="0x10004",load-size="9880",transfer-rate="6586",
19320write-rate="429"
19321(@value{GDBP})
19322@end smallexample
19323
19324
19325@subheading The @code{-target-exec-status} Command
19326@findex -target-exec-status
19327
19328@subsubheading Synopsis
19329
19330@smallexample
19331 -target-exec-status
19332@end smallexample
19333
19334Provide information on the state of the target (whether it is running or
19335not, for instance).
19336
19337@subsubheading @value{GDBN} Command
19338
19339There's no equivalent @value{GDBN} command.
19340
19341@subsubheading Example
19342N.A.
19343
19344
19345@subheading The @code{-target-list-available-targets} Command
19346@findex -target-list-available-targets
19347
19348@subsubheading Synopsis
19349
19350@smallexample
19351 -target-list-available-targets
19352@end smallexample
19353
19354List the possible targets to connect to.
19355
19356@subsubheading @value{GDBN} Command
19357
19358The corresponding @value{GDBN} command is @samp{help target}.
19359
19360@subsubheading Example
19361N.A.
19362
19363
19364@subheading The @code{-target-list-current-targets} Command
19365@findex -target-list-current-targets
19366
19367@subsubheading Synopsis
19368
19369@smallexample
19370 -target-list-current-targets
19371@end smallexample
19372
19373Describe the current target.
19374
19375@subsubheading @value{GDBN} Command
19376
19377The corresponding information is printed by @samp{info file} (among
19378other things).
19379
19380@subsubheading Example
19381N.A.
19382
19383
19384@subheading The @code{-target-list-parameters} Command
19385@findex -target-list-parameters
19386
19387@subsubheading Synopsis
19388
19389@smallexample
19390 -target-list-parameters
19391@end smallexample
19392
19393@c ????
19394
19395@subsubheading @value{GDBN} Command
19396
19397No equivalent.
19398
19399@subsubheading Example
19400N.A.
19401
19402
19403@subheading The @code{-target-select} Command
19404@findex -target-select
19405
19406@subsubheading Synopsis
19407
19408@smallexample
19409 -target-select @var{type} @var{parameters @dots{}}
19410@end smallexample
19411
19412Connect @value{GDBN} to the remote target. This command takes two args:
19413
19414@table @samp
19415@item @var{type}
19416The type of target, for instance @samp{async}, @samp{remote}, etc.
19417@item @var{parameters}
19418Device names, host names and the like. @xref{Target Commands, ,
19419Commands for managing targets}, for more details.
19420@end table
19421
19422The output is a connection notification, followed by the address at
19423which the target program is, in the following form:
19424
19425@smallexample
19426^connected,addr="@var{address}",func="@var{function name}",
19427 args=[@var{arg list}]
19428@end smallexample
19429
19430@subsubheading @value{GDBN} Command
19431
19432The corresponding @value{GDBN} command is @samp{target}.
19433
19434@subsubheading Example
19435
19436@smallexample
19437(@value{GDBP})
19438-target-select async /dev/ttya
19439^connected,addr="0xfe00a300",func="??",args=[]
19440(@value{GDBP})
19441@end smallexample
19442
19443@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
19444@node GDB/MI Thread Commands
19445@section @sc{gdb/mi} Thread Commands
19446
19447
19448@subheading The @code{-thread-info} Command
19449@findex -thread-info
19450
19451@subsubheading Synopsis
19452
19453@smallexample
19454 -thread-info
19455@end smallexample
19456
19457@subsubheading @value{GDBN} command
19458
19459No equivalent.
19460
19461@subsubheading Example
19462N.A.
19463
19464
19465@subheading The @code{-thread-list-all-threads} Command
19466@findex -thread-list-all-threads
19467
19468@subsubheading Synopsis
19469
19470@smallexample
19471 -thread-list-all-threads
19472@end smallexample
19473
19474@subsubheading @value{GDBN} Command
19475
19476The equivalent @value{GDBN} command is @samp{info threads}.
19477
19478@subsubheading Example
19479N.A.
19480
19481
19482@subheading The @code{-thread-list-ids} Command
19483@findex -thread-list-ids
19484
19485@subsubheading Synopsis
19486
19487@smallexample
19488 -thread-list-ids
19489@end smallexample
19490
19491Produces a list of the currently known @value{GDBN} thread ids. At the
19492end of the list it also prints the total number of such threads.
19493
19494@subsubheading @value{GDBN} Command
19495
19496Part of @samp{info threads} supplies the same information.
19497
19498@subsubheading Example
19499
19500No threads present, besides the main process:
19501
19502@smallexample
19503(@value{GDBP})
19504-thread-list-ids
19505^done,thread-ids=@{@},number-of-threads="0"
19506(@value{GDBP})
19507@end smallexample
19508
19509
19510Several threads:
19511
19512@smallexample
19513(@value{GDBP})
19514-thread-list-ids
19515^done,thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@},
19516number-of-threads="3"
19517(@value{GDBP})
19518@end smallexample
19519
19520
19521@subheading The @code{-thread-select} Command
19522@findex -thread-select
19523
19524@subsubheading Synopsis
19525
19526@smallexample
19527 -thread-select @var{threadnum}
19528@end smallexample
19529
19530Make @var{threadnum} the current thread. It prints the number of the new
19531current thread, and the topmost frame for that thread.
19532
19533@subsubheading @value{GDBN} Command
19534
19535The corresponding @value{GDBN} command is @samp{thread}.
19536
19537@subsubheading Example
19538
19539@smallexample
19540(@value{GDBP})
19541-exec-next
19542^running
19543(@value{GDBP})
19544*stopped,reason="end-stepping-range",thread-id="2",line="187",
19545file="../../../devo/gdb/testsuite/gdb.threads/linux-dp.c"
19546(@value{GDBP})
19547-thread-list-ids
19548^done,
19549thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@},
19550number-of-threads="3"
19551(@value{GDBP})
19552-thread-select 3
19553^done,new-thread-id="3",
19554frame=@{level="0",func="vprintf",
19555args=[@{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""@},
19556@{name="arg",value="0x2"@}],file="vprintf.c",line="31"@}
19557(@value{GDBP})
19558@end smallexample
19559
19560@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
19561@node GDB/MI Tracepoint Commands
19562@section @sc{gdb/mi} Tracepoint Commands
19563
19564The tracepoint commands are not yet implemented.
19565
19566@c @subheading -trace-actions
19567
19568@c @subheading -trace-delete
19569
19570@c @subheading -trace-disable
19571
19572@c @subheading -trace-dump
19573
19574@c @subheading -trace-enable
19575
19576@c @subheading -trace-exists
19577
19578@c @subheading -trace-find
19579
19580@c @subheading -trace-frame-number
19581
19582@c @subheading -trace-info
19583
19584@c @subheading -trace-insert
19585
19586@c @subheading -trace-list
19587
19588@c @subheading -trace-pass-count
19589
19590@c @subheading -trace-save
19591
19592@c @subheading -trace-start
19593
19594@c @subheading -trace-stop
19595
19596
19597@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
19598@node GDB/MI Variable Objects
19599@section @sc{gdb/mi} Variable Objects
19600
19601
19602@subheading Motivation for Variable Objects in @sc{gdb/mi}
19603
19604For the implementation of a variable debugger window (locals, watched
19605expressions, etc.), we are proposing the adaptation of the existing code
19606used by @code{Insight}.
19607
19608The two main reasons for that are:
19609
19610@enumerate 1
19611@item
19612It has been proven in practice (it is already on its second generation).
19613
19614@item
19615It will shorten development time (needless to say how important it is
19616now).
19617@end enumerate
19618
19619The original interface was designed to be used by Tcl code, so it was
19620slightly changed so it could be used through @sc{gdb/mi}. This section
19621describes the @sc{gdb/mi} operations that will be available and gives some
19622hints about their use.
19623
19624@emph{Note}: In addition to the set of operations described here, we
19625expect the @sc{gui} implementation of a variable window to require, at
19626least, the following operations:
19627
19628@itemize @bullet
19629@item @code{-gdb-show} @code{output-radix}
19630@item @code{-stack-list-arguments}
19631@item @code{-stack-list-locals}
19632@item @code{-stack-select-frame}
19633@end itemize
19634
19635@subheading Introduction to Variable Objects in @sc{gdb/mi}
19636
19637@cindex variable objects in @sc{gdb/mi}
19638The basic idea behind variable objects is the creation of a named object
19639to represent a variable, an expression, a memory location or even a CPU
19640register. For each object created, a set of operations is available for
19641examining or changing its properties.
19642
19643Furthermore, complex data types, such as C structures, are represented
19644in a tree format. For instance, the @code{struct} type variable is the
19645root and the children will represent the struct members. If a child
19646is itself of a complex type, it will also have children of its own.
19647Appropriate language differences are handled for C, C@t{++} and Java.
19648
19649When returning the actual values of the objects, this facility allows
19650for the individual selection of the display format used in the result
19651creation. It can be chosen among: binary, decimal, hexadecimal, octal
19652and natural. Natural refers to a default format automatically
19653chosen based on the variable type (like decimal for an @code{int}, hex
19654for pointers, etc.).
19655
19656The following is the complete set of @sc{gdb/mi} operations defined to
19657access this functionality:
19658
19659@multitable @columnfractions .4 .6
19660@item @strong{Operation}
19661@tab @strong{Description}
19662
19663@item @code{-var-create}
19664@tab create a variable object
19665@item @code{-var-delete}
19666@tab delete the variable object and its children
19667@item @code{-var-set-format}
19668@tab set the display format of this variable
19669@item @code{-var-show-format}
19670@tab show the display format of this variable
19671@item @code{-var-info-num-children}
19672@tab tells how many children this object has
19673@item @code{-var-list-children}
19674@tab return a list of the object's children
19675@item @code{-var-info-type}
19676@tab show the type of this variable object
19677@item @code{-var-info-expression}
19678@tab print what this variable object represents
19679@item @code{-var-show-attributes}
19680@tab is this variable editable? does it exist here?
19681@item @code{-var-evaluate-expression}
19682@tab get the value of this variable
19683@item @code{-var-assign}
19684@tab set the value of this variable
19685@item @code{-var-update}
19686@tab update the variable and its children
19687@end multitable
19688
19689In the next subsection we describe each operation in detail and suggest
19690how it can be used.
19691
19692@subheading Description And Use of Operations on Variable Objects
19693
19694@subheading The @code{-var-create} Command
19695@findex -var-create
19696
19697@subsubheading Synopsis
19698
19699@smallexample
19700 -var-create @{@var{name} | "-"@}
19701 @{@var{frame-addr} | "*"@} @var{expression}
19702@end smallexample
19703
19704This operation creates a variable object, which allows the monitoring of
19705a variable, the result of an expression, a memory cell or a CPU
19706register.
19707
19708The @var{name} parameter is the string by which the object can be
19709referenced. It must be unique. If @samp{-} is specified, the varobj
19710system will generate a string ``varNNNNNN'' automatically. It will be
19711unique provided that one does not specify @var{name} on that format.
19712The command fails if a duplicate name is found.
19713
19714The frame under which the expression should be evaluated can be
19715specified by @var{frame-addr}. A @samp{*} indicates that the current
19716frame should be used.
19717
19718@var{expression} is any expression valid on the current language set (must not
19719begin with a @samp{*}), or one of the following:
19720
19721@itemize @bullet
19722@item
19723@samp{*@var{addr}}, where @var{addr} is the address of a memory cell
19724
19725@item
19726@samp{*@var{addr}-@var{addr}} --- a memory address range (TBD)
19727
19728@item
19729@samp{$@var{regname}} --- a CPU register name
19730@end itemize
19731
19732@subsubheading Result
19733
19734This operation returns the name, number of children and the type of the
19735object created. Type is returned as a string as the ones generated by
19736the @value{GDBN} CLI:
19737
19738@smallexample
19739 name="@var{name}",numchild="N",type="@var{type}"
19740@end smallexample
19741
19742
19743@subheading The @code{-var-delete} Command
19744@findex -var-delete
19745
19746@subsubheading Synopsis
19747
19748@smallexample
19749 -var-delete @var{name}
19750@end smallexample
19751
19752Deletes a previously created variable object and all of its children.
19753
19754Returns an error if the object @var{name} is not found.
19755
19756
19757@subheading The @code{-var-set-format} Command
19758@findex -var-set-format
19759
19760@subsubheading Synopsis
19761
19762@smallexample
19763 -var-set-format @var{name} @var{format-spec}
19764@end smallexample
19765
19766Sets the output format for the value of the object @var{name} to be
19767@var{format-spec}.
19768
19769The syntax for the @var{format-spec} is as follows:
19770
19771@smallexample
19772 @var{format-spec} @expansion{}
19773 @{binary | decimal | hexadecimal | octal | natural@}
19774@end smallexample
19775
19776
19777@subheading The @code{-var-show-format} Command
19778@findex -var-show-format
19779
19780@subsubheading Synopsis
19781
19782@smallexample
19783 -var-show-format @var{name}
19784@end smallexample
19785
19786Returns the format used to display the value of the object @var{name}.
19787
19788@smallexample
19789 @var{format} @expansion{}
19790 @var{format-spec}
19791@end smallexample
19792
19793
19794@subheading The @code{-var-info-num-children} Command
19795@findex -var-info-num-children
19796
19797@subsubheading Synopsis
19798
19799@smallexample
19800 -var-info-num-children @var{name}
19801@end smallexample
19802
19803Returns the number of children of a variable object @var{name}:
19804
19805@smallexample
19806 numchild=@var{n}
19807@end smallexample
19808
19809
19810@subheading The @code{-var-list-children} Command
19811@findex -var-list-children
19812
19813@subsubheading Synopsis
19814
19815@smallexample
bc8ced35 19816 -var-list-children [@var{print-values}] @var{name}
922fbb7b
AC
19817@end smallexample
19818
bc8ced35
NR
19819Returns a list of the children of the specified variable object. With
19820just the variable object name as an argument or with an optional
19821preceding argument of 0 or @code{--no-values}, prints only the names of the
19822variables. With an optional preceding argument of 1 or @code{--all-values},
19823also prints their values.
19824
19825@subsubheading Example
922fbb7b
AC
19826
19827@smallexample
bc8ced35
NR
19828(@value{GDBP})
19829 -var-list-children n
922fbb7b
AC
19830 numchild=@var{n},children=[@{name=@var{name},
19831 numchild=@var{n},type=@var{type}@},@r{(repeats N times)}]
bc8ced35
NR
19832(@value{GDBP})
19833 -var-list-children --all-values n
19834 numchild=@var{n},children=[@{name=@var{name},
19835 numchild=@var{n},value=@var{value},type=@var{type}@},@r{(repeats N times)}]
922fbb7b
AC
19836@end smallexample
19837
19838
19839@subheading The @code{-var-info-type} Command
19840@findex -var-info-type
19841
19842@subsubheading Synopsis
19843
19844@smallexample
19845 -var-info-type @var{name}
19846@end smallexample
19847
19848Returns the type of the specified variable @var{name}. The type is
19849returned as a string in the same format as it is output by the
19850@value{GDBN} CLI:
19851
19852@smallexample
19853 type=@var{typename}
19854@end smallexample
19855
19856
19857@subheading The @code{-var-info-expression} Command
19858@findex -var-info-expression
19859
19860@subsubheading Synopsis
19861
19862@smallexample
19863 -var-info-expression @var{name}
19864@end smallexample
19865
19866Returns what is represented by the variable object @var{name}:
19867
19868@smallexample
19869 lang=@var{lang-spec},exp=@var{expression}
19870@end smallexample
19871
19872@noindent
19873where @var{lang-spec} is @code{@{"C" | "C++" | "Java"@}}.
19874
19875@subheading The @code{-var-show-attributes} Command
19876@findex -var-show-attributes
19877
19878@subsubheading Synopsis
19879
19880@smallexample
19881 -var-show-attributes @var{name}
19882@end smallexample
19883
19884List attributes of the specified variable object @var{name}:
19885
19886@smallexample
19887 status=@var{attr} [ ( ,@var{attr} )* ]
19888@end smallexample
19889
19890@noindent
19891where @var{attr} is @code{@{ @{ editable | noneditable @} | TBD @}}.
19892
19893@subheading The @code{-var-evaluate-expression} Command
19894@findex -var-evaluate-expression
19895
19896@subsubheading Synopsis
19897
19898@smallexample
19899 -var-evaluate-expression @var{name}
19900@end smallexample
19901
19902Evaluates the expression that is represented by the specified variable
19903object and returns its value as a string in the current format specified
19904for the object:
19905
19906@smallexample
19907 value=@var{value}
19908@end smallexample
19909
19910Note that one must invoke @code{-var-list-children} for a variable
19911before the value of a child variable can be evaluated.
19912
19913@subheading The @code{-var-assign} Command
19914@findex -var-assign
19915
19916@subsubheading Synopsis
19917
19918@smallexample
19919 -var-assign @var{name} @var{expression}
19920@end smallexample
19921
19922Assigns the value of @var{expression} to the variable object specified
19923by @var{name}. The object must be @samp{editable}. If the variable's
b383017d 19924value is altered by the assign, the variable will show up in any
922fbb7b
AC
19925subsequent @code{-var-update} list.
19926
19927@subsubheading Example
19928
19929@smallexample
19930(@value{GDBP})
19931-var-assign var1 3
19932^done,value="3"
19933(@value{GDBP})
19934-var-update *
19935^done,changelist=[@{name="var1",in_scope="true",type_changed="false"@}]
19936(@value{GDBP})
19937@end smallexample
19938
19939@subheading The @code{-var-update} Command
19940@findex -var-update
19941
19942@subsubheading Synopsis
19943
19944@smallexample
19945 -var-update @{@var{name} | "*"@}
19946@end smallexample
19947
19948Update the value of the variable object @var{name} by evaluating its
19949expression after fetching all the new values from memory or registers.
19950A @samp{*} causes all existing variable objects to be updated.
19951
19952
19953@node Annotations
19954@chapter @value{GDBN} Annotations
19955
086432e2
AC
19956This chapter describes annotations in @value{GDBN}. Annotations were
19957designed to interface @value{GDBN} to graphical user interfaces or other
19958similar programs which want to interact with @value{GDBN} at a
922fbb7b
AC
19959relatively high level.
19960
086432e2
AC
19961The annotation mechanism has largely been superseeded by @sc{gdb/mi}
19962(@pxref{GDB/MI}).
19963
922fbb7b
AC
19964@ignore
19965This is Edition @value{EDITION}, @value{DATE}.
19966@end ignore
19967
19968@menu
19969* Annotations Overview:: What annotations are; the general syntax.
19970* Server Prefix:: Issuing a command without affecting user state.
922fbb7b
AC
19971* Prompting:: Annotations marking @value{GDBN}'s need for input.
19972* Errors:: Annotations for error messages.
922fbb7b
AC
19973* Invalidation:: Some annotations describe things now invalid.
19974* Annotations for Running::
19975 Whether the program is running, how it stopped, etc.
19976* Source Annotations:: Annotations describing source code.
922fbb7b
AC
19977@end menu
19978
19979@node Annotations Overview
19980@section What is an Annotation?
19981@cindex annotations
19982
922fbb7b
AC
19983Annotations start with a newline character, two @samp{control-z}
19984characters, and the name of the annotation. If there is no additional
19985information associated with this annotation, the name of the annotation
19986is followed immediately by a newline. If there is additional
19987information, the name of the annotation is followed by a space, the
19988additional information, and a newline. The additional information
19989cannot contain newline characters.
19990
19991Any output not beginning with a newline and two @samp{control-z}
19992characters denotes literal output from @value{GDBN}. Currently there is
19993no need for @value{GDBN} to output a newline followed by two
19994@samp{control-z} characters, but if there was such a need, the
19995annotations could be extended with an @samp{escape} annotation which
19996means those three characters as output.
19997
086432e2
AC
19998The annotation @var{level}, which is specified using the
19999@option{--annotate} command line option (@pxref{Mode Options}), controls
20000how much information @value{GDBN} prints together with its prompt,
20001values of expressions, source lines, and other types of output. Level 0
20002is for no anntations, level 1 is for use when @value{GDBN} is run as a
20003subprocess of @sc{gnu} Emacs, level 3 is the maximum annotation suitable
20004for programs that control @value{GDBN}, and level 2 annotations have
20005been made obsolete (@pxref{Limitations, , Limitations of the Annotation
09d4efe1
EZ
20006Interface, annotate, GDB's Obsolete Annotations}).
20007
20008@table @code
20009@kindex set annotate
20010@item set annotate @var{level}
20011The @value{GDB} command @code{set annotate} sets the level of
20012annotations to the specified @var{level}.
9c16f35a
EZ
20013
20014@item show annotate
20015@kindex show annotate
20016Show the current annotation level.
09d4efe1
EZ
20017@end table
20018
20019This chapter describes level 3 annotations.
086432e2 20020
922fbb7b
AC
20021A simple example of starting up @value{GDBN} with annotations is:
20022
20023@smallexample
086432e2
AC
20024$ @kbd{gdb --annotate=3}
20025GNU gdb 6.0
20026Copyright 2003 Free Software Foundation, Inc.
922fbb7b
AC
20027GDB is free software, covered by the GNU General Public License,
20028and you are welcome to change it and/or distribute copies of it
20029under certain conditions.
20030Type "show copying" to see the conditions.
20031There is absolutely no warranty for GDB. Type "show warranty"
20032for details.
086432e2 20033This GDB was configured as "i386-pc-linux-gnu"
922fbb7b
AC
20034
20035^Z^Zpre-prompt
f7dc1244 20036(@value{GDBP})
922fbb7b 20037^Z^Zprompt
086432e2 20038@kbd{quit}
922fbb7b
AC
20039
20040^Z^Zpost-prompt
b383017d 20041$
922fbb7b
AC
20042@end smallexample
20043
20044Here @samp{quit} is input to @value{GDBN}; the rest is output from
20045@value{GDBN}. The three lines beginning @samp{^Z^Z} (where @samp{^Z}
20046denotes a @samp{control-z} character) are annotations; the rest is
20047output from @value{GDBN}.
20048
20049@node Server Prefix
20050@section The Server Prefix
20051@cindex server prefix for annotations
20052
20053To issue a command to @value{GDBN} without affecting certain aspects of
20054the state which is seen by users, prefix it with @samp{server }. This
20055means that this command will not affect the command history, nor will it
20056affect @value{GDBN}'s notion of which command to repeat if @key{RET} is
20057pressed on a line by itself.
20058
20059The server prefix does not affect the recording of values into the value
20060history; to print a value without recording it into the value history,
20061use the @code{output} command instead of the @code{print} command.
20062
922fbb7b
AC
20063@node Prompting
20064@section Annotation for @value{GDBN} Input
20065
20066@cindex annotations for prompts
20067When @value{GDBN} prompts for input, it annotates this fact so it is possible
20068to know when to send output, when the output from a given command is
20069over, etc.
20070
20071Different kinds of input each have a different @dfn{input type}. Each
20072input type has three annotations: a @code{pre-} annotation, which
20073denotes the beginning of any prompt which is being output, a plain
20074annotation, which denotes the end of the prompt, and then a @code{post-}
20075annotation which denotes the end of any echo which may (or may not) be
20076associated with the input. For example, the @code{prompt} input type
20077features the following annotations:
20078
20079@smallexample
20080^Z^Zpre-prompt
20081^Z^Zprompt
20082^Z^Zpost-prompt
20083@end smallexample
20084
20085The input types are
20086
20087@table @code
20088@findex pre-prompt
20089@findex prompt
20090@findex post-prompt
20091@item prompt
20092When @value{GDBN} is prompting for a command (the main @value{GDBN} prompt).
20093
20094@findex pre-commands
20095@findex commands
20096@findex post-commands
20097@item commands
20098When @value{GDBN} prompts for a set of commands, like in the @code{commands}
20099command. The annotations are repeated for each command which is input.
20100
20101@findex pre-overload-choice
20102@findex overload-choice
20103@findex post-overload-choice
20104@item overload-choice
20105When @value{GDBN} wants the user to select between various overloaded functions.
20106
20107@findex pre-query
20108@findex query
20109@findex post-query
20110@item query
20111When @value{GDBN} wants the user to confirm a potentially dangerous operation.
20112
20113@findex pre-prompt-for-continue
20114@findex prompt-for-continue
20115@findex post-prompt-for-continue
20116@item prompt-for-continue
20117When @value{GDBN} is asking the user to press return to continue. Note: Don't
20118expect this to work well; instead use @code{set height 0} to disable
20119prompting. This is because the counting of lines is buggy in the
20120presence of annotations.
20121@end table
20122
20123@node Errors
20124@section Errors
20125@cindex annotations for errors, warnings and interrupts
20126
20127@findex quit
20128@smallexample
20129^Z^Zquit
20130@end smallexample
20131
20132This annotation occurs right before @value{GDBN} responds to an interrupt.
20133
20134@findex error
20135@smallexample
20136^Z^Zerror
20137@end smallexample
20138
20139This annotation occurs right before @value{GDBN} responds to an error.
20140
20141Quit and error annotations indicate that any annotations which @value{GDBN} was
20142in the middle of may end abruptly. For example, if a
20143@code{value-history-begin} annotation is followed by a @code{error}, one
20144cannot expect to receive the matching @code{value-history-end}. One
20145cannot expect not to receive it either, however; an error annotation
20146does not necessarily mean that @value{GDBN} is immediately returning all the way
20147to the top level.
20148
20149@findex error-begin
20150A quit or error annotation may be preceded by
20151
20152@smallexample
20153^Z^Zerror-begin
20154@end smallexample
20155
20156Any output between that and the quit or error annotation is the error
20157message.
20158
20159Warning messages are not yet annotated.
20160@c If we want to change that, need to fix warning(), type_error(),
20161@c range_error(), and possibly other places.
20162
922fbb7b
AC
20163@node Invalidation
20164@section Invalidation Notices
20165
20166@cindex annotations for invalidation messages
20167The following annotations say that certain pieces of state may have
20168changed.
20169
20170@table @code
20171@findex frames-invalid
20172@item ^Z^Zframes-invalid
20173
20174The frames (for example, output from the @code{backtrace} command) may
20175have changed.
20176
20177@findex breakpoints-invalid
20178@item ^Z^Zbreakpoints-invalid
20179
20180The breakpoints may have changed. For example, the user just added or
20181deleted a breakpoint.
20182@end table
20183
20184@node Annotations for Running
20185@section Running the Program
20186@cindex annotations for running programs
20187
20188@findex starting
20189@findex stopping
20190When the program starts executing due to a @value{GDBN} command such as
b383017d 20191@code{step} or @code{continue},
922fbb7b
AC
20192
20193@smallexample
20194^Z^Zstarting
20195@end smallexample
20196
b383017d 20197is output. When the program stops,
922fbb7b
AC
20198
20199@smallexample
20200^Z^Zstopped
20201@end smallexample
20202
20203is output. Before the @code{stopped} annotation, a variety of
20204annotations describe how the program stopped.
20205
20206@table @code
20207@findex exited
20208@item ^Z^Zexited @var{exit-status}
20209The program exited, and @var{exit-status} is the exit status (zero for
20210successful exit, otherwise nonzero).
20211
20212@findex signalled
20213@findex signal-name
20214@findex signal-name-end
20215@findex signal-string
20216@findex signal-string-end
20217@item ^Z^Zsignalled
20218The program exited with a signal. After the @code{^Z^Zsignalled}, the
20219annotation continues:
20220
20221@smallexample
20222@var{intro-text}
20223^Z^Zsignal-name
20224@var{name}
20225^Z^Zsignal-name-end
20226@var{middle-text}
20227^Z^Zsignal-string
20228@var{string}
20229^Z^Zsignal-string-end
20230@var{end-text}
20231@end smallexample
20232
20233@noindent
20234where @var{name} is the name of the signal, such as @code{SIGILL} or
20235@code{SIGSEGV}, and @var{string} is the explanation of the signal, such
20236as @code{Illegal Instruction} or @code{Segmentation fault}.
20237@var{intro-text}, @var{middle-text}, and @var{end-text} are for the
20238user's benefit and have no particular format.
20239
20240@findex signal
20241@item ^Z^Zsignal
20242The syntax of this annotation is just like @code{signalled}, but @value{GDBN} is
20243just saying that the program received the signal, not that it was
20244terminated with it.
20245
20246@findex breakpoint
20247@item ^Z^Zbreakpoint @var{number}
20248The program hit breakpoint number @var{number}.
20249
20250@findex watchpoint
20251@item ^Z^Zwatchpoint @var{number}
20252The program hit watchpoint number @var{number}.
20253@end table
20254
20255@node Source Annotations
20256@section Displaying Source
20257@cindex annotations for source display
20258
20259@findex source
20260The following annotation is used instead of displaying source code:
20261
20262@smallexample
20263^Z^Zsource @var{filename}:@var{line}:@var{character}:@var{middle}:@var{addr}
20264@end smallexample
20265
20266where @var{filename} is an absolute file name indicating which source
20267file, @var{line} is the line number within that file (where 1 is the
20268first line in the file), @var{character} is the character position
20269within the file (where 0 is the first character in the file) (for most
20270debug formats this will necessarily point to the beginning of a line),
20271@var{middle} is @samp{middle} if @var{addr} is in the middle of the
20272line, or @samp{beg} if @var{addr} is at the beginning of the line, and
20273@var{addr} is the address in the target program associated with the
20274source which is being displayed. @var{addr} is in the form @samp{0x}
20275followed by one or more lowercase hex digits (note that this does not
20276depend on the language).
20277
8e04817f
AC
20278@node GDB Bugs
20279@chapter Reporting Bugs in @value{GDBN}
20280@cindex bugs in @value{GDBN}
20281@cindex reporting bugs in @value{GDBN}
c906108c 20282
8e04817f 20283Your bug reports play an essential role in making @value{GDBN} reliable.
c906108c 20284
8e04817f
AC
20285Reporting a bug may help you by bringing a solution to your problem, or it
20286may not. But in any case the principal function of a bug report is to help
20287the entire community by making the next version of @value{GDBN} work better. Bug
20288reports are your contribution to the maintenance of @value{GDBN}.
c906108c 20289
8e04817f
AC
20290In order for a bug report to serve its purpose, you must include the
20291information that enables us to fix the bug.
c4555f82
SC
20292
20293@menu
8e04817f
AC
20294* Bug Criteria:: Have you found a bug?
20295* Bug Reporting:: How to report bugs
c4555f82
SC
20296@end menu
20297
8e04817f
AC
20298@node Bug Criteria
20299@section Have you found a bug?
20300@cindex bug criteria
c4555f82 20301
8e04817f 20302If you are not sure whether you have found a bug, here are some guidelines:
c4555f82
SC
20303
20304@itemize @bullet
8e04817f
AC
20305@cindex fatal signal
20306@cindex debugger crash
20307@cindex crash of debugger
c4555f82 20308@item
8e04817f
AC
20309If the debugger gets a fatal signal, for any input whatever, that is a
20310@value{GDBN} bug. Reliable debuggers never crash.
20311
20312@cindex error on valid input
20313@item
20314If @value{GDBN} produces an error message for valid input, that is a
20315bug. (Note that if you're cross debugging, the problem may also be
20316somewhere in the connection to the target.)
c4555f82 20317
8e04817f 20318@cindex invalid input
c4555f82 20319@item
8e04817f
AC
20320If @value{GDBN} does not produce an error message for invalid input,
20321that is a bug. However, you should note that your idea of
20322``invalid input'' might be our idea of ``an extension'' or ``support
20323for traditional practice''.
20324
20325@item
20326If you are an experienced user of debugging tools, your suggestions
20327for improvement of @value{GDBN} are welcome in any case.
c4555f82
SC
20328@end itemize
20329
8e04817f
AC
20330@node Bug Reporting
20331@section How to report bugs
20332@cindex bug reports
20333@cindex @value{GDBN} bugs, reporting
20334
20335A number of companies and individuals offer support for @sc{gnu} products.
20336If you obtained @value{GDBN} from a support organization, we recommend you
20337contact that organization first.
20338
20339You can find contact information for many support companies and
20340individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs
20341distribution.
20342@c should add a web page ref...
20343
129188f6
AC
20344In any event, we also recommend that you submit bug reports for
20345@value{GDBN}. The prefered method is to submit them directly using
20346@uref{http://www.gnu.org/software/gdb/bugs/, @value{GDBN}'s Bugs web
20347page}. Alternatively, the @email{bug-gdb@@gnu.org, e-mail gateway} can
20348be used.
8e04817f
AC
20349
20350@strong{Do not send bug reports to @samp{info-gdb}, or to
20351@samp{help-gdb}, or to any newsgroups.} Most users of @value{GDBN} do
20352not want to receive bug reports. Those that do have arranged to receive
20353@samp{bug-gdb}.
20354
20355The mailing list @samp{bug-gdb} has a newsgroup @samp{gnu.gdb.bug} which
20356serves as a repeater. The mailing list and the newsgroup carry exactly
20357the same messages. Often people think of posting bug reports to the
20358newsgroup instead of mailing them. This appears to work, but it has one
20359problem which can be crucial: a newsgroup posting often lacks a mail
20360path back to the sender. Thus, if we need to ask for more information,
20361we may be unable to reach you. For this reason, it is better to send
20362bug reports to the mailing list.
c4555f82 20363
8e04817f
AC
20364The fundamental principle of reporting bugs usefully is this:
20365@strong{report all the facts}. If you are not sure whether to state a
20366fact or leave it out, state it!
c4555f82 20367
8e04817f
AC
20368Often people omit facts because they think they know what causes the
20369problem and assume that some details do not matter. Thus, you might
20370assume that the name of the variable you use in an example does not matter.
20371Well, probably it does not, but one cannot be sure. Perhaps the bug is a
20372stray memory reference which happens to fetch from the location where that
20373name is stored in memory; perhaps, if the name were different, the contents
20374of that location would fool the debugger into doing the right thing despite
20375the bug. Play it safe and give a specific, complete example. That is the
20376easiest thing for you to do, and the most helpful.
c4555f82 20377
8e04817f
AC
20378Keep in mind that the purpose of a bug report is to enable us to fix the
20379bug. It may be that the bug has been reported previously, but neither
20380you nor we can know that unless your bug report is complete and
20381self-contained.
c4555f82 20382
8e04817f
AC
20383Sometimes people give a few sketchy facts and ask, ``Does this ring a
20384bell?'' Those bug reports are useless, and we urge everyone to
20385@emph{refuse to respond to them} except to chide the sender to report
20386bugs properly.
20387
20388To enable us to fix the bug, you should include all these things:
c4555f82
SC
20389
20390@itemize @bullet
20391@item
8e04817f
AC
20392The version of @value{GDBN}. @value{GDBN} announces it if you start
20393with no arguments; you can also print it at any time using @code{show
20394version}.
c4555f82 20395
8e04817f
AC
20396Without this, we will not know whether there is any point in looking for
20397the bug in the current version of @value{GDBN}.
c4555f82
SC
20398
20399@item
8e04817f
AC
20400The type of machine you are using, and the operating system name and
20401version number.
c4555f82
SC
20402
20403@item
8e04817f
AC
20404What compiler (and its version) was used to compile @value{GDBN}---e.g.
20405``@value{GCC}--2.8.1''.
c4555f82
SC
20406
20407@item
8e04817f
AC
20408What compiler (and its version) was used to compile the program you are
20409debugging---e.g. ``@value{GCC}--2.8.1'', or ``HP92453-01 A.10.32.03 HP
20410C Compiler''. For GCC, you can say @code{gcc --version} to get this
20411information; for other compilers, see the documentation for those
20412compilers.
c4555f82 20413
8e04817f
AC
20414@item
20415The command arguments you gave the compiler to compile your example and
20416observe the bug. For example, did you use @samp{-O}? To guarantee
20417you will not omit something important, list them all. A copy of the
20418Makefile (or the output from make) is sufficient.
c4555f82 20419
8e04817f
AC
20420If we were to try to guess the arguments, we would probably guess wrong
20421and then we might not encounter the bug.
c4555f82 20422
8e04817f
AC
20423@item
20424A complete input script, and all necessary source files, that will
20425reproduce the bug.
c4555f82 20426
8e04817f
AC
20427@item
20428A description of what behavior you observe that you believe is
20429incorrect. For example, ``It gets a fatal signal.''
c4555f82 20430
8e04817f
AC
20431Of course, if the bug is that @value{GDBN} gets a fatal signal, then we
20432will certainly notice it. But if the bug is incorrect output, we might
20433not notice unless it is glaringly wrong. You might as well not give us
20434a chance to make a mistake.
c4555f82 20435
8e04817f
AC
20436Even if the problem you experience is a fatal signal, you should still
20437say so explicitly. Suppose something strange is going on, such as, your
20438copy of @value{GDBN} is out of synch, or you have encountered a bug in
20439the C library on your system. (This has happened!) Your copy might
20440crash and ours would not. If you told us to expect a crash, then when
20441ours fails to crash, we would know that the bug was not happening for
20442us. If you had not told us to expect a crash, then we would not be able
20443to draw any conclusion from our observations.
c4555f82 20444
e0c07bf0
MC
20445@pindex script
20446@cindex recording a session script
20447To collect all this information, you can use a session recording program
20448such as @command{script}, which is available on many Unix systems.
20449Just run your @value{GDBN} session inside @command{script} and then
20450include the @file{typescript} file with your bug report.
20451
20452Another way to record a @value{GDBN} session is to run @value{GDBN}
20453inside Emacs and then save the entire buffer to a file.
20454
8e04817f
AC
20455@item
20456If you wish to suggest changes to the @value{GDBN} source, send us context
20457diffs. If you even discuss something in the @value{GDBN} source, refer to
20458it by context, not by line number.
c4555f82 20459
8e04817f
AC
20460The line numbers in our development sources will not match those in your
20461sources. Your line numbers would convey no useful information to us.
c4555f82 20462
8e04817f 20463@end itemize
c4555f82 20464
8e04817f 20465Here are some things that are not necessary:
c4555f82 20466
8e04817f
AC
20467@itemize @bullet
20468@item
20469A description of the envelope of the bug.
c4555f82 20470
8e04817f
AC
20471Often people who encounter a bug spend a lot of time investigating
20472which changes to the input file will make the bug go away and which
20473changes will not affect it.
c4555f82 20474
8e04817f
AC
20475This is often time consuming and not very useful, because the way we
20476will find the bug is by running a single example under the debugger
20477with breakpoints, not by pure deduction from a series of examples.
20478We recommend that you save your time for something else.
c4555f82 20479
8e04817f
AC
20480Of course, if you can find a simpler example to report @emph{instead}
20481of the original one, that is a convenience for us. Errors in the
20482output will be easier to spot, running under the debugger will take
20483less time, and so on.
c4555f82 20484
8e04817f
AC
20485However, simplification is not vital; if you do not want to do this,
20486report the bug anyway and send us the entire test case you used.
c4555f82 20487
8e04817f
AC
20488@item
20489A patch for the bug.
c4555f82 20490
8e04817f
AC
20491A patch for the bug does help us if it is a good one. But do not omit
20492the necessary information, such as the test case, on the assumption that
20493a patch is all we need. We might see problems with your patch and decide
20494to fix the problem another way, or we might not understand it at all.
c4555f82 20495
8e04817f
AC
20496Sometimes with a program as complicated as @value{GDBN} it is very hard to
20497construct an example that will make the program follow a certain path
20498through the code. If you do not send us the example, we will not be able
20499to construct one, so we will not be able to verify that the bug is fixed.
c4555f82 20500
8e04817f
AC
20501And if we cannot understand what bug you are trying to fix, or why your
20502patch should be an improvement, we will not install it. A test case will
20503help us to understand.
c4555f82 20504
8e04817f
AC
20505@item
20506A guess about what the bug is or what it depends on.
c4555f82 20507
8e04817f
AC
20508Such guesses are usually wrong. Even we cannot guess right about such
20509things without first using the debugger to find the facts.
20510@end itemize
c4555f82 20511
8e04817f
AC
20512@c The readline documentation is distributed with the readline code
20513@c and consists of the two following files:
20514@c rluser.texinfo
20515@c inc-hist.texinfo
20516@c Use -I with makeinfo to point to the appropriate directory,
20517@c environment var TEXINPUTS with TeX.
20518@include rluser.texinfo
20519@include inc-hist.texinfo
c4555f82 20520
c4555f82 20521
8e04817f
AC
20522@node Formatting Documentation
20523@appendix Formatting Documentation
c4555f82 20524
8e04817f
AC
20525@cindex @value{GDBN} reference card
20526@cindex reference card
20527The @value{GDBN} 4 release includes an already-formatted reference card, ready
20528for printing with PostScript or Ghostscript, in the @file{gdb}
20529subdirectory of the main source directory@footnote{In
20530@file{gdb-@value{GDBVN}/gdb/refcard.ps} of the version @value{GDBVN}
20531release.}. If you can use PostScript or Ghostscript with your printer,
20532you can print the reference card immediately with @file{refcard.ps}.
c4555f82 20533
8e04817f
AC
20534The release also includes the source for the reference card. You
20535can format it, using @TeX{}, by typing:
c4555f82 20536
474c8240 20537@smallexample
8e04817f 20538make refcard.dvi
474c8240 20539@end smallexample
c4555f82 20540
8e04817f
AC
20541The @value{GDBN} reference card is designed to print in @dfn{landscape}
20542mode on US ``letter'' size paper;
20543that is, on a sheet 11 inches wide by 8.5 inches
20544high. You will need to specify this form of printing as an option to
20545your @sc{dvi} output program.
c4555f82 20546
8e04817f 20547@cindex documentation
c4555f82 20548
8e04817f
AC
20549All the documentation for @value{GDBN} comes as part of the machine-readable
20550distribution. The documentation is written in Texinfo format, which is
20551a documentation system that uses a single source file to produce both
20552on-line information and a printed manual. You can use one of the Info
20553formatting commands to create the on-line version of the documentation
20554and @TeX{} (or @code{texi2roff}) to typeset the printed version.
c4555f82 20555
8e04817f
AC
20556@value{GDBN} includes an already formatted copy of the on-line Info
20557version of this manual in the @file{gdb} subdirectory. The main Info
20558file is @file{gdb-@value{GDBVN}/gdb/gdb.info}, and it refers to
20559subordinate files matching @samp{gdb.info*} in the same directory. If
20560necessary, you can print out these files, or read them with any editor;
20561but they are easier to read using the @code{info} subsystem in @sc{gnu}
20562Emacs or the standalone @code{info} program, available as part of the
20563@sc{gnu} Texinfo distribution.
c4555f82 20564
8e04817f
AC
20565If you want to format these Info files yourself, you need one of the
20566Info formatting programs, such as @code{texinfo-format-buffer} or
20567@code{makeinfo}.
c4555f82 20568
8e04817f
AC
20569If you have @code{makeinfo} installed, and are in the top level
20570@value{GDBN} source directory (@file{gdb-@value{GDBVN}}, in the case of
20571version @value{GDBVN}), you can make the Info file by typing:
c4555f82 20572
474c8240 20573@smallexample
8e04817f
AC
20574cd gdb
20575make gdb.info
474c8240 20576@end smallexample
c4555f82 20577
8e04817f
AC
20578If you want to typeset and print copies of this manual, you need @TeX{},
20579a program to print its @sc{dvi} output files, and @file{texinfo.tex}, the
20580Texinfo definitions file.
c4555f82 20581
8e04817f
AC
20582@TeX{} is a typesetting program; it does not print files directly, but
20583produces output files called @sc{dvi} files. To print a typeset
20584document, you need a program to print @sc{dvi} files. If your system
20585has @TeX{} installed, chances are it has such a program. The precise
20586command to use depends on your system; @kbd{lpr -d} is common; another
20587(for PostScript devices) is @kbd{dvips}. The @sc{dvi} print command may
20588require a file name without any extension or a @samp{.dvi} extension.
c4555f82 20589
8e04817f
AC
20590@TeX{} also requires a macro definitions file called
20591@file{texinfo.tex}. This file tells @TeX{} how to typeset a document
20592written in Texinfo format. On its own, @TeX{} cannot either read or
20593typeset a Texinfo file. @file{texinfo.tex} is distributed with GDB
20594and is located in the @file{gdb-@var{version-number}/texinfo}
20595directory.
c4555f82 20596
8e04817f
AC
20597If you have @TeX{} and a @sc{dvi} printer program installed, you can
20598typeset and print this manual. First switch to the the @file{gdb}
20599subdirectory of the main source directory (for example, to
20600@file{gdb-@value{GDBVN}/gdb}) and type:
c4555f82 20601
474c8240 20602@smallexample
8e04817f 20603make gdb.dvi
474c8240 20604@end smallexample
c4555f82 20605
8e04817f 20606Then give @file{gdb.dvi} to your @sc{dvi} printing program.
c4555f82 20607
8e04817f
AC
20608@node Installing GDB
20609@appendix Installing @value{GDBN}
20610@cindex configuring @value{GDBN}
20611@cindex installation
94e91d6d 20612@cindex configuring @value{GDBN}, and source tree subdirectories
c4555f82 20613
8e04817f
AC
20614@value{GDBN} comes with a @code{configure} script that automates the process
20615of preparing @value{GDBN} for installation; you can then use @code{make} to
20616build the @code{gdb} program.
20617@iftex
20618@c irrelevant in info file; it's as current as the code it lives with.
20619@footnote{If you have a more recent version of @value{GDBN} than @value{GDBVN},
20620look at the @file{README} file in the sources; we may have improved the
20621installation procedures since publishing this manual.}
20622@end iftex
c4555f82 20623
8e04817f
AC
20624The @value{GDBN} distribution includes all the source code you need for
20625@value{GDBN} in a single directory, whose name is usually composed by
20626appending the version number to @samp{gdb}.
c4555f82 20627
8e04817f
AC
20628For example, the @value{GDBN} version @value{GDBVN} distribution is in the
20629@file{gdb-@value{GDBVN}} directory. That directory contains:
c4555f82 20630
8e04817f
AC
20631@table @code
20632@item gdb-@value{GDBVN}/configure @r{(and supporting files)}
20633script for configuring @value{GDBN} and all its supporting libraries
c4555f82 20634
8e04817f
AC
20635@item gdb-@value{GDBVN}/gdb
20636the source specific to @value{GDBN} itself
c4555f82 20637
8e04817f
AC
20638@item gdb-@value{GDBVN}/bfd
20639source for the Binary File Descriptor library
c906108c 20640
8e04817f
AC
20641@item gdb-@value{GDBVN}/include
20642@sc{gnu} include files
c906108c 20643
8e04817f
AC
20644@item gdb-@value{GDBVN}/libiberty
20645source for the @samp{-liberty} free software library
c906108c 20646
8e04817f
AC
20647@item gdb-@value{GDBVN}/opcodes
20648source for the library of opcode tables and disassemblers
c906108c 20649
8e04817f
AC
20650@item gdb-@value{GDBVN}/readline
20651source for the @sc{gnu} command-line interface
c906108c 20652
8e04817f
AC
20653@item gdb-@value{GDBVN}/glob
20654source for the @sc{gnu} filename pattern-matching subroutine
c906108c 20655
8e04817f
AC
20656@item gdb-@value{GDBVN}/mmalloc
20657source for the @sc{gnu} memory-mapped malloc package
20658@end table
c906108c 20659
8e04817f
AC
20660The simplest way to configure and build @value{GDBN} is to run @code{configure}
20661from the @file{gdb-@var{version-number}} source directory, which in
20662this example is the @file{gdb-@value{GDBVN}} directory.
c906108c 20663
8e04817f
AC
20664First switch to the @file{gdb-@var{version-number}} source directory
20665if you are not already in it; then run @code{configure}. Pass the
20666identifier for the platform on which @value{GDBN} will run as an
20667argument.
c906108c 20668
8e04817f 20669For example:
c906108c 20670
474c8240 20671@smallexample
8e04817f
AC
20672cd gdb-@value{GDBVN}
20673./configure @var{host}
20674make
474c8240 20675@end smallexample
c906108c 20676
8e04817f
AC
20677@noindent
20678where @var{host} is an identifier such as @samp{sun4} or
20679@samp{decstation}, that identifies the platform where @value{GDBN} will run.
20680(You can often leave off @var{host}; @code{configure} tries to guess the
20681correct value by examining your system.)
c906108c 20682
8e04817f
AC
20683Running @samp{configure @var{host}} and then running @code{make} builds the
20684@file{bfd}, @file{readline}, @file{mmalloc}, and @file{libiberty}
20685libraries, then @code{gdb} itself. The configured source files, and the
20686binaries, are left in the corresponding source directories.
c906108c 20687
8e04817f
AC
20688@need 750
20689@code{configure} is a Bourne-shell (@code{/bin/sh}) script; if your
20690system does not recognize this automatically when you run a different
20691shell, you may need to run @code{sh} on it explicitly:
c906108c 20692
474c8240 20693@smallexample
8e04817f 20694sh configure @var{host}
474c8240 20695@end smallexample
c906108c 20696
8e04817f
AC
20697If you run @code{configure} from a directory that contains source
20698directories for multiple libraries or programs, such as the
20699@file{gdb-@value{GDBVN}} source directory for version @value{GDBVN}, @code{configure}
20700creates configuration files for every directory level underneath (unless
20701you tell it not to, with the @samp{--norecursion} option).
20702
94e91d6d
MC
20703You should run the @code{configure} script from the top directory in the
20704source tree, the @file{gdb-@var{version-number}} directory. If you run
20705@code{configure} from one of the subdirectories, you will configure only
20706that subdirectory. That is usually not what you want. In particular,
20707if you run the first @code{configure} from the @file{gdb} subdirectory
20708of the @file{gdb-@var{version-number}} directory, you will omit the
20709configuration of @file{bfd}, @file{readline}, and other sibling
20710directories of the @file{gdb} subdirectory. This leads to build errors
20711about missing include files such as @file{bfd/bfd.h}.
c906108c 20712
8e04817f
AC
20713You can install @code{@value{GDBP}} anywhere; it has no hardwired paths.
20714However, you should make sure that the shell on your path (named by
20715the @samp{SHELL} environment variable) is publicly readable. Remember
20716that @value{GDBN} uses the shell to start your program---some systems refuse to
20717let @value{GDBN} debug child processes whose programs are not readable.
c906108c 20718
8e04817f
AC
20719@menu
20720* Separate Objdir:: Compiling @value{GDBN} in another directory
20721* Config Names:: Specifying names for hosts and targets
20722* Configure Options:: Summary of options for configure
20723@end menu
c906108c 20724
8e04817f
AC
20725@node Separate Objdir
20726@section Compiling @value{GDBN} in another directory
c906108c 20727
8e04817f
AC
20728If you want to run @value{GDBN} versions for several host or target machines,
20729you need a different @code{gdb} compiled for each combination of
20730host and target. @code{configure} is designed to make this easy by
20731allowing you to generate each configuration in a separate subdirectory,
20732rather than in the source directory. If your @code{make} program
20733handles the @samp{VPATH} feature (@sc{gnu} @code{make} does), running
20734@code{make} in each of these directories builds the @code{gdb}
20735program specified there.
c906108c 20736
8e04817f
AC
20737To build @code{gdb} in a separate directory, run @code{configure}
20738with the @samp{--srcdir} option to specify where to find the source.
20739(You also need to specify a path to find @code{configure}
20740itself from your working directory. If the path to @code{configure}
20741would be the same as the argument to @samp{--srcdir}, you can leave out
20742the @samp{--srcdir} option; it is assumed.)
c906108c 20743
8e04817f
AC
20744For example, with version @value{GDBVN}, you can build @value{GDBN} in a
20745separate directory for a Sun 4 like this:
c906108c 20746
474c8240 20747@smallexample
8e04817f
AC
20748@group
20749cd gdb-@value{GDBVN}
20750mkdir ../gdb-sun4
20751cd ../gdb-sun4
20752../gdb-@value{GDBVN}/configure sun4
20753make
20754@end group
474c8240 20755@end smallexample
c906108c 20756
8e04817f
AC
20757When @code{configure} builds a configuration using a remote source
20758directory, it creates a tree for the binaries with the same structure
20759(and using the same names) as the tree under the source directory. In
20760the example, you'd find the Sun 4 library @file{libiberty.a} in the
20761directory @file{gdb-sun4/libiberty}, and @value{GDBN} itself in
20762@file{gdb-sun4/gdb}.
c906108c 20763
94e91d6d
MC
20764Make sure that your path to the @file{configure} script has just one
20765instance of @file{gdb} in it. If your path to @file{configure} looks
20766like @file{../gdb-@value{GDBVN}/gdb/configure}, you are configuring only
20767one subdirectory of @value{GDBN}, not the whole package. This leads to
20768build errors about missing include files such as @file{bfd/bfd.h}.
20769
8e04817f
AC
20770One popular reason to build several @value{GDBN} configurations in separate
20771directories is to configure @value{GDBN} for cross-compiling (where
20772@value{GDBN} runs on one machine---the @dfn{host}---while debugging
20773programs that run on another machine---the @dfn{target}).
20774You specify a cross-debugging target by
20775giving the @samp{--target=@var{target}} option to @code{configure}.
c906108c 20776
8e04817f
AC
20777When you run @code{make} to build a program or library, you must run
20778it in a configured directory---whatever directory you were in when you
20779called @code{configure} (or one of its subdirectories).
c906108c 20780
8e04817f
AC
20781The @code{Makefile} that @code{configure} generates in each source
20782directory also runs recursively. If you type @code{make} in a source
20783directory such as @file{gdb-@value{GDBVN}} (or in a separate configured
20784directory configured with @samp{--srcdir=@var{dirname}/gdb-@value{GDBVN}}), you
20785will build all the required libraries, and then build GDB.
c906108c 20786
8e04817f
AC
20787When you have multiple hosts or targets configured in separate
20788directories, you can run @code{make} on them in parallel (for example,
20789if they are NFS-mounted on each of the hosts); they will not interfere
20790with each other.
c906108c 20791
8e04817f
AC
20792@node Config Names
20793@section Specifying names for hosts and targets
c906108c 20794
8e04817f
AC
20795The specifications used for hosts and targets in the @code{configure}
20796script are based on a three-part naming scheme, but some short predefined
20797aliases are also supported. The full naming scheme encodes three pieces
20798of information in the following pattern:
c906108c 20799
474c8240 20800@smallexample
8e04817f 20801@var{architecture}-@var{vendor}-@var{os}
474c8240 20802@end smallexample
c906108c 20803
8e04817f
AC
20804For example, you can use the alias @code{sun4} as a @var{host} argument,
20805or as the value for @var{target} in a @code{--target=@var{target}}
20806option. The equivalent full name is @samp{sparc-sun-sunos4}.
c906108c 20807
8e04817f
AC
20808The @code{configure} script accompanying @value{GDBN} does not provide
20809any query facility to list all supported host and target names or
20810aliases. @code{configure} calls the Bourne shell script
20811@code{config.sub} to map abbreviations to full names; you can read the
20812script, if you wish, or you can use it to test your guesses on
20813abbreviations---for example:
c906108c 20814
8e04817f
AC
20815@smallexample
20816% sh config.sub i386-linux
20817i386-pc-linux-gnu
20818% sh config.sub alpha-linux
20819alpha-unknown-linux-gnu
20820% sh config.sub hp9k700
20821hppa1.1-hp-hpux
20822% sh config.sub sun4
20823sparc-sun-sunos4.1.1
20824% sh config.sub sun3
20825m68k-sun-sunos4.1.1
20826% sh config.sub i986v
20827Invalid configuration `i986v': machine `i986v' not recognized
20828@end smallexample
c906108c 20829
8e04817f
AC
20830@noindent
20831@code{config.sub} is also distributed in the @value{GDBN} source
20832directory (@file{gdb-@value{GDBVN}}, for version @value{GDBVN}).
d700128c 20833
8e04817f
AC
20834@node Configure Options
20835@section @code{configure} options
c906108c 20836
8e04817f
AC
20837Here is a summary of the @code{configure} options and arguments that
20838are most often useful for building @value{GDBN}. @code{configure} also has
20839several other options not listed here. @inforef{What Configure
20840Does,,configure.info}, for a full explanation of @code{configure}.
c906108c 20841
474c8240 20842@smallexample
8e04817f
AC
20843configure @r{[}--help@r{]}
20844 @r{[}--prefix=@var{dir}@r{]}
20845 @r{[}--exec-prefix=@var{dir}@r{]}
20846 @r{[}--srcdir=@var{dirname}@r{]}
20847 @r{[}--norecursion@r{]} @r{[}--rm@r{]}
20848 @r{[}--target=@var{target}@r{]}
20849 @var{host}
474c8240 20850@end smallexample
c906108c 20851
8e04817f
AC
20852@noindent
20853You may introduce options with a single @samp{-} rather than
20854@samp{--} if you prefer; but you may abbreviate option names if you use
20855@samp{--}.
c906108c 20856
8e04817f
AC
20857@table @code
20858@item --help
20859Display a quick summary of how to invoke @code{configure}.
c906108c 20860
8e04817f
AC
20861@item --prefix=@var{dir}
20862Configure the source to install programs and files under directory
20863@file{@var{dir}}.
c906108c 20864
8e04817f
AC
20865@item --exec-prefix=@var{dir}
20866Configure the source to install programs under directory
20867@file{@var{dir}}.
c906108c 20868
8e04817f
AC
20869@c avoid splitting the warning from the explanation:
20870@need 2000
20871@item --srcdir=@var{dirname}
20872@strong{Warning: using this option requires @sc{gnu} @code{make}, or another
20873@code{make} that implements the @code{VPATH} feature.}@*
20874Use this option to make configurations in directories separate from the
20875@value{GDBN} source directories. Among other things, you can use this to
20876build (or maintain) several configurations simultaneously, in separate
20877directories. @code{configure} writes configuration specific files in
20878the current directory, but arranges for them to use the source in the
20879directory @var{dirname}. @code{configure} creates directories under
20880the working directory in parallel to the source directories below
20881@var{dirname}.
c906108c 20882
8e04817f
AC
20883@item --norecursion
20884Configure only the directory level where @code{configure} is executed; do not
20885propagate configuration to subdirectories.
c906108c 20886
8e04817f
AC
20887@item --target=@var{target}
20888Configure @value{GDBN} for cross-debugging programs running on the specified
20889@var{target}. Without this option, @value{GDBN} is configured to debug
20890programs that run on the same machine (@var{host}) as @value{GDBN} itself.
c906108c 20891
8e04817f 20892There is no convenient way to generate a list of all available targets.
c906108c 20893
8e04817f
AC
20894@item @var{host} @dots{}
20895Configure @value{GDBN} to run on the specified @var{host}.
c906108c 20896
8e04817f
AC
20897There is no convenient way to generate a list of all available hosts.
20898@end table
c906108c 20899
8e04817f
AC
20900There are many other options available as well, but they are generally
20901needed for special purposes only.
c906108c 20902
8e04817f
AC
20903@node Maintenance Commands
20904@appendix Maintenance Commands
20905@cindex maintenance commands
20906@cindex internal commands
c906108c 20907
8e04817f 20908In addition to commands intended for @value{GDBN} users, @value{GDBN}
09d4efe1
EZ
20909includes a number of commands intended for @value{GDBN} developers,
20910that are not documented elsewhere in this manual. These commands are
da316a69
EZ
20911provided here for reference. (For commands that turn on debugging
20912messages, see @ref{Debugging Output}.)
c906108c 20913
8e04817f 20914@table @code
09d4efe1
EZ
20915@kindex maint agent
20916@item maint agent @var{expression}
20917Translate the given @var{expression} into remote agent bytecodes.
20918This command is useful for debugging the Agent Expression mechanism
20919(@pxref{Agent Expressions}).
20920
8e04817f
AC
20921@kindex maint info breakpoints
20922@item @anchor{maint info breakpoints}maint info breakpoints
20923Using the same format as @samp{info breakpoints}, display both the
20924breakpoints you've set explicitly, and those @value{GDBN} is using for
20925internal purposes. Internal breakpoints are shown with negative
20926breakpoint numbers. The type column identifies what kind of breakpoint
20927is shown:
c906108c 20928
8e04817f
AC
20929@table @code
20930@item breakpoint
20931Normal, explicitly set breakpoint.
c906108c 20932
8e04817f
AC
20933@item watchpoint
20934Normal, explicitly set watchpoint.
c906108c 20935
8e04817f
AC
20936@item longjmp
20937Internal breakpoint, used to handle correctly stepping through
20938@code{longjmp} calls.
c906108c 20939
8e04817f
AC
20940@item longjmp resume
20941Internal breakpoint at the target of a @code{longjmp}.
c906108c 20942
8e04817f
AC
20943@item until
20944Temporary internal breakpoint used by the @value{GDBN} @code{until} command.
c906108c 20945
8e04817f
AC
20946@item finish
20947Temporary internal breakpoint used by the @value{GDBN} @code{finish} command.
c906108c 20948
8e04817f
AC
20949@item shlib events
20950Shared library events.
c906108c 20951
8e04817f 20952@end table
c906108c 20953
09d4efe1
EZ
20954@kindex maint check-symtabs
20955@item maint check-symtabs
20956Check the consistency of psymtabs and symtabs.
20957
20958@kindex maint cplus first_component
20959@item maint cplus first_component @var{name}
20960Print the first C@t{++} class/namespace component of @var{name}.
20961
20962@kindex maint cplus namespace
20963@item maint cplus namespace
20964Print the list of possible C@t{++} namespaces.
20965
20966@kindex maint demangle
20967@item maint demangle @var{name}
20968Demangle a C@t{++} or Objective-C manled @var{name}.
20969
20970@kindex maint deprecate
20971@kindex maint undeprecate
20972@cindex deprecated commands
20973@item maint deprecate @var{command} @r{[}@var{replacement}@r{]}
20974@itemx maint undeprecate @var{command}
20975Deprecate or undeprecate the named @var{command}. Deprecated commands
20976cause @value{GDBN} to issue a warning when you use them. The optional
20977argument @var{replacement} says which newer command should be used in
20978favor of the deprecated one; if it is given, @value{GDBN} will mention
20979the replacement as part of the warning.
20980
20981@kindex maint dump-me
20982@item maint dump-me
20983Cause a fatal signal in the debugger and force it to dump its core.
20984
8d30a00d
AC
20985@kindex maint internal-error
20986@kindex maint internal-warning
09d4efe1
EZ
20987@item maint internal-error @r{[}@var{message-text}@r{]}
20988@itemx maint internal-warning @r{[}@var{message-text}@r{]}
8d30a00d
AC
20989Cause @value{GDBN} to call the internal function @code{internal_error}
20990or @code{internal_warning} and hence behave as though an internal error
20991or internal warning has been detected. In addition to reporting the
20992internal problem, these functions give the user the opportunity to
20993either quit @value{GDBN} or create a core file of the current
20994@value{GDBN} session.
20995
09d4efe1
EZ
20996These commands take an optional parameter @var{message-text} that is
20997used as the text of the error or warning message.
20998
20999Here's an example of using @code{indernal-error}:
21000
8d30a00d 21001@smallexample
f7dc1244 21002(@value{GDBP}) @kbd{maint internal-error testing, 1, 2}
8d30a00d
AC
21003@dots{}/maint.c:121: internal-error: testing, 1, 2
21004A problem internal to GDB has been detected. Further
21005debugging may prove unreliable.
21006Quit this debugging session? (y or n) @kbd{n}
21007Create a core file? (y or n) @kbd{n}
f7dc1244 21008(@value{GDBP})
8d30a00d
AC
21009@end smallexample
21010
09d4efe1
EZ
21011@kindex maint packet
21012@item maint packet @var{text}
21013If @value{GDBN} is talking to an inferior via the serial protocol,
21014then this command sends the string @var{text} to the inferior, and
21015displays the response packet. @value{GDBN} supplies the initial
21016@samp{$} character, the terminating @samp{#} character, and the
21017checksum.
21018
21019@kindex maint print architecture
21020@item maint print architecture @r{[}@var{file}@r{]}
21021Print the entire architecture configuration. The optional argument
21022@var{file} names the file where the output goes.
8d30a00d 21023
00905d52
AC
21024@kindex maint print dummy-frames
21025@item maint print dummy-frames
21026
21027Prints the contents of @value{GDBN}'s internal dummy-frame stack.
21028
21029@smallexample
f7dc1244 21030(@value{GDBP}) @kbd{b add}
00905d52 21031@dots{}
f7dc1244 21032(@value{GDBP}) @kbd{print add(2,3)}
00905d52
AC
21033Breakpoint 2, add (a=2, b=3) at @dots{}
2103458 return (a + b);
21035The program being debugged stopped while in a function called from GDB.
21036@dots{}
f7dc1244 21037(@value{GDBP}) @kbd{maint print dummy-frames}
00905d52
AC
210380x1a57c80: pc=0x01014068 fp=0x0200bddc sp=0x0200bdd6
21039 top=0x0200bdd4 id=@{stack=0x200bddc,code=0x101405c@}
21040 call_lo=0x01014000 call_hi=0x01014001
f7dc1244 21041(@value{GDBP})
00905d52
AC
21042@end smallexample
21043
21044Takes an optional file parameter.
21045
0680b120
AC
21046@kindex maint print registers
21047@kindex maint print raw-registers
21048@kindex maint print cooked-registers
617073a9 21049@kindex maint print register-groups
09d4efe1
EZ
21050@item maint print registers @r{[}@var{file}@r{]}
21051@itemx maint print raw-registers @r{[}@var{file}@r{]}
21052@itemx maint print cooked-registers @r{[}@var{file}@r{]}
21053@itemx maint print register-groups @r{[}@var{file}@r{]}
0680b120
AC
21054Print @value{GDBN}'s internal register data structures.
21055
617073a9
AC
21056The command @code{maint print raw-registers} includes the contents of
21057the raw register cache; the command @code{maint print cooked-registers}
21058includes the (cooked) value of all registers; and the command
21059@code{maint print register-groups} includes the groups that each
21060register is a member of. @xref{Registers,, Registers, gdbint,
21061@value{GDBN} Internals}.
0680b120 21062
09d4efe1
EZ
21063These commands take an optional parameter, a file name to which to
21064write the information.
0680b120 21065
617073a9 21066@kindex maint print reggroups
09d4efe1
EZ
21067@item maint print reggroups @r{[}@var{file}@r{]}
21068Print @value{GDBN}'s internal register group data structures. The
21069optional argument @var{file} tells to what file to write the
21070information.
617073a9 21071
09d4efe1 21072The register groups info looks like this:
617073a9
AC
21073
21074@smallexample
f7dc1244 21075(@value{GDBP}) @kbd{maint print reggroups}
b383017d
RM
21076 Group Type
21077 general user
21078 float user
21079 all user
21080 vector user
21081 system user
21082 save internal
21083 restore internal
617073a9
AC
21084@end smallexample
21085
09d4efe1
EZ
21086@kindex flushregs
21087@item flushregs
21088This command forces @value{GDBN} to flush its internal register cache.
21089
21090@kindex maint print objfiles
21091@cindex info for known object files
21092@item maint print objfiles
21093Print a dump of all known object files. For each object file, this
21094command prints its name, address in memory, and all of its psymtabs
21095and symtabs.
21096
21097@kindex maint print statistics
21098@cindex bcache statistics
21099@item maint print statistics
21100This command prints, for each object file in the program, various data
21101about that object file followed by the byte cache (@dfn{bcache})
21102statistics for the object file. The objfile data includes the number
21103of minimal, partical, full, and stabs symbols, the number of types
21104defined by the objfile, the number of as yet unexpanded psym tables,
21105the number of line tables and string tables, and the amount of memory
21106used by the various tables. The bcache statistics include the counts,
21107sizes, and counts of duplicates of all and unique objects, max,
21108average, and median entry size, total memory used and its overhead and
21109savings, and various measures of the hash table size and chain
21110lengths.
21111
21112@kindex maint print type
21113@cindex type chain of a data type
21114@item maint print type @var{expr}
21115Print the type chain for a type specified by @var{expr}. The argument
21116can be either a type name or a symbol. If it is a symbol, the type of
21117that symbol is described. The type chain produced by this command is
21118a recursive definition of the data type as stored in @value{GDBN}'s
21119data structures, including its flags and contained types.
21120
21121@kindex maint set dwarf2 max-cache-age
21122@kindex maint show dwarf2 max-cache-age
21123@item maint set dwarf2 max-cache-age
21124@itemx maint show dwarf2 max-cache-age
21125Control the DWARF 2 compilation unit cache.
21126
21127@cindex DWARF 2 compilation units cache
21128In object files with inter-compilation-unit references, such as those
21129produced by the GCC option @samp{-feliminate-dwarf2-dups}, the DWARF 2
21130reader needs to frequently refer to previously read compilation units.
21131This setting controls how long a compilation unit will remain in the
21132cache if it is not referenced. A higher limit means that cached
21133compilation units will be stored in memory longer, and more total
21134memory will be used. Setting it to zero disables caching, which will
21135slow down @value{GDBN} startup, but reduce memory consumption.
21136
e7ba9c65
DJ
21137@kindex maint set profile
21138@kindex maint show profile
21139@cindex profiling GDB
21140@item maint set profile
21141@itemx maint show profile
21142Control profiling of @value{GDBN}.
21143
21144Profiling will be disabled until you use the @samp{maint set profile}
21145command to enable it. When you enable profiling, the system will begin
21146collecting timing and execution count data; when you disable profiling or
21147exit @value{GDBN}, the results will be written to a log file. Remember that
21148if you use profiling, @value{GDBN} will overwrite the profiling log file
21149(often called @file{gmon.out}). If you have a record of important profiling
21150data in a @file{gmon.out} file, be sure to move it to a safe location.
21151
21152Configuring with @samp{--enable-profiling} arranges for @value{GDBN} to be
b383017d 21153compiled with the @samp{-pg} compiler option.
e7ba9c65 21154
09d4efe1
EZ
21155@kindex maint show-debug-regs
21156@cindex x86 hardware debug registers
21157@item maint show-debug-regs
21158Control whether to show variables that mirror the x86 hardware debug
21159registers. Use @code{ON} to enable, @code{OFF} to disable. If
21160enabled, the debug registers values are shown when GDB inserts or
21161removes a hardware breakpoint or watchpoint, and when the inferior
21162triggers a hardware-assisted breakpoint or watchpoint.
21163
21164@kindex maint space
21165@cindex memory used by commands
21166@item maint space
21167Control whether to display memory usage for each command. If set to a
21168nonzero value, @value{GDBN} will display how much memory each command
21169took, following the command's own output. This can also be requested
21170by invoking @value{GDBN} with the @option{--statistics} command-line
21171switch (@pxref{Mode Options}).
21172
21173@kindex maint time
21174@cindex time of command execution
21175@item maint time
21176Control whether to display the execution time for each command. If
21177set to a nonzero value, @value{GDBN} will display how much time it
21178took to execute each command, following the command's own output.
21179This can also be requested by invoking @value{GDBN} with the
21180@option{--statistics} command-line switch (@pxref{Mode Options}).
21181
21182@kindex maint translate-address
21183@item maint translate-address @r{[}@var{section}@r{]} @var{addr}
21184Find the symbol stored at the location specified by the address
21185@var{addr} and an optional section name @var{section}. If found,
21186@value{GDBN} prints the name of the closest symbol and an offset from
21187the symbol's location to the specified address. This is similar to
21188the @code{info address} command (@pxref{Symbols}), except that this
21189command also allows to find symbols in other sections.
ae038cb0 21190
8e04817f 21191@end table
c906108c 21192
9c16f35a
EZ
21193The following command is useful for non-interactive invocations of
21194@value{GDBN}, such as in the test suite.
21195
21196@table @code
21197@item set watchdog @var{nsec}
21198@kindex set watchdog
21199@cindex watchdog timer
21200@cindex timeout for commands
21201Set the maximum number of seconds @value{GDBN} will wait for the
21202target operation to finish. If this time expires, @value{GDBN}
21203reports and error and the command is aborted.
21204
21205@item show watchdog
21206Show the current setting of the target wait timeout.
21207@end table
c906108c 21208
e0ce93ac 21209@node Remote Protocol
8e04817f 21210@appendix @value{GDBN} Remote Serial Protocol
c906108c 21211
ee2d5c50
AC
21212@menu
21213* Overview::
21214* Packets::
21215* Stop Reply Packets::
21216* General Query Packets::
21217* Register Packet Format::
21218* Examples::
0ce1b118 21219* File-I/O remote protocol extension::
ee2d5c50
AC
21220@end menu
21221
21222@node Overview
21223@section Overview
21224
8e04817f
AC
21225There may be occasions when you need to know something about the
21226protocol---for example, if there is only one serial port to your target
21227machine, you might want your program to do something special if it
21228recognizes a packet meant for @value{GDBN}.
c906108c 21229
d2c6833e 21230In the examples below, @samp{->} and @samp{<-} are used to indicate
8e04817f 21231transmitted and received data respectfully.
c906108c 21232
8e04817f
AC
21233@cindex protocol, @value{GDBN} remote serial
21234@cindex serial protocol, @value{GDBN} remote
21235@cindex remote serial protocol
21236All @value{GDBN} commands and responses (other than acknowledgments) are
21237sent as a @var{packet}. A @var{packet} is introduced with the character
21238@samp{$}, the actual @var{packet-data}, and the terminating character
21239@samp{#} followed by a two-digit @var{checksum}:
c906108c 21240
474c8240 21241@smallexample
8e04817f 21242@code{$}@var{packet-data}@code{#}@var{checksum}
474c8240 21243@end smallexample
8e04817f 21244@noindent
c906108c 21245
8e04817f
AC
21246@cindex checksum, for @value{GDBN} remote
21247@noindent
21248The two-digit @var{checksum} is computed as the modulo 256 sum of all
21249characters between the leading @samp{$} and the trailing @samp{#} (an
21250eight bit unsigned checksum).
c906108c 21251
8e04817f
AC
21252Implementors should note that prior to @value{GDBN} 5.0 the protocol
21253specification also included an optional two-digit @var{sequence-id}:
c906108c 21254
474c8240 21255@smallexample
8e04817f 21256@code{$}@var{sequence-id}@code{:}@var{packet-data}@code{#}@var{checksum}
474c8240 21257@end smallexample
c906108c 21258
8e04817f
AC
21259@cindex sequence-id, for @value{GDBN} remote
21260@noindent
21261That @var{sequence-id} was appended to the acknowledgment. @value{GDBN}
21262has never output @var{sequence-id}s. Stubs that handle packets added
21263since @value{GDBN} 5.0 must not accept @var{sequence-id}.
c906108c 21264
8e04817f
AC
21265@cindex acknowledgment, for @value{GDBN} remote
21266When either the host or the target machine receives a packet, the first
21267response expected is an acknowledgment: either @samp{+} (to indicate
21268the package was received correctly) or @samp{-} (to request
21269retransmission):
c906108c 21270
474c8240 21271@smallexample
d2c6833e
AC
21272-> @code{$}@var{packet-data}@code{#}@var{checksum}
21273<- @code{+}
474c8240 21274@end smallexample
8e04817f 21275@noindent
53a5351d 21276
8e04817f
AC
21277The host (@value{GDBN}) sends @var{command}s, and the target (the
21278debugging stub incorporated in your program) sends a @var{response}. In
21279the case of step and continue @var{command}s, the response is only sent
21280when the operation has completed (the target has again stopped).
c906108c 21281
8e04817f
AC
21282@var{packet-data} consists of a sequence of characters with the
21283exception of @samp{#} and @samp{$} (see @samp{X} packet for additional
21284exceptions).
c906108c 21285
8e04817f 21286Fields within the packet should be separated using @samp{,} @samp{;} or
ee2d5c50 21287@cindex remote protocol, field separator
8e04817f 21288@samp{:}. Except where otherwise noted all numbers are represented in
ee2d5c50 21289@sc{hex} with leading zeros suppressed.
c906108c 21290
8e04817f
AC
21291Implementors should note that prior to @value{GDBN} 5.0, the character
21292@samp{:} could not appear as the third character in a packet (as it
21293would potentially conflict with the @var{sequence-id}).
c906108c 21294
8e04817f
AC
21295Response @var{data} can be run-length encoded to save space. A @samp{*}
21296means that the next character is an @sc{ascii} encoding giving a repeat count
21297which stands for that many repetitions of the character preceding the
21298@samp{*}. The encoding is @code{n+29}, yielding a printable character
21299where @code{n >=3} (which is where rle starts to win). The printable
21300characters @samp{$}, @samp{#}, @samp{+} and @samp{-} or with a numeric
21301value greater than 126 should not be used.
c906108c 21302
8e04817f 21303So:
474c8240 21304@smallexample
8e04817f 21305"@code{0* }"
474c8240 21306@end smallexample
8e04817f
AC
21307@noindent
21308means the same as "0000".
c906108c 21309
8e04817f
AC
21310The error response returned for some packets includes a two character
21311error number. That number is not well defined.
c906108c 21312
8e04817f
AC
21313For any @var{command} not supported by the stub, an empty response
21314(@samp{$#00}) should be returned. That way it is possible to extend the
21315protocol. A newer @value{GDBN} can tell if a packet is supported based
21316on that response.
c906108c 21317
b383017d
RM
21318A stub is required to support the @samp{g}, @samp{G}, @samp{m}, @samp{M},
21319@samp{c}, and @samp{s} @var{command}s. All other @var{command}s are
8e04817f 21320optional.
c906108c 21321
ee2d5c50
AC
21322@node Packets
21323@section Packets
21324
21325The following table provides a complete list of all currently defined
21326@var{command}s and their corresponding response @var{data}.
9c16f35a
EZ
21327@xref{File-I/O remote protocol extension}, for details about the File
21328I/O extension of the remote protocol.
ee2d5c50
AC
21329
21330@table @r
21331
21332@item @code{!} --- extended mode
21333@cindex @code{!} packet
21334
8e04817f
AC
21335Enable extended mode. In extended mode, the remote server is made
21336persistent. The @samp{R} packet is used to restart the program being
21337debugged.
ee2d5c50
AC
21338
21339Reply:
21340@table @samp
21341@item OK
8e04817f 21342The remote target both supports and has enabled extended mode.
ee2d5c50 21343@end table
c906108c 21344
ee2d5c50
AC
21345@item @code{?} --- last signal
21346@cindex @code{?} packet
c906108c 21347
ee2d5c50
AC
21348Indicate the reason the target halted. The reply is the same as for
21349step and continue.
c906108c 21350
ee2d5c50
AC
21351Reply:
21352@xref{Stop Reply Packets}, for the reply specifications.
21353
21354@item @code{a} --- reserved
21355
21356Reserved for future use.
21357
21358@item @code{A}@var{arglen}@code{,}@var{argnum}@code{,}@var{arg}@code{,@dots{}} --- set program arguments @strong{(reserved)}
21359@cindex @code{A} packet
c906108c 21360
8e04817f
AC
21361Initialized @samp{argv[]} array passed into program. @var{arglen}
21362specifies the number of bytes in the hex encoded byte stream @var{arg}.
ee2d5c50
AC
21363See @code{gdbserver} for more details.
21364
21365Reply:
21366@table @samp
21367@item OK
21368@item E@var{NN}
21369@end table
21370
21371@item @code{b}@var{baud} --- set baud @strong{(deprecated)}
21372@cindex @code{b} packet
21373
21374Change the serial line speed to @var{baud}.
21375
21376JTC: @emph{When does the transport layer state change? When it's
21377received, or after the ACK is transmitted. In either case, there are
21378problems if the command or the acknowledgment packet is dropped.}
21379
21380Stan: @emph{If people really wanted to add something like this, and get
21381it working for the first time, they ought to modify ser-unix.c to send
21382some kind of out-of-band message to a specially-setup stub and have the
21383switch happen "in between" packets, so that from remote protocol's point
21384of view, nothing actually happened.}
21385
21386@item @code{B}@var{addr},@var{mode} --- set breakpoint @strong{(deprecated)}
21387@cindex @code{B} packet
21388
8e04817f 21389Set (@var{mode} is @samp{S}) or clear (@var{mode} is @samp{C}) a
2f870471
AC
21390breakpoint at @var{addr}.
21391
21392This packet has been replaced by the @samp{Z} and @samp{z} packets
21393(@pxref{insert breakpoint or watchpoint packet}).
c906108c 21394
ee2d5c50
AC
21395@item @code{c}@var{addr} --- continue
21396@cindex @code{c} packet
21397
21398@var{addr} is address to resume. If @var{addr} is omitted, resume at
8e04817f 21399current address.
c906108c 21400
ee2d5c50
AC
21401Reply:
21402@xref{Stop Reply Packets}, for the reply specifications.
21403
21404@item @code{C}@var{sig}@code{;}@var{addr} --- continue with signal
21405@cindex @code{C} packet
21406
8e04817f
AC
21407Continue with signal @var{sig} (hex signal number). If
21408@code{;}@var{addr} is omitted, resume at same address.
c906108c 21409
ee2d5c50
AC
21410Reply:
21411@xref{Stop Reply Packets}, for the reply specifications.
c906108c 21412
ee2d5c50
AC
21413@item @code{d} --- toggle debug @strong{(deprecated)}
21414@cindex @code{d} packet
21415
21416Toggle debug flag.
21417
21418@item @code{D} --- detach
21419@cindex @code{D} packet
21420
21421Detach @value{GDBN} from the remote system. Sent to the remote target
07f31aa6 21422before @value{GDBN} disconnects via the @code{detach} command.
ee2d5c50
AC
21423
21424Reply:
21425@table @samp
21426@item @emph{no response}
8e04817f 21427@value{GDBN} does not check for any response after sending this packet.
ee2d5c50 21428@end table
c906108c 21429
ee2d5c50 21430@item @code{e} --- reserved
c906108c 21431
ee2d5c50 21432Reserved for future use.
c906108c 21433
ee2d5c50 21434@item @code{E} --- reserved
c906108c 21435
ee2d5c50 21436Reserved for future use.
c906108c 21437
ee2d5c50
AC
21438@item @code{f} --- reserved
21439
21440Reserved for future use.
21441
0ce1b118
CV
21442@item @code{F}@var{RC}@code{,}@var{EE}@code{,}@var{CF}@code{;}@var{XX} --- Reply to target's F packet.
21443@cindex @code{F} packet
ee2d5c50 21444
0ce1b118
CV
21445This packet is send by @value{GDBN} as reply to a @code{F} request packet
21446sent by the target. This is part of the File-I/O protocol extension.
21447@xref{File-I/O remote protocol extension}, for the specification.
ee2d5c50
AC
21448
21449@item @code{g} --- read registers
21450@anchor{read registers packet}
21451@cindex @code{g} packet
21452
21453Read general registers.
21454
21455Reply:
21456@table @samp
21457@item @var{XX@dots{}}
8e04817f
AC
21458Each byte of register data is described by two hex digits. The bytes
21459with the register are transmitted in target byte order. The size of
21460each register and their position within the @samp{g} @var{packet} are
12c266ea
AC
21461determined by the @value{GDBN} internal macros
21462@var{DEPRECATED_REGISTER_RAW_SIZE} and @var{REGISTER_NAME} macros. The
21463specification of several standard @code{g} packets is specified below.
ee2d5c50
AC
21464@item E@var{NN}
21465for an error.
21466@end table
c906108c 21467
ee2d5c50
AC
21468@item @code{G}@var{XX@dots{}} --- write regs
21469@cindex @code{G} packet
c906108c 21470
ee2d5c50
AC
21471@xref{read registers packet}, for a description of the @var{XX@dots{}}
21472data.
21473
21474Reply:
21475@table @samp
21476@item OK
21477for success
21478@item E@var{NN}
21479for an error
21480@end table
21481
21482@item @code{h} --- reserved
21483
21484Reserved for future use.
21485
b383017d 21486@item @code{H}@var{c}@var{t@dots{}} --- set thread
ee2d5c50 21487@cindex @code{H} packet
c906108c 21488
8e04817f 21489Set thread for subsequent operations (@samp{m}, @samp{M}, @samp{g},
ee2d5c50
AC
21490@samp{G}, et.al.). @var{c} depends on the operation to be performed: it
21491should be @samp{c} for step and continue operations, @samp{g} for other
21492operations. The thread designator @var{t@dots{}} may be -1, meaning all
21493the threads, a thread number, or zero which means pick any thread.
21494
21495Reply:
21496@table @samp
21497@item OK
21498for success
21499@item E@var{NN}
21500for an error
21501@end table
c906108c 21502
8e04817f
AC
21503@c FIXME: JTC:
21504@c 'H': How restrictive (or permissive) is the thread model. If a
21505@c thread is selected and stopped, are other threads allowed
21506@c to continue to execute? As I mentioned above, I think the
21507@c semantics of each command when a thread is selected must be
21508@c described. For example:
21509@c
21510@c 'g': If the stub supports threads and a specific thread is
21511@c selected, returns the register block from that thread;
21512@c otherwise returns current registers.
21513@c
21514@c 'G' If the stub supports threads and a specific thread is
21515@c selected, sets the registers of the register block of
21516@c that thread; otherwise sets current registers.
c906108c 21517
ee2d5c50
AC
21518@item @code{i}@var{addr}@code{,}@var{nnn} --- cycle step @strong{(draft)}
21519@anchor{cycle step packet}
21520@cindex @code{i} packet
21521
8e04817f
AC
21522Step the remote target by a single clock cycle. If @code{,}@var{nnn} is
21523present, cycle step @var{nnn} cycles. If @var{addr} is present, cycle
21524step starting at that address.
c906108c 21525
ee2d5c50
AC
21526@item @code{I} --- signal then cycle step @strong{(reserved)}
21527@cindex @code{I} packet
21528
21529@xref{step with signal packet}. @xref{cycle step packet}.
21530
21531@item @code{j} --- reserved
21532
21533Reserved for future use.
21534
21535@item @code{J} --- reserved
c906108c 21536
ee2d5c50 21537Reserved for future use.
c906108c 21538
ee2d5c50
AC
21539@item @code{k} --- kill request
21540@cindex @code{k} packet
c906108c 21541
ac282366 21542FIXME: @emph{There is no description of how to operate when a specific
ee2d5c50
AC
21543thread context has been selected (i.e.@: does 'k' kill only that
21544thread?)}.
c906108c 21545
ee2d5c50 21546@item @code{K} --- reserved
c906108c 21547
ee2d5c50
AC
21548Reserved for future use.
21549
21550@item @code{l} --- reserved
21551
21552Reserved for future use.
21553
21554@item @code{L} --- reserved
21555
21556Reserved for future use.
21557
21558@item @code{m}@var{addr}@code{,}@var{length} --- read memory
21559@cindex @code{m} packet
c906108c 21560
8e04817f 21561Read @var{length} bytes of memory starting at address @var{addr}.
ee2d5c50 21562Neither @value{GDBN} nor the stub assume that sized memory transfers are
2e834e49 21563assumed using word aligned accesses. FIXME: @emph{A word aligned memory
8e04817f 21564transfer mechanism is needed.}
c906108c 21565
ee2d5c50
AC
21566Reply:
21567@table @samp
21568@item @var{XX@dots{}}
21569@var{XX@dots{}} is mem contents. Can be fewer bytes than requested if able
21570to read only part of the data. Neither @value{GDBN} nor the stub assume
2e834e49 21571that sized memory transfers are assumed using word aligned
ee2d5c50
AC
21572accesses. FIXME: @emph{A word aligned memory transfer mechanism is
21573needed.}
21574@item E@var{NN}
21575@var{NN} is errno
21576@end table
21577
21578@item @code{M}@var{addr},@var{length}@code{:}@var{XX@dots{}} --- write mem
21579@cindex @code{M} packet
21580
8e04817f 21581Write @var{length} bytes of memory starting at address @var{addr}.
ee2d5c50
AC
21582@var{XX@dots{}} is the data.
21583
21584Reply:
21585@table @samp
21586@item OK
21587for success
21588@item E@var{NN}
8e04817f
AC
21589for an error (this includes the case where only part of the data was
21590written).
ee2d5c50 21591@end table
c906108c 21592
ee2d5c50 21593@item @code{n} --- reserved
c906108c 21594
ee2d5c50 21595Reserved for future use.
c906108c 21596
ee2d5c50 21597@item @code{N} --- reserved
c906108c 21598
ee2d5c50 21599Reserved for future use.
c906108c 21600
ee2d5c50
AC
21601@item @code{o} --- reserved
21602
21603Reserved for future use.
21604
21605@item @code{O} --- reserved
21606
2e868123 21607@item @code{p}@var{hex number of register} --- read register packet
ee2d5c50
AC
21608@cindex @code{p} packet
21609
2e868123
AC
21610@xref{read registers packet}, for a description of how the returned
21611register value is encoded.
ee2d5c50
AC
21612
21613Reply:
21614@table @samp
2e868123
AC
21615@item @var{XX@dots{}}
21616the register's value
21617@item E@var{NN}
21618for an error
21619@item
21620Indicating an unrecognized @var{query}.
ee2d5c50
AC
21621@end table
21622
21623@item @code{P}@var{n@dots{}}@code{=}@var{r@dots{}} --- write register
21624@anchor{write register packet}
21625@cindex @code{P} packet
21626
21627Write register @var{n@dots{}} with value @var{r@dots{}}, which contains two hex
8e04817f 21628digits for each byte in the register (target byte order).
c906108c 21629
ee2d5c50
AC
21630Reply:
21631@table @samp
21632@item OK
21633for success
21634@item E@var{NN}
21635for an error
21636@end table
21637
21638@item @code{q}@var{query} --- general query
21639@anchor{general query packet}
21640@cindex @code{q} packet
21641
21642Request info about @var{query}. In general @value{GDBN} queries have a
21643leading upper case letter. Custom vendor queries should use a company
21644prefix (in lower case) ex: @samp{qfsf.var}. @var{query} may optionally
21645be followed by a @samp{,} or @samp{;} separated list. Stubs must ensure
21646that they match the full @var{query} name.
21647
21648Reply:
21649@table @samp
21650@item @var{XX@dots{}}
21651Hex encoded data from query. The reply can not be empty.
21652@item E@var{NN}
21653error reply
8e04817f 21654@item
ee2d5c50
AC
21655Indicating an unrecognized @var{query}.
21656@end table
21657
21658@item @code{Q}@var{var}@code{=}@var{val} --- general set
21659@cindex @code{Q} packet
21660
21661Set value of @var{var} to @var{val}.
21662
21663@xref{general query packet}, for a discussion of naming conventions.
c906108c 21664
ee2d5c50
AC
21665@item @code{r} --- reset @strong{(deprecated)}
21666@cindex @code{r} packet
c906108c 21667
8e04817f 21668Reset the entire system.
c906108c 21669
ee2d5c50
AC
21670@item @code{R}@var{XX} --- remote restart
21671@cindex @code{R} packet
21672
8e04817f
AC
21673Restart the program being debugged. @var{XX}, while needed, is ignored.
21674This packet is only available in extended mode.
ee2d5c50
AC
21675
21676Reply:
21677@table @samp
21678@item @emph{no reply}
8e04817f 21679The @samp{R} packet has no reply.
ee2d5c50
AC
21680@end table
21681
21682@item @code{s}@var{addr} --- step
21683@cindex @code{s} packet
c906108c 21684
8e04817f
AC
21685@var{addr} is address to resume. If @var{addr} is omitted, resume at
21686same address.
c906108c 21687
ee2d5c50
AC
21688Reply:
21689@xref{Stop Reply Packets}, for the reply specifications.
21690
21691@item @code{S}@var{sig}@code{;}@var{addr} --- step with signal
21692@anchor{step with signal packet}
21693@cindex @code{S} packet
21694
8e04817f 21695Like @samp{C} but step not continue.
c906108c 21696
ee2d5c50
AC
21697Reply:
21698@xref{Stop Reply Packets}, for the reply specifications.
21699
b383017d 21700@item @code{t}@var{addr}@code{:}@var{PP}@code{,}@var{MM} --- search
ee2d5c50
AC
21701@cindex @code{t} packet
21702
8e04817f 21703Search backwards starting at address @var{addr} for a match with pattern
ee2d5c50
AC
21704@var{PP} and mask @var{MM}. @var{PP} and @var{MM} are 4 bytes.
21705@var{addr} must be at least 3 digits.
c906108c 21706
ee2d5c50
AC
21707@item @code{T}@var{XX} --- thread alive
21708@cindex @code{T} packet
c906108c 21709
ee2d5c50 21710Find out if the thread XX is alive.
c906108c 21711
ee2d5c50
AC
21712Reply:
21713@table @samp
21714@item OK
21715thread is still alive
21716@item E@var{NN}
21717thread is dead
21718@end table
21719
21720@item @code{u} --- reserved
21721
21722Reserved for future use.
21723
21724@item @code{U} --- reserved
21725
21726Reserved for future use.
21727
86d30acc 21728@item @code{v} --- verbose packet prefix
ee2d5c50 21729
86d30acc
DJ
21730Packets starting with @code{v} are identified by a multi-letter name,
21731up to the first @code{;} or @code{?} (or the end of the packet).
21732
21733@item @code{vCont}[;@var{action}[@code{:}@var{tid}]]... --- extended resume
21734@cindex @code{vCont} packet
21735
21736Resume the inferior. Different actions may be specified for each thread.
21737If an action is specified with no @var{tid}, then it is applied to any
21738threads that don't have a specific action specified; if no default action is
21739specified then other threads should remain stopped. Specifying multiple
21740default actions is an error; specifying no actions is also an error.
21741Thread IDs are specified in hexadecimal. Currently supported actions are:
21742
21743@table @code
21744@item c
21745Continue.
21746@item C@var{sig}
21747Continue with signal @var{sig}. @var{sig} should be two hex digits.
21748@item s
21749Step.
21750@item S@var{sig}
21751Step with signal @var{sig}. @var{sig} should be two hex digits.
21752@end table
21753
21754The optional @var{addr} argument normally associated with these packets is
21755not supported in @code{vCont}.
21756
21757Reply:
21758@xref{Stop Reply Packets}, for the reply specifications.
21759
21760@item @code{vCont?} --- extended resume query
21761@cindex @code{vCont?} packet
21762
21763Query support for the @code{vCont} packet.
21764
21765Reply:
21766@table @samp
21767@item @code{vCont}[;@var{action}]...
21768The @code{vCont} packet is supported. Each @var{action} is a supported
21769command in the @code{vCont} packet.
21770@item
21771The @code{vCont} packet is not supported.
21772@end table
ee2d5c50
AC
21773
21774@item @code{V} --- reserved
c906108c 21775
ee2d5c50 21776Reserved for future use.
c906108c 21777
ee2d5c50 21778@item @code{w} --- reserved
c906108c 21779
ee2d5c50 21780Reserved for future use.
c906108c 21781
ee2d5c50 21782@item @code{W} --- reserved
c906108c 21783
ee2d5c50 21784Reserved for future use.
c906108c 21785
ee2d5c50
AC
21786@item @code{x} --- reserved
21787
21788Reserved for future use.
21789
21790@item @code{X}@var{addr}@code{,}@var{length}@var{:}@var{XX@dots{}} --- write mem (binary)
21791@cindex @code{X} packet
21792
21793@var{addr} is address, @var{length} is number of bytes, @var{XX@dots{}}
21794is binary data. The characters @code{$}, @code{#}, and @code{0x7d} are
69065f5d
AC
21795escaped using @code{0x7d}, and then XORed with @code{0x20}.
21796For example, @code{0x7d} would be transmitted as @code{0x7d 0x5d}.
c906108c 21797
ee2d5c50
AC
21798Reply:
21799@table @samp
21800@item OK
21801for success
21802@item E@var{NN}
21803for an error
21804@end table
21805
21806@item @code{y} --- reserved
c906108c 21807
ee2d5c50 21808Reserved for future use.
c906108c 21809
ee2d5c50
AC
21810@item @code{Y} reserved
21811
21812Reserved for future use.
21813
2f870471
AC
21814@item @code{z}@var{type}@code{,}@var{addr}@code{,}@var{length} --- remove breakpoint or watchpoint @strong{(draft)}
21815@itemx @code{Z}@var{type}@code{,}@var{addr}@code{,}@var{length} --- insert breakpoint or watchpoint @strong{(draft)}
21816@anchor{insert breakpoint or watchpoint packet}
ee2d5c50 21817@cindex @code{z} packet
2f870471 21818@cindex @code{Z} packets
ee2d5c50 21819
2f870471
AC
21820Insert (@code{Z}) or remove (@code{z}) a @var{type} breakpoint or
21821watchpoint starting at address @var{address} and covering the next
21822@var{length} bytes.
ee2d5c50 21823
2f870471
AC
21824Each breakpoint and watchpoint packet @var{type} is documented
21825separately.
21826
512217c7
AC
21827@emph{Implementation notes: A remote target shall return an empty string
21828for an unrecognized breakpoint or watchpoint packet @var{type}. A
21829remote target shall support either both or neither of a given
2f870471
AC
21830@code{Z}@var{type}@dots{} and @code{z}@var{type}@dots{} packet pair. To
21831avoid potential problems with duplicate packets, the operations should
21832be implemented in an idempotent way.}
21833
21834@item @code{z}@code{0}@code{,}@var{addr}@code{,}@var{length} --- remove memory breakpoint @strong{(draft)}
21835@item @code{Z}@code{0}@code{,}@var{addr}@code{,}@var{length} --- insert memory breakpoint @strong{(draft)}
21836@cindex @code{z0} packet
21837@cindex @code{Z0} packet
21838
21839Insert (@code{Z0}) or remove (@code{z0}) a memory breakpoint at address
21840@code{addr} of size @code{length}.
21841
21842A memory breakpoint is implemented by replacing the instruction at
21843@var{addr} with a software breakpoint or trap instruction. The
21844@code{length} is used by targets that indicates the size of the
21845breakpoint (in bytes) that should be inserted (e.g., the @sc{arm} and
21846@sc{mips} can insert either a 2 or 4 byte breakpoint).
c906108c 21847
2f870471
AC
21848@emph{Implementation note: It is possible for a target to copy or move
21849code that contains memory breakpoints (e.g., when implementing
21850overlays). The behavior of this packet, in the presence of such a
21851target, is not defined.}
c906108c 21852
ee2d5c50
AC
21853Reply:
21854@table @samp
2f870471
AC
21855@item OK
21856success
21857@item
21858not supported
ee2d5c50
AC
21859@item E@var{NN}
21860for an error
2f870471
AC
21861@end table
21862
21863@item @code{z}@code{1}@code{,}@var{addr}@code{,}@var{length} --- remove hardware breakpoint @strong{(draft)}
21864@item @code{Z}@code{1}@code{,}@var{addr}@code{,}@var{length} --- insert hardware breakpoint @strong{(draft)}
21865@cindex @code{z1} packet
21866@cindex @code{Z1} packet
21867
21868Insert (@code{Z1}) or remove (@code{z1}) a hardware breakpoint at
21869address @code{addr} of size @code{length}.
21870
21871A hardware breakpoint is implemented using a mechanism that is not
21872dependant on being able to modify the target's memory.
21873
21874@emph{Implementation note: A hardware breakpoint is not affected by code
21875movement.}
21876
21877Reply:
21878@table @samp
ee2d5c50 21879@item OK
2f870471
AC
21880success
21881@item
21882not supported
21883@item E@var{NN}
21884for an error
21885@end table
21886
21887@item @code{z}@code{2}@code{,}@var{addr}@code{,}@var{length} --- remove write watchpoint @strong{(draft)}
21888@item @code{Z}@code{2}@code{,}@var{addr}@code{,}@var{length} --- insert write watchpoint @strong{(draft)}
21889@cindex @code{z2} packet
21890@cindex @code{Z2} packet
21891
21892Insert (@code{Z2}) or remove (@code{z2}) a write watchpoint.
21893
21894Reply:
21895@table @samp
21896@item OK
21897success
21898@item
21899not supported
21900@item E@var{NN}
21901for an error
21902@end table
21903
21904@item @code{z}@code{3}@code{,}@var{addr}@code{,}@var{length} --- remove read watchpoint @strong{(draft)}
21905@item @code{Z}@code{3}@code{,}@var{addr}@code{,}@var{length} --- insert read watchpoint @strong{(draft)}
21906@cindex @code{z3} packet
21907@cindex @code{Z3} packet
21908
2e834e49 21909Insert (@code{Z3}) or remove (@code{z3}) a read watchpoint.
2f870471
AC
21910
21911Reply:
21912@table @samp
21913@item OK
21914success
21915@item
21916not supported
21917@item E@var{NN}
21918for an error
21919@end table
21920
2e834e49
HPN
21921@item @code{z}@code{4}@code{,}@var{addr}@code{,}@var{length} --- remove access watchpoint @strong{(draft)}
21922@item @code{Z}@code{4}@code{,}@var{addr}@code{,}@var{length} --- insert access watchpoint @strong{(draft)}
2f870471
AC
21923@cindex @code{z4} packet
21924@cindex @code{Z4} packet
21925
21926Insert (@code{Z4}) or remove (@code{z4}) an access watchpoint.
21927
21928Reply:
21929@table @samp
21930@item OK
21931success
21932@item
21933not supported
21934@item E@var{NN}
21935for an error
ee2d5c50
AC
21936@end table
21937
21938@end table
c906108c 21939
ee2d5c50
AC
21940@node Stop Reply Packets
21941@section Stop Reply Packets
21942@cindex stop reply packets
c906108c 21943
8e04817f
AC
21944The @samp{C}, @samp{c}, @samp{S}, @samp{s} and @samp{?} packets can
21945receive any of the below as a reply. In the case of the @samp{C},
21946@samp{c}, @samp{S} and @samp{s} packets, that reply is only returned
21947when the target halts. In the below the exact meaning of @samp{signal
21948number} is poorly defined. In general one of the UNIX signal numbering
21949conventions is used.
c906108c 21950
ee2d5c50 21951@table @samp
c906108c 21952
ee2d5c50
AC
21953@item S@var{AA}
21954@var{AA} is the signal number
c906108c 21955
8e04817f 21956@item @code{T}@var{AA}@var{n...}@code{:}@var{r...}@code{;}@var{n...}@code{:}@var{r...}@code{;}@var{n...}@code{:}@var{r...}@code{;}
ee2d5c50
AC
21957@cindex @code{T} packet reply
21958
8e04817f
AC
21959@var{AA} = two hex digit signal number; @var{n...} = register number
21960(hex), @var{r...} = target byte ordered register contents, size defined
12c266ea
AC
21961by @code{DEPRECATED_REGISTER_RAW_SIZE}; @var{n...} = @samp{thread},
21962@var{r...} = thread process ID, this is a hex integer; @var{n...} =
21963(@samp{watch} | @samp{rwatch} | @samp{awatch}, @var{r...} = data
21964address, this is a hex integer; @var{n...} = other string not starting
21965with valid hex digit. @value{GDBN} should ignore this @var{n...},
21966@var{r...} pair and go on to the next. This way we can extend the
21967protocol.
c906108c 21968
ee2d5c50
AC
21969@item W@var{AA}
21970
8e04817f 21971The process exited, and @var{AA} is the exit status. This is only
ee2d5c50
AC
21972applicable to certain targets.
21973
21974@item X@var{AA}
c906108c 21975
8e04817f 21976The process terminated with signal @var{AA}.
c906108c 21977
ee2d5c50 21978@item O@var{XX@dots{}}
c906108c 21979
ee2d5c50
AC
21980@var{XX@dots{}} is hex encoding of @sc{ascii} data. This can happen at
21981any time while the program is running and the debugger should continue
21982to wait for @samp{W}, @samp{T}, etc.
21983
0ce1b118
CV
21984@item F@var{call-id}@code{,}@var{parameter@dots{}}
21985
21986@var{call-id} is the identifier which says which host system call should
21987be called. This is just the name of the function. Translation into the
21988correct system call is only applicable as it's defined in @value{GDBN}.
21989@xref{File-I/O remote protocol extension}, for a list of implemented
21990system calls.
21991
21992@var{parameter@dots{}} is a list of parameters as defined for this very
21993system call.
21994
21995The target replies with this packet when it expects @value{GDBN} to call
21996a host system call on behalf of the target. @value{GDBN} replies with
21997an appropriate @code{F} packet and keeps up waiting for the next reply
21998packet from the target. The latest @samp{C}, @samp{c}, @samp{S} or
21999@samp{s} action is expected to be continued.
22000@xref{File-I/O remote protocol extension}, for more details.
22001
ee2d5c50
AC
22002@end table
22003
22004@node General Query Packets
22005@section General Query Packets
9c16f35a 22006@cindex remote query requests
c906108c 22007
8e04817f 22008The following set and query packets have already been defined.
c906108c 22009
ee2d5c50 22010@table @r
c906108c 22011
ee2d5c50 22012@item @code{q}@code{C} --- current thread
9c16f35a
EZ
22013@cindex current thread, remote request
22014@cindex @code{qC} packet
ee2d5c50
AC
22015Return the current thread id.
22016
22017Reply:
22018@table @samp
22019@item @code{QC}@var{pid}
e1aac25b 22020Where @var{pid} is an unsigned hexidecimal process id.
ee2d5c50
AC
22021@item *
22022Any other reply implies the old pid.
22023@end table
22024
22025@item @code{q}@code{fThreadInfo} -- all thread ids
9c16f35a
EZ
22026@cindex list active threads, remote request
22027@cindex @code{qfThreadInfo} packet
ee2d5c50 22028@code{q}@code{sThreadInfo}
c906108c 22029
8e04817f
AC
22030Obtain a list of active thread ids from the target (OS). Since there
22031may be too many active threads to fit into one reply packet, this query
22032works iteratively: it may require more than one query/reply sequence to
22033obtain the entire list of threads. The first query of the sequence will
22034be the @code{qf}@code{ThreadInfo} query; subsequent queries in the
22035sequence will be the @code{qs}@code{ThreadInfo} query.
ee2d5c50
AC
22036
22037NOTE: replaces the @code{qL} query (see below).
22038
22039Reply:
22040@table @samp
22041@item @code{m}@var{id}
22042A single thread id
22043@item @code{m}@var{id},@var{id}@dots{}
22044a comma-separated list of thread ids
22045@item @code{l}
22046(lower case 'el') denotes end of list.
22047@end table
22048
22049In response to each query, the target will reply with a list of one or
e1aac25b
JB
22050more thread ids, in big-endian unsigned hex, separated by commas.
22051@value{GDBN} will respond to each reply with a request for more thread
22052ids (using the @code{qs} form of the query), until the target responds
22053with @code{l} (lower-case el, for @code{'last'}).
c906108c 22054
ee2d5c50 22055@item @code{q}@code{ThreadExtraInfo}@code{,}@var{id} --- extra thread info
9c16f35a
EZ
22056@cindex thread attributes info, remote request
22057@cindex @code{qThreadExtraInfo} packet
ee2d5c50
AC
22058Where @var{id} is a thread-id in big-endian hex. Obtain a printable
22059string description of a thread's attributes from the target OS. This
22060string may contain anything that the target OS thinks is interesting for
22061@value{GDBN} to tell the user about the thread. The string is displayed
22062in @value{GDBN}'s @samp{info threads} display. Some examples of
22063possible thread extra info strings are ``Runnable'', or ``Blocked on
22064Mutex''.
22065
22066Reply:
22067@table @samp
22068@item @var{XX@dots{}}
22069Where @var{XX@dots{}} is a hex encoding of @sc{ascii} data, comprising
22070the printable string containing the extra information about the thread's
8e04817f 22071attributes.
ee2d5c50
AC
22072@end table
22073
22074@item @code{q}@code{L}@var{startflag}@var{threadcount}@var{nextthread} --- query @var{LIST} or @var{threadLIST} @strong{(deprecated)}
c906108c 22075
8e04817f
AC
22076Obtain thread information from RTOS. Where: @var{startflag} (one hex
22077digit) is one to indicate the first query and zero to indicate a
22078subsequent query; @var{threadcount} (two hex digits) is the maximum
22079number of threads the response packet can contain; and @var{nextthread}
22080(eight hex digits), for subsequent queries (@var{startflag} is zero), is
22081returned in the response as @var{argthread}.
ee2d5c50
AC
22082
22083NOTE: this query is replaced by the @code{q}@code{fThreadInfo} query
22084(see above).
22085
22086Reply:
22087@table @samp
22088@item @code{q}@code{M}@var{count}@var{done}@var{argthread}@var{thread@dots{}}
8e04817f
AC
22089Where: @var{count} (two hex digits) is the number of threads being
22090returned; @var{done} (one hex digit) is zero to indicate more threads
22091and one indicates no further threads; @var{argthreadid} (eight hex
ee2d5c50
AC
22092digits) is @var{nextthread} from the request packet; @var{thread@dots{}}
22093is a sequence of thread IDs from the target. @var{threadid} (eight hex
8e04817f 22094digits). See @code{remote.c:parse_threadlist_response()}.
ee2d5c50 22095@end table
c906108c 22096
ee2d5c50 22097@item @code{q}@code{CRC:}@var{addr}@code{,}@var{length} --- compute CRC of memory block
9c16f35a
EZ
22098@cindex CRC of memory block, remote request
22099@cindex @code{qCRC} packet
ee2d5c50
AC
22100Reply:
22101@table @samp
22102@item @code{E}@var{NN}
22103An error (such as memory fault)
22104@item @code{C}@var{CRC32}
22105A 32 bit cyclic redundancy check of the specified memory region.
22106@end table
22107
22108@item @code{q}@code{Offsets} --- query sect offs
9c16f35a
EZ
22109@cindex section offsets, remote request
22110@cindex @code{qOffsets} packet
8e04817f
AC
22111Get section offsets that the target used when re-locating the downloaded
22112image. @emph{Note: while a @code{Bss} offset is included in the
22113response, @value{GDBN} ignores this and instead applies the @code{Data}
22114offset to the @code{Bss} section.}
c906108c 22115
ee2d5c50
AC
22116Reply:
22117@table @samp
22118@item @code{Text=}@var{xxx}@code{;Data=}@var{yyy}@code{;Bss=}@var{zzz}
22119@end table
22120
22121@item @code{q}@code{P}@var{mode}@var{threadid} --- thread info request
9c16f35a
EZ
22122@cindex thread information, remote request
22123@cindex @code{qP} packet
8e04817f
AC
22124Returns information on @var{threadid}. Where: @var{mode} is a hex
22125encoded 32 bit mode; @var{threadid} is a hex encoded 64 bit thread ID.
ee2d5c50
AC
22126
22127Reply:
22128@table @samp
22129@item *
22130@end table
22131
8e04817f 22132See @code{remote.c:remote_unpack_thread_info_response()}.
c906108c 22133
ee2d5c50 22134@item @code{q}@code{Rcmd,}@var{command} --- remote command
9c16f35a
EZ
22135@cindex execute remote command, remote request
22136@cindex @code{qRcmd} packet
ee2d5c50 22137@var{command} (hex encoded) is passed to the local interpreter for
8e04817f
AC
22138execution. Invalid commands should be reported using the output string.
22139Before the final result packet, the target may also respond with a
ee2d5c50
AC
22140number of intermediate @code{O}@var{output} console output packets.
22141@emph{Implementors should note that providing access to a stubs's
22142interpreter may have security implications}.
22143
22144Reply:
22145@table @samp
22146@item OK
8e04817f 22147A command response with no output.
ee2d5c50 22148@item @var{OUTPUT}
8e04817f 22149A command response with the hex encoded output string @var{OUTPUT}.
ee2d5c50 22150@item @code{E}@var{NN}
8e04817f 22151Indicate a badly formed request.
ee2d5c50 22152@item @samp{}
8e04817f 22153When @samp{q}@samp{Rcmd} is not recognized.
ee2d5c50 22154@end table
9c16f35a 22155z
ee2d5c50 22156@item @code{qSymbol::} --- symbol lookup
9c16f35a
EZ
22157@cindex symbol lookup, remote request
22158@cindex @code{qSymbol} packet
8e04817f
AC
22159Notify the target that @value{GDBN} is prepared to serve symbol lookup
22160requests. Accept requests from the target for the values of symbols.
ee2d5c50
AC
22161
22162Reply:
22163@table @samp
22164@item @code{OK}
8e04817f 22165The target does not need to look up any (more) symbols.
ee2d5c50
AC
22166@item @code{qSymbol:}@var{sym_name}
22167The target requests the value of symbol @var{sym_name} (hex encoded).
22168@value{GDBN} may provide the value by using the
22169@code{qSymbol:}@var{sym_value}:@var{sym_name} message, described below.
22170@end table
22171
22172@item @code{qSymbol:}@var{sym_value}:@var{sym_name} --- symbol value
22173
22174Set the value of @var{sym_name} to @var{sym_value}.
22175
22176@var{sym_name} (hex encoded) is the name of a symbol whose value the
22177target has previously requested.
22178
22179@var{sym_value} (hex) is the value for symbol @var{sym_name}. If
22180@value{GDBN} cannot supply a value for @var{sym_name}, then this field
22181will be empty.
22182
22183Reply:
22184@table @samp
22185@item @code{OK}
8e04817f 22186The target does not need to look up any (more) symbols.
ee2d5c50
AC
22187@item @code{qSymbol:}@var{sym_name}
22188The target requests the value of a new symbol @var{sym_name} (hex
22189encoded). @value{GDBN} will continue to supply the values of symbols
22190(if available), until the target ceases to request them.
22191@end table
eb12ee30 22192
649e03f6 22193@item @code{qPart}:@var{object}:@code{read}:@var{annex}:@var{offset},@var{length} --- read special data
9c16f35a
EZ
22194@cindex read special object, remote request
22195@cindex @code{qPart} packet
649e03f6
RM
22196Read uninterpreted bytes from the target's special data area
22197identified by the keyword @code{object}.
22198Request @var{length} bytes starting at @var{offset} bytes into the data.
22199The content and encoding of @var{annex} is specific to the object;
22200it can supply additional details about what data to access.
22201
22202Here are the specific requests of this form defined so far.
22203All @samp{@code{qPart}:@var{object}:@code{read}:@dots{}}
22204requests use the same reply formats, listed below.
22205
22206@table @asis
22207@item @code{qPart}:@code{auxv}:@code{read}::@var{offset},@var{length}
9c16f35a
EZ
22208Access the target's @dfn{auxiliary vector}. @xref{Auxiliary Vector},
22209and see @ref{Remote configuration, read-aux-vector-packet}.
649e03f6
RM
22210Note @var{annex} must be empty.
22211@end table
22212
22213Reply:
22214@table @asis
22215@item @code{OK}
22216The @var{offset} in the request is at the end of the data.
22217There is no more data to be read.
22218
22219@item @var{XX@dots{}}
22220Hex encoded data bytes read.
22221This may be fewer bytes than the @var{length} in the request.
22222
22223@item @code{E00}
22224The request was malformed, or @var{annex} was invalid.
22225
22226@item @code{E}@var{nn}
22227The offset was invalid, or there was an error encountered reading the data.
22228@var{nn} is a hex-encoded @code{errno} value.
22229
22230@item @code{""} (empty)
22231An empty reply indicates the @var{object} or @var{annex} string was not
22232recognized by the stub.
22233@end table
22234
22235@item @code{qPart}:@var{object}:@code{write}:@var{annex}:@var{offset}:@var{data@dots{}}
9c16f35a 22236@cindex write data into object, remote request
649e03f6
RM
22237Write uninterpreted bytes into the target's special data area
22238identified by the keyword @code{object},
22239starting at @var{offset} bytes into the data.
22240@var{data@dots{}} is the hex-encoded data to be written.
22241The content and encoding of @var{annex} is specific to the object;
22242it can supply additional details about what data to access.
22243
22244No requests of this form are presently in use. This specification
22245serves as a placeholder to document the common format that new
22246specific request specifications ought to use.
22247
22248Reply:
22249@table @asis
22250@item @var{nn}
22251@var{nn} (hex encoded) is the number of bytes written.
22252This may be fewer bytes than supplied in the request.
22253
22254@item @code{E00}
22255The request was malformed, or @var{annex} was invalid.
22256
22257@item @code{E}@var{nn}
22258The offset was invalid, or there was an error encountered writing the data.
22259@var{nn} is a hex-encoded @code{errno} value.
22260
22261@item @code{""} (empty)
22262An empty reply indicates the @var{object} or @var{annex} string was not
22263recognized by the stub, or that the object does not support writing.
22264@end table
22265
22266@item @code{qPart}:@var{object}:@var{operation}:@dots{}
22267Requests of this form may be added in the future. When a stub does
22268not recognize the @var{object} keyword, or its support for
22269@var{object} does not recognize the @var{operation} keyword,
22270the stub must respond with an empty packet.
83761cbd
KB
22271
22272@item @code{qGetTLSAddr}:@var{thread-id},@var{offset},@var{lm} --- get thread local storage address
9c16f35a
EZ
22273@cindex get thread-local storage address, remote request
22274@cindex @code{qGetTLSAddr} packet
83761cbd
KB
22275Fetch the address associated with thread local storage specified
22276by @var{thread-id}, @var{offset}, and @var{lm}.
22277
22278@var{thread-id} is the (big endian, hex encoded) thread id associated with the
22279thread for which to fetch the TLS address.
22280
22281@var{offset} is the (big endian, hex encoded) offset associated with the
22282thread local variable. (This offset is obtained from the debug
22283information associated with the variable.)
22284
22285@var{lm} is the (big endian, hex encoded) OS/ABI specific encoding of the
22286the load module associated with the thread local storage. For example,
22287a @sc{gnu}/Linux system will pass the link map address of the shared
22288object associated with the thread local storage under consideration.
22289Other operating environments may choose to represent the load module
22290differently, so the precise meaning of this parameter will vary.
22291
22292Reply:
22293@table @asis
68c71a2e 22294@item @var{XX@dots{}}
83761cbd
KB
22295Hex encoded (big endian) bytes representing the address of the thread
22296local storage requested.
22297
22298@item @code{E}@var{nn} (where @var{nn} are hex digits)
22299An error occurred.
22300
22301@item @code{""} (empty)
22302An empty reply indicates that @code{qGetTLSAddr} is not supported by the stub.
22303@end table
22304
ee2d5c50
AC
22305@end table
22306
22307@node Register Packet Format
22308@section Register Packet Format
eb12ee30 22309
8e04817f 22310The following @samp{g}/@samp{G} packets have previously been defined.
ee2d5c50
AC
22311In the below, some thirty-two bit registers are transferred as
22312sixty-four bits. Those registers should be zero/sign extended (which?)
22313to fill the space allocated. Register bytes are transfered in target
22314byte order. The two nibbles within a register byte are transfered
22315most-significant - least-significant.
eb12ee30 22316
ee2d5c50 22317@table @r
eb12ee30 22318
8e04817f 22319@item MIPS32
ee2d5c50 22320
8e04817f
AC
22321All registers are transfered as thirty-two bit quantities in the order:
2232232 general-purpose; sr; lo; hi; bad; cause; pc; 32 floating-point
22323registers; fsr; fir; fp.
eb12ee30 22324
8e04817f 22325@item MIPS64
ee2d5c50 22326
8e04817f
AC
22327All registers are transfered as sixty-four bit quantities (including
22328thirty-two bit registers such as @code{sr}). The ordering is the same
22329as @code{MIPS32}.
eb12ee30 22330
ee2d5c50
AC
22331@end table
22332
22333@node Examples
22334@section Examples
eb12ee30 22335
8e04817f
AC
22336Example sequence of a target being re-started. Notice how the restart
22337does not get any direct output:
eb12ee30 22338
474c8240 22339@smallexample
d2c6833e
AC
22340-> @code{R00}
22341<- @code{+}
8e04817f 22342@emph{target restarts}
d2c6833e 22343-> @code{?}
8e04817f 22344<- @code{+}
d2c6833e
AC
22345<- @code{T001:1234123412341234}
22346-> @code{+}
474c8240 22347@end smallexample
eb12ee30 22348
8e04817f 22349Example sequence of a target being stepped by a single instruction:
eb12ee30 22350
474c8240 22351@smallexample
d2c6833e 22352-> @code{G1445@dots{}}
8e04817f 22353<- @code{+}
d2c6833e
AC
22354-> @code{s}
22355<- @code{+}
22356@emph{time passes}
22357<- @code{T001:1234123412341234}
8e04817f 22358-> @code{+}
d2c6833e 22359-> @code{g}
8e04817f 22360<- @code{+}
d2c6833e
AC
22361<- @code{1455@dots{}}
22362-> @code{+}
474c8240 22363@end smallexample
eb12ee30 22364
0ce1b118
CV
22365@node File-I/O remote protocol extension
22366@section File-I/O remote protocol extension
22367@cindex File-I/O remote protocol extension
22368
22369@menu
22370* File-I/O Overview::
22371* Protocol basics::
1d8b2f28
JB
22372* The F request packet::
22373* The F reply packet::
0ce1b118
CV
22374* Memory transfer::
22375* The Ctrl-C message::
22376* Console I/O::
22377* The isatty call::
22378* The system call::
22379* List of supported calls::
22380* Protocol specific representation of datatypes::
22381* Constants::
22382* File-I/O Examples::
22383@end menu
22384
22385@node File-I/O Overview
22386@subsection File-I/O Overview
22387@cindex file-i/o overview
22388
9c16f35a
EZ
22389The @dfn{File I/O remote protocol extension} (short: File-I/O) allows the
22390target to use the host's file system and console I/O when calling various
0ce1b118
CV
22391system calls. System calls on the target system are translated into a
22392remote protocol packet to the host system which then performs the needed
22393actions and returns with an adequate response packet to the target system.
22394This simulates file system operations even on targets that lack file systems.
22395
22396The protocol is defined host- and target-system independent. It uses
9c16f35a 22397its own independent representation of datatypes and values. Both,
0ce1b118
CV
22398@value{GDBN} and the target's @value{GDBN} stub are responsible for
22399translating the system dependent values into the unified protocol values
22400when data is transmitted.
22401
22402The communication is synchronous. A system call is possible only
22403when GDB is waiting for the @samp{C}, @samp{c}, @samp{S} or @samp{s}
22404packets. While @value{GDBN} handles the request for a system call,
22405the target is stopped to allow deterministic access to the target's
22406memory. Therefore File-I/O is not interuptible by target signals. It
22407is possible to interrupt File-I/O by a user interrupt (Ctrl-C), though.
22408
22409The target's request to perform a host system call does not finish
22410the latest @samp{C}, @samp{c}, @samp{S} or @samp{s} action. That means,
22411after finishing the system call, the target returns to continuing the
22412previous activity (continue, step). No additional continue or step
22413request from @value{GDBN} is required.
22414
22415@smallexample
f7dc1244 22416(@value{GDBP}) continue
0ce1b118
CV
22417 <- target requests 'system call X'
22418 target is stopped, @value{GDBN} executes system call
22419 -> GDB returns result
22420 ... target continues, GDB returns to wait for the target
22421 <- target hits breakpoint and sends a Txx packet
22422@end smallexample
22423
22424The protocol is only used for files on the host file system and
22425for I/O on the console. Character or block special devices, pipes,
22426named pipes or sockets or any other communication method on the host
22427system are not supported by this protocol.
22428
22429@node Protocol basics
22430@subsection Protocol basics
22431@cindex protocol basics, file-i/o
22432
22433The File-I/O protocol uses the @code{F} packet, as request as well
22434as as reply packet. Since a File-I/O system call can only occur when
b383017d 22435@value{GDBN} is waiting for the continuing or stepping target, the
0ce1b118
CV
22436File-I/O request is a reply that @value{GDBN} has to expect as a result
22437of a former @samp{C}, @samp{c}, @samp{S} or @samp{s} packet.
22438This @code{F} packet contains all information needed to allow @value{GDBN}
22439to call the appropriate host system call:
22440
22441@itemize @bullet
b383017d 22442@item
0ce1b118
CV
22443A unique identifier for the requested system call.
22444
22445@item
22446All parameters to the system call. Pointers are given as addresses
22447in the target memory address space. Pointers to strings are given as
b383017d 22448pointer/length pair. Numerical values are given as they are.
0ce1b118
CV
22449Numerical control values are given in a protocol specific representation.
22450
22451@end itemize
22452
22453At that point @value{GDBN} has to perform the following actions.
22454
22455@itemize @bullet
b383017d 22456@item
0ce1b118
CV
22457If parameter pointer values are given, which point to data needed as input
22458to a system call, @value{GDBN} requests this data from the target with a
22459standard @code{m} packet request. This additional communication has to be
22460expected by the target implementation and is handled as any other @code{m}
22461packet.
22462
22463@item
22464@value{GDBN} translates all value from protocol representation to host
22465representation as needed. Datatypes are coerced into the host types.
22466
22467@item
22468@value{GDBN} calls the system call
22469
22470@item
22471It then coerces datatypes back to protocol representation.
22472
22473@item
22474If pointer parameters in the request packet point to buffer space in which
22475a system call is expected to copy data to, the data is transmitted to the
22476target using a @code{M} or @code{X} packet. This packet has to be expected
22477by the target implementation and is handled as any other @code{M} or @code{X}
22478packet.
22479
22480@end itemize
22481
22482Eventually @value{GDBN} replies with another @code{F} packet which contains all
22483necessary information for the target to continue. This at least contains
22484
22485@itemize @bullet
22486@item
22487Return value.
22488
22489@item
22490@code{errno}, if has been changed by the system call.
22491
22492@item
22493``Ctrl-C'' flag.
22494
22495@end itemize
22496
22497After having done the needed type and value coercion, the target continues
22498the latest continue or step action.
22499
1d8b2f28 22500@node The F request packet
0ce1b118
CV
22501@subsection The @code{F} request packet
22502@cindex file-i/o request packet
22503@cindex @code{F} request packet
22504
22505The @code{F} request packet has the following format:
22506
22507@table @samp
22508
22509@smallexample
22510@code{F}@var{call-id}@code{,}@var{parameter@dots{}}
22511@end smallexample
22512
22513@var{call-id} is the identifier to indicate the host system call to be called.
22514This is just the name of the function.
22515
22516@var{parameter@dots{}} are the parameters to the system call.
22517
b383017d 22518@end table
0ce1b118
CV
22519
22520Parameters are hexadecimal integer values, either the real values in case
22521of scalar datatypes, as pointers to target buffer space in case of compound
22522datatypes and unspecified memory areas or as pointer/length pairs in case
22523of string parameters. These are appended to the call-id, each separated
22524from its predecessor by a comma. All values are transmitted in ASCII
22525string representation, pointer/length pairs separated by a slash.
22526
1d8b2f28 22527@node The F reply packet
0ce1b118
CV
22528@subsection The @code{F} reply packet
22529@cindex file-i/o reply packet
22530@cindex @code{F} reply packet
22531
22532The @code{F} reply packet has the following format:
22533
22534@table @samp
22535
22536@smallexample
22537@code{F}@var{retcode}@code{,}@var{errno}@code{,}@var{Ctrl-C flag}@code{;}@var{call specific attachment}
22538@end smallexample
22539
22540@var{retcode} is the return code of the system call as hexadecimal value.
22541
22542@var{errno} is the errno set by the call, in protocol specific representation.
22543This parameter can be omitted if the call was successful.
22544
22545@var{Ctrl-C flag} is only send if the user requested a break. In this
22546case, @var{errno} must be send as well, even if the call was successful.
22547The @var{Ctrl-C flag} itself consists of the character 'C':
22548
22549@smallexample
22550F0,0,C
22551@end smallexample
22552
22553@noindent
22554or, if the call was interupted before the host call has been performed:
22555
22556@smallexample
22557F-1,4,C
22558@end smallexample
22559
22560@noindent
22561assuming 4 is the protocol specific representation of @code{EINTR}.
22562
22563@end table
22564
22565@node Memory transfer
22566@subsection Memory transfer
22567@cindex memory transfer, in file-i/o protocol
22568
22569Structured data which is transferred using a memory read or write as e.g.@:
22570a @code{struct stat} is expected to be in a protocol specific format with
22571all scalar multibyte datatypes being big endian. This should be done by
22572the target before the @code{F} packet is sent resp.@: by @value{GDBN} before
22573it transfers memory to the target. Transferred pointers to structured
22574data should point to the already coerced data at any time.
22575
22576@node The Ctrl-C message
22577@subsection The Ctrl-C message
22578@cindex ctrl-c message, in file-i/o protocol
22579
22580A special case is, if the @var{Ctrl-C flag} is set in the @value{GDBN}
22581reply packet. In this case the target should behave, as if it had
22582gotten a break message. The meaning for the target is ``system call
22583interupted by @code{SIGINT}''. Consequentially, the target should actually stop
22584(as with a break message) and return to @value{GDBN} with a @code{T02}
b383017d 22585packet. In this case, it's important for the target to know, in which
0ce1b118
CV
22586state the system call was interrupted. Since this action is by design
22587not an atomic operation, we have to differ between two cases:
22588
22589@itemize @bullet
22590@item
22591The system call hasn't been performed on the host yet.
22592
22593@item
22594The system call on the host has been finished.
22595
22596@end itemize
22597
22598These two states can be distinguished by the target by the value of the
22599returned @code{errno}. If it's the protocol representation of @code{EINTR}, the system
22600call hasn't been performed. This is equivalent to the @code{EINTR} handling
22601on POSIX systems. In any other case, the target may presume that the
22602system call has been finished --- successful or not --- and should behave
22603as if the break message arrived right after the system call.
22604
22605@value{GDBN} must behave reliable. If the system call has not been called
22606yet, @value{GDBN} may send the @code{F} reply immediately, setting @code{EINTR} as
22607@code{errno} in the packet. If the system call on the host has been finished
22608before the user requests a break, the full action must be finshed by
22609@value{GDBN}. This requires sending @code{M} or @code{X} packets as they fit.
22610The @code{F} packet may only be send when either nothing has happened
22611or the full action has been completed.
22612
22613@node Console I/O
22614@subsection Console I/O
22615@cindex console i/o as part of file-i/o
22616
22617By default and if not explicitely closed by the target system, the file
22618descriptors 0, 1 and 2 are connected to the @value{GDBN} console. Output
22619on the @value{GDBN} console is handled as any other file output operation
22620(@code{write(1, @dots{})} or @code{write(2, @dots{})}). Console input is handled
22621by @value{GDBN} so that after the target read request from file descriptor
226220 all following typing is buffered until either one of the following
22623conditions is met:
22624
22625@itemize @bullet
22626@item
22627The user presses @kbd{Ctrl-C}. The behaviour is as explained above, the
22628@code{read}
22629system call is treated as finished.
22630
22631@item
22632The user presses @kbd{Enter}. This is treated as end of input with a trailing
22633line feed.
22634
22635@item
22636The user presses @kbd{Ctrl-D}. This is treated as end of input. No trailing
22637character, especially no Ctrl-D is appended to the input.
22638
22639@end itemize
22640
22641If the user has typed more characters as fit in the buffer given to
22642the read call, the trailing characters are buffered in @value{GDBN} until
22643either another @code{read(0, @dots{})} is requested by the target or debugging
22644is stopped on users request.
22645
22646@node The isatty call
22647@subsection The isatty(3) call
22648@cindex isatty call, file-i/o protocol
22649
22650A special case in this protocol is the library call @code{isatty} which
9c16f35a 22651is implemented as its own call inside of this protocol. It returns
0ce1b118
CV
226521 to the target if the file descriptor given as parameter is attached
22653to the @value{GDBN} console, 0 otherwise. Implementing through system calls
22654would require implementing @code{ioctl} and would be more complex than
22655needed.
22656
22657@node The system call
22658@subsection The system(3) call
22659@cindex system call, file-i/o protocol
22660
22661The other special case in this protocol is the @code{system} call which
9c16f35a 22662is implemented as its own call, too. @value{GDBN} is taking over the full
0ce1b118
CV
22663task of calling the necessary host calls to perform the @code{system}
22664call. The return value of @code{system} is simplified before it's returned
22665to the target. Basically, the only signal transmitted back is @code{EINTR}
22666in case the user pressed @kbd{Ctrl-C}. Otherwise the return value consists
22667entirely of the exit status of the called command.
22668
9c16f35a
EZ
22669Due to security concerns, the @code{system} call is by default refused
22670by @value{GDBN}. The user has to allow this call explicitly with the
22671@kbd{set remote system-call-allowed 1} command.
0ce1b118 22672
9c16f35a
EZ
22673@table @code
22674@item set remote system-call-allowed
22675@kindex set remote system-call-allowed
22676Control whether to allow the @code{system} calls in the File I/O
22677protocol for the remote target. The default is zero (disabled).
0ce1b118 22678
9c16f35a 22679@item show remote system-call-allowed
0ce1b118 22680@kindex show remote system-call-allowed
9c16f35a
EZ
22681Show the current setting of system calls for the remote File I/O
22682protocol.
0ce1b118
CV
22683@end table
22684
22685@node List of supported calls
22686@subsection List of supported calls
22687@cindex list of supported file-i/o calls
22688
22689@menu
22690* open::
22691* close::
22692* read::
22693* write::
22694* lseek::
22695* rename::
22696* unlink::
22697* stat/fstat::
22698* gettimeofday::
22699* isatty::
22700* system::
22701@end menu
22702
22703@node open
22704@unnumberedsubsubsec open
22705@cindex open, file-i/o system call
22706
22707@smallexample
22708@exdent Synopsis:
22709int open(const char *pathname, int flags);
22710int open(const char *pathname, int flags, mode_t mode);
22711
b383017d 22712@exdent Request:
0ce1b118
CV
22713Fopen,pathptr/len,flags,mode
22714@end smallexample
22715
22716@noindent
22717@code{flags} is the bitwise or of the following values:
22718
22719@table @code
b383017d 22720@item O_CREAT
0ce1b118
CV
22721If the file does not exist it will be created. The host
22722rules apply as far as file ownership and time stamps
22723are concerned.
22724
b383017d 22725@item O_EXCL
0ce1b118
CV
22726When used with O_CREAT, if the file already exists it is
22727an error and open() fails.
22728
b383017d 22729@item O_TRUNC
0ce1b118
CV
22730If the file already exists and the open mode allows
22731writing (O_RDWR or O_WRONLY is given) it will be
22732truncated to length 0.
22733
b383017d 22734@item O_APPEND
0ce1b118
CV
22735The file is opened in append mode.
22736
b383017d 22737@item O_RDONLY
0ce1b118
CV
22738The file is opened for reading only.
22739
b383017d 22740@item O_WRONLY
0ce1b118
CV
22741The file is opened for writing only.
22742
b383017d 22743@item O_RDWR
0ce1b118
CV
22744The file is opened for reading and writing.
22745
22746@noindent
22747Each other bit is silently ignored.
22748
22749@end table
22750
22751@noindent
22752@code{mode} is the bitwise or of the following values:
22753
22754@table @code
b383017d 22755@item S_IRUSR
0ce1b118
CV
22756User has read permission.
22757
b383017d 22758@item S_IWUSR
0ce1b118
CV
22759User has write permission.
22760
b383017d 22761@item S_IRGRP
0ce1b118
CV
22762Group has read permission.
22763
b383017d 22764@item S_IWGRP
0ce1b118
CV
22765Group has write permission.
22766
b383017d 22767@item S_IROTH
0ce1b118
CV
22768Others have read permission.
22769
b383017d 22770@item S_IWOTH
0ce1b118
CV
22771Others have write permission.
22772
22773@noindent
22774Each other bit is silently ignored.
22775
22776@end table
22777
22778@smallexample
22779@exdent Return value:
22780open returns the new file descriptor or -1 if an error
22781occured.
22782
22783@exdent Errors:
22784@end smallexample
22785
22786@table @code
b383017d 22787@item EEXIST
0ce1b118
CV
22788pathname already exists and O_CREAT and O_EXCL were used.
22789
b383017d 22790@item EISDIR
0ce1b118
CV
22791pathname refers to a directory.
22792
b383017d 22793@item EACCES
0ce1b118
CV
22794The requested access is not allowed.
22795
22796@item ENAMETOOLONG
22797pathname was too long.
22798
b383017d 22799@item ENOENT
0ce1b118
CV
22800A directory component in pathname does not exist.
22801
b383017d 22802@item ENODEV
0ce1b118
CV
22803pathname refers to a device, pipe, named pipe or socket.
22804
b383017d 22805@item EROFS
0ce1b118
CV
22806pathname refers to a file on a read-only filesystem and
22807write access was requested.
22808
b383017d 22809@item EFAULT
0ce1b118
CV
22810pathname is an invalid pointer value.
22811
b383017d 22812@item ENOSPC
0ce1b118
CV
22813No space on device to create the file.
22814
b383017d 22815@item EMFILE
0ce1b118
CV
22816The process already has the maximum number of files open.
22817
b383017d 22818@item ENFILE
0ce1b118
CV
22819The limit on the total number of files open on the system
22820has been reached.
22821
b383017d 22822@item EINTR
0ce1b118
CV
22823The call was interrupted by the user.
22824@end table
22825
22826@node close
22827@unnumberedsubsubsec close
22828@cindex close, file-i/o system call
22829
22830@smallexample
b383017d 22831@exdent Synopsis:
0ce1b118
CV
22832int close(int fd);
22833
b383017d 22834@exdent Request:
0ce1b118
CV
22835Fclose,fd
22836
22837@exdent Return value:
22838close returns zero on success, or -1 if an error occurred.
22839
22840@exdent Errors:
22841@end smallexample
22842
22843@table @code
b383017d 22844@item EBADF
0ce1b118
CV
22845fd isn't a valid open file descriptor.
22846
b383017d 22847@item EINTR
0ce1b118
CV
22848The call was interrupted by the user.
22849@end table
22850
22851@node read
22852@unnumberedsubsubsec read
22853@cindex read, file-i/o system call
22854
22855@smallexample
b383017d 22856@exdent Synopsis:
0ce1b118
CV
22857int read(int fd, void *buf, unsigned int count);
22858
b383017d 22859@exdent Request:
0ce1b118
CV
22860Fread,fd,bufptr,count
22861
22862@exdent Return value:
22863On success, the number of bytes read is returned.
22864Zero indicates end of file. If count is zero, read
b383017d 22865returns zero as well. On error, -1 is returned.
0ce1b118
CV
22866
22867@exdent Errors:
22868@end smallexample
22869
22870@table @code
b383017d 22871@item EBADF
0ce1b118
CV
22872fd is not a valid file descriptor or is not open for
22873reading.
22874
b383017d 22875@item EFAULT
0ce1b118
CV
22876buf is an invalid pointer value.
22877
b383017d 22878@item EINTR
0ce1b118
CV
22879The call was interrupted by the user.
22880@end table
22881
22882@node write
22883@unnumberedsubsubsec write
22884@cindex write, file-i/o system call
22885
22886@smallexample
b383017d 22887@exdent Synopsis:
0ce1b118
CV
22888int write(int fd, const void *buf, unsigned int count);
22889
b383017d 22890@exdent Request:
0ce1b118
CV
22891Fwrite,fd,bufptr,count
22892
22893@exdent Return value:
22894On success, the number of bytes written are returned.
22895Zero indicates nothing was written. On error, -1
22896is returned.
22897
22898@exdent Errors:
22899@end smallexample
22900
22901@table @code
b383017d 22902@item EBADF
0ce1b118
CV
22903fd is not a valid file descriptor or is not open for
22904writing.
22905
b383017d 22906@item EFAULT
0ce1b118
CV
22907buf is an invalid pointer value.
22908
b383017d 22909@item EFBIG
0ce1b118
CV
22910An attempt was made to write a file that exceeds the
22911host specific maximum file size allowed.
22912
b383017d 22913@item ENOSPC
0ce1b118
CV
22914No space on device to write the data.
22915
b383017d 22916@item EINTR
0ce1b118
CV
22917The call was interrupted by the user.
22918@end table
22919
22920@node lseek
22921@unnumberedsubsubsec lseek
22922@cindex lseek, file-i/o system call
22923
22924@smallexample
b383017d 22925@exdent Synopsis:
0ce1b118
CV
22926long lseek (int fd, long offset, int flag);
22927
b383017d 22928@exdent Request:
0ce1b118
CV
22929Flseek,fd,offset,flag
22930@end smallexample
22931
22932@code{flag} is one of:
22933
22934@table @code
b383017d 22935@item SEEK_SET
0ce1b118
CV
22936The offset is set to offset bytes.
22937
b383017d 22938@item SEEK_CUR
0ce1b118
CV
22939The offset is set to its current location plus offset
22940bytes.
22941
b383017d 22942@item SEEK_END
0ce1b118
CV
22943The offset is set to the size of the file plus offset
22944bytes.
22945@end table
22946
22947@smallexample
22948@exdent Return value:
22949On success, the resulting unsigned offset in bytes from
22950the beginning of the file is returned. Otherwise, a
22951value of -1 is returned.
22952
22953@exdent Errors:
22954@end smallexample
22955
22956@table @code
b383017d 22957@item EBADF
0ce1b118
CV
22958fd is not a valid open file descriptor.
22959
b383017d 22960@item ESPIPE
0ce1b118
CV
22961fd is associated with the @value{GDBN} console.
22962
b383017d 22963@item EINVAL
0ce1b118
CV
22964flag is not a proper value.
22965
b383017d 22966@item EINTR
0ce1b118
CV
22967The call was interrupted by the user.
22968@end table
22969
22970@node rename
22971@unnumberedsubsubsec rename
22972@cindex rename, file-i/o system call
22973
22974@smallexample
b383017d 22975@exdent Synopsis:
0ce1b118
CV
22976int rename(const char *oldpath, const char *newpath);
22977
b383017d 22978@exdent Request:
0ce1b118
CV
22979Frename,oldpathptr/len,newpathptr/len
22980
22981@exdent Return value:
22982On success, zero is returned. On error, -1 is returned.
22983
22984@exdent Errors:
22985@end smallexample
22986
22987@table @code
b383017d 22988@item EISDIR
0ce1b118
CV
22989newpath is an existing directory, but oldpath is not a
22990directory.
22991
b383017d 22992@item EEXIST
0ce1b118
CV
22993newpath is a non-empty directory.
22994
b383017d 22995@item EBUSY
0ce1b118
CV
22996oldpath or newpath is a directory that is in use by some
22997process.
22998
b383017d 22999@item EINVAL
0ce1b118
CV
23000An attempt was made to make a directory a subdirectory
23001of itself.
23002
b383017d 23003@item ENOTDIR
0ce1b118
CV
23004A component used as a directory in oldpath or new
23005path is not a directory. Or oldpath is a directory
23006and newpath exists but is not a directory.
23007
b383017d 23008@item EFAULT
0ce1b118
CV
23009oldpathptr or newpathptr are invalid pointer values.
23010
b383017d 23011@item EACCES
0ce1b118
CV
23012No access to the file or the path of the file.
23013
23014@item ENAMETOOLONG
b383017d 23015
0ce1b118
CV
23016oldpath or newpath was too long.
23017
b383017d 23018@item ENOENT
0ce1b118
CV
23019A directory component in oldpath or newpath does not exist.
23020
b383017d 23021@item EROFS
0ce1b118
CV
23022The file is on a read-only filesystem.
23023
b383017d 23024@item ENOSPC
0ce1b118
CV
23025The device containing the file has no room for the new
23026directory entry.
23027
b383017d 23028@item EINTR
0ce1b118
CV
23029The call was interrupted by the user.
23030@end table
23031
23032@node unlink
23033@unnumberedsubsubsec unlink
23034@cindex unlink, file-i/o system call
23035
23036@smallexample
b383017d 23037@exdent Synopsis:
0ce1b118
CV
23038int unlink(const char *pathname);
23039
b383017d 23040@exdent Request:
0ce1b118
CV
23041Funlink,pathnameptr/len
23042
23043@exdent Return value:
23044On success, zero is returned. On error, -1 is returned.
23045
23046@exdent Errors:
23047@end smallexample
23048
23049@table @code
b383017d 23050@item EACCES
0ce1b118
CV
23051No access to the file or the path of the file.
23052
b383017d 23053@item EPERM
0ce1b118
CV
23054The system does not allow unlinking of directories.
23055
b383017d 23056@item EBUSY
0ce1b118
CV
23057The file pathname cannot be unlinked because it's
23058being used by another process.
23059
b383017d 23060@item EFAULT
0ce1b118
CV
23061pathnameptr is an invalid pointer value.
23062
23063@item ENAMETOOLONG
23064pathname was too long.
23065
b383017d 23066@item ENOENT
0ce1b118
CV
23067A directory component in pathname does not exist.
23068
b383017d 23069@item ENOTDIR
0ce1b118
CV
23070A component of the path is not a directory.
23071
b383017d 23072@item EROFS
0ce1b118
CV
23073The file is on a read-only filesystem.
23074
b383017d 23075@item EINTR
0ce1b118
CV
23076The call was interrupted by the user.
23077@end table
23078
23079@node stat/fstat
23080@unnumberedsubsubsec stat/fstat
23081@cindex fstat, file-i/o system call
23082@cindex stat, file-i/o system call
23083
23084@smallexample
b383017d 23085@exdent Synopsis:
0ce1b118
CV
23086int stat(const char *pathname, struct stat *buf);
23087int fstat(int fd, struct stat *buf);
23088
b383017d 23089@exdent Request:
0ce1b118
CV
23090Fstat,pathnameptr/len,bufptr
23091Ffstat,fd,bufptr
23092
23093@exdent Return value:
23094On success, zero is returned. On error, -1 is returned.
23095
23096@exdent Errors:
23097@end smallexample
23098
23099@table @code
b383017d 23100@item EBADF
0ce1b118
CV
23101fd is not a valid open file.
23102
b383017d 23103@item ENOENT
0ce1b118
CV
23104A directory component in pathname does not exist or the
23105path is an empty string.
23106
b383017d 23107@item ENOTDIR
0ce1b118
CV
23108A component of the path is not a directory.
23109
b383017d 23110@item EFAULT
0ce1b118
CV
23111pathnameptr is an invalid pointer value.
23112
b383017d 23113@item EACCES
0ce1b118
CV
23114No access to the file or the path of the file.
23115
23116@item ENAMETOOLONG
23117pathname was too long.
23118
b383017d 23119@item EINTR
0ce1b118
CV
23120The call was interrupted by the user.
23121@end table
23122
23123@node gettimeofday
23124@unnumberedsubsubsec gettimeofday
23125@cindex gettimeofday, file-i/o system call
23126
23127@smallexample
b383017d 23128@exdent Synopsis:
0ce1b118
CV
23129int gettimeofday(struct timeval *tv, void *tz);
23130
b383017d 23131@exdent Request:
0ce1b118
CV
23132Fgettimeofday,tvptr,tzptr
23133
23134@exdent Return value:
23135On success, 0 is returned, -1 otherwise.
23136
23137@exdent Errors:
23138@end smallexample
23139
23140@table @code
b383017d 23141@item EINVAL
0ce1b118
CV
23142tz is a non-NULL pointer.
23143
b383017d 23144@item EFAULT
0ce1b118
CV
23145tvptr and/or tzptr is an invalid pointer value.
23146@end table
23147
23148@node isatty
23149@unnumberedsubsubsec isatty
23150@cindex isatty, file-i/o system call
23151
23152@smallexample
b383017d 23153@exdent Synopsis:
0ce1b118
CV
23154int isatty(int fd);
23155
b383017d 23156@exdent Request:
0ce1b118
CV
23157Fisatty,fd
23158
23159@exdent Return value:
23160Returns 1 if fd refers to the @value{GDBN} console, 0 otherwise.
23161
23162@exdent Errors:
23163@end smallexample
23164
23165@table @code
b383017d 23166@item EINTR
0ce1b118
CV
23167The call was interrupted by the user.
23168@end table
23169
23170@node system
23171@unnumberedsubsubsec system
23172@cindex system, file-i/o system call
23173
23174@smallexample
b383017d 23175@exdent Synopsis:
0ce1b118
CV
23176int system(const char *command);
23177
b383017d 23178@exdent Request:
0ce1b118
CV
23179Fsystem,commandptr/len
23180
23181@exdent Return value:
23182The value returned is -1 on error and the return status
23183of the command otherwise. Only the exit status of the
23184command is returned, which is extracted from the hosts
23185system return value by calling WEXITSTATUS(retval).
23186In case /bin/sh could not be executed, 127 is returned.
23187
23188@exdent Errors:
23189@end smallexample
23190
23191@table @code
b383017d 23192@item EINTR
0ce1b118
CV
23193The call was interrupted by the user.
23194@end table
23195
23196@node Protocol specific representation of datatypes
23197@subsection Protocol specific representation of datatypes
23198@cindex protocol specific representation of datatypes, in file-i/o protocol
23199
23200@menu
23201* Integral datatypes::
23202* Pointer values::
23203* struct stat::
23204* struct timeval::
23205@end menu
23206
23207@node Integral datatypes
23208@unnumberedsubsubsec Integral datatypes
23209@cindex integral datatypes, in file-i/o protocol
23210
23211The integral datatypes used in the system calls are
23212
23213@smallexample
23214int@r{,} unsigned int@r{,} long@r{,} unsigned long@r{,} mode_t @r{and} time_t
23215@end smallexample
23216
23217@code{Int}, @code{unsigned int}, @code{mode_t} and @code{time_t} are
23218implemented as 32 bit values in this protocol.
23219
b383017d
RM
23220@code{Long} and @code{unsigned long} are implemented as 64 bit types.
23221
0ce1b118
CV
23222@xref{Limits}, for corresponding MIN and MAX values (similar to those
23223in @file{limits.h}) to allow range checking on host and target.
23224
23225@code{time_t} datatypes are defined as seconds since the Epoch.
23226
23227All integral datatypes transferred as part of a memory read or write of a
23228structured datatype e.g.@: a @code{struct stat} have to be given in big endian
23229byte order.
23230
23231@node Pointer values
23232@unnumberedsubsubsec Pointer values
23233@cindex pointer values, in file-i/o protocol
23234
23235Pointers to target data are transmitted as they are. An exception
23236is made for pointers to buffers for which the length isn't
23237transmitted as part of the function call, namely strings. Strings
23238are transmitted as a pointer/length pair, both as hex values, e.g.@:
23239
23240@smallexample
23241@code{1aaf/12}
23242@end smallexample
23243
23244@noindent
23245which is a pointer to data of length 18 bytes at position 0x1aaf.
23246The length is defined as the full string length in bytes, including
23247the trailing null byte. Example:
23248
23249@smallexample
23250``hello, world'' at address 0x123456
23251@end smallexample
23252
23253@noindent
23254is transmitted as
23255
23256@smallexample
23257@code{123456/d}
23258@end smallexample
23259
23260@node struct stat
23261@unnumberedsubsubsec struct stat
23262@cindex struct stat, in file-i/o protocol
23263
23264The buffer of type struct stat used by the target and @value{GDBN} is defined
23265as follows:
23266
23267@smallexample
23268struct stat @{
23269 unsigned int st_dev; /* device */
23270 unsigned int st_ino; /* inode */
23271 mode_t st_mode; /* protection */
23272 unsigned int st_nlink; /* number of hard links */
23273 unsigned int st_uid; /* user ID of owner */
23274 unsigned int st_gid; /* group ID of owner */
23275 unsigned int st_rdev; /* device type (if inode device) */
23276 unsigned long st_size; /* total size, in bytes */
23277 unsigned long st_blksize; /* blocksize for filesystem I/O */
23278 unsigned long st_blocks; /* number of blocks allocated */
23279 time_t st_atime; /* time of last access */
23280 time_t st_mtime; /* time of last modification */
23281 time_t st_ctime; /* time of last change */
23282@};
23283@end smallexample
23284
23285The integral datatypes are conforming to the definitions given in the
23286approriate section (see @ref{Integral datatypes}, for details) so this
23287structure is of size 64 bytes.
23288
23289The values of several fields have a restricted meaning and/or
23290range of values.
23291
23292@smallexample
23293st_dev: 0 file
23294 1 console
23295
23296st_ino: No valid meaning for the target. Transmitted unchanged.
23297
23298st_mode: Valid mode bits are described in Appendix C. Any other
23299 bits have currently no meaning for the target.
23300
23301st_uid: No valid meaning for the target. Transmitted unchanged.
23302
23303st_gid: No valid meaning for the target. Transmitted unchanged.
23304
23305st_rdev: No valid meaning for the target. Transmitted unchanged.
23306
23307st_atime, st_mtime, st_ctime:
23308 These values have a host and file system dependent
23309 accuracy. Especially on Windows hosts the file systems
23310 don't support exact timing values.
23311@end smallexample
23312
23313The target gets a struct stat of the above representation and is
23314responsible to coerce it to the target representation before
23315continuing.
23316
23317Note that due to size differences between the host and target
23318representation of stat members, these members could eventually
23319get truncated on the target.
23320
23321@node struct timeval
23322@unnumberedsubsubsec struct timeval
23323@cindex struct timeval, in file-i/o protocol
23324
23325The buffer of type struct timeval used by the target and @value{GDBN}
23326is defined as follows:
23327
23328@smallexample
b383017d 23329struct timeval @{
0ce1b118
CV
23330 time_t tv_sec; /* second */
23331 long tv_usec; /* microsecond */
23332@};
23333@end smallexample
23334
23335The integral datatypes are conforming to the definitions given in the
23336approriate section (see @ref{Integral datatypes}, for details) so this
23337structure is of size 8 bytes.
23338
23339@node Constants
23340@subsection Constants
23341@cindex constants, in file-i/o protocol
23342
23343The following values are used for the constants inside of the
23344protocol. @value{GDBN} and target are resposible to translate these
23345values before and after the call as needed.
23346
23347@menu
23348* Open flags::
23349* mode_t values::
23350* Errno values::
23351* Lseek flags::
23352* Limits::
23353@end menu
23354
23355@node Open flags
23356@unnumberedsubsubsec Open flags
23357@cindex open flags, in file-i/o protocol
23358
23359All values are given in hexadecimal representation.
23360
23361@smallexample
23362 O_RDONLY 0x0
23363 O_WRONLY 0x1
23364 O_RDWR 0x2
23365 O_APPEND 0x8
23366 O_CREAT 0x200
23367 O_TRUNC 0x400
23368 O_EXCL 0x800
23369@end smallexample
23370
23371@node mode_t values
23372@unnumberedsubsubsec mode_t values
23373@cindex mode_t values, in file-i/o protocol
23374
23375All values are given in octal representation.
23376
23377@smallexample
23378 S_IFREG 0100000
23379 S_IFDIR 040000
23380 S_IRUSR 0400
23381 S_IWUSR 0200
23382 S_IXUSR 0100
23383 S_IRGRP 040
23384 S_IWGRP 020
23385 S_IXGRP 010
23386 S_IROTH 04
23387 S_IWOTH 02
23388 S_IXOTH 01
23389@end smallexample
23390
23391@node Errno values
23392@unnumberedsubsubsec Errno values
23393@cindex errno values, in file-i/o protocol
23394
23395All values are given in decimal representation.
23396
23397@smallexample
23398 EPERM 1
23399 ENOENT 2
23400 EINTR 4
23401 EBADF 9
23402 EACCES 13
23403 EFAULT 14
23404 EBUSY 16
23405 EEXIST 17
23406 ENODEV 19
23407 ENOTDIR 20
23408 EISDIR 21
23409 EINVAL 22
23410 ENFILE 23
23411 EMFILE 24
23412 EFBIG 27
23413 ENOSPC 28
23414 ESPIPE 29
23415 EROFS 30
23416 ENAMETOOLONG 91
23417 EUNKNOWN 9999
23418@end smallexample
23419
23420 EUNKNOWN is used as a fallback error value if a host system returns
23421 any error value not in the list of supported error numbers.
23422
23423@node Lseek flags
23424@unnumberedsubsubsec Lseek flags
23425@cindex lseek flags, in file-i/o protocol
23426
23427@smallexample
23428 SEEK_SET 0
23429 SEEK_CUR 1
23430 SEEK_END 2
23431@end smallexample
23432
23433@node Limits
23434@unnumberedsubsubsec Limits
23435@cindex limits, in file-i/o protocol
23436
23437All values are given in decimal representation.
23438
23439@smallexample
23440 INT_MIN -2147483648
23441 INT_MAX 2147483647
23442 UINT_MAX 4294967295
23443 LONG_MIN -9223372036854775808
23444 LONG_MAX 9223372036854775807
23445 ULONG_MAX 18446744073709551615
23446@end smallexample
23447
23448@node File-I/O Examples
23449@subsection File-I/O Examples
23450@cindex file-i/o examples
23451
23452Example sequence of a write call, file descriptor 3, buffer is at target
23453address 0x1234, 6 bytes should be written:
23454
23455@smallexample
23456<- @code{Fwrite,3,1234,6}
23457@emph{request memory read from target}
23458-> @code{m1234,6}
23459<- XXXXXX
23460@emph{return "6 bytes written"}
23461-> @code{F6}
23462@end smallexample
23463
23464Example sequence of a read call, file descriptor 3, buffer is at target
23465address 0x1234, 6 bytes should be read:
23466
23467@smallexample
23468<- @code{Fread,3,1234,6}
23469@emph{request memory write to target}
23470-> @code{X1234,6:XXXXXX}
23471@emph{return "6 bytes read"}
23472-> @code{F6}
23473@end smallexample
23474
23475Example sequence of a read call, call fails on the host due to invalid
23476file descriptor (EBADF):
23477
23478@smallexample
23479<- @code{Fread,3,1234,6}
23480-> @code{F-1,9}
23481@end smallexample
23482
23483Example sequence of a read call, user presses Ctrl-C before syscall on
23484host is called:
23485
23486@smallexample
23487<- @code{Fread,3,1234,6}
23488-> @code{F-1,4,C}
23489<- @code{T02}
23490@end smallexample
23491
23492Example sequence of a read call, user presses Ctrl-C after syscall on
23493host is called:
23494
23495@smallexample
23496<- @code{Fread,3,1234,6}
23497-> @code{X1234,6:XXXXXX}
23498<- @code{T02}
23499@end smallexample
23500
f418dd93
DJ
23501@include agentexpr.texi
23502
aab4e0ec 23503@include gpl.texi
eb12ee30 23504
2154891a 23505@raisesections
6826cf00 23506@include fdl.texi
2154891a 23507@lowersections
6826cf00 23508
6d2ebf8b 23509@node Index
c906108c
SS
23510@unnumbered Index
23511
23512@printindex cp
23513
23514@tex
23515% I think something like @colophon should be in texinfo. In the
23516% meantime:
23517\long\def\colophon{\hbox to0pt{}\vfill
23518\centerline{The body of this manual is set in}
23519\centerline{\fontname\tenrm,}
23520\centerline{with headings in {\bf\fontname\tenbf}}
23521\centerline{and examples in {\tt\fontname\tentt}.}
23522\centerline{{\it\fontname\tenit\/},}
23523\centerline{{\bf\fontname\tenbf}, and}
23524\centerline{{\sl\fontname\tensl\/}}
23525\centerline{are used for emphasis.}\vfill}
23526\page\colophon
23527% Blame: doc@cygnus.com, 1991.
23528@end tex
23529
c906108c 23530@bye
This page took 1.833237 seconds and 4 git commands to generate.