2010-04-07 Eric B. Weddington <eric.weddington@atmel.com>
[deliverable/binutils-gdb.git] / gdb / doc / gdb.texinfo
CommitLineData
c906108c 1\input texinfo @c -*-texinfo-*-
c02a867d 2@c Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998,
9d2897ad 3@c 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
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
89c73ade 24@syncodeindex tp cp
c906108c 25
41afff9a 26@c readline appendices use @vindex, @findex and @ftable,
48e934c6 27@c annotate.texi and gdbmi use @findex.
c906108c 28@syncodeindex vr cp
41afff9a 29@syncodeindex fn cp
c906108c
SS
30
31@c !!set GDB manual's edition---not the same as GDB version!
9fe8321b 32@c This is updated by GNU Press.
e9c75b65 33@set EDITION Ninth
c906108c 34
87885426
FN
35@c !!set GDB edit command default editor
36@set EDITOR /bin/ex
c906108c 37
6c0e9fb3 38@c THIS MANUAL REQUIRES TEXINFO 4.0 OR LATER.
c906108c 39
c906108c 40@c This is a dir.info fragment to support semi-automated addition of
6d2ebf8b 41@c manuals to an info tree.
03727ca6 42@dircategory Software development
96a2c332 43@direntry
03727ca6 44* Gdb: (gdb). The GNU debugger.
96a2c332
SS
45@end direntry
46
a67ec3f4
JM
47@copying
48Copyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
9d2897ad 491998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
a67ec3f4 50Free Software Foundation, Inc.
c906108c 51
e9c75b65
EZ
52Permission is granted to copy, distribute and/or modify this document
53under the terms of the GNU Free Documentation License, Version 1.1 or
54any later version published by the Free Software Foundation; with the
959acfd1
EZ
55Invariant Sections being ``Free Software'' and ``Free Software Needs
56Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,''
57and with the Back-Cover Texts as in (a) below.
c906108c 58
b8533aec
DJ
59(a) The FSF's Back-Cover Text is: ``You are free to copy and modify
60this GNU Manual. Buying copies from GNU Press supports the FSF in
61developing GNU and promoting software freedom.''
a67ec3f4
JM
62@end copying
63
64@ifnottex
65This file documents the @sc{gnu} debugger @value{GDBN}.
66
67This is the @value{EDITION} Edition, of @cite{Debugging with
68@value{GDBN}: the @sc{gnu} Source-Level Debugger} for @value{GDBN}
69@ifset VERSION_PACKAGE
70@value{VERSION_PACKAGE}
71@end ifset
72Version @value{GDBVN}.
73
74@insertcopying
75@end ifnottex
c906108c
SS
76
77@titlepage
78@title Debugging with @value{GDBN}
79@subtitle The @sc{gnu} Source-Level Debugger
c906108c 80@sp 1
c906108c 81@subtitle @value{EDITION} Edition, for @value{GDBN} version @value{GDBVN}
c16158bc
JM
82@ifset VERSION_PACKAGE
83@sp 1
84@subtitle @value{VERSION_PACKAGE}
85@end ifset
9e9c5ae7 86@author Richard Stallman, Roland Pesch, Stan Shebs, et al.
c906108c 87@page
c906108c
SS
88@tex
89{\parskip=0pt
c16158bc 90\hfill (Send bugs and comments on @value{GDBN} to @value{BUGURL}.)\par
c906108c
SS
91\hfill {\it Debugging with @value{GDBN}}\par
92\hfill \TeX{}info \texinfoversion\par
93}
94@end tex
53a5351d 95
c906108c 96@vskip 0pt plus 1filll
c906108c 97Published by the Free Software Foundation @*
c02a867d
EZ
9851 Franklin Street, Fifth Floor,
99Boston, MA 02110-1301, USA@*
6d2ebf8b 100ISBN 1-882114-77-9 @*
e9c75b65 101
a67ec3f4 102@insertcopying
3fb6a982
JB
103@page
104This edition of the GDB manual is dedicated to the memory of Fred
105Fish. Fred was a long-standing contributor to GDB and to Free
106software in general. We will miss him.
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
c16158bc
JM
117This is the @value{EDITION} Edition, for @value{GDBN}
118@ifset VERSION_PACKAGE
119@value{VERSION_PACKAGE}
120@end ifset
121Version @value{GDBVN}.
c906108c 122
9d2897ad 123Copyright (C) 1988-2010 Free Software Foundation, Inc.
6d2ebf8b 124
3fb6a982
JB
125This edition of the GDB manual is dedicated to the memory of Fred
126Fish. Fred was a long-standing contributor to GDB and to Free
127software in general. We will miss him.
128
6d2ebf8b
SS
129@menu
130* Summary:: Summary of @value{GDBN}
131* Sample Session:: A sample @value{GDBN} session
132
133* Invocation:: Getting in and out of @value{GDBN}
134* Commands:: @value{GDBN} commands
135* Running:: Running programs under @value{GDBN}
136* Stopping:: Stopping and continuing
bacec72f 137* Reverse Execution:: Running programs backward
a2311334 138* Process Record and Replay:: Recording inferior's execution and replaying it
6d2ebf8b
SS
139* Stack:: Examining the stack
140* Source:: Examining source files
141* Data:: Examining data
edb3359d 142* Optimized Code:: Debugging optimized code
e2e0bcd1 143* Macros:: Preprocessor Macros
b37052ae 144* Tracepoints:: Debugging remote targets non-intrusively
df0cd8c5 145* Overlays:: Debugging programs that use overlays
6d2ebf8b
SS
146
147* Languages:: Using @value{GDBN} with different languages
148
149* Symbols:: Examining the symbol table
150* Altering:: Altering execution
151* GDB Files:: @value{GDBN} files
152* Targets:: Specifying a debugging target
6b2f586d 153* Remote Debugging:: Debugging remote programs
6d2ebf8b
SS
154* Configurations:: Configuration-specific information
155* Controlling GDB:: Controlling @value{GDBN}
d57a3c85 156* Extending GDB:: Extending @value{GDBN}
21c294e6 157* Interpreters:: Command Interpreters
c8f4133a 158* TUI:: @value{GDBN} Text User Interface
6d2ebf8b 159* Emacs:: Using @value{GDBN} under @sc{gnu} Emacs
7162c0ca 160* GDB/MI:: @value{GDBN}'s Machine Interface.
c8f4133a 161* Annotations:: @value{GDBN}'s annotation interface.
4efc6507 162* JIT Interface:: Using the JIT debugging interface.
6d2ebf8b
SS
163
164* GDB Bugs:: Reporting bugs in @value{GDBN}
6d2ebf8b
SS
165
166* Command Line Editing:: Command Line Editing
167* Using History Interactively:: Using History Interactively
0869d01b 168* Formatting Documentation:: How to format and print @value{GDBN} documentation
6d2ebf8b 169* Installing GDB:: Installing GDB
eb12ee30 170* Maintenance Commands:: Maintenance Commands
e0ce93ac 171* Remote Protocol:: GDB Remote Serial Protocol
f418dd93 172* Agent Expressions:: The GDB Agent Expression Mechanism
23181151
DJ
173* Target Descriptions:: How targets can describe themselves to
174 @value{GDBN}
07e059b5
VP
175* Operating System Information:: Getting additional information from
176 the operating system
00bf0b85 177* Trace File Format:: GDB trace file format
aab4e0ec
AC
178* Copying:: GNU General Public License says
179 how you can copy and share GDB
6826cf00 180* GNU Free Documentation License:: The license for this documentation
6d2ebf8b
SS
181* Index:: Index
182@end menu
183
6c0e9fb3 184@end ifnottex
c906108c 185
449f3b6c 186@contents
449f3b6c 187
6d2ebf8b 188@node Summary
c906108c
SS
189@unnumbered Summary of @value{GDBN}
190
191The purpose of a debugger such as @value{GDBN} is to allow you to see what is
192going on ``inside'' another program while it executes---or what another
193program was doing at the moment it crashed.
194
195@value{GDBN} can do four main kinds of things (plus other things in support of
196these) to help you catch bugs in the act:
197
198@itemize @bullet
199@item
200Start your program, specifying anything that might affect its behavior.
201
202@item
203Make your program stop on specified conditions.
204
205@item
206Examine what has happened, when your program has stopped.
207
208@item
209Change things in your program, so you can experiment with correcting the
210effects of one bug and go on to learn about another.
211@end itemize
212
49efadf5 213You can use @value{GDBN} to debug programs written in C and C@t{++}.
79a6e687 214For more information, see @ref{Supported Languages,,Supported Languages}.
c906108c
SS
215For more information, see @ref{C,,C and C++}.
216
cce74817 217@cindex Modula-2
e632838e
AC
218Support for Modula-2 is partial. For information on Modula-2, see
219@ref{Modula-2,,Modula-2}.
c906108c 220
cce74817
JM
221@cindex Pascal
222Debugging Pascal programs which use sets, subranges, file variables, or
223nested functions does not currently work. @value{GDBN} does not support
224entering expressions, printing values, or similar features using Pascal
225syntax.
c906108c 226
c906108c
SS
227@cindex Fortran
228@value{GDBN} can be used to debug programs written in Fortran, although
53a5351d 229it may be necessary to refer to some variables with a trailing
cce74817 230underscore.
c906108c 231
b37303ee
AF
232@value{GDBN} can be used to debug programs written in Objective-C,
233using either the Apple/NeXT or the GNU Objective-C runtime.
234
c906108c
SS
235@menu
236* Free Software:: Freely redistributable software
237* Contributors:: Contributors to GDB
238@end menu
239
6d2ebf8b 240@node Free Software
79a6e687 241@unnumberedsec Free Software
c906108c 242
5d161b24 243@value{GDBN} is @dfn{free software}, protected by the @sc{gnu}
c906108c
SS
244General Public License
245(GPL). The GPL gives you the freedom to copy or adapt a licensed
246program---but every person getting a copy also gets with it the
247freedom to modify that copy (which means that they must get access to
248the source code), and the freedom to distribute further copies.
249Typical software companies use copyrights to limit your freedoms; the
250Free Software Foundation uses the GPL to preserve these freedoms.
251
252Fundamentally, the General Public License is a license which says that
253you have these freedoms and that you cannot take these freedoms away
254from anyone else.
255
2666264b 256@unnumberedsec Free Software Needs Free Documentation
959acfd1
EZ
257
258The biggest deficiency in the free software community today is not in
259the software---it is the lack of good free documentation that we can
260include with the free software. Many of our most important
261programs do not come with free reference manuals and free introductory
262texts. Documentation is an essential part of any software package;
263when an important free software package does not come with a free
264manual and a free tutorial, that is a major gap. We have many such
265gaps today.
266
267Consider Perl, for instance. The tutorial manuals that people
268normally use are non-free. How did this come about? Because the
269authors of those manuals published them with restrictive terms---no
270copying, no modification, source files not available---which exclude
271them from the free software world.
272
273That wasn't the first time this sort of thing happened, and it was far
274from the last. Many times we have heard a GNU user eagerly describe a
275manual that he is writing, his intended contribution to the community,
276only to learn that he had ruined everything by signing a publication
277contract to make it non-free.
278
279Free documentation, like free software, is a matter of freedom, not
280price. The problem with the non-free manual is not that publishers
281charge a price for printed copies---that in itself is fine. (The Free
282Software Foundation sells printed copies of manuals, too.) The
283problem is the restrictions on the use of the manual. Free manuals
284are available in source code form, and give you permission to copy and
285modify. Non-free manuals do not allow this.
286
287The criteria of freedom for a free manual are roughly the same as for
288free software. Redistribution (including the normal kinds of
289commercial redistribution) must be permitted, so that the manual can
290accompany every copy of the program, both on-line and on paper.
291
292Permission for modification of the technical content is crucial too.
293When people modify the software, adding or changing features, if they
294are conscientious they will change the manual too---so they can
295provide accurate and clear documentation for the modified program. A
296manual that leaves you no choice but to write a new manual to document
297a changed version of the program is not really available to our
298community.
299
300Some kinds of limits on the way modification is handled are
301acceptable. For example, requirements to preserve the original
302author's copyright notice, the distribution terms, or the list of
303authors, are ok. It is also no problem to require modified versions
304to include notice that they were modified. Even entire sections that
305may not be deleted or changed are acceptable, as long as they deal
306with nontechnical topics (like this one). These kinds of restrictions
307are acceptable because they don't obstruct the community's normal use
308of the manual.
309
310However, it must be possible to modify all the @emph{technical}
311content of the manual, and then distribute the result in all the usual
312media, through all the usual channels. Otherwise, the restrictions
313obstruct the use of the manual, it is not free, and we need another
314manual to replace it.
315
316Please spread the word about this issue. Our community continues to
317lose manuals to proprietary publishing. If we spread the word that
318free software needs free reference manuals and free tutorials, perhaps
319the next person who wants to contribute by writing documentation will
320realize, before it is too late, that only free manuals contribute to
321the free software community.
322
323If you are writing documentation, please insist on publishing it under
324the GNU Free Documentation License or another free documentation
325license. Remember that this decision requires your approval---you
326don't have to let the publisher decide. Some commercial publishers
327will use a free license if you insist, but they will not propose the
328option; it is up to you to raise the issue and say firmly that this is
329what you want. If the publisher you are dealing with refuses, please
330try other publishers. If you're not sure whether a proposed license
42584a72 331is free, write to @email{licensing@@gnu.org}.
959acfd1
EZ
332
333You can encourage commercial publishers to sell more free, copylefted
334manuals and tutorials by buying them, and particularly by buying
335copies from the publishers that paid for their writing or for major
336improvements. Meanwhile, try to avoid buying non-free documentation
337at all. Check the distribution terms of a manual before you buy it,
338and insist that whoever seeks your business must respect your freedom.
72c9928d
EZ
339Check the history of the book, and try to reward the publishers that
340have paid or pay the authors to work on it.
959acfd1
EZ
341
342The Free Software Foundation maintains a list of free documentation
343published by other publishers, at
344@url{http://www.fsf.org/doc/other-free-books.html}.
345
6d2ebf8b 346@node Contributors
96a2c332
SS
347@unnumberedsec Contributors to @value{GDBN}
348
349Richard Stallman was the original author of @value{GDBN}, and of many
350other @sc{gnu} programs. Many others have contributed to its
351development. This section attempts to credit major contributors. One
352of the virtues of free software is that everyone is free to contribute
353to it; with regret, we cannot actually acknowledge everyone here. The
354file @file{ChangeLog} in the @value{GDBN} distribution approximates a
c906108c
SS
355blow-by-blow account.
356
357Changes much prior to version 2.0 are lost in the mists of time.
358
359@quotation
360@emph{Plea:} Additions to this section are particularly welcome. If you
361or your friends (or enemies, to be evenhanded) have been unfairly
362omitted from this list, we would like to add your names!
363@end quotation
364
365So that they may not regard their many labors as thankless, we
366particularly thank those who shepherded @value{GDBN} through major
367releases:
7ba3cf9c 368Andrew Cagney (releases 6.3, 6.2, 6.1, 6.0, 5.3, 5.2, 5.1 and 5.0);
c906108c
SS
369Jim Blandy (release 4.18);
370Jason Molenda (release 4.17);
371Stan Shebs (release 4.14);
372Fred Fish (releases 4.16, 4.15, 4.13, 4.12, 4.11, 4.10, and 4.9);
373Stu Grossman and John Gilmore (releases 4.8, 4.7, 4.6, 4.5, and 4.4);
374John Gilmore (releases 4.3, 4.2, 4.1, 4.0, and 3.9);
375Jim Kingdon (releases 3.5, 3.4, and 3.3);
376and Randy Smith (releases 3.2, 3.1, and 3.0).
377
378Richard Stallman, assisted at various times by Peter TerMaat, Chris
379Hanson, and Richard Mlynarik, handled releases through 2.8.
380
b37052ae
EZ
381Michael Tiemann is the author of most of the @sc{gnu} C@t{++} support
382in @value{GDBN}, with significant additional contributions from Per
383Bothner and Daniel Berlin. James Clark wrote the @sc{gnu} C@t{++}
384demangler. Early work on C@t{++} was by Peter TerMaat (who also did
385much general update work leading to release 3.0).
c906108c 386
b37052ae 387@value{GDBN} uses the BFD subroutine library to examine multiple
c906108c
SS
388object-file formats; BFD was a joint project of David V.
389Henkel-Wallace, Rich Pixley, Steve Chamberlain, and John Gilmore.
390
391David Johnson wrote the original COFF support; Pace Willison did
392the original support for encapsulated COFF.
393
0179ffac 394Brent Benson of Harris Computer Systems contributed DWARF 2 support.
c906108c
SS
395
396Adam de Boor and Bradley Davis contributed the ISI Optimum V support.
397Per Bothner, Noboyuki Hikichi, and Alessandro Forin contributed MIPS
398support.
399Jean-Daniel Fekete contributed Sun 386i support.
400Chris Hanson improved the HP9000 support.
401Noboyuki Hikichi and Tomoyuki Hasei contributed Sony/News OS 3 support.
402David Johnson contributed Encore Umax support.
403Jyrki Kuoppala contributed Altos 3068 support.
404Jeff Law contributed HP PA and SOM support.
405Keith Packard contributed NS32K support.
406Doug Rabson contributed Acorn Risc Machine support.
407Bob Rusk contributed Harris Nighthawk CX-UX support.
408Chris Smith contributed Convex support (and Fortran debugging).
409Jonathan Stone contributed Pyramid support.
410Michael Tiemann contributed SPARC support.
411Tim Tucker contributed support for the Gould NP1 and Gould Powernode.
412Pace Willison contributed Intel 386 support.
413Jay Vosburgh contributed Symmetry support.
a37295f9 414Marko Mlinar contributed OpenRISC 1000 support.
c906108c 415
1104b9e7 416Andreas Schwab contributed M68K @sc{gnu}/Linux support.
c906108c
SS
417
418Rich Schaefer and Peter Schauer helped with support of SunOS shared
419libraries.
420
421Jay Fenlason and Roland McGrath ensured that @value{GDBN} and GAS agree
422about several machine instruction sets.
423
424Patrick Duval, Ted Goldstein, Vikram Koka and Glenn Engel helped develop
425remote debugging. Intel Corporation, Wind River Systems, AMD, and ARM
426contributed remote debugging modules for the i960, VxWorks, A29K UDI,
427and RDI targets, respectively.
428
429Brian Fox is the author of the readline libraries providing
430command-line editing and command history.
431
7a292a7a
SS
432Andrew Beers of SUNY Buffalo wrote the language-switching code, the
433Modula-2 support, and contributed the Languages chapter of this manual.
c906108c 434
5d161b24 435Fred Fish wrote most of the support for Unix System Vr4.
b37052ae 436He also enhanced the command-completion support to cover C@t{++} overloaded
c906108c 437symbols.
c906108c 438
f24c5e49
KI
439Hitachi America (now Renesas America), Ltd. sponsored the support for
440H8/300, H8/500, and Super-H processors.
c906108c
SS
441
442NEC sponsored the support for the v850, Vr4xxx, and Vr5xxx processors.
443
f24c5e49
KI
444Mitsubishi (now Renesas) sponsored the support for D10V, D30V, and M32R/D
445processors.
c906108c
SS
446
447Toshiba sponsored the support for the TX39 Mips processor.
448
449Matsushita sponsored the support for the MN10200 and MN10300 processors.
450
96a2c332 451Fujitsu sponsored the support for SPARClite and FR30 processors.
c906108c
SS
452
453Kung Hsu, Jeff Law, and Rick Sladkey added support for hardware
454watchpoints.
455
456Michael Snyder added support for tracepoints.
457
458Stu Grossman wrote gdbserver.
459
460Jim Kingdon, Peter Schauer, Ian Taylor, and Stu Grossman made
96a2c332 461nearly innumerable bug fixes and cleanups throughout @value{GDBN}.
c906108c
SS
462
463The following people at the Hewlett-Packard Company contributed
464support for the PA-RISC 2.0 architecture, HP-UX 10.20, 10.30, and 11.0
b37052ae 465(narrow mode), HP's implementation of kernel threads, HP's aC@t{++}
d0d5df6f
AC
466compiler, and the Text User Interface (nee Terminal User Interface):
467Ben Krepp, Richard Title, John Bishop, Susan Macchia, Kathy Mann,
468Satish Pai, India Paul, Steve Rehrauer, and Elena Zannoni. Kim Haase
469provided HP-specific information in this manual.
c906108c 470
b37052ae
EZ
471DJ Delorie ported @value{GDBN} to MS-DOS, for the DJGPP project.
472Robert Hoehne made significant contributions to the DJGPP port.
473
96a2c332
SS
474Cygnus Solutions has sponsored @value{GDBN} maintenance and much of its
475development since 1991. Cygnus engineers who have worked on @value{GDBN}
2df3850c
JM
476fulltime include Mark Alexander, Jim Blandy, Per Bothner, Kevin
477Buettner, Edith Epstein, Chris Faylor, Fred Fish, Martin Hunt, Jim
478Ingham, John Gilmore, Stu Grossman, Kung Hsu, Jim Kingdon, John Metzler,
479Fernando Nasser, Geoffrey Noer, Dawn Perchik, Rich Pixley, Zdenek
480Radouch, Keith Seitz, Stan Shebs, David Taylor, and Elena Zannoni. In
481addition, Dave Brolley, Ian Carmichael, Steve Chamberlain, Nick Clifton,
482JT Conklin, Stan Cox, DJ Delorie, Ulrich Drepper, Frank Eigler, Doug
483Evans, Sean Fagan, David Henkel-Wallace, Richard Henderson, Jeff
484Holcomb, Jeff Law, Jim Lemke, Tom Lord, Bob Manson, Michael Meissner,
485Jason Merrill, Catherine Moore, Drew Moseley, Ken Raeburn, Gavin
486Romig-Koch, Rob Savoye, Jamie Smith, Mike Stump, Ian Taylor, Angela
487Thomas, Michael Tiemann, Tom Tromey, Ron Unrau, Jim Wilson, and David
488Zuhn have made contributions both large and small.
c906108c 489
ffed4509
AC
490Andrew Cagney, Fernando Nasser, and Elena Zannoni, while working for
491Cygnus Solutions, implemented the original @sc{gdb/mi} interface.
492
e2e0bcd1
JB
493Jim Blandy added support for preprocessor macros, while working for Red
494Hat.
c906108c 495
a9967aef
AC
496Andrew Cagney designed @value{GDBN}'s architecture vector. Many
497people including Andrew Cagney, Stephane Carrez, Randolph Chung, Nick
498Duffek, Richard Henderson, Mark Kettenis, Grace Sainsbury, Kei
499Sakamoto, Yoshinori Sato, Michael Snyder, Andreas Schwab, Jason
500Thorpe, Corinna Vinschen, Ulrich Weigand, and Elena Zannoni, helped
501with the migration of old architectures to this new framework.
502
c5e30d01
AC
503Andrew Cagney completely re-designed and re-implemented @value{GDBN}'s
504unwinder framework, this consisting of a fresh new design featuring
505frame IDs, independent frame sniffers, and the sentinel frame. Mark
506Kettenis implemented the @sc{dwarf 2} unwinder, Jeff Johnston the
507libunwind unwinder, and Andrew Cagney the dummy, sentinel, tramp, and
db2e3e2e 508trad unwinders. The architecture-specific changes, each involving a
c5e30d01
AC
509complete rewrite of the architecture's frame code, were carried out by
510Jim Blandy, Joel Brobecker, Kevin Buettner, Andrew Cagney, Stephane
511Carrez, Randolph Chung, Orjan Friberg, Richard Henderson, Daniel
512Jacobowitz, Jeff Johnston, Mark Kettenis, Theodore A. Roth, Kei
513Sakamoto, Yoshinori Sato, Michael Snyder, Corinna Vinschen, and Ulrich
514Weigand.
515
ca3bf3bd
DJ
516Christian Zankel, Ross Morley, Bob Wilson, and Maxim Grigoriev from
517Tensilica, Inc.@: contributed support for Xtensa processors. Others
518who have worked on the Xtensa port of @value{GDBN} in the past include
519Steve Tjiang, John Newlin, and Scott Foehner.
520
08be9d71
ME
521Michael Eager and staff of Xilinx, Inc., contributed support for the
522Xilinx MicroBlaze architecture.
523
6d2ebf8b 524@node Sample Session
c906108c
SS
525@chapter A Sample @value{GDBN} Session
526
527You can use this manual at your leisure to read all about @value{GDBN}.
528However, a handful of commands are enough to get started using the
529debugger. This chapter illustrates those commands.
530
531@iftex
532In this sample session, we emphasize user input like this: @b{input},
533to make it easier to pick out from the surrounding output.
534@end iftex
535
536@c FIXME: this example may not be appropriate for some configs, where
537@c FIXME...primary interest is in remote use.
538
539One of the preliminary versions of @sc{gnu} @code{m4} (a generic macro
540processor) exhibits the following bug: sometimes, when we change its
541quote strings from the default, the commands used to capture one macro
542definition within another stop working. In the following short @code{m4}
543session, we define a macro @code{foo} which expands to @code{0000}; we
544then use the @code{m4} built-in @code{defn} to define @code{bar} as the
545same thing. However, when we change the open quote string to
546@code{<QUOTE>} and the close quote string to @code{<UNQUOTE>}, the same
547procedure fails to define a new synonym @code{baz}:
548
549@smallexample
550$ @b{cd gnu/m4}
551$ @b{./m4}
552@b{define(foo,0000)}
553
554@b{foo}
5550000
556@b{define(bar,defn(`foo'))}
557
558@b{bar}
5590000
560@b{changequote(<QUOTE>,<UNQUOTE>)}
561
562@b{define(baz,defn(<QUOTE>foo<UNQUOTE>))}
563@b{baz}
c8aa23ab 564@b{Ctrl-d}
c906108c
SS
565m4: End of input: 0: fatal error: EOF in string
566@end smallexample
567
568@noindent
569Let us use @value{GDBN} to try to see what is going on.
570
c906108c
SS
571@smallexample
572$ @b{@value{GDBP} m4}
573@c FIXME: this falsifies the exact text played out, to permit smallbook
574@c FIXME... format to come out better.
575@value{GDBN} is free software and you are welcome to distribute copies
5d161b24 576 of it under certain conditions; type "show copying" to see
c906108c 577 the conditions.
5d161b24 578There is absolutely no warranty for @value{GDBN}; type "show warranty"
c906108c
SS
579 for details.
580
581@value{GDBN} @value{GDBVN}, Copyright 1999 Free Software Foundation, Inc...
582(@value{GDBP})
583@end smallexample
c906108c
SS
584
585@noindent
586@value{GDBN} reads only enough symbol data to know where to find the
587rest when needed; as a result, the first prompt comes up very quickly.
588We now tell @value{GDBN} to use a narrower display width than usual, so
589that examples fit in this manual.
590
591@smallexample
592(@value{GDBP}) @b{set width 70}
593@end smallexample
594
595@noindent
596We need to see how the @code{m4} built-in @code{changequote} works.
597Having looked at the source, we know the relevant subroutine is
598@code{m4_changequote}, so we set a breakpoint there with the @value{GDBN}
599@code{break} command.
600
601@smallexample
602(@value{GDBP}) @b{break m4_changequote}
603Breakpoint 1 at 0x62f4: file builtin.c, line 879.
604@end smallexample
605
606@noindent
607Using the @code{run} command, we start @code{m4} running under @value{GDBN}
608control; as long as control does not reach the @code{m4_changequote}
609subroutine, the program runs as usual:
610
611@smallexample
612(@value{GDBP}) @b{run}
613Starting program: /work/Editorial/gdb/gnu/m4/m4
614@b{define(foo,0000)}
615
616@b{foo}
6170000
618@end smallexample
619
620@noindent
621To trigger the breakpoint, we call @code{changequote}. @value{GDBN}
622suspends execution of @code{m4}, displaying information about the
623context where it stops.
624
625@smallexample
626@b{changequote(<QUOTE>,<UNQUOTE>)}
627
5d161b24 628Breakpoint 1, m4_changequote (argc=3, argv=0x33c70)
c906108c
SS
629 at builtin.c:879
630879 if (bad_argc(TOKEN_DATA_TEXT(argv[0]),argc,1,3))
631@end smallexample
632
633@noindent
634Now we use the command @code{n} (@code{next}) to advance execution to
635the next line of the current function.
636
637@smallexample
638(@value{GDBP}) @b{n}
639882 set_quotes((argc >= 2) ? TOKEN_DATA_TEXT(argv[1])\
640 : nil,
641@end smallexample
642
643@noindent
644@code{set_quotes} looks like a promising subroutine. We can go into it
645by using the command @code{s} (@code{step}) instead of @code{next}.
646@code{step} goes to the next line to be executed in @emph{any}
647subroutine, so it steps into @code{set_quotes}.
648
649@smallexample
650(@value{GDBP}) @b{s}
651set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>")
652 at input.c:530
653530 if (lquote != def_lquote)
654@end smallexample
655
656@noindent
657The display that shows the subroutine where @code{m4} is now
658suspended (and its arguments) is called a stack frame display. It
659shows a summary of the stack. We can use the @code{backtrace}
660command (which can also be spelled @code{bt}), to see where we are
661in the stack as a whole: the @code{backtrace} command displays a
662stack frame for each active subroutine.
663
664@smallexample
665(@value{GDBP}) @b{bt}
666#0 set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>")
667 at input.c:530
5d161b24 668#1 0x6344 in m4_changequote (argc=3, argv=0x33c70)
c906108c
SS
669 at builtin.c:882
670#2 0x8174 in expand_macro (sym=0x33320) at macro.c:242
671#3 0x7a88 in expand_token (obs=0x0, t=209696, td=0xf7fffa30)
672 at macro.c:71
673#4 0x79dc in expand_input () at macro.c:40
674#5 0x2930 in main (argc=0, argv=0xf7fffb20) at m4.c:195
675@end smallexample
676
677@noindent
678We step through a few more lines to see what happens. The first two
679times, we can use @samp{s}; the next two times we use @code{n} to avoid
680falling into the @code{xstrdup} subroutine.
681
682@smallexample
683(@value{GDBP}) @b{s}
6840x3b5c 532 if (rquote != def_rquote)
685(@value{GDBP}) @b{s}
6860x3b80 535 lquote = (lq == nil || *lq == '\0') ? \
687def_lquote : xstrdup(lq);
688(@value{GDBP}) @b{n}
689536 rquote = (rq == nil || *rq == '\0') ? def_rquote\
690 : xstrdup(rq);
691(@value{GDBP}) @b{n}
692538 len_lquote = strlen(rquote);
693@end smallexample
694
695@noindent
696The last line displayed looks a little odd; we can examine the variables
697@code{lquote} and @code{rquote} to see if they are in fact the new left
698and right quotes we specified. We use the command @code{p}
699(@code{print}) to see their values.
700
701@smallexample
702(@value{GDBP}) @b{p lquote}
703$1 = 0x35d40 "<QUOTE>"
704(@value{GDBP}) @b{p rquote}
705$2 = 0x35d50 "<UNQUOTE>"
706@end smallexample
707
708@noindent
709@code{lquote} and @code{rquote} are indeed the new left and right quotes.
710To look at some context, we can display ten lines of source
711surrounding the current line with the @code{l} (@code{list}) command.
712
713@smallexample
714(@value{GDBP}) @b{l}
715533 xfree(rquote);
716534
717535 lquote = (lq == nil || *lq == '\0') ? def_lquote\
718 : xstrdup (lq);
719536 rquote = (rq == nil || *rq == '\0') ? def_rquote\
720 : xstrdup (rq);
721537
722538 len_lquote = strlen(rquote);
723539 len_rquote = strlen(lquote);
724540 @}
725541
726542 void
727@end smallexample
728
729@noindent
730Let us step past the two lines that set @code{len_lquote} and
731@code{len_rquote}, and then examine the values of those variables.
732
733@smallexample
734(@value{GDBP}) @b{n}
735539 len_rquote = strlen(lquote);
736(@value{GDBP}) @b{n}
737540 @}
738(@value{GDBP}) @b{p len_lquote}
739$3 = 9
740(@value{GDBP}) @b{p len_rquote}
741$4 = 7
742@end smallexample
743
744@noindent
745That certainly looks wrong, assuming @code{len_lquote} and
746@code{len_rquote} are meant to be the lengths of @code{lquote} and
747@code{rquote} respectively. We can set them to better values using
748the @code{p} command, since it can print the value of
749any expression---and that expression can include subroutine calls and
750assignments.
751
752@smallexample
753(@value{GDBP}) @b{p len_lquote=strlen(lquote)}
754$5 = 7
755(@value{GDBP}) @b{p len_rquote=strlen(rquote)}
756$6 = 9
757@end smallexample
758
759@noindent
760Is that enough to fix the problem of using the new quotes with the
761@code{m4} built-in @code{defn}? We can allow @code{m4} to continue
762executing with the @code{c} (@code{continue}) command, and then try the
763example that caused trouble initially:
764
765@smallexample
766(@value{GDBP}) @b{c}
767Continuing.
768
769@b{define(baz,defn(<QUOTE>foo<UNQUOTE>))}
770
771baz
7720000
773@end smallexample
774
775@noindent
776Success! The new quotes now work just as well as the default ones. The
777problem seems to have been just the two typos defining the wrong
778lengths. We allow @code{m4} exit by giving it an EOF as input:
779
780@smallexample
c8aa23ab 781@b{Ctrl-d}
c906108c
SS
782Program exited normally.
783@end smallexample
784
785@noindent
786The message @samp{Program exited normally.} is from @value{GDBN}; it
787indicates @code{m4} has finished executing. We can end our @value{GDBN}
788session with the @value{GDBN} @code{quit} command.
789
790@smallexample
791(@value{GDBP}) @b{quit}
792@end smallexample
c906108c 793
6d2ebf8b 794@node Invocation
c906108c
SS
795@chapter Getting In and Out of @value{GDBN}
796
797This chapter discusses how to start @value{GDBN}, and how to get out of it.
5d161b24 798The essentials are:
c906108c 799@itemize @bullet
5d161b24 800@item
53a5351d 801type @samp{@value{GDBP}} to start @value{GDBN}.
5d161b24 802@item
c8aa23ab 803type @kbd{quit} or @kbd{Ctrl-d} to exit.
c906108c
SS
804@end itemize
805
806@menu
807* Invoking GDB:: How to start @value{GDBN}
808* Quitting GDB:: How to quit @value{GDBN}
809* Shell Commands:: How to use shell commands inside @value{GDBN}
79a6e687 810* Logging Output:: How to log @value{GDBN}'s output to a file
c906108c
SS
811@end menu
812
6d2ebf8b 813@node Invoking GDB
c906108c
SS
814@section Invoking @value{GDBN}
815
c906108c
SS
816Invoke @value{GDBN} by running the program @code{@value{GDBP}}. Once started,
817@value{GDBN} reads commands from the terminal until you tell it to exit.
818
819You can also run @code{@value{GDBP}} with a variety of arguments and options,
820to specify more of your debugging environment at the outset.
821
c906108c
SS
822The command-line options described here are designed
823to cover a variety of situations; in some environments, some of these
5d161b24 824options may effectively be unavailable.
c906108c
SS
825
826The most usual way to start @value{GDBN} is with one argument,
827specifying an executable program:
828
474c8240 829@smallexample
c906108c 830@value{GDBP} @var{program}
474c8240 831@end smallexample
c906108c 832
c906108c
SS
833@noindent
834You can also start with both an executable program and a core file
835specified:
836
474c8240 837@smallexample
c906108c 838@value{GDBP} @var{program} @var{core}
474c8240 839@end smallexample
c906108c
SS
840
841You can, instead, specify a process ID as a second argument, if you want
842to debug a running process:
843
474c8240 844@smallexample
c906108c 845@value{GDBP} @var{program} 1234
474c8240 846@end smallexample
c906108c
SS
847
848@noindent
849would attach @value{GDBN} to process @code{1234} (unless you also have a file
850named @file{1234}; @value{GDBN} does check for a core file first).
851
c906108c 852Taking advantage of the second command-line argument requires a fairly
2df3850c
JM
853complete operating system; when you use @value{GDBN} as a remote
854debugger attached to a bare board, there may not be any notion of
855``process'', and there is often no way to get a core dump. @value{GDBN}
856will warn you if it is unable to attach or to read core dumps.
c906108c 857
aa26fa3a
TT
858You can optionally have @code{@value{GDBP}} pass any arguments after the
859executable file to the inferior using @code{--args}. This option stops
860option processing.
474c8240 861@smallexample
3f94c067 862@value{GDBP} --args gcc -O2 -c foo.c
474c8240 863@end smallexample
aa26fa3a
TT
864This will cause @code{@value{GDBP}} to debug @code{gcc}, and to set
865@code{gcc}'s command-line arguments (@pxref{Arguments}) to @samp{-O2 -c foo.c}.
866
96a2c332 867You can run @code{@value{GDBP}} without printing the front material, which describes
c906108c
SS
868@value{GDBN}'s non-warranty, by specifying @code{-silent}:
869
870@smallexample
871@value{GDBP} -silent
872@end smallexample
873
874@noindent
875You can further control how @value{GDBN} starts up by using command-line
876options. @value{GDBN} itself can remind you of the options available.
877
878@noindent
879Type
880
474c8240 881@smallexample
c906108c 882@value{GDBP} -help
474c8240 883@end smallexample
c906108c
SS
884
885@noindent
886to display all available options and briefly describe their use
887(@samp{@value{GDBP} -h} is a shorter equivalent).
888
889All options and command line arguments you give are processed
890in sequential order. The order makes a difference when the
891@samp{-x} option is used.
892
893
894@menu
c906108c
SS
895* File Options:: Choosing files
896* Mode Options:: Choosing modes
6fc08d32 897* Startup:: What @value{GDBN} does during startup
c906108c
SS
898@end menu
899
6d2ebf8b 900@node File Options
79a6e687 901@subsection Choosing Files
c906108c 902
2df3850c 903When @value{GDBN} starts, it reads any arguments other than options as
c906108c
SS
904specifying an executable file and core file (or process ID). This is
905the same as if the arguments were specified by the @samp{-se} and
d52fb0e9 906@samp{-c} (or @samp{-p}) options respectively. (@value{GDBN} reads the
19837790
MS
907first argument that does not have an associated option flag as
908equivalent to the @samp{-se} option followed by that argument; and the
909second argument that does not have an associated option flag, if any, as
910equivalent to the @samp{-c}/@samp{-p} option followed by that argument.)
911If the second argument begins with a decimal digit, @value{GDBN} will
912first attempt to attach to it as a process, and if that fails, attempt
913to open it as a corefile. If you have a corefile whose name begins with
b383017d 914a digit, you can prevent @value{GDBN} from treating it as a pid by
c1468174 915prefixing it with @file{./}, e.g.@: @file{./12345}.
7a292a7a
SS
916
917If @value{GDBN} has not been configured to included core file support,
918such as for most embedded targets, then it will complain about a second
919argument and ignore it.
c906108c
SS
920
921Many options have both long and short forms; both are shown in the
922following list. @value{GDBN} also recognizes the long forms if you truncate
923them, so long as enough of the option is present to be unambiguous.
924(If you prefer, you can flag option arguments with @samp{--} rather
925than @samp{-}, though we illustrate the more usual convention.)
926
d700128c
EZ
927@c NOTE: the @cindex entries here use double dashes ON PURPOSE. This
928@c way, both those who look for -foo and --foo in the index, will find
929@c it.
930
c906108c
SS
931@table @code
932@item -symbols @var{file}
933@itemx -s @var{file}
d700128c
EZ
934@cindex @code{--symbols}
935@cindex @code{-s}
c906108c
SS
936Read symbol table from file @var{file}.
937
938@item -exec @var{file}
939@itemx -e @var{file}
d700128c
EZ
940@cindex @code{--exec}
941@cindex @code{-e}
7a292a7a
SS
942Use file @var{file} as the executable file to execute when appropriate,
943and for examining pure data in conjunction with a core dump.
c906108c
SS
944
945@item -se @var{file}
d700128c 946@cindex @code{--se}
c906108c
SS
947Read symbol table from file @var{file} and use it as the executable
948file.
949
c906108c
SS
950@item -core @var{file}
951@itemx -c @var{file}
d700128c
EZ
952@cindex @code{--core}
953@cindex @code{-c}
b383017d 954Use file @var{file} as a core dump to examine.
c906108c 955
19837790
MS
956@item -pid @var{number}
957@itemx -p @var{number}
958@cindex @code{--pid}
959@cindex @code{-p}
960Connect to process ID @var{number}, as with the @code{attach} command.
c906108c
SS
961
962@item -command @var{file}
963@itemx -x @var{file}
d700128c
EZ
964@cindex @code{--command}
965@cindex @code{-x}
95433b34
JB
966Execute commands from file @var{file}. The contents of this file is
967evaluated exactly as the @code{source} command would.
8150ff9c 968@xref{Command Files,, Command files}.
c906108c 969
8a5a3c82
AS
970@item -eval-command @var{command}
971@itemx -ex @var{command}
972@cindex @code{--eval-command}
973@cindex @code{-ex}
974Execute a single @value{GDBN} command.
975
976This option may be used multiple times to call multiple commands. It may
977also be interleaved with @samp{-command} as required.
978
979@smallexample
980@value{GDBP} -ex 'target sim' -ex 'load' \
981 -x setbreakpoints -ex 'run' a.out
982@end smallexample
983
c906108c
SS
984@item -directory @var{directory}
985@itemx -d @var{directory}
d700128c
EZ
986@cindex @code{--directory}
987@cindex @code{-d}
4b505b12 988Add @var{directory} to the path to search for source and script files.
c906108c 989
c906108c
SS
990@item -r
991@itemx -readnow
d700128c
EZ
992@cindex @code{--readnow}
993@cindex @code{-r}
c906108c
SS
994Read each symbol file's entire symbol table immediately, rather than
995the default, which is to read it incrementally as it is needed.
996This makes startup slower, but makes future operations faster.
53a5351d 997
c906108c
SS
998@end table
999
6d2ebf8b 1000@node Mode Options
79a6e687 1001@subsection Choosing Modes
c906108c
SS
1002
1003You can run @value{GDBN} in various alternative modes---for example, in
1004batch mode or quiet mode.
1005
1006@table @code
1007@item -nx
1008@itemx -n
d700128c
EZ
1009@cindex @code{--nx}
1010@cindex @code{-n}
96565e91 1011Do not execute commands found in any initialization files. Normally,
2df3850c
JM
1012@value{GDBN} executes the commands in these files after all the command
1013options and arguments have been processed. @xref{Command Files,,Command
79a6e687 1014Files}.
c906108c
SS
1015
1016@item -quiet
d700128c 1017@itemx -silent
c906108c 1018@itemx -q
d700128c
EZ
1019@cindex @code{--quiet}
1020@cindex @code{--silent}
1021@cindex @code{-q}
c906108c
SS
1022``Quiet''. Do not print the introductory and copyright messages. These
1023messages are also suppressed in batch mode.
1024
1025@item -batch
d700128c 1026@cindex @code{--batch}
c906108c
SS
1027Run in batch mode. Exit with status @code{0} after processing all the
1028command files specified with @samp{-x} (and all commands from
1029initialization files, if not inhibited with @samp{-n}). Exit with
1030nonzero status if an error occurs in executing the @value{GDBN} commands
7c953934
TT
1031in the command files. Batch mode also disables pagination;
1032@pxref{Screen Size} and acts as if @kbd{set confirm off} were in
1033effect (@pxref{Messages/Warnings}).
c906108c 1034
2df3850c
JM
1035Batch mode may be useful for running @value{GDBN} as a filter, for
1036example to download and run a program on another computer; in order to
1037make this more useful, the message
c906108c 1038
474c8240 1039@smallexample
c906108c 1040Program exited normally.
474c8240 1041@end smallexample
c906108c
SS
1042
1043@noindent
2df3850c
JM
1044(which is ordinarily issued whenever a program running under
1045@value{GDBN} control terminates) is not issued when running in batch
1046mode.
1047
1a088d06
AS
1048@item -batch-silent
1049@cindex @code{--batch-silent}
1050Run in batch mode exactly like @samp{-batch}, but totally silently. All
1051@value{GDBN} output to @code{stdout} is prevented (@code{stderr} is
1052unaffected). This is much quieter than @samp{-silent} and would be useless
1053for an interactive session.
1054
1055This is particularly useful when using targets that give @samp{Loading section}
1056messages, for example.
1057
1058Note that targets that give their output via @value{GDBN}, as opposed to
1059writing directly to @code{stdout}, will also be made silent.
1060
4b0ad762
AS
1061@item -return-child-result
1062@cindex @code{--return-child-result}
1063The return code from @value{GDBN} will be the return code from the child
1064process (the process being debugged), with the following exceptions:
1065
1066@itemize @bullet
1067@item
1068@value{GDBN} exits abnormally. E.g., due to an incorrect argument or an
1069internal error. In this case the exit code is the same as it would have been
1070without @samp{-return-child-result}.
1071@item
1072The user quits with an explicit value. E.g., @samp{quit 1}.
1073@item
1074The child process never runs, or is not allowed to terminate, in which case
1075the exit code will be -1.
1076@end itemize
1077
1078This option is useful in conjunction with @samp{-batch} or @samp{-batch-silent},
1079when @value{GDBN} is being used as a remote program loader or simulator
1080interface.
1081
2df3850c
JM
1082@item -nowindows
1083@itemx -nw
d700128c
EZ
1084@cindex @code{--nowindows}
1085@cindex @code{-nw}
2df3850c 1086``No windows''. If @value{GDBN} comes with a graphical user interface
96a2c332 1087(GUI) built in, then this option tells @value{GDBN} to only use the command-line
2df3850c
JM
1088interface. If no GUI is available, this option has no effect.
1089
1090@item -windows
1091@itemx -w
d700128c
EZ
1092@cindex @code{--windows}
1093@cindex @code{-w}
2df3850c
JM
1094If @value{GDBN} includes a GUI, then this option requires it to be
1095used if possible.
c906108c
SS
1096
1097@item -cd @var{directory}
d700128c 1098@cindex @code{--cd}
c906108c
SS
1099Run @value{GDBN} using @var{directory} as its working directory,
1100instead of the current directory.
1101
c906108c
SS
1102@item -fullname
1103@itemx -f
d700128c
EZ
1104@cindex @code{--fullname}
1105@cindex @code{-f}
7a292a7a
SS
1106@sc{gnu} Emacs sets this option when it runs @value{GDBN} as a
1107subprocess. It tells @value{GDBN} to output the full file name and line
1108number in a standard, recognizable fashion each time a stack frame is
1109displayed (which includes each time your program stops). This
1110recognizable format looks like two @samp{\032} characters, followed by
1111the file name, line number and character position separated by colons,
1112and a newline. The Emacs-to-@value{GDBN} interface program uses the two
1113@samp{\032} characters as a signal to display the source code for the
1114frame.
c906108c 1115
d700128c
EZ
1116@item -epoch
1117@cindex @code{--epoch}
1118The Epoch Emacs-@value{GDBN} interface sets this option when it runs
1119@value{GDBN} as a subprocess. It tells @value{GDBN} to modify its print
1120routines so as to allow Epoch to display values of expressions in a
1121separate window.
1122
1123@item -annotate @var{level}
1124@cindex @code{--annotate}
1125This option sets the @dfn{annotation level} inside @value{GDBN}. Its
1126effect is identical to using @samp{set annotate @var{level}}
086432e2
AC
1127(@pxref{Annotations}). The annotation @var{level} controls how much
1128information @value{GDBN} prints together with its prompt, values of
1129expressions, source lines, and other types of output. Level 0 is the
1130normal, level 1 is for use when @value{GDBN} is run as a subprocess of
1131@sc{gnu} Emacs, level 3 is the maximum annotation suitable for programs
1132that control @value{GDBN}, and level 2 has been deprecated.
1133
265eeb58 1134The annotation mechanism has largely been superseded by @sc{gdb/mi}
086432e2 1135(@pxref{GDB/MI}).
d700128c 1136
aa26fa3a
TT
1137@item --args
1138@cindex @code{--args}
1139Change interpretation of command line so that arguments following the
1140executable file are passed as command line arguments to the inferior.
1141This option stops option processing.
1142
2df3850c
JM
1143@item -baud @var{bps}
1144@itemx -b @var{bps}
d700128c
EZ
1145@cindex @code{--baud}
1146@cindex @code{-b}
c906108c
SS
1147Set the line speed (baud rate or bits per second) of any serial
1148interface used by @value{GDBN} for remote debugging.
c906108c 1149
f47b1503
AS
1150@item -l @var{timeout}
1151@cindex @code{-l}
1152Set the timeout (in seconds) of any communication used by @value{GDBN}
1153for remote debugging.
1154
c906108c 1155@item -tty @var{device}
d700128c
EZ
1156@itemx -t @var{device}
1157@cindex @code{--tty}
1158@cindex @code{-t}
c906108c
SS
1159Run using @var{device} for your program's standard input and output.
1160@c FIXME: kingdon thinks there is more to -tty. Investigate.
c906108c 1161
53a5351d 1162@c resolve the situation of these eventually
c4555f82
SC
1163@item -tui
1164@cindex @code{--tui}
d0d5df6f
AC
1165Activate the @dfn{Text User Interface} when starting. The Text User
1166Interface manages several text windows on the terminal, showing
1167source, assembly, registers and @value{GDBN} command outputs
1168(@pxref{TUI, ,@value{GDBN} Text User Interface}). Alternatively, the
1169Text User Interface can be enabled by invoking the program
46ba6afa 1170@samp{@value{GDBTUI}}. Do not use this option if you run @value{GDBN} from
d0d5df6f 1171Emacs (@pxref{Emacs, ,Using @value{GDBN} under @sc{gnu} Emacs}).
53a5351d
JM
1172
1173@c @item -xdb
d700128c 1174@c @cindex @code{--xdb}
53a5351d
JM
1175@c Run in XDB compatibility mode, allowing the use of certain XDB commands.
1176@c For information, see the file @file{xdb_trans.html}, which is usually
1177@c installed in the directory @code{/opt/langtools/wdb/doc} on HP-UX
1178@c systems.
1179
d700128c
EZ
1180@item -interpreter @var{interp}
1181@cindex @code{--interpreter}
1182Use the interpreter @var{interp} for interface with the controlling
1183program or device. This option is meant to be set by programs which
94bbb2c0 1184communicate with @value{GDBN} using it as a back end.
21c294e6 1185@xref{Interpreters, , Command Interpreters}.
94bbb2c0 1186
da0f9dcd 1187@samp{--interpreter=mi} (or @samp{--interpreter=mi2}) causes
2fcf52f0 1188@value{GDBN} to use the @dfn{@sc{gdb/mi} interface} (@pxref{GDB/MI, ,
6b5e8c01 1189The @sc{gdb/mi} Interface}) included since @value{GDBN} version 6.0. The
6c74ac8b
AC
1190previous @sc{gdb/mi} interface, included in @value{GDBN} version 5.3 and
1191selected with @samp{--interpreter=mi1}, is deprecated. Earlier
1192@sc{gdb/mi} interfaces are no longer supported.
d700128c
EZ
1193
1194@item -write
1195@cindex @code{--write}
1196Open the executable and core files for both reading and writing. This
1197is equivalent to the @samp{set write on} command inside @value{GDBN}
1198(@pxref{Patching}).
1199
1200@item -statistics
1201@cindex @code{--statistics}
1202This option causes @value{GDBN} to print statistics about time and
1203memory usage after it completes each command and returns to the prompt.
1204
1205@item -version
1206@cindex @code{--version}
1207This option causes @value{GDBN} to print its version number and
1208no-warranty blurb, and exit.
1209
c906108c
SS
1210@end table
1211
6fc08d32 1212@node Startup
79a6e687 1213@subsection What @value{GDBN} Does During Startup
6fc08d32
EZ
1214@cindex @value{GDBN} startup
1215
1216Here's the description of what @value{GDBN} does during session startup:
1217
1218@enumerate
1219@item
1220Sets up the command interpreter as specified by the command line
1221(@pxref{Mode Options, interpreter}).
1222
1223@item
1224@cindex init file
098b41a6
JG
1225Reads the system-wide @dfn{init file} (if @option{--with-system-gdbinit} was
1226used when building @value{GDBN}; @pxref{System-wide configuration,
1227 ,System-wide configuration and settings}) and executes all the commands in
1228that file.
1229
1230@item
1231Reads the init file (if any) in your home directory@footnote{On
6fc08d32
EZ
1232DOS/Windows systems, the home directory is the one pointed to by the
1233@code{HOME} environment variable.} and executes all the commands in
1234that file.
1235
1236@item
1237Processes command line options and operands.
1238
1239@item
1240Reads and executes the commands from init file (if any) in the current
119b882a
EZ
1241working directory. This is only done if the current directory is
1242different from your home directory. Thus, you can have more than one
1243init file, one generic in your home directory, and another, specific
1244to the program you are debugging, in the directory where you invoke
6fc08d32
EZ
1245@value{GDBN}.
1246
1247@item
1248Reads command files specified by the @samp{-x} option. @xref{Command
1249Files}, for more details about @value{GDBN} command files.
1250
1251@item
1252Reads the command history recorded in the @dfn{history file}.
d620b259 1253@xref{Command History}, for more details about the command history and the
6fc08d32
EZ
1254files where @value{GDBN} records it.
1255@end enumerate
1256
1257Init files use the same syntax as @dfn{command files} (@pxref{Command
1258Files}) and are processed by @value{GDBN} in the same way. The init
1259file in your home directory can set options (such as @samp{set
1260complaints}) that affect subsequent processing of command line options
1261and operands. Init files are not executed if you use the @samp{-nx}
79a6e687 1262option (@pxref{Mode Options, ,Choosing Modes}).
6fc08d32 1263
098b41a6
JG
1264To display the list of init files loaded by gdb at startup, you
1265can use @kbd{gdb --help}.
1266
6fc08d32
EZ
1267@cindex init file name
1268@cindex @file{.gdbinit}
119b882a 1269@cindex @file{gdb.ini}
8807d78b 1270The @value{GDBN} init files are normally called @file{.gdbinit}.
119b882a
EZ
1271The DJGPP port of @value{GDBN} uses the name @file{gdb.ini}, due to
1272the limitations of file names imposed by DOS filesystems. The Windows
1273ports of @value{GDBN} use the standard name, but if they find a
1274@file{gdb.ini} file, they warn you about that and suggest to rename
1275the file to the standard name.
1276
6fc08d32 1277
6d2ebf8b 1278@node Quitting GDB
c906108c
SS
1279@section Quitting @value{GDBN}
1280@cindex exiting @value{GDBN}
1281@cindex leaving @value{GDBN}
1282
1283@table @code
1284@kindex quit @r{[}@var{expression}@r{]}
41afff9a 1285@kindex q @r{(@code{quit})}
96a2c332
SS
1286@item quit @r{[}@var{expression}@r{]}
1287@itemx q
1288To exit @value{GDBN}, use the @code{quit} command (abbreviated
c8aa23ab 1289@code{q}), or type an end-of-file character (usually @kbd{Ctrl-d}). If you
96a2c332
SS
1290do not supply @var{expression}, @value{GDBN} will terminate normally;
1291otherwise it will terminate using the result of @var{expression} as the
1292error code.
c906108c
SS
1293@end table
1294
1295@cindex interrupt
c8aa23ab 1296An interrupt (often @kbd{Ctrl-c}) does not exit from @value{GDBN}, but rather
c906108c
SS
1297terminates the action of any @value{GDBN} command that is in progress and
1298returns to @value{GDBN} command level. It is safe to type the interrupt
1299character at any time because @value{GDBN} does not allow it to take effect
1300until a time when it is safe.
1301
c906108c
SS
1302If you have been using @value{GDBN} to control an attached process or
1303device, you can release it with the @code{detach} command
79a6e687 1304(@pxref{Attach, ,Debugging an Already-running Process}).
c906108c 1305
6d2ebf8b 1306@node Shell Commands
79a6e687 1307@section Shell Commands
c906108c
SS
1308
1309If you need to execute occasional shell commands during your
1310debugging session, there is no need to leave or suspend @value{GDBN}; you can
1311just use the @code{shell} command.
1312
1313@table @code
1314@kindex shell
1315@cindex shell escape
1316@item shell @var{command string}
1317Invoke a standard shell to execute @var{command string}.
c906108c 1318If it exists, the environment variable @code{SHELL} determines which
d4f3574e
SS
1319shell to run. Otherwise @value{GDBN} uses the default shell
1320(@file{/bin/sh} on Unix systems, @file{COMMAND.COM} on MS-DOS, etc.).
c906108c
SS
1321@end table
1322
1323The utility @code{make} is often needed in development environments.
1324You do not have to use the @code{shell} command for this purpose in
1325@value{GDBN}:
1326
1327@table @code
1328@kindex make
1329@cindex calling make
1330@item make @var{make-args}
1331Execute the @code{make} program with the specified
1332arguments. This is equivalent to @samp{shell make @var{make-args}}.
1333@end table
1334
79a6e687
BW
1335@node Logging Output
1336@section Logging Output
0fac0b41 1337@cindex logging @value{GDBN} output
9c16f35a 1338@cindex save @value{GDBN} output to a file
0fac0b41
DJ
1339
1340You may want to save the output of @value{GDBN} commands to a file.
1341There are several commands to control @value{GDBN}'s logging.
1342
1343@table @code
1344@kindex set logging
1345@item set logging on
1346Enable logging.
1347@item set logging off
1348Disable logging.
9c16f35a 1349@cindex logging file name
0fac0b41
DJ
1350@item set logging file @var{file}
1351Change the name of the current logfile. The default logfile is @file{gdb.txt}.
1352@item set logging overwrite [on|off]
1353By default, @value{GDBN} will append to the logfile. Set @code{overwrite} if
1354you want @code{set logging on} to overwrite the logfile instead.
1355@item set logging redirect [on|off]
1356By default, @value{GDBN} output will go to both the terminal and the logfile.
1357Set @code{redirect} if you want output to go only to the log file.
1358@kindex show logging
1359@item show logging
1360Show the current values of the logging settings.
1361@end table
1362
6d2ebf8b 1363@node Commands
c906108c
SS
1364@chapter @value{GDBN} Commands
1365
1366You can abbreviate a @value{GDBN} command to the first few letters of the command
1367name, if that abbreviation is unambiguous; and you can repeat certain
1368@value{GDBN} commands by typing just @key{RET}. You can also use the @key{TAB}
1369key to get @value{GDBN} to fill out the rest of a word in a command (or to
1370show you the alternatives available, if there is more than one possibility).
1371
1372@menu
1373* Command Syntax:: How to give commands to @value{GDBN}
1374* Completion:: Command completion
1375* Help:: How to ask @value{GDBN} for help
1376@end menu
1377
6d2ebf8b 1378@node Command Syntax
79a6e687 1379@section Command Syntax
c906108c
SS
1380
1381A @value{GDBN} command is a single line of input. There is no limit on
1382how long it can be. It starts with a command name, which is followed by
1383arguments whose meaning depends on the command name. For example, the
1384command @code{step} accepts an argument which is the number of times to
1385step, as in @samp{step 5}. You can also use the @code{step} command
96a2c332 1386with no arguments. Some commands do not allow any arguments.
c906108c
SS
1387
1388@cindex abbreviation
1389@value{GDBN} command names may always be truncated if that abbreviation is
1390unambiguous. Other possible command abbreviations are listed in the
1391documentation for individual commands. In some cases, even ambiguous
1392abbreviations are allowed; for example, @code{s} is specially defined as
1393equivalent to @code{step} even though there are other commands whose
1394names start with @code{s}. You can test abbreviations by using them as
1395arguments to the @code{help} command.
1396
1397@cindex repeating commands
41afff9a 1398@kindex RET @r{(repeat last command)}
c906108c 1399A blank line as input to @value{GDBN} (typing just @key{RET}) means to
96a2c332 1400repeat the previous command. Certain commands (for example, @code{run})
c906108c
SS
1401will not repeat this way; these are commands whose unintentional
1402repetition might cause trouble and which you are unlikely to want to
c45da7e6
EZ
1403repeat. User-defined commands can disable this feature; see
1404@ref{Define, dont-repeat}.
c906108c
SS
1405
1406The @code{list} and @code{x} commands, when you repeat them with
1407@key{RET}, construct new arguments rather than repeating
1408exactly as typed. This permits easy scanning of source or memory.
1409
1410@value{GDBN} can also use @key{RET} in another way: to partition lengthy
1411output, in a way similar to the common utility @code{more}
79a6e687 1412(@pxref{Screen Size,,Screen Size}). Since it is easy to press one
c906108c
SS
1413@key{RET} too many in this situation, @value{GDBN} disables command
1414repetition after any command that generates this sort of display.
1415
41afff9a 1416@kindex # @r{(a comment)}
c906108c
SS
1417@cindex comment
1418Any text from a @kbd{#} to the end of the line is a comment; it does
1419nothing. This is useful mainly in command files (@pxref{Command
79a6e687 1420Files,,Command Files}).
c906108c 1421
88118b3a 1422@cindex repeating command sequences
c8aa23ab
EZ
1423@kindex Ctrl-o @r{(operate-and-get-next)}
1424The @kbd{Ctrl-o} binding is useful for repeating a complex sequence of
7f9087cb 1425commands. This command accepts the current line, like @key{RET}, and
88118b3a
TT
1426then fetches the next line relative to the current line from the history
1427for editing.
1428
6d2ebf8b 1429@node Completion
79a6e687 1430@section Command Completion
c906108c
SS
1431
1432@cindex completion
1433@cindex word completion
1434@value{GDBN} can fill in the rest of a word in a command for you, if there is
1435only one possibility; it can also show you what the valid possibilities
1436are for the next word in a command, at any time. This works for @value{GDBN}
1437commands, @value{GDBN} subcommands, and the names of symbols in your program.
1438
1439Press the @key{TAB} key whenever you want @value{GDBN} to fill out the rest
1440of a word. If there is only one possibility, @value{GDBN} fills in the
1441word, and waits for you to finish the command (or press @key{RET} to
1442enter it). For example, if you type
1443
1444@c FIXME "@key" does not distinguish its argument sufficiently to permit
1445@c complete accuracy in these examples; space introduced for clarity.
1446@c If texinfo enhancements make it unnecessary, it would be nice to
1447@c replace " @key" by "@key" in the following...
474c8240 1448@smallexample
c906108c 1449(@value{GDBP}) info bre @key{TAB}
474c8240 1450@end smallexample
c906108c
SS
1451
1452@noindent
1453@value{GDBN} fills in the rest of the word @samp{breakpoints}, since that is
1454the only @code{info} subcommand beginning with @samp{bre}:
1455
474c8240 1456@smallexample
c906108c 1457(@value{GDBP}) info breakpoints
474c8240 1458@end smallexample
c906108c
SS
1459
1460@noindent
1461You can either press @key{RET} at this point, to run the @code{info
1462breakpoints} command, or backspace and enter something else, if
1463@samp{breakpoints} does not look like the command you expected. (If you
1464were sure you wanted @code{info breakpoints} in the first place, you
1465might as well just type @key{RET} immediately after @samp{info bre},
1466to exploit command abbreviations rather than command completion).
1467
1468If there is more than one possibility for the next word when you press
1469@key{TAB}, @value{GDBN} sounds a bell. You can either supply more
1470characters and try again, or just press @key{TAB} a second time;
1471@value{GDBN} displays all the possible completions for that word. For
1472example, you might want to set a breakpoint on a subroutine whose name
1473begins with @samp{make_}, but when you type @kbd{b make_@key{TAB}} @value{GDBN}
1474just sounds the bell. Typing @key{TAB} again displays all the
1475function names in your program that begin with those characters, for
1476example:
1477
474c8240 1478@smallexample
c906108c
SS
1479(@value{GDBP}) b make_ @key{TAB}
1480@exdent @value{GDBN} sounds bell; press @key{TAB} again, to see:
5d161b24
DB
1481make_a_section_from_file make_environ
1482make_abs_section make_function_type
1483make_blockvector make_pointer_type
1484make_cleanup make_reference_type
c906108c
SS
1485make_command make_symbol_completion_list
1486(@value{GDBP}) b make_
474c8240 1487@end smallexample
c906108c
SS
1488
1489@noindent
1490After displaying the available possibilities, @value{GDBN} copies your
1491partial input (@samp{b make_} in the example) so you can finish the
1492command.
1493
1494If you just want to see the list of alternatives in the first place, you
b37052ae 1495can press @kbd{M-?} rather than pressing @key{TAB} twice. @kbd{M-?}
7a292a7a 1496means @kbd{@key{META} ?}. You can type this either by holding down a
c906108c 1497key designated as the @key{META} shift on your keyboard (if there is
7a292a7a 1498one) while typing @kbd{?}, or as @key{ESC} followed by @kbd{?}.
c906108c
SS
1499
1500@cindex quotes in commands
1501@cindex completion of quoted strings
1502Sometimes the string you need, while logically a ``word'', may contain
7a292a7a
SS
1503parentheses or other characters that @value{GDBN} normally excludes from
1504its notion of a word. To permit word completion to work in this
1505situation, you may enclose words in @code{'} (single quote marks) in
1506@value{GDBN} commands.
c906108c 1507
c906108c 1508The most likely situation where you might need this is in typing the
b37052ae
EZ
1509name of a C@t{++} function. This is because C@t{++} allows function
1510overloading (multiple definitions of the same function, distinguished
1511by argument type). For example, when you want to set a breakpoint you
1512may need to distinguish whether you mean the version of @code{name}
1513that takes an @code{int} parameter, @code{name(int)}, or the version
1514that takes a @code{float} parameter, @code{name(float)}. To use the
1515word-completion facilities in this situation, type a single quote
1516@code{'} at the beginning of the function name. This alerts
1517@value{GDBN} that it may need to consider more information than usual
1518when you press @key{TAB} or @kbd{M-?} to request word completion:
c906108c 1519
474c8240 1520@smallexample
96a2c332 1521(@value{GDBP}) b 'bubble( @kbd{M-?}
c906108c
SS
1522bubble(double,double) bubble(int,int)
1523(@value{GDBP}) b 'bubble(
474c8240 1524@end smallexample
c906108c
SS
1525
1526In some cases, @value{GDBN} can tell that completing a name requires using
1527quotes. When this happens, @value{GDBN} inserts the quote for you (while
1528completing as much as it can) if you do not type the quote in the first
1529place:
1530
474c8240 1531@smallexample
c906108c
SS
1532(@value{GDBP}) b bub @key{TAB}
1533@exdent @value{GDBN} alters your input line to the following, and rings a bell:
1534(@value{GDBP}) b 'bubble(
474c8240 1535@end smallexample
c906108c
SS
1536
1537@noindent
1538In general, @value{GDBN} can tell that a quote is needed (and inserts it) if
1539you have not yet started typing the argument list when you ask for
1540completion on an overloaded symbol.
1541
79a6e687
BW
1542For more information about overloaded functions, see @ref{C Plus Plus
1543Expressions, ,C@t{++} Expressions}. You can use the command @code{set
c906108c 1544overload-resolution off} to disable overload resolution;
79a6e687 1545see @ref{Debugging C Plus Plus, ,@value{GDBN} Features for C@t{++}}.
c906108c 1546
65d12d83
TT
1547@cindex completion of structure field names
1548@cindex structure field name completion
1549@cindex completion of union field names
1550@cindex union field name completion
1551When completing in an expression which looks up a field in a
1552structure, @value{GDBN} also tries@footnote{The completer can be
1553confused by certain kinds of invalid expressions. Also, it only
1554examines the static type of the expression, not the dynamic type.} to
1555limit completions to the field names available in the type of the
1556left-hand-side:
1557
1558@smallexample
1559(@value{GDBP}) p gdb_stdout.@kbd{M-?}
1560magic to_delete to_fputs to_put to_rewind
1561to_data to_flush to_isatty to_read to_write
1562@end smallexample
1563
1564@noindent
1565This is because the @code{gdb_stdout} is a variable of the type
1566@code{struct ui_file} that is defined in @value{GDBN} sources as
1567follows:
1568
1569@smallexample
1570struct ui_file
1571@{
1572 int *magic;
1573 ui_file_flush_ftype *to_flush;
1574 ui_file_write_ftype *to_write;
1575 ui_file_fputs_ftype *to_fputs;
1576 ui_file_read_ftype *to_read;
1577 ui_file_delete_ftype *to_delete;
1578 ui_file_isatty_ftype *to_isatty;
1579 ui_file_rewind_ftype *to_rewind;
1580 ui_file_put_ftype *to_put;
1581 void *to_data;
1582@}
1583@end smallexample
1584
c906108c 1585
6d2ebf8b 1586@node Help
79a6e687 1587@section Getting Help
c906108c
SS
1588@cindex online documentation
1589@kindex help
1590
5d161b24 1591You can always ask @value{GDBN} itself for information on its commands,
c906108c
SS
1592using the command @code{help}.
1593
1594@table @code
41afff9a 1595@kindex h @r{(@code{help})}
c906108c
SS
1596@item help
1597@itemx h
1598You can use @code{help} (abbreviated @code{h}) with no arguments to
1599display a short list of named classes of commands:
1600
1601@smallexample
1602(@value{GDBP}) help
1603List of classes of commands:
1604
2df3850c 1605aliases -- Aliases of other commands
c906108c 1606breakpoints -- Making program stop at certain points
2df3850c 1607data -- Examining data
c906108c 1608files -- Specifying and examining files
2df3850c
JM
1609internals -- Maintenance commands
1610obscure -- Obscure features
1611running -- Running the program
1612stack -- Examining the stack
c906108c
SS
1613status -- Status inquiries
1614support -- Support facilities
12c27660 1615tracepoints -- Tracing of program execution without
96a2c332 1616 stopping the program
c906108c 1617user-defined -- User-defined commands
c906108c 1618
5d161b24 1619Type "help" followed by a class name for a list of
c906108c 1620commands in that class.
5d161b24 1621Type "help" followed by command name for full
c906108c
SS
1622documentation.
1623Command name abbreviations are allowed if unambiguous.
1624(@value{GDBP})
1625@end smallexample
96a2c332 1626@c the above line break eliminates huge line overfull...
c906108c
SS
1627
1628@item help @var{class}
1629Using one of the general help classes as an argument, you can get a
1630list of the individual commands in that class. For example, here is the
1631help display for the class @code{status}:
1632
1633@smallexample
1634(@value{GDBP}) help status
1635Status inquiries.
1636
1637List of commands:
1638
1639@c Line break in "show" line falsifies real output, but needed
1640@c to fit in smallbook page size.
2df3850c 1641info -- Generic command for showing things
12c27660 1642 about the program being debugged
2df3850c 1643show -- Generic command for showing things
12c27660 1644 about the debugger
c906108c 1645
5d161b24 1646Type "help" followed by command name for full
c906108c
SS
1647documentation.
1648Command name abbreviations are allowed if unambiguous.
1649(@value{GDBP})
1650@end smallexample
1651
1652@item help @var{command}
1653With a command name as @code{help} argument, @value{GDBN} displays a
1654short paragraph on how to use that command.
1655
6837a0a2
DB
1656@kindex apropos
1657@item apropos @var{args}
09d4efe1 1658The @code{apropos} command searches through all of the @value{GDBN}
6837a0a2 1659commands, and their documentation, for the regular expression specified in
99e008fe 1660@var{args}. It prints out all matches found. For example:
6837a0a2
DB
1661
1662@smallexample
1663apropos reload
1664@end smallexample
1665
b37052ae
EZ
1666@noindent
1667results in:
6837a0a2
DB
1668
1669@smallexample
6d2ebf8b
SS
1670@c @group
1671set symbol-reloading -- Set dynamic symbol table reloading
12c27660 1672 multiple times in one run
6d2ebf8b 1673show symbol-reloading -- Show dynamic symbol table reloading
12c27660 1674 multiple times in one run
6d2ebf8b 1675@c @end group
6837a0a2
DB
1676@end smallexample
1677
c906108c
SS
1678@kindex complete
1679@item complete @var{args}
1680The @code{complete @var{args}} command lists all the possible completions
1681for the beginning of a command. Use @var{args} to specify the beginning of the
1682command you want completed. For example:
1683
1684@smallexample
1685complete i
1686@end smallexample
1687
1688@noindent results in:
1689
1690@smallexample
1691@group
2df3850c
JM
1692if
1693ignore
c906108c
SS
1694info
1695inspect
c906108c
SS
1696@end group
1697@end smallexample
1698
1699@noindent This is intended for use by @sc{gnu} Emacs.
1700@end table
1701
1702In addition to @code{help}, you can use the @value{GDBN} commands @code{info}
1703and @code{show} to inquire about the state of your program, or the state
1704of @value{GDBN} itself. Each command supports many topics of inquiry; this
1705manual introduces each of them in the appropriate context. The listings
1706under @code{info} and under @code{show} in the Index point to
1707all the sub-commands. @xref{Index}.
1708
1709@c @group
1710@table @code
1711@kindex info
41afff9a 1712@kindex i @r{(@code{info})}
c906108c
SS
1713@item info
1714This command (abbreviated @code{i}) is for describing the state of your
cda4ce5a 1715program. For example, you can show the arguments passed to a function
c906108c
SS
1716with @code{info args}, list the registers currently in use with @code{info
1717registers}, or list the breakpoints you have set with @code{info breakpoints}.
1718You can get a complete list of the @code{info} sub-commands with
1719@w{@code{help info}}.
1720
1721@kindex set
1722@item set
5d161b24 1723You can assign the result of an expression to an environment variable with
c906108c
SS
1724@code{set}. For example, you can set the @value{GDBN} prompt to a $-sign with
1725@code{set prompt $}.
1726
1727@kindex show
1728@item show
5d161b24 1729In contrast to @code{info}, @code{show} is for describing the state of
c906108c
SS
1730@value{GDBN} itself.
1731You can change most of the things you can @code{show}, by using the
1732related command @code{set}; for example, you can control what number
1733system is used for displays with @code{set radix}, or simply inquire
1734which is currently in use with @code{show radix}.
1735
1736@kindex info set
1737To display all the settable parameters and their current
1738values, you can use @code{show} with no arguments; you may also use
1739@code{info set}. Both commands produce the same display.
1740@c FIXME: "info set" violates the rule that "info" is for state of
1741@c FIXME...program. Ck w/ GNU: "info set" to be called something else,
1742@c FIXME...or change desc of rule---eg "state of prog and debugging session"?
1743@end table
1744@c @end group
1745
1746Here are three miscellaneous @code{show} subcommands, all of which are
1747exceptional in lacking corresponding @code{set} commands:
1748
1749@table @code
1750@kindex show version
9c16f35a 1751@cindex @value{GDBN} version number
c906108c
SS
1752@item show version
1753Show what version of @value{GDBN} is running. You should include this
2df3850c
JM
1754information in @value{GDBN} bug-reports. If multiple versions of
1755@value{GDBN} are in use at your site, you may need to determine which
1756version of @value{GDBN} you are running; as @value{GDBN} evolves, new
1757commands are introduced, and old ones may wither away. Also, many
1758system vendors ship variant versions of @value{GDBN}, and there are
96a2c332 1759variant versions of @value{GDBN} in @sc{gnu}/Linux distributions as well.
2df3850c
JM
1760The version number is the same as the one announced when you start
1761@value{GDBN}.
c906108c
SS
1762
1763@kindex show copying
09d4efe1 1764@kindex info copying
9c16f35a 1765@cindex display @value{GDBN} copyright
c906108c 1766@item show copying
09d4efe1 1767@itemx info copying
c906108c
SS
1768Display information about permission for copying @value{GDBN}.
1769
1770@kindex show warranty
09d4efe1 1771@kindex info warranty
c906108c 1772@item show warranty
09d4efe1 1773@itemx info warranty
2df3850c 1774Display the @sc{gnu} ``NO WARRANTY'' statement, or a warranty,
96a2c332 1775if your version of @value{GDBN} comes with one.
2df3850c 1776
c906108c
SS
1777@end table
1778
6d2ebf8b 1779@node Running
c906108c
SS
1780@chapter Running Programs Under @value{GDBN}
1781
1782When you run a program under @value{GDBN}, you must first generate
1783debugging information when you compile it.
7a292a7a
SS
1784
1785You may start @value{GDBN} with its arguments, if any, in an environment
1786of your choice. If you are doing native debugging, you may redirect
1787your program's input and output, debug an already running process, or
1788kill a child process.
c906108c
SS
1789
1790@menu
1791* Compilation:: Compiling for debugging
1792* Starting:: Starting your program
c906108c
SS
1793* Arguments:: Your program's arguments
1794* Environment:: Your program's environment
c906108c
SS
1795
1796* Working Directory:: Your program's working directory
1797* Input/Output:: Your program's input and output
1798* Attach:: Debugging an already-running process
1799* Kill Process:: Killing the child process
c906108c 1800
6c95b8df 1801* Inferiors and Programs:: Debugging multiple inferiors and programs
c906108c 1802* Threads:: Debugging programs with multiple threads
6c95b8df 1803* Forks:: Debugging forks
5c95884b 1804* Checkpoint/Restart:: Setting a @emph{bookmark} to return to later
c906108c
SS
1805@end menu
1806
6d2ebf8b 1807@node Compilation
79a6e687 1808@section Compiling for Debugging
c906108c
SS
1809
1810In order to debug a program effectively, you need to generate
1811debugging information when you compile it. This debugging information
1812is stored in the object file; it describes the data type of each
1813variable or function and the correspondence between source line numbers
1814and addresses in the executable code.
1815
1816To request debugging information, specify the @samp{-g} option when you run
1817the compiler.
1818
514c4d71 1819Programs that are to be shipped to your customers are compiled with
edb3359d 1820optimizations, using the @samp{-O} compiler option. However, some
514c4d71
EZ
1821compilers are unable to handle the @samp{-g} and @samp{-O} options
1822together. Using those compilers, you cannot generate optimized
c906108c
SS
1823executables containing debugging information.
1824
514c4d71 1825@value{NGCC}, the @sc{gnu} C/C@t{++} compiler, supports @samp{-g} with or
53a5351d
JM
1826without @samp{-O}, making it possible to debug optimized code. We
1827recommend that you @emph{always} use @samp{-g} whenever you compile a
1828program. You may think your program is correct, but there is no sense
edb3359d 1829in pushing your luck. For more information, see @ref{Optimized Code}.
c906108c
SS
1830
1831Older versions of the @sc{gnu} C compiler permitted a variant option
1832@w{@samp{-gg}} for debugging information. @value{GDBN} no longer supports this
1833format; if your @sc{gnu} C compiler has this option, do not use it.
1834
514c4d71
EZ
1835@value{GDBN} knows about preprocessor macros and can show you their
1836expansion (@pxref{Macros}). Most compilers do not include information
1837about preprocessor macros in the debugging information if you specify
1838the @option{-g} flag alone, because this information is rather large.
1839Version 3.1 and later of @value{NGCC}, the @sc{gnu} C compiler,
1840provides macro information if you specify the options
1841@option{-gdwarf-2} and @option{-g3}; the former option requests
1842debugging information in the Dwarf 2 format, and the latter requests
1843``extra information''. In the future, we hope to find more compact
1844ways to represent macro information, so that it can be included with
1845@option{-g} alone.
1846
c906108c 1847@need 2000
6d2ebf8b 1848@node Starting
79a6e687 1849@section Starting your Program
c906108c
SS
1850@cindex starting
1851@cindex running
1852
1853@table @code
1854@kindex run
41afff9a 1855@kindex r @r{(@code{run})}
c906108c
SS
1856@item run
1857@itemx r
7a292a7a
SS
1858Use the @code{run} command to start your program under @value{GDBN}.
1859You must first specify the program name (except on VxWorks) with an
1860argument to @value{GDBN} (@pxref{Invocation, ,Getting In and Out of
1861@value{GDBN}}), or by using the @code{file} or @code{exec-file} command
79a6e687 1862(@pxref{Files, ,Commands to Specify Files}).
c906108c
SS
1863
1864@end table
1865
c906108c
SS
1866If you are running your program in an execution environment that
1867supports processes, @code{run} creates an inferior process and makes
8edfe269
DJ
1868that process run your program. In some environments without processes,
1869@code{run} jumps to the start of your program. Other targets,
1870like @samp{remote}, are always running. If you get an error
1871message like this one:
1872
1873@smallexample
1874The "remote" target does not support "run".
1875Try "help target" or "continue".
1876@end smallexample
1877
1878@noindent
1879then use @code{continue} to run your program. You may need @code{load}
1880first (@pxref{load}).
c906108c
SS
1881
1882The execution of a program is affected by certain information it
1883receives from its superior. @value{GDBN} provides ways to specify this
1884information, which you must do @emph{before} starting your program. (You
1885can change it after starting your program, but such changes only affect
1886your program the next time you start it.) This information may be
1887divided into four categories:
1888
1889@table @asis
1890@item The @emph{arguments.}
1891Specify the arguments to give your program as the arguments of the
1892@code{run} command. If a shell is available on your target, the shell
1893is used to pass the arguments, so that you may use normal conventions
1894(such as wildcard expansion or variable substitution) in describing
1895the arguments.
1896In Unix systems, you can control which shell is used with the
1897@code{SHELL} environment variable.
79a6e687 1898@xref{Arguments, ,Your Program's Arguments}.
c906108c
SS
1899
1900@item The @emph{environment.}
1901Your program normally inherits its environment from @value{GDBN}, but you can
1902use the @value{GDBN} commands @code{set environment} and @code{unset
1903environment} to change parts of the environment that affect
79a6e687 1904your program. @xref{Environment, ,Your Program's Environment}.
c906108c
SS
1905
1906@item The @emph{working directory.}
1907Your program inherits its working directory from @value{GDBN}. You can set
1908the @value{GDBN} working directory with the @code{cd} command in @value{GDBN}.
79a6e687 1909@xref{Working Directory, ,Your Program's Working Directory}.
c906108c
SS
1910
1911@item The @emph{standard input and output.}
1912Your program normally uses the same device for standard input and
1913standard output as @value{GDBN} is using. You can redirect input and output
1914in the @code{run} command line, or you can use the @code{tty} command to
1915set a different device for your program.
79a6e687 1916@xref{Input/Output, ,Your Program's Input and Output}.
c906108c
SS
1917
1918@cindex pipes
1919@emph{Warning:} While input and output redirection work, you cannot use
1920pipes to pass the output of the program you are debugging to another
1921program; if you attempt this, @value{GDBN} is likely to wind up debugging the
1922wrong program.
1923@end table
c906108c
SS
1924
1925When you issue the @code{run} command, your program begins to execute
79a6e687 1926immediately. @xref{Stopping, ,Stopping and Continuing}, for discussion
c906108c
SS
1927of how to arrange for your program to stop. Once your program has
1928stopped, you may call functions in your program, using the @code{print}
1929or @code{call} commands. @xref{Data, ,Examining Data}.
1930
1931If the modification time of your symbol file has changed since the last
1932time @value{GDBN} read its symbols, @value{GDBN} discards its symbol
1933table, and reads it again. When it does this, @value{GDBN} tries to retain
1934your current breakpoints.
1935
4e8b0763
JB
1936@table @code
1937@kindex start
1938@item start
1939@cindex run to main procedure
1940The name of the main procedure can vary from language to language.
1941With C or C@t{++}, the main procedure name is always @code{main}, but
1942other languages such as Ada do not require a specific name for their
1943main procedure. The debugger provides a convenient way to start the
1944execution of the program and to stop at the beginning of the main
1945procedure, depending on the language used.
1946
1947The @samp{start} command does the equivalent of setting a temporary
1948breakpoint at the beginning of the main procedure and then invoking
1949the @samp{run} command.
1950
f018e82f
EZ
1951@cindex elaboration phase
1952Some programs contain an @dfn{elaboration} phase where some startup code is
1953executed before the main procedure is called. This depends on the
1954languages used to write your program. In C@t{++}, for instance,
4e8b0763
JB
1955constructors for static and global objects are executed before
1956@code{main} is called. It is therefore possible that the debugger stops
1957before reaching the main procedure. However, the temporary breakpoint
1958will remain to halt execution.
1959
1960Specify the arguments to give to your program as arguments to the
1961@samp{start} command. These arguments will be given verbatim to the
1962underlying @samp{run} command. Note that the same arguments will be
1963reused if no argument is provided during subsequent calls to
1964@samp{start} or @samp{run}.
1965
1966It is sometimes necessary to debug the program during elaboration. In
1967these cases, using the @code{start} command would stop the execution of
1968your program too late, as the program would have already completed the
1969elaboration phase. Under these circumstances, insert breakpoints in your
1970elaboration code before running your program.
ccd213ac
DJ
1971
1972@kindex set exec-wrapper
1973@item set exec-wrapper @var{wrapper}
1974@itemx show exec-wrapper
1975@itemx unset exec-wrapper
1976When @samp{exec-wrapper} is set, the specified wrapper is used to
1977launch programs for debugging. @value{GDBN} starts your program
1978with a shell command of the form @kbd{exec @var{wrapper}
1979@var{program}}. Quoting is added to @var{program} and its
1980arguments, but not to @var{wrapper}, so you should add quotes if
1981appropriate for your shell. The wrapper runs until it executes
1982your program, and then @value{GDBN} takes control.
1983
1984You can use any program that eventually calls @code{execve} with
1985its arguments as a wrapper. Several standard Unix utilities do
1986this, e.g.@: @code{env} and @code{nohup}. Any Unix shell script ending
1987with @code{exec "$@@"} will also work.
1988
1989For example, you can use @code{env} to pass an environment variable to
1990the debugged program, without setting the variable in your shell's
1991environment:
1992
1993@smallexample
1994(@value{GDBP}) set exec-wrapper env 'LD_PRELOAD=libtest.so'
1995(@value{GDBP}) run
1996@end smallexample
1997
1998This command is available when debugging locally on most targets, excluding
1999@sc{djgpp}, Cygwin, MS Windows, and QNX Neutrino.
2000
10568435
JK
2001@kindex set disable-randomization
2002@item set disable-randomization
2003@itemx set disable-randomization on
2004This option (enabled by default in @value{GDBN}) will turn off the native
2005randomization of the virtual address space of the started program. This option
2006is useful for multiple debugging sessions to make the execution better
2007reproducible and memory addresses reusable across debugging sessions.
2008
2009This feature is implemented only on @sc{gnu}/Linux. You can get the same
2010behavior using
2011
2012@smallexample
2013(@value{GDBP}) set exec-wrapper setarch `uname -m` -R
2014@end smallexample
2015
2016@item set disable-randomization off
2017Leave the behavior of the started executable unchanged. Some bugs rear their
2018ugly heads only when the program is loaded at certain addresses. If your bug
2019disappears when you run the program under @value{GDBN}, that might be because
2020@value{GDBN} by default disables the address randomization on platforms, such
2021as @sc{gnu}/Linux, which do that for stand-alone programs. Use @kbd{set
2022disable-randomization off} to try to reproduce such elusive bugs.
2023
2024The virtual address space randomization is implemented only on @sc{gnu}/Linux.
2025It protects the programs against some kinds of security attacks. In these
2026cases the attacker needs to know the exact location of a concrete executable
2027code. Randomizing its location makes it impossible to inject jumps misusing
2028a code at its expected addresses.
2029
2030Prelinking shared libraries provides a startup performance advantage but it
2031makes addresses in these libraries predictable for privileged processes by
2032having just unprivileged access at the target system. Reading the shared
2033library binary gives enough information for assembling the malicious code
2034misusing it. Still even a prelinked shared library can get loaded at a new
2035random address just requiring the regular relocation process during the
2036startup. Shared libraries not already prelinked are always loaded at
2037a randomly chosen address.
2038
2039Position independent executables (PIE) contain position independent code
2040similar to the shared libraries and therefore such executables get loaded at
2041a randomly chosen address upon startup. PIE executables always load even
2042already prelinked shared libraries at a random address. You can build such
2043executable using @command{gcc -fPIE -pie}.
2044
2045Heap (malloc storage), stack and custom mmap areas are always placed randomly
2046(as long as the randomization is enabled).
2047
2048@item show disable-randomization
2049Show the current setting of the explicit disable of the native randomization of
2050the virtual address space of the started program.
2051
4e8b0763
JB
2052@end table
2053
6d2ebf8b 2054@node Arguments
79a6e687 2055@section Your Program's Arguments
c906108c
SS
2056
2057@cindex arguments (to your program)
2058The arguments to your program can be specified by the arguments of the
5d161b24 2059@code{run} command.
c906108c
SS
2060They are passed to a shell, which expands wildcard characters and
2061performs redirection of I/O, and thence to your program. Your
2062@code{SHELL} environment variable (if it exists) specifies what shell
2063@value{GDBN} uses. If you do not define @code{SHELL}, @value{GDBN} uses
d4f3574e
SS
2064the default shell (@file{/bin/sh} on Unix).
2065
2066On non-Unix systems, the program is usually invoked directly by
2067@value{GDBN}, which emulates I/O redirection via the appropriate system
2068calls, and the wildcard characters are expanded by the startup code of
2069the program, not by the shell.
c906108c
SS
2070
2071@code{run} with no arguments uses the same arguments used by the previous
2072@code{run}, or those set by the @code{set args} command.
2073
c906108c 2074@table @code
41afff9a 2075@kindex set args
c906108c
SS
2076@item set args
2077Specify the arguments to be used the next time your program is run. If
2078@code{set args} has no arguments, @code{run} executes your program
2079with no arguments. Once you have run your program with arguments,
2080using @code{set args} before the next @code{run} is the only way to run
2081it again without arguments.
2082
2083@kindex show args
2084@item show args
2085Show the arguments to give your program when it is started.
2086@end table
2087
6d2ebf8b 2088@node Environment
79a6e687 2089@section Your Program's Environment
c906108c
SS
2090
2091@cindex environment (of your program)
2092The @dfn{environment} consists of a set of environment variables and
2093their values. Environment variables conventionally record such things as
2094your user name, your home directory, your terminal type, and your search
2095path for programs to run. Usually you set up environment variables with
2096the shell and they are inherited by all the other programs you run. When
2097debugging, it can be useful to try running your program with a modified
2098environment without having to start @value{GDBN} over again.
2099
2100@table @code
2101@kindex path
2102@item path @var{directory}
2103Add @var{directory} to the front of the @code{PATH} environment variable
17cc6a06
EZ
2104(the search path for executables) that will be passed to your program.
2105The value of @code{PATH} used by @value{GDBN} does not change.
d4f3574e
SS
2106You may specify several directory names, separated by whitespace or by a
2107system-dependent separator character (@samp{:} on Unix, @samp{;} on
2108MS-DOS and MS-Windows). If @var{directory} is already in the path, it
2109is moved to the front, so it is searched sooner.
c906108c
SS
2110
2111You can use the string @samp{$cwd} to refer to whatever is the current
2112working directory at the time @value{GDBN} searches the path. If you
2113use @samp{.} instead, it refers to the directory where you executed the
2114@code{path} command. @value{GDBN} replaces @samp{.} in the
2115@var{directory} argument (with the current path) before adding
2116@var{directory} to the search path.
2117@c 'path' is explicitly nonrepeatable, but RMS points out it is silly to
2118@c document that, since repeating it would be a no-op.
2119
2120@kindex show paths
2121@item show paths
2122Display the list of search paths for executables (the @code{PATH}
2123environment variable).
2124
2125@kindex show environment
2126@item show environment @r{[}@var{varname}@r{]}
2127Print the value of environment variable @var{varname} to be given to
2128your program when it starts. If you do not supply @var{varname},
2129print the names and values of all environment variables to be given to
2130your program. You can abbreviate @code{environment} as @code{env}.
2131
2132@kindex set environment
53a5351d 2133@item set environment @var{varname} @r{[}=@var{value}@r{]}
c906108c
SS
2134Set environment variable @var{varname} to @var{value}. The value
2135changes for your program only, not for @value{GDBN} itself. @var{value} may
2136be any string; the values of environment variables are just strings, and
2137any interpretation is supplied by your program itself. The @var{value}
2138parameter is optional; if it is eliminated, the variable is set to a
2139null value.
2140@c "any string" here does not include leading, trailing
2141@c blanks. Gnu asks: does anyone care?
2142
2143For example, this command:
2144
474c8240 2145@smallexample
c906108c 2146set env USER = foo
474c8240 2147@end smallexample
c906108c
SS
2148
2149@noindent
d4f3574e 2150tells the debugged program, when subsequently run, that its user is named
c906108c
SS
2151@samp{foo}. (The spaces around @samp{=} are used for clarity here; they
2152are not actually required.)
2153
2154@kindex unset environment
2155@item unset environment @var{varname}
2156Remove variable @var{varname} from the environment to be passed to your
2157program. This is different from @samp{set env @var{varname} =};
2158@code{unset environment} removes the variable from the environment,
2159rather than assigning it an empty value.
2160@end table
2161
d4f3574e
SS
2162@emph{Warning:} On Unix systems, @value{GDBN} runs your program using
2163the shell indicated
c906108c
SS
2164by your @code{SHELL} environment variable if it exists (or
2165@code{/bin/sh} if not). If your @code{SHELL} variable names a shell
2166that runs an initialization file---such as @file{.cshrc} for C-shell, or
2167@file{.bashrc} for BASH---any variables you set in that file affect
2168your program. You may wish to move setting of environment variables to
2169files that are only run when you sign on, such as @file{.login} or
2170@file{.profile}.
2171
6d2ebf8b 2172@node Working Directory
79a6e687 2173@section Your Program's Working Directory
c906108c
SS
2174
2175@cindex working directory (of your program)
2176Each time you start your program with @code{run}, it inherits its
2177working directory from the current working directory of @value{GDBN}.
2178The @value{GDBN} working directory is initially whatever it inherited
2179from its parent process (typically the shell), but you can specify a new
2180working directory in @value{GDBN} with the @code{cd} command.
2181
2182The @value{GDBN} working directory also serves as a default for the commands
2183that specify files for @value{GDBN} to operate on. @xref{Files, ,Commands to
79a6e687 2184Specify Files}.
c906108c
SS
2185
2186@table @code
2187@kindex cd
721c2651 2188@cindex change working directory
c906108c
SS
2189@item cd @var{directory}
2190Set the @value{GDBN} working directory to @var{directory}.
2191
2192@kindex pwd
2193@item pwd
2194Print the @value{GDBN} working directory.
2195@end table
2196
60bf7e09
EZ
2197It is generally impossible to find the current working directory of
2198the process being debugged (since a program can change its directory
2199during its run). If you work on a system where @value{GDBN} is
2200configured with the @file{/proc} support, you can use the @code{info
2201proc} command (@pxref{SVR4 Process Information}) to find out the
2202current working directory of the debuggee.
2203
6d2ebf8b 2204@node Input/Output
79a6e687 2205@section Your Program's Input and Output
c906108c
SS
2206
2207@cindex redirection
2208@cindex i/o
2209@cindex terminal
2210By default, the program you run under @value{GDBN} does input and output to
5d161b24 2211the same terminal that @value{GDBN} uses. @value{GDBN} switches the terminal
c906108c
SS
2212to its own terminal modes to interact with you, but it records the terminal
2213modes your program was using and switches back to them when you continue
2214running your program.
2215
2216@table @code
2217@kindex info terminal
2218@item info terminal
2219Displays information recorded by @value{GDBN} about the terminal modes your
2220program is using.
2221@end table
2222
2223You can redirect your program's input and/or output using shell
2224redirection with the @code{run} command. For example,
2225
474c8240 2226@smallexample
c906108c 2227run > outfile
474c8240 2228@end smallexample
c906108c
SS
2229
2230@noindent
2231starts your program, diverting its output to the file @file{outfile}.
2232
2233@kindex tty
2234@cindex controlling terminal
2235Another way to specify where your program should do input and output is
2236with the @code{tty} command. This command accepts a file name as
2237argument, and causes this file to be the default for future @code{run}
2238commands. It also resets the controlling terminal for the child
2239process, for future @code{run} commands. For example,
2240
474c8240 2241@smallexample
c906108c 2242tty /dev/ttyb
474c8240 2243@end smallexample
c906108c
SS
2244
2245@noindent
2246directs that processes started with subsequent @code{run} commands
2247default to do input and output on the terminal @file{/dev/ttyb} and have
2248that as their controlling terminal.
2249
2250An explicit redirection in @code{run} overrides the @code{tty} command's
2251effect on the input/output device, but not its effect on the controlling
2252terminal.
2253
2254When you use the @code{tty} command or redirect input in the @code{run}
2255command, only the input @emph{for your program} is affected. The input
3cb3b8df
BR
2256for @value{GDBN} still comes from your terminal. @code{tty} is an alias
2257for @code{set inferior-tty}.
2258
2259@cindex inferior tty
2260@cindex set inferior controlling terminal
2261You can use the @code{show inferior-tty} command to tell @value{GDBN} to
2262display the name of the terminal that will be used for future runs of your
2263program.
2264
2265@table @code
2266@item set inferior-tty /dev/ttyb
2267@kindex set inferior-tty
2268Set the tty for the program being debugged to /dev/ttyb.
2269
2270@item show inferior-tty
2271@kindex show inferior-tty
2272Show the current tty for the program being debugged.
2273@end table
c906108c 2274
6d2ebf8b 2275@node Attach
79a6e687 2276@section Debugging an Already-running Process
c906108c
SS
2277@kindex attach
2278@cindex attach
2279
2280@table @code
2281@item attach @var{process-id}
2282This command attaches to a running process---one that was started
2283outside @value{GDBN}. (@code{info files} shows your active
2284targets.) The command takes as argument a process ID. The usual way to
09d4efe1 2285find out the @var{process-id} of a Unix process is with the @code{ps} utility,
c906108c
SS
2286or with the @samp{jobs -l} shell command.
2287
2288@code{attach} does not repeat if you press @key{RET} a second time after
2289executing the command.
2290@end table
2291
2292To use @code{attach}, your program must be running in an environment
2293which supports processes; for example, @code{attach} does not work for
2294programs on bare-board targets that lack an operating system. You must
2295also have permission to send the process a signal.
2296
2297When you use @code{attach}, the debugger finds the program running in
2298the process first by looking in the current working directory, then (if
2299the program is not found) by using the source file search path
79a6e687 2300(@pxref{Source Path, ,Specifying Source Directories}). You can also use
c906108c
SS
2301the @code{file} command to load the program. @xref{Files, ,Commands to
2302Specify Files}.
2303
2304The first thing @value{GDBN} does after arranging to debug the specified
2305process is to stop it. You can examine and modify an attached process
53a5351d
JM
2306with all the @value{GDBN} commands that are ordinarily available when
2307you start processes with @code{run}. You can insert breakpoints; you
2308can step and continue; you can modify storage. If you would rather the
2309process continue running, you may use the @code{continue} command after
c906108c
SS
2310attaching @value{GDBN} to the process.
2311
2312@table @code
2313@kindex detach
2314@item detach
2315When you have finished debugging the attached process, you can use the
2316@code{detach} command to release it from @value{GDBN} control. Detaching
2317the process continues its execution. After the @code{detach} command,
2318that process and @value{GDBN} become completely independent once more, and you
2319are ready to @code{attach} another process or start one with @code{run}.
2320@code{detach} does not repeat if you press @key{RET} again after
2321executing the command.
2322@end table
2323
159fcc13
JK
2324If you exit @value{GDBN} while you have an attached process, you detach
2325that process. If you use the @code{run} command, you kill that process.
2326By default, @value{GDBN} asks for confirmation if you try to do either of these
2327things; you can control whether or not you need to confirm by using the
2328@code{set confirm} command (@pxref{Messages/Warnings, ,Optional Warnings and
79a6e687 2329Messages}).
c906108c 2330
6d2ebf8b 2331@node Kill Process
79a6e687 2332@section Killing the Child Process
c906108c
SS
2333
2334@table @code
2335@kindex kill
2336@item kill
2337Kill the child process in which your program is running under @value{GDBN}.
2338@end table
2339
2340This command is useful if you wish to debug a core dump instead of a
2341running process. @value{GDBN} ignores any core dump file while your program
2342is running.
2343
2344On some operating systems, a program cannot be executed outside @value{GDBN}
2345while you have breakpoints set on it inside @value{GDBN}. You can use the
2346@code{kill} command in this situation to permit running your program
2347outside the debugger.
2348
2349The @code{kill} command is also useful if you wish to recompile and
2350relink your program, since on many systems it is impossible to modify an
2351executable file while it is running in a process. In this case, when you
2352next type @code{run}, @value{GDBN} notices that the file has changed, and
2353reads the symbol table again (while trying to preserve your current
2354breakpoint settings).
2355
6c95b8df
PA
2356@node Inferiors and Programs
2357@section Debugging Multiple Inferiors and Programs
b77209e0 2358
6c95b8df
PA
2359@value{GDBN} lets you run and debug multiple programs in a single
2360session. In addition, @value{GDBN} on some systems may let you run
2361several programs simultaneously (otherwise you have to exit from one
2362before starting another). In the most general case, you can have
2363multiple threads of execution in each of multiple processes, launched
2364from multiple executables.
b77209e0
PA
2365
2366@cindex inferior
2367@value{GDBN} represents the state of each program execution with an
2368object called an @dfn{inferior}. An inferior typically corresponds to
2369a process, but is more general and applies also to targets that do not
2370have processes. Inferiors may be created before a process runs, and
6c95b8df
PA
2371may be retained after a process exits. Inferiors have unique
2372identifiers that are different from process ids. Usually each
2373inferior will also have its own distinct address space, although some
2374embedded targets may have several inferiors running in different parts
2375of a single address space. Each inferior may in turn have multiple
2376threads running in it.
b77209e0 2377
6c95b8df
PA
2378To find out what inferiors exist at any moment, use @w{@code{info
2379inferiors}}:
b77209e0
PA
2380
2381@table @code
2382@kindex info inferiors
2383@item info inferiors
2384Print a list of all inferiors currently being managed by @value{GDBN}.
3a1ff0b6
PA
2385
2386@value{GDBN} displays for each inferior (in this order):
2387
2388@enumerate
2389@item
2390the inferior number assigned by @value{GDBN}
2391
2392@item
2393the target system's inferior identifier
6c95b8df
PA
2394
2395@item
2396the name of the executable the inferior is running.
2397
3a1ff0b6
PA
2398@end enumerate
2399
2400@noindent
2401An asterisk @samp{*} preceding the @value{GDBN} inferior number
2402indicates the current inferior.
2403
2404For example,
2277426b 2405@end table
3a1ff0b6
PA
2406@c end table here to get a little more width for example
2407
2408@smallexample
2409(@value{GDBP}) info inferiors
6c95b8df
PA
2410 Num Description Executable
2411 2 process 2307 hello
2412* 1 process 3401 goodbye
3a1ff0b6 2413@end smallexample
2277426b
PA
2414
2415To switch focus between inferiors, use the @code{inferior} command:
2416
2417@table @code
3a1ff0b6
PA
2418@kindex inferior @var{infno}
2419@item inferior @var{infno}
2420Make inferior number @var{infno} the current inferior. The argument
2421@var{infno} is the inferior number assigned by @value{GDBN}, as shown
2422in the first field of the @samp{info inferiors} display.
2277426b
PA
2423@end table
2424
6c95b8df
PA
2425
2426You can get multiple executables into a debugging session via the
2427@code{add-inferior} and @w{@code{clone-inferior}} commands. On some
2428systems @value{GDBN} can add inferiors to the debug session
2429automatically by following calls to @code{fork} and @code{exec}. To
2430remove inferiors from the debugging session use the
2431@w{@code{remove-inferior}} command.
2432
2433@table @code
2434@kindex add-inferior
2435@item add-inferior [ -copies @var{n} ] [ -exec @var{executable} ]
2436Adds @var{n} inferiors to be run using @var{executable} as the
2437executable. @var{n} defaults to 1. If no executable is specified,
2438the inferiors begins empty, with no program. You can still assign or
2439change the program assigned to the inferior at any time by using the
2440@code{file} command with the executable name as its argument.
2441
2442@kindex clone-inferior
2443@item clone-inferior [ -copies @var{n} ] [ @var{infno} ]
2444Adds @var{n} inferiors ready to execute the same program as inferior
2445@var{infno}. @var{n} defaults to 1. @var{infno} defaults to the
2446number of the current inferior. This is a convenient command when you
2447want to run another instance of the inferior you are debugging.
2448
2449@smallexample
2450(@value{GDBP}) info inferiors
2451 Num Description Executable
2452* 1 process 29964 helloworld
2453(@value{GDBP}) clone-inferior
2454Added inferior 2.
24551 inferiors added.
2456(@value{GDBP}) info inferiors
2457 Num Description Executable
2458 2 <null> helloworld
2459* 1 process 29964 helloworld
2460@end smallexample
2461
2462You can now simply switch focus to inferior 2 and run it.
2463
2464@kindex remove-inferior
2465@item remove-inferior @var{infno}
2466Removes the inferior @var{infno}. It is not possible to remove an
2467inferior that is running with this command. For those, use the
2468@code{kill} or @code{detach} command first.
2469
2470@end table
2471
2472To quit debugging one of the running inferiors that is not the current
2473inferior, you can either detach from it by using the @w{@code{detach
2474inferior}} command (allowing it to run independently), or kill it
2475using the @w{@code{kill inferior}} command:
2277426b
PA
2476
2477@table @code
3a1ff0b6
PA
2478@kindex detach inferior @var{infno}
2479@item detach inferior @var{infno}
2277426b 2480Detach from the inferior identified by @value{GDBN} inferior number
3a1ff0b6 2481@var{infno}, and remove it from the inferior list.
2277426b 2482
3a1ff0b6
PA
2483@kindex kill inferior @var{infno}
2484@item kill inferior @var{infno}
2277426b 2485Kill the inferior identified by @value{GDBN} inferior number
3a1ff0b6 2486@var{infno}, and remove it from the inferior list.
2277426b
PA
2487@end table
2488
6c95b8df
PA
2489After the successful completion of a command such as @code{detach},
2490@code{detach inferior}, @code{kill} or @code{kill inferior}, or after
2491a normal process exit, the inferior is still valid and listed with
2492@code{info inferiors}, ready to be restarted.
2493
2494
2277426b
PA
2495To be notified when inferiors are started or exit under @value{GDBN}'s
2496control use @w{@code{set print inferior-events}}:
b77209e0 2497
2277426b 2498@table @code
b77209e0
PA
2499@kindex set print inferior-events
2500@cindex print messages on inferior start and exit
2501@item set print inferior-events
2502@itemx set print inferior-events on
2503@itemx set print inferior-events off
2504The @code{set print inferior-events} command allows you to enable or
2505disable printing of messages when @value{GDBN} notices that new
2506inferiors have started or that inferiors have exited or have been
2507detached. By default, these messages will not be printed.
2508
2509@kindex show print inferior-events
2510@item show print inferior-events
2511Show whether messages will be printed when @value{GDBN} detects that
2512inferiors have started, exited or have been detached.
2513@end table
2514
6c95b8df
PA
2515Many commands will work the same with multiple programs as with a
2516single program: e.g., @code{print myglobal} will simply display the
2517value of @code{myglobal} in the current inferior.
2518
2519
2520Occasionaly, when debugging @value{GDBN} itself, it may be useful to
2521get more info about the relationship of inferiors, programs, address
2522spaces in a debug session. You can do that with the @w{@code{maint
2523info program-spaces}} command.
2524
2525@table @code
2526@kindex maint info program-spaces
2527@item maint info program-spaces
2528Print a list of all program spaces currently being managed by
2529@value{GDBN}.
2530
2531@value{GDBN} displays for each program space (in this order):
2532
2533@enumerate
2534@item
2535the program space number assigned by @value{GDBN}
2536
2537@item
2538the name of the executable loaded into the program space, with e.g.,
2539the @code{file} command.
2540
2541@end enumerate
2542
2543@noindent
2544An asterisk @samp{*} preceding the @value{GDBN} program space number
2545indicates the current program space.
2546
2547In addition, below each program space line, @value{GDBN} prints extra
2548information that isn't suitable to display in tabular form. For
2549example, the list of inferiors bound to the program space.
2550
2551@smallexample
2552(@value{GDBP}) maint info program-spaces
2553 Id Executable
2554 2 goodbye
2555 Bound inferiors: ID 1 (process 21561)
2556* 1 hello
2557@end smallexample
2558
2559Here we can see that no inferior is running the program @code{hello},
2560while @code{process 21561} is running the program @code{goodbye}. On
2561some targets, it is possible that multiple inferiors are bound to the
2562same program space. The most common example is that of debugging both
2563the parent and child processes of a @code{vfork} call. For example,
2564
2565@smallexample
2566(@value{GDBP}) maint info program-spaces
2567 Id Executable
2568* 1 vfork-test
2569 Bound inferiors: ID 2 (process 18050), ID 1 (process 18045)
2570@end smallexample
2571
2572Here, both inferior 2 and inferior 1 are running in the same program
2573space as a result of inferior 1 having executed a @code{vfork} call.
2574@end table
2575
6d2ebf8b 2576@node Threads
79a6e687 2577@section Debugging Programs with Multiple Threads
c906108c
SS
2578
2579@cindex threads of execution
2580@cindex multiple threads
2581@cindex switching threads
2582In some operating systems, such as HP-UX and Solaris, a single program
2583may have more than one @dfn{thread} of execution. The precise semantics
2584of threads differ from one operating system to another, but in general
2585the threads of a single program are akin to multiple processes---except
2586that they share one address space (that is, they can all examine and
2587modify the same variables). On the other hand, each thread has its own
2588registers and execution stack, and perhaps private memory.
2589
2590@value{GDBN} provides these facilities for debugging multi-thread
2591programs:
2592
2593@itemize @bullet
2594@item automatic notification of new threads
2595@item @samp{thread @var{threadno}}, a command to switch among threads
2596@item @samp{info threads}, a command to inquire about existing threads
5d161b24 2597@item @samp{thread apply [@var{threadno}] [@var{all}] @var{args}},
c906108c
SS
2598a command to apply a command to a list of threads
2599@item thread-specific breakpoints
93815fbf
VP
2600@item @samp{set print thread-events}, which controls printing of
2601messages on thread start and exit.
17a37d48
PP
2602@item @samp{set libthread-db-search-path @var{path}}, which lets
2603the user specify which @code{libthread_db} to use if the default choice
2604isn't compatible with the program.
c906108c
SS
2605@end itemize
2606
c906108c
SS
2607@quotation
2608@emph{Warning:} These facilities are not yet available on every
2609@value{GDBN} configuration where the operating system supports threads.
2610If your @value{GDBN} does not support threads, these commands have no
2611effect. For example, a system without thread support shows no output
2612from @samp{info threads}, and always rejects the @code{thread} command,
2613like this:
2614
2615@smallexample
2616(@value{GDBP}) info threads
2617(@value{GDBP}) thread 1
2618Thread ID 1 not known. Use the "info threads" command to
2619see the IDs of currently known threads.
2620@end smallexample
2621@c FIXME to implementors: how hard would it be to say "sorry, this GDB
2622@c doesn't support threads"?
2623@end quotation
c906108c
SS
2624
2625@cindex focus of debugging
2626@cindex current thread
2627The @value{GDBN} thread debugging facility allows you to observe all
2628threads while your program runs---but whenever @value{GDBN} takes
2629control, one thread in particular is always the focus of debugging.
2630This thread is called the @dfn{current thread}. Debugging commands show
2631program information from the perspective of the current thread.
2632
41afff9a 2633@cindex @code{New} @var{systag} message
c906108c
SS
2634@cindex thread identifier (system)
2635@c FIXME-implementors!! It would be more helpful if the [New...] message
2636@c included GDB's numeric thread handle, so you could just go to that
2637@c thread without first checking `info threads'.
2638Whenever @value{GDBN} detects a new thread in your program, it displays
2639the target system's identification for the thread with a message in the
2640form @samp{[New @var{systag}]}. @var{systag} is a thread identifier
2641whose form varies depending on the particular system. For example, on
8807d78b 2642@sc{gnu}/Linux, you might see
c906108c 2643
474c8240 2644@smallexample
8807d78b 2645[New Thread 46912507313328 (LWP 25582)]
474c8240 2646@end smallexample
c906108c
SS
2647
2648@noindent
2649when @value{GDBN} notices a new thread. In contrast, on an SGI system,
2650the @var{systag} is simply something like @samp{process 368}, with no
2651further qualifier.
2652
2653@c FIXME!! (1) Does the [New...] message appear even for the very first
2654@c thread of a program, or does it only appear for the
6ca652b0 2655@c second---i.e.@: when it becomes obvious we have a multithread
c906108c
SS
2656@c program?
2657@c (2) *Is* there necessarily a first thread always? Or do some
2658@c multithread systems permit starting a program with multiple
5d161b24 2659@c threads ab initio?
c906108c
SS
2660
2661@cindex thread number
2662@cindex thread identifier (GDB)
2663For debugging purposes, @value{GDBN} associates its own thread
2664number---always a single integer---with each thread in your program.
2665
2666@table @code
2667@kindex info threads
2668@item info threads
2669Display a summary of all threads currently in your
2670program. @value{GDBN} displays for each thread (in this order):
2671
2672@enumerate
09d4efe1
EZ
2673@item
2674the thread number assigned by @value{GDBN}
c906108c 2675
09d4efe1
EZ
2676@item
2677the target system's thread identifier (@var{systag})
c906108c 2678
09d4efe1
EZ
2679@item
2680the current stack frame summary for that thread
c906108c
SS
2681@end enumerate
2682
2683@noindent
2684An asterisk @samp{*} to the left of the @value{GDBN} thread number
2685indicates the current thread.
2686
5d161b24 2687For example,
c906108c
SS
2688@end table
2689@c end table here to get a little more width for example
2690
2691@smallexample
2692(@value{GDBP}) info threads
2693 3 process 35 thread 27 0x34e5 in sigpause ()
2694 2 process 35 thread 23 0x34e5 in sigpause ()
2695* 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8)
2696 at threadtest.c:68
2697@end smallexample
53a5351d
JM
2698
2699On HP-UX systems:
c906108c 2700
4644b6e3
EZ
2701@cindex debugging multithreaded programs (on HP-UX)
2702@cindex thread identifier (GDB), on HP-UX
c906108c
SS
2703For debugging purposes, @value{GDBN} associates its own thread
2704number---a small integer assigned in thread-creation order---with each
2705thread in your program.
2706
41afff9a
EZ
2707@cindex @code{New} @var{systag} message, on HP-UX
2708@cindex thread identifier (system), on HP-UX
c906108c
SS
2709@c FIXME-implementors!! It would be more helpful if the [New...] message
2710@c included GDB's numeric thread handle, so you could just go to that
2711@c thread without first checking `info threads'.
2712Whenever @value{GDBN} detects a new thread in your program, it displays
2713both @value{GDBN}'s thread number and the target system's identification for the thread with a message in the
2714form @samp{[New @var{systag}]}. @var{systag} is a thread identifier
2715whose form varies depending on the particular system. For example, on
2716HP-UX, you see
2717
474c8240 2718@smallexample
c906108c 2719[New thread 2 (system thread 26594)]
474c8240 2720@end smallexample
c906108c
SS
2721
2722@noindent
5d161b24 2723when @value{GDBN} notices a new thread.
c906108c
SS
2724
2725@table @code
4644b6e3 2726@kindex info threads (HP-UX)
c906108c
SS
2727@item info threads
2728Display a summary of all threads currently in your
2729program. @value{GDBN} displays for each thread (in this order):
2730
2731@enumerate
2732@item the thread number assigned by @value{GDBN}
2733
2734@item the target system's thread identifier (@var{systag})
2735
2736@item the current stack frame summary for that thread
2737@end enumerate
2738
2739@noindent
2740An asterisk @samp{*} to the left of the @value{GDBN} thread number
2741indicates the current thread.
2742
5d161b24 2743For example,
c906108c
SS
2744@end table
2745@c end table here to get a little more width for example
2746
474c8240 2747@smallexample
c906108c 2748(@value{GDBP}) info threads
6d2ebf8b
SS
2749 * 3 system thread 26607 worker (wptr=0x7b09c318 "@@") \@*
2750 at quicksort.c:137
2751 2 system thread 26606 0x7b0030d8 in __ksleep () \@*
2752 from /usr/lib/libc.2
2753 1 system thread 27905 0x7b003498 in _brk () \@*
2754 from /usr/lib/libc.2
474c8240 2755@end smallexample
c906108c 2756
c45da7e6
EZ
2757On Solaris, you can display more information about user threads with a
2758Solaris-specific command:
2759
2760@table @code
2761@item maint info sol-threads
2762@kindex maint info sol-threads
2763@cindex thread info (Solaris)
2764Display info on Solaris user threads.
2765@end table
2766
c906108c
SS
2767@table @code
2768@kindex thread @var{threadno}
2769@item thread @var{threadno}
2770Make thread number @var{threadno} the current thread. The command
2771argument @var{threadno} is the internal @value{GDBN} thread number, as
2772shown in the first field of the @samp{info threads} display.
2773@value{GDBN} responds by displaying the system identifier of the thread
2774you selected, and its current stack frame summary:
2775
2776@smallexample
2777@c FIXME!! This example made up; find a @value{GDBN} w/threads and get real one
2778(@value{GDBP}) thread 2
c906108c 2779[Switching to process 35 thread 23]
c906108c
SS
27800x34e5 in sigpause ()
2781@end smallexample
2782
2783@noindent
2784As with the @samp{[New @dots{}]} message, the form of the text after
2785@samp{Switching to} depends on your system's conventions for identifying
5d161b24 2786threads.
c906108c 2787
9c16f35a 2788@kindex thread apply
638ac427 2789@cindex apply command to several threads
839c27b7
EZ
2790@item thread apply [@var{threadno}] [@var{all}] @var{command}
2791The @code{thread apply} command allows you to apply the named
2792@var{command} to one or more threads. Specify the numbers of the
2793threads that you want affected with the command argument
2794@var{threadno}. It can be a single thread number, one of the numbers
2795shown in the first field of the @samp{info threads} display; or it
2796could be a range of thread numbers, as in @code{2-4}. To apply a
2797command to all threads, type @kbd{thread apply all @var{command}}.
93815fbf
VP
2798
2799@kindex set print thread-events
2800@cindex print messages on thread start and exit
2801@item set print thread-events
2802@itemx set print thread-events on
2803@itemx set print thread-events off
2804The @code{set print thread-events} command allows you to enable or
2805disable printing of messages when @value{GDBN} notices that new threads have
2806started or that threads have exited. By default, these messages will
2807be printed if detection of these events is supported by the target.
2808Note that these messages cannot be disabled on all targets.
2809
2810@kindex show print thread-events
2811@item show print thread-events
2812Show whether messages will be printed when @value{GDBN} detects that threads
2813have started and exited.
c906108c
SS
2814@end table
2815
79a6e687 2816@xref{Thread Stops,,Stopping and Starting Multi-thread Programs}, for
c906108c
SS
2817more information about how @value{GDBN} behaves when you stop and start
2818programs with multiple threads.
2819
79a6e687 2820@xref{Set Watchpoints,,Setting Watchpoints}, for information about
c906108c 2821watchpoints in programs with multiple threads.
c906108c 2822
17a37d48
PP
2823@table @code
2824@kindex set libthread-db-search-path
2825@cindex search path for @code{libthread_db}
2826@item set libthread-db-search-path @r{[}@var{path}@r{]}
2827If this variable is set, @var{path} is a colon-separated list of
2828directories @value{GDBN} will use to search for @code{libthread_db}.
2829If you omit @var{path}, @samp{libthread-db-search-path} will be reset to
2830an empty list.
2831
2832On @sc{gnu}/Linux and Solaris systems, @value{GDBN} uses a ``helper''
2833@code{libthread_db} library to obtain information about threads in the
2834inferior process. @value{GDBN} will use @samp{libthread-db-search-path}
2835to find @code{libthread_db}. If that fails, @value{GDBN} will continue
2836with default system shared library directories, and finally the directory
2837from which @code{libpthread} was loaded in the inferior process.
2838
2839For any @code{libthread_db} library @value{GDBN} finds in above directories,
2840@value{GDBN} attempts to initialize it with the current inferior process.
2841If this initialization fails (which could happen because of a version
2842mismatch between @code{libthread_db} and @code{libpthread}), @value{GDBN}
2843will unload @code{libthread_db}, and continue with the next directory.
2844If none of @code{libthread_db} libraries initialize successfully,
2845@value{GDBN} will issue a warning and thread debugging will be disabled.
2846
2847Setting @code{libthread-db-search-path} is currently implemented
2848only on some platforms.
2849
2850@kindex show libthread-db-search-path
2851@item show libthread-db-search-path
2852Display current libthread_db search path.
2853@end table
2854
6c95b8df
PA
2855@node Forks
2856@section Debugging Forks
c906108c
SS
2857
2858@cindex fork, debugging programs which call
2859@cindex multiple processes
2860@cindex processes, multiple
53a5351d
JM
2861On most systems, @value{GDBN} has no special support for debugging
2862programs which create additional processes using the @code{fork}
2863function. When a program forks, @value{GDBN} will continue to debug the
2864parent process and the child process will run unimpeded. If you have
2865set a breakpoint in any code which the child then executes, the child
2866will get a @code{SIGTRAP} signal which (unless it catches the signal)
2867will cause it to terminate.
c906108c
SS
2868
2869However, if you want to debug the child process there is a workaround
2870which isn't too painful. Put a call to @code{sleep} in the code which
2871the child process executes after the fork. It may be useful to sleep
2872only if a certain environment variable is set, or a certain file exists,
2873so that the delay need not occur when you don't want to run @value{GDBN}
2874on the child. While the child is sleeping, use the @code{ps} program to
2875get its process ID. Then tell @value{GDBN} (a new invocation of
2876@value{GDBN} if you are also debugging the parent process) to attach to
d4f3574e 2877the child process (@pxref{Attach}). From that point on you can debug
c906108c 2878the child process just like any other process which you attached to.
c906108c 2879
b51970ac
DJ
2880On some systems, @value{GDBN} provides support for debugging programs that
2881create additional processes using the @code{fork} or @code{vfork} functions.
2882Currently, the only platforms with this feature are HP-UX (11.x and later
a6b151f1 2883only?) and @sc{gnu}/Linux (kernel version 2.5.60 and later).
c906108c
SS
2884
2885By default, when a program forks, @value{GDBN} will continue to debug
2886the parent process and the child process will run unimpeded.
2887
2888If you want to follow the child process instead of the parent process,
2889use the command @w{@code{set follow-fork-mode}}.
2890
2891@table @code
2892@kindex set follow-fork-mode
2893@item set follow-fork-mode @var{mode}
2894Set the debugger response to a program call of @code{fork} or
2895@code{vfork}. A call to @code{fork} or @code{vfork} creates a new
9c16f35a 2896process. The @var{mode} argument can be:
c906108c
SS
2897
2898@table @code
2899@item parent
2900The original process is debugged after a fork. The child process runs
2df3850c 2901unimpeded. This is the default.
c906108c
SS
2902
2903@item child
2904The new process is debugged after a fork. The parent process runs
2905unimpeded.
2906
c906108c
SS
2907@end table
2908
9c16f35a 2909@kindex show follow-fork-mode
c906108c 2910@item show follow-fork-mode
2df3850c 2911Display the current debugger response to a @code{fork} or @code{vfork} call.
c906108c
SS
2912@end table
2913
5c95884b
MS
2914@cindex debugging multiple processes
2915On Linux, if you want to debug both the parent and child processes, use the
2916command @w{@code{set detach-on-fork}}.
2917
2918@table @code
2919@kindex set detach-on-fork
2920@item set detach-on-fork @var{mode}
2921Tells gdb whether to detach one of the processes after a fork, or
2922retain debugger control over them both.
2923
2924@table @code
2925@item on
2926The child process (or parent process, depending on the value of
2927@code{follow-fork-mode}) will be detached and allowed to run
2928independently. This is the default.
2929
2930@item off
2931Both processes will be held under the control of @value{GDBN}.
2932One process (child or parent, depending on the value of
2933@code{follow-fork-mode}) is debugged as usual, while the other
2934is held suspended.
2935
2936@end table
2937
11310833
NR
2938@kindex show detach-on-fork
2939@item show detach-on-fork
2940Show whether detach-on-fork mode is on/off.
5c95884b
MS
2941@end table
2942
2277426b
PA
2943If you choose to set @samp{detach-on-fork} mode off, then @value{GDBN}
2944will retain control of all forked processes (including nested forks).
2945You can list the forked processes under the control of @value{GDBN} by
2946using the @w{@code{info inferiors}} command, and switch from one fork
6c95b8df
PA
2947to another by using the @code{inferior} command (@pxref{Inferiors and
2948Programs, ,Debugging Multiple Inferiors and Programs}).
5c95884b
MS
2949
2950To quit debugging one of the forked processes, you can either detach
2277426b
PA
2951from it by using the @w{@code{detach inferior}} command (allowing it
2952to run independently), or kill it using the @w{@code{kill inferior}}
6c95b8df
PA
2953command. @xref{Inferiors and Programs, ,Debugging Multiple Inferiors
2954and Programs}.
5c95884b 2955
c906108c
SS
2956If you ask to debug a child process and a @code{vfork} is followed by an
2957@code{exec}, @value{GDBN} executes the new target up to the first
2958breakpoint in the new target. If you have a breakpoint set on
2959@code{main} in your original program, the breakpoint will also be set on
2960the child process's @code{main}.
2961
2277426b
PA
2962On some systems, when a child process is spawned by @code{vfork}, you
2963cannot debug the child or parent until an @code{exec} call completes.
c906108c
SS
2964
2965If you issue a @code{run} command to @value{GDBN} after an @code{exec}
6c95b8df
PA
2966call executes, the new target restarts. To restart the parent
2967process, use the @code{file} command with the parent executable name
2968as its argument. By default, after an @code{exec} call executes,
2969@value{GDBN} discards the symbols of the previous executable image.
2970You can change this behaviour with the @w{@code{set follow-exec-mode}}
2971command.
2972
2973@table @code
2974@kindex set follow-exec-mode
2975@item set follow-exec-mode @var{mode}
2976
2977Set debugger response to a program call of @code{exec}. An
2978@code{exec} call replaces the program image of a process.
2979
2980@code{follow-exec-mode} can be:
2981
2982@table @code
2983@item new
2984@value{GDBN} creates a new inferior and rebinds the process to this
2985new inferior. The program the process was running before the
2986@code{exec} call can be restarted afterwards by restarting the
2987original inferior.
2988
2989For example:
2990
2991@smallexample
2992(@value{GDBP}) info inferiors
2993(gdb) info inferior
2994 Id Description Executable
2995* 1 <null> prog1
2996(@value{GDBP}) run
2997process 12020 is executing new program: prog2
2998Program exited normally.
2999(@value{GDBP}) info inferiors
3000 Id Description Executable
3001* 2 <null> prog2
3002 1 <null> prog1
3003@end smallexample
3004
3005@item same
3006@value{GDBN} keeps the process bound to the same inferior. The new
3007executable image replaces the previous executable loaded in the
3008inferior. Restarting the inferior after the @code{exec} call, with
3009e.g., the @code{run} command, restarts the executable the process was
3010running after the @code{exec} call. This is the default mode.
3011
3012For example:
3013
3014@smallexample
3015(@value{GDBP}) info inferiors
3016 Id Description Executable
3017* 1 <null> prog1
3018(@value{GDBP}) run
3019process 12020 is executing new program: prog2
3020Program exited normally.
3021(@value{GDBP}) info inferiors
3022 Id Description Executable
3023* 1 <null> prog2
3024@end smallexample
3025
3026@end table
3027@end table
c906108c
SS
3028
3029You can use the @code{catch} command to make @value{GDBN} stop whenever
3030a @code{fork}, @code{vfork}, or @code{exec} call is made. @xref{Set
79a6e687 3031Catchpoints, ,Setting Catchpoints}.
c906108c 3032
5c95884b 3033@node Checkpoint/Restart
79a6e687 3034@section Setting a @emph{Bookmark} to Return to Later
5c95884b
MS
3035
3036@cindex checkpoint
3037@cindex restart
3038@cindex bookmark
3039@cindex snapshot of a process
3040@cindex rewind program state
3041
3042On certain operating systems@footnote{Currently, only
3043@sc{gnu}/Linux.}, @value{GDBN} is able to save a @dfn{snapshot} of a
3044program's state, called a @dfn{checkpoint}, and come back to it
3045later.
3046
3047Returning to a checkpoint effectively undoes everything that has
3048happened in the program since the @code{checkpoint} was saved. This
3049includes changes in memory, registers, and even (within some limits)
3050system state. Effectively, it is like going back in time to the
3051moment when the checkpoint was saved.
3052
3053Thus, if you're stepping thru a program and you think you're
3054getting close to the point where things go wrong, you can save
3055a checkpoint. Then, if you accidentally go too far and miss
3056the critical statement, instead of having to restart your program
3057from the beginning, you can just go back to the checkpoint and
3058start again from there.
3059
3060This can be especially useful if it takes a lot of time or
3061steps to reach the point where you think the bug occurs.
3062
3063To use the @code{checkpoint}/@code{restart} method of debugging:
3064
3065@table @code
3066@kindex checkpoint
3067@item checkpoint
3068Save a snapshot of the debugged program's current execution state.
3069The @code{checkpoint} command takes no arguments, but each checkpoint
3070is assigned a small integer id, similar to a breakpoint id.
3071
3072@kindex info checkpoints
3073@item info checkpoints
3074List the checkpoints that have been saved in the current debugging
3075session. For each checkpoint, the following information will be
3076listed:
3077
3078@table @code
3079@item Checkpoint ID
3080@item Process ID
3081@item Code Address
3082@item Source line, or label
3083@end table
3084
3085@kindex restart @var{checkpoint-id}
3086@item restart @var{checkpoint-id}
3087Restore the program state that was saved as checkpoint number
3088@var{checkpoint-id}. All program variables, registers, stack frames
3089etc.@: will be returned to the values that they had when the checkpoint
3090was saved. In essence, gdb will ``wind back the clock'' to the point
3091in time when the checkpoint was saved.
3092
3093Note that breakpoints, @value{GDBN} variables, command history etc.
3094are not affected by restoring a checkpoint. In general, a checkpoint
3095only restores things that reside in the program being debugged, not in
3096the debugger.
3097
b8db102d
MS
3098@kindex delete checkpoint @var{checkpoint-id}
3099@item delete checkpoint @var{checkpoint-id}
5c95884b
MS
3100Delete the previously-saved checkpoint identified by @var{checkpoint-id}.
3101
3102@end table
3103
3104Returning to a previously saved checkpoint will restore the user state
3105of the program being debugged, plus a significant subset of the system
3106(OS) state, including file pointers. It won't ``un-write'' data from
3107a file, but it will rewind the file pointer to the previous location,
3108so that the previously written data can be overwritten. For files
3109opened in read mode, the pointer will also be restored so that the
3110previously read data can be read again.
3111
3112Of course, characters that have been sent to a printer (or other
3113external device) cannot be ``snatched back'', and characters received
3114from eg.@: a serial device can be removed from internal program buffers,
3115but they cannot be ``pushed back'' into the serial pipeline, ready to
3116be received again. Similarly, the actual contents of files that have
3117been changed cannot be restored (at this time).
3118
3119However, within those constraints, you actually can ``rewind'' your
3120program to a previously saved point in time, and begin debugging it
3121again --- and you can change the course of events so as to debug a
3122different execution path this time.
3123
3124@cindex checkpoints and process id
3125Finally, there is one bit of internal program state that will be
3126different when you return to a checkpoint --- the program's process
3127id. Each checkpoint will have a unique process id (or @var{pid}),
3128and each will be different from the program's original @var{pid}.
3129If your program has saved a local copy of its process id, this could
3130potentially pose a problem.
3131
79a6e687 3132@subsection A Non-obvious Benefit of Using Checkpoints
5c95884b
MS
3133
3134On some systems such as @sc{gnu}/Linux, address space randomization
3135is performed on new processes for security reasons. This makes it
3136difficult or impossible to set a breakpoint, or watchpoint, on an
3137absolute address if you have to restart the program, since the
3138absolute location of a symbol will change from one execution to the
3139next.
3140
3141A checkpoint, however, is an @emph{identical} copy of a process.
3142Therefore if you create a checkpoint at (eg.@:) the start of main,
3143and simply return to that checkpoint instead of restarting the
3144process, you can avoid the effects of address randomization and
3145your symbols will all stay in the same place.
3146
6d2ebf8b 3147@node Stopping
c906108c
SS
3148@chapter Stopping and Continuing
3149
3150The principal purposes of using a debugger are so that you can stop your
3151program before it terminates; or so that, if your program runs into
3152trouble, you can investigate and find out why.
3153
7a292a7a
SS
3154Inside @value{GDBN}, your program may stop for any of several reasons,
3155such as a signal, a breakpoint, or reaching a new line after a
3156@value{GDBN} command such as @code{step}. You may then examine and
3157change variables, set new breakpoints or remove old ones, and then
3158continue execution. Usually, the messages shown by @value{GDBN} provide
3159ample explanation of the status of your program---but you can also
3160explicitly request this information at any time.
c906108c
SS
3161
3162@table @code
3163@kindex info program
3164@item info program
3165Display information about the status of your program: whether it is
7a292a7a 3166running or not, what process it is, and why it stopped.
c906108c
SS
3167@end table
3168
3169@menu
3170* Breakpoints:: Breakpoints, watchpoints, and catchpoints
3171* Continuing and Stepping:: Resuming execution
c906108c 3172* Signals:: Signals
c906108c 3173* Thread Stops:: Stopping and starting multi-thread programs
c906108c
SS
3174@end menu
3175
6d2ebf8b 3176@node Breakpoints
79a6e687 3177@section Breakpoints, Watchpoints, and Catchpoints
c906108c
SS
3178
3179@cindex breakpoints
3180A @dfn{breakpoint} makes your program stop whenever a certain point in
3181the program is reached. For each breakpoint, you can add conditions to
3182control in finer detail whether your program stops. You can set
3183breakpoints with the @code{break} command and its variants (@pxref{Set
79a6e687 3184Breaks, ,Setting Breakpoints}), to specify the place where your program
c906108c
SS
3185should stop by line number, function name or exact address in the
3186program.
3187
09d4efe1
EZ
3188On some systems, you can set breakpoints in shared libraries before
3189the executable is run. There is a minor limitation on HP-UX systems:
3190you must wait until the executable is run in order to set breakpoints
3191in shared library routines that are not called directly by the program
3192(for example, routines that are arguments in a @code{pthread_create}
3193call).
c906108c
SS
3194
3195@cindex watchpoints
fd60e0df 3196@cindex data breakpoints
c906108c
SS
3197@cindex memory tracing
3198@cindex breakpoint on memory address
3199@cindex breakpoint on variable modification
3200A @dfn{watchpoint} is a special breakpoint that stops your program
fd60e0df 3201when the value of an expression changes. The expression may be a value
0ced0c34 3202of a variable, or it could involve values of one or more variables
fd60e0df
EZ
3203combined by operators, such as @samp{a + b}. This is sometimes called
3204@dfn{data breakpoints}. You must use a different command to set
79a6e687 3205watchpoints (@pxref{Set Watchpoints, ,Setting Watchpoints}), but aside
fd60e0df
EZ
3206from that, you can manage a watchpoint like any other breakpoint: you
3207enable, disable, and delete both breakpoints and watchpoints using the
3208same commands.
c906108c
SS
3209
3210You can arrange to have values from your program displayed automatically
3211whenever @value{GDBN} stops at a breakpoint. @xref{Auto Display,,
79a6e687 3212Automatic Display}.
c906108c
SS
3213
3214@cindex catchpoints
3215@cindex breakpoint on events
3216A @dfn{catchpoint} is another special breakpoint that stops your program
b37052ae 3217when a certain kind of event occurs, such as the throwing of a C@t{++}
c906108c
SS
3218exception or the loading of a library. As with watchpoints, you use a
3219different command to set a catchpoint (@pxref{Set Catchpoints, ,Setting
79a6e687 3220Catchpoints}), but aside from that, you can manage a catchpoint like any
c906108c 3221other breakpoint. (To stop when your program receives a signal, use the
d4f3574e 3222@code{handle} command; see @ref{Signals, ,Signals}.)
c906108c
SS
3223
3224@cindex breakpoint numbers
3225@cindex numbers for breakpoints
3226@value{GDBN} assigns a number to each breakpoint, watchpoint, or
3227catchpoint when you create it; these numbers are successive integers
3228starting with one. In many of the commands for controlling various
3229features of breakpoints you use the breakpoint number to say which
3230breakpoint you want to change. Each breakpoint may be @dfn{enabled} or
3231@dfn{disabled}; if disabled, it has no effect on your program until you
3232enable it again.
3233
c5394b80
JM
3234@cindex breakpoint ranges
3235@cindex ranges of breakpoints
3236Some @value{GDBN} commands accept a range of breakpoints on which to
3237operate. A breakpoint range is either a single breakpoint number, like
3238@samp{5}, or two such numbers, in increasing order, separated by a
3239hyphen, like @samp{5-7}. When a breakpoint range is given to a command,
d52fb0e9 3240all breakpoints in that range are operated on.
c5394b80 3241
c906108c
SS
3242@menu
3243* Set Breaks:: Setting breakpoints
3244* Set Watchpoints:: Setting watchpoints
3245* Set Catchpoints:: Setting catchpoints
3246* Delete Breaks:: Deleting breakpoints
3247* Disabling:: Disabling breakpoints
3248* Conditions:: Break conditions
3249* Break Commands:: Breakpoint command lists
d4f3574e 3250* Error in Breakpoints:: ``Cannot insert breakpoints''
79a6e687 3251* Breakpoint-related Warnings:: ``Breakpoint address adjusted...''
c906108c
SS
3252@end menu
3253
6d2ebf8b 3254@node Set Breaks
79a6e687 3255@subsection Setting Breakpoints
c906108c 3256
5d161b24 3257@c FIXME LMB what does GDB do if no code on line of breakpt?
c906108c
SS
3258@c consider in particular declaration with/without initialization.
3259@c
3260@c FIXME 2 is there stuff on this already? break at fun start, already init?
3261
3262@kindex break
41afff9a
EZ
3263@kindex b @r{(@code{break})}
3264@vindex $bpnum@r{, convenience variable}
c906108c
SS
3265@cindex latest breakpoint
3266Breakpoints are set with the @code{break} command (abbreviated
5d161b24 3267@code{b}). The debugger convenience variable @samp{$bpnum} records the
f3b28801 3268number of the breakpoint you've set most recently; see @ref{Convenience
79a6e687 3269Vars,, Convenience Variables}, for a discussion of what you can do with
c906108c
SS
3270convenience variables.
3271
c906108c 3272@table @code
2a25a5ba
EZ
3273@item break @var{location}
3274Set a breakpoint at the given @var{location}, which can specify a
3275function name, a line number, or an address of an instruction.
3276(@xref{Specify Location}, for a list of all the possible ways to
3277specify a @var{location}.) The breakpoint will stop your program just
3278before it executes any of the code in the specified @var{location}.
3279
c906108c 3280When using source languages that permit overloading of symbols, such as
2a25a5ba 3281C@t{++}, a function name may refer to more than one possible place to break.
6ba66d6a
JB
3282@xref{Ambiguous Expressions,,Ambiguous Expressions}, for a discussion of
3283that situation.
c906108c 3284
45ac276d 3285It is also possible to insert a breakpoint that will stop the program
2c88c651
JB
3286only if a specific thread (@pxref{Thread-Specific Breakpoints})
3287or a specific task (@pxref{Ada Tasks}) hits that breakpoint.
45ac276d 3288
c906108c
SS
3289@item break
3290When called without any arguments, @code{break} sets a breakpoint at
3291the next instruction to be executed in the selected stack frame
3292(@pxref{Stack, ,Examining the Stack}). In any selected frame but the
3293innermost, this makes your program stop as soon as control
3294returns to that frame. This is similar to the effect of a
3295@code{finish} command in the frame inside the selected frame---except
3296that @code{finish} does not leave an active breakpoint. If you use
3297@code{break} without an argument in the innermost frame, @value{GDBN} stops
3298the next time it reaches the current location; this may be useful
3299inside loops.
3300
3301@value{GDBN} normally ignores breakpoints when it resumes execution, until at
3302least one instruction has been executed. If it did not do this, you
3303would be unable to proceed past a breakpoint without first disabling the
3304breakpoint. This rule applies whether or not the breakpoint already
3305existed when your program stopped.
3306
3307@item break @dots{} if @var{cond}
3308Set a breakpoint with condition @var{cond}; evaluate the expression
3309@var{cond} each time the breakpoint is reached, and stop only if the
3310value is nonzero---that is, if @var{cond} evaluates as true.
3311@samp{@dots{}} stands for one of the possible arguments described
3312above (or no argument) specifying where to break. @xref{Conditions,
79a6e687 3313,Break Conditions}, for more information on breakpoint conditions.
c906108c
SS
3314
3315@kindex tbreak
3316@item tbreak @var{args}
3317Set a breakpoint enabled only for one stop. @var{args} are the
3318same as for the @code{break} command, and the breakpoint is set in the same
3319way, but the breakpoint is automatically deleted after the first time your
79a6e687 3320program stops there. @xref{Disabling, ,Disabling Breakpoints}.
c906108c 3321
c906108c 3322@kindex hbreak
ba04e063 3323@cindex hardware breakpoints
c906108c 3324@item hbreak @var{args}
d4f3574e
SS
3325Set a hardware-assisted breakpoint. @var{args} are the same as for the
3326@code{break} command and the breakpoint is set in the same way, but the
c906108c
SS
3327breakpoint requires hardware support and some target hardware may not
3328have this support. The main purpose of this is EPROM/ROM code
d4f3574e
SS
3329debugging, so you can set a breakpoint at an instruction without
3330changing the instruction. This can be used with the new trap-generation
09d4efe1 3331provided by SPARClite DSU and most x86-based targets. These targets
d4f3574e
SS
3332will generate traps when a program accesses some data or instruction
3333address that is assigned to the debug registers. However the hardware
3334breakpoint registers can take a limited number of breakpoints. For
3335example, on the DSU, only two data breakpoints can be set at a time, and
3336@value{GDBN} will reject this command if more than two are used. Delete
3337or disable unused hardware breakpoints before setting new ones
79a6e687
BW
3338(@pxref{Disabling, ,Disabling Breakpoints}).
3339@xref{Conditions, ,Break Conditions}.
9c16f35a
EZ
3340For remote targets, you can restrict the number of hardware
3341breakpoints @value{GDBN} will use, see @ref{set remote
3342hardware-breakpoint-limit}.
501eef12 3343
c906108c
SS
3344@kindex thbreak
3345@item thbreak @var{args}
3346Set a hardware-assisted breakpoint enabled only for one stop. @var{args}
3347are the same as for the @code{hbreak} command and the breakpoint is set in
5d161b24 3348the same way. However, like the @code{tbreak} command,
c906108c
SS
3349the breakpoint is automatically deleted after the
3350first time your program stops there. Also, like the @code{hbreak}
5d161b24 3351command, the breakpoint requires hardware support and some target hardware
79a6e687
BW
3352may not have this support. @xref{Disabling, ,Disabling Breakpoints}.
3353See also @ref{Conditions, ,Break Conditions}.
c906108c
SS
3354
3355@kindex rbreak
3356@cindex regular expression
c45da7e6
EZ
3357@cindex breakpoints in functions matching a regexp
3358@cindex set breakpoints in many functions
c906108c 3359@item rbreak @var{regex}
c906108c 3360Set breakpoints on all functions matching the regular expression
11cf8741
JM
3361@var{regex}. This command sets an unconditional breakpoint on all
3362matches, printing a list of all breakpoints it set. Once these
3363breakpoints are set, they are treated just like the breakpoints set with
3364the @code{break} command. You can delete them, disable them, or make
3365them conditional the same way as any other breakpoint.
3366
3367The syntax of the regular expression is the standard one used with tools
3368like @file{grep}. Note that this is different from the syntax used by
3369shells, so for instance @code{foo*} matches all functions that include
3370an @code{fo} followed by zero or more @code{o}s. There is an implicit
3371@code{.*} leading and trailing the regular expression you supply, so to
3372match only functions that begin with @code{foo}, use @code{^foo}.
c906108c 3373
f7dc1244 3374@cindex non-member C@t{++} functions, set breakpoint in
b37052ae 3375When debugging C@t{++} programs, @code{rbreak} is useful for setting
c906108c
SS
3376breakpoints on overloaded functions that are not members of any special
3377classes.
c906108c 3378
f7dc1244
EZ
3379@cindex set breakpoints on all functions
3380The @code{rbreak} command can be used to set breakpoints in
3381@strong{all} the functions in a program, like this:
3382
3383@smallexample
3384(@value{GDBP}) rbreak .
3385@end smallexample
3386
c906108c
SS
3387@kindex info breakpoints
3388@cindex @code{$_} and @code{info breakpoints}
3389@item info breakpoints @r{[}@var{n}@r{]}
3390@itemx info break @r{[}@var{n}@r{]}
c906108c 3391Print a table of all breakpoints, watchpoints, and catchpoints set and
45ac1734
EZ
3392not deleted. Optional argument @var{n} means print information only
3393about the specified breakpoint (or watchpoint or catchpoint). For
3394each breakpoint, following columns are printed:
c906108c
SS
3395
3396@table @emph
3397@item Breakpoint Numbers
3398@item Type
3399Breakpoint, watchpoint, or catchpoint.
3400@item Disposition
3401Whether the breakpoint is marked to be disabled or deleted when hit.
3402@item Enabled or Disabled
3403Enabled breakpoints are marked with @samp{y}. @samp{n} marks breakpoints
b3db7447 3404that are not enabled.
c906108c 3405@item Address
fe6fbf8b 3406Where the breakpoint is in your program, as a memory address. For a
b3db7447
NR
3407pending breakpoint whose address is not yet known, this field will
3408contain @samp{<PENDING>}. Such breakpoint won't fire until a shared
3409library that has the symbol or line referred by breakpoint is loaded.
3410See below for details. A breakpoint with several locations will
3b784c4f 3411have @samp{<MULTIPLE>} in this field---see below for details.
c906108c
SS
3412@item What
3413Where the breakpoint is in the source for your program, as a file and
2650777c
JJ
3414line number. For a pending breakpoint, the original string passed to
3415the breakpoint command will be listed as it cannot be resolved until
3416the appropriate shared library is loaded in the future.
c906108c
SS
3417@end table
3418
3419@noindent
3420If a breakpoint is conditional, @code{info break} shows the condition on
3421the line following the affected breakpoint; breakpoint commands, if any,
2650777c
JJ
3422are listed after that. A pending breakpoint is allowed to have a condition
3423specified for it. The condition is not parsed for validity until a shared
3424library is loaded that allows the pending breakpoint to resolve to a
3425valid location.
c906108c
SS
3426
3427@noindent
3428@code{info break} with a breakpoint
3429number @var{n} as argument lists only that breakpoint. The
3430convenience variable @code{$_} and the default examining-address for
3431the @code{x} command are set to the address of the last breakpoint
79a6e687 3432listed (@pxref{Memory, ,Examining Memory}).
c906108c
SS
3433
3434@noindent
3435@code{info break} displays a count of the number of times the breakpoint
3436has been hit. This is especially useful in conjunction with the
3437@code{ignore} command. You can ignore a large number of breakpoint
3438hits, look at the breakpoint info to see how many times the breakpoint
3439was hit, and then run again, ignoring one less than that number. This
3440will get you quickly to the last hit of that breakpoint.
3441@end table
3442
3443@value{GDBN} allows you to set any number of breakpoints at the same place in
3444your program. There is nothing silly or meaningless about this. When
3445the breakpoints are conditional, this is even useful
79a6e687 3446(@pxref{Conditions, ,Break Conditions}).
c906108c 3447
2e9132cc
EZ
3448@cindex multiple locations, breakpoints
3449@cindex breakpoints, multiple locations
fcda367b 3450It is possible that a breakpoint corresponds to several locations
fe6fbf8b
VP
3451in your program. Examples of this situation are:
3452
3453@itemize @bullet
fe6fbf8b
VP
3454@item
3455For a C@t{++} constructor, the @value{NGCC} compiler generates several
3456instances of the function body, used in different cases.
3457
3458@item
3459For a C@t{++} template function, a given line in the function can
3460correspond to any number of instantiations.
3461
3462@item
3463For an inlined function, a given source line can correspond to
3464several places where that function is inlined.
fe6fbf8b
VP
3465@end itemize
3466
3467In all those cases, @value{GDBN} will insert a breakpoint at all
2e9132cc
EZ
3468the relevant locations@footnote{
3469As of this writing, multiple-location breakpoints work only if there's
3470line number information for all the locations. This means that they
3471will generally not work in system libraries, unless you have debug
3472info with line numbers for them.}.
fe6fbf8b 3473
3b784c4f
EZ
3474A breakpoint with multiple locations is displayed in the breakpoint
3475table using several rows---one header row, followed by one row for
3476each breakpoint location. The header row has @samp{<MULTIPLE>} in the
3477address column. The rows for individual locations contain the actual
3478addresses for locations, and show the functions to which those
3479locations belong. The number column for a location is of the form
fe6fbf8b
VP
3480@var{breakpoint-number}.@var{location-number}.
3481
3482For example:
3b784c4f 3483
fe6fbf8b
VP
3484@smallexample
3485Num Type Disp Enb Address What
34861 breakpoint keep y <MULTIPLE>
3487 stop only if i==1
3488 breakpoint already hit 1 time
34891.1 y 0x080486a2 in void foo<int>() at t.cc:8
34901.2 y 0x080486ca in void foo<double>() at t.cc:8
3491@end smallexample
3492
3493Each location can be individually enabled or disabled by passing
3494@var{breakpoint-number}.@var{location-number} as argument to the
3b784c4f
EZ
3495@code{enable} and @code{disable} commands. Note that you cannot
3496delete the individual locations from the list, you can only delete the
16bfc218 3497entire list of locations that belong to their parent breakpoint (with
3b784c4f
EZ
3498the @kbd{delete @var{num}} command, where @var{num} is the number of
3499the parent breakpoint, 1 in the above example). Disabling or enabling
3500the parent breakpoint (@pxref{Disabling}) affects all of the locations
3501that belong to that breakpoint.
fe6fbf8b 3502
2650777c 3503@cindex pending breakpoints
fe6fbf8b 3504It's quite common to have a breakpoint inside a shared library.
3b784c4f 3505Shared libraries can be loaded and unloaded explicitly,
fe6fbf8b
VP
3506and possibly repeatedly, as the program is executed. To support
3507this use case, @value{GDBN} updates breakpoint locations whenever
3508any shared library is loaded or unloaded. Typically, you would
fcda367b 3509set a breakpoint in a shared library at the beginning of your
fe6fbf8b
VP
3510debugging session, when the library is not loaded, and when the
3511symbols from the library are not available. When you try to set
3512breakpoint, @value{GDBN} will ask you if you want to set
3b784c4f 3513a so called @dfn{pending breakpoint}---breakpoint whose address
fe6fbf8b
VP
3514is not yet resolved.
3515
3516After the program is run, whenever a new shared library is loaded,
3517@value{GDBN} reevaluates all the breakpoints. When a newly loaded
3518shared library contains the symbol or line referred to by some
3519pending breakpoint, that breakpoint is resolved and becomes an
3520ordinary breakpoint. When a library is unloaded, all breakpoints
3521that refer to its symbols or source lines become pending again.
3522
3523This logic works for breakpoints with multiple locations, too. For
3524example, if you have a breakpoint in a C@t{++} template function, and
3525a newly loaded shared library has an instantiation of that template,
3526a new location is added to the list of locations for the breakpoint.
3527
3528Except for having unresolved address, pending breakpoints do not
3529differ from regular breakpoints. You can set conditions or commands,
3530enable and disable them and perform other breakpoint operations.
3531
3532@value{GDBN} provides some additional commands for controlling what
3533happens when the @samp{break} command cannot resolve breakpoint
3534address specification to an address:
dd79a6cf
JJ
3535
3536@kindex set breakpoint pending
3537@kindex show breakpoint pending
3538@table @code
3539@item set breakpoint pending auto
3540This is the default behavior. When @value{GDBN} cannot find the breakpoint
3541location, it queries you whether a pending breakpoint should be created.
3542
3543@item set breakpoint pending on
3544This indicates that an unrecognized breakpoint location should automatically
3545result in a pending breakpoint being created.
3546
3547@item set breakpoint pending off
3548This indicates that pending breakpoints are not to be created. Any
3549unrecognized breakpoint location results in an error. This setting does
3550not affect any pending breakpoints previously created.
3551
3552@item show breakpoint pending
3553Show the current behavior setting for creating pending breakpoints.
3554@end table
2650777c 3555
fe6fbf8b
VP
3556The settings above only affect the @code{break} command and its
3557variants. Once breakpoint is set, it will be automatically updated
3558as shared libraries are loaded and unloaded.
2650777c 3559
765dc015
VP
3560@cindex automatic hardware breakpoints
3561For some targets, @value{GDBN} can automatically decide if hardware or
3562software breakpoints should be used, depending on whether the
3563breakpoint address is read-only or read-write. This applies to
3564breakpoints set with the @code{break} command as well as to internal
3565breakpoints set by commands like @code{next} and @code{finish}. For
fcda367b 3566breakpoints set with @code{hbreak}, @value{GDBN} will always use hardware
765dc015
VP
3567breakpoints.
3568
3569You can control this automatic behaviour with the following commands::
3570
3571@kindex set breakpoint auto-hw
3572@kindex show breakpoint auto-hw
3573@table @code
3574@item set breakpoint auto-hw on
3575This is the default behavior. When @value{GDBN} sets a breakpoint, it
3576will try to use the target memory map to decide if software or hardware
3577breakpoint must be used.
3578
3579@item set breakpoint auto-hw off
3580This indicates @value{GDBN} should not automatically select breakpoint
3581type. If the target provides a memory map, @value{GDBN} will warn when
3582trying to set software breakpoint at a read-only address.
3583@end table
3584
74960c60
VP
3585@value{GDBN} normally implements breakpoints by replacing the program code
3586at the breakpoint address with a special instruction, which, when
3587executed, given control to the debugger. By default, the program
3588code is so modified only when the program is resumed. As soon as
3589the program stops, @value{GDBN} restores the original instructions. This
3590behaviour guards against leaving breakpoints inserted in the
3591target should gdb abrubptly disconnect. However, with slow remote
3592targets, inserting and removing breakpoint can reduce the performance.
3593This behavior can be controlled with the following commands::
3594
3595@kindex set breakpoint always-inserted
3596@kindex show breakpoint always-inserted
3597@table @code
3598@item set breakpoint always-inserted off
33e5cbd6
PA
3599All breakpoints, including newly added by the user, are inserted in
3600the target only when the target is resumed. All breakpoints are
3601removed from the target when it stops.
74960c60
VP
3602
3603@item set breakpoint always-inserted on
3604Causes all breakpoints to be inserted in the target at all times. If
3605the user adds a new breakpoint, or changes an existing breakpoint, the
3606breakpoints in the target are updated immediately. A breakpoint is
3607removed from the target only when breakpoint itself is removed.
33e5cbd6
PA
3608
3609@cindex non-stop mode, and @code{breakpoint always-inserted}
3610@item set breakpoint always-inserted auto
3611This is the default mode. If @value{GDBN} is controlling the inferior
3612in non-stop mode (@pxref{Non-Stop Mode}), gdb behaves as if
3613@code{breakpoint always-inserted} mode is on. If @value{GDBN} is
3614controlling the inferior in all-stop mode, @value{GDBN} behaves as if
3615@code{breakpoint always-inserted} mode is off.
74960c60 3616@end table
765dc015 3617
c906108c
SS
3618@cindex negative breakpoint numbers
3619@cindex internal @value{GDBN} breakpoints
eb12ee30
AC
3620@value{GDBN} itself sometimes sets breakpoints in your program for
3621special purposes, such as proper handling of @code{longjmp} (in C
3622programs). These internal breakpoints are assigned negative numbers,
3623starting with @code{-1}; @samp{info breakpoints} does not display them.
c906108c 3624You can see these breakpoints with the @value{GDBN} maintenance command
eb12ee30 3625@samp{maint info breakpoints} (@pxref{maint info breakpoints}).
c906108c
SS
3626
3627
6d2ebf8b 3628@node Set Watchpoints
79a6e687 3629@subsection Setting Watchpoints
c906108c
SS
3630
3631@cindex setting watchpoints
c906108c
SS
3632You can use a watchpoint to stop execution whenever the value of an
3633expression changes, without having to predict a particular place where
fd60e0df
EZ
3634this may happen. (This is sometimes called a @dfn{data breakpoint}.)
3635The expression may be as simple as the value of a single variable, or
3636as complex as many variables combined by operators. Examples include:
3637
3638@itemize @bullet
3639@item
3640A reference to the value of a single variable.
3641
3642@item
3643An address cast to an appropriate data type. For example,
3644@samp{*(int *)0x12345678} will watch a 4-byte region at the specified
3645address (assuming an @code{int} occupies 4 bytes).
3646
3647@item
3648An arbitrarily complex expression, such as @samp{a*b + c/d}. The
3649expression can use any operators valid in the program's native
3650language (@pxref{Languages}).
3651@end itemize
c906108c 3652
fa4727a6
DJ
3653You can set a watchpoint on an expression even if the expression can
3654not be evaluated yet. For instance, you can set a watchpoint on
3655@samp{*global_ptr} before @samp{global_ptr} is initialized.
3656@value{GDBN} will stop when your program sets @samp{global_ptr} and
3657the expression produces a valid value. If the expression becomes
3658valid in some other way than changing a variable (e.g.@: if the memory
3659pointed to by @samp{*global_ptr} becomes readable as the result of a
3660@code{malloc} call), @value{GDBN} may not stop until the next time
3661the expression changes.
3662
82f2d802
EZ
3663@cindex software watchpoints
3664@cindex hardware watchpoints
c906108c 3665Depending on your system, watchpoints may be implemented in software or
2df3850c 3666hardware. @value{GDBN} does software watchpointing by single-stepping your
c906108c
SS
3667program and testing the variable's value each time, which is hundreds of
3668times slower than normal execution. (But this may still be worth it, to
3669catch errors where you have no clue what part of your program is the
3670culprit.)
3671
37e4754d 3672On some systems, such as HP-UX, PowerPC, @sc{gnu}/Linux and most other
82f2d802
EZ
3673x86-based targets, @value{GDBN} includes support for hardware
3674watchpoints, which do not slow down the running of your program.
c906108c
SS
3675
3676@table @code
3677@kindex watch
d8b2a693 3678@item watch @var{expr} @r{[}thread @var{threadnum}@r{]}
fd60e0df
EZ
3679Set a watchpoint for an expression. @value{GDBN} will break when the
3680expression @var{expr} is written into by the program and its value
3681changes. The simplest (and the most popular) use of this command is
3682to watch the value of a single variable:
3683
3684@smallexample
3685(@value{GDBP}) watch foo
3686@end smallexample
c906108c 3687
d8b2a693
JB
3688If the command includes a @code{@r{[}thread @var{threadnum}@r{]}}
3689clause, @value{GDBN} breaks only when the thread identified by
3690@var{threadnum} changes the value of @var{expr}. If any other threads
3691change the value of @var{expr}, @value{GDBN} will not break. Note
3692that watchpoints restricted to a single thread in this way only work
3693with Hardware Watchpoints.
3694
c906108c 3695@kindex rwatch
d8b2a693 3696@item rwatch @var{expr} @r{[}thread @var{threadnum}@r{]}
09d4efe1
EZ
3697Set a watchpoint that will break when the value of @var{expr} is read
3698by the program.
c906108c
SS
3699
3700@kindex awatch
d8b2a693 3701@item awatch @var{expr} @r{[}thread @var{threadnum}@r{]}
09d4efe1
EZ
3702Set a watchpoint that will break when @var{expr} is either read from
3703or written into by the program.
c906108c 3704
45ac1734 3705@kindex info watchpoints @r{[}@var{n}@r{]}
c906108c 3706@item info watchpoints
d77f58be
SS
3707This command prints a list of watchpoints, using the same format as
3708@code{info break} (@pxref{Set Breaks}).
c906108c
SS
3709@end table
3710
3711@value{GDBN} sets a @dfn{hardware watchpoint} if possible. Hardware
3712watchpoints execute very quickly, and the debugger reports a change in
3713value at the exact instruction where the change occurs. If @value{GDBN}
3714cannot set a hardware watchpoint, it sets a software watchpoint, which
3715executes more slowly and reports the change in value at the next
82f2d802
EZ
3716@emph{statement}, not the instruction, after the change occurs.
3717
82f2d802
EZ
3718@cindex use only software watchpoints
3719You can force @value{GDBN} to use only software watchpoints with the
3720@kbd{set can-use-hw-watchpoints 0} command. With this variable set to
3721zero, @value{GDBN} will never try to use hardware watchpoints, even if
3722the underlying system supports them. (Note that hardware-assisted
3723watchpoints that were set @emph{before} setting
3724@code{can-use-hw-watchpoints} to zero will still use the hardware
d3e8051b 3725mechanism of watching expression values.)
c906108c 3726
9c16f35a
EZ
3727@table @code
3728@item set can-use-hw-watchpoints
3729@kindex set can-use-hw-watchpoints
3730Set whether or not to use hardware watchpoints.
3731
3732@item show can-use-hw-watchpoints
3733@kindex show can-use-hw-watchpoints
3734Show the current mode of using hardware watchpoints.
3735@end table
3736
3737For remote targets, you can restrict the number of hardware
3738watchpoints @value{GDBN} will use, see @ref{set remote
3739hardware-breakpoint-limit}.
3740
c906108c
SS
3741When you issue the @code{watch} command, @value{GDBN} reports
3742
474c8240 3743@smallexample
c906108c 3744Hardware watchpoint @var{num}: @var{expr}
474c8240 3745@end smallexample
c906108c
SS
3746
3747@noindent
3748if it was able to set a hardware watchpoint.
3749
7be570e7
JM
3750Currently, the @code{awatch} and @code{rwatch} commands can only set
3751hardware watchpoints, because accesses to data that don't change the
3752value of the watched expression cannot be detected without examining
3753every instruction as it is being executed, and @value{GDBN} does not do
3754that currently. If @value{GDBN} finds that it is unable to set a
3755hardware breakpoint with the @code{awatch} or @code{rwatch} command, it
3756will print a message like this:
3757
3758@smallexample
3759Expression cannot be implemented with read/access watchpoint.
3760@end smallexample
3761
3762Sometimes, @value{GDBN} cannot set a hardware watchpoint because the
3763data type of the watched expression is wider than what a hardware
3764watchpoint on the target machine can handle. For example, some systems
3765can only watch regions that are up to 4 bytes wide; on such systems you
3766cannot set hardware watchpoints for an expression that yields a
3767double-precision floating-point number (which is typically 8 bytes
3768wide). As a work-around, it might be possible to break the large region
3769into a series of smaller ones and watch them with separate watchpoints.
3770
3771If you set too many hardware watchpoints, @value{GDBN} might be unable
3772to insert all of them when you resume the execution of your program.
3773Since the precise number of active watchpoints is unknown until such
3774time as the program is about to be resumed, @value{GDBN} might not be
3775able to warn you about this when you set the watchpoints, and the
3776warning will be printed only when the program is resumed:
3777
3778@smallexample
3779Hardware watchpoint @var{num}: Could not insert watchpoint
3780@end smallexample
3781
3782@noindent
3783If this happens, delete or disable some of the watchpoints.
3784
fd60e0df
EZ
3785Watching complex expressions that reference many variables can also
3786exhaust the resources available for hardware-assisted watchpoints.
3787That's because @value{GDBN} needs to watch every variable in the
3788expression with separately allocated resources.
3789
c906108c 3790If you call a function interactively using @code{print} or @code{call},
2df3850c 3791any watchpoints you have set will be inactive until @value{GDBN} reaches another
c906108c
SS
3792kind of breakpoint or the call completes.
3793
7be570e7
JM
3794@value{GDBN} automatically deletes watchpoints that watch local
3795(automatic) variables, or expressions that involve such variables, when
3796they go out of scope, that is, when the execution leaves the block in
3797which these variables were defined. In particular, when the program
3798being debugged terminates, @emph{all} local variables go out of scope,
3799and so only watchpoints that watch global variables remain set. If you
3800rerun the program, you will need to set all such watchpoints again. One
3801way of doing that would be to set a code breakpoint at the entry to the
3802@code{main} function and when it breaks, set all the watchpoints.
3803
c906108c
SS
3804@cindex watchpoints and threads
3805@cindex threads and watchpoints
d983da9c
DJ
3806In multi-threaded programs, watchpoints will detect changes to the
3807watched expression from every thread.
3808
3809@quotation
3810@emph{Warning:} In multi-threaded programs, software watchpoints
53a5351d
JM
3811have only limited usefulness. If @value{GDBN} creates a software
3812watchpoint, it can only watch the value of an expression @emph{in a
3813single thread}. If you are confident that the expression can only
3814change due to the current thread's activity (and if you are also
3815confident that no other thread can become current), then you can use
3816software watchpoints as usual. However, @value{GDBN} may not notice
3817when a non-current thread's activity changes the expression. (Hardware
3818watchpoints, in contrast, watch an expression in all threads.)
c906108c 3819@end quotation
c906108c 3820
501eef12
AC
3821@xref{set remote hardware-watchpoint-limit}.
3822
6d2ebf8b 3823@node Set Catchpoints
79a6e687 3824@subsection Setting Catchpoints
d4f3574e 3825@cindex catchpoints, setting
c906108c
SS
3826@cindex exception handlers
3827@cindex event handling
3828
3829You can use @dfn{catchpoints} to cause the debugger to stop for certain
b37052ae 3830kinds of program events, such as C@t{++} exceptions or the loading of a
c906108c
SS
3831shared library. Use the @code{catch} command to set a catchpoint.
3832
3833@table @code
3834@kindex catch
3835@item catch @var{event}
3836Stop when @var{event} occurs. @var{event} can be any of the following:
3837@table @code
3838@item throw
4644b6e3 3839@cindex stop on C@t{++} exceptions
b37052ae 3840The throwing of a C@t{++} exception.
c906108c
SS
3841
3842@item catch
b37052ae 3843The catching of a C@t{++} exception.
c906108c 3844
8936fcda
JB
3845@item exception
3846@cindex Ada exception catching
3847@cindex catch Ada exceptions
3848An Ada exception being raised. If an exception name is specified
3849at the end of the command (eg @code{catch exception Program_Error}),
3850the debugger will stop only when this specific exception is raised.
3851Otherwise, the debugger stops execution when any Ada exception is raised.
3852
87f67dba
JB
3853When inserting an exception catchpoint on a user-defined exception whose
3854name is identical to one of the exceptions defined by the language, the
3855fully qualified name must be used as the exception name. Otherwise,
3856@value{GDBN} will assume that it should stop on the pre-defined exception
3857rather than the user-defined one. For instance, assuming an exception
3858called @code{Constraint_Error} is defined in package @code{Pck}, then
3859the command to use to catch such exceptions is @kbd{catch exception
3860Pck.Constraint_Error}.
3861
8936fcda
JB
3862@item exception unhandled
3863An exception that was raised but is not handled by the program.
3864
3865@item assert
3866A failed Ada assertion.
3867
c906108c 3868@item exec
4644b6e3 3869@cindex break on fork/exec
5ee187d7
DJ
3870A call to @code{exec}. This is currently only available for HP-UX
3871and @sc{gnu}/Linux.
c906108c 3872
a96d9b2e 3873@item syscall
ee8e71d4 3874@itemx syscall @r{[}@var{name} @r{|} @var{number}@r{]} @dots{}
a96d9b2e
SDJ
3875@cindex break on a system call.
3876A call to or return from a system call, a.k.a.@: @dfn{syscall}. A
3877syscall is a mechanism for application programs to request a service
3878from the operating system (OS) or one of the OS system services.
3879@value{GDBN} can catch some or all of the syscalls issued by the
3880debuggee, and show the related information for each syscall. If no
3881argument is specified, calls to and returns from all system calls
3882will be caught.
3883
3884@var{name} can be any system call name that is valid for the
3885underlying OS. Just what syscalls are valid depends on the OS. On
3886GNU and Unix systems, you can find the full list of valid syscall
3887names on @file{/usr/include/asm/unistd.h}.
3888
3889@c For MS-Windows, the syscall names and the corresponding numbers
3890@c can be found, e.g., on this URL:
3891@c http://www.metasploit.com/users/opcode/syscalls.html
3892@c but we don't support Windows syscalls yet.
3893
3894Normally, @value{GDBN} knows in advance which syscalls are valid for
3895each OS, so you can use the @value{GDBN} command-line completion
3896facilities (@pxref{Completion,, command completion}) to list the
3897available choices.
3898
3899You may also specify the system call numerically. A syscall's
3900number is the value passed to the OS's syscall dispatcher to
3901identify the requested service. When you specify the syscall by its
3902name, @value{GDBN} uses its database of syscalls to convert the name
3903into the corresponding numeric code, but using the number directly
3904may be useful if @value{GDBN}'s database does not have the complete
3905list of syscalls on your system (e.g., because @value{GDBN} lags
3906behind the OS upgrades).
3907
3908The example below illustrates how this command works if you don't provide
3909arguments to it:
3910
3911@smallexample
3912(@value{GDBP}) catch syscall
3913Catchpoint 1 (syscall)
3914(@value{GDBP}) r
3915Starting program: /tmp/catch-syscall
3916
3917Catchpoint 1 (call to syscall 'close'), \
3918 0xffffe424 in __kernel_vsyscall ()
3919(@value{GDBP}) c
3920Continuing.
3921
3922Catchpoint 1 (returned from syscall 'close'), \
3923 0xffffe424 in __kernel_vsyscall ()
3924(@value{GDBP})
3925@end smallexample
3926
3927Here is an example of catching a system call by name:
3928
3929@smallexample
3930(@value{GDBP}) catch syscall chroot
3931Catchpoint 1 (syscall 'chroot' [61])
3932(@value{GDBP}) r
3933Starting program: /tmp/catch-syscall
3934
3935Catchpoint 1 (call to syscall 'chroot'), \
3936 0xffffe424 in __kernel_vsyscall ()
3937(@value{GDBP}) c
3938Continuing.
3939
3940Catchpoint 1 (returned from syscall 'chroot'), \
3941 0xffffe424 in __kernel_vsyscall ()
3942(@value{GDBP})
3943@end smallexample
3944
3945An example of specifying a system call numerically. In the case
3946below, the syscall number has a corresponding entry in the XML
3947file, so @value{GDBN} finds its name and prints it:
3948
3949@smallexample
3950(@value{GDBP}) catch syscall 252
3951Catchpoint 1 (syscall(s) 'exit_group')
3952(@value{GDBP}) r
3953Starting program: /tmp/catch-syscall
3954
3955Catchpoint 1 (call to syscall 'exit_group'), \
3956 0xffffe424 in __kernel_vsyscall ()
3957(@value{GDBP}) c
3958Continuing.
3959
3960Program exited normally.
3961(@value{GDBP})
3962@end smallexample
3963
3964However, there can be situations when there is no corresponding name
3965in XML file for that syscall number. In this case, @value{GDBN} prints
3966a warning message saying that it was not able to find the syscall name,
3967but the catchpoint will be set anyway. See the example below:
3968
3969@smallexample
3970(@value{GDBP}) catch syscall 764
3971warning: The number '764' does not represent a known syscall.
3972Catchpoint 2 (syscall 764)
3973(@value{GDBP})
3974@end smallexample
3975
3976If you configure @value{GDBN} using the @samp{--without-expat} option,
3977it will not be able to display syscall names. Also, if your
3978architecture does not have an XML file describing its system calls,
3979you will not be able to see the syscall names. It is important to
3980notice that these two features are used for accessing the syscall
3981name database. In either case, you will see a warning like this:
3982
3983@smallexample
3984(@value{GDBP}) catch syscall
3985warning: Could not open "syscalls/i386-linux.xml"
3986warning: Could not load the syscall XML file 'syscalls/i386-linux.xml'.
3987GDB will not be able to display syscall names.
3988Catchpoint 1 (syscall)
3989(@value{GDBP})
3990@end smallexample
3991
3992Of course, the file name will change depending on your architecture and system.
3993
3994Still using the example above, you can also try to catch a syscall by its
3995number. In this case, you would see something like:
3996
3997@smallexample
3998(@value{GDBP}) catch syscall 252
3999Catchpoint 1 (syscall(s) 252)
4000@end smallexample
4001
4002Again, in this case @value{GDBN} would not be able to display syscall's names.
4003
c906108c 4004@item fork
5ee187d7
DJ
4005A call to @code{fork}. This is currently only available for HP-UX
4006and @sc{gnu}/Linux.
c906108c
SS
4007
4008@item vfork
5ee187d7
DJ
4009A call to @code{vfork}. This is currently only available for HP-UX
4010and @sc{gnu}/Linux.
c906108c 4011
c906108c
SS
4012@end table
4013
4014@item tcatch @var{event}
4015Set a catchpoint that is enabled only for one stop. The catchpoint is
4016automatically deleted after the first time the event is caught.
4017
4018@end table
4019
4020Use the @code{info break} command to list the current catchpoints.
4021
b37052ae 4022There are currently some limitations to C@t{++} exception handling
c906108c
SS
4023(@code{catch throw} and @code{catch catch}) in @value{GDBN}:
4024
4025@itemize @bullet
4026@item
4027If you call a function interactively, @value{GDBN} normally returns
4028control to you when the function has finished executing. If the call
4029raises an exception, however, the call may bypass the mechanism that
4030returns control to you and cause your program either to abort or to
4031simply continue running until it hits a breakpoint, catches a signal
4032that @value{GDBN} is listening for, or exits. This is the case even if
4033you set a catchpoint for the exception; catchpoints on exceptions are
4034disabled within interactive calls.
4035
4036@item
4037You cannot raise an exception interactively.
4038
4039@item
4040You cannot install an exception handler interactively.
4041@end itemize
4042
4043@cindex raise exceptions
4044Sometimes @code{catch} is not the best way to debug exception handling:
4045if you need to know exactly where an exception is raised, it is better to
4046stop @emph{before} the exception handler is called, since that way you
4047can see the stack before any unwinding takes place. If you set a
4048breakpoint in an exception handler instead, it may not be easy to find
4049out where the exception was raised.
4050
4051To stop just before an exception handler is called, you need some
b37052ae 4052knowledge of the implementation. In the case of @sc{gnu} C@t{++}, exceptions are
c906108c
SS
4053raised by calling a library function named @code{__raise_exception}
4054which has the following ANSI C interface:
4055
474c8240 4056@smallexample
c906108c 4057 /* @var{addr} is where the exception identifier is stored.
d4f3574e
SS
4058 @var{id} is the exception identifier. */
4059 void __raise_exception (void **addr, void *id);
474c8240 4060@end smallexample
c906108c
SS
4061
4062@noindent
4063To make the debugger catch all exceptions before any stack
4064unwinding takes place, set a breakpoint on @code{__raise_exception}
79a6e687 4065(@pxref{Breakpoints, ,Breakpoints; Watchpoints; and Exceptions}).
c906108c 4066
79a6e687 4067With a conditional breakpoint (@pxref{Conditions, ,Break Conditions})
c906108c
SS
4068that depends on the value of @var{id}, you can stop your program when
4069a specific exception is raised. You can use multiple conditional
4070breakpoints to stop your program when any of a number of exceptions are
4071raised.
4072
4073
6d2ebf8b 4074@node Delete Breaks
79a6e687 4075@subsection Deleting Breakpoints
c906108c
SS
4076
4077@cindex clearing breakpoints, watchpoints, catchpoints
4078@cindex deleting breakpoints, watchpoints, catchpoints
4079It is often necessary to eliminate a breakpoint, watchpoint, or
4080catchpoint once it has done its job and you no longer want your program
4081to stop there. This is called @dfn{deleting} the breakpoint. A
4082breakpoint that has been deleted no longer exists; it is forgotten.
4083
4084With the @code{clear} command you can delete breakpoints according to
4085where they are in your program. With the @code{delete} command you can
4086delete individual breakpoints, watchpoints, or catchpoints by specifying
4087their breakpoint numbers.
4088
4089It is not necessary to delete a breakpoint to proceed past it. @value{GDBN}
4090automatically ignores breakpoints on the first instruction to be executed
4091when you continue execution without changing the execution address.
4092
4093@table @code
4094@kindex clear
4095@item clear
4096Delete any breakpoints at the next instruction to be executed in the
79a6e687 4097selected stack frame (@pxref{Selection, ,Selecting a Frame}). When
c906108c
SS
4098the innermost frame is selected, this is a good way to delete a
4099breakpoint where your program just stopped.
4100
2a25a5ba
EZ
4101@item clear @var{location}
4102Delete any breakpoints set at the specified @var{location}.
4103@xref{Specify Location}, for the various forms of @var{location}; the
4104most useful ones are listed below:
4105
4106@table @code
c906108c
SS
4107@item clear @var{function}
4108@itemx clear @var{filename}:@var{function}
09d4efe1 4109Delete any breakpoints set at entry to the named @var{function}.
c906108c
SS
4110
4111@item clear @var{linenum}
4112@itemx clear @var{filename}:@var{linenum}
09d4efe1
EZ
4113Delete any breakpoints set at or within the code of the specified
4114@var{linenum} of the specified @var{filename}.
2a25a5ba 4115@end table
c906108c
SS
4116
4117@cindex delete breakpoints
4118@kindex delete
41afff9a 4119@kindex d @r{(@code{delete})}
c5394b80
JM
4120@item delete @r{[}breakpoints@r{]} @r{[}@var{range}@dots{}@r{]}
4121Delete the breakpoints, watchpoints, or catchpoints of the breakpoint
4122ranges specified as arguments. If no argument is specified, delete all
c906108c
SS
4123breakpoints (@value{GDBN} asks confirmation, unless you have @code{set
4124confirm off}). You can abbreviate this command as @code{d}.
4125@end table
4126
6d2ebf8b 4127@node Disabling
79a6e687 4128@subsection Disabling Breakpoints
c906108c 4129
4644b6e3 4130@cindex enable/disable a breakpoint
c906108c
SS
4131Rather than deleting a breakpoint, watchpoint, or catchpoint, you might
4132prefer to @dfn{disable} it. This makes the breakpoint inoperative as if
4133it had been deleted, but remembers the information on the breakpoint so
4134that you can @dfn{enable} it again later.
4135
4136You disable and enable breakpoints, watchpoints, and catchpoints with
d77f58be
SS
4137the @code{enable} and @code{disable} commands, optionally specifying
4138one or more breakpoint numbers as arguments. Use @code{info break} to
4139print a list of all breakpoints, watchpoints, and catchpoints if you
4140do not know which numbers to use.
c906108c 4141
3b784c4f
EZ
4142Disabling and enabling a breakpoint that has multiple locations
4143affects all of its locations.
4144
c906108c
SS
4145A breakpoint, watchpoint, or catchpoint can have any of four different
4146states of enablement:
4147
4148@itemize @bullet
4149@item
4150Enabled. The breakpoint stops your program. A breakpoint set
4151with the @code{break} command starts out in this state.
4152@item
4153Disabled. The breakpoint has no effect on your program.
4154@item
4155Enabled once. The breakpoint stops your program, but then becomes
d4f3574e 4156disabled.
c906108c
SS
4157@item
4158Enabled for deletion. The breakpoint stops your program, but
d4f3574e
SS
4159immediately after it does so it is deleted permanently. A breakpoint
4160set with the @code{tbreak} command starts out in this state.
c906108c
SS
4161@end itemize
4162
4163You can use the following commands to enable or disable breakpoints,
4164watchpoints, and catchpoints:
4165
4166@table @code
c906108c 4167@kindex disable
41afff9a 4168@kindex dis @r{(@code{disable})}
c5394b80 4169@item disable @r{[}breakpoints@r{]} @r{[}@var{range}@dots{}@r{]}
c906108c
SS
4170Disable the specified breakpoints---or all breakpoints, if none are
4171listed. A disabled breakpoint has no effect but is not forgotten. All
4172options such as ignore-counts, conditions and commands are remembered in
4173case the breakpoint is enabled again later. You may abbreviate
4174@code{disable} as @code{dis}.
4175
c906108c 4176@kindex enable
c5394b80 4177@item enable @r{[}breakpoints@r{]} @r{[}@var{range}@dots{}@r{]}
c906108c
SS
4178Enable the specified breakpoints (or all defined breakpoints). They
4179become effective once again in stopping your program.
4180
c5394b80 4181@item enable @r{[}breakpoints@r{]} once @var{range}@dots{}
c906108c
SS
4182Enable the specified breakpoints temporarily. @value{GDBN} disables any
4183of these breakpoints immediately after stopping your program.
4184
c5394b80 4185@item enable @r{[}breakpoints@r{]} delete @var{range}@dots{}
c906108c
SS
4186Enable the specified breakpoints to work once, then die. @value{GDBN}
4187deletes any of these breakpoints as soon as your program stops there.
09d4efe1 4188Breakpoints set by the @code{tbreak} command start out in this state.
c906108c
SS
4189@end table
4190
d4f3574e
SS
4191@c FIXME: I think the following ``Except for [...] @code{tbreak}'' is
4192@c confusing: tbreak is also initially enabled.
c906108c 4193Except for a breakpoint set with @code{tbreak} (@pxref{Set Breaks,
79a6e687 4194,Setting Breakpoints}), breakpoints that you set are initially enabled;
c906108c
SS
4195subsequently, they become disabled or enabled only when you use one of
4196the commands above. (The command @code{until} can set and delete a
4197breakpoint of its own, but it does not change the state of your other
4198breakpoints; see @ref{Continuing and Stepping, ,Continuing and
79a6e687 4199Stepping}.)
c906108c 4200
6d2ebf8b 4201@node Conditions
79a6e687 4202@subsection Break Conditions
c906108c
SS
4203@cindex conditional breakpoints
4204@cindex breakpoint conditions
4205
4206@c FIXME what is scope of break condition expr? Context where wanted?
5d161b24 4207@c in particular for a watchpoint?
c906108c
SS
4208The simplest sort of breakpoint breaks every time your program reaches a
4209specified place. You can also specify a @dfn{condition} for a
4210breakpoint. A condition is just a Boolean expression in your
4211programming language (@pxref{Expressions, ,Expressions}). A breakpoint with
4212a condition evaluates the expression each time your program reaches it,
4213and your program stops only if the condition is @emph{true}.
4214
4215This is the converse of using assertions for program validation; in that
4216situation, you want to stop when the assertion is violated---that is,
4217when the condition is false. In C, if you want to test an assertion expressed
4218by the condition @var{assert}, you should set the condition
4219@samp{! @var{assert}} on the appropriate breakpoint.
4220
4221Conditions are also accepted for watchpoints; you may not need them,
4222since a watchpoint is inspecting the value of an expression anyhow---but
4223it might be simpler, say, to just set a watchpoint on a variable name,
4224and specify a condition that tests whether the new value is an interesting
4225one.
4226
4227Break conditions can have side effects, and may even call functions in
4228your program. This can be useful, for example, to activate functions
4229that log program progress, or to use your own print functions to
99e008fe 4230format special data structures. The effects are completely predictable
c906108c
SS
4231unless there is another enabled breakpoint at the same address. (In
4232that case, @value{GDBN} might see the other breakpoint first and stop your
4233program without checking the condition of this one.) Note that
d4f3574e
SS
4234breakpoint commands are usually more convenient and flexible than break
4235conditions for the
c906108c 4236purpose of performing side effects when a breakpoint is reached
79a6e687 4237(@pxref{Break Commands, ,Breakpoint Command Lists}).
c906108c
SS
4238
4239Break conditions can be specified when a breakpoint is set, by using
4240@samp{if} in the arguments to the @code{break} command. @xref{Set
79a6e687 4241Breaks, ,Setting Breakpoints}. They can also be changed at any time
c906108c 4242with the @code{condition} command.
53a5351d 4243
c906108c
SS
4244You can also use the @code{if} keyword with the @code{watch} command.
4245The @code{catch} command does not recognize the @code{if} keyword;
4246@code{condition} is the only way to impose a further condition on a
4247catchpoint.
c906108c
SS
4248
4249@table @code
4250@kindex condition
4251@item condition @var{bnum} @var{expression}
4252Specify @var{expression} as the break condition for breakpoint,
4253watchpoint, or catchpoint number @var{bnum}. After you set a condition,
4254breakpoint @var{bnum} stops your program only if the value of
4255@var{expression} is true (nonzero, in C). When you use
4256@code{condition}, @value{GDBN} checks @var{expression} immediately for
4257syntactic correctness, and to determine whether symbols in it have
d4f3574e
SS
4258referents in the context of your breakpoint. If @var{expression} uses
4259symbols not referenced in the context of the breakpoint, @value{GDBN}
4260prints an error message:
4261
474c8240 4262@smallexample
d4f3574e 4263No symbol "foo" in current context.
474c8240 4264@end smallexample
d4f3574e
SS
4265
4266@noindent
c906108c
SS
4267@value{GDBN} does
4268not actually evaluate @var{expression} at the time the @code{condition}
d4f3574e
SS
4269command (or a command that sets a breakpoint with a condition, like
4270@code{break if @dots{}}) is given, however. @xref{Expressions, ,Expressions}.
c906108c
SS
4271
4272@item condition @var{bnum}
4273Remove the condition from breakpoint number @var{bnum}. It becomes
4274an ordinary unconditional breakpoint.
4275@end table
4276
4277@cindex ignore count (of breakpoint)
4278A special case of a breakpoint condition is to stop only when the
4279breakpoint has been reached a certain number of times. This is so
4280useful that there is a special way to do it, using the @dfn{ignore
4281count} of the breakpoint. Every breakpoint has an ignore count, which
4282is an integer. Most of the time, the ignore count is zero, and
4283therefore has no effect. But if your program reaches a breakpoint whose
4284ignore count is positive, then instead of stopping, it just decrements
4285the ignore count by one and continues. As a result, if the ignore count
4286value is @var{n}, the breakpoint does not stop the next @var{n} times
4287your program reaches it.
4288
4289@table @code
4290@kindex ignore
4291@item ignore @var{bnum} @var{count}
4292Set the ignore count of breakpoint number @var{bnum} to @var{count}.
4293The next @var{count} times the breakpoint is reached, your program's
4294execution does not stop; other than to decrement the ignore count, @value{GDBN}
4295takes no action.
4296
4297To make the breakpoint stop the next time it is reached, specify
4298a count of zero.
4299
4300When you use @code{continue} to resume execution of your program from a
4301breakpoint, you can specify an ignore count directly as an argument to
4302@code{continue}, rather than using @code{ignore}. @xref{Continuing and
79a6e687 4303Stepping,,Continuing and Stepping}.
c906108c
SS
4304
4305If a breakpoint has a positive ignore count and a condition, the
4306condition is not checked. Once the ignore count reaches zero,
4307@value{GDBN} resumes checking the condition.
4308
4309You could achieve the effect of the ignore count with a condition such
4310as @w{@samp{$foo-- <= 0}} using a debugger convenience variable that
4311is decremented each time. @xref{Convenience Vars, ,Convenience
79a6e687 4312Variables}.
c906108c
SS
4313@end table
4314
4315Ignore counts apply to breakpoints, watchpoints, and catchpoints.
4316
4317
6d2ebf8b 4318@node Break Commands
79a6e687 4319@subsection Breakpoint Command Lists
c906108c
SS
4320
4321@cindex breakpoint commands
4322You can give any breakpoint (or watchpoint or catchpoint) a series of
4323commands to execute when your program stops due to that breakpoint. For
4324example, you might want to print the values of certain expressions, or
4325enable other breakpoints.
4326
4327@table @code
4328@kindex commands
ca91424e 4329@kindex end@r{ (breakpoint commands)}
95a42b64 4330@item commands @r{[}@var{range}@dots{}@r{]}
c906108c
SS
4331@itemx @dots{} @var{command-list} @dots{}
4332@itemx end
95a42b64 4333Specify a list of commands for the given breakpoints. The commands
c906108c
SS
4334themselves appear on the following lines. Type a line containing just
4335@code{end} to terminate the commands.
4336
4337To remove all commands from a breakpoint, type @code{commands} and
4338follow it immediately with @code{end}; that is, give no commands.
4339
95a42b64
TT
4340With no argument, @code{commands} refers to the last breakpoint,
4341watchpoint, or catchpoint set (not to the breakpoint most recently
4342encountered). If the most recent breakpoints were set with a single
4343command, then the @code{commands} will apply to all the breakpoints
4344set by that command. This applies to breakpoints set by
86b17b60
PA
4345@code{rbreak}, and also applies when a single @code{break} command
4346creates multiple breakpoints (@pxref{Ambiguous Expressions,,Ambiguous
4347Expressions}).
c906108c
SS
4348@end table
4349
4350Pressing @key{RET} as a means of repeating the last @value{GDBN} command is
4351disabled within a @var{command-list}.
4352
4353You can use breakpoint commands to start your program up again. Simply
4354use the @code{continue} command, or @code{step}, or any other command
4355that resumes execution.
4356
4357Any other commands in the command list, after a command that resumes
4358execution, are ignored. This is because any time you resume execution
4359(even with a simple @code{next} or @code{step}), you may encounter
4360another breakpoint---which could have its own command list, leading to
4361ambiguities about which list to execute.
4362
4363@kindex silent
4364If the first command you specify in a command list is @code{silent}, the
4365usual message about stopping at a breakpoint is not printed. This may
4366be desirable for breakpoints that are to print a specific message and
4367then continue. If none of the remaining commands print anything, you
4368see no sign that the breakpoint was reached. @code{silent} is
4369meaningful only at the beginning of a breakpoint command list.
4370
4371The commands @code{echo}, @code{output}, and @code{printf} allow you to
4372print precisely controlled output, and are often useful in silent
79a6e687 4373breakpoints. @xref{Output, ,Commands for Controlled Output}.
c906108c
SS
4374
4375For example, here is how you could use breakpoint commands to print the
4376value of @code{x} at entry to @code{foo} whenever @code{x} is positive.
4377
474c8240 4378@smallexample
c906108c
SS
4379break foo if x>0
4380commands
4381silent
4382printf "x is %d\n",x
4383cont
4384end
474c8240 4385@end smallexample
c906108c
SS
4386
4387One application for breakpoint commands is to compensate for one bug so
4388you can test for another. Put a breakpoint just after the erroneous line
4389of code, give it a condition to detect the case in which something
4390erroneous has been done, and give it commands to assign correct values
4391to any variables that need them. End with the @code{continue} command
4392so that your program does not stop, and start with the @code{silent}
4393command so that no output is produced. Here is an example:
4394
474c8240 4395@smallexample
c906108c
SS
4396break 403
4397commands
4398silent
4399set x = y + 4
4400cont
4401end
474c8240 4402@end smallexample
c906108c 4403
c906108c 4404@c @ifclear BARETARGET
6d2ebf8b 4405@node Error in Breakpoints
d4f3574e 4406@subsection ``Cannot insert breakpoints''
c906108c 4407
fa3a767f
PA
4408If you request too many active hardware-assisted breakpoints and
4409watchpoints, you will see this error message:
d4f3574e
SS
4410
4411@c FIXME: the precise wording of this message may change; the relevant
4412@c source change is not committed yet (Sep 3, 1999).
4413@smallexample
4414Stopped; cannot insert breakpoints.
4415You may have requested too many hardware breakpoints and watchpoints.
4416@end smallexample
4417
4418@noindent
4419This message is printed when you attempt to resume the program, since
4420only then @value{GDBN} knows exactly how many hardware breakpoints and
4421watchpoints it needs to insert.
4422
4423When this message is printed, you need to disable or remove some of the
4424hardware-assisted breakpoints and watchpoints, and then continue.
4425
79a6e687 4426@node Breakpoint-related Warnings
1485d690
KB
4427@subsection ``Breakpoint address adjusted...''
4428@cindex breakpoint address adjusted
4429
4430Some processor architectures place constraints on the addresses at
4431which breakpoints may be placed. For architectures thus constrained,
4432@value{GDBN} will attempt to adjust the breakpoint's address to comply
4433with the constraints dictated by the architecture.
4434
4435One example of such an architecture is the Fujitsu FR-V. The FR-V is
4436a VLIW architecture in which a number of RISC-like instructions may be
4437bundled together for parallel execution. The FR-V architecture
4438constrains the location of a breakpoint instruction within such a
4439bundle to the instruction with the lowest address. @value{GDBN}
4440honors this constraint by adjusting a breakpoint's address to the
4441first in the bundle.
4442
4443It is not uncommon for optimized code to have bundles which contain
4444instructions from different source statements, thus it may happen that
4445a breakpoint's address will be adjusted from one source statement to
4446another. Since this adjustment may significantly alter @value{GDBN}'s
4447breakpoint related behavior from what the user expects, a warning is
4448printed when the breakpoint is first set and also when the breakpoint
4449is hit.
4450
4451A warning like the one below is printed when setting a breakpoint
4452that's been subject to address adjustment:
4453
4454@smallexample
4455warning: Breakpoint address adjusted from 0x00010414 to 0x00010410.
4456@end smallexample
4457
4458Such warnings are printed both for user settable and @value{GDBN}'s
4459internal breakpoints. If you see one of these warnings, you should
4460verify that a breakpoint set at the adjusted address will have the
4461desired affect. If not, the breakpoint in question may be removed and
b383017d 4462other breakpoints may be set which will have the desired behavior.
1485d690
KB
4463E.g., it may be sufficient to place the breakpoint at a later
4464instruction. A conditional breakpoint may also be useful in some
4465cases to prevent the breakpoint from triggering too often.
4466
4467@value{GDBN} will also issue a warning when stopping at one of these
4468adjusted breakpoints:
4469
4470@smallexample
4471warning: Breakpoint 1 address previously adjusted from 0x00010414
4472to 0x00010410.
4473@end smallexample
4474
4475When this warning is encountered, it may be too late to take remedial
4476action except in cases where the breakpoint is hit earlier or more
4477frequently than expected.
d4f3574e 4478
6d2ebf8b 4479@node Continuing and Stepping
79a6e687 4480@section Continuing and Stepping
c906108c
SS
4481
4482@cindex stepping
4483@cindex continuing
4484@cindex resuming execution
4485@dfn{Continuing} means resuming program execution until your program
4486completes normally. In contrast, @dfn{stepping} means executing just
4487one more ``step'' of your program, where ``step'' may mean either one
4488line of source code, or one machine instruction (depending on what
7a292a7a
SS
4489particular command you use). Either when continuing or when stepping,
4490your program may stop even sooner, due to a breakpoint or a signal. (If
d4f3574e
SS
4491it stops due to a signal, you may want to use @code{handle}, or use
4492@samp{signal 0} to resume execution. @xref{Signals, ,Signals}.)
c906108c
SS
4493
4494@table @code
4495@kindex continue
41afff9a
EZ
4496@kindex c @r{(@code{continue})}
4497@kindex fg @r{(resume foreground execution)}
c906108c
SS
4498@item continue @r{[}@var{ignore-count}@r{]}
4499@itemx c @r{[}@var{ignore-count}@r{]}
4500@itemx fg @r{[}@var{ignore-count}@r{]}
4501Resume program execution, at the address where your program last stopped;
4502any breakpoints set at that address are bypassed. The optional argument
4503@var{ignore-count} allows you to specify a further number of times to
4504ignore a breakpoint at this location; its effect is like that of
79a6e687 4505@code{ignore} (@pxref{Conditions, ,Break Conditions}).
c906108c
SS
4506
4507The argument @var{ignore-count} is meaningful only when your program
4508stopped due to a breakpoint. At other times, the argument to
4509@code{continue} is ignored.
4510
d4f3574e
SS
4511The synonyms @code{c} and @code{fg} (for @dfn{foreground}, as the
4512debugged program is deemed to be the foreground program) are provided
4513purely for convenience, and have exactly the same behavior as
4514@code{continue}.
c906108c
SS
4515@end table
4516
4517To resume execution at a different place, you can use @code{return}
79a6e687 4518(@pxref{Returning, ,Returning from a Function}) to go back to the
c906108c 4519calling function; or @code{jump} (@pxref{Jumping, ,Continuing at a
79a6e687 4520Different Address}) to go to an arbitrary location in your program.
c906108c
SS
4521
4522A typical technique for using stepping is to set a breakpoint
79a6e687 4523(@pxref{Breakpoints, ,Breakpoints; Watchpoints; and Catchpoints}) at the
c906108c
SS
4524beginning of the function or the section of your program where a problem
4525is believed to lie, run your program until it stops at that breakpoint,
4526and then step through the suspect area, examining the variables that are
4527interesting, until you see the problem happen.
4528
4529@table @code
4530@kindex step
41afff9a 4531@kindex s @r{(@code{step})}
c906108c
SS
4532@item step
4533Continue running your program until control reaches a different source
4534line, then stop it and return control to @value{GDBN}. This command is
4535abbreviated @code{s}.
4536
4537@quotation
4538@c "without debugging information" is imprecise; actually "without line
4539@c numbers in the debugging information". (gcc -g1 has debugging info but
4540@c not line numbers). But it seems complex to try to make that
4541@c distinction here.
4542@emph{Warning:} If you use the @code{step} command while control is
4543within a function that was compiled without debugging information,
4544execution proceeds until control reaches a function that does have
4545debugging information. Likewise, it will not step into a function which
4546is compiled without debugging information. To step through functions
4547without debugging information, use the @code{stepi} command, described
4548below.
4549@end quotation
4550
4a92d011
EZ
4551The @code{step} command only stops at the first instruction of a source
4552line. This prevents the multiple stops that could otherwise occur in
4553@code{switch} statements, @code{for} loops, etc. @code{step} continues
4554to stop if a function that has debugging information is called within
4555the line. In other words, @code{step} @emph{steps inside} any functions
4556called within the line.
c906108c 4557
d4f3574e
SS
4558Also, the @code{step} command only enters a function if there is line
4559number information for the function. Otherwise it acts like the
5d161b24 4560@code{next} command. This avoids problems when using @code{cc -gl}
c906108c 4561on MIPS machines. Previously, @code{step} entered subroutines if there
5d161b24 4562was any debugging information about the routine.
c906108c
SS
4563
4564@item step @var{count}
4565Continue running as in @code{step}, but do so @var{count} times. If a
7a292a7a
SS
4566breakpoint is reached, or a signal not related to stepping occurs before
4567@var{count} steps, stepping stops right away.
c906108c
SS
4568
4569@kindex next
41afff9a 4570@kindex n @r{(@code{next})}
c906108c
SS
4571@item next @r{[}@var{count}@r{]}
4572Continue to the next source line in the current (innermost) stack frame.
7a292a7a
SS
4573This is similar to @code{step}, but function calls that appear within
4574the line of code are executed without stopping. Execution stops when
4575control reaches a different line of code at the original stack level
4576that was executing when you gave the @code{next} command. This command
4577is abbreviated @code{n}.
c906108c
SS
4578
4579An argument @var{count} is a repeat count, as for @code{step}.
4580
4581
4582@c FIX ME!! Do we delete this, or is there a way it fits in with
4583@c the following paragraph? --- Vctoria
4584@c
4585@c @code{next} within a function that lacks debugging information acts like
4586@c @code{step}, but any function calls appearing within the code of the
4587@c function are executed without stopping.
4588
d4f3574e
SS
4589The @code{next} command only stops at the first instruction of a
4590source line. This prevents multiple stops that could otherwise occur in
4a92d011 4591@code{switch} statements, @code{for} loops, etc.
c906108c 4592
b90a5f51
CF
4593@kindex set step-mode
4594@item set step-mode
4595@cindex functions without line info, and stepping
4596@cindex stepping into functions with no line info
4597@itemx set step-mode on
4a92d011 4598The @code{set step-mode on} command causes the @code{step} command to
b90a5f51
CF
4599stop at the first instruction of a function which contains no debug line
4600information rather than stepping over it.
4601
4a92d011
EZ
4602This is useful in cases where you may be interested in inspecting the
4603machine instructions of a function which has no symbolic info and do not
4604want @value{GDBN} to automatically skip over this function.
b90a5f51
CF
4605
4606@item set step-mode off
4a92d011 4607Causes the @code{step} command to step over any functions which contains no
b90a5f51
CF
4608debug information. This is the default.
4609
9c16f35a
EZ
4610@item show step-mode
4611Show whether @value{GDBN} will stop in or step over functions without
4612source line debug information.
4613
c906108c 4614@kindex finish
8dfa32fc 4615@kindex fin @r{(@code{finish})}
c906108c
SS
4616@item finish
4617Continue running until just after function in the selected stack frame
8dfa32fc
JB
4618returns. Print the returned value (if any). This command can be
4619abbreviated as @code{fin}.
c906108c
SS
4620
4621Contrast this with the @code{return} command (@pxref{Returning,
79a6e687 4622,Returning from a Function}).
c906108c
SS
4623
4624@kindex until
41afff9a 4625@kindex u @r{(@code{until})}
09d4efe1 4626@cindex run until specified location
c906108c
SS
4627@item until
4628@itemx u
4629Continue running until a source line past the current line, in the
4630current stack frame, is reached. This command is used to avoid single
4631stepping through a loop more than once. It is like the @code{next}
4632command, except that when @code{until} encounters a jump, it
4633automatically continues execution until the program counter is greater
4634than the address of the jump.
4635
4636This means that when you reach the end of a loop after single stepping
4637though it, @code{until} makes your program continue execution until it
4638exits the loop. In contrast, a @code{next} command at the end of a loop
4639simply steps back to the beginning of the loop, which forces you to step
4640through the next iteration.
4641
4642@code{until} always stops your program if it attempts to exit the current
4643stack frame.
4644
4645@code{until} may produce somewhat counterintuitive results if the order
4646of machine code does not match the order of the source lines. For
4647example, in the following excerpt from a debugging session, the @code{f}
4648(@code{frame}) command shows that execution is stopped at line
4649@code{206}; yet when we use @code{until}, we get to line @code{195}:
4650
474c8240 4651@smallexample
c906108c
SS
4652(@value{GDBP}) f
4653#0 main (argc=4, argv=0xf7fffae8) at m4.c:206
4654206 expand_input();
4655(@value{GDBP}) until
4656195 for ( ; argc > 0; NEXTARG) @{
474c8240 4657@end smallexample
c906108c
SS
4658
4659This happened because, for execution efficiency, the compiler had
4660generated code for the loop closure test at the end, rather than the
4661start, of the loop---even though the test in a C @code{for}-loop is
4662written before the body of the loop. The @code{until} command appeared
4663to step back to the beginning of the loop when it advanced to this
4664expression; however, it has not really gone to an earlier
4665statement---not in terms of the actual machine code.
4666
4667@code{until} with no argument works by means of single
4668instruction stepping, and hence is slower than @code{until} with an
4669argument.
4670
4671@item until @var{location}
4672@itemx u @var{location}
4673Continue running your program until either the specified location is
4674reached, or the current stack frame returns. @var{location} is any of
2a25a5ba
EZ
4675the forms described in @ref{Specify Location}.
4676This form of the command uses temporary breakpoints, and
c60eb6f1
EZ
4677hence is quicker than @code{until} without an argument. The specified
4678location is actually reached only if it is in the current frame. This
4679implies that @code{until} can be used to skip over recursive function
4680invocations. For instance in the code below, if the current location is
4681line @code{96}, issuing @code{until 99} will execute the program up to
db2e3e2e 4682line @code{99} in the same invocation of factorial, i.e., after the inner
c60eb6f1
EZ
4683invocations have returned.
4684
4685@smallexample
468694 int factorial (int value)
468795 @{
468896 if (value > 1) @{
468997 value *= factorial (value - 1);
469098 @}
469199 return (value);
4692100 @}
4693@end smallexample
4694
4695
4696@kindex advance @var{location}
4697@itemx advance @var{location}
09d4efe1 4698Continue running the program up to the given @var{location}. An argument is
2a25a5ba
EZ
4699required, which should be of one of the forms described in
4700@ref{Specify Location}.
4701Execution will also stop upon exit from the current stack
c60eb6f1
EZ
4702frame. This command is similar to @code{until}, but @code{advance} will
4703not skip over recursive function calls, and the target location doesn't
4704have to be in the same frame as the current one.
4705
c906108c
SS
4706
4707@kindex stepi
41afff9a 4708@kindex si @r{(@code{stepi})}
c906108c 4709@item stepi
96a2c332 4710@itemx stepi @var{arg}
c906108c
SS
4711@itemx si
4712Execute one machine instruction, then stop and return to the debugger.
4713
4714It is often useful to do @samp{display/i $pc} when stepping by machine
4715instructions. This makes @value{GDBN} automatically display the next
4716instruction to be executed, each time your program stops. @xref{Auto
79a6e687 4717Display,, Automatic Display}.
c906108c
SS
4718
4719An argument is a repeat count, as in @code{step}.
4720
4721@need 750
4722@kindex nexti
41afff9a 4723@kindex ni @r{(@code{nexti})}
c906108c 4724@item nexti
96a2c332 4725@itemx nexti @var{arg}
c906108c
SS
4726@itemx ni
4727Execute one machine instruction, but if it is a function call,
4728proceed until the function returns.
4729
4730An argument is a repeat count, as in @code{next}.
4731@end table
4732
6d2ebf8b 4733@node Signals
c906108c
SS
4734@section Signals
4735@cindex signals
4736
4737A signal is an asynchronous event that can happen in a program. The
4738operating system defines the possible kinds of signals, and gives each
4739kind a name and a number. For example, in Unix @code{SIGINT} is the
c8aa23ab 4740signal a program gets when you type an interrupt character (often @kbd{Ctrl-c});
c906108c
SS
4741@code{SIGSEGV} is the signal a program gets from referencing a place in
4742memory far away from all the areas in use; @code{SIGALRM} occurs when
4743the alarm clock timer goes off (which happens only if your program has
4744requested an alarm).
4745
4746@cindex fatal signals
4747Some signals, including @code{SIGALRM}, are a normal part of the
4748functioning of your program. Others, such as @code{SIGSEGV}, indicate
d4f3574e 4749errors; these signals are @dfn{fatal} (they kill your program immediately) if the
c906108c
SS
4750program has not specified in advance some other way to handle the signal.
4751@code{SIGINT} does not indicate an error in your program, but it is normally
4752fatal so it can carry out the purpose of the interrupt: to kill the program.
4753
4754@value{GDBN} has the ability to detect any occurrence of a signal in your
4755program. You can tell @value{GDBN} in advance what to do for each kind of
4756signal.
4757
4758@cindex handling signals
24f93129
EZ
4759Normally, @value{GDBN} is set up to let the non-erroneous signals like
4760@code{SIGALRM} be silently passed to your program
4761(so as not to interfere with their role in the program's functioning)
c906108c
SS
4762but to stop your program immediately whenever an error signal happens.
4763You can change these settings with the @code{handle} command.
4764
4765@table @code
4766@kindex info signals
09d4efe1 4767@kindex info handle
c906108c 4768@item info signals
96a2c332 4769@itemx info handle
c906108c
SS
4770Print a table of all the kinds of signals and how @value{GDBN} has been told to
4771handle each one. You can use this to see the signal numbers of all
4772the defined types of signals.
4773
45ac1734
EZ
4774@item info signals @var{sig}
4775Similar, but print information only about the specified signal number.
4776
d4f3574e 4777@code{info handle} is an alias for @code{info signals}.
c906108c
SS
4778
4779@kindex handle
45ac1734 4780@item handle @var{signal} @r{[}@var{keywords}@dots{}@r{]}
5ece1a18
EZ
4781Change the way @value{GDBN} handles signal @var{signal}. @var{signal}
4782can be the number of a signal or its name (with or without the
24f93129 4783@samp{SIG} at the beginning); a list of signal numbers of the form
5ece1a18 4784@samp{@var{low}-@var{high}}; or the word @samp{all}, meaning all the
45ac1734
EZ
4785known signals. Optional arguments @var{keywords}, described below,
4786say what change to make.
c906108c
SS
4787@end table
4788
4789@c @group
4790The keywords allowed by the @code{handle} command can be abbreviated.
4791Their full names are:
4792
4793@table @code
4794@item nostop
4795@value{GDBN} should not stop your program when this signal happens. It may
4796still print a message telling you that the signal has come in.
4797
4798@item stop
4799@value{GDBN} should stop your program when this signal happens. This implies
4800the @code{print} keyword as well.
4801
4802@item print
4803@value{GDBN} should print a message when this signal happens.
4804
4805@item noprint
4806@value{GDBN} should not mention the occurrence of the signal at all. This
4807implies the @code{nostop} keyword as well.
4808
4809@item pass
5ece1a18 4810@itemx noignore
c906108c
SS
4811@value{GDBN} should allow your program to see this signal; your program
4812can handle the signal, or else it may terminate if the signal is fatal
5ece1a18 4813and not handled. @code{pass} and @code{noignore} are synonyms.
c906108c
SS
4814
4815@item nopass
5ece1a18 4816@itemx ignore
c906108c 4817@value{GDBN} should not allow your program to see this signal.
5ece1a18 4818@code{nopass} and @code{ignore} are synonyms.
c906108c
SS
4819@end table
4820@c @end group
4821
d4f3574e
SS
4822When a signal stops your program, the signal is not visible to the
4823program until you
c906108c
SS
4824continue. Your program sees the signal then, if @code{pass} is in
4825effect for the signal in question @emph{at that time}. In other words,
4826after @value{GDBN} reports a signal, you can use the @code{handle}
4827command with @code{pass} or @code{nopass} to control whether your
4828program sees that signal when you continue.
4829
24f93129
EZ
4830The default is set to @code{nostop}, @code{noprint}, @code{pass} for
4831non-erroneous signals such as @code{SIGALRM}, @code{SIGWINCH} and
4832@code{SIGCHLD}, and to @code{stop}, @code{print}, @code{pass} for the
4833erroneous signals.
4834
c906108c
SS
4835You can also use the @code{signal} command to prevent your program from
4836seeing a signal, or cause it to see a signal it normally would not see,
4837or to give it any signal at any time. For example, if your program stopped
4838due to some sort of memory reference error, you might store correct
4839values into the erroneous variables and continue, hoping to see more
4840execution; but your program would probably terminate immediately as
4841a result of the fatal signal once it saw the signal. To prevent this,
4842you can continue with @samp{signal 0}. @xref{Signaling, ,Giving your
79a6e687 4843Program a Signal}.
c906108c 4844
4aa995e1
PA
4845@cindex extra signal information
4846@anchor{extra signal information}
4847
4848On some targets, @value{GDBN} can inspect extra signal information
4849associated with the intercepted signal, before it is actually
4850delivered to the program being debugged. This information is exported
4851by the convenience variable @code{$_siginfo}, and consists of data
4852that is passed by the kernel to the signal handler at the time of the
4853receipt of a signal. The data type of the information itself is
4854target dependent. You can see the data type using the @code{ptype
4855$_siginfo} command. On Unix systems, it typically corresponds to the
4856standard @code{siginfo_t} type, as defined in the @file{signal.h}
4857system header.
4858
4859Here's an example, on a @sc{gnu}/Linux system, printing the stray
4860referenced address that raised a segmentation fault.
4861
4862@smallexample
4863@group
4864(@value{GDBP}) continue
4865Program received signal SIGSEGV, Segmentation fault.
48660x0000000000400766 in main ()
486769 *(int *)p = 0;
4868(@value{GDBP}) ptype $_siginfo
4869type = struct @{
4870 int si_signo;
4871 int si_errno;
4872 int si_code;
4873 union @{
4874 int _pad[28];
4875 struct @{...@} _kill;
4876 struct @{...@} _timer;
4877 struct @{...@} _rt;
4878 struct @{...@} _sigchld;
4879 struct @{...@} _sigfault;
4880 struct @{...@} _sigpoll;
4881 @} _sifields;
4882@}
4883(@value{GDBP}) ptype $_siginfo._sifields._sigfault
4884type = struct @{
4885 void *si_addr;
4886@}
4887(@value{GDBP}) p $_siginfo._sifields._sigfault.si_addr
4888$1 = (void *) 0x7ffff7ff7000
4889@end group
4890@end smallexample
4891
4892Depending on target support, @code{$_siginfo} may also be writable.
4893
6d2ebf8b 4894@node Thread Stops
79a6e687 4895@section Stopping and Starting Multi-thread Programs
c906108c 4896
0606b73b
SL
4897@cindex stopped threads
4898@cindex threads, stopped
4899
4900@cindex continuing threads
4901@cindex threads, continuing
4902
4903@value{GDBN} supports debugging programs with multiple threads
4904(@pxref{Threads,, Debugging Programs with Multiple Threads}). There
4905are two modes of controlling execution of your program within the
4906debugger. In the default mode, referred to as @dfn{all-stop mode},
4907when any thread in your program stops (for example, at a breakpoint
4908or while being stepped), all other threads in the program are also stopped by
4909@value{GDBN}. On some targets, @value{GDBN} also supports
4910@dfn{non-stop mode}, in which other threads can continue to run freely while
4911you examine the stopped thread in the debugger.
4912
4913@menu
4914* All-Stop Mode:: All threads stop when GDB takes control
4915* Non-Stop Mode:: Other threads continue to execute
4916* Background Execution:: Running your program asynchronously
4917* Thread-Specific Breakpoints:: Controlling breakpoints
4918* Interrupted System Calls:: GDB may interfere with system calls
4919@end menu
4920
4921@node All-Stop Mode
4922@subsection All-Stop Mode
4923
4924@cindex all-stop mode
4925
4926In all-stop mode, whenever your program stops under @value{GDBN} for any reason,
4927@emph{all} threads of execution stop, not just the current thread. This
4928allows you to examine the overall state of the program, including
4929switching between threads, without worrying that things may change
4930underfoot.
4931
4932Conversely, whenever you restart the program, @emph{all} threads start
4933executing. @emph{This is true even when single-stepping} with commands
4934like @code{step} or @code{next}.
4935
4936In particular, @value{GDBN} cannot single-step all threads in lockstep.
4937Since thread scheduling is up to your debugging target's operating
4938system (not controlled by @value{GDBN}), other threads may
4939execute more than one statement while the current thread completes a
4940single step. Moreover, in general other threads stop in the middle of a
4941statement, rather than at a clean statement boundary, when the program
4942stops.
4943
4944You might even find your program stopped in another thread after
4945continuing or even single-stepping. This happens whenever some other
4946thread runs into a breakpoint, a signal, or an exception before the
4947first thread completes whatever you requested.
4948
4949@cindex automatic thread selection
4950@cindex switching threads automatically
4951@cindex threads, automatic switching
4952Whenever @value{GDBN} stops your program, due to a breakpoint or a
4953signal, it automatically selects the thread where that breakpoint or
4954signal happened. @value{GDBN} alerts you to the context switch with a
4955message such as @samp{[Switching to Thread @var{n}]} to identify the
4956thread.
4957
4958On some OSes, you can modify @value{GDBN}'s default behavior by
4959locking the OS scheduler to allow only a single thread to run.
4960
4961@table @code
4962@item set scheduler-locking @var{mode}
4963@cindex scheduler locking mode
4964@cindex lock scheduler
4965Set the scheduler locking mode. If it is @code{off}, then there is no
4966locking and any thread may run at any time. If @code{on}, then only the
4967current thread may run when the inferior is resumed. The @code{step}
4968mode optimizes for single-stepping; it prevents other threads
4969from preempting the current thread while you are stepping, so that
4970the focus of debugging does not change unexpectedly.
4971Other threads only rarely (or never) get a chance to run
4972when you step. They are more likely to run when you @samp{next} over a
4973function call, and they are completely free to run when you use commands
4974like @samp{continue}, @samp{until}, or @samp{finish}. However, unless another
4975thread hits a breakpoint during its timeslice, @value{GDBN} does not change
4976the current thread away from the thread that you are debugging.
4977
4978@item show scheduler-locking
4979Display the current scheduler locking mode.
4980@end table
4981
d4db2f36
PA
4982@cindex resume threads of multiple processes simultaneously
4983By default, when you issue one of the execution commands such as
4984@code{continue}, @code{next} or @code{step}, @value{GDBN} allows only
4985threads of the current inferior to run. For example, if @value{GDBN}
4986is attached to two inferiors, each with two threads, the
4987@code{continue} command resumes only the two threads of the current
4988inferior. This is useful, for example, when you debug a program that
4989forks and you want to hold the parent stopped (so that, for instance,
4990it doesn't run to exit), while you debug the child. In other
4991situations, you may not be interested in inspecting the current state
4992of any of the processes @value{GDBN} is attached to, and you may want
4993to resume them all until some breakpoint is hit. In the latter case,
4994you can instruct @value{GDBN} to allow all threads of all the
4995inferiors to run with the @w{@code{set schedule-multiple}} command.
4996
4997@table @code
4998@kindex set schedule-multiple
4999@item set schedule-multiple
5000Set the mode for allowing threads of multiple processes to be resumed
5001when an execution command is issued. When @code{on}, all threads of
5002all processes are allowed to run. When @code{off}, only the threads
5003of the current process are resumed. The default is @code{off}. The
5004@code{scheduler-locking} mode takes precedence when set to @code{on},
5005or while you are stepping and set to @code{step}.
5006
5007@item show schedule-multiple
5008Display the current mode for resuming the execution of threads of
5009multiple processes.
5010@end table
5011
0606b73b
SL
5012@node Non-Stop Mode
5013@subsection Non-Stop Mode
5014
5015@cindex non-stop mode
5016
5017@c This section is really only a place-holder, and needs to be expanded
5018@c with more details.
5019
5020For some multi-threaded targets, @value{GDBN} supports an optional
5021mode of operation in which you can examine stopped program threads in
5022the debugger while other threads continue to execute freely. This
5023minimizes intrusion when debugging live systems, such as programs
5024where some threads have real-time constraints or must continue to
5025respond to external events. This is referred to as @dfn{non-stop} mode.
5026
5027In non-stop mode, when a thread stops to report a debugging event,
5028@emph{only} that thread is stopped; @value{GDBN} does not stop other
5029threads as well, in contrast to the all-stop mode behavior. Additionally,
5030execution commands such as @code{continue} and @code{step} apply by default
5031only to the current thread in non-stop mode, rather than all threads as
5032in all-stop mode. This allows you to control threads explicitly in
5033ways that are not possible in all-stop mode --- for example, stepping
5034one thread while allowing others to run freely, stepping
5035one thread while holding all others stopped, or stepping several threads
5036independently and simultaneously.
5037
5038To enter non-stop mode, use this sequence of commands before you run
5039or attach to your program:
5040
0606b73b
SL
5041@smallexample
5042# Enable the async interface.
c6ebd6cf 5043set target-async 1
0606b73b 5044
0606b73b
SL
5045# If using the CLI, pagination breaks non-stop.
5046set pagination off
5047
5048# Finally, turn it on!
5049set non-stop on
5050@end smallexample
5051
5052You can use these commands to manipulate the non-stop mode setting:
5053
5054@table @code
5055@kindex set non-stop
5056@item set non-stop on
5057Enable selection of non-stop mode.
5058@item set non-stop off
5059Disable selection of non-stop mode.
5060@kindex show non-stop
5061@item show non-stop
5062Show the current non-stop enablement setting.
5063@end table
5064
5065Note these commands only reflect whether non-stop mode is enabled,
5066not whether the currently-executing program is being run in non-stop mode.
5067In particular, the @code{set non-stop} preference is only consulted when
5068@value{GDBN} starts or connects to the target program, and it is generally
5069not possible to switch modes once debugging has started. Furthermore,
5070since not all targets support non-stop mode, even when you have enabled
5071non-stop mode, @value{GDBN} may still fall back to all-stop operation by
5072default.
5073
5074In non-stop mode, all execution commands apply only to the current thread
5075by default. That is, @code{continue} only continues one thread.
5076To continue all threads, issue @code{continue -a} or @code{c -a}.
5077
5078You can use @value{GDBN}'s background execution commands
5079(@pxref{Background Execution}) to run some threads in the background
5080while you continue to examine or step others from @value{GDBN}.
5081The MI execution commands (@pxref{GDB/MI Program Execution}) are
5082always executed asynchronously in non-stop mode.
5083
5084Suspending execution is done with the @code{interrupt} command when
5085running in the background, or @kbd{Ctrl-c} during foreground execution.
5086In all-stop mode, this stops the whole process;
5087but in non-stop mode the interrupt applies only to the current thread.
5088To stop the whole program, use @code{interrupt -a}.
5089
5090Other execution commands do not currently support the @code{-a} option.
5091
5092In non-stop mode, when a thread stops, @value{GDBN} doesn't automatically make
5093that thread current, as it does in all-stop mode. This is because the
5094thread stop notifications are asynchronous with respect to @value{GDBN}'s
5095command interpreter, and it would be confusing if @value{GDBN} unexpectedly
5096changed to a different thread just as you entered a command to operate on the
5097previously current thread.
5098
5099@node Background Execution
5100@subsection Background Execution
5101
5102@cindex foreground execution
5103@cindex background execution
5104@cindex asynchronous execution
5105@cindex execution, foreground, background and asynchronous
5106
5107@value{GDBN}'s execution commands have two variants: the normal
5108foreground (synchronous) behavior, and a background
5109(asynchronous) behavior. In foreground execution, @value{GDBN} waits for
5110the program to report that some thread has stopped before prompting for
5111another command. In background execution, @value{GDBN} immediately gives
5112a command prompt so that you can issue other commands while your program runs.
5113
32fc0df9
PA
5114You need to explicitly enable asynchronous mode before you can use
5115background execution commands. You can use these commands to
5116manipulate the asynchronous mode setting:
5117
5118@table @code
5119@kindex set target-async
5120@item set target-async on
5121Enable asynchronous mode.
5122@item set target-async off
5123Disable asynchronous mode.
5124@kindex show target-async
5125@item show target-async
5126Show the current target-async setting.
5127@end table
5128
5129If the target doesn't support async mode, @value{GDBN} issues an error
5130message if you attempt to use the background execution commands.
5131
0606b73b
SL
5132To specify background execution, add a @code{&} to the command. For example,
5133the background form of the @code{continue} command is @code{continue&}, or
5134just @code{c&}. The execution commands that accept background execution
5135are:
5136
5137@table @code
5138@kindex run&
5139@item run
5140@xref{Starting, , Starting your Program}.
5141
5142@item attach
5143@kindex attach&
5144@xref{Attach, , Debugging an Already-running Process}.
5145
5146@item step
5147@kindex step&
5148@xref{Continuing and Stepping, step}.
5149
5150@item stepi
5151@kindex stepi&
5152@xref{Continuing and Stepping, stepi}.
5153
5154@item next
5155@kindex next&
5156@xref{Continuing and Stepping, next}.
5157
7ce58dd2
DE
5158@item nexti
5159@kindex nexti&
5160@xref{Continuing and Stepping, nexti}.
5161
0606b73b
SL
5162@item continue
5163@kindex continue&
5164@xref{Continuing and Stepping, continue}.
5165
5166@item finish
5167@kindex finish&
5168@xref{Continuing and Stepping, finish}.
5169
5170@item until
5171@kindex until&
5172@xref{Continuing and Stepping, until}.
5173
5174@end table
5175
5176Background execution is especially useful in conjunction with non-stop
5177mode for debugging programs with multiple threads; see @ref{Non-Stop Mode}.
5178However, you can also use these commands in the normal all-stop mode with
5179the restriction that you cannot issue another execution command until the
5180previous one finishes. Examples of commands that are valid in all-stop
5181mode while the program is running include @code{help} and @code{info break}.
5182
5183You can interrupt your program while it is running in the background by
5184using the @code{interrupt} command.
5185
5186@table @code
5187@kindex interrupt
5188@item interrupt
5189@itemx interrupt -a
5190
5191Suspend execution of the running program. In all-stop mode,
5192@code{interrupt} stops the whole process, but in non-stop mode, it stops
5193only the current thread. To stop the whole program in non-stop mode,
5194use @code{interrupt -a}.
5195@end table
5196
0606b73b
SL
5197@node Thread-Specific Breakpoints
5198@subsection Thread-Specific Breakpoints
5199
c906108c 5200When your program has multiple threads (@pxref{Threads,, Debugging
79a6e687 5201Programs with Multiple Threads}), you can choose whether to set
c906108c
SS
5202breakpoints on all threads, or on a particular thread.
5203
5204@table @code
5205@cindex breakpoints and threads
5206@cindex thread breakpoints
5207@kindex break @dots{} thread @var{threadno}
5208@item break @var{linespec} thread @var{threadno}
5209@itemx break @var{linespec} thread @var{threadno} if @dots{}
5210@var{linespec} specifies source lines; there are several ways of
2a25a5ba
EZ
5211writing them (@pxref{Specify Location}), but the effect is always to
5212specify some source line.
c906108c
SS
5213
5214Use the qualifier @samp{thread @var{threadno}} with a breakpoint command
5215to specify that you only want @value{GDBN} to stop the program when a
5216particular thread reaches this breakpoint. @var{threadno} is one of the
5217numeric thread identifiers assigned by @value{GDBN}, shown in the first
5218column of the @samp{info threads} display.
5219
5220If you do not specify @samp{thread @var{threadno}} when you set a
5221breakpoint, the breakpoint applies to @emph{all} threads of your
5222program.
5223
5224You can use the @code{thread} qualifier on conditional breakpoints as
b6199126
DJ
5225well; in this case, place @samp{thread @var{threadno}} before or
5226after the breakpoint condition, like this:
c906108c
SS
5227
5228@smallexample
2df3850c 5229(@value{GDBP}) break frik.c:13 thread 28 if bartab > lim
c906108c
SS
5230@end smallexample
5231
5232@end table
5233
0606b73b
SL
5234@node Interrupted System Calls
5235@subsection Interrupted System Calls
c906108c 5236
36d86913
MC
5237@cindex thread breakpoints and system calls
5238@cindex system calls and thread breakpoints
5239@cindex premature return from system calls
0606b73b
SL
5240There is an unfortunate side effect when using @value{GDBN} to debug
5241multi-threaded programs. If one thread stops for a
36d86913
MC
5242breakpoint, or for some other reason, and another thread is blocked in a
5243system call, then the system call may return prematurely. This is a
5244consequence of the interaction between multiple threads and the signals
5245that @value{GDBN} uses to implement breakpoints and other events that
5246stop execution.
5247
5248To handle this problem, your program should check the return value of
5249each system call and react appropriately. This is good programming
5250style anyways.
5251
5252For example, do not write code like this:
5253
5254@smallexample
5255 sleep (10);
5256@end smallexample
5257
5258The call to @code{sleep} will return early if a different thread stops
5259at a breakpoint or for some other reason.
5260
5261Instead, write this:
5262
5263@smallexample
5264 int unslept = 10;
5265 while (unslept > 0)
5266 unslept = sleep (unslept);
5267@end smallexample
5268
5269A system call is allowed to return early, so the system is still
5270conforming to its specification. But @value{GDBN} does cause your
5271multi-threaded program to behave differently than it would without
5272@value{GDBN}.
5273
5274Also, @value{GDBN} uses internal breakpoints in the thread library to
5275monitor certain events such as thread creation and thread destruction.
5276When such an event happens, a system call in another thread may return
5277prematurely, even though your program does not appear to stop.
5278
c906108c 5279
bacec72f
MS
5280@node Reverse Execution
5281@chapter Running programs backward
5282@cindex reverse execution
5283@cindex running programs backward
5284
5285When you are debugging a program, it is not unusual to realize that
5286you have gone too far, and some event of interest has already happened.
5287If the target environment supports it, @value{GDBN} can allow you to
5288``rewind'' the program by running it backward.
5289
5290A target environment that supports reverse execution should be able
5291to ``undo'' the changes in machine state that have taken place as the
5292program was executing normally. Variables, registers etc.@: should
5293revert to their previous values. Obviously this requires a great
5294deal of sophistication on the part of the target environment; not
5295all target environments can support reverse execution.
5296
5297When a program is executed in reverse, the instructions that
5298have most recently been executed are ``un-executed'', in reverse
5299order. The program counter runs backward, following the previous
5300thread of execution in reverse. As each instruction is ``un-executed'',
5301the values of memory and/or registers that were changed by that
5302instruction are reverted to their previous states. After executing
5303a piece of source code in reverse, all side effects of that code
5304should be ``undone'', and all variables should be returned to their
5305prior values@footnote{
5306Note that some side effects are easier to undo than others. For instance,
5307memory and registers are relatively easy, but device I/O is hard. Some
5308targets may be able undo things like device I/O, and some may not.
5309
5310The contract between @value{GDBN} and the reverse executing target
5311requires only that the target do something reasonable when
5312@value{GDBN} tells it to execute backwards, and then report the
5313results back to @value{GDBN}. Whatever the target reports back to
5314@value{GDBN}, @value{GDBN} will report back to the user. @value{GDBN}
5315assumes that the memory and registers that the target reports are in a
5316consistant state, but @value{GDBN} accepts whatever it is given.
5317}.
5318
5319If you are debugging in a target environment that supports
5320reverse execution, @value{GDBN} provides the following commands.
5321
5322@table @code
5323@kindex reverse-continue
5324@kindex rc @r{(@code{reverse-continue})}
5325@item reverse-continue @r{[}@var{ignore-count}@r{]}
5326@itemx rc @r{[}@var{ignore-count}@r{]}
5327Beginning at the point where your program last stopped, start executing
5328in reverse. Reverse execution will stop for breakpoints and synchronous
5329exceptions (signals), just like normal execution. Behavior of
5330asynchronous signals depends on the target environment.
5331
5332@kindex reverse-step
5333@kindex rs @r{(@code{step})}
5334@item reverse-step @r{[}@var{count}@r{]}
5335Run the program backward until control reaches the start of a
5336different source line; then stop it, and return control to @value{GDBN}.
5337
5338Like the @code{step} command, @code{reverse-step} will only stop
5339at the beginning of a source line. It ``un-executes'' the previously
5340executed source line. If the previous source line included calls to
5341debuggable functions, @code{reverse-step} will step (backward) into
5342the called function, stopping at the beginning of the @emph{last}
5343statement in the called function (typically a return statement).
5344
5345Also, as with the @code{step} command, if non-debuggable functions are
5346called, @code{reverse-step} will run thru them backward without stopping.
5347
5348@kindex reverse-stepi
5349@kindex rsi @r{(@code{reverse-stepi})}
5350@item reverse-stepi @r{[}@var{count}@r{]}
5351Reverse-execute one machine instruction. Note that the instruction
5352to be reverse-executed is @emph{not} the one pointed to by the program
5353counter, but the instruction executed prior to that one. For instance,
5354if the last instruction was a jump, @code{reverse-stepi} will take you
5355back from the destination of the jump to the jump instruction itself.
5356
5357@kindex reverse-next
5358@kindex rn @r{(@code{reverse-next})}
5359@item reverse-next @r{[}@var{count}@r{]}
5360Run backward to the beginning of the previous line executed in
5361the current (innermost) stack frame. If the line contains function
5362calls, they will be ``un-executed'' without stopping. Starting from
5363the first line of a function, @code{reverse-next} will take you back
5364to the caller of that function, @emph{before} the function was called,
5365just as the normal @code{next} command would take you from the last
5366line of a function back to its return to its caller
16af530a 5367@footnote{Unless the code is too heavily optimized.}.
bacec72f
MS
5368
5369@kindex reverse-nexti
5370@kindex rni @r{(@code{reverse-nexti})}
5371@item reverse-nexti @r{[}@var{count}@r{]}
5372Like @code{nexti}, @code{reverse-nexti} executes a single instruction
5373in reverse, except that called functions are ``un-executed'' atomically.
5374That is, if the previously executed instruction was a return from
540aa8e7 5375another function, @code{reverse-nexti} will continue to execute
bacec72f
MS
5376in reverse until the call to that function (from the current stack
5377frame) is reached.
5378
5379@kindex reverse-finish
5380@item reverse-finish
5381Just as the @code{finish} command takes you to the point where the
5382current function returns, @code{reverse-finish} takes you to the point
5383where it was called. Instead of ending up at the end of the current
5384function invocation, you end up at the beginning.
5385
5386@kindex set exec-direction
5387@item set exec-direction
5388Set the direction of target execution.
5389@itemx set exec-direction reverse
5390@cindex execute forward or backward in time
5391@value{GDBN} will perform all execution commands in reverse, until the
5392exec-direction mode is changed to ``forward''. Affected commands include
5393@code{step, stepi, next, nexti, continue, and finish}. The @code{return}
5394command cannot be used in reverse mode.
5395@item set exec-direction forward
5396@value{GDBN} will perform all execution commands in the normal fashion.
5397This is the default.
5398@end table
5399
c906108c 5400
a2311334
EZ
5401@node Process Record and Replay
5402@chapter Recording Inferior's Execution and Replaying It
53cc454a
HZ
5403@cindex process record and replay
5404@cindex recording inferior's execution and replaying it
5405
8e05493c
EZ
5406On some platforms, @value{GDBN} provides a special @dfn{process record
5407and replay} target that can record a log of the process execution, and
5408replay it later with both forward and reverse execution commands.
a2311334
EZ
5409
5410@cindex replay mode
5411When this target is in use, if the execution log includes the record
5412for the next instruction, @value{GDBN} will debug in @dfn{replay
5413mode}. In the replay mode, the inferior does not really execute code
5414instructions. Instead, all the events that normally happen during
5415code execution are taken from the execution log. While code is not
5416really executed in replay mode, the values of registers (including the
5417program counter register) and the memory of the inferior are still
8e05493c
EZ
5418changed as they normally would. Their contents are taken from the
5419execution log.
a2311334
EZ
5420
5421@cindex record mode
5422If the record for the next instruction is not in the execution log,
5423@value{GDBN} will debug in @dfn{record mode}. In this mode, the
5424inferior executes normally, and @value{GDBN} records the execution log
5425for future replay.
5426
8e05493c
EZ
5427The process record and replay target supports reverse execution
5428(@pxref{Reverse Execution}), even if the platform on which the
5429inferior runs does not. However, the reverse execution is limited in
5430this case by the range of the instructions recorded in the execution
5431log. In other words, reverse execution on platforms that don't
5432support it directly can only be done in the replay mode.
5433
5434When debugging in the reverse direction, @value{GDBN} will work in
5435replay mode as long as the execution log includes the record for the
5436previous instruction; otherwise, it will work in record mode, if the
5437platform supports reverse execution, or stop if not.
5438
a2311334
EZ
5439For architecture environments that support process record and replay,
5440@value{GDBN} provides the following commands:
53cc454a
HZ
5441
5442@table @code
5443@kindex target record
5444@kindex record
5445@kindex rec
5446@item target record
a2311334
EZ
5447This command starts the process record and replay target. The process
5448record and replay target can only debug a process that is already
5449running. Therefore, you need first to start the process with the
5450@kbd{run} or @kbd{start} commands, and then start the recording with
5451the @kbd{target record} command.
5452
5453Both @code{record} and @code{rec} are aliases of @code{target record}.
5454
5455@cindex displaced stepping, and process record and replay
5456Displaced stepping (@pxref{Maintenance Commands,, displaced stepping})
5457will be automatically disabled when process record and replay target
5458is started. That's because the process record and replay target
5459doesn't support displaced stepping.
5460
5461@cindex non-stop mode, and process record and replay
5462@cindex asynchronous execution, and process record and replay
5463If the inferior is in the non-stop mode (@pxref{Non-Stop Mode}) or in
5464the asynchronous execution mode (@pxref{Background Execution}), the
5465process record and replay target cannot be started because it doesn't
5466support these two modes.
53cc454a
HZ
5467
5468@kindex record stop
5469@kindex rec s
5470@item record stop
a2311334
EZ
5471Stop the process record and replay target. When process record and
5472replay target stops, the entire execution log will be deleted and the
5473inferior will either be terminated, or will remain in its final state.
53cc454a 5474
a2311334
EZ
5475When you stop the process record and replay target in record mode (at
5476the end of the execution log), the inferior will be stopped at the
5477next instruction that would have been recorded. In other words, if
5478you record for a while and then stop recording, the inferior process
5479will be left in the same state as if the recording never happened.
53cc454a 5480
a2311334
EZ
5481On the other hand, if the process record and replay target is stopped
5482while in replay mode (that is, not at the end of the execution log,
5483but at some earlier point), the inferior process will become ``live''
5484at that earlier state, and it will then be possible to continue the
5485usual ``live'' debugging of the process from that state.
53cc454a 5486
a2311334
EZ
5487When the inferior process exits, or @value{GDBN} detaches from it,
5488process record and replay target will automatically stop itself.
53cc454a
HZ
5489
5490@kindex set record insn-number-max
5491@item set record insn-number-max @var{limit}
5492Set the limit of instructions to be recorded. Default value is 200000.
5493
a2311334
EZ
5494If @var{limit} is a positive number, then @value{GDBN} will start
5495deleting instructions from the log once the number of the record
5496instructions becomes greater than @var{limit}. For every new recorded
5497instruction, @value{GDBN} will delete the earliest recorded
5498instruction to keep the number of recorded instructions at the limit.
5499(Since deleting recorded instructions loses information, @value{GDBN}
5500lets you control what happens when the limit is reached, by means of
5501the @code{stop-at-limit} option, described below.)
53cc454a 5502
a2311334
EZ
5503If @var{limit} is zero, @value{GDBN} will never delete recorded
5504instructions from the execution log. The number of recorded
5505instructions is unlimited in this case.
53cc454a
HZ
5506
5507@kindex show record insn-number-max
5508@item show record insn-number-max
a2311334 5509Show the limit of instructions to be recorded.
53cc454a
HZ
5510
5511@kindex set record stop-at-limit
a2311334
EZ
5512@item set record stop-at-limit
5513Control the behavior when the number of recorded instructions reaches
5514the limit. If ON (the default), @value{GDBN} will stop when the limit
5515is reached for the first time and ask you whether you want to stop the
5516inferior or continue running it and recording the execution log. If
5517you decide to continue recording, each new recorded instruction will
5518cause the oldest one to be deleted.
53cc454a 5519
a2311334
EZ
5520If this option is OFF, @value{GDBN} will automatically delete the
5521oldest record to make room for each new one, without asking.
53cc454a
HZ
5522
5523@kindex show record stop-at-limit
5524@item show record stop-at-limit
a2311334 5525Show the current setting of @code{stop-at-limit}.
53cc454a 5526
29153c24
MS
5527@kindex info record
5528@item info record
5529Show various statistics about the state of process record and its
5530in-memory execution log buffer, including:
5531
5532@itemize @bullet
5533@item
5534Whether in record mode or replay mode.
5535@item
5536Lowest recorded instruction number (counting from when the current execution log started recording instructions).
5537@item
5538Highest recorded instruction number.
5539@item
5540Current instruction about to be replayed (if in replay mode).
5541@item
5542Number of instructions contained in the execution log.
5543@item
5544Maximum number of instructions that may be contained in the execution log.
5545@end itemize
53cc454a
HZ
5546
5547@kindex record delete
5548@kindex rec del
5549@item record delete
a2311334 5550When record target runs in replay mode (``in the past''), delete the
53cc454a 5551subsequent execution log and begin to record a new execution log starting
a2311334 5552from the current address. This means you will abandon the previously
53cc454a
HZ
5553recorded ``future'' and begin recording a new ``future''.
5554@end table
5555
5556
6d2ebf8b 5557@node Stack
c906108c
SS
5558@chapter Examining the Stack
5559
5560When your program has stopped, the first thing you need to know is where it
5561stopped and how it got there.
5562
5563@cindex call stack
5d161b24
DB
5564Each time your program performs a function call, information about the call
5565is generated.
5566That information includes the location of the call in your program,
5567the arguments of the call,
c906108c 5568and the local variables of the function being called.
5d161b24 5569The information is saved in a block of data called a @dfn{stack frame}.
c906108c
SS
5570The stack frames are allocated in a region of memory called the @dfn{call
5571stack}.
5572
5573When your program stops, the @value{GDBN} commands for examining the
5574stack allow you to see all of this information.
5575
5576@cindex selected frame
5577One of the stack frames is @dfn{selected} by @value{GDBN} and many
5578@value{GDBN} commands refer implicitly to the selected frame. In
5579particular, whenever you ask @value{GDBN} for the value of a variable in
5580your program, the value is found in the selected frame. There are
5581special @value{GDBN} commands to select whichever frame you are
79a6e687 5582interested in. @xref{Selection, ,Selecting a Frame}.
c906108c
SS
5583
5584When your program stops, @value{GDBN} automatically selects the
5d161b24 5585currently executing frame and describes it briefly, similar to the
79a6e687 5586@code{frame} command (@pxref{Frame Info, ,Information about a Frame}).
c906108c
SS
5587
5588@menu
5589* Frames:: Stack frames
5590* Backtrace:: Backtraces
5591* Selection:: Selecting a frame
5592* Frame Info:: Information on a frame
c906108c
SS
5593
5594@end menu
5595
6d2ebf8b 5596@node Frames
79a6e687 5597@section Stack Frames
c906108c 5598
d4f3574e 5599@cindex frame, definition
c906108c
SS
5600@cindex stack frame
5601The call stack is divided up into contiguous pieces called @dfn{stack
5602frames}, or @dfn{frames} for short; each frame is the data associated
5603with one call to one function. The frame contains the arguments given
5604to the function, the function's local variables, and the address at
5605which the function is executing.
5606
5607@cindex initial frame
5608@cindex outermost frame
5609@cindex innermost frame
5610When your program is started, the stack has only one frame, that of the
5611function @code{main}. This is called the @dfn{initial} frame or the
5612@dfn{outermost} frame. Each time a function is called, a new frame is
5613made. Each time a function returns, the frame for that function invocation
5614is eliminated. If a function is recursive, there can be many frames for
5615the same function. The frame for the function in which execution is
5616actually occurring is called the @dfn{innermost} frame. This is the most
5617recently created of all the stack frames that still exist.
5618
5619@cindex frame pointer
5620Inside your program, stack frames are identified by their addresses. A
5621stack frame consists of many bytes, each of which has its own address; each
5622kind of computer has a convention for choosing one byte whose
5623address serves as the address of the frame. Usually this address is kept
e09f16f9
EZ
5624in a register called the @dfn{frame pointer register}
5625(@pxref{Registers, $fp}) while execution is going on in that frame.
c906108c
SS
5626
5627@cindex frame number
5628@value{GDBN} assigns numbers to all existing stack frames, starting with
5629zero for the innermost frame, one for the frame that called it,
5630and so on upward. These numbers do not really exist in your program;
5631they are assigned by @value{GDBN} to give you a way of designating stack
5632frames in @value{GDBN} commands.
5633
6d2ebf8b
SS
5634@c The -fomit-frame-pointer below perennially causes hbox overflow
5635@c underflow problems.
c906108c
SS
5636@cindex frameless execution
5637Some compilers provide a way to compile functions so that they operate
e22ea452 5638without stack frames. (For example, the @value{NGCC} option
474c8240 5639@smallexample
6d2ebf8b 5640@samp{-fomit-frame-pointer}
474c8240 5641@end smallexample
6d2ebf8b 5642generates functions without a frame.)
c906108c
SS
5643This is occasionally done with heavily used library functions to save
5644the frame setup time. @value{GDBN} has limited facilities for dealing
5645with these function invocations. If the innermost function invocation
5646has no stack frame, @value{GDBN} nevertheless regards it as though
5647it had a separate frame, which is numbered zero as usual, allowing
5648correct tracing of the function call chain. However, @value{GDBN} has
5649no provision for frameless functions elsewhere in the stack.
5650
5651@table @code
d4f3574e 5652@kindex frame@r{, command}
41afff9a 5653@cindex current stack frame
c906108c 5654@item frame @var{args}
5d161b24 5655The @code{frame} command allows you to move from one stack frame to another,
c906108c 5656and to print the stack frame you select. @var{args} may be either the
5d161b24
DB
5657address of the frame or the stack frame number. Without an argument,
5658@code{frame} prints the current stack frame.
c906108c
SS
5659
5660@kindex select-frame
41afff9a 5661@cindex selecting frame silently
c906108c
SS
5662@item select-frame
5663The @code{select-frame} command allows you to move from one stack frame
5664to another without printing the frame. This is the silent version of
5665@code{frame}.
5666@end table
5667
6d2ebf8b 5668@node Backtrace
c906108c
SS
5669@section Backtraces
5670
09d4efe1
EZ
5671@cindex traceback
5672@cindex call stack traces
c906108c
SS
5673A backtrace is a summary of how your program got where it is. It shows one
5674line per frame, for many frames, starting with the currently executing
5675frame (frame zero), followed by its caller (frame one), and on up the
5676stack.
5677
5678@table @code
5679@kindex backtrace
41afff9a 5680@kindex bt @r{(@code{backtrace})}
c906108c
SS
5681@item backtrace
5682@itemx bt
5683Print a backtrace of the entire stack: one line per frame for all
5684frames in the stack.
5685
5686You can stop the backtrace at any time by typing the system interrupt
c8aa23ab 5687character, normally @kbd{Ctrl-c}.
c906108c
SS
5688
5689@item backtrace @var{n}
5690@itemx bt @var{n}
5691Similar, but print only the innermost @var{n} frames.
5692
5693@item backtrace -@var{n}
5694@itemx bt -@var{n}
5695Similar, but print only the outermost @var{n} frames.
0f061b69
NR
5696
5697@item backtrace full
0f061b69 5698@itemx bt full
dd74f6ae
NR
5699@itemx bt full @var{n}
5700@itemx bt full -@var{n}
e7109c7e 5701Print the values of the local variables also. @var{n} specifies the
286ba84d 5702number of frames to print, as described above.
c906108c
SS
5703@end table
5704
5705@kindex where
5706@kindex info stack
c906108c
SS
5707The names @code{where} and @code{info stack} (abbreviated @code{info s})
5708are additional aliases for @code{backtrace}.
5709
839c27b7
EZ
5710@cindex multiple threads, backtrace
5711In a multi-threaded program, @value{GDBN} by default shows the
5712backtrace only for the current thread. To display the backtrace for
5713several or all of the threads, use the command @code{thread apply}
5714(@pxref{Threads, thread apply}). For example, if you type @kbd{thread
5715apply all backtrace}, @value{GDBN} will display the backtrace for all
5716the threads; this is handy when you debug a core dump of a
5717multi-threaded program.
5718
c906108c
SS
5719Each line in the backtrace shows the frame number and the function name.
5720The program counter value is also shown---unless you use @code{set
5721print address off}. The backtrace also shows the source file name and
5722line number, as well as the arguments to the function. The program
5723counter value is omitted if it is at the beginning of the code for that
5724line number.
5725
5726Here is an example of a backtrace. It was made with the command
5727@samp{bt 3}, so it shows the innermost three frames.
5728
5729@smallexample
5730@group
5d161b24 5731#0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8)
c906108c 5732 at builtin.c:993
4f5376b2 5733#1 0x6e38 in expand_macro (sym=0x2b600, data=...) at macro.c:242
c906108c
SS
5734#2 0x6840 in expand_token (obs=0x0, t=177664, td=0xf7fffb08)
5735 at macro.c:71
5736(More stack frames follow...)
5737@end group
5738@end smallexample
5739
5740@noindent
5741The display for frame zero does not begin with a program counter
5742value, indicating that your program has stopped at the beginning of the
5743code for line @code{993} of @code{builtin.c}.
5744
4f5376b2
JB
5745@noindent
5746The value of parameter @code{data} in frame 1 has been replaced by
5747@code{@dots{}}. By default, @value{GDBN} prints the value of a parameter
5748only if it is a scalar (integer, pointer, enumeration, etc). See command
5749@kbd{set print frame-arguments} in @ref{Print Settings} for more details
5750on how to configure the way function parameter values are printed.
5751
18999be5
EZ
5752@cindex value optimized out, in backtrace
5753@cindex function call arguments, optimized out
5754If your program was compiled with optimizations, some compilers will
5755optimize away arguments passed to functions if those arguments are
5756never used after the call. Such optimizations generate code that
5757passes arguments through registers, but doesn't store those arguments
5758in the stack frame. @value{GDBN} has no way of displaying such
5759arguments in stack frames other than the innermost one. Here's what
5760such a backtrace might look like:
5761
5762@smallexample
5763@group
5764#0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8)
5765 at builtin.c:993
5766#1 0x6e38 in expand_macro (sym=<value optimized out>) at macro.c:242
5767#2 0x6840 in expand_token (obs=0x0, t=<value optimized out>, td=0xf7fffb08)
5768 at macro.c:71
5769(More stack frames follow...)
5770@end group
5771@end smallexample
5772
5773@noindent
5774The values of arguments that were not saved in their stack frames are
5775shown as @samp{<value optimized out>}.
5776
5777If you need to display the values of such optimized-out arguments,
5778either deduce that from other variables whose values depend on the one
5779you are interested in, or recompile without optimizations.
5780
a8f24a35
EZ
5781@cindex backtrace beyond @code{main} function
5782@cindex program entry point
5783@cindex startup code, and backtrace
25d29d70
AC
5784Most programs have a standard user entry point---a place where system
5785libraries and startup code transition into user code. For C this is
d416eeec
EZ
5786@code{main}@footnote{
5787Note that embedded programs (the so-called ``free-standing''
5788environment) are not required to have a @code{main} function as the
5789entry point. They could even have multiple entry points.}.
5790When @value{GDBN} finds the entry function in a backtrace
25d29d70
AC
5791it will terminate the backtrace, to avoid tracing into highly
5792system-specific (and generally uninteresting) code.
5793
5794If you need to examine the startup code, or limit the number of levels
5795in a backtrace, you can change this behavior:
95f90d25
DJ
5796
5797@table @code
25d29d70
AC
5798@item set backtrace past-main
5799@itemx set backtrace past-main on
4644b6e3 5800@kindex set backtrace
25d29d70
AC
5801Backtraces will continue past the user entry point.
5802
5803@item set backtrace past-main off
95f90d25
DJ
5804Backtraces will stop when they encounter the user entry point. This is the
5805default.
5806
25d29d70 5807@item show backtrace past-main
4644b6e3 5808@kindex show backtrace
25d29d70
AC
5809Display the current user entry point backtrace policy.
5810
2315ffec
RC
5811@item set backtrace past-entry
5812@itemx set backtrace past-entry on
a8f24a35 5813Backtraces will continue past the internal entry point of an application.
2315ffec
RC
5814This entry point is encoded by the linker when the application is built,
5815and is likely before the user entry point @code{main} (or equivalent) is called.
5816
5817@item set backtrace past-entry off
d3e8051b 5818Backtraces will stop when they encounter the internal entry point of an
2315ffec
RC
5819application. This is the default.
5820
5821@item show backtrace past-entry
5822Display the current internal entry point backtrace policy.
5823
25d29d70
AC
5824@item set backtrace limit @var{n}
5825@itemx set backtrace limit 0
5826@cindex backtrace limit
5827Limit the backtrace to @var{n} levels. A value of zero means
5828unlimited.
95f90d25 5829
25d29d70
AC
5830@item show backtrace limit
5831Display the current limit on backtrace levels.
95f90d25
DJ
5832@end table
5833
6d2ebf8b 5834@node Selection
79a6e687 5835@section Selecting a Frame
c906108c
SS
5836
5837Most commands for examining the stack and other data in your program work on
5838whichever stack frame is selected at the moment. Here are the commands for
5839selecting a stack frame; all of them finish by printing a brief description
5840of the stack frame just selected.
5841
5842@table @code
d4f3574e 5843@kindex frame@r{, selecting}
41afff9a 5844@kindex f @r{(@code{frame})}
c906108c
SS
5845@item frame @var{n}
5846@itemx f @var{n}
5847Select frame number @var{n}. Recall that frame zero is the innermost
5848(currently executing) frame, frame one is the frame that called the
5849innermost one, and so on. The highest-numbered frame is the one for
5850@code{main}.
5851
5852@item frame @var{addr}
5853@itemx f @var{addr}
5854Select the frame at address @var{addr}. This is useful mainly if the
5855chaining of stack frames has been damaged by a bug, making it
5856impossible for @value{GDBN} to assign numbers properly to all frames. In
5857addition, this can be useful when your program has multiple stacks and
5858switches between them.
5859
c906108c
SS
5860On the SPARC architecture, @code{frame} needs two addresses to
5861select an arbitrary frame: a frame pointer and a stack pointer.
5862
5863On the MIPS and Alpha architecture, it needs two addresses: a stack
5864pointer and a program counter.
5865
5866On the 29k architecture, it needs three addresses: a register stack
5867pointer, a program counter, and a memory stack pointer.
c906108c
SS
5868
5869@kindex up
5870@item up @var{n}
5871Move @var{n} frames up the stack. For positive numbers @var{n}, this
5872advances toward the outermost frame, to higher frame numbers, to frames
5873that have existed longer. @var{n} defaults to one.
5874
5875@kindex down
41afff9a 5876@kindex do @r{(@code{down})}
c906108c
SS
5877@item down @var{n}
5878Move @var{n} frames down the stack. For positive numbers @var{n}, this
5879advances toward the innermost frame, to lower frame numbers, to frames
5880that were created more recently. @var{n} defaults to one. You may
5881abbreviate @code{down} as @code{do}.
5882@end table
5883
5884All of these commands end by printing two lines of output describing the
5885frame. The first line shows the frame number, the function name, the
5886arguments, and the source file and line number of execution in that
5d161b24 5887frame. The second line shows the text of that source line.
c906108c
SS
5888
5889@need 1000
5890For example:
5891
5892@smallexample
5893@group
5894(@value{GDBP}) up
5895#1 0x22f0 in main (argc=1, argv=0xf7fffbf4, env=0xf7fffbfc)
5896 at env.c:10
589710 read_input_file (argv[i]);
5898@end group
5899@end smallexample
5900
5901After such a printout, the @code{list} command with no arguments
5902prints ten lines centered on the point of execution in the frame.
87885426
FN
5903You can also edit the program at the point of execution with your favorite
5904editing program by typing @code{edit}.
79a6e687 5905@xref{List, ,Printing Source Lines},
87885426 5906for details.
c906108c
SS
5907
5908@table @code
5909@kindex down-silently
5910@kindex up-silently
5911@item up-silently @var{n}
5912@itemx down-silently @var{n}
5913These two commands are variants of @code{up} and @code{down},
5914respectively; they differ in that they do their work silently, without
5915causing display of the new frame. They are intended primarily for use
5916in @value{GDBN} command scripts, where the output might be unnecessary and
5917distracting.
5918@end table
5919
6d2ebf8b 5920@node Frame Info
79a6e687 5921@section Information About a Frame
c906108c
SS
5922
5923There are several other commands to print information about the selected
5924stack frame.
5925
5926@table @code
5927@item frame
5928@itemx f
5929When used without any argument, this command does not change which
5930frame is selected, but prints a brief description of the currently
5931selected stack frame. It can be abbreviated @code{f}. With an
5932argument, this command is used to select a stack frame.
79a6e687 5933@xref{Selection, ,Selecting a Frame}.
c906108c
SS
5934
5935@kindex info frame
41afff9a 5936@kindex info f @r{(@code{info frame})}
c906108c
SS
5937@item info frame
5938@itemx info f
5939This command prints a verbose description of the selected stack frame,
5940including:
5941
5942@itemize @bullet
5d161b24
DB
5943@item
5944the address of the frame
c906108c
SS
5945@item
5946the address of the next frame down (called by this frame)
5947@item
5948the address of the next frame up (caller of this frame)
5949@item
5950the language in which the source code corresponding to this frame is written
5951@item
5952the address of the frame's arguments
5953@item
d4f3574e
SS
5954the address of the frame's local variables
5955@item
c906108c
SS
5956the program counter saved in it (the address of execution in the caller frame)
5957@item
5958which registers were saved in the frame
5959@end itemize
5960
5961@noindent The verbose description is useful when
5962something has gone wrong that has made the stack format fail to fit
5963the usual conventions.
5964
5965@item info frame @var{addr}
5966@itemx info f @var{addr}
5967Print a verbose description of the frame at address @var{addr}, without
5968selecting that frame. The selected frame remains unchanged by this
5969command. This requires the same kind of address (more than one for some
5970architectures) that you specify in the @code{frame} command.
79a6e687 5971@xref{Selection, ,Selecting a Frame}.
c906108c
SS
5972
5973@kindex info args
5974@item info args
5975Print the arguments of the selected frame, each on a separate line.
5976
5977@item info locals
5978@kindex info locals
5979Print the local variables of the selected frame, each on a separate
5980line. These are all variables (declared either static or automatic)
5981accessible at the point of execution of the selected frame.
5982
c906108c 5983@kindex info catch
d4f3574e
SS
5984@cindex catch exceptions, list active handlers
5985@cindex exception handlers, how to list
c906108c
SS
5986@item info catch
5987Print a list of all the exception handlers that are active in the
5988current stack frame at the current point of execution. To see other
5989exception handlers, visit the associated frame (using the @code{up},
5990@code{down}, or @code{frame} commands); then type @code{info catch}.
79a6e687 5991@xref{Set Catchpoints, , Setting Catchpoints}.
53a5351d 5992
c906108c
SS
5993@end table
5994
c906108c 5995
6d2ebf8b 5996@node Source
c906108c
SS
5997@chapter Examining Source Files
5998
5999@value{GDBN} can print parts of your program's source, since the debugging
6000information recorded in the program tells @value{GDBN} what source files were
6001used to build it. When your program stops, @value{GDBN} spontaneously prints
6002the line where it stopped. Likewise, when you select a stack frame
79a6e687 6003(@pxref{Selection, ,Selecting a Frame}), @value{GDBN} prints the line where
c906108c
SS
6004execution in that frame has stopped. You can print other portions of
6005source files by explicit command.
6006
7a292a7a 6007If you use @value{GDBN} through its @sc{gnu} Emacs interface, you may
d4f3574e 6008prefer to use Emacs facilities to view source; see @ref{Emacs, ,Using
7a292a7a 6009@value{GDBN} under @sc{gnu} Emacs}.
c906108c
SS
6010
6011@menu
6012* List:: Printing source lines
2a25a5ba 6013* Specify Location:: How to specify code locations
87885426 6014* Edit:: Editing source files
c906108c 6015* Search:: Searching source files
c906108c
SS
6016* Source Path:: Specifying source directories
6017* Machine Code:: Source and machine code
6018@end menu
6019
6d2ebf8b 6020@node List
79a6e687 6021@section Printing Source Lines
c906108c
SS
6022
6023@kindex list
41afff9a 6024@kindex l @r{(@code{list})}
c906108c 6025To print lines from a source file, use the @code{list} command
5d161b24 6026(abbreviated @code{l}). By default, ten lines are printed.
2a25a5ba
EZ
6027There are several ways to specify what part of the file you want to
6028print; see @ref{Specify Location}, for the full list.
c906108c
SS
6029
6030Here are the forms of the @code{list} command most commonly used:
6031
6032@table @code
6033@item list @var{linenum}
6034Print lines centered around line number @var{linenum} in the
6035current source file.
6036
6037@item list @var{function}
6038Print lines centered around the beginning of function
6039@var{function}.
6040
6041@item list
6042Print more lines. If the last lines printed were printed with a
6043@code{list} command, this prints lines following the last lines
6044printed; however, if the last line printed was a solitary line printed
6045as part of displaying a stack frame (@pxref{Stack, ,Examining the
6046Stack}), this prints lines centered around that line.
6047
6048@item list -
6049Print lines just before the lines last printed.
6050@end table
6051
9c16f35a 6052@cindex @code{list}, how many lines to display
c906108c
SS
6053By default, @value{GDBN} prints ten source lines with any of these forms of
6054the @code{list} command. You can change this using @code{set listsize}:
6055
6056@table @code
6057@kindex set listsize
6058@item set listsize @var{count}
6059Make the @code{list} command display @var{count} source lines (unless
6060the @code{list} argument explicitly specifies some other number).
6061
6062@kindex show listsize
6063@item show listsize
6064Display the number of lines that @code{list} prints.
6065@end table
6066
6067Repeating a @code{list} command with @key{RET} discards the argument,
6068so it is equivalent to typing just @code{list}. This is more useful
6069than listing the same lines again. An exception is made for an
6070argument of @samp{-}; that argument is preserved in repetition so that
6071each repetition moves up in the source file.
6072
c906108c
SS
6073In general, the @code{list} command expects you to supply zero, one or two
6074@dfn{linespecs}. Linespecs specify source lines; there are several ways
2a25a5ba
EZ
6075of writing them (@pxref{Specify Location}), but the effect is always
6076to specify some source line.
6077
c906108c
SS
6078Here is a complete description of the possible arguments for @code{list}:
6079
6080@table @code
6081@item list @var{linespec}
6082Print lines centered around the line specified by @var{linespec}.
6083
6084@item list @var{first},@var{last}
6085Print lines from @var{first} to @var{last}. Both arguments are
2a25a5ba
EZ
6086linespecs. When a @code{list} command has two linespecs, and the
6087source file of the second linespec is omitted, this refers to
6088the same source file as the first linespec.
c906108c
SS
6089
6090@item list ,@var{last}
6091Print lines ending with @var{last}.
6092
6093@item list @var{first},
6094Print lines starting with @var{first}.
6095
6096@item list +
6097Print lines just after the lines last printed.
6098
6099@item list -
6100Print lines just before the lines last printed.
6101
6102@item list
6103As described in the preceding table.
6104@end table
6105
2a25a5ba
EZ
6106@node Specify Location
6107@section Specifying a Location
6108@cindex specifying location
6109@cindex linespec
c906108c 6110
2a25a5ba
EZ
6111Several @value{GDBN} commands accept arguments that specify a location
6112of your program's code. Since @value{GDBN} is a source-level
6113debugger, a location usually specifies some line in the source code;
6114for that reason, locations are also known as @dfn{linespecs}.
c906108c 6115
2a25a5ba
EZ
6116Here are all the different ways of specifying a code location that
6117@value{GDBN} understands:
c906108c 6118
2a25a5ba
EZ
6119@table @code
6120@item @var{linenum}
6121Specifies the line number @var{linenum} of the current source file.
c906108c 6122
2a25a5ba
EZ
6123@item -@var{offset}
6124@itemx +@var{offset}
6125Specifies the line @var{offset} lines before or after the @dfn{current
6126line}. For the @code{list} command, the current line is the last one
6127printed; for the breakpoint commands, this is the line at which
6128execution stopped in the currently selected @dfn{stack frame}
6129(@pxref{Frames, ,Frames}, for a description of stack frames.) When
6130used as the second of the two linespecs in a @code{list} command,
6131this specifies the line @var{offset} lines up or down from the first
6132linespec.
6133
6134@item @var{filename}:@var{linenum}
6135Specifies the line @var{linenum} in the source file @var{filename}.
c906108c
SS
6136
6137@item @var{function}
6138Specifies the line that begins the body of the function @var{function}.
2a25a5ba 6139For example, in C, this is the line with the open brace.
c906108c
SS
6140
6141@item @var{filename}:@var{function}
2a25a5ba
EZ
6142Specifies the line that begins the body of the function @var{function}
6143in the file @var{filename}. You only need the file name with a
6144function name to avoid ambiguity when there are identically named
6145functions in different source files.
c906108c
SS
6146
6147@item *@var{address}
2a25a5ba
EZ
6148Specifies the program address @var{address}. For line-oriented
6149commands, such as @code{list} and @code{edit}, this specifies a source
6150line that contains @var{address}. For @code{break} and other
6151breakpoint oriented commands, this can be used to set breakpoints in
6152parts of your program which do not have debugging information or
6153source files.
6154
6155Here @var{address} may be any expression valid in the current working
6156language (@pxref{Languages, working language}) that specifies a code
5fa54e5d
EZ
6157address. In addition, as a convenience, @value{GDBN} extends the
6158semantics of expressions used in locations to cover the situations
6159that frequently happen during debugging. Here are the various forms
6160of @var{address}:
2a25a5ba
EZ
6161
6162@table @code
6163@item @var{expression}
6164Any expression valid in the current working language.
6165
6166@item @var{funcaddr}
6167An address of a function or procedure derived from its name. In C,
6168C@t{++}, Java, Objective-C, Fortran, minimal, and assembly, this is
6169simply the function's name @var{function} (and actually a special case
6170of a valid expression). In Pascal and Modula-2, this is
6171@code{&@var{function}}. In Ada, this is @code{@var{function}'Address}
6172(although the Pascal form also works).
6173
6174This form specifies the address of the function's first instruction,
6175before the stack frame and arguments have been set up.
6176
6177@item '@var{filename}'::@var{funcaddr}
6178Like @var{funcaddr} above, but also specifies the name of the source
6179file explicitly. This is useful if the name of the function does not
6180specify the function unambiguously, e.g., if there are several
6181functions with identical names in different source files.
c906108c
SS
6182@end table
6183
2a25a5ba
EZ
6184@end table
6185
6186
87885426 6187@node Edit
79a6e687 6188@section Editing Source Files
87885426
FN
6189@cindex editing source files
6190
6191@kindex edit
6192@kindex e @r{(@code{edit})}
6193To edit the lines in a source file, use the @code{edit} command.
6194The editing program of your choice
6195is invoked with the current line set to
6196the active line in the program.
6197Alternatively, there are several ways to specify what part of the file you
2a25a5ba 6198want to print if you want to see other parts of the program:
87885426
FN
6199
6200@table @code
2a25a5ba
EZ
6201@item edit @var{location}
6202Edit the source file specified by @code{location}. Editing starts at
6203that @var{location}, e.g., at the specified source line of the
6204specified file. @xref{Specify Location}, for all the possible forms
6205of the @var{location} argument; here are the forms of the @code{edit}
6206command most commonly used:
87885426 6207
2a25a5ba 6208@table @code
87885426
FN
6209@item edit @var{number}
6210Edit the current source file with @var{number} as the active line number.
6211
6212@item edit @var{function}
6213Edit the file containing @var{function} at the beginning of its definition.
2a25a5ba 6214@end table
87885426 6215
87885426
FN
6216@end table
6217
79a6e687 6218@subsection Choosing your Editor
87885426
FN
6219You can customize @value{GDBN} to use any editor you want
6220@footnote{
6221The only restriction is that your editor (say @code{ex}), recognizes the
6222following command-line syntax:
10998722 6223@smallexample
87885426 6224ex +@var{number} file
10998722 6225@end smallexample
15387254
EZ
6226The optional numeric value +@var{number} specifies the number of the line in
6227the file where to start editing.}.
6228By default, it is @file{@value{EDITOR}}, but you can change this
10998722
AC
6229by setting the environment variable @code{EDITOR} before using
6230@value{GDBN}. For example, to configure @value{GDBN} to use the
6231@code{vi} editor, you could use these commands with the @code{sh} shell:
6232@smallexample
87885426
FN
6233EDITOR=/usr/bin/vi
6234export EDITOR
15387254 6235gdb @dots{}
10998722 6236@end smallexample
87885426 6237or in the @code{csh} shell,
10998722 6238@smallexample
87885426 6239setenv EDITOR /usr/bin/vi
15387254 6240gdb @dots{}
10998722 6241@end smallexample
87885426 6242
6d2ebf8b 6243@node Search
79a6e687 6244@section Searching Source Files
15387254 6245@cindex searching source files
c906108c
SS
6246
6247There are two commands for searching through the current source file for a
6248regular expression.
6249
6250@table @code
6251@kindex search
6252@kindex forward-search
6253@item forward-search @var{regexp}
6254@itemx search @var{regexp}
6255The command @samp{forward-search @var{regexp}} checks each line,
6256starting with the one following the last line listed, for a match for
5d161b24 6257@var{regexp}. It lists the line that is found. You can use the
c906108c
SS
6258synonym @samp{search @var{regexp}} or abbreviate the command name as
6259@code{fo}.
6260
09d4efe1 6261@kindex reverse-search
c906108c
SS
6262@item reverse-search @var{regexp}
6263The command @samp{reverse-search @var{regexp}} checks each line, starting
6264with the one before the last line listed and going backward, for a match
6265for @var{regexp}. It lists the line that is found. You can abbreviate
6266this command as @code{rev}.
6267@end table
c906108c 6268
6d2ebf8b 6269@node Source Path
79a6e687 6270@section Specifying Source Directories
c906108c
SS
6271
6272@cindex source path
6273@cindex directories for source files
6274Executable programs sometimes do not record the directories of the source
6275files from which they were compiled, just the names. Even when they do,
6276the directories could be moved between the compilation and your debugging
6277session. @value{GDBN} has a list of directories to search for source files;
6278this is called the @dfn{source path}. Each time @value{GDBN} wants a source file,
6279it tries all the directories in the list, in the order they are present
0b66e38c
EZ
6280in the list, until it finds a file with the desired name.
6281
6282For example, suppose an executable references the file
6283@file{/usr/src/foo-1.0/lib/foo.c}, and our source path is
6284@file{/mnt/cross}. The file is first looked up literally; if this
6285fails, @file{/mnt/cross/usr/src/foo-1.0/lib/foo.c} is tried; if this
6286fails, @file{/mnt/cross/foo.c} is opened; if this fails, an error
6287message is printed. @value{GDBN} does not look up the parts of the
6288source file name, such as @file{/mnt/cross/src/foo-1.0/lib/foo.c}.
6289Likewise, the subdirectories of the source path are not searched: if
6290the source path is @file{/mnt/cross}, and the binary refers to
6291@file{foo.c}, @value{GDBN} would not find it under
6292@file{/mnt/cross/usr/src/foo-1.0/lib}.
6293
6294Plain file names, relative file names with leading directories, file
6295names containing dots, etc.@: are all treated as described above; for
6296instance, if the source path is @file{/mnt/cross}, and the source file
6297is recorded as @file{../lib/foo.c}, @value{GDBN} would first try
6298@file{../lib/foo.c}, then @file{/mnt/cross/../lib/foo.c}, and after
6299that---@file{/mnt/cross/foo.c}.
6300
6301Note that the executable search path is @emph{not} used to locate the
cd852561 6302source files.
c906108c
SS
6303
6304Whenever you reset or rearrange the source path, @value{GDBN} clears out
6305any information it has cached about where source files are found and where
6306each line is in the file.
6307
6308@kindex directory
6309@kindex dir
d4f3574e
SS
6310When you start @value{GDBN}, its source path includes only @samp{cdir}
6311and @samp{cwd}, in that order.
c906108c
SS
6312To add other directories, use the @code{directory} command.
6313
4b505b12
AS
6314The search path is used to find both program source files and @value{GDBN}
6315script files (read using the @samp{-command} option and @samp{source} command).
6316
30daae6c
JB
6317In addition to the source path, @value{GDBN} provides a set of commands
6318that manage a list of source path substitution rules. A @dfn{substitution
6319rule} specifies how to rewrite source directories stored in the program's
6320debug information in case the sources were moved to a different
6321directory between compilation and debugging. A rule is made of
6322two strings, the first specifying what needs to be rewritten in
6323the path, and the second specifying how it should be rewritten.
6324In @ref{set substitute-path}, we name these two parts @var{from} and
6325@var{to} respectively. @value{GDBN} does a simple string replacement
6326of @var{from} with @var{to} at the start of the directory part of the
6327source file name, and uses that result instead of the original file
6328name to look up the sources.
6329
6330Using the previous example, suppose the @file{foo-1.0} tree has been
6331moved from @file{/usr/src} to @file{/mnt/cross}, then you can tell
3f94c067 6332@value{GDBN} to replace @file{/usr/src} in all source path names with
30daae6c
JB
6333@file{/mnt/cross}. The first lookup will then be
6334@file{/mnt/cross/foo-1.0/lib/foo.c} in place of the original location
6335of @file{/usr/src/foo-1.0/lib/foo.c}. To define a source path
6336substitution rule, use the @code{set substitute-path} command
6337(@pxref{set substitute-path}).
6338
6339To avoid unexpected substitution results, a rule is applied only if the
6340@var{from} part of the directory name ends at a directory separator.
6341For instance, a rule substituting @file{/usr/source} into
6342@file{/mnt/cross} will be applied to @file{/usr/source/foo-1.0} but
6343not to @file{/usr/sourceware/foo-2.0}. And because the substitution
d3e8051b 6344is applied only at the beginning of the directory name, this rule will
30daae6c
JB
6345not be applied to @file{/root/usr/source/baz.c} either.
6346
6347In many cases, you can achieve the same result using the @code{directory}
6348command. However, @code{set substitute-path} can be more efficient in
6349the case where the sources are organized in a complex tree with multiple
6350subdirectories. With the @code{directory} command, you need to add each
6351subdirectory of your project. If you moved the entire tree while
6352preserving its internal organization, then @code{set substitute-path}
6353allows you to direct the debugger to all the sources with one single
6354command.
6355
6356@code{set substitute-path} is also more than just a shortcut command.
6357The source path is only used if the file at the original location no
6358longer exists. On the other hand, @code{set substitute-path} modifies
6359the debugger behavior to look at the rewritten location instead. So, if
6360for any reason a source file that is not relevant to your executable is
6361located at the original location, a substitution rule is the only
3f94c067 6362method available to point @value{GDBN} at the new location.
30daae6c 6363
29b0e8a2
JM
6364@cindex @samp{--with-relocated-sources}
6365@cindex default source path substitution
6366You can configure a default source path substitution rule by
6367configuring @value{GDBN} with the
6368@samp{--with-relocated-sources=@var{dir}} option. The @var{dir}
6369should be the name of a directory under @value{GDBN}'s configured
6370prefix (set with @samp{--prefix} or @samp{--exec-prefix}), and
6371directory names in debug information under @var{dir} will be adjusted
6372automatically if the installed @value{GDBN} is moved to a new
6373location. This is useful if @value{GDBN}, libraries or executables
6374with debug information and corresponding source code are being moved
6375together.
6376
c906108c
SS
6377@table @code
6378@item directory @var{dirname} @dots{}
6379@item dir @var{dirname} @dots{}
6380Add directory @var{dirname} to the front of the source path. Several
d4f3574e
SS
6381directory names may be given to this command, separated by @samp{:}
6382(@samp{;} on MS-DOS and MS-Windows, where @samp{:} usually appears as
6383part of absolute file names) or
c906108c
SS
6384whitespace. You may specify a directory that is already in the source
6385path; this moves it forward, so @value{GDBN} searches it sooner.
6386
6387@kindex cdir
6388@kindex cwd
41afff9a 6389@vindex $cdir@r{, convenience variable}
d3e8051b 6390@vindex $cwd@r{, convenience variable}
c906108c
SS
6391@cindex compilation directory
6392@cindex current directory
6393@cindex working directory
6394@cindex directory, current
6395@cindex directory, compilation
6396You can use the string @samp{$cdir} to refer to the compilation
6397directory (if one is recorded), and @samp{$cwd} to refer to the current
6398working directory. @samp{$cwd} is not the same as @samp{.}---the former
6399tracks the current working directory as it changes during your @value{GDBN}
6400session, while the latter is immediately expanded to the current
6401directory at the time you add an entry to the source path.
6402
6403@item directory
cd852561 6404Reset the source path to its default value (@samp{$cdir:$cwd} on Unix systems). This requires confirmation.
c906108c
SS
6405
6406@c RET-repeat for @code{directory} is explicitly disabled, but since
6407@c repeating it would be a no-op we do not say that. (thanks to RMS)
6408
6409@item show directories
6410@kindex show directories
6411Print the source path: show which directories it contains.
30daae6c
JB
6412
6413@anchor{set substitute-path}
6414@item set substitute-path @var{from} @var{to}
6415@kindex set substitute-path
6416Define a source path substitution rule, and add it at the end of the
6417current list of existing substitution rules. If a rule with the same
6418@var{from} was already defined, then the old rule is also deleted.
6419
6420For example, if the file @file{/foo/bar/baz.c} was moved to
6421@file{/mnt/cross/baz.c}, then the command
6422
6423@smallexample
6424(@value{GDBP}) set substitute-path /usr/src /mnt/cross
6425@end smallexample
6426
6427@noindent
6428will tell @value{GDBN} to replace @samp{/usr/src} with
6429@samp{/mnt/cross}, which will allow @value{GDBN} to find the file
6430@file{baz.c} even though it was moved.
6431
6432In the case when more than one substitution rule have been defined,
6433the rules are evaluated one by one in the order where they have been
6434defined. The first one matching, if any, is selected to perform
6435the substitution.
6436
6437For instance, if we had entered the following commands:
6438
6439@smallexample
6440(@value{GDBP}) set substitute-path /usr/src/include /mnt/include
6441(@value{GDBP}) set substitute-path /usr/src /mnt/src
6442@end smallexample
6443
6444@noindent
6445@value{GDBN} would then rewrite @file{/usr/src/include/defs.h} into
6446@file{/mnt/include/defs.h} by using the first rule. However, it would
6447use the second rule to rewrite @file{/usr/src/lib/foo.c} into
6448@file{/mnt/src/lib/foo.c}.
6449
6450
6451@item unset substitute-path [path]
6452@kindex unset substitute-path
6453If a path is specified, search the current list of substitution rules
6454for a rule that would rewrite that path. Delete that rule if found.
6455A warning is emitted by the debugger if no rule could be found.
6456
6457If no path is specified, then all substitution rules are deleted.
6458
6459@item show substitute-path [path]
6460@kindex show substitute-path
6461If a path is specified, then print the source path substitution rule
6462which would rewrite that path, if any.
6463
6464If no path is specified, then print all existing source path substitution
6465rules.
6466
c906108c
SS
6467@end table
6468
6469If your source path is cluttered with directories that are no longer of
6470interest, @value{GDBN} may sometimes cause confusion by finding the wrong
6471versions of source. You can correct the situation as follows:
6472
6473@enumerate
6474@item
cd852561 6475Use @code{directory} with no argument to reset the source path to its default value.
c906108c
SS
6476
6477@item
6478Use @code{directory} with suitable arguments to reinstall the
6479directories you want in the source path. You can add all the
6480directories in one command.
6481@end enumerate
6482
6d2ebf8b 6483@node Machine Code
79a6e687 6484@section Source and Machine Code
15387254 6485@cindex source line and its code address
c906108c
SS
6486
6487You can use the command @code{info line} to map source lines to program
6488addresses (and vice versa), and the command @code{disassemble} to display
91440f57
HZ
6489a range of addresses as machine instructions. You can use the command
6490@code{set disassemble-next-line} to set whether to disassemble next
6491source line when execution stops. When run under @sc{gnu} Emacs
d4f3574e 6492mode, the @code{info line} command causes the arrow to point to the
5d161b24 6493line specified. Also, @code{info line} prints addresses in symbolic form as
c906108c
SS
6494well as hex.
6495
6496@table @code
6497@kindex info line
6498@item info line @var{linespec}
6499Print the starting and ending addresses of the compiled code for
6500source line @var{linespec}. You can specify source lines in any of
2a25a5ba 6501the ways documented in @ref{Specify Location}.
c906108c
SS
6502@end table
6503
6504For example, we can use @code{info line} to discover the location of
6505the object code for the first line of function
6506@code{m4_changequote}:
6507
d4f3574e
SS
6508@c FIXME: I think this example should also show the addresses in
6509@c symbolic form, as they usually would be displayed.
c906108c 6510@smallexample
96a2c332 6511(@value{GDBP}) info line m4_changequote
c906108c
SS
6512Line 895 of "builtin.c" starts at pc 0x634c and ends at 0x6350.
6513@end smallexample
6514
6515@noindent
15387254 6516@cindex code address and its source line
c906108c
SS
6517We can also inquire (using @code{*@var{addr}} as the form for
6518@var{linespec}) what source line covers a particular address:
6519@smallexample
6520(@value{GDBP}) info line *0x63ff
6521Line 926 of "builtin.c" starts at pc 0x63e4 and ends at 0x6404.
6522@end smallexample
6523
6524@cindex @code{$_} and @code{info line}
15387254 6525@cindex @code{x} command, default address
41afff9a 6526@kindex x@r{(examine), and} info line
c906108c
SS
6527After @code{info line}, the default address for the @code{x} command
6528is changed to the starting address of the line, so that @samp{x/i} is
6529sufficient to begin examining the machine code (@pxref{Memory,
79a6e687 6530,Examining Memory}). Also, this address is saved as the value of the
c906108c 6531convenience variable @code{$_} (@pxref{Convenience Vars, ,Convenience
79a6e687 6532Variables}).
c906108c
SS
6533
6534@table @code
6535@kindex disassemble
6536@cindex assembly instructions
6537@cindex instructions, assembly
6538@cindex machine instructions
6539@cindex listing machine instructions
6540@item disassemble
d14508fe 6541@itemx disassemble /m
9b117ef3 6542@itemx disassemble /r
c906108c 6543This specialized command dumps a range of memory as machine
d14508fe 6544instructions. It can also print mixed source+disassembly by specifying
9b117ef3
HZ
6545the @code{/m} modifier and print the raw instructions in hex as well as
6546in symbolic form by specifying the @code{/r}.
d14508fe 6547The default memory range is the function surrounding the
c906108c
SS
6548program counter of the selected frame. A single argument to this
6549command is a program counter value; @value{GDBN} dumps the function
21a0512e
PP
6550surrounding this value. When two arguments are given, they should
6551be separated by a comma, possibly surrounded by whitespace. The
6552arguments specify a range of addresses (first inclusive, second exclusive)
6553to dump. In that case, the name of the function is also printed (since
6554there could be several functions in the given range).
6555
6556The argument(s) can be any expression yielding a numeric value, such as
6557@samp{0x32c4}, @samp{&main+10} or @samp{$pc - 8}.
2b28d209
PP
6558
6559If the range of memory being disassembled contains current program counter,
6560the instruction at that location is shown with a @code{=>} marker.
c906108c
SS
6561@end table
6562
c906108c
SS
6563The following example shows the disassembly of a range of addresses of
6564HP PA-RISC 2.0 code:
6565
6566@smallexample
21a0512e 6567(@value{GDBP}) disas 0x32c4, 0x32e4
c906108c 6568Dump of assembler code from 0x32c4 to 0x32e4:
2b28d209
PP
6569 0x32c4 <main+204>: addil 0,dp
6570 0x32c8 <main+208>: ldw 0x22c(sr0,r1),r26
6571 0x32cc <main+212>: ldil 0x3000,r31
6572 0x32d0 <main+216>: ble 0x3f8(sr4,r31)
6573 0x32d4 <main+220>: ldo 0(r31),rp
6574 0x32d8 <main+224>: addil -0x800,dp
6575 0x32dc <main+228>: ldo 0x588(r1),r26
6576 0x32e0 <main+232>: ldil 0x3000,r31
c906108c
SS
6577End of assembler dump.
6578@end smallexample
c906108c 6579
2b28d209
PP
6580Here is an example showing mixed source+assembly for Intel x86, when the
6581program is stopped just after function prologue:
d14508fe
DE
6582
6583@smallexample
6584(@value{GDBP}) disas /m main
6585Dump of assembler code for function main:
65865 @{
9c419145
PP
6587 0x08048330 <+0>: push %ebp
6588 0x08048331 <+1>: mov %esp,%ebp
6589 0x08048333 <+3>: sub $0x8,%esp
6590 0x08048336 <+6>: and $0xfffffff0,%esp
6591 0x08048339 <+9>: sub $0x10,%esp
d14508fe
DE
6592
65936 printf ("Hello.\n");
9c419145
PP
6594=> 0x0804833c <+12>: movl $0x8048440,(%esp)
6595 0x08048343 <+19>: call 0x8048284 <puts@@plt>
d14508fe
DE
6596
65977 return 0;
65988 @}
9c419145
PP
6599 0x08048348 <+24>: mov $0x0,%eax
6600 0x0804834d <+29>: leave
6601 0x0804834e <+30>: ret
d14508fe
DE
6602
6603End of assembler dump.
6604@end smallexample
6605
c906108c
SS
6606Some architectures have more than one commonly-used set of instruction
6607mnemonics or other syntax.
6608
76d17f34
EZ
6609For programs that were dynamically linked and use shared libraries,
6610instructions that call functions or branch to locations in the shared
6611libraries might show a seemingly bogus location---it's actually a
6612location of the relocation table. On some architectures, @value{GDBN}
6613might be able to resolve these to actual function names.
6614
c906108c 6615@table @code
d4f3574e 6616@kindex set disassembly-flavor
d4f3574e
SS
6617@cindex Intel disassembly flavor
6618@cindex AT&T disassembly flavor
6619@item set disassembly-flavor @var{instruction-set}
c906108c
SS
6620Select the instruction set to use when disassembling the
6621program via the @code{disassemble} or @code{x/i} commands.
6622
6623Currently this command is only defined for the Intel x86 family. You
d4f3574e
SS
6624can set @var{instruction-set} to either @code{intel} or @code{att}.
6625The default is @code{att}, the AT&T flavor used by default by Unix
6626assemblers for x86-based targets.
9c16f35a
EZ
6627
6628@kindex show disassembly-flavor
6629@item show disassembly-flavor
6630Show the current setting of the disassembly flavor.
c906108c
SS
6631@end table
6632
91440f57
HZ
6633@table @code
6634@kindex set disassemble-next-line
6635@kindex show disassemble-next-line
6636@item set disassemble-next-line
6637@itemx show disassemble-next-line
32ae1842
EZ
6638Control whether or not @value{GDBN} will disassemble the next source
6639line or instruction when execution stops. If ON, @value{GDBN} will
6640display disassembly of the next source line when execution of the
6641program being debugged stops. This is @emph{in addition} to
6642displaying the source line itself, which @value{GDBN} always does if
6643possible. If the next source line cannot be displayed for some reason
6644(e.g., if @value{GDBN} cannot find the source file, or there's no line
6645info in the debug info), @value{GDBN} will display disassembly of the
6646next @emph{instruction} instead of showing the next source line. If
6647AUTO, @value{GDBN} will display disassembly of next instruction only
6648if the source line cannot be displayed. This setting causes
6649@value{GDBN} to display some feedback when you step through a function
6650with no line info or whose source file is unavailable. The default is
6651OFF, which means never display the disassembly of the next line or
6652instruction.
91440f57
HZ
6653@end table
6654
c906108c 6655
6d2ebf8b 6656@node Data
c906108c
SS
6657@chapter Examining Data
6658
6659@cindex printing data
6660@cindex examining data
6661@kindex print
6662@kindex inspect
6663@c "inspect" is not quite a synonym if you are using Epoch, which we do not
6664@c document because it is nonstandard... Under Epoch it displays in a
6665@c different window or something like that.
6666The usual way to examine data in your program is with the @code{print}
7a292a7a
SS
6667command (abbreviated @code{p}), or its synonym @code{inspect}. It
6668evaluates and prints the value of an expression of the language your
6669program is written in (@pxref{Languages, ,Using @value{GDBN} with
78e2826b
TT
6670Different Languages}). It may also print the expression using a
6671Python-based pretty-printer (@pxref{Pretty Printing}).
c906108c
SS
6672
6673@table @code
d4f3574e
SS
6674@item print @var{expr}
6675@itemx print /@var{f} @var{expr}
6676@var{expr} is an expression (in the source language). By default the
6677value of @var{expr} is printed in a format appropriate to its data type;
c906108c 6678you can choose a different format by specifying @samp{/@var{f}}, where
d4f3574e 6679@var{f} is a letter specifying the format; see @ref{Output Formats,,Output
79a6e687 6680Formats}.
c906108c
SS
6681
6682@item print
6683@itemx print /@var{f}
15387254 6684@cindex reprint the last value
d4f3574e 6685If you omit @var{expr}, @value{GDBN} displays the last value again (from the
79a6e687 6686@dfn{value history}; @pxref{Value History, ,Value History}). This allows you to
c906108c
SS
6687conveniently inspect the same value in an alternative format.
6688@end table
6689
6690A more low-level way of examining data is with the @code{x} command.
6691It examines data in memory at a specified address and prints it in a
79a6e687 6692specified format. @xref{Memory, ,Examining Memory}.
c906108c 6693
7a292a7a 6694If you are interested in information about types, or about how the
d4f3574e
SS
6695fields of a struct or a class are declared, use the @code{ptype @var{exp}}
6696command rather than @code{print}. @xref{Symbols, ,Examining the Symbol
7a292a7a 6697Table}.
c906108c
SS
6698
6699@menu
6700* Expressions:: Expressions
6ba66d6a 6701* Ambiguous Expressions:: Ambiguous Expressions
c906108c
SS
6702* Variables:: Program variables
6703* Arrays:: Artificial arrays
6704* Output Formats:: Output formats
6705* Memory:: Examining memory
6706* Auto Display:: Automatic display
6707* Print Settings:: Print settings
6708* Value History:: Value history
6709* Convenience Vars:: Convenience variables
6710* Registers:: Registers
c906108c 6711* Floating Point Hardware:: Floating point hardware
53c69bd7 6712* Vector Unit:: Vector Unit
721c2651 6713* OS Information:: Auxiliary data provided by operating system
29e57380 6714* Memory Region Attributes:: Memory region attributes
16d9dec6 6715* Dump/Restore Files:: Copy between memory and a file
384ee23f 6716* Core File Generation:: Cause a program dump its core
a0eb71c5
KB
6717* Character Sets:: Debugging programs that use a different
6718 character set than GDB does
09d4efe1 6719* Caching Remote Data:: Data caching for remote targets
08388c79 6720* Searching Memory:: Searching memory for a sequence of bytes
c906108c
SS
6721@end menu
6722
6d2ebf8b 6723@node Expressions
c906108c
SS
6724@section Expressions
6725
6726@cindex expressions
6727@code{print} and many other @value{GDBN} commands accept an expression and
6728compute its value. Any kind of constant, variable or operator defined
6729by the programming language you are using is valid in an expression in
e2e0bcd1
JB
6730@value{GDBN}. This includes conditional expressions, function calls,
6731casts, and string constants. It also includes preprocessor macros, if
6732you compiled your program to include this information; see
6733@ref{Compilation}.
c906108c 6734
15387254 6735@cindex arrays in expressions
d4f3574e
SS
6736@value{GDBN} supports array constants in expressions input by
6737the user. The syntax is @{@var{element}, @var{element}@dots{}@}. For example,
63092375
DJ
6738you can use the command @code{print @{1, 2, 3@}} to create an array
6739of three integers. If you pass an array to a function or assign it
6740to a program variable, @value{GDBN} copies the array to memory that
6741is @code{malloc}ed in the target program.
c906108c 6742
c906108c
SS
6743Because C is so widespread, most of the expressions shown in examples in
6744this manual are in C. @xref{Languages, , Using @value{GDBN} with Different
6745Languages}, for information on how to use expressions in other
6746languages.
6747
6748In this section, we discuss operators that you can use in @value{GDBN}
6749expressions regardless of your programming language.
6750
15387254 6751@cindex casts, in expressions
c906108c
SS
6752Casts are supported in all languages, not just in C, because it is so
6753useful to cast a number into a pointer in order to examine a structure
6754at that address in memory.
6755@c FIXME: casts supported---Mod2 true?
c906108c
SS
6756
6757@value{GDBN} supports these operators, in addition to those common
6758to programming languages:
6759
6760@table @code
6761@item @@
6762@samp{@@} is a binary operator for treating parts of memory as arrays.
79a6e687 6763@xref{Arrays, ,Artificial Arrays}, for more information.
c906108c
SS
6764
6765@item ::
6766@samp{::} allows you to specify a variable in terms of the file or
79a6e687 6767function where it is defined. @xref{Variables, ,Program Variables}.
c906108c
SS
6768
6769@cindex @{@var{type}@}
6770@cindex type casting memory
6771@cindex memory, viewing as typed object
6772@cindex casts, to view memory
6773@item @{@var{type}@} @var{addr}
6774Refers to an object of type @var{type} stored at address @var{addr} in
6775memory. @var{addr} may be any expression whose value is an integer or
6776pointer (but parentheses are required around binary operators, just as in
6777a cast). This construct is allowed regardless of what kind of data is
6778normally supposed to reside at @var{addr}.
6779@end table
6780
6ba66d6a
JB
6781@node Ambiguous Expressions
6782@section Ambiguous Expressions
6783@cindex ambiguous expressions
6784
6785Expressions can sometimes contain some ambiguous elements. For instance,
6786some programming languages (notably Ada, C@t{++} and Objective-C) permit
6787a single function name to be defined several times, for application in
6788different contexts. This is called @dfn{overloading}. Another example
6789involving Ada is generics. A @dfn{generic package} is similar to C@t{++}
6790templates and is typically instantiated several times, resulting in
6791the same function name being defined in different contexts.
6792
6793In some cases and depending on the language, it is possible to adjust
6794the expression to remove the ambiguity. For instance in C@t{++}, you
6795can specify the signature of the function you want to break on, as in
6796@kbd{break @var{function}(@var{types})}. In Ada, using the fully
6797qualified name of your function often makes the expression unambiguous
6798as well.
6799
6800When an ambiguity that needs to be resolved is detected, the debugger
6801has the capability to display a menu of numbered choices for each
6802possibility, and then waits for the selection with the prompt @samp{>}.
6803The first option is always @samp{[0] cancel}, and typing @kbd{0 @key{RET}}
6804aborts the current command. If the command in which the expression was
6805used allows more than one choice to be selected, the next option in the
6806menu is @samp{[1] all}, and typing @kbd{1 @key{RET}} selects all possible
6807choices.
6808
6809For example, the following session excerpt shows an attempt to set a
6810breakpoint at the overloaded symbol @code{String::after}.
6811We choose three particular definitions of that function name:
6812
6813@c FIXME! This is likely to change to show arg type lists, at least
6814@smallexample
6815@group
6816(@value{GDBP}) b String::after
6817[0] cancel
6818[1] all
6819[2] file:String.cc; line number:867
6820[3] file:String.cc; line number:860
6821[4] file:String.cc; line number:875
6822[5] file:String.cc; line number:853
6823[6] file:String.cc; line number:846
6824[7] file:String.cc; line number:735
6825> 2 4 6
6826Breakpoint 1 at 0xb26c: file String.cc, line 867.
6827Breakpoint 2 at 0xb344: file String.cc, line 875.
6828Breakpoint 3 at 0xafcc: file String.cc, line 846.
6829Multiple breakpoints were set.
6830Use the "delete" command to delete unwanted
6831 breakpoints.
6832(@value{GDBP})
6833@end group
6834@end smallexample
6835
6836@table @code
6837@kindex set multiple-symbols
6838@item set multiple-symbols @var{mode}
6839@cindex multiple-symbols menu
6840
6841This option allows you to adjust the debugger behavior when an expression
6842is ambiguous.
6843
6844By default, @var{mode} is set to @code{all}. If the command with which
6845the expression is used allows more than one choice, then @value{GDBN}
6846automatically selects all possible choices. For instance, inserting
6847a breakpoint on a function using an ambiguous name results in a breakpoint
6848inserted on each possible match. However, if a unique choice must be made,
6849then @value{GDBN} uses the menu to help you disambiguate the expression.
6850For instance, printing the address of an overloaded function will result
6851in the use of the menu.
6852
6853When @var{mode} is set to @code{ask}, the debugger always uses the menu
6854when an ambiguity is detected.
6855
6856Finally, when @var{mode} is set to @code{cancel}, the debugger reports
6857an error due to the ambiguity and the command is aborted.
6858
6859@kindex show multiple-symbols
6860@item show multiple-symbols
6861Show the current value of the @code{multiple-symbols} setting.
6862@end table
6863
6d2ebf8b 6864@node Variables
79a6e687 6865@section Program Variables
c906108c
SS
6866
6867The most common kind of expression to use is the name of a variable
6868in your program.
6869
6870Variables in expressions are understood in the selected stack frame
79a6e687 6871(@pxref{Selection, ,Selecting a Frame}); they must be either:
c906108c
SS
6872
6873@itemize @bullet
6874@item
6875global (or file-static)
6876@end itemize
6877
5d161b24 6878@noindent or
c906108c
SS
6879
6880@itemize @bullet
6881@item
6882visible according to the scope rules of the
6883programming language from the point of execution in that frame
5d161b24 6884@end itemize
c906108c
SS
6885
6886@noindent This means that in the function
6887
474c8240 6888@smallexample
c906108c
SS
6889foo (a)
6890 int a;
6891@{
6892 bar (a);
6893 @{
6894 int b = test ();
6895 bar (b);
6896 @}
6897@}
474c8240 6898@end smallexample
c906108c
SS
6899
6900@noindent
6901you can examine and use the variable @code{a} whenever your program is
6902executing within the function @code{foo}, but you can only use or
6903examine the variable @code{b} while your program is executing inside
6904the block where @code{b} is declared.
6905
6906@cindex variable name conflict
6907There is an exception: you can refer to a variable or function whose
6908scope is a single source file even if the current execution point is not
6909in this file. But it is possible to have more than one such variable or
6910function with the same name (in different source files). If that
6911happens, referring to that name has unpredictable effects. If you wish,
6912you can specify a static variable in a particular function or file,
15387254 6913using the colon-colon (@code{::}) notation:
c906108c 6914
d4f3574e 6915@cindex colon-colon, context for variables/functions
12c27660 6916@ifnotinfo
c906108c 6917@c info cannot cope with a :: index entry, but why deprive hard copy readers?
41afff9a 6918@cindex @code{::}, context for variables/functions
12c27660 6919@end ifnotinfo
474c8240 6920@smallexample
c906108c
SS
6921@var{file}::@var{variable}
6922@var{function}::@var{variable}
474c8240 6923@end smallexample
c906108c
SS
6924
6925@noindent
6926Here @var{file} or @var{function} is the name of the context for the
6927static @var{variable}. In the case of file names, you can use quotes to
6928make sure @value{GDBN} parses the file name as a single word---for example,
6929to print a global value of @code{x} defined in @file{f2.c}:
6930
474c8240 6931@smallexample
c906108c 6932(@value{GDBP}) p 'f2.c'::x
474c8240 6933@end smallexample
c906108c 6934
b37052ae 6935@cindex C@t{++} scope resolution
c906108c 6936This use of @samp{::} is very rarely in conflict with the very similar
b37052ae 6937use of the same notation in C@t{++}. @value{GDBN} also supports use of the C@t{++}
c906108c
SS
6938scope resolution operator in @value{GDBN} expressions.
6939@c FIXME: Um, so what happens in one of those rare cases where it's in
6940@c conflict?? --mew
c906108c
SS
6941
6942@cindex wrong values
6943@cindex variable values, wrong
15387254
EZ
6944@cindex function entry/exit, wrong values of variables
6945@cindex optimized code, wrong values of variables
c906108c
SS
6946@quotation
6947@emph{Warning:} Occasionally, a local variable may appear to have the
6948wrong value at certain points in a function---just after entry to a new
6949scope, and just before exit.
6950@end quotation
6951You may see this problem when you are stepping by machine instructions.
6952This is because, on most machines, it takes more than one instruction to
6953set up a stack frame (including local variable definitions); if you are
6954stepping by machine instructions, variables may appear to have the wrong
6955values until the stack frame is completely built. On exit, it usually
6956also takes more than one machine instruction to destroy a stack frame;
6957after you begin stepping through that group of instructions, local
6958variable definitions may be gone.
6959
6960This may also happen when the compiler does significant optimizations.
6961To be sure of always seeing accurate values, turn off all optimization
6962when compiling.
6963
d4f3574e
SS
6964@cindex ``No symbol "foo" in current context''
6965Another possible effect of compiler optimizations is to optimize
6966unused variables out of existence, or assign variables to registers (as
6967opposed to memory addresses). Depending on the support for such cases
6968offered by the debug info format used by the compiler, @value{GDBN}
6969might not be able to display values for such local variables. If that
6970happens, @value{GDBN} will print a message like this:
6971
474c8240 6972@smallexample
d4f3574e 6973No symbol "foo" in current context.
474c8240 6974@end smallexample
d4f3574e
SS
6975
6976To solve such problems, either recompile without optimizations, or use a
6977different debug info format, if the compiler supports several such
15387254 6978formats. For example, @value{NGCC}, the @sc{gnu} C/C@t{++} compiler,
0179ffac
DC
6979usually supports the @option{-gstabs+} option. @option{-gstabs+}
6980produces debug info in a format that is superior to formats such as
6981COFF. You may be able to use DWARF 2 (@option{-gdwarf-2}), which is also
6982an effective form for debug info. @xref{Debugging Options,,Options
ce9341a1
BW
6983for Debugging Your Program or GCC, gcc.info, Using the @sc{gnu}
6984Compiler Collection (GCC)}.
79a6e687 6985@xref{C, ,C and C@t{++}}, for more information about debug info formats
15387254 6986that are best suited to C@t{++} programs.
d4f3574e 6987
ab1adacd
EZ
6988If you ask to print an object whose contents are unknown to
6989@value{GDBN}, e.g., because its data type is not completely specified
6990by the debug information, @value{GDBN} will say @samp{<incomplete
6991type>}. @xref{Symbols, incomplete type}, for more about this.
6992
3a60f64e
JK
6993Strings are identified as arrays of @code{char} values without specified
6994signedness. Arrays of either @code{signed char} or @code{unsigned char} get
6995printed as arrays of 1 byte sized integers. @code{-fsigned-char} or
6996@code{-funsigned-char} @value{NGCC} options have no effect as @value{GDBN}
6997defines literal string type @code{"char"} as @code{char} without a sign.
6998For program code
6999
7000@smallexample
7001char var0[] = "A";
7002signed char var1[] = "A";
7003@end smallexample
7004
7005You get during debugging
7006@smallexample
7007(gdb) print var0
7008$1 = "A"
7009(gdb) print var1
7010$2 = @{65 'A', 0 '\0'@}
7011@end smallexample
7012
6d2ebf8b 7013@node Arrays
79a6e687 7014@section Artificial Arrays
c906108c
SS
7015
7016@cindex artificial array
15387254 7017@cindex arrays
41afff9a 7018@kindex @@@r{, referencing memory as an array}
c906108c
SS
7019It is often useful to print out several successive objects of the
7020same type in memory; a section of an array, or an array of
7021dynamically determined size for which only a pointer exists in the
7022program.
7023
7024You can do this by referring to a contiguous span of memory as an
7025@dfn{artificial array}, using the binary operator @samp{@@}. The left
7026operand of @samp{@@} should be the first element of the desired array
7027and be an individual object. The right operand should be the desired length
7028of the array. The result is an array value whose elements are all of
7029the type of the left argument. The first element is actually the left
7030argument; the second element comes from bytes of memory immediately
7031following those that hold the first element, and so on. Here is an
7032example. If a program says
7033
474c8240 7034@smallexample
c906108c 7035int *array = (int *) malloc (len * sizeof (int));
474c8240 7036@end smallexample
c906108c
SS
7037
7038@noindent
7039you can print the contents of @code{array} with
7040
474c8240 7041@smallexample
c906108c 7042p *array@@len
474c8240 7043@end smallexample
c906108c
SS
7044
7045The left operand of @samp{@@} must reside in memory. Array values made
7046with @samp{@@} in this way behave just like other arrays in terms of
7047subscripting, and are coerced to pointers when used in expressions.
7048Artificial arrays most often appear in expressions via the value history
79a6e687 7049(@pxref{Value History, ,Value History}), after printing one out.
c906108c
SS
7050
7051Another way to create an artificial array is to use a cast.
7052This re-interprets a value as if it were an array.
7053The value need not be in memory:
474c8240 7054@smallexample
c906108c
SS
7055(@value{GDBP}) p/x (short[2])0x12345678
7056$1 = @{0x1234, 0x5678@}
474c8240 7057@end smallexample
c906108c
SS
7058
7059As a convenience, if you leave the array length out (as in
c3f6f71d 7060@samp{(@var{type}[])@var{value}}) @value{GDBN} calculates the size to fill
c906108c 7061the value (as @samp{sizeof(@var{value})/sizeof(@var{type})}:
474c8240 7062@smallexample
c906108c
SS
7063(@value{GDBP}) p/x (short[])0x12345678
7064$2 = @{0x1234, 0x5678@}
474c8240 7065@end smallexample
c906108c
SS
7066
7067Sometimes the artificial array mechanism is not quite enough; in
7068moderately complex data structures, the elements of interest may not
7069actually be adjacent---for example, if you are interested in the values
7070of pointers in an array. One useful work-around in this situation is
7071to use a convenience variable (@pxref{Convenience Vars, ,Convenience
79a6e687 7072Variables}) as a counter in an expression that prints the first
c906108c
SS
7073interesting value, and then repeat that expression via @key{RET}. For
7074instance, suppose you have an array @code{dtab} of pointers to
7075structures, and you are interested in the values of a field @code{fv}
7076in each structure. Here is an example of what you might type:
7077
474c8240 7078@smallexample
c906108c
SS
7079set $i = 0
7080p dtab[$i++]->fv
7081@key{RET}
7082@key{RET}
7083@dots{}
474c8240 7084@end smallexample
c906108c 7085
6d2ebf8b 7086@node Output Formats
79a6e687 7087@section Output Formats
c906108c
SS
7088
7089@cindex formatted output
7090@cindex output formats
7091By default, @value{GDBN} prints a value according to its data type. Sometimes
7092this is not what you want. For example, you might want to print a number
7093in hex, or a pointer in decimal. Or you might want to view data in memory
7094at a certain address as a character string or as an instruction. To do
7095these things, specify an @dfn{output format} when you print a value.
7096
7097The simplest use of output formats is to say how to print a value
7098already computed. This is done by starting the arguments of the
7099@code{print} command with a slash and a format letter. The format
7100letters supported are:
7101
7102@table @code
7103@item x
7104Regard the bits of the value as an integer, and print the integer in
7105hexadecimal.
7106
7107@item d
7108Print as integer in signed decimal.
7109
7110@item u
7111Print as integer in unsigned decimal.
7112
7113@item o
7114Print as integer in octal.
7115
7116@item t
7117Print as integer in binary. The letter @samp{t} stands for ``two''.
7118@footnote{@samp{b} cannot be used because these format letters are also
7119used with the @code{x} command, where @samp{b} stands for ``byte'';
79a6e687 7120see @ref{Memory,,Examining Memory}.}
c906108c
SS
7121
7122@item a
7123@cindex unknown address, locating
3d67e040 7124@cindex locate address
c906108c
SS
7125Print as an address, both absolute in hexadecimal and as an offset from
7126the nearest preceding symbol. You can use this format used to discover
7127where (in what function) an unknown address is located:
7128
474c8240 7129@smallexample
c906108c
SS
7130(@value{GDBP}) p/a 0x54320
7131$3 = 0x54320 <_initialize_vx+396>
474c8240 7132@end smallexample
c906108c 7133
3d67e040
EZ
7134@noindent
7135The command @code{info symbol 0x54320} yields similar results.
7136@xref{Symbols, info symbol}.
7137
c906108c 7138@item c
51274035
EZ
7139Regard as an integer and print it as a character constant. This
7140prints both the numerical value and its character representation. The
7141character representation is replaced with the octal escape @samp{\nnn}
7142for characters outside the 7-bit @sc{ascii} range.
c906108c 7143
ea37ba09
DJ
7144Without this format, @value{GDBN} displays @code{char},
7145@w{@code{unsigned char}}, and @w{@code{signed char}} data as character
7146constants. Single-byte members of vectors are displayed as integer
7147data.
7148
c906108c
SS
7149@item f
7150Regard the bits of the value as a floating point number and print
7151using typical floating point syntax.
ea37ba09
DJ
7152
7153@item s
7154@cindex printing strings
7155@cindex printing byte arrays
7156Regard as a string, if possible. With this format, pointers to single-byte
7157data are displayed as null-terminated strings and arrays of single-byte data
7158are displayed as fixed-length strings. Other values are displayed in their
7159natural types.
7160
7161Without this format, @value{GDBN} displays pointers to and arrays of
7162@code{char}, @w{@code{unsigned char}}, and @w{@code{signed char}} as
7163strings. Single-byte members of a vector are displayed as an integer
7164array.
a6bac58e
TT
7165
7166@item r
7167@cindex raw printing
7168Print using the @samp{raw} formatting. By default, @value{GDBN} will
78e2826b
TT
7169use a Python-based pretty-printer, if one is available (@pxref{Pretty
7170Printing}). This typically results in a higher-level display of the
7171value's contents. The @samp{r} format bypasses any Python
7172pretty-printer which might exist.
c906108c
SS
7173@end table
7174
7175For example, to print the program counter in hex (@pxref{Registers}), type
7176
474c8240 7177@smallexample
c906108c 7178p/x $pc
474c8240 7179@end smallexample
c906108c
SS
7180
7181@noindent
7182Note that no space is required before the slash; this is because command
7183names in @value{GDBN} cannot contain a slash.
7184
7185To reprint the last value in the value history with a different format,
7186you can use the @code{print} command with just a format and no
7187expression. For example, @samp{p/x} reprints the last value in hex.
7188
6d2ebf8b 7189@node Memory
79a6e687 7190@section Examining Memory
c906108c
SS
7191
7192You can use the command @code{x} (for ``examine'') to examine memory in
7193any of several formats, independently of your program's data types.
7194
7195@cindex examining memory
7196@table @code
41afff9a 7197@kindex x @r{(examine memory)}
c906108c
SS
7198@item x/@var{nfu} @var{addr}
7199@itemx x @var{addr}
7200@itemx x
7201Use the @code{x} command to examine memory.
7202@end table
7203
7204@var{n}, @var{f}, and @var{u} are all optional parameters that specify how
7205much memory to display and how to format it; @var{addr} is an
7206expression giving the address where you want to start displaying memory.
7207If you use defaults for @var{nfu}, you need not type the slash @samp{/}.
7208Several commands set convenient defaults for @var{addr}.
7209
7210@table @r
7211@item @var{n}, the repeat count
7212The repeat count is a decimal integer; the default is 1. It specifies
7213how much memory (counting by units @var{u}) to display.
7214@c This really is **decimal**; unaffected by 'set radix' as of GDB
7215@c 4.1.2.
7216
7217@item @var{f}, the display format
51274035
EZ
7218The display format is one of the formats used by @code{print}
7219(@samp{x}, @samp{d}, @samp{u}, @samp{o}, @samp{t}, @samp{a}, @samp{c},
ea37ba09
DJ
7220@samp{f}, @samp{s}), and in addition @samp{i} (for machine instructions).
7221The default is @samp{x} (hexadecimal) initially. The default changes
7222each time you use either @code{x} or @code{print}.
c906108c
SS
7223
7224@item @var{u}, the unit size
7225The unit size is any of
7226
7227@table @code
7228@item b
7229Bytes.
7230@item h
7231Halfwords (two bytes).
7232@item w
7233Words (four bytes). This is the initial default.
7234@item g
7235Giant words (eight bytes).
7236@end table
7237
7238Each time you specify a unit size with @code{x}, that size becomes the
7239default unit the next time you use @code{x}. (For the @samp{s} and
7240@samp{i} formats, the unit size is ignored and is normally not written.)
7241
7242@item @var{addr}, starting display address
7243@var{addr} is the address where you want @value{GDBN} to begin displaying
7244memory. The expression need not have a pointer value (though it may);
7245it is always interpreted as an integer address of a byte of memory.
7246@xref{Expressions, ,Expressions}, for more information on expressions. The default for
7247@var{addr} is usually just after the last address examined---but several
7248other commands also set the default address: @code{info breakpoints} (to
7249the address of the last breakpoint listed), @code{info line} (to the
7250starting address of a line), and @code{print} (if you use it to display
7251a value from memory).
7252@end table
7253
7254For example, @samp{x/3uh 0x54320} is a request to display three halfwords
7255(@code{h}) of memory, formatted as unsigned decimal integers (@samp{u}),
7256starting at address @code{0x54320}. @samp{x/4xw $sp} prints the four
7257words (@samp{w}) of memory above the stack pointer (here, @samp{$sp};
d4f3574e 7258@pxref{Registers, ,Registers}) in hexadecimal (@samp{x}).
c906108c
SS
7259
7260Since the letters indicating unit sizes are all distinct from the
7261letters specifying output formats, you do not have to remember whether
7262unit size or format comes first; either order works. The output
7263specifications @samp{4xw} and @samp{4wx} mean exactly the same thing.
7264(However, the count @var{n} must come first; @samp{wx4} does not work.)
7265
7266Even though the unit size @var{u} is ignored for the formats @samp{s}
7267and @samp{i}, you might still want to use a count @var{n}; for example,
7268@samp{3i} specifies that you want to see three machine instructions,
a4642986
MR
7269including any operands. For convenience, especially when used with
7270the @code{display} command, the @samp{i} format also prints branch delay
7271slot instructions, if any, beyond the count specified, which immediately
7272follow the last instruction that is within the count. The command
7273@code{disassemble} gives an alternative way of inspecting machine
7274instructions; see @ref{Machine Code,,Source and Machine Code}.
c906108c
SS
7275
7276All the defaults for the arguments to @code{x} are designed to make it
7277easy to continue scanning memory with minimal specifications each time
7278you use @code{x}. For example, after you have inspected three machine
7279instructions with @samp{x/3i @var{addr}}, you can inspect the next seven
7280with just @samp{x/7}. If you use @key{RET} to repeat the @code{x} command,
7281the repeat count @var{n} is used again; the other arguments default as
7282for successive uses of @code{x}.
7283
2b28d209
PP
7284When examining machine instructions, the instruction at current program
7285counter is shown with a @code{=>} marker. For example:
7286
7287@smallexample
7288(@value{GDBP}) x/5i $pc-6
7289 0x804837f <main+11>: mov %esp,%ebp
7290 0x8048381 <main+13>: push %ecx
7291 0x8048382 <main+14>: sub $0x4,%esp
7292=> 0x8048385 <main+17>: movl $0x8048460,(%esp)
7293 0x804838c <main+24>: call 0x80482d4 <puts@@plt>
7294@end smallexample
7295
c906108c
SS
7296@cindex @code{$_}, @code{$__}, and value history
7297The addresses and contents printed by the @code{x} command are not saved
7298in the value history because there is often too much of them and they
7299would get in the way. Instead, @value{GDBN} makes these values available for
7300subsequent use in expressions as values of the convenience variables
7301@code{$_} and @code{$__}. After an @code{x} command, the last address
7302examined is available for use in expressions in the convenience variable
7303@code{$_}. The contents of that address, as examined, are available in
7304the convenience variable @code{$__}.
7305
7306If the @code{x} command has a repeat count, the address and contents saved
7307are from the last memory unit printed; this is not the same as the last
7308address printed if several units were printed on the last line of output.
7309
09d4efe1
EZ
7310@cindex remote memory comparison
7311@cindex verify remote memory image
7312When you are debugging a program running on a remote target machine
ea35711c 7313(@pxref{Remote Debugging}), you may wish to verify the program's image in the
09d4efe1
EZ
7314remote machine's memory against the executable file you downloaded to
7315the target. The @code{compare-sections} command is provided for such
7316situations.
7317
7318@table @code
7319@kindex compare-sections
7320@item compare-sections @r{[}@var{section-name}@r{]}
7321Compare the data of a loadable section @var{section-name} in the
7322executable file of the program being debugged with the same section in
7323the remote machine's memory, and report any mismatches. With no
7324arguments, compares all loadable sections. This command's
7325availability depends on the target's support for the @code{"qCRC"}
7326remote request.
7327@end table
7328
6d2ebf8b 7329@node Auto Display
79a6e687 7330@section Automatic Display
c906108c
SS
7331@cindex automatic display
7332@cindex display of expressions
7333
7334If you find that you want to print the value of an expression frequently
7335(to see how it changes), you might want to add it to the @dfn{automatic
7336display list} so that @value{GDBN} prints its value each time your program stops.
7337Each expression added to the list is given a number to identify it;
7338to remove an expression from the list, you specify that number.
7339The automatic display looks like this:
7340
474c8240 7341@smallexample
c906108c
SS
73422: foo = 38
73433: bar[5] = (struct hack *) 0x3804
474c8240 7344@end smallexample
c906108c
SS
7345
7346@noindent
7347This display shows item numbers, expressions and their current values. As with
7348displays you request manually using @code{x} or @code{print}, you can
7349specify the output format you prefer; in fact, @code{display} decides
ea37ba09
DJ
7350whether to use @code{print} or @code{x} depending your format
7351specification---it uses @code{x} if you specify either the @samp{i}
7352or @samp{s} format, or a unit size; otherwise it uses @code{print}.
c906108c
SS
7353
7354@table @code
7355@kindex display
d4f3574e
SS
7356@item display @var{expr}
7357Add the expression @var{expr} to the list of expressions to display
c906108c
SS
7358each time your program stops. @xref{Expressions, ,Expressions}.
7359
7360@code{display} does not repeat if you press @key{RET} again after using it.
7361
d4f3574e 7362@item display/@var{fmt} @var{expr}
c906108c 7363For @var{fmt} specifying only a display format and not a size or
d4f3574e 7364count, add the expression @var{expr} to the auto-display list but
c906108c 7365arrange to display it each time in the specified format @var{fmt}.
79a6e687 7366@xref{Output Formats,,Output Formats}.
c906108c
SS
7367
7368@item display/@var{fmt} @var{addr}
7369For @var{fmt} @samp{i} or @samp{s}, or including a unit-size or a
7370number of units, add the expression @var{addr} as a memory address to
7371be examined each time your program stops. Examining means in effect
79a6e687 7372doing @samp{x/@var{fmt} @var{addr}}. @xref{Memory, ,Examining Memory}.
c906108c
SS
7373@end table
7374
7375For example, @samp{display/i $pc} can be helpful, to see the machine
7376instruction about to be executed each time execution stops (@samp{$pc}
d4f3574e 7377is a common name for the program counter; @pxref{Registers, ,Registers}).
c906108c
SS
7378
7379@table @code
7380@kindex delete display
7381@kindex undisplay
7382@item undisplay @var{dnums}@dots{}
7383@itemx delete display @var{dnums}@dots{}
7384Remove item numbers @var{dnums} from the list of expressions to display.
7385
7386@code{undisplay} does not repeat if you press @key{RET} after using it.
7387(Otherwise you would just get the error @samp{No display number @dots{}}.)
7388
7389@kindex disable display
7390@item disable display @var{dnums}@dots{}
7391Disable the display of item numbers @var{dnums}. A disabled display
7392item is not printed automatically, but is not forgotten. It may be
7393enabled again later.
7394
7395@kindex enable display
7396@item enable display @var{dnums}@dots{}
7397Enable display of item numbers @var{dnums}. It becomes effective once
7398again in auto display of its expression, until you specify otherwise.
7399
7400@item display
7401Display the current values of the expressions on the list, just as is
7402done when your program stops.
7403
7404@kindex info display
7405@item info display
7406Print the list of expressions previously set up to display
7407automatically, each one with its item number, but without showing the
7408values. This includes disabled expressions, which are marked as such.
7409It also includes expressions which would not be displayed right now
7410because they refer to automatic variables not currently available.
7411@end table
7412
15387254 7413@cindex display disabled out of scope
c906108c
SS
7414If a display expression refers to local variables, then it does not make
7415sense outside the lexical context for which it was set up. Such an
7416expression is disabled when execution enters a context where one of its
7417variables is not defined. For example, if you give the command
7418@code{display last_char} while inside a function with an argument
7419@code{last_char}, @value{GDBN} displays this argument while your program
7420continues to stop inside that function. When it stops elsewhere---where
7421there is no variable @code{last_char}---the display is disabled
7422automatically. The next time your program stops where @code{last_char}
7423is meaningful, you can enable the display expression once again.
7424
6d2ebf8b 7425@node Print Settings
79a6e687 7426@section Print Settings
c906108c
SS
7427
7428@cindex format options
7429@cindex print settings
7430@value{GDBN} provides the following ways to control how arrays, structures,
7431and symbols are printed.
7432
7433@noindent
7434These settings are useful for debugging programs in any language:
7435
7436@table @code
4644b6e3 7437@kindex set print
c906108c
SS
7438@item set print address
7439@itemx set print address on
4644b6e3 7440@cindex print/don't print memory addresses
c906108c
SS
7441@value{GDBN} prints memory addresses showing the location of stack
7442traces, structure values, pointer values, breakpoints, and so forth,
7443even when it also displays the contents of those addresses. The default
7444is @code{on}. For example, this is what a stack frame display looks like with
7445@code{set print address on}:
7446
7447@smallexample
7448@group
7449(@value{GDBP}) f
7450#0 set_quotes (lq=0x34c78 "<<", rq=0x34c88 ">>")
7451 at input.c:530
7452530 if (lquote != def_lquote)
7453@end group
7454@end smallexample
7455
7456@item set print address off
7457Do not print addresses when displaying their contents. For example,
7458this is the same stack frame displayed with @code{set print address off}:
7459
7460@smallexample
7461@group
7462(@value{GDBP}) set print addr off
7463(@value{GDBP}) f
7464#0 set_quotes (lq="<<", rq=">>") at input.c:530
7465530 if (lquote != def_lquote)
7466@end group
7467@end smallexample
7468
7469You can use @samp{set print address off} to eliminate all machine
7470dependent displays from the @value{GDBN} interface. For example, with
7471@code{print address off}, you should get the same text for backtraces on
7472all machines---whether or not they involve pointer arguments.
7473
4644b6e3 7474@kindex show print
c906108c
SS
7475@item show print address
7476Show whether or not addresses are to be printed.
7477@end table
7478
7479When @value{GDBN} prints a symbolic address, it normally prints the
7480closest earlier symbol plus an offset. If that symbol does not uniquely
7481identify the address (for example, it is a name whose scope is a single
7482source file), you may need to clarify. One way to do this is with
7483@code{info line}, for example @samp{info line *0x4537}. Alternately,
7484you can set @value{GDBN} to print the source file and line number when
7485it prints a symbolic address:
7486
7487@table @code
c906108c 7488@item set print symbol-filename on
9c16f35a
EZ
7489@cindex source file and line of a symbol
7490@cindex symbol, source file and line
c906108c
SS
7491Tell @value{GDBN} to print the source file name and line number of a
7492symbol in the symbolic form of an address.
7493
7494@item set print symbol-filename off
7495Do not print source file name and line number of a symbol. This is the
7496default.
7497
c906108c
SS
7498@item show print symbol-filename
7499Show whether or not @value{GDBN} will print the source file name and
7500line number of a symbol in the symbolic form of an address.
7501@end table
7502
7503Another situation where it is helpful to show symbol filenames and line
7504numbers is when disassembling code; @value{GDBN} shows you the line
7505number and source file that corresponds to each instruction.
7506
7507Also, you may wish to see the symbolic form only if the address being
7508printed is reasonably close to the closest earlier symbol:
7509
7510@table @code
c906108c 7511@item set print max-symbolic-offset @var{max-offset}
4644b6e3 7512@cindex maximum value for offset of closest symbol
c906108c
SS
7513Tell @value{GDBN} to only display the symbolic form of an address if the
7514offset between the closest earlier symbol and the address is less than
5d161b24 7515@var{max-offset}. The default is 0, which tells @value{GDBN}
c906108c
SS
7516to always print the symbolic form of an address if any symbol precedes it.
7517
c906108c
SS
7518@item show print max-symbolic-offset
7519Ask how large the maximum offset is that @value{GDBN} prints in a
7520symbolic address.
7521@end table
7522
7523@cindex wild pointer, interpreting
7524@cindex pointer, finding referent
7525If you have a pointer and you are not sure where it points, try
7526@samp{set print symbol-filename on}. Then you can determine the name
7527and source file location of the variable where it points, using
7528@samp{p/a @var{pointer}}. This interprets the address in symbolic form.
7529For example, here @value{GDBN} shows that a variable @code{ptt} points
7530at another variable @code{t}, defined in @file{hi2.c}:
7531
474c8240 7532@smallexample
c906108c
SS
7533(@value{GDBP}) set print symbol-filename on
7534(@value{GDBP}) p/a ptt
7535$4 = 0xe008 <t in hi2.c>
474c8240 7536@end smallexample
c906108c
SS
7537
7538@quotation
7539@emph{Warning:} For pointers that point to a local variable, @samp{p/a}
7540does not show the symbol name and filename of the referent, even with
7541the appropriate @code{set print} options turned on.
7542@end quotation
7543
7544Other settings control how different kinds of objects are printed:
7545
7546@table @code
c906108c
SS
7547@item set print array
7548@itemx set print array on
4644b6e3 7549@cindex pretty print arrays
c906108c
SS
7550Pretty print arrays. This format is more convenient to read,
7551but uses more space. The default is off.
7552
7553@item set print array off
7554Return to compressed format for arrays.
7555
c906108c
SS
7556@item show print array
7557Show whether compressed or pretty format is selected for displaying
7558arrays.
7559
3c9c013a
JB
7560@cindex print array indexes
7561@item set print array-indexes
7562@itemx set print array-indexes on
7563Print the index of each element when displaying arrays. May be more
7564convenient to locate a given element in the array or quickly find the
7565index of a given element in that printed array. The default is off.
7566
7567@item set print array-indexes off
7568Stop printing element indexes when displaying arrays.
7569
7570@item show print array-indexes
7571Show whether the index of each element is printed when displaying
7572arrays.
7573
c906108c 7574@item set print elements @var{number-of-elements}
4644b6e3 7575@cindex number of array elements to print
9c16f35a 7576@cindex limit on number of printed array elements
c906108c
SS
7577Set a limit on how many elements of an array @value{GDBN} will print.
7578If @value{GDBN} is printing a large array, it stops printing after it has
7579printed the number of elements set by the @code{set print elements} command.
7580This limit also applies to the display of strings.
d4f3574e 7581When @value{GDBN} starts, this limit is set to 200.
c906108c
SS
7582Setting @var{number-of-elements} to zero means that the printing is unlimited.
7583
c906108c
SS
7584@item show print elements
7585Display the number of elements of a large array that @value{GDBN} will print.
7586If the number is 0, then the printing is unlimited.
7587
b4740add 7588@item set print frame-arguments @var{value}
a0381d3a 7589@kindex set print frame-arguments
b4740add
JB
7590@cindex printing frame argument values
7591@cindex print all frame argument values
7592@cindex print frame argument values for scalars only
7593@cindex do not print frame argument values
7594This command allows to control how the values of arguments are printed
7595when the debugger prints a frame (@pxref{Frames}). The possible
7596values are:
7597
7598@table @code
7599@item all
4f5376b2 7600The values of all arguments are printed.
b4740add
JB
7601
7602@item scalars
7603Print the value of an argument only if it is a scalar. The value of more
7604complex arguments such as arrays, structures, unions, etc, is replaced
4f5376b2
JB
7605by @code{@dots{}}. This is the default. Here is an example where
7606only scalar arguments are shown:
b4740add
JB
7607
7608@smallexample
7609#1 0x08048361 in call_me (i=3, s=@dots{}, ss=0xbf8d508c, u=@dots{}, e=green)
7610 at frame-args.c:23
7611@end smallexample
7612
7613@item none
7614None of the argument values are printed. Instead, the value of each argument
7615is replaced by @code{@dots{}}. In this case, the example above now becomes:
7616
7617@smallexample
7618#1 0x08048361 in call_me (i=@dots{}, s=@dots{}, ss=@dots{}, u=@dots{}, e=@dots{})
7619 at frame-args.c:23
7620@end smallexample
7621@end table
7622
4f5376b2
JB
7623By default, only scalar arguments are printed. This command can be used
7624to configure the debugger to print the value of all arguments, regardless
7625of their type. However, it is often advantageous to not print the value
7626of more complex parameters. For instance, it reduces the amount of
7627information printed in each frame, making the backtrace more readable.
7628Also, it improves performance when displaying Ada frames, because
7629the computation of large arguments can sometimes be CPU-intensive,
7630especially in large applications. Setting @code{print frame-arguments}
7631to @code{scalars} (the default) or @code{none} avoids this computation,
7632thus speeding up the display of each Ada frame.
b4740add
JB
7633
7634@item show print frame-arguments
7635Show how the value of arguments should be displayed when printing a frame.
7636
9c16f35a
EZ
7637@item set print repeats
7638@cindex repeated array elements
7639Set the threshold for suppressing display of repeated array
d3e8051b 7640elements. When the number of consecutive identical elements of an
9c16f35a
EZ
7641array exceeds the threshold, @value{GDBN} prints the string
7642@code{"<repeats @var{n} times>"}, where @var{n} is the number of
7643identical repetitions, instead of displaying the identical elements
7644themselves. Setting the threshold to zero will cause all elements to
7645be individually printed. The default threshold is 10.
7646
7647@item show print repeats
7648Display the current threshold for printing repeated identical
7649elements.
7650
c906108c 7651@item set print null-stop
4644b6e3 7652@cindex @sc{null} elements in arrays
c906108c 7653Cause @value{GDBN} to stop printing the characters of an array when the first
d4f3574e 7654@sc{null} is encountered. This is useful when large arrays actually
c906108c 7655contain only short strings.
d4f3574e 7656The default is off.
c906108c 7657
9c16f35a
EZ
7658@item show print null-stop
7659Show whether @value{GDBN} stops printing an array on the first
7660@sc{null} character.
7661
c906108c 7662@item set print pretty on
9c16f35a
EZ
7663@cindex print structures in indented form
7664@cindex indentation in structure display
5d161b24 7665Cause @value{GDBN} to print structures in an indented format with one member
c906108c
SS
7666per line, like this:
7667
7668@smallexample
7669@group
7670$1 = @{
7671 next = 0x0,
7672 flags = @{
7673 sweet = 1,
7674 sour = 1
7675 @},
7676 meat = 0x54 "Pork"
7677@}
7678@end group
7679@end smallexample
7680
7681@item set print pretty off
7682Cause @value{GDBN} to print structures in a compact format, like this:
7683
7684@smallexample
7685@group
7686$1 = @{next = 0x0, flags = @{sweet = 1, sour = 1@}, \
7687meat = 0x54 "Pork"@}
7688@end group
7689@end smallexample
7690
7691@noindent
7692This is the default format.
7693
c906108c
SS
7694@item show print pretty
7695Show which format @value{GDBN} is using to print structures.
7696
c906108c 7697@item set print sevenbit-strings on
4644b6e3
EZ
7698@cindex eight-bit characters in strings
7699@cindex octal escapes in strings
c906108c
SS
7700Print using only seven-bit characters; if this option is set,
7701@value{GDBN} displays any eight-bit characters (in strings or
7702character values) using the notation @code{\}@var{nnn}. This setting is
7703best if you are working in English (@sc{ascii}) and you use the
7704high-order bit of characters as a marker or ``meta'' bit.
7705
7706@item set print sevenbit-strings off
7707Print full eight-bit characters. This allows the use of more
7708international character sets, and is the default.
7709
c906108c
SS
7710@item show print sevenbit-strings
7711Show whether or not @value{GDBN} is printing only seven-bit characters.
7712
c906108c 7713@item set print union on
4644b6e3 7714@cindex unions in structures, printing
9c16f35a
EZ
7715Tell @value{GDBN} to print unions which are contained in structures
7716and other unions. This is the default setting.
c906108c
SS
7717
7718@item set print union off
9c16f35a
EZ
7719Tell @value{GDBN} not to print unions which are contained in
7720structures and other unions. @value{GDBN} will print @code{"@{...@}"}
7721instead.
c906108c 7722
c906108c
SS
7723@item show print union
7724Ask @value{GDBN} whether or not it will print unions which are contained in
9c16f35a 7725structures and other unions.
c906108c
SS
7726
7727For example, given the declarations
7728
7729@smallexample
7730typedef enum @{Tree, Bug@} Species;
7731typedef enum @{Big_tree, Acorn, Seedling@} Tree_forms;
5d161b24 7732typedef enum @{Caterpillar, Cocoon, Butterfly@}
c906108c
SS
7733 Bug_forms;
7734
7735struct thing @{
7736 Species it;
7737 union @{
7738 Tree_forms tree;
7739 Bug_forms bug;
7740 @} form;
7741@};
7742
7743struct thing foo = @{Tree, @{Acorn@}@};
7744@end smallexample
7745
7746@noindent
7747with @code{set print union on} in effect @samp{p foo} would print
7748
7749@smallexample
7750$1 = @{it = Tree, form = @{tree = Acorn, bug = Cocoon@}@}
7751@end smallexample
7752
7753@noindent
7754and with @code{set print union off} in effect it would print
7755
7756@smallexample
7757$1 = @{it = Tree, form = @{...@}@}
7758@end smallexample
9c16f35a
EZ
7759
7760@noindent
7761@code{set print union} affects programs written in C-like languages
7762and in Pascal.
c906108c
SS
7763@end table
7764
c906108c
SS
7765@need 1000
7766@noindent
b37052ae 7767These settings are of interest when debugging C@t{++} programs:
c906108c
SS
7768
7769@table @code
4644b6e3 7770@cindex demangling C@t{++} names
c906108c
SS
7771@item set print demangle
7772@itemx set print demangle on
b37052ae 7773Print C@t{++} names in their source form rather than in the encoded
c906108c 7774(``mangled'') form passed to the assembler and linker for type-safe
d4f3574e 7775linkage. The default is on.
c906108c 7776
c906108c 7777@item show print demangle
b37052ae 7778Show whether C@t{++} names are printed in mangled or demangled form.
c906108c 7779
c906108c
SS
7780@item set print asm-demangle
7781@itemx set print asm-demangle on
b37052ae 7782Print C@t{++} names in their source form rather than their mangled form, even
c906108c
SS
7783in assembler code printouts such as instruction disassemblies.
7784The default is off.
7785
c906108c 7786@item show print asm-demangle
b37052ae 7787Show whether C@t{++} names in assembly listings are printed in mangled
c906108c
SS
7788or demangled form.
7789
b37052ae
EZ
7790@cindex C@t{++} symbol decoding style
7791@cindex symbol decoding style, C@t{++}
a8f24a35 7792@kindex set demangle-style
c906108c
SS
7793@item set demangle-style @var{style}
7794Choose among several encoding schemes used by different compilers to
b37052ae 7795represent C@t{++} names. The choices for @var{style} are currently:
c906108c
SS
7796
7797@table @code
7798@item auto
7799Allow @value{GDBN} to choose a decoding style by inspecting your program.
7800
7801@item gnu
b37052ae 7802Decode based on the @sc{gnu} C@t{++} compiler (@code{g++}) encoding algorithm.
c906108c 7803This is the default.
c906108c
SS
7804
7805@item hp
b37052ae 7806Decode based on the HP ANSI C@t{++} (@code{aCC}) encoding algorithm.
c906108c
SS
7807
7808@item lucid
b37052ae 7809Decode based on the Lucid C@t{++} compiler (@code{lcc}) encoding algorithm.
c906108c
SS
7810
7811@item arm
b37052ae 7812Decode using the algorithm in the @cite{C@t{++} Annotated Reference Manual}.
c906108c
SS
7813@strong{Warning:} this setting alone is not sufficient to allow
7814debugging @code{cfront}-generated executables. @value{GDBN} would
7815require further enhancement to permit that.
7816
7817@end table
7818If you omit @var{style}, you will see a list of possible formats.
7819
c906108c 7820@item show demangle-style
b37052ae 7821Display the encoding style currently in use for decoding C@t{++} symbols.
c906108c 7822
c906108c
SS
7823@item set print object
7824@itemx set print object on
4644b6e3 7825@cindex derived type of an object, printing
9c16f35a 7826@cindex display derived types
c906108c
SS
7827When displaying a pointer to an object, identify the @emph{actual}
7828(derived) type of the object rather than the @emph{declared} type, using
7829the virtual function table.
7830
7831@item set print object off
7832Display only the declared type of objects, without reference to the
7833virtual function table. This is the default setting.
7834
c906108c
SS
7835@item show print object
7836Show whether actual, or declared, object types are displayed.
7837
c906108c
SS
7838@item set print static-members
7839@itemx set print static-members on
4644b6e3 7840@cindex static members of C@t{++} objects
b37052ae 7841Print static members when displaying a C@t{++} object. The default is on.
c906108c
SS
7842
7843@item set print static-members off
b37052ae 7844Do not print static members when displaying a C@t{++} object.
c906108c 7845
c906108c 7846@item show print static-members
9c16f35a
EZ
7847Show whether C@t{++} static members are printed or not.
7848
7849@item set print pascal_static-members
7850@itemx set print pascal_static-members on
d3e8051b
EZ
7851@cindex static members of Pascal objects
7852@cindex Pascal objects, static members display
9c16f35a
EZ
7853Print static members when displaying a Pascal object. The default is on.
7854
7855@item set print pascal_static-members off
7856Do not print static members when displaying a Pascal object.
7857
7858@item show print pascal_static-members
7859Show whether Pascal static members are printed or not.
c906108c
SS
7860
7861@c These don't work with HP ANSI C++ yet.
c906108c
SS
7862@item set print vtbl
7863@itemx set print vtbl on
4644b6e3 7864@cindex pretty print C@t{++} virtual function tables
9c16f35a
EZ
7865@cindex virtual functions (C@t{++}) display
7866@cindex VTBL display
b37052ae 7867Pretty print C@t{++} virtual function tables. The default is off.
c906108c 7868(The @code{vtbl} commands do not work on programs compiled with the HP
b37052ae 7869ANSI C@t{++} compiler (@code{aCC}).)
c906108c
SS
7870
7871@item set print vtbl off
b37052ae 7872Do not pretty print C@t{++} virtual function tables.
c906108c 7873
c906108c 7874@item show print vtbl
b37052ae 7875Show whether C@t{++} virtual function tables are pretty printed, or not.
c906108c 7876@end table
c906108c 7877
6d2ebf8b 7878@node Value History
79a6e687 7879@section Value History
c906108c
SS
7880
7881@cindex value history
9c16f35a 7882@cindex history of values printed by @value{GDBN}
5d161b24
DB
7883Values printed by the @code{print} command are saved in the @value{GDBN}
7884@dfn{value history}. This allows you to refer to them in other expressions.
7885Values are kept until the symbol table is re-read or discarded
7886(for example with the @code{file} or @code{symbol-file} commands).
7887When the symbol table changes, the value history is discarded,
7888since the values may contain pointers back to the types defined in the
c906108c
SS
7889symbol table.
7890
7891@cindex @code{$}
7892@cindex @code{$$}
7893@cindex history number
7894The values printed are given @dfn{history numbers} by which you can
7895refer to them. These are successive integers starting with one.
7896@code{print} shows you the history number assigned to a value by
7897printing @samp{$@var{num} = } before the value; here @var{num} is the
7898history number.
7899
7900To refer to any previous value, use @samp{$} followed by the value's
7901history number. The way @code{print} labels its output is designed to
7902remind you of this. Just @code{$} refers to the most recent value in
7903the history, and @code{$$} refers to the value before that.
7904@code{$$@var{n}} refers to the @var{n}th value from the end; @code{$$2}
7905is the value just prior to @code{$$}, @code{$$1} is equivalent to
7906@code{$$}, and @code{$$0} is equivalent to @code{$}.
7907
7908For example, suppose you have just printed a pointer to a structure and
7909want to see the contents of the structure. It suffices to type
7910
474c8240 7911@smallexample
c906108c 7912p *$
474c8240 7913@end smallexample
c906108c
SS
7914
7915If you have a chain of structures where the component @code{next} points
7916to the next one, you can print the contents of the next one with this:
7917
474c8240 7918@smallexample
c906108c 7919p *$.next
474c8240 7920@end smallexample
c906108c
SS
7921
7922@noindent
7923You can print successive links in the chain by repeating this
7924command---which you can do by just typing @key{RET}.
7925
7926Note that the history records values, not expressions. If the value of
7927@code{x} is 4 and you type these commands:
7928
474c8240 7929@smallexample
c906108c
SS
7930print x
7931set x=5
474c8240 7932@end smallexample
c906108c
SS
7933
7934@noindent
7935then the value recorded in the value history by the @code{print} command
7936remains 4 even though the value of @code{x} has changed.
7937
7938@table @code
7939@kindex show values
7940@item show values
7941Print the last ten values in the value history, with their item numbers.
7942This is like @samp{p@ $$9} repeated ten times, except that @code{show
7943values} does not change the history.
7944
7945@item show values @var{n}
7946Print ten history values centered on history item number @var{n}.
7947
7948@item show values +
7949Print ten history values just after the values last printed. If no more
7950values are available, @code{show values +} produces no display.
7951@end table
7952
7953Pressing @key{RET} to repeat @code{show values @var{n}} has exactly the
7954same effect as @samp{show values +}.
7955
6d2ebf8b 7956@node Convenience Vars
79a6e687 7957@section Convenience Variables
c906108c
SS
7958
7959@cindex convenience variables
9c16f35a 7960@cindex user-defined variables
c906108c
SS
7961@value{GDBN} provides @dfn{convenience variables} that you can use within
7962@value{GDBN} to hold on to a value and refer to it later. These variables
7963exist entirely within @value{GDBN}; they are not part of your program, and
7964setting a convenience variable has no direct effect on further execution
7965of your program. That is why you can use them freely.
7966
7967Convenience variables are prefixed with @samp{$}. Any name preceded by
7968@samp{$} can be used for a convenience variable, unless it is one of
d4f3574e 7969the predefined machine-specific register names (@pxref{Registers, ,Registers}).
c906108c 7970(Value history references, in contrast, are @emph{numbers} preceded
79a6e687 7971by @samp{$}. @xref{Value History, ,Value History}.)
c906108c
SS
7972
7973You can save a value in a convenience variable with an assignment
7974expression, just as you would set a variable in your program.
7975For example:
7976
474c8240 7977@smallexample
c906108c 7978set $foo = *object_ptr
474c8240 7979@end smallexample
c906108c
SS
7980
7981@noindent
7982would save in @code{$foo} the value contained in the object pointed to by
7983@code{object_ptr}.
7984
7985Using a convenience variable for the first time creates it, but its
7986value is @code{void} until you assign a new value. You can alter the
7987value with another assignment at any time.
7988
7989Convenience variables have no fixed types. You can assign a convenience
7990variable any type of value, including structures and arrays, even if
7991that variable already has a value of a different type. The convenience
7992variable, when used as an expression, has the type of its current value.
7993
7994@table @code
7995@kindex show convenience
9c16f35a 7996@cindex show all user variables
c906108c
SS
7997@item show convenience
7998Print a list of convenience variables used so far, and their values.
d4f3574e 7999Abbreviated @code{show conv}.
53e5f3cf
AS
8000
8001@kindex init-if-undefined
8002@cindex convenience variables, initializing
8003@item init-if-undefined $@var{variable} = @var{expression}
8004Set a convenience variable if it has not already been set. This is useful
8005for user-defined commands that keep some state. It is similar, in concept,
8006to using local static variables with initializers in C (except that
8007convenience variables are global). It can also be used to allow users to
8008override default values used in a command script.
8009
8010If the variable is already defined then the expression is not evaluated so
8011any side-effects do not occur.
c906108c
SS
8012@end table
8013
8014One of the ways to use a convenience variable is as a counter to be
8015incremented or a pointer to be advanced. For example, to print
8016a field from successive elements of an array of structures:
8017
474c8240 8018@smallexample
c906108c
SS
8019set $i = 0
8020print bar[$i++]->contents
474c8240 8021@end smallexample
c906108c 8022
d4f3574e
SS
8023@noindent
8024Repeat that command by typing @key{RET}.
c906108c
SS
8025
8026Some convenience variables are created automatically by @value{GDBN} and given
8027values likely to be useful.
8028
8029@table @code
41afff9a 8030@vindex $_@r{, convenience variable}
c906108c
SS
8031@item $_
8032The variable @code{$_} is automatically set by the @code{x} command to
79a6e687 8033the last address examined (@pxref{Memory, ,Examining Memory}). Other
c906108c
SS
8034commands which provide a default address for @code{x} to examine also
8035set @code{$_} to that address; these commands include @code{info line}
8036and @code{info breakpoint}. The type of @code{$_} is @code{void *}
8037except when set by the @code{x} command, in which case it is a pointer
8038to the type of @code{$__}.
8039
41afff9a 8040@vindex $__@r{, convenience variable}
c906108c
SS
8041@item $__
8042The variable @code{$__} is automatically set by the @code{x} command
8043to the value found in the last address examined. Its type is chosen
8044to match the format in which the data was printed.
8045
8046@item $_exitcode
41afff9a 8047@vindex $_exitcode@r{, convenience variable}
c906108c
SS
8048The variable @code{$_exitcode} is automatically set to the exit code when
8049the program being debugged terminates.
4aa995e1
PA
8050
8051@item $_siginfo
8052@vindex $_siginfo@r{, convenience variable}
ec7e75e7
PP
8053The variable @code{$_siginfo} contains extra signal information
8054(@pxref{extra signal information}). Note that @code{$_siginfo}
8055could be empty, if the application has not yet received any signals.
8056For example, it will be empty before you execute the @code{run} command.
c906108c
SS
8057@end table
8058
53a5351d
JM
8059On HP-UX systems, if you refer to a function or variable name that
8060begins with a dollar sign, @value{GDBN} searches for a user or system
8061name first, before it searches for a convenience variable.
c906108c 8062
bc3b79fd
TJB
8063@cindex convenience functions
8064@value{GDBN} also supplies some @dfn{convenience functions}. These
8065have a syntax similar to convenience variables. A convenience
8066function can be used in an expression just like an ordinary function;
8067however, a convenience function is implemented internally to
8068@value{GDBN}.
8069
8070@table @code
8071@item help function
8072@kindex help function
8073@cindex show all convenience functions
8074Print a list of all convenience functions.
8075@end table
8076
6d2ebf8b 8077@node Registers
c906108c
SS
8078@section Registers
8079
8080@cindex registers
8081You can refer to machine register contents, in expressions, as variables
8082with names starting with @samp{$}. The names of registers are different
8083for each machine; use @code{info registers} to see the names used on
8084your machine.
8085
8086@table @code
8087@kindex info registers
8088@item info registers
8089Print the names and values of all registers except floating-point
c85508ee 8090and vector registers (in the selected stack frame).
c906108c
SS
8091
8092@kindex info all-registers
8093@cindex floating point registers
8094@item info all-registers
8095Print the names and values of all registers, including floating-point
c85508ee 8096and vector registers (in the selected stack frame).
c906108c
SS
8097
8098@item info registers @var{regname} @dots{}
8099Print the @dfn{relativized} value of each specified register @var{regname}.
5d161b24
DB
8100As discussed in detail below, register values are normally relative to
8101the selected stack frame. @var{regname} may be any register name valid on
c906108c
SS
8102the machine you are using, with or without the initial @samp{$}.
8103@end table
8104
e09f16f9
EZ
8105@cindex stack pointer register
8106@cindex program counter register
8107@cindex process status register
8108@cindex frame pointer register
8109@cindex standard registers
c906108c
SS
8110@value{GDBN} has four ``standard'' register names that are available (in
8111expressions) on most machines---whenever they do not conflict with an
8112architecture's canonical mnemonics for registers. The register names
8113@code{$pc} and @code{$sp} are used for the program counter register and
8114the stack pointer. @code{$fp} is used for a register that contains a
8115pointer to the current stack frame, and @code{$ps} is used for a
8116register that contains the processor status. For example,
8117you could print the program counter in hex with
8118
474c8240 8119@smallexample
c906108c 8120p/x $pc
474c8240 8121@end smallexample
c906108c
SS
8122
8123@noindent
8124or print the instruction to be executed next with
8125
474c8240 8126@smallexample
c906108c 8127x/i $pc
474c8240 8128@end smallexample
c906108c
SS
8129
8130@noindent
8131or add four to the stack pointer@footnote{This is a way of removing
8132one word from the stack, on machines where stacks grow downward in
8133memory (most machines, nowadays). This assumes that the innermost
8134stack frame is selected; setting @code{$sp} is not allowed when other
8135stack frames are selected. To pop entire frames off the stack,
8136regardless of machine architecture, use @code{return};
79a6e687 8137see @ref{Returning, ,Returning from a Function}.} with
c906108c 8138
474c8240 8139@smallexample
c906108c 8140set $sp += 4
474c8240 8141@end smallexample
c906108c
SS
8142
8143Whenever possible, these four standard register names are available on
8144your machine even though the machine has different canonical mnemonics,
8145so long as there is no conflict. The @code{info registers} command
8146shows the canonical names. For example, on the SPARC, @code{info
8147registers} displays the processor status register as @code{$psr} but you
d4f3574e
SS
8148can also refer to it as @code{$ps}; and on x86-based machines @code{$ps}
8149is an alias for the @sc{eflags} register.
c906108c
SS
8150
8151@value{GDBN} always considers the contents of an ordinary register as an
8152integer when the register is examined in this way. Some machines have
8153special registers which can hold nothing but floating point; these
8154registers are considered to have floating point values. There is no way
8155to refer to the contents of an ordinary register as floating point value
8156(although you can @emph{print} it as a floating point value with
8157@samp{print/f $@var{regname}}).
8158
8159Some registers have distinct ``raw'' and ``virtual'' data formats. This
8160means that the data format in which the register contents are saved by
8161the operating system is not the same one that your program normally
8162sees. For example, the registers of the 68881 floating point
8163coprocessor are always saved in ``extended'' (raw) format, but all C
8164programs expect to work with ``double'' (virtual) format. In such
5d161b24 8165cases, @value{GDBN} normally works with the virtual format only (the format
c906108c
SS
8166that makes sense for your program), but the @code{info registers} command
8167prints the data in both formats.
8168
36b80e65
EZ
8169@cindex SSE registers (x86)
8170@cindex MMX registers (x86)
8171Some machines have special registers whose contents can be interpreted
8172in several different ways. For example, modern x86-based machines
8173have SSE and MMX registers that can hold several values packed
8174together in several different formats. @value{GDBN} refers to such
8175registers in @code{struct} notation:
8176
8177@smallexample
8178(@value{GDBP}) print $xmm1
8179$1 = @{
8180 v4_float = @{0, 3.43859137e-038, 1.54142831e-044, 1.821688e-044@},
8181 v2_double = @{9.92129282474342e-303, 2.7585945287983262e-313@},
8182 v16_int8 = "\000\000\000\000\3706;\001\v\000\000\000\r\000\000",
8183 v8_int16 = @{0, 0, 14072, 315, 11, 0, 13, 0@},
8184 v4_int32 = @{0, 20657912, 11, 13@},
8185 v2_int64 = @{88725056443645952, 55834574859@},
8186 uint128 = 0x0000000d0000000b013b36f800000000
8187@}
8188@end smallexample
8189
8190@noindent
8191To set values of such registers, you need to tell @value{GDBN} which
8192view of the register you wish to change, as if you were assigning
8193value to a @code{struct} member:
8194
8195@smallexample
8196 (@value{GDBP}) set $xmm1.uint128 = 0x000000000000000000000000FFFFFFFF
8197@end smallexample
8198
c906108c 8199Normally, register values are relative to the selected stack frame
79a6e687 8200(@pxref{Selection, ,Selecting a Frame}). This means that you get the
c906108c
SS
8201value that the register would contain if all stack frames farther in
8202were exited and their saved registers restored. In order to see the
8203true contents of hardware registers, you must select the innermost
8204frame (with @samp{frame 0}).
8205
8206However, @value{GDBN} must deduce where registers are saved, from the machine
8207code generated by your compiler. If some registers are not saved, or if
8208@value{GDBN} is unable to locate the saved registers, the selected stack
8209frame makes no difference.
8210
6d2ebf8b 8211@node Floating Point Hardware
79a6e687 8212@section Floating Point Hardware
c906108c
SS
8213@cindex floating point
8214
8215Depending on the configuration, @value{GDBN} may be able to give
8216you more information about the status of the floating point hardware.
8217
8218@table @code
8219@kindex info float
8220@item info float
8221Display hardware-dependent information about the floating
8222point unit. The exact contents and layout vary depending on the
8223floating point chip. Currently, @samp{info float} is supported on
8224the ARM and x86 machines.
8225@end table
c906108c 8226
e76f1f2e
AC
8227@node Vector Unit
8228@section Vector Unit
8229@cindex vector unit
8230
8231Depending on the configuration, @value{GDBN} may be able to give you
8232more information about the status of the vector unit.
8233
8234@table @code
8235@kindex info vector
8236@item info vector
8237Display information about the vector unit. The exact contents and
8238layout vary depending on the hardware.
8239@end table
8240
721c2651 8241@node OS Information
79a6e687 8242@section Operating System Auxiliary Information
721c2651
EZ
8243@cindex OS information
8244
8245@value{GDBN} provides interfaces to useful OS facilities that can help
8246you debug your program.
8247
8248@cindex @code{ptrace} system call
8249@cindex @code{struct user} contents
8250When @value{GDBN} runs on a @dfn{Posix system} (such as GNU or Unix
8251machines), it interfaces with the inferior via the @code{ptrace}
8252system call. The operating system creates a special sata structure,
8253called @code{struct user}, for this interface. You can use the
8254command @code{info udot} to display the contents of this data
8255structure.
8256
8257@table @code
8258@item info udot
8259@kindex info udot
8260Display the contents of the @code{struct user} maintained by the OS
8261kernel for the program being debugged. @value{GDBN} displays the
8262contents of @code{struct user} as a list of hex numbers, similar to
8263the @code{examine} command.
8264@end table
8265
b383017d
RM
8266@cindex auxiliary vector
8267@cindex vector, auxiliary
b383017d
RM
8268Some operating systems supply an @dfn{auxiliary vector} to programs at
8269startup. This is akin to the arguments and environment that you
8270specify for a program, but contains a system-dependent variety of
8271binary values that tell system libraries important details about the
8272hardware, operating system, and process. Each value's purpose is
8273identified by an integer tag; the meanings are well-known but system-specific.
8274Depending on the configuration and operating system facilities,
9c16f35a
EZ
8275@value{GDBN} may be able to show you this information. For remote
8276targets, this functionality may further depend on the remote stub's
427c3a89
DJ
8277support of the @samp{qXfer:auxv:read} packet, see
8278@ref{qXfer auxiliary vector read}.
b383017d
RM
8279
8280@table @code
8281@kindex info auxv
8282@item info auxv
8283Display the auxiliary vector of the inferior, which can be either a
e4937fc1 8284live process or a core dump file. @value{GDBN} prints each tag value
b383017d
RM
8285numerically, and also shows names and text descriptions for recognized
8286tags. Some values in the vector are numbers, some bit masks, and some
e4937fc1 8287pointers to strings or other data. @value{GDBN} displays each value in the
b383017d
RM
8288most appropriate form for a recognized tag, and in hexadecimal for
8289an unrecognized tag.
8290@end table
8291
07e059b5
VP
8292On some targets, @value{GDBN} can access operating-system-specific information
8293and display it to user, without interpretation. For remote targets,
8294this functionality depends on the remote stub's support of the
8295@samp{qXfer:osdata:read} packet, see @ref{qXfer osdata read}.
8296
8297@table @code
8298@kindex info os processes
8299@item info os processes
8300Display the list of processes on the target. For each process,
8301@value{GDBN} prints the process identifier, the name of the user, and
8302the command corresponding to the process.
8303@end table
721c2651 8304
29e57380 8305@node Memory Region Attributes
79a6e687 8306@section Memory Region Attributes
29e57380
C
8307@cindex memory region attributes
8308
b383017d 8309@dfn{Memory region attributes} allow you to describe special handling
fd79ecee
DJ
8310required by regions of your target's memory. @value{GDBN} uses
8311attributes to determine whether to allow certain types of memory
8312accesses; whether to use specific width accesses; and whether to cache
8313target memory. By default the description of memory regions is
8314fetched from the target (if the current target supports this), but the
8315user can override the fetched regions.
29e57380
C
8316
8317Defined memory regions can be individually enabled and disabled. When a
8318memory region is disabled, @value{GDBN} uses the default attributes when
8319accessing memory in that region. Similarly, if no memory regions have
8320been defined, @value{GDBN} uses the default attributes when accessing
8321all memory.
8322
b383017d 8323When a memory region is defined, it is given a number to identify it;
29e57380
C
8324to enable, disable, or remove a memory region, you specify that number.
8325
8326@table @code
8327@kindex mem
bfac230e 8328@item mem @var{lower} @var{upper} @var{attributes}@dots{}
09d4efe1
EZ
8329Define a memory region bounded by @var{lower} and @var{upper} with
8330attributes @var{attributes}@dots{}, and add it to the list of regions
8331monitored by @value{GDBN}. Note that @var{upper} == 0 is a special
d3e8051b 8332case: it is treated as the target's maximum memory address.
bfac230e 8333(0xffff on 16 bit targets, 0xffffffff on 32 bit targets, etc.)
29e57380 8334
fd79ecee
DJ
8335@item mem auto
8336Discard any user changes to the memory regions and use target-supplied
8337regions, if available, or no regions if the target does not support.
8338
29e57380
C
8339@kindex delete mem
8340@item delete mem @var{nums}@dots{}
09d4efe1
EZ
8341Remove memory regions @var{nums}@dots{} from the list of regions
8342monitored by @value{GDBN}.
29e57380
C
8343
8344@kindex disable mem
8345@item disable mem @var{nums}@dots{}
09d4efe1 8346Disable monitoring of memory regions @var{nums}@dots{}.
b383017d 8347A disabled memory region is not forgotten.
29e57380
C
8348It may be enabled again later.
8349
8350@kindex enable mem
8351@item enable mem @var{nums}@dots{}
09d4efe1 8352Enable monitoring of memory regions @var{nums}@dots{}.
29e57380
C
8353
8354@kindex info mem
8355@item info mem
8356Print a table of all defined memory regions, with the following columns
09d4efe1 8357for each region:
29e57380
C
8358
8359@table @emph
8360@item Memory Region Number
8361@item Enabled or Disabled.
b383017d 8362Enabled memory regions are marked with @samp{y}.
29e57380
C
8363Disabled memory regions are marked with @samp{n}.
8364
8365@item Lo Address
8366The address defining the inclusive lower bound of the memory region.
8367
8368@item Hi Address
8369The address defining the exclusive upper bound of the memory region.
8370
8371@item Attributes
8372The list of attributes set for this memory region.
8373@end table
8374@end table
8375
8376
8377@subsection Attributes
8378
b383017d 8379@subsubsection Memory Access Mode
29e57380
C
8380The access mode attributes set whether @value{GDBN} may make read or
8381write accesses to a memory region.
8382
8383While these attributes prevent @value{GDBN} from performing invalid
8384memory accesses, they do nothing to prevent the target system, I/O DMA,
359df76b 8385etc.@: from accessing memory.
29e57380
C
8386
8387@table @code
8388@item ro
8389Memory is read only.
8390@item wo
8391Memory is write only.
8392@item rw
6ca652b0 8393Memory is read/write. This is the default.
29e57380
C
8394@end table
8395
8396@subsubsection Memory Access Size
d3e8051b 8397The access size attribute tells @value{GDBN} to use specific sized
29e57380
C
8398accesses in the memory region. Often memory mapped device registers
8399require specific sized accesses. If no access size attribute is
8400specified, @value{GDBN} may use accesses of any size.
8401
8402@table @code
8403@item 8
8404Use 8 bit memory accesses.
8405@item 16
8406Use 16 bit memory accesses.
8407@item 32
8408Use 32 bit memory accesses.
8409@item 64
8410Use 64 bit memory accesses.
8411@end table
8412
8413@c @subsubsection Hardware/Software Breakpoints
8414@c The hardware/software breakpoint attributes set whether @value{GDBN}
8415@c will use hardware or software breakpoints for the internal breakpoints
8416@c used by the step, next, finish, until, etc. commands.
8417@c
8418@c @table @code
8419@c @item hwbreak
b383017d 8420@c Always use hardware breakpoints
29e57380
C
8421@c @item swbreak (default)
8422@c @end table
8423
8424@subsubsection Data Cache
8425The data cache attributes set whether @value{GDBN} will cache target
8426memory. While this generally improves performance by reducing debug
8427protocol overhead, it can lead to incorrect results because @value{GDBN}
8428does not know about volatile variables or memory mapped device
8429registers.
8430
8431@table @code
8432@item cache
b383017d 8433Enable @value{GDBN} to cache target memory.
6ca652b0
EZ
8434@item nocache
8435Disable @value{GDBN} from caching target memory. This is the default.
29e57380
C
8436@end table
8437
4b5752d0
VP
8438@subsection Memory Access Checking
8439@value{GDBN} can be instructed to refuse accesses to memory that is
8440not explicitly described. This can be useful if accessing such
8441regions has undesired effects for a specific target, or to provide
8442better error checking. The following commands control this behaviour.
8443
8444@table @code
8445@kindex set mem inaccessible-by-default
8446@item set mem inaccessible-by-default [on|off]
8447If @code{on} is specified, make @value{GDBN} treat memory not
8448explicitly described by the memory ranges as non-existent and refuse accesses
8449to such memory. The checks are only performed if there's at least one
8450memory range defined. If @code{off} is specified, make @value{GDBN}
8451treat the memory not explicitly described by the memory ranges as RAM.
56cf5405 8452The default value is @code{on}.
4b5752d0
VP
8453@kindex show mem inaccessible-by-default
8454@item show mem inaccessible-by-default
8455Show the current handling of accesses to unknown memory.
8456@end table
8457
8458
29e57380 8459@c @subsubsection Memory Write Verification
b383017d 8460@c The memory write verification attributes set whether @value{GDBN}
29e57380
C
8461@c will re-reads data after each write to verify the write was successful.
8462@c
8463@c @table @code
8464@c @item verify
8465@c @item noverify (default)
8466@c @end table
8467
16d9dec6 8468@node Dump/Restore Files
79a6e687 8469@section Copy Between Memory and a File
16d9dec6
MS
8470@cindex dump/restore files
8471@cindex append data to a file
8472@cindex dump data to a file
8473@cindex restore data from a file
16d9dec6 8474
df5215a6
JB
8475You can use the commands @code{dump}, @code{append}, and
8476@code{restore} to copy data between target memory and a file. The
8477@code{dump} and @code{append} commands write data to a file, and the
8478@code{restore} command reads data from a file back into the inferior's
8479memory. Files may be in binary, Motorola S-record, Intel hex, or
8480Tektronix Hex format; however, @value{GDBN} can only append to binary
8481files.
8482
8483@table @code
8484
8485@kindex dump
8486@item dump @r{[}@var{format}@r{]} memory @var{filename} @var{start_addr} @var{end_addr}
8487@itemx dump @r{[}@var{format}@r{]} value @var{filename} @var{expr}
8488Dump the contents of memory from @var{start_addr} to @var{end_addr},
8489or the value of @var{expr}, to @var{filename} in the given format.
16d9dec6 8490
df5215a6 8491The @var{format} parameter may be any one of:
16d9dec6 8492@table @code
df5215a6
JB
8493@item binary
8494Raw binary form.
8495@item ihex
8496Intel hex format.
8497@item srec
8498Motorola S-record format.
8499@item tekhex
8500Tektronix Hex format.
8501@end table
8502
8503@value{GDBN} uses the same definitions of these formats as the
8504@sc{gnu} binary utilities, like @samp{objdump} and @samp{objcopy}. If
8505@var{format} is omitted, @value{GDBN} dumps the data in raw binary
8506form.
8507
8508@kindex append
8509@item append @r{[}binary@r{]} memory @var{filename} @var{start_addr} @var{end_addr}
8510@itemx append @r{[}binary@r{]} value @var{filename} @var{expr}
8511Append the contents of memory from @var{start_addr} to @var{end_addr},
09d4efe1 8512or the value of @var{expr}, to the file @var{filename}, in raw binary form.
df5215a6
JB
8513(@value{GDBN} can only append data to files in raw binary form.)
8514
8515@kindex restore
8516@item restore @var{filename} @r{[}binary@r{]} @var{bias} @var{start} @var{end}
8517Restore the contents of file @var{filename} into memory. The
8518@code{restore} command can automatically recognize any known @sc{bfd}
8519file format, except for raw binary. To restore a raw binary file you
8520must specify the optional keyword @code{binary} after the filename.
16d9dec6 8521
b383017d 8522If @var{bias} is non-zero, its value will be added to the addresses
16d9dec6
MS
8523contained in the file. Binary files always start at address zero, so
8524they will be restored at address @var{bias}. Other bfd files have
8525a built-in location; they will be restored at offset @var{bias}
8526from that location.
8527
8528If @var{start} and/or @var{end} are non-zero, then only data between
8529file offset @var{start} and file offset @var{end} will be restored.
b383017d 8530These offsets are relative to the addresses in the file, before
16d9dec6
MS
8531the @var{bias} argument is applied.
8532
8533@end table
8534
384ee23f
EZ
8535@node Core File Generation
8536@section How to Produce a Core File from Your Program
8537@cindex dump core from inferior
8538
8539A @dfn{core file} or @dfn{core dump} is a file that records the memory
8540image of a running process and its process status (register values
8541etc.). Its primary use is post-mortem debugging of a program that
8542crashed while it ran outside a debugger. A program that crashes
8543automatically produces a core file, unless this feature is disabled by
8544the user. @xref{Files}, for information on invoking @value{GDBN} in
8545the post-mortem debugging mode.
8546
8547Occasionally, you may wish to produce a core file of the program you
8548are debugging in order to preserve a snapshot of its state.
8549@value{GDBN} has a special command for that.
8550
8551@table @code
8552@kindex gcore
8553@kindex generate-core-file
8554@item generate-core-file [@var{file}]
8555@itemx gcore [@var{file}]
8556Produce a core dump of the inferior process. The optional argument
8557@var{file} specifies the file name where to put the core dump. If not
8558specified, the file name defaults to @file{core.@var{pid}}, where
8559@var{pid} is the inferior process ID.
8560
8561Note that this command is implemented only for some systems (as of
8562this writing, @sc{gnu}/Linux, FreeBSD, Solaris, Unixware, and S390).
8563@end table
8564
a0eb71c5
KB
8565@node Character Sets
8566@section Character Sets
8567@cindex character sets
8568@cindex charset
8569@cindex translating between character sets
8570@cindex host character set
8571@cindex target character set
8572
8573If the program you are debugging uses a different character set to
8574represent characters and strings than the one @value{GDBN} uses itself,
8575@value{GDBN} can automatically translate between the character sets for
8576you. The character set @value{GDBN} uses we call the @dfn{host
8577character set}; the one the inferior program uses we call the
8578@dfn{target character set}.
8579
8580For example, if you are running @value{GDBN} on a @sc{gnu}/Linux system, which
8581uses the ISO Latin 1 character set, but you are using @value{GDBN}'s
ea35711c 8582remote protocol (@pxref{Remote Debugging}) to debug a program
a0eb71c5
KB
8583running on an IBM mainframe, which uses the @sc{ebcdic} character set,
8584then the host character set is Latin-1, and the target character set is
8585@sc{ebcdic}. If you give @value{GDBN} the command @code{set
e33d66ec 8586target-charset EBCDIC-US}, then @value{GDBN} translates between
a0eb71c5
KB
8587@sc{ebcdic} and Latin 1 as you print character or string values, or use
8588character and string literals in expressions.
8589
8590@value{GDBN} has no way to automatically recognize which character set
8591the inferior program uses; you must tell it, using the @code{set
8592target-charset} command, described below.
8593
8594Here are the commands for controlling @value{GDBN}'s character set
8595support:
8596
8597@table @code
8598@item set target-charset @var{charset}
8599@kindex set target-charset
10af6951
EZ
8600Set the current target character set to @var{charset}. To display the
8601list of supported target character sets, type
8602@kbd{@w{set target-charset @key{TAB}@key{TAB}}}.
a0eb71c5 8603
a0eb71c5
KB
8604@item set host-charset @var{charset}
8605@kindex set host-charset
8606Set the current host character set to @var{charset}.
8607
8608By default, @value{GDBN} uses a host character set appropriate to the
8609system it is running on; you can override that default using the
732f6a93
TT
8610@code{set host-charset} command. On some systems, @value{GDBN} cannot
8611automatically determine the appropriate host character set. In this
8612case, @value{GDBN} uses @samp{UTF-8}.
a0eb71c5
KB
8613
8614@value{GDBN} can only use certain character sets as its host character
10af6951
EZ
8615set. If you type @kbd{@w{set target-charset @key{TAB}@key{TAB}}},
8616@value{GDBN} will list the host character sets it supports.
a0eb71c5
KB
8617
8618@item set charset @var{charset}
8619@kindex set charset
e33d66ec 8620Set the current host and target character sets to @var{charset}. As
10af6951
EZ
8621above, if you type @kbd{@w{set charset @key{TAB}@key{TAB}}},
8622@value{GDBN} will list the names of the character sets that can be used
e33d66ec
EZ
8623for both host and target.
8624
a0eb71c5 8625@item show charset
a0eb71c5 8626@kindex show charset
10af6951 8627Show the names of the current host and target character sets.
e33d66ec 8628
10af6951 8629@item show host-charset
a0eb71c5 8630@kindex show host-charset
10af6951 8631Show the name of the current host character set.
e33d66ec 8632
10af6951 8633@item show target-charset
a0eb71c5 8634@kindex show target-charset
10af6951 8635Show the name of the current target character set.
a0eb71c5 8636
10af6951
EZ
8637@item set target-wide-charset @var{charset}
8638@kindex set target-wide-charset
8639Set the current target's wide character set to @var{charset}. This is
8640the character set used by the target's @code{wchar_t} type. To
8641display the list of supported wide character sets, type
8642@kbd{@w{set target-wide-charset @key{TAB}@key{TAB}}}.
8643
8644@item show target-wide-charset
8645@kindex show target-wide-charset
8646Show the name of the current target's wide character set.
a0eb71c5
KB
8647@end table
8648
a0eb71c5
KB
8649Here is an example of @value{GDBN}'s character set support in action.
8650Assume that the following source code has been placed in the file
8651@file{charset-test.c}:
8652
8653@smallexample
8654#include <stdio.h>
8655
8656char ascii_hello[]
8657 = @{72, 101, 108, 108, 111, 44, 32, 119,
8658 111, 114, 108, 100, 33, 10, 0@};
8659char ibm1047_hello[]
8660 = @{200, 133, 147, 147, 150, 107, 64, 166,
8661 150, 153, 147, 132, 90, 37, 0@};
8662
8663main ()
8664@{
8665 printf ("Hello, world!\n");
8666@}
10998722 8667@end smallexample
a0eb71c5
KB
8668
8669In this program, @code{ascii_hello} and @code{ibm1047_hello} are arrays
8670containing the string @samp{Hello, world!} followed by a newline,
8671encoded in the @sc{ascii} and @sc{ibm1047} character sets.
8672
8673We compile the program, and invoke the debugger on it:
8674
8675@smallexample
8676$ gcc -g charset-test.c -o charset-test
8677$ gdb -nw charset-test
8678GNU gdb 2001-12-19-cvs
8679Copyright 2001 Free Software Foundation, Inc.
8680@dots{}
f7dc1244 8681(@value{GDBP})
10998722 8682@end smallexample
a0eb71c5
KB
8683
8684We can use the @code{show charset} command to see what character sets
8685@value{GDBN} is currently using to interpret and display characters and
8686strings:
8687
8688@smallexample
f7dc1244 8689(@value{GDBP}) show charset
e33d66ec 8690The current host and target character set is `ISO-8859-1'.
f7dc1244 8691(@value{GDBP})
10998722 8692@end smallexample
a0eb71c5
KB
8693
8694For the sake of printing this manual, let's use @sc{ascii} as our
8695initial character set:
8696@smallexample
f7dc1244
EZ
8697(@value{GDBP}) set charset ASCII
8698(@value{GDBP}) show charset
e33d66ec 8699The current host and target character set is `ASCII'.
f7dc1244 8700(@value{GDBP})
10998722 8701@end smallexample
a0eb71c5
KB
8702
8703Let's assume that @sc{ascii} is indeed the correct character set for our
8704host system --- in other words, let's assume that if @value{GDBN} prints
8705characters using the @sc{ascii} character set, our terminal will display
8706them properly. Since our current target character set is also
8707@sc{ascii}, the contents of @code{ascii_hello} print legibly:
8708
8709@smallexample
f7dc1244 8710(@value{GDBP}) print ascii_hello
a0eb71c5 8711$1 = 0x401698 "Hello, world!\n"
f7dc1244 8712(@value{GDBP}) print ascii_hello[0]
a0eb71c5 8713$2 = 72 'H'
f7dc1244 8714(@value{GDBP})
10998722 8715@end smallexample
a0eb71c5
KB
8716
8717@value{GDBN} uses the target character set for character and string
8718literals you use in expressions:
8719
8720@smallexample
f7dc1244 8721(@value{GDBP}) print '+'
a0eb71c5 8722$3 = 43 '+'
f7dc1244 8723(@value{GDBP})
10998722 8724@end smallexample
a0eb71c5
KB
8725
8726The @sc{ascii} character set uses the number 43 to encode the @samp{+}
8727character.
8728
8729@value{GDBN} relies on the user to tell it which character set the
8730target program uses. If we print @code{ibm1047_hello} while our target
8731character set is still @sc{ascii}, we get jibberish:
8732
8733@smallexample
f7dc1244 8734(@value{GDBP}) print ibm1047_hello
a0eb71c5 8735$4 = 0x4016a8 "\310\205\223\223\226k@@\246\226\231\223\204Z%"
f7dc1244 8736(@value{GDBP}) print ibm1047_hello[0]
a0eb71c5 8737$5 = 200 '\310'
f7dc1244 8738(@value{GDBP})
10998722 8739@end smallexample
a0eb71c5 8740
e33d66ec 8741If we invoke the @code{set target-charset} followed by @key{TAB}@key{TAB},
a0eb71c5
KB
8742@value{GDBN} tells us the character sets it supports:
8743
8744@smallexample
f7dc1244 8745(@value{GDBP}) set target-charset
b383017d 8746ASCII EBCDIC-US IBM1047 ISO-8859-1
f7dc1244 8747(@value{GDBP}) set target-charset
10998722 8748@end smallexample
a0eb71c5
KB
8749
8750We can select @sc{ibm1047} as our target character set, and examine the
8751program's strings again. Now the @sc{ascii} string is wrong, but
8752@value{GDBN} translates the contents of @code{ibm1047_hello} from the
8753target character set, @sc{ibm1047}, to the host character set,
8754@sc{ascii}, and they display correctly:
8755
8756@smallexample
f7dc1244
EZ
8757(@value{GDBP}) set target-charset IBM1047
8758(@value{GDBP}) show charset
e33d66ec
EZ
8759The current host character set is `ASCII'.
8760The current target character set is `IBM1047'.
f7dc1244 8761(@value{GDBP}) print ascii_hello
a0eb71c5 8762$6 = 0x401698 "\110\145%%?\054\040\167?\162%\144\041\012"
f7dc1244 8763(@value{GDBP}) print ascii_hello[0]
a0eb71c5 8764$7 = 72 '\110'
f7dc1244 8765(@value{GDBP}) print ibm1047_hello
a0eb71c5 8766$8 = 0x4016a8 "Hello, world!\n"
f7dc1244 8767(@value{GDBP}) print ibm1047_hello[0]
a0eb71c5 8768$9 = 200 'H'
f7dc1244 8769(@value{GDBP})
10998722 8770@end smallexample
a0eb71c5
KB
8771
8772As above, @value{GDBN} uses the target character set for character and
8773string literals you use in expressions:
8774
8775@smallexample
f7dc1244 8776(@value{GDBP}) print '+'
a0eb71c5 8777$10 = 78 '+'
f7dc1244 8778(@value{GDBP})
10998722 8779@end smallexample
a0eb71c5 8780
e33d66ec 8781The @sc{ibm1047} character set uses the number 78 to encode the @samp{+}
a0eb71c5
KB
8782character.
8783
09d4efe1
EZ
8784@node Caching Remote Data
8785@section Caching Data of Remote Targets
8786@cindex caching data of remote targets
8787
4e5d721f 8788@value{GDBN} caches data exchanged between the debugger and a
ea35711c 8789remote target (@pxref{Remote Debugging}). Such caching generally improves
09d4efe1 8790performance, because it reduces the overhead of the remote protocol by
4e5d721f
DE
8791bundling memory reads and writes into large chunks. Unfortunately, simply
8792caching everything would lead to incorrect results, since @value{GDBN}
8793does not necessarily know anything about volatile values, memory-mapped I/O
29b090c0
DE
8794addresses, etc. Furthermore, in non-stop mode (@pxref{Non-Stop Mode})
8795memory can be changed @emph{while} a gdb command is executing.
8796Therefore, by default, @value{GDBN} only caches data
8797known to be on the stack@footnote{In non-stop mode, it is moderately
8798rare for a running thread to modify the stack of a stopped thread
8799in a way that would interfere with a backtrace, and caching of
8800stack reads provides a significant speed up of remote backtraces.}.
8801Other regions of memory can be explicitly marked as
4e5d721f 8802cacheable; see @pxref{Memory Region Attributes}.
09d4efe1
EZ
8803
8804@table @code
8805@kindex set remotecache
8806@item set remotecache on
8807@itemx set remotecache off
4e5d721f
DE
8808This option no longer does anything; it exists for compatibility
8809with old scripts.
09d4efe1
EZ
8810
8811@kindex show remotecache
8812@item show remotecache
4e5d721f
DE
8813Show the current state of the obsolete remotecache flag.
8814
8815@kindex set stack-cache
8816@item set stack-cache on
8817@itemx set stack-cache off
8818Enable or disable caching of stack accesses. When @code{ON}, use
8819caching. By default, this option is @code{ON}.
8820
8821@kindex show stack-cache
8822@item show stack-cache
8823Show the current state of data caching for memory accesses.
09d4efe1
EZ
8824
8825@kindex info dcache
4e5d721f 8826@item info dcache @r{[}line@r{]}
09d4efe1 8827Print the information about the data cache performance. The
4e5d721f
DE
8828information displayed includes the dcache width and depth, and for
8829each cache line, its number, address, and how many times it was
8830referenced. This command is useful for debugging the data cache
8831operation.
8832
8833If a line number is specified, the contents of that line will be
8834printed in hex.
09d4efe1
EZ
8835@end table
8836
08388c79
DE
8837@node Searching Memory
8838@section Search Memory
8839@cindex searching memory
8840
8841Memory can be searched for a particular sequence of bytes with the
8842@code{find} command.
8843
8844@table @code
8845@kindex find
8846@item find @r{[}/@var{sn}@r{]} @var{start_addr}, +@var{len}, @var{val1} @r{[}, @var{val2}, @dots{}@r{]}
8847@itemx find @r{[}/@var{sn}@r{]} @var{start_addr}, @var{end_addr}, @var{val1} @r{[}, @var{val2}, @dots{}@r{]}
8848Search memory for the sequence of bytes specified by @var{val1}, @var{val2},
8849etc. The search begins at address @var{start_addr} and continues for either
8850@var{len} bytes or through to @var{end_addr} inclusive.
8851@end table
8852
8853@var{s} and @var{n} are optional parameters.
8854They may be specified in either order, apart or together.
8855
8856@table @r
8857@item @var{s}, search query size
8858The size of each search query value.
8859
8860@table @code
8861@item b
8862bytes
8863@item h
8864halfwords (two bytes)
8865@item w
8866words (four bytes)
8867@item g
8868giant words (eight bytes)
8869@end table
8870
8871All values are interpreted in the current language.
8872This means, for example, that if the current source language is C/C@t{++}
8873then searching for the string ``hello'' includes the trailing '\0'.
8874
8875If the value size is not specified, it is taken from the
8876value's type in the current language.
8877This is useful when one wants to specify the search
8878pattern as a mixture of types.
8879Note that this means, for example, that in the case of C-like languages
8880a search for an untyped 0x42 will search for @samp{(int) 0x42}
8881which is typically four bytes.
8882
8883@item @var{n}, maximum number of finds
8884The maximum number of matches to print. The default is to print all finds.
8885@end table
8886
8887You can use strings as search values. Quote them with double-quotes
8888 (@code{"}).
8889The string value is copied into the search pattern byte by byte,
8890regardless of the endianness of the target and the size specification.
8891
8892The address of each match found is printed as well as a count of the
8893number of matches found.
8894
8895The address of the last value found is stored in convenience variable
8896@samp{$_}.
8897A count of the number of matches is stored in @samp{$numfound}.
8898
8899For example, if stopped at the @code{printf} in this function:
8900
8901@smallexample
8902void
8903hello ()
8904@{
8905 static char hello[] = "hello-hello";
8906 static struct @{ char c; short s; int i; @}
8907 __attribute__ ((packed)) mixed
8908 = @{ 'c', 0x1234, 0x87654321 @};
8909 printf ("%s\n", hello);
8910@}
8911@end smallexample
8912
8913@noindent
8914you get during debugging:
8915
8916@smallexample
8917(gdb) find &hello[0], +sizeof(hello), "hello"
89180x804956d <hello.1620+6>
89191 pattern found
8920(gdb) find &hello[0], +sizeof(hello), 'h', 'e', 'l', 'l', 'o'
89210x8049567 <hello.1620>
89220x804956d <hello.1620+6>
89232 patterns found
8924(gdb) find /b1 &hello[0], +sizeof(hello), 'h', 0x65, 'l'
89250x8049567 <hello.1620>
89261 pattern found
8927(gdb) find &mixed, +sizeof(mixed), (char) 'c', (short) 0x1234, (int) 0x87654321
89280x8049560 <mixed.1625>
89291 pattern found
8930(gdb) print $numfound
8931$1 = 1
8932(gdb) print $_
8933$2 = (void *) 0x8049560
8934@end smallexample
a0eb71c5 8935
edb3359d
DJ
8936@node Optimized Code
8937@chapter Debugging Optimized Code
8938@cindex optimized code, debugging
8939@cindex debugging optimized code
8940
8941Almost all compilers support optimization. With optimization
8942disabled, the compiler generates assembly code that corresponds
8943directly to your source code, in a simplistic way. As the compiler
8944applies more powerful optimizations, the generated assembly code
8945diverges from your original source code. With help from debugging
8946information generated by the compiler, @value{GDBN} can map from
8947the running program back to constructs from your original source.
8948
8949@value{GDBN} is more accurate with optimization disabled. If you
8950can recompile without optimization, it is easier to follow the
8951progress of your program during debugging. But, there are many cases
8952where you may need to debug an optimized version.
8953
8954When you debug a program compiled with @samp{-g -O}, remember that the
8955optimizer has rearranged your code; the debugger shows you what is
8956really there. Do not be too surprised when the execution path does not
8957exactly match your source file! An extreme example: if you define a
8958variable, but never use it, @value{GDBN} never sees that
8959variable---because the compiler optimizes it out of existence.
8960
8961Some things do not work as well with @samp{-g -O} as with just
8962@samp{-g}, particularly on machines with instruction scheduling. If in
8963doubt, recompile with @samp{-g} alone, and if this fixes the problem,
8964please report it to us as a bug (including a test case!).
8965@xref{Variables}, for more information about debugging optimized code.
8966
8967@menu
8968* Inline Functions:: How @value{GDBN} presents inlining
8969@end menu
8970
8971@node Inline Functions
8972@section Inline Functions
8973@cindex inline functions, debugging
8974
8975@dfn{Inlining} is an optimization that inserts a copy of the function
8976body directly at each call site, instead of jumping to a shared
8977routine. @value{GDBN} displays inlined functions just like
8978non-inlined functions. They appear in backtraces. You can view their
8979arguments and local variables, step into them with @code{step}, skip
8980them with @code{next}, and escape from them with @code{finish}.
8981You can check whether a function was inlined by using the
8982@code{info frame} command.
8983
8984For @value{GDBN} to support inlined functions, the compiler must
8985record information about inlining in the debug information ---
8986@value{NGCC} using the @sc{dwarf 2} format does this, and several
8987other compilers do also. @value{GDBN} only supports inlined functions
8988when using @sc{dwarf 2}. Versions of @value{NGCC} before 4.1
8989do not emit two required attributes (@samp{DW_AT_call_file} and
8990@samp{DW_AT_call_line}); @value{GDBN} does not display inlined
8991function calls with earlier versions of @value{NGCC}. It instead
8992displays the arguments and local variables of inlined functions as
8993local variables in the caller.
8994
8995The body of an inlined function is directly included at its call site;
8996unlike a non-inlined function, there are no instructions devoted to
8997the call. @value{GDBN} still pretends that the call site and the
8998start of the inlined function are different instructions. Stepping to
8999the call site shows the call site, and then stepping again shows
9000the first line of the inlined function, even though no additional
9001instructions are executed.
9002
9003This makes source-level debugging much clearer; you can see both the
9004context of the call and then the effect of the call. Only stepping by
9005a single instruction using @code{stepi} or @code{nexti} does not do
9006this; single instruction steps always show the inlined body.
9007
9008There are some ways that @value{GDBN} does not pretend that inlined
9009function calls are the same as normal calls:
9010
9011@itemize @bullet
9012@item
9013You cannot set breakpoints on inlined functions. @value{GDBN}
9014either reports that there is no symbol with that name, or else sets the
9015breakpoint only on non-inlined copies of the function. This limitation
9016will be removed in a future version of @value{GDBN}; until then,
9017set a breakpoint by line number on the first line of the inlined
9018function instead.
9019
9020@item
9021Setting breakpoints at the call site of an inlined function may not
9022work, because the call site does not contain any code. @value{GDBN}
9023may incorrectly move the breakpoint to the next line of the enclosing
9024function, after the call. This limitation will be removed in a future
9025version of @value{GDBN}; until then, set a breakpoint on an earlier line
9026or inside the inlined function instead.
9027
9028@item
9029@value{GDBN} cannot locate the return value of inlined calls after
9030using the @code{finish} command. This is a limitation of compiler-generated
9031debugging information; after @code{finish}, you can step to the next line
9032and print a variable where your program stored the return value.
9033
9034@end itemize
9035
9036
e2e0bcd1
JB
9037@node Macros
9038@chapter C Preprocessor Macros
9039
49efadf5 9040Some languages, such as C and C@t{++}, provide a way to define and invoke
e2e0bcd1
JB
9041``preprocessor macros'' which expand into strings of tokens.
9042@value{GDBN} can evaluate expressions containing macro invocations, show
9043the result of macro expansion, and show a macro's definition, including
9044where it was defined.
9045
9046You may need to compile your program specially to provide @value{GDBN}
9047with information about preprocessor macros. Most compilers do not
9048include macros in their debugging information, even when you compile
9049with the @option{-g} flag. @xref{Compilation}.
9050
9051A program may define a macro at one point, remove that definition later,
9052and then provide a different definition after that. Thus, at different
9053points in the program, a macro may have different definitions, or have
9054no definition at all. If there is a current stack frame, @value{GDBN}
9055uses the macros in scope at that frame's source code line. Otherwise,
9056@value{GDBN} uses the macros in scope at the current listing location;
9057see @ref{List}.
9058
e2e0bcd1
JB
9059Whenever @value{GDBN} evaluates an expression, it always expands any
9060macro invocations present in the expression. @value{GDBN} also provides
9061the following commands for working with macros explicitly.
9062
9063@table @code
9064
9065@kindex macro expand
9066@cindex macro expansion, showing the results of preprocessor
9067@cindex preprocessor macro expansion, showing the results of
9068@cindex expanding preprocessor macros
9069@item macro expand @var{expression}
9070@itemx macro exp @var{expression}
9071Show the results of expanding all preprocessor macro invocations in
9072@var{expression}. Since @value{GDBN} simply expands macros, but does
9073not parse the result, @var{expression} need not be a valid expression;
9074it can be any string of tokens.
9075
09d4efe1 9076@kindex macro exp1
e2e0bcd1
JB
9077@item macro expand-once @var{expression}
9078@itemx macro exp1 @var{expression}
4644b6e3 9079@cindex expand macro once
e2e0bcd1
JB
9080@i{(This command is not yet implemented.)} Show the results of
9081expanding those preprocessor macro invocations that appear explicitly in
9082@var{expression}. Macro invocations appearing in that expansion are
9083left unchanged. This command allows you to see the effect of a
9084particular macro more clearly, without being confused by further
9085expansions. Since @value{GDBN} simply expands macros, but does not
9086parse the result, @var{expression} need not be a valid expression; it
9087can be any string of tokens.
9088
475b0867 9089@kindex info macro
e2e0bcd1
JB
9090@cindex macro definition, showing
9091@cindex definition, showing a macro's
475b0867 9092@item info macro @var{macro}
e2e0bcd1 9093Show the definition of the macro named @var{macro}, and describe the
484086b7 9094source location or compiler command-line where that definition was established.
e2e0bcd1
JB
9095
9096@kindex macro define
9097@cindex user-defined macros
9098@cindex defining macros interactively
9099@cindex macros, user-defined
9100@item macro define @var{macro} @var{replacement-list}
9101@itemx macro define @var{macro}(@var{arglist}) @var{replacement-list}
d7d9f01e
TT
9102Introduce a definition for a preprocessor macro named @var{macro},
9103invocations of which are replaced by the tokens given in
9104@var{replacement-list}. The first form of this command defines an
9105``object-like'' macro, which takes no arguments; the second form
9106defines a ``function-like'' macro, which takes the arguments given in
9107@var{arglist}.
9108
9109A definition introduced by this command is in scope in every
9110expression evaluated in @value{GDBN}, until it is removed with the
9111@code{macro undef} command, described below. The definition overrides
9112all definitions for @var{macro} present in the program being debugged,
9113as well as any previous user-supplied definition.
e2e0bcd1
JB
9114
9115@kindex macro undef
9116@item macro undef @var{macro}
d7d9f01e
TT
9117Remove any user-supplied definition for the macro named @var{macro}.
9118This command only affects definitions provided with the @code{macro
9119define} command, described above; it cannot remove definitions present
9120in the program being debugged.
e2e0bcd1 9121
09d4efe1
EZ
9122@kindex macro list
9123@item macro list
d7d9f01e 9124List all the macros defined using the @code{macro define} command.
e2e0bcd1
JB
9125@end table
9126
9127@cindex macros, example of debugging with
9128Here is a transcript showing the above commands in action. First, we
9129show our source files:
9130
9131@smallexample
9132$ cat sample.c
9133#include <stdio.h>
9134#include "sample.h"
9135
9136#define M 42
9137#define ADD(x) (M + x)
9138
9139main ()
9140@{
9141#define N 28
9142 printf ("Hello, world!\n");
9143#undef N
9144 printf ("We're so creative.\n");
9145#define N 1729
9146 printf ("Goodbye, world!\n");
9147@}
9148$ cat sample.h
9149#define Q <
9150$
9151@end smallexample
9152
9153Now, we compile the program using the @sc{gnu} C compiler, @value{NGCC}.
9154We pass the @option{-gdwarf-2} and @option{-g3} flags to ensure the
9155compiler includes information about preprocessor macros in the debugging
9156information.
9157
9158@smallexample
9159$ gcc -gdwarf-2 -g3 sample.c -o sample
9160$
9161@end smallexample
9162
9163Now, we start @value{GDBN} on our sample program:
9164
9165@smallexample
9166$ gdb -nw sample
9167GNU gdb 2002-05-06-cvs
9168Copyright 2002 Free Software Foundation, Inc.
9169GDB is free software, @dots{}
f7dc1244 9170(@value{GDBP})
e2e0bcd1
JB
9171@end smallexample
9172
9173We can expand macros and examine their definitions, even when the
9174program is not running. @value{GDBN} uses the current listing position
9175to decide which macro definitions are in scope:
9176
9177@smallexample
f7dc1244 9178(@value{GDBP}) list main
e2e0bcd1
JB
91793
91804 #define M 42
91815 #define ADD(x) (M + x)
91826
91837 main ()
91848 @{
91859 #define N 28
918610 printf ("Hello, world!\n");
918711 #undef N
918812 printf ("We're so creative.\n");
f7dc1244 9189(@value{GDBP}) info macro ADD
e2e0bcd1
JB
9190Defined at /home/jimb/gdb/macros/play/sample.c:5
9191#define ADD(x) (M + x)
f7dc1244 9192(@value{GDBP}) info macro Q
e2e0bcd1
JB
9193Defined at /home/jimb/gdb/macros/play/sample.h:1
9194 included at /home/jimb/gdb/macros/play/sample.c:2
9195#define Q <
f7dc1244 9196(@value{GDBP}) macro expand ADD(1)
e2e0bcd1 9197expands to: (42 + 1)
f7dc1244 9198(@value{GDBP}) macro expand-once ADD(1)
e2e0bcd1 9199expands to: once (M + 1)
f7dc1244 9200(@value{GDBP})
e2e0bcd1
JB
9201@end smallexample
9202
d7d9f01e 9203In the example above, note that @code{macro expand-once} expands only
e2e0bcd1
JB
9204the macro invocation explicit in the original text --- the invocation of
9205@code{ADD} --- but does not expand the invocation of the macro @code{M},
9206which was introduced by @code{ADD}.
9207
3f94c067
BW
9208Once the program is running, @value{GDBN} uses the macro definitions in
9209force at the source line of the current stack frame:
e2e0bcd1
JB
9210
9211@smallexample
f7dc1244 9212(@value{GDBP}) break main
e2e0bcd1 9213Breakpoint 1 at 0x8048370: file sample.c, line 10.
f7dc1244 9214(@value{GDBP}) run
b383017d 9215Starting program: /home/jimb/gdb/macros/play/sample
e2e0bcd1
JB
9216
9217Breakpoint 1, main () at sample.c:10
921810 printf ("Hello, world!\n");
f7dc1244 9219(@value{GDBP})
e2e0bcd1
JB
9220@end smallexample
9221
9222At line 10, the definition of the macro @code{N} at line 9 is in force:
9223
9224@smallexample
f7dc1244 9225(@value{GDBP}) info macro N
e2e0bcd1
JB
9226Defined at /home/jimb/gdb/macros/play/sample.c:9
9227#define N 28
f7dc1244 9228(@value{GDBP}) macro expand N Q M
e2e0bcd1 9229expands to: 28 < 42
f7dc1244 9230(@value{GDBP}) print N Q M
e2e0bcd1 9231$1 = 1
f7dc1244 9232(@value{GDBP})
e2e0bcd1
JB
9233@end smallexample
9234
9235As we step over directives that remove @code{N}'s definition, and then
9236give it a new definition, @value{GDBN} finds the definition (or lack
9237thereof) in force at each point:
9238
9239@smallexample
f7dc1244 9240(@value{GDBP}) next
e2e0bcd1
JB
9241Hello, world!
924212 printf ("We're so creative.\n");
f7dc1244 9243(@value{GDBP}) info macro N
e2e0bcd1
JB
9244The symbol `N' has no definition as a C/C++ preprocessor macro
9245at /home/jimb/gdb/macros/play/sample.c:12
f7dc1244 9246(@value{GDBP}) next
e2e0bcd1
JB
9247We're so creative.
924814 printf ("Goodbye, world!\n");
f7dc1244 9249(@value{GDBP}) info macro N
e2e0bcd1
JB
9250Defined at /home/jimb/gdb/macros/play/sample.c:13
9251#define N 1729
f7dc1244 9252(@value{GDBP}) macro expand N Q M
e2e0bcd1 9253expands to: 1729 < 42
f7dc1244 9254(@value{GDBP}) print N Q M
e2e0bcd1 9255$2 = 0
f7dc1244 9256(@value{GDBP})
e2e0bcd1
JB
9257@end smallexample
9258
484086b7
JK
9259In addition to source files, macros can be defined on the compilation command
9260line using the @option{-D@var{name}=@var{value}} syntax. For macros defined in
9261such a way, @value{GDBN} displays the location of their definition as line zero
9262of the source file submitted to the compiler.
9263
9264@smallexample
9265(@value{GDBP}) info macro __STDC__
9266Defined at /home/jimb/gdb/macros/play/sample.c:0
9267-D__STDC__=1
9268(@value{GDBP})
9269@end smallexample
9270
e2e0bcd1 9271
b37052ae
EZ
9272@node Tracepoints
9273@chapter Tracepoints
9274@c This chapter is based on the documentation written by Michael
9275@c Snyder, David Taylor, Jim Blandy, and Elena Zannoni.
9276
9277@cindex tracepoints
9278In some applications, it is not feasible for the debugger to interrupt
9279the program's execution long enough for the developer to learn
9280anything helpful about its behavior. If the program's correctness
9281depends on its real-time behavior, delays introduced by a debugger
9282might cause the program to change its behavior drastically, or perhaps
9283fail, even when the code itself is correct. It is useful to be able
9284to observe the program's behavior without interrupting it.
9285
9286Using @value{GDBN}'s @code{trace} and @code{collect} commands, you can
9287specify locations in the program, called @dfn{tracepoints}, and
9288arbitrary expressions to evaluate when those tracepoints are reached.
9289Later, using the @code{tfind} command, you can examine the values
9290those expressions had when the program hit the tracepoints. The
9291expressions may also denote objects in memory---structures or arrays,
9292for example---whose values @value{GDBN} should record; while visiting
9293a particular tracepoint, you may inspect those objects as if they were
9294in memory at that moment. However, because @value{GDBN} records these
9295values without interacting with you, it can do so quickly and
9296unobtrusively, hopefully not disturbing the program's behavior.
9297
9298The tracepoint facility is currently available only for remote
9d29849a
JB
9299targets. @xref{Targets}. In addition, your remote target must know
9300how to collect trace data. This functionality is implemented in the
9301remote stub; however, none of the stubs distributed with @value{GDBN}
9302support tracepoints as of this writing. The format of the remote
9303packets used to implement tracepoints are described in @ref{Tracepoint
9304Packets}.
b37052ae 9305
00bf0b85
SS
9306It is also possible to get trace data from a file, in a manner reminiscent
9307of corefiles; you specify the filename, and use @code{tfind} to search
9308through the file. @xref{Trace Files}, for more details.
9309
b37052ae
EZ
9310This chapter describes the tracepoint commands and features.
9311
9312@menu
b383017d
RM
9313* Set Tracepoints::
9314* Analyze Collected Data::
9315* Tracepoint Variables::
00bf0b85 9316* Trace Files::
b37052ae
EZ
9317@end menu
9318
9319@node Set Tracepoints
9320@section Commands to Set Tracepoints
9321
9322Before running such a @dfn{trace experiment}, an arbitrary number of
1042e4c0
SS
9323tracepoints can be set. A tracepoint is actually a special type of
9324breakpoint (@pxref{Set Breaks}), so you can manipulate it using
9325standard breakpoint commands. For instance, as with breakpoints,
9326tracepoint numbers are successive integers starting from one, and many
9327of the commands associated with tracepoints take the tracepoint number
9328as their argument, to identify which tracepoint to work on.
b37052ae
EZ
9329
9330For each tracepoint, you can specify, in advance, some arbitrary set
9331of data that you want the target to collect in the trace buffer when
9332it hits that tracepoint. The collected data can include registers,
9333local variables, or global data. Later, you can use @value{GDBN}
9334commands to examine the values these data had at the time the
9335tracepoint was hit.
9336
7d13fe92
SS
9337Tracepoints do not support every breakpoint feature. Ignore counts on
9338tracepoints have no effect, and tracepoints cannot run @value{GDBN}
9339commands when they are hit. Tracepoints may not be thread-specific
9340either.
1042e4c0 9341
7a697b8d
SS
9342@cindex fast tracepoints
9343Some targets may support @dfn{fast tracepoints}, which are inserted in
9344a different way (such as with a jump instead of a trap), that is
9345faster but possibly restricted in where they may be installed.
9346
b37052ae
EZ
9347This section describes commands to set tracepoints and associated
9348conditions and actions.
9349
9350@menu
b383017d
RM
9351* Create and Delete Tracepoints::
9352* Enable and Disable Tracepoints::
9353* Tracepoint Passcounts::
782b2b07 9354* Tracepoint Conditions::
f61e138d 9355* Trace State Variables::
b383017d
RM
9356* Tracepoint Actions::
9357* Listing Tracepoints::
79a6e687 9358* Starting and Stopping Trace Experiments::
c9429232 9359* Tracepoint Restrictions::
b37052ae
EZ
9360@end menu
9361
9362@node Create and Delete Tracepoints
9363@subsection Create and Delete Tracepoints
9364
9365@table @code
9366@cindex set tracepoint
9367@kindex trace
1042e4c0 9368@item trace @var{location}
b37052ae 9369The @code{trace} command is very similar to the @code{break} command.
1042e4c0
SS
9370Its argument @var{location} can be a source line, a function name, or
9371an address in the target program. @xref{Specify Location}. The
9372@code{trace} command defines a tracepoint, which is a point in the
9373target program where the debugger will briefly stop, collect some
9374data, and then allow the program to continue. Setting a tracepoint or
9375changing its actions doesn't take effect until the next @code{tstart}
9376command, and once a trace experiment is running, further changes will
9377not have any effect until the next trace experiment starts.
b37052ae
EZ
9378
9379Here are some examples of using the @code{trace} command:
9380
9381@smallexample
9382(@value{GDBP}) @b{trace foo.c:121} // a source file and line number
9383
9384(@value{GDBP}) @b{trace +2} // 2 lines forward
9385
9386(@value{GDBP}) @b{trace my_function} // first source line of function
9387
9388(@value{GDBP}) @b{trace *my_function} // EXACT start address of function
9389
9390(@value{GDBP}) @b{trace *0x2117c4} // an address
9391@end smallexample
9392
9393@noindent
9394You can abbreviate @code{trace} as @code{tr}.
9395
782b2b07
SS
9396@item trace @var{location} if @var{cond}
9397Set a tracepoint with condition @var{cond}; evaluate the expression
9398@var{cond} each time the tracepoint is reached, and collect data only
9399if the value is nonzero---that is, if @var{cond} evaluates as true.
9400@xref{Tracepoint Conditions, ,Tracepoint Conditions}, for more
9401information on tracepoint conditions.
9402
7a697b8d
SS
9403@item ftrace @var{location} [ if @var{cond} ]
9404@cindex set fast tracepoint
9405@kindex ftrace
9406The @code{ftrace} command sets a fast tracepoint. For targets that
9407support them, fast tracepoints will use a more efficient but possibly
9408less general technique to trigger data collection, such as a jump
9409instruction instead of a trap, or some sort of hardware support. It
9410may not be possible to create a fast tracepoint at the desired
9411location, in which case the command will exit with an explanatory
9412message.
9413
9414@value{GDBN} handles arguments to @code{ftrace} exactly as for
9415@code{trace}.
9416
b37052ae
EZ
9417@vindex $tpnum
9418@cindex last tracepoint number
9419@cindex recent tracepoint number
9420@cindex tracepoint number
9421The convenience variable @code{$tpnum} records the tracepoint number
9422of the most recently set tracepoint.
9423
9424@kindex delete tracepoint
9425@cindex tracepoint deletion
9426@item delete tracepoint @r{[}@var{num}@r{]}
9427Permanently delete one or more tracepoints. With no argument, the
1042e4c0
SS
9428default is to delete all tracepoints. Note that the regular
9429@code{delete} command can remove tracepoints also.
b37052ae
EZ
9430
9431Examples:
9432
9433@smallexample
9434(@value{GDBP}) @b{delete trace 1 2 3} // remove three tracepoints
9435
9436(@value{GDBP}) @b{delete trace} // remove all tracepoints
9437@end smallexample
9438
9439@noindent
9440You can abbreviate this command as @code{del tr}.
9441@end table
9442
9443@node Enable and Disable Tracepoints
9444@subsection Enable and Disable Tracepoints
9445
1042e4c0
SS
9446These commands are deprecated; they are equivalent to plain @code{disable} and @code{enable}.
9447
b37052ae
EZ
9448@table @code
9449@kindex disable tracepoint
9450@item disable tracepoint @r{[}@var{num}@r{]}
9451Disable tracepoint @var{num}, or all tracepoints if no argument
9452@var{num} is given. A disabled tracepoint will have no effect during
9453the next trace experiment, but it is not forgotten. You can re-enable
9454a disabled tracepoint using the @code{enable tracepoint} command.
9455
9456@kindex enable tracepoint
9457@item enable tracepoint @r{[}@var{num}@r{]}
9458Enable tracepoint @var{num}, or all tracepoints. The enabled
9459tracepoints will become effective the next time a trace experiment is
9460run.
9461@end table
9462
9463@node Tracepoint Passcounts
9464@subsection Tracepoint Passcounts
9465
9466@table @code
9467@kindex passcount
9468@cindex tracepoint pass count
9469@item passcount @r{[}@var{n} @r{[}@var{num}@r{]]}
9470Set the @dfn{passcount} of a tracepoint. The passcount is a way to
9471automatically stop a trace experiment. If a tracepoint's passcount is
9472@var{n}, then the trace experiment will be automatically stopped on
9473the @var{n}'th time that tracepoint is hit. If the tracepoint number
9474@var{num} is not specified, the @code{passcount} command sets the
9475passcount of the most recently defined tracepoint. If no passcount is
9476given, the trace experiment will run until stopped explicitly by the
9477user.
9478
9479Examples:
9480
9481@smallexample
b383017d 9482(@value{GDBP}) @b{passcount 5 2} // Stop on the 5th execution of
6826cf00 9483@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// tracepoint 2}
b37052ae
EZ
9484
9485(@value{GDBP}) @b{passcount 12} // Stop on the 12th execution of the
6826cf00 9486@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// most recently defined tracepoint.}
b37052ae
EZ
9487(@value{GDBP}) @b{trace foo}
9488(@value{GDBP}) @b{pass 3}
9489(@value{GDBP}) @b{trace bar}
9490(@value{GDBP}) @b{pass 2}
9491(@value{GDBP}) @b{trace baz}
9492(@value{GDBP}) @b{pass 1} // Stop tracing when foo has been
6826cf00
EZ
9493@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// executed 3 times OR when bar has}
9494@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// been executed 2 times}
9495@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// OR when baz has been executed 1 time.}
b37052ae
EZ
9496@end smallexample
9497@end table
9498
782b2b07
SS
9499@node Tracepoint Conditions
9500@subsection Tracepoint Conditions
9501@cindex conditional tracepoints
9502@cindex tracepoint conditions
9503
9504The simplest sort of tracepoint collects data every time your program
9505reaches a specified place. You can also specify a @dfn{condition} for
9506a tracepoint. A condition is just a Boolean expression in your
9507programming language (@pxref{Expressions, ,Expressions}). A
9508tracepoint with a condition evaluates the expression each time your
9509program reaches it, and data collection happens only if the condition
9510is true.
9511
9512Tracepoint conditions can be specified when a tracepoint is set, by
9513using @samp{if} in the arguments to the @code{trace} command.
9514@xref{Create and Delete Tracepoints, ,Setting Tracepoints}. They can
9515also be set or changed at any time with the @code{condition} command,
9516just as with breakpoints.
9517
9518Unlike breakpoint conditions, @value{GDBN} does not actually evaluate
9519the conditional expression itself. Instead, @value{GDBN} encodes the
9520expression into an agent expression (@pxref{Agent Expressions}
9521suitable for execution on the target, independently of @value{GDBN}.
9522Global variables become raw memory locations, locals become stack
9523accesses, and so forth.
9524
9525For instance, suppose you have a function that is usually called
9526frequently, but should not be called after an error has occurred. You
9527could use the following tracepoint command to collect data about calls
9528of that function that happen while the error code is propagating
9529through the program; an unconditional tracepoint could end up
9530collecting thousands of useless trace frames that you would have to
9531search through.
9532
9533@smallexample
9534(@value{GDBP}) @kbd{trace normal_operation if errcode > 0}
9535@end smallexample
9536
f61e138d
SS
9537@node Trace State Variables
9538@subsection Trace State Variables
9539@cindex trace state variables
9540
9541A @dfn{trace state variable} is a special type of variable that is
9542created and managed by target-side code. The syntax is the same as
9543that for GDB's convenience variables (a string prefixed with ``$''),
9544but they are stored on the target. They must be created explicitly,
9545using a @code{tvariable} command. They are always 64-bit signed
9546integers.
9547
9548Trace state variables are remembered by @value{GDBN}, and downloaded
9549to the target along with tracepoint information when the trace
9550experiment starts. There are no intrinsic limits on the number of
9551trace state variables, beyond memory limitations of the target.
9552
9553@cindex convenience variables, and trace state variables
9554Although trace state variables are managed by the target, you can use
9555them in print commands and expressions as if they were convenience
9556variables; @value{GDBN} will get the current value from the target
9557while the trace experiment is running. Trace state variables share
9558the same namespace as other ``$'' variables, which means that you
9559cannot have trace state variables with names like @code{$23} or
9560@code{$pc}, nor can you have a trace state variable and a convenience
9561variable with the same name.
9562
9563@table @code
9564
9565@item tvariable $@var{name} [ = @var{expression} ]
9566@kindex tvariable
9567The @code{tvariable} command creates a new trace state variable named
9568@code{$@var{name}}, and optionally gives it an initial value of
9569@var{expression}. @var{expression} is evaluated when this command is
9570entered; the result will be converted to an integer if possible,
9571otherwise @value{GDBN} will report an error. A subsequent
9572@code{tvariable} command specifying the same name does not create a
9573variable, but instead assigns the supplied initial value to the
9574existing variable of that name, overwriting any previous initial
9575value. The default initial value is 0.
9576
9577@item info tvariables
9578@kindex info tvariables
9579List all the trace state variables along with their initial values.
9580Their current values may also be displayed, if the trace experiment is
9581currently running.
9582
9583@item delete tvariable @r{[} $@var{name} @dots{} @r{]}
9584@kindex delete tvariable
9585Delete the given trace state variables, or all of them if no arguments
9586are specified.
9587
9588@end table
9589
b37052ae
EZ
9590@node Tracepoint Actions
9591@subsection Tracepoint Action Lists
9592
9593@table @code
9594@kindex actions
9595@cindex tracepoint actions
9596@item actions @r{[}@var{num}@r{]}
9597This command will prompt for a list of actions to be taken when the
9598tracepoint is hit. If the tracepoint number @var{num} is not
9599specified, this command sets the actions for the one that was most
9600recently defined (so that you can define a tracepoint and then say
9601@code{actions} without bothering about its number). You specify the
9602actions themselves on the following lines, one action at a time, and
9603terminate the actions list with a line containing just @code{end}. So
7d13fe92 9604far, the only defined actions are @code{collect}, @code{teval}, and
b37052ae
EZ
9605@code{while-stepping}.
9606
9607@cindex remove actions from a tracepoint
9608To remove all actions from a tracepoint, type @samp{actions @var{num}}
9609and follow it immediately with @samp{end}.
9610
9611@smallexample
9612(@value{GDBP}) @b{collect @var{data}} // collect some data
9613
6826cf00 9614(@value{GDBP}) @b{while-stepping 5} // single-step 5 times, collect data
b37052ae 9615
6826cf00 9616(@value{GDBP}) @b{end} // signals the end of actions.
b37052ae
EZ
9617@end smallexample
9618
9619In the following example, the action list begins with @code{collect}
9620commands indicating the things to be collected when the tracepoint is
9621hit. Then, in order to single-step and collect additional data
9622following the tracepoint, a @code{while-stepping} command is used,
7d13fe92
SS
9623followed by the list of things to be collected after each step in a
9624sequence of single steps. The @code{while-stepping} command is
9625terminated by its own separate @code{end} command. Lastly, the action
9626list is terminated by an @code{end} command.
b37052ae
EZ
9627
9628@smallexample
9629(@value{GDBP}) @b{trace foo}
9630(@value{GDBP}) @b{actions}
9631Enter actions for tracepoint 1, one per line:
9632> collect bar,baz
9633> collect $regs
9634> while-stepping 12
9635 > collect $fp, $sp
9636 > end
9637end
9638@end smallexample
9639
9640@kindex collect @r{(tracepoints)}
9641@item collect @var{expr1}, @var{expr2}, @dots{}
9642Collect values of the given expressions when the tracepoint is hit.
9643This command accepts a comma-separated list of any valid expressions.
9644In addition to global, static, or local variables, the following
9645special arguments are supported:
9646
9647@table @code
9648@item $regs
9649collect all registers
9650
9651@item $args
9652collect all function arguments
9653
9654@item $locals
9655collect all local variables.
9656@end table
9657
9658You can give several consecutive @code{collect} commands, each one
9659with a single argument, or one @code{collect} command with several
9660arguments separated by commas: the effect is the same.
9661
f5c37c66
EZ
9662The command @code{info scope} (@pxref{Symbols, info scope}) is
9663particularly useful for figuring out what data to collect.
9664
6da95a67
SS
9665@kindex teval @r{(tracepoints)}
9666@item teval @var{expr1}, @var{expr2}, @dots{}
9667Evaluate the given expressions when the tracepoint is hit. This
9668command accepts a comma-separated list of expressions. The results
9669are discarded, so this is mainly useful for assigning values to trace
9670state variables (@pxref{Trace State Variables}) without adding those
9671values to the trace buffer, as would be the case if the @code{collect}
9672action were used.
9673
b37052ae
EZ
9674@kindex while-stepping @r{(tracepoints)}
9675@item while-stepping @var{n}
c9429232 9676Perform @var{n} single-step instruction traces after the tracepoint,
7d13fe92 9677collecting new data after each step. The @code{while-stepping}
c9429232
SS
9678command is followed by the list of what to collect while stepping
9679(followed by its own @code{end} command):
b37052ae
EZ
9680
9681@smallexample
9682> while-stepping 12
9683 > collect $regs, myglobal
9684 > end
9685>
9686@end smallexample
9687
9688@noindent
7d13fe92
SS
9689Note that @code{$pc} is not automatically collected by
9690@code{while-stepping}; you need to explicitly collect that register if
9691you need it. You may abbreviate @code{while-stepping} as @code{ws} or
b37052ae 9692@code{stepping}.
236f1d4d
SS
9693
9694@item set default-collect @var{expr1}, @var{expr2}, @dots{}
9695@kindex set default-collect
9696@cindex default collection action
9697This variable is a list of expressions to collect at each tracepoint
9698hit. It is effectively an additional @code{collect} action prepended
9699to every tracepoint action list. The expressions are parsed
9700individually for each tracepoint, so for instance a variable named
9701@code{xyz} may be interpreted as a global for one tracepoint, and a
9702local for another, as appropriate to the tracepoint's location.
9703
9704@item show default-collect
9705@kindex show default-collect
9706Show the list of expressions that are collected by default at each
9707tracepoint hit.
9708
b37052ae
EZ
9709@end table
9710
9711@node Listing Tracepoints
9712@subsection Listing Tracepoints
9713
9714@table @code
9715@kindex info tracepoints
09d4efe1 9716@kindex info tp
b37052ae
EZ
9717@cindex information about tracepoints
9718@item info tracepoints @r{[}@var{num}@r{]}
1042e4c0
SS
9719Display information about the tracepoint @var{num}. If you don't
9720specify a tracepoint number, displays information about all the
9721tracepoints defined so far. The format is similar to that used for
9722@code{info breakpoints}; in fact, @code{info tracepoints} is the same
9723command, simply restricting itself to tracepoints.
9724
9725A tracepoint's listing may include additional information specific to
9726tracing:
b37052ae
EZ
9727
9728@itemize @bullet
9729@item
b37052ae
EZ
9730its passcount as given by the @code{passcount @var{n}} command
9731@item
9732its step count as given by the @code{while-stepping @var{n}} command
9733@item
1042e4c0
SS
9734its action list as given by the @code{actions} command. The actions
9735are prefixed with an @samp{A} so as to distinguish them from commands.
b37052ae
EZ
9736@end itemize
9737
9738@smallexample
9739(@value{GDBP}) @b{info trace}
1042e4c0
SS
9740Num Type Disp Enb Address What
97411 tracepoint keep y 0x0804ab57 in foo() at main.cxx:7
9742 pass count 1200
9743 step count 20
9744 A while-stepping 20
9745 A collect globfoo, $regs
9746 A end
9747 A collect globfoo2
9748 A end
b37052ae
EZ
9749(@value{GDBP})
9750@end smallexample
9751
9752@noindent
9753This command can be abbreviated @code{info tp}.
9754@end table
9755
79a6e687
BW
9756@node Starting and Stopping Trace Experiments
9757@subsection Starting and Stopping Trace Experiments
b37052ae
EZ
9758
9759@table @code
9760@kindex tstart
9761@cindex start a new trace experiment
9762@cindex collected data discarded
9763@item tstart
9764This command takes no arguments. It starts the trace experiment, and
9765begins collecting data. This has the side effect of discarding all
9766the data collected in the trace buffer during the previous trace
9767experiment.
9768
9769@kindex tstop
9770@cindex stop a running trace experiment
9771@item tstop
9772This command takes no arguments. It ends the trace experiment, and
9773stops collecting data.
9774
68c71a2e 9775@strong{Note}: a trace experiment and data collection may stop
b37052ae
EZ
9776automatically if any tracepoint's passcount is reached
9777(@pxref{Tracepoint Passcounts}), or if the trace buffer becomes full.
9778
9779@kindex tstatus
9780@cindex status of trace data collection
9781@cindex trace experiment, status of
9782@item tstatus
9783This command displays the status of the current trace data
9784collection.
9785@end table
9786
9787Here is an example of the commands we described so far:
9788
9789@smallexample
9790(@value{GDBP}) @b{trace gdb_c_test}
9791(@value{GDBP}) @b{actions}
9792Enter actions for tracepoint #1, one per line.
9793> collect $regs,$locals,$args
9794> while-stepping 11
9795 > collect $regs
9796 > end
9797> end
9798(@value{GDBP}) @b{tstart}
9799 [time passes @dots{}]
9800(@value{GDBP}) @b{tstop}
9801@end smallexample
9802
d5551862
SS
9803@cindex disconnected tracing
9804You can choose to continue running the trace experiment even if
9805@value{GDBN} disconnects from the target, voluntarily or
9806involuntarily. For commands such as @code{detach}, the debugger will
9807ask what you want to do with the trace. But for unexpected
9808terminations (@value{GDBN} crash, network outage), it would be
9809unfortunate to lose hard-won trace data, so the variable
9810@code{disconnected-tracing} lets you decide whether the trace should
9811continue running without @value{GDBN}.
9812
9813@table @code
9814@item set disconnected-tracing on
9815@itemx set disconnected-tracing off
9816@kindex set disconnected-tracing
9817Choose whether a tracing run should continue to run if @value{GDBN}
9818has disconnected from the target. Note that @code{detach} or
9819@code{quit} will ask you directly what to do about a running trace no
9820matter what this variable's setting, so the variable is mainly useful
9821for handling unexpected situations, such as loss of the network.
9822
9823@item show disconnected-tracing
9824@kindex show disconnected-tracing
9825Show the current choice for disconnected tracing.
9826
9827@end table
9828
9829When you reconnect to the target, the trace experiment may or may not
9830still be running; it might have filled the trace buffer in the
9831meantime, or stopped for one of the other reasons. If it is running,
9832it will continue after reconnection.
9833
9834Upon reconnection, the target will upload information about the
9835tracepoints in effect. @value{GDBN} will then compare that
9836information to the set of tracepoints currently defined, and attempt
9837to match them up, allowing for the possibility that the numbers may
9838have changed due to creation and deletion in the meantime. If one of
9839the target's tracepoints does not match any in @value{GDBN}, the
9840debugger will create a new tracepoint, so that you have a number with
9841which to specify that tracepoint. This matching-up process is
9842necessarily heuristic, and it may result in useless tracepoints being
9843created; you may simply delete them if they are of no use.
b37052ae 9844
4daf5ac0
SS
9845@cindex circular trace buffer
9846If your target agent supports a @dfn{circular trace buffer}, then you
9847can run a trace experiment indefinitely without filling the trace
9848buffer; when space runs out, the agent deletes already-collected trace
9849frames, oldest first, until there is enough room to continue
9850collecting. This is especially useful if your tracepoints are being
9851hit too often, and your trace gets terminated prematurely because the
9852buffer is full. To ask for a circular trace buffer, simply set
9853@samp{circular_trace_buffer} to on. You can set this at any time,
9854including during tracing; if the agent can do it, it will change
9855buffer handling on the fly, otherwise it will not take effect until
9856the next run.
9857
9858@table @code
9859@item set circular-trace-buffer on
9860@itemx set circular-trace-buffer off
9861@kindex set circular-trace-buffer
9862Choose whether a tracing run should use a linear or circular buffer
9863for trace data. A linear buffer will not lose any trace data, but may
9864fill up prematurely, while a circular buffer will discard old trace
9865data, but it will have always room for the latest tracepoint hits.
9866
9867@item show circular-trace-buffer
9868@kindex show circular-trace-buffer
9869Show the current choice for the trace buffer. Note that this may not
9870match the agent's current buffer handling, nor is it guaranteed to
9871match the setting that might have been in effect during a past run,
9872for instance if you are looking at frames from a trace file.
9873
9874@end table
9875
c9429232
SS
9876@node Tracepoint Restrictions
9877@subsection Tracepoint Restrictions
9878
9879@cindex tracepoint restrictions
9880There are a number of restrictions on the use of tracepoints. As
9881described above, tracepoint data gathering occurs on the target
9882without interaction from @value{GDBN}. Thus the full capabilities of
9883the debugger are not available during data gathering, and then at data
9884examination time, you will be limited by only having what was
9885collected. The following items describe some common problems, but it
9886is not exhaustive, and you may run into additional difficulties not
9887mentioned here.
9888
9889@itemize @bullet
9890
9891@item
9892Tracepoint expressions are intended to gather objects (lvalues). Thus
9893the full flexibility of GDB's expression evaluator is not available.
9894You cannot call functions, cast objects to aggregate types, access
9895convenience variables or modify values (except by assignment to trace
9896state variables). Some language features may implicitly call
9897functions (for instance Objective-C fields with accessors), and therefore
9898cannot be collected either.
9899
9900@item
9901Collection of local variables, either individually or in bulk with
9902@code{$locals} or @code{$args}, during @code{while-stepping} may
9903behave erratically. The stepping action may enter a new scope (for
9904instance by stepping into a function), or the location of the variable
9905may change (for instance it is loaded into a register). The
9906tracepoint data recorded uses the location information for the
9907variables that is correct for the tracepoint location. When the
9908tracepoint is created, it is not possible, in general, to determine
9909where the steps of a @code{while-stepping} sequence will advance the
9910program---particularly if a conditional branch is stepped.
9911
9912@item
9913Collection of an incompletely-initialized or partially-destroyed object
9914may result in something that @value{GDBN} cannot display, or displays
9915in a misleading way.
9916
9917@item
9918When @value{GDBN} displays a pointer to character it automatically
9919dereferences the pointer to also display characters of the string
9920being pointed to. However, collecting the pointer during tracing does
9921not automatically collect the string. You need to explicitly
9922dereference the pointer and provide size information if you want to
9923collect not only the pointer, but the memory pointed to. For example,
9924@code{*ptr@@50} can be used to collect the 50 element array pointed to
9925by @code{ptr}.
9926
9927@item
9928It is not possible to collect a complete stack backtrace at a
9929tracepoint. Instead, you may collect the registers and a few hundred
9930bytes from the stack pointer with something like @code{*$esp@@300}
9931(adjust to use the name of the actual stack pointer register on your
9932target architecture, and the amount of stack you wish to capture).
9933Then the @code{backtrace} command will show a partial backtrace when
9934using a trace frame. The number of stack frames that can be examined
9935depends on the sizes of the frames in the collected stack. Note that
9936if you ask for a block so large that it goes past the bottom of the
9937stack, the target agent may report an error trying to read from an
9938invalid address.
9939
af54718e
SS
9940@item
9941If you do not collect registers at a tracepoint, @value{GDBN} can
9942infer that the value of @code{$pc} must be the same as the address of
9943the tracepoint and use that when you are looking at a trace frame
9944for that tracepoint. However, this cannot work if the tracepoint has
9945multiple locations (for instance if it was set in a function that was
9946inlined), or if it has a @code{while-stepping} loop. In those cases
9947@value{GDBN} will warn you that it can't infer @code{$pc}, and default
9948it to zero.
9949
c9429232
SS
9950@end itemize
9951
b37052ae 9952@node Analyze Collected Data
79a6e687 9953@section Using the Collected Data
b37052ae
EZ
9954
9955After the tracepoint experiment ends, you use @value{GDBN} commands
9956for examining the trace data. The basic idea is that each tracepoint
9957collects a trace @dfn{snapshot} every time it is hit and another
9958snapshot every time it single-steps. All these snapshots are
9959consecutively numbered from zero and go into a buffer, and you can
9960examine them later. The way you examine them is to @dfn{focus} on a
9961specific trace snapshot. When the remote stub is focused on a trace
9962snapshot, it will respond to all @value{GDBN} requests for memory and
9963registers by reading from the buffer which belongs to that snapshot,
9964rather than from @emph{real} memory or registers of the program being
9965debugged. This means that @strong{all} @value{GDBN} commands
9966(@code{print}, @code{info registers}, @code{backtrace}, etc.) will
9967behave as if we were currently debugging the program state as it was
9968when the tracepoint occurred. Any requests for data that are not in
9969the buffer will fail.
9970
9971@menu
9972* tfind:: How to select a trace snapshot
9973* tdump:: How to display all data for a snapshot
9974* save-tracepoints:: How to save tracepoints for a future run
9975@end menu
9976
9977@node tfind
9978@subsection @code{tfind @var{n}}
9979
9980@kindex tfind
9981@cindex select trace snapshot
9982@cindex find trace snapshot
9983The basic command for selecting a trace snapshot from the buffer is
9984@code{tfind @var{n}}, which finds trace snapshot number @var{n},
9985counting from zero. If no argument @var{n} is given, the next
9986snapshot is selected.
9987
9988Here are the various forms of using the @code{tfind} command.
9989
9990@table @code
9991@item tfind start
9992Find the first snapshot in the buffer. This is a synonym for
9993@code{tfind 0} (since 0 is the number of the first snapshot).
9994
9995@item tfind none
9996Stop debugging trace snapshots, resume @emph{live} debugging.
9997
9998@item tfind end
9999Same as @samp{tfind none}.
10000
10001@item tfind
10002No argument means find the next trace snapshot.
10003
10004@item tfind -
10005Find the previous trace snapshot before the current one. This permits
10006retracing earlier steps.
10007
10008@item tfind tracepoint @var{num}
10009Find the next snapshot associated with tracepoint @var{num}. Search
10010proceeds forward from the last examined trace snapshot. If no
10011argument @var{num} is given, it means find the next snapshot collected
10012for the same tracepoint as the current snapshot.
10013
10014@item tfind pc @var{addr}
10015Find the next snapshot associated with the value @var{addr} of the
10016program counter. Search proceeds forward from the last examined trace
10017snapshot. If no argument @var{addr} is given, it means find the next
10018snapshot with the same value of PC as the current snapshot.
10019
10020@item tfind outside @var{addr1}, @var{addr2}
10021Find the next snapshot whose PC is outside the given range of
081dfbf7 10022addresses (exclusive).
b37052ae
EZ
10023
10024@item tfind range @var{addr1}, @var{addr2}
10025Find the next snapshot whose PC is between @var{addr1} and
081dfbf7 10026@var{addr2} (inclusive).
b37052ae
EZ
10027
10028@item tfind line @r{[}@var{file}:@r{]}@var{n}
10029Find the next snapshot associated with the source line @var{n}. If
10030the optional argument @var{file} is given, refer to line @var{n} in
10031that source file. Search proceeds forward from the last examined
10032trace snapshot. If no argument @var{n} is given, it means find the
10033next line other than the one currently being examined; thus saying
10034@code{tfind line} repeatedly can appear to have the same effect as
10035stepping from line to line in a @emph{live} debugging session.
10036@end table
10037
10038The default arguments for the @code{tfind} commands are specifically
10039designed to make it easy to scan through the trace buffer. For
10040instance, @code{tfind} with no argument selects the next trace
10041snapshot, and @code{tfind -} with no argument selects the previous
10042trace snapshot. So, by giving one @code{tfind} command, and then
10043simply hitting @key{RET} repeatedly you can examine all the trace
10044snapshots in order. Or, by saying @code{tfind -} and then hitting
10045@key{RET} repeatedly you can examine the snapshots in reverse order.
10046The @code{tfind line} command with no argument selects the snapshot
10047for the next source line executed. The @code{tfind pc} command with
10048no argument selects the next snapshot with the same program counter
10049(PC) as the current frame. The @code{tfind tracepoint} command with
10050no argument selects the next trace snapshot collected by the same
10051tracepoint as the current one.
10052
10053In addition to letting you scan through the trace buffer manually,
10054these commands make it easy to construct @value{GDBN} scripts that
10055scan through the trace buffer and print out whatever collected data
10056you are interested in. Thus, if we want to examine the PC, FP, and SP
10057registers from each trace frame in the buffer, we can say this:
10058
10059@smallexample
10060(@value{GDBP}) @b{tfind start}
10061(@value{GDBP}) @b{while ($trace_frame != -1)}
10062> printf "Frame %d, PC = %08X, SP = %08X, FP = %08X\n", \
10063 $trace_frame, $pc, $sp, $fp
10064> tfind
10065> end
10066
10067Frame 0, PC = 0020DC64, SP = 0030BF3C, FP = 0030BF44
10068Frame 1, PC = 0020DC6C, SP = 0030BF38, FP = 0030BF44
10069Frame 2, PC = 0020DC70, SP = 0030BF34, FP = 0030BF44
10070Frame 3, PC = 0020DC74, SP = 0030BF30, FP = 0030BF44
10071Frame 4, PC = 0020DC78, SP = 0030BF2C, FP = 0030BF44
10072Frame 5, PC = 0020DC7C, SP = 0030BF28, FP = 0030BF44
10073Frame 6, PC = 0020DC80, SP = 0030BF24, FP = 0030BF44
10074Frame 7, PC = 0020DC84, SP = 0030BF20, FP = 0030BF44
10075Frame 8, PC = 0020DC88, SP = 0030BF1C, FP = 0030BF44
10076Frame 9, PC = 0020DC8E, SP = 0030BF18, FP = 0030BF44
10077Frame 10, PC = 00203F6C, SP = 0030BE3C, FP = 0030BF14
10078@end smallexample
10079
10080Or, if we want to examine the variable @code{X} at each source line in
10081the buffer:
10082
10083@smallexample
10084(@value{GDBP}) @b{tfind start}
10085(@value{GDBP}) @b{while ($trace_frame != -1)}
10086> printf "Frame %d, X == %d\n", $trace_frame, X
10087> tfind line
10088> end
10089
10090Frame 0, X = 1
10091Frame 7, X = 2
10092Frame 13, X = 255
10093@end smallexample
10094
10095@node tdump
10096@subsection @code{tdump}
10097@kindex tdump
10098@cindex dump all data collected at tracepoint
10099@cindex tracepoint data, display
10100
10101This command takes no arguments. It prints all the data collected at
10102the current trace snapshot.
10103
10104@smallexample
10105(@value{GDBP}) @b{trace 444}
10106(@value{GDBP}) @b{actions}
10107Enter actions for tracepoint #2, one per line:
10108> collect $regs, $locals, $args, gdb_long_test
10109> end
10110
10111(@value{GDBP}) @b{tstart}
10112
10113(@value{GDBP}) @b{tfind line 444}
10114#0 gdb_test (p1=0x11, p2=0x22, p3=0x33, p4=0x44, p5=0x55, p6=0x66)
10115at gdb_test.c:444
10116444 printp( "%s: arguments = 0x%X 0x%X 0x%X 0x%X 0x%X 0x%X\n", )
10117
10118(@value{GDBP}) @b{tdump}
10119Data collected at tracepoint 2, trace frame 1:
10120d0 0xc4aa0085 -995491707
10121d1 0x18 24
10122d2 0x80 128
10123d3 0x33 51
10124d4 0x71aea3d 119204413
10125d5 0x22 34
10126d6 0xe0 224
10127d7 0x380035 3670069
10128a0 0x19e24a 1696330
10129a1 0x3000668 50333288
10130a2 0x100 256
10131a3 0x322000 3284992
10132a4 0x3000698 50333336
10133a5 0x1ad3cc 1758156
10134fp 0x30bf3c 0x30bf3c
10135sp 0x30bf34 0x30bf34
10136ps 0x0 0
10137pc 0x20b2c8 0x20b2c8
10138fpcontrol 0x0 0
10139fpstatus 0x0 0
10140fpiaddr 0x0 0
10141p = 0x20e5b4 "gdb-test"
10142p1 = (void *) 0x11
10143p2 = (void *) 0x22
10144p3 = (void *) 0x33
10145p4 = (void *) 0x44
10146p5 = (void *) 0x55
10147p6 = (void *) 0x66
10148gdb_long_test = 17 '\021'
10149
10150(@value{GDBP})
10151@end smallexample
10152
af54718e
SS
10153@code{tdump} works by scanning the tracepoint's current collection
10154actions and printing the value of each expression listed. So
10155@code{tdump} can fail, if after a run, you change the tracepoint's
10156actions to mention variables that were not collected during the run.
10157
10158Also, for tracepoints with @code{while-stepping} loops, @code{tdump}
10159uses the collected value of @code{$pc} to distinguish between trace
10160frames that were collected at the tracepoint hit, and frames that were
10161collected while stepping. This allows it to correctly choose whether
10162to display the basic list of collections, or the collections from the
10163body of the while-stepping loop. However, if @code{$pc} was not collected,
10164then @code{tdump} will always attempt to dump using the basic collection
10165list, and may fail if a while-stepping frame does not include all the
10166same data that is collected at the tracepoint hit.
10167@c This is getting pretty arcane, example would be good.
10168
b37052ae
EZ
10169@node save-tracepoints
10170@subsection @code{save-tracepoints @var{filename}}
10171@kindex save-tracepoints
10172@cindex save tracepoints for future sessions
10173
10174This command saves all current tracepoint definitions together with
10175their actions and passcounts, into a file @file{@var{filename}}
10176suitable for use in a later debugging session. To read the saved
10177tracepoint definitions, use the @code{source} command (@pxref{Command
10178Files}).
10179
10180@node Tracepoint Variables
10181@section Convenience Variables for Tracepoints
10182@cindex tracepoint variables
10183@cindex convenience variables for tracepoints
10184
10185@table @code
10186@vindex $trace_frame
10187@item (int) $trace_frame
10188The current trace snapshot (a.k.a.@: @dfn{frame}) number, or -1 if no
10189snapshot is selected.
10190
10191@vindex $tracepoint
10192@item (int) $tracepoint
10193The tracepoint for the current trace snapshot.
10194
10195@vindex $trace_line
10196@item (int) $trace_line
10197The line number for the current trace snapshot.
10198
10199@vindex $trace_file
10200@item (char []) $trace_file
10201The source file for the current trace snapshot.
10202
10203@vindex $trace_func
10204@item (char []) $trace_func
10205The name of the function containing @code{$tracepoint}.
10206@end table
10207
10208Note: @code{$trace_file} is not suitable for use in @code{printf},
10209use @code{output} instead.
10210
10211Here's a simple example of using these convenience variables for
10212stepping through all the trace snapshots and printing some of their
f61e138d
SS
10213data. Note that these are not the same as trace state variables,
10214which are managed by the target.
b37052ae
EZ
10215
10216@smallexample
10217(@value{GDBP}) @b{tfind start}
10218
10219(@value{GDBP}) @b{while $trace_frame != -1}
10220> output $trace_file
10221> printf ", line %d (tracepoint #%d)\n", $trace_line, $tracepoint
10222> tfind
10223> end
10224@end smallexample
10225
00bf0b85
SS
10226@node Trace Files
10227@section Using Trace Files
10228@cindex trace files
10229
10230In some situations, the target running a trace experiment may no
10231longer be available; perhaps it crashed, or the hardware was needed
10232for a different activity. To handle these cases, you can arrange to
10233dump the trace data into a file, and later use that file as a source
10234of trace data, via the @code{target tfile} command.
10235
10236@table @code
10237
10238@kindex tsave
10239@item tsave [ -r ] @var{filename}
10240Save the trace data to @var{filename}. By default, this command
10241assumes that @var{filename} refers to the host filesystem, so if
10242necessary @value{GDBN} will copy raw trace data up from the target and
10243then save it. If the target supports it, you can also supply the
10244optional argument @code{-r} (``remote'') to direct the target to save
10245the data directly into @var{filename} in its own filesystem, which may be
10246more efficient if the trace buffer is very large. (Note, however, that
10247@code{target tfile} can only read from files accessible to the host.)
10248
10249@kindex target tfile
10250@kindex tfile
10251@item target tfile @var{filename}
10252Use the file named @var{filename} as a source of trace data. Commands
10253that examine data work as they do with a live target, but it is not
10254possible to run any new trace experiments. @code{tstatus} will report
10255the state of the trace run at the moment the data was saved, as well
10256as the current trace frame you are examining. @var{filename} must be
10257on a filesystem accessible to the host.
10258
10259@end table
10260
df0cd8c5
JB
10261@node Overlays
10262@chapter Debugging Programs That Use Overlays
10263@cindex overlays
10264
10265If your program is too large to fit completely in your target system's
10266memory, you can sometimes use @dfn{overlays} to work around this
10267problem. @value{GDBN} provides some support for debugging programs that
10268use overlays.
10269
10270@menu
10271* How Overlays Work:: A general explanation of overlays.
10272* Overlay Commands:: Managing overlays in @value{GDBN}.
10273* Automatic Overlay Debugging:: @value{GDBN} can find out which overlays are
10274 mapped by asking the inferior.
10275* Overlay Sample Program:: A sample program using overlays.
10276@end menu
10277
10278@node How Overlays Work
10279@section How Overlays Work
10280@cindex mapped overlays
10281@cindex unmapped overlays
10282@cindex load address, overlay's
10283@cindex mapped address
10284@cindex overlay area
10285
10286Suppose you have a computer whose instruction address space is only 64
10287kilobytes long, but which has much more memory which can be accessed by
10288other means: special instructions, segment registers, or memory
10289management hardware, for example. Suppose further that you want to
10290adapt a program which is larger than 64 kilobytes to run on this system.
10291
10292One solution is to identify modules of your program which are relatively
10293independent, and need not call each other directly; call these modules
10294@dfn{overlays}. Separate the overlays from the main program, and place
10295their machine code in the larger memory. Place your main program in
10296instruction memory, but leave at least enough space there to hold the
10297largest overlay as well.
10298
10299Now, to call a function located in an overlay, you must first copy that
10300overlay's machine code from the large memory into the space set aside
10301for it in the instruction memory, and then jump to its entry point
10302there.
10303
c928edc0
AC
10304@c NB: In the below the mapped area's size is greater or equal to the
10305@c size of all overlays. This is intentional to remind the developer
10306@c that overlays don't necessarily need to be the same size.
10307
474c8240 10308@smallexample
df0cd8c5 10309@group
c928edc0
AC
10310 Data Instruction Larger
10311Address Space Address Space Address Space
10312+-----------+ +-----------+ +-----------+
10313| | | | | |
10314+-----------+ +-----------+ +-----------+<-- overlay 1
10315| program | | main | .----| overlay 1 | load address
10316| variables | | program | | +-----------+
10317| and heap | | | | | |
10318+-----------+ | | | +-----------+<-- overlay 2
10319| | +-----------+ | | | load address
10320+-----------+ | | | .-| overlay 2 |
10321 | | | | | |
10322 mapped --->+-----------+ | | +-----------+
10323 address | | | | | |
10324 | overlay | <-' | | |
10325 | area | <---' +-----------+<-- overlay 3
10326 | | <---. | | load address
10327 +-----------+ `--| overlay 3 |
10328 | | | |
10329 +-----------+ | |
10330 +-----------+
10331 | |
10332 +-----------+
10333
10334 @anchor{A code overlay}A code overlay
df0cd8c5 10335@end group
474c8240 10336@end smallexample
df0cd8c5 10337
c928edc0
AC
10338The diagram (@pxref{A code overlay}) shows a system with separate data
10339and instruction address spaces. To map an overlay, the program copies
10340its code from the larger address space to the instruction address space.
10341Since the overlays shown here all use the same mapped address, only one
10342may be mapped at a time. For a system with a single address space for
10343data and instructions, the diagram would be similar, except that the
10344program variables and heap would share an address space with the main
10345program and the overlay area.
df0cd8c5
JB
10346
10347An overlay loaded into instruction memory and ready for use is called a
10348@dfn{mapped} overlay; its @dfn{mapped address} is its address in the
10349instruction memory. An overlay not present (or only partially present)
10350in instruction memory is called @dfn{unmapped}; its @dfn{load address}
10351is its address in the larger memory. The mapped address is also called
10352the @dfn{virtual memory address}, or @dfn{VMA}; the load address is also
10353called the @dfn{load memory address}, or @dfn{LMA}.
10354
10355Unfortunately, overlays are not a completely transparent way to adapt a
10356program to limited instruction memory. They introduce a new set of
10357global constraints you must keep in mind as you design your program:
10358
10359@itemize @bullet
10360
10361@item
10362Before calling or returning to a function in an overlay, your program
10363must make sure that overlay is actually mapped. Otherwise, the call or
10364return will transfer control to the right address, but in the wrong
10365overlay, and your program will probably crash.
10366
10367@item
10368If the process of mapping an overlay is expensive on your system, you
10369will need to choose your overlays carefully to minimize their effect on
10370your program's performance.
10371
10372@item
10373The executable file you load onto your system must contain each
10374overlay's instructions, appearing at the overlay's load address, not its
10375mapped address. However, each overlay's instructions must be relocated
10376and its symbols defined as if the overlay were at its mapped address.
10377You can use GNU linker scripts to specify different load and relocation
10378addresses for pieces of your program; see @ref{Overlay Description,,,
10379ld.info, Using ld: the GNU linker}.
10380
10381@item
10382The procedure for loading executable files onto your system must be able
10383to load their contents into the larger address space as well as the
10384instruction and data spaces.
10385
10386@end itemize
10387
10388The overlay system described above is rather simple, and could be
10389improved in many ways:
10390
10391@itemize @bullet
10392
10393@item
10394If your system has suitable bank switch registers or memory management
10395hardware, you could use those facilities to make an overlay's load area
10396contents simply appear at their mapped address in instruction space.
10397This would probably be faster than copying the overlay to its mapped
10398area in the usual way.
10399
10400@item
10401If your overlays are small enough, you could set aside more than one
10402overlay area, and have more than one overlay mapped at a time.
10403
10404@item
10405You can use overlays to manage data, as well as instructions. In
10406general, data overlays are even less transparent to your design than
10407code overlays: whereas code overlays only require care when you call or
10408return to functions, data overlays require care every time you access
10409the data. Also, if you change the contents of a data overlay, you
10410must copy its contents back out to its load address before you can copy a
10411different data overlay into the same mapped area.
10412
10413@end itemize
10414
10415
10416@node Overlay Commands
10417@section Overlay Commands
10418
10419To use @value{GDBN}'s overlay support, each overlay in your program must
10420correspond to a separate section of the executable file. The section's
10421virtual memory address and load memory address must be the overlay's
10422mapped and load addresses. Identifying overlays with sections allows
10423@value{GDBN} to determine the appropriate address of a function or
10424variable, depending on whether the overlay is mapped or not.
10425
10426@value{GDBN}'s overlay commands all start with the word @code{overlay};
10427you can abbreviate this as @code{ov} or @code{ovly}. The commands are:
10428
10429@table @code
10430@item overlay off
4644b6e3 10431@kindex overlay
df0cd8c5
JB
10432Disable @value{GDBN}'s overlay support. When overlay support is
10433disabled, @value{GDBN} assumes that all functions and variables are
10434always present at their mapped addresses. By default, @value{GDBN}'s
10435overlay support is disabled.
10436
10437@item overlay manual
df0cd8c5
JB
10438@cindex manual overlay debugging
10439Enable @dfn{manual} overlay debugging. In this mode, @value{GDBN}
10440relies on you to tell it which overlays are mapped, and which are not,
10441using the @code{overlay map-overlay} and @code{overlay unmap-overlay}
10442commands described below.
10443
10444@item overlay map-overlay @var{overlay}
10445@itemx overlay map @var{overlay}
df0cd8c5
JB
10446@cindex map an overlay
10447Tell @value{GDBN} that @var{overlay} is now mapped; @var{overlay} must
10448be the name of the object file section containing the overlay. When an
10449overlay is mapped, @value{GDBN} assumes it can find the overlay's
10450functions and variables at their mapped addresses. @value{GDBN} assumes
10451that any other overlays whose mapped ranges overlap that of
10452@var{overlay} are now unmapped.
10453
10454@item overlay unmap-overlay @var{overlay}
10455@itemx overlay unmap @var{overlay}
df0cd8c5
JB
10456@cindex unmap an overlay
10457Tell @value{GDBN} that @var{overlay} is no longer mapped; @var{overlay}
10458must be the name of the object file section containing the overlay.
10459When an overlay is unmapped, @value{GDBN} assumes it can find the
10460overlay's functions and variables at their load addresses.
10461
10462@item overlay auto
df0cd8c5
JB
10463Enable @dfn{automatic} overlay debugging. In this mode, @value{GDBN}
10464consults a data structure the overlay manager maintains in the inferior
10465to see which overlays are mapped. For details, see @ref{Automatic
10466Overlay Debugging}.
10467
10468@item overlay load-target
10469@itemx overlay load
df0cd8c5
JB
10470@cindex reloading the overlay table
10471Re-read the overlay table from the inferior. Normally, @value{GDBN}
10472re-reads the table @value{GDBN} automatically each time the inferior
10473stops, so this command should only be necessary if you have changed the
10474overlay mapping yourself using @value{GDBN}. This command is only
10475useful when using automatic overlay debugging.
10476
10477@item overlay list-overlays
10478@itemx overlay list
10479@cindex listing mapped overlays
10480Display a list of the overlays currently mapped, along with their mapped
10481addresses, load addresses, and sizes.
10482
10483@end table
10484
10485Normally, when @value{GDBN} prints a code address, it includes the name
10486of the function the address falls in:
10487
474c8240 10488@smallexample
f7dc1244 10489(@value{GDBP}) print main
df0cd8c5 10490$3 = @{int ()@} 0x11a0 <main>
474c8240 10491@end smallexample
df0cd8c5
JB
10492@noindent
10493When overlay debugging is enabled, @value{GDBN} recognizes code in
10494unmapped overlays, and prints the names of unmapped functions with
10495asterisks around them. For example, if @code{foo} is a function in an
10496unmapped overlay, @value{GDBN} prints it this way:
10497
474c8240 10498@smallexample
f7dc1244 10499(@value{GDBP}) overlay list
df0cd8c5 10500No sections are mapped.
f7dc1244 10501(@value{GDBP}) print foo
df0cd8c5 10502$5 = @{int (int)@} 0x100000 <*foo*>
474c8240 10503@end smallexample
df0cd8c5
JB
10504@noindent
10505When @code{foo}'s overlay is mapped, @value{GDBN} prints the function's
10506name normally:
10507
474c8240 10508@smallexample
f7dc1244 10509(@value{GDBP}) overlay list
b383017d 10510Section .ov.foo.text, loaded at 0x100000 - 0x100034,
df0cd8c5 10511 mapped at 0x1016 - 0x104a
f7dc1244 10512(@value{GDBP}) print foo
df0cd8c5 10513$6 = @{int (int)@} 0x1016 <foo>
474c8240 10514@end smallexample
df0cd8c5
JB
10515
10516When overlay debugging is enabled, @value{GDBN} can find the correct
10517address for functions and variables in an overlay, whether or not the
10518overlay is mapped. This allows most @value{GDBN} commands, like
10519@code{break} and @code{disassemble}, to work normally, even on unmapped
10520code. However, @value{GDBN}'s breakpoint support has some limitations:
10521
10522@itemize @bullet
10523@item
10524@cindex breakpoints in overlays
10525@cindex overlays, setting breakpoints in
10526You can set breakpoints in functions in unmapped overlays, as long as
10527@value{GDBN} can write to the overlay at its load address.
10528@item
10529@value{GDBN} can not set hardware or simulator-based breakpoints in
10530unmapped overlays. However, if you set a breakpoint at the end of your
10531overlay manager (and tell @value{GDBN} which overlays are now mapped, if
10532you are using manual overlay management), @value{GDBN} will re-set its
10533breakpoints properly.
10534@end itemize
10535
10536
10537@node Automatic Overlay Debugging
10538@section Automatic Overlay Debugging
10539@cindex automatic overlay debugging
10540
10541@value{GDBN} can automatically track which overlays are mapped and which
10542are not, given some simple co-operation from the overlay manager in the
10543inferior. If you enable automatic overlay debugging with the
10544@code{overlay auto} command (@pxref{Overlay Commands}), @value{GDBN}
10545looks in the inferior's memory for certain variables describing the
10546current state of the overlays.
10547
10548Here are the variables your overlay manager must define to support
10549@value{GDBN}'s automatic overlay debugging:
10550
10551@table @asis
10552
10553@item @code{_ovly_table}:
10554This variable must be an array of the following structures:
10555
474c8240 10556@smallexample
df0cd8c5
JB
10557struct
10558@{
10559 /* The overlay's mapped address. */
10560 unsigned long vma;
10561
10562 /* The size of the overlay, in bytes. */
10563 unsigned long size;
10564
10565 /* The overlay's load address. */
10566 unsigned long lma;
10567
10568 /* Non-zero if the overlay is currently mapped;
10569 zero otherwise. */
10570 unsigned long mapped;
10571@}
474c8240 10572@end smallexample
df0cd8c5
JB
10573
10574@item @code{_novlys}:
10575This variable must be a four-byte signed integer, holding the total
10576number of elements in @code{_ovly_table}.
10577
10578@end table
10579
10580To decide whether a particular overlay is mapped or not, @value{GDBN}
10581looks for an entry in @w{@code{_ovly_table}} whose @code{vma} and
10582@code{lma} members equal the VMA and LMA of the overlay's section in the
10583executable file. When @value{GDBN} finds a matching entry, it consults
10584the entry's @code{mapped} member to determine whether the overlay is
10585currently mapped.
10586
81d46470 10587In addition, your overlay manager may define a function called
def71bfa 10588@code{_ovly_debug_event}. If this function is defined, @value{GDBN}
81d46470
MS
10589will silently set a breakpoint there. If the overlay manager then
10590calls this function whenever it has changed the overlay table, this
10591will enable @value{GDBN} to accurately keep track of which overlays
10592are in program memory, and update any breakpoints that may be set
b383017d 10593in overlays. This will allow breakpoints to work even if the
81d46470
MS
10594overlays are kept in ROM or other non-writable memory while they
10595are not being executed.
df0cd8c5
JB
10596
10597@node Overlay Sample Program
10598@section Overlay Sample Program
10599@cindex overlay example program
10600
10601When linking a program which uses overlays, you must place the overlays
10602at their load addresses, while relocating them to run at their mapped
10603addresses. To do this, you must write a linker script (@pxref{Overlay
10604Description,,, ld.info, Using ld: the GNU linker}). Unfortunately,
10605since linker scripts are specific to a particular host system, target
10606architecture, and target memory layout, this manual cannot provide
10607portable sample code demonstrating @value{GDBN}'s overlay support.
10608
10609However, the @value{GDBN} source distribution does contain an overlaid
10610program, with linker scripts for a few systems, as part of its test
10611suite. The program consists of the following files from
10612@file{gdb/testsuite/gdb.base}:
10613
10614@table @file
10615@item overlays.c
10616The main program file.
10617@item ovlymgr.c
10618A simple overlay manager, used by @file{overlays.c}.
10619@item foo.c
10620@itemx bar.c
10621@itemx baz.c
10622@itemx grbx.c
10623Overlay modules, loaded and used by @file{overlays.c}.
10624@item d10v.ld
10625@itemx m32r.ld
10626Linker scripts for linking the test program on the @code{d10v-elf}
10627and @code{m32r-elf} targets.
10628@end table
10629
10630You can build the test program using the @code{d10v-elf} GCC
10631cross-compiler like this:
10632
474c8240 10633@smallexample
df0cd8c5
JB
10634$ d10v-elf-gcc -g -c overlays.c
10635$ d10v-elf-gcc -g -c ovlymgr.c
10636$ d10v-elf-gcc -g -c foo.c
10637$ d10v-elf-gcc -g -c bar.c
10638$ d10v-elf-gcc -g -c baz.c
10639$ d10v-elf-gcc -g -c grbx.c
10640$ d10v-elf-gcc -g overlays.o ovlymgr.o foo.o bar.o \
10641 baz.o grbx.o -Wl,-Td10v.ld -o overlays
474c8240 10642@end smallexample
df0cd8c5
JB
10643
10644The build process is identical for any other architecture, except that
10645you must substitute the appropriate compiler and linker script for the
10646target system for @code{d10v-elf-gcc} and @code{d10v.ld}.
10647
10648
6d2ebf8b 10649@node Languages
c906108c
SS
10650@chapter Using @value{GDBN} with Different Languages
10651@cindex languages
10652
c906108c
SS
10653Although programming languages generally have common aspects, they are
10654rarely expressed in the same manner. For instance, in ANSI C,
10655dereferencing a pointer @code{p} is accomplished by @code{*p}, but in
10656Modula-2, it is accomplished by @code{p^}. Values can also be
5d161b24 10657represented (and displayed) differently. Hex numbers in C appear as
c906108c 10658@samp{0x1ae}, while in Modula-2 they appear as @samp{1AEH}.
c906108c
SS
10659
10660@cindex working language
10661Language-specific information is built into @value{GDBN} for some languages,
10662allowing you to express operations like the above in your program's
10663native language, and allowing @value{GDBN} to output values in a manner
10664consistent with the syntax of your program's native language. The
10665language you use to build expressions is called the @dfn{working
10666language}.
10667
10668@menu
10669* Setting:: Switching between source languages
10670* Show:: Displaying the language
c906108c 10671* Checks:: Type and range checks
79a6e687
BW
10672* Supported Languages:: Supported languages
10673* Unsupported Languages:: Unsupported languages
c906108c
SS
10674@end menu
10675
6d2ebf8b 10676@node Setting
79a6e687 10677@section Switching Between Source Languages
c906108c
SS
10678
10679There are two ways to control the working language---either have @value{GDBN}
10680set it automatically, or select it manually yourself. You can use the
10681@code{set language} command for either purpose. On startup, @value{GDBN}
10682defaults to setting the language automatically. The working language is
10683used to determine how expressions you type are interpreted, how values
10684are printed, etc.
10685
10686In addition to the working language, every source file that
10687@value{GDBN} knows about has its own working language. For some object
10688file formats, the compiler might indicate which language a particular
10689source file is in. However, most of the time @value{GDBN} infers the
10690language from the name of the file. The language of a source file
b37052ae 10691controls whether C@t{++} names are demangled---this way @code{backtrace} can
c906108c 10692show each frame appropriately for its own language. There is no way to
d4f3574e
SS
10693set the language of a source file from within @value{GDBN}, but you can
10694set the language associated with a filename extension. @xref{Show, ,
79a6e687 10695Displaying the Language}.
c906108c
SS
10696
10697This is most commonly a problem when you use a program, such
5d161b24 10698as @code{cfront} or @code{f2c}, that generates C but is written in
c906108c
SS
10699another language. In that case, make the
10700program use @code{#line} directives in its C output; that way
10701@value{GDBN} will know the correct language of the source code of the original
10702program, and will display that source code, not the generated C code.
10703
10704@menu
10705* Filenames:: Filename extensions and languages.
10706* Manually:: Setting the working language manually
10707* Automatically:: Having @value{GDBN} infer the source language
10708@end menu
10709
6d2ebf8b 10710@node Filenames
79a6e687 10711@subsection List of Filename Extensions and Languages
c906108c
SS
10712
10713If a source file name ends in one of the following extensions, then
10714@value{GDBN} infers that its language is the one indicated.
10715
10716@table @file
e07c999f
PH
10717@item .ada
10718@itemx .ads
10719@itemx .adb
10720@itemx .a
10721Ada source file.
c906108c
SS
10722
10723@item .c
10724C source file
10725
10726@item .C
10727@itemx .cc
10728@itemx .cp
10729@itemx .cpp
10730@itemx .cxx
10731@itemx .c++
b37052ae 10732C@t{++} source file
c906108c 10733
b37303ee
AF
10734@item .m
10735Objective-C source file
10736
c906108c
SS
10737@item .f
10738@itemx .F
10739Fortran source file
10740
c906108c
SS
10741@item .mod
10742Modula-2 source file
c906108c
SS
10743
10744@item .s
10745@itemx .S
10746Assembler source file. This actually behaves almost like C, but
10747@value{GDBN} does not skip over function prologues when stepping.
10748@end table
10749
10750In addition, you may set the language associated with a filename
79a6e687 10751extension. @xref{Show, , Displaying the Language}.
c906108c 10752
6d2ebf8b 10753@node Manually
79a6e687 10754@subsection Setting the Working Language
c906108c
SS
10755
10756If you allow @value{GDBN} to set the language automatically,
10757expressions are interpreted the same way in your debugging session and
10758your program.
10759
10760@kindex set language
10761If you wish, you may set the language manually. To do this, issue the
10762command @samp{set language @var{lang}}, where @var{lang} is the name of
5d161b24 10763a language, such as
c906108c 10764@code{c} or @code{modula-2}.
c906108c
SS
10765For a list of the supported languages, type @samp{set language}.
10766
c906108c
SS
10767Setting the language manually prevents @value{GDBN} from updating the working
10768language automatically. This can lead to confusion if you try
10769to debug a program when the working language is not the same as the
10770source language, when an expression is acceptable to both
10771languages---but means different things. For instance, if the current
10772source file were written in C, and @value{GDBN} was parsing Modula-2, a
10773command such as:
10774
474c8240 10775@smallexample
c906108c 10776print a = b + c
474c8240 10777@end smallexample
c906108c
SS
10778
10779@noindent
10780might not have the effect you intended. In C, this means to add
10781@code{b} and @code{c} and place the result in @code{a}. The result
10782printed would be the value of @code{a}. In Modula-2, this means to compare
10783@code{a} to the result of @code{b+c}, yielding a @code{BOOLEAN} value.
c906108c 10784
6d2ebf8b 10785@node Automatically
79a6e687 10786@subsection Having @value{GDBN} Infer the Source Language
c906108c
SS
10787
10788To have @value{GDBN} set the working language automatically, use
10789@samp{set language local} or @samp{set language auto}. @value{GDBN}
10790then infers the working language. That is, when your program stops in a
10791frame (usually by encountering a breakpoint), @value{GDBN} sets the
10792working language to the language recorded for the function in that
10793frame. If the language for a frame is unknown (that is, if the function
10794or block corresponding to the frame was defined in a source file that
10795does not have a recognized extension), the current working language is
10796not changed, and @value{GDBN} issues a warning.
10797
10798This may not seem necessary for most programs, which are written
10799entirely in one source language. However, program modules and libraries
10800written in one source language can be used by a main program written in
10801a different source language. Using @samp{set language auto} in this
10802case frees you from having to set the working language manually.
10803
6d2ebf8b 10804@node Show
79a6e687 10805@section Displaying the Language
c906108c
SS
10806
10807The following commands help you find out which language is the
10808working language, and also what language source files were written in.
10809
c906108c
SS
10810@table @code
10811@item show language
9c16f35a 10812@kindex show language
c906108c
SS
10813Display the current working language. This is the
10814language you can use with commands such as @code{print} to
10815build and compute expressions that may involve variables in your program.
10816
10817@item info frame
4644b6e3 10818@kindex info frame@r{, show the source language}
5d161b24 10819Display the source language for this frame. This language becomes the
c906108c 10820working language if you use an identifier from this frame.
79a6e687 10821@xref{Frame Info, ,Information about a Frame}, to identify the other
c906108c
SS
10822information listed here.
10823
10824@item info source
4644b6e3 10825@kindex info source@r{, show the source language}
c906108c 10826Display the source language of this source file.
5d161b24 10827@xref{Symbols, ,Examining the Symbol Table}, to identify the other
c906108c
SS
10828information listed here.
10829@end table
10830
10831In unusual circumstances, you may have source files with extensions
10832not in the standard list. You can then set the extension associated
10833with a language explicitly:
10834
c906108c 10835@table @code
09d4efe1 10836@item set extension-language @var{ext} @var{language}
9c16f35a 10837@kindex set extension-language
09d4efe1
EZ
10838Tell @value{GDBN} that source files with extension @var{ext} are to be
10839assumed as written in the source language @var{language}.
c906108c
SS
10840
10841@item info extensions
9c16f35a 10842@kindex info extensions
c906108c
SS
10843List all the filename extensions and the associated languages.
10844@end table
10845
6d2ebf8b 10846@node Checks
79a6e687 10847@section Type and Range Checking
c906108c
SS
10848
10849@quotation
10850@emph{Warning:} In this release, the @value{GDBN} commands for type and range
10851checking are included, but they do not yet have any effect. This
10852section documents the intended facilities.
10853@end quotation
10854@c FIXME remove warning when type/range code added
10855
10856Some languages are designed to guard you against making seemingly common
10857errors through a series of compile- and run-time checks. These include
10858checking the type of arguments to functions and operators, and making
10859sure mathematical overflows are caught at run time. Checks such as
10860these help to ensure a program's correctness once it has been compiled
10861by eliminating type mismatches, and providing active checks for range
10862errors when your program is running.
10863
10864@value{GDBN} can check for conditions like the above if you wish.
9c16f35a
EZ
10865Although @value{GDBN} does not check the statements in your program,
10866it can check expressions entered directly into @value{GDBN} for
10867evaluation via the @code{print} command, for example. As with the
10868working language, @value{GDBN} can also decide whether or not to check
10869automatically based on your program's source language.
79a6e687 10870@xref{Supported Languages, ,Supported Languages}, for the default
9c16f35a 10871settings of supported languages.
c906108c
SS
10872
10873@menu
10874* Type Checking:: An overview of type checking
10875* Range Checking:: An overview of range checking
10876@end menu
10877
10878@cindex type checking
10879@cindex checks, type
6d2ebf8b 10880@node Type Checking
79a6e687 10881@subsection An Overview of Type Checking
c906108c
SS
10882
10883Some languages, such as Modula-2, are strongly typed, meaning that the
10884arguments to operators and functions have to be of the correct type,
10885otherwise an error occurs. These checks prevent type mismatch
10886errors from ever causing any run-time problems. For example,
10887
10888@smallexample
108891 + 2 @result{} 3
10890@exdent but
10891@error{} 1 + 2.3
10892@end smallexample
10893
10894The second example fails because the @code{CARDINAL} 1 is not
10895type-compatible with the @code{REAL} 2.3.
10896
5d161b24
DB
10897For the expressions you use in @value{GDBN} commands, you can tell the
10898@value{GDBN} type checker to skip checking;
10899to treat any mismatches as errors and abandon the expression;
10900or to only issue warnings when type mismatches occur,
c906108c
SS
10901but evaluate the expression anyway. When you choose the last of
10902these, @value{GDBN} evaluates expressions like the second example above, but
10903also issues a warning.
10904
5d161b24
DB
10905Even if you turn type checking off, there may be other reasons
10906related to type that prevent @value{GDBN} from evaluating an expression.
10907For instance, @value{GDBN} does not know how to add an @code{int} and
10908a @code{struct foo}. These particular type errors have nothing to do
10909with the language in use, and usually arise from expressions, such as
c906108c
SS
10910the one described above, which make little sense to evaluate anyway.
10911
10912Each language defines to what degree it is strict about type. For
10913instance, both Modula-2 and C require the arguments to arithmetical
10914operators to be numbers. In C, enumerated types and pointers can be
10915represented as numbers, so that they are valid arguments to mathematical
79a6e687 10916operators. @xref{Supported Languages, ,Supported Languages}, for further
c906108c
SS
10917details on specific languages.
10918
10919@value{GDBN} provides some additional commands for controlling the type checker:
10920
c906108c
SS
10921@kindex set check type
10922@kindex show check type
10923@table @code
10924@item set check type auto
10925Set type checking on or off based on the current working language.
79a6e687 10926@xref{Supported Languages, ,Supported Languages}, for the default settings for
c906108c
SS
10927each language.
10928
10929@item set check type on
10930@itemx set check type off
10931Set type checking on or off, overriding the default setting for the
10932current working language. Issue a warning if the setting does not
10933match the language default. If any type mismatches occur in
d4f3574e 10934evaluating an expression while type checking is on, @value{GDBN} prints a
c906108c
SS
10935message and aborts evaluation of the expression.
10936
10937@item set check type warn
10938Cause the type checker to issue warnings, but to always attempt to
10939evaluate the expression. Evaluating the expression may still
10940be impossible for other reasons. For example, @value{GDBN} cannot add
10941numbers and structures.
10942
10943@item show type
5d161b24 10944Show the current setting of the type checker, and whether or not @value{GDBN}
c906108c
SS
10945is setting it automatically.
10946@end table
10947
10948@cindex range checking
10949@cindex checks, range
6d2ebf8b 10950@node Range Checking
79a6e687 10951@subsection An Overview of Range Checking
c906108c
SS
10952
10953In some languages (such as Modula-2), it is an error to exceed the
10954bounds of a type; this is enforced with run-time checks. Such range
10955checking is meant to ensure program correctness by making sure
10956computations do not overflow, or indices on an array element access do
10957not exceed the bounds of the array.
10958
10959For expressions you use in @value{GDBN} commands, you can tell
10960@value{GDBN} to treat range errors in one of three ways: ignore them,
10961always treat them as errors and abandon the expression, or issue
10962warnings but evaluate the expression anyway.
10963
10964A range error can result from numerical overflow, from exceeding an
10965array index bound, or when you type a constant that is not a member
10966of any type. Some languages, however, do not treat overflows as an
10967error. In many implementations of C, mathematical overflow causes the
10968result to ``wrap around'' to lower values---for example, if @var{m} is
10969the largest integer value, and @var{s} is the smallest, then
10970
474c8240 10971@smallexample
c906108c 10972@var{m} + 1 @result{} @var{s}
474c8240 10973@end smallexample
c906108c
SS
10974
10975This, too, is specific to individual languages, and in some cases
79a6e687
BW
10976specific to individual compilers or machines. @xref{Supported Languages, ,
10977Supported Languages}, for further details on specific languages.
c906108c
SS
10978
10979@value{GDBN} provides some additional commands for controlling the range checker:
10980
c906108c
SS
10981@kindex set check range
10982@kindex show check range
10983@table @code
10984@item set check range auto
10985Set range checking on or off based on the current working language.
79a6e687 10986@xref{Supported Languages, ,Supported Languages}, for the default settings for
c906108c
SS
10987each language.
10988
10989@item set check range on
10990@itemx set check range off
10991Set range checking on or off, overriding the default setting for the
10992current working language. A warning is issued if the setting does not
c3f6f71d
JM
10993match the language default. If a range error occurs and range checking is on,
10994then a message is printed and evaluation of the expression is aborted.
c906108c
SS
10995
10996@item set check range warn
10997Output messages when the @value{GDBN} range checker detects a range error,
10998but attempt to evaluate the expression anyway. Evaluating the
10999expression may still be impossible for other reasons, such as accessing
11000memory that the process does not own (a typical example from many Unix
11001systems).
11002
11003@item show range
11004Show the current setting of the range checker, and whether or not it is
11005being set automatically by @value{GDBN}.
11006@end table
c906108c 11007
79a6e687
BW
11008@node Supported Languages
11009@section Supported Languages
c906108c 11010
9c16f35a
EZ
11011@value{GDBN} supports C, C@t{++}, Objective-C, Fortran, Java, Pascal,
11012assembly, Modula-2, and Ada.
cce74817 11013@c This is false ...
c906108c
SS
11014Some @value{GDBN} features may be used in expressions regardless of the
11015language you use: the @value{GDBN} @code{@@} and @code{::} operators,
11016and the @samp{@{type@}addr} construct (@pxref{Expressions,
11017,Expressions}) can be used with the constructs of any supported
11018language.
11019
11020The following sections detail to what degree each source language is
11021supported by @value{GDBN}. These sections are not meant to be language
11022tutorials or references, but serve only as a reference guide to what the
11023@value{GDBN} expression parser accepts, and what input and output
11024formats should look like for different languages. There are many good
11025books written on each of these languages; please look to these for a
11026language reference or tutorial.
11027
c906108c 11028@menu
b37303ee 11029* C:: C and C@t{++}
b383017d 11030* Objective-C:: Objective-C
09d4efe1 11031* Fortran:: Fortran
9c16f35a 11032* Pascal:: Pascal
b37303ee 11033* Modula-2:: Modula-2
e07c999f 11034* Ada:: Ada
c906108c
SS
11035@end menu
11036
6d2ebf8b 11037@node C
b37052ae 11038@subsection C and C@t{++}
7a292a7a 11039
b37052ae
EZ
11040@cindex C and C@t{++}
11041@cindex expressions in C or C@t{++}
c906108c 11042
b37052ae 11043Since C and C@t{++} are so closely related, many features of @value{GDBN} apply
c906108c
SS
11044to both languages. Whenever this is the case, we discuss those languages
11045together.
11046
41afff9a
EZ
11047@cindex C@t{++}
11048@cindex @code{g++}, @sc{gnu} C@t{++} compiler
b37052ae
EZ
11049@cindex @sc{gnu} C@t{++}
11050The C@t{++} debugging facilities are jointly implemented by the C@t{++}
11051compiler and @value{GDBN}. Therefore, to debug your C@t{++} code
11052effectively, you must compile your C@t{++} programs with a supported
11053C@t{++} compiler, such as @sc{gnu} @code{g++}, or the HP ANSI C@t{++}
c906108c
SS
11054compiler (@code{aCC}).
11055
0179ffac
DC
11056For best results when using @sc{gnu} C@t{++}, use the DWARF 2 debugging
11057format; if it doesn't work on your system, try the stabs+ debugging
11058format. You can select those formats explicitly with the @code{g++}
11059command-line options @option{-gdwarf-2} and @option{-gstabs+}.
ce9341a1
BW
11060@xref{Debugging Options,,Options for Debugging Your Program or GCC,
11061gcc.info, Using the @sc{gnu} Compiler Collection (GCC)}.
c906108c 11062
c906108c 11063@menu
b37052ae
EZ
11064* C Operators:: C and C@t{++} operators
11065* C Constants:: C and C@t{++} constants
79a6e687 11066* C Plus Plus Expressions:: C@t{++} expressions
b37052ae
EZ
11067* C Defaults:: Default settings for C and C@t{++}
11068* C Checks:: C and C@t{++} type and range checks
c906108c 11069* Debugging C:: @value{GDBN} and C
79a6e687 11070* Debugging C Plus Plus:: @value{GDBN} features for C@t{++}
febe4383 11071* Decimal Floating Point:: Numbers in Decimal Floating Point format
c906108c 11072@end menu
c906108c 11073
6d2ebf8b 11074@node C Operators
79a6e687 11075@subsubsection C and C@t{++} Operators
7a292a7a 11076
b37052ae 11077@cindex C and C@t{++} operators
c906108c
SS
11078
11079Operators must be defined on values of specific types. For instance,
11080@code{+} is defined on numbers, but not on structures. Operators are
5d161b24 11081often defined on groups of types.
c906108c 11082
b37052ae 11083For the purposes of C and C@t{++}, the following definitions hold:
c906108c
SS
11084
11085@itemize @bullet
53a5351d 11086
c906108c 11087@item
c906108c 11088@emph{Integral types} include @code{int} with any of its storage-class
b37052ae 11089specifiers; @code{char}; @code{enum}; and, for C@t{++}, @code{bool}.
c906108c
SS
11090
11091@item
d4f3574e
SS
11092@emph{Floating-point types} include @code{float}, @code{double}, and
11093@code{long double} (if supported by the target platform).
c906108c
SS
11094
11095@item
53a5351d 11096@emph{Pointer types} include all types defined as @code{(@var{type} *)}.
c906108c
SS
11097
11098@item
11099@emph{Scalar types} include all of the above.
53a5351d 11100
c906108c
SS
11101@end itemize
11102
11103@noindent
11104The following operators are supported. They are listed here
11105in order of increasing precedence:
11106
11107@table @code
11108@item ,
11109The comma or sequencing operator. Expressions in a comma-separated list
11110are evaluated from left to right, with the result of the entire
11111expression being the last expression evaluated.
11112
11113@item =
11114Assignment. The value of an assignment expression is the value
11115assigned. Defined on scalar types.
11116
11117@item @var{op}=
11118Used in an expression of the form @w{@code{@var{a} @var{op}= @var{b}}},
11119and translated to @w{@code{@var{a} = @var{a op b}}}.
d4f3574e 11120@w{@code{@var{op}=}} and @code{=} have the same precedence.
c906108c
SS
11121@var{op} is any one of the operators @code{|}, @code{^}, @code{&},
11122@code{<<}, @code{>>}, @code{+}, @code{-}, @code{*}, @code{/}, @code{%}.
11123
11124@item ?:
11125The ternary operator. @code{@var{a} ? @var{b} : @var{c}} can be thought
11126of as: if @var{a} then @var{b} else @var{c}. @var{a} should be of an
11127integral type.
11128
11129@item ||
11130Logical @sc{or}. Defined on integral types.
11131
11132@item &&
11133Logical @sc{and}. Defined on integral types.
11134
11135@item |
11136Bitwise @sc{or}. Defined on integral types.
11137
11138@item ^
11139Bitwise exclusive-@sc{or}. Defined on integral types.
11140
11141@item &
11142Bitwise @sc{and}. Defined on integral types.
11143
11144@item ==@r{, }!=
11145Equality and inequality. Defined on scalar types. The value of these
11146expressions is 0 for false and non-zero for true.
11147
11148@item <@r{, }>@r{, }<=@r{, }>=
11149Less than, greater than, less than or equal, greater than or equal.
11150Defined on scalar types. The value of these expressions is 0 for false
11151and non-zero for true.
11152
11153@item <<@r{, }>>
11154left shift, and right shift. Defined on integral types.
11155
11156@item @@
11157The @value{GDBN} ``artificial array'' operator (@pxref{Expressions, ,Expressions}).
11158
11159@item +@r{, }-
11160Addition and subtraction. Defined on integral types, floating-point types and
11161pointer types.
11162
11163@item *@r{, }/@r{, }%
11164Multiplication, division, and modulus. Multiplication and division are
11165defined on integral and floating-point types. Modulus is defined on
11166integral types.
11167
11168@item ++@r{, }--
11169Increment and decrement. When appearing before a variable, the
11170operation is performed before the variable is used in an expression;
11171when appearing after it, the variable's value is used before the
11172operation takes place.
11173
11174@item *
11175Pointer dereferencing. Defined on pointer types. Same precedence as
11176@code{++}.
11177
11178@item &
11179Address operator. Defined on variables. Same precedence as @code{++}.
11180
b37052ae
EZ
11181For debugging C@t{++}, @value{GDBN} implements a use of @samp{&} beyond what is
11182allowed in the C@t{++} language itself: you can use @samp{&(&@var{ref})}
b17828ca 11183to examine the address
b37052ae 11184where a C@t{++} reference variable (declared with @samp{&@var{ref}}) is
c906108c 11185stored.
c906108c
SS
11186
11187@item -
11188Negative. Defined on integral and floating-point types. Same
11189precedence as @code{++}.
11190
11191@item !
11192Logical negation. Defined on integral types. Same precedence as
11193@code{++}.
11194
11195@item ~
11196Bitwise complement operator. Defined on integral types. Same precedence as
11197@code{++}.
11198
11199
11200@item .@r{, }->
11201Structure member, and pointer-to-structure member. For convenience,
11202@value{GDBN} regards the two as equivalent, choosing whether to dereference a
11203pointer based on the stored type information.
11204Defined on @code{struct} and @code{union} data.
11205
c906108c
SS
11206@item .*@r{, }->*
11207Dereferences of pointers to members.
c906108c
SS
11208
11209@item []
11210Array indexing. @code{@var{a}[@var{i}]} is defined as
11211@code{*(@var{a}+@var{i})}. Same precedence as @code{->}.
11212
11213@item ()
11214Function parameter list. Same precedence as @code{->}.
11215
c906108c 11216@item ::
b37052ae 11217C@t{++} scope resolution operator. Defined on @code{struct}, @code{union},
7a292a7a 11218and @code{class} types.
c906108c
SS
11219
11220@item ::
7a292a7a
SS
11221Doubled colons also represent the @value{GDBN} scope operator
11222(@pxref{Expressions, ,Expressions}). Same precedence as @code{::},
11223above.
c906108c
SS
11224@end table
11225
c906108c
SS
11226If an operator is redefined in the user code, @value{GDBN} usually
11227attempts to invoke the redefined version instead of using the operator's
11228predefined meaning.
c906108c 11229
6d2ebf8b 11230@node C Constants
79a6e687 11231@subsubsection C and C@t{++} Constants
c906108c 11232
b37052ae 11233@cindex C and C@t{++} constants
c906108c 11234
b37052ae 11235@value{GDBN} allows you to express the constants of C and C@t{++} in the
c906108c 11236following ways:
c906108c
SS
11237
11238@itemize @bullet
11239@item
11240Integer constants are a sequence of digits. Octal constants are
6ca652b0
EZ
11241specified by a leading @samp{0} (i.e.@: zero), and hexadecimal constants
11242by a leading @samp{0x} or @samp{0X}. Constants may also end with a letter
c906108c
SS
11243@samp{l}, specifying that the constant should be treated as a
11244@code{long} value.
11245
11246@item
11247Floating point constants are a sequence of digits, followed by a decimal
11248point, followed by a sequence of digits, and optionally followed by an
11249exponent. An exponent is of the form:
11250@samp{@w{e@r{[[}+@r{]|}-@r{]}@var{nnn}}}, where @var{nnn} is another
11251sequence of digits. The @samp{+} is optional for positive exponents.
d4f3574e
SS
11252A floating-point constant may also end with a letter @samp{f} or
11253@samp{F}, specifying that the constant should be treated as being of
11254the @code{float} (as opposed to the default @code{double}) type; or with
11255a letter @samp{l} or @samp{L}, which specifies a @code{long double}
11256constant.
c906108c
SS
11257
11258@item
11259Enumerated constants consist of enumerated identifiers, or their
11260integral equivalents.
11261
11262@item
11263Character constants are a single character surrounded by single quotes
11264(@code{'}), or a number---the ordinal value of the corresponding character
d4f3574e 11265(usually its @sc{ascii} value). Within quotes, the single character may
c906108c
SS
11266be represented by a letter or by @dfn{escape sequences}, which are of
11267the form @samp{\@var{nnn}}, where @var{nnn} is the octal representation
11268of the character's ordinal value; or of the form @samp{\@var{x}}, where
11269@samp{@var{x}} is a predefined special character---for example,
11270@samp{\n} for newline.
11271
11272@item
96a2c332
SS
11273String constants are a sequence of character constants surrounded by
11274double quotes (@code{"}). Any valid character constant (as described
11275above) may appear. Double quotes within the string must be preceded by
11276a backslash, so for instance @samp{"a\"b'c"} is a string of five
11277characters.
c906108c
SS
11278
11279@item
11280Pointer constants are an integral value. You can also write pointers
11281to constants using the C operator @samp{&}.
11282
11283@item
11284Array constants are comma-separated lists surrounded by braces @samp{@{}
11285and @samp{@}}; for example, @samp{@{1,2,3@}} is a three-element array of
11286integers, @samp{@{@{1,2@}, @{3,4@}, @{5,6@}@}} is a three-by-two array,
11287and @samp{@{&"hi", &"there", &"fred"@}} is a three-element array of pointers.
11288@end itemize
11289
79a6e687
BW
11290@node C Plus Plus Expressions
11291@subsubsection C@t{++} Expressions
b37052ae
EZ
11292
11293@cindex expressions in C@t{++}
11294@value{GDBN} expression handling can interpret most C@t{++} expressions.
11295
0179ffac
DC
11296@cindex debugging C@t{++} programs
11297@cindex C@t{++} compilers
11298@cindex debug formats and C@t{++}
11299@cindex @value{NGCC} and C@t{++}
c906108c 11300@quotation
b37052ae 11301@emph{Warning:} @value{GDBN} can only debug C@t{++} code if you use the
0179ffac
DC
11302proper compiler and the proper debug format. Currently, @value{GDBN}
11303works best when debugging C@t{++} code that is compiled with
11304@value{NGCC} 2.95.3 or with @value{NGCC} 3.1 or newer, using the options
11305@option{-gdwarf-2} or @option{-gstabs+}. DWARF 2 is preferred over
11306stabs+. Most configurations of @value{NGCC} emit either DWARF 2 or
11307stabs+ as their default debug format, so you usually don't need to
11308specify a debug format explicitly. Other compilers and/or debug formats
11309are likely to work badly or not at all when using @value{GDBN} to debug
11310C@t{++} code.
c906108c 11311@end quotation
c906108c
SS
11312
11313@enumerate
11314
11315@cindex member functions
11316@item
11317Member function calls are allowed; you can use expressions like
11318
474c8240 11319@smallexample
c906108c 11320count = aml->GetOriginal(x, y)
474c8240 11321@end smallexample
c906108c 11322
41afff9a 11323@vindex this@r{, inside C@t{++} member functions}
b37052ae 11324@cindex namespace in C@t{++}
c906108c
SS
11325@item
11326While a member function is active (in the selected stack frame), your
11327expressions have the same namespace available as the member function;
11328that is, @value{GDBN} allows implicit references to the class instance
b37052ae 11329pointer @code{this} following the same rules as C@t{++}.
c906108c 11330
c906108c 11331@cindex call overloaded functions
d4f3574e 11332@cindex overloaded functions, calling
b37052ae 11333@cindex type conversions in C@t{++}
c906108c
SS
11334@item
11335You can call overloaded functions; @value{GDBN} resolves the function
d4f3574e 11336call to the right definition, with some restrictions. @value{GDBN} does not
c906108c
SS
11337perform overload resolution involving user-defined type conversions,
11338calls to constructors, or instantiations of templates that do not exist
11339in the program. It also cannot handle ellipsis argument lists or
11340default arguments.
11341
11342It does perform integral conversions and promotions, floating-point
11343promotions, arithmetic conversions, pointer conversions, conversions of
11344class objects to base classes, and standard conversions such as those of
11345functions or arrays to pointers; it requires an exact match on the
11346number of function arguments.
11347
11348Overload resolution is always performed, unless you have specified
79a6e687
BW
11349@code{set overload-resolution off}. @xref{Debugging C Plus Plus,
11350,@value{GDBN} Features for C@t{++}}.
c906108c 11351
d4f3574e 11352You must specify @code{set overload-resolution off} in order to use an
c906108c
SS
11353explicit function signature to call an overloaded function, as in
11354@smallexample
11355p 'foo(char,int)'('x', 13)
11356@end smallexample
d4f3574e 11357
c906108c 11358The @value{GDBN} command-completion facility can simplify this;
79a6e687 11359see @ref{Completion, ,Command Completion}.
c906108c 11360
c906108c
SS
11361@cindex reference declarations
11362@item
b37052ae
EZ
11363@value{GDBN} understands variables declared as C@t{++} references; you can use
11364them in expressions just as you do in C@t{++} source---they are automatically
c906108c
SS
11365dereferenced.
11366
11367In the parameter list shown when @value{GDBN} displays a frame, the values of
11368reference variables are not displayed (unlike other variables); this
11369avoids clutter, since references are often used for large structures.
11370The @emph{address} of a reference variable is always shown, unless
11371you have specified @samp{set print address off}.
11372
11373@item
b37052ae 11374@value{GDBN} supports the C@t{++} name resolution operator @code{::}---your
c906108c
SS
11375expressions can use it just as expressions in your program do. Since
11376one scope may be defined in another, you can use @code{::} repeatedly if
11377necessary, for example in an expression like
11378@samp{@var{scope1}::@var{scope2}::@var{name}}. @value{GDBN} also allows
b37052ae 11379resolving name scope by reference to source files, in both C and C@t{++}
79a6e687 11380debugging (@pxref{Variables, ,Program Variables}).
c906108c
SS
11381@end enumerate
11382
b37052ae 11383In addition, when used with HP's C@t{++} compiler, @value{GDBN} supports
53a5351d
JM
11384calling virtual functions correctly, printing out virtual bases of
11385objects, calling functions in a base subobject, casting objects, and
11386invoking user-defined operators.
c906108c 11387
6d2ebf8b 11388@node C Defaults
79a6e687 11389@subsubsection C and C@t{++} Defaults
7a292a7a 11390
b37052ae 11391@cindex C and C@t{++} defaults
c906108c 11392
c906108c
SS
11393If you allow @value{GDBN} to set type and range checking automatically, they
11394both default to @code{off} whenever the working language changes to
b37052ae 11395C or C@t{++}. This happens regardless of whether you or @value{GDBN}
c906108c 11396selects the working language.
c906108c
SS
11397
11398If you allow @value{GDBN} to set the language automatically, it
11399recognizes source files whose names end with @file{.c}, @file{.C}, or
11400@file{.cc}, etc, and when @value{GDBN} enters code compiled from one of
b37052ae 11401these files, it sets the working language to C or C@t{++}.
79a6e687 11402@xref{Automatically, ,Having @value{GDBN} Infer the Source Language},
c906108c
SS
11403for further details.
11404
c906108c
SS
11405@c Type checking is (a) primarily motivated by Modula-2, and (b)
11406@c unimplemented. If (b) changes, it might make sense to let this node
11407@c appear even if Mod-2 does not, but meanwhile ignore it. roland 16jul93.
7a292a7a 11408
6d2ebf8b 11409@node C Checks
79a6e687 11410@subsubsection C and C@t{++} Type and Range Checks
7a292a7a 11411
b37052ae 11412@cindex C and C@t{++} checks
c906108c 11413
b37052ae 11414By default, when @value{GDBN} parses C or C@t{++} expressions, type checking
c906108c
SS
11415is not used. However, if you turn type checking on, @value{GDBN}
11416considers two variables type equivalent if:
11417
11418@itemize @bullet
11419@item
11420The two variables are structured and have the same structure, union, or
11421enumerated tag.
11422
11423@item
11424The two variables have the same type name, or types that have been
11425declared equivalent through @code{typedef}.
11426
11427@ignore
11428@c leaving this out because neither J Gilmore nor R Pesch understand it.
11429@c FIXME--beers?
11430@item
11431The two @code{struct}, @code{union}, or @code{enum} variables are
11432declared in the same declaration. (Note: this may not be true for all C
11433compilers.)
11434@end ignore
11435@end itemize
11436
11437Range checking, if turned on, is done on mathematical operations. Array
11438indices are not checked, since they are often used to index a pointer
11439that is not itself an array.
c906108c 11440
6d2ebf8b 11441@node Debugging C
c906108c 11442@subsubsection @value{GDBN} and C
c906108c
SS
11443
11444The @code{set print union} and @code{show print union} commands apply to
11445the @code{union} type. When set to @samp{on}, any @code{union} that is
7a292a7a
SS
11446inside a @code{struct} or @code{class} is also printed. Otherwise, it
11447appears as @samp{@{...@}}.
c906108c
SS
11448
11449The @code{@@} operator aids in the debugging of dynamic arrays, formed
11450with pointers and a memory allocation function. @xref{Expressions,
11451,Expressions}.
11452
79a6e687
BW
11453@node Debugging C Plus Plus
11454@subsubsection @value{GDBN} Features for C@t{++}
c906108c 11455
b37052ae 11456@cindex commands for C@t{++}
7a292a7a 11457
b37052ae
EZ
11458Some @value{GDBN} commands are particularly useful with C@t{++}, and some are
11459designed specifically for use with C@t{++}. Here is a summary:
c906108c
SS
11460
11461@table @code
11462@cindex break in overloaded functions
11463@item @r{breakpoint menus}
11464When you want a breakpoint in a function whose name is overloaded,
6ba66d6a
JB
11465@value{GDBN} has the capability to display a menu of possible breakpoint
11466locations to help you specify which function definition you want.
11467@xref{Ambiguous Expressions,,Ambiguous Expressions}.
c906108c 11468
b37052ae 11469@cindex overloading in C@t{++}
c906108c
SS
11470@item rbreak @var{regex}
11471Setting breakpoints using regular expressions is helpful for setting
11472breakpoints on overloaded functions that are not members of any special
11473classes.
79a6e687 11474@xref{Set Breaks, ,Setting Breakpoints}.
c906108c 11475
b37052ae 11476@cindex C@t{++} exception handling
c906108c
SS
11477@item catch throw
11478@itemx catch catch
b37052ae 11479Debug C@t{++} exception handling using these commands. @xref{Set
79a6e687 11480Catchpoints, , Setting Catchpoints}.
c906108c
SS
11481
11482@cindex inheritance
11483@item ptype @var{typename}
11484Print inheritance relationships as well as other information for type
11485@var{typename}.
11486@xref{Symbols, ,Examining the Symbol Table}.
11487
b37052ae 11488@cindex C@t{++} symbol display
c906108c
SS
11489@item set print demangle
11490@itemx show print demangle
11491@itemx set print asm-demangle
11492@itemx show print asm-demangle
b37052ae
EZ
11493Control whether C@t{++} symbols display in their source form, both when
11494displaying code as C@t{++} source and when displaying disassemblies.
79a6e687 11495@xref{Print Settings, ,Print Settings}.
c906108c
SS
11496
11497@item set print object
11498@itemx show print object
11499Choose whether to print derived (actual) or declared types of objects.
79a6e687 11500@xref{Print Settings, ,Print Settings}.
c906108c
SS
11501
11502@item set print vtbl
11503@itemx show print vtbl
11504Control the format for printing virtual function tables.
79a6e687 11505@xref{Print Settings, ,Print Settings}.
c906108c 11506(The @code{vtbl} commands do not work on programs compiled with the HP
b37052ae 11507ANSI C@t{++} compiler (@code{aCC}).)
c906108c
SS
11508
11509@kindex set overload-resolution
d4f3574e 11510@cindex overloaded functions, overload resolution
c906108c 11511@item set overload-resolution on
b37052ae 11512Enable overload resolution for C@t{++} expression evaluation. The default
c906108c
SS
11513is on. For overloaded functions, @value{GDBN} evaluates the arguments
11514and searches for a function whose signature matches the argument types,
79a6e687
BW
11515using the standard C@t{++} conversion rules (see @ref{C Plus Plus
11516Expressions, ,C@t{++} Expressions}, for details).
11517If it cannot find a match, it emits a message.
c906108c
SS
11518
11519@item set overload-resolution off
b37052ae 11520Disable overload resolution for C@t{++} expression evaluation. For
c906108c
SS
11521overloaded functions that are not class member functions, @value{GDBN}
11522chooses the first function of the specified name that it finds in the
11523symbol table, whether or not its arguments are of the correct type. For
11524overloaded functions that are class member functions, @value{GDBN}
11525searches for a function whose signature @emph{exactly} matches the
11526argument types.
c906108c 11527
9c16f35a
EZ
11528@kindex show overload-resolution
11529@item show overload-resolution
11530Show the current setting of overload resolution.
11531
c906108c
SS
11532@item @r{Overloaded symbol names}
11533You can specify a particular definition of an overloaded symbol, using
b37052ae 11534the same notation that is used to declare such symbols in C@t{++}: type
c906108c
SS
11535@code{@var{symbol}(@var{types})} rather than just @var{symbol}. You can
11536also use the @value{GDBN} command-line word completion facilities to list the
11537available choices, or to finish the type list for you.
79a6e687 11538@xref{Completion,, Command Completion}, for details on how to do this.
c906108c 11539@end table
c906108c 11540
febe4383
TJB
11541@node Decimal Floating Point
11542@subsubsection Decimal Floating Point format
11543@cindex decimal floating point format
11544
11545@value{GDBN} can examine, set and perform computations with numbers in
11546decimal floating point format, which in the C language correspond to the
11547@code{_Decimal32}, @code{_Decimal64} and @code{_Decimal128} types as
11548specified by the extension to support decimal floating-point arithmetic.
11549
11550There are two encodings in use, depending on the architecture: BID (Binary
11551Integer Decimal) for x86 and x86-64, and DPD (Densely Packed Decimal) for
99e008fe 11552PowerPC. @value{GDBN} will use the appropriate encoding for the configured
febe4383
TJB
11553target.
11554
11555Because of a limitation in @file{libdecnumber}, the library used by @value{GDBN}
11556to manipulate decimal floating point numbers, it is not possible to convert
11557(using a cast, for example) integers wider than 32-bit to decimal float.
11558
11559In addition, in order to imitate @value{GDBN}'s behaviour with binary floating
11560point computations, error checking in decimal float operations ignores
11561underflow, overflow and divide by zero exceptions.
11562
4acd40f3 11563In the PowerPC architecture, @value{GDBN} provides a set of pseudo-registers
99e008fe
EZ
11564to inspect @code{_Decimal128} values stored in floating point registers.
11565See @ref{PowerPC,,PowerPC} for more details.
4acd40f3 11566
b37303ee
AF
11567@node Objective-C
11568@subsection Objective-C
11569
11570@cindex Objective-C
11571This section provides information about some commands and command
721c2651
EZ
11572options that are useful for debugging Objective-C code. See also
11573@ref{Symbols, info classes}, and @ref{Symbols, info selectors}, for a
11574few more commands specific to Objective-C support.
b37303ee
AF
11575
11576@menu
b383017d
RM
11577* Method Names in Commands::
11578* The Print Command with Objective-C::
b37303ee
AF
11579@end menu
11580
c8f4133a 11581@node Method Names in Commands
b37303ee
AF
11582@subsubsection Method Names in Commands
11583
11584The following commands have been extended to accept Objective-C method
11585names as line specifications:
11586
11587@kindex clear@r{, and Objective-C}
11588@kindex break@r{, and Objective-C}
11589@kindex info line@r{, and Objective-C}
11590@kindex jump@r{, and Objective-C}
11591@kindex list@r{, and Objective-C}
11592@itemize
11593@item @code{clear}
11594@item @code{break}
11595@item @code{info line}
11596@item @code{jump}
11597@item @code{list}
11598@end itemize
11599
11600A fully qualified Objective-C method name is specified as
11601
11602@smallexample
11603-[@var{Class} @var{methodName}]
11604@end smallexample
11605
c552b3bb
JM
11606where the minus sign is used to indicate an instance method and a
11607plus sign (not shown) is used to indicate a class method. The class
11608name @var{Class} and method name @var{methodName} are enclosed in
11609brackets, similar to the way messages are specified in Objective-C
11610source code. For example, to set a breakpoint at the @code{create}
11611instance method of class @code{Fruit} in the program currently being
11612debugged, enter:
b37303ee
AF
11613
11614@smallexample
11615break -[Fruit create]
11616@end smallexample
11617
11618To list ten program lines around the @code{initialize} class method,
11619enter:
11620
11621@smallexample
11622list +[NSText initialize]
11623@end smallexample
11624
c552b3bb
JM
11625In the current version of @value{GDBN}, the plus or minus sign is
11626required. In future versions of @value{GDBN}, the plus or minus
11627sign will be optional, but you can use it to narrow the search. It
11628is also possible to specify just a method name:
b37303ee
AF
11629
11630@smallexample
11631break create
11632@end smallexample
11633
11634You must specify the complete method name, including any colons. If
11635your program's source files contain more than one @code{create} method,
11636you'll be presented with a numbered list of classes that implement that
11637method. Indicate your choice by number, or type @samp{0} to exit if
11638none apply.
11639
11640As another example, to clear a breakpoint established at the
11641@code{makeKeyAndOrderFront:} method of the @code{NSWindow} class, enter:
11642
11643@smallexample
11644clear -[NSWindow makeKeyAndOrderFront:]
11645@end smallexample
11646
11647@node The Print Command with Objective-C
11648@subsubsection The Print Command With Objective-C
721c2651 11649@cindex Objective-C, print objects
c552b3bb
JM
11650@kindex print-object
11651@kindex po @r{(@code{print-object})}
b37303ee 11652
c552b3bb 11653The print command has also been extended to accept methods. For example:
b37303ee
AF
11654
11655@smallexample
c552b3bb 11656print -[@var{object} hash]
b37303ee
AF
11657@end smallexample
11658
11659@cindex print an Objective-C object description
c552b3bb
JM
11660@cindex @code{_NSPrintForDebugger}, and printing Objective-C objects
11661@noindent
11662will tell @value{GDBN} to send the @code{hash} message to @var{object}
11663and print the result. Also, an additional command has been added,
11664@code{print-object} or @code{po} for short, which is meant to print
11665the description of an object. However, this command may only work
11666with certain Objective-C libraries that have a particular hook
11667function, @code{_NSPrintForDebugger}, defined.
b37303ee 11668
09d4efe1
EZ
11669@node Fortran
11670@subsection Fortran
11671@cindex Fortran-specific support in @value{GDBN}
11672
814e32d7
WZ
11673@value{GDBN} can be used to debug programs written in Fortran, but it
11674currently supports only the features of Fortran 77 language.
11675
11676@cindex trailing underscore, in Fortran symbols
11677Some Fortran compilers (@sc{gnu} Fortran 77 and Fortran 95 compilers
11678among them) append an underscore to the names of variables and
11679functions. When you debug programs compiled by those compilers, you
11680will need to refer to variables and functions with a trailing
11681underscore.
11682
11683@menu
11684* Fortran Operators:: Fortran operators and expressions
11685* Fortran Defaults:: Default settings for Fortran
79a6e687 11686* Special Fortran Commands:: Special @value{GDBN} commands for Fortran
814e32d7
WZ
11687@end menu
11688
11689@node Fortran Operators
79a6e687 11690@subsubsection Fortran Operators and Expressions
814e32d7
WZ
11691
11692@cindex Fortran operators and expressions
11693
11694Operators must be defined on values of specific types. For instance,
11695@code{+} is defined on numbers, but not on characters or other non-
ff2587ec 11696arithmetic types. Operators are often defined on groups of types.
814e32d7
WZ
11697
11698@table @code
11699@item **
99e008fe 11700The exponentiation operator. It raises the first operand to the power
814e32d7
WZ
11701of the second one.
11702
11703@item :
11704The range operator. Normally used in the form of array(low:high) to
11705represent a section of array.
68837c9d
MD
11706
11707@item %
11708The access component operator. Normally used to access elements in derived
11709types. Also suitable for unions. As unions aren't part of regular Fortran,
11710this can only happen when accessing a register that uses a gdbarch-defined
11711union type.
814e32d7
WZ
11712@end table
11713
11714@node Fortran Defaults
11715@subsubsection Fortran Defaults
11716
11717@cindex Fortran Defaults
11718
11719Fortran symbols are usually case-insensitive, so @value{GDBN} by
11720default uses case-insensitive matches for Fortran symbols. You can
11721change that with the @samp{set case-insensitive} command, see
11722@ref{Symbols}, for the details.
11723
79a6e687
BW
11724@node Special Fortran Commands
11725@subsubsection Special Fortran Commands
814e32d7
WZ
11726
11727@cindex Special Fortran commands
11728
db2e3e2e
BW
11729@value{GDBN} has some commands to support Fortran-specific features,
11730such as displaying common blocks.
814e32d7 11731
09d4efe1
EZ
11732@table @code
11733@cindex @code{COMMON} blocks, Fortran
11734@kindex info common
11735@item info common @r{[}@var{common-name}@r{]}
11736This command prints the values contained in the Fortran @code{COMMON}
11737block whose name is @var{common-name}. With no argument, the names of
d52fb0e9 11738all @code{COMMON} blocks visible at the current program location are
09d4efe1
EZ
11739printed.
11740@end table
11741
9c16f35a
EZ
11742@node Pascal
11743@subsection Pascal
11744
11745@cindex Pascal support in @value{GDBN}, limitations
11746Debugging Pascal programs which use sets, subranges, file variables, or
11747nested functions does not currently work. @value{GDBN} does not support
11748entering expressions, printing values, or similar features using Pascal
11749syntax.
11750
11751The Pascal-specific command @code{set print pascal_static-members}
11752controls whether static members of Pascal objects are displayed.
11753@xref{Print Settings, pascal_static-members}.
11754
09d4efe1 11755@node Modula-2
c906108c 11756@subsection Modula-2
7a292a7a 11757
d4f3574e 11758@cindex Modula-2, @value{GDBN} support
c906108c
SS
11759
11760The extensions made to @value{GDBN} to support Modula-2 only support
11761output from the @sc{gnu} Modula-2 compiler (which is currently being
11762developed). Other Modula-2 compilers are not currently supported, and
11763attempting to debug executables produced by them is most likely
11764to give an error as @value{GDBN} reads in the executable's symbol
11765table.
11766
11767@cindex expressions in Modula-2
11768@menu
11769* M2 Operators:: Built-in operators
11770* Built-In Func/Proc:: Built-in functions and procedures
11771* M2 Constants:: Modula-2 constants
72019c9c 11772* M2 Types:: Modula-2 types
c906108c
SS
11773* M2 Defaults:: Default settings for Modula-2
11774* Deviations:: Deviations from standard Modula-2
11775* M2 Checks:: Modula-2 type and range checks
11776* M2 Scope:: The scope operators @code{::} and @code{.}
11777* GDB/M2:: @value{GDBN} and Modula-2
11778@end menu
11779
6d2ebf8b 11780@node M2 Operators
c906108c
SS
11781@subsubsection Operators
11782@cindex Modula-2 operators
11783
11784Operators must be defined on values of specific types. For instance,
11785@code{+} is defined on numbers, but not on structures. Operators are
11786often defined on groups of types. For the purposes of Modula-2, the
11787following definitions hold:
11788
11789@itemize @bullet
11790
11791@item
11792@emph{Integral types} consist of @code{INTEGER}, @code{CARDINAL}, and
11793their subranges.
11794
11795@item
11796@emph{Character types} consist of @code{CHAR} and its subranges.
11797
11798@item
11799@emph{Floating-point types} consist of @code{REAL}.
11800
11801@item
11802@emph{Pointer types} consist of anything declared as @code{POINTER TO
11803@var{type}}.
11804
11805@item
11806@emph{Scalar types} consist of all of the above.
11807
11808@item
11809@emph{Set types} consist of @code{SET} and @code{BITSET} types.
11810
11811@item
11812@emph{Boolean types} consist of @code{BOOLEAN}.
11813@end itemize
11814
11815@noindent
11816The following operators are supported, and appear in order of
11817increasing precedence:
11818
11819@table @code
11820@item ,
11821Function argument or array index separator.
11822
11823@item :=
11824Assignment. The value of @var{var} @code{:=} @var{value} is
11825@var{value}.
11826
11827@item <@r{, }>
11828Less than, greater than on integral, floating-point, or enumerated
11829types.
11830
11831@item <=@r{, }>=
96a2c332 11832Less than or equal to, greater than or equal to
c906108c
SS
11833on integral, floating-point and enumerated types, or set inclusion on
11834set types. Same precedence as @code{<}.
11835
11836@item =@r{, }<>@r{, }#
11837Equality and two ways of expressing inequality, valid on scalar types.
11838Same precedence as @code{<}. In @value{GDBN} scripts, only @code{<>} is
11839available for inequality, since @code{#} conflicts with the script
11840comment character.
11841
11842@item IN
11843Set membership. Defined on set types and the types of their members.
11844Same precedence as @code{<}.
11845
11846@item OR
11847Boolean disjunction. Defined on boolean types.
11848
11849@item AND@r{, }&
d4f3574e 11850Boolean conjunction. Defined on boolean types.
c906108c
SS
11851
11852@item @@
11853The @value{GDBN} ``artificial array'' operator (@pxref{Expressions, ,Expressions}).
11854
11855@item +@r{, }-
11856Addition and subtraction on integral and floating-point types, or union
11857and difference on set types.
11858
11859@item *
11860Multiplication on integral and floating-point types, or set intersection
11861on set types.
11862
11863@item /
11864Division on floating-point types, or symmetric set difference on set
11865types. Same precedence as @code{*}.
11866
11867@item DIV@r{, }MOD
11868Integer division and remainder. Defined on integral types. Same
11869precedence as @code{*}.
11870
11871@item -
99e008fe 11872Negative. Defined on @code{INTEGER} and @code{REAL} data.
c906108c
SS
11873
11874@item ^
11875Pointer dereferencing. Defined on pointer types.
11876
11877@item NOT
11878Boolean negation. Defined on boolean types. Same precedence as
11879@code{^}.
11880
11881@item .
11882@code{RECORD} field selector. Defined on @code{RECORD} data. Same
11883precedence as @code{^}.
11884
11885@item []
11886Array indexing. Defined on @code{ARRAY} data. Same precedence as @code{^}.
11887
11888@item ()
11889Procedure argument list. Defined on @code{PROCEDURE} objects. Same precedence
11890as @code{^}.
11891
11892@item ::@r{, }.
11893@value{GDBN} and Modula-2 scope operators.
11894@end table
11895
11896@quotation
72019c9c 11897@emph{Warning:} Set expressions and their operations are not yet supported, so @value{GDBN}
c906108c
SS
11898treats the use of the operator @code{IN}, or the use of operators
11899@code{+}, @code{-}, @code{*}, @code{/}, @code{=}, , @code{<>}, @code{#},
11900@code{<=}, and @code{>=} on sets as an error.
11901@end quotation
11902
cb51c4e0 11903
6d2ebf8b 11904@node Built-In Func/Proc
79a6e687 11905@subsubsection Built-in Functions and Procedures
cb51c4e0 11906@cindex Modula-2 built-ins
c906108c
SS
11907
11908Modula-2 also makes available several built-in procedures and functions.
11909In describing these, the following metavariables are used:
11910
11911@table @var
11912
11913@item a
11914represents an @code{ARRAY} variable.
11915
11916@item c
11917represents a @code{CHAR} constant or variable.
11918
11919@item i
11920represents a variable or constant of integral type.
11921
11922@item m
11923represents an identifier that belongs to a set. Generally used in the
11924same function with the metavariable @var{s}. The type of @var{s} should
11925be @code{SET OF @var{mtype}} (where @var{mtype} is the type of @var{m}).
11926
11927@item n
11928represents a variable or constant of integral or floating-point type.
11929
11930@item r
11931represents a variable or constant of floating-point type.
11932
11933@item t
11934represents a type.
11935
11936@item v
11937represents a variable.
11938
11939@item x
11940represents a variable or constant of one of many types. See the
11941explanation of the function for details.
11942@end table
11943
11944All Modula-2 built-in procedures also return a result, described below.
11945
11946@table @code
11947@item ABS(@var{n})
11948Returns the absolute value of @var{n}.
11949
11950@item CAP(@var{c})
11951If @var{c} is a lower case letter, it returns its upper case
c3f6f71d 11952equivalent, otherwise it returns its argument.
c906108c
SS
11953
11954@item CHR(@var{i})
11955Returns the character whose ordinal value is @var{i}.
11956
11957@item DEC(@var{v})
c3f6f71d 11958Decrements the value in the variable @var{v} by one. Returns the new value.
c906108c
SS
11959
11960@item DEC(@var{v},@var{i})
11961Decrements the value in the variable @var{v} by @var{i}. Returns the
11962new value.
11963
11964@item EXCL(@var{m},@var{s})
11965Removes the element @var{m} from the set @var{s}. Returns the new
11966set.
11967
11968@item FLOAT(@var{i})
11969Returns the floating point equivalent of the integer @var{i}.
11970
11971@item HIGH(@var{a})
11972Returns the index of the last member of @var{a}.
11973
11974@item INC(@var{v})
c3f6f71d 11975Increments the value in the variable @var{v} by one. Returns the new value.
c906108c
SS
11976
11977@item INC(@var{v},@var{i})
11978Increments the value in the variable @var{v} by @var{i}. Returns the
11979new value.
11980
11981@item INCL(@var{m},@var{s})
11982Adds the element @var{m} to the set @var{s} if it is not already
11983there. Returns the new set.
11984
11985@item MAX(@var{t})
11986Returns the maximum value of the type @var{t}.
11987
11988@item MIN(@var{t})
11989Returns the minimum value of the type @var{t}.
11990
11991@item ODD(@var{i})
11992Returns boolean TRUE if @var{i} is an odd number.
11993
11994@item ORD(@var{x})
11995Returns the ordinal value of its argument. For example, the ordinal
c3f6f71d
JM
11996value of a character is its @sc{ascii} value (on machines supporting the
11997@sc{ascii} character set). @var{x} must be of an ordered type, which include
c906108c
SS
11998integral, character and enumerated types.
11999
12000@item SIZE(@var{x})
12001Returns the size of its argument. @var{x} can be a variable or a type.
12002
12003@item TRUNC(@var{r})
12004Returns the integral part of @var{r}.
12005
844781a1
GM
12006@item TSIZE(@var{x})
12007Returns the size of its argument. @var{x} can be a variable or a type.
12008
c906108c
SS
12009@item VAL(@var{t},@var{i})
12010Returns the member of the type @var{t} whose ordinal value is @var{i}.
12011@end table
12012
12013@quotation
12014@emph{Warning:} Sets and their operations are not yet supported, so
12015@value{GDBN} treats the use of procedures @code{INCL} and @code{EXCL} as
12016an error.
12017@end quotation
12018
12019@cindex Modula-2 constants
6d2ebf8b 12020@node M2 Constants
c906108c
SS
12021@subsubsection Constants
12022
12023@value{GDBN} allows you to express the constants of Modula-2 in the following
12024ways:
12025
12026@itemize @bullet
12027
12028@item
12029Integer constants are simply a sequence of digits. When used in an
12030expression, a constant is interpreted to be type-compatible with the
12031rest of the expression. Hexadecimal integers are specified by a
12032trailing @samp{H}, and octal integers by a trailing @samp{B}.
12033
12034@item
12035Floating point constants appear as a sequence of digits, followed by a
12036decimal point and another sequence of digits. An optional exponent can
12037then be specified, in the form @samp{E@r{[}+@r{|}-@r{]}@var{nnn}}, where
12038@samp{@r{[}+@r{|}-@r{]}@var{nnn}} is the desired exponent. All of the
12039digits of the floating point constant must be valid decimal (base 10)
12040digits.
12041
12042@item
12043Character constants consist of a single character enclosed by a pair of
12044like quotes, either single (@code{'}) or double (@code{"}). They may
c3f6f71d 12045also be expressed by their ordinal value (their @sc{ascii} value, usually)
c906108c
SS
12046followed by a @samp{C}.
12047
12048@item
12049String constants consist of a sequence of characters enclosed by a
12050pair of like quotes, either single (@code{'}) or double (@code{"}).
12051Escape sequences in the style of C are also allowed. @xref{C
79a6e687 12052Constants, ,C and C@t{++} Constants}, for a brief explanation of escape
c906108c
SS
12053sequences.
12054
12055@item
12056Enumerated constants consist of an enumerated identifier.
12057
12058@item
12059Boolean constants consist of the identifiers @code{TRUE} and
12060@code{FALSE}.
12061
12062@item
12063Pointer constants consist of integral values only.
12064
12065@item
12066Set constants are not yet supported.
12067@end itemize
12068
72019c9c
GM
12069@node M2 Types
12070@subsubsection Modula-2 Types
12071@cindex Modula-2 types
12072
12073Currently @value{GDBN} can print the following data types in Modula-2
12074syntax: array types, record types, set types, pointer types, procedure
12075types, enumerated types, subrange types and base types. You can also
12076print the contents of variables declared using these type.
12077This section gives a number of simple source code examples together with
12078sample @value{GDBN} sessions.
12079
12080The first example contains the following section of code:
12081
12082@smallexample
12083VAR
12084 s: SET OF CHAR ;
12085 r: [20..40] ;
12086@end smallexample
12087
12088@noindent
12089and you can request @value{GDBN} to interrogate the type and value of
12090@code{r} and @code{s}.
12091
12092@smallexample
12093(@value{GDBP}) print s
12094@{'A'..'C', 'Z'@}
12095(@value{GDBP}) ptype s
12096SET OF CHAR
12097(@value{GDBP}) print r
1209821
12099(@value{GDBP}) ptype r
12100[20..40]
12101@end smallexample
12102
12103@noindent
12104Likewise if your source code declares @code{s} as:
12105
12106@smallexample
12107VAR
12108 s: SET ['A'..'Z'] ;
12109@end smallexample
12110
12111@noindent
12112then you may query the type of @code{s} by:
12113
12114@smallexample
12115(@value{GDBP}) ptype s
12116type = SET ['A'..'Z']
12117@end smallexample
12118
12119@noindent
12120Note that at present you cannot interactively manipulate set
12121expressions using the debugger.
12122
12123The following example shows how you might declare an array in Modula-2
12124and how you can interact with @value{GDBN} to print its type and contents:
12125
12126@smallexample
12127VAR
12128 s: ARRAY [-10..10] OF CHAR ;
12129@end smallexample
12130
12131@smallexample
12132(@value{GDBP}) ptype s
12133ARRAY [-10..10] OF CHAR
12134@end smallexample
12135
12136Note that the array handling is not yet complete and although the type
12137is printed correctly, expression handling still assumes that all
12138arrays have a lower bound of zero and not @code{-10} as in the example
844781a1 12139above.
72019c9c
GM
12140
12141Here are some more type related Modula-2 examples:
12142
12143@smallexample
12144TYPE
12145 colour = (blue, red, yellow, green) ;
12146 t = [blue..yellow] ;
12147VAR
12148 s: t ;
12149BEGIN
12150 s := blue ;
12151@end smallexample
12152
12153@noindent
12154The @value{GDBN} interaction shows how you can query the data type
12155and value of a variable.
12156
12157@smallexample
12158(@value{GDBP}) print s
12159$1 = blue
12160(@value{GDBP}) ptype t
12161type = [blue..yellow]
12162@end smallexample
12163
12164@noindent
12165In this example a Modula-2 array is declared and its contents
12166displayed. Observe that the contents are written in the same way as
12167their @code{C} counterparts.
12168
12169@smallexample
12170VAR
12171 s: ARRAY [1..5] OF CARDINAL ;
12172BEGIN
12173 s[1] := 1 ;
12174@end smallexample
12175
12176@smallexample
12177(@value{GDBP}) print s
12178$1 = @{1, 0, 0, 0, 0@}
12179(@value{GDBP}) ptype s
12180type = ARRAY [1..5] OF CARDINAL
12181@end smallexample
12182
12183The Modula-2 language interface to @value{GDBN} also understands
12184pointer types as shown in this example:
12185
12186@smallexample
12187VAR
12188 s: POINTER TO ARRAY [1..5] OF CARDINAL ;
12189BEGIN
12190 NEW(s) ;
12191 s^[1] := 1 ;
12192@end smallexample
12193
12194@noindent
12195and you can request that @value{GDBN} describes the type of @code{s}.
12196
12197@smallexample
12198(@value{GDBP}) ptype s
12199type = POINTER TO ARRAY [1..5] OF CARDINAL
12200@end smallexample
12201
12202@value{GDBN} handles compound types as we can see in this example.
12203Here we combine array types, record types, pointer types and subrange
12204types:
12205
12206@smallexample
12207TYPE
12208 foo = RECORD
12209 f1: CARDINAL ;
12210 f2: CHAR ;
12211 f3: myarray ;
12212 END ;
12213
12214 myarray = ARRAY myrange OF CARDINAL ;
12215 myrange = [-2..2] ;
12216VAR
12217 s: POINTER TO ARRAY myrange OF foo ;
12218@end smallexample
12219
12220@noindent
12221and you can ask @value{GDBN} to describe the type of @code{s} as shown
12222below.
12223
12224@smallexample
12225(@value{GDBP}) ptype s
12226type = POINTER TO ARRAY [-2..2] OF foo = RECORD
12227 f1 : CARDINAL;
12228 f2 : CHAR;
12229 f3 : ARRAY [-2..2] OF CARDINAL;
12230END
12231@end smallexample
12232
6d2ebf8b 12233@node M2 Defaults
79a6e687 12234@subsubsection Modula-2 Defaults
c906108c
SS
12235@cindex Modula-2 defaults
12236
12237If type and range checking are set automatically by @value{GDBN}, they
12238both default to @code{on} whenever the working language changes to
d4f3574e 12239Modula-2. This happens regardless of whether you or @value{GDBN}
c906108c
SS
12240selected the working language.
12241
12242If you allow @value{GDBN} to set the language automatically, then entering
12243code compiled from a file whose name ends with @file{.mod} sets the
79a6e687
BW
12244working language to Modula-2. @xref{Automatically, ,Having @value{GDBN}
12245Infer the Source Language}, for further details.
c906108c 12246
6d2ebf8b 12247@node Deviations
79a6e687 12248@subsubsection Deviations from Standard Modula-2
c906108c
SS
12249@cindex Modula-2, deviations from
12250
12251A few changes have been made to make Modula-2 programs easier to debug.
12252This is done primarily via loosening its type strictness:
12253
12254@itemize @bullet
12255@item
12256Unlike in standard Modula-2, pointer constants can be formed by
12257integers. This allows you to modify pointer variables during
12258debugging. (In standard Modula-2, the actual address contained in a
12259pointer variable is hidden from you; it can only be modified
12260through direct assignment to another pointer variable or expression that
12261returned a pointer.)
12262
12263@item
12264C escape sequences can be used in strings and characters to represent
12265non-printable characters. @value{GDBN} prints out strings with these
12266escape sequences embedded. Single non-printable characters are
12267printed using the @samp{CHR(@var{nnn})} format.
12268
12269@item
12270The assignment operator (@code{:=}) returns the value of its right-hand
12271argument.
12272
12273@item
12274All built-in procedures both modify @emph{and} return their argument.
12275@end itemize
12276
6d2ebf8b 12277@node M2 Checks
79a6e687 12278@subsubsection Modula-2 Type and Range Checks
c906108c
SS
12279@cindex Modula-2 checks
12280
12281@quotation
12282@emph{Warning:} in this release, @value{GDBN} does not yet perform type or
12283range checking.
12284@end quotation
12285@c FIXME remove warning when type/range checks added
12286
12287@value{GDBN} considers two Modula-2 variables type equivalent if:
12288
12289@itemize @bullet
12290@item
12291They are of types that have been declared equivalent via a @code{TYPE
12292@var{t1} = @var{t2}} statement
12293
12294@item
12295They have been declared on the same line. (Note: This is true of the
12296@sc{gnu} Modula-2 compiler, but it may not be true of other compilers.)
12297@end itemize
12298
12299As long as type checking is enabled, any attempt to combine variables
12300whose types are not equivalent is an error.
12301
12302Range checking is done on all mathematical operations, assignment, array
12303index bounds, and all built-in functions and procedures.
12304
6d2ebf8b 12305@node M2 Scope
79a6e687 12306@subsubsection The Scope Operators @code{::} and @code{.}
c906108c 12307@cindex scope
41afff9a 12308@cindex @code{.}, Modula-2 scope operator
c906108c
SS
12309@cindex colon, doubled as scope operator
12310@ifinfo
41afff9a 12311@vindex colon-colon@r{, in Modula-2}
c906108c
SS
12312@c Info cannot handle :: but TeX can.
12313@end ifinfo
a67ec3f4 12314@ifnotinfo
41afff9a 12315@vindex ::@r{, in Modula-2}
a67ec3f4 12316@end ifnotinfo
c906108c
SS
12317
12318There are a few subtle differences between the Modula-2 scope operator
12319(@code{.}) and the @value{GDBN} scope operator (@code{::}). The two have
12320similar syntax:
12321
474c8240 12322@smallexample
c906108c
SS
12323
12324@var{module} . @var{id}
12325@var{scope} :: @var{id}
474c8240 12326@end smallexample
c906108c
SS
12327
12328@noindent
12329where @var{scope} is the name of a module or a procedure,
12330@var{module} the name of a module, and @var{id} is any declared
12331identifier within your program, except another module.
12332
12333Using the @code{::} operator makes @value{GDBN} search the scope
12334specified by @var{scope} for the identifier @var{id}. If it is not
12335found in the specified scope, then @value{GDBN} searches all scopes
12336enclosing the one specified by @var{scope}.
12337
12338Using the @code{.} operator makes @value{GDBN} search the current scope for
12339the identifier specified by @var{id} that was imported from the
12340definition module specified by @var{module}. With this operator, it is
12341an error if the identifier @var{id} was not imported from definition
12342module @var{module}, or if @var{id} is not an identifier in
12343@var{module}.
12344
6d2ebf8b 12345@node GDB/M2
c906108c
SS
12346@subsubsection @value{GDBN} and Modula-2
12347
12348Some @value{GDBN} commands have little use when debugging Modula-2 programs.
12349Five subcommands of @code{set print} and @code{show print} apply
b37052ae 12350specifically to C and C@t{++}: @samp{vtbl}, @samp{demangle},
c906108c 12351@samp{asm-demangle}, @samp{object}, and @samp{union}. The first four
b37052ae 12352apply to C@t{++}, and the last to the C @code{union} type, which has no direct
c906108c
SS
12353analogue in Modula-2.
12354
12355The @code{@@} operator (@pxref{Expressions, ,Expressions}), while available
d4f3574e 12356with any language, is not useful with Modula-2. Its
c906108c 12357intent is to aid the debugging of @dfn{dynamic arrays}, which cannot be
b37052ae 12358created in Modula-2 as they can in C or C@t{++}. However, because an
c906108c 12359address can be specified by an integral constant, the construct
d4f3574e 12360@samp{@{@var{type}@}@var{adrexp}} is still useful.
c906108c
SS
12361
12362@cindex @code{#} in Modula-2
12363In @value{GDBN} scripts, the Modula-2 inequality operator @code{#} is
12364interpreted as the beginning of a comment. Use @code{<>} instead.
c906108c 12365
e07c999f
PH
12366@node Ada
12367@subsection Ada
12368@cindex Ada
12369
12370The extensions made to @value{GDBN} for Ada only support
12371output from the @sc{gnu} Ada (GNAT) compiler.
12372Other Ada compilers are not currently supported, and
12373attempting to debug executables produced by them is most likely
12374to be difficult.
12375
12376
12377@cindex expressions in Ada
12378@menu
12379* Ada Mode Intro:: General remarks on the Ada syntax
12380 and semantics supported by Ada mode
12381 in @value{GDBN}.
12382* Omissions from Ada:: Restrictions on the Ada expression syntax.
12383* Additions to Ada:: Extensions of the Ada expression syntax.
12384* Stopping Before Main Program:: Debugging the program during elaboration.
20924a55
JB
12385* Ada Tasks:: Listing and setting breakpoints in tasks.
12386* Ada Tasks and Core Files:: Tasking Support when Debugging Core Files
e07c999f
PH
12387* Ada Glitches:: Known peculiarities of Ada mode.
12388@end menu
12389
12390@node Ada Mode Intro
12391@subsubsection Introduction
12392@cindex Ada mode, general
12393
12394The Ada mode of @value{GDBN} supports a fairly large subset of Ada expression
12395syntax, with some extensions.
12396The philosophy behind the design of this subset is
12397
12398@itemize @bullet
12399@item
12400That @value{GDBN} should provide basic literals and access to operations for
12401arithmetic, dereferencing, field selection, indexing, and subprogram calls,
12402leaving more sophisticated computations to subprograms written into the
12403program (which therefore may be called from @value{GDBN}).
12404
12405@item
12406That type safety and strict adherence to Ada language restrictions
12407are not particularly important to the @value{GDBN} user.
12408
12409@item
12410That brevity is important to the @value{GDBN} user.
12411@end itemize
12412
f3a2dd1a
JB
12413Thus, for brevity, the debugger acts as if all names declared in
12414user-written packages are directly visible, even if they are not visible
12415according to Ada rules, thus making it unnecessary to fully qualify most
12416names with their packages, regardless of context. Where this causes
12417ambiguity, @value{GDBN} asks the user's intent.
e07c999f
PH
12418
12419The debugger will start in Ada mode if it detects an Ada main program.
12420As for other languages, it will enter Ada mode when stopped in a program that
12421was translated from an Ada source file.
12422
12423While in Ada mode, you may use `@t{--}' for comments. This is useful
12424mostly for documenting command files. The standard @value{GDBN} comment
12425(@samp{#}) still works at the beginning of a line in Ada mode, but not in the
12426middle (to allow based literals).
12427
12428The debugger supports limited overloading. Given a subprogram call in which
12429the function symbol has multiple definitions, it will use the number of
12430actual parameters and some information about their types to attempt to narrow
12431the set of definitions. It also makes very limited use of context, preferring
12432procedures to functions in the context of the @code{call} command, and
12433functions to procedures elsewhere.
12434
12435@node Omissions from Ada
12436@subsubsection Omissions from Ada
12437@cindex Ada, omissions from
12438
12439Here are the notable omissions from the subset:
12440
12441@itemize @bullet
12442@item
12443Only a subset of the attributes are supported:
12444
12445@itemize @minus
12446@item
12447@t{'First}, @t{'Last}, and @t{'Length}
12448 on array objects (not on types and subtypes).
12449
12450@item
12451@t{'Min} and @t{'Max}.
12452
12453@item
12454@t{'Pos} and @t{'Val}.
12455
12456@item
12457@t{'Tag}.
12458
12459@item
12460@t{'Range} on array objects (not subtypes), but only as the right
12461operand of the membership (@code{in}) operator.
12462
12463@item
12464@t{'Access}, @t{'Unchecked_Access}, and
12465@t{'Unrestricted_Access} (a GNAT extension).
12466
12467@item
12468@t{'Address}.
12469@end itemize
12470
12471@item
12472The names in
12473@code{Characters.Latin_1} are not available and
12474concatenation is not implemented. Thus, escape characters in strings are
12475not currently available.
12476
12477@item
12478Equality tests (@samp{=} and @samp{/=}) on arrays test for bitwise
12479equality of representations. They will generally work correctly
12480for strings and arrays whose elements have integer or enumeration types.
12481They may not work correctly for arrays whose element
12482types have user-defined equality, for arrays of real values
12483(in particular, IEEE-conformant floating point, because of negative
12484zeroes and NaNs), and for arrays whose elements contain unused bits with
12485indeterminate values.
12486
12487@item
12488The other component-by-component array operations (@code{and}, @code{or},
12489@code{xor}, @code{not}, and relational tests other than equality)
12490are not implemented.
12491
12492@item
860701dc
PH
12493@cindex array aggregates (Ada)
12494@cindex record aggregates (Ada)
12495@cindex aggregates (Ada)
12496There is limited support for array and record aggregates. They are
12497permitted only on the right sides of assignments, as in these examples:
12498
12499@smallexample
077e0a52
JB
12500(@value{GDBP}) set An_Array := (1, 2, 3, 4, 5, 6)
12501(@value{GDBP}) set An_Array := (1, others => 0)
12502(@value{GDBP}) set An_Array := (0|4 => 1, 1..3 => 2, 5 => 6)
12503(@value{GDBP}) set A_2D_Array := ((1, 2, 3), (4, 5, 6), (7, 8, 9))
12504(@value{GDBP}) set A_Record := (1, "Peter", True);
12505(@value{GDBP}) set A_Record := (Name => "Peter", Id => 1, Alive => True)
860701dc
PH
12506@end smallexample
12507
12508Changing a
12509discriminant's value by assigning an aggregate has an
12510undefined effect if that discriminant is used within the record.
12511However, you can first modify discriminants by directly assigning to
12512them (which normally would not be allowed in Ada), and then performing an
12513aggregate assignment. For example, given a variable @code{A_Rec}
12514declared to have a type such as:
12515
12516@smallexample
12517type Rec (Len : Small_Integer := 0) is record
12518 Id : Integer;
12519 Vals : IntArray (1 .. Len);
12520end record;
12521@end smallexample
12522
12523you can assign a value with a different size of @code{Vals} with two
12524assignments:
12525
12526@smallexample
077e0a52
JB
12527(@value{GDBP}) set A_Rec.Len := 4
12528(@value{GDBP}) set A_Rec := (Id => 42, Vals => (1, 2, 3, 4))
860701dc
PH
12529@end smallexample
12530
12531As this example also illustrates, @value{GDBN} is very loose about the usual
12532rules concerning aggregates. You may leave out some of the
12533components of an array or record aggregate (such as the @code{Len}
12534component in the assignment to @code{A_Rec} above); they will retain their
12535original values upon assignment. You may freely use dynamic values as
12536indices in component associations. You may even use overlapping or
12537redundant component associations, although which component values are
12538assigned in such cases is not defined.
e07c999f
PH
12539
12540@item
12541Calls to dispatching subprograms are not implemented.
12542
12543@item
12544The overloading algorithm is much more limited (i.e., less selective)
ae21e955
BW
12545than that of real Ada. It makes only limited use of the context in
12546which a subexpression appears to resolve its meaning, and it is much
12547looser in its rules for allowing type matches. As a result, some
12548function calls will be ambiguous, and the user will be asked to choose
12549the proper resolution.
e07c999f
PH
12550
12551@item
12552The @code{new} operator is not implemented.
12553
12554@item
12555Entry calls are not implemented.
12556
12557@item
12558Aside from printing, arithmetic operations on the native VAX floating-point
12559formats are not supported.
12560
12561@item
12562It is not possible to slice a packed array.
158c7665
PH
12563
12564@item
12565The names @code{True} and @code{False}, when not part of a qualified name,
12566are interpreted as if implicitly prefixed by @code{Standard}, regardless of
12567context.
12568Should your program
12569redefine these names in a package or procedure (at best a dubious practice),
12570you will have to use fully qualified names to access their new definitions.
e07c999f
PH
12571@end itemize
12572
12573@node Additions to Ada
12574@subsubsection Additions to Ada
12575@cindex Ada, deviations from
12576
12577As it does for other languages, @value{GDBN} makes certain generic
12578extensions to Ada (@pxref{Expressions}):
12579
12580@itemize @bullet
12581@item
ae21e955
BW
12582If the expression @var{E} is a variable residing in memory (typically
12583a local variable or array element) and @var{N} is a positive integer,
12584then @code{@var{E}@@@var{N}} displays the values of @var{E} and the
12585@var{N}-1 adjacent variables following it in memory as an array. In
12586Ada, this operator is generally not necessary, since its prime use is
12587in displaying parts of an array, and slicing will usually do this in
12588Ada. However, there are occasional uses when debugging programs in
12589which certain debugging information has been optimized away.
e07c999f
PH
12590
12591@item
ae21e955
BW
12592@code{@var{B}::@var{var}} means ``the variable named @var{var} that
12593appears in function or file @var{B}.'' When @var{B} is a file name,
12594you must typically surround it in single quotes.
e07c999f
PH
12595
12596@item
12597The expression @code{@{@var{type}@} @var{addr}} means ``the variable of type
12598@var{type} that appears at address @var{addr}.''
12599
12600@item
12601A name starting with @samp{$} is a convenience variable
12602(@pxref{Convenience Vars}) or a machine register (@pxref{Registers}).
12603@end itemize
12604
ae21e955
BW
12605In addition, @value{GDBN} provides a few other shortcuts and outright
12606additions specific to Ada:
e07c999f
PH
12607
12608@itemize @bullet
12609@item
12610The assignment statement is allowed as an expression, returning
12611its right-hand operand as its value. Thus, you may enter
12612
12613@smallexample
077e0a52
JB
12614(@value{GDBP}) set x := y + 3
12615(@value{GDBP}) print A(tmp := y + 1)
e07c999f
PH
12616@end smallexample
12617
12618@item
12619The semicolon is allowed as an ``operator,'' returning as its value
12620the value of its right-hand operand.
12621This allows, for example,
12622complex conditional breaks:
12623
12624@smallexample
077e0a52
JB
12625(@value{GDBP}) break f
12626(@value{GDBP}) condition 1 (report(i); k += 1; A(k) > 100)
e07c999f
PH
12627@end smallexample
12628
12629@item
12630Rather than use catenation and symbolic character names to introduce special
12631characters into strings, one may instead use a special bracket notation,
12632which is also used to print strings. A sequence of characters of the form
12633@samp{["@var{XX}"]} within a string or character literal denotes the
12634(single) character whose numeric encoding is @var{XX} in hexadecimal. The
12635sequence of characters @samp{["""]} also denotes a single quotation mark
12636in strings. For example,
12637@smallexample
12638 "One line.["0a"]Next line.["0a"]"
12639@end smallexample
12640@noindent
ae21e955
BW
12641contains an ASCII newline character (@code{Ada.Characters.Latin_1.LF})
12642after each period.
e07c999f
PH
12643
12644@item
12645The subtype used as a prefix for the attributes @t{'Pos}, @t{'Min}, and
12646@t{'Max} is optional (and is ignored in any case). For example, it is valid
12647to write
12648
12649@smallexample
077e0a52 12650(@value{GDBP}) print 'max(x, y)
e07c999f
PH
12651@end smallexample
12652
12653@item
12654When printing arrays, @value{GDBN} uses positional notation when the
12655array has a lower bound of 1, and uses a modified named notation otherwise.
ae21e955
BW
12656For example, a one-dimensional array of three integers with a lower bound
12657of 3 might print as
e07c999f
PH
12658
12659@smallexample
12660(3 => 10, 17, 1)
12661@end smallexample
12662
12663@noindent
12664That is, in contrast to valid Ada, only the first component has a @code{=>}
12665clause.
12666
12667@item
12668You may abbreviate attributes in expressions with any unique,
12669multi-character subsequence of
12670their names (an exact match gets preference).
12671For example, you may use @t{a'len}, @t{a'gth}, or @t{a'lh}
12672in place of @t{a'length}.
12673
12674@item
12675@cindex quoting Ada internal identifiers
12676Since Ada is case-insensitive, the debugger normally maps identifiers you type
12677to lower case. The GNAT compiler uses upper-case characters for
12678some of its internal identifiers, which are normally of no interest to users.
12679For the rare occasions when you actually have to look at them,
12680enclose them in angle brackets to avoid the lower-case mapping.
12681For example,
12682@smallexample
077e0a52 12683(@value{GDBP}) print <JMPBUF_SAVE>[0]
e07c999f
PH
12684@end smallexample
12685
12686@item
12687Printing an object of class-wide type or dereferencing an
12688access-to-class-wide value will display all the components of the object's
12689specific type (as indicated by its run-time tag). Likewise, component
12690selection on such a value will operate on the specific type of the
12691object.
12692
12693@end itemize
12694
12695@node Stopping Before Main Program
12696@subsubsection Stopping at the Very Beginning
12697
12698@cindex breakpointing Ada elaboration code
12699It is sometimes necessary to debug the program during elaboration, and
12700before reaching the main procedure.
12701As defined in the Ada Reference
12702Manual, the elaboration code is invoked from a procedure called
12703@code{adainit}. To run your program up to the beginning of
12704elaboration, simply use the following two commands:
12705@code{tbreak adainit} and @code{run}.
12706
20924a55
JB
12707@node Ada Tasks
12708@subsubsection Extensions for Ada Tasks
12709@cindex Ada, tasking
12710
12711Support for Ada tasks is analogous to that for threads (@pxref{Threads}).
12712@value{GDBN} provides the following task-related commands:
12713
12714@table @code
12715@kindex info tasks
12716@item info tasks
12717This command shows a list of current Ada tasks, as in the following example:
12718
12719
12720@smallexample
12721@iftex
12722@leftskip=0.5cm
12723@end iftex
12724(@value{GDBP}) info tasks
12725 ID TID P-ID Pri State Name
12726 1 8088000 0 15 Child Activation Wait main_task
12727 2 80a4000 1 15 Accept Statement b
12728 3 809a800 1 15 Child Activation Wait a
32cd1edc 12729* 4 80ae800 3 15 Runnable c
20924a55
JB
12730
12731@end smallexample
12732
12733@noindent
12734In this listing, the asterisk before the last task indicates it to be the
12735task currently being inspected.
12736
12737@table @asis
12738@item ID
12739Represents @value{GDBN}'s internal task number.
12740
12741@item TID
12742The Ada task ID.
12743
12744@item P-ID
12745The parent's task ID (@value{GDBN}'s internal task number).
12746
12747@item Pri
12748The base priority of the task.
12749
12750@item State
12751Current state of the task.
12752
12753@table @code
12754@item Unactivated
12755The task has been created but has not been activated. It cannot be
12756executing.
12757
20924a55
JB
12758@item Runnable
12759The task is not blocked for any reason known to Ada. (It may be waiting
12760for a mutex, though.) It is conceptually "executing" in normal mode.
12761
12762@item Terminated
12763The task is terminated, in the sense of ARM 9.3 (5). Any dependents
12764that were waiting on terminate alternatives have been awakened and have
12765terminated themselves.
12766
12767@item Child Activation Wait
12768The task is waiting for created tasks to complete activation.
12769
12770@item Accept Statement
12771The task is waiting on an accept or selective wait statement.
12772
12773@item Waiting on entry call
12774The task is waiting on an entry call.
12775
12776@item Async Select Wait
12777The task is waiting to start the abortable part of an asynchronous
12778select statement.
12779
12780@item Delay Sleep
12781The task is waiting on a select statement with only a delay
12782alternative open.
12783
12784@item Child Termination Wait
12785The task is sleeping having completed a master within itself, and is
12786waiting for the tasks dependent on that master to become terminated or
12787waiting on a terminate Phase.
12788
12789@item Wait Child in Term Alt
12790The task is sleeping waiting for tasks on terminate alternatives to
12791finish terminating.
12792
12793@item Accepting RV with @var{taskno}
12794The task is accepting a rendez-vous with the task @var{taskno}.
12795@end table
12796
12797@item Name
12798Name of the task in the program.
12799
12800@end table
12801
12802@kindex info task @var{taskno}
12803@item info task @var{taskno}
12804This command shows detailled informations on the specified task, as in
12805the following example:
12806@smallexample
12807@iftex
12808@leftskip=0.5cm
12809@end iftex
12810(@value{GDBP}) info tasks
12811 ID TID P-ID Pri State Name
12812 1 8077880 0 15 Child Activation Wait main_task
32cd1edc 12813* 2 807c468 1 15 Runnable task_1
20924a55
JB
12814(@value{GDBP}) info task 2
12815Ada Task: 0x807c468
12816Name: task_1
12817Thread: 0x807f378
12818Parent: 1 (main_task)
12819Base Priority: 15
12820State: Runnable
12821@end smallexample
12822
12823@item task
12824@kindex task@r{ (Ada)}
12825@cindex current Ada task ID
12826This command prints the ID of the current task.
12827
12828@smallexample
12829@iftex
12830@leftskip=0.5cm
12831@end iftex
12832(@value{GDBP}) info tasks
12833 ID TID P-ID Pri State Name
12834 1 8077870 0 15 Child Activation Wait main_task
32cd1edc 12835* 2 807c458 1 15 Runnable t
20924a55
JB
12836(@value{GDBP}) task
12837[Current task is 2]
12838@end smallexample
12839
12840@item task @var{taskno}
12841@cindex Ada task switching
12842This command is like the @code{thread @var{threadno}}
12843command (@pxref{Threads}). It switches the context of debugging
12844from the current task to the given task.
12845
12846@smallexample
12847@iftex
12848@leftskip=0.5cm
12849@end iftex
12850(@value{GDBP}) info tasks
12851 ID TID P-ID Pri State Name
12852 1 8077870 0 15 Child Activation Wait main_task
32cd1edc 12853* 2 807c458 1 15 Runnable t
20924a55
JB
12854(@value{GDBP}) task 1
12855[Switching to task 1]
12856#0 0x8067726 in pthread_cond_wait ()
12857(@value{GDBP}) bt
12858#0 0x8067726 in pthread_cond_wait ()
12859#1 0x8056714 in system.os_interface.pthread_cond_wait ()
12860#2 0x805cb63 in system.task_primitives.operations.sleep ()
12861#3 0x806153e in system.tasking.stages.activate_tasks ()
12862#4 0x804aacc in un () at un.adb:5
12863@end smallexample
12864
45ac276d
JB
12865@item break @var{linespec} task @var{taskno}
12866@itemx break @var{linespec} task @var{taskno} if @dots{}
12867@cindex breakpoints and tasks, in Ada
12868@cindex task breakpoints, in Ada
12869@kindex break @dots{} task @var{taskno}@r{ (Ada)}
12870These commands are like the @code{break @dots{} thread @dots{}}
12871command (@pxref{Thread Stops}).
12872@var{linespec} specifies source lines, as described
12873in @ref{Specify Location}.
12874
12875Use the qualifier @samp{task @var{taskno}} with a breakpoint command
12876to specify that you only want @value{GDBN} to stop the program when a
12877particular Ada task reaches this breakpoint. @var{taskno} is one of the
12878numeric task identifiers assigned by @value{GDBN}, shown in the first
12879column of the @samp{info tasks} display.
12880
12881If you do not specify @samp{task @var{taskno}} when you set a
12882breakpoint, the breakpoint applies to @emph{all} tasks of your
12883program.
12884
12885You can use the @code{task} qualifier on conditional breakpoints as
12886well; in this case, place @samp{task @var{taskno}} before the
12887breakpoint condition (before the @code{if}).
12888
12889For example,
12890
12891@smallexample
12892@iftex
12893@leftskip=0.5cm
12894@end iftex
12895(@value{GDBP}) info tasks
12896 ID TID P-ID Pri State Name
12897 1 140022020 0 15 Child Activation Wait main_task
12898 2 140045060 1 15 Accept/Select Wait t2
12899 3 140044840 1 15 Runnable t1
12900* 4 140056040 1 15 Runnable t3
12901(@value{GDBP}) b 15 task 2
12902Breakpoint 5 at 0x120044cb0: file test_task_debug.adb, line 15.
12903(@value{GDBP}) cont
12904Continuing.
12905task # 1 running
12906task # 2 running
12907
12908Breakpoint 5, test_task_debug () at test_task_debug.adb:15
1290915 flush;
12910(@value{GDBP}) info tasks
12911 ID TID P-ID Pri State Name
12912 1 140022020 0 15 Child Activation Wait main_task
12913* 2 140045060 1 15 Runnable t2
12914 3 140044840 1 15 Runnable t1
12915 4 140056040 1 15 Delay Sleep t3
12916@end smallexample
20924a55
JB
12917@end table
12918
12919@node Ada Tasks and Core Files
12920@subsubsection Tasking Support when Debugging Core Files
12921@cindex Ada tasking and core file debugging
12922
12923When inspecting a core file, as opposed to debugging a live program,
12924tasking support may be limited or even unavailable, depending on
12925the platform being used.
12926For instance, on x86-linux, the list of tasks is available, but task
12927switching is not supported. On Tru64, however, task switching will work
12928as usual.
12929
12930On certain platforms, including Tru64, the debugger needs to perform some
12931memory writes in order to provide Ada tasking support. When inspecting
12932a core file, this means that the core file must be opened with read-write
12933privileges, using the command @samp{"set write on"} (@pxref{Patching}).
12934Under these circumstances, you should make a backup copy of the core
12935file before inspecting it with @value{GDBN}.
12936
e07c999f
PH
12937@node Ada Glitches
12938@subsubsection Known Peculiarities of Ada Mode
12939@cindex Ada, problems
12940
12941Besides the omissions listed previously (@pxref{Omissions from Ada}),
12942we know of several problems with and limitations of Ada mode in
12943@value{GDBN},
12944some of which will be fixed with planned future releases of the debugger
12945and the GNU Ada compiler.
12946
12947@itemize @bullet
12948@item
12949Currently, the debugger
12950has insufficient information to determine whether certain pointers represent
12951pointers to objects or the objects themselves.
12952Thus, the user may have to tack an extra @code{.all} after an expression
12953to get it printed properly.
12954
12955@item
12956Static constants that the compiler chooses not to materialize as objects in
12957storage are invisible to the debugger.
12958
12959@item
12960Named parameter associations in function argument lists are ignored (the
12961argument lists are treated as positional).
12962
12963@item
12964Many useful library packages are currently invisible to the debugger.
12965
12966@item
12967Fixed-point arithmetic, conversions, input, and output is carried out using
12968floating-point arithmetic, and may give results that only approximate those on
12969the host machine.
12970
e07c999f
PH
12971@item
12972The GNAT compiler never generates the prefix @code{Standard} for any of
12973the standard symbols defined by the Ada language. @value{GDBN} knows about
12974this: it will strip the prefix from names when you use it, and will never
12975look for a name you have so qualified among local symbols, nor match against
12976symbols in other packages or subprograms. If you have
12977defined entities anywhere in your program other than parameters and
12978local variables whose simple names match names in @code{Standard},
12979GNAT's lack of qualification here can cause confusion. When this happens,
12980you can usually resolve the confusion
12981by qualifying the problematic names with package
12982@code{Standard} explicitly.
12983@end itemize
12984
95433b34
JB
12985Older versions of the compiler sometimes generate erroneous debugging
12986information, resulting in the debugger incorrectly printing the value
12987of affected entities. In some cases, the debugger is able to work
12988around an issue automatically. In other cases, the debugger is able
12989to work around the issue, but the work-around has to be specifically
12990enabled.
12991
12992@kindex set ada trust-PAD-over-XVS
12993@kindex show ada trust-PAD-over-XVS
12994@table @code
12995
12996@item set ada trust-PAD-over-XVS on
12997Configure GDB to strictly follow the GNAT encoding when computing the
12998value of Ada entities, particularly when @code{PAD} and @code{PAD___XVS}
12999types are involved (see @code{ada/exp_dbug.ads} in the GCC sources for
13000a complete description of the encoding used by the GNAT compiler).
13001This is the default.
13002
13003@item set ada trust-PAD-over-XVS off
13004This is related to the encoding using by the GNAT compiler. If @value{GDBN}
13005sometimes prints the wrong value for certain entities, changing @code{ada
13006trust-PAD-over-XVS} to @code{off} activates a work-around which may fix
13007the issue. It is always safe to set @code{ada trust-PAD-over-XVS} to
13008@code{off}, but this incurs a slight performance penalty, so it is
13009recommended to leave this setting to @code{on} unless necessary.
13010
13011@end table
13012
79a6e687
BW
13013@node Unsupported Languages
13014@section Unsupported Languages
4e562065
JB
13015
13016@cindex unsupported languages
13017@cindex minimal language
13018In addition to the other fully-supported programming languages,
13019@value{GDBN} also provides a pseudo-language, called @code{minimal}.
13020It does not represent a real programming language, but provides a set
13021of capabilities close to what the C or assembly languages provide.
13022This should allow most simple operations to be performed while debugging
13023an application that uses a language currently not supported by @value{GDBN}.
13024
13025If the language is set to @code{auto}, @value{GDBN} will automatically
13026select this language if the current frame corresponds to an unsupported
13027language.
13028
6d2ebf8b 13029@node Symbols
c906108c
SS
13030@chapter Examining the Symbol Table
13031
d4f3574e 13032The commands described in this chapter allow you to inquire about the
c906108c
SS
13033symbols (names of variables, functions and types) defined in your
13034program. This information is inherent in the text of your program and
13035does not change as your program executes. @value{GDBN} finds it in your
13036program's symbol table, in the file indicated when you started @value{GDBN}
79a6e687
BW
13037(@pxref{File Options, ,Choosing Files}), or by one of the
13038file-management commands (@pxref{Files, ,Commands to Specify Files}).
c906108c
SS
13039
13040@cindex symbol names
13041@cindex names of symbols
13042@cindex quoting names
13043Occasionally, you may need to refer to symbols that contain unusual
13044characters, which @value{GDBN} ordinarily treats as word delimiters. The
13045most frequent case is in referring to static variables in other
79a6e687 13046source files (@pxref{Variables,,Program Variables}). File names
c906108c
SS
13047are recorded in object files as debugging symbols, but @value{GDBN} would
13048ordinarily parse a typical file name, like @file{foo.c}, as the three words
13049@samp{foo} @samp{.} @samp{c}. To allow @value{GDBN} to recognize
13050@samp{foo.c} as a single symbol, enclose it in single quotes; for example,
13051
474c8240 13052@smallexample
c906108c 13053p 'foo.c'::x
474c8240 13054@end smallexample
c906108c
SS
13055
13056@noindent
13057looks up the value of @code{x} in the scope of the file @file{foo.c}.
13058
13059@table @code
a8f24a35
EZ
13060@cindex case-insensitive symbol names
13061@cindex case sensitivity in symbol names
13062@kindex set case-sensitive
13063@item set case-sensitive on
13064@itemx set case-sensitive off
13065@itemx set case-sensitive auto
13066Normally, when @value{GDBN} looks up symbols, it matches their names
13067with case sensitivity determined by the current source language.
13068Occasionally, you may wish to control that. The command @code{set
13069case-sensitive} lets you do that by specifying @code{on} for
13070case-sensitive matches or @code{off} for case-insensitive ones. If
13071you specify @code{auto}, case sensitivity is reset to the default
13072suitable for the source language. The default is case-sensitive
13073matches for all languages except for Fortran, for which the default is
13074case-insensitive matches.
13075
9c16f35a
EZ
13076@kindex show case-sensitive
13077@item show case-sensitive
a8f24a35
EZ
13078This command shows the current setting of case sensitivity for symbols
13079lookups.
13080
c906108c 13081@kindex info address
b37052ae 13082@cindex address of a symbol
c906108c
SS
13083@item info address @var{symbol}
13084Describe where the data for @var{symbol} is stored. For a register
13085variable, this says which register it is kept in. For a non-register
13086local variable, this prints the stack-frame offset at which the variable
13087is always stored.
13088
13089Note the contrast with @samp{print &@var{symbol}}, which does not work
13090at all for a register variable, and for a stack local variable prints
13091the exact address of the current instantiation of the variable.
13092
3d67e040 13093@kindex info symbol
b37052ae 13094@cindex symbol from address
9c16f35a 13095@cindex closest symbol and offset for an address
3d67e040
EZ
13096@item info symbol @var{addr}
13097Print the name of a symbol which is stored at the address @var{addr}.
13098If no symbol is stored exactly at @var{addr}, @value{GDBN} prints the
13099nearest symbol and an offset from it:
13100
474c8240 13101@smallexample
3d67e040
EZ
13102(@value{GDBP}) info symbol 0x54320
13103_initialize_vx + 396 in section .text
474c8240 13104@end smallexample
3d67e040
EZ
13105
13106@noindent
13107This is the opposite of the @code{info address} command. You can use
13108it to find out the name of a variable or a function given its address.
13109
c14c28ba
PP
13110For dynamically linked executables, the name of executable or shared
13111library containing the symbol is also printed:
13112
13113@smallexample
13114(@value{GDBP}) info symbol 0x400225
13115_start + 5 in section .text of /tmp/a.out
13116(@value{GDBP}) info symbol 0x2aaaac2811cf
13117__read_nocancel + 6 in section .text of /usr/lib64/libc.so.6
13118@end smallexample
13119
c906108c 13120@kindex whatis
62f3a2ba
FF
13121@item whatis [@var{arg}]
13122Print the data type of @var{arg}, which can be either an expression or
13123a data type. With no argument, print the data type of @code{$}, the
13124last value in the value history. If @var{arg} is an expression, it is
13125not actually evaluated, and any side-effecting operations (such as
13126assignments or function calls) inside it do not take place. If
13127@var{arg} is a type name, it may be the name of a type or typedef, or
13128for C code it may have the form @samp{class @var{class-name}},
13129@samp{struct @var{struct-tag}}, @samp{union @var{union-tag}} or
13130@samp{enum @var{enum-tag}}.
c906108c
SS
13131@xref{Expressions, ,Expressions}.
13132
c906108c 13133@kindex ptype
62f3a2ba
FF
13134@item ptype [@var{arg}]
13135@code{ptype} accepts the same arguments as @code{whatis}, but prints a
13136detailed description of the type, instead of just the name of the type.
13137@xref{Expressions, ,Expressions}.
c906108c
SS
13138
13139For example, for this variable declaration:
13140
474c8240 13141@smallexample
c906108c 13142struct complex @{double real; double imag;@} v;
474c8240 13143@end smallexample
c906108c
SS
13144
13145@noindent
13146the two commands give this output:
13147
474c8240 13148@smallexample
c906108c
SS
13149@group
13150(@value{GDBP}) whatis v
13151type = struct complex
13152(@value{GDBP}) ptype v
13153type = struct complex @{
13154 double real;
13155 double imag;
13156@}
13157@end group
474c8240 13158@end smallexample
c906108c
SS
13159
13160@noindent
13161As with @code{whatis}, using @code{ptype} without an argument refers to
13162the type of @code{$}, the last value in the value history.
13163
ab1adacd
EZ
13164@cindex incomplete type
13165Sometimes, programs use opaque data types or incomplete specifications
13166of complex data structure. If the debug information included in the
13167program does not allow @value{GDBN} to display a full declaration of
13168the data type, it will say @samp{<incomplete type>}. For example,
13169given these declarations:
13170
13171@smallexample
13172 struct foo;
13173 struct foo *fooptr;
13174@end smallexample
13175
13176@noindent
13177but no definition for @code{struct foo} itself, @value{GDBN} will say:
13178
13179@smallexample
ddb50cd7 13180 (@value{GDBP}) ptype foo
ab1adacd
EZ
13181 $1 = <incomplete type>
13182@end smallexample
13183
13184@noindent
13185``Incomplete type'' is C terminology for data types that are not
13186completely specified.
13187
c906108c
SS
13188@kindex info types
13189@item info types @var{regexp}
13190@itemx info types
09d4efe1
EZ
13191Print a brief description of all types whose names match the regular
13192expression @var{regexp} (or all types in your program, if you supply
13193no argument). Each complete typename is matched as though it were a
13194complete line; thus, @samp{i type value} gives information on all
13195types in your program whose names include the string @code{value}, but
13196@samp{i type ^value$} gives information only on types whose complete
13197name is @code{value}.
c906108c
SS
13198
13199This command differs from @code{ptype} in two ways: first, like
13200@code{whatis}, it does not print a detailed description; second, it
13201lists all source files where a type is defined.
13202
b37052ae
EZ
13203@kindex info scope
13204@cindex local variables
09d4efe1 13205@item info scope @var{location}
b37052ae 13206List all the variables local to a particular scope. This command
09d4efe1
EZ
13207accepts a @var{location} argument---a function name, a source line, or
13208an address preceded by a @samp{*}, and prints all the variables local
2a25a5ba
EZ
13209to the scope defined by that location. (@xref{Specify Location}, for
13210details about supported forms of @var{location}.) For example:
b37052ae
EZ
13211
13212@smallexample
13213(@value{GDBP}) @b{info scope command_line_handler}
13214Scope for command_line_handler:
13215Symbol rl is an argument at stack/frame offset 8, length 4.
13216Symbol linebuffer is in static storage at address 0x150a18, length 4.
13217Symbol linelength is in static storage at address 0x150a1c, length 4.
13218Symbol p is a local variable in register $esi, length 4.
13219Symbol p1 is a local variable in register $ebx, length 4.
13220Symbol nline is a local variable in register $edx, length 4.
13221Symbol repeat is a local variable at frame offset -8, length 4.
13222@end smallexample
13223
f5c37c66
EZ
13224@noindent
13225This command is especially useful for determining what data to collect
13226during a @dfn{trace experiment}, see @ref{Tracepoint Actions,
13227collect}.
13228
c906108c
SS
13229@kindex info source
13230@item info source
919d772c
JB
13231Show information about the current source file---that is, the source file for
13232the function containing the current point of execution:
13233@itemize @bullet
13234@item
13235the name of the source file, and the directory containing it,
13236@item
13237the directory it was compiled in,
13238@item
13239its length, in lines,
13240@item
13241which programming language it is written in,
13242@item
13243whether the executable includes debugging information for that file, and
13244if so, what format the information is in (e.g., STABS, Dwarf 2, etc.), and
13245@item
13246whether the debugging information includes information about
13247preprocessor macros.
13248@end itemize
13249
c906108c
SS
13250
13251@kindex info sources
13252@item info sources
13253Print the names of all source files in your program for which there is
13254debugging information, organized into two lists: files whose symbols
13255have already been read, and files whose symbols will be read when needed.
13256
13257@kindex info functions
13258@item info functions
13259Print the names and data types of all defined functions.
13260
13261@item info functions @var{regexp}
13262Print the names and data types of all defined functions
13263whose names contain a match for regular expression @var{regexp}.
13264Thus, @samp{info fun step} finds all functions whose names
13265include @code{step}; @samp{info fun ^step} finds those whose names
b383017d 13266start with @code{step}. If a function name contains characters
c1468174 13267that conflict with the regular expression language (e.g.@:
1c5dfdad 13268@samp{operator*()}), they may be quoted with a backslash.
c906108c
SS
13269
13270@kindex info variables
13271@item info variables
0fe7935b 13272Print the names and data types of all variables that are defined
6ca652b0 13273outside of functions (i.e.@: excluding local variables).
c906108c
SS
13274
13275@item info variables @var{regexp}
13276Print the names and data types of all variables (except for local
13277variables) whose names contain a match for regular expression
13278@var{regexp}.
13279
b37303ee 13280@kindex info classes
721c2651 13281@cindex Objective-C, classes and selectors
b37303ee
AF
13282@item info classes
13283@itemx info classes @var{regexp}
13284Display all Objective-C classes in your program, or
13285(with the @var{regexp} argument) all those matching a particular regular
13286expression.
13287
13288@kindex info selectors
13289@item info selectors
13290@itemx info selectors @var{regexp}
13291Display all Objective-C selectors in your program, or
13292(with the @var{regexp} argument) all those matching a particular regular
13293expression.
13294
c906108c
SS
13295@ignore
13296This was never implemented.
13297@kindex info methods
13298@item info methods
13299@itemx info methods @var{regexp}
13300The @code{info methods} command permits the user to examine all defined
b37052ae
EZ
13301methods within C@t{++} program, or (with the @var{regexp} argument) a
13302specific set of methods found in the various C@t{++} classes. Many
13303C@t{++} classes provide a large number of methods. Thus, the output
c906108c
SS
13304from the @code{ptype} command can be overwhelming and hard to use. The
13305@code{info-methods} command filters the methods, printing only those
13306which match the regular-expression @var{regexp}.
13307@end ignore
13308
c906108c
SS
13309@cindex reloading symbols
13310Some systems allow individual object files that make up your program to
7a292a7a
SS
13311be replaced without stopping and restarting your program. For example,
13312in VxWorks you can simply recompile a defective object file and keep on
13313running. If you are running on one of these systems, you can allow
13314@value{GDBN} to reload the symbols for automatically relinked modules:
c906108c
SS
13315
13316@table @code
13317@kindex set symbol-reloading
13318@item set symbol-reloading on
13319Replace symbol definitions for the corresponding source file when an
13320object file with a particular name is seen again.
13321
13322@item set symbol-reloading off
6d2ebf8b
SS
13323Do not replace symbol definitions when encountering object files of the
13324same name more than once. This is the default state; if you are not
13325running on a system that permits automatic relinking of modules, you
13326should leave @code{symbol-reloading} off, since otherwise @value{GDBN}
13327may discard symbols when linking large programs, that may contain
13328several modules (from different directories or libraries) with the same
13329name.
c906108c
SS
13330
13331@kindex show symbol-reloading
13332@item show symbol-reloading
13333Show the current @code{on} or @code{off} setting.
13334@end table
c906108c 13335
9c16f35a 13336@cindex opaque data types
c906108c
SS
13337@kindex set opaque-type-resolution
13338@item set opaque-type-resolution on
13339Tell @value{GDBN} to resolve opaque types. An opaque type is a type
13340declared as a pointer to a @code{struct}, @code{class}, or
13341@code{union}---for example, @code{struct MyType *}---that is used in one
13342source file although the full declaration of @code{struct MyType} is in
13343another source file. The default is on.
13344
13345A change in the setting of this subcommand will not take effect until
13346the next time symbols for a file are loaded.
13347
13348@item set opaque-type-resolution off
13349Tell @value{GDBN} not to resolve opaque types. In this case, the type
13350is printed as follows:
13351@smallexample
13352@{<no data fields>@}
13353@end smallexample
13354
13355@kindex show opaque-type-resolution
13356@item show opaque-type-resolution
13357Show whether opaque types are resolved or not.
c906108c
SS
13358
13359@kindex maint print symbols
13360@cindex symbol dump
13361@kindex maint print psymbols
13362@cindex partial symbol dump
13363@item maint print symbols @var{filename}
13364@itemx maint print psymbols @var{filename}
13365@itemx maint print msymbols @var{filename}
13366Write a dump of debugging symbol data into the file @var{filename}.
13367These commands are used to debug the @value{GDBN} symbol-reading code. Only
13368symbols with debugging data are included. If you use @samp{maint print
13369symbols}, @value{GDBN} includes all the symbols for which it has already
13370collected full details: that is, @var{filename} reflects symbols for
13371only those files whose symbols @value{GDBN} has read. You can use the
13372command @code{info sources} to find out which files these are. If you
13373use @samp{maint print psymbols} instead, the dump shows information about
13374symbols that @value{GDBN} only knows partially---that is, symbols defined in
13375files that @value{GDBN} has skimmed, but not yet read completely. Finally,
13376@samp{maint print msymbols} dumps just the minimal symbol information
13377required for each object file from which @value{GDBN} has read some symbols.
79a6e687 13378@xref{Files, ,Commands to Specify Files}, for a discussion of how
c906108c 13379@value{GDBN} reads symbols (in the description of @code{symbol-file}).
44ea7b70 13380
5e7b2f39
JB
13381@kindex maint info symtabs
13382@kindex maint info psymtabs
44ea7b70
JB
13383@cindex listing @value{GDBN}'s internal symbol tables
13384@cindex symbol tables, listing @value{GDBN}'s internal
13385@cindex full symbol tables, listing @value{GDBN}'s internal
13386@cindex partial symbol tables, listing @value{GDBN}'s internal
5e7b2f39
JB
13387@item maint info symtabs @r{[} @var{regexp} @r{]}
13388@itemx maint info psymtabs @r{[} @var{regexp} @r{]}
44ea7b70
JB
13389
13390List the @code{struct symtab} or @code{struct partial_symtab}
13391structures whose names match @var{regexp}. If @var{regexp} is not
13392given, list them all. The output includes expressions which you can
13393copy into a @value{GDBN} debugging this one to examine a particular
13394structure in more detail. For example:
13395
13396@smallexample
5e7b2f39 13397(@value{GDBP}) maint info psymtabs dwarf2read
44ea7b70
JB
13398@{ objfile /home/gnu/build/gdb/gdb
13399 ((struct objfile *) 0x82e69d0)
b383017d 13400 @{ psymtab /home/gnu/src/gdb/dwarf2read.c
44ea7b70
JB
13401 ((struct partial_symtab *) 0x8474b10)
13402 readin no
13403 fullname (null)
13404 text addresses 0x814d3c8 -- 0x8158074
13405 globals (* (struct partial_symbol **) 0x8507a08 @@ 9)
13406 statics (* (struct partial_symbol **) 0x40e95b78 @@ 2882)
13407 dependencies (none)
13408 @}
13409@}
5e7b2f39 13410(@value{GDBP}) maint info symtabs
44ea7b70
JB
13411(@value{GDBP})
13412@end smallexample
13413@noindent
13414We see that there is one partial symbol table whose filename contains
13415the string @samp{dwarf2read}, belonging to the @samp{gdb} executable;
13416and we see that @value{GDBN} has not read in any symtabs yet at all.
13417If we set a breakpoint on a function, that will cause @value{GDBN} to
13418read the symtab for the compilation unit containing that function:
13419
13420@smallexample
13421(@value{GDBP}) break dwarf2_psymtab_to_symtab
13422Breakpoint 1 at 0x814e5da: file /home/gnu/src/gdb/dwarf2read.c,
13423line 1574.
5e7b2f39 13424(@value{GDBP}) maint info symtabs
b383017d 13425@{ objfile /home/gnu/build/gdb/gdb
44ea7b70 13426 ((struct objfile *) 0x82e69d0)
b383017d 13427 @{ symtab /home/gnu/src/gdb/dwarf2read.c
44ea7b70
JB
13428 ((struct symtab *) 0x86c1f38)
13429 dirname (null)
13430 fullname (null)
13431 blockvector ((struct blockvector *) 0x86c1bd0) (primary)
1b39d5c0 13432 linetable ((struct linetable *) 0x8370fa0)
44ea7b70
JB
13433 debugformat DWARF 2
13434 @}
13435@}
b383017d 13436(@value{GDBP})
44ea7b70 13437@end smallexample
c906108c
SS
13438@end table
13439
44ea7b70 13440
6d2ebf8b 13441@node Altering
c906108c
SS
13442@chapter Altering Execution
13443
13444Once you think you have found an error in your program, you might want to
13445find out for certain whether correcting the apparent error would lead to
13446correct results in the rest of the run. You can find the answer by
13447experiment, using the @value{GDBN} features for altering execution of the
13448program.
13449
13450For example, you can store new values into variables or memory
7a292a7a
SS
13451locations, give your program a signal, restart it at a different
13452address, or even return prematurely from a function.
c906108c
SS
13453
13454@menu
13455* Assignment:: Assignment to variables
13456* Jumping:: Continuing at a different address
c906108c 13457* Signaling:: Giving your program a signal
c906108c
SS
13458* Returning:: Returning from a function
13459* Calling:: Calling your program's functions
13460* Patching:: Patching your program
13461@end menu
13462
6d2ebf8b 13463@node Assignment
79a6e687 13464@section Assignment to Variables
c906108c
SS
13465
13466@cindex assignment
13467@cindex setting variables
13468To alter the value of a variable, evaluate an assignment expression.
13469@xref{Expressions, ,Expressions}. For example,
13470
474c8240 13471@smallexample
c906108c 13472print x=4
474c8240 13473@end smallexample
c906108c
SS
13474
13475@noindent
13476stores the value 4 into the variable @code{x}, and then prints the
5d161b24 13477value of the assignment expression (which is 4).
c906108c
SS
13478@xref{Languages, ,Using @value{GDBN} with Different Languages}, for more
13479information on operators in supported languages.
c906108c
SS
13480
13481@kindex set variable
13482@cindex variables, setting
13483If you are not interested in seeing the value of the assignment, use the
13484@code{set} command instead of the @code{print} command. @code{set} is
13485really the same as @code{print} except that the expression's value is
13486not printed and is not put in the value history (@pxref{Value History,
79a6e687 13487,Value History}). The expression is evaluated only for its effects.
c906108c 13488
c906108c
SS
13489If the beginning of the argument string of the @code{set} command
13490appears identical to a @code{set} subcommand, use the @code{set
13491variable} command instead of just @code{set}. This command is identical
13492to @code{set} except for its lack of subcommands. For example, if your
13493program has a variable @code{width}, you get an error if you try to set
13494a new value with just @samp{set width=13}, because @value{GDBN} has the
13495command @code{set width}:
13496
474c8240 13497@smallexample
c906108c
SS
13498(@value{GDBP}) whatis width
13499type = double
13500(@value{GDBP}) p width
13501$4 = 13
13502(@value{GDBP}) set width=47
13503Invalid syntax in expression.
474c8240 13504@end smallexample
c906108c
SS
13505
13506@noindent
13507The invalid expression, of course, is @samp{=47}. In
13508order to actually set the program's variable @code{width}, use
13509
474c8240 13510@smallexample
c906108c 13511(@value{GDBP}) set var width=47
474c8240 13512@end smallexample
53a5351d 13513
c906108c
SS
13514Because the @code{set} command has many subcommands that can conflict
13515with the names of program variables, it is a good idea to use the
13516@code{set variable} command instead of just @code{set}. For example, if
13517your program has a variable @code{g}, you run into problems if you try
13518to set a new value with just @samp{set g=4}, because @value{GDBN} has
13519the command @code{set gnutarget}, abbreviated @code{set g}:
13520
474c8240 13521@smallexample
c906108c
SS
13522@group
13523(@value{GDBP}) whatis g
13524type = double
13525(@value{GDBP}) p g
13526$1 = 1
13527(@value{GDBP}) set g=4
2df3850c 13528(@value{GDBP}) p g
c906108c
SS
13529$2 = 1
13530(@value{GDBP}) r
13531The program being debugged has been started already.
13532Start it from the beginning? (y or n) y
13533Starting program: /home/smith/cc_progs/a.out
6d2ebf8b
SS
13534"/home/smith/cc_progs/a.out": can't open to read symbols:
13535 Invalid bfd target.
c906108c
SS
13536(@value{GDBP}) show g
13537The current BFD target is "=4".
13538@end group
474c8240 13539@end smallexample
c906108c
SS
13540
13541@noindent
13542The program variable @code{g} did not change, and you silently set the
13543@code{gnutarget} to an invalid value. In order to set the variable
13544@code{g}, use
13545
474c8240 13546@smallexample
c906108c 13547(@value{GDBP}) set var g=4
474c8240 13548@end smallexample
c906108c
SS
13549
13550@value{GDBN} allows more implicit conversions in assignments than C; you can
13551freely store an integer value into a pointer variable or vice versa,
13552and you can convert any structure to any other structure that is the
13553same length or shorter.
13554@comment FIXME: how do structs align/pad in these conversions?
13555@comment /doc@cygnus.com 18dec1990
13556
13557To store values into arbitrary places in memory, use the @samp{@{@dots{}@}}
13558construct to generate a value of specified type at a specified address
13559(@pxref{Expressions, ,Expressions}). For example, @code{@{int@}0x83040} refers
13560to memory location @code{0x83040} as an integer (which implies a certain size
13561and representation in memory), and
13562
474c8240 13563@smallexample
c906108c 13564set @{int@}0x83040 = 4
474c8240 13565@end smallexample
c906108c
SS
13566
13567@noindent
13568stores the value 4 into that memory location.
13569
6d2ebf8b 13570@node Jumping
79a6e687 13571@section Continuing at a Different Address
c906108c
SS
13572
13573Ordinarily, when you continue your program, you do so at the place where
13574it stopped, with the @code{continue} command. You can instead continue at
13575an address of your own choosing, with the following commands:
13576
13577@table @code
13578@kindex jump
13579@item jump @var{linespec}
2a25a5ba
EZ
13580@itemx jump @var{location}
13581Resume execution at line @var{linespec} or at address given by
13582@var{location}. Execution stops again immediately if there is a
13583breakpoint there. @xref{Specify Location}, for a description of the
13584different forms of @var{linespec} and @var{location}. It is common
13585practice to use the @code{tbreak} command in conjunction with
13586@code{jump}. @xref{Set Breaks, ,Setting Breakpoints}.
c906108c
SS
13587
13588The @code{jump} command does not change the current stack frame, or
13589the stack pointer, or the contents of any memory location or any
13590register other than the program counter. If line @var{linespec} is in
13591a different function from the one currently executing, the results may
13592be bizarre if the two functions expect different patterns of arguments or
13593of local variables. For this reason, the @code{jump} command requests
13594confirmation if the specified line is not in the function currently
13595executing. However, even bizarre results are predictable if you are
13596well acquainted with the machine-language code of your program.
c906108c
SS
13597@end table
13598
c906108c 13599@c Doesn't work on HP-UX; have to set $pcoqh and $pcoqt.
53a5351d
JM
13600On many systems, you can get much the same effect as the @code{jump}
13601command by storing a new value into the register @code{$pc}. The
13602difference is that this does not start your program running; it only
13603changes the address of where it @emph{will} run when you continue. For
13604example,
c906108c 13605
474c8240 13606@smallexample
c906108c 13607set $pc = 0x485
474c8240 13608@end smallexample
c906108c
SS
13609
13610@noindent
13611makes the next @code{continue} command or stepping command execute at
13612address @code{0x485}, rather than at the address where your program stopped.
79a6e687 13613@xref{Continuing and Stepping, ,Continuing and Stepping}.
c906108c
SS
13614
13615The most common occasion to use the @code{jump} command is to back
13616up---perhaps with more breakpoints set---over a portion of a program
13617that has already executed, in order to examine its execution in more
13618detail.
13619
c906108c 13620@c @group
6d2ebf8b 13621@node Signaling
79a6e687 13622@section Giving your Program a Signal
9c16f35a 13623@cindex deliver a signal to a program
c906108c
SS
13624
13625@table @code
13626@kindex signal
13627@item signal @var{signal}
13628Resume execution where your program stopped, but immediately give it the
13629signal @var{signal}. @var{signal} can be the name or the number of a
13630signal. For example, on many systems @code{signal 2} and @code{signal
13631SIGINT} are both ways of sending an interrupt signal.
13632
13633Alternatively, if @var{signal} is zero, continue execution without
13634giving a signal. This is useful when your program stopped on account of
13635a signal and would ordinary see the signal when resumed with the
13636@code{continue} command; @samp{signal 0} causes it to resume without a
13637signal.
13638
13639@code{signal} does not repeat when you press @key{RET} a second time
13640after executing the command.
13641@end table
13642@c @end group
13643
13644Invoking the @code{signal} command is not the same as invoking the
13645@code{kill} utility from the shell. Sending a signal with @code{kill}
13646causes @value{GDBN} to decide what to do with the signal depending on
13647the signal handling tables (@pxref{Signals}). The @code{signal} command
13648passes the signal directly to your program.
13649
c906108c 13650
6d2ebf8b 13651@node Returning
79a6e687 13652@section Returning from a Function
c906108c
SS
13653
13654@table @code
13655@cindex returning from a function
13656@kindex return
13657@item return
13658@itemx return @var{expression}
13659You can cancel execution of a function call with the @code{return}
13660command. If you give an
13661@var{expression} argument, its value is used as the function's return
13662value.
13663@end table
13664
13665When you use @code{return}, @value{GDBN} discards the selected stack frame
13666(and all frames within it). You can think of this as making the
13667discarded frame return prematurely. If you wish to specify a value to
13668be returned, give that value as the argument to @code{return}.
13669
13670This pops the selected stack frame (@pxref{Selection, ,Selecting a
79a6e687 13671Frame}), and any other frames inside of it, leaving its caller as the
c906108c
SS
13672innermost remaining frame. That frame becomes selected. The
13673specified value is stored in the registers used for returning values
13674of functions.
13675
13676The @code{return} command does not resume execution; it leaves the
13677program stopped in the state that would exist if the function had just
13678returned. In contrast, the @code{finish} command (@pxref{Continuing
79a6e687 13679and Stepping, ,Continuing and Stepping}) resumes execution until the
c906108c
SS
13680selected stack frame returns naturally.
13681
61ff14c6
JK
13682@value{GDBN} needs to know how the @var{expression} argument should be set for
13683the inferior. The concrete registers assignment depends on the OS ABI and the
13684type being returned by the selected stack frame. For example it is common for
13685OS ABI to return floating point values in FPU registers while integer values in
13686CPU registers. Still some ABIs return even floating point values in CPU
13687registers. Larger integer widths (such as @code{long long int}) also have
13688specific placement rules. @value{GDBN} already knows the OS ABI from its
13689current target so it needs to find out also the type being returned to make the
13690assignment into the right register(s).
13691
13692Normally, the selected stack frame has debug info. @value{GDBN} will always
13693use the debug info instead of the implicit type of @var{expression} when the
13694debug info is available. For example, if you type @kbd{return -1}, and the
13695function in the current stack frame is declared to return a @code{long long
13696int}, @value{GDBN} transparently converts the implicit @code{int} value of -1
13697into a @code{long long int}:
13698
13699@smallexample
13700Breakpoint 1, func () at gdb.base/return-nodebug.c:29
1370129 return 31;
13702(@value{GDBP}) return -1
13703Make func return now? (y or n) y
13704#0 0x004004f6 in main () at gdb.base/return-nodebug.c:43
1370543 printf ("result=%lld\n", func ());
13706(@value{GDBP})
13707@end smallexample
13708
13709However, if the selected stack frame does not have a debug info, e.g., if the
13710function was compiled without debug info, @value{GDBN} has to find out the type
13711to return from user. Specifying a different type by mistake may set the value
13712in different inferior registers than the caller code expects. For example,
13713typing @kbd{return -1} with its implicit type @code{int} would set only a part
13714of a @code{long long int} result for a debug info less function (on 32-bit
13715architectures). Therefore the user is required to specify the return type by
13716an appropriate cast explicitly:
13717
13718@smallexample
13719Breakpoint 2, 0x0040050b in func ()
13720(@value{GDBP}) return -1
13721Return value type not available for selected stack frame.
13722Please use an explicit cast of the value to return.
13723(@value{GDBP}) return (long long int) -1
13724Make selected stack frame return now? (y or n) y
13725#0 0x00400526 in main ()
13726(@value{GDBP})
13727@end smallexample
13728
6d2ebf8b 13729@node Calling
79a6e687 13730@section Calling Program Functions
c906108c 13731
f8568604 13732@table @code
c906108c 13733@cindex calling functions
f8568604
EZ
13734@cindex inferior functions, calling
13735@item print @var{expr}
d3e8051b 13736Evaluate the expression @var{expr} and display the resulting value.
f8568604
EZ
13737@var{expr} may include calls to functions in the program being
13738debugged.
13739
c906108c 13740@kindex call
c906108c
SS
13741@item call @var{expr}
13742Evaluate the expression @var{expr} without displaying @code{void}
13743returned values.
c906108c
SS
13744
13745You can use this variant of the @code{print} command if you want to
f8568604
EZ
13746execute a function from your program that does not return anything
13747(a.k.a.@: @dfn{a void function}), but without cluttering the output
13748with @code{void} returned values that @value{GDBN} will otherwise
13749print. If the result is not void, it is printed and saved in the
13750value history.
13751@end table
13752
9c16f35a
EZ
13753It is possible for the function you call via the @code{print} or
13754@code{call} command to generate a signal (e.g., if there's a bug in
13755the function, or if you passed it incorrect arguments). What happens
13756in that case is controlled by the @code{set unwindonsignal} command.
13757
7cd1089b
PM
13758Similarly, with a C@t{++} program it is possible for the function you
13759call via the @code{print} or @code{call} command to generate an
13760exception that is not handled due to the constraints of the dummy
13761frame. In this case, any exception that is raised in the frame, but has
13762an out-of-frame exception handler will not be found. GDB builds a
13763dummy-frame for the inferior function call, and the unwinder cannot
13764seek for exception handlers outside of this dummy-frame. What happens
13765in that case is controlled by the
13766@code{set unwind-on-terminating-exception} command.
13767
9c16f35a
EZ
13768@table @code
13769@item set unwindonsignal
13770@kindex set unwindonsignal
13771@cindex unwind stack in called functions
13772@cindex call dummy stack unwinding
13773Set unwinding of the stack if a signal is received while in a function
13774that @value{GDBN} called in the program being debugged. If set to on,
13775@value{GDBN} unwinds the stack it created for the call and restores
13776the context to what it was before the call. If set to off (the
13777default), @value{GDBN} stops in the frame where the signal was
13778received.
13779
13780@item show unwindonsignal
13781@kindex show unwindonsignal
13782Show the current setting of stack unwinding in the functions called by
13783@value{GDBN}.
7cd1089b
PM
13784
13785@item set unwind-on-terminating-exception
13786@kindex set unwind-on-terminating-exception
13787@cindex unwind stack in called functions with unhandled exceptions
13788@cindex call dummy stack unwinding on unhandled exception.
13789Set unwinding of the stack if a C@t{++} exception is raised, but left
13790unhandled while in a function that @value{GDBN} called in the program being
13791debugged. If set to on (the default), @value{GDBN} unwinds the stack
13792it created for the call and restores the context to what it was before
13793the call. If set to off, @value{GDBN} the exception is delivered to
13794the default C@t{++} exception handler and the inferior terminated.
13795
13796@item show unwind-on-terminating-exception
13797@kindex show unwind-on-terminating-exception
13798Show the current setting of stack unwinding in the functions called by
13799@value{GDBN}.
13800
9c16f35a
EZ
13801@end table
13802
f8568604
EZ
13803@cindex weak alias functions
13804Sometimes, a function you wish to call is actually a @dfn{weak alias}
13805for another function. In such case, @value{GDBN} might not pick up
13806the type information, including the types of the function arguments,
13807which causes @value{GDBN} to call the inferior function incorrectly.
13808As a result, the called function will function erroneously and may
13809even crash. A solution to that is to use the name of the aliased
13810function instead.
c906108c 13811
6d2ebf8b 13812@node Patching
79a6e687 13813@section Patching Programs
7a292a7a 13814
c906108c
SS
13815@cindex patching binaries
13816@cindex writing into executables
c906108c 13817@cindex writing into corefiles
c906108c 13818
7a292a7a
SS
13819By default, @value{GDBN} opens the file containing your program's
13820executable code (or the corefile) read-only. This prevents accidental
13821alterations to machine code; but it also prevents you from intentionally
13822patching your program's binary.
c906108c
SS
13823
13824If you'd like to be able to patch the binary, you can specify that
13825explicitly with the @code{set write} command. For example, you might
13826want to turn on internal debugging flags, or even to make emergency
13827repairs.
13828
13829@table @code
13830@kindex set write
13831@item set write on
13832@itemx set write off
7a292a7a 13833If you specify @samp{set write on}, @value{GDBN} opens executable and
20924a55 13834core files for both reading and writing; if you specify @kbd{set write
c906108c
SS
13835off} (the default), @value{GDBN} opens them read-only.
13836
13837If you have already loaded a file, you must load it again (using the
7a292a7a
SS
13838@code{exec-file} or @code{core-file} command) after changing @code{set
13839write}, for your new setting to take effect.
c906108c
SS
13840
13841@item show write
13842@kindex show write
7a292a7a
SS
13843Display whether executable files and core files are opened for writing
13844as well as reading.
c906108c
SS
13845@end table
13846
6d2ebf8b 13847@node GDB Files
c906108c
SS
13848@chapter @value{GDBN} Files
13849
7a292a7a
SS
13850@value{GDBN} needs to know the file name of the program to be debugged,
13851both in order to read its symbol table and in order to start your
13852program. To debug a core dump of a previous run, you must also tell
13853@value{GDBN} the name of the core dump file.
c906108c
SS
13854
13855@menu
13856* Files:: Commands to specify files
5b5d99cf 13857* Separate Debug Files:: Debugging information in separate files
c906108c 13858* Symbol Errors:: Errors reading symbol files
b14b1491 13859* Data Files:: GDB data files
c906108c
SS
13860@end menu
13861
6d2ebf8b 13862@node Files
79a6e687 13863@section Commands to Specify Files
c906108c 13864
7a292a7a 13865@cindex symbol table
c906108c 13866@cindex core dump file
7a292a7a
SS
13867
13868You may want to specify executable and core dump file names. The usual
13869way to do this is at start-up time, using the arguments to
13870@value{GDBN}'s start-up commands (@pxref{Invocation, , Getting In and
13871Out of @value{GDBN}}).
c906108c
SS
13872
13873Occasionally it is necessary to change to a different file during a
397ca115
EZ
13874@value{GDBN} session. Or you may run @value{GDBN} and forget to
13875specify a file you want to use. Or you are debugging a remote target
79a6e687
BW
13876via @code{gdbserver} (@pxref{Server, file, Using the @code{gdbserver}
13877Program}). In these situations the @value{GDBN} commands to specify
0869d01b 13878new files are useful.
c906108c
SS
13879
13880@table @code
13881@cindex executable file
13882@kindex file
13883@item file @var{filename}
13884Use @var{filename} as the program to be debugged. It is read for its
13885symbols and for the contents of pure memory. It is also the program
13886executed when you use the @code{run} command. If you do not specify a
5d161b24
DB
13887directory and the file is not found in the @value{GDBN} working directory,
13888@value{GDBN} uses the environment variable @code{PATH} as a list of
13889directories to search, just as the shell does when looking for a program
13890to run. You can change the value of this variable, for both @value{GDBN}
c906108c
SS
13891and your program, using the @code{path} command.
13892
fc8be69e
EZ
13893@cindex unlinked object files
13894@cindex patching object files
13895You can load unlinked object @file{.o} files into @value{GDBN} using
13896the @code{file} command. You will not be able to ``run'' an object
13897file, but you can disassemble functions and inspect variables. Also,
13898if the underlying BFD functionality supports it, you could use
13899@kbd{gdb -write} to patch object files using this technique. Note
13900that @value{GDBN} can neither interpret nor modify relocations in this
13901case, so branches and some initialized variables will appear to go to
13902the wrong place. But this feature is still handy from time to time.
13903
c906108c
SS
13904@item file
13905@code{file} with no argument makes @value{GDBN} discard any information it
13906has on both executable file and the symbol table.
13907
13908@kindex exec-file
13909@item exec-file @r{[} @var{filename} @r{]}
13910Specify that the program to be run (but not the symbol table) is found
13911in @var{filename}. @value{GDBN} searches the environment variable @code{PATH}
13912if necessary to locate your program. Omitting @var{filename} means to
13913discard information on the executable file.
13914
13915@kindex symbol-file
13916@item symbol-file @r{[} @var{filename} @r{]}
13917Read symbol table information from file @var{filename}. @code{PATH} is
13918searched when necessary. Use the @code{file} command to get both symbol
13919table and program to run from the same file.
13920
13921@code{symbol-file} with no argument clears out @value{GDBN} information on your
13922program's symbol table.
13923
ae5a43e0
DJ
13924The @code{symbol-file} command causes @value{GDBN} to forget the contents of
13925some breakpoints and auto-display expressions. This is because they may
13926contain pointers to the internal data recording symbols and data types,
13927which are part of the old symbol table data being discarded inside
13928@value{GDBN}.
c906108c
SS
13929
13930@code{symbol-file} does not repeat if you press @key{RET} again after
13931executing it once.
13932
13933When @value{GDBN} is configured for a particular environment, it
13934understands debugging information in whatever format is the standard
13935generated for that environment; you may use either a @sc{gnu} compiler, or
13936other compilers that adhere to the local conventions.
c906108c 13937Best results are usually obtained from @sc{gnu} compilers; for example,
e22ea452 13938using @code{@value{NGCC}} you can generate debugging information for
c906108c 13939optimized code.
c906108c
SS
13940
13941For most kinds of object files, with the exception of old SVR3 systems
13942using COFF, the @code{symbol-file} command does not normally read the
13943symbol table in full right away. Instead, it scans the symbol table
13944quickly to find which source files and which symbols are present. The
13945details are read later, one source file at a time, as they are needed.
13946
13947The purpose of this two-stage reading strategy is to make @value{GDBN}
13948start up faster. For the most part, it is invisible except for
13949occasional pauses while the symbol table details for a particular source
13950file are being read. (The @code{set verbose} command can turn these
13951pauses into messages if desired. @xref{Messages/Warnings, ,Optional
79a6e687 13952Warnings and Messages}.)
c906108c 13953
c906108c
SS
13954We have not implemented the two-stage strategy for COFF yet. When the
13955symbol table is stored in COFF format, @code{symbol-file} reads the
13956symbol table data in full right away. Note that ``stabs-in-COFF''
13957still does the two-stage strategy, since the debug info is actually
13958in stabs format.
13959
13960@kindex readnow
13961@cindex reading symbols immediately
13962@cindex symbols, reading immediately
6ac33a4e
TT
13963@item symbol-file @r{[} -readnow @r{]} @var{filename}
13964@itemx file @r{[} -readnow @r{]} @var{filename}
c906108c
SS
13965You can override the @value{GDBN} two-stage strategy for reading symbol
13966tables by using the @samp{-readnow} option with any of the commands that
13967load symbol table information, if you want to be sure @value{GDBN} has the
5d161b24 13968entire symbol table available.
c906108c 13969
c906108c
SS
13970@c FIXME: for now no mention of directories, since this seems to be in
13971@c flux. 13mar1992 status is that in theory GDB would look either in
13972@c current dir or in same dir as myprog; but issues like competing
13973@c GDB's, or clutter in system dirs, mean that in practice right now
13974@c only current dir is used. FFish says maybe a special GDB hierarchy
13975@c (eg rooted in val of env var GDBSYMS) could exist for mappable symbol
13976@c files.
13977
c906108c 13978@kindex core-file
09d4efe1 13979@item core-file @r{[}@var{filename}@r{]}
4644b6e3 13980@itemx core
c906108c
SS
13981Specify the whereabouts of a core dump file to be used as the ``contents
13982of memory''. Traditionally, core files contain only some parts of the
13983address space of the process that generated them; @value{GDBN} can access the
13984executable file itself for other parts.
13985
13986@code{core-file} with no argument specifies that no core file is
13987to be used.
13988
13989Note that the core file is ignored when your program is actually running
7a292a7a
SS
13990under @value{GDBN}. So, if you have been running your program and you
13991wish to debug a core file instead, you must kill the subprocess in which
13992the program is running. To do this, use the @code{kill} command
79a6e687 13993(@pxref{Kill Process, ,Killing the Child Process}).
c906108c 13994
c906108c
SS
13995@kindex add-symbol-file
13996@cindex dynamic linking
13997@item add-symbol-file @var{filename} @var{address}
a94ab193 13998@itemx add-symbol-file @var{filename} @var{address} @r{[} -readnow @r{]}
17d9d558 13999@itemx add-symbol-file @var{filename} @r{-s}@var{section} @var{address} @dots{}
96a2c332
SS
14000The @code{add-symbol-file} command reads additional symbol table
14001information from the file @var{filename}. You would use this command
14002when @var{filename} has been dynamically loaded (by some other means)
14003into the program that is running. @var{address} should be the memory
14004address at which the file has been loaded; @value{GDBN} cannot figure
d167840f
EZ
14005this out for itself. You can additionally specify an arbitrary number
14006of @samp{@r{-s}@var{section} @var{address}} pairs, to give an explicit
14007section name and base address for that section. You can specify any
14008@var{address} as an expression.
c906108c
SS
14009
14010The symbol table of the file @var{filename} is added to the symbol table
14011originally read with the @code{symbol-file} command. You can use the
96a2c332
SS
14012@code{add-symbol-file} command any number of times; the new symbol data
14013thus read keeps adding to the old. To discard all old symbol data
14014instead, use the @code{symbol-file} command without any arguments.
c906108c 14015
17d9d558
JB
14016@cindex relocatable object files, reading symbols from
14017@cindex object files, relocatable, reading symbols from
14018@cindex reading symbols from relocatable object files
14019@cindex symbols, reading from relocatable object files
14020@cindex @file{.o} files, reading symbols from
14021Although @var{filename} is typically a shared library file, an
14022executable file, or some other object file which has been fully
14023relocated for loading into a process, you can also load symbolic
14024information from relocatable @file{.o} files, as long as:
14025
14026@itemize @bullet
14027@item
14028the file's symbolic information refers only to linker symbols defined in
14029that file, not to symbols defined by other object files,
14030@item
14031every section the file's symbolic information refers to has actually
14032been loaded into the inferior, as it appears in the file, and
14033@item
14034you can determine the address at which every section was loaded, and
14035provide these to the @code{add-symbol-file} command.
14036@end itemize
14037
14038@noindent
14039Some embedded operating systems, like Sun Chorus and VxWorks, can load
14040relocatable files into an already running program; such systems
14041typically make the requirements above easy to meet. However, it's
14042important to recognize that many native systems use complex link
49efadf5 14043procedures (@code{.linkonce} section factoring and C@t{++} constructor table
17d9d558
JB
14044assembly, for example) that make the requirements difficult to meet. In
14045general, one cannot assume that using @code{add-symbol-file} to read a
14046relocatable object file's symbolic information will have the same effect
14047as linking the relocatable object file into the program in the normal
14048way.
14049
c906108c
SS
14050@code{add-symbol-file} does not repeat if you press @key{RET} after using it.
14051
c45da7e6
EZ
14052@kindex add-symbol-file-from-memory
14053@cindex @code{syscall DSO}
14054@cindex load symbols from memory
14055@item add-symbol-file-from-memory @var{address}
14056Load symbols from the given @var{address} in a dynamically loaded
14057object file whose image is mapped directly into the inferior's memory.
14058For example, the Linux kernel maps a @code{syscall DSO} into each
14059process's address space; this DSO provides kernel-specific code for
14060some system calls. The argument can be any expression whose
14061evaluation yields the address of the file's shared object file header.
14062For this command to work, you must have used @code{symbol-file} or
14063@code{exec-file} commands in advance.
14064
09d4efe1
EZ
14065@kindex add-shared-symbol-files
14066@kindex assf
14067@item add-shared-symbol-files @var{library-file}
14068@itemx assf @var{library-file}
14069The @code{add-shared-symbol-files} command can currently be used only
14070in the Cygwin build of @value{GDBN} on MS-Windows OS, where it is an
14071alias for the @code{dll-symbols} command (@pxref{Cygwin Native}).
14072@value{GDBN} automatically looks for shared libraries, however if
14073@value{GDBN} does not find yours, you can invoke
14074@code{add-shared-symbol-files}. It takes one argument: the shared
14075library's file name. @code{assf} is a shorthand alias for
14076@code{add-shared-symbol-files}.
c906108c 14077
c906108c 14078@kindex section
09d4efe1
EZ
14079@item section @var{section} @var{addr}
14080The @code{section} command changes the base address of the named
14081@var{section} of the exec file to @var{addr}. This can be used if the
14082exec file does not contain section addresses, (such as in the
14083@code{a.out} format), or when the addresses specified in the file
14084itself are wrong. Each section must be changed separately. The
14085@code{info files} command, described below, lists all the sections and
14086their addresses.
c906108c
SS
14087
14088@kindex info files
14089@kindex info target
14090@item info files
14091@itemx info target
7a292a7a
SS
14092@code{info files} and @code{info target} are synonymous; both print the
14093current target (@pxref{Targets, ,Specifying a Debugging Target}),
14094including the names of the executable and core dump files currently in
14095use by @value{GDBN}, and the files from which symbols were loaded. The
14096command @code{help target} lists all possible targets rather than
14097current ones.
14098
fe95c787
MS
14099@kindex maint info sections
14100@item maint info sections
14101Another command that can give you extra information about program sections
14102is @code{maint info sections}. In addition to the section information
14103displayed by @code{info files}, this command displays the flags and file
14104offset of each section in the executable and core dump files. In addition,
14105@code{maint info sections} provides the following command options (which
14106may be arbitrarily combined):
14107
14108@table @code
14109@item ALLOBJ
14110Display sections for all loaded object files, including shared libraries.
14111@item @var{sections}
6600abed 14112Display info only for named @var{sections}.
fe95c787
MS
14113@item @var{section-flags}
14114Display info only for sections for which @var{section-flags} are true.
14115The section flags that @value{GDBN} currently knows about are:
14116@table @code
14117@item ALLOC
14118Section will have space allocated in the process when loaded.
14119Set for all sections except those containing debug information.
14120@item LOAD
14121Section will be loaded from the file into the child process memory.
14122Set for pre-initialized code and data, clear for @code{.bss} sections.
14123@item RELOC
14124Section needs to be relocated before loading.
14125@item READONLY
14126Section cannot be modified by the child process.
14127@item CODE
14128Section contains executable code only.
6600abed 14129@item DATA
fe95c787
MS
14130Section contains data only (no executable code).
14131@item ROM
14132Section will reside in ROM.
14133@item CONSTRUCTOR
14134Section contains data for constructor/destructor lists.
14135@item HAS_CONTENTS
14136Section is not empty.
14137@item NEVER_LOAD
14138An instruction to the linker to not output the section.
14139@item COFF_SHARED_LIBRARY
14140A notification to the linker that the section contains
14141COFF shared library information.
14142@item IS_COMMON
14143Section contains common symbols.
14144@end table
14145@end table
6763aef9 14146@kindex set trust-readonly-sections
9c16f35a 14147@cindex read-only sections
6763aef9
MS
14148@item set trust-readonly-sections on
14149Tell @value{GDBN} that readonly sections in your object file
6ca652b0 14150really are read-only (i.e.@: that their contents will not change).
6763aef9
MS
14151In that case, @value{GDBN} can fetch values from these sections
14152out of the object file, rather than from the target program.
14153For some targets (notably embedded ones), this can be a significant
14154enhancement to debugging performance.
14155
14156The default is off.
14157
14158@item set trust-readonly-sections off
15110bc3 14159Tell @value{GDBN} not to trust readonly sections. This means that
6763aef9
MS
14160the contents of the section might change while the program is running,
14161and must therefore be fetched from the target when needed.
9c16f35a
EZ
14162
14163@item show trust-readonly-sections
14164Show the current setting of trusting readonly sections.
c906108c
SS
14165@end table
14166
14167All file-specifying commands allow both absolute and relative file names
14168as arguments. @value{GDBN} always converts the file name to an absolute file
14169name and remembers it that way.
14170
c906108c 14171@cindex shared libraries
9cceb671
DJ
14172@anchor{Shared Libraries}
14173@value{GDBN} supports @sc{gnu}/Linux, MS-Windows, HP-UX, SunOS, SVr4, Irix,
9c16f35a 14174and IBM RS/6000 AIX shared libraries.
53a5351d 14175
9cceb671
DJ
14176On MS-Windows @value{GDBN} must be linked with the Expat library to support
14177shared libraries. @xref{Expat}.
14178
c906108c
SS
14179@value{GDBN} automatically loads symbol definitions from shared libraries
14180when you use the @code{run} command, or when you examine a core file.
14181(Before you issue the @code{run} command, @value{GDBN} does not understand
14182references to a function in a shared library, however---unless you are
14183debugging a core file).
53a5351d
JM
14184
14185On HP-UX, if the program loads a library explicitly, @value{GDBN}
14186automatically loads the symbols at the time of the @code{shl_load} call.
14187
c906108c
SS
14188@c FIXME: some @value{GDBN} release may permit some refs to undef
14189@c FIXME...symbols---eg in a break cmd---assuming they are from a shared
14190@c FIXME...lib; check this from time to time when updating manual
14191
b7209cb4
FF
14192There are times, however, when you may wish to not automatically load
14193symbol definitions from shared libraries, such as when they are
14194particularly large or there are many of them.
14195
14196To control the automatic loading of shared library symbols, use the
14197commands:
14198
14199@table @code
14200@kindex set auto-solib-add
14201@item set auto-solib-add @var{mode}
14202If @var{mode} is @code{on}, symbols from all shared object libraries
14203will be loaded automatically when the inferior begins execution, you
14204attach to an independently started inferior, or when the dynamic linker
14205informs @value{GDBN} that a new library has been loaded. If @var{mode}
14206is @code{off}, symbols must be loaded manually, using the
14207@code{sharedlibrary} command. The default value is @code{on}.
14208
dcaf7c2c
EZ
14209@cindex memory used for symbol tables
14210If your program uses lots of shared libraries with debug info that
14211takes large amounts of memory, you can decrease the @value{GDBN}
14212memory footprint by preventing it from automatically loading the
14213symbols from shared libraries. To that end, type @kbd{set
14214auto-solib-add off} before running the inferior, then load each
14215library whose debug symbols you do need with @kbd{sharedlibrary
d3e8051b 14216@var{regexp}}, where @var{regexp} is a regular expression that matches
dcaf7c2c
EZ
14217the libraries whose symbols you want to be loaded.
14218
b7209cb4
FF
14219@kindex show auto-solib-add
14220@item show auto-solib-add
14221Display the current autoloading mode.
14222@end table
14223
c45da7e6 14224@cindex load shared library
b7209cb4
FF
14225To explicitly load shared library symbols, use the @code{sharedlibrary}
14226command:
14227
c906108c
SS
14228@table @code
14229@kindex info sharedlibrary
14230@kindex info share
55333a84
DE
14231@item info share @var{regex}
14232@itemx info sharedlibrary @var{regex}
14233Print the names of the shared libraries which are currently loaded
14234that match @var{regex}. If @var{regex} is omitted then print
14235all shared libraries that are loaded.
c906108c
SS
14236
14237@kindex sharedlibrary
14238@kindex share
14239@item sharedlibrary @var{regex}
14240@itemx share @var{regex}
c906108c
SS
14241Load shared object library symbols for files matching a
14242Unix regular expression.
14243As with files loaded automatically, it only loads shared libraries
14244required by your program for a core file or after typing @code{run}. If
14245@var{regex} is omitted all shared libraries required by your program are
14246loaded.
c45da7e6
EZ
14247
14248@item nosharedlibrary
14249@kindex nosharedlibrary
14250@cindex unload symbols from shared libraries
14251Unload all shared object library symbols. This discards all symbols
14252that have been loaded from all shared libraries. Symbols from shared
14253libraries that were loaded by explicit user requests are not
14254discarded.
c906108c
SS
14255@end table
14256
721c2651
EZ
14257Sometimes you may wish that @value{GDBN} stops and gives you control
14258when any of shared library events happen. Use the @code{set
14259stop-on-solib-events} command for this:
14260
14261@table @code
14262@item set stop-on-solib-events
14263@kindex set stop-on-solib-events
14264This command controls whether @value{GDBN} should give you control
14265when the dynamic linker notifies it about some shared library event.
14266The most common event of interest is loading or unloading of a new
14267shared library.
14268
14269@item show stop-on-solib-events
14270@kindex show stop-on-solib-events
14271Show whether @value{GDBN} stops and gives you control when shared
14272library events happen.
14273@end table
14274
f5ebfba0 14275Shared libraries are also supported in many cross or remote debugging
f1838a98
UW
14276configurations. @value{GDBN} needs to have access to the target's libraries;
14277this can be accomplished either by providing copies of the libraries
14278on the host system, or by asking @value{GDBN} to automatically retrieve the
14279libraries from the target. If copies of the target libraries are
14280provided, they need to be the same as the target libraries, although the
f5ebfba0
DJ
14281copies on the target can be stripped as long as the copies on the host are
14282not.
14283
59b7b46f
EZ
14284@cindex where to look for shared libraries
14285For remote debugging, you need to tell @value{GDBN} where the target
14286libraries are, so that it can load the correct copies---otherwise, it
14287may try to load the host's libraries. @value{GDBN} has two variables
14288to specify the search directories for target libraries.
f5ebfba0
DJ
14289
14290@table @code
59b7b46f 14291@cindex prefix for shared library file names
f822c95b 14292@cindex system root, alternate
f5ebfba0 14293@kindex set solib-absolute-prefix
f822c95b
DJ
14294@kindex set sysroot
14295@item set sysroot @var{path}
14296Use @var{path} as the system root for the program being debugged. Any
14297absolute shared library paths will be prefixed with @var{path}; many
14298runtime loaders store the absolute paths to the shared library in the
14299target program's memory. If you use @code{set sysroot} to find shared
14300libraries, they need to be laid out in the same way that they are on
14301the target, with e.g.@: a @file{/lib} and @file{/usr/lib} hierarchy
14302under @var{path}.
14303
f1838a98
UW
14304If @var{path} starts with the sequence @file{remote:}, @value{GDBN} will
14305retrieve the target libraries from the remote system. This is only
14306supported when using a remote target that supports the @code{remote get}
14307command (@pxref{File Transfer,,Sending files to a remote system}).
14308The part of @var{path} following the initial @file{remote:}
14309(if present) is used as system root prefix on the remote file system.
14310@footnote{If you want to specify a local system root using a directory
14311that happens to be named @file{remote:}, you need to use some equivalent
14312variant of the name like @file{./remote:}.}
14313
f822c95b
DJ
14314The @code{set solib-absolute-prefix} command is an alias for @code{set
14315sysroot}.
14316
14317@cindex default system root
59b7b46f 14318@cindex @samp{--with-sysroot}
f822c95b
DJ
14319You can set the default system root by using the configure-time
14320@samp{--with-sysroot} option. If the system root is inside
14321@value{GDBN}'s configured binary prefix (set with @samp{--prefix} or
14322@samp{--exec-prefix}), then the default system root will be updated
14323automatically if the installed @value{GDBN} is moved to a new
14324location.
14325
14326@kindex show sysroot
14327@item show sysroot
f5ebfba0
DJ
14328Display the current shared library prefix.
14329
14330@kindex set solib-search-path
14331@item set solib-search-path @var{path}
f822c95b
DJ
14332If this variable is set, @var{path} is a colon-separated list of
14333directories to search for shared libraries. @samp{solib-search-path}
14334is used after @samp{sysroot} fails to locate the library, or if the
14335path to the library is relative instead of absolute. If you want to
14336use @samp{solib-search-path} instead of @samp{sysroot}, be sure to set
d3e8051b 14337@samp{sysroot} to a nonexistent directory to prevent @value{GDBN} from
f822c95b 14338finding your host's libraries. @samp{sysroot} is preferred; setting
d3e8051b 14339it to a nonexistent directory may interfere with automatic loading
f822c95b 14340of shared library symbols.
f5ebfba0
DJ
14341
14342@kindex show solib-search-path
14343@item show solib-search-path
14344Display the current shared library search path.
14345@end table
14346
5b5d99cf
JB
14347
14348@node Separate Debug Files
14349@section Debugging Information in Separate Files
14350@cindex separate debugging information files
14351@cindex debugging information in separate files
14352@cindex @file{.debug} subdirectories
14353@cindex debugging information directory, global
14354@cindex global debugging information directory
c7e83d54
EZ
14355@cindex build ID, and separate debugging files
14356@cindex @file{.build-id} directory
5b5d99cf
JB
14357
14358@value{GDBN} allows you to put a program's debugging information in a
14359file separate from the executable itself, in a way that allows
14360@value{GDBN} to find and load the debugging information automatically.
c7e83d54
EZ
14361Since debugging information can be very large---sometimes larger
14362than the executable code itself---some systems distribute debugging
5b5d99cf
JB
14363information for their executables in separate files, which users can
14364install only when they need to debug a problem.
14365
c7e83d54
EZ
14366@value{GDBN} supports two ways of specifying the separate debug info
14367file:
5b5d99cf
JB
14368
14369@itemize @bullet
14370@item
c7e83d54
EZ
14371The executable contains a @dfn{debug link} that specifies the name of
14372the separate debug info file. The separate debug file's name is
14373usually @file{@var{executable}.debug}, where @var{executable} is the
14374name of the corresponding executable file without leading directories
14375(e.g., @file{ls.debug} for @file{/usr/bin/ls}). In addition, the
99e008fe
EZ
14376debug link specifies a 32-bit @dfn{Cyclic Redundancy Check} (CRC)
14377checksum for the debug file, which @value{GDBN} uses to validate that
14378the executable and the debug file came from the same build.
c7e83d54
EZ
14379
14380@item
7e27a47a 14381The executable contains a @dfn{build ID}, a unique bit string that is
c7e83d54 14382also present in the corresponding debug info file. (This is supported
7e27a47a
EZ
14383only on some operating systems, notably those which use the ELF format
14384for binary files and the @sc{gnu} Binutils.) For more details about
14385this feature, see the description of the @option{--build-id}
14386command-line option in @ref{Options, , Command Line Options, ld.info,
14387The GNU Linker}. The debug info file's name is not specified
14388explicitly by the build ID, but can be computed from the build ID, see
14389below.
d3750b24
JK
14390@end itemize
14391
c7e83d54
EZ
14392Depending on the way the debug info file is specified, @value{GDBN}
14393uses two different methods of looking for the debug file:
d3750b24
JK
14394
14395@itemize @bullet
14396@item
c7e83d54
EZ
14397For the ``debug link'' method, @value{GDBN} looks up the named file in
14398the directory of the executable file, then in a subdirectory of that
14399directory named @file{.debug}, and finally under the global debug
14400directory, in a subdirectory whose name is identical to the leading
14401directories of the executable's absolute file name.
14402
14403@item
83f83d7f 14404For the ``build ID'' method, @value{GDBN} looks in the
c7e83d54
EZ
14405@file{.build-id} subdirectory of the global debug directory for a file
14406named @file{@var{nn}/@var{nnnnnnnn}.debug}, where @var{nn} are the
7e27a47a
EZ
14407first 2 hex characters of the build ID bit string, and @var{nnnnnnnn}
14408are the rest of the bit string. (Real build ID strings are 32 or more
14409hex characters, not 10.)
c7e83d54
EZ
14410@end itemize
14411
14412So, for example, suppose you ask @value{GDBN} to debug
7e27a47a
EZ
14413@file{/usr/bin/ls}, which has a debug link that specifies the
14414file @file{ls.debug}, and a build ID whose value in hex is
c7e83d54
EZ
14415@code{abcdef1234}. If the global debug directory is
14416@file{/usr/lib/debug}, then @value{GDBN} will look for the following
14417debug information files, in the indicated order:
14418
14419@itemize @minus
14420@item
14421@file{/usr/lib/debug/.build-id/ab/cdef1234.debug}
d3750b24 14422@item
c7e83d54 14423@file{/usr/bin/ls.debug}
5b5d99cf 14424@item
c7e83d54 14425@file{/usr/bin/.debug/ls.debug}
5b5d99cf 14426@item
c7e83d54 14427@file{/usr/lib/debug/usr/bin/ls.debug}.
5b5d99cf 14428@end itemize
5b5d99cf
JB
14429
14430You can set the global debugging info directory's name, and view the
14431name @value{GDBN} is currently using.
14432
14433@table @code
14434
14435@kindex set debug-file-directory
24ddea62
JK
14436@item set debug-file-directory @var{directories}
14437Set the directories which @value{GDBN} searches for separate debugging
14438information files to @var{directory}. Multiple directory components can be set
14439concatenating them by a directory separator.
5b5d99cf
JB
14440
14441@kindex show debug-file-directory
14442@item show debug-file-directory
24ddea62 14443Show the directories @value{GDBN} searches for separate debugging
5b5d99cf
JB
14444information files.
14445
14446@end table
14447
14448@cindex @code{.gnu_debuglink} sections
c7e83d54 14449@cindex debug link sections
5b5d99cf
JB
14450A debug link is a special section of the executable file named
14451@code{.gnu_debuglink}. The section must contain:
14452
14453@itemize
14454@item
14455A filename, with any leading directory components removed, followed by
14456a zero byte,
14457@item
14458zero to three bytes of padding, as needed to reach the next four-byte
14459boundary within the section, and
14460@item
14461a four-byte CRC checksum, stored in the same endianness used for the
14462executable file itself. The checksum is computed on the debugging
14463information file's full contents by the function given below, passing
14464zero as the @var{crc} argument.
14465@end itemize
14466
14467Any executable file format can carry a debug link, as long as it can
14468contain a section named @code{.gnu_debuglink} with the contents
14469described above.
14470
d3750b24 14471@cindex @code{.note.gnu.build-id} sections
c7e83d54 14472@cindex build ID sections
7e27a47a
EZ
14473The build ID is a special section in the executable file (and in other
14474ELF binary files that @value{GDBN} may consider). This section is
14475often named @code{.note.gnu.build-id}, but that name is not mandatory.
14476It contains unique identification for the built files---the ID remains
14477the same across multiple builds of the same build tree. The default
14478algorithm SHA1 produces 160 bits (40 hexadecimal characters) of the
14479content for the build ID string. The same section with an identical
14480value is present in the original built binary with symbols, in its
14481stripped variant, and in the separate debugging information file.
d3750b24 14482
5b5d99cf
JB
14483The debugging information file itself should be an ordinary
14484executable, containing a full set of linker symbols, sections, and
14485debugging information. The sections of the debugging information file
c7e83d54
EZ
14486should have the same names, addresses, and sizes as the original file,
14487but they need not contain any data---much like a @code{.bss} section
5b5d99cf
JB
14488in an ordinary executable.
14489
7e27a47a 14490The @sc{gnu} binary utilities (Binutils) package includes the
c7e83d54
EZ
14491@samp{objcopy} utility that can produce
14492the separated executable / debugging information file pairs using the
14493following commands:
14494
14495@smallexample
14496@kbd{objcopy --only-keep-debug foo foo.debug}
14497@kbd{strip -g foo}
c7e83d54
EZ
14498@end smallexample
14499
14500@noindent
14501These commands remove the debugging
83f83d7f
JK
14502information from the executable file @file{foo} and place it in the file
14503@file{foo.debug}. You can use the first, second or both methods to link the
14504two files:
14505
14506@itemize @bullet
14507@item
14508The debug link method needs the following additional command to also leave
14509behind a debug link in @file{foo}:
14510
14511@smallexample
14512@kbd{objcopy --add-gnu-debuglink=foo.debug foo}
14513@end smallexample
14514
14515Ulrich Drepper's @file{elfutils} package, starting with version 0.53, contains
d3750b24 14516a version of the @code{strip} command such that the command @kbd{strip foo -f
83f83d7f
JK
14517foo.debug} has the same functionality as the two @code{objcopy} commands and
14518the @code{ln -s} command above, together.
14519
14520@item
14521Build ID gets embedded into the main executable using @code{ld --build-id} or
14522the @value{NGCC} counterpart @code{gcc -Wl,--build-id}. Build ID support plus
14523compatibility fixes for debug files separation are present in @sc{gnu} binary
7e27a47a 14524utilities (Binutils) package since version 2.18.
83f83d7f
JK
14525@end itemize
14526
14527@noindent
d3750b24 14528
99e008fe
EZ
14529@cindex CRC algorithm definition
14530The CRC used in @code{.gnu_debuglink} is the CRC-32 defined in
14531IEEE 802.3 using the polynomial:
14532
14533@c TexInfo requires naked braces for multi-digit exponents for Tex
14534@c output, but this causes HTML output to barf. HTML has to be set using
14535@c raw commands. So we end up having to specify this equation in 2
14536@c different ways!
14537@ifhtml
14538@display
14539@html
14540 <em>x</em><sup>32</sup> + <em>x</em><sup>26</sup> + <em>x</em><sup>23</sup> + <em>x</em><sup>22</sup> + <em>x</em><sup>16</sup> + <em>x</em><sup>12</sup> + <em>x</em><sup>11</sup>
14541 + <em>x</em><sup>10</sup> + <em>x</em><sup>8</sup> + <em>x</em><sup>7</sup> + <em>x</em><sup>5</sup> + <em>x</em><sup>4</sup> + <em>x</em><sup>2</sup> + <em>x</em> + 1
14542@end html
14543@end display
14544@end ifhtml
14545@ifnothtml
14546@display
14547 @math{x^{32} + x^{26} + x^{23} + x^{22} + x^{16} + x^{12} + x^{11}}
14548 @math{+ x^{10} + x^8 + x^7 + x^5 + x^4 + x^2 + x + 1}
14549@end display
14550@end ifnothtml
14551
14552The function is computed byte at a time, taking the least
14553significant bit of each byte first. The initial pattern
14554@code{0xffffffff} is used, to ensure leading zeros affect the CRC and
14555the final result is inverted to ensure trailing zeros also affect the
14556CRC.
14557
14558@emph{Note:} This is the same CRC polynomial as used in handling the
14559@dfn{Remote Serial Protocol} @code{qCRC} packet (@pxref{Remote Protocol,
14560, @value{GDBN} Remote Serial Protocol}). However in the
14561case of the Remote Serial Protocol, the CRC is computed @emph{most}
14562significant bit first, and the result is not inverted, so trailing
14563zeros have no effect on the CRC value.
14564
14565To complete the description, we show below the code of the function
14566which produces the CRC used in @code{.gnu_debuglink}. Inverting the
14567initially supplied @code{crc} argument means that an initial call to
14568this function passing in zero will start computing the CRC using
14569@code{0xffffffff}.
5b5d99cf 14570
4644b6e3 14571@kindex gnu_debuglink_crc32
5b5d99cf
JB
14572@smallexample
14573unsigned long
14574gnu_debuglink_crc32 (unsigned long crc,
14575 unsigned char *buf, size_t len)
14576@{
14577 static const unsigned long crc32_table[256] =
14578 @{
14579 0x00000000, 0x77073096, 0xee0e612c, 0x990951ba, 0x076dc419,
14580 0x706af48f, 0xe963a535, 0x9e6495a3, 0x0edb8832, 0x79dcb8a4,
14581 0xe0d5e91e, 0x97d2d988, 0x09b64c2b, 0x7eb17cbd, 0xe7b82d07,
14582 0x90bf1d91, 0x1db71064, 0x6ab020f2, 0xf3b97148, 0x84be41de,
14583 0x1adad47d, 0x6ddde4eb, 0xf4d4b551, 0x83d385c7, 0x136c9856,
14584 0x646ba8c0, 0xfd62f97a, 0x8a65c9ec, 0x14015c4f, 0x63066cd9,
14585 0xfa0f3d63, 0x8d080df5, 0x3b6e20c8, 0x4c69105e, 0xd56041e4,
14586 0xa2677172, 0x3c03e4d1, 0x4b04d447, 0xd20d85fd, 0xa50ab56b,
14587 0x35b5a8fa, 0x42b2986c, 0xdbbbc9d6, 0xacbcf940, 0x32d86ce3,
14588 0x45df5c75, 0xdcd60dcf, 0xabd13d59, 0x26d930ac, 0x51de003a,
14589 0xc8d75180, 0xbfd06116, 0x21b4f4b5, 0x56b3c423, 0xcfba9599,
14590 0xb8bda50f, 0x2802b89e, 0x5f058808, 0xc60cd9b2, 0xb10be924,
14591 0x2f6f7c87, 0x58684c11, 0xc1611dab, 0xb6662d3d, 0x76dc4190,
14592 0x01db7106, 0x98d220bc, 0xefd5102a, 0x71b18589, 0x06b6b51f,
14593 0x9fbfe4a5, 0xe8b8d433, 0x7807c9a2, 0x0f00f934, 0x9609a88e,
14594 0xe10e9818, 0x7f6a0dbb, 0x086d3d2d, 0x91646c97, 0xe6635c01,
14595 0x6b6b51f4, 0x1c6c6162, 0x856530d8, 0xf262004e, 0x6c0695ed,
14596 0x1b01a57b, 0x8208f4c1, 0xf50fc457, 0x65b0d9c6, 0x12b7e950,
14597 0x8bbeb8ea, 0xfcb9887c, 0x62dd1ddf, 0x15da2d49, 0x8cd37cf3,
14598 0xfbd44c65, 0x4db26158, 0x3ab551ce, 0xa3bc0074, 0xd4bb30e2,
14599 0x4adfa541, 0x3dd895d7, 0xa4d1c46d, 0xd3d6f4fb, 0x4369e96a,
14600 0x346ed9fc, 0xad678846, 0xda60b8d0, 0x44042d73, 0x33031de5,
14601 0xaa0a4c5f, 0xdd0d7cc9, 0x5005713c, 0x270241aa, 0xbe0b1010,
14602 0xc90c2086, 0x5768b525, 0x206f85b3, 0xb966d409, 0xce61e49f,
14603 0x5edef90e, 0x29d9c998, 0xb0d09822, 0xc7d7a8b4, 0x59b33d17,
14604 0x2eb40d81, 0xb7bd5c3b, 0xc0ba6cad, 0xedb88320, 0x9abfb3b6,
14605 0x03b6e20c, 0x74b1d29a, 0xead54739, 0x9dd277af, 0x04db2615,
14606 0x73dc1683, 0xe3630b12, 0x94643b84, 0x0d6d6a3e, 0x7a6a5aa8,
14607 0xe40ecf0b, 0x9309ff9d, 0x0a00ae27, 0x7d079eb1, 0xf00f9344,
14608 0x8708a3d2, 0x1e01f268, 0x6906c2fe, 0xf762575d, 0x806567cb,
14609 0x196c3671, 0x6e6b06e7, 0xfed41b76, 0x89d32be0, 0x10da7a5a,
14610 0x67dd4acc, 0xf9b9df6f, 0x8ebeeff9, 0x17b7be43, 0x60b08ed5,
14611 0xd6d6a3e8, 0xa1d1937e, 0x38d8c2c4, 0x4fdff252, 0xd1bb67f1,
14612 0xa6bc5767, 0x3fb506dd, 0x48b2364b, 0xd80d2bda, 0xaf0a1b4c,
14613 0x36034af6, 0x41047a60, 0xdf60efc3, 0xa867df55, 0x316e8eef,
14614 0x4669be79, 0xcb61b38c, 0xbc66831a, 0x256fd2a0, 0x5268e236,
14615 0xcc0c7795, 0xbb0b4703, 0x220216b9, 0x5505262f, 0xc5ba3bbe,
14616 0xb2bd0b28, 0x2bb45a92, 0x5cb36a04, 0xc2d7ffa7, 0xb5d0cf31,
14617 0x2cd99e8b, 0x5bdeae1d, 0x9b64c2b0, 0xec63f226, 0x756aa39c,
14618 0x026d930a, 0x9c0906a9, 0xeb0e363f, 0x72076785, 0x05005713,
14619 0x95bf4a82, 0xe2b87a14, 0x7bb12bae, 0x0cb61b38, 0x92d28e9b,
14620 0xe5d5be0d, 0x7cdcefb7, 0x0bdbdf21, 0x86d3d2d4, 0xf1d4e242,
14621 0x68ddb3f8, 0x1fda836e, 0x81be16cd, 0xf6b9265b, 0x6fb077e1,
14622 0x18b74777, 0x88085ae6, 0xff0f6a70, 0x66063bca, 0x11010b5c,
14623 0x8f659eff, 0xf862ae69, 0x616bffd3, 0x166ccf45, 0xa00ae278,
14624 0xd70dd2ee, 0x4e048354, 0x3903b3c2, 0xa7672661, 0xd06016f7,
14625 0x4969474d, 0x3e6e77db, 0xaed16a4a, 0xd9d65adc, 0x40df0b66,
14626 0x37d83bf0, 0xa9bcae53, 0xdebb9ec5, 0x47b2cf7f, 0x30b5ffe9,
14627 0xbdbdf21c, 0xcabac28a, 0x53b39330, 0x24b4a3a6, 0xbad03605,
14628 0xcdd70693, 0x54de5729, 0x23d967bf, 0xb3667a2e, 0xc4614ab8,
14629 0x5d681b02, 0x2a6f2b94, 0xb40bbe37, 0xc30c8ea1, 0x5a05df1b,
14630 0x2d02ef8d
14631 @};
14632 unsigned char *end;
14633
14634 crc = ~crc & 0xffffffff;
14635 for (end = buf + len; buf < end; ++buf)
14636 crc = crc32_table[(crc ^ *buf) & 0xff] ^ (crc >> 8);
e7a3abfc 14637 return ~crc & 0xffffffff;
5b5d99cf
JB
14638@}
14639@end smallexample
14640
c7e83d54
EZ
14641@noindent
14642This computation does not apply to the ``build ID'' method.
14643
5b5d99cf 14644
6d2ebf8b 14645@node Symbol Errors
79a6e687 14646@section Errors Reading Symbol Files
c906108c
SS
14647
14648While reading a symbol file, @value{GDBN} occasionally encounters problems,
14649such as symbol types it does not recognize, or known bugs in compiler
14650output. By default, @value{GDBN} does not notify you of such problems, since
14651they are relatively common and primarily of interest to people
14652debugging compilers. If you are interested in seeing information
14653about ill-constructed symbol tables, you can either ask @value{GDBN} to print
14654only one message about each such type of problem, no matter how many
14655times the problem occurs; or you can ask @value{GDBN} to print more messages,
14656to see how many times the problems occur, with the @code{set
79a6e687
BW
14657complaints} command (@pxref{Messages/Warnings, ,Optional Warnings and
14658Messages}).
c906108c
SS
14659
14660The messages currently printed, and their meanings, include:
14661
14662@table @code
14663@item inner block not inside outer block in @var{symbol}
14664
14665The symbol information shows where symbol scopes begin and end
14666(such as at the start of a function or a block of statements). This
14667error indicates that an inner scope block is not fully contained
14668in its outer scope blocks.
14669
14670@value{GDBN} circumvents the problem by treating the inner block as if it had
14671the same scope as the outer block. In the error message, @var{symbol}
14672may be shown as ``@code{(don't know)}'' if the outer block is not a
14673function.
14674
14675@item block at @var{address} out of order
14676
14677The symbol information for symbol scope blocks should occur in
14678order of increasing addresses. This error indicates that it does not
14679do so.
14680
14681@value{GDBN} does not circumvent this problem, and has trouble
14682locating symbols in the source file whose symbols it is reading. (You
14683can often determine what source file is affected by specifying
79a6e687
BW
14684@code{set verbose on}. @xref{Messages/Warnings, ,Optional Warnings and
14685Messages}.)
c906108c
SS
14686
14687@item bad block start address patched
14688
14689The symbol information for a symbol scope block has a start address
14690smaller than the address of the preceding source line. This is known
14691to occur in the SunOS 4.1.1 (and earlier) C compiler.
14692
14693@value{GDBN} circumvents the problem by treating the symbol scope block as
14694starting on the previous source line.
14695
14696@item bad string table offset in symbol @var{n}
14697
14698@cindex foo
14699Symbol number @var{n} contains a pointer into the string table which is
14700larger than the size of the string table.
14701
14702@value{GDBN} circumvents the problem by considering the symbol to have the
14703name @code{foo}, which may cause other problems if many symbols end up
14704with this name.
14705
14706@item unknown symbol type @code{0x@var{nn}}
14707
7a292a7a
SS
14708The symbol information contains new data types that @value{GDBN} does
14709not yet know how to read. @code{0x@var{nn}} is the symbol type of the
d4f3574e 14710uncomprehended information, in hexadecimal.
c906108c 14711
7a292a7a
SS
14712@value{GDBN} circumvents the error by ignoring this symbol information.
14713This usually allows you to debug your program, though certain symbols
c906108c 14714are not accessible. If you encounter such a problem and feel like
7a292a7a
SS
14715debugging it, you can debug @code{@value{GDBP}} with itself, breakpoint
14716on @code{complain}, then go up to the function @code{read_dbx_symtab}
14717and examine @code{*bufp} to see the symbol.
c906108c
SS
14718
14719@item stub type has NULL name
c906108c 14720
7a292a7a 14721@value{GDBN} could not find the full definition for a struct or class.
c906108c 14722
7a292a7a 14723@item const/volatile indicator missing (ok if using g++ v1.x), got@dots{}
b37052ae 14724The symbol information for a C@t{++} member function is missing some
7a292a7a
SS
14725information that recent versions of the compiler should have output for
14726it.
c906108c
SS
14727
14728@item info mismatch between compiler and debugger
14729
14730@value{GDBN} could not parse a type specification output by the compiler.
7a292a7a 14731
c906108c
SS
14732@end table
14733
b14b1491
TT
14734@node Data Files
14735@section GDB Data Files
14736
14737@cindex prefix for data files
14738@value{GDBN} will sometimes read an auxiliary data file. These files
14739are kept in a directory known as the @dfn{data directory}.
14740
14741You can set the data directory's name, and view the name @value{GDBN}
14742is currently using.
14743
14744@table @code
14745@kindex set data-directory
14746@item set data-directory @var{directory}
14747Set the directory which @value{GDBN} searches for auxiliary data files
14748to @var{directory}.
14749
14750@kindex show data-directory
14751@item show data-directory
14752Show the directory @value{GDBN} searches for auxiliary data files.
14753@end table
14754
14755@cindex default data directory
14756@cindex @samp{--with-gdb-datadir}
14757You can set the default data directory by using the configure-time
14758@samp{--with-gdb-datadir} option. If the data directory is inside
14759@value{GDBN}'s configured binary prefix (set with @samp{--prefix} or
14760@samp{--exec-prefix}), then the default data directory will be updated
14761automatically if the installed @value{GDBN} is moved to a new
14762location.
14763
6d2ebf8b 14764@node Targets
c906108c 14765@chapter Specifying a Debugging Target
7a292a7a 14766
c906108c 14767@cindex debugging target
c906108c 14768A @dfn{target} is the execution environment occupied by your program.
53a5351d
JM
14769
14770Often, @value{GDBN} runs in the same host environment as your program;
14771in that case, the debugging target is specified as a side effect when
14772you use the @code{file} or @code{core} commands. When you need more
c906108c
SS
14773flexibility---for example, running @value{GDBN} on a physically separate
14774host, or controlling a standalone system over a serial port or a
53a5351d
JM
14775realtime system over a TCP/IP connection---you can use the @code{target}
14776command to specify one of the target types configured for @value{GDBN}
79a6e687 14777(@pxref{Target Commands, ,Commands for Managing Targets}).
c906108c 14778
a8f24a35
EZ
14779@cindex target architecture
14780It is possible to build @value{GDBN} for several different @dfn{target
14781architectures}. When @value{GDBN} is built like that, you can choose
14782one of the available architectures with the @kbd{set architecture}
14783command.
14784
14785@table @code
14786@kindex set architecture
14787@kindex show architecture
14788@item set architecture @var{arch}
14789This command sets the current target architecture to @var{arch}. The
14790value of @var{arch} can be @code{"auto"}, in addition to one of the
14791supported architectures.
14792
14793@item show architecture
14794Show the current target architecture.
9c16f35a
EZ
14795
14796@item set processor
14797@itemx processor
14798@kindex set processor
14799@kindex show processor
14800These are alias commands for, respectively, @code{set architecture}
14801and @code{show architecture}.
a8f24a35
EZ
14802@end table
14803
c906108c
SS
14804@menu
14805* Active Targets:: Active targets
14806* Target Commands:: Commands for managing targets
c906108c 14807* Byte Order:: Choosing target byte order
c906108c
SS
14808@end menu
14809
6d2ebf8b 14810@node Active Targets
79a6e687 14811@section Active Targets
7a292a7a 14812
c906108c
SS
14813@cindex stacking targets
14814@cindex active targets
14815@cindex multiple targets
14816
c906108c 14817There are three classes of targets: processes, core files, and
7a292a7a
SS
14818executable files. @value{GDBN} can work concurrently on up to three
14819active targets, one in each class. This allows you to (for example)
14820start a process and inspect its activity without abandoning your work on
14821a core file.
c906108c
SS
14822
14823For example, if you execute @samp{gdb a.out}, then the executable file
14824@code{a.out} is the only active target. If you designate a core file as
14825well---presumably from a prior run that crashed and coredumped---then
14826@value{GDBN} has two active targets and uses them in tandem, looking
14827first in the corefile target, then in the executable file, to satisfy
14828requests for memory addresses. (Typically, these two classes of target
14829are complementary, since core files contain only a program's
14830read-write memory---variables and so on---plus machine status, while
14831executable files contain only the program text and initialized data.)
c906108c
SS
14832
14833When you type @code{run}, your executable file becomes an active process
7a292a7a
SS
14834target as well. When a process target is active, all @value{GDBN}
14835commands requesting memory addresses refer to that target; addresses in
14836an active core file or executable file target are obscured while the
14837process target is active.
c906108c 14838
7a292a7a 14839Use the @code{core-file} and @code{exec-file} commands to select a new
79a6e687
BW
14840core file or executable target (@pxref{Files, ,Commands to Specify
14841Files}). To specify as a target a process that is already running, use
14842the @code{attach} command (@pxref{Attach, ,Debugging an Already-running
14843Process}).
c906108c 14844
6d2ebf8b 14845@node Target Commands
79a6e687 14846@section Commands for Managing Targets
c906108c
SS
14847
14848@table @code
14849@item target @var{type} @var{parameters}
7a292a7a
SS
14850Connects the @value{GDBN} host environment to a target machine or
14851process. A target is typically a protocol for talking to debugging
14852facilities. You use the argument @var{type} to specify the type or
14853protocol of the target machine.
c906108c
SS
14854
14855Further @var{parameters} are interpreted by the target protocol, but
14856typically include things like device names or host names to connect
14857with, process numbers, and baud rates.
c906108c
SS
14858
14859The @code{target} command does not repeat if you press @key{RET} again
14860after executing the command.
14861
14862@kindex help target
14863@item help target
14864Displays the names of all targets available. To display targets
14865currently selected, use either @code{info target} or @code{info files}
79a6e687 14866(@pxref{Files, ,Commands to Specify Files}).
c906108c
SS
14867
14868@item help target @var{name}
14869Describe a particular target, including any parameters necessary to
14870select it.
14871
14872@kindex set gnutarget
14873@item set gnutarget @var{args}
5d161b24 14874@value{GDBN} uses its own library BFD to read your files. @value{GDBN}
c906108c 14875knows whether it is reading an @dfn{executable},
5d161b24
DB
14876a @dfn{core}, or a @dfn{.o} file; however, you can specify the file format
14877with the @code{set gnutarget} command. Unlike most @code{target} commands,
c906108c
SS
14878with @code{gnutarget} the @code{target} refers to a program, not a machine.
14879
d4f3574e 14880@quotation
c906108c
SS
14881@emph{Warning:} To specify a file format with @code{set gnutarget},
14882you must know the actual BFD name.
d4f3574e 14883@end quotation
c906108c 14884
d4f3574e 14885@noindent
79a6e687 14886@xref{Files, , Commands to Specify Files}.
c906108c 14887
5d161b24 14888@kindex show gnutarget
c906108c
SS
14889@item show gnutarget
14890Use the @code{show gnutarget} command to display what file format
14891@code{gnutarget} is set to read. If you have not set @code{gnutarget},
14892@value{GDBN} will determine the file format for each file automatically,
14893and @code{show gnutarget} displays @samp{The current BDF target is "auto"}.
14894@end table
14895
4644b6e3 14896@cindex common targets
c906108c
SS
14897Here are some common targets (available, or not, depending on the GDB
14898configuration):
c906108c
SS
14899
14900@table @code
4644b6e3 14901@kindex target
c906108c 14902@item target exec @var{program}
4644b6e3 14903@cindex executable file target
c906108c
SS
14904An executable file. @samp{target exec @var{program}} is the same as
14905@samp{exec-file @var{program}}.
14906
c906108c 14907@item target core @var{filename}
4644b6e3 14908@cindex core dump file target
c906108c
SS
14909A core dump file. @samp{target core @var{filename}} is the same as
14910@samp{core-file @var{filename}}.
c906108c 14911
1a10341b 14912@item target remote @var{medium}
4644b6e3 14913@cindex remote target
1a10341b
JB
14914A remote system connected to @value{GDBN} via a serial line or network
14915connection. This command tells @value{GDBN} to use its own remote
14916protocol over @var{medium} for debugging. @xref{Remote Debugging}.
14917
14918For example, if you have a board connected to @file{/dev/ttya} on the
14919machine running @value{GDBN}, you could say:
14920
14921@smallexample
14922target remote /dev/ttya
14923@end smallexample
14924
14925@code{target remote} supports the @code{load} command. This is only
14926useful if you have some other way of getting the stub to the target
14927system, and you can put it somewhere in memory where it won't get
14928clobbered by the download.
c906108c 14929
ee8e71d4 14930@item target sim @r{[}@var{simargs}@r{]} @dots{}
4644b6e3 14931@cindex built-in simulator target
2df3850c 14932Builtin CPU simulator. @value{GDBN} includes simulators for most architectures.
104c1213 14933In general,
474c8240 14934@smallexample
104c1213
JM
14935 target sim
14936 load
14937 run
474c8240 14938@end smallexample
d4f3574e 14939@noindent
104c1213 14940works; however, you cannot assume that a specific memory map, device
d4f3574e 14941drivers, or even basic I/O is available, although some simulators do
104c1213
JM
14942provide these. For info about any processor-specific simulator details,
14943see the appropriate section in @ref{Embedded Processors, ,Embedded
14944Processors}.
14945
c906108c
SS
14946@end table
14947
104c1213 14948Some configurations may include these targets as well:
c906108c
SS
14949
14950@table @code
14951
c906108c 14952@item target nrom @var{dev}
4644b6e3 14953@cindex NetROM ROM emulator target
c906108c
SS
14954NetROM ROM emulator. This target only supports downloading.
14955
c906108c
SS
14956@end table
14957
5d161b24 14958Different targets are available on different configurations of @value{GDBN};
c906108c 14959your configuration may have more or fewer targets.
c906108c 14960
721c2651
EZ
14961Many remote targets require you to download the executable's code once
14962you've successfully established a connection. You may wish to control
3d00d119
DJ
14963various aspects of this process.
14964
14965@table @code
721c2651
EZ
14966
14967@item set hash
14968@kindex set hash@r{, for remote monitors}
14969@cindex hash mark while downloading
14970This command controls whether a hash mark @samp{#} is displayed while
14971downloading a file to the remote monitor. If on, a hash mark is
14972displayed after each S-record is successfully downloaded to the
14973monitor.
14974
14975@item show hash
14976@kindex show hash@r{, for remote monitors}
14977Show the current status of displaying the hash mark.
14978
14979@item set debug monitor
14980@kindex set debug monitor
14981@cindex display remote monitor communications
14982Enable or disable display of communications messages between
14983@value{GDBN} and the remote monitor.
14984
14985@item show debug monitor
14986@kindex show debug monitor
14987Show the current status of displaying communications between
14988@value{GDBN} and the remote monitor.
a8f24a35 14989@end table
c906108c
SS
14990
14991@table @code
14992
14993@kindex load @var{filename}
14994@item load @var{filename}
8edfe269 14995@anchor{load}
c906108c
SS
14996Depending on what remote debugging facilities are configured into
14997@value{GDBN}, the @code{load} command may be available. Where it exists, it
14998is meant to make @var{filename} (an executable) available for debugging
14999on the remote system---by downloading, or dynamic linking, for example.
15000@code{load} also records the @var{filename} symbol table in @value{GDBN}, like
15001the @code{add-symbol-file} command.
15002
15003If your @value{GDBN} does not have a @code{load} command, attempting to
15004execute it gets the error message ``@code{You can't do that when your
15005target is @dots{}}''
c906108c
SS
15006
15007The file is loaded at whatever address is specified in the executable.
15008For some object file formats, you can specify the load address when you
15009link the program; for other formats, like a.out, the object file format
15010specifies a fixed address.
15011@c FIXME! This would be a good place for an xref to the GNU linker doc.
15012
68437a39
DJ
15013Depending on the remote side capabilities, @value{GDBN} may be able to
15014load programs into flash memory.
15015
c906108c
SS
15016@code{load} does not repeat if you press @key{RET} again after using it.
15017@end table
15018
6d2ebf8b 15019@node Byte Order
79a6e687 15020@section Choosing Target Byte Order
7a292a7a 15021
c906108c
SS
15022@cindex choosing target byte order
15023@cindex target byte order
c906108c 15024
172c2a43 15025Some types of processors, such as the MIPS, PowerPC, and Renesas SH,
c906108c
SS
15026offer the ability to run either big-endian or little-endian byte
15027orders. Usually the executable or symbol will include a bit to
15028designate the endian-ness, and you will not need to worry about
15029which to use. However, you may still find it useful to adjust
d4f3574e 15030@value{GDBN}'s idea of processor endian-ness manually.
c906108c
SS
15031
15032@table @code
4644b6e3 15033@kindex set endian
c906108c
SS
15034@item set endian big
15035Instruct @value{GDBN} to assume the target is big-endian.
15036
c906108c
SS
15037@item set endian little
15038Instruct @value{GDBN} to assume the target is little-endian.
15039
c906108c
SS
15040@item set endian auto
15041Instruct @value{GDBN} to use the byte order associated with the
15042executable.
15043
15044@item show endian
15045Display @value{GDBN}'s current idea of the target byte order.
15046
15047@end table
15048
15049Note that these commands merely adjust interpretation of symbolic
15050data on the host, and that they have absolutely no effect on the
15051target system.
15052
ea35711c
DJ
15053
15054@node Remote Debugging
15055@chapter Debugging Remote Programs
c906108c
SS
15056@cindex remote debugging
15057
15058If you are trying to debug a program running on a machine that cannot run
5d161b24
DB
15059@value{GDBN} in the usual way, it is often useful to use remote debugging.
15060For example, you might use remote debugging on an operating system kernel,
c906108c
SS
15061or on a small system which does not have a general purpose operating system
15062powerful enough to run a full-featured debugger.
15063
15064Some configurations of @value{GDBN} have special serial or TCP/IP interfaces
15065to make this work with particular debugging targets. In addition,
5d161b24 15066@value{GDBN} comes with a generic serial protocol (specific to @value{GDBN},
c906108c
SS
15067but not specific to any particular target system) which you can use if you
15068write the remote stubs---the code that runs on the remote system to
15069communicate with @value{GDBN}.
15070
15071Other remote targets may be available in your
15072configuration of @value{GDBN}; use @code{help target} to list them.
c906108c 15073
6b2f586d 15074@menu
07f31aa6 15075* Connecting:: Connecting to a remote target
a6b151f1 15076* File Transfer:: Sending files to a remote system
6b2f586d 15077* Server:: Using the gdbserver program
79a6e687
BW
15078* Remote Configuration:: Remote configuration
15079* Remote Stub:: Implementing a remote stub
6b2f586d
AC
15080@end menu
15081
07f31aa6 15082@node Connecting
79a6e687 15083@section Connecting to a Remote Target
07f31aa6
DJ
15084
15085On the @value{GDBN} host machine, you will need an unstripped copy of
d3e8051b 15086your program, since @value{GDBN} needs symbol and debugging information.
07f31aa6
DJ
15087Start up @value{GDBN} as usual, using the name of the local copy of your
15088program as the first argument.
15089
86941c27
JB
15090@cindex @code{target remote}
15091@value{GDBN} can communicate with the target over a serial line, or
15092over an @acronym{IP} network using @acronym{TCP} or @acronym{UDP}. In
15093each case, @value{GDBN} uses the same protocol for debugging your
15094program; only the medium carrying the debugging packets varies. The
15095@code{target remote} command establishes a connection to the target.
15096Its arguments indicate which medium to use:
15097
15098@table @code
15099
15100@item target remote @var{serial-device}
07f31aa6 15101@cindex serial line, @code{target remote}
86941c27
JB
15102Use @var{serial-device} to communicate with the target. For example,
15103to use a serial line connected to the device named @file{/dev/ttyb}:
15104
15105@smallexample
15106target remote /dev/ttyb
15107@end smallexample
15108
07f31aa6
DJ
15109If you're using a serial line, you may want to give @value{GDBN} the
15110@w{@samp{--baud}} option, or use the @code{set remotebaud} command
79a6e687 15111(@pxref{Remote Configuration, set remotebaud}) before the
9c16f35a 15112@code{target} command.
07f31aa6 15113
86941c27
JB
15114@item target remote @code{@var{host}:@var{port}}
15115@itemx target remote @code{tcp:@var{host}:@var{port}}
15116@cindex @acronym{TCP} port, @code{target remote}
15117Debug using a @acronym{TCP} connection to @var{port} on @var{host}.
15118The @var{host} may be either a host name or a numeric @acronym{IP}
15119address; @var{port} must be a decimal number. The @var{host} could be
15120the target machine itself, if it is directly connected to the net, or
15121it might be a terminal server which in turn has a serial line to the
15122target.
07f31aa6 15123
86941c27
JB
15124For example, to connect to port 2828 on a terminal server named
15125@code{manyfarms}:
07f31aa6
DJ
15126
15127@smallexample
15128target remote manyfarms:2828
15129@end smallexample
15130
86941c27
JB
15131If your remote target is actually running on the same machine as your
15132debugger session (e.g.@: a simulator for your target running on the
15133same host), you can omit the hostname. For example, to connect to
15134port 1234 on your local machine:
07f31aa6
DJ
15135
15136@smallexample
15137target remote :1234
15138@end smallexample
15139@noindent
15140
15141Note that the colon is still required here.
15142
86941c27
JB
15143@item target remote @code{udp:@var{host}:@var{port}}
15144@cindex @acronym{UDP} port, @code{target remote}
15145Debug using @acronym{UDP} packets to @var{port} on @var{host}. For example, to
15146connect to @acronym{UDP} port 2828 on a terminal server named @code{manyfarms}:
07f31aa6
DJ
15147
15148@smallexample
15149target remote udp:manyfarms:2828
15150@end smallexample
15151
86941c27
JB
15152When using a @acronym{UDP} connection for remote debugging, you should
15153keep in mind that the `U' stands for ``Unreliable''. @acronym{UDP}
15154can silently drop packets on busy or unreliable networks, which will
15155cause havoc with your debugging session.
15156
66b8c7f6
JB
15157@item target remote | @var{command}
15158@cindex pipe, @code{target remote} to
15159Run @var{command} in the background and communicate with it using a
15160pipe. The @var{command} is a shell command, to be parsed and expanded
15161by the system's command shell, @code{/bin/sh}; it should expect remote
15162protocol packets on its standard input, and send replies on its
15163standard output. You could use this to run a stand-alone simulator
15164that speaks the remote debugging protocol, to make net connections
15165using programs like @code{ssh}, or for other similar tricks.
15166
15167If @var{command} closes its standard output (perhaps by exiting),
15168@value{GDBN} will try to send it a @code{SIGTERM} signal. (If the
15169program has already exited, this will have no effect.)
15170
86941c27 15171@end table
07f31aa6 15172
86941c27 15173Once the connection has been established, you can use all the usual
8edfe269
DJ
15174commands to examine and change data. The remote program is already
15175running; you can use @kbd{step} and @kbd{continue}, and you do not
15176need to use @kbd{run}.
07f31aa6
DJ
15177
15178@cindex interrupting remote programs
15179@cindex remote programs, interrupting
15180Whenever @value{GDBN} is waiting for the remote program, if you type the
c8aa23ab 15181interrupt character (often @kbd{Ctrl-c}), @value{GDBN} attempts to stop the
07f31aa6
DJ
15182program. This may or may not succeed, depending in part on the hardware
15183and the serial drivers the remote system uses. If you type the
15184interrupt character once again, @value{GDBN} displays this prompt:
15185
15186@smallexample
15187Interrupted while waiting for the program.
15188Give up (and stop debugging it)? (y or n)
15189@end smallexample
15190
15191If you type @kbd{y}, @value{GDBN} abandons the remote debugging session.
15192(If you decide you want to try again later, you can use @samp{target
15193remote} again to connect once more.) If you type @kbd{n}, @value{GDBN}
15194goes back to waiting.
15195
15196@table @code
15197@kindex detach (remote)
15198@item detach
15199When you have finished debugging the remote program, you can use the
15200@code{detach} command to release it from @value{GDBN} control.
15201Detaching from the target normally resumes its execution, but the results
15202will depend on your particular remote stub. After the @code{detach}
15203command, @value{GDBN} is free to connect to another target.
15204
15205@kindex disconnect
15206@item disconnect
15207The @code{disconnect} command behaves like @code{detach}, except that
15208the target is generally not resumed. It will wait for @value{GDBN}
15209(this instance or another one) to connect and continue debugging. After
15210the @code{disconnect} command, @value{GDBN} is again free to connect to
15211another target.
09d4efe1
EZ
15212
15213@cindex send command to remote monitor
fad38dfa
EZ
15214@cindex extend @value{GDBN} for remote targets
15215@cindex add new commands for external monitor
09d4efe1
EZ
15216@kindex monitor
15217@item monitor @var{cmd}
fad38dfa
EZ
15218This command allows you to send arbitrary commands directly to the
15219remote monitor. Since @value{GDBN} doesn't care about the commands it
15220sends like this, this command is the way to extend @value{GDBN}---you
15221can add new commands that only the external monitor will understand
15222and implement.
07f31aa6
DJ
15223@end table
15224
a6b151f1
DJ
15225@node File Transfer
15226@section Sending files to a remote system
15227@cindex remote target, file transfer
15228@cindex file transfer
15229@cindex sending files to remote systems
15230
15231Some remote targets offer the ability to transfer files over the same
15232connection used to communicate with @value{GDBN}. This is convenient
15233for targets accessible through other means, e.g.@: @sc{gnu}/Linux systems
15234running @code{gdbserver} over a network interface. For other targets,
15235e.g.@: embedded devices with only a single serial port, this may be
15236the only way to upload or download files.
15237
15238Not all remote targets support these commands.
15239
15240@table @code
15241@kindex remote put
15242@item remote put @var{hostfile} @var{targetfile}
15243Copy file @var{hostfile} from the host system (the machine running
15244@value{GDBN}) to @var{targetfile} on the target system.
15245
15246@kindex remote get
15247@item remote get @var{targetfile} @var{hostfile}
15248Copy file @var{targetfile} from the target system to @var{hostfile}
15249on the host system.
15250
15251@kindex remote delete
15252@item remote delete @var{targetfile}
15253Delete @var{targetfile} from the target system.
15254
15255@end table
15256
6f05cf9f 15257@node Server
79a6e687 15258@section Using the @code{gdbserver} Program
6f05cf9f
AC
15259
15260@kindex gdbserver
15261@cindex remote connection without stubs
15262@code{gdbserver} is a control program for Unix-like systems, which
15263allows you to connect your program with a remote @value{GDBN} via
15264@code{target remote}---but without linking in the usual debugging stub.
15265
15266@code{gdbserver} is not a complete replacement for the debugging stubs,
15267because it requires essentially the same operating-system facilities
15268that @value{GDBN} itself does. In fact, a system that can run
15269@code{gdbserver} to connect to a remote @value{GDBN} could also run
15270@value{GDBN} locally! @code{gdbserver} is sometimes useful nevertheless,
15271because it is a much smaller program than @value{GDBN} itself. It is
15272also easier to port than all of @value{GDBN}, so you may be able to get
15273started more quickly on a new system by using @code{gdbserver}.
15274Finally, if you develop code for real-time systems, you may find that
15275the tradeoffs involved in real-time operation make it more convenient to
15276do as much development work as possible on another system, for example
15277by cross-compiling. You can use @code{gdbserver} to make a similar
15278choice for debugging.
15279
15280@value{GDBN} and @code{gdbserver} communicate via either a serial line
15281or a TCP connection, using the standard @value{GDBN} remote serial
15282protocol.
15283
2d717e4f
DJ
15284@quotation
15285@emph{Warning:} @code{gdbserver} does not have any built-in security.
15286Do not run @code{gdbserver} connected to any public network; a
15287@value{GDBN} connection to @code{gdbserver} provides access to the
15288target system with the same privileges as the user running
15289@code{gdbserver}.
15290@end quotation
15291
15292@subsection Running @code{gdbserver}
15293@cindex arguments, to @code{gdbserver}
15294
15295Run @code{gdbserver} on the target system. You need a copy of the
15296program you want to debug, including any libraries it requires.
6f05cf9f
AC
15297@code{gdbserver} does not need your program's symbol table, so you can
15298strip the program if necessary to save space. @value{GDBN} on the host
15299system does all the symbol handling.
15300
15301To use the server, you must tell it how to communicate with @value{GDBN};
56460a61 15302the name of your program; and the arguments for your program. The usual
6f05cf9f
AC
15303syntax is:
15304
15305@smallexample
15306target> gdbserver @var{comm} @var{program} [ @var{args} @dots{} ]
15307@end smallexample
15308
15309@var{comm} is either a device name (to use a serial line) or a TCP
15310hostname and portnumber. For example, to debug Emacs with the argument
15311@samp{foo.txt} and communicate with @value{GDBN} over the serial port
15312@file{/dev/com1}:
15313
15314@smallexample
15315target> gdbserver /dev/com1 emacs foo.txt
15316@end smallexample
15317
15318@code{gdbserver} waits passively for the host @value{GDBN} to communicate
15319with it.
15320
15321To use a TCP connection instead of a serial line:
15322
15323@smallexample
15324target> gdbserver host:2345 emacs foo.txt
15325@end smallexample
15326
15327The only difference from the previous example is the first argument,
15328specifying that you are communicating with the host @value{GDBN} via
15329TCP. The @samp{host:2345} argument means that @code{gdbserver} is to
15330expect a TCP connection from machine @samp{host} to local TCP port 2345.
15331(Currently, the @samp{host} part is ignored.) You can choose any number
15332you want for the port number as long as it does not conflict with any
15333TCP ports already in use on the target system (for example, @code{23} is
15334reserved for @code{telnet}).@footnote{If you choose a port number that
15335conflicts with another service, @code{gdbserver} prints an error message
15336and exits.} You must use the same port number with the host @value{GDBN}
15337@code{target remote} command.
15338
2d717e4f
DJ
15339@subsubsection Attaching to a Running Program
15340
56460a61
DJ
15341On some targets, @code{gdbserver} can also attach to running programs.
15342This is accomplished via the @code{--attach} argument. The syntax is:
15343
15344@smallexample
2d717e4f 15345target> gdbserver --attach @var{comm} @var{pid}
56460a61
DJ
15346@end smallexample
15347
15348@var{pid} is the process ID of a currently running process. It isn't necessary
15349to point @code{gdbserver} at a binary for the running process.
15350
b1fe9455
DJ
15351@pindex pidof
15352@cindex attach to a program by name
15353You can debug processes by name instead of process ID if your target has the
15354@code{pidof} utility:
15355
15356@smallexample
2d717e4f 15357target> gdbserver --attach @var{comm} `pidof @var{program}`
b1fe9455
DJ
15358@end smallexample
15359
f822c95b 15360In case more than one copy of @var{program} is running, or @var{program}
b1fe9455
DJ
15361has multiple threads, most versions of @code{pidof} support the
15362@code{-s} option to only return the first process ID.
15363
2d717e4f
DJ
15364@subsubsection Multi-Process Mode for @code{gdbserver}
15365@cindex gdbserver, multiple processes
15366@cindex multiple processes with gdbserver
15367
15368When you connect to @code{gdbserver} using @code{target remote},
15369@code{gdbserver} debugs the specified program only once. When the
15370program exits, or you detach from it, @value{GDBN} closes the connection
15371and @code{gdbserver} exits.
15372
6e6c6f50 15373If you connect using @kbd{target extended-remote}, @code{gdbserver}
2d717e4f
DJ
15374enters multi-process mode. When the debugged program exits, or you
15375detach from it, @value{GDBN} stays connected to @code{gdbserver} even
15376though no program is running. The @code{run} and @code{attach}
15377commands instruct @code{gdbserver} to run or attach to a new program.
15378The @code{run} command uses @code{set remote exec-file} (@pxref{set
15379remote exec-file}) to select the program to run. Command line
15380arguments are supported, except for wildcard expansion and I/O
15381redirection (@pxref{Arguments}).
15382
15383To start @code{gdbserver} without supplying an initial command to run
15384or process ID to attach, use the @option{--multi} command line option.
6e6c6f50 15385Then you can connect using @kbd{target extended-remote} and start
2d717e4f
DJ
15386the program you want to debug.
15387
15388@code{gdbserver} does not automatically exit in multi-process mode.
15389You can terminate it by using @code{monitor exit}
15390(@pxref{Monitor Commands for gdbserver}).
15391
15392@subsubsection Other Command-Line Arguments for @code{gdbserver}
15393
62709adf
PA
15394The @option{--debug} option tells @code{gdbserver} to display extra
15395status information about the debugging process. The
15396@option{--remote-debug} option tells @code{gdbserver} to display
15397remote protocol debug output. These options are intended for
15398@code{gdbserver} development and for bug reports to the developers.
2d717e4f 15399
ccd213ac
DJ
15400The @option{--wrapper} option specifies a wrapper to launch programs
15401for debugging. The option should be followed by the name of the
15402wrapper, then any command-line arguments to pass to the wrapper, then
15403@kbd{--} indicating the end of the wrapper arguments.
15404
15405@code{gdbserver} runs the specified wrapper program with a combined
15406command line including the wrapper arguments, then the name of the
15407program to debug, then any arguments to the program. The wrapper
15408runs until it executes your program, and then @value{GDBN} gains control.
15409
15410You can use any program that eventually calls @code{execve} with
15411its arguments as a wrapper. Several standard Unix utilities do
15412this, e.g.@: @code{env} and @code{nohup}. Any Unix shell script ending
15413with @code{exec "$@@"} will also work.
15414
15415For example, you can use @code{env} to pass an environment variable to
15416the debugged program, without setting the variable in @code{gdbserver}'s
15417environment:
15418
15419@smallexample
15420$ gdbserver --wrapper env LD_PRELOAD=libtest.so -- :2222 ./testprog
15421@end smallexample
15422
2d717e4f
DJ
15423@subsection Connecting to @code{gdbserver}
15424
15425Run @value{GDBN} on the host system.
15426
15427First make sure you have the necessary symbol files. Load symbols for
f822c95b
DJ
15428your application using the @code{file} command before you connect. Use
15429@code{set sysroot} to locate target libraries (unless your @value{GDBN}
2d717e4f 15430was compiled with the correct sysroot using @code{--with-sysroot}).
f822c95b
DJ
15431
15432The symbol file and target libraries must exactly match the executable
15433and libraries on the target, with one exception: the files on the host
15434system should not be stripped, even if the files on the target system
15435are. Mismatched or missing files will lead to confusing results
15436during debugging. On @sc{gnu}/Linux targets, mismatched or missing
15437files may also prevent @code{gdbserver} from debugging multi-threaded
15438programs.
15439
79a6e687 15440Connect to your target (@pxref{Connecting,,Connecting to a Remote Target}).
6f05cf9f
AC
15441For TCP connections, you must start up @code{gdbserver} prior to using
15442the @code{target remote} command. Otherwise you may get an error whose
15443text depends on the host system, but which usually looks something like
2d717e4f 15444@samp{Connection refused}. Don't use the @code{load}
397ca115 15445command in @value{GDBN} when using @code{gdbserver}, since the program is
f822c95b 15446already on the target.
07f31aa6 15447
79a6e687 15448@subsection Monitor Commands for @code{gdbserver}
c74d0ad8 15449@cindex monitor commands, for @code{gdbserver}
2d717e4f 15450@anchor{Monitor Commands for gdbserver}
c74d0ad8
DJ
15451
15452During a @value{GDBN} session using @code{gdbserver}, you can use the
15453@code{monitor} command to send special requests to @code{gdbserver}.
2d717e4f 15454Here are the available commands.
c74d0ad8
DJ
15455
15456@table @code
15457@item monitor help
15458List the available monitor commands.
15459
15460@item monitor set debug 0
15461@itemx monitor set debug 1
15462Disable or enable general debugging messages.
15463
15464@item monitor set remote-debug 0
15465@itemx monitor set remote-debug 1
15466Disable or enable specific debugging messages associated with the remote
15467protocol (@pxref{Remote Protocol}).
15468
cdbfd419
PP
15469@item monitor set libthread-db-search-path [PATH]
15470@cindex gdbserver, search path for @code{libthread_db}
15471When this command is issued, @var{path} is a colon-separated list of
15472directories to search for @code{libthread_db} (@pxref{Threads,,set
15473libthread-db-search-path}). If you omit @var{path},
15474@samp{libthread-db-search-path} will be reset to an empty list.
15475
2d717e4f
DJ
15476@item monitor exit
15477Tell gdbserver to exit immediately. This command should be followed by
15478@code{disconnect} to close the debugging session. @code{gdbserver} will
15479detach from any attached processes and kill any processes it created.
15480Use @code{monitor exit} to terminate @code{gdbserver} at the end
15481of a multi-process mode debug session.
15482
c74d0ad8
DJ
15483@end table
15484
79a6e687
BW
15485@node Remote Configuration
15486@section Remote Configuration
501eef12 15487
9c16f35a
EZ
15488@kindex set remote
15489@kindex show remote
15490This section documents the configuration options available when
15491debugging remote programs. For the options related to the File I/O
fc320d37 15492extensions of the remote protocol, see @ref{system,
9c16f35a 15493system-call-allowed}.
501eef12
AC
15494
15495@table @code
9c16f35a 15496@item set remoteaddresssize @var{bits}
d3e8051b 15497@cindex address size for remote targets
9c16f35a
EZ
15498@cindex bits in remote address
15499Set the maximum size of address in a memory packet to the specified
15500number of bits. @value{GDBN} will mask off the address bits above
15501that number, when it passes addresses to the remote target. The
15502default value is the number of bits in the target's address.
15503
15504@item show remoteaddresssize
15505Show the current value of remote address size in bits.
15506
15507@item set remotebaud @var{n}
15508@cindex baud rate for remote targets
15509Set the baud rate for the remote serial I/O to @var{n} baud. The
15510value is used to set the speed of the serial port used for debugging
15511remote targets.
15512
15513@item show remotebaud
15514Show the current speed of the remote connection.
15515
15516@item set remotebreak
15517@cindex interrupt remote programs
15518@cindex BREAK signal instead of Ctrl-C
9a6253be 15519@anchor{set remotebreak}
9c16f35a 15520If set to on, @value{GDBN} sends a @code{BREAK} signal to the remote
c8aa23ab 15521when you type @kbd{Ctrl-c} to interrupt the program running
9a7a1b36 15522on the remote. If set to off, @value{GDBN} sends the @samp{Ctrl-C}
9c16f35a
EZ
15523character instead. The default is off, since most remote systems
15524expect to see @samp{Ctrl-C} as the interrupt signal.
15525
15526@item show remotebreak
15527Show whether @value{GDBN} sends @code{BREAK} or @samp{Ctrl-C} to
15528interrupt the remote program.
15529
23776285
MR
15530@item set remoteflow on
15531@itemx set remoteflow off
15532@kindex set remoteflow
15533Enable or disable hardware flow control (@code{RTS}/@code{CTS})
15534on the serial port used to communicate to the remote target.
15535
15536@item show remoteflow
15537@kindex show remoteflow
15538Show the current setting of hardware flow control.
15539
9c16f35a
EZ
15540@item set remotelogbase @var{base}
15541Set the base (a.k.a.@: radix) of logging serial protocol
15542communications to @var{base}. Supported values of @var{base} are:
15543@code{ascii}, @code{octal}, and @code{hex}. The default is
15544@code{ascii}.
15545
15546@item show remotelogbase
15547Show the current setting of the radix for logging remote serial
15548protocol.
15549
15550@item set remotelogfile @var{file}
15551@cindex record serial communications on file
15552Record remote serial communications on the named @var{file}. The
15553default is not to record at all.
15554
15555@item show remotelogfile.
15556Show the current setting of the file name on which to record the
15557serial communications.
15558
15559@item set remotetimeout @var{num}
15560@cindex timeout for serial communications
15561@cindex remote timeout
15562Set the timeout limit to wait for the remote target to respond to
15563@var{num} seconds. The default is 2 seconds.
15564
15565@item show remotetimeout
15566Show the current number of seconds to wait for the remote target
15567responses.
15568
15569@cindex limit hardware breakpoints and watchpoints
15570@cindex remote target, limit break- and watchpoints
501eef12
AC
15571@anchor{set remote hardware-watchpoint-limit}
15572@anchor{set remote hardware-breakpoint-limit}
15573@item set remote hardware-watchpoint-limit @var{limit}
15574@itemx set remote hardware-breakpoint-limit @var{limit}
15575Restrict @value{GDBN} to using @var{limit} remote hardware breakpoint or
15576watchpoints. A limit of -1, the default, is treated as unlimited.
2d717e4f
DJ
15577
15578@item set remote exec-file @var{filename}
15579@itemx show remote exec-file
15580@anchor{set remote exec-file}
15581@cindex executable file, for remote target
15582Select the file used for @code{run} with @code{target
15583extended-remote}. This should be set to a filename valid on the
15584target system. If it is not set, the target will use a default
15585filename (e.g.@: the last program run).
84603566 15586
9a7071a8
JB
15587@item set remote interrupt-sequence
15588@cindex interrupt remote programs
15589@cindex select Ctrl-C, BREAK or BREAK-g
15590Allow the user to select one of @samp{Ctrl-C}, a @code{BREAK} or
15591@samp{BREAK-g} as the
15592sequence to the remote target in order to interrupt the execution.
15593@samp{Ctrl-C} is a default. Some system prefers @code{BREAK} which
15594is high level of serial line for some certain time.
15595Linux kernel prefers @samp{BREAK-g}, a.k.a Magic SysRq g.
15596It is @code{BREAK} signal followed by character @code{g}.
15597
15598@item show interrupt-sequence
15599Show which of @samp{Ctrl-C}, @code{BREAK} or @code{BREAK-g}
15600is sent by @value{GDBN} to interrupt the remote program.
15601@code{BREAK-g} is BREAK signal followed by @code{g} and
15602also known as Magic SysRq g.
15603
15604@item set remote interrupt-on-connect
15605@cindex send interrupt-sequence on start
15606Specify whether interrupt-sequence is sent to remote target when
15607@value{GDBN} connects to it. This is mostly needed when you debug
15608Linux kernel. Linux kernel expects @code{BREAK} followed by @code{g}
15609which is known as Magic SysRq g in order to connect @value{GDBN}.
15610
15611@item show interrupt-on-connect
15612Show whether interrupt-sequence is sent
15613to remote target when @value{GDBN} connects to it.
15614
84603566
SL
15615@kindex set tcp
15616@kindex show tcp
15617@item set tcp auto-retry on
15618@cindex auto-retry, for remote TCP target
15619Enable auto-retry for remote TCP connections. This is useful if the remote
15620debugging agent is launched in parallel with @value{GDBN}; there is a race
15621condition because the agent may not become ready to accept the connection
15622before @value{GDBN} attempts to connect. When auto-retry is
15623enabled, if the initial attempt to connect fails, @value{GDBN} reattempts
15624to establish the connection using the timeout specified by
15625@code{set tcp connect-timeout}.
15626
15627@item set tcp auto-retry off
15628Do not auto-retry failed TCP connections.
15629
15630@item show tcp auto-retry
15631Show the current auto-retry setting.
15632
15633@item set tcp connect-timeout @var{seconds}
15634@cindex connection timeout, for remote TCP target
15635@cindex timeout, for remote target connection
15636Set the timeout for establishing a TCP connection to the remote target to
15637@var{seconds}. The timeout affects both polling to retry failed connections
15638(enabled by @code{set tcp auto-retry on}) and waiting for connections
15639that are merely slow to complete, and represents an approximate cumulative
15640value.
15641
15642@item show tcp connect-timeout
15643Show the current connection timeout setting.
501eef12
AC
15644@end table
15645
427c3a89
DJ
15646@cindex remote packets, enabling and disabling
15647The @value{GDBN} remote protocol autodetects the packets supported by
15648your debugging stub. If you need to override the autodetection, you
15649can use these commands to enable or disable individual packets. Each
15650packet can be set to @samp{on} (the remote target supports this
15651packet), @samp{off} (the remote target does not support this packet),
15652or @samp{auto} (detect remote target support for this packet). They
15653all default to @samp{auto}. For more information about each packet,
15654see @ref{Remote Protocol}.
15655
15656During normal use, you should not have to use any of these commands.
15657If you do, that may be a bug in your remote debugging stub, or a bug
15658in @value{GDBN}. You may want to report the problem to the
15659@value{GDBN} developers.
15660
cfa9d6d9
DJ
15661For each packet @var{name}, the command to enable or disable the
15662packet is @code{set remote @var{name}-packet}. The available settings
15663are:
427c3a89 15664
cfa9d6d9 15665@multitable @columnfractions 0.28 0.32 0.25
427c3a89
DJ
15666@item Command Name
15667@tab Remote Packet
15668@tab Related Features
15669
cfa9d6d9 15670@item @code{fetch-register}
427c3a89
DJ
15671@tab @code{p}
15672@tab @code{info registers}
15673
cfa9d6d9 15674@item @code{set-register}
427c3a89
DJ
15675@tab @code{P}
15676@tab @code{set}
15677
cfa9d6d9 15678@item @code{binary-download}
427c3a89
DJ
15679@tab @code{X}
15680@tab @code{load}, @code{set}
15681
cfa9d6d9 15682@item @code{read-aux-vector}
427c3a89
DJ
15683@tab @code{qXfer:auxv:read}
15684@tab @code{info auxv}
15685
cfa9d6d9 15686@item @code{symbol-lookup}
427c3a89
DJ
15687@tab @code{qSymbol}
15688@tab Detecting multiple threads
15689
2d717e4f
DJ
15690@item @code{attach}
15691@tab @code{vAttach}
15692@tab @code{attach}
15693
cfa9d6d9 15694@item @code{verbose-resume}
427c3a89
DJ
15695@tab @code{vCont}
15696@tab Stepping or resuming multiple threads
15697
2d717e4f
DJ
15698@item @code{run}
15699@tab @code{vRun}
15700@tab @code{run}
15701
cfa9d6d9 15702@item @code{software-breakpoint}
427c3a89
DJ
15703@tab @code{Z0}
15704@tab @code{break}
15705
cfa9d6d9 15706@item @code{hardware-breakpoint}
427c3a89
DJ
15707@tab @code{Z1}
15708@tab @code{hbreak}
15709
cfa9d6d9 15710@item @code{write-watchpoint}
427c3a89
DJ
15711@tab @code{Z2}
15712@tab @code{watch}
15713
cfa9d6d9 15714@item @code{read-watchpoint}
427c3a89
DJ
15715@tab @code{Z3}
15716@tab @code{rwatch}
15717
cfa9d6d9 15718@item @code{access-watchpoint}
427c3a89
DJ
15719@tab @code{Z4}
15720@tab @code{awatch}
15721
cfa9d6d9
DJ
15722@item @code{target-features}
15723@tab @code{qXfer:features:read}
15724@tab @code{set architecture}
15725
15726@item @code{library-info}
15727@tab @code{qXfer:libraries:read}
15728@tab @code{info sharedlibrary}
15729
15730@item @code{memory-map}
15731@tab @code{qXfer:memory-map:read}
15732@tab @code{info mem}
15733
15734@item @code{read-spu-object}
15735@tab @code{qXfer:spu:read}
15736@tab @code{info spu}
15737
15738@item @code{write-spu-object}
15739@tab @code{qXfer:spu:write}
15740@tab @code{info spu}
15741
4aa995e1
PA
15742@item @code{read-siginfo-object}
15743@tab @code{qXfer:siginfo:read}
15744@tab @code{print $_siginfo}
15745
15746@item @code{write-siginfo-object}
15747@tab @code{qXfer:siginfo:write}
15748@tab @code{set $_siginfo}
15749
dc146f7c
VP
15750@item @code{threads}
15751@tab @code{qXfer:threads:read}
15752@tab @code{info threads}
15753
cfa9d6d9 15754@item @code{get-thread-local-@*storage-address}
427c3a89
DJ
15755@tab @code{qGetTLSAddr}
15756@tab Displaying @code{__thread} variables
15757
08388c79
DE
15758@item @code{search-memory}
15759@tab @code{qSearch:memory}
15760@tab @code{find}
15761
427c3a89
DJ
15762@item @code{supported-packets}
15763@tab @code{qSupported}
15764@tab Remote communications parameters
15765
cfa9d6d9 15766@item @code{pass-signals}
89be2091
DJ
15767@tab @code{QPassSignals}
15768@tab @code{handle @var{signal}}
15769
a6b151f1
DJ
15770@item @code{hostio-close-packet}
15771@tab @code{vFile:close}
15772@tab @code{remote get}, @code{remote put}
15773
15774@item @code{hostio-open-packet}
15775@tab @code{vFile:open}
15776@tab @code{remote get}, @code{remote put}
15777
15778@item @code{hostio-pread-packet}
15779@tab @code{vFile:pread}
15780@tab @code{remote get}, @code{remote put}
15781
15782@item @code{hostio-pwrite-packet}
15783@tab @code{vFile:pwrite}
15784@tab @code{remote get}, @code{remote put}
15785
15786@item @code{hostio-unlink-packet}
15787@tab @code{vFile:unlink}
15788@tab @code{remote delete}
a6f3e723
SL
15789
15790@item @code{noack-packet}
15791@tab @code{QStartNoAckMode}
15792@tab Packet acknowledgment
07e059b5
VP
15793
15794@item @code{osdata}
15795@tab @code{qXfer:osdata:read}
15796@tab @code{info os}
0b16c5cf
PA
15797
15798@item @code{query-attached}
15799@tab @code{qAttached}
15800@tab Querying remote process attach state.
427c3a89
DJ
15801@end multitable
15802
79a6e687
BW
15803@node Remote Stub
15804@section Implementing a Remote Stub
7a292a7a 15805
8e04817f
AC
15806@cindex debugging stub, example
15807@cindex remote stub, example
15808@cindex stub example, remote debugging
15809The stub files provided with @value{GDBN} implement the target side of the
15810communication protocol, and the @value{GDBN} side is implemented in the
15811@value{GDBN} source file @file{remote.c}. Normally, you can simply allow
15812these subroutines to communicate, and ignore the details. (If you're
15813implementing your own stub file, you can still ignore the details: start
15814with one of the existing stub files. @file{sparc-stub.c} is the best
15815organized, and therefore the easiest to read.)
15816
104c1213
JM
15817@cindex remote serial debugging, overview
15818To debug a program running on another machine (the debugging
15819@dfn{target} machine), you must first arrange for all the usual
15820prerequisites for the program to run by itself. For example, for a C
15821program, you need:
c906108c 15822
104c1213
JM
15823@enumerate
15824@item
15825A startup routine to set up the C runtime environment; these usually
15826have a name like @file{crt0}. The startup routine may be supplied by
15827your hardware supplier, or you may have to write your own.
96baa820 15828
5d161b24 15829@item
d4f3574e 15830A C subroutine library to support your program's
104c1213 15831subroutine calls, notably managing input and output.
96baa820 15832
104c1213
JM
15833@item
15834A way of getting your program to the other machine---for example, a
15835download program. These are often supplied by the hardware
15836manufacturer, but you may have to write your own from hardware
15837documentation.
15838@end enumerate
96baa820 15839
104c1213
JM
15840The next step is to arrange for your program to use a serial port to
15841communicate with the machine where @value{GDBN} is running (the @dfn{host}
15842machine). In general terms, the scheme looks like this:
96baa820 15843
104c1213
JM
15844@table @emph
15845@item On the host,
15846@value{GDBN} already understands how to use this protocol; when everything
15847else is set up, you can simply use the @samp{target remote} command
15848(@pxref{Targets,,Specifying a Debugging Target}).
15849
15850@item On the target,
15851you must link with your program a few special-purpose subroutines that
15852implement the @value{GDBN} remote serial protocol. The file containing these
15853subroutines is called a @dfn{debugging stub}.
15854
15855On certain remote targets, you can use an auxiliary program
15856@code{gdbserver} instead of linking a stub into your program.
79a6e687 15857@xref{Server,,Using the @code{gdbserver} Program}, for details.
104c1213 15858@end table
96baa820 15859
104c1213
JM
15860The debugging stub is specific to the architecture of the remote
15861machine; for example, use @file{sparc-stub.c} to debug programs on
15862@sc{sparc} boards.
96baa820 15863
104c1213
JM
15864@cindex remote serial stub list
15865These working remote stubs are distributed with @value{GDBN}:
96baa820 15866
104c1213
JM
15867@table @code
15868
15869@item i386-stub.c
41afff9a 15870@cindex @file{i386-stub.c}
104c1213
JM
15871@cindex Intel
15872@cindex i386
15873For Intel 386 and compatible architectures.
15874
15875@item m68k-stub.c
41afff9a 15876@cindex @file{m68k-stub.c}
104c1213
JM
15877@cindex Motorola 680x0
15878@cindex m680x0
15879For Motorola 680x0 architectures.
15880
15881@item sh-stub.c
41afff9a 15882@cindex @file{sh-stub.c}
172c2a43 15883@cindex Renesas
104c1213 15884@cindex SH
172c2a43 15885For Renesas SH architectures.
104c1213
JM
15886
15887@item sparc-stub.c
41afff9a 15888@cindex @file{sparc-stub.c}
104c1213
JM
15889@cindex Sparc
15890For @sc{sparc} architectures.
15891
15892@item sparcl-stub.c
41afff9a 15893@cindex @file{sparcl-stub.c}
104c1213
JM
15894@cindex Fujitsu
15895@cindex SparcLite
15896For Fujitsu @sc{sparclite} architectures.
15897
15898@end table
15899
15900The @file{README} file in the @value{GDBN} distribution may list other
15901recently added stubs.
15902
15903@menu
15904* Stub Contents:: What the stub can do for you
15905* Bootstrapping:: What you must do for the stub
15906* Debug Session:: Putting it all together
104c1213
JM
15907@end menu
15908
6d2ebf8b 15909@node Stub Contents
79a6e687 15910@subsection What the Stub Can Do for You
104c1213
JM
15911
15912@cindex remote serial stub
15913The debugging stub for your architecture supplies these three
15914subroutines:
15915
15916@table @code
15917@item set_debug_traps
4644b6e3 15918@findex set_debug_traps
104c1213
JM
15919@cindex remote serial stub, initialization
15920This routine arranges for @code{handle_exception} to run when your
15921program stops. You must call this subroutine explicitly near the
15922beginning of your program.
15923
15924@item handle_exception
4644b6e3 15925@findex handle_exception
104c1213
JM
15926@cindex remote serial stub, main routine
15927This is the central workhorse, but your program never calls it
15928explicitly---the setup code arranges for @code{handle_exception} to
15929run when a trap is triggered.
15930
15931@code{handle_exception} takes control when your program stops during
15932execution (for example, on a breakpoint), and mediates communications
15933with @value{GDBN} on the host machine. This is where the communications
15934protocol is implemented; @code{handle_exception} acts as the @value{GDBN}
d4f3574e 15935representative on the target machine. It begins by sending summary
104c1213
JM
15936information on the state of your program, then continues to execute,
15937retrieving and transmitting any information @value{GDBN} needs, until you
15938execute a @value{GDBN} command that makes your program resume; at that point,
15939@code{handle_exception} returns control to your own code on the target
5d161b24 15940machine.
104c1213
JM
15941
15942@item breakpoint
15943@cindex @code{breakpoint} subroutine, remote
15944Use this auxiliary subroutine to make your program contain a
15945breakpoint. Depending on the particular situation, this may be the only
15946way for @value{GDBN} to get control. For instance, if your target
15947machine has some sort of interrupt button, you won't need to call this;
15948pressing the interrupt button transfers control to
15949@code{handle_exception}---in effect, to @value{GDBN}. On some machines,
15950simply receiving characters on the serial port may also trigger a trap;
15951again, in that situation, you don't need to call @code{breakpoint} from
15952your own program---simply running @samp{target remote} from the host
5d161b24 15953@value{GDBN} session gets control.
104c1213
JM
15954
15955Call @code{breakpoint} if none of these is true, or if you simply want
15956to make certain your program stops at a predetermined point for the
15957start of your debugging session.
15958@end table
15959
6d2ebf8b 15960@node Bootstrapping
79a6e687 15961@subsection What You Must Do for the Stub
104c1213
JM
15962
15963@cindex remote stub, support routines
15964The debugging stubs that come with @value{GDBN} are set up for a particular
15965chip architecture, but they have no information about the rest of your
15966debugging target machine.
15967
15968First of all you need to tell the stub how to communicate with the
15969serial port.
15970
15971@table @code
15972@item int getDebugChar()
4644b6e3 15973@findex getDebugChar
104c1213
JM
15974Write this subroutine to read a single character from the serial port.
15975It may be identical to @code{getchar} for your target system; a
15976different name is used to allow you to distinguish the two if you wish.
15977
15978@item void putDebugChar(int)
4644b6e3 15979@findex putDebugChar
104c1213 15980Write this subroutine to write a single character to the serial port.
5d161b24 15981It may be identical to @code{putchar} for your target system; a
104c1213
JM
15982different name is used to allow you to distinguish the two if you wish.
15983@end table
15984
15985@cindex control C, and remote debugging
15986@cindex interrupting remote targets
15987If you want @value{GDBN} to be able to stop your program while it is
15988running, you need to use an interrupt-driven serial driver, and arrange
15989for it to stop when it receives a @code{^C} (@samp{\003}, the control-C
15990character). That is the character which @value{GDBN} uses to tell the
15991remote system to stop.
15992
15993Getting the debugging target to return the proper status to @value{GDBN}
15994probably requires changes to the standard stub; one quick and dirty way
15995is to just execute a breakpoint instruction (the ``dirty'' part is that
15996@value{GDBN} reports a @code{SIGTRAP} instead of a @code{SIGINT}).
15997
15998Other routines you need to supply are:
15999
16000@table @code
16001@item void exceptionHandler (int @var{exception_number}, void *@var{exception_address})
4644b6e3 16002@findex exceptionHandler
104c1213
JM
16003Write this function to install @var{exception_address} in the exception
16004handling tables. You need to do this because the stub does not have any
16005way of knowing what the exception handling tables on your target system
16006are like (for example, the processor's table might be in @sc{rom},
16007containing entries which point to a table in @sc{ram}).
16008@var{exception_number} is the exception number which should be changed;
16009its meaning is architecture-dependent (for example, different numbers
16010might represent divide by zero, misaligned access, etc). When this
16011exception occurs, control should be transferred directly to
16012@var{exception_address}, and the processor state (stack, registers,
16013and so on) should be just as it is when a processor exception occurs. So if
16014you want to use a jump instruction to reach @var{exception_address}, it
16015should be a simple jump, not a jump to subroutine.
16016
16017For the 386, @var{exception_address} should be installed as an interrupt
16018gate so that interrupts are masked while the handler runs. The gate
16019should be at privilege level 0 (the most privileged level). The
16020@sc{sparc} and 68k stubs are able to mask interrupts themselves without
16021help from @code{exceptionHandler}.
16022
16023@item void flush_i_cache()
4644b6e3 16024@findex flush_i_cache
d4f3574e 16025On @sc{sparc} and @sc{sparclite} only, write this subroutine to flush the
104c1213
JM
16026instruction cache, if any, on your target machine. If there is no
16027instruction cache, this subroutine may be a no-op.
16028
16029On target machines that have instruction caches, @value{GDBN} requires this
16030function to make certain that the state of your program is stable.
16031@end table
16032
16033@noindent
16034You must also make sure this library routine is available:
16035
16036@table @code
16037@item void *memset(void *, int, int)
4644b6e3 16038@findex memset
104c1213
JM
16039This is the standard library function @code{memset} that sets an area of
16040memory to a known value. If you have one of the free versions of
16041@code{libc.a}, @code{memset} can be found there; otherwise, you must
16042either obtain it from your hardware manufacturer, or write your own.
16043@end table
16044
16045If you do not use the GNU C compiler, you may need other standard
16046library subroutines as well; this varies from one stub to another,
16047but in general the stubs are likely to use any of the common library
e22ea452 16048subroutines which @code{@value{NGCC}} generates as inline code.
104c1213
JM
16049
16050
6d2ebf8b 16051@node Debug Session
79a6e687 16052@subsection Putting it All Together
104c1213
JM
16053
16054@cindex remote serial debugging summary
16055In summary, when your program is ready to debug, you must follow these
16056steps.
16057
16058@enumerate
16059@item
6d2ebf8b 16060Make sure you have defined the supporting low-level routines
79a6e687 16061(@pxref{Bootstrapping,,What You Must Do for the Stub}):
104c1213
JM
16062@display
16063@code{getDebugChar}, @code{putDebugChar},
16064@code{flush_i_cache}, @code{memset}, @code{exceptionHandler}.
16065@end display
16066
16067@item
16068Insert these lines near the top of your program:
16069
474c8240 16070@smallexample
104c1213
JM
16071set_debug_traps();
16072breakpoint();
474c8240 16073@end smallexample
104c1213
JM
16074
16075@item
16076For the 680x0 stub only, you need to provide a variable called
16077@code{exceptionHook}. Normally you just use:
16078
474c8240 16079@smallexample
104c1213 16080void (*exceptionHook)() = 0;
474c8240 16081@end smallexample
104c1213 16082
d4f3574e 16083@noindent
104c1213 16084but if before calling @code{set_debug_traps}, you set it to point to a
598ca718 16085function in your program, that function is called when
104c1213
JM
16086@code{@value{GDBN}} continues after stopping on a trap (for example, bus
16087error). The function indicated by @code{exceptionHook} is called with
16088one parameter: an @code{int} which is the exception number.
16089
16090@item
16091Compile and link together: your program, the @value{GDBN} debugging stub for
16092your target architecture, and the supporting subroutines.
16093
16094@item
16095Make sure you have a serial connection between your target machine and
16096the @value{GDBN} host, and identify the serial port on the host.
16097
16098@item
16099@c The "remote" target now provides a `load' command, so we should
16100@c document that. FIXME.
16101Download your program to your target machine (or get it there by
16102whatever means the manufacturer provides), and start it.
16103
16104@item
07f31aa6 16105Start @value{GDBN} on the host, and connect to the target
79a6e687 16106(@pxref{Connecting,,Connecting to a Remote Target}).
9db8d71f 16107
104c1213
JM
16108@end enumerate
16109
8e04817f
AC
16110@node Configurations
16111@chapter Configuration-Specific Information
104c1213 16112
8e04817f
AC
16113While nearly all @value{GDBN} commands are available for all native and
16114cross versions of the debugger, there are some exceptions. This chapter
16115describes things that are only available in certain configurations.
104c1213 16116
8e04817f
AC
16117There are three major categories of configurations: native
16118configurations, where the host and target are the same, embedded
16119operating system configurations, which are usually the same for several
16120different processor architectures, and bare embedded processors, which
16121are quite different from each other.
104c1213 16122
8e04817f
AC
16123@menu
16124* Native::
16125* Embedded OS::
16126* Embedded Processors::
16127* Architectures::
16128@end menu
104c1213 16129
8e04817f
AC
16130@node Native
16131@section Native
104c1213 16132
8e04817f
AC
16133This section describes details specific to particular native
16134configurations.
6cf7e474 16135
8e04817f
AC
16136@menu
16137* HP-UX:: HP-UX
7561d450 16138* BSD libkvm Interface:: Debugging BSD kernel memory images
8e04817f
AC
16139* SVR4 Process Information:: SVR4 process information
16140* DJGPP Native:: Features specific to the DJGPP port
78c47bea 16141* Cygwin Native:: Features specific to the Cygwin port
14d6dd68 16142* Hurd Native:: Features specific to @sc{gnu} Hurd
a64548ea 16143* Neutrino:: Features specific to QNX Neutrino
a80b95ba 16144* Darwin:: Features specific to Darwin
8e04817f 16145@end menu
6cf7e474 16146
8e04817f
AC
16147@node HP-UX
16148@subsection HP-UX
104c1213 16149
8e04817f
AC
16150On HP-UX systems, if you refer to a function or variable name that
16151begins with a dollar sign, @value{GDBN} searches for a user or system
16152name first, before it searches for a convenience variable.
104c1213 16153
9c16f35a 16154
7561d450
MK
16155@node BSD libkvm Interface
16156@subsection BSD libkvm Interface
16157
16158@cindex libkvm
16159@cindex kernel memory image
16160@cindex kernel crash dump
16161
16162BSD-derived systems (FreeBSD/NetBSD/OpenBSD) have a kernel memory
16163interface that provides a uniform interface for accessing kernel virtual
16164memory images, including live systems and crash dumps. @value{GDBN}
16165uses this interface to allow you to debug live kernels and kernel crash
16166dumps on many native BSD configurations. This is implemented as a
16167special @code{kvm} debugging target. For debugging a live system, load
16168the currently running kernel into @value{GDBN} and connect to the
16169@code{kvm} target:
16170
16171@smallexample
16172(@value{GDBP}) @b{target kvm}
16173@end smallexample
16174
16175For debugging crash dumps, provide the file name of the crash dump as an
16176argument:
16177
16178@smallexample
16179(@value{GDBP}) @b{target kvm /var/crash/bsd.0}
16180@end smallexample
16181
16182Once connected to the @code{kvm} target, the following commands are
16183available:
16184
16185@table @code
16186@kindex kvm
16187@item kvm pcb
721c2651 16188Set current context from the @dfn{Process Control Block} (PCB) address.
7561d450
MK
16189
16190@item kvm proc
16191Set current context from proc address. This command isn't available on
16192modern FreeBSD systems.
16193@end table
16194
8e04817f 16195@node SVR4 Process Information
79a6e687 16196@subsection SVR4 Process Information
60bf7e09
EZ
16197@cindex /proc
16198@cindex examine process image
16199@cindex process info via @file{/proc}
104c1213 16200
60bf7e09
EZ
16201Many versions of SVR4 and compatible systems provide a facility called
16202@samp{/proc} that can be used to examine the image of a running
16203process using file-system subroutines. If @value{GDBN} is configured
16204for an operating system with this facility, the command @code{info
16205proc} is available to report information about the process running
16206your program, or about any process running on your system. @code{info
16207proc} works only on SVR4 systems that include the @code{procfs} code.
16208This includes, as of this writing, @sc{gnu}/Linux, OSF/1 (Digital
16209Unix), Solaris, Irix, and Unixware, but not HP-UX, for example.
104c1213 16210
8e04817f
AC
16211@table @code
16212@kindex info proc
60bf7e09 16213@cindex process ID
8e04817f 16214@item info proc
60bf7e09
EZ
16215@itemx info proc @var{process-id}
16216Summarize available information about any running process. If a
16217process ID is specified by @var{process-id}, display information about
16218that process; otherwise display information about the program being
16219debugged. The summary includes the debugged process ID, the command
16220line used to invoke it, its current working directory, and its
16221executable file's absolute file name.
16222
16223On some systems, @var{process-id} can be of the form
16224@samp{[@var{pid}]/@var{tid}} which specifies a certain thread ID
16225within a process. If the optional @var{pid} part is missing, it means
16226a thread from the process being debugged (the leading @samp{/} still
16227needs to be present, or else @value{GDBN} will interpret the number as
16228a process ID rather than a thread ID).
6cf7e474 16229
8e04817f 16230@item info proc mappings
60bf7e09
EZ
16231@cindex memory address space mappings
16232Report the memory address space ranges accessible in the program, with
16233information on whether the process has read, write, or execute access
16234rights to each range. On @sc{gnu}/Linux systems, each memory range
16235includes the object file which is mapped to that range, instead of the
16236memory access rights to that range.
16237
16238@item info proc stat
16239@itemx info proc status
16240@cindex process detailed status information
16241These subcommands are specific to @sc{gnu}/Linux systems. They show
16242the process-related information, including the user ID and group ID;
16243how many threads are there in the process; its virtual memory usage;
16244the signals that are pending, blocked, and ignored; its TTY; its
16245consumption of system and user time; its stack size; its @samp{nice}
2eecc4ab 16246value; etc. For more information, see the @samp{proc} man page
60bf7e09
EZ
16247(type @kbd{man 5 proc} from your shell prompt).
16248
16249@item info proc all
16250Show all the information about the process described under all of the
16251above @code{info proc} subcommands.
16252
8e04817f
AC
16253@ignore
16254@comment These sub-options of 'info proc' were not included when
16255@comment procfs.c was re-written. Keep their descriptions around
16256@comment against the day when someone finds the time to put them back in.
16257@kindex info proc times
16258@item info proc times
16259Starting time, user CPU time, and system CPU time for your program and
16260its children.
6cf7e474 16261
8e04817f
AC
16262@kindex info proc id
16263@item info proc id
16264Report on the process IDs related to your program: its own process ID,
16265the ID of its parent, the process group ID, and the session ID.
8e04817f 16266@end ignore
721c2651
EZ
16267
16268@item set procfs-trace
16269@kindex set procfs-trace
16270@cindex @code{procfs} API calls
16271This command enables and disables tracing of @code{procfs} API calls.
16272
16273@item show procfs-trace
16274@kindex show procfs-trace
16275Show the current state of @code{procfs} API call tracing.
16276
16277@item set procfs-file @var{file}
16278@kindex set procfs-file
16279Tell @value{GDBN} to write @code{procfs} API trace to the named
16280@var{file}. @value{GDBN} appends the trace info to the previous
16281contents of the file. The default is to display the trace on the
16282standard output.
16283
16284@item show procfs-file
16285@kindex show procfs-file
16286Show the file to which @code{procfs} API trace is written.
16287
16288@item proc-trace-entry
16289@itemx proc-trace-exit
16290@itemx proc-untrace-entry
16291@itemx proc-untrace-exit
16292@kindex proc-trace-entry
16293@kindex proc-trace-exit
16294@kindex proc-untrace-entry
16295@kindex proc-untrace-exit
16296These commands enable and disable tracing of entries into and exits
16297from the @code{syscall} interface.
16298
16299@item info pidlist
16300@kindex info pidlist
16301@cindex process list, QNX Neutrino
16302For QNX Neutrino only, this command displays the list of all the
16303processes and all the threads within each process.
16304
16305@item info meminfo
16306@kindex info meminfo
16307@cindex mapinfo list, QNX Neutrino
16308For QNX Neutrino only, this command displays the list of all mapinfos.
8e04817f 16309@end table
104c1213 16310
8e04817f
AC
16311@node DJGPP Native
16312@subsection Features for Debugging @sc{djgpp} Programs
16313@cindex @sc{djgpp} debugging
16314@cindex native @sc{djgpp} debugging
16315@cindex MS-DOS-specific commands
104c1213 16316
514c4d71
EZ
16317@cindex DPMI
16318@sc{djgpp} is a port of the @sc{gnu} development tools to MS-DOS and
8e04817f
AC
16319MS-Windows. @sc{djgpp} programs are 32-bit protected-mode programs
16320that use the @dfn{DPMI} (DOS Protected-Mode Interface) API to run on
16321top of real-mode DOS systems and their emulations.
104c1213 16322
8e04817f
AC
16323@value{GDBN} supports native debugging of @sc{djgpp} programs, and
16324defines a few commands specific to the @sc{djgpp} port. This
16325subsection describes those commands.
104c1213 16326
8e04817f
AC
16327@table @code
16328@kindex info dos
16329@item info dos
16330This is a prefix of @sc{djgpp}-specific commands which print
16331information about the target system and important OS structures.
f1251bdd 16332
8e04817f
AC
16333@kindex sysinfo
16334@cindex MS-DOS system info
16335@cindex free memory information (MS-DOS)
16336@item info dos sysinfo
16337This command displays assorted information about the underlying
16338platform: the CPU type and features, the OS version and flavor, the
16339DPMI version, and the available conventional and DPMI memory.
104c1213 16340
8e04817f
AC
16341@cindex GDT
16342@cindex LDT
16343@cindex IDT
16344@cindex segment descriptor tables
16345@cindex descriptor tables display
16346@item info dos gdt
16347@itemx info dos ldt
16348@itemx info dos idt
16349These 3 commands display entries from, respectively, Global, Local,
16350and Interrupt Descriptor Tables (GDT, LDT, and IDT). The descriptor
16351tables are data structures which store a descriptor for each segment
16352that is currently in use. The segment's selector is an index into a
16353descriptor table; the table entry for that index holds the
16354descriptor's base address and limit, and its attributes and access
16355rights.
104c1213 16356
8e04817f
AC
16357A typical @sc{djgpp} program uses 3 segments: a code segment, a data
16358segment (used for both data and the stack), and a DOS segment (which
16359allows access to DOS/BIOS data structures and absolute addresses in
16360conventional memory). However, the DPMI host will usually define
16361additional segments in order to support the DPMI environment.
d4f3574e 16362
8e04817f
AC
16363@cindex garbled pointers
16364These commands allow to display entries from the descriptor tables.
16365Without an argument, all entries from the specified table are
16366displayed. An argument, which should be an integer expression, means
16367display a single entry whose index is given by the argument. For
16368example, here's a convenient way to display information about the
16369debugged program's data segment:
104c1213 16370
8e04817f
AC
16371@smallexample
16372@exdent @code{(@value{GDBP}) info dos ldt $ds}
16373@exdent @code{0x13f: base=0x11970000 limit=0x0009ffff 32-Bit Data (Read/Write, Exp-up)}
16374@end smallexample
104c1213 16375
8e04817f
AC
16376@noindent
16377This comes in handy when you want to see whether a pointer is outside
16378the data segment's limit (i.e.@: @dfn{garbled}).
104c1213 16379
8e04817f
AC
16380@cindex page tables display (MS-DOS)
16381@item info dos pde
16382@itemx info dos pte
16383These two commands display entries from, respectively, the Page
16384Directory and the Page Tables. Page Directories and Page Tables are
16385data structures which control how virtual memory addresses are mapped
16386into physical addresses. A Page Table includes an entry for every
16387page of memory that is mapped into the program's address space; there
16388may be several Page Tables, each one holding up to 4096 entries. A
16389Page Directory has up to 4096 entries, one each for every Page Table
16390that is currently in use.
104c1213 16391
8e04817f
AC
16392Without an argument, @kbd{info dos pde} displays the entire Page
16393Directory, and @kbd{info dos pte} displays all the entries in all of
16394the Page Tables. An argument, an integer expression, given to the
16395@kbd{info dos pde} command means display only that entry from the Page
16396Directory table. An argument given to the @kbd{info dos pte} command
16397means display entries from a single Page Table, the one pointed to by
16398the specified entry in the Page Directory.
104c1213 16399
8e04817f
AC
16400@cindex direct memory access (DMA) on MS-DOS
16401These commands are useful when your program uses @dfn{DMA} (Direct
16402Memory Access), which needs physical addresses to program the DMA
16403controller.
104c1213 16404
8e04817f 16405These commands are supported only with some DPMI servers.
104c1213 16406
8e04817f
AC
16407@cindex physical address from linear address
16408@item info dos address-pte @var{addr}
16409This command displays the Page Table entry for a specified linear
514c4d71
EZ
16410address. The argument @var{addr} is a linear address which should
16411already have the appropriate segment's base address added to it,
16412because this command accepts addresses which may belong to @emph{any}
16413segment. For example, here's how to display the Page Table entry for
16414the page where a variable @code{i} is stored:
104c1213 16415
b383017d 16416@smallexample
8e04817f
AC
16417@exdent @code{(@value{GDBP}) info dos address-pte __djgpp_base_address + (char *)&i}
16418@exdent @code{Page Table entry for address 0x11a00d30:}
b383017d 16419@exdent @code{Base=0x02698000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0xd30}
8e04817f 16420@end smallexample
104c1213 16421
8e04817f
AC
16422@noindent
16423This says that @code{i} is stored at offset @code{0xd30} from the page
514c4d71 16424whose physical base address is @code{0x02698000}, and shows all the
8e04817f 16425attributes of that page.
104c1213 16426
8e04817f
AC
16427Note that you must cast the addresses of variables to a @code{char *},
16428since otherwise the value of @code{__djgpp_base_address}, the base
16429address of all variables and functions in a @sc{djgpp} program, will
16430be added using the rules of C pointer arithmetics: if @code{i} is
16431declared an @code{int}, @value{GDBN} will add 4 times the value of
16432@code{__djgpp_base_address} to the address of @code{i}.
104c1213 16433
8e04817f
AC
16434Here's another example, it displays the Page Table entry for the
16435transfer buffer:
104c1213 16436
8e04817f
AC
16437@smallexample
16438@exdent @code{(@value{GDBP}) info dos address-pte *((unsigned *)&_go32_info_block + 3)}
16439@exdent @code{Page Table entry for address 0x29110:}
16440@exdent @code{Base=0x00029000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0x110}
16441@end smallexample
104c1213 16442
8e04817f
AC
16443@noindent
16444(The @code{+ 3} offset is because the transfer buffer's address is the
514c4d71
EZ
164453rd member of the @code{_go32_info_block} structure.) The output
16446clearly shows that this DPMI server maps the addresses in conventional
16447memory 1:1, i.e.@: the physical (@code{0x00029000} + @code{0x110}) and
16448linear (@code{0x29110}) addresses are identical.
104c1213 16449
8e04817f
AC
16450This command is supported only with some DPMI servers.
16451@end table
104c1213 16452
c45da7e6 16453@cindex DOS serial data link, remote debugging
a8f24a35
EZ
16454In addition to native debugging, the DJGPP port supports remote
16455debugging via a serial data link. The following commands are specific
16456to remote serial debugging in the DJGPP port of @value{GDBN}.
16457
16458@table @code
16459@kindex set com1base
16460@kindex set com1irq
16461@kindex set com2base
16462@kindex set com2irq
16463@kindex set com3base
16464@kindex set com3irq
16465@kindex set com4base
16466@kindex set com4irq
16467@item set com1base @var{addr}
16468This command sets the base I/O port address of the @file{COM1} serial
16469port.
16470
16471@item set com1irq @var{irq}
16472This command sets the @dfn{Interrupt Request} (@code{IRQ}) line to use
16473for the @file{COM1} serial port.
16474
16475There are similar commands @samp{set com2base}, @samp{set com3irq},
16476etc.@: for setting the port address and the @code{IRQ} lines for the
16477other 3 COM ports.
16478
16479@kindex show com1base
16480@kindex show com1irq
16481@kindex show com2base
16482@kindex show com2irq
16483@kindex show com3base
16484@kindex show com3irq
16485@kindex show com4base
16486@kindex show com4irq
16487The related commands @samp{show com1base}, @samp{show com1irq} etc.@:
16488display the current settings of the base address and the @code{IRQ}
16489lines used by the COM ports.
c45da7e6
EZ
16490
16491@item info serial
16492@kindex info serial
16493@cindex DOS serial port status
16494This command prints the status of the 4 DOS serial ports. For each
16495port, it prints whether it's active or not, its I/O base address and
16496IRQ number, whether it uses a 16550-style FIFO, its baudrate, and the
16497counts of various errors encountered so far.
a8f24a35
EZ
16498@end table
16499
16500
78c47bea 16501@node Cygwin Native
79a6e687 16502@subsection Features for Debugging MS Windows PE Executables
78c47bea
PM
16503@cindex MS Windows debugging
16504@cindex native Cygwin debugging
16505@cindex Cygwin-specific commands
16506
be448670 16507@value{GDBN} supports native debugging of MS Windows programs, including
cbb8f428
EZ
16508DLLs with and without symbolic debugging information.
16509
16510@cindex Ctrl-BREAK, MS-Windows
16511@cindex interrupt debuggee on MS-Windows
16512MS-Windows programs that call @code{SetConsoleMode} to switch off the
16513special meaning of the @samp{Ctrl-C} keystroke cannot be interrupted
16514by typing @kbd{C-c}. For this reason, @value{GDBN} on MS-Windows
16515supports @kbd{C-@key{BREAK}} as an alternative interrupt key
16516sequence, which can be used to interrupt the debuggee even if it
16517ignores @kbd{C-c}.
16518
16519There are various additional Cygwin-specific commands, described in
16520this section. Working with DLLs that have no debugging symbols is
16521described in @ref{Non-debug DLL Symbols}.
78c47bea
PM
16522
16523@table @code
16524@kindex info w32
16525@item info w32
db2e3e2e 16526This is a prefix of MS Windows-specific commands which print
78c47bea
PM
16527information about the target system and important OS structures.
16528
16529@item info w32 selector
16530This command displays information returned by
16531the Win32 API @code{GetThreadSelectorEntry} function.
16532It takes an optional argument that is evaluated to
16533a long value to give the information about this given selector.
16534Without argument, this command displays information
d3e8051b 16535about the six segment registers.
78c47bea
PM
16536
16537@kindex info dll
16538@item info dll
db2e3e2e 16539This is a Cygwin-specific alias of @code{info shared}.
78c47bea
PM
16540
16541@kindex dll-symbols
16542@item dll-symbols
16543This command loads symbols from a dll similarly to
16544add-sym command but without the need to specify a base address.
16545
be90c084 16546@kindex set cygwin-exceptions
e16b02ee
EZ
16547@cindex debugging the Cygwin DLL
16548@cindex Cygwin DLL, debugging
be90c084 16549@item set cygwin-exceptions @var{mode}
e16b02ee
EZ
16550If @var{mode} is @code{on}, @value{GDBN} will break on exceptions that
16551happen inside the Cygwin DLL. If @var{mode} is @code{off},
16552@value{GDBN} will delay recognition of exceptions, and may ignore some
16553exceptions which seem to be caused by internal Cygwin DLL
16554``bookkeeping''. This option is meant primarily for debugging the
16555Cygwin DLL itself; the default value is @code{off} to avoid annoying
16556@value{GDBN} users with false @code{SIGSEGV} signals.
be90c084
CF
16557
16558@kindex show cygwin-exceptions
16559@item show cygwin-exceptions
e16b02ee
EZ
16560Displays whether @value{GDBN} will break on exceptions that happen
16561inside the Cygwin DLL itself.
be90c084 16562
b383017d 16563@kindex set new-console
78c47bea 16564@item set new-console @var{mode}
b383017d 16565If @var{mode} is @code{on} the debuggee will
78c47bea 16566be started in a new console on next start.
e03e5e7b 16567If @var{mode} is @code{off}, the debuggee will
78c47bea
PM
16568be started in the same console as the debugger.
16569
16570@kindex show new-console
16571@item show new-console
16572Displays whether a new console is used
16573when the debuggee is started.
16574
16575@kindex set new-group
16576@item set new-group @var{mode}
16577This boolean value controls whether the debuggee should
16578start a new group or stay in the same group as the debugger.
16579This affects the way the Windows OS handles
c8aa23ab 16580@samp{Ctrl-C}.
78c47bea
PM
16581
16582@kindex show new-group
16583@item show new-group
16584Displays current value of new-group boolean.
16585
16586@kindex set debugevents
16587@item set debugevents
219eec71
EZ
16588This boolean value adds debug output concerning kernel events related
16589to the debuggee seen by the debugger. This includes events that
16590signal thread and process creation and exit, DLL loading and
16591unloading, console interrupts, and debugging messages produced by the
16592Windows @code{OutputDebugString} API call.
78c47bea
PM
16593
16594@kindex set debugexec
16595@item set debugexec
b383017d 16596This boolean value adds debug output concerning execute events
219eec71 16597(such as resume thread) seen by the debugger.
78c47bea
PM
16598
16599@kindex set debugexceptions
16600@item set debugexceptions
219eec71
EZ
16601This boolean value adds debug output concerning exceptions in the
16602debuggee seen by the debugger.
78c47bea
PM
16603
16604@kindex set debugmemory
16605@item set debugmemory
219eec71
EZ
16606This boolean value adds debug output concerning debuggee memory reads
16607and writes by the debugger.
78c47bea
PM
16608
16609@kindex set shell
16610@item set shell
16611This boolean values specifies whether the debuggee is called
16612via a shell or directly (default value is on).
16613
16614@kindex show shell
16615@item show shell
16616Displays if the debuggee will be started with a shell.
16617
16618@end table
16619
be448670 16620@menu
79a6e687 16621* Non-debug DLL Symbols:: Support for DLLs without debugging symbols
be448670
CF
16622@end menu
16623
79a6e687
BW
16624@node Non-debug DLL Symbols
16625@subsubsection Support for DLLs without Debugging Symbols
be448670
CF
16626@cindex DLLs with no debugging symbols
16627@cindex Minimal symbols and DLLs
16628
16629Very often on windows, some of the DLLs that your program relies on do
16630not include symbolic debugging information (for example,
db2e3e2e 16631@file{kernel32.dll}). When @value{GDBN} doesn't recognize any debugging
be448670 16632symbols in a DLL, it relies on the minimal amount of symbolic
db2e3e2e 16633information contained in the DLL's export table. This section
be448670
CF
16634describes working with such symbols, known internally to @value{GDBN} as
16635``minimal symbols''.
16636
16637Note that before the debugged program has started execution, no DLLs
db2e3e2e 16638will have been loaded. The easiest way around this problem is simply to
be448670 16639start the program --- either by setting a breakpoint or letting the
db2e3e2e 16640program run once to completion. It is also possible to force
be448670 16641@value{GDBN} to load a particular DLL before starting the executable ---
12c27660 16642see the shared library information in @ref{Files}, or the
db2e3e2e 16643@code{dll-symbols} command in @ref{Cygwin Native}. Currently,
be448670
CF
16644explicitly loading symbols from a DLL with no debugging information will
16645cause the symbol names to be duplicated in @value{GDBN}'s lookup table,
16646which may adversely affect symbol lookup performance.
16647
79a6e687 16648@subsubsection DLL Name Prefixes
be448670
CF
16649
16650In keeping with the naming conventions used by the Microsoft debugging
16651tools, DLL export symbols are made available with a prefix based on the
16652DLL name, for instance @code{KERNEL32!CreateFileA}. The plain name is
16653also entered into the symbol table, so @code{CreateFileA} is often
99e008fe 16654sufficient. In some cases there will be name clashes within a program
be448670
CF
16655(particularly if the executable itself includes full debugging symbols)
16656necessitating the use of the fully qualified name when referring to the
99e008fe 16657contents of the DLL. Use single-quotes around the name to avoid the
be448670
CF
16658exclamation mark (``!'') being interpreted as a language operator.
16659
16660Note that the internal name of the DLL may be all upper-case, even
99e008fe 16661though the file name of the DLL is lower-case, or vice-versa. Since
be448670
CF
16662symbols within @value{GDBN} are @emph{case-sensitive} this may cause
16663some confusion. If in doubt, try the @code{info functions} and
0869d01b
NR
16664@code{info variables} commands or even @code{maint print msymbols}
16665(@pxref{Symbols}). Here's an example:
be448670
CF
16666
16667@smallexample
f7dc1244 16668(@value{GDBP}) info function CreateFileA
be448670
CF
16669All functions matching regular expression "CreateFileA":
16670
16671Non-debugging symbols:
166720x77e885f4 CreateFileA
166730x77e885f4 KERNEL32!CreateFileA
16674@end smallexample
16675
16676@smallexample
f7dc1244 16677(@value{GDBP}) info function !
be448670
CF
16678All functions matching regular expression "!":
16679
16680Non-debugging symbols:
166810x6100114c cygwin1!__assert
166820x61004034 cygwin1!_dll_crt0@@0
166830x61004240 cygwin1!dll_crt0(per_process *)
16684[etc...]
16685@end smallexample
16686
79a6e687 16687@subsubsection Working with Minimal Symbols
be448670
CF
16688
16689Symbols extracted from a DLL's export table do not contain very much
16690type information. All that @value{GDBN} can do is guess whether a symbol
16691refers to a function or variable depending on the linker section that
16692contains the symbol. Also note that the actual contents of the memory
16693contained in a DLL are not available unless the program is running. This
16694means that you cannot examine the contents of a variable or disassemble
16695a function within a DLL without a running program.
16696
16697Variables are generally treated as pointers and dereferenced
16698automatically. For this reason, it is often necessary to prefix a
16699variable name with the address-of operator (``&'') and provide explicit
16700type information in the command. Here's an example of the type of
16701problem:
16702
16703@smallexample
f7dc1244 16704(@value{GDBP}) print 'cygwin1!__argv'
be448670
CF
16705$1 = 268572168
16706@end smallexample
16707
16708@smallexample
f7dc1244 16709(@value{GDBP}) x 'cygwin1!__argv'
be448670
CF
167100x10021610: "\230y\""
16711@end smallexample
16712
16713And two possible solutions:
16714
16715@smallexample
f7dc1244 16716(@value{GDBP}) print ((char **)'cygwin1!__argv')[0]
be448670
CF
16717$2 = 0x22fd98 "/cygdrive/c/mydirectory/myprogram"
16718@end smallexample
16719
16720@smallexample
f7dc1244 16721(@value{GDBP}) x/2x &'cygwin1!__argv'
be448670 167220x610c0aa8 <cygwin1!__argv>: 0x10021608 0x00000000
f7dc1244 16723(@value{GDBP}) x/x 0x10021608
be448670 167240x10021608: 0x0022fd98
f7dc1244 16725(@value{GDBP}) x/s 0x0022fd98
be448670
CF
167260x22fd98: "/cygdrive/c/mydirectory/myprogram"
16727@end smallexample
16728
16729Setting a break point within a DLL is possible even before the program
16730starts execution. However, under these circumstances, @value{GDBN} can't
16731examine the initial instructions of the function in order to skip the
16732function's frame set-up code. You can work around this by using ``*&''
16733to set the breakpoint at a raw memory address:
16734
16735@smallexample
f7dc1244 16736(@value{GDBP}) break *&'python22!PyOS_Readline'
be448670
CF
16737Breakpoint 1 at 0x1e04eff0
16738@end smallexample
16739
16740The author of these extensions is not entirely convinced that setting a
16741break point within a shared DLL like @file{kernel32.dll} is completely
16742safe.
16743
14d6dd68 16744@node Hurd Native
79a6e687 16745@subsection Commands Specific to @sc{gnu} Hurd Systems
14d6dd68
EZ
16746@cindex @sc{gnu} Hurd debugging
16747
16748This subsection describes @value{GDBN} commands specific to the
16749@sc{gnu} Hurd native debugging.
16750
16751@table @code
16752@item set signals
16753@itemx set sigs
16754@kindex set signals@r{, Hurd command}
16755@kindex set sigs@r{, Hurd command}
16756This command toggles the state of inferior signal interception by
16757@value{GDBN}. Mach exceptions, such as breakpoint traps, are not
16758affected by this command. @code{sigs} is a shorthand alias for
16759@code{signals}.
16760
16761@item show signals
16762@itemx show sigs
16763@kindex show signals@r{, Hurd command}
16764@kindex show sigs@r{, Hurd command}
16765Show the current state of intercepting inferior's signals.
16766
16767@item set signal-thread
16768@itemx set sigthread
16769@kindex set signal-thread
16770@kindex set sigthread
16771This command tells @value{GDBN} which thread is the @code{libc} signal
16772thread. That thread is run when a signal is delivered to a running
16773process. @code{set sigthread} is the shorthand alias of @code{set
16774signal-thread}.
16775
16776@item show signal-thread
16777@itemx show sigthread
16778@kindex show signal-thread
16779@kindex show sigthread
16780These two commands show which thread will run when the inferior is
16781delivered a signal.
16782
16783@item set stopped
16784@kindex set stopped@r{, Hurd command}
16785This commands tells @value{GDBN} that the inferior process is stopped,
16786as with the @code{SIGSTOP} signal. The stopped process can be
16787continued by delivering a signal to it.
16788
16789@item show stopped
16790@kindex show stopped@r{, Hurd command}
16791This command shows whether @value{GDBN} thinks the debuggee is
16792stopped.
16793
16794@item set exceptions
16795@kindex set exceptions@r{, Hurd command}
16796Use this command to turn off trapping of exceptions in the inferior.
16797When exception trapping is off, neither breakpoints nor
16798single-stepping will work. To restore the default, set exception
16799trapping on.
16800
16801@item show exceptions
16802@kindex show exceptions@r{, Hurd command}
16803Show the current state of trapping exceptions in the inferior.
16804
16805@item set task pause
16806@kindex set task@r{, Hurd commands}
16807@cindex task attributes (@sc{gnu} Hurd)
16808@cindex pause current task (@sc{gnu} Hurd)
16809This command toggles task suspension when @value{GDBN} has control.
16810Setting it to on takes effect immediately, and the task is suspended
16811whenever @value{GDBN} gets control. Setting it to off will take
16812effect the next time the inferior is continued. If this option is set
16813to off, you can use @code{set thread default pause on} or @code{set
16814thread pause on} (see below) to pause individual threads.
16815
16816@item show task pause
16817@kindex show task@r{, Hurd commands}
16818Show the current state of task suspension.
16819
16820@item set task detach-suspend-count
16821@cindex task suspend count
16822@cindex detach from task, @sc{gnu} Hurd
16823This command sets the suspend count the task will be left with when
16824@value{GDBN} detaches from it.
16825
16826@item show task detach-suspend-count
16827Show the suspend count the task will be left with when detaching.
16828
16829@item set task exception-port
16830@itemx set task excp
16831@cindex task exception port, @sc{gnu} Hurd
16832This command sets the task exception port to which @value{GDBN} will
16833forward exceptions. The argument should be the value of the @dfn{send
16834rights} of the task. @code{set task excp} is a shorthand alias.
16835
16836@item set noninvasive
16837@cindex noninvasive task options
16838This command switches @value{GDBN} to a mode that is the least
16839invasive as far as interfering with the inferior is concerned. This
16840is the same as using @code{set task pause}, @code{set exceptions}, and
16841@code{set signals} to values opposite to the defaults.
16842
16843@item info send-rights
16844@itemx info receive-rights
16845@itemx info port-rights
16846@itemx info port-sets
16847@itemx info dead-names
16848@itemx info ports
16849@itemx info psets
16850@cindex send rights, @sc{gnu} Hurd
16851@cindex receive rights, @sc{gnu} Hurd
16852@cindex port rights, @sc{gnu} Hurd
16853@cindex port sets, @sc{gnu} Hurd
16854@cindex dead names, @sc{gnu} Hurd
16855These commands display information about, respectively, send rights,
16856receive rights, port rights, port sets, and dead names of a task.
16857There are also shorthand aliases: @code{info ports} for @code{info
16858port-rights} and @code{info psets} for @code{info port-sets}.
16859
16860@item set thread pause
16861@kindex set thread@r{, Hurd command}
16862@cindex thread properties, @sc{gnu} Hurd
16863@cindex pause current thread (@sc{gnu} Hurd)
16864This command toggles current thread suspension when @value{GDBN} has
16865control. Setting it to on takes effect immediately, and the current
16866thread is suspended whenever @value{GDBN} gets control. Setting it to
16867off will take effect the next time the inferior is continued.
16868Normally, this command has no effect, since when @value{GDBN} has
16869control, the whole task is suspended. However, if you used @code{set
16870task pause off} (see above), this command comes in handy to suspend
16871only the current thread.
16872
16873@item show thread pause
16874@kindex show thread@r{, Hurd command}
16875This command shows the state of current thread suspension.
16876
16877@item set thread run
d3e8051b 16878This command sets whether the current thread is allowed to run.
14d6dd68
EZ
16879
16880@item show thread run
16881Show whether the current thread is allowed to run.
16882
16883@item set thread detach-suspend-count
16884@cindex thread suspend count, @sc{gnu} Hurd
16885@cindex detach from thread, @sc{gnu} Hurd
16886This command sets the suspend count @value{GDBN} will leave on a
16887thread when detaching. This number is relative to the suspend count
16888found by @value{GDBN} when it notices the thread; use @code{set thread
16889takeover-suspend-count} to force it to an absolute value.
16890
16891@item show thread detach-suspend-count
16892Show the suspend count @value{GDBN} will leave on the thread when
16893detaching.
16894
16895@item set thread exception-port
16896@itemx set thread excp
16897Set the thread exception port to which to forward exceptions. This
16898overrides the port set by @code{set task exception-port} (see above).
16899@code{set thread excp} is the shorthand alias.
16900
16901@item set thread takeover-suspend-count
16902Normally, @value{GDBN}'s thread suspend counts are relative to the
16903value @value{GDBN} finds when it notices each thread. This command
16904changes the suspend counts to be absolute instead.
16905
16906@item set thread default
16907@itemx show thread default
16908@cindex thread default settings, @sc{gnu} Hurd
16909Each of the above @code{set thread} commands has a @code{set thread
16910default} counterpart (e.g., @code{set thread default pause}, @code{set
16911thread default exception-port}, etc.). The @code{thread default}
16912variety of commands sets the default thread properties for all
16913threads; you can then change the properties of individual threads with
16914the non-default commands.
16915@end table
16916
16917
a64548ea
EZ
16918@node Neutrino
16919@subsection QNX Neutrino
16920@cindex QNX Neutrino
16921
16922@value{GDBN} provides the following commands specific to the QNX
16923Neutrino target:
16924
16925@table @code
16926@item set debug nto-debug
16927@kindex set debug nto-debug
16928When set to on, enables debugging messages specific to the QNX
16929Neutrino support.
16930
16931@item show debug nto-debug
16932@kindex show debug nto-debug
16933Show the current state of QNX Neutrino messages.
16934@end table
16935
a80b95ba
TG
16936@node Darwin
16937@subsection Darwin
16938@cindex Darwin
16939
16940@value{GDBN} provides the following commands specific to the Darwin target:
16941
16942@table @code
16943@item set debug darwin @var{num}
16944@kindex set debug darwin
16945When set to a non zero value, enables debugging messages specific to
16946the Darwin support. Higher values produce more verbose output.
16947
16948@item show debug darwin
16949@kindex show debug darwin
16950Show the current state of Darwin messages.
16951
16952@item set debug mach-o @var{num}
16953@kindex set debug mach-o
16954When set to a non zero value, enables debugging messages while
16955@value{GDBN} is reading Darwin object files. (@dfn{Mach-O} is the
16956file format used on Darwin for object and executable files.) Higher
16957values produce more verbose output. This is a command to diagnose
16958problems internal to @value{GDBN} and should not be needed in normal
16959usage.
16960
16961@item show debug mach-o
16962@kindex show debug mach-o
16963Show the current state of Mach-O file messages.
16964
16965@item set mach-exceptions on
16966@itemx set mach-exceptions off
16967@kindex set mach-exceptions
16968On Darwin, faults are first reported as a Mach exception and are then
16969mapped to a Posix signal. Use this command to turn on trapping of
16970Mach exceptions in the inferior. This might be sometimes useful to
16971better understand the cause of a fault. The default is off.
16972
16973@item show mach-exceptions
16974@kindex show mach-exceptions
16975Show the current state of exceptions trapping.
16976@end table
16977
a64548ea 16978
8e04817f
AC
16979@node Embedded OS
16980@section Embedded Operating Systems
104c1213 16981
8e04817f
AC
16982This section describes configurations involving the debugging of
16983embedded operating systems that are available for several different
16984architectures.
d4f3574e 16985
8e04817f
AC
16986@menu
16987* VxWorks:: Using @value{GDBN} with VxWorks
16988@end menu
104c1213 16989
8e04817f
AC
16990@value{GDBN} includes the ability to debug programs running on
16991various real-time operating systems.
104c1213 16992
8e04817f
AC
16993@node VxWorks
16994@subsection Using @value{GDBN} with VxWorks
104c1213 16995
8e04817f 16996@cindex VxWorks
104c1213 16997
8e04817f 16998@table @code
104c1213 16999
8e04817f
AC
17000@kindex target vxworks
17001@item target vxworks @var{machinename}
17002A VxWorks system, attached via TCP/IP. The argument @var{machinename}
17003is the target system's machine name or IP address.
104c1213 17004
8e04817f 17005@end table
104c1213 17006
8e04817f
AC
17007On VxWorks, @code{load} links @var{filename} dynamically on the
17008current target system as well as adding its symbols in @value{GDBN}.
104c1213 17009
8e04817f
AC
17010@value{GDBN} enables developers to spawn and debug tasks running on networked
17011VxWorks targets from a Unix host. Already-running tasks spawned from
17012the VxWorks shell can also be debugged. @value{GDBN} uses code that runs on
17013both the Unix host and on the VxWorks target. The program
17014@code{@value{GDBP}} is installed and executed on the Unix host. (It may be
17015installed with the name @code{vxgdb}, to distinguish it from a
17016@value{GDBN} for debugging programs on the host itself.)
104c1213 17017
8e04817f
AC
17018@table @code
17019@item VxWorks-timeout @var{args}
17020@kindex vxworks-timeout
17021All VxWorks-based targets now support the option @code{vxworks-timeout}.
17022This option is set by the user, and @var{args} represents the number of
17023seconds @value{GDBN} waits for responses to rpc's. You might use this if
17024your VxWorks target is a slow software simulator or is on the far side
17025of a thin network line.
17026@end table
104c1213 17027
8e04817f
AC
17028The following information on connecting to VxWorks was current when
17029this manual was produced; newer releases of VxWorks may use revised
17030procedures.
104c1213 17031
4644b6e3 17032@findex INCLUDE_RDB
8e04817f
AC
17033To use @value{GDBN} with VxWorks, you must rebuild your VxWorks kernel
17034to include the remote debugging interface routines in the VxWorks
17035library @file{rdb.a}. To do this, define @code{INCLUDE_RDB} in the
17036VxWorks configuration file @file{configAll.h} and rebuild your VxWorks
17037kernel. The resulting kernel contains @file{rdb.a}, and spawns the
17038source debugging task @code{tRdbTask} when VxWorks is booted. For more
17039information on configuring and remaking VxWorks, see the manufacturer's
17040manual.
17041@c VxWorks, see the @cite{VxWorks Programmer's Guide}.
104c1213 17042
8e04817f
AC
17043Once you have included @file{rdb.a} in your VxWorks system image and set
17044your Unix execution search path to find @value{GDBN}, you are ready to
17045run @value{GDBN}. From your Unix host, run @code{@value{GDBP}} (or
17046@code{vxgdb}, depending on your installation).
104c1213 17047
8e04817f 17048@value{GDBN} comes up showing the prompt:
104c1213 17049
474c8240 17050@smallexample
8e04817f 17051(vxgdb)
474c8240 17052@end smallexample
104c1213 17053
8e04817f
AC
17054@menu
17055* VxWorks Connection:: Connecting to VxWorks
17056* VxWorks Download:: VxWorks download
17057* VxWorks Attach:: Running tasks
17058@end menu
104c1213 17059
8e04817f
AC
17060@node VxWorks Connection
17061@subsubsection Connecting to VxWorks
104c1213 17062
8e04817f
AC
17063The @value{GDBN} command @code{target} lets you connect to a VxWorks target on the
17064network. To connect to a target whose host name is ``@code{tt}'', type:
104c1213 17065
474c8240 17066@smallexample
8e04817f 17067(vxgdb) target vxworks tt
474c8240 17068@end smallexample
104c1213 17069
8e04817f
AC
17070@need 750
17071@value{GDBN} displays messages like these:
104c1213 17072
8e04817f
AC
17073@smallexample
17074Attaching remote machine across net...
17075Connected to tt.
17076@end smallexample
104c1213 17077
8e04817f
AC
17078@need 1000
17079@value{GDBN} then attempts to read the symbol tables of any object modules
17080loaded into the VxWorks target since it was last booted. @value{GDBN} locates
17081these files by searching the directories listed in the command search
79a6e687 17082path (@pxref{Environment, ,Your Program's Environment}); if it fails
8e04817f 17083to find an object file, it displays a message such as:
5d161b24 17084
474c8240 17085@smallexample
8e04817f 17086prog.o: No such file or directory.
474c8240 17087@end smallexample
104c1213 17088
8e04817f
AC
17089When this happens, add the appropriate directory to the search path with
17090the @value{GDBN} command @code{path}, and execute the @code{target}
17091command again.
104c1213 17092
8e04817f 17093@node VxWorks Download
79a6e687 17094@subsubsection VxWorks Download
104c1213 17095
8e04817f
AC
17096@cindex download to VxWorks
17097If you have connected to the VxWorks target and you want to debug an
17098object that has not yet been loaded, you can use the @value{GDBN}
17099@code{load} command to download a file from Unix to VxWorks
17100incrementally. The object file given as an argument to the @code{load}
17101command is actually opened twice: first by the VxWorks target in order
17102to download the code, then by @value{GDBN} in order to read the symbol
17103table. This can lead to problems if the current working directories on
17104the two systems differ. If both systems have NFS mounted the same
17105filesystems, you can avoid these problems by using absolute paths.
17106Otherwise, it is simplest to set the working directory on both systems
17107to the directory in which the object file resides, and then to reference
17108the file by its name, without any path. For instance, a program
17109@file{prog.o} may reside in @file{@var{vxpath}/vw/demo/rdb} in VxWorks
17110and in @file{@var{hostpath}/vw/demo/rdb} on the host. To load this
17111program, type this on VxWorks:
104c1213 17112
474c8240 17113@smallexample
8e04817f 17114-> cd "@var{vxpath}/vw/demo/rdb"
474c8240 17115@end smallexample
104c1213 17116
8e04817f
AC
17117@noindent
17118Then, in @value{GDBN}, type:
104c1213 17119
474c8240 17120@smallexample
8e04817f
AC
17121(vxgdb) cd @var{hostpath}/vw/demo/rdb
17122(vxgdb) load prog.o
474c8240 17123@end smallexample
104c1213 17124
8e04817f 17125@value{GDBN} displays a response similar to this:
104c1213 17126
8e04817f
AC
17127@smallexample
17128Reading symbol data from wherever/vw/demo/rdb/prog.o... done.
17129@end smallexample
104c1213 17130
8e04817f
AC
17131You can also use the @code{load} command to reload an object module
17132after editing and recompiling the corresponding source file. Note that
17133this makes @value{GDBN} delete all currently-defined breakpoints,
17134auto-displays, and convenience variables, and to clear the value
17135history. (This is necessary in order to preserve the integrity of
17136debugger's data structures that reference the target system's symbol
17137table.)
104c1213 17138
8e04817f 17139@node VxWorks Attach
79a6e687 17140@subsubsection Running Tasks
104c1213
JM
17141
17142@cindex running VxWorks tasks
17143You can also attach to an existing task using the @code{attach} command as
17144follows:
17145
474c8240 17146@smallexample
104c1213 17147(vxgdb) attach @var{task}
474c8240 17148@end smallexample
104c1213
JM
17149
17150@noindent
17151where @var{task} is the VxWorks hexadecimal task ID. The task can be running
17152or suspended when you attach to it. Running tasks are suspended at
17153the time of attachment.
17154
6d2ebf8b 17155@node Embedded Processors
104c1213
JM
17156@section Embedded Processors
17157
17158This section goes into details specific to particular embedded
17159configurations.
17160
c45da7e6
EZ
17161@cindex send command to simulator
17162Whenever a specific embedded processor has a simulator, @value{GDBN}
17163allows to send an arbitrary command to the simulator.
17164
17165@table @code
17166@item sim @var{command}
17167@kindex sim@r{, a command}
17168Send an arbitrary @var{command} string to the simulator. Consult the
17169documentation for the specific simulator in use for information about
17170acceptable commands.
17171@end table
17172
7d86b5d5 17173
104c1213 17174@menu
c45da7e6 17175* ARM:: ARM RDI
172c2a43 17176* M32R/D:: Renesas M32R/D
104c1213 17177* M68K:: Motorola M68K
08be9d71 17178* MicroBlaze:: Xilinx MicroBlaze
104c1213 17179* MIPS Embedded:: MIPS Embedded
a37295f9 17180* OpenRISC 1000:: OpenRisc 1000
104c1213 17181* PA:: HP PA Embedded
4acd40f3 17182* PowerPC Embedded:: PowerPC Embedded
104c1213
JM
17183* Sparclet:: Tsqware Sparclet
17184* Sparclite:: Fujitsu Sparclite
104c1213 17185* Z8000:: Zilog Z8000
a64548ea
EZ
17186* AVR:: Atmel AVR
17187* CRIS:: CRIS
17188* Super-H:: Renesas Super-H
104c1213
JM
17189@end menu
17190
6d2ebf8b 17191@node ARM
104c1213 17192@subsection ARM
c45da7e6 17193@cindex ARM RDI
104c1213
JM
17194
17195@table @code
8e04817f
AC
17196@kindex target rdi
17197@item target rdi @var{dev}
17198ARM Angel monitor, via RDI library interface to ADP protocol. You may
17199use this target to communicate with both boards running the Angel
17200monitor, or with the EmbeddedICE JTAG debug device.
17201
17202@kindex target rdp
17203@item target rdp @var{dev}
17204ARM Demon monitor.
17205
17206@end table
17207
e2f4edfd
EZ
17208@value{GDBN} provides the following ARM-specific commands:
17209
17210@table @code
17211@item set arm disassembler
17212@kindex set arm
17213This commands selects from a list of disassembly styles. The
17214@code{"std"} style is the standard style.
17215
17216@item show arm disassembler
17217@kindex show arm
17218Show the current disassembly style.
17219
17220@item set arm apcs32
17221@cindex ARM 32-bit mode
17222This command toggles ARM operation mode between 32-bit and 26-bit.
17223
17224@item show arm apcs32
17225Display the current usage of the ARM 32-bit mode.
17226
17227@item set arm fpu @var{fputype}
17228This command sets the ARM floating-point unit (FPU) type. The
17229argument @var{fputype} can be one of these:
17230
17231@table @code
17232@item auto
17233Determine the FPU type by querying the OS ABI.
17234@item softfpa
17235Software FPU, with mixed-endian doubles on little-endian ARM
17236processors.
17237@item fpa
17238GCC-compiled FPA co-processor.
17239@item softvfp
17240Software FPU with pure-endian doubles.
17241@item vfp
17242VFP co-processor.
17243@end table
17244
17245@item show arm fpu
17246Show the current type of the FPU.
17247
17248@item set arm abi
17249This command forces @value{GDBN} to use the specified ABI.
17250
17251@item show arm abi
17252Show the currently used ABI.
17253
0428b8f5
DJ
17254@item set arm fallback-mode (arm|thumb|auto)
17255@value{GDBN} uses the symbol table, when available, to determine
17256whether instructions are ARM or Thumb. This command controls
17257@value{GDBN}'s default behavior when the symbol table is not
17258available. The default is @samp{auto}, which causes @value{GDBN} to
17259use the current execution mode (from the @code{T} bit in the @code{CPSR}
17260register).
17261
17262@item show arm fallback-mode
17263Show the current fallback instruction mode.
17264
17265@item set arm force-mode (arm|thumb|auto)
17266This command overrides use of the symbol table to determine whether
17267instructions are ARM or Thumb. The default is @samp{auto}, which
17268causes @value{GDBN} to use the symbol table and then the setting
17269of @samp{set arm fallback-mode}.
17270
17271@item show arm force-mode
17272Show the current forced instruction mode.
17273
e2f4edfd
EZ
17274@item set debug arm
17275Toggle whether to display ARM-specific debugging messages from the ARM
17276target support subsystem.
17277
17278@item show debug arm
17279Show whether ARM-specific debugging messages are enabled.
17280@end table
17281
c45da7e6
EZ
17282The following commands are available when an ARM target is debugged
17283using the RDI interface:
17284
17285@table @code
17286@item rdilogfile @r{[}@var{file}@r{]}
17287@kindex rdilogfile
17288@cindex ADP (Angel Debugger Protocol) logging
17289Set the filename for the ADP (Angel Debugger Protocol) packet log.
17290With an argument, sets the log file to the specified @var{file}. With
17291no argument, show the current log file name. The default log file is
17292@file{rdi.log}.
17293
17294@item rdilogenable @r{[}@var{arg}@r{]}
17295@kindex rdilogenable
17296Control logging of ADP packets. With an argument of 1 or @code{"yes"}
17297enables logging, with an argument 0 or @code{"no"} disables it. With
17298no arguments displays the current setting. When logging is enabled,
17299ADP packets exchanged between @value{GDBN} and the RDI target device
17300are logged to a file.
17301
17302@item set rdiromatzero
17303@kindex set rdiromatzero
17304@cindex ROM at zero address, RDI
17305Tell @value{GDBN} whether the target has ROM at address 0. If on,
17306vector catching is disabled, so that zero address can be used. If off
17307(the default), vector catching is enabled. For this command to take
17308effect, it needs to be invoked prior to the @code{target rdi} command.
17309
17310@item show rdiromatzero
17311@kindex show rdiromatzero
17312Show the current setting of ROM at zero address.
17313
17314@item set rdiheartbeat
17315@kindex set rdiheartbeat
17316@cindex RDI heartbeat
17317Enable or disable RDI heartbeat packets. It is not recommended to
17318turn on this option, since it confuses ARM and EPI JTAG interface, as
17319well as the Angel monitor.
17320
17321@item show rdiheartbeat
17322@kindex show rdiheartbeat
17323Show the setting of RDI heartbeat packets.
17324@end table
17325
ee8e71d4
EZ
17326@table @code
17327@item target sim @r{[}@var{simargs}@r{]} @dots{}
17328The @value{GDBN} ARM simulator accepts the following optional arguments.
17329
17330@table @code
17331@item --swi-support=@var{type}
17332Tell the simulator which SWI interfaces to support.
17333@var{type} may be a comma separated list of the following values.
17334The default value is @code{all}.
17335
17336@table @code
17337@item none
17338@item demon
17339@item angel
17340@item redboot
17341@item all
17342@end table
17343@end table
17344@end table
e2f4edfd 17345
8e04817f 17346@node M32R/D
ba04e063 17347@subsection Renesas M32R/D and M32R/SDI
8e04817f
AC
17348
17349@table @code
8e04817f
AC
17350@kindex target m32r
17351@item target m32r @var{dev}
172c2a43 17352Renesas M32R/D ROM monitor.
8e04817f 17353
fb3e19c0
KI
17354@kindex target m32rsdi
17355@item target m32rsdi @var{dev}
17356Renesas M32R SDI server, connected via parallel port to the board.
721c2651
EZ
17357@end table
17358
17359The following @value{GDBN} commands are specific to the M32R monitor:
17360
17361@table @code
17362@item set download-path @var{path}
17363@kindex set download-path
17364@cindex find downloadable @sc{srec} files (M32R)
d3e8051b 17365Set the default path for finding downloadable @sc{srec} files.
721c2651
EZ
17366
17367@item show download-path
17368@kindex show download-path
17369Show the default path for downloadable @sc{srec} files.
fb3e19c0 17370
721c2651
EZ
17371@item set board-address @var{addr}
17372@kindex set board-address
17373@cindex M32-EVA target board address
17374Set the IP address for the M32R-EVA target board.
17375
17376@item show board-address
17377@kindex show board-address
17378Show the current IP address of the target board.
17379
17380@item set server-address @var{addr}
17381@kindex set server-address
17382@cindex download server address (M32R)
17383Set the IP address for the download server, which is the @value{GDBN}'s
17384host machine.
17385
17386@item show server-address
17387@kindex show server-address
17388Display the IP address of the download server.
17389
17390@item upload @r{[}@var{file}@r{]}
17391@kindex upload@r{, M32R}
17392Upload the specified @sc{srec} @var{file} via the monitor's Ethernet
17393upload capability. If no @var{file} argument is given, the current
17394executable file is uploaded.
17395
17396@item tload @r{[}@var{file}@r{]}
17397@kindex tload@r{, M32R}
17398Test the @code{upload} command.
8e04817f
AC
17399@end table
17400
ba04e063
EZ
17401The following commands are available for M32R/SDI:
17402
17403@table @code
17404@item sdireset
17405@kindex sdireset
17406@cindex reset SDI connection, M32R
17407This command resets the SDI connection.
17408
17409@item sdistatus
17410@kindex sdistatus
17411This command shows the SDI connection status.
17412
17413@item debug_chaos
17414@kindex debug_chaos
17415@cindex M32R/Chaos debugging
17416Instructs the remote that M32R/Chaos debugging is to be used.
17417
17418@item use_debug_dma
17419@kindex use_debug_dma
17420Instructs the remote to use the DEBUG_DMA method of accessing memory.
17421
17422@item use_mon_code
17423@kindex use_mon_code
17424Instructs the remote to use the MON_CODE method of accessing memory.
17425
17426@item use_ib_break
17427@kindex use_ib_break
17428Instructs the remote to set breakpoints by IB break.
17429
17430@item use_dbt_break
17431@kindex use_dbt_break
17432Instructs the remote to set breakpoints by DBT.
17433@end table
17434
8e04817f
AC
17435@node M68K
17436@subsection M68k
17437
7ce59000
DJ
17438The Motorola m68k configuration includes ColdFire support, and a
17439target command for the following ROM monitor.
8e04817f
AC
17440
17441@table @code
17442
8e04817f
AC
17443@kindex target dbug
17444@item target dbug @var{dev}
17445dBUG ROM monitor for Motorola ColdFire.
17446
8e04817f
AC
17447@end table
17448
08be9d71
ME
17449@node MicroBlaze
17450@subsection MicroBlaze
17451@cindex Xilinx MicroBlaze
17452@cindex XMD, Xilinx Microprocessor Debugger
17453
17454The MicroBlaze is a soft-core processor supported on various Xilinx
17455FPGAs, such as Spartan or Virtex series. Boards with these processors
17456usually have JTAG ports which connect to a host system running the Xilinx
17457Embedded Development Kit (EDK) or Software Development Kit (SDK).
17458This host system is used to download the configuration bitstream to
17459the target FPGA. The Xilinx Microprocessor Debugger (XMD) program
17460communicates with the target board using the JTAG interface and
17461presents a @code{gdbserver} interface to the board. By default
17462@code{xmd} uses port @code{1234}. (While it is possible to change
17463this default port, it requires the use of undocumented @code{xmd}
17464commands. Contact Xilinx support if you need to do this.)
17465
17466Use these GDB commands to connect to the MicroBlaze target processor.
17467
17468@table @code
17469@item target remote :1234
17470Use this command to connect to the target if you are running @value{GDBN}
17471on the same system as @code{xmd}.
17472
17473@item target remote @var{xmd-host}:1234
17474Use this command to connect to the target if it is connected to @code{xmd}
17475running on a different system named @var{xmd-host}.
17476
17477@item load
17478Use this command to download a program to the MicroBlaze target.
17479
17480@item set debug microblaze @var{n}
17481Enable MicroBlaze-specific debugging messages if non-zero.
17482
17483@item show debug microblaze @var{n}
17484Show MicroBlaze-specific debugging level.
17485@end table
17486
8e04817f
AC
17487@node MIPS Embedded
17488@subsection MIPS Embedded
17489
17490@cindex MIPS boards
17491@value{GDBN} can use the MIPS remote debugging protocol to talk to a
17492MIPS board attached to a serial line. This is available when
17493you configure @value{GDBN} with @samp{--target=mips-idt-ecoff}.
104c1213 17494
8e04817f
AC
17495@need 1000
17496Use these @value{GDBN} commands to specify the connection to your target board:
104c1213 17497
8e04817f
AC
17498@table @code
17499@item target mips @var{port}
17500@kindex target mips @var{port}
17501To run a program on the board, start up @code{@value{GDBP}} with the
17502name of your program as the argument. To connect to the board, use the
17503command @samp{target mips @var{port}}, where @var{port} is the name of
17504the serial port connected to the board. If the program has not already
17505been downloaded to the board, you may use the @code{load} command to
17506download it. You can then use all the usual @value{GDBN} commands.
104c1213 17507
8e04817f
AC
17508For example, this sequence connects to the target board through a serial
17509port, and loads and runs a program called @var{prog} through the
17510debugger:
104c1213 17511
474c8240 17512@smallexample
8e04817f
AC
17513host$ @value{GDBP} @var{prog}
17514@value{GDBN} is free software and @dots{}
17515(@value{GDBP}) target mips /dev/ttyb
17516(@value{GDBP}) load @var{prog}
17517(@value{GDBP}) run
474c8240 17518@end smallexample
104c1213 17519
8e04817f
AC
17520@item target mips @var{hostname}:@var{portnumber}
17521On some @value{GDBN} host configurations, you can specify a TCP
17522connection (for instance, to a serial line managed by a terminal
17523concentrator) instead of a serial port, using the syntax
17524@samp{@var{hostname}:@var{portnumber}}.
104c1213 17525
8e04817f
AC
17526@item target pmon @var{port}
17527@kindex target pmon @var{port}
17528PMON ROM monitor.
104c1213 17529
8e04817f
AC
17530@item target ddb @var{port}
17531@kindex target ddb @var{port}
17532NEC's DDB variant of PMON for Vr4300.
104c1213 17533
8e04817f
AC
17534@item target lsi @var{port}
17535@kindex target lsi @var{port}
17536LSI variant of PMON.
104c1213 17537
8e04817f
AC
17538@kindex target r3900
17539@item target r3900 @var{dev}
17540Densan DVE-R3900 ROM monitor for Toshiba R3900 Mips.
104c1213 17541
8e04817f
AC
17542@kindex target array
17543@item target array @var{dev}
17544Array Tech LSI33K RAID controller board.
104c1213 17545
8e04817f 17546@end table
104c1213 17547
104c1213 17548
8e04817f
AC
17549@noindent
17550@value{GDBN} also supports these special commands for MIPS targets:
104c1213 17551
8e04817f 17552@table @code
8e04817f
AC
17553@item set mipsfpu double
17554@itemx set mipsfpu single
17555@itemx set mipsfpu none
a64548ea 17556@itemx set mipsfpu auto
8e04817f
AC
17557@itemx show mipsfpu
17558@kindex set mipsfpu
17559@kindex show mipsfpu
17560@cindex MIPS remote floating point
17561@cindex floating point, MIPS remote
17562If your target board does not support the MIPS floating point
17563coprocessor, you should use the command @samp{set mipsfpu none} (if you
17564need this, you may wish to put the command in your @value{GDBN} init
17565file). This tells @value{GDBN} how to find the return value of
17566functions which return floating point values. It also allows
17567@value{GDBN} to avoid saving the floating point registers when calling
17568functions on the board. If you are using a floating point coprocessor
17569with only single precision floating point support, as on the @sc{r4650}
17570processor, use the command @samp{set mipsfpu single}. The default
17571double precision floating point coprocessor may be selected using
17572@samp{set mipsfpu double}.
104c1213 17573
8e04817f
AC
17574In previous versions the only choices were double precision or no
17575floating point, so @samp{set mipsfpu on} will select double precision
17576and @samp{set mipsfpu off} will select no floating point.
104c1213 17577
8e04817f
AC
17578As usual, you can inquire about the @code{mipsfpu} variable with
17579@samp{show mipsfpu}.
104c1213 17580
8e04817f
AC
17581@item set timeout @var{seconds}
17582@itemx set retransmit-timeout @var{seconds}
17583@itemx show timeout
17584@itemx show retransmit-timeout
17585@cindex @code{timeout}, MIPS protocol
17586@cindex @code{retransmit-timeout}, MIPS protocol
17587@kindex set timeout
17588@kindex show timeout
17589@kindex set retransmit-timeout
17590@kindex show retransmit-timeout
17591You can control the timeout used while waiting for a packet, in the MIPS
17592remote protocol, with the @code{set timeout @var{seconds}} command. The
17593default is 5 seconds. Similarly, you can control the timeout used while
a6f3e723 17594waiting for an acknowledgment of a packet with the @code{set
8e04817f
AC
17595retransmit-timeout @var{seconds}} command. The default is 3 seconds.
17596You can inspect both values with @code{show timeout} and @code{show
17597retransmit-timeout}. (These commands are @emph{only} available when
17598@value{GDBN} is configured for @samp{--target=mips-idt-ecoff}.)
104c1213 17599
8e04817f
AC
17600The timeout set by @code{set timeout} does not apply when @value{GDBN}
17601is waiting for your program to stop. In that case, @value{GDBN} waits
17602forever because it has no way of knowing how long the program is going
17603to run before stopping.
ba04e063
EZ
17604
17605@item set syn-garbage-limit @var{num}
17606@kindex set syn-garbage-limit@r{, MIPS remote}
17607@cindex synchronize with remote MIPS target
17608Limit the maximum number of characters @value{GDBN} should ignore when
17609it tries to synchronize with the remote target. The default is 10
17610characters. Setting the limit to -1 means there's no limit.
17611
17612@item show syn-garbage-limit
17613@kindex show syn-garbage-limit@r{, MIPS remote}
17614Show the current limit on the number of characters to ignore when
17615trying to synchronize with the remote system.
17616
17617@item set monitor-prompt @var{prompt}
17618@kindex set monitor-prompt@r{, MIPS remote}
17619@cindex remote monitor prompt
17620Tell @value{GDBN} to expect the specified @var{prompt} string from the
17621remote monitor. The default depends on the target:
17622@table @asis
17623@item pmon target
17624@samp{PMON}
17625@item ddb target
17626@samp{NEC010}
17627@item lsi target
17628@samp{PMON>}
17629@end table
17630
17631@item show monitor-prompt
17632@kindex show monitor-prompt@r{, MIPS remote}
17633Show the current strings @value{GDBN} expects as the prompt from the
17634remote monitor.
17635
17636@item set monitor-warnings
17637@kindex set monitor-warnings@r{, MIPS remote}
17638Enable or disable monitor warnings about hardware breakpoints. This
17639has effect only for the @code{lsi} target. When on, @value{GDBN} will
17640display warning messages whose codes are returned by the @code{lsi}
17641PMON monitor for breakpoint commands.
17642
17643@item show monitor-warnings
17644@kindex show monitor-warnings@r{, MIPS remote}
17645Show the current setting of printing monitor warnings.
17646
17647@item pmon @var{command}
17648@kindex pmon@r{, MIPS remote}
17649@cindex send PMON command
17650This command allows sending an arbitrary @var{command} string to the
17651monitor. The monitor must be in debug mode for this to work.
8e04817f 17652@end table
104c1213 17653
a37295f9
MM
17654@node OpenRISC 1000
17655@subsection OpenRISC 1000
17656@cindex OpenRISC 1000
17657
17658@cindex or1k boards
17659See OR1k Architecture document (@uref{www.opencores.org}) for more information
17660about platform and commands.
17661
17662@table @code
17663
17664@kindex target jtag
17665@item target jtag jtag://@var{host}:@var{port}
17666
17667Connects to remote JTAG server.
17668JTAG remote server can be either an or1ksim or JTAG server,
17669connected via parallel port to the board.
17670
17671Example: @code{target jtag jtag://localhost:9999}
17672
17673@kindex or1ksim
17674@item or1ksim @var{command}
17675If connected to @code{or1ksim} OpenRISC 1000 Architectural
17676Simulator, proprietary commands can be executed.
17677
17678@kindex info or1k spr
17679@item info or1k spr
17680Displays spr groups.
17681
17682@item info or1k spr @var{group}
17683@itemx info or1k spr @var{groupno}
17684Displays register names in selected group.
17685
17686@item info or1k spr @var{group} @var{register}
17687@itemx info or1k spr @var{register}
17688@itemx info or1k spr @var{groupno} @var{registerno}
17689@itemx info or1k spr @var{registerno}
17690Shows information about specified spr register.
17691
17692@kindex spr
17693@item spr @var{group} @var{register} @var{value}
17694@itemx spr @var{register @var{value}}
17695@itemx spr @var{groupno} @var{registerno @var{value}}
17696@itemx spr @var{registerno @var{value}}
17697Writes @var{value} to specified spr register.
17698@end table
17699
17700Some implementations of OpenRISC 1000 Architecture also have hardware trace.
17701It is very similar to @value{GDBN} trace, except it does not interfere with normal
17702program execution and is thus much faster. Hardware breakpoints/watchpoint
17703triggers can be set using:
17704@table @code
17705@item $LEA/$LDATA
17706Load effective address/data
17707@item $SEA/$SDATA
17708Store effective address/data
17709@item $AEA/$ADATA
17710Access effective address ($SEA or $LEA) or data ($SDATA/$LDATA)
17711@item $FETCH
17712Fetch data
17713@end table
17714
17715When triggered, it can capture low level data, like: @code{PC}, @code{LSEA},
17716@code{LDATA}, @code{SDATA}, @code{READSPR}, @code{WRITESPR}, @code{INSTR}.
17717
17718@code{htrace} commands:
17719@cindex OpenRISC 1000 htrace
17720@table @code
17721@kindex hwatch
17722@item hwatch @var{conditional}
d3e8051b 17723Set hardware watchpoint on combination of Load/Store Effective Address(es)
a37295f9
MM
17724or Data. For example:
17725
17726@code{hwatch ($LEA == my_var) && ($LDATA < 50) || ($SEA == my_var) && ($SDATA >= 50)}
17727
17728@code{hwatch ($LEA == my_var) && ($LDATA < 50) || ($SEA == my_var) && ($SDATA >= 50)}
17729
4644b6e3 17730@kindex htrace
a37295f9
MM
17731@item htrace info
17732Display information about current HW trace configuration.
17733
a37295f9
MM
17734@item htrace trigger @var{conditional}
17735Set starting criteria for HW trace.
17736
a37295f9
MM
17737@item htrace qualifier @var{conditional}
17738Set acquisition qualifier for HW trace.
17739
a37295f9
MM
17740@item htrace stop @var{conditional}
17741Set HW trace stopping criteria.
17742
f153cc92 17743@item htrace record [@var{data}]*
a37295f9
MM
17744Selects the data to be recorded, when qualifier is met and HW trace was
17745triggered.
17746
a37295f9 17747@item htrace enable
a37295f9
MM
17748@itemx htrace disable
17749Enables/disables the HW trace.
17750
f153cc92 17751@item htrace rewind [@var{filename}]
a37295f9
MM
17752Clears currently recorded trace data.
17753
17754If filename is specified, new trace file is made and any newly collected data
17755will be written there.
17756
f153cc92 17757@item htrace print [@var{start} [@var{len}]]
a37295f9
MM
17758Prints trace buffer, using current record configuration.
17759
a37295f9
MM
17760@item htrace mode continuous
17761Set continuous trace mode.
17762
a37295f9
MM
17763@item htrace mode suspend
17764Set suspend trace mode.
17765
17766@end table
17767
4acd40f3
TJB
17768@node PowerPC Embedded
17769@subsection PowerPC Embedded
104c1213 17770
55eddb0f
DJ
17771@value{GDBN} provides the following PowerPC-specific commands:
17772
104c1213 17773@table @code
55eddb0f
DJ
17774@kindex set powerpc
17775@item set powerpc soft-float
17776@itemx show powerpc soft-float
17777Force @value{GDBN} to use (or not use) a software floating point calling
17778convention. By default, @value{GDBN} selects the calling convention based
17779on the selected architecture and the provided executable file.
17780
17781@item set powerpc vector-abi
17782@itemx show powerpc vector-abi
17783Force @value{GDBN} to use the specified calling convention for vector
17784arguments and return values. The valid options are @samp{auto};
17785@samp{generic}, to avoid vector registers even if they are present;
17786@samp{altivec}, to use AltiVec registers; and @samp{spe} to use SPE
17787registers. By default, @value{GDBN} selects the calling convention
17788based on the selected architecture and the provided executable file.
17789
8e04817f
AC
17790@kindex target dink32
17791@item target dink32 @var{dev}
17792DINK32 ROM monitor.
104c1213 17793
8e04817f
AC
17794@kindex target ppcbug
17795@item target ppcbug @var{dev}
17796@kindex target ppcbug1
17797@item target ppcbug1 @var{dev}
17798PPCBUG ROM monitor for PowerPC.
104c1213 17799
8e04817f
AC
17800@kindex target sds
17801@item target sds @var{dev}
17802SDS monitor, running on a PowerPC board (such as Motorola's ADS).
c45da7e6 17803@end table
8e04817f 17804
c45da7e6 17805@cindex SDS protocol
d52fb0e9 17806The following commands specific to the SDS protocol are supported
55eddb0f 17807by @value{GDBN}:
c45da7e6
EZ
17808
17809@table @code
17810@item set sdstimeout @var{nsec}
17811@kindex set sdstimeout
17812Set the timeout for SDS protocol reads to be @var{nsec} seconds. The
17813default is 2 seconds.
17814
17815@item show sdstimeout
17816@kindex show sdstimeout
17817Show the current value of the SDS timeout.
17818
17819@item sds @var{command}
17820@kindex sds@r{, a command}
17821Send the specified @var{command} string to the SDS monitor.
8e04817f
AC
17822@end table
17823
c45da7e6 17824
8e04817f
AC
17825@node PA
17826@subsection HP PA Embedded
104c1213
JM
17827
17828@table @code
17829
8e04817f
AC
17830@kindex target op50n
17831@item target op50n @var{dev}
17832OP50N monitor, running on an OKI HPPA board.
17833
17834@kindex target w89k
17835@item target w89k @var{dev}
17836W89K monitor, running on a Winbond HPPA board.
104c1213
JM
17837
17838@end table
17839
8e04817f
AC
17840@node Sparclet
17841@subsection Tsqware Sparclet
104c1213 17842
8e04817f
AC
17843@cindex Sparclet
17844
17845@value{GDBN} enables developers to debug tasks running on
17846Sparclet targets from a Unix host.
17847@value{GDBN} uses code that runs on
17848both the Unix host and on the Sparclet target. The program
17849@code{@value{GDBP}} is installed and executed on the Unix host.
104c1213 17850
8e04817f
AC
17851@table @code
17852@item remotetimeout @var{args}
17853@kindex remotetimeout
17854@value{GDBN} supports the option @code{remotetimeout}.
17855This option is set by the user, and @var{args} represents the number of
17856seconds @value{GDBN} waits for responses.
104c1213
JM
17857@end table
17858
8e04817f
AC
17859@cindex compiling, on Sparclet
17860When compiling for debugging, include the options @samp{-g} to get debug
17861information and @samp{-Ttext} to relocate the program to where you wish to
17862load it on the target. You may also want to add the options @samp{-n} or
17863@samp{-N} in order to reduce the size of the sections. Example:
104c1213 17864
474c8240 17865@smallexample
8e04817f 17866sparclet-aout-gcc prog.c -Ttext 0x12010000 -g -o prog -N
474c8240 17867@end smallexample
104c1213 17868
8e04817f 17869You can use @code{objdump} to verify that the addresses are what you intended:
104c1213 17870
474c8240 17871@smallexample
8e04817f 17872sparclet-aout-objdump --headers --syms prog
474c8240 17873@end smallexample
104c1213 17874
8e04817f
AC
17875@cindex running, on Sparclet
17876Once you have set
17877your Unix execution search path to find @value{GDBN}, you are ready to
17878run @value{GDBN}. From your Unix host, run @code{@value{GDBP}}
17879(or @code{sparclet-aout-gdb}, depending on your installation).
104c1213 17880
8e04817f
AC
17881@value{GDBN} comes up showing the prompt:
17882
474c8240 17883@smallexample
8e04817f 17884(gdbslet)
474c8240 17885@end smallexample
104c1213
JM
17886
17887@menu
8e04817f
AC
17888* Sparclet File:: Setting the file to debug
17889* Sparclet Connection:: Connecting to Sparclet
17890* Sparclet Download:: Sparclet download
17891* Sparclet Execution:: Running and debugging
104c1213
JM
17892@end menu
17893
8e04817f 17894@node Sparclet File
79a6e687 17895@subsubsection Setting File to Debug
104c1213 17896
8e04817f 17897The @value{GDBN} command @code{file} lets you choose with program to debug.
104c1213 17898
474c8240 17899@smallexample
8e04817f 17900(gdbslet) file prog
474c8240 17901@end smallexample
104c1213 17902
8e04817f
AC
17903@need 1000
17904@value{GDBN} then attempts to read the symbol table of @file{prog}.
17905@value{GDBN} locates
17906the file by searching the directories listed in the command search
17907path.
12c27660 17908If the file was compiled with debug information (option @samp{-g}), source
8e04817f
AC
17909files will be searched as well.
17910@value{GDBN} locates
17911the source files by searching the directories listed in the directory search
79a6e687 17912path (@pxref{Environment, ,Your Program's Environment}).
8e04817f
AC
17913If it fails
17914to find a file, it displays a message such as:
104c1213 17915
474c8240 17916@smallexample
8e04817f 17917prog: No such file or directory.
474c8240 17918@end smallexample
104c1213 17919
8e04817f
AC
17920When this happens, add the appropriate directories to the search paths with
17921the @value{GDBN} commands @code{path} and @code{dir}, and execute the
17922@code{target} command again.
104c1213 17923
8e04817f
AC
17924@node Sparclet Connection
17925@subsubsection Connecting to Sparclet
104c1213 17926
8e04817f
AC
17927The @value{GDBN} command @code{target} lets you connect to a Sparclet target.
17928To connect to a target on serial port ``@code{ttya}'', type:
104c1213 17929
474c8240 17930@smallexample
8e04817f
AC
17931(gdbslet) target sparclet /dev/ttya
17932Remote target sparclet connected to /dev/ttya
17933main () at ../prog.c:3
474c8240 17934@end smallexample
104c1213 17935
8e04817f
AC
17936@need 750
17937@value{GDBN} displays messages like these:
104c1213 17938
474c8240 17939@smallexample
8e04817f 17940Connected to ttya.
474c8240 17941@end smallexample
104c1213 17942
8e04817f 17943@node Sparclet Download
79a6e687 17944@subsubsection Sparclet Download
104c1213 17945
8e04817f
AC
17946@cindex download to Sparclet
17947Once connected to the Sparclet target,
17948you can use the @value{GDBN}
17949@code{load} command to download the file from the host to the target.
17950The file name and load offset should be given as arguments to the @code{load}
17951command.
17952Since the file format is aout, the program must be loaded to the starting
17953address. You can use @code{objdump} to find out what this value is. The load
17954offset is an offset which is added to the VMA (virtual memory address)
17955of each of the file's sections.
17956For instance, if the program
17957@file{prog} was linked to text address 0x1201000, with data at 0x12010160
17958and bss at 0x12010170, in @value{GDBN}, type:
104c1213 17959
474c8240 17960@smallexample
8e04817f
AC
17961(gdbslet) load prog 0x12010000
17962Loading section .text, size 0xdb0 vma 0x12010000
474c8240 17963@end smallexample
104c1213 17964
8e04817f
AC
17965If the code is loaded at a different address then what the program was linked
17966to, you may need to use the @code{section} and @code{add-symbol-file} commands
17967to tell @value{GDBN} where to map the symbol table.
17968
17969@node Sparclet Execution
79a6e687 17970@subsubsection Running and Debugging
8e04817f
AC
17971
17972@cindex running and debugging Sparclet programs
17973You can now begin debugging the task using @value{GDBN}'s execution control
17974commands, @code{b}, @code{step}, @code{run}, etc. See the @value{GDBN}
17975manual for the list of commands.
17976
474c8240 17977@smallexample
8e04817f
AC
17978(gdbslet) b main
17979Breakpoint 1 at 0x12010000: file prog.c, line 3.
17980(gdbslet) run
17981Starting program: prog
17982Breakpoint 1, main (argc=1, argv=0xeffff21c) at prog.c:3
179833 char *symarg = 0;
17984(gdbslet) step
179854 char *execarg = "hello!";
17986(gdbslet)
474c8240 17987@end smallexample
8e04817f
AC
17988
17989@node Sparclite
17990@subsection Fujitsu Sparclite
104c1213
JM
17991
17992@table @code
17993
8e04817f
AC
17994@kindex target sparclite
17995@item target sparclite @var{dev}
17996Fujitsu sparclite boards, used only for the purpose of loading.
17997You must use an additional command to debug the program.
17998For example: target remote @var{dev} using @value{GDBN} standard
17999remote protocol.
104c1213
JM
18000
18001@end table
18002
8e04817f
AC
18003@node Z8000
18004@subsection Zilog Z8000
104c1213 18005
8e04817f
AC
18006@cindex Z8000
18007@cindex simulator, Z8000
18008@cindex Zilog Z8000 simulator
104c1213 18009
8e04817f
AC
18010When configured for debugging Zilog Z8000 targets, @value{GDBN} includes
18011a Z8000 simulator.
18012
18013For the Z8000 family, @samp{target sim} simulates either the Z8002 (the
18014unsegmented variant of the Z8000 architecture) or the Z8001 (the
18015segmented variant). The simulator recognizes which architecture is
18016appropriate by inspecting the object code.
104c1213 18017
8e04817f
AC
18018@table @code
18019@item target sim @var{args}
18020@kindex sim
18021@kindex target sim@r{, with Z8000}
18022Debug programs on a simulated CPU. If the simulator supports setup
18023options, specify them via @var{args}.
104c1213
JM
18024@end table
18025
8e04817f
AC
18026@noindent
18027After specifying this target, you can debug programs for the simulated
18028CPU in the same style as programs for your host computer; use the
18029@code{file} command to load a new program image, the @code{run} command
18030to run your program, and so on.
18031
18032As well as making available all the usual machine registers
18033(@pxref{Registers, ,Registers}), the Z8000 simulator provides three
18034additional items of information as specially named registers:
104c1213
JM
18035
18036@table @code
18037
8e04817f
AC
18038@item cycles
18039Counts clock-ticks in the simulator.
104c1213 18040
8e04817f
AC
18041@item insts
18042Counts instructions run in the simulator.
104c1213 18043
8e04817f
AC
18044@item time
18045Execution time in 60ths of a second.
104c1213 18046
8e04817f 18047@end table
104c1213 18048
8e04817f
AC
18049You can refer to these values in @value{GDBN} expressions with the usual
18050conventions; for example, @w{@samp{b fputc if $cycles>5000}} sets a
18051conditional breakpoint that suspends only after at least 5000
18052simulated clock ticks.
104c1213 18053
a64548ea
EZ
18054@node AVR
18055@subsection Atmel AVR
18056@cindex AVR
18057
18058When configured for debugging the Atmel AVR, @value{GDBN} supports the
18059following AVR-specific commands:
18060
18061@table @code
18062@item info io_registers
18063@kindex info io_registers@r{, AVR}
18064@cindex I/O registers (Atmel AVR)
18065This command displays information about the AVR I/O registers. For
18066each register, @value{GDBN} prints its number and value.
18067@end table
18068
18069@node CRIS
18070@subsection CRIS
18071@cindex CRIS
18072
18073When configured for debugging CRIS, @value{GDBN} provides the
18074following CRIS-specific commands:
18075
18076@table @code
18077@item set cris-version @var{ver}
18078@cindex CRIS version
e22e55c9
OF
18079Set the current CRIS version to @var{ver}, either @samp{10} or @samp{32}.
18080The CRIS version affects register names and sizes. This command is useful in
18081case autodetection of the CRIS version fails.
a64548ea
EZ
18082
18083@item show cris-version
18084Show the current CRIS version.
18085
18086@item set cris-dwarf2-cfi
18087@cindex DWARF-2 CFI and CRIS
e22e55c9
OF
18088Set the usage of DWARF-2 CFI for CRIS debugging. The default is @samp{on}.
18089Change to @samp{off} when using @code{gcc-cris} whose version is below
18090@code{R59}.
a64548ea
EZ
18091
18092@item show cris-dwarf2-cfi
18093Show the current state of using DWARF-2 CFI.
e22e55c9
OF
18094
18095@item set cris-mode @var{mode}
18096@cindex CRIS mode
18097Set the current CRIS mode to @var{mode}. It should only be changed when
18098debugging in guru mode, in which case it should be set to
18099@samp{guru} (the default is @samp{normal}).
18100
18101@item show cris-mode
18102Show the current CRIS mode.
a64548ea
EZ
18103@end table
18104
18105@node Super-H
18106@subsection Renesas Super-H
18107@cindex Super-H
18108
18109For the Renesas Super-H processor, @value{GDBN} provides these
18110commands:
18111
18112@table @code
18113@item regs
18114@kindex regs@r{, Super-H}
18115Show the values of all Super-H registers.
c055b101
CV
18116
18117@item set sh calling-convention @var{convention}
18118@kindex set sh calling-convention
18119Set the calling-convention used when calling functions from @value{GDBN}.
18120Allowed values are @samp{gcc}, which is the default setting, and @samp{renesas}.
18121With the @samp{gcc} setting, functions are called using the @value{NGCC} calling
18122convention. If the DWARF-2 information of the called function specifies
18123that the function follows the Renesas calling convention, the function
18124is called using the Renesas calling convention. If the calling convention
18125is set to @samp{renesas}, the Renesas calling convention is always used,
18126regardless of the DWARF-2 information. This can be used to override the
18127default of @samp{gcc} if debug information is missing, or the compiler
18128does not emit the DWARF-2 calling convention entry for a function.
18129
18130@item show sh calling-convention
18131@kindex show sh calling-convention
18132Show the current calling convention setting.
18133
a64548ea
EZ
18134@end table
18135
18136
8e04817f
AC
18137@node Architectures
18138@section Architectures
104c1213 18139
8e04817f
AC
18140This section describes characteristics of architectures that affect
18141all uses of @value{GDBN} with the architecture, both native and cross.
104c1213 18142
8e04817f 18143@menu
9c16f35a 18144* i386::
8e04817f
AC
18145* A29K::
18146* Alpha::
18147* MIPS::
a64548ea 18148* HPPA:: HP PA architecture
23d964e7 18149* SPU:: Cell Broadband Engine SPU architecture
4acd40f3 18150* PowerPC::
8e04817f 18151@end menu
104c1213 18152
9c16f35a 18153@node i386
db2e3e2e 18154@subsection x86 Architecture-specific Issues
9c16f35a
EZ
18155
18156@table @code
18157@item set struct-convention @var{mode}
18158@kindex set struct-convention
18159@cindex struct return convention
18160@cindex struct/union returned in registers
18161Set the convention used by the inferior to return @code{struct}s and
18162@code{union}s from functions to @var{mode}. Possible values of
18163@var{mode} are @code{"pcc"}, @code{"reg"}, and @code{"default"} (the
18164default). @code{"default"} or @code{"pcc"} means that @code{struct}s
18165are returned on the stack, while @code{"reg"} means that a
18166@code{struct} or a @code{union} whose size is 1, 2, 4, or 8 bytes will
18167be returned in a register.
18168
18169@item show struct-convention
18170@kindex show struct-convention
18171Show the current setting of the convention to return @code{struct}s
18172from functions.
18173@end table
18174
8e04817f
AC
18175@node A29K
18176@subsection A29K
104c1213
JM
18177
18178@table @code
104c1213 18179
8e04817f
AC
18180@kindex set rstack_high_address
18181@cindex AMD 29K register stack
18182@cindex register stack, AMD29K
18183@item set rstack_high_address @var{address}
18184On AMD 29000 family processors, registers are saved in a separate
18185@dfn{register stack}. There is no way for @value{GDBN} to determine the
18186extent of this stack. Normally, @value{GDBN} just assumes that the
18187stack is ``large enough''. This may result in @value{GDBN} referencing
18188memory locations that do not exist. If necessary, you can get around
18189this problem by specifying the ending address of the register stack with
18190the @code{set rstack_high_address} command. The argument should be an
18191address, which you probably want to precede with @samp{0x} to specify in
18192hexadecimal.
104c1213 18193
8e04817f
AC
18194@kindex show rstack_high_address
18195@item show rstack_high_address
18196Display the current limit of the register stack, on AMD 29000 family
18197processors.
104c1213 18198
8e04817f 18199@end table
104c1213 18200
8e04817f
AC
18201@node Alpha
18202@subsection Alpha
104c1213 18203
8e04817f 18204See the following section.
104c1213 18205
8e04817f
AC
18206@node MIPS
18207@subsection MIPS
104c1213 18208
8e04817f
AC
18209@cindex stack on Alpha
18210@cindex stack on MIPS
18211@cindex Alpha stack
18212@cindex MIPS stack
18213Alpha- and MIPS-based computers use an unusual stack frame, which
18214sometimes requires @value{GDBN} to search backward in the object code to
18215find the beginning of a function.
104c1213 18216
8e04817f
AC
18217@cindex response time, MIPS debugging
18218To improve response time (especially for embedded applications, where
18219@value{GDBN} may be restricted to a slow serial line for this search)
18220you may want to limit the size of this search, using one of these
18221commands:
104c1213 18222
8e04817f
AC
18223@table @code
18224@cindex @code{heuristic-fence-post} (Alpha, MIPS)
18225@item set heuristic-fence-post @var{limit}
18226Restrict @value{GDBN} to examining at most @var{limit} bytes in its
18227search for the beginning of a function. A value of @var{0} (the
18228default) means there is no limit. However, except for @var{0}, the
18229larger the limit the more bytes @code{heuristic-fence-post} must search
e2f4edfd
EZ
18230and therefore the longer it takes to run. You should only need to use
18231this command when debugging a stripped executable.
104c1213 18232
8e04817f
AC
18233@item show heuristic-fence-post
18234Display the current limit.
18235@end table
104c1213
JM
18236
18237@noindent
8e04817f
AC
18238These commands are available @emph{only} when @value{GDBN} is configured
18239for debugging programs on Alpha or MIPS processors.
104c1213 18240
a64548ea
EZ
18241Several MIPS-specific commands are available when debugging MIPS
18242programs:
18243
18244@table @code
a64548ea
EZ
18245@item set mips abi @var{arg}
18246@kindex set mips abi
18247@cindex set ABI for MIPS
18248Tell @value{GDBN} which MIPS ABI is used by the inferior. Possible
18249values of @var{arg} are:
18250
18251@table @samp
18252@item auto
18253The default ABI associated with the current binary (this is the
18254default).
18255@item o32
18256@item o64
18257@item n32
18258@item n64
18259@item eabi32
18260@item eabi64
18261@item auto
18262@end table
18263
18264@item show mips abi
18265@kindex show mips abi
18266Show the MIPS ABI used by @value{GDBN} to debug the inferior.
18267
18268@item set mipsfpu
18269@itemx show mipsfpu
18270@xref{MIPS Embedded, set mipsfpu}.
18271
18272@item set mips mask-address @var{arg}
18273@kindex set mips mask-address
18274@cindex MIPS addresses, masking
18275This command determines whether the most-significant 32 bits of 64-bit
18276MIPS addresses are masked off. The argument @var{arg} can be
18277@samp{on}, @samp{off}, or @samp{auto}. The latter is the default
18278setting, which lets @value{GDBN} determine the correct value.
18279
18280@item show mips mask-address
18281@kindex show mips mask-address
18282Show whether the upper 32 bits of MIPS addresses are masked off or
18283not.
18284
18285@item set remote-mips64-transfers-32bit-regs
18286@kindex set remote-mips64-transfers-32bit-regs
18287This command controls compatibility with 64-bit MIPS targets that
18288transfer data in 32-bit quantities. If you have an old MIPS 64 target
18289that transfers 32 bits for some registers, like @sc{sr} and @sc{fsr},
18290and 64 bits for other registers, set this option to @samp{on}.
18291
18292@item show remote-mips64-transfers-32bit-regs
18293@kindex show remote-mips64-transfers-32bit-regs
18294Show the current setting of compatibility with older MIPS 64 targets.
18295
18296@item set debug mips
18297@kindex set debug mips
18298This command turns on and off debugging messages for the MIPS-specific
18299target code in @value{GDBN}.
18300
18301@item show debug mips
18302@kindex show debug mips
18303Show the current setting of MIPS debugging messages.
18304@end table
18305
18306
18307@node HPPA
18308@subsection HPPA
18309@cindex HPPA support
18310
d3e8051b 18311When @value{GDBN} is debugging the HP PA architecture, it provides the
a64548ea
EZ
18312following special commands:
18313
18314@table @code
18315@item set debug hppa
18316@kindex set debug hppa
db2e3e2e 18317This command determines whether HPPA architecture-specific debugging
a64548ea
EZ
18318messages are to be displayed.
18319
18320@item show debug hppa
18321Show whether HPPA debugging messages are displayed.
18322
18323@item maint print unwind @var{address}
18324@kindex maint print unwind@r{, HPPA}
18325This command displays the contents of the unwind table entry at the
18326given @var{address}.
18327
18328@end table
18329
104c1213 18330
23d964e7
UW
18331@node SPU
18332@subsection Cell Broadband Engine SPU architecture
18333@cindex Cell Broadband Engine
18334@cindex SPU
18335
18336When @value{GDBN} is debugging the Cell Broadband Engine SPU architecture,
18337it provides the following special commands:
18338
18339@table @code
18340@item info spu event
18341@kindex info spu
18342Display SPU event facility status. Shows current event mask
18343and pending event status.
18344
18345@item info spu signal
18346Display SPU signal notification facility status. Shows pending
18347signal-control word and signal notification mode of both signal
18348notification channels.
18349
18350@item info spu mailbox
18351Display SPU mailbox facility status. Shows all pending entries,
18352in order of processing, in each of the SPU Write Outbound,
18353SPU Write Outbound Interrupt, and SPU Read Inbound mailboxes.
18354
18355@item info spu dma
18356Display MFC DMA status. Shows all pending commands in the MFC
18357DMA queue. For each entry, opcode, tag, class IDs, effective
18358and local store addresses and transfer size are shown.
18359
18360@item info spu proxydma
18361Display MFC Proxy-DMA status. Shows all pending commands in the MFC
18362Proxy-DMA queue. For each entry, opcode, tag, class IDs, effective
18363and local store addresses and transfer size are shown.
18364
18365@end table
18366
3285f3fe
UW
18367When @value{GDBN} is debugging a combined PowerPC/SPU application
18368on the Cell Broadband Engine, it provides in addition the following
18369special commands:
18370
18371@table @code
18372@item set spu stop-on-load @var{arg}
18373@kindex set spu
18374Set whether to stop for new SPE threads. When set to @code{on}, @value{GDBN}
18375will give control to the user when a new SPE thread enters its @code{main}
18376function. The default is @code{off}.
18377
18378@item show spu stop-on-load
18379@kindex show spu
18380Show whether to stop for new SPE threads.
18381
ff1a52c6
UW
18382@item set spu auto-flush-cache @var{arg}
18383Set whether to automatically flush the software-managed cache. When set to
18384@code{on}, @value{GDBN} will automatically cause the SPE software-managed
18385cache to be flushed whenever SPE execution stops. This provides a consistent
18386view of PowerPC memory that is accessed via the cache. If an application
18387does not use the software-managed cache, this option has no effect.
18388
18389@item show spu auto-flush-cache
18390Show whether to automatically flush the software-managed cache.
18391
3285f3fe
UW
18392@end table
18393
4acd40f3
TJB
18394@node PowerPC
18395@subsection PowerPC
18396@cindex PowerPC architecture
18397
18398When @value{GDBN} is debugging the PowerPC architecture, it provides a set of
18399pseudo-registers to enable inspection of 128-bit wide Decimal Floating Point
18400numbers stored in the floating point registers. These values must be stored
18401in two consecutive registers, always starting at an even register like
18402@code{f0} or @code{f2}.
18403
18404The pseudo-registers go from @code{$dl0} through @code{$dl15}, and are formed
18405by joining the even/odd register pairs @code{f0} and @code{f1} for @code{$dl0},
18406@code{f2} and @code{f3} for @code{$dl1} and so on.
18407
aeac0ff9 18408For POWER7 processors, @value{GDBN} provides a set of pseudo-registers, the 64-bit
677c5bb1
LM
18409wide Extended Floating Point Registers (@samp{f32} through @samp{f63}).
18410
23d964e7 18411
8e04817f
AC
18412@node Controlling GDB
18413@chapter Controlling @value{GDBN}
18414
18415You can alter the way @value{GDBN} interacts with you by using the
18416@code{set} command. For commands controlling how @value{GDBN} displays
79a6e687 18417data, see @ref{Print Settings, ,Print Settings}. Other settings are
8e04817f
AC
18418described here.
18419
18420@menu
18421* Prompt:: Prompt
18422* Editing:: Command editing
d620b259 18423* Command History:: Command history
8e04817f
AC
18424* Screen Size:: Screen size
18425* Numbers:: Numbers
1e698235 18426* ABI:: Configuring the current ABI
8e04817f
AC
18427* Messages/Warnings:: Optional warnings and messages
18428* Debugging Output:: Optional messages about internal happenings
14fb1bac 18429* Other Misc Settings:: Other Miscellaneous Settings
8e04817f
AC
18430@end menu
18431
18432@node Prompt
18433@section Prompt
104c1213 18434
8e04817f 18435@cindex prompt
104c1213 18436
8e04817f
AC
18437@value{GDBN} indicates its readiness to read a command by printing a string
18438called the @dfn{prompt}. This string is normally @samp{(@value{GDBP})}. You
18439can change the prompt string with the @code{set prompt} command. For
18440instance, when debugging @value{GDBN} with @value{GDBN}, it is useful to change
18441the prompt in one of the @value{GDBN} sessions so that you can always tell
18442which one you are talking to.
104c1213 18443
8e04817f
AC
18444@emph{Note:} @code{set prompt} does not add a space for you after the
18445prompt you set. This allows you to set a prompt which ends in a space
18446or a prompt that does not.
104c1213 18447
8e04817f
AC
18448@table @code
18449@kindex set prompt
18450@item set prompt @var{newprompt}
18451Directs @value{GDBN} to use @var{newprompt} as its prompt string henceforth.
104c1213 18452
8e04817f
AC
18453@kindex show prompt
18454@item show prompt
18455Prints a line of the form: @samp{Gdb's prompt is: @var{your-prompt}}
104c1213
JM
18456@end table
18457
8e04817f 18458@node Editing
79a6e687 18459@section Command Editing
8e04817f
AC
18460@cindex readline
18461@cindex command line editing
104c1213 18462
703663ab 18463@value{GDBN} reads its input commands via the @dfn{Readline} interface. This
8e04817f
AC
18464@sc{gnu} library provides consistent behavior for programs which provide a
18465command line interface to the user. Advantages are @sc{gnu} Emacs-style
18466or @dfn{vi}-style inline editing of commands, @code{csh}-like history
18467substitution, and a storage and recall of command history across
18468debugging sessions.
104c1213 18469
8e04817f
AC
18470You may control the behavior of command line editing in @value{GDBN} with the
18471command @code{set}.
104c1213 18472
8e04817f
AC
18473@table @code
18474@kindex set editing
18475@cindex editing
18476@item set editing
18477@itemx set editing on
18478Enable command line editing (enabled by default).
104c1213 18479
8e04817f
AC
18480@item set editing off
18481Disable command line editing.
104c1213 18482
8e04817f
AC
18483@kindex show editing
18484@item show editing
18485Show whether command line editing is enabled.
104c1213
JM
18486@end table
18487
703663ab
EZ
18488@xref{Command Line Editing}, for more details about the Readline
18489interface. Users unfamiliar with @sc{gnu} Emacs or @code{vi} are
18490encouraged to read that chapter.
18491
d620b259 18492@node Command History
79a6e687 18493@section Command History
703663ab 18494@cindex command history
8e04817f
AC
18495
18496@value{GDBN} can keep track of the commands you type during your
18497debugging sessions, so that you can be certain of precisely what
18498happened. Use these commands to manage the @value{GDBN} command
18499history facility.
104c1213 18500
703663ab
EZ
18501@value{GDBN} uses the @sc{gnu} History library, a part of the Readline
18502package, to provide the history facility. @xref{Using History
18503Interactively}, for the detailed description of the History library.
18504
d620b259 18505To issue a command to @value{GDBN} without affecting certain aspects of
9e6c4bd5
NR
18506the state which is seen by users, prefix it with @samp{server }
18507(@pxref{Server Prefix}). This
d620b259
NR
18508means that this command will not affect the command history, nor will it
18509affect @value{GDBN}'s notion of which command to repeat if @key{RET} is
18510pressed on a line by itself.
18511
18512@cindex @code{server}, command prefix
18513The server prefix does not affect the recording of values into the value
18514history; to print a value without recording it into the value history,
18515use the @code{output} command instead of the @code{print} command.
18516
703663ab
EZ
18517Here is the description of @value{GDBN} commands related to command
18518history.
18519
104c1213 18520@table @code
8e04817f
AC
18521@cindex history substitution
18522@cindex history file
18523@kindex set history filename
4644b6e3 18524@cindex @env{GDBHISTFILE}, environment variable
8e04817f
AC
18525@item set history filename @var{fname}
18526Set the name of the @value{GDBN} command history file to @var{fname}.
18527This is the file where @value{GDBN} reads an initial command history
18528list, and where it writes the command history from this session when it
18529exits. You can access this list through history expansion or through
18530the history command editing characters listed below. This file defaults
18531to the value of the environment variable @code{GDBHISTFILE}, or to
18532@file{./.gdb_history} (@file{./_gdb_history} on MS-DOS) if this variable
18533is not set.
104c1213 18534
9c16f35a
EZ
18535@cindex save command history
18536@kindex set history save
8e04817f
AC
18537@item set history save
18538@itemx set history save on
18539Record command history in a file, whose name may be specified with the
18540@code{set history filename} command. By default, this option is disabled.
104c1213 18541
8e04817f
AC
18542@item set history save off
18543Stop recording command history in a file.
104c1213 18544
8e04817f 18545@cindex history size
9c16f35a 18546@kindex set history size
6fc08d32 18547@cindex @env{HISTSIZE}, environment variable
8e04817f
AC
18548@item set history size @var{size}
18549Set the number of commands which @value{GDBN} keeps in its history list.
18550This defaults to the value of the environment variable
18551@code{HISTSIZE}, or to 256 if this variable is not set.
104c1213
JM
18552@end table
18553
8e04817f 18554History expansion assigns special meaning to the character @kbd{!}.
703663ab 18555@xref{Event Designators}, for more details.
8e04817f 18556
703663ab 18557@cindex history expansion, turn on/off
8e04817f
AC
18558Since @kbd{!} is also the logical not operator in C, history expansion
18559is off by default. If you decide to enable history expansion with the
18560@code{set history expansion on} command, you may sometimes need to
18561follow @kbd{!} (when it is used as logical not, in an expression) with
18562a space or a tab to prevent it from being expanded. The readline
18563history facilities do not attempt substitution on the strings
18564@kbd{!=} and @kbd{!(}, even when history expansion is enabled.
18565
18566The commands to control history expansion are:
104c1213
JM
18567
18568@table @code
8e04817f
AC
18569@item set history expansion on
18570@itemx set history expansion
703663ab 18571@kindex set history expansion
8e04817f 18572Enable history expansion. History expansion is off by default.
104c1213 18573
8e04817f
AC
18574@item set history expansion off
18575Disable history expansion.
104c1213 18576
8e04817f
AC
18577@c @group
18578@kindex show history
18579@item show history
18580@itemx show history filename
18581@itemx show history save
18582@itemx show history size
18583@itemx show history expansion
18584These commands display the state of the @value{GDBN} history parameters.
18585@code{show history} by itself displays all four states.
18586@c @end group
18587@end table
18588
18589@table @code
9c16f35a
EZ
18590@kindex show commands
18591@cindex show last commands
18592@cindex display command history
8e04817f
AC
18593@item show commands
18594Display the last ten commands in the command history.
104c1213 18595
8e04817f
AC
18596@item show commands @var{n}
18597Print ten commands centered on command number @var{n}.
18598
18599@item show commands +
18600Print ten commands just after the commands last printed.
104c1213
JM
18601@end table
18602
8e04817f 18603@node Screen Size
79a6e687 18604@section Screen Size
8e04817f
AC
18605@cindex size of screen
18606@cindex pauses in output
104c1213 18607
8e04817f
AC
18608Certain commands to @value{GDBN} may produce large amounts of
18609information output to the screen. To help you read all of it,
18610@value{GDBN} pauses and asks you for input at the end of each page of
18611output. Type @key{RET} when you want to continue the output, or @kbd{q}
18612to discard the remaining output. Also, the screen width setting
18613determines when to wrap lines of output. Depending on what is being
18614printed, @value{GDBN} tries to break the line at a readable place,
18615rather than simply letting it overflow onto the following line.
18616
18617Normally @value{GDBN} knows the size of the screen from the terminal
18618driver software. For example, on Unix @value{GDBN} uses the termcap data base
18619together with the value of the @code{TERM} environment variable and the
18620@code{stty rows} and @code{stty cols} settings. If this is not correct,
18621you can override it with the @code{set height} and @code{set
18622width} commands:
18623
18624@table @code
18625@kindex set height
18626@kindex set width
18627@kindex show width
18628@kindex show height
18629@item set height @var{lpp}
18630@itemx show height
18631@itemx set width @var{cpl}
18632@itemx show width
18633These @code{set} commands specify a screen height of @var{lpp} lines and
18634a screen width of @var{cpl} characters. The associated @code{show}
18635commands display the current settings.
104c1213 18636
8e04817f
AC
18637If you specify a height of zero lines, @value{GDBN} does not pause during
18638output no matter how long the output is. This is useful if output is to a
18639file or to an editor buffer.
104c1213 18640
8e04817f
AC
18641Likewise, you can specify @samp{set width 0} to prevent @value{GDBN}
18642from wrapping its output.
9c16f35a
EZ
18643
18644@item set pagination on
18645@itemx set pagination off
18646@kindex set pagination
18647Turn the output pagination on or off; the default is on. Turning
7c953934
TT
18648pagination off is the alternative to @code{set height 0}. Note that
18649running @value{GDBN} with the @option{--batch} option (@pxref{Mode
18650Options, -batch}) also automatically disables pagination.
9c16f35a
EZ
18651
18652@item show pagination
18653@kindex show pagination
18654Show the current pagination mode.
104c1213
JM
18655@end table
18656
8e04817f
AC
18657@node Numbers
18658@section Numbers
18659@cindex number representation
18660@cindex entering numbers
104c1213 18661
8e04817f
AC
18662You can always enter numbers in octal, decimal, or hexadecimal in
18663@value{GDBN} by the usual conventions: octal numbers begin with
18664@samp{0}, decimal numbers end with @samp{.}, and hexadecimal numbers
eb2dae08
EZ
18665begin with @samp{0x}. Numbers that neither begin with @samp{0} or
18666@samp{0x}, nor end with a @samp{.} are, by default, entered in base
1866710; likewise, the default display for numbers---when no particular
18668format is specified---is base 10. You can change the default base for
18669both input and output with the commands described below.
104c1213 18670
8e04817f
AC
18671@table @code
18672@kindex set input-radix
18673@item set input-radix @var{base}
18674Set the default base for numeric input. Supported choices
18675for @var{base} are decimal 8, 10, or 16. @var{base} must itself be
eb2dae08 18676specified either unambiguously or using the current input radix; for
8e04817f 18677example, any of
104c1213 18678
8e04817f 18679@smallexample
9c16f35a
EZ
18680set input-radix 012
18681set input-radix 10.
18682set input-radix 0xa
8e04817f 18683@end smallexample
104c1213 18684
8e04817f 18685@noindent
9c16f35a 18686sets the input base to decimal. On the other hand, @samp{set input-radix 10}
eb2dae08
EZ
18687leaves the input radix unchanged, no matter what it was, since
18688@samp{10}, being without any leading or trailing signs of its base, is
18689interpreted in the current radix. Thus, if the current radix is 16,
18690@samp{10} is interpreted in hex, i.e.@: as 16 decimal, which doesn't
18691change the radix.
104c1213 18692
8e04817f
AC
18693@kindex set output-radix
18694@item set output-radix @var{base}
18695Set the default base for numeric display. Supported choices
18696for @var{base} are decimal 8, 10, or 16. @var{base} must itself be
eb2dae08 18697specified either unambiguously or using the current input radix.
104c1213 18698
8e04817f
AC
18699@kindex show input-radix
18700@item show input-radix
18701Display the current default base for numeric input.
104c1213 18702
8e04817f
AC
18703@kindex show output-radix
18704@item show output-radix
18705Display the current default base for numeric display.
9c16f35a
EZ
18706
18707@item set radix @r{[}@var{base}@r{]}
18708@itemx show radix
18709@kindex set radix
18710@kindex show radix
18711These commands set and show the default base for both input and output
18712of numbers. @code{set radix} sets the radix of input and output to
18713the same base; without an argument, it resets the radix back to its
18714default value of 10.
18715
8e04817f 18716@end table
104c1213 18717
1e698235 18718@node ABI
79a6e687 18719@section Configuring the Current ABI
1e698235
DJ
18720
18721@value{GDBN} can determine the @dfn{ABI} (Application Binary Interface) of your
18722application automatically. However, sometimes you need to override its
18723conclusions. Use these commands to manage @value{GDBN}'s view of the
18724current ABI.
18725
98b45e30
DJ
18726@cindex OS ABI
18727@kindex set osabi
b4e9345d 18728@kindex show osabi
98b45e30
DJ
18729
18730One @value{GDBN} configuration can debug binaries for multiple operating
b383017d 18731system targets, either via remote debugging or native emulation.
98b45e30
DJ
18732@value{GDBN} will autodetect the @dfn{OS ABI} (Operating System ABI) in use,
18733but you can override its conclusion using the @code{set osabi} command.
18734One example where this is useful is in debugging of binaries which use
18735an alternate C library (e.g.@: @sc{uClibc} for @sc{gnu}/Linux) which does
18736not have the same identifying marks that the standard C library for your
18737platform provides.
18738
18739@table @code
18740@item show osabi
18741Show the OS ABI currently in use.
18742
18743@item set osabi
18744With no argument, show the list of registered available OS ABI's.
18745
18746@item set osabi @var{abi}
18747Set the current OS ABI to @var{abi}.
18748@end table
18749
1e698235 18750@cindex float promotion
1e698235
DJ
18751
18752Generally, the way that an argument of type @code{float} is passed to a
18753function depends on whether the function is prototyped. For a prototyped
18754(i.e.@: ANSI/ISO style) function, @code{float} arguments are passed unchanged,
18755according to the architecture's convention for @code{float}. For unprototyped
18756(i.e.@: K&R style) functions, @code{float} arguments are first promoted to type
18757@code{double} and then passed.
18758
18759Unfortunately, some forms of debug information do not reliably indicate whether
18760a function is prototyped. If @value{GDBN} calls a function that is not marked
18761as prototyped, it consults @kbd{set coerce-float-to-double}.
18762
18763@table @code
a8f24a35 18764@kindex set coerce-float-to-double
1e698235
DJ
18765@item set coerce-float-to-double
18766@itemx set coerce-float-to-double on
18767Arguments of type @code{float} will be promoted to @code{double} when passed
18768to an unprototyped function. This is the default setting.
18769
18770@item set coerce-float-to-double off
18771Arguments of type @code{float} will be passed directly to unprototyped
18772functions.
9c16f35a
EZ
18773
18774@kindex show coerce-float-to-double
18775@item show coerce-float-to-double
18776Show the current setting of promoting @code{float} to @code{double}.
1e698235
DJ
18777@end table
18778
f1212245
DJ
18779@kindex set cp-abi
18780@kindex show cp-abi
18781@value{GDBN} needs to know the ABI used for your program's C@t{++}
18782objects. The correct C@t{++} ABI depends on which C@t{++} compiler was
18783used to build your application. @value{GDBN} only fully supports
18784programs with a single C@t{++} ABI; if your program contains code using
18785multiple C@t{++} ABI's or if @value{GDBN} can not identify your
18786program's ABI correctly, you can tell @value{GDBN} which ABI to use.
18787Currently supported ABI's include ``gnu-v2'', for @code{g++} versions
18788before 3.0, ``gnu-v3'', for @code{g++} versions 3.0 and later, and
18789``hpaCC'' for the HP ANSI C@t{++} compiler. Other C@t{++} compilers may
18790use the ``gnu-v2'' or ``gnu-v3'' ABI's as well. The default setting is
18791``auto''.
18792
18793@table @code
18794@item show cp-abi
18795Show the C@t{++} ABI currently in use.
18796
18797@item set cp-abi
18798With no argument, show the list of supported C@t{++} ABI's.
18799
18800@item set cp-abi @var{abi}
18801@itemx set cp-abi auto
18802Set the current C@t{++} ABI to @var{abi}, or return to automatic detection.
18803@end table
18804
8e04817f 18805@node Messages/Warnings
79a6e687 18806@section Optional Warnings and Messages
104c1213 18807
9c16f35a
EZ
18808@cindex verbose operation
18809@cindex optional warnings
8e04817f
AC
18810By default, @value{GDBN} is silent about its inner workings. If you are
18811running on a slow machine, you may want to use the @code{set verbose}
18812command. This makes @value{GDBN} tell you when it does a lengthy
18813internal operation, so you will not think it has crashed.
104c1213 18814
8e04817f
AC
18815Currently, the messages controlled by @code{set verbose} are those
18816which announce that the symbol table for a source file is being read;
79a6e687 18817see @code{symbol-file} in @ref{Files, ,Commands to Specify Files}.
104c1213 18818
8e04817f
AC
18819@table @code
18820@kindex set verbose
18821@item set verbose on
18822Enables @value{GDBN} output of certain informational messages.
104c1213 18823
8e04817f
AC
18824@item set verbose off
18825Disables @value{GDBN} output of certain informational messages.
104c1213 18826
8e04817f
AC
18827@kindex show verbose
18828@item show verbose
18829Displays whether @code{set verbose} is on or off.
18830@end table
104c1213 18831
8e04817f
AC
18832By default, if @value{GDBN} encounters bugs in the symbol table of an
18833object file, it is silent; but if you are debugging a compiler, you may
79a6e687
BW
18834find this information useful (@pxref{Symbol Errors, ,Errors Reading
18835Symbol Files}).
104c1213 18836
8e04817f 18837@table @code
104c1213 18838
8e04817f
AC
18839@kindex set complaints
18840@item set complaints @var{limit}
18841Permits @value{GDBN} to output @var{limit} complaints about each type of
18842unusual symbols before becoming silent about the problem. Set
18843@var{limit} to zero to suppress all complaints; set it to a large number
18844to prevent complaints from being suppressed.
104c1213 18845
8e04817f
AC
18846@kindex show complaints
18847@item show complaints
18848Displays how many symbol complaints @value{GDBN} is permitted to produce.
104c1213 18849
8e04817f 18850@end table
104c1213 18851
d837706a 18852@anchor{confirmation requests}
8e04817f
AC
18853By default, @value{GDBN} is cautious, and asks what sometimes seems to be a
18854lot of stupid questions to confirm certain commands. For example, if
18855you try to run a program which is already running:
104c1213 18856
474c8240 18857@smallexample
8e04817f
AC
18858(@value{GDBP}) run
18859The program being debugged has been started already.
18860Start it from the beginning? (y or n)
474c8240 18861@end smallexample
104c1213 18862
8e04817f
AC
18863If you are willing to unflinchingly face the consequences of your own
18864commands, you can disable this ``feature'':
104c1213 18865
8e04817f 18866@table @code
104c1213 18867
8e04817f
AC
18868@kindex set confirm
18869@cindex flinching
18870@cindex confirmation
18871@cindex stupid questions
18872@item set confirm off
7c953934
TT
18873Disables confirmation requests. Note that running @value{GDBN} with
18874the @option{--batch} option (@pxref{Mode Options, -batch}) also
18875automatically disables confirmation requests.
104c1213 18876
8e04817f
AC
18877@item set confirm on
18878Enables confirmation requests (the default).
104c1213 18879
8e04817f
AC
18880@kindex show confirm
18881@item show confirm
18882Displays state of confirmation requests.
18883
18884@end table
104c1213 18885
16026cd7
AS
18886@cindex command tracing
18887If you need to debug user-defined commands or sourced files you may find it
18888useful to enable @dfn{command tracing}. In this mode each command will be
18889printed as it is executed, prefixed with one or more @samp{+} symbols, the
18890quantity denoting the call depth of each command.
18891
18892@table @code
18893@kindex set trace-commands
18894@cindex command scripts, debugging
18895@item set trace-commands on
18896Enable command tracing.
18897@item set trace-commands off
18898Disable command tracing.
18899@item show trace-commands
18900Display the current state of command tracing.
18901@end table
18902
8e04817f 18903@node Debugging Output
79a6e687 18904@section Optional Messages about Internal Happenings
4644b6e3
EZ
18905@cindex optional debugging messages
18906
da316a69
EZ
18907@value{GDBN} has commands that enable optional debugging messages from
18908various @value{GDBN} subsystems; normally these commands are of
18909interest to @value{GDBN} maintainers, or when reporting a bug. This
18910section documents those commands.
18911
104c1213 18912@table @code
a8f24a35
EZ
18913@kindex set exec-done-display
18914@item set exec-done-display
18915Turns on or off the notification of asynchronous commands'
18916completion. When on, @value{GDBN} will print a message when an
18917asynchronous command finishes its execution. The default is off.
18918@kindex show exec-done-display
18919@item show exec-done-display
18920Displays the current setting of asynchronous command completion
18921notification.
4644b6e3
EZ
18922@kindex set debug
18923@cindex gdbarch debugging info
a8f24a35 18924@cindex architecture debugging info
8e04817f 18925@item set debug arch
a8f24a35 18926Turns on or off display of gdbarch debugging info. The default is off
4644b6e3 18927@kindex show debug
8e04817f
AC
18928@item show debug arch
18929Displays the current state of displaying gdbarch debugging info.
721c2651
EZ
18930@item set debug aix-thread
18931@cindex AIX threads
18932Display debugging messages about inner workings of the AIX thread
18933module.
18934@item show debug aix-thread
18935Show the current state of AIX thread debugging info display.
d97bc12b
DE
18936@item set debug dwarf2-die
18937@cindex DWARF2 DIEs
18938Dump DWARF2 DIEs after they are read in.
18939The value is the number of nesting levels to print.
18940A value of zero turns off the display.
18941@item show debug dwarf2-die
18942Show the current state of DWARF2 DIE debugging.
237fc4c9
PA
18943@item set debug displaced
18944@cindex displaced stepping debugging info
18945Turns on or off display of @value{GDBN} debugging info for the
18946displaced stepping support. The default is off.
18947@item show debug displaced
18948Displays the current state of displaying @value{GDBN} debugging info
18949related to displaced stepping.
8e04817f 18950@item set debug event
4644b6e3 18951@cindex event debugging info
a8f24a35 18952Turns on or off display of @value{GDBN} event debugging info. The
8e04817f 18953default is off.
8e04817f
AC
18954@item show debug event
18955Displays the current state of displaying @value{GDBN} event debugging
18956info.
8e04817f 18957@item set debug expression
4644b6e3 18958@cindex expression debugging info
721c2651
EZ
18959Turns on or off display of debugging info about @value{GDBN}
18960expression parsing. The default is off.
8e04817f 18961@item show debug expression
721c2651
EZ
18962Displays the current state of displaying debugging info about
18963@value{GDBN} expression parsing.
7453dc06 18964@item set debug frame
4644b6e3 18965@cindex frame debugging info
7453dc06
AC
18966Turns on or off display of @value{GDBN} frame debugging info. The
18967default is off.
7453dc06
AC
18968@item show debug frame
18969Displays the current state of displaying @value{GDBN} frame debugging
18970info.
cbe54154
PA
18971@item set debug gnu-nat
18972@cindex @sc{gnu}/Hurd debug messages
18973Turns on or off debugging messages from the @sc{gnu}/Hurd debug support.
18974@item show debug gnu-nat
18975Show the current state of @sc{gnu}/Hurd debugging messages.
30e91e0b
RC
18976@item set debug infrun
18977@cindex inferior debugging info
18978Turns on or off display of @value{GDBN} debugging info for running the inferior.
18979The default is off. @file{infrun.c} contains GDB's runtime state machine used
18980for implementing operations such as single-stepping the inferior.
18981@item show debug infrun
18982Displays the current state of @value{GDBN} inferior debugging.
da316a69
EZ
18983@item set debug lin-lwp
18984@cindex @sc{gnu}/Linux LWP debug messages
18985@cindex Linux lightweight processes
721c2651 18986Turns on or off debugging messages from the Linux LWP debug support.
da316a69
EZ
18987@item show debug lin-lwp
18988Show the current state of Linux LWP debugging messages.
b84876c2
PA
18989@item set debug lin-lwp-async
18990@cindex @sc{gnu}/Linux LWP async debug messages
18991@cindex Linux lightweight processes
18992Turns on or off debugging messages from the Linux LWP async debug support.
18993@item show debug lin-lwp-async
18994Show the current state of Linux LWP async debugging messages.
2b4855ab 18995@item set debug observer
4644b6e3 18996@cindex observer debugging info
2b4855ab
AC
18997Turns on or off display of @value{GDBN} observer debugging. This
18998includes info such as the notification of observable events.
2b4855ab
AC
18999@item show debug observer
19000Displays the current state of observer debugging.
8e04817f 19001@item set debug overload
4644b6e3 19002@cindex C@t{++} overload debugging info
8e04817f 19003Turns on or off display of @value{GDBN} C@t{++} overload debugging
359df76b 19004info. This includes info such as ranking of functions, etc. The default
8e04817f 19005is off.
8e04817f
AC
19006@item show debug overload
19007Displays the current state of displaying @value{GDBN} C@t{++} overload
19008debugging info.
92981e24
TT
19009@cindex expression parser, debugging info
19010@cindex debug expression parser
19011@item set debug parser
19012Turns on or off the display of expression parser debugging output.
19013Internally, this sets the @code{yydebug} variable in the expression
19014parser. @xref{Tracing, , Tracing Your Parser, bison, Bison}, for
19015details. The default is off.
19016@item show debug parser
19017Show the current state of expression parser debugging.
8e04817f
AC
19018@cindex packets, reporting on stdout
19019@cindex serial connections, debugging
605a56cb
DJ
19020@cindex debug remote protocol
19021@cindex remote protocol debugging
19022@cindex display remote packets
8e04817f
AC
19023@item set debug remote
19024Turns on or off display of reports on all packets sent back and forth across
19025the serial line to the remote machine. The info is printed on the
19026@value{GDBN} standard output stream. The default is off.
8e04817f
AC
19027@item show debug remote
19028Displays the state of display of remote packets.
8e04817f
AC
19029@item set debug serial
19030Turns on or off display of @value{GDBN} serial debugging info. The
19031default is off.
8e04817f
AC
19032@item show debug serial
19033Displays the current state of displaying @value{GDBN} serial debugging
19034info.
c45da7e6
EZ
19035@item set debug solib-frv
19036@cindex FR-V shared-library debugging
19037Turns on or off debugging messages for FR-V shared-library code.
19038@item show debug solib-frv
19039Display the current state of FR-V shared-library code debugging
19040messages.
8e04817f 19041@item set debug target
4644b6e3 19042@cindex target debugging info
8e04817f
AC
19043Turns on or off display of @value{GDBN} target debugging info. This info
19044includes what is going on at the target level of GDB, as it happens. The
701b08bb
DJ
19045default is 0. Set it to 1 to track events, and to 2 to also track the
19046value of large memory transfers. Changes to this flag do not take effect
19047until the next time you connect to a target or use the @code{run} command.
8e04817f
AC
19048@item show debug target
19049Displays the current state of displaying @value{GDBN} target debugging
19050info.
75feb17d
DJ
19051@item set debug timestamp
19052@cindex timestampping debugging info
19053Turns on or off display of timestamps with @value{GDBN} debugging info.
19054When enabled, seconds and microseconds are displayed before each debugging
19055message.
19056@item show debug timestamp
19057Displays the current state of displaying timestamps with @value{GDBN}
19058debugging info.
c45da7e6 19059@item set debugvarobj
4644b6e3 19060@cindex variable object debugging info
8e04817f
AC
19061Turns on or off display of @value{GDBN} variable object debugging
19062info. The default is off.
c45da7e6 19063@item show debugvarobj
8e04817f
AC
19064Displays the current state of displaying @value{GDBN} variable object
19065debugging info.
e776119f
DJ
19066@item set debug xml
19067@cindex XML parser debugging
19068Turns on or off debugging messages for built-in XML parsers.
19069@item show debug xml
19070Displays the current state of XML debugging messages.
8e04817f 19071@end table
104c1213 19072
14fb1bac
JB
19073@node Other Misc Settings
19074@section Other Miscellaneous Settings
19075@cindex miscellaneous settings
19076
19077@table @code
19078@kindex set interactive-mode
19079@item set interactive-mode
19080If @code{on}, forces @value{GDBN} to operate interactively.
19081If @code{off}, forces @value{GDBN} to operate non-interactively,
19082If @code{auto} (the default), @value{GDBN} guesses which mode to use,
19083based on whether the debugger was started in a terminal or not.
19084
19085In the vast majority of cases, the debugger should be able to guess
19086correctly which mode should be used. But this setting can be useful
19087in certain specific cases, such as running a MinGW @value{GDBN}
19088inside a cygwin window.
19089
19090@kindex show interactive-mode
19091@item show interactive-mode
19092Displays whether the debugger is operating in interactive mode or not.
19093@end table
19094
d57a3c85
TJB
19095@node Extending GDB
19096@chapter Extending @value{GDBN}
19097@cindex extending GDB
19098
19099@value{GDBN} provides two mechanisms for extension. The first is based
19100on composition of @value{GDBN} commands, and the second is based on the
19101Python scripting language.
19102
95433b34
JB
19103To facilitate the use of these extensions, @value{GDBN} is capable
19104of evaluating the contents of a file. When doing so, @value{GDBN}
19105can recognize which scripting language is being used by looking at
19106the filename extension. Files with an unrecognized filename extension
19107are always treated as a @value{GDBN} Command Files.
19108@xref{Command Files,, Command files}.
19109
19110You can control how @value{GDBN} evaluates these files with the following
19111setting:
19112
19113@table @code
19114@kindex set script-extension
19115@kindex show script-extension
19116@item set script-extension off
19117All scripts are always evaluated as @value{GDBN} Command Files.
19118
19119@item set script-extension soft
19120The debugger determines the scripting language based on filename
19121extension. If this scripting language is supported, @value{GDBN}
19122evaluates the script using that language. Otherwise, it evaluates
19123the file as a @value{GDBN} Command File.
19124
19125@item set script-extension strict
19126The debugger determines the scripting language based on filename
19127extension, and evaluates the script using that language. If the
19128language is not supported, then the evaluation fails.
19129
19130@item show script-extension
19131Display the current value of the @code{script-extension} option.
19132
19133@end table
19134
d57a3c85
TJB
19135@menu
19136* Sequences:: Canned Sequences of Commands
19137* Python:: Scripting @value{GDBN} using Python
19138@end menu
19139
8e04817f 19140@node Sequences
d57a3c85 19141@section Canned Sequences of Commands
104c1213 19142
8e04817f 19143Aside from breakpoint commands (@pxref{Break Commands, ,Breakpoint
79a6e687 19144Command Lists}), @value{GDBN} provides two ways to store sequences of
8e04817f
AC
19145commands for execution as a unit: user-defined commands and command
19146files.
104c1213 19147
8e04817f 19148@menu
fcc73fe3
EZ
19149* Define:: How to define your own commands
19150* Hooks:: Hooks for user-defined commands
19151* Command Files:: How to write scripts of commands to be stored in a file
19152* Output:: Commands for controlled output
8e04817f 19153@end menu
104c1213 19154
8e04817f 19155@node Define
d57a3c85 19156@subsection User-defined Commands
104c1213 19157
8e04817f 19158@cindex user-defined command
fcc73fe3 19159@cindex arguments, to user-defined commands
8e04817f
AC
19160A @dfn{user-defined command} is a sequence of @value{GDBN} commands to
19161which you assign a new name as a command. This is done with the
19162@code{define} command. User commands may accept up to 10 arguments
19163separated by whitespace. Arguments are accessed within the user command
c03c782f 19164via @code{$arg0@dots{}$arg9}. A trivial example:
104c1213 19165
8e04817f
AC
19166@smallexample
19167define adder
19168 print $arg0 + $arg1 + $arg2
c03c782f 19169end
8e04817f 19170@end smallexample
104c1213
JM
19171
19172@noindent
8e04817f 19173To execute the command use:
104c1213 19174
8e04817f
AC
19175@smallexample
19176adder 1 2 3
19177@end smallexample
104c1213 19178
8e04817f
AC
19179@noindent
19180This defines the command @code{adder}, which prints the sum of
19181its three arguments. Note the arguments are text substitutions, so they may
19182reference variables, use complex expressions, or even perform inferior
19183functions calls.
104c1213 19184
fcc73fe3
EZ
19185@cindex argument count in user-defined commands
19186@cindex how many arguments (user-defined commands)
c03c782f
AS
19187In addition, @code{$argc} may be used to find out how many arguments have
19188been passed. This expands to a number in the range 0@dots{}10.
19189
19190@smallexample
19191define adder
19192 if $argc == 2
19193 print $arg0 + $arg1
19194 end
19195 if $argc == 3
19196 print $arg0 + $arg1 + $arg2
19197 end
19198end
19199@end smallexample
19200
104c1213 19201@table @code
104c1213 19202
8e04817f
AC
19203@kindex define
19204@item define @var{commandname}
19205Define a command named @var{commandname}. If there is already a command
19206by that name, you are asked to confirm that you want to redefine it.
adb483fe
DJ
19207@var{commandname} may be a bare command name consisting of letters,
19208numbers, dashes, and underscores. It may also start with any predefined
19209prefix command. For example, @samp{define target my-target} creates
19210a user-defined @samp{target my-target} command.
104c1213 19211
8e04817f
AC
19212The definition of the command is made up of other @value{GDBN} command lines,
19213which are given following the @code{define} command. The end of these
19214commands is marked by a line containing @code{end}.
104c1213 19215
8e04817f 19216@kindex document
ca91424e 19217@kindex end@r{ (user-defined commands)}
8e04817f
AC
19218@item document @var{commandname}
19219Document the user-defined command @var{commandname}, so that it can be
19220accessed by @code{help}. The command @var{commandname} must already be
19221defined. This command reads lines of documentation just as @code{define}
19222reads the lines of the command definition, ending with @code{end}.
19223After the @code{document} command is finished, @code{help} on command
19224@var{commandname} displays the documentation you have written.
104c1213 19225
8e04817f
AC
19226You may use the @code{document} command again to change the
19227documentation of a command. Redefining the command with @code{define}
19228does not change the documentation.
104c1213 19229
c45da7e6
EZ
19230@kindex dont-repeat
19231@cindex don't repeat command
19232@item dont-repeat
19233Used inside a user-defined command, this tells @value{GDBN} that this
19234command should not be repeated when the user hits @key{RET}
19235(@pxref{Command Syntax, repeat last command}).
19236
8e04817f
AC
19237@kindex help user-defined
19238@item help user-defined
19239List all user-defined commands, with the first line of the documentation
19240(if any) for each.
104c1213 19241
8e04817f
AC
19242@kindex show user
19243@item show user
19244@itemx show user @var{commandname}
19245Display the @value{GDBN} commands used to define @var{commandname} (but
19246not its documentation). If no @var{commandname} is given, display the
19247definitions for all user-defined commands.
104c1213 19248
fcc73fe3 19249@cindex infinite recursion in user-defined commands
20f01a46
DH
19250@kindex show max-user-call-depth
19251@kindex set max-user-call-depth
19252@item show max-user-call-depth
5ca0cb28
DH
19253@itemx set max-user-call-depth
19254The value of @code{max-user-call-depth} controls how many recursion
3f94c067 19255levels are allowed in user-defined commands before @value{GDBN} suspects an
5ca0cb28 19256infinite recursion and aborts the command.
104c1213
JM
19257@end table
19258
fcc73fe3
EZ
19259In addition to the above commands, user-defined commands frequently
19260use control flow commands, described in @ref{Command Files}.
19261
8e04817f
AC
19262When user-defined commands are executed, the
19263commands of the definition are not printed. An error in any command
19264stops execution of the user-defined command.
104c1213 19265
8e04817f
AC
19266If used interactively, commands that would ask for confirmation proceed
19267without asking when used inside a user-defined command. Many @value{GDBN}
19268commands that normally print messages to say what they are doing omit the
19269messages when used in a user-defined command.
104c1213 19270
8e04817f 19271@node Hooks
d57a3c85 19272@subsection User-defined Command Hooks
8e04817f
AC
19273@cindex command hooks
19274@cindex hooks, for commands
19275@cindex hooks, pre-command
104c1213 19276
8e04817f 19277@kindex hook
8e04817f
AC
19278You may define @dfn{hooks}, which are a special kind of user-defined
19279command. Whenever you run the command @samp{foo}, if the user-defined
19280command @samp{hook-foo} exists, it is executed (with no arguments)
19281before that command.
104c1213 19282
8e04817f
AC
19283@cindex hooks, post-command
19284@kindex hookpost
8e04817f
AC
19285A hook may also be defined which is run after the command you executed.
19286Whenever you run the command @samp{foo}, if the user-defined command
19287@samp{hookpost-foo} exists, it is executed (with no arguments) after
19288that command. Post-execution hooks may exist simultaneously with
19289pre-execution hooks, for the same command.
104c1213 19290
8e04817f 19291It is valid for a hook to call the command which it hooks. If this
9f1c6395 19292occurs, the hook is not re-executed, thereby avoiding infinite recursion.
104c1213 19293
8e04817f
AC
19294@c It would be nice if hookpost could be passed a parameter indicating
19295@c if the command it hooks executed properly or not. FIXME!
104c1213 19296
8e04817f
AC
19297@kindex stop@r{, a pseudo-command}
19298In addition, a pseudo-command, @samp{stop} exists. Defining
19299(@samp{hook-stop}) makes the associated commands execute every time
19300execution stops in your program: before breakpoint commands are run,
19301displays are printed, or the stack frame is printed.
104c1213 19302
8e04817f
AC
19303For example, to ignore @code{SIGALRM} signals while
19304single-stepping, but treat them normally during normal execution,
19305you could define:
104c1213 19306
474c8240 19307@smallexample
8e04817f
AC
19308define hook-stop
19309handle SIGALRM nopass
19310end
104c1213 19311
8e04817f
AC
19312define hook-run
19313handle SIGALRM pass
19314end
104c1213 19315
8e04817f 19316define hook-continue
d3e8051b 19317handle SIGALRM pass
8e04817f 19318end
474c8240 19319@end smallexample
104c1213 19320
d3e8051b 19321As a further example, to hook at the beginning and end of the @code{echo}
b383017d 19322command, and to add extra text to the beginning and end of the message,
8e04817f 19323you could define:
104c1213 19324
474c8240 19325@smallexample
8e04817f
AC
19326define hook-echo
19327echo <<<---
19328end
104c1213 19329
8e04817f
AC
19330define hookpost-echo
19331echo --->>>\n
19332end
104c1213 19333
8e04817f
AC
19334(@value{GDBP}) echo Hello World
19335<<<---Hello World--->>>
19336(@value{GDBP})
104c1213 19337
474c8240 19338@end smallexample
104c1213 19339
8e04817f
AC
19340You can define a hook for any single-word command in @value{GDBN}, but
19341not for command aliases; you should define a hook for the basic command
c1468174 19342name, e.g.@: @code{backtrace} rather than @code{bt}.
8e04817f
AC
19343@c FIXME! So how does Joe User discover whether a command is an alias
19344@c or not?
adb483fe
DJ
19345You can hook a multi-word command by adding @code{hook-} or
19346@code{hookpost-} to the last word of the command, e.g.@:
19347@samp{define target hook-remote} to add a hook to @samp{target remote}.
19348
8e04817f
AC
19349If an error occurs during the execution of your hook, execution of
19350@value{GDBN} commands stops and @value{GDBN} issues a prompt
19351(before the command that you actually typed had a chance to run).
104c1213 19352
8e04817f
AC
19353If you try to define a hook which does not match any known command, you
19354get a warning from the @code{define} command.
c906108c 19355
8e04817f 19356@node Command Files
d57a3c85 19357@subsection Command Files
c906108c 19358
8e04817f 19359@cindex command files
fcc73fe3 19360@cindex scripting commands
6fc08d32
EZ
19361A command file for @value{GDBN} is a text file made of lines that are
19362@value{GDBN} commands. Comments (lines starting with @kbd{#}) may
19363also be included. An empty line in a command file does nothing; it
19364does not mean to repeat the last command, as it would from the
19365terminal.
c906108c 19366
6fc08d32 19367You can request the execution of a command file with the @code{source}
95433b34
JB
19368command. Note that the @code{source} command is also used to evaluate
19369scripts that are not Command Files. The exact behavior can be configured
19370using the @code{script-extension} setting.
19371@xref{Extending GDB,, Extending GDB}.
c906108c 19372
8e04817f
AC
19373@table @code
19374@kindex source
ca91424e 19375@cindex execute commands from a file
16026cd7 19376@item source [@code{-v}] @var{filename}
8e04817f 19377Execute the command file @var{filename}.
c906108c
SS
19378@end table
19379
fcc73fe3
EZ
19380The lines in a command file are generally executed sequentially,
19381unless the order of execution is changed by one of the
19382@emph{flow-control commands} described below. The commands are not
a71ec265
DH
19383printed as they are executed. An error in any command terminates
19384execution of the command file and control is returned to the console.
c906108c 19385
08001717
DE
19386@value{GDBN} first searches for @var{filename} in the current directory.
19387If the file is not found there, and @var{filename} does not specify a
19388directory, then @value{GDBN} also looks for the file on the source search path
19389(specified with the @samp{directory} command);
19390except that @file{$cdir} is not searched because the compilation directory
19391is not relevant to scripts.
4b505b12 19392
16026cd7
AS
19393If @code{-v}, for verbose mode, is given then @value{GDBN} displays
19394each command as it is executed. The option must be given before
19395@var{filename}, and is interpreted as part of the filename anywhere else.
19396
8e04817f
AC
19397Commands that would ask for confirmation if used interactively proceed
19398without asking when used in a command file. Many @value{GDBN} commands that
19399normally print messages to say what they are doing omit the messages
19400when called from command files.
c906108c 19401
8e04817f
AC
19402@value{GDBN} also accepts command input from standard input. In this
19403mode, normal output goes to standard output and error output goes to
19404standard error. Errors in a command file supplied on standard input do
6fc08d32 19405not terminate execution of the command file---execution continues with
8e04817f 19406the next command.
c906108c 19407
474c8240 19408@smallexample
8e04817f 19409gdb < cmds > log 2>&1
474c8240 19410@end smallexample
c906108c 19411
8e04817f
AC
19412(The syntax above will vary depending on the shell used.) This example
19413will execute commands from the file @file{cmds}. All output and errors
19414would be directed to @file{log}.
c906108c 19415
fcc73fe3
EZ
19416Since commands stored on command files tend to be more general than
19417commands typed interactively, they frequently need to deal with
19418complicated situations, such as different or unexpected values of
19419variables and symbols, changes in how the program being debugged is
19420built, etc. @value{GDBN} provides a set of flow-control commands to
19421deal with these complexities. Using these commands, you can write
19422complex scripts that loop over data structures, execute commands
19423conditionally, etc.
19424
19425@table @code
19426@kindex if
19427@kindex else
19428@item if
19429@itemx else
19430This command allows to include in your script conditionally executed
19431commands. The @code{if} command takes a single argument, which is an
19432expression to evaluate. It is followed by a series of commands that
19433are executed only if the expression is true (its value is nonzero).
19434There can then optionally be an @code{else} line, followed by a series
19435of commands that are only executed if the expression was false. The
19436end of the list is marked by a line containing @code{end}.
19437
19438@kindex while
19439@item while
19440This command allows to write loops. Its syntax is similar to
19441@code{if}: the command takes a single argument, which is an expression
19442to evaluate, and must be followed by the commands to execute, one per
19443line, terminated by an @code{end}. These commands are called the
19444@dfn{body} of the loop. The commands in the body of @code{while} are
19445executed repeatedly as long as the expression evaluates to true.
19446
19447@kindex loop_break
19448@item loop_break
19449This command exits the @code{while} loop in whose body it is included.
19450Execution of the script continues after that @code{while}s @code{end}
19451line.
19452
19453@kindex loop_continue
19454@item loop_continue
19455This command skips the execution of the rest of the body of commands
19456in the @code{while} loop in whose body it is included. Execution
19457branches to the beginning of the @code{while} loop, where it evaluates
19458the controlling expression.
ca91424e
EZ
19459
19460@kindex end@r{ (if/else/while commands)}
19461@item end
19462Terminate the block of commands that are the body of @code{if},
19463@code{else}, or @code{while} flow-control commands.
fcc73fe3
EZ
19464@end table
19465
19466
8e04817f 19467@node Output
d57a3c85 19468@subsection Commands for Controlled Output
c906108c 19469
8e04817f
AC
19470During the execution of a command file or a user-defined command, normal
19471@value{GDBN} output is suppressed; the only output that appears is what is
19472explicitly printed by the commands in the definition. This section
19473describes three commands useful for generating exactly the output you
19474want.
c906108c
SS
19475
19476@table @code
8e04817f
AC
19477@kindex echo
19478@item echo @var{text}
19479@c I do not consider backslash-space a standard C escape sequence
19480@c because it is not in ANSI.
19481Print @var{text}. Nonprinting characters can be included in
19482@var{text} using C escape sequences, such as @samp{\n} to print a
19483newline. @strong{No newline is printed unless you specify one.}
19484In addition to the standard C escape sequences, a backslash followed
19485by a space stands for a space. This is useful for displaying a
19486string with spaces at the beginning or the end, since leading and
19487trailing spaces are otherwise trimmed from all arguments.
19488To print @samp{@w{ }and foo =@w{ }}, use the command
19489@samp{echo \@w{ }and foo = \@w{ }}.
c906108c 19490
8e04817f
AC
19491A backslash at the end of @var{text} can be used, as in C, to continue
19492the command onto subsequent lines. For example,
c906108c 19493
474c8240 19494@smallexample
8e04817f
AC
19495echo This is some text\n\
19496which is continued\n\
19497onto several lines.\n
474c8240 19498@end smallexample
c906108c 19499
8e04817f 19500produces the same output as
c906108c 19501
474c8240 19502@smallexample
8e04817f
AC
19503echo This is some text\n
19504echo which is continued\n
19505echo onto several lines.\n
474c8240 19506@end smallexample
c906108c 19507
8e04817f
AC
19508@kindex output
19509@item output @var{expression}
19510Print the value of @var{expression} and nothing but that value: no
19511newlines, no @samp{$@var{nn} = }. The value is not entered in the
19512value history either. @xref{Expressions, ,Expressions}, for more information
19513on expressions.
c906108c 19514
8e04817f
AC
19515@item output/@var{fmt} @var{expression}
19516Print the value of @var{expression} in format @var{fmt}. You can use
19517the same formats as for @code{print}. @xref{Output Formats,,Output
79a6e687 19518Formats}, for more information.
c906108c 19519
8e04817f 19520@kindex printf
82160952
EZ
19521@item printf @var{template}, @var{expressions}@dots{}
19522Print the values of one or more @var{expressions} under the control of
19523the string @var{template}. To print several values, make
19524@var{expressions} be a comma-separated list of individual expressions,
19525which may be either numbers or pointers. Their values are printed as
19526specified by @var{template}, exactly as a C program would do by
19527executing the code below:
c906108c 19528
474c8240 19529@smallexample
82160952 19530printf (@var{template}, @var{expressions}@dots{});
474c8240 19531@end smallexample
c906108c 19532
82160952
EZ
19533As in @code{C} @code{printf}, ordinary characters in @var{template}
19534are printed verbatim, while @dfn{conversion specification} introduced
19535by the @samp{%} character cause subsequent @var{expressions} to be
19536evaluated, their values converted and formatted according to type and
19537style information encoded in the conversion specifications, and then
19538printed.
19539
8e04817f 19540For example, you can print two values in hex like this:
c906108c 19541
8e04817f
AC
19542@smallexample
19543printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo
19544@end smallexample
c906108c 19545
82160952
EZ
19546@code{printf} supports all the standard @code{C} conversion
19547specifications, including the flags and modifiers between the @samp{%}
19548character and the conversion letter, with the following exceptions:
19549
19550@itemize @bullet
19551@item
19552The argument-ordering modifiers, such as @samp{2$}, are not supported.
19553
19554@item
19555The modifier @samp{*} is not supported for specifying precision or
19556width.
19557
19558@item
19559The @samp{'} flag (for separation of digits into groups according to
19560@code{LC_NUMERIC'}) is not supported.
19561
19562@item
19563The type modifiers @samp{hh}, @samp{j}, @samp{t}, and @samp{z} are not
19564supported.
19565
19566@item
19567The conversion letter @samp{n} (as in @samp{%n}) is not supported.
19568
19569@item
19570The conversion letters @samp{a} and @samp{A} are not supported.
19571@end itemize
19572
19573@noindent
19574Note that the @samp{ll} type modifier is supported only if the
19575underlying @code{C} implementation used to build @value{GDBN} supports
19576the @code{long long int} type, and the @samp{L} type modifier is
19577supported only if @code{long double} type is available.
19578
19579As in @code{C}, @code{printf} supports simple backslash-escape
19580sequences, such as @code{\n}, @samp{\t}, @samp{\\}, @samp{\"},
19581@samp{\a}, and @samp{\f}, that consist of backslash followed by a
19582single character. Octal and hexadecimal escape sequences are not
19583supported.
1a619819
LM
19584
19585Additionally, @code{printf} supports conversion specifications for DFP
0aea4bf3
LM
19586(@dfn{Decimal Floating Point}) types using the following length modifiers
19587together with a floating point specifier.
1a619819
LM
19588letters:
19589
19590@itemize @bullet
19591@item
19592@samp{H} for printing @code{Decimal32} types.
19593
19594@item
19595@samp{D} for printing @code{Decimal64} types.
19596
19597@item
19598@samp{DD} for printing @code{Decimal128} types.
19599@end itemize
19600
19601If the underlying @code{C} implementation used to build @value{GDBN} has
0aea4bf3 19602support for the three length modifiers for DFP types, other modifiers
3b784c4f 19603such as width and precision will also be available for @value{GDBN} to use.
1a619819
LM
19604
19605In case there is no such @code{C} support, no additional modifiers will be
19606available and the value will be printed in the standard way.
19607
19608Here's an example of printing DFP types using the above conversion letters:
19609@smallexample
0aea4bf3 19610printf "D32: %Hf - D64: %Df - D128: %DDf\n",1.2345df,1.2E10dd,1.2E1dl
1a619819
LM
19611@end smallexample
19612
c906108c
SS
19613@end table
19614
d57a3c85
TJB
19615@node Python
19616@section Scripting @value{GDBN} using Python
19617@cindex python scripting
19618@cindex scripting with python
19619
19620You can script @value{GDBN} using the @uref{http://www.python.org/,
19621Python programming language}. This feature is available only if
19622@value{GDBN} was configured using @option{--with-python}.
19623
19624@menu
19625* Python Commands:: Accessing Python from @value{GDBN}.
19626* Python API:: Accessing @value{GDBN} from Python.
19627@end menu
19628
19629@node Python Commands
19630@subsection Python Commands
19631@cindex python commands
19632@cindex commands to access python
19633
19634@value{GDBN} provides one command for accessing the Python interpreter,
19635and one related setting:
19636
19637@table @code
19638@kindex python
19639@item python @r{[}@var{code}@r{]}
19640The @code{python} command can be used to evaluate Python code.
19641
19642If given an argument, the @code{python} command will evaluate the
19643argument as a Python command. For example:
19644
19645@smallexample
19646(@value{GDBP}) python print 23
1964723
19648@end smallexample
19649
19650If you do not provide an argument to @code{python}, it will act as a
19651multi-line command, like @code{define}. In this case, the Python
19652script is made up of subsequent command lines, given after the
19653@code{python} command. This command list is terminated using a line
19654containing @code{end}. For example:
19655
19656@smallexample
19657(@value{GDBP}) python
19658Type python script
19659End with a line saying just "end".
19660>print 23
19661>end
1966223
19663@end smallexample
19664
19665@kindex maint set python print-stack
19666@item maint set python print-stack
19667By default, @value{GDBN} will print a stack trace when an error occurs
19668in a Python script. This can be controlled using @code{maint set
19669python print-stack}: if @code{on}, the default, then Python stack
19670printing is enabled; if @code{off}, then Python stack printing is
19671disabled.
19672@end table
19673
95433b34
JB
19674It is also possible to execute a Python script from the @value{GDBN}
19675interpreter:
19676
19677@table @code
19678@item source @file{script-name}
19679The script name must end with @samp{.py} and @value{GDBN} must be configured
19680to recognize the script language based on filename extension using
19681the @code{script-extension} setting. @xref{Extending GDB, ,Extending GDB}.
19682
19683@item python execfile ("script-name")
19684This method is based on the @code{execfile} Python built-in function,
19685and thus is always available.
19686@end table
19687
d57a3c85
TJB
19688@node Python API
19689@subsection Python API
19690@cindex python api
19691@cindex programming in python
19692
19693@cindex python stdout
19694@cindex python pagination
19695At startup, @value{GDBN} overrides Python's @code{sys.stdout} and
19696@code{sys.stderr} to print using @value{GDBN}'s output-paging streams.
19697A Python program which outputs to one of these streams may have its
19698output interrupted by the user (@pxref{Screen Size}). In this
19699situation, a Python @code{KeyboardInterrupt} exception is thrown.
19700
19701@menu
19702* Basic Python:: Basic Python Functions.
19703* Exception Handling::
89c73ade 19704* Auto-loading:: Automatically loading Python code.
a08702d6 19705* Values From Inferior::
2c74e833 19706* Types In Python:: Python representation of types.
a6bac58e
TT
19707* Pretty Printing:: Pretty-printing values.
19708* Selecting Pretty-Printers:: How GDB chooses a pretty-printer.
d8906c6f 19709* Commands In Python:: Implementing new commands in Python.
bc3b79fd 19710* Functions In Python:: Writing new convenience functions.
89c73ade 19711* Objfiles In Python:: Object files.
f3e9a817
PM
19712* Frames In Python:: Accessing inferior stack frames from Python.
19713* Blocks In Python:: Accessing frame blocks from Python.
19714* Symbols In Python:: Python representation of symbols.
19715* Symbol Tables In Python:: Python representation of symbol tables.
be759fcf 19716* Lazy Strings In Python:: Python representation of lazy strings.
d57a3c85
TJB
19717@end menu
19718
19719@node Basic Python
19720@subsubsection Basic Python
19721
19722@cindex python functions
19723@cindex python module
19724@cindex gdb module
19725@value{GDBN} introduces a new Python module, named @code{gdb}. All
19726methods and classes added by @value{GDBN} are placed in this module.
19727@value{GDBN} automatically @code{import}s the @code{gdb} module for
19728use in all scripts evaluated by the @code{python} command.
19729
19730@findex gdb.execute
12453b93 19731@defun execute command [from_tty]
d57a3c85
TJB
19732Evaluate @var{command}, a string, as a @value{GDBN} CLI command.
19733If a GDB exception happens while @var{command} runs, it is
19734translated as described in @ref{Exception Handling,,Exception Handling}.
19735If no exceptions occur, this function returns @code{None}.
12453b93
TJB
19736
19737@var{from_tty} specifies whether @value{GDBN} ought to consider this
19738command as having originated from the user invoking it interactively.
19739It must be a boolean value. If omitted, it defaults to @code{False}.
d57a3c85
TJB
19740@end defun
19741
8f500870
TT
19742@findex gdb.parameter
19743@defun parameter parameter
d57a3c85
TJB
19744Return the value of a @value{GDBN} parameter. @var{parameter} is a
19745string naming the parameter to look up; @var{parameter} may contain
19746spaces if the parameter has a multi-part name. For example,
19747@samp{print object} is a valid parameter name.
19748
19749If the named parameter does not exist, this function throws a
19750@code{RuntimeError}. Otherwise, the parameter's value is converted to
19751a Python value of the appropriate type, and returned.
19752@end defun
19753
08c637de
TJB
19754@findex gdb.history
19755@defun history number
19756Return a value from @value{GDBN}'s value history (@pxref{Value
19757History}). @var{number} indicates which history element to return.
19758If @var{number} is negative, then @value{GDBN} will take its absolute value
19759and count backward from the last element (i.e., the most recent element) to
19760find the value to return. If @var{number} is zero, then @value{GDBN} will
a0c36267 19761return the most recent element. If the element specified by @var{number}
08c637de
TJB
19762doesn't exist in the value history, a @code{RuntimeError} exception will be
19763raised.
19764
19765If no exception is raised, the return value is always an instance of
19766@code{gdb.Value} (@pxref{Values From Inferior}).
19767@end defun
19768
57a1d736
TT
19769@findex gdb.parse_and_eval
19770@defun parse_and_eval expression
19771Parse @var{expression} as an expression in the current language,
19772evaluate it, and return the result as a @code{gdb.Value}.
19773@var{expression} must be a string.
19774
19775This function can be useful when implementing a new command
19776(@pxref{Commands In Python}), as it provides a way to parse the
19777command's argument as an expression. It is also useful simply to
19778compute values, for example, it is the only way to get the value of a
19779convenience variable (@pxref{Convenience Vars}) as a @code{gdb.Value}.
19780@end defun
19781
d57a3c85
TJB
19782@findex gdb.write
19783@defun write string
19784Print a string to @value{GDBN}'s paginated standard output stream.
19785Writing to @code{sys.stdout} or @code{sys.stderr} will automatically
19786call this function.
19787@end defun
19788
19789@findex gdb.flush
19790@defun flush
19791Flush @value{GDBN}'s paginated standard output stream. Flushing
19792@code{sys.stdout} or @code{sys.stderr} will automatically call this
19793function.
19794@end defun
19795
f870a310
TT
19796@findex gdb.target_charset
19797@defun target_charset
19798Return the name of the current target character set (@pxref{Character
19799Sets}). This differs from @code{gdb.parameter('target-charset')} in
19800that @samp{auto} is never returned.
19801@end defun
19802
19803@findex gdb.target_wide_charset
19804@defun target_wide_charset
19805Return the name of the current target wide character set
19806(@pxref{Character Sets}). This differs from
19807@code{gdb.parameter('target-wide-charset')} in that @samp{auto} is
19808never returned.
19809@end defun
19810
d57a3c85
TJB
19811@node Exception Handling
19812@subsubsection Exception Handling
19813@cindex python exceptions
19814@cindex exceptions, python
19815
19816When executing the @code{python} command, Python exceptions
19817uncaught within the Python code are translated to calls to
19818@value{GDBN} error-reporting mechanism. If the command that called
19819@code{python} does not handle the error, @value{GDBN} will
19820terminate it and print an error message containing the Python
19821exception name, the associated value, and the Python call stack
19822backtrace at the point where the exception was raised. Example:
19823
19824@smallexample
19825(@value{GDBP}) python print foo
19826Traceback (most recent call last):
19827 File "<string>", line 1, in <module>
19828NameError: name 'foo' is not defined
19829@end smallexample
19830
19831@value{GDBN} errors that happen in @value{GDBN} commands invoked by Python
19832code are converted to Python @code{RuntimeError} exceptions. User
19833interrupt (via @kbd{C-c} or by typing @kbd{q} at a pagination
19834prompt) is translated to a Python @code{KeyboardInterrupt}
19835exception. If you catch these exceptions in your Python code, your
19836exception handler will see @code{RuntimeError} or
19837@code{KeyboardInterrupt} as the exception type, the @value{GDBN} error
19838message as its value, and the Python call stack backtrace at the
19839Python statement closest to where the @value{GDBN} error occured as the
19840traceback.
19841
89c73ade
TT
19842@node Auto-loading
19843@subsubsection Auto-loading
19844@cindex auto-loading, Python
19845
19846When a new object file is read (for example, due to the @code{file}
19847command, or because the inferior has loaded a shared library),
19848@value{GDBN} will look for a file named @file{@var{objfile}-gdb.py},
19849where @var{objfile} is the object file's real name, formed by ensuring
19850that the file name is absolute, following all symlinks, and resolving
19851@code{.} and @code{..} components. If this file exists and is
19852readable, @value{GDBN} will evaluate it as a Python script.
19853
19854If this file does not exist, and if the parameter
19855@code{debug-file-directory} is set (@pxref{Separate Debug Files}),
24ddea62
JK
19856then @value{GDBN} will use for its each separated directory component
19857@code{component} the file named @file{@code{component}/@var{real-name}}, where
89c73ade
TT
19858@var{real-name} is the object file's real name, as described above.
19859
19860Finally, if this file does not exist, then @value{GDBN} will look for
19861a file named @file{@var{data-directory}/python/auto-load/@var{real-name}}, where
19862@var{data-directory} is @value{GDBN}'s data directory (available via
19863@code{show data-directory}, @pxref{Data Files}), and @var{real-name}
19864is the object file's real name, as described above.
19865
19866When reading an auto-loaded file, @value{GDBN} sets the ``current
19867objfile''. This is available via the @code{gdb.current_objfile}
19868function (@pxref{Objfiles In Python}). This can be useful for
19869registering objfile-specific pretty-printers.
19870
19871The auto-loading feature is useful for supplying application-specific
19872debugging commands and scripts. You can enable or disable this
19873feature, and view its current state.
19874
19875@table @code
19876@kindex maint set python auto-load
19877@item maint set python auto-load [yes|no]
19878Enable or disable the Python auto-loading feature.
19879
c375651d
DE
19880@kindex maint show python auto-load
19881@item maint show python auto-load
89c73ade
TT
19882Show whether Python auto-loading is enabled or disabled.
19883@end table
19884
19885@value{GDBN} does not track which files it has already auto-loaded.
19886So, your @samp{-gdb.py} file should take care to ensure that it may be
19887evaluated multiple times without error.
19888
a08702d6
TJB
19889@node Values From Inferior
19890@subsubsection Values From Inferior
19891@cindex values from inferior, with Python
19892@cindex python, working with values from inferior
19893
19894@cindex @code{gdb.Value}
19895@value{GDBN} provides values it obtains from the inferior program in
19896an object of type @code{gdb.Value}. @value{GDBN} uses this object
19897for its internal bookkeeping of the inferior's values, and for
19898fetching values when necessary.
19899
19900Inferior values that are simple scalars can be used directly in
19901Python expressions that are valid for the value's data type. Here's
19902an example for an integer or floating-point value @code{some_val}:
19903
19904@smallexample
19905bar = some_val + 2
19906@end smallexample
19907
19908@noindent
19909As result of this, @code{bar} will also be a @code{gdb.Value} object
19910whose values are of the same type as those of @code{some_val}.
19911
19912Inferior values that are structures or instances of some class can
19913be accessed using the Python @dfn{dictionary syntax}. For example, if
19914@code{some_val} is a @code{gdb.Value} instance holding a structure, you
19915can access its @code{foo} element with:
19916
19917@smallexample
19918bar = some_val['foo']
19919@end smallexample
19920
19921Again, @code{bar} will also be a @code{gdb.Value} object.
19922
c0c6f777 19923The following attributes are provided:
a08702d6 19924
def2b000 19925@table @code
2c74e833 19926@defivar Value address
c0c6f777
TJB
19927If this object is addressable, this read-only attribute holds a
19928@code{gdb.Value} object representing the address. Otherwise,
19929this attribute holds @code{None}.
2c74e833 19930@end defivar
c0c6f777 19931
def2b000 19932@cindex optimized out value in Python
2c74e833 19933@defivar Value is_optimized_out
def2b000
TJB
19934This read-only boolean attribute is true if the compiler optimized out
19935this value, thus it is not available for fetching from the inferior.
2c74e833
TT
19936@end defivar
19937
19938@defivar Value type
19939The type of this @code{gdb.Value}. The value of this attribute is a
19940@code{gdb.Type} object.
19941@end defivar
def2b000
TJB
19942@end table
19943
19944The following methods are provided:
19945
19946@table @code
14ff2235
PM
19947@defmethod Value cast type
19948Return a new instance of @code{gdb.Value} that is the result of
19949casting this instance to the type described by @var{type}, which must
19950be a @code{gdb.Type} object. If the cast cannot be performed for some
19951reason, this method throws an exception.
19952@end defmethod
19953
a08702d6 19954@defmethod Value dereference
def2b000
TJB
19955For pointer data types, this method returns a new @code{gdb.Value} object
19956whose contents is the object pointed to by the pointer. For example, if
19957@code{foo} is a C pointer to an @code{int}, declared in your C program as
a08702d6
TJB
19958
19959@smallexample
19960int *foo;
19961@end smallexample
19962
19963@noindent
19964then you can use the corresponding @code{gdb.Value} to access what
19965@code{foo} points to like this:
19966
19967@smallexample
19968bar = foo.dereference ()
19969@end smallexample
19970
19971The result @code{bar} will be a @code{gdb.Value} object holding the
19972value pointed to by @code{foo}.
19973@end defmethod
19974
fbb8f299 19975@defmethod Value string @r{[}encoding@r{]} @r{[}errors@r{]} @r{[}length@r{]}
b6cb8e7d
TJB
19976If this @code{gdb.Value} represents a string, then this method
19977converts the contents to a Python string. Otherwise, this method will
19978throw an exception.
19979
19980Strings are recognized in a language-specific way; whether a given
19981@code{gdb.Value} represents a string is determined by the current
19982language.
19983
19984For C-like languages, a value is a string if it is a pointer to or an
19985array of characters or ints. The string is assumed to be terminated
fbb8f299
PM
19986by a zero of the appropriate width. However if the optional length
19987argument is given, the string will be converted to that given length,
19988ignoring any embedded zeros that the string may contain.
b6cb8e7d
TJB
19989
19990If the optional @var{encoding} argument is given, it must be a string
19991naming the encoding of the string in the @code{gdb.Value}, such as
19992@code{"ascii"}, @code{"iso-8859-6"} or @code{"utf-8"}. It accepts
19993the same encodings as the corresponding argument to Python's
19994@code{string.decode} method, and the Python codec machinery will be used
19995to convert the string. If @var{encoding} is not given, or if
19996@var{encoding} is the empty string, then either the @code{target-charset}
19997(@pxref{Character Sets}) will be used, or a language-specific encoding
19998will be used, if the current language is able to supply one.
19999
20000The optional @var{errors} argument is the same as the corresponding
20001argument to Python's @code{string.decode} method.
fbb8f299
PM
20002
20003If the optional @var{length} argument is given, the string will be
20004fetched and converted to the given length.
b6cb8e7d 20005@end defmethod
be759fcf
PM
20006
20007@defmethod Value lazy_string @r{[}encoding@r{]} @r{[}length@r{]}
20008If this @code{gdb.Value} represents a string, then this method
20009converts the contents to a @code{gdb.LazyString} (@pxref{Lazy Strings
20010In Python}). Otherwise, this method will throw an exception.
20011
20012If the optional @var{encoding} argument is given, it must be a string
20013naming the encoding of the @code{gdb.LazyString}. Some examples are:
20014@samp{ascii}, @samp{iso-8859-6} or @samp{utf-8}. If the
20015@var{encoding} argument is an encoding that @value{GDBN} does
20016recognize, @value{GDBN} will raise an error.
20017
20018When a lazy string is printed, the @value{GDBN} encoding machinery is
20019used to convert the string during printing. If the optional
20020@var{encoding} argument is not provided, or is an empty string,
20021@value{GDBN} will automatically select the encoding most suitable for
20022the string type. For further information on encoding in @value{GDBN}
20023please see @ref{Character Sets}.
20024
20025If the optional @var{length} argument is given, the string will be
20026fetched and encoded to the length of characters specified. If
20027the @var{length} argument is not provided, the string will be fetched
20028and encoded until a null of appropriate width is found.
20029@end defmethod
def2b000 20030@end table
b6cb8e7d 20031
2c74e833
TT
20032@node Types In Python
20033@subsubsection Types In Python
20034@cindex types in Python
20035@cindex Python, working with types
20036
20037@tindex gdb.Type
20038@value{GDBN} represents types from the inferior using the class
20039@code{gdb.Type}.
20040
20041The following type-related functions are available in the @code{gdb}
20042module:
20043
20044@findex gdb.lookup_type
20045@defun lookup_type name [block]
20046This function looks up a type by name. @var{name} is the name of the
20047type to look up. It must be a string.
20048
5107b149
PM
20049If @var{block} is given, then @var{name} is looked up in that scope.
20050Otherwise, it is searched for globally.
20051
2c74e833
TT
20052Ordinarily, this function will return an instance of @code{gdb.Type}.
20053If the named type cannot be found, it will throw an exception.
20054@end defun
20055
20056An instance of @code{Type} has the following attributes:
20057
20058@table @code
20059@defivar Type code
20060The type code for this type. The type code will be one of the
20061@code{TYPE_CODE_} constants defined below.
20062@end defivar
20063
20064@defivar Type sizeof
20065The size of this type, in target @code{char} units. Usually, a
20066target's @code{char} type will be an 8-bit byte. However, on some
20067unusual platforms, this type may have a different size.
20068@end defivar
20069
20070@defivar Type tag
20071The tag name for this type. The tag name is the name after
20072@code{struct}, @code{union}, or @code{enum} in C and C@t{++}; not all
20073languages have this concept. If this type has no tag name, then
20074@code{None} is returned.
20075@end defivar
20076@end table
20077
20078The following methods are provided:
20079
20080@table @code
20081@defmethod Type fields
20082For structure and union types, this method returns the fields. Range
20083types have two fields, the minimum and maximum values. Enum types
20084have one field per enum constant. Function and method types have one
20085field per parameter. The base types of C@t{++} classes are also
20086represented as fields. If the type has no fields, or does not fit
20087into one of these categories, an empty sequence will be returned.
20088
20089Each field is an object, with some pre-defined attributes:
20090@table @code
20091@item bitpos
20092This attribute is not available for @code{static} fields (as in
20093C@t{++} or Java). For non-@code{static} fields, the value is the bit
20094position of the field.
20095
20096@item name
20097The name of the field, or @code{None} for anonymous fields.
20098
20099@item artificial
20100This is @code{True} if the field is artificial, usually meaning that
20101it was provided by the compiler and not the user. This attribute is
20102always provided, and is @code{False} if the field is not artificial.
20103
bfd31e71
PM
20104@item is_base_class
20105This is @code{True} if the field represents a base class of a C@t{++}
20106structure. This attribute is always provided, and is @code{False}
20107if the field is not a base class of the type that is the argument of
20108@code{fields}, or if that type was not a C@t{++} class.
20109
2c74e833
TT
20110@item bitsize
20111If the field is packed, or is a bitfield, then this will have a
20112non-zero value, which is the size of the field in bits. Otherwise,
20113this will be zero; in this case the field's size is given by its type.
20114
20115@item type
20116The type of the field. This is usually an instance of @code{Type},
20117but it can be @code{None} in some situations.
20118@end table
20119@end defmethod
20120
20121@defmethod Type const
20122Return a new @code{gdb.Type} object which represents a
20123@code{const}-qualified variant of this type.
20124@end defmethod
20125
20126@defmethod Type volatile
20127Return a new @code{gdb.Type} object which represents a
20128@code{volatile}-qualified variant of this type.
20129@end defmethod
20130
20131@defmethod Type unqualified
20132Return a new @code{gdb.Type} object which represents an unqualified
20133variant of this type. That is, the result is neither @code{const} nor
20134@code{volatile}.
20135@end defmethod
20136
361ae042
PM
20137@defmethod Type range
20138Return a Python @code{Tuple} object that contains two elements: the
20139low bound of the argument type and the high bound of that type. If
20140the type does not have a range, @value{GDBN} will raise a
20141@code{RuntimeError} exception.
20142@end defmethod
20143
2c74e833
TT
20144@defmethod Type reference
20145Return a new @code{gdb.Type} object which represents a reference to this
20146type.
20147@end defmethod
20148
7a6973ad
TT
20149@defmethod Type pointer
20150Return a new @code{gdb.Type} object which represents a pointer to this
20151type.
20152@end defmethod
20153
2c74e833
TT
20154@defmethod Type strip_typedefs
20155Return a new @code{gdb.Type} that represents the real type,
20156after removing all layers of typedefs.
20157@end defmethod
20158
20159@defmethod Type target
20160Return a new @code{gdb.Type} object which represents the target type
20161of this type.
20162
20163For a pointer type, the target type is the type of the pointed-to
20164object. For an array type (meaning C-like arrays), the target type is
20165the type of the elements of the array. For a function or method type,
20166the target type is the type of the return value. For a complex type,
20167the target type is the type of the elements. For a typedef, the
20168target type is the aliased type.
20169
20170If the type does not have a target, this method will throw an
20171exception.
20172@end defmethod
20173
5107b149 20174@defmethod Type template_argument n [block]
2c74e833
TT
20175If this @code{gdb.Type} is an instantiation of a template, this will
20176return a new @code{gdb.Type} which represents the type of the
20177@var{n}th template argument.
20178
20179If this @code{gdb.Type} is not a template type, this will throw an
20180exception. Ordinarily, only C@t{++} code will have template types.
20181
5107b149
PM
20182If @var{block} is given, then @var{name} is looked up in that scope.
20183Otherwise, it is searched for globally.
2c74e833
TT
20184@end defmethod
20185@end table
20186
20187
20188Each type has a code, which indicates what category this type falls
20189into. The available type categories are represented by constants
20190defined in the @code{gdb} module:
20191
20192@table @code
20193@findex TYPE_CODE_PTR
20194@findex gdb.TYPE_CODE_PTR
20195@item TYPE_CODE_PTR
20196The type is a pointer.
20197
20198@findex TYPE_CODE_ARRAY
20199@findex gdb.TYPE_CODE_ARRAY
20200@item TYPE_CODE_ARRAY
20201The type is an array.
20202
20203@findex TYPE_CODE_STRUCT
20204@findex gdb.TYPE_CODE_STRUCT
20205@item TYPE_CODE_STRUCT
20206The type is a structure.
20207
20208@findex TYPE_CODE_UNION
20209@findex gdb.TYPE_CODE_UNION
20210@item TYPE_CODE_UNION
20211The type is a union.
20212
20213@findex TYPE_CODE_ENUM
20214@findex gdb.TYPE_CODE_ENUM
20215@item TYPE_CODE_ENUM
20216The type is an enum.
20217
20218@findex TYPE_CODE_FLAGS
20219@findex gdb.TYPE_CODE_FLAGS
20220@item TYPE_CODE_FLAGS
20221A bit flags type, used for things such as status registers.
20222
20223@findex TYPE_CODE_FUNC
20224@findex gdb.TYPE_CODE_FUNC
20225@item TYPE_CODE_FUNC
20226The type is a function.
20227
20228@findex TYPE_CODE_INT
20229@findex gdb.TYPE_CODE_INT
20230@item TYPE_CODE_INT
20231The type is an integer type.
20232
20233@findex TYPE_CODE_FLT
20234@findex gdb.TYPE_CODE_FLT
20235@item TYPE_CODE_FLT
20236A floating point type.
20237
20238@findex TYPE_CODE_VOID
20239@findex gdb.TYPE_CODE_VOID
20240@item TYPE_CODE_VOID
20241The special type @code{void}.
20242
20243@findex TYPE_CODE_SET
20244@findex gdb.TYPE_CODE_SET
20245@item TYPE_CODE_SET
20246A Pascal set type.
20247
20248@findex TYPE_CODE_RANGE
20249@findex gdb.TYPE_CODE_RANGE
20250@item TYPE_CODE_RANGE
20251A range type, that is, an integer type with bounds.
20252
20253@findex TYPE_CODE_STRING
20254@findex gdb.TYPE_CODE_STRING
20255@item TYPE_CODE_STRING
20256A string type. Note that this is only used for certain languages with
20257language-defined string types; C strings are not represented this way.
20258
20259@findex TYPE_CODE_BITSTRING
20260@findex gdb.TYPE_CODE_BITSTRING
20261@item TYPE_CODE_BITSTRING
20262A string of bits.
20263
20264@findex TYPE_CODE_ERROR
20265@findex gdb.TYPE_CODE_ERROR
20266@item TYPE_CODE_ERROR
20267An unknown or erroneous type.
20268
20269@findex TYPE_CODE_METHOD
20270@findex gdb.TYPE_CODE_METHOD
20271@item TYPE_CODE_METHOD
20272A method type, as found in C@t{++} or Java.
20273
20274@findex TYPE_CODE_METHODPTR
20275@findex gdb.TYPE_CODE_METHODPTR
20276@item TYPE_CODE_METHODPTR
20277A pointer-to-member-function.
20278
20279@findex TYPE_CODE_MEMBERPTR
20280@findex gdb.TYPE_CODE_MEMBERPTR
20281@item TYPE_CODE_MEMBERPTR
20282A pointer-to-member.
20283
20284@findex TYPE_CODE_REF
20285@findex gdb.TYPE_CODE_REF
20286@item TYPE_CODE_REF
20287A reference type.
20288
20289@findex TYPE_CODE_CHAR
20290@findex gdb.TYPE_CODE_CHAR
20291@item TYPE_CODE_CHAR
20292A character type.
20293
20294@findex TYPE_CODE_BOOL
20295@findex gdb.TYPE_CODE_BOOL
20296@item TYPE_CODE_BOOL
20297A boolean type.
20298
20299@findex TYPE_CODE_COMPLEX
20300@findex gdb.TYPE_CODE_COMPLEX
20301@item TYPE_CODE_COMPLEX
20302A complex float type.
20303
20304@findex TYPE_CODE_TYPEDEF
20305@findex gdb.TYPE_CODE_TYPEDEF
20306@item TYPE_CODE_TYPEDEF
20307A typedef to some other type.
20308
20309@findex TYPE_CODE_NAMESPACE
20310@findex gdb.TYPE_CODE_NAMESPACE
20311@item TYPE_CODE_NAMESPACE
20312A C@t{++} namespace.
20313
20314@findex TYPE_CODE_DECFLOAT
20315@findex gdb.TYPE_CODE_DECFLOAT
20316@item TYPE_CODE_DECFLOAT
20317A decimal floating point type.
20318
20319@findex TYPE_CODE_INTERNAL_FUNCTION
20320@findex gdb.TYPE_CODE_INTERNAL_FUNCTION
20321@item TYPE_CODE_INTERNAL_FUNCTION
20322A function internal to @value{GDBN}. This is the type used to represent
20323convenience functions.
20324@end table
20325
a6bac58e
TT
20326@node Pretty Printing
20327@subsubsection Pretty Printing
20328
20329@value{GDBN} provides a mechanism to allow pretty-printing of values
20330using Python code. The pretty-printer API allows application-specific
20331code to greatly simplify the display of complex objects. This
20332mechanism works for both MI and the CLI.
20333
20334For example, here is how a C@t{++} @code{std::string} looks without a
20335pretty-printer:
20336
20337@smallexample
20338(@value{GDBP}) print s
20339$1 = @{
20340 static npos = 4294967295,
20341 _M_dataplus = @{
20342 <std::allocator<char>> = @{
20343 <__gnu_cxx::new_allocator<char>> = @{<No data fields>@}, <No data fields>@},
20344 members of std::basic_string<char, std::char_traits<char>, std::allocator<char> >::_Alloc_hider:
20345 _M_p = 0x804a014 "abcd"
20346 @}
20347@}
20348@end smallexample
20349
20350After a pretty-printer for @code{std::string} has been installed, only
20351the contents are printed:
20352
20353@smallexample
20354(@value{GDBP}) print s
20355$2 = "abcd"
20356@end smallexample
20357
20358A pretty-printer is just an object that holds a value and implements a
20359specific interface, defined here.
20360
20361@defop Operation {pretty printer} children (self)
20362@value{GDBN} will call this method on a pretty-printer to compute the
20363children of the pretty-printer's value.
20364
20365This method must return an object conforming to the Python iterator
20366protocol. Each item returned by the iterator must be a tuple holding
20367two elements. The first element is the ``name'' of the child; the
20368second element is the child's value. The value can be any Python
20369object which is convertible to a @value{GDBN} value.
20370
20371This method is optional. If it does not exist, @value{GDBN} will act
20372as though the value has no children.
20373@end defop
20374
20375@defop Operation {pretty printer} display_hint (self)
20376The CLI may call this method and use its result to change the
20377formatting of a value. The result will also be supplied to an MI
20378consumer as a @samp{displayhint} attribute of the variable being
20379printed.
20380
20381This method is optional. If it does exist, this method must return a
20382string.
20383
20384Some display hints are predefined by @value{GDBN}:
20385
20386@table @samp
20387@item array
20388Indicate that the object being printed is ``array-like''. The CLI
20389uses this to respect parameters such as @code{set print elements} and
20390@code{set print array}.
20391
20392@item map
20393Indicate that the object being printed is ``map-like'', and that the
20394children of this value can be assumed to alternate between keys and
20395values.
20396
20397@item string
20398Indicate that the object being printed is ``string-like''. If the
20399printer's @code{to_string} method returns a Python string of some
20400kind, then @value{GDBN} will call its internal language-specific
20401string-printing function to format the string. For the CLI this means
20402adding quotation marks, possibly escaping some characters, respecting
20403@code{set print elements}, and the like.
20404@end table
20405@end defop
20406
20407@defop Operation {pretty printer} to_string (self)
20408@value{GDBN} will call this method to display the string
20409representation of the value passed to the object's constructor.
20410
20411When printing from the CLI, if the @code{to_string} method exists,
20412then @value{GDBN} will prepend its result to the values returned by
20413@code{children}. Exactly how this formatting is done is dependent on
20414the display hint, and may change as more hints are added. Also,
20415depending on the print settings (@pxref{Print Settings}), the CLI may
20416print just the result of @code{to_string} in a stack trace, omitting
20417the result of @code{children}.
20418
20419If this method returns a string, it is printed verbatim.
20420
20421Otherwise, if this method returns an instance of @code{gdb.Value},
20422then @value{GDBN} prints this value. This may result in a call to
20423another pretty-printer.
20424
20425If instead the method returns a Python value which is convertible to a
20426@code{gdb.Value}, then @value{GDBN} performs the conversion and prints
20427the resulting value. Again, this may result in a call to another
20428pretty-printer. Python scalars (integers, floats, and booleans) and
20429strings are convertible to @code{gdb.Value}; other types are not.
20430
20431If the result is not one of these types, an exception is raised.
20432@end defop
20433
20434@node Selecting Pretty-Printers
20435@subsubsection Selecting Pretty-Printers
20436
20437The Python list @code{gdb.pretty_printers} contains an array of
20438functions that have been registered via addition as a pretty-printer.
20439Each @code{gdb.Objfile} also contains a @code{pretty_printers}
20440attribute.
20441
20442A function on one of these lists is passed a single @code{gdb.Value}
20443argument and should return a pretty-printer object conforming to the
20444interface definition above (@pxref{Pretty Printing}). If a function
20445cannot create a pretty-printer for the value, it should return
20446@code{None}.
20447
20448@value{GDBN} first checks the @code{pretty_printers} attribute of each
20449@code{gdb.Objfile} and iteratively calls each function in the list for
20450that @code{gdb.Objfile} until it receives a pretty-printer object.
20451After these lists have been exhausted, it tries the global
20452@code{gdb.pretty-printers} list, again calling each function until an
20453object is returned.
20454
20455The order in which the objfiles are searched is not specified. For a
20456given list, functions are always invoked from the head of the list,
20457and iterated over sequentially until the end of the list, or a printer
20458object is returned.
20459
20460Here is an example showing how a @code{std::string} printer might be
20461written:
20462
20463@smallexample
20464class StdStringPrinter:
20465 "Print a std::string"
20466
20467 def __init__ (self, val):
20468 self.val = val
20469
20470 def to_string (self):
20471 return self.val['_M_dataplus']['_M_p']
20472
20473 def display_hint (self):
20474 return 'string'
20475@end smallexample
20476
20477And here is an example showing how a lookup function for the printer
20478example above might be written.
20479
20480@smallexample
20481def str_lookup_function (val):
20482
20483 lookup_tag = val.type.tag
20484 regex = re.compile ("^std::basic_string<char,.*>$")
20485 if lookup_tag == None:
20486 return None
20487 if regex.match (lookup_tag):
20488 return StdStringPrinter (val)
20489
20490 return None
20491@end smallexample
20492
20493The example lookup function extracts the value's type, and attempts to
20494match it to a type that it can pretty-print. If it is a type the
20495printer can pretty-print, it will return a printer object. If not, it
20496returns @code{None}.
20497
20498We recommend that you put your core pretty-printers into a Python
20499package. If your pretty-printers are for use with a library, we
20500further recommend embedding a version number into the package name.
20501This practice will enable @value{GDBN} to load multiple versions of
20502your pretty-printers at the same time, because they will have
20503different names.
20504
20505You should write auto-loaded code (@pxref{Auto-loading}) such that it
20506can be evaluated multiple times without changing its meaning. An
20507ideal auto-load file will consist solely of @code{import}s of your
20508printer modules, followed by a call to a register pretty-printers with
20509the current objfile.
20510
20511Taken as a whole, this approach will scale nicely to multiple
20512inferiors, each potentially using a different library version.
20513Embedding a version number in the Python package name will ensure that
20514@value{GDBN} is able to load both sets of printers simultaneously.
20515Then, because the search for pretty-printers is done by objfile, and
20516because your auto-loaded code took care to register your library's
20517printers with a specific objfile, @value{GDBN} will find the correct
20518printers for the specific version of the library used by each
20519inferior.
20520
20521To continue the @code{std::string} example (@pxref{Pretty Printing}),
20522this code might appear in @code{gdb.libstdcxx.v6}:
20523
20524@smallexample
20525def register_printers (objfile):
20526 objfile.pretty_printers.add (str_lookup_function)
20527@end smallexample
20528
20529@noindent
20530And then the corresponding contents of the auto-load file would be:
20531
20532@smallexample
20533import gdb.libstdcxx.v6
20534gdb.libstdcxx.v6.register_printers (gdb.current_objfile ())
20535@end smallexample
20536
d8906c6f
TJB
20537@node Commands In Python
20538@subsubsection Commands In Python
20539
20540@cindex commands in python
20541@cindex python commands
d8906c6f
TJB
20542You can implement new @value{GDBN} CLI commands in Python. A CLI
20543command is implemented using an instance of the @code{gdb.Command}
20544class, most commonly using a subclass.
20545
cc924cad 20546@defmethod Command __init__ name @var{command_class} @r{[}@var{completer_class}@r{]} @r{[}@var{prefix}@r{]}
d8906c6f
TJB
20547The object initializer for @code{Command} registers the new command
20548with @value{GDBN}. This initializer is normally invoked from the
20549subclass' own @code{__init__} method.
20550
20551@var{name} is the name of the command. If @var{name} consists of
20552multiple words, then the initial words are looked for as prefix
20553commands. In this case, if one of the prefix commands does not exist,
20554an exception is raised.
20555
20556There is no support for multi-line commands.
20557
cc924cad 20558@var{command_class} should be one of the @samp{COMMAND_} constants
d8906c6f
TJB
20559defined below. This argument tells @value{GDBN} how to categorize the
20560new command in the help system.
20561
cc924cad 20562@var{completer_class} is an optional argument. If given, it should be
d8906c6f
TJB
20563one of the @samp{COMPLETE_} constants defined below. This argument
20564tells @value{GDBN} how to perform completion for this command. If not
20565given, @value{GDBN} will attempt to complete using the object's
20566@code{complete} method (see below); if no such method is found, an
20567error will occur when completion is attempted.
20568
20569@var{prefix} is an optional argument. If @code{True}, then the new
20570command is a prefix command; sub-commands of this command may be
20571registered.
20572
20573The help text for the new command is taken from the Python
20574documentation string for the command's class, if there is one. If no
20575documentation string is provided, the default value ``This command is
20576not documented.'' is used.
20577@end defmethod
20578
a0c36267 20579@cindex don't repeat Python command
d8906c6f
TJB
20580@defmethod Command dont_repeat
20581By default, a @value{GDBN} command is repeated when the user enters a
20582blank line at the command prompt. A command can suppress this
20583behavior by invoking the @code{dont_repeat} method. This is similar
20584to the user command @code{dont-repeat}, see @ref{Define, dont-repeat}.
20585@end defmethod
20586
20587@defmethod Command invoke argument from_tty
20588This method is called by @value{GDBN} when this command is invoked.
20589
20590@var{argument} is a string. It is the argument to the command, after
20591leading and trailing whitespace has been stripped.
20592
20593@var{from_tty} is a boolean argument. When true, this means that the
20594command was entered by the user at the terminal; when false it means
20595that the command came from elsewhere.
20596
20597If this method throws an exception, it is turned into a @value{GDBN}
20598@code{error} call. Otherwise, the return value is ignored.
20599@end defmethod
20600
a0c36267 20601@cindex completion of Python commands
d8906c6f
TJB
20602@defmethod Command complete text word
20603This method is called by @value{GDBN} when the user attempts
20604completion on this command. All forms of completion are handled by
a0c36267
EZ
20605this method, that is, the @key{TAB} and @key{M-?} key bindings
20606(@pxref{Completion}), and the @code{complete} command (@pxref{Help,
20607complete}).
d8906c6f
TJB
20608
20609The arguments @var{text} and @var{word} are both strings. @var{text}
20610holds the complete command line up to the cursor's location.
20611@var{word} holds the last word of the command line; this is computed
20612using a word-breaking heuristic.
20613
20614The @code{complete} method can return several values:
20615@itemize @bullet
20616@item
20617If the return value is a sequence, the contents of the sequence are
20618used as the completions. It is up to @code{complete} to ensure that the
20619contents actually do complete the word. A zero-length sequence is
20620allowed, it means that there were no completions available. Only
20621string elements of the sequence are used; other elements in the
20622sequence are ignored.
20623
20624@item
20625If the return value is one of the @samp{COMPLETE_} constants defined
20626below, then the corresponding @value{GDBN}-internal completion
20627function is invoked, and its result is used.
20628
20629@item
20630All other results are treated as though there were no available
20631completions.
20632@end itemize
20633@end defmethod
20634
d8906c6f
TJB
20635When a new command is registered, it must be declared as a member of
20636some general class of commands. This is used to classify top-level
20637commands in the on-line help system; note that prefix commands are not
20638listed under their own category but rather that of their top-level
20639command. The available classifications are represented by constants
20640defined in the @code{gdb} module:
20641
20642@table @code
20643@findex COMMAND_NONE
20644@findex gdb.COMMAND_NONE
20645@item COMMAND_NONE
20646The command does not belong to any particular class. A command in
20647this category will not be displayed in any of the help categories.
20648
20649@findex COMMAND_RUNNING
20650@findex gdb.COMMAND_RUNNING
a0c36267 20651@item COMMAND_RUNNING
d8906c6f
TJB
20652The command is related to running the inferior. For example,
20653@code{start}, @code{step}, and @code{continue} are in this category.
a0c36267 20654Type @kbd{help running} at the @value{GDBN} prompt to see a list of
d8906c6f
TJB
20655commands in this category.
20656
20657@findex COMMAND_DATA
20658@findex gdb.COMMAND_DATA
a0c36267 20659@item COMMAND_DATA
d8906c6f
TJB
20660The command is related to data or variables. For example,
20661@code{call}, @code{find}, and @code{print} are in this category. Type
a0c36267 20662@kbd{help data} at the @value{GDBN} prompt to see a list of commands
d8906c6f
TJB
20663in this category.
20664
20665@findex COMMAND_STACK
20666@findex gdb.COMMAND_STACK
20667@item COMMAND_STACK
20668The command has to do with manipulation of the stack. For example,
20669@code{backtrace}, @code{frame}, and @code{return} are in this
a0c36267 20670category. Type @kbd{help stack} at the @value{GDBN} prompt to see a
d8906c6f
TJB
20671list of commands in this category.
20672
20673@findex COMMAND_FILES
20674@findex gdb.COMMAND_FILES
20675@item COMMAND_FILES
20676This class is used for file-related commands. For example,
20677@code{file}, @code{list} and @code{section} are in this category.
a0c36267 20678Type @kbd{help files} at the @value{GDBN} prompt to see a list of
d8906c6f
TJB
20679commands in this category.
20680
20681@findex COMMAND_SUPPORT
20682@findex gdb.COMMAND_SUPPORT
20683@item COMMAND_SUPPORT
20684This should be used for ``support facilities'', generally meaning
20685things that are useful to the user when interacting with @value{GDBN},
20686but not related to the state of the inferior. For example,
20687@code{help}, @code{make}, and @code{shell} are in this category. Type
a0c36267 20688@kbd{help support} at the @value{GDBN} prompt to see a list of
d8906c6f
TJB
20689commands in this category.
20690
20691@findex COMMAND_STATUS
20692@findex gdb.COMMAND_STATUS
a0c36267 20693@item COMMAND_STATUS
d8906c6f
TJB
20694The command is an @samp{info}-related command, that is, related to the
20695state of @value{GDBN} itself. For example, @code{info}, @code{macro},
a0c36267 20696and @code{show} are in this category. Type @kbd{help status} at the
d8906c6f
TJB
20697@value{GDBN} prompt to see a list of commands in this category.
20698
20699@findex COMMAND_BREAKPOINTS
20700@findex gdb.COMMAND_BREAKPOINTS
a0c36267 20701@item COMMAND_BREAKPOINTS
d8906c6f 20702The command has to do with breakpoints. For example, @code{break},
a0c36267 20703@code{clear}, and @code{delete} are in this category. Type @kbd{help
d8906c6f
TJB
20704breakpoints} at the @value{GDBN} prompt to see a list of commands in
20705this category.
20706
20707@findex COMMAND_TRACEPOINTS
20708@findex gdb.COMMAND_TRACEPOINTS
a0c36267 20709@item COMMAND_TRACEPOINTS
d8906c6f
TJB
20710The command has to do with tracepoints. For example, @code{trace},
20711@code{actions}, and @code{tfind} are in this category. Type
a0c36267 20712@kbd{help tracepoints} at the @value{GDBN} prompt to see a list of
d8906c6f
TJB
20713commands in this category.
20714
20715@findex COMMAND_OBSCURE
20716@findex gdb.COMMAND_OBSCURE
20717@item COMMAND_OBSCURE
20718The command is only used in unusual circumstances, or is not of
20719general interest to users. For example, @code{checkpoint},
a0c36267 20720@code{fork}, and @code{stop} are in this category. Type @kbd{help
d8906c6f
TJB
20721obscure} at the @value{GDBN} prompt to see a list of commands in this
20722category.
20723
20724@findex COMMAND_MAINTENANCE
20725@findex gdb.COMMAND_MAINTENANCE
20726@item COMMAND_MAINTENANCE
20727The command is only useful to @value{GDBN} maintainers. The
20728@code{maintenance} and @code{flushregs} commands are in this category.
a0c36267 20729Type @kbd{help internals} at the @value{GDBN} prompt to see a list of
d8906c6f
TJB
20730commands in this category.
20731@end table
20732
d8906c6f
TJB
20733A new command can use a predefined completion function, either by
20734specifying it via an argument at initialization, or by returning it
20735from the @code{complete} method. These predefined completion
20736constants are all defined in the @code{gdb} module:
20737
20738@table @code
20739@findex COMPLETE_NONE
20740@findex gdb.COMPLETE_NONE
20741@item COMPLETE_NONE
20742This constant means that no completion should be done.
20743
20744@findex COMPLETE_FILENAME
20745@findex gdb.COMPLETE_FILENAME
20746@item COMPLETE_FILENAME
20747This constant means that filename completion should be performed.
20748
20749@findex COMPLETE_LOCATION
20750@findex gdb.COMPLETE_LOCATION
20751@item COMPLETE_LOCATION
20752This constant means that location completion should be done.
20753@xref{Specify Location}.
20754
20755@findex COMPLETE_COMMAND
20756@findex gdb.COMPLETE_COMMAND
20757@item COMPLETE_COMMAND
20758This constant means that completion should examine @value{GDBN}
20759command names.
20760
20761@findex COMPLETE_SYMBOL
20762@findex gdb.COMPLETE_SYMBOL
20763@item COMPLETE_SYMBOL
20764This constant means that completion should be done using symbol names
20765as the source.
20766@end table
20767
20768The following code snippet shows how a trivial CLI command can be
20769implemented in Python:
20770
20771@smallexample
20772class HelloWorld (gdb.Command):
20773 """Greet the whole world."""
20774
20775 def __init__ (self):
20776 super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_OBSCURE)
20777
20778 def invoke (self, arg, from_tty):
20779 print "Hello, World!"
20780
20781HelloWorld ()
20782@end smallexample
20783
20784The last line instantiates the class, and is necessary to trigger the
20785registration of the command with @value{GDBN}. Depending on how the
20786Python code is read into @value{GDBN}, you may need to import the
20787@code{gdb} module explicitly.
20788
bc3b79fd
TJB
20789@node Functions In Python
20790@subsubsection Writing new convenience functions
20791
20792@cindex writing convenience functions
20793@cindex convenience functions in python
20794@cindex python convenience functions
20795@tindex gdb.Function
20796@tindex Function
20797You can implement new convenience functions (@pxref{Convenience Vars})
20798in Python. A convenience function is an instance of a subclass of the
20799class @code{gdb.Function}.
20800
20801@defmethod Function __init__ name
20802The initializer for @code{Function} registers the new function with
20803@value{GDBN}. The argument @var{name} is the name of the function,
20804a string. The function will be visible to the user as a convenience
20805variable of type @code{internal function}, whose name is the same as
20806the given @var{name}.
20807
20808The documentation for the new function is taken from the documentation
20809string for the new class.
20810@end defmethod
20811
20812@defmethod Function invoke @var{*args}
20813When a convenience function is evaluated, its arguments are converted
20814to instances of @code{gdb.Value}, and then the function's
20815@code{invoke} method is called. Note that @value{GDBN} does not
20816predetermine the arity of convenience functions. Instead, all
20817available arguments are passed to @code{invoke}, following the
20818standard Python calling convention. In particular, a convenience
20819function can have default values for parameters without ill effect.
20820
20821The return value of this method is used as its value in the enclosing
20822expression. If an ordinary Python value is returned, it is converted
20823to a @code{gdb.Value} following the usual rules.
20824@end defmethod
20825
20826The following code snippet shows how a trivial convenience function can
20827be implemented in Python:
20828
20829@smallexample
20830class Greet (gdb.Function):
20831 """Return string to greet someone.
20832Takes a name as argument."""
20833
20834 def __init__ (self):
20835 super (Greet, self).__init__ ("greet")
20836
20837 def invoke (self, name):
20838 return "Hello, %s!" % name.string ()
20839
20840Greet ()
20841@end smallexample
20842
20843The last line instantiates the class, and is necessary to trigger the
20844registration of the function with @value{GDBN}. Depending on how the
20845Python code is read into @value{GDBN}, you may need to import the
20846@code{gdb} module explicitly.
20847
89c73ade
TT
20848@node Objfiles In Python
20849@subsubsection Objfiles In Python
20850
20851@cindex objfiles in python
20852@tindex gdb.Objfile
20853@tindex Objfile
20854@value{GDBN} loads symbols for an inferior from various
20855symbol-containing files (@pxref{Files}). These include the primary
20856executable file, any shared libraries used by the inferior, and any
20857separate debug info files (@pxref{Separate Debug Files}).
20858@value{GDBN} calls these symbol-containing files @dfn{objfiles}.
20859
20860The following objfile-related functions are available in the
20861@code{gdb} module:
20862
20863@findex gdb.current_objfile
20864@defun current_objfile
20865When auto-loading a Python script (@pxref{Auto-loading}), @value{GDBN}
20866sets the ``current objfile'' to the corresponding objfile. This
20867function returns the current objfile. If there is no current objfile,
20868this function returns @code{None}.
20869@end defun
20870
20871@findex gdb.objfiles
20872@defun objfiles
20873Return a sequence of all the objfiles current known to @value{GDBN}.
20874@xref{Objfiles In Python}.
20875@end defun
20876
20877Each objfile is represented by an instance of the @code{gdb.Objfile}
20878class.
20879
20880@defivar Objfile filename
20881The file name of the objfile as a string.
20882@end defivar
20883
20884@defivar Objfile pretty_printers
20885The @code{pretty_printers} attribute is a list of functions. It is
20886used to look up pretty-printers. A @code{Value} is passed to each
20887function in order; if the function returns @code{None}, then the
20888search continues. Otherwise, the return value should be an object
a6bac58e
TT
20889which is used to format the value. @xref{Pretty Printing}, for more
20890information.
89c73ade
TT
20891@end defivar
20892
f8f6f20b 20893@node Frames In Python
f3e9a817 20894@subsubsection Accessing inferior stack frames from Python.
f8f6f20b
TJB
20895
20896@cindex frames in python
20897When the debugged program stops, @value{GDBN} is able to analyze its call
20898stack (@pxref{Frames,,Stack frames}). The @code{gdb.Frame} class
20899represents a frame in the stack. A @code{gdb.Frame} object is only valid
20900while its corresponding frame exists in the inferior's stack. If you try
20901to use an invalid frame object, @value{GDBN} will throw a @code{RuntimeError}
20902exception.
20903
20904Two @code{gdb.Frame} objects can be compared for equality with the @code{==}
20905operator, like:
20906
20907@smallexample
20908(@value{GDBP}) python print gdb.newest_frame() == gdb.selected_frame ()
20909True
20910@end smallexample
20911
20912The following frame-related functions are available in the @code{gdb} module:
20913
20914@findex gdb.selected_frame
20915@defun selected_frame
20916Return the selected frame object. (@pxref{Selection,,Selecting a Frame}).
20917@end defun
20918
20919@defun frame_stop_reason_string reason
20920Return a string explaining the reason why @value{GDBN} stopped unwinding
20921frames, as expressed by the given @var{reason} code (an integer, see the
20922@code{unwind_stop_reason} method further down in this section).
20923@end defun
20924
20925A @code{gdb.Frame} object has the following methods:
20926
20927@table @code
20928@defmethod Frame is_valid
20929Returns true if the @code{gdb.Frame} object is valid, false if not.
20930A frame object can become invalid if the frame it refers to doesn't
20931exist anymore in the inferior. All @code{gdb.Frame} methods will throw
20932an exception if it is invalid at the time the method is called.
20933@end defmethod
20934
20935@defmethod Frame name
20936Returns the function name of the frame, or @code{None} if it can't be
20937obtained.
20938@end defmethod
20939
20940@defmethod Frame type
20941Returns the type of the frame. The value can be one of
20942@code{gdb.NORMAL_FRAME}, @code{gdb.DUMMY_FRAME}, @code{gdb.SIGTRAMP_FRAME}
20943or @code{gdb.SENTINEL_FRAME}.
20944@end defmethod
20945
20946@defmethod Frame unwind_stop_reason
20947Return an integer representing the reason why it's not possible to find
20948more frames toward the outermost frame. Use
20949@code{gdb.frame_stop_reason_string} to convert the value returned by this
20950function to a string.
20951@end defmethod
20952
20953@defmethod Frame pc
20954Returns the frame's resume address.
20955@end defmethod
20956
f3e9a817
PM
20957@defmethod Frame block
20958Return the frame's code block. @xref{Blocks In Python}.
20959@end defmethod
20960
20961@defmethod Frame function
20962Return the symbol for the function corresponding to this frame.
20963@xref{Symbols In Python}.
20964@end defmethod
20965
f8f6f20b
TJB
20966@defmethod Frame older
20967Return the frame that called this frame.
20968@end defmethod
20969
20970@defmethod Frame newer
20971Return the frame called by this frame.
20972@end defmethod
20973
f3e9a817
PM
20974@defmethod Frame find_sal
20975Return the frame's symtab and line object.
20976@xref{Symbol Tables In Python}.
20977@end defmethod
20978
dc00d89f
PM
20979@defmethod Frame read_var variable @r{[}block@r{]}
20980Return the value of @var{variable} in this frame. If the optional
20981argument @var{block} is provided, search for the variable from that
20982block; otherwise start at the frame's current block (which is
20983determined by the frame's current program counter). @var{variable}
20984must be a string or a @code{gdb.Symbol} object. @var{block} must be a
20985@code{gdb.Block} object.
f8f6f20b 20986@end defmethod
f3e9a817
PM
20987
20988@defmethod Frame select
20989Set this frame to be the selected frame. @xref{Stack, ,Examining the
20990Stack}.
20991@end defmethod
20992@end table
20993
20994@node Blocks In Python
20995@subsubsection Accessing frame blocks from Python.
20996
20997@cindex blocks in python
20998@tindex gdb.Block
20999
21000Within each frame, @value{GDBN} maintains information on each block
21001stored in that frame. These blocks are organized hierarchically, and
21002are represented individually in Python as a @code{gdb.Block}.
21003Please see @ref{Frames In Python}, for a more in-depth discussion on
21004frames. Furthermore, see @ref{Stack, ,Examining the Stack}, for more
21005detailed technical information on @value{GDBN}'s book-keeping of the
21006stack.
21007
21008The following block-related functions are available in the @code{gdb}
21009module:
21010
21011@findex gdb.block_for_pc
21012@defun block_for_pc pc
21013Return the @code{gdb.Block} containing the given @var{pc} value. If the
21014block cannot be found for the @var{pc} value specified, the function
21015will return @code{None}.
21016@end defun
21017
21018A @code{gdb.Block} object has the following attributes:
21019
21020@table @code
21021@defivar Block start
21022The start address of the block. This attribute is not writable.
21023@end defivar
21024
21025@defivar Block end
21026The end address of the block. This attribute is not writable.
21027@end defivar
21028
21029@defivar Block function
21030The name of the block represented as a @code{gdb.Symbol}. If the
21031block is not named, then this attribute holds @code{None}. This
21032attribute is not writable.
21033@end defivar
21034
21035@defivar Block superblock
21036The block containing this block. If this parent block does not exist,
21037this attribute holds @code{None}. This attribute is not writable.
21038@end defivar
21039@end table
21040
21041@node Symbols In Python
21042@subsubsection Python representation of Symbols.
21043
21044@cindex symbols in python
21045@tindex gdb.Symbol
21046
21047@value{GDBN} represents every variable, function and type as an
21048entry in a symbol table. @xref{Symbols, ,Examining the Symbol Table}.
21049Similarly, Python represents these symbols in @value{GDBN} with the
21050@code{gdb.Symbol} object.
21051
21052The following symbol-related functions are available in the @code{gdb}
21053module:
21054
21055@findex gdb.lookup_symbol
21056@defun lookup_symbol name [block] [domain]
21057This function searches for a symbol by name. The search scope can be
21058restricted to the parameters defined in the optional domain and block
21059arguments.
21060
21061@var{name} is the name of the symbol. It must be a string. The
21062optional @var{block} argument restricts the search to symbols visible
21063in that @var{block}. The @var{block} argument must be a
21064@code{gdb.Block} object. The optional @var{domain} argument restricts
21065the search to the domain type. The @var{domain} argument must be a
21066domain constant defined in the @code{gdb} module and described later
21067in this chapter.
21068@end defun
21069
21070A @code{gdb.Symbol} object has the following attributes:
21071
21072@table @code
21073@defivar Symbol symtab
21074The symbol table in which the symbol appears. This attribute is
21075represented as a @code{gdb.Symtab} object. @xref{Symbol Tables In
21076Python}. This attribute is not writable.
21077@end defivar
21078
21079@defivar Symbol name
21080The name of the symbol as a string. This attribute is not writable.
21081@end defivar
21082
21083@defivar Symbol linkage_name
21084The name of the symbol, as used by the linker (i.e., may be mangled).
21085This attribute is not writable.
21086@end defivar
21087
21088@defivar Symbol print_name
21089The name of the symbol in a form suitable for output. This is either
21090@code{name} or @code{linkage_name}, depending on whether the user
21091asked @value{GDBN} to display demangled or mangled names.
21092@end defivar
21093
21094@defivar Symbol addr_class
21095The address class of the symbol. This classifies how to find the value
21096of a symbol. Each address class is a constant defined in the
21097@code{gdb} module and described later in this chapter.
21098@end defivar
21099
21100@defivar Symbol is_argument
21101@code{True} if the symbol is an argument of a function.
21102@end defivar
21103
21104@defivar Symbol is_constant
21105@code{True} if the symbol is a constant.
21106@end defivar
21107
21108@defivar Symbol is_function
21109@code{True} if the symbol is a function or a method.
21110@end defivar
21111
21112@defivar Symbol is_variable
21113@code{True} if the symbol is a variable.
21114@end defivar
21115@end table
21116
21117The available domain categories in @code{gdb.Symbol} are represented
21118as constants in the @code{gdb} module:
21119
21120@table @code
21121@findex SYMBOL_UNDEF_DOMAIN
21122@findex gdb.SYMBOL_UNDEF_DOMAIN
21123@item SYMBOL_UNDEF_DOMAIN
21124This is used when a domain has not been discovered or none of the
21125following domains apply. This usually indicates an error either
21126in the symbol information or in @value{GDBN}'s handling of symbols.
21127@findex SYMBOL_VAR_DOMAIN
21128@findex gdb.SYMBOL_VAR_DOMAIN
21129@item SYMBOL_VAR_DOMAIN
21130This domain contains variables, function names, typedef names and enum
21131type values.
21132@findex SYMBOL_STRUCT_DOMAIN
21133@findex gdb.SYMBOL_STRUCT_DOMAIN
21134@item SYMBOL_STRUCT_DOMAIN
21135This domain holds struct, union and enum type names.
21136@findex SYMBOL_LABEL_DOMAIN
21137@findex gdb.SYMBOL_LABEL_DOMAIN
21138@item SYMBOL_LABEL_DOMAIN
21139This domain contains names of labels (for gotos).
21140@findex SYMBOL_VARIABLES_DOMAIN
21141@findex gdb.SYMBOL_VARIABLES_DOMAIN
21142@item SYMBOL_VARIABLES_DOMAIN
21143This domain holds a subset of the @code{SYMBOLS_VAR_DOMAIN}; it
21144contains everything minus functions and types.
21145@findex SYMBOL_FUNCTIONS_DOMAIN
21146@findex gdb.SYMBOL_FUNCTIONS_DOMAIN
21147@item SYMBOL_FUNCTION_DOMAIN
21148This domain contains all functions.
21149@findex SYMBOL_TYPES_DOMAIN
21150@findex gdb.SYMBOL_TYPES_DOMAIN
21151@item SYMBOL_TYPES_DOMAIN
21152This domain contains all types.
21153@end table
21154
21155The available address class categories in @code{gdb.Symbol} are represented
21156as constants in the @code{gdb} module:
21157
21158@table @code
21159@findex SYMBOL_LOC_UNDEF
21160@findex gdb.SYMBOL_LOC_UNDEF
21161@item SYMBOL_LOC_UNDEF
21162If this is returned by address class, it indicates an error either in
21163the symbol information or in @value{GDBN}'s handling of symbols.
21164@findex SYMBOL_LOC_CONST
21165@findex gdb.SYMBOL_LOC_CONST
21166@item SYMBOL_LOC_CONST
21167Value is constant int.
21168@findex SYMBOL_LOC_STATIC
21169@findex gdb.SYMBOL_LOC_STATIC
21170@item SYMBOL_LOC_STATIC
21171Value is at a fixed address.
21172@findex SYMBOL_LOC_REGISTER
21173@findex gdb.SYMBOL_LOC_REGISTER
21174@item SYMBOL_LOC_REGISTER
21175Value is in a register.
21176@findex SYMBOL_LOC_ARG
21177@findex gdb.SYMBOL_LOC_ARG
21178@item SYMBOL_LOC_ARG
21179Value is an argument. This value is at the offset stored within the
21180symbol inside the frame's argument list.
21181@findex SYMBOL_LOC_REF_ARG
21182@findex gdb.SYMBOL_LOC_REF_ARG
21183@item SYMBOL_LOC_REF_ARG
21184Value address is stored in the frame's argument list. Just like
21185@code{LOC_ARG} except that the value's address is stored at the
21186offset, not the value itself.
21187@findex SYMBOL_LOC_REGPARM_ADDR
21188@findex gdb.SYMBOL_LOC_REGPARM_ADDR
21189@item SYMBOL_LOC_REGPARM_ADDR
21190Value is a specified register. Just like @code{LOC_REGISTER} except
21191the register holds the address of the argument instead of the argument
21192itself.
21193@findex SYMBOL_LOC_LOCAL
21194@findex gdb.SYMBOL_LOC_LOCAL
21195@item SYMBOL_LOC_LOCAL
21196Value is a local variable.
21197@findex SYMBOL_LOC_TYPEDEF
21198@findex gdb.SYMBOL_LOC_TYPEDEF
21199@item SYMBOL_LOC_TYPEDEF
21200Value not used. Symbols in the domain @code{SYMBOL_STRUCT_DOMAIN} all
21201have this class.
21202@findex SYMBOL_LOC_BLOCK
21203@findex gdb.SYMBOL_LOC_BLOCK
21204@item SYMBOL_LOC_BLOCK
21205Value is a block.
21206@findex SYMBOL_LOC_CONST_BYTES
21207@findex gdb.SYMBOL_LOC_CONST_BYTES
21208@item SYMBOL_LOC_CONST_BYTES
21209Value is a byte-sequence.
21210@findex SYMBOL_LOC_UNRESOLVED
21211@findex gdb.SYMBOL_LOC_UNRESOLVED
21212@item SYMBOL_LOC_UNRESOLVED
21213Value is at a fixed address, but the address of the variable has to be
21214determined from the minimal symbol table whenever the variable is
21215referenced.
21216@findex SYMBOL_LOC_OPTIMIZED_OUT
21217@findex gdb.SYMBOL_LOC_OPTIMIZED_OUT
21218@item SYMBOL_LOC_OPTIMIZED_OUT
21219The value does not actually exist in the program.
21220@findex SYMBOL_LOC_COMPUTED
21221@findex gdb.SYMBOL_LOC_COMPUTED
21222@item SYMBOL_LOC_COMPUTED
21223The value's address is a computed location.
21224@end table
21225
21226@node Symbol Tables In Python
21227@subsubsection Symbol table representation in Python.
21228
21229@cindex symbol tables in python
21230@tindex gdb.Symtab
21231@tindex gdb.Symtab_and_line
21232
21233Access to symbol table data maintained by @value{GDBN} on the inferior
21234is exposed to Python via two objects: @code{gdb.Symtab_and_line} and
21235@code{gdb.Symtab}. Symbol table and line data for a frame is returned
21236from the @code{find_sal} method in @code{gdb.Frame} object.
21237@xref{Frames In Python}.
21238
21239For more information on @value{GDBN}'s symbol table management, see
21240@ref{Symbols, ,Examining the Symbol Table}, for more information.
21241
21242A @code{gdb.Symtab_and_line} object has the following attributes:
21243
21244@table @code
21245@defivar Symtab_and_line symtab
21246The symbol table object (@code{gdb.Symtab}) for this frame.
21247This attribute is not writable.
21248@end defivar
21249
21250@defivar Symtab_and_line pc
21251Indicates the current program counter address. This attribute is not
21252writable.
21253@end defivar
21254
21255@defivar Symtab_and_line line
21256Indicates the current line number for this object. This
21257attribute is not writable.
21258@end defivar
21259@end table
21260
21261A @code{gdb.Symtab} object has the following attributes:
21262
21263@table @code
21264@defivar Symtab filename
21265The symbol table's source filename. This attribute is not writable.
21266@end defivar
21267
21268@defivar Symtab objfile
21269The symbol table's backing object file. @xref{Objfiles In Python}.
21270This attribute is not writable.
21271@end defivar
21272@end table
21273
21274The following methods are provided:
21275
21276@table @code
21277@defmethod Symtab fullname
21278Return the symbol table's source absolute file name.
21279@end defmethod
f8f6f20b
TJB
21280@end table
21281
be759fcf
PM
21282@node Lazy Strings In Python
21283@subsubsection Python representation of lazy strings.
21284
21285@cindex lazy strings in python
21286@tindex gdb.LazyString
21287
21288A @dfn{lazy string} is a string whose contents is not retrieved or
21289encoded until it is needed.
21290
21291A @code{gdb.LazyString} is represented in @value{GDBN} as an
21292@code{address} that points to a region of memory, an @code{encoding}
21293that will be used to encode that region of memory, and a @code{length}
21294to delimit the region of memory that represents the string. The
21295difference between a @code{gdb.LazyString} and a string wrapped within
21296a @code{gdb.Value} is that a @code{gdb.LazyString} will be treated
21297differently by @value{GDBN} when printing. A @code{gdb.LazyString} is
21298retrieved and encoded during printing, while a @code{gdb.Value}
21299wrapping a string is immediately retrieved and encoded on creation.
21300
21301A @code{gdb.LazyString} object has the following functions:
21302
21303@defmethod LazyString value
21304Convert the @code{gdb.LazyString} to a @code{gdb.Value}. This value
21305will point to the string in memory, but will lose all the delayed
21306retrieval, encoding and handling that @value{GDBN} applies to a
21307@code{gdb.LazyString}.
21308@end defmethod
21309
21310@defivar LazyString address
21311This attribute holds the address of the string. This attribute is not
21312writable.
21313@end defivar
21314
21315@defivar LazyString length
21316This attribute holds the length of the string in characters. If the
21317length is -1, then the string will be fetched and encoded up to the
21318first null of appropriate width. This attribute is not writable.
21319@end defivar
21320
21321@defivar LazyString encoding
21322This attribute holds the encoding that will be applied to the string
21323when the string is printed by @value{GDBN}. If the encoding is not
21324set, or contains an empty string, then @value{GDBN} will select the
21325most appropriate encoding when the string is printed. This attribute
21326is not writable.
21327@end defivar
21328
21329@defivar LazyString type
21330This attribute holds the type that is represented by the lazy string's
21331type. For a lazy string this will always be a pointer type. To
21332resolve this to the lazy string's character type, use the type's
21333@code{target} method. @xref{Types In Python}. This attribute is not
21334writable.
21335@end defivar
21336
21c294e6
AC
21337@node Interpreters
21338@chapter Command Interpreters
21339@cindex command interpreters
21340
21341@value{GDBN} supports multiple command interpreters, and some command
21342infrastructure to allow users or user interface writers to switch
21343between interpreters or run commands in other interpreters.
21344
21345@value{GDBN} currently supports two command interpreters, the console
21346interpreter (sometimes called the command-line interpreter or @sc{cli})
21347and the machine interface interpreter (or @sc{gdb/mi}). This manual
21348describes both of these interfaces in great detail.
21349
21350By default, @value{GDBN} will start with the console interpreter.
21351However, the user may choose to start @value{GDBN} with another
21352interpreter by specifying the @option{-i} or @option{--interpreter}
21353startup options. Defined interpreters include:
21354
21355@table @code
21356@item console
21357@cindex console interpreter
21358The traditional console or command-line interpreter. This is the most often
21359used interpreter with @value{GDBN}. With no interpreter specified at runtime,
21360@value{GDBN} will use this interpreter.
21361
21362@item mi
21363@cindex mi interpreter
21364The newest @sc{gdb/mi} interface (currently @code{mi2}). Used primarily
21365by programs wishing to use @value{GDBN} as a backend for a debugger GUI
21366or an IDE. For more information, see @ref{GDB/MI, ,The @sc{gdb/mi}
21367Interface}.
21368
21369@item mi2
21370@cindex mi2 interpreter
21371The current @sc{gdb/mi} interface.
21372
21373@item mi1
21374@cindex mi1 interpreter
21375The @sc{gdb/mi} interface included in @value{GDBN} 5.1, 5.2, and 5.3.
21376
21377@end table
21378
21379@cindex invoke another interpreter
21380The interpreter being used by @value{GDBN} may not be dynamically
21381switched at runtime. Although possible, this could lead to a very
21382precarious situation. Consider an IDE using @sc{gdb/mi}. If a user
21383enters the command "interpreter-set console" in a console view,
21384@value{GDBN} would switch to using the console interpreter, rendering
21385the IDE inoperable!
21386
21387@kindex interpreter-exec
21388Although you may only choose a single interpreter at startup, you may execute
21389commands in any interpreter from the current interpreter using the appropriate
21390command. If you are running the console interpreter, simply use the
21391@code{interpreter-exec} command:
21392
21393@smallexample
21394interpreter-exec mi "-data-list-register-names"
21395@end smallexample
21396
21397@sc{gdb/mi} has a similar command, although it is only available in versions of
21398@value{GDBN} which support @sc{gdb/mi} version 2 (or greater).
21399
8e04817f
AC
21400@node TUI
21401@chapter @value{GDBN} Text User Interface
21402@cindex TUI
d0d5df6f 21403@cindex Text User Interface
c906108c 21404
8e04817f
AC
21405@menu
21406* TUI Overview:: TUI overview
21407* TUI Keys:: TUI key bindings
7cf36c78 21408* TUI Single Key Mode:: TUI single key mode
db2e3e2e 21409* TUI Commands:: TUI-specific commands
8e04817f
AC
21410* TUI Configuration:: TUI configuration variables
21411@end menu
c906108c 21412
46ba6afa 21413The @value{GDBN} Text User Interface (TUI) is a terminal
d0d5df6f
AC
21414interface which uses the @code{curses} library to show the source
21415file, the assembly output, the program registers and @value{GDBN}
46ba6afa
BW
21416commands in separate text windows. The TUI mode is supported only
21417on platforms where a suitable version of the @code{curses} library
21418is available.
d0d5df6f 21419
46ba6afa
BW
21420@pindex @value{GDBTUI}
21421The TUI mode is enabled by default when you invoke @value{GDBN} as
21422either @samp{@value{GDBTUI}} or @samp{@value{GDBP} -tui}.
21423You can also switch in and out of TUI mode while @value{GDBN} runs by
21424using various TUI commands and key bindings, such as @kbd{C-x C-a}.
21425@xref{TUI Keys, ,TUI Key Bindings}.
c906108c 21426
8e04817f 21427@node TUI Overview
79a6e687 21428@section TUI Overview
c906108c 21429
46ba6afa 21430In TUI mode, @value{GDBN} can display several text windows:
c906108c 21431
8e04817f
AC
21432@table @emph
21433@item command
21434This window is the @value{GDBN} command window with the @value{GDBN}
46ba6afa
BW
21435prompt and the @value{GDBN} output. The @value{GDBN} input is still
21436managed using readline.
c906108c 21437
8e04817f
AC
21438@item source
21439The source window shows the source file of the program. The current
46ba6afa 21440line and active breakpoints are displayed in this window.
c906108c 21441
8e04817f
AC
21442@item assembly
21443The assembly window shows the disassembly output of the program.
c906108c 21444
8e04817f 21445@item register
46ba6afa
BW
21446This window shows the processor registers. Registers are highlighted
21447when their values change.
c906108c
SS
21448@end table
21449
269c21fe 21450The source and assembly windows show the current program position
46ba6afa
BW
21451by highlighting the current line and marking it with a @samp{>} marker.
21452Breakpoints are indicated with two markers. The first marker
269c21fe
SC
21453indicates the breakpoint type:
21454
21455@table @code
21456@item B
21457Breakpoint which was hit at least once.
21458
21459@item b
21460Breakpoint which was never hit.
21461
21462@item H
21463Hardware breakpoint which was hit at least once.
21464
21465@item h
21466Hardware breakpoint which was never hit.
269c21fe
SC
21467@end table
21468
21469The second marker indicates whether the breakpoint is enabled or not:
21470
21471@table @code
21472@item +
21473Breakpoint is enabled.
21474
21475@item -
21476Breakpoint is disabled.
269c21fe
SC
21477@end table
21478
46ba6afa
BW
21479The source, assembly and register windows are updated when the current
21480thread changes, when the frame changes, or when the program counter
21481changes.
21482
21483These windows are not all visible at the same time. The command
21484window is always visible. The others can be arranged in several
21485layouts:
c906108c 21486
8e04817f
AC
21487@itemize @bullet
21488@item
46ba6afa 21489source only,
2df3850c 21490
8e04817f 21491@item
46ba6afa 21492assembly only,
8e04817f
AC
21493
21494@item
46ba6afa 21495source and assembly,
8e04817f
AC
21496
21497@item
46ba6afa 21498source and registers, or
c906108c 21499
8e04817f 21500@item
46ba6afa 21501assembly and registers.
8e04817f 21502@end itemize
c906108c 21503
46ba6afa 21504A status line above the command window shows the following information:
b7bb15bc
SC
21505
21506@table @emph
21507@item target
46ba6afa 21508Indicates the current @value{GDBN} target.
b7bb15bc
SC
21509(@pxref{Targets, ,Specifying a Debugging Target}).
21510
21511@item process
46ba6afa 21512Gives the current process or thread number.
b7bb15bc
SC
21513When no process is being debugged, this field is set to @code{No process}.
21514
21515@item function
21516Gives the current function name for the selected frame.
21517The name is demangled if demangling is turned on (@pxref{Print Settings}).
46ba6afa 21518When there is no symbol corresponding to the current program counter,
b7bb15bc
SC
21519the string @code{??} is displayed.
21520
21521@item line
21522Indicates the current line number for the selected frame.
46ba6afa 21523When the current line number is not known, the string @code{??} is displayed.
b7bb15bc
SC
21524
21525@item pc
21526Indicates the current program counter address.
b7bb15bc
SC
21527@end table
21528
8e04817f
AC
21529@node TUI Keys
21530@section TUI Key Bindings
21531@cindex TUI key bindings
c906108c 21532
8e04817f 21533The TUI installs several key bindings in the readline keymaps
46ba6afa 21534(@pxref{Command Line Editing}). The following key bindings
8e04817f 21535are installed for both TUI mode and the @value{GDBN} standard mode.
c906108c 21536
8e04817f
AC
21537@table @kbd
21538@kindex C-x C-a
21539@item C-x C-a
21540@kindex C-x a
21541@itemx C-x a
21542@kindex C-x A
21543@itemx C-x A
46ba6afa
BW
21544Enter or leave the TUI mode. When leaving the TUI mode,
21545the curses window management stops and @value{GDBN} operates using
21546its standard mode, writing on the terminal directly. When reentering
21547the TUI mode, control is given back to the curses windows.
8e04817f 21548The screen is then refreshed.
c906108c 21549
8e04817f
AC
21550@kindex C-x 1
21551@item C-x 1
21552Use a TUI layout with only one window. The layout will
21553either be @samp{source} or @samp{assembly}. When the TUI mode
21554is not active, it will switch to the TUI mode.
2df3850c 21555
8e04817f 21556Think of this key binding as the Emacs @kbd{C-x 1} binding.
c906108c 21557
8e04817f
AC
21558@kindex C-x 2
21559@item C-x 2
21560Use a TUI layout with at least two windows. When the current
46ba6afa 21561layout already has two windows, the next layout with two windows is used.
8e04817f
AC
21562When a new layout is chosen, one window will always be common to the
21563previous layout and the new one.
c906108c 21564
8e04817f 21565Think of it as the Emacs @kbd{C-x 2} binding.
2df3850c 21566
72ffddc9
SC
21567@kindex C-x o
21568@item C-x o
21569Change the active window. The TUI associates several key bindings
46ba6afa 21570(like scrolling and arrow keys) with the active window. This command
72ffddc9
SC
21571gives the focus to the next TUI window.
21572
21573Think of it as the Emacs @kbd{C-x o} binding.
21574
7cf36c78
SC
21575@kindex C-x s
21576@item C-x s
46ba6afa
BW
21577Switch in and out of the TUI SingleKey mode that binds single
21578keys to @value{GDBN} commands (@pxref{TUI Single Key Mode}).
c906108c
SS
21579@end table
21580
46ba6afa 21581The following key bindings only work in the TUI mode:
5d161b24 21582
46ba6afa 21583@table @asis
8e04817f 21584@kindex PgUp
46ba6afa 21585@item @key{PgUp}
8e04817f 21586Scroll the active window one page up.
c906108c 21587
8e04817f 21588@kindex PgDn
46ba6afa 21589@item @key{PgDn}
8e04817f 21590Scroll the active window one page down.
c906108c 21591
8e04817f 21592@kindex Up
46ba6afa 21593@item @key{Up}
8e04817f 21594Scroll the active window one line up.
c906108c 21595
8e04817f 21596@kindex Down
46ba6afa 21597@item @key{Down}
8e04817f 21598Scroll the active window one line down.
c906108c 21599
8e04817f 21600@kindex Left
46ba6afa 21601@item @key{Left}
8e04817f 21602Scroll the active window one column left.
c906108c 21603
8e04817f 21604@kindex Right
46ba6afa 21605@item @key{Right}
8e04817f 21606Scroll the active window one column right.
c906108c 21607
8e04817f 21608@kindex C-L
46ba6afa 21609@item @kbd{C-L}
8e04817f 21610Refresh the screen.
8e04817f 21611@end table
c906108c 21612
46ba6afa
BW
21613Because the arrow keys scroll the active window in the TUI mode, they
21614are not available for their normal use by readline unless the command
21615window has the focus. When another window is active, you must use
21616other readline key bindings such as @kbd{C-p}, @kbd{C-n}, @kbd{C-b}
21617and @kbd{C-f} to control the command window.
8e04817f 21618
7cf36c78
SC
21619@node TUI Single Key Mode
21620@section TUI Single Key Mode
21621@cindex TUI single key mode
21622
46ba6afa
BW
21623The TUI also provides a @dfn{SingleKey} mode, which binds several
21624frequently used @value{GDBN} commands to single keys. Type @kbd{C-x s} to
21625switch into this mode, where the following key bindings are used:
7cf36c78
SC
21626
21627@table @kbd
21628@kindex c @r{(SingleKey TUI key)}
21629@item c
21630continue
21631
21632@kindex d @r{(SingleKey TUI key)}
21633@item d
21634down
21635
21636@kindex f @r{(SingleKey TUI key)}
21637@item f
21638finish
21639
21640@kindex n @r{(SingleKey TUI key)}
21641@item n
21642next
21643
21644@kindex q @r{(SingleKey TUI key)}
21645@item q
46ba6afa 21646exit the SingleKey mode.
7cf36c78
SC
21647
21648@kindex r @r{(SingleKey TUI key)}
21649@item r
21650run
21651
21652@kindex s @r{(SingleKey TUI key)}
21653@item s
21654step
21655
21656@kindex u @r{(SingleKey TUI key)}
21657@item u
21658up
21659
21660@kindex v @r{(SingleKey TUI key)}
21661@item v
21662info locals
21663
21664@kindex w @r{(SingleKey TUI key)}
21665@item w
21666where
7cf36c78
SC
21667@end table
21668
21669Other keys temporarily switch to the @value{GDBN} command prompt.
21670The key that was pressed is inserted in the editing buffer so that
21671it is possible to type most @value{GDBN} commands without interaction
46ba6afa
BW
21672with the TUI SingleKey mode. Once the command is entered the TUI
21673SingleKey mode is restored. The only way to permanently leave
7f9087cb 21674this mode is by typing @kbd{q} or @kbd{C-x s}.
7cf36c78
SC
21675
21676
8e04817f 21677@node TUI Commands
db2e3e2e 21678@section TUI-specific Commands
8e04817f
AC
21679@cindex TUI commands
21680
21681The TUI has specific commands to control the text windows.
46ba6afa
BW
21682These commands are always available, even when @value{GDBN} is not in
21683the TUI mode. When @value{GDBN} is in the standard mode, most
21684of these commands will automatically switch to the TUI mode.
c906108c 21685
ff12863f
PA
21686Note that if @value{GDBN}'s @code{stdout} is not connected to a
21687terminal, or @value{GDBN} has been started with the machine interface
21688interpreter (@pxref{GDB/MI, ,The @sc{gdb/mi} Interface}), most of
21689these commands will fail with an error, because it would not be
21690possible or desirable to enable curses window management.
21691
c906108c 21692@table @code
3d757584
SC
21693@item info win
21694@kindex info win
21695List and give the size of all displayed windows.
21696
8e04817f 21697@item layout next
4644b6e3 21698@kindex layout
8e04817f 21699Display the next layout.
2df3850c 21700
8e04817f 21701@item layout prev
8e04817f 21702Display the previous layout.
c906108c 21703
8e04817f 21704@item layout src
8e04817f 21705Display the source window only.
c906108c 21706
8e04817f 21707@item layout asm
8e04817f 21708Display the assembly window only.
c906108c 21709
8e04817f 21710@item layout split
8e04817f 21711Display the source and assembly window.
c906108c 21712
8e04817f 21713@item layout regs
8e04817f
AC
21714Display the register window together with the source or assembly window.
21715
46ba6afa 21716@item focus next
8e04817f 21717@kindex focus
46ba6afa
BW
21718Make the next window active for scrolling.
21719
21720@item focus prev
21721Make the previous window active for scrolling.
21722
21723@item focus src
21724Make the source window active for scrolling.
21725
21726@item focus asm
21727Make the assembly window active for scrolling.
21728
21729@item focus regs
21730Make the register window active for scrolling.
21731
21732@item focus cmd
21733Make the command window active for scrolling.
c906108c 21734
8e04817f
AC
21735@item refresh
21736@kindex refresh
7f9087cb 21737Refresh the screen. This is similar to typing @kbd{C-L}.
c906108c 21738
6a1b180d
SC
21739@item tui reg float
21740@kindex tui reg
21741Show the floating point registers in the register window.
21742
21743@item tui reg general
21744Show the general registers in the register window.
21745
21746@item tui reg next
21747Show the next register group. The list of register groups as well as
21748their order is target specific. The predefined register groups are the
21749following: @code{general}, @code{float}, @code{system}, @code{vector},
21750@code{all}, @code{save}, @code{restore}.
21751
21752@item tui reg system
21753Show the system registers in the register window.
21754
8e04817f
AC
21755@item update
21756@kindex update
21757Update the source window and the current execution point.
c906108c 21758
8e04817f
AC
21759@item winheight @var{name} +@var{count}
21760@itemx winheight @var{name} -@var{count}
21761@kindex winheight
21762Change the height of the window @var{name} by @var{count}
21763lines. Positive counts increase the height, while negative counts
21764decrease it.
2df3850c 21765
46ba6afa
BW
21766@item tabset @var{nchars}
21767@kindex tabset
c45da7e6 21768Set the width of tab stops to be @var{nchars} characters.
c906108c
SS
21769@end table
21770
8e04817f 21771@node TUI Configuration
79a6e687 21772@section TUI Configuration Variables
8e04817f 21773@cindex TUI configuration variables
c906108c 21774
46ba6afa 21775Several configuration variables control the appearance of TUI windows.
c906108c 21776
8e04817f
AC
21777@table @code
21778@item set tui border-kind @var{kind}
21779@kindex set tui border-kind
21780Select the border appearance for the source, assembly and register windows.
21781The possible values are the following:
21782@table @code
21783@item space
21784Use a space character to draw the border.
c906108c 21785
8e04817f 21786@item ascii
46ba6afa 21787Use @sc{ascii} characters @samp{+}, @samp{-} and @samp{|} to draw the border.
c906108c 21788
8e04817f
AC
21789@item acs
21790Use the Alternate Character Set to draw the border. The border is
21791drawn using character line graphics if the terminal supports them.
8e04817f 21792@end table
c78b4128 21793
8e04817f
AC
21794@item set tui border-mode @var{mode}
21795@kindex set tui border-mode
46ba6afa
BW
21796@itemx set tui active-border-mode @var{mode}
21797@kindex set tui active-border-mode
21798Select the display attributes for the borders of the inactive windows
21799or the active window. The @var{mode} can be one of the following:
8e04817f
AC
21800@table @code
21801@item normal
21802Use normal attributes to display the border.
c906108c 21803
8e04817f
AC
21804@item standout
21805Use standout mode.
c906108c 21806
8e04817f
AC
21807@item reverse
21808Use reverse video mode.
c906108c 21809
8e04817f
AC
21810@item half
21811Use half bright mode.
c906108c 21812
8e04817f
AC
21813@item half-standout
21814Use half bright and standout mode.
c906108c 21815
8e04817f
AC
21816@item bold
21817Use extra bright or bold mode.
c78b4128 21818
8e04817f
AC
21819@item bold-standout
21820Use extra bright or bold and standout mode.
8e04817f 21821@end table
8e04817f 21822@end table
c78b4128 21823
8e04817f
AC
21824@node Emacs
21825@chapter Using @value{GDBN} under @sc{gnu} Emacs
c78b4128 21826
8e04817f
AC
21827@cindex Emacs
21828@cindex @sc{gnu} Emacs
21829A special interface allows you to use @sc{gnu} Emacs to view (and
21830edit) the source files for the program you are debugging with
21831@value{GDBN}.
c906108c 21832
8e04817f
AC
21833To use this interface, use the command @kbd{M-x gdb} in Emacs. Give the
21834executable file you want to debug as an argument. This command starts
21835@value{GDBN} as a subprocess of Emacs, with input and output through a newly
21836created Emacs buffer.
21837@c (Do not use the @code{-tui} option to run @value{GDBN} from Emacs.)
c906108c 21838
5e252a2e 21839Running @value{GDBN} under Emacs can be just like running @value{GDBN} normally except for two
8e04817f 21840things:
c906108c 21841
8e04817f
AC
21842@itemize @bullet
21843@item
5e252a2e
NR
21844All ``terminal'' input and output goes through an Emacs buffer, called
21845the GUD buffer.
c906108c 21846
8e04817f
AC
21847This applies both to @value{GDBN} commands and their output, and to the input
21848and output done by the program you are debugging.
bf0184be 21849
8e04817f
AC
21850This is useful because it means that you can copy the text of previous
21851commands and input them again; you can even use parts of the output
21852in this way.
bf0184be 21853
8e04817f
AC
21854All the facilities of Emacs' Shell mode are available for interacting
21855with your program. In particular, you can send signals the usual
21856way---for example, @kbd{C-c C-c} for an interrupt, @kbd{C-c C-z} for a
21857stop.
bf0184be
ND
21858
21859@item
8e04817f 21860@value{GDBN} displays source code through Emacs.
bf0184be 21861
8e04817f
AC
21862Each time @value{GDBN} displays a stack frame, Emacs automatically finds the
21863source file for that frame and puts an arrow (@samp{=>}) at the
21864left margin of the current line. Emacs uses a separate buffer for
21865source display, and splits the screen to show both your @value{GDBN} session
21866and the source.
bf0184be 21867
8e04817f
AC
21868Explicit @value{GDBN} @code{list} or search commands still produce output as
21869usual, but you probably have no reason to use them from Emacs.
5e252a2e
NR
21870@end itemize
21871
21872We call this @dfn{text command mode}. Emacs 22.1, and later, also uses
21873a graphical mode, enabled by default, which provides further buffers
21874that can control the execution and describe the state of your program.
21875@xref{GDB Graphical Interface,,, Emacs, The @sc{gnu} Emacs Manual}.
c906108c 21876
64fabec2
AC
21877If you specify an absolute file name when prompted for the @kbd{M-x
21878gdb} argument, then Emacs sets your current working directory to where
21879your program resides. If you only specify the file name, then Emacs
21880sets your current working directory to to the directory associated
21881with the previous buffer. In this case, @value{GDBN} may find your
21882program by searching your environment's @code{PATH} variable, but on
21883some operating systems it might not find the source. So, although the
21884@value{GDBN} input and output session proceeds normally, the auxiliary
21885buffer does not display the current source and line of execution.
21886
21887The initial working directory of @value{GDBN} is printed on the top
5e252a2e
NR
21888line of the GUD buffer and this serves as a default for the commands
21889that specify files for @value{GDBN} to operate on. @xref{Files,
21890,Commands to Specify Files}.
64fabec2
AC
21891
21892By default, @kbd{M-x gdb} calls the program called @file{gdb}. If you
21893need to call @value{GDBN} by a different name (for example, if you
21894keep several configurations around, with different names) you can
21895customize the Emacs variable @code{gud-gdb-command-name} to run the
21896one you want.
8e04817f 21897
5e252a2e 21898In the GUD buffer, you can use these special Emacs commands in
8e04817f 21899addition to the standard Shell mode commands:
c906108c 21900
8e04817f
AC
21901@table @kbd
21902@item C-h m
5e252a2e 21903Describe the features of Emacs' GUD Mode.
c906108c 21904
64fabec2 21905@item C-c C-s
8e04817f
AC
21906Execute to another source line, like the @value{GDBN} @code{step} command; also
21907update the display window to show the current file and location.
c906108c 21908
64fabec2 21909@item C-c C-n
8e04817f
AC
21910Execute to next source line in this function, skipping all function
21911calls, like the @value{GDBN} @code{next} command. Then update the display window
21912to show the current file and location.
c906108c 21913
64fabec2 21914@item C-c C-i
8e04817f
AC
21915Execute one instruction, like the @value{GDBN} @code{stepi} command; update
21916display window accordingly.
c906108c 21917
8e04817f
AC
21918@item C-c C-f
21919Execute until exit from the selected stack frame, like the @value{GDBN}
21920@code{finish} command.
c906108c 21921
64fabec2 21922@item C-c C-r
8e04817f
AC
21923Continue execution of your program, like the @value{GDBN} @code{continue}
21924command.
b433d00b 21925
64fabec2 21926@item C-c <
8e04817f
AC
21927Go up the number of frames indicated by the numeric argument
21928(@pxref{Arguments, , Numeric Arguments, Emacs, The @sc{gnu} Emacs Manual}),
21929like the @value{GDBN} @code{up} command.
b433d00b 21930
64fabec2 21931@item C-c >
8e04817f
AC
21932Go down the number of frames indicated by the numeric argument, like the
21933@value{GDBN} @code{down} command.
8e04817f 21934@end table
c906108c 21935
7f9087cb 21936In any source file, the Emacs command @kbd{C-x @key{SPC}} (@code{gud-break})
8e04817f 21937tells @value{GDBN} to set a breakpoint on the source line point is on.
c906108c 21938
5e252a2e
NR
21939In text command mode, if you type @kbd{M-x speedbar}, Emacs displays a
21940separate frame which shows a backtrace when the GUD buffer is current.
21941Move point to any frame in the stack and type @key{RET} to make it
21942become the current frame and display the associated source in the
21943source buffer. Alternatively, click @kbd{Mouse-2} to make the
21944selected frame become the current one. In graphical mode, the
21945speedbar displays watch expressions.
64fabec2 21946
8e04817f
AC
21947If you accidentally delete the source-display buffer, an easy way to get
21948it back is to type the command @code{f} in the @value{GDBN} buffer, to
21949request a frame display; when you run under Emacs, this recreates
21950the source buffer if necessary to show you the context of the current
21951frame.
c906108c 21952
8e04817f
AC
21953The source files displayed in Emacs are in ordinary Emacs buffers
21954which are visiting the source files in the usual way. You can edit
21955the files with these buffers if you wish; but keep in mind that @value{GDBN}
21956communicates with Emacs in terms of line numbers. If you add or
21957delete lines from the text, the line numbers that @value{GDBN} knows cease
21958to correspond properly with the code.
b383017d 21959
5e252a2e
NR
21960A more detailed description of Emacs' interaction with @value{GDBN} is
21961given in the Emacs manual (@pxref{Debuggers,,, Emacs, The @sc{gnu}
21962Emacs Manual}).
c906108c 21963
8e04817f
AC
21964@c The following dropped because Epoch is nonstandard. Reactivate
21965@c if/when v19 does something similar. ---doc@cygnus.com 19dec1990
21966@ignore
21967@kindex Emacs Epoch environment
21968@kindex Epoch
21969@kindex inspect
c906108c 21970
8e04817f
AC
21971Version 18 of @sc{gnu} Emacs has a built-in window system
21972called the @code{epoch}
21973environment. Users of this environment can use a new command,
21974@code{inspect} which performs identically to @code{print} except that
21975each value is printed in its own window.
21976@end ignore
c906108c 21977
922fbb7b
AC
21978
21979@node GDB/MI
21980@chapter The @sc{gdb/mi} Interface
21981
21982@unnumberedsec Function and Purpose
21983
21984@cindex @sc{gdb/mi}, its purpose
6b5e8c01
NR
21985@sc{gdb/mi} is a line based machine oriented text interface to
21986@value{GDBN} and is activated by specifying using the
21987@option{--interpreter} command line option (@pxref{Mode Options}). It
21988is specifically intended to support the development of systems which
21989use the debugger as just one small component of a larger system.
922fbb7b
AC
21990
21991This chapter is a specification of the @sc{gdb/mi} interface. It is written
21992in the form of a reference manual.
21993
21994Note that @sc{gdb/mi} is still under construction, so some of the
af6eff6f
NR
21995features described below are incomplete and subject to change
21996(@pxref{GDB/MI Development and Front Ends, , @sc{gdb/mi} Development and Front Ends}).
922fbb7b
AC
21997
21998@unnumberedsec Notation and Terminology
21999
22000@cindex notational conventions, for @sc{gdb/mi}
22001This chapter uses the following notation:
22002
22003@itemize @bullet
22004@item
22005@code{|} separates two alternatives.
22006
22007@item
22008@code{[ @var{something} ]} indicates that @var{something} is optional:
22009it may or may not be given.
22010
22011@item
22012@code{( @var{group} )*} means that @var{group} inside the parentheses
22013may repeat zero or more times.
22014
22015@item
22016@code{( @var{group} )+} means that @var{group} inside the parentheses
22017may repeat one or more times.
22018
22019@item
22020@code{"@var{string}"} means a literal @var{string}.
22021@end itemize
22022
22023@ignore
22024@heading Dependencies
22025@end ignore
22026
922fbb7b 22027@menu
c3b108f7 22028* GDB/MI General Design::
922fbb7b
AC
22029* GDB/MI Command Syntax::
22030* GDB/MI Compatibility with CLI::
af6eff6f 22031* GDB/MI Development and Front Ends::
922fbb7b 22032* GDB/MI Output Records::
ef21caaf 22033* GDB/MI Simple Examples::
922fbb7b 22034* GDB/MI Command Description Format::
ef21caaf 22035* GDB/MI Breakpoint Commands::
a2c02241
NR
22036* GDB/MI Program Context::
22037* GDB/MI Thread Commands::
22038* GDB/MI Program Execution::
22039* GDB/MI Stack Manipulation::
22040* GDB/MI Variable Objects::
922fbb7b 22041* GDB/MI Data Manipulation::
a2c02241
NR
22042* GDB/MI Tracepoint Commands::
22043* GDB/MI Symbol Query::
351ff01a 22044* GDB/MI File Commands::
922fbb7b
AC
22045@ignore
22046* GDB/MI Kod Commands::
22047* GDB/MI Memory Overlay Commands::
22048* GDB/MI Signal Handling Commands::
22049@end ignore
922fbb7b 22050* GDB/MI Target Manipulation::
a6b151f1 22051* GDB/MI File Transfer Commands::
ef21caaf 22052* GDB/MI Miscellaneous Commands::
922fbb7b
AC
22053@end menu
22054
c3b108f7
VP
22055@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
22056@node GDB/MI General Design
22057@section @sc{gdb/mi} General Design
22058@cindex GDB/MI General Design
22059
22060Interaction of a @sc{GDB/MI} frontend with @value{GDBN} involves three
22061parts---commands sent to @value{GDBN}, responses to those commands
22062and notifications. Each command results in exactly one response,
22063indicating either successful completion of the command, or an error.
22064For the commands that do not resume the target, the response contains the
22065requested information. For the commands that resume the target, the
22066response only indicates whether the target was successfully resumed.
22067Notifications is the mechanism for reporting changes in the state of the
22068target, or in @value{GDBN} state, that cannot conveniently be associated with
22069a command and reported as part of that command response.
22070
22071The important examples of notifications are:
22072@itemize @bullet
22073
22074@item
22075Exec notifications. These are used to report changes in
22076target state---when a target is resumed, or stopped. It would not
22077be feasible to include this information in response of resuming
22078commands, because one resume commands can result in multiple events in
22079different threads. Also, quite some time may pass before any event
22080happens in the target, while a frontend needs to know whether the resuming
22081command itself was successfully executed.
22082
22083@item
22084Console output, and status notifications. Console output
22085notifications are used to report output of CLI commands, as well as
22086diagnostics for other commands. Status notifications are used to
22087report the progress of a long-running operation. Naturally, including
22088this information in command response would mean no output is produced
22089until the command is finished, which is undesirable.
22090
22091@item
22092General notifications. Commands may have various side effects on
22093the @value{GDBN} or target state beyond their official purpose. For example,
22094a command may change the selected thread. Although such changes can
22095be included in command response, using notification allows for more
22096orthogonal frontend design.
22097
22098@end itemize
22099
22100There's no guarantee that whenever an MI command reports an error,
22101@value{GDBN} or the target are in any specific state, and especially,
22102the state is not reverted to the state before the MI command was
22103processed. Therefore, whenever an MI command results in an error,
22104we recommend that the frontend refreshes all the information shown in
22105the user interface.
22106
508094de
NR
22107
22108@menu
22109* Context management::
22110* Asynchronous and non-stop modes::
22111* Thread groups::
22112@end menu
22113
22114@node Context management
c3b108f7
VP
22115@subsection Context management
22116
22117In most cases when @value{GDBN} accesses the target, this access is
22118done in context of a specific thread and frame (@pxref{Frames}).
22119Often, even when accessing global data, the target requires that a thread
22120be specified. The CLI interface maintains the selected thread and frame,
22121and supplies them to target on each command. This is convenient,
22122because a command line user would not want to specify that information
22123explicitly on each command, and because user interacts with
22124@value{GDBN} via a single terminal, so no confusion is possible as
22125to what thread and frame are the current ones.
22126
22127In the case of MI, the concept of selected thread and frame is less
22128useful. First, a frontend can easily remember this information
22129itself. Second, a graphical frontend can have more than one window,
22130each one used for debugging a different thread, and the frontend might
22131want to access additional threads for internal purposes. This
22132increases the risk that by relying on implicitly selected thread, the
22133frontend may be operating on a wrong one. Therefore, each MI command
22134should explicitly specify which thread and frame to operate on. To
22135make it possible, each MI command accepts the @samp{--thread} and
22136@samp{--frame} options, the value to each is @value{GDBN} identifier
22137for thread and frame to operate on.
22138
22139Usually, each top-level window in a frontend allows the user to select
22140a thread and a frame, and remembers the user selection for further
22141operations. However, in some cases @value{GDBN} may suggest that the
22142current thread be changed. For example, when stopping on a breakpoint
22143it is reasonable to switch to the thread where breakpoint is hit. For
22144another example, if the user issues the CLI @samp{thread} command via
22145the frontend, it is desirable to change the frontend's selected thread to the
22146one specified by user. @value{GDBN} communicates the suggestion to
22147change current thread using the @samp{=thread-selected} notification.
22148No such notification is available for the selected frame at the moment.
22149
22150Note that historically, MI shares the selected thread with CLI, so
22151frontends used the @code{-thread-select} to execute commands in the
22152right context. However, getting this to work right is cumbersome. The
22153simplest way is for frontend to emit @code{-thread-select} command
22154before every command. This doubles the number of commands that need
22155to be sent. The alternative approach is to suppress @code{-thread-select}
22156if the selected thread in @value{GDBN} is supposed to be identical to the
22157thread the frontend wants to operate on. However, getting this
22158optimization right can be tricky. In particular, if the frontend
22159sends several commands to @value{GDBN}, and one of the commands changes the
22160selected thread, then the behaviour of subsequent commands will
22161change. So, a frontend should either wait for response from such
22162problematic commands, or explicitly add @code{-thread-select} for
22163all subsequent commands. No frontend is known to do this exactly
22164right, so it is suggested to just always pass the @samp{--thread} and
22165@samp{--frame} options.
22166
508094de 22167@node Asynchronous and non-stop modes
c3b108f7
VP
22168@subsection Asynchronous command execution and non-stop mode
22169
22170On some targets, @value{GDBN} is capable of processing MI commands
22171even while the target is running. This is called @dfn{asynchronous
22172command execution} (@pxref{Background Execution}). The frontend may
22173specify a preferrence for asynchronous execution using the
22174@code{-gdb-set target-async 1} command, which should be emitted before
22175either running the executable or attaching to the target. After the
22176frontend has started the executable or attached to the target, it can
22177find if asynchronous execution is enabled using the
22178@code{-list-target-features} command.
22179
22180Even if @value{GDBN} can accept a command while target is running,
22181many commands that access the target do not work when the target is
22182running. Therefore, asynchronous command execution is most useful
22183when combined with non-stop mode (@pxref{Non-Stop Mode}). Then,
22184it is possible to examine the state of one thread, while other threads
22185are running.
22186
22187When a given thread is running, MI commands that try to access the
22188target in the context of that thread may not work, or may work only on
22189some targets. In particular, commands that try to operate on thread's
22190stack will not work, on any target. Commands that read memory, or
22191modify breakpoints, may work or not work, depending on the target. Note
22192that even commands that operate on global state, such as @code{print},
22193@code{set}, and breakpoint commands, still access the target in the
22194context of a specific thread, so frontend should try to find a
22195stopped thread and perform the operation on that thread (using the
22196@samp{--thread} option).
22197
22198Which commands will work in the context of a running thread is
22199highly target dependent. However, the two commands
22200@code{-exec-interrupt}, to stop a thread, and @code{-thread-info},
22201to find the state of a thread, will always work.
22202
508094de 22203@node Thread groups
c3b108f7
VP
22204@subsection Thread groups
22205@value{GDBN} may be used to debug several processes at the same time.
22206On some platfroms, @value{GDBN} may support debugging of several
22207hardware systems, each one having several cores with several different
22208processes running on each core. This section describes the MI
22209mechanism to support such debugging scenarios.
22210
22211The key observation is that regardless of the structure of the
22212target, MI can have a global list of threads, because most commands that
22213accept the @samp{--thread} option do not need to know what process that
22214thread belongs to. Therefore, it is not necessary to introduce
22215neither additional @samp{--process} option, nor an notion of the
22216current process in the MI interface. The only strictly new feature
22217that is required is the ability to find how the threads are grouped
22218into processes.
22219
22220To allow the user to discover such grouping, and to support arbitrary
22221hierarchy of machines/cores/processes, MI introduces the concept of a
22222@dfn{thread group}. Thread group is a collection of threads and other
22223thread groups. A thread group always has a string identifier, a type,
22224and may have additional attributes specific to the type. A new
22225command, @code{-list-thread-groups}, returns the list of top-level
22226thread groups, which correspond to processes that @value{GDBN} is
22227debugging at the moment. By passing an identifier of a thread group
22228to the @code{-list-thread-groups} command, it is possible to obtain
22229the members of specific thread group.
22230
22231To allow the user to easily discover processes, and other objects, he
22232wishes to debug, a concept of @dfn{available thread group} is
22233introduced. Available thread group is an thread group that
22234@value{GDBN} is not debugging, but that can be attached to, using the
22235@code{-target-attach} command. The list of available top-level thread
22236groups can be obtained using @samp{-list-thread-groups --available}.
22237In general, the content of a thread group may be only retrieved only
22238after attaching to that thread group.
22239
a79b8f6e
VP
22240Thread groups are related to inferiors (@pxref{Inferiors and
22241Programs}). Each inferior corresponds to a thread group of a special
22242type @samp{process}, and some additional operations are permitted on
22243such thread groups.
22244
922fbb7b
AC
22245@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
22246@node GDB/MI Command Syntax
22247@section @sc{gdb/mi} Command Syntax
22248
22249@menu
22250* GDB/MI Input Syntax::
22251* GDB/MI Output Syntax::
922fbb7b
AC
22252@end menu
22253
22254@node GDB/MI Input Syntax
22255@subsection @sc{gdb/mi} Input Syntax
22256
22257@cindex input syntax for @sc{gdb/mi}
22258@cindex @sc{gdb/mi}, input syntax
22259@table @code
22260@item @var{command} @expansion{}
22261@code{@var{cli-command} | @var{mi-command}}
22262
22263@item @var{cli-command} @expansion{}
22264@code{[ @var{token} ] @var{cli-command} @var{nl}}, where
22265@var{cli-command} is any existing @value{GDBN} CLI command.
22266
22267@item @var{mi-command} @expansion{}
22268@code{[ @var{token} ] "-" @var{operation} ( " " @var{option} )*
22269@code{[} " --" @code{]} ( " " @var{parameter} )* @var{nl}}
22270
22271@item @var{token} @expansion{}
22272"any sequence of digits"
22273
22274@item @var{option} @expansion{}
22275@code{"-" @var{parameter} [ " " @var{parameter} ]}
22276
22277@item @var{parameter} @expansion{}
22278@code{@var{non-blank-sequence} | @var{c-string}}
22279
22280@item @var{operation} @expansion{}
22281@emph{any of the operations described in this chapter}
22282
22283@item @var{non-blank-sequence} @expansion{}
22284@emph{anything, provided it doesn't contain special characters such as
22285"-", @var{nl}, """ and of course " "}
22286
22287@item @var{c-string} @expansion{}
22288@code{""" @var{seven-bit-iso-c-string-content} """}
22289
22290@item @var{nl} @expansion{}
22291@code{CR | CR-LF}
22292@end table
22293
22294@noindent
22295Notes:
22296
22297@itemize @bullet
22298@item
22299The CLI commands are still handled by the @sc{mi} interpreter; their
22300output is described below.
22301
22302@item
22303The @code{@var{token}}, when present, is passed back when the command
22304finishes.
22305
22306@item
22307Some @sc{mi} commands accept optional arguments as part of the parameter
22308list. Each option is identified by a leading @samp{-} (dash) and may be
22309followed by an optional argument parameter. Options occur first in the
22310parameter list and can be delimited from normal parameters using
22311@samp{--} (this is useful when some parameters begin with a dash).
22312@end itemize
22313
22314Pragmatics:
22315
22316@itemize @bullet
22317@item
22318We want easy access to the existing CLI syntax (for debugging).
22319
22320@item
22321We want it to be easy to spot a @sc{mi} operation.
22322@end itemize
22323
22324@node GDB/MI Output Syntax
22325@subsection @sc{gdb/mi} Output Syntax
22326
22327@cindex output syntax of @sc{gdb/mi}
22328@cindex @sc{gdb/mi}, output syntax
22329The output from @sc{gdb/mi} consists of zero or more out-of-band records
22330followed, optionally, by a single result record. This result record
22331is for the most recent command. The sequence of output records is
594fe323 22332terminated by @samp{(gdb)}.
922fbb7b
AC
22333
22334If an input command was prefixed with a @code{@var{token}} then the
22335corresponding output for that command will also be prefixed by that same
22336@var{token}.
22337
22338@table @code
22339@item @var{output} @expansion{}
594fe323 22340@code{( @var{out-of-band-record} )* [ @var{result-record} ] "(gdb)" @var{nl}}
922fbb7b
AC
22341
22342@item @var{result-record} @expansion{}
22343@code{ [ @var{token} ] "^" @var{result-class} ( "," @var{result} )* @var{nl}}
22344
22345@item @var{out-of-band-record} @expansion{}
22346@code{@var{async-record} | @var{stream-record}}
22347
22348@item @var{async-record} @expansion{}
22349@code{@var{exec-async-output} | @var{status-async-output} | @var{notify-async-output}}
22350
22351@item @var{exec-async-output} @expansion{}
22352@code{[ @var{token} ] "*" @var{async-output}}
22353
22354@item @var{status-async-output} @expansion{}
22355@code{[ @var{token} ] "+" @var{async-output}}
22356
22357@item @var{notify-async-output} @expansion{}
22358@code{[ @var{token} ] "=" @var{async-output}}
22359
22360@item @var{async-output} @expansion{}
22361@code{@var{async-class} ( "," @var{result} )* @var{nl}}
22362
22363@item @var{result-class} @expansion{}
22364@code{"done" | "running" | "connected" | "error" | "exit"}
22365
22366@item @var{async-class} @expansion{}
22367@code{"stopped" | @var{others}} (where @var{others} will be added
22368depending on the needs---this is still in development).
22369
22370@item @var{result} @expansion{}
22371@code{ @var{variable} "=" @var{value}}
22372
22373@item @var{variable} @expansion{}
22374@code{ @var{string} }
22375
22376@item @var{value} @expansion{}
22377@code{ @var{const} | @var{tuple} | @var{list} }
22378
22379@item @var{const} @expansion{}
22380@code{@var{c-string}}
22381
22382@item @var{tuple} @expansion{}
22383@code{ "@{@}" | "@{" @var{result} ( "," @var{result} )* "@}" }
22384
22385@item @var{list} @expansion{}
22386@code{ "[]" | "[" @var{value} ( "," @var{value} )* "]" | "["
22387@var{result} ( "," @var{result} )* "]" }
22388
22389@item @var{stream-record} @expansion{}
22390@code{@var{console-stream-output} | @var{target-stream-output} | @var{log-stream-output}}
22391
22392@item @var{console-stream-output} @expansion{}
22393@code{"~" @var{c-string}}
22394
22395@item @var{target-stream-output} @expansion{}
22396@code{"@@" @var{c-string}}
22397
22398@item @var{log-stream-output} @expansion{}
22399@code{"&" @var{c-string}}
22400
22401@item @var{nl} @expansion{}
22402@code{CR | CR-LF}
22403
22404@item @var{token} @expansion{}
22405@emph{any sequence of digits}.
22406@end table
22407
22408@noindent
22409Notes:
22410
22411@itemize @bullet
22412@item
22413All output sequences end in a single line containing a period.
22414
22415@item
721c02de
VP
22416The @code{@var{token}} is from the corresponding request. Note that
22417for all async output, while the token is allowed by the grammar and
22418may be output by future versions of @value{GDBN} for select async
22419output messages, it is generally omitted. Frontends should treat
22420all async output as reporting general changes in the state of the
22421target and there should be no need to associate async output to any
22422prior command.
922fbb7b
AC
22423
22424@item
22425@cindex status output in @sc{gdb/mi}
22426@var{status-async-output} contains on-going status information about the
22427progress of a slow operation. It can be discarded. All status output is
22428prefixed by @samp{+}.
22429
22430@item
22431@cindex async output in @sc{gdb/mi}
22432@var{exec-async-output} contains asynchronous state change on the target
22433(stopped, started, disappeared). All async output is prefixed by
22434@samp{*}.
22435
22436@item
22437@cindex notify output in @sc{gdb/mi}
22438@var{notify-async-output} contains supplementary information that the
22439client should handle (e.g., a new breakpoint information). All notify
22440output is prefixed by @samp{=}.
22441
22442@item
22443@cindex console output in @sc{gdb/mi}
22444@var{console-stream-output} is output that should be displayed as is in the
22445console. It is the textual response to a CLI command. All the console
22446output is prefixed by @samp{~}.
22447
22448@item
22449@cindex target output in @sc{gdb/mi}
22450@var{target-stream-output} is the output produced by the target program.
22451All the target output is prefixed by @samp{@@}.
22452
22453@item
22454@cindex log output in @sc{gdb/mi}
22455@var{log-stream-output} is output text coming from @value{GDBN}'s internals, for
22456instance messages that should be displayed as part of an error log. All
22457the log output is prefixed by @samp{&}.
22458
22459@item
22460@cindex list output in @sc{gdb/mi}
22461New @sc{gdb/mi} commands should only output @var{lists} containing
22462@var{values}.
22463
22464
22465@end itemize
22466
22467@xref{GDB/MI Stream Records, , @sc{gdb/mi} Stream Records}, for more
22468details about the various output records.
22469
922fbb7b
AC
22470@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
22471@node GDB/MI Compatibility with CLI
22472@section @sc{gdb/mi} Compatibility with CLI
22473
22474@cindex compatibility, @sc{gdb/mi} and CLI
22475@cindex @sc{gdb/mi}, compatibility with CLI
922fbb7b 22476
a2c02241
NR
22477For the developers convenience CLI commands can be entered directly,
22478but there may be some unexpected behaviour. For example, commands
22479that query the user will behave as if the user replied yes, breakpoint
22480command lists are not executed and some CLI commands, such as
22481@code{if}, @code{when} and @code{define}, prompt for further input with
22482@samp{>}, which is not valid MI output.
ef21caaf
NR
22483
22484This feature may be removed at some stage in the future and it is
a2c02241
NR
22485recommended that front ends use the @code{-interpreter-exec} command
22486(@pxref{-interpreter-exec}).
922fbb7b 22487
af6eff6f
NR
22488@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
22489@node GDB/MI Development and Front Ends
22490@section @sc{gdb/mi} Development and Front Ends
22491@cindex @sc{gdb/mi} development
22492
22493The application which takes the MI output and presents the state of the
22494program being debugged to the user is called a @dfn{front end}.
22495
22496Although @sc{gdb/mi} is still incomplete, it is currently being used
22497by a variety of front ends to @value{GDBN}. This makes it difficult
22498to introduce new functionality without breaking existing usage. This
22499section tries to minimize the problems by describing how the protocol
22500might change.
22501
22502Some changes in MI need not break a carefully designed front end, and
22503for these the MI version will remain unchanged. The following is a
22504list of changes that may occur within one level, so front ends should
22505parse MI output in a way that can handle them:
22506
22507@itemize @bullet
22508@item
22509New MI commands may be added.
22510
22511@item
22512New fields may be added to the output of any MI command.
22513
36ece8b3
NR
22514@item
22515The range of values for fields with specified values, e.g.,
9f708cb2 22516@code{in_scope} (@pxref{-var-update}) may be extended.
36ece8b3 22517
af6eff6f
NR
22518@c The format of field's content e.g type prefix, may change so parse it
22519@c at your own risk. Yes, in general?
22520
22521@c The order of fields may change? Shouldn't really matter but it might
22522@c resolve inconsistencies.
22523@end itemize
22524
22525If the changes are likely to break front ends, the MI version level
22526will be increased by one. This will allow the front end to parse the
22527output according to the MI version. Apart from mi0, new versions of
22528@value{GDBN} will not support old versions of MI and it will be the
22529responsibility of the front end to work with the new one.
22530
22531@c Starting with mi3, add a new command -mi-version that prints the MI
22532@c version?
22533
22534The best way to avoid unexpected changes in MI that might break your front
22535end is to make your project known to @value{GDBN} developers and
7a9a6b69 22536follow development on @email{gdb@@sourceware.org} and
fa0f268d 22537@email{gdb-patches@@sourceware.org}.
af6eff6f
NR
22538@cindex mailing lists
22539
922fbb7b
AC
22540@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
22541@node GDB/MI Output Records
22542@section @sc{gdb/mi} Output Records
22543
22544@menu
22545* GDB/MI Result Records::
22546* GDB/MI Stream Records::
82f68b1c 22547* GDB/MI Async Records::
c3b108f7 22548* GDB/MI Frame Information::
dc146f7c 22549* GDB/MI Thread Information::
922fbb7b
AC
22550@end menu
22551
22552@node GDB/MI Result Records
22553@subsection @sc{gdb/mi} Result Records
22554
22555@cindex result records in @sc{gdb/mi}
22556@cindex @sc{gdb/mi}, result records
22557In addition to a number of out-of-band notifications, the response to a
22558@sc{gdb/mi} command includes one of the following result indications:
22559
22560@table @code
22561@findex ^done
22562@item "^done" [ "," @var{results} ]
22563The synchronous operation was successful, @code{@var{results}} are the return
22564values.
22565
22566@item "^running"
22567@findex ^running
8e9c5e02
VP
22568This result record is equivalent to @samp{^done}. Historically, it
22569was output instead of @samp{^done} if the command has resumed the
22570target. This behaviour is maintained for backward compatibility, but
22571all frontends should treat @samp{^done} and @samp{^running}
22572identically and rely on the @samp{*running} output record to determine
22573which threads are resumed.
922fbb7b 22574
ef21caaf
NR
22575@item "^connected"
22576@findex ^connected
3f94c067 22577@value{GDBN} has connected to a remote target.
ef21caaf 22578
922fbb7b
AC
22579@item "^error" "," @var{c-string}
22580@findex ^error
22581The operation failed. The @code{@var{c-string}} contains the corresponding
22582error message.
ef21caaf
NR
22583
22584@item "^exit"
22585@findex ^exit
3f94c067 22586@value{GDBN} has terminated.
ef21caaf 22587
922fbb7b
AC
22588@end table
22589
22590@node GDB/MI Stream Records
22591@subsection @sc{gdb/mi} Stream Records
22592
22593@cindex @sc{gdb/mi}, stream records
22594@cindex stream records in @sc{gdb/mi}
22595@value{GDBN} internally maintains a number of output streams: the console, the
22596target, and the log. The output intended for each of these streams is
22597funneled through the @sc{gdb/mi} interface using @dfn{stream records}.
22598
22599Each stream record begins with a unique @dfn{prefix character} which
22600identifies its stream (@pxref{GDB/MI Output Syntax, , @sc{gdb/mi} Output
22601Syntax}). In addition to the prefix, each stream record contains a
22602@code{@var{string-output}}. This is either raw text (with an implicit new
22603line) or a quoted C string (which does not contain an implicit newline).
22604
22605@table @code
22606@item "~" @var{string-output}
22607The console output stream contains text that should be displayed in the
22608CLI console window. It contains the textual responses to CLI commands.
22609
22610@item "@@" @var{string-output}
22611The target output stream contains any textual output from the running
ef21caaf
NR
22612target. This is only present when GDB's event loop is truly
22613asynchronous, which is currently only the case for remote targets.
922fbb7b
AC
22614
22615@item "&" @var{string-output}
22616The log stream contains debugging messages being produced by @value{GDBN}'s
22617internals.
22618@end table
22619
82f68b1c
VP
22620@node GDB/MI Async Records
22621@subsection @sc{gdb/mi} Async Records
922fbb7b 22622
82f68b1c
VP
22623@cindex async records in @sc{gdb/mi}
22624@cindex @sc{gdb/mi}, async records
22625@dfn{Async} records are used to notify the @sc{gdb/mi} client of
922fbb7b 22626additional changes that have occurred. Those changes can either be a
82f68b1c 22627consequence of @sc{gdb/mi} commands (e.g., a breakpoint modified) or a result of
922fbb7b
AC
22628target activity (e.g., target stopped).
22629
8eb41542 22630The following is the list of possible async records:
922fbb7b
AC
22631
22632@table @code
034dad6f 22633
e1ac3328
VP
22634@item *running,thread-id="@var{thread}"
22635The target is now running. The @var{thread} field tells which
22636specific thread is now running, and can be @samp{all} if all threads
22637are running. The frontend should assume that no interaction with a
22638running thread is possible after this notification is produced.
22639The frontend should not assume that this notification is output
22640only once for any command. @value{GDBN} may emit this notification
22641several times, either for different threads, because it cannot resume
22642all threads together, or even for a single thread, if the thread must
22643be stepped though some code before letting it run freely.
22644
dc146f7c 22645@item *stopped,reason="@var{reason}",thread-id="@var{id}",stopped-threads="@var{stopped}",core="@var{core}"
82f68b1c
VP
22646The target has stopped. The @var{reason} field can have one of the
22647following values:
034dad6f
BR
22648
22649@table @code
22650@item breakpoint-hit
22651A breakpoint was reached.
22652@item watchpoint-trigger
22653A watchpoint was triggered.
22654@item read-watchpoint-trigger
22655A read watchpoint was triggered.
22656@item access-watchpoint-trigger
22657An access watchpoint was triggered.
22658@item function-finished
22659An -exec-finish or similar CLI command was accomplished.
22660@item location-reached
22661An -exec-until or similar CLI command was accomplished.
22662@item watchpoint-scope
22663A watchpoint has gone out of scope.
22664@item end-stepping-range
22665An -exec-next, -exec-next-instruction, -exec-step, -exec-step-instruction or
22666similar CLI command was accomplished.
22667@item exited-signalled
22668The inferior exited because of a signal.
22669@item exited
22670The inferior exited.
22671@item exited-normally
22672The inferior exited normally.
22673@item signal-received
22674A signal was received by the inferior.
922fbb7b
AC
22675@end table
22676
c3b108f7
VP
22677The @var{id} field identifies the thread that directly caused the stop
22678-- for example by hitting a breakpoint. Depending on whether all-stop
22679mode is in effect (@pxref{All-Stop Mode}), @value{GDBN} may either
22680stop all threads, or only the thread that directly triggered the stop.
22681If all threads are stopped, the @var{stopped} field will have the
22682value of @code{"all"}. Otherwise, the value of the @var{stopped}
22683field will be a list of thread identifiers. Presently, this list will
22684always include a single thread, but frontend should be prepared to see
dc146f7c
VP
22685several threads in the list. The @var{core} field reports the
22686processor core on which the stop event has happened. This field may be absent
22687if such information is not available.
c3b108f7 22688
a79b8f6e
VP
22689@item =thread-group-added,id="@var{id}"
22690@itemx =thread-group-removed,id="@var{id}"
22691A thread group was either added or removed. The @var{id} field
22692contains the @value{GDBN} identifier of the thread group. When a thread
22693group is added, it generally might not be associated with a running
22694process. When a thread group is removed, its id becomes invalid and
22695cannot be used in any way.
22696
22697@item =thread-group-started,id="@var{id}",pid="@var{pid}"
22698A thread group became associated with a running program,
22699either because the program was just started or the thread group
22700was attached to a program. The @var{id} field contains the
22701@value{GDBN} identifier of the thread group. The @var{pid} field
22702contains process identifier, specific to the operating system.
22703
c3b108f7 22704@itemx =thread-group-exited,id="@var{id}"
a79b8f6e
VP
22705A thread group is no longer associated with a running program,
22706either because the program has exited, or because it was detached
c3b108f7
VP
22707from. The @var{id} field contains the @value{GDBN} identifier of the
22708thread group.
22709
22710@item =thread-created,id="@var{id}",group-id="@var{gid}"
22711@itemx =thread-exited,id="@var{id}",group-id="@var{gid}"
82f68b1c 22712A thread either was created, or has exited. The @var{id} field
c3b108f7
VP
22713contains the @value{GDBN} identifier of the thread. The @var{gid}
22714field identifies the thread group this thread belongs to.
66bb093b
VP
22715
22716@item =thread-selected,id="@var{id}"
22717Informs that the selected thread was changed as result of the last
22718command. This notification is not emitted as result of @code{-thread-select}
22719command but is emitted whenever an MI command that is not documented
22720to change the selected thread actually changes it. In particular,
22721invoking, directly or indirectly (via user-defined command), the CLI
22722@code{thread} command, will generate this notification.
22723
22724We suggest that in response to this notification, front ends
22725highlight the selected thread and cause subsequent commands to apply to
22726that thread.
22727
c86cf029
VP
22728@item =library-loaded,...
22729Reports that a new library file was loaded by the program. This
22730notification has 4 fields---@var{id}, @var{target-name},
134eb42c 22731@var{host-name}, and @var{symbols-loaded}. The @var{id} field is an
c86cf029
VP
22732opaque identifier of the library. For remote debugging case,
22733@var{target-name} and @var{host-name} fields give the name of the
134eb42c
VP
22734library file on the target, and on the host respectively. For native
22735debugging, both those fields have the same value. The
c86cf029 22736@var{symbols-loaded} field reports if the debug symbols for this
a79b8f6e
VP
22737library are loaded. The @var{thread-group} field, if present,
22738specifies the id of the thread group in whose context the library was loaded.
22739If the field is absent, it means the library was loaded in the context
22740of all present thread groups.
c86cf029
VP
22741
22742@item =library-unloaded,...
134eb42c 22743Reports that a library was unloaded by the program. This notification
c86cf029 22744has 3 fields---@var{id}, @var{target-name} and @var{host-name} with
a79b8f6e
VP
22745the same meaning as for the @code{=library-loaded} notification.
22746The @var{thread-group} field, if present, specifies the id of the
22747thread group in whose context the library was unloaded. If the field is
22748absent, it means the library was unloaded in the context of all present
22749thread groups.
c86cf029 22750
82f68b1c
VP
22751@end table
22752
c3b108f7
VP
22753@node GDB/MI Frame Information
22754@subsection @sc{gdb/mi} Frame Information
22755
22756Response from many MI commands includes an information about stack
22757frame. This information is a tuple that may have the following
22758fields:
22759
22760@table @code
22761@item level
22762The level of the stack frame. The innermost frame has the level of
22763zero. This field is always present.
22764
22765@item func
22766The name of the function corresponding to the frame. This field may
22767be absent if @value{GDBN} is unable to determine the function name.
22768
22769@item addr
22770The code address for the frame. This field is always present.
22771
22772@item file
22773The name of the source files that correspond to the frame's code
22774address. This field may be absent.
22775
22776@item line
22777The source line corresponding to the frames' code address. This field
22778may be absent.
22779
22780@item from
22781The name of the binary file (either executable or shared library) the
22782corresponds to the frame's code address. This field may be absent.
22783
22784@end table
82f68b1c 22785
dc146f7c
VP
22786@node GDB/MI Thread Information
22787@subsection @sc{gdb/mi} Thread Information
22788
22789Whenever @value{GDBN} has to report an information about a thread, it
22790uses a tuple with the following fields:
22791
22792@table @code
22793@item id
22794The numeric id assigned to the thread by @value{GDBN}. This field is
22795always present.
22796
22797@item target-id
22798Target-specific string identifying the thread. This field is always present.
22799
22800@item details
22801Additional information about the thread provided by the target.
22802It is supposed to be human-readable and not interpreted by the
22803frontend. This field is optional.
22804
22805@item state
22806Either @samp{stopped} or @samp{running}, depending on whether the
22807thread is presently running. This field is always present.
22808
22809@item core
22810The value of this field is an integer number of the processor core the
22811thread was last seen on. This field is optional.
22812@end table
22813
922fbb7b 22814
ef21caaf
NR
22815@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
22816@node GDB/MI Simple Examples
22817@section Simple Examples of @sc{gdb/mi} Interaction
22818@cindex @sc{gdb/mi}, simple examples
22819
22820This subsection presents several simple examples of interaction using
22821the @sc{gdb/mi} interface. In these examples, @samp{->} means that the
22822following line is passed to @sc{gdb/mi} as input, while @samp{<-} means
22823the output received from @sc{gdb/mi}.
22824
d3e8051b 22825Note the line breaks shown in the examples are here only for
ef21caaf
NR
22826readability, they don't appear in the real output.
22827
79a6e687 22828@subheading Setting a Breakpoint
ef21caaf
NR
22829
22830Setting a breakpoint generates synchronous output which contains detailed
22831information of the breakpoint.
22832
22833@smallexample
22834-> -break-insert main
22835<- ^done,bkpt=@{number="1",type="breakpoint",disp="keep",
22836 enabled="y",addr="0x08048564",func="main",file="myprog.c",
22837 fullname="/home/nickrob/myprog.c",line="68",times="0"@}
22838<- (gdb)
22839@end smallexample
22840
22841@subheading Program Execution
22842
22843Program execution generates asynchronous records and MI gives the
22844reason that execution stopped.
22845
22846@smallexample
22847-> -exec-run
22848<- ^running
22849<- (gdb)
a47ec5fe 22850<- *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",thread-id="0",
ef21caaf
NR
22851 frame=@{addr="0x08048564",func="main",
22852 args=[@{name="argc",value="1"@},@{name="argv",value="0xbfc4d4d4"@}],
22853 file="myprog.c",fullname="/home/nickrob/myprog.c",line="68"@}
22854<- (gdb)
22855-> -exec-continue
22856<- ^running
22857<- (gdb)
22858<- *stopped,reason="exited-normally"
22859<- (gdb)
22860@end smallexample
22861
3f94c067 22862@subheading Quitting @value{GDBN}
ef21caaf 22863
3f94c067 22864Quitting @value{GDBN} just prints the result class @samp{^exit}.
ef21caaf
NR
22865
22866@smallexample
22867-> (gdb)
22868<- -gdb-exit
22869<- ^exit
22870@end smallexample
22871
a6b29f87
VP
22872Please note that @samp{^exit} is printed immediately, but it might
22873take some time for @value{GDBN} to actually exit. During that time, @value{GDBN}
22874performs necessary cleanups, including killing programs being debugged
22875or disconnecting from debug hardware, so the frontend should wait till
22876@value{GDBN} exits and should only forcibly kill @value{GDBN} if it
22877fails to exit in reasonable time.
22878
a2c02241 22879@subheading A Bad Command
ef21caaf
NR
22880
22881Here's what happens if you pass a non-existent command:
22882
22883@smallexample
22884-> -rubbish
22885<- ^error,msg="Undefined MI command: rubbish"
594fe323 22886<- (gdb)
ef21caaf
NR
22887@end smallexample
22888
22889
922fbb7b
AC
22890@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
22891@node GDB/MI Command Description Format
22892@section @sc{gdb/mi} Command Description Format
22893
22894The remaining sections describe blocks of commands. Each block of
22895commands is laid out in a fashion similar to this section.
22896
922fbb7b
AC
22897@subheading Motivation
22898
22899The motivation for this collection of commands.
22900
22901@subheading Introduction
22902
22903A brief introduction to this collection of commands as a whole.
22904
22905@subheading Commands
22906
22907For each command in the block, the following is described:
22908
22909@subsubheading Synopsis
22910
22911@smallexample
22912 -command @var{args}@dots{}
22913@end smallexample
22914
922fbb7b
AC
22915@subsubheading Result
22916
265eeb58 22917@subsubheading @value{GDBN} Command
922fbb7b 22918
265eeb58 22919The corresponding @value{GDBN} CLI command(s), if any.
922fbb7b
AC
22920
22921@subsubheading Example
22922
ef21caaf
NR
22923Example(s) formatted for readability. Some of the described commands have
22924not been implemented yet and these are labeled N.A.@: (not available).
22925
22926
922fbb7b 22927@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
ef21caaf
NR
22928@node GDB/MI Breakpoint Commands
22929@section @sc{gdb/mi} Breakpoint Commands
922fbb7b
AC
22930
22931@cindex breakpoint commands for @sc{gdb/mi}
22932@cindex @sc{gdb/mi}, breakpoint commands
22933This section documents @sc{gdb/mi} commands for manipulating
22934breakpoints.
22935
22936@subheading The @code{-break-after} Command
22937@findex -break-after
22938
22939@subsubheading Synopsis
22940
22941@smallexample
22942 -break-after @var{number} @var{count}
22943@end smallexample
22944
22945The breakpoint number @var{number} is not in effect until it has been
22946hit @var{count} times. To see how this is reflected in the output of
22947the @samp{-break-list} command, see the description of the
22948@samp{-break-list} command below.
22949
22950@subsubheading @value{GDBN} Command
22951
22952The corresponding @value{GDBN} command is @samp{ignore}.
22953
22954@subsubheading Example
22955
22956@smallexample
594fe323 22957(gdb)
922fbb7b 22958-break-insert main
a47ec5fe
AR
22959^done,bkpt=@{number="1",type="breakpoint",disp="keep",
22960enabled="y",addr="0x000100d0",func="main",file="hello.c",
948d5102 22961fullname="/home/foo/hello.c",line="5",times="0"@}
594fe323 22962(gdb)
922fbb7b
AC
22963-break-after 1 3
22964~
22965^done
594fe323 22966(gdb)
922fbb7b
AC
22967-break-list
22968^done,BreakpointTable=@{nr_rows="1",nr_cols="6",
22969hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
22970@{width="14",alignment="-1",col_name="type",colhdr="Type"@},
22971@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
22972@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
22973@{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
22974@{width="40",alignment="2",col_name="what",colhdr="What"@}],
22975body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
948d5102
NR
22976addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
22977line="5",times="0",ignore="3"@}]@}
594fe323 22978(gdb)
922fbb7b
AC
22979@end smallexample
22980
22981@ignore
22982@subheading The @code{-break-catch} Command
22983@findex -break-catch
48cb2d85 22984@end ignore
922fbb7b
AC
22985
22986@subheading The @code{-break-commands} Command
22987@findex -break-commands
922fbb7b 22988
48cb2d85
VP
22989@subsubheading Synopsis
22990
22991@smallexample
22992 -break-commands @var{number} [ @var{command1} ... @var{commandN} ]
22993@end smallexample
22994
22995Specifies the CLI commands that should be executed when breakpoint
22996@var{number} is hit. The parameters @var{command1} to @var{commandN}
22997are the commands. If no command is specified, any previously-set
22998commands are cleared. @xref{Break Commands}. Typical use of this
22999functionality is tracing a program, that is, printing of values of
23000some variables whenever breakpoint is hit and then continuing.
23001
23002@subsubheading @value{GDBN} Command
23003
23004The corresponding @value{GDBN} command is @samp{commands}.
23005
23006@subsubheading Example
23007
23008@smallexample
23009(gdb)
23010-break-insert main
23011^done,bkpt=@{number="1",type="breakpoint",disp="keep",
23012enabled="y",addr="0x000100d0",func="main",file="hello.c",
23013fullname="/home/foo/hello.c",line="5",times="0"@}
23014(gdb)
23015-break-commands 1 "print v" "continue"
23016^done
23017(gdb)
23018@end smallexample
922fbb7b
AC
23019
23020@subheading The @code{-break-condition} Command
23021@findex -break-condition
23022
23023@subsubheading Synopsis
23024
23025@smallexample
23026 -break-condition @var{number} @var{expr}
23027@end smallexample
23028
23029Breakpoint @var{number} will stop the program only if the condition in
23030@var{expr} is true. The condition becomes part of the
23031@samp{-break-list} output (see the description of the @samp{-break-list}
23032command below).
23033
23034@subsubheading @value{GDBN} Command
23035
23036The corresponding @value{GDBN} command is @samp{condition}.
23037
23038@subsubheading Example
23039
23040@smallexample
594fe323 23041(gdb)
922fbb7b
AC
23042-break-condition 1 1
23043^done
594fe323 23044(gdb)
922fbb7b
AC
23045-break-list
23046^done,BreakpointTable=@{nr_rows="1",nr_cols="6",
23047hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
23048@{width="14",alignment="-1",col_name="type",colhdr="Type"@},
23049@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
23050@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
23051@{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
23052@{width="40",alignment="2",col_name="what",colhdr="What"@}],
23053body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
948d5102
NR
23054addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
23055line="5",cond="1",times="0",ignore="3"@}]@}
594fe323 23056(gdb)
922fbb7b
AC
23057@end smallexample
23058
23059@subheading The @code{-break-delete} Command
23060@findex -break-delete
23061
23062@subsubheading Synopsis
23063
23064@smallexample
23065 -break-delete ( @var{breakpoint} )+
23066@end smallexample
23067
23068Delete the breakpoint(s) whose number(s) are specified in the argument
23069list. This is obviously reflected in the breakpoint list.
23070
79a6e687 23071@subsubheading @value{GDBN} Command
922fbb7b
AC
23072
23073The corresponding @value{GDBN} command is @samp{delete}.
23074
23075@subsubheading Example
23076
23077@smallexample
594fe323 23078(gdb)
922fbb7b
AC
23079-break-delete 1
23080^done
594fe323 23081(gdb)
922fbb7b
AC
23082-break-list
23083^done,BreakpointTable=@{nr_rows="0",nr_cols="6",
23084hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
23085@{width="14",alignment="-1",col_name="type",colhdr="Type"@},
23086@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
23087@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
23088@{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
23089@{width="40",alignment="2",col_name="what",colhdr="What"@}],
23090body=[]@}
594fe323 23091(gdb)
922fbb7b
AC
23092@end smallexample
23093
23094@subheading The @code{-break-disable} Command
23095@findex -break-disable
23096
23097@subsubheading Synopsis
23098
23099@smallexample
23100 -break-disable ( @var{breakpoint} )+
23101@end smallexample
23102
23103Disable the named @var{breakpoint}(s). The field @samp{enabled} in the
23104break list is now set to @samp{n} for the named @var{breakpoint}(s).
23105
23106@subsubheading @value{GDBN} Command
23107
23108The corresponding @value{GDBN} command is @samp{disable}.
23109
23110@subsubheading Example
23111
23112@smallexample
594fe323 23113(gdb)
922fbb7b
AC
23114-break-disable 2
23115^done
594fe323 23116(gdb)
922fbb7b
AC
23117-break-list
23118^done,BreakpointTable=@{nr_rows="1",nr_cols="6",
23119hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
23120@{width="14",alignment="-1",col_name="type",colhdr="Type"@},
23121@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
23122@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
23123@{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
23124@{width="40",alignment="2",col_name="what",colhdr="What"@}],
23125body=[bkpt=@{number="2",type="breakpoint",disp="keep",enabled="n",
948d5102
NR
23126addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
23127line="5",times="0"@}]@}
594fe323 23128(gdb)
922fbb7b
AC
23129@end smallexample
23130
23131@subheading The @code{-break-enable} Command
23132@findex -break-enable
23133
23134@subsubheading Synopsis
23135
23136@smallexample
23137 -break-enable ( @var{breakpoint} )+
23138@end smallexample
23139
23140Enable (previously disabled) @var{breakpoint}(s).
23141
23142@subsubheading @value{GDBN} Command
23143
23144The corresponding @value{GDBN} command is @samp{enable}.
23145
23146@subsubheading Example
23147
23148@smallexample
594fe323 23149(gdb)
922fbb7b
AC
23150-break-enable 2
23151^done
594fe323 23152(gdb)
922fbb7b
AC
23153-break-list
23154^done,BreakpointTable=@{nr_rows="1",nr_cols="6",
23155hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
23156@{width="14",alignment="-1",col_name="type",colhdr="Type"@},
23157@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
23158@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
23159@{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
23160@{width="40",alignment="2",col_name="what",colhdr="What"@}],
23161body=[bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y",
948d5102
NR
23162addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
23163line="5",times="0"@}]@}
594fe323 23164(gdb)
922fbb7b
AC
23165@end smallexample
23166
23167@subheading The @code{-break-info} Command
23168@findex -break-info
23169
23170@subsubheading Synopsis
23171
23172@smallexample
23173 -break-info @var{breakpoint}
23174@end smallexample
23175
23176@c REDUNDANT???
23177Get information about a single breakpoint.
23178
79a6e687 23179@subsubheading @value{GDBN} Command
922fbb7b
AC
23180
23181The corresponding @value{GDBN} command is @samp{info break @var{breakpoint}}.
23182
23183@subsubheading Example
23184N.A.
23185
23186@subheading The @code{-break-insert} Command
23187@findex -break-insert
23188
23189@subsubheading Synopsis
23190
23191@smallexample
18148017 23192 -break-insert [ -t ] [ -h ] [ -f ] [ -d ] [ -a ]
922fbb7b 23193 [ -c @var{condition} ] [ -i @var{ignore-count} ]
afe8ab22 23194 [ -p @var{thread} ] [ @var{location} ]
922fbb7b
AC
23195@end smallexample
23196
23197@noindent
afe8ab22 23198If specified, @var{location}, can be one of:
922fbb7b
AC
23199
23200@itemize @bullet
23201@item function
23202@c @item +offset
23203@c @item -offset
23204@c @item linenum
23205@item filename:linenum
23206@item filename:function
23207@item *address
23208@end itemize
23209
23210The possible optional parameters of this command are:
23211
23212@table @samp
23213@item -t
948d5102 23214Insert a temporary breakpoint.
922fbb7b
AC
23215@item -h
23216Insert a hardware breakpoint.
23217@item -c @var{condition}
23218Make the breakpoint conditional on @var{condition}.
23219@item -i @var{ignore-count}
23220Initialize the @var{ignore-count}.
afe8ab22
VP
23221@item -f
23222If @var{location} cannot be parsed (for example if it
23223refers to unknown files or functions), create a pending
23224breakpoint. Without this flag, @value{GDBN} will report
23225an error, and won't create a breakpoint, if @var{location}
23226cannot be parsed.
41447f92
VP
23227@item -d
23228Create a disabled breakpoint.
18148017
VP
23229@item -a
23230Create a tracepoint. @xref{Tracepoints}. When this parameter
23231is used together with @samp{-h}, a fast tracepoint is created.
922fbb7b
AC
23232@end table
23233
23234@subsubheading Result
23235
23236The result is in the form:
23237
23238@smallexample
948d5102
NR
23239^done,bkpt=@{number="@var{number}",type="@var{type}",disp="del"|"keep",
23240enabled="y"|"n",addr="@var{hex}",func="@var{funcname}",file="@var{filename}",
ef21caaf
NR
23241fullname="@var{full_filename}",line="@var{lineno}",[thread="@var{threadno},]
23242times="@var{times}"@}
922fbb7b
AC
23243@end smallexample
23244
23245@noindent
948d5102
NR
23246where @var{number} is the @value{GDBN} number for this breakpoint,
23247@var{funcname} is the name of the function where the breakpoint was
23248inserted, @var{filename} is the name of the source file which contains
23249this function, @var{lineno} is the source line number within that file
23250and @var{times} the number of times that the breakpoint has been hit
23251(always 0 for -break-insert but may be greater for -break-info or -break-list
23252which use the same output).
922fbb7b
AC
23253
23254Note: this format is open to change.
23255@c An out-of-band breakpoint instead of part of the result?
23256
23257@subsubheading @value{GDBN} Command
23258
23259The corresponding @value{GDBN} commands are @samp{break}, @samp{tbreak},
23260@samp{hbreak}, @samp{thbreak}, and @samp{rbreak}.
23261
23262@subsubheading Example
23263
23264@smallexample
594fe323 23265(gdb)
922fbb7b 23266-break-insert main
948d5102
NR
23267^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",
23268fullname="/home/foo/recursive2.c,line="4",times="0"@}
594fe323 23269(gdb)
922fbb7b 23270-break-insert -t foo
948d5102
NR
23271^done,bkpt=@{number="2",addr="0x00010774",file="recursive2.c",
23272fullname="/home/foo/recursive2.c,line="11",times="0"@}
594fe323 23273(gdb)
922fbb7b
AC
23274-break-list
23275^done,BreakpointTable=@{nr_rows="2",nr_cols="6",
23276hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
23277@{width="14",alignment="-1",col_name="type",colhdr="Type"@},
23278@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
23279@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
23280@{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
23281@{width="40",alignment="2",col_name="what",colhdr="What"@}],
23282body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
948d5102
NR
23283addr="0x0001072c", func="main",file="recursive2.c",
23284fullname="/home/foo/recursive2.c,"line="4",times="0"@},
922fbb7b 23285bkpt=@{number="2",type="breakpoint",disp="del",enabled="y",
948d5102
NR
23286addr="0x00010774",func="foo",file="recursive2.c",
23287fullname="/home/foo/recursive2.c",line="11",times="0"@}]@}
594fe323 23288(gdb)
922fbb7b
AC
23289-break-insert -r foo.*
23290~int foo(int, int);
948d5102
NR
23291^done,bkpt=@{number="3",addr="0x00010774",file="recursive2.c,
23292"fullname="/home/foo/recursive2.c",line="11",times="0"@}
594fe323 23293(gdb)
922fbb7b
AC
23294@end smallexample
23295
23296@subheading The @code{-break-list} Command
23297@findex -break-list
23298
23299@subsubheading Synopsis
23300
23301@smallexample
23302 -break-list
23303@end smallexample
23304
23305Displays the list of inserted breakpoints, showing the following fields:
23306
23307@table @samp
23308@item Number
23309number of the breakpoint
23310@item Type
23311type of the breakpoint: @samp{breakpoint} or @samp{watchpoint}
23312@item Disposition
23313should the breakpoint be deleted or disabled when it is hit: @samp{keep}
23314or @samp{nokeep}
23315@item Enabled
23316is the breakpoint enabled or no: @samp{y} or @samp{n}
23317@item Address
23318memory location at which the breakpoint is set
23319@item What
23320logical location of the breakpoint, expressed by function name, file
23321name, line number
23322@item Times
23323number of times the breakpoint has been hit
23324@end table
23325
23326If there are no breakpoints or watchpoints, the @code{BreakpointTable}
23327@code{body} field is an empty list.
23328
23329@subsubheading @value{GDBN} Command
23330
23331The corresponding @value{GDBN} command is @samp{info break}.
23332
23333@subsubheading Example
23334
23335@smallexample
594fe323 23336(gdb)
922fbb7b
AC
23337-break-list
23338^done,BreakpointTable=@{nr_rows="2",nr_cols="6",
23339hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
23340@{width="14",alignment="-1",col_name="type",colhdr="Type"@},
23341@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
23342@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
23343@{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
23344@{width="40",alignment="2",col_name="what",colhdr="What"@}],
23345body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
23346addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@},
23347bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y",
948d5102
NR
23348addr="0x00010114",func="foo",file="hello.c",fullname="/home/foo/hello.c",
23349line="13",times="0"@}]@}
594fe323 23350(gdb)
922fbb7b
AC
23351@end smallexample
23352
23353Here's an example of the result when there are no breakpoints:
23354
23355@smallexample
594fe323 23356(gdb)
922fbb7b
AC
23357-break-list
23358^done,BreakpointTable=@{nr_rows="0",nr_cols="6",
23359hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
23360@{width="14",alignment="-1",col_name="type",colhdr="Type"@},
23361@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
23362@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
23363@{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
23364@{width="40",alignment="2",col_name="what",colhdr="What"@}],
23365body=[]@}
594fe323 23366(gdb)
922fbb7b
AC
23367@end smallexample
23368
18148017
VP
23369@subheading The @code{-break-passcount} Command
23370@findex -break-passcount
23371
23372@subsubheading Synopsis
23373
23374@smallexample
23375 -break-passcount @var{tracepoint-number} @var{passcount}
23376@end smallexample
23377
23378Set the passcount for tracepoint @var{tracepoint-number} to
23379@var{passcount}. If the breakpoint referred to by @var{tracepoint-number}
23380is not a tracepoint, error is emitted. This corresponds to CLI
23381command @samp{passcount}.
23382
922fbb7b
AC
23383@subheading The @code{-break-watch} Command
23384@findex -break-watch
23385
23386@subsubheading Synopsis
23387
23388@smallexample
23389 -break-watch [ -a | -r ]
23390@end smallexample
23391
23392Create a watchpoint. With the @samp{-a} option it will create an
d3e8051b 23393@dfn{access} watchpoint, i.e., a watchpoint that triggers either on a
922fbb7b 23394read from or on a write to the memory location. With the @samp{-r}
d3e8051b 23395option, the watchpoint created is a @dfn{read} watchpoint, i.e., it will
922fbb7b
AC
23396trigger only when the memory location is accessed for reading. Without
23397either of the options, the watchpoint created is a regular watchpoint,
d3e8051b 23398i.e., it will trigger when the memory location is accessed for writing.
79a6e687 23399@xref{Set Watchpoints, , Setting Watchpoints}.
922fbb7b
AC
23400
23401Note that @samp{-break-list} will report a single list of watchpoints and
23402breakpoints inserted.
23403
23404@subsubheading @value{GDBN} Command
23405
23406The corresponding @value{GDBN} commands are @samp{watch}, @samp{awatch}, and
23407@samp{rwatch}.
23408
23409@subsubheading Example
23410
23411Setting a watchpoint on a variable in the @code{main} function:
23412
23413@smallexample
594fe323 23414(gdb)
922fbb7b
AC
23415-break-watch x
23416^done,wpt=@{number="2",exp="x"@}
594fe323 23417(gdb)
922fbb7b
AC
23418-exec-continue
23419^running
0869d01b
NR
23420(gdb)
23421*stopped,reason="watchpoint-trigger",wpt=@{number="2",exp="x"@},
922fbb7b 23422value=@{old="-268439212",new="55"@},
76ff342d 23423frame=@{func="main",args=[],file="recursive2.c",
948d5102 23424fullname="/home/foo/bar/recursive2.c",line="5"@}
594fe323 23425(gdb)
922fbb7b
AC
23426@end smallexample
23427
23428Setting a watchpoint on a variable local to a function. @value{GDBN} will stop
23429the program execution twice: first for the variable changing value, then
23430for the watchpoint going out of scope.
23431
23432@smallexample
594fe323 23433(gdb)
922fbb7b
AC
23434-break-watch C
23435^done,wpt=@{number="5",exp="C"@}
594fe323 23436(gdb)
922fbb7b
AC
23437-exec-continue
23438^running
0869d01b
NR
23439(gdb)
23440*stopped,reason="watchpoint-trigger",
922fbb7b
AC
23441wpt=@{number="5",exp="C"@},value=@{old="-276895068",new="3"@},
23442frame=@{func="callee4",args=[],
76ff342d
DJ
23443file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
23444fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13"@}
594fe323 23445(gdb)
922fbb7b
AC
23446-exec-continue
23447^running
0869d01b
NR
23448(gdb)
23449*stopped,reason="watchpoint-scope",wpnum="5",
922fbb7b
AC
23450frame=@{func="callee3",args=[@{name="strarg",
23451value="0x11940 \"A string argument.\""@}],
76ff342d
DJ
23452file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
23453fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
594fe323 23454(gdb)
922fbb7b
AC
23455@end smallexample
23456
23457Listing breakpoints and watchpoints, at different points in the program
23458execution. Note that once the watchpoint goes out of scope, it is
23459deleted.
23460
23461@smallexample
594fe323 23462(gdb)
922fbb7b
AC
23463-break-watch C
23464^done,wpt=@{number="2",exp="C"@}
594fe323 23465(gdb)
922fbb7b
AC
23466-break-list
23467^done,BreakpointTable=@{nr_rows="2",nr_cols="6",
23468hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
23469@{width="14",alignment="-1",col_name="type",colhdr="Type"@},
23470@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
23471@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
23472@{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
23473@{width="40",alignment="2",col_name="what",colhdr="What"@}],
23474body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
23475addr="0x00010734",func="callee4",
948d5102
NR
23476file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
23477fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c"line="8",times="1"@},
922fbb7b
AC
23478bkpt=@{number="2",type="watchpoint",disp="keep",
23479enabled="y",addr="",what="C",times="0"@}]@}
594fe323 23480(gdb)
922fbb7b
AC
23481-exec-continue
23482^running
0869d01b
NR
23483(gdb)
23484*stopped,reason="watchpoint-trigger",wpt=@{number="2",exp="C"@},
922fbb7b
AC
23485value=@{old="-276895068",new="3"@},
23486frame=@{func="callee4",args=[],
76ff342d
DJ
23487file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
23488fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13"@}
594fe323 23489(gdb)
922fbb7b
AC
23490-break-list
23491^done,BreakpointTable=@{nr_rows="2",nr_cols="6",
23492hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
23493@{width="14",alignment="-1",col_name="type",colhdr="Type"@},
23494@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
23495@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
23496@{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
23497@{width="40",alignment="2",col_name="what",colhdr="What"@}],
23498body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
23499addr="0x00010734",func="callee4",
948d5102
NR
23500file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
23501fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"@},
922fbb7b
AC
23502bkpt=@{number="2",type="watchpoint",disp="keep",
23503enabled="y",addr="",what="C",times="-5"@}]@}
594fe323 23504(gdb)
922fbb7b
AC
23505-exec-continue
23506^running
23507^done,reason="watchpoint-scope",wpnum="2",
23508frame=@{func="callee3",args=[@{name="strarg",
23509value="0x11940 \"A string argument.\""@}],
76ff342d
DJ
23510file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
23511fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
594fe323 23512(gdb)
922fbb7b
AC
23513-break-list
23514^done,BreakpointTable=@{nr_rows="1",nr_cols="6",
23515hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
23516@{width="14",alignment="-1",col_name="type",colhdr="Type"@},
23517@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
23518@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
23519@{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
23520@{width="40",alignment="2",col_name="what",colhdr="What"@}],
23521body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
23522addr="0x00010734",func="callee4",
948d5102
NR
23523file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
23524fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8",
23525times="1"@}]@}
594fe323 23526(gdb)
922fbb7b
AC
23527@end smallexample
23528
23529@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
a2c02241
NR
23530@node GDB/MI Program Context
23531@section @sc{gdb/mi} Program Context
922fbb7b 23532
a2c02241
NR
23533@subheading The @code{-exec-arguments} Command
23534@findex -exec-arguments
922fbb7b 23535
922fbb7b
AC
23536
23537@subsubheading Synopsis
23538
23539@smallexample
a2c02241 23540 -exec-arguments @var{args}
922fbb7b
AC
23541@end smallexample
23542
a2c02241
NR
23543Set the inferior program arguments, to be used in the next
23544@samp{-exec-run}.
922fbb7b 23545
a2c02241 23546@subsubheading @value{GDBN} Command
922fbb7b 23547
a2c02241 23548The corresponding @value{GDBN} command is @samp{set args}.
922fbb7b 23549
a2c02241 23550@subsubheading Example
922fbb7b 23551
fbc5282e
MK
23552@smallexample
23553(gdb)
23554-exec-arguments -v word
23555^done
23556(gdb)
23557@end smallexample
922fbb7b 23558
a2c02241 23559
9901a55b 23560@ignore
a2c02241
NR
23561@subheading The @code{-exec-show-arguments} Command
23562@findex -exec-show-arguments
23563
23564@subsubheading Synopsis
23565
23566@smallexample
23567 -exec-show-arguments
23568@end smallexample
23569
23570Print the arguments of the program.
922fbb7b
AC
23571
23572@subsubheading @value{GDBN} Command
23573
a2c02241 23574The corresponding @value{GDBN} command is @samp{show args}.
922fbb7b
AC
23575
23576@subsubheading Example
a2c02241 23577N.A.
9901a55b 23578@end ignore
922fbb7b 23579
922fbb7b 23580
a2c02241
NR
23581@subheading The @code{-environment-cd} Command
23582@findex -environment-cd
922fbb7b 23583
a2c02241 23584@subsubheading Synopsis
922fbb7b
AC
23585
23586@smallexample
a2c02241 23587 -environment-cd @var{pathdir}
922fbb7b
AC
23588@end smallexample
23589
a2c02241 23590Set @value{GDBN}'s working directory.
922fbb7b 23591
a2c02241 23592@subsubheading @value{GDBN} Command
922fbb7b 23593
a2c02241
NR
23594The corresponding @value{GDBN} command is @samp{cd}.
23595
23596@subsubheading Example
922fbb7b
AC
23597
23598@smallexample
594fe323 23599(gdb)
a2c02241
NR
23600-environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
23601^done
594fe323 23602(gdb)
922fbb7b
AC
23603@end smallexample
23604
23605
a2c02241
NR
23606@subheading The @code{-environment-directory} Command
23607@findex -environment-directory
922fbb7b
AC
23608
23609@subsubheading Synopsis
23610
23611@smallexample
a2c02241 23612 -environment-directory [ -r ] [ @var{pathdir} ]+
922fbb7b
AC
23613@end smallexample
23614
a2c02241
NR
23615Add directories @var{pathdir} to beginning of search path for source files.
23616If the @samp{-r} option is used, the search path is reset to the default
23617search path. If directories @var{pathdir} are supplied in addition to the
23618@samp{-r} option, the search path is first reset and then addition
23619occurs as normal.
23620Multiple directories may be specified, separated by blanks. Specifying
23621multiple directories in a single command
23622results in the directories added to the beginning of the
23623search path in the same order they were presented in the command.
23624If blanks are needed as
23625part of a directory name, double-quotes should be used around
23626the name. In the command output, the path will show up separated
d3e8051b 23627by the system directory-separator character. The directory-separator
a2c02241
NR
23628character must not be used
23629in any directory name.
23630If no directories are specified, the current search path is displayed.
922fbb7b
AC
23631
23632@subsubheading @value{GDBN} Command
23633
a2c02241 23634The corresponding @value{GDBN} command is @samp{dir}.
922fbb7b
AC
23635
23636@subsubheading Example
23637
922fbb7b 23638@smallexample
594fe323 23639(gdb)
a2c02241
NR
23640-environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
23641^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd"
594fe323 23642(gdb)
a2c02241
NR
23643-environment-directory ""
23644^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd"
594fe323 23645(gdb)
a2c02241
NR
23646-environment-directory -r /home/jjohnstn/src/gdb /usr/src
23647^done,source-path="/home/jjohnstn/src/gdb:/usr/src:$cdir:$cwd"
594fe323 23648(gdb)
a2c02241
NR
23649-environment-directory -r
23650^done,source-path="$cdir:$cwd"
594fe323 23651(gdb)
922fbb7b
AC
23652@end smallexample
23653
23654
a2c02241
NR
23655@subheading The @code{-environment-path} Command
23656@findex -environment-path
922fbb7b
AC
23657
23658@subsubheading Synopsis
23659
23660@smallexample
a2c02241 23661 -environment-path [ -r ] [ @var{pathdir} ]+
922fbb7b
AC
23662@end smallexample
23663
a2c02241
NR
23664Add directories @var{pathdir} to beginning of search path for object files.
23665If the @samp{-r} option is used, the search path is reset to the original
23666search path that existed at gdb start-up. If directories @var{pathdir} are
23667supplied in addition to the
23668@samp{-r} option, the search path is first reset and then addition
23669occurs as normal.
23670Multiple directories may be specified, separated by blanks. Specifying
23671multiple directories in a single command
23672results in the directories added to the beginning of the
23673search path in the same order they were presented in the command.
23674If blanks are needed as
23675part of a directory name, double-quotes should be used around
23676the name. In the command output, the path will show up separated
d3e8051b 23677by the system directory-separator character. The directory-separator
a2c02241
NR
23678character must not be used
23679in any directory name.
23680If no directories are specified, the current path is displayed.
23681
922fbb7b
AC
23682
23683@subsubheading @value{GDBN} Command
23684
a2c02241 23685The corresponding @value{GDBN} command is @samp{path}.
922fbb7b
AC
23686
23687@subsubheading Example
23688
922fbb7b 23689@smallexample
594fe323 23690(gdb)
a2c02241
NR
23691-environment-path
23692^done,path="/usr/bin"
594fe323 23693(gdb)
a2c02241
NR
23694-environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb /bin
23695^done,path="/kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb:/bin:/usr/bin"
594fe323 23696(gdb)
a2c02241
NR
23697-environment-path -r /usr/local/bin
23698^done,path="/usr/local/bin:/usr/bin"
594fe323 23699(gdb)
922fbb7b
AC
23700@end smallexample
23701
23702
a2c02241
NR
23703@subheading The @code{-environment-pwd} Command
23704@findex -environment-pwd
922fbb7b
AC
23705
23706@subsubheading Synopsis
23707
23708@smallexample
a2c02241 23709 -environment-pwd
922fbb7b
AC
23710@end smallexample
23711
a2c02241 23712Show the current working directory.
922fbb7b 23713
79a6e687 23714@subsubheading @value{GDBN} Command
922fbb7b 23715
a2c02241 23716The corresponding @value{GDBN} command is @samp{pwd}.
922fbb7b
AC
23717
23718@subsubheading Example
23719
922fbb7b 23720@smallexample
594fe323 23721(gdb)
a2c02241
NR
23722-environment-pwd
23723^done,cwd="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb"
594fe323 23724(gdb)
922fbb7b
AC
23725@end smallexample
23726
a2c02241
NR
23727@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
23728@node GDB/MI Thread Commands
23729@section @sc{gdb/mi} Thread Commands
23730
23731
23732@subheading The @code{-thread-info} Command
23733@findex -thread-info
922fbb7b
AC
23734
23735@subsubheading Synopsis
23736
23737@smallexample
8e8901c5 23738 -thread-info [ @var{thread-id} ]
922fbb7b
AC
23739@end smallexample
23740
8e8901c5
VP
23741Reports information about either a specific thread, if
23742the @var{thread-id} parameter is present, or about all
23743threads. When printing information about all threads,
23744also reports the current thread.
23745
79a6e687 23746@subsubheading @value{GDBN} Command
922fbb7b 23747
8e8901c5
VP
23748The @samp{info thread} command prints the same information
23749about all threads.
922fbb7b
AC
23750
23751@subsubheading Example
922fbb7b
AC
23752
23753@smallexample
8e8901c5
VP
23754-thread-info
23755^done,threads=[
23756@{id="2",target-id="Thread 0xb7e14b90 (LWP 21257)",
c3b108f7 23757 frame=@{level="0",addr="0xffffe410",func="__kernel_vsyscall",args=[]@},state="running"@},
8e8901c5
VP
23758@{id="1",target-id="Thread 0xb7e156b0 (LWP 21254)",
23759 frame=@{level="0",addr="0x0804891f",func="foo",args=[@{name="i",value="10"@}],
c3b108f7 23760 file="/tmp/a.c",fullname="/tmp/a.c",line="158"@},state="running"@}],
8e8901c5
VP
23761current-thread-id="1"
23762(gdb)
922fbb7b
AC
23763@end smallexample
23764
c3b108f7
VP
23765The @samp{state} field may have the following values:
23766
23767@table @code
23768@item stopped
23769The thread is stopped. Frame information is available for stopped
23770threads.
23771
23772@item running
23773The thread is running. There's no frame information for running
23774threads.
23775
23776@end table
23777
a2c02241
NR
23778@subheading The @code{-thread-list-ids} Command
23779@findex -thread-list-ids
922fbb7b 23780
a2c02241 23781@subsubheading Synopsis
922fbb7b 23782
a2c02241
NR
23783@smallexample
23784 -thread-list-ids
23785@end smallexample
922fbb7b 23786
a2c02241
NR
23787Produces a list of the currently known @value{GDBN} thread ids. At the
23788end of the list it also prints the total number of such threads.
922fbb7b 23789
c3b108f7
VP
23790This command is retained for historical reasons, the
23791@code{-thread-info} command should be used instead.
23792
922fbb7b
AC
23793@subsubheading @value{GDBN} Command
23794
a2c02241 23795Part of @samp{info threads} supplies the same information.
922fbb7b
AC
23796
23797@subsubheading Example
23798
922fbb7b 23799@smallexample
594fe323 23800(gdb)
a2c02241
NR
23801-thread-list-ids
23802^done,thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@},
592375cd 23803current-thread-id="1",number-of-threads="3"
594fe323 23804(gdb)
922fbb7b
AC
23805@end smallexample
23806
a2c02241
NR
23807
23808@subheading The @code{-thread-select} Command
23809@findex -thread-select
922fbb7b
AC
23810
23811@subsubheading Synopsis
23812
23813@smallexample
a2c02241 23814 -thread-select @var{threadnum}
922fbb7b
AC
23815@end smallexample
23816
a2c02241
NR
23817Make @var{threadnum} the current thread. It prints the number of the new
23818current thread, and the topmost frame for that thread.
922fbb7b 23819
c3b108f7
VP
23820This command is deprecated in favor of explicitly using the
23821@samp{--thread} option to each command.
23822
922fbb7b
AC
23823@subsubheading @value{GDBN} Command
23824
a2c02241 23825The corresponding @value{GDBN} command is @samp{thread}.
922fbb7b
AC
23826
23827@subsubheading Example
922fbb7b
AC
23828
23829@smallexample
594fe323 23830(gdb)
a2c02241
NR
23831-exec-next
23832^running
594fe323 23833(gdb)
a2c02241
NR
23834*stopped,reason="end-stepping-range",thread-id="2",line="187",
23835file="../../../devo/gdb/testsuite/gdb.threads/linux-dp.c"
594fe323 23836(gdb)
a2c02241
NR
23837-thread-list-ids
23838^done,
23839thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@},
23840number-of-threads="3"
594fe323 23841(gdb)
a2c02241
NR
23842-thread-select 3
23843^done,new-thread-id="3",
23844frame=@{level="0",func="vprintf",
23845args=[@{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""@},
23846@{name="arg",value="0x2"@}],file="vprintf.c",line="31"@}
594fe323 23847(gdb)
922fbb7b
AC
23848@end smallexample
23849
a2c02241
NR
23850@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
23851@node GDB/MI Program Execution
23852@section @sc{gdb/mi} Program Execution
922fbb7b 23853
ef21caaf 23854These are the asynchronous commands which generate the out-of-band
3f94c067 23855record @samp{*stopped}. Currently @value{GDBN} only really executes
ef21caaf
NR
23856asynchronously with remote targets and this interaction is mimicked in
23857other cases.
922fbb7b 23858
922fbb7b
AC
23859@subheading The @code{-exec-continue} Command
23860@findex -exec-continue
23861
23862@subsubheading Synopsis
23863
23864@smallexample
540aa8e7 23865 -exec-continue [--reverse] [--all|--thread-group N]
922fbb7b
AC
23866@end smallexample
23867
540aa8e7
MS
23868Resumes the execution of the inferior program, which will continue
23869to execute until it reaches a debugger stop event. If the
23870@samp{--reverse} option is specified, execution resumes in reverse until
23871it reaches a stop event. Stop events may include
23872@itemize @bullet
23873@item
23874breakpoints or watchpoints
23875@item
23876signals or exceptions
23877@item
23878the end of the process (or its beginning under @samp{--reverse})
23879@item
23880the end or beginning of a replay log if one is being used.
23881@end itemize
23882In all-stop mode (@pxref{All-Stop
23883Mode}), may resume only one thread, or all threads, depending on the
23884value of the @samp{scheduler-locking} variable. If @samp{--all} is
a79b8f6e 23885specified, all threads (in all inferiors) will be resumed. The @samp{--all} option is
540aa8e7
MS
23886ignored in all-stop mode. If the @samp{--thread-group} options is
23887specified, then all threads in that thread group are resumed.
922fbb7b
AC
23888
23889@subsubheading @value{GDBN} Command
23890
23891The corresponding @value{GDBN} corresponding is @samp{continue}.
23892
23893@subsubheading Example
23894
23895@smallexample
23896-exec-continue
23897^running
594fe323 23898(gdb)
922fbb7b 23899@@Hello world
a47ec5fe
AR
23900*stopped,reason="breakpoint-hit",disp="keep",bkptno="2",frame=@{
23901func="foo",args=[],file="hello.c",fullname="/home/foo/bar/hello.c",
23902line="13"@}
594fe323 23903(gdb)
922fbb7b
AC
23904@end smallexample
23905
23906
23907@subheading The @code{-exec-finish} Command
23908@findex -exec-finish
23909
23910@subsubheading Synopsis
23911
23912@smallexample
540aa8e7 23913 -exec-finish [--reverse]
922fbb7b
AC
23914@end smallexample
23915
ef21caaf
NR
23916Resumes the execution of the inferior program until the current
23917function is exited. Displays the results returned by the function.
540aa8e7
MS
23918If the @samp{--reverse} option is specified, resumes the reverse
23919execution of the inferior program until the point where current
23920function was called.
922fbb7b
AC
23921
23922@subsubheading @value{GDBN} Command
23923
23924The corresponding @value{GDBN} command is @samp{finish}.
23925
23926@subsubheading Example
23927
23928Function returning @code{void}.
23929
23930@smallexample
23931-exec-finish
23932^running
594fe323 23933(gdb)
922fbb7b
AC
23934@@hello from foo
23935*stopped,reason="function-finished",frame=@{func="main",args=[],
948d5102 23936file="hello.c",fullname="/home/foo/bar/hello.c",line="7"@}
594fe323 23937(gdb)
922fbb7b
AC
23938@end smallexample
23939
23940Function returning other than @code{void}. The name of the internal
23941@value{GDBN} variable storing the result is printed, together with the
23942value itself.
23943
23944@smallexample
23945-exec-finish
23946^running
594fe323 23947(gdb)
922fbb7b
AC
23948*stopped,reason="function-finished",frame=@{addr="0x000107b0",func="foo",
23949args=[@{name="a",value="1"],@{name="b",value="9"@}@},
948d5102 23950file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
922fbb7b 23951gdb-result-var="$1",return-value="0"
594fe323 23952(gdb)
922fbb7b
AC
23953@end smallexample
23954
23955
23956@subheading The @code{-exec-interrupt} Command
23957@findex -exec-interrupt
23958
23959@subsubheading Synopsis
23960
23961@smallexample
c3b108f7 23962 -exec-interrupt [--all|--thread-group N]
922fbb7b
AC
23963@end smallexample
23964
ef21caaf
NR
23965Interrupts the background execution of the target. Note how the token
23966associated with the stop message is the one for the execution command
23967that has been interrupted. The token for the interrupt itself only
23968appears in the @samp{^done} output. If the user is trying to
922fbb7b
AC
23969interrupt a non-running program, an error message will be printed.
23970
c3b108f7
VP
23971Note that when asynchronous execution is enabled, this command is
23972asynchronous just like other execution commands. That is, first the
23973@samp{^done} response will be printed, and the target stop will be
23974reported after that using the @samp{*stopped} notification.
23975
23976In non-stop mode, only the context thread is interrupted by default.
a79b8f6e
VP
23977All threads (in all inferiors) will be interrupted if the
23978@samp{--all} option is specified. If the @samp{--thread-group}
23979option is specified, all threads in that group will be interrupted.
c3b108f7 23980
922fbb7b
AC
23981@subsubheading @value{GDBN} Command
23982
23983The corresponding @value{GDBN} command is @samp{interrupt}.
23984
23985@subsubheading Example
23986
23987@smallexample
594fe323 23988(gdb)
922fbb7b
AC
23989111-exec-continue
23990111^running
23991
594fe323 23992(gdb)
922fbb7b
AC
23993222-exec-interrupt
23994222^done
594fe323 23995(gdb)
922fbb7b 23996111*stopped,signal-name="SIGINT",signal-meaning="Interrupt",
76ff342d 23997frame=@{addr="0x00010140",func="foo",args=[],file="try.c",
948d5102 23998fullname="/home/foo/bar/try.c",line="13"@}
594fe323 23999(gdb)
922fbb7b 24000
594fe323 24001(gdb)
922fbb7b
AC
24002-exec-interrupt
24003^error,msg="mi_cmd_exec_interrupt: Inferior not executing."
594fe323 24004(gdb)
922fbb7b
AC
24005@end smallexample
24006
83eba9b7
VP
24007@subheading The @code{-exec-jump} Command
24008@findex -exec-jump
24009
24010@subsubheading Synopsis
24011
24012@smallexample
24013 -exec-jump @var{location}
24014@end smallexample
24015
24016Resumes execution of the inferior program at the location specified by
24017parameter. @xref{Specify Location}, for a description of the
24018different forms of @var{location}.
24019
24020@subsubheading @value{GDBN} Command
24021
24022The corresponding @value{GDBN} command is @samp{jump}.
24023
24024@subsubheading Example
24025
24026@smallexample
24027-exec-jump foo.c:10
24028*running,thread-id="all"
24029^running
24030@end smallexample
24031
922fbb7b
AC
24032
24033@subheading The @code{-exec-next} Command
24034@findex -exec-next
24035
24036@subsubheading Synopsis
24037
24038@smallexample
540aa8e7 24039 -exec-next [--reverse]
922fbb7b
AC
24040@end smallexample
24041
ef21caaf
NR
24042Resumes execution of the inferior program, stopping when the beginning
24043of the next source line is reached.
922fbb7b 24044
540aa8e7
MS
24045If the @samp{--reverse} option is specified, resumes reverse execution
24046of the inferior program, stopping at the beginning of the previous
24047source line. If you issue this command on the first line of a
24048function, it will take you back to the caller of that function, to the
24049source line where the function was called.
24050
24051
922fbb7b
AC
24052@subsubheading @value{GDBN} Command
24053
24054The corresponding @value{GDBN} command is @samp{next}.
24055
24056@subsubheading Example
24057
24058@smallexample
24059-exec-next
24060^running
594fe323 24061(gdb)
922fbb7b 24062*stopped,reason="end-stepping-range",line="8",file="hello.c"
594fe323 24063(gdb)
922fbb7b
AC
24064@end smallexample
24065
24066
24067@subheading The @code{-exec-next-instruction} Command
24068@findex -exec-next-instruction
24069
24070@subsubheading Synopsis
24071
24072@smallexample
540aa8e7 24073 -exec-next-instruction [--reverse]
922fbb7b
AC
24074@end smallexample
24075
ef21caaf
NR
24076Executes one machine instruction. If the instruction is a function
24077call, continues until the function returns. If the program stops at an
24078instruction in the middle of a source line, the address will be
24079printed as well.
922fbb7b 24080
540aa8e7
MS
24081If the @samp{--reverse} option is specified, resumes reverse execution
24082of the inferior program, stopping at the previous instruction. If the
24083previously executed instruction was a return from another function,
24084it will continue to execute in reverse until the call to that function
24085(from the current stack frame) is reached.
24086
922fbb7b
AC
24087@subsubheading @value{GDBN} Command
24088
24089The corresponding @value{GDBN} command is @samp{nexti}.
24090
24091@subsubheading Example
24092
24093@smallexample
594fe323 24094(gdb)
922fbb7b
AC
24095-exec-next-instruction
24096^running
24097
594fe323 24098(gdb)
922fbb7b
AC
24099*stopped,reason="end-stepping-range",
24100addr="0x000100d4",line="5",file="hello.c"
594fe323 24101(gdb)
922fbb7b
AC
24102@end smallexample
24103
24104
24105@subheading The @code{-exec-return} Command
24106@findex -exec-return
24107
24108@subsubheading Synopsis
24109
24110@smallexample
24111 -exec-return
24112@end smallexample
24113
24114Makes current function return immediately. Doesn't execute the inferior.
24115Displays the new current frame.
24116
24117@subsubheading @value{GDBN} Command
24118
24119The corresponding @value{GDBN} command is @samp{return}.
24120
24121@subsubheading Example
24122
24123@smallexample
594fe323 24124(gdb)
922fbb7b
AC
24125200-break-insert callee4
24126200^done,bkpt=@{number="1",addr="0x00010734",
24127file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@}
594fe323 24128(gdb)
922fbb7b
AC
24129000-exec-run
24130000^running
594fe323 24131(gdb)
a47ec5fe 24132000*stopped,reason="breakpoint-hit",disp="keep",bkptno="1",
922fbb7b 24133frame=@{func="callee4",args=[],
76ff342d
DJ
24134file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
24135fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8"@}
594fe323 24136(gdb)
922fbb7b
AC
24137205-break-delete
24138205^done
594fe323 24139(gdb)
922fbb7b
AC
24140111-exec-return
24141111^done,frame=@{level="0",func="callee3",
24142args=[@{name="strarg",
24143value="0x11940 \"A string argument.\""@}],
76ff342d
DJ
24144file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
24145fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
594fe323 24146(gdb)
922fbb7b
AC
24147@end smallexample
24148
24149
24150@subheading The @code{-exec-run} Command
24151@findex -exec-run
24152
24153@subsubheading Synopsis
24154
24155@smallexample
a79b8f6e 24156 -exec-run [--all | --thread-group N]
922fbb7b
AC
24157@end smallexample
24158
ef21caaf
NR
24159Starts execution of the inferior from the beginning. The inferior
24160executes until either a breakpoint is encountered or the program
24161exits. In the latter case the output will include an exit code, if
24162the program has exited exceptionally.
922fbb7b 24163
a79b8f6e
VP
24164When no option is specified, the current inferior is started. If the
24165@samp{--thread-group} option is specified, it should refer to a thread
24166group of type @samp{process}, and that thread group will be started.
24167If the @samp{--all} option is specified, then all inferiors will be started.
24168
922fbb7b
AC
24169@subsubheading @value{GDBN} Command
24170
24171The corresponding @value{GDBN} command is @samp{run}.
24172
ef21caaf 24173@subsubheading Examples
922fbb7b
AC
24174
24175@smallexample
594fe323 24176(gdb)
922fbb7b
AC
24177-break-insert main
24178^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",line="4"@}
594fe323 24179(gdb)
922fbb7b
AC
24180-exec-run
24181^running
594fe323 24182(gdb)
a47ec5fe 24183*stopped,reason="breakpoint-hit",disp="keep",bkptno="1",
76ff342d 24184frame=@{func="main",args=[],file="recursive2.c",
948d5102 24185fullname="/home/foo/bar/recursive2.c",line="4"@}
594fe323 24186(gdb)
922fbb7b
AC
24187@end smallexample
24188
ef21caaf
NR
24189@noindent
24190Program exited normally:
24191
24192@smallexample
594fe323 24193(gdb)
ef21caaf
NR
24194-exec-run
24195^running
594fe323 24196(gdb)
ef21caaf
NR
24197x = 55
24198*stopped,reason="exited-normally"
594fe323 24199(gdb)
ef21caaf
NR
24200@end smallexample
24201
24202@noindent
24203Program exited exceptionally:
24204
24205@smallexample
594fe323 24206(gdb)
ef21caaf
NR
24207-exec-run
24208^running
594fe323 24209(gdb)
ef21caaf
NR
24210x = 55
24211*stopped,reason="exited",exit-code="01"
594fe323 24212(gdb)
ef21caaf
NR
24213@end smallexample
24214
24215Another way the program can terminate is if it receives a signal such as
24216@code{SIGINT}. In this case, @sc{gdb/mi} displays this:
24217
24218@smallexample
594fe323 24219(gdb)
ef21caaf
NR
24220*stopped,reason="exited-signalled",signal-name="SIGINT",
24221signal-meaning="Interrupt"
24222@end smallexample
24223
922fbb7b 24224
a2c02241
NR
24225@c @subheading -exec-signal
24226
24227
24228@subheading The @code{-exec-step} Command
24229@findex -exec-step
922fbb7b
AC
24230
24231@subsubheading Synopsis
24232
24233@smallexample
540aa8e7 24234 -exec-step [--reverse]
922fbb7b
AC
24235@end smallexample
24236
a2c02241
NR
24237Resumes execution of the inferior program, stopping when the beginning
24238of the next source line is reached, if the next source line is not a
24239function call. If it is, stop at the first instruction of the called
540aa8e7
MS
24240function. If the @samp{--reverse} option is specified, resumes reverse
24241execution of the inferior program, stopping at the beginning of the
24242previously executed source line.
922fbb7b
AC
24243
24244@subsubheading @value{GDBN} Command
24245
a2c02241 24246The corresponding @value{GDBN} command is @samp{step}.
922fbb7b
AC
24247
24248@subsubheading Example
24249
24250Stepping into a function:
24251
24252@smallexample
24253-exec-step
24254^running
594fe323 24255(gdb)
922fbb7b
AC
24256*stopped,reason="end-stepping-range",
24257frame=@{func="foo",args=[@{name="a",value="10"@},
76ff342d 24258@{name="b",value="0"@}],file="recursive2.c",
948d5102 24259fullname="/home/foo/bar/recursive2.c",line="11"@}
594fe323 24260(gdb)
922fbb7b
AC
24261@end smallexample
24262
24263Regular stepping:
24264
24265@smallexample
24266-exec-step
24267^running
594fe323 24268(gdb)
922fbb7b 24269*stopped,reason="end-stepping-range",line="14",file="recursive2.c"
594fe323 24270(gdb)
922fbb7b
AC
24271@end smallexample
24272
24273
24274@subheading The @code{-exec-step-instruction} Command
24275@findex -exec-step-instruction
24276
24277@subsubheading Synopsis
24278
24279@smallexample
540aa8e7 24280 -exec-step-instruction [--reverse]
922fbb7b
AC
24281@end smallexample
24282
540aa8e7
MS
24283Resumes the inferior which executes one machine instruction. If the
24284@samp{--reverse} option is specified, resumes reverse execution of the
24285inferior program, stopping at the previously executed instruction.
24286The output, once @value{GDBN} has stopped, will vary depending on
24287whether we have stopped in the middle of a source line or not. In the
24288former case, the address at which the program stopped will be printed
24289as well.
922fbb7b
AC
24290
24291@subsubheading @value{GDBN} Command
24292
24293The corresponding @value{GDBN} command is @samp{stepi}.
24294
24295@subsubheading Example
24296
24297@smallexample
594fe323 24298(gdb)
922fbb7b
AC
24299-exec-step-instruction
24300^running
24301
594fe323 24302(gdb)
922fbb7b 24303*stopped,reason="end-stepping-range",
76ff342d 24304frame=@{func="foo",args=[],file="try.c",
948d5102 24305fullname="/home/foo/bar/try.c",line="10"@}
594fe323 24306(gdb)
922fbb7b
AC
24307-exec-step-instruction
24308^running
24309
594fe323 24310(gdb)
922fbb7b 24311*stopped,reason="end-stepping-range",
76ff342d 24312frame=@{addr="0x000100f4",func="foo",args=[],file="try.c",
948d5102 24313fullname="/home/foo/bar/try.c",line="10"@}
594fe323 24314(gdb)
922fbb7b
AC
24315@end smallexample
24316
24317
24318@subheading The @code{-exec-until} Command
24319@findex -exec-until
24320
24321@subsubheading Synopsis
24322
24323@smallexample
24324 -exec-until [ @var{location} ]
24325@end smallexample
24326
ef21caaf
NR
24327Executes the inferior until the @var{location} specified in the
24328argument is reached. If there is no argument, the inferior executes
24329until a source line greater than the current one is reached. The
24330reason for stopping in this case will be @samp{location-reached}.
922fbb7b
AC
24331
24332@subsubheading @value{GDBN} Command
24333
24334The corresponding @value{GDBN} command is @samp{until}.
24335
24336@subsubheading Example
24337
24338@smallexample
594fe323 24339(gdb)
922fbb7b
AC
24340-exec-until recursive2.c:6
24341^running
594fe323 24342(gdb)
922fbb7b
AC
24343x = 55
24344*stopped,reason="location-reached",frame=@{func="main",args=[],
948d5102 24345file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="6"@}
594fe323 24346(gdb)
922fbb7b
AC
24347@end smallexample
24348
24349@ignore
24350@subheading -file-clear
24351Is this going away????
24352@end ignore
24353
351ff01a 24354@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
a2c02241
NR
24355@node GDB/MI Stack Manipulation
24356@section @sc{gdb/mi} Stack Manipulation Commands
351ff01a 24357
922fbb7b 24358
a2c02241
NR
24359@subheading The @code{-stack-info-frame} Command
24360@findex -stack-info-frame
922fbb7b
AC
24361
24362@subsubheading Synopsis
24363
24364@smallexample
a2c02241 24365 -stack-info-frame
922fbb7b
AC
24366@end smallexample
24367
a2c02241 24368Get info on the selected frame.
922fbb7b
AC
24369
24370@subsubheading @value{GDBN} Command
24371
a2c02241
NR
24372The corresponding @value{GDBN} command is @samp{info frame} or @samp{frame}
24373(without arguments).
922fbb7b
AC
24374
24375@subsubheading Example
24376
24377@smallexample
594fe323 24378(gdb)
a2c02241
NR
24379-stack-info-frame
24380^done,frame=@{level="1",addr="0x0001076c",func="callee3",
24381file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
24382fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"@}
594fe323 24383(gdb)
922fbb7b
AC
24384@end smallexample
24385
a2c02241
NR
24386@subheading The @code{-stack-info-depth} Command
24387@findex -stack-info-depth
922fbb7b
AC
24388
24389@subsubheading Synopsis
24390
24391@smallexample
a2c02241 24392 -stack-info-depth [ @var{max-depth} ]
922fbb7b
AC
24393@end smallexample
24394
a2c02241
NR
24395Return the depth of the stack. If the integer argument @var{max-depth}
24396is specified, do not count beyond @var{max-depth} frames.
922fbb7b
AC
24397
24398@subsubheading @value{GDBN} Command
24399
a2c02241 24400There's no equivalent @value{GDBN} command.
922fbb7b
AC
24401
24402@subsubheading Example
24403
a2c02241
NR
24404For a stack with frame levels 0 through 11:
24405
922fbb7b 24406@smallexample
594fe323 24407(gdb)
a2c02241
NR
24408-stack-info-depth
24409^done,depth="12"
594fe323 24410(gdb)
a2c02241
NR
24411-stack-info-depth 4
24412^done,depth="4"
594fe323 24413(gdb)
a2c02241
NR
24414-stack-info-depth 12
24415^done,depth="12"
594fe323 24416(gdb)
a2c02241
NR
24417-stack-info-depth 11
24418^done,depth="11"
594fe323 24419(gdb)
a2c02241
NR
24420-stack-info-depth 13
24421^done,depth="12"
594fe323 24422(gdb)
922fbb7b
AC
24423@end smallexample
24424
a2c02241
NR
24425@subheading The @code{-stack-list-arguments} Command
24426@findex -stack-list-arguments
922fbb7b
AC
24427
24428@subsubheading Synopsis
24429
24430@smallexample
3afae151 24431 -stack-list-arguments @var{print-values}
a2c02241 24432 [ @var{low-frame} @var{high-frame} ]
922fbb7b
AC
24433@end smallexample
24434
a2c02241
NR
24435Display a list of the arguments for the frames between @var{low-frame}
24436and @var{high-frame} (inclusive). If @var{low-frame} and
2f1acb09
VP
24437@var{high-frame} are not provided, list the arguments for the whole
24438call stack. If the two arguments are equal, show the single frame
24439at the corresponding level. It is an error if @var{low-frame} is
24440larger than the actual number of frames. On the other hand,
24441@var{high-frame} may be larger than the actual number of frames, in
24442which case only existing frames will be returned.
a2c02241 24443
3afae151
VP
24444If @var{print-values} is 0 or @code{--no-values}, print only the names of
24445the variables; if it is 1 or @code{--all-values}, print also their
24446values; and if it is 2 or @code{--simple-values}, print the name,
24447type and value for simple data types, and the name and type for arrays,
24448structures and unions.
922fbb7b 24449
b3372f91
VP
24450Use of this command to obtain arguments in a single frame is
24451deprecated in favor of the @samp{-stack-list-variables} command.
24452
922fbb7b
AC
24453@subsubheading @value{GDBN} Command
24454
a2c02241
NR
24455@value{GDBN} does not have an equivalent command. @code{gdbtk} has a
24456@samp{gdb_get_args} command which partially overlaps with the
24457functionality of @samp{-stack-list-arguments}.
922fbb7b
AC
24458
24459@subsubheading Example
922fbb7b 24460
a2c02241 24461@smallexample
594fe323 24462(gdb)
a2c02241
NR
24463-stack-list-frames
24464^done,
24465stack=[
24466frame=@{level="0",addr="0x00010734",func="callee4",
24467file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
24468fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8"@},
24469frame=@{level="1",addr="0x0001076c",func="callee3",
24470file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
24471fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"@},
24472frame=@{level="2",addr="0x0001078c",func="callee2",
24473file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
24474fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="22"@},
24475frame=@{level="3",addr="0x000107b4",func="callee1",
24476file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
24477fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="27"@},
24478frame=@{level="4",addr="0x000107e0",func="main",
24479file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
24480fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="32"@}]
594fe323 24481(gdb)
a2c02241
NR
24482-stack-list-arguments 0
24483^done,
24484stack-args=[
24485frame=@{level="0",args=[]@},
24486frame=@{level="1",args=[name="strarg"]@},
24487frame=@{level="2",args=[name="intarg",name="strarg"]@},
24488frame=@{level="3",args=[name="intarg",name="strarg",name="fltarg"]@},
24489frame=@{level="4",args=[]@}]
594fe323 24490(gdb)
a2c02241
NR
24491-stack-list-arguments 1
24492^done,
24493stack-args=[
24494frame=@{level="0",args=[]@},
24495frame=@{level="1",
24496 args=[@{name="strarg",value="0x11940 \"A string argument.\""@}]@},
24497frame=@{level="2",args=[
24498@{name="intarg",value="2"@},
24499@{name="strarg",value="0x11940 \"A string argument.\""@}]@},
24500@{frame=@{level="3",args=[
24501@{name="intarg",value="2"@},
24502@{name="strarg",value="0x11940 \"A string argument.\""@},
24503@{name="fltarg",value="3.5"@}]@},
24504frame=@{level="4",args=[]@}]
594fe323 24505(gdb)
a2c02241
NR
24506-stack-list-arguments 0 2 2
24507^done,stack-args=[frame=@{level="2",args=[name="intarg",name="strarg"]@}]
594fe323 24508(gdb)
a2c02241
NR
24509-stack-list-arguments 1 2 2
24510^done,stack-args=[frame=@{level="2",
24511args=[@{name="intarg",value="2"@},
24512@{name="strarg",value="0x11940 \"A string argument.\""@}]@}]
594fe323 24513(gdb)
a2c02241
NR
24514@end smallexample
24515
24516@c @subheading -stack-list-exception-handlers
922fbb7b 24517
a2c02241
NR
24518
24519@subheading The @code{-stack-list-frames} Command
24520@findex -stack-list-frames
1abaf70c
BR
24521
24522@subsubheading Synopsis
24523
24524@smallexample
a2c02241 24525 -stack-list-frames [ @var{low-frame} @var{high-frame} ]
1abaf70c
BR
24526@end smallexample
24527
a2c02241
NR
24528List the frames currently on the stack. For each frame it displays the
24529following info:
24530
24531@table @samp
24532@item @var{level}
d3e8051b 24533The frame number, 0 being the topmost frame, i.e., the innermost function.
a2c02241
NR
24534@item @var{addr}
24535The @code{$pc} value for that frame.
24536@item @var{func}
24537Function name.
24538@item @var{file}
24539File name of the source file where the function lives.
24540@item @var{line}
24541Line number corresponding to the @code{$pc}.
24542@end table
24543
24544If invoked without arguments, this command prints a backtrace for the
24545whole stack. If given two integer arguments, it shows the frames whose
24546levels are between the two arguments (inclusive). If the two arguments
2ab1eb7a
VP
24547are equal, it shows the single frame at the corresponding level. It is
24548an error if @var{low-frame} is larger than the actual number of
a5451f4e 24549frames. On the other hand, @var{high-frame} may be larger than the
2ab1eb7a 24550actual number of frames, in which case only existing frames will be returned.
1abaf70c
BR
24551
24552@subsubheading @value{GDBN} Command
24553
a2c02241 24554The corresponding @value{GDBN} commands are @samp{backtrace} and @samp{where}.
1abaf70c
BR
24555
24556@subsubheading Example
24557
a2c02241
NR
24558Full stack backtrace:
24559
1abaf70c 24560@smallexample
594fe323 24561(gdb)
a2c02241
NR
24562-stack-list-frames
24563^done,stack=
24564[frame=@{level="0",addr="0x0001076c",func="foo",
24565 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="11"@},
24566frame=@{level="1",addr="0x000107a4",func="foo",
24567 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
24568frame=@{level="2",addr="0x000107a4",func="foo",
24569 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
24570frame=@{level="3",addr="0x000107a4",func="foo",
24571 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
24572frame=@{level="4",addr="0x000107a4",func="foo",
24573 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
24574frame=@{level="5",addr="0x000107a4",func="foo",
24575 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
24576frame=@{level="6",addr="0x000107a4",func="foo",
24577 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
24578frame=@{level="7",addr="0x000107a4",func="foo",
24579 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
24580frame=@{level="8",addr="0x000107a4",func="foo",
24581 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
24582frame=@{level="9",addr="0x000107a4",func="foo",
24583 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
24584frame=@{level="10",addr="0x000107a4",func="foo",
24585 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
24586frame=@{level="11",addr="0x00010738",func="main",
24587 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="4"@}]
594fe323 24588(gdb)
1abaf70c
BR
24589@end smallexample
24590
a2c02241 24591Show frames between @var{low_frame} and @var{high_frame}:
1abaf70c 24592
a2c02241 24593@smallexample
594fe323 24594(gdb)
a2c02241
NR
24595-stack-list-frames 3 5
24596^done,stack=
24597[frame=@{level="3",addr="0x000107a4",func="foo",
24598 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
24599frame=@{level="4",addr="0x000107a4",func="foo",
24600 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
24601frame=@{level="5",addr="0x000107a4",func="foo",
24602 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@}]
594fe323 24603(gdb)
a2c02241 24604@end smallexample
922fbb7b 24605
a2c02241 24606Show a single frame:
922fbb7b
AC
24607
24608@smallexample
594fe323 24609(gdb)
a2c02241
NR
24610-stack-list-frames 3 3
24611^done,stack=
24612[frame=@{level="3",addr="0x000107a4",func="foo",
24613 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@}]
594fe323 24614(gdb)
922fbb7b
AC
24615@end smallexample
24616
922fbb7b 24617
a2c02241
NR
24618@subheading The @code{-stack-list-locals} Command
24619@findex -stack-list-locals
57c22c6c 24620
a2c02241 24621@subsubheading Synopsis
922fbb7b
AC
24622
24623@smallexample
a2c02241 24624 -stack-list-locals @var{print-values}
922fbb7b
AC
24625@end smallexample
24626
a2c02241
NR
24627Display the local variable names for the selected frame. If
24628@var{print-values} is 0 or @code{--no-values}, print only the names of
24629the variables; if it is 1 or @code{--all-values}, print also their
24630values; and if it is 2 or @code{--simple-values}, print the name,
3afae151 24631type and value for simple data types, and the name and type for arrays,
a2c02241
NR
24632structures and unions. In this last case, a frontend can immediately
24633display the value of simple data types and create variable objects for
d3e8051b 24634other data types when the user wishes to explore their values in
a2c02241 24635more detail.
922fbb7b 24636
b3372f91
VP
24637This command is deprecated in favor of the
24638@samp{-stack-list-variables} command.
24639
922fbb7b
AC
24640@subsubheading @value{GDBN} Command
24641
a2c02241 24642@samp{info locals} in @value{GDBN}, @samp{gdb_get_locals} in @code{gdbtk}.
922fbb7b
AC
24643
24644@subsubheading Example
922fbb7b
AC
24645
24646@smallexample
594fe323 24647(gdb)
a2c02241
NR
24648-stack-list-locals 0
24649^done,locals=[name="A",name="B",name="C"]
594fe323 24650(gdb)
a2c02241
NR
24651-stack-list-locals --all-values
24652^done,locals=[@{name="A",value="1"@},@{name="B",value="2"@},
24653 @{name="C",value="@{1, 2, 3@}"@}]
24654-stack-list-locals --simple-values
24655^done,locals=[@{name="A",type="int",value="1"@},
24656 @{name="B",type="int",value="2"@},@{name="C",type="int [3]"@}]
594fe323 24657(gdb)
922fbb7b
AC
24658@end smallexample
24659
b3372f91
VP
24660@subheading The @code{-stack-list-variables} Command
24661@findex -stack-list-variables
24662
24663@subsubheading Synopsis
24664
24665@smallexample
24666 -stack-list-variables @var{print-values}
24667@end smallexample
24668
24669Display the names of local variables and function arguments for the selected frame. If
24670@var{print-values} is 0 or @code{--no-values}, print only the names of
24671the variables; if it is 1 or @code{--all-values}, print also their
24672values; and if it is 2 or @code{--simple-values}, print the name,
3afae151 24673type and value for simple data types, and the name and type for arrays,
b3372f91
VP
24674structures and unions.
24675
24676@subsubheading Example
24677
24678@smallexample
24679(gdb)
24680-stack-list-variables --thread 1 --frame 0 --all-values
4f412fd0 24681^done,variables=[@{name="x",value="11"@},@{name="s",value="@{a = 1, b = 2@}"@}]
b3372f91
VP
24682(gdb)
24683@end smallexample
24684
922fbb7b 24685
a2c02241
NR
24686@subheading The @code{-stack-select-frame} Command
24687@findex -stack-select-frame
922fbb7b
AC
24688
24689@subsubheading Synopsis
24690
24691@smallexample
a2c02241 24692 -stack-select-frame @var{framenum}
922fbb7b
AC
24693@end smallexample
24694
a2c02241
NR
24695Change the selected frame. Select a different frame @var{framenum} on
24696the stack.
922fbb7b 24697
c3b108f7
VP
24698This command in deprecated in favor of passing the @samp{--frame}
24699option to every command.
24700
922fbb7b
AC
24701@subsubheading @value{GDBN} Command
24702
a2c02241
NR
24703The corresponding @value{GDBN} commands are @samp{frame}, @samp{up},
24704@samp{down}, @samp{select-frame}, @samp{up-silent}, and @samp{down-silent}.
922fbb7b
AC
24705
24706@subsubheading Example
24707
24708@smallexample
594fe323 24709(gdb)
a2c02241 24710-stack-select-frame 2
922fbb7b 24711^done
594fe323 24712(gdb)
922fbb7b
AC
24713@end smallexample
24714
24715@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
a2c02241
NR
24716@node GDB/MI Variable Objects
24717@section @sc{gdb/mi} Variable Objects
922fbb7b 24718
a1b5960f 24719@ignore
922fbb7b 24720
a2c02241 24721@subheading Motivation for Variable Objects in @sc{gdb/mi}
922fbb7b 24722
a2c02241
NR
24723For the implementation of a variable debugger window (locals, watched
24724expressions, etc.), we are proposing the adaptation of the existing code
24725used by @code{Insight}.
922fbb7b 24726
a2c02241 24727The two main reasons for that are:
922fbb7b 24728
a2c02241
NR
24729@enumerate 1
24730@item
24731It has been proven in practice (it is already on its second generation).
922fbb7b 24732
a2c02241
NR
24733@item
24734It will shorten development time (needless to say how important it is
24735now).
24736@end enumerate
922fbb7b 24737
a2c02241
NR
24738The original interface was designed to be used by Tcl code, so it was
24739slightly changed so it could be used through @sc{gdb/mi}. This section
24740describes the @sc{gdb/mi} operations that will be available and gives some
24741hints about their use.
922fbb7b 24742
a2c02241
NR
24743@emph{Note}: In addition to the set of operations described here, we
24744expect the @sc{gui} implementation of a variable window to require, at
24745least, the following operations:
922fbb7b 24746
a2c02241
NR
24747@itemize @bullet
24748@item @code{-gdb-show} @code{output-radix}
24749@item @code{-stack-list-arguments}
24750@item @code{-stack-list-locals}
24751@item @code{-stack-select-frame}
24752@end itemize
922fbb7b 24753
a1b5960f
VP
24754@end ignore
24755
c8b2f53c 24756@subheading Introduction to Variable Objects
922fbb7b 24757
a2c02241 24758@cindex variable objects in @sc{gdb/mi}
c8b2f53c
VP
24759
24760Variable objects are "object-oriented" MI interface for examining and
24761changing values of expressions. Unlike some other MI interfaces that
24762work with expressions, variable objects are specifically designed for
24763simple and efficient presentation in the frontend. A variable object
24764is identified by string name. When a variable object is created, the
24765frontend specifies the expression for that variable object. The
24766expression can be a simple variable, or it can be an arbitrary complex
24767expression, and can even involve CPU registers. After creating a
24768variable object, the frontend can invoke other variable object
24769operations---for example to obtain or change the value of a variable
24770object, or to change display format.
24771
24772Variable objects have hierarchical tree structure. Any variable object
24773that corresponds to a composite type, such as structure in C, has
24774a number of child variable objects, for example corresponding to each
24775element of a structure. A child variable object can itself have
24776children, recursively. Recursion ends when we reach
25d5ea92
VP
24777leaf variable objects, which always have built-in types. Child variable
24778objects are created only by explicit request, so if a frontend
24779is not interested in the children of a particular variable object, no
24780child will be created.
c8b2f53c
VP
24781
24782For a leaf variable object it is possible to obtain its value as a
24783string, or set the value from a string. String value can be also
24784obtained for a non-leaf variable object, but it's generally a string
24785that only indicates the type of the object, and does not list its
24786contents. Assignment to a non-leaf variable object is not allowed.
24787
24788A frontend does not need to read the values of all variable objects each time
24789the program stops. Instead, MI provides an update command that lists all
24790variable objects whose values has changed since the last update
24791operation. This considerably reduces the amount of data that must
25d5ea92
VP
24792be transferred to the frontend. As noted above, children variable
24793objects are created on demand, and only leaf variable objects have a
24794real value. As result, gdb will read target memory only for leaf
24795variables that frontend has created.
24796
24797The automatic update is not always desirable. For example, a frontend
24798might want to keep a value of some expression for future reference,
24799and never update it. For another example, fetching memory is
24800relatively slow for embedded targets, so a frontend might want
24801to disable automatic update for the variables that are either not
24802visible on the screen, or ``closed''. This is possible using so
24803called ``frozen variable objects''. Such variable objects are never
24804implicitly updated.
922fbb7b 24805
c3b108f7
VP
24806Variable objects can be either @dfn{fixed} or @dfn{floating}. For the
24807fixed variable object, the expression is parsed when the variable
24808object is created, including associating identifiers to specific
24809variables. The meaning of expression never changes. For a floating
24810variable object the values of variables whose names appear in the
24811expressions are re-evaluated every time in the context of the current
24812frame. Consider this example:
24813
24814@smallexample
24815void do_work(...)
24816@{
24817 struct work_state state;
24818
24819 if (...)
24820 do_work(...);
24821@}
24822@end smallexample
24823
24824If a fixed variable object for the @code{state} variable is created in
24825this function, and we enter the recursive call, the the variable
24826object will report the value of @code{state} in the top-level
24827@code{do_work} invocation. On the other hand, a floating variable
24828object will report the value of @code{state} in the current frame.
24829
24830If an expression specified when creating a fixed variable object
24831refers to a local variable, the variable object becomes bound to the
24832thread and frame in which the variable object is created. When such
24833variable object is updated, @value{GDBN} makes sure that the
24834thread/frame combination the variable object is bound to still exists,
24835and re-evaluates the variable object in context of that thread/frame.
24836
a2c02241
NR
24837The following is the complete set of @sc{gdb/mi} operations defined to
24838access this functionality:
922fbb7b 24839
a2c02241
NR
24840@multitable @columnfractions .4 .6
24841@item @strong{Operation}
24842@tab @strong{Description}
922fbb7b 24843
0cc7d26f
TT
24844@item @code{-enable-pretty-printing}
24845@tab enable Python-based pretty-printing
a2c02241
NR
24846@item @code{-var-create}
24847@tab create a variable object
24848@item @code{-var-delete}
22d8a470 24849@tab delete the variable object and/or its children
a2c02241
NR
24850@item @code{-var-set-format}
24851@tab set the display format of this variable
24852@item @code{-var-show-format}
24853@tab show the display format of this variable
24854@item @code{-var-info-num-children}
24855@tab tells how many children this object has
24856@item @code{-var-list-children}
24857@tab return a list of the object's children
24858@item @code{-var-info-type}
24859@tab show the type of this variable object
24860@item @code{-var-info-expression}
02142340
VP
24861@tab print parent-relative expression that this variable object represents
24862@item @code{-var-info-path-expression}
24863@tab print full expression that this variable object represents
a2c02241
NR
24864@item @code{-var-show-attributes}
24865@tab is this variable editable? does it exist here?
24866@item @code{-var-evaluate-expression}
24867@tab get the value of this variable
24868@item @code{-var-assign}
24869@tab set the value of this variable
24870@item @code{-var-update}
24871@tab update the variable and its children
25d5ea92
VP
24872@item @code{-var-set-frozen}
24873@tab set frozeness attribute
0cc7d26f
TT
24874@item @code{-var-set-update-range}
24875@tab set range of children to display on update
a2c02241 24876@end multitable
922fbb7b 24877
a2c02241
NR
24878In the next subsection we describe each operation in detail and suggest
24879how it can be used.
922fbb7b 24880
a2c02241 24881@subheading Description And Use of Operations on Variable Objects
922fbb7b 24882
0cc7d26f
TT
24883@subheading The @code{-enable-pretty-printing} Command
24884@findex -enable-pretty-printing
24885
24886@smallexample
24887-enable-pretty-printing
24888@end smallexample
24889
24890@value{GDBN} allows Python-based visualizers to affect the output of the
24891MI variable object commands. However, because there was no way to
24892implement this in a fully backward-compatible way, a front end must
24893request that this functionality be enabled.
24894
24895Once enabled, this feature cannot be disabled.
24896
24897Note that if Python support has not been compiled into @value{GDBN},
24898this command will still succeed (and do nothing).
24899
f43030c4
TT
24900This feature is currently (as of @value{GDBN} 7.0) experimental, and
24901may work differently in future versions of @value{GDBN}.
24902
a2c02241
NR
24903@subheading The @code{-var-create} Command
24904@findex -var-create
ef21caaf 24905
a2c02241 24906@subsubheading Synopsis
ef21caaf 24907
a2c02241
NR
24908@smallexample
24909 -var-create @{@var{name} | "-"@}
c3b108f7 24910 @{@var{frame-addr} | "*" | "@@"@} @var{expression}
a2c02241
NR
24911@end smallexample
24912
24913This operation creates a variable object, which allows the monitoring of
24914a variable, the result of an expression, a memory cell or a CPU
24915register.
ef21caaf 24916
a2c02241
NR
24917The @var{name} parameter is the string by which the object can be
24918referenced. It must be unique. If @samp{-} is specified, the varobj
24919system will generate a string ``varNNNNNN'' automatically. It will be
c3b108f7 24920unique provided that one does not specify @var{name} of that format.
a2c02241 24921The command fails if a duplicate name is found.
ef21caaf 24922
a2c02241
NR
24923The frame under which the expression should be evaluated can be
24924specified by @var{frame-addr}. A @samp{*} indicates that the current
c3b108f7
VP
24925frame should be used. A @samp{@@} indicates that a floating variable
24926object must be created.
922fbb7b 24927
a2c02241
NR
24928@var{expression} is any expression valid on the current language set (must not
24929begin with a @samp{*}), or one of the following:
922fbb7b 24930
a2c02241
NR
24931@itemize @bullet
24932@item
24933@samp{*@var{addr}}, where @var{addr} is the address of a memory cell
922fbb7b 24934
a2c02241
NR
24935@item
24936@samp{*@var{addr}-@var{addr}} --- a memory address range (TBD)
922fbb7b 24937
a2c02241
NR
24938@item
24939@samp{$@var{regname}} --- a CPU register name
24940@end itemize
922fbb7b 24941
0cc7d26f
TT
24942@cindex dynamic varobj
24943A varobj's contents may be provided by a Python-based pretty-printer. In this
24944case the varobj is known as a @dfn{dynamic varobj}. Dynamic varobjs
24945have slightly different semantics in some cases. If the
24946@code{-enable-pretty-printing} command is not sent, then @value{GDBN}
24947will never create a dynamic varobj. This ensures backward
24948compatibility for existing clients.
24949
a2c02241 24950@subsubheading Result
922fbb7b 24951
0cc7d26f
TT
24952This operation returns attributes of the newly-created varobj. These
24953are:
24954
24955@table @samp
24956@item name
24957The name of the varobj.
24958
24959@item numchild
24960The number of children of the varobj. This number is not necessarily
24961reliable for a dynamic varobj. Instead, you must examine the
24962@samp{has_more} attribute.
24963
24964@item value
24965The varobj's scalar value. For a varobj whose type is some sort of
24966aggregate (e.g., a @code{struct}), or for a dynamic varobj, this value
24967will not be interesting.
24968
24969@item type
24970The varobj's type. This is a string representation of the type, as
24971would be printed by the @value{GDBN} CLI.
24972
24973@item thread-id
24974If a variable object is bound to a specific thread, then this is the
24975thread's identifier.
24976
24977@item has_more
24978For a dynamic varobj, this indicates whether there appear to be any
24979children available. For a non-dynamic varobj, this will be 0.
24980
24981@item dynamic
24982This attribute will be present and have the value @samp{1} if the
24983varobj is a dynamic varobj. If the varobj is not a dynamic varobj,
24984then this attribute will not be present.
24985
24986@item displayhint
24987A dynamic varobj can supply a display hint to the front end. The
24988value comes directly from the Python pretty-printer object's
24989@code{display_hint} method. @xref{Pretty Printing}.
24990@end table
24991
24992Typical output will look like this:
922fbb7b
AC
24993
24994@smallexample
0cc7d26f
TT
24995 name="@var{name}",numchild="@var{N}",type="@var{type}",thread-id="@var{M}",
24996 has_more="@var{has_more}"
dcaaae04
NR
24997@end smallexample
24998
a2c02241
NR
24999
25000@subheading The @code{-var-delete} Command
25001@findex -var-delete
922fbb7b
AC
25002
25003@subsubheading Synopsis
25004
25005@smallexample
22d8a470 25006 -var-delete [ -c ] @var{name}
922fbb7b
AC
25007@end smallexample
25008
a2c02241 25009Deletes a previously created variable object and all of its children.
22d8a470 25010With the @samp{-c} option, just deletes the children.
922fbb7b 25011
a2c02241 25012Returns an error if the object @var{name} is not found.
922fbb7b 25013
922fbb7b 25014
a2c02241
NR
25015@subheading The @code{-var-set-format} Command
25016@findex -var-set-format
922fbb7b 25017
a2c02241 25018@subsubheading Synopsis
922fbb7b
AC
25019
25020@smallexample
a2c02241 25021 -var-set-format @var{name} @var{format-spec}
922fbb7b
AC
25022@end smallexample
25023
a2c02241
NR
25024Sets the output format for the value of the object @var{name} to be
25025@var{format-spec}.
25026
de051565 25027@anchor{-var-set-format}
a2c02241
NR
25028The syntax for the @var{format-spec} is as follows:
25029
25030@smallexample
25031 @var{format-spec} @expansion{}
25032 @{binary | decimal | hexadecimal | octal | natural@}
25033@end smallexample
25034
c8b2f53c
VP
25035The natural format is the default format choosen automatically
25036based on the variable type (like decimal for an @code{int}, hex
25037for pointers, etc.).
25038
25039For a variable with children, the format is set only on the
25040variable itself, and the children are not affected.
a2c02241
NR
25041
25042@subheading The @code{-var-show-format} Command
25043@findex -var-show-format
922fbb7b
AC
25044
25045@subsubheading Synopsis
25046
25047@smallexample
a2c02241 25048 -var-show-format @var{name}
922fbb7b
AC
25049@end smallexample
25050
a2c02241 25051Returns the format used to display the value of the object @var{name}.
922fbb7b 25052
a2c02241
NR
25053@smallexample
25054 @var{format} @expansion{}
25055 @var{format-spec}
25056@end smallexample
922fbb7b 25057
922fbb7b 25058
a2c02241
NR
25059@subheading The @code{-var-info-num-children} Command
25060@findex -var-info-num-children
25061
25062@subsubheading Synopsis
25063
25064@smallexample
25065 -var-info-num-children @var{name}
25066@end smallexample
25067
25068Returns the number of children of a variable object @var{name}:
25069
25070@smallexample
25071 numchild=@var{n}
25072@end smallexample
25073
0cc7d26f
TT
25074Note that this number is not completely reliable for a dynamic varobj.
25075It will return the current number of children, but more children may
25076be available.
25077
a2c02241
NR
25078
25079@subheading The @code{-var-list-children} Command
25080@findex -var-list-children
25081
25082@subsubheading Synopsis
25083
25084@smallexample
0cc7d26f 25085 -var-list-children [@var{print-values}] @var{name} [@var{from} @var{to}]
a2c02241 25086@end smallexample
b569d230 25087@anchor{-var-list-children}
a2c02241
NR
25088
25089Return a list of the children of the specified variable object and
25090create variable objects for them, if they do not already exist. With
25091a single argument or if @var{print-values} has a value for of 0 or
25092@code{--no-values}, print only the names of the variables; if
25093@var{print-values} is 1 or @code{--all-values}, also print their
25094values; and if it is 2 or @code{--simple-values} print the name and
25095value for simple data types and just the name for arrays, structures
25096and unions.
922fbb7b 25097
0cc7d26f
TT
25098@var{from} and @var{to}, if specified, indicate the range of children
25099to report. If @var{from} or @var{to} is less than zero, the range is
25100reset and all children will be reported. Otherwise, children starting
25101at @var{from} (zero-based) and up to and excluding @var{to} will be
25102reported.
25103
25104If a child range is requested, it will only affect the current call to
25105@code{-var-list-children}, but not future calls to @code{-var-update}.
25106For this, you must instead use @code{-var-set-update-range}. The
25107intent of this approach is to enable a front end to implement any
25108update approach it likes; for example, scrolling a view may cause the
25109front end to request more children with @code{-var-list-children}, and
25110then the front end could call @code{-var-set-update-range} with a
25111different range to ensure that future updates are restricted to just
25112the visible items.
25113
b569d230
EZ
25114For each child the following results are returned:
25115
25116@table @var
25117
25118@item name
25119Name of the variable object created for this child.
25120
25121@item exp
25122The expression to be shown to the user by the front end to designate this child.
25123For example this may be the name of a structure member.
25124
0cc7d26f
TT
25125For a dynamic varobj, this value cannot be used to form an
25126expression. There is no way to do this at all with a dynamic varobj.
25127
b569d230
EZ
25128For C/C@t{++} structures there are several pseudo children returned to
25129designate access qualifiers. For these pseudo children @var{exp} is
25130@samp{public}, @samp{private}, or @samp{protected}. In this case the
25131type and value are not present.
25132
0cc7d26f
TT
25133A dynamic varobj will not report the access qualifying
25134pseudo-children, regardless of the language. This information is not
25135available at all with a dynamic varobj.
25136
b569d230 25137@item numchild
0cc7d26f
TT
25138Number of children this child has. For a dynamic varobj, this will be
251390.
b569d230
EZ
25140
25141@item type
25142The type of the child.
25143
25144@item value
25145If values were requested, this is the value.
25146
25147@item thread-id
25148If this variable object is associated with a thread, this is the thread id.
25149Otherwise this result is not present.
25150
25151@item frozen
25152If the variable object is frozen, this variable will be present with a value of 1.
25153@end table
25154
0cc7d26f
TT
25155The result may have its own attributes:
25156
25157@table @samp
25158@item displayhint
25159A dynamic varobj can supply a display hint to the front end. The
25160value comes directly from the Python pretty-printer object's
25161@code{display_hint} method. @xref{Pretty Printing}.
25162
25163@item has_more
25164This is an integer attribute which is nonzero if there are children
25165remaining after the end of the selected range.
25166@end table
25167
922fbb7b
AC
25168@subsubheading Example
25169
25170@smallexample
594fe323 25171(gdb)
a2c02241 25172 -var-list-children n
b569d230 25173 ^done,numchild=@var{n},children=[child=@{name=@var{name},exp=@var{exp},
a2c02241 25174 numchild=@var{n},type=@var{type}@},@r{(repeats N times)}]
594fe323 25175(gdb)
a2c02241 25176 -var-list-children --all-values n
b569d230 25177 ^done,numchild=@var{n},children=[child=@{name=@var{name},exp=@var{exp},
a2c02241 25178 numchild=@var{n},value=@var{value},type=@var{type}@},@r{(repeats N times)}]
922fbb7b
AC
25179@end smallexample
25180
922fbb7b 25181
a2c02241
NR
25182@subheading The @code{-var-info-type} Command
25183@findex -var-info-type
922fbb7b 25184
a2c02241
NR
25185@subsubheading Synopsis
25186
25187@smallexample
25188 -var-info-type @var{name}
25189@end smallexample
25190
25191Returns the type of the specified variable @var{name}. The type is
25192returned as a string in the same format as it is output by the
25193@value{GDBN} CLI:
25194
25195@smallexample
25196 type=@var{typename}
25197@end smallexample
25198
25199
25200@subheading The @code{-var-info-expression} Command
25201@findex -var-info-expression
922fbb7b
AC
25202
25203@subsubheading Synopsis
25204
25205@smallexample
a2c02241 25206 -var-info-expression @var{name}
922fbb7b
AC
25207@end smallexample
25208
02142340
VP
25209Returns a string that is suitable for presenting this
25210variable object in user interface. The string is generally
25211not valid expression in the current language, and cannot be evaluated.
25212
25213For example, if @code{a} is an array, and variable object
25214@code{A} was created for @code{a}, then we'll get this output:
922fbb7b 25215
a2c02241 25216@smallexample
02142340
VP
25217(gdb) -var-info-expression A.1
25218^done,lang="C",exp="1"
a2c02241 25219@end smallexample
922fbb7b 25220
a2c02241 25221@noindent
02142340
VP
25222Here, the values of @code{lang} can be @code{@{"C" | "C++" | "Java"@}}.
25223
25224Note that the output of the @code{-var-list-children} command also
25225includes those expressions, so the @code{-var-info-expression} command
25226is of limited use.
25227
25228@subheading The @code{-var-info-path-expression} Command
25229@findex -var-info-path-expression
25230
25231@subsubheading Synopsis
25232
25233@smallexample
25234 -var-info-path-expression @var{name}
25235@end smallexample
25236
25237Returns an expression that can be evaluated in the current
25238context and will yield the same value that a variable object has.
25239Compare this with the @code{-var-info-expression} command, which
25240result can be used only for UI presentation. Typical use of
25241the @code{-var-info-path-expression} command is creating a
25242watchpoint from a variable object.
25243
0cc7d26f
TT
25244This command is currently not valid for children of a dynamic varobj,
25245and will give an error when invoked on one.
25246
02142340
VP
25247For example, suppose @code{C} is a C@t{++} class, derived from class
25248@code{Base}, and that the @code{Base} class has a member called
25249@code{m_size}. Assume a variable @code{c} is has the type of
25250@code{C} and a variable object @code{C} was created for variable
25251@code{c}. Then, we'll get this output:
25252@smallexample
25253(gdb) -var-info-path-expression C.Base.public.m_size
25254^done,path_expr=((Base)c).m_size)
25255@end smallexample
922fbb7b 25256
a2c02241
NR
25257@subheading The @code{-var-show-attributes} Command
25258@findex -var-show-attributes
922fbb7b 25259
a2c02241 25260@subsubheading Synopsis
922fbb7b 25261
a2c02241
NR
25262@smallexample
25263 -var-show-attributes @var{name}
25264@end smallexample
922fbb7b 25265
a2c02241 25266List attributes of the specified variable object @var{name}:
922fbb7b
AC
25267
25268@smallexample
a2c02241 25269 status=@var{attr} [ ( ,@var{attr} )* ]
922fbb7b
AC
25270@end smallexample
25271
a2c02241
NR
25272@noindent
25273where @var{attr} is @code{@{ @{ editable | noneditable @} | TBD @}}.
25274
25275@subheading The @code{-var-evaluate-expression} Command
25276@findex -var-evaluate-expression
25277
25278@subsubheading Synopsis
25279
25280@smallexample
de051565 25281 -var-evaluate-expression [-f @var{format-spec}] @var{name}
a2c02241
NR
25282@end smallexample
25283
25284Evaluates the expression that is represented by the specified variable
de051565
MK
25285object and returns its value as a string. The format of the string
25286can be specified with the @samp{-f} option. The possible values of
25287this option are the same as for @code{-var-set-format}
25288(@pxref{-var-set-format}). If the @samp{-f} option is not specified,
25289the current display format will be used. The current display format
25290can be changed using the @code{-var-set-format} command.
a2c02241
NR
25291
25292@smallexample
25293 value=@var{value}
25294@end smallexample
25295
25296Note that one must invoke @code{-var-list-children} for a variable
25297before the value of a child variable can be evaluated.
25298
25299@subheading The @code{-var-assign} Command
25300@findex -var-assign
25301
25302@subsubheading Synopsis
25303
25304@smallexample
25305 -var-assign @var{name} @var{expression}
25306@end smallexample
25307
25308Assigns the value of @var{expression} to the variable object specified
25309by @var{name}. The object must be @samp{editable}. If the variable's
25310value is altered by the assign, the variable will show up in any
25311subsequent @code{-var-update} list.
25312
25313@subsubheading Example
922fbb7b
AC
25314
25315@smallexample
594fe323 25316(gdb)
a2c02241
NR
25317-var-assign var1 3
25318^done,value="3"
594fe323 25319(gdb)
a2c02241
NR
25320-var-update *
25321^done,changelist=[@{name="var1",in_scope="true",type_changed="false"@}]
594fe323 25322(gdb)
922fbb7b
AC
25323@end smallexample
25324
a2c02241
NR
25325@subheading The @code{-var-update} Command
25326@findex -var-update
25327
25328@subsubheading Synopsis
25329
25330@smallexample
25331 -var-update [@var{print-values}] @{@var{name} | "*"@}
25332@end smallexample
25333
c8b2f53c
VP
25334Reevaluate the expressions corresponding to the variable object
25335@var{name} and all its direct and indirect children, and return the
36ece8b3
NR
25336list of variable objects whose values have changed; @var{name} must
25337be a root variable object. Here, ``changed'' means that the result of
25338@code{-var-evaluate-expression} before and after the
25339@code{-var-update} is different. If @samp{*} is used as the variable
9f708cb2
VP
25340object names, all existing variable objects are updated, except
25341for frozen ones (@pxref{-var-set-frozen}). The option
36ece8b3 25342@var{print-values} determines whether both names and values, or just
de051565 25343names are printed. The possible values of this option are the same
36ece8b3
NR
25344as for @code{-var-list-children} (@pxref{-var-list-children}). It is
25345recommended to use the @samp{--all-values} option, to reduce the
25346number of MI commands needed on each program stop.
c8b2f53c 25347
c3b108f7
VP
25348With the @samp{*} parameter, if a variable object is bound to a
25349currently running thread, it will not be updated, without any
25350diagnostic.
a2c02241 25351
0cc7d26f
TT
25352If @code{-var-set-update-range} was previously used on a varobj, then
25353only the selected range of children will be reported.
922fbb7b 25354
0cc7d26f
TT
25355@code{-var-update} reports all the changed varobjs in a tuple named
25356@samp{changelist}.
25357
25358Each item in the change list is itself a tuple holding:
25359
25360@table @samp
25361@item name
25362The name of the varobj.
25363
25364@item value
25365If values were requested for this update, then this field will be
25366present and will hold the value of the varobj.
922fbb7b 25367
0cc7d26f 25368@item in_scope
9f708cb2 25369@anchor{-var-update}
0cc7d26f 25370This field is a string which may take one of three values:
36ece8b3
NR
25371
25372@table @code
25373@item "true"
25374The variable object's current value is valid.
25375
25376@item "false"
25377The variable object does not currently hold a valid value but it may
25378hold one in the future if its associated expression comes back into
25379scope.
25380
25381@item "invalid"
25382The variable object no longer holds a valid value.
25383This can occur when the executable file being debugged has changed,
25384either through recompilation or by using the @value{GDBN} @code{file}
25385command. The front end should normally choose to delete these variable
25386objects.
25387@end table
25388
25389In the future new values may be added to this list so the front should
25390be prepared for this possibility. @xref{GDB/MI Development and Front Ends, ,@sc{GDB/MI} Development and Front Ends}.
25391
0cc7d26f
TT
25392@item type_changed
25393This is only present if the varobj is still valid. If the type
25394changed, then this will be the string @samp{true}; otherwise it will
25395be @samp{false}.
25396
25397@item new_type
25398If the varobj's type changed, then this field will be present and will
25399hold the new type.
25400
25401@item new_num_children
25402For a dynamic varobj, if the number of children changed, or if the
25403type changed, this will be the new number of children.
25404
25405The @samp{numchild} field in other varobj responses is generally not
25406valid for a dynamic varobj -- it will show the number of children that
25407@value{GDBN} knows about, but because dynamic varobjs lazily
25408instantiate their children, this will not reflect the number of
25409children which may be available.
25410
25411The @samp{new_num_children} attribute only reports changes to the
25412number of children known by @value{GDBN}. This is the only way to
25413detect whether an update has removed children (which necessarily can
25414only happen at the end of the update range).
25415
25416@item displayhint
25417The display hint, if any.
25418
25419@item has_more
25420This is an integer value, which will be 1 if there are more children
25421available outside the varobj's update range.
25422
25423@item dynamic
25424This attribute will be present and have the value @samp{1} if the
25425varobj is a dynamic varobj. If the varobj is not a dynamic varobj,
25426then this attribute will not be present.
25427
25428@item new_children
25429If new children were added to a dynamic varobj within the selected
25430update range (as set by @code{-var-set-update-range}), then they will
25431be listed in this attribute.
25432@end table
25433
25434@subsubheading Example
25435
25436@smallexample
25437(gdb)
25438-var-assign var1 3
25439^done,value="3"
25440(gdb)
25441-var-update --all-values var1
25442^done,changelist=[@{name="var1",value="3",in_scope="true",
25443type_changed="false"@}]
25444(gdb)
25445@end smallexample
25446
25d5ea92
VP
25447@subheading The @code{-var-set-frozen} Command
25448@findex -var-set-frozen
9f708cb2 25449@anchor{-var-set-frozen}
25d5ea92
VP
25450
25451@subsubheading Synopsis
25452
25453@smallexample
9f708cb2 25454 -var-set-frozen @var{name} @var{flag}
25d5ea92
VP
25455@end smallexample
25456
9f708cb2 25457Set the frozenness flag on the variable object @var{name}. The
25d5ea92 25458@var{flag} parameter should be either @samp{1} to make the variable
9f708cb2 25459frozen or @samp{0} to make it unfrozen. If a variable object is
25d5ea92 25460frozen, then neither itself, nor any of its children, are
9f708cb2 25461implicitly updated by @code{-var-update} of
25d5ea92
VP
25462a parent variable or by @code{-var-update *}. Only
25463@code{-var-update} of the variable itself will update its value and
25464values of its children. After a variable object is unfrozen, it is
25465implicitly updated by all subsequent @code{-var-update} operations.
25466Unfreezing a variable does not update it, only subsequent
25467@code{-var-update} does.
25468
25469@subsubheading Example
25470
25471@smallexample
25472(gdb)
25473-var-set-frozen V 1
25474^done
25475(gdb)
25476@end smallexample
25477
0cc7d26f
TT
25478@subheading The @code{-var-set-update-range} command
25479@findex -var-set-update-range
25480@anchor{-var-set-update-range}
25481
25482@subsubheading Synopsis
25483
25484@smallexample
25485 -var-set-update-range @var{name} @var{from} @var{to}
25486@end smallexample
25487
25488Set the range of children to be returned by future invocations of
25489@code{-var-update}.
25490
25491@var{from} and @var{to} indicate the range of children to report. If
25492@var{from} or @var{to} is less than zero, the range is reset and all
25493children will be reported. Otherwise, children starting at @var{from}
25494(zero-based) and up to and excluding @var{to} will be reported.
25495
25496@subsubheading Example
25497
25498@smallexample
25499(gdb)
25500-var-set-update-range V 1 2
25501^done
25502@end smallexample
25503
b6313243
TT
25504@subheading The @code{-var-set-visualizer} command
25505@findex -var-set-visualizer
25506@anchor{-var-set-visualizer}
25507
25508@subsubheading Synopsis
25509
25510@smallexample
25511 -var-set-visualizer @var{name} @var{visualizer}
25512@end smallexample
25513
25514Set a visualizer for the variable object @var{name}.
25515
25516@var{visualizer} is the visualizer to use. The special value
25517@samp{None} means to disable any visualizer in use.
25518
25519If not @samp{None}, @var{visualizer} must be a Python expression.
25520This expression must evaluate to a callable object which accepts a
25521single argument. @value{GDBN} will call this object with the value of
25522the varobj @var{name} as an argument (this is done so that the same
25523Python pretty-printing code can be used for both the CLI and MI).
25524When called, this object must return an object which conforms to the
25525pretty-printing interface (@pxref{Pretty Printing}).
25526
25527The pre-defined function @code{gdb.default_visualizer} may be used to
25528select a visualizer by following the built-in process
25529(@pxref{Selecting Pretty-Printers}). This is done automatically when
25530a varobj is created, and so ordinarily is not needed.
25531
25532This feature is only available if Python support is enabled. The MI
25533command @code{-list-features} (@pxref{GDB/MI Miscellaneous Commands})
25534can be used to check this.
25535
25536@subsubheading Example
25537
25538Resetting the visualizer:
25539
25540@smallexample
25541(gdb)
25542-var-set-visualizer V None
25543^done
25544@end smallexample
25545
25546Reselecting the default (type-based) visualizer:
25547
25548@smallexample
25549(gdb)
25550-var-set-visualizer V gdb.default_visualizer
25551^done
25552@end smallexample
25553
25554Suppose @code{SomeClass} is a visualizer class. A lambda expression
25555can be used to instantiate this class for a varobj:
25556
25557@smallexample
25558(gdb)
25559-var-set-visualizer V "lambda val: SomeClass()"
25560^done
25561@end smallexample
25d5ea92 25562
a2c02241
NR
25563@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
25564@node GDB/MI Data Manipulation
25565@section @sc{gdb/mi} Data Manipulation
922fbb7b 25566
a2c02241
NR
25567@cindex data manipulation, in @sc{gdb/mi}
25568@cindex @sc{gdb/mi}, data manipulation
25569This section describes the @sc{gdb/mi} commands that manipulate data:
25570examine memory and registers, evaluate expressions, etc.
25571
25572@c REMOVED FROM THE INTERFACE.
25573@c @subheading -data-assign
25574@c Change the value of a program variable. Plenty of side effects.
79a6e687 25575@c @subsubheading GDB Command
a2c02241
NR
25576@c set variable
25577@c @subsubheading Example
25578@c N.A.
25579
25580@subheading The @code{-data-disassemble} Command
25581@findex -data-disassemble
922fbb7b
AC
25582
25583@subsubheading Synopsis
25584
25585@smallexample
a2c02241
NR
25586 -data-disassemble
25587 [ -s @var{start-addr} -e @var{end-addr} ]
25588 | [ -f @var{filename} -l @var{linenum} [ -n @var{lines} ] ]
25589 -- @var{mode}
922fbb7b
AC
25590@end smallexample
25591
a2c02241
NR
25592@noindent
25593Where:
25594
25595@table @samp
25596@item @var{start-addr}
25597is the beginning address (or @code{$pc})
25598@item @var{end-addr}
25599is the end address
25600@item @var{filename}
25601is the name of the file to disassemble
25602@item @var{linenum}
25603is the line number to disassemble around
25604@item @var{lines}
d3e8051b 25605is the number of disassembly lines to be produced. If it is -1,
a2c02241
NR
25606the whole function will be disassembled, in case no @var{end-addr} is
25607specified. If @var{end-addr} is specified as a non-zero value, and
25608@var{lines} is lower than the number of disassembly lines between
25609@var{start-addr} and @var{end-addr}, only @var{lines} lines are
25610displayed; if @var{lines} is higher than the number of lines between
25611@var{start-addr} and @var{end-addr}, only the lines up to @var{end-addr}
25612are displayed.
25613@item @var{mode}
25614is either 0 (meaning only disassembly) or 1 (meaning mixed source and
25615disassembly).
25616@end table
25617
25618@subsubheading Result
25619
25620The output for each instruction is composed of four fields:
25621
25622@itemize @bullet
25623@item Address
25624@item Func-name
25625@item Offset
25626@item Instruction
25627@end itemize
25628
25629Note that whatever included in the instruction field, is not manipulated
d3e8051b 25630directly by @sc{gdb/mi}, i.e., it is not possible to adjust its format.
922fbb7b
AC
25631
25632@subsubheading @value{GDBN} Command
25633
a2c02241 25634There's no direct mapping from this command to the CLI.
922fbb7b
AC
25635
25636@subsubheading Example
25637
a2c02241
NR
25638Disassemble from the current value of @code{$pc} to @code{$pc + 20}:
25639
922fbb7b 25640@smallexample
594fe323 25641(gdb)
a2c02241
NR
25642-data-disassemble -s $pc -e "$pc + 20" -- 0
25643^done,
25644asm_insns=[
25645@{address="0x000107c0",func-name="main",offset="4",
25646inst="mov 2, %o0"@},
25647@{address="0x000107c4",func-name="main",offset="8",
25648inst="sethi %hi(0x11800), %o2"@},
25649@{address="0x000107c8",func-name="main",offset="12",
25650inst="or %o2, 0x140, %o1\t! 0x11940 <_lib_version+8>"@},
25651@{address="0x000107cc",func-name="main",offset="16",
25652inst="sethi %hi(0x11800), %o2"@},
25653@{address="0x000107d0",func-name="main",offset="20",
25654inst="or %o2, 0x168, %o4\t! 0x11968 <_lib_version+48>"@}]
594fe323 25655(gdb)
a2c02241
NR
25656@end smallexample
25657
25658Disassemble the whole @code{main} function. Line 32 is part of
25659@code{main}.
25660
25661@smallexample
25662-data-disassemble -f basics.c -l 32 -- 0
25663^done,asm_insns=[
25664@{address="0x000107bc",func-name="main",offset="0",
25665inst="save %sp, -112, %sp"@},
25666@{address="0x000107c0",func-name="main",offset="4",
25667inst="mov 2, %o0"@},
25668@{address="0x000107c4",func-name="main",offset="8",
25669inst="sethi %hi(0x11800), %o2"@},
25670[@dots{}]
25671@{address="0x0001081c",func-name="main",offset="96",inst="ret "@},
25672@{address="0x00010820",func-name="main",offset="100",inst="restore "@}]
594fe323 25673(gdb)
922fbb7b
AC
25674@end smallexample
25675
a2c02241 25676Disassemble 3 instructions from the start of @code{main}:
922fbb7b 25677
a2c02241 25678@smallexample
594fe323 25679(gdb)
a2c02241
NR
25680-data-disassemble -f basics.c -l 32 -n 3 -- 0
25681^done,asm_insns=[
25682@{address="0x000107bc",func-name="main",offset="0",
25683inst="save %sp, -112, %sp"@},
25684@{address="0x000107c0",func-name="main",offset="4",
25685inst="mov 2, %o0"@},
25686@{address="0x000107c4",func-name="main",offset="8",
25687inst="sethi %hi(0x11800), %o2"@}]
594fe323 25688(gdb)
a2c02241
NR
25689@end smallexample
25690
25691Disassemble 3 instructions from the start of @code{main} in mixed mode:
25692
25693@smallexample
594fe323 25694(gdb)
a2c02241
NR
25695-data-disassemble -f basics.c -l 32 -n 3 -- 1
25696^done,asm_insns=[
25697src_and_asm_line=@{line="31",
25698file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \
25699 testsuite/gdb.mi/basics.c",line_asm_insn=[
25700@{address="0x000107bc",func-name="main",offset="0",
25701inst="save %sp, -112, %sp"@}]@},
25702src_and_asm_line=@{line="32",
25703file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \
25704 testsuite/gdb.mi/basics.c",line_asm_insn=[
25705@{address="0x000107c0",func-name="main",offset="4",
25706inst="mov 2, %o0"@},
25707@{address="0x000107c4",func-name="main",offset="8",
25708inst="sethi %hi(0x11800), %o2"@}]@}]
594fe323 25709(gdb)
a2c02241
NR
25710@end smallexample
25711
25712
25713@subheading The @code{-data-evaluate-expression} Command
25714@findex -data-evaluate-expression
922fbb7b
AC
25715
25716@subsubheading Synopsis
25717
25718@smallexample
a2c02241 25719 -data-evaluate-expression @var{expr}
922fbb7b
AC
25720@end smallexample
25721
a2c02241
NR
25722Evaluate @var{expr} as an expression. The expression could contain an
25723inferior function call. The function call will execute synchronously.
25724If the expression contains spaces, it must be enclosed in double quotes.
922fbb7b
AC
25725
25726@subsubheading @value{GDBN} Command
25727
a2c02241
NR
25728The corresponding @value{GDBN} commands are @samp{print}, @samp{output}, and
25729@samp{call}. In @code{gdbtk} only, there's a corresponding
25730@samp{gdb_eval} command.
922fbb7b
AC
25731
25732@subsubheading Example
25733
a2c02241
NR
25734In the following example, the numbers that precede the commands are the
25735@dfn{tokens} described in @ref{GDB/MI Command Syntax, ,@sc{gdb/mi}
25736Command Syntax}. Notice how @sc{gdb/mi} returns the same tokens in its
25737output.
25738
922fbb7b 25739@smallexample
a2c02241
NR
25740211-data-evaluate-expression A
25741211^done,value="1"
594fe323 25742(gdb)
a2c02241
NR
25743311-data-evaluate-expression &A
25744311^done,value="0xefffeb7c"
594fe323 25745(gdb)
a2c02241
NR
25746411-data-evaluate-expression A+3
25747411^done,value="4"
594fe323 25748(gdb)
a2c02241
NR
25749511-data-evaluate-expression "A + 3"
25750511^done,value="4"
594fe323 25751(gdb)
a2c02241 25752@end smallexample
922fbb7b
AC
25753
25754
a2c02241
NR
25755@subheading The @code{-data-list-changed-registers} Command
25756@findex -data-list-changed-registers
922fbb7b
AC
25757
25758@subsubheading Synopsis
25759
25760@smallexample
a2c02241 25761 -data-list-changed-registers
922fbb7b
AC
25762@end smallexample
25763
a2c02241 25764Display a list of the registers that have changed.
922fbb7b
AC
25765
25766@subsubheading @value{GDBN} Command
25767
a2c02241
NR
25768@value{GDBN} doesn't have a direct analog for this command; @code{gdbtk}
25769has the corresponding command @samp{gdb_changed_register_list}.
922fbb7b
AC
25770
25771@subsubheading Example
922fbb7b 25772
a2c02241 25773On a PPC MBX board:
922fbb7b
AC
25774
25775@smallexample
594fe323 25776(gdb)
a2c02241
NR
25777-exec-continue
25778^running
922fbb7b 25779
594fe323 25780(gdb)
a47ec5fe
AR
25781*stopped,reason="breakpoint-hit",disp="keep",bkptno="1",frame=@{
25782func="main",args=[],file="try.c",fullname="/home/foo/bar/try.c",
25783line="5"@}
594fe323 25784(gdb)
a2c02241
NR
25785-data-list-changed-registers
25786^done,changed-registers=["0","1","2","4","5","6","7","8","9",
25787"10","11","13","14","15","16","17","18","19","20","21","22","23",
25788"24","25","26","27","28","30","31","64","65","66","67","69"]
594fe323 25789(gdb)
a2c02241 25790@end smallexample
922fbb7b
AC
25791
25792
a2c02241
NR
25793@subheading The @code{-data-list-register-names} Command
25794@findex -data-list-register-names
922fbb7b
AC
25795
25796@subsubheading Synopsis
25797
25798@smallexample
a2c02241 25799 -data-list-register-names [ ( @var{regno} )+ ]
922fbb7b
AC
25800@end smallexample
25801
a2c02241
NR
25802Show a list of register names for the current target. If no arguments
25803are given, it shows a list of the names of all the registers. If
25804integer numbers are given as arguments, it will print a list of the
25805names of the registers corresponding to the arguments. To ensure
25806consistency between a register name and its number, the output list may
25807include empty register names.
922fbb7b
AC
25808
25809@subsubheading @value{GDBN} Command
25810
a2c02241
NR
25811@value{GDBN} does not have a command which corresponds to
25812@samp{-data-list-register-names}. In @code{gdbtk} there is a
25813corresponding command @samp{gdb_regnames}.
922fbb7b
AC
25814
25815@subsubheading Example
922fbb7b 25816
a2c02241
NR
25817For the PPC MBX board:
25818@smallexample
594fe323 25819(gdb)
a2c02241
NR
25820-data-list-register-names
25821^done,register-names=["r0","r1","r2","r3","r4","r5","r6","r7",
25822"r8","r9","r10","r11","r12","r13","r14","r15","r16","r17","r18",
25823"r19","r20","r21","r22","r23","r24","r25","r26","r27","r28","r29",
25824"r30","r31","f0","f1","f2","f3","f4","f5","f6","f7","f8","f9",
25825"f10","f11","f12","f13","f14","f15","f16","f17","f18","f19","f20",
25826"f21","f22","f23","f24","f25","f26","f27","f28","f29","f30","f31",
25827"", "pc","ps","cr","lr","ctr","xer"]
594fe323 25828(gdb)
a2c02241
NR
25829-data-list-register-names 1 2 3
25830^done,register-names=["r1","r2","r3"]
594fe323 25831(gdb)
a2c02241 25832@end smallexample
922fbb7b 25833
a2c02241
NR
25834@subheading The @code{-data-list-register-values} Command
25835@findex -data-list-register-values
922fbb7b
AC
25836
25837@subsubheading Synopsis
25838
25839@smallexample
a2c02241 25840 -data-list-register-values @var{fmt} [ ( @var{regno} )*]
922fbb7b
AC
25841@end smallexample
25842
a2c02241
NR
25843Display the registers' contents. @var{fmt} is the format according to
25844which the registers' contents are to be returned, followed by an optional
25845list of numbers specifying the registers to display. A missing list of
25846numbers indicates that the contents of all the registers must be returned.
25847
25848Allowed formats for @var{fmt} are:
25849
25850@table @code
25851@item x
25852Hexadecimal
25853@item o
25854Octal
25855@item t
25856Binary
25857@item d
25858Decimal
25859@item r
25860Raw
25861@item N
25862Natural
25863@end table
922fbb7b
AC
25864
25865@subsubheading @value{GDBN} Command
25866
a2c02241
NR
25867The corresponding @value{GDBN} commands are @samp{info reg}, @samp{info
25868all-reg}, and (in @code{gdbtk}) @samp{gdb_fetch_registers}.
922fbb7b
AC
25869
25870@subsubheading Example
922fbb7b 25871
a2c02241
NR
25872For a PPC MBX board (note: line breaks are for readability only, they
25873don't appear in the actual output):
25874
25875@smallexample
594fe323 25876(gdb)
a2c02241
NR
25877-data-list-register-values r 64 65
25878^done,register-values=[@{number="64",value="0xfe00a300"@},
25879@{number="65",value="0x00029002"@}]
594fe323 25880(gdb)
a2c02241
NR
25881-data-list-register-values x
25882^done,register-values=[@{number="0",value="0xfe0043c8"@},
25883@{number="1",value="0x3fff88"@},@{number="2",value="0xfffffffe"@},
25884@{number="3",value="0x0"@},@{number="4",value="0xa"@},
25885@{number="5",value="0x3fff68"@},@{number="6",value="0x3fff58"@},
25886@{number="7",value="0xfe011e98"@},@{number="8",value="0x2"@},
25887@{number="9",value="0xfa202820"@},@{number="10",value="0xfa202808"@},
25888@{number="11",value="0x1"@},@{number="12",value="0x0"@},
25889@{number="13",value="0x4544"@},@{number="14",value="0xffdfffff"@},
25890@{number="15",value="0xffffffff"@},@{number="16",value="0xfffffeff"@},
25891@{number="17",value="0xefffffed"@},@{number="18",value="0xfffffffe"@},
25892@{number="19",value="0xffffffff"@},@{number="20",value="0xffffffff"@},
25893@{number="21",value="0xffffffff"@},@{number="22",value="0xfffffff7"@},
25894@{number="23",value="0xffffffff"@},@{number="24",value="0xffffffff"@},
25895@{number="25",value="0xffffffff"@},@{number="26",value="0xfffffffb"@},
25896@{number="27",value="0xffffffff"@},@{number="28",value="0xf7bfffff"@},
25897@{number="29",value="0x0"@},@{number="30",value="0xfe010000"@},
25898@{number="31",value="0x0"@},@{number="32",value="0x0"@},
25899@{number="33",value="0x0"@},@{number="34",value="0x0"@},
25900@{number="35",value="0x0"@},@{number="36",value="0x0"@},
25901@{number="37",value="0x0"@},@{number="38",value="0x0"@},
25902@{number="39",value="0x0"@},@{number="40",value="0x0"@},
25903@{number="41",value="0x0"@},@{number="42",value="0x0"@},
25904@{number="43",value="0x0"@},@{number="44",value="0x0"@},
25905@{number="45",value="0x0"@},@{number="46",value="0x0"@},
25906@{number="47",value="0x0"@},@{number="48",value="0x0"@},
25907@{number="49",value="0x0"@},@{number="50",value="0x0"@},
25908@{number="51",value="0x0"@},@{number="52",value="0x0"@},
25909@{number="53",value="0x0"@},@{number="54",value="0x0"@},
25910@{number="55",value="0x0"@},@{number="56",value="0x0"@},
25911@{number="57",value="0x0"@},@{number="58",value="0x0"@},
25912@{number="59",value="0x0"@},@{number="60",value="0x0"@},
25913@{number="61",value="0x0"@},@{number="62",value="0x0"@},
25914@{number="63",value="0x0"@},@{number="64",value="0xfe00a300"@},
25915@{number="65",value="0x29002"@},@{number="66",value="0x202f04b5"@},
25916@{number="67",value="0xfe0043b0"@},@{number="68",value="0xfe00b3e4"@},
25917@{number="69",value="0x20002b03"@}]
594fe323 25918(gdb)
a2c02241 25919@end smallexample
922fbb7b 25920
a2c02241
NR
25921
25922@subheading The @code{-data-read-memory} Command
25923@findex -data-read-memory
922fbb7b
AC
25924
25925@subsubheading Synopsis
25926
25927@smallexample
a2c02241
NR
25928 -data-read-memory [ -o @var{byte-offset} ]
25929 @var{address} @var{word-format} @var{word-size}
25930 @var{nr-rows} @var{nr-cols} [ @var{aschar} ]
922fbb7b
AC
25931@end smallexample
25932
a2c02241
NR
25933@noindent
25934where:
922fbb7b 25935
a2c02241
NR
25936@table @samp
25937@item @var{address}
25938An expression specifying the address of the first memory word to be
25939read. Complex expressions containing embedded white space should be
25940quoted using the C convention.
922fbb7b 25941
a2c02241
NR
25942@item @var{word-format}
25943The format to be used to print the memory words. The notation is the
25944same as for @value{GDBN}'s @code{print} command (@pxref{Output Formats,
79a6e687 25945,Output Formats}).
922fbb7b 25946
a2c02241
NR
25947@item @var{word-size}
25948The size of each memory word in bytes.
922fbb7b 25949
a2c02241
NR
25950@item @var{nr-rows}
25951The number of rows in the output table.
922fbb7b 25952
a2c02241
NR
25953@item @var{nr-cols}
25954The number of columns in the output table.
922fbb7b 25955
a2c02241
NR
25956@item @var{aschar}
25957If present, indicates that each row should include an @sc{ascii} dump. The
25958value of @var{aschar} is used as a padding character when a byte is not a
25959member of the printable @sc{ascii} character set (printable @sc{ascii}
25960characters are those whose code is between 32 and 126, inclusively).
922fbb7b 25961
a2c02241
NR
25962@item @var{byte-offset}
25963An offset to add to the @var{address} before fetching memory.
25964@end table
922fbb7b 25965
a2c02241
NR
25966This command displays memory contents as a table of @var{nr-rows} by
25967@var{nr-cols} words, each word being @var{word-size} bytes. In total,
25968@code{@var{nr-rows} * @var{nr-cols} * @var{word-size}} bytes are read
25969(returned as @samp{total-bytes}). Should less than the requested number
25970of bytes be returned by the target, the missing words are identified
25971using @samp{N/A}. The number of bytes read from the target is returned
25972in @samp{nr-bytes} and the starting address used to read memory in
25973@samp{addr}.
25974
25975The address of the next/previous row or page is available in
25976@samp{next-row} and @samp{prev-row}, @samp{next-page} and
25977@samp{prev-page}.
922fbb7b
AC
25978
25979@subsubheading @value{GDBN} Command
25980
a2c02241
NR
25981The corresponding @value{GDBN} command is @samp{x}. @code{gdbtk} has
25982@samp{gdb_get_mem} memory read command.
922fbb7b
AC
25983
25984@subsubheading Example
32e7087d 25985
a2c02241
NR
25986Read six bytes of memory starting at @code{bytes+6} but then offset by
25987@code{-6} bytes. Format as three rows of two columns. One byte per
25988word. Display each word in hex.
32e7087d
JB
25989
25990@smallexample
594fe323 25991(gdb)
a2c02241
NR
259929-data-read-memory -o -6 -- bytes+6 x 1 3 2
259939^done,addr="0x00001390",nr-bytes="6",total-bytes="6",
25994next-row="0x00001396",prev-row="0x0000138e",next-page="0x00001396",
25995prev-page="0x0000138a",memory=[
25996@{addr="0x00001390",data=["0x00","0x01"]@},
25997@{addr="0x00001392",data=["0x02","0x03"]@},
25998@{addr="0x00001394",data=["0x04","0x05"]@}]
594fe323 25999(gdb)
32e7087d
JB
26000@end smallexample
26001
a2c02241
NR
26002Read two bytes of memory starting at address @code{shorts + 64} and
26003display as a single word formatted in decimal.
32e7087d 26004
32e7087d 26005@smallexample
594fe323 26006(gdb)
a2c02241
NR
260075-data-read-memory shorts+64 d 2 1 1
260085^done,addr="0x00001510",nr-bytes="2",total-bytes="2",
26009next-row="0x00001512",prev-row="0x0000150e",
26010next-page="0x00001512",prev-page="0x0000150e",memory=[
26011@{addr="0x00001510",data=["128"]@}]
594fe323 26012(gdb)
32e7087d
JB
26013@end smallexample
26014
a2c02241
NR
26015Read thirty two bytes of memory starting at @code{bytes+16} and format
26016as eight rows of four columns. Include a string encoding with @samp{x}
26017used as the non-printable character.
922fbb7b
AC
26018
26019@smallexample
594fe323 26020(gdb)
a2c02241
NR
260214-data-read-memory bytes+16 x 1 8 4 x
260224^done,addr="0x000013a0",nr-bytes="32",total-bytes="32",
26023next-row="0x000013c0",prev-row="0x0000139c",
26024next-page="0x000013c0",prev-page="0x00001380",memory=[
26025@{addr="0x000013a0",data=["0x10","0x11","0x12","0x13"],ascii="xxxx"@},
26026@{addr="0x000013a4",data=["0x14","0x15","0x16","0x17"],ascii="xxxx"@},
26027@{addr="0x000013a8",data=["0x18","0x19","0x1a","0x1b"],ascii="xxxx"@},
26028@{addr="0x000013ac",data=["0x1c","0x1d","0x1e","0x1f"],ascii="xxxx"@},
26029@{addr="0x000013b0",data=["0x20","0x21","0x22","0x23"],ascii=" !\"#"@},
26030@{addr="0x000013b4",data=["0x24","0x25","0x26","0x27"],ascii="$%&'"@},
26031@{addr="0x000013b8",data=["0x28","0x29","0x2a","0x2b"],ascii="()*+"@},
26032@{addr="0x000013bc",data=["0x2c","0x2d","0x2e","0x2f"],ascii=",-./"@}]
594fe323 26033(gdb)
922fbb7b
AC
26034@end smallexample
26035
a2c02241
NR
26036@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
26037@node GDB/MI Tracepoint Commands
26038@section @sc{gdb/mi} Tracepoint Commands
922fbb7b 26039
18148017
VP
26040The commands defined in this section implement MI support for
26041tracepoints. For detailed introduction, see @ref{Tracepoints}.
26042
26043@subheading The @code{-trace-find} Command
26044@findex -trace-find
26045
26046@subsubheading Synopsis
26047
26048@smallexample
26049 -trace-find @var{mode} [@var{parameters}@dots{}]
26050@end smallexample
26051
26052Find a trace frame using criteria defined by @var{mode} and
26053@var{parameters}. The following table lists permissible
26054modes and their parameters. For details of operation, see @ref{tfind}.
26055
26056@table @samp
26057
26058@item none
26059No parameters are required. Stops examining trace frames.
26060
26061@item frame-number
26062An integer is required as parameter. Selects tracepoint frame with
26063that index.
26064
26065@item tracepoint-number
26066An integer is required as parameter. Finds next
26067trace frame that corresponds to tracepoint with the specified number.
26068
26069@item pc
26070An address is required as parameter. Finds
26071next trace frame that corresponds to any tracepoint at the specified
26072address.
26073
26074@item pc-inside-range
26075Two addresses are required as parameters. Finds next trace
26076frame that corresponds to a tracepoint at an address inside the
26077specified range. Both bounds are considered to be inside the range.
26078
26079@item pc-outside-range
26080Two addresses are required as parameters. Finds
26081next trace frame that corresponds to a tracepoint at an address outside
26082the specified range. Both bounds are considered to be inside the range.
26083
26084@item line
26085Line specification is required as parameter. @xref{Specify Location}.
26086Finds next trace frame that corresponds to a tracepoint at
26087the specified location.
26088
26089@end table
26090
26091If @samp{none} was passed as @var{mode}, the response does not
26092have fields. Otherwise, the response may have the following fields:
26093
26094@table @samp
26095@item found
26096This field has either @samp{0} or @samp{1} as the value, depending
26097on whether a matching tracepoint was found.
26098
26099@item traceframe
26100The index of the found traceframe. This field is present iff
26101the @samp{found} field has value of @samp{1}.
26102
26103@item tracepoint
26104The index of the found tracepoint. This field is present iff
26105the @samp{found} field has value of @samp{1}.
26106
26107@item frame
26108The information about the frame corresponding to the found trace
26109frame. This field is present only if a trace frame was found.
cd64ee31 26110@xref{GDB/MI Frame Information}, for description of this field.
18148017
VP
26111
26112@end table
26113
7d13fe92
SS
26114@subsubheading @value{GDBN} Command
26115
26116The corresponding @value{GDBN} command is @samp{tfind}.
26117
18148017
VP
26118@subheading -trace-define-variable
26119@findex -trace-define-variable
26120
26121@subsubheading Synopsis
26122
26123@smallexample
26124 -trace-define-variable @var{name} [ @var{value} ]
26125@end smallexample
26126
26127Create trace variable @var{name} if it does not exist. If
26128@var{value} is specified, sets the initial value of the specified
26129trace variable to that value. Note that the @var{name} should start
26130with the @samp{$} character.
26131
7d13fe92
SS
26132@subsubheading @value{GDBN} Command
26133
26134The corresponding @value{GDBN} command is @samp{tvariable}.
26135
18148017
VP
26136@subheading -trace-list-variables
26137@findex -trace-list-variables
922fbb7b 26138
18148017 26139@subsubheading Synopsis
922fbb7b 26140
18148017
VP
26141@smallexample
26142 -trace-list-variables
26143@end smallexample
922fbb7b 26144
18148017
VP
26145Return a table of all defined trace variables. Each element of the
26146table has the following fields:
922fbb7b 26147
18148017
VP
26148@table @samp
26149@item name
26150The name of the trace variable. This field is always present.
922fbb7b 26151
18148017
VP
26152@item initial
26153The initial value. This is a 64-bit signed integer. This
26154field is always present.
922fbb7b 26155
18148017
VP
26156@item current
26157The value the trace variable has at the moment. This is a 64-bit
26158signed integer. This field is absent iff current value is
26159not defined, for example if the trace was never run, or is
26160presently running.
922fbb7b 26161
18148017 26162@end table
922fbb7b 26163
7d13fe92
SS
26164@subsubheading @value{GDBN} Command
26165
26166The corresponding @value{GDBN} command is @samp{tvariables}.
26167
18148017 26168@subsubheading Example
922fbb7b 26169
18148017
VP
26170@smallexample
26171(gdb)
26172-trace-list-variables
26173^done,trace-variables=@{nr_rows="1",nr_cols="3",
26174hdr=[@{width="15",alignment="-1",col_name="name",colhdr="Name"@},
26175 @{width="11",alignment="-1",col_name="initial",colhdr="Initial"@},
26176 @{width="11",alignment="-1",col_name="current",colhdr="Current"@}],
26177body=[variable=@{name="$trace_timestamp",initial="0"@}
26178 variable=@{name="$foo",initial="10",current="15"@}]@}
26179(gdb)
26180@end smallexample
922fbb7b 26181
18148017
VP
26182@subheading -trace-save
26183@findex -trace-save
922fbb7b 26184
18148017
VP
26185@subsubheading Synopsis
26186
26187@smallexample
26188 -trace-save [-r ] @var{filename}
26189@end smallexample
26190
26191Saves the collected trace data to @var{filename}. Without the
26192@samp{-r} option, the data is downloaded from the target and saved
26193in a local file. With the @samp{-r} option the target is asked
26194to perform the save.
26195
7d13fe92
SS
26196@subsubheading @value{GDBN} Command
26197
26198The corresponding @value{GDBN} command is @samp{tsave}.
26199
18148017
VP
26200
26201@subheading -trace-start
26202@findex -trace-start
26203
26204@subsubheading Synopsis
26205
26206@smallexample
26207 -trace-start
26208@end smallexample
922fbb7b 26209
18148017
VP
26210Starts a tracing experiments. The result of this command does not
26211have any fields.
922fbb7b 26212
7d13fe92
SS
26213@subsubheading @value{GDBN} Command
26214
26215The corresponding @value{GDBN} command is @samp{tstart}.
26216
18148017
VP
26217@subheading -trace-status
26218@findex -trace-status
922fbb7b 26219
18148017
VP
26220@subsubheading Synopsis
26221
26222@smallexample
26223 -trace-status
26224@end smallexample
26225
26226Obtains the status of a tracing experiement. The result may include
26227the following fields:
26228
26229@table @samp
26230
26231@item supported
26232May have a value of either @samp{0}, when no tracing operations are
26233supported, @samp{1}, when all tracing operations are supported, or
26234@samp{file} when examining trace file. In the latter case, examining
26235of trace frame is possible but new tracing experiement cannot be
26236started. This field is always present.
26237
26238@item running
26239May have a value of either @samp{0} or @samp{1} depending on whether
26240tracing experiement is in progress on target. This field is present
26241if @samp{supported} field is not @samp{0}.
26242
26243@item stop-reason
26244Report the reason why the tracing was stopped last time. This field
26245may be absent iff tracing was never stopped on target yet. The
26246value of @samp{request} means the tracing was stopped as result of
26247the @code{-trace-stop} command. The value of @samp{overflow} means
26248the tracing buffer is full. The value of @samp{disconnection} means
26249tracing was automatically stopped when @value{GDBN} has disconnected.
26250The value of @samp{passcount} means tracing was stopped when a
26251tracepoint was passed a maximal number of times for that tracepoint.
26252This field is present if @samp{supported} field is not @samp{0}.
26253
26254@item stopping-tracepoint
26255The number of tracepoint whose passcount as exceeded. This field is
26256present iff the @samp{stop-reason} field has the value of
26257@samp{passcount}.
26258
26259@item frames
26260This field is an integer number of currently collected frames. This
26261field is optional.
26262
26263@item buffer-size
26264@itemx buffer-free
26265These fields tell the current size of the tracing buffer and the
26266remaining space. These field is optional.
26267
26268@end table
26269
7d13fe92
SS
26270@subsubheading @value{GDBN} Command
26271
26272The corresponding @value{GDBN} command is @samp{tstatus}.
26273
18148017
VP
26274@subheading -trace-stop
26275@findex -trace-stop
26276
26277@subsubheading Synopsis
26278
26279@smallexample
26280 -trace-stop
26281@end smallexample
922fbb7b 26282
18148017
VP
26283Stops a tracing experiment. The result of this command has the same
26284fields as @code{-trace-status}, except that the @samp{supported} and
26285@samp{running} fields are not output.
922fbb7b 26286
7d13fe92
SS
26287@subsubheading @value{GDBN} Command
26288
26289The corresponding @value{GDBN} command is @samp{tstop}.
26290
922fbb7b 26291
a2c02241
NR
26292@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
26293@node GDB/MI Symbol Query
26294@section @sc{gdb/mi} Symbol Query Commands
922fbb7b
AC
26295
26296
9901a55b 26297@ignore
a2c02241
NR
26298@subheading The @code{-symbol-info-address} Command
26299@findex -symbol-info-address
922fbb7b
AC
26300
26301@subsubheading Synopsis
26302
26303@smallexample
a2c02241 26304 -symbol-info-address @var{symbol}
922fbb7b
AC
26305@end smallexample
26306
a2c02241 26307Describe where @var{symbol} is stored.
922fbb7b
AC
26308
26309@subsubheading @value{GDBN} Command
26310
a2c02241 26311The corresponding @value{GDBN} command is @samp{info address}.
922fbb7b
AC
26312
26313@subsubheading Example
26314N.A.
26315
26316
a2c02241
NR
26317@subheading The @code{-symbol-info-file} Command
26318@findex -symbol-info-file
922fbb7b
AC
26319
26320@subsubheading Synopsis
26321
26322@smallexample
a2c02241 26323 -symbol-info-file
922fbb7b
AC
26324@end smallexample
26325
a2c02241 26326Show the file for the symbol.
922fbb7b 26327
a2c02241 26328@subsubheading @value{GDBN} Command
922fbb7b 26329
a2c02241
NR
26330There's no equivalent @value{GDBN} command. @code{gdbtk} has
26331@samp{gdb_find_file}.
922fbb7b
AC
26332
26333@subsubheading Example
26334N.A.
26335
26336
a2c02241
NR
26337@subheading The @code{-symbol-info-function} Command
26338@findex -symbol-info-function
922fbb7b
AC
26339
26340@subsubheading Synopsis
26341
26342@smallexample
a2c02241 26343 -symbol-info-function
922fbb7b
AC
26344@end smallexample
26345
a2c02241 26346Show which function the symbol lives in.
922fbb7b
AC
26347
26348@subsubheading @value{GDBN} Command
26349
a2c02241 26350@samp{gdb_get_function} in @code{gdbtk}.
922fbb7b
AC
26351
26352@subsubheading Example
26353N.A.
26354
26355
a2c02241
NR
26356@subheading The @code{-symbol-info-line} Command
26357@findex -symbol-info-line
922fbb7b
AC
26358
26359@subsubheading Synopsis
26360
26361@smallexample
a2c02241 26362 -symbol-info-line
922fbb7b
AC
26363@end smallexample
26364
a2c02241 26365Show the core addresses of the code for a source line.
922fbb7b 26366
a2c02241 26367@subsubheading @value{GDBN} Command
922fbb7b 26368
a2c02241
NR
26369The corresponding @value{GDBN} command is @samp{info line}.
26370@code{gdbtk} has the @samp{gdb_get_line} and @samp{gdb_get_file} commands.
922fbb7b
AC
26371
26372@subsubheading Example
a2c02241 26373N.A.
922fbb7b
AC
26374
26375
a2c02241
NR
26376@subheading The @code{-symbol-info-symbol} Command
26377@findex -symbol-info-symbol
07f31aa6
DJ
26378
26379@subsubheading Synopsis
26380
a2c02241
NR
26381@smallexample
26382 -symbol-info-symbol @var{addr}
26383@end smallexample
07f31aa6 26384
a2c02241 26385Describe what symbol is at location @var{addr}.
07f31aa6 26386
a2c02241 26387@subsubheading @value{GDBN} Command
07f31aa6 26388
a2c02241 26389The corresponding @value{GDBN} command is @samp{info symbol}.
07f31aa6
DJ
26390
26391@subsubheading Example
a2c02241 26392N.A.
07f31aa6
DJ
26393
26394
a2c02241
NR
26395@subheading The @code{-symbol-list-functions} Command
26396@findex -symbol-list-functions
922fbb7b
AC
26397
26398@subsubheading Synopsis
26399
26400@smallexample
a2c02241 26401 -symbol-list-functions
922fbb7b
AC
26402@end smallexample
26403
a2c02241 26404List the functions in the executable.
922fbb7b
AC
26405
26406@subsubheading @value{GDBN} Command
26407
a2c02241
NR
26408@samp{info functions} in @value{GDBN}, @samp{gdb_listfunc} and
26409@samp{gdb_search} in @code{gdbtk}.
922fbb7b
AC
26410
26411@subsubheading Example
a2c02241 26412N.A.
9901a55b 26413@end ignore
922fbb7b
AC
26414
26415
a2c02241
NR
26416@subheading The @code{-symbol-list-lines} Command
26417@findex -symbol-list-lines
922fbb7b
AC
26418
26419@subsubheading Synopsis
26420
26421@smallexample
a2c02241 26422 -symbol-list-lines @var{filename}
922fbb7b
AC
26423@end smallexample
26424
a2c02241
NR
26425Print the list of lines that contain code and their associated program
26426addresses for the given source filename. The entries are sorted in
26427ascending PC order.
922fbb7b
AC
26428
26429@subsubheading @value{GDBN} Command
26430
a2c02241 26431There is no corresponding @value{GDBN} command.
922fbb7b
AC
26432
26433@subsubheading Example
a2c02241 26434@smallexample
594fe323 26435(gdb)
a2c02241
NR
26436-symbol-list-lines basics.c
26437^done,lines=[@{pc="0x08048554",line="7"@},@{pc="0x0804855a",line="8"@}]
594fe323 26438(gdb)
a2c02241 26439@end smallexample
922fbb7b
AC
26440
26441
9901a55b 26442@ignore
a2c02241
NR
26443@subheading The @code{-symbol-list-types} Command
26444@findex -symbol-list-types
922fbb7b
AC
26445
26446@subsubheading Synopsis
26447
26448@smallexample
a2c02241 26449 -symbol-list-types
922fbb7b
AC
26450@end smallexample
26451
a2c02241 26452List all the type names.
922fbb7b
AC
26453
26454@subsubheading @value{GDBN} Command
26455
a2c02241
NR
26456The corresponding commands are @samp{info types} in @value{GDBN},
26457@samp{gdb_search} in @code{gdbtk}.
922fbb7b
AC
26458
26459@subsubheading Example
26460N.A.
26461
26462
a2c02241
NR
26463@subheading The @code{-symbol-list-variables} Command
26464@findex -symbol-list-variables
922fbb7b
AC
26465
26466@subsubheading Synopsis
26467
26468@smallexample
a2c02241 26469 -symbol-list-variables
922fbb7b
AC
26470@end smallexample
26471
a2c02241 26472List all the global and static variable names.
922fbb7b
AC
26473
26474@subsubheading @value{GDBN} Command
26475
a2c02241 26476@samp{info variables} in @value{GDBN}, @samp{gdb_search} in @code{gdbtk}.
922fbb7b
AC
26477
26478@subsubheading Example
26479N.A.
26480
26481
a2c02241
NR
26482@subheading The @code{-symbol-locate} Command
26483@findex -symbol-locate
922fbb7b
AC
26484
26485@subsubheading Synopsis
26486
26487@smallexample
a2c02241 26488 -symbol-locate
922fbb7b
AC
26489@end smallexample
26490
922fbb7b
AC
26491@subsubheading @value{GDBN} Command
26492
a2c02241 26493@samp{gdb_loc} in @code{gdbtk}.
922fbb7b
AC
26494
26495@subsubheading Example
26496N.A.
26497
26498
a2c02241
NR
26499@subheading The @code{-symbol-type} Command
26500@findex -symbol-type
922fbb7b
AC
26501
26502@subsubheading Synopsis
26503
26504@smallexample
a2c02241 26505 -symbol-type @var{variable}
922fbb7b
AC
26506@end smallexample
26507
a2c02241 26508Show type of @var{variable}.
922fbb7b 26509
a2c02241 26510@subsubheading @value{GDBN} Command
922fbb7b 26511
a2c02241
NR
26512The corresponding @value{GDBN} command is @samp{ptype}, @code{gdbtk} has
26513@samp{gdb_obj_variable}.
26514
26515@subsubheading Example
26516N.A.
9901a55b 26517@end ignore
a2c02241
NR
26518
26519
26520@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
26521@node GDB/MI File Commands
26522@section @sc{gdb/mi} File Commands
26523
26524This section describes the GDB/MI commands to specify executable file names
26525and to read in and obtain symbol table information.
26526
26527@subheading The @code{-file-exec-and-symbols} Command
26528@findex -file-exec-and-symbols
26529
26530@subsubheading Synopsis
922fbb7b
AC
26531
26532@smallexample
a2c02241 26533 -file-exec-and-symbols @var{file}
922fbb7b
AC
26534@end smallexample
26535
a2c02241
NR
26536Specify the executable file to be debugged. This file is the one from
26537which the symbol table is also read. If no file is specified, the
26538command clears the executable and symbol information. If breakpoints
26539are set when using this command with no arguments, @value{GDBN} will produce
26540error messages. Otherwise, no output is produced, except a completion
26541notification.
26542
922fbb7b
AC
26543@subsubheading @value{GDBN} Command
26544
a2c02241 26545The corresponding @value{GDBN} command is @samp{file}.
922fbb7b
AC
26546
26547@subsubheading Example
26548
26549@smallexample
594fe323 26550(gdb)
a2c02241
NR
26551-file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
26552^done
594fe323 26553(gdb)
922fbb7b
AC
26554@end smallexample
26555
922fbb7b 26556
a2c02241
NR
26557@subheading The @code{-file-exec-file} Command
26558@findex -file-exec-file
922fbb7b
AC
26559
26560@subsubheading Synopsis
26561
26562@smallexample
a2c02241 26563 -file-exec-file @var{file}
922fbb7b
AC
26564@end smallexample
26565
a2c02241
NR
26566Specify the executable file to be debugged. Unlike
26567@samp{-file-exec-and-symbols}, the symbol table is @emph{not} read
26568from this file. If used without argument, @value{GDBN} clears the information
26569about the executable file. No output is produced, except a completion
26570notification.
922fbb7b 26571
a2c02241
NR
26572@subsubheading @value{GDBN} Command
26573
26574The corresponding @value{GDBN} command is @samp{exec-file}.
922fbb7b
AC
26575
26576@subsubheading Example
a2c02241
NR
26577
26578@smallexample
594fe323 26579(gdb)
a2c02241
NR
26580-file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
26581^done
594fe323 26582(gdb)
a2c02241 26583@end smallexample
922fbb7b
AC
26584
26585
9901a55b 26586@ignore
a2c02241
NR
26587@subheading The @code{-file-list-exec-sections} Command
26588@findex -file-list-exec-sections
922fbb7b
AC
26589
26590@subsubheading Synopsis
26591
26592@smallexample
a2c02241 26593 -file-list-exec-sections
922fbb7b
AC
26594@end smallexample
26595
a2c02241
NR
26596List the sections of the current executable file.
26597
922fbb7b
AC
26598@subsubheading @value{GDBN} Command
26599
a2c02241
NR
26600The @value{GDBN} command @samp{info file} shows, among the rest, the same
26601information as this command. @code{gdbtk} has a corresponding command
26602@samp{gdb_load_info}.
922fbb7b
AC
26603
26604@subsubheading Example
26605N.A.
9901a55b 26606@end ignore
922fbb7b
AC
26607
26608
a2c02241
NR
26609@subheading The @code{-file-list-exec-source-file} Command
26610@findex -file-list-exec-source-file
922fbb7b
AC
26611
26612@subsubheading Synopsis
26613
26614@smallexample
a2c02241 26615 -file-list-exec-source-file
922fbb7b
AC
26616@end smallexample
26617
a2c02241 26618List the line number, the current source file, and the absolute path
44288b44
NR
26619to the current source file for the current executable. The macro
26620information field has a value of @samp{1} or @samp{0} depending on
26621whether or not the file includes preprocessor macro information.
922fbb7b
AC
26622
26623@subsubheading @value{GDBN} Command
26624
a2c02241 26625The @value{GDBN} equivalent is @samp{info source}
922fbb7b
AC
26626
26627@subsubheading Example
26628
922fbb7b 26629@smallexample
594fe323 26630(gdb)
a2c02241 26631123-file-list-exec-source-file
44288b44 26632123^done,line="1",file="foo.c",fullname="/home/bar/foo.c,macro-info="1"
594fe323 26633(gdb)
922fbb7b
AC
26634@end smallexample
26635
26636
a2c02241
NR
26637@subheading The @code{-file-list-exec-source-files} Command
26638@findex -file-list-exec-source-files
922fbb7b
AC
26639
26640@subsubheading Synopsis
26641
26642@smallexample
a2c02241 26643 -file-list-exec-source-files
922fbb7b
AC
26644@end smallexample
26645
a2c02241
NR
26646List the source files for the current executable.
26647
3f94c067
BW
26648It will always output the filename, but only when @value{GDBN} can find
26649the absolute file name of a source file, will it output the fullname.
922fbb7b
AC
26650
26651@subsubheading @value{GDBN} Command
26652
a2c02241
NR
26653The @value{GDBN} equivalent is @samp{info sources}.
26654@code{gdbtk} has an analogous command @samp{gdb_listfiles}.
922fbb7b
AC
26655
26656@subsubheading Example
922fbb7b 26657@smallexample
594fe323 26658(gdb)
a2c02241
NR
26659-file-list-exec-source-files
26660^done,files=[
26661@{file=foo.c,fullname=/home/foo.c@},
26662@{file=/home/bar.c,fullname=/home/bar.c@},
26663@{file=gdb_could_not_find_fullpath.c@}]
594fe323 26664(gdb)
922fbb7b
AC
26665@end smallexample
26666
9901a55b 26667@ignore
a2c02241
NR
26668@subheading The @code{-file-list-shared-libraries} Command
26669@findex -file-list-shared-libraries
922fbb7b 26670
a2c02241 26671@subsubheading Synopsis
922fbb7b 26672
a2c02241
NR
26673@smallexample
26674 -file-list-shared-libraries
26675@end smallexample
922fbb7b 26676
a2c02241 26677List the shared libraries in the program.
922fbb7b 26678
a2c02241 26679@subsubheading @value{GDBN} Command
922fbb7b 26680
a2c02241 26681The corresponding @value{GDBN} command is @samp{info shared}.
922fbb7b 26682
a2c02241
NR
26683@subsubheading Example
26684N.A.
922fbb7b
AC
26685
26686
a2c02241
NR
26687@subheading The @code{-file-list-symbol-files} Command
26688@findex -file-list-symbol-files
922fbb7b 26689
a2c02241 26690@subsubheading Synopsis
922fbb7b 26691
a2c02241
NR
26692@smallexample
26693 -file-list-symbol-files
26694@end smallexample
922fbb7b 26695
a2c02241 26696List symbol files.
922fbb7b 26697
a2c02241 26698@subsubheading @value{GDBN} Command
922fbb7b 26699
a2c02241 26700The corresponding @value{GDBN} command is @samp{info file} (part of it).
922fbb7b 26701
a2c02241
NR
26702@subsubheading Example
26703N.A.
9901a55b 26704@end ignore
922fbb7b 26705
922fbb7b 26706
a2c02241
NR
26707@subheading The @code{-file-symbol-file} Command
26708@findex -file-symbol-file
922fbb7b 26709
a2c02241 26710@subsubheading Synopsis
922fbb7b 26711
a2c02241
NR
26712@smallexample
26713 -file-symbol-file @var{file}
26714@end smallexample
922fbb7b 26715
a2c02241
NR
26716Read symbol table info from the specified @var{file} argument. When
26717used without arguments, clears @value{GDBN}'s symbol table info. No output is
26718produced, except for a completion notification.
922fbb7b 26719
a2c02241 26720@subsubheading @value{GDBN} Command
922fbb7b 26721
a2c02241 26722The corresponding @value{GDBN} command is @samp{symbol-file}.
922fbb7b 26723
a2c02241 26724@subsubheading Example
922fbb7b 26725
a2c02241 26726@smallexample
594fe323 26727(gdb)
a2c02241
NR
26728-file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
26729^done
594fe323 26730(gdb)
a2c02241 26731@end smallexample
922fbb7b 26732
a2c02241 26733@ignore
a2c02241
NR
26734@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
26735@node GDB/MI Memory Overlay Commands
26736@section @sc{gdb/mi} Memory Overlay Commands
922fbb7b 26737
a2c02241 26738The memory overlay commands are not implemented.
922fbb7b 26739
a2c02241 26740@c @subheading -overlay-auto
922fbb7b 26741
a2c02241 26742@c @subheading -overlay-list-mapping-state
922fbb7b 26743
a2c02241 26744@c @subheading -overlay-list-overlays
922fbb7b 26745
a2c02241 26746@c @subheading -overlay-map
922fbb7b 26747
a2c02241 26748@c @subheading -overlay-off
922fbb7b 26749
a2c02241 26750@c @subheading -overlay-on
922fbb7b 26751
a2c02241 26752@c @subheading -overlay-unmap
922fbb7b 26753
a2c02241
NR
26754@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
26755@node GDB/MI Signal Handling Commands
26756@section @sc{gdb/mi} Signal Handling Commands
922fbb7b 26757
a2c02241 26758Signal handling commands are not implemented.
922fbb7b 26759
a2c02241 26760@c @subheading -signal-handle
922fbb7b 26761
a2c02241 26762@c @subheading -signal-list-handle-actions
922fbb7b 26763
a2c02241
NR
26764@c @subheading -signal-list-signal-types
26765@end ignore
922fbb7b 26766
922fbb7b 26767
a2c02241
NR
26768@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
26769@node GDB/MI Target Manipulation
26770@section @sc{gdb/mi} Target Manipulation Commands
922fbb7b
AC
26771
26772
a2c02241
NR
26773@subheading The @code{-target-attach} Command
26774@findex -target-attach
922fbb7b
AC
26775
26776@subsubheading Synopsis
26777
26778@smallexample
c3b108f7 26779 -target-attach @var{pid} | @var{gid} | @var{file}
922fbb7b
AC
26780@end smallexample
26781
c3b108f7
VP
26782Attach to a process @var{pid} or a file @var{file} outside of
26783@value{GDBN}, or a thread group @var{gid}. If attaching to a thread
26784group, the id previously returned by
26785@samp{-list-thread-groups --available} must be used.
922fbb7b 26786
79a6e687 26787@subsubheading @value{GDBN} Command
922fbb7b 26788
a2c02241 26789The corresponding @value{GDBN} command is @samp{attach}.
922fbb7b 26790
a2c02241 26791@subsubheading Example
b56e7235
VP
26792@smallexample
26793(gdb)
26794-target-attach 34
26795=thread-created,id="1"
5ae4183a 26796*stopped,thread-id="1",frame=@{addr="0xb7f7e410",func="bar",args=[]@}
b56e7235
VP
26797^done
26798(gdb)
26799@end smallexample
a2c02241 26800
9901a55b 26801@ignore
a2c02241
NR
26802@subheading The @code{-target-compare-sections} Command
26803@findex -target-compare-sections
922fbb7b
AC
26804
26805@subsubheading Synopsis
26806
26807@smallexample
a2c02241 26808 -target-compare-sections [ @var{section} ]
922fbb7b
AC
26809@end smallexample
26810
a2c02241
NR
26811Compare data of section @var{section} on target to the exec file.
26812Without the argument, all sections are compared.
922fbb7b 26813
a2c02241 26814@subsubheading @value{GDBN} Command
922fbb7b 26815
a2c02241 26816The @value{GDBN} equivalent is @samp{compare-sections}.
922fbb7b 26817
a2c02241
NR
26818@subsubheading Example
26819N.A.
9901a55b 26820@end ignore
a2c02241
NR
26821
26822
26823@subheading The @code{-target-detach} Command
26824@findex -target-detach
922fbb7b
AC
26825
26826@subsubheading Synopsis
26827
26828@smallexample
c3b108f7 26829 -target-detach [ @var{pid} | @var{gid} ]
922fbb7b
AC
26830@end smallexample
26831
a2c02241 26832Detach from the remote target which normally resumes its execution.
c3b108f7
VP
26833If either @var{pid} or @var{gid} is specified, detaches from either
26834the specified process, or specified thread group. There's no output.
a2c02241 26835
79a6e687 26836@subsubheading @value{GDBN} Command
a2c02241
NR
26837
26838The corresponding @value{GDBN} command is @samp{detach}.
26839
26840@subsubheading Example
922fbb7b
AC
26841
26842@smallexample
594fe323 26843(gdb)
a2c02241
NR
26844-target-detach
26845^done
594fe323 26846(gdb)
922fbb7b
AC
26847@end smallexample
26848
26849
a2c02241
NR
26850@subheading The @code{-target-disconnect} Command
26851@findex -target-disconnect
922fbb7b
AC
26852
26853@subsubheading Synopsis
26854
123dc839 26855@smallexample
a2c02241 26856 -target-disconnect
123dc839 26857@end smallexample
922fbb7b 26858
a2c02241
NR
26859Disconnect from the remote target. There's no output and the target is
26860generally not resumed.
26861
79a6e687 26862@subsubheading @value{GDBN} Command
a2c02241
NR
26863
26864The corresponding @value{GDBN} command is @samp{disconnect}.
bc8ced35
NR
26865
26866@subsubheading Example
922fbb7b
AC
26867
26868@smallexample
594fe323 26869(gdb)
a2c02241
NR
26870-target-disconnect
26871^done
594fe323 26872(gdb)
922fbb7b
AC
26873@end smallexample
26874
26875
a2c02241
NR
26876@subheading The @code{-target-download} Command
26877@findex -target-download
922fbb7b
AC
26878
26879@subsubheading Synopsis
26880
26881@smallexample
a2c02241 26882 -target-download
922fbb7b
AC
26883@end smallexample
26884
a2c02241
NR
26885Loads the executable onto the remote target.
26886It prints out an update message every half second, which includes the fields:
26887
26888@table @samp
26889@item section
26890The name of the section.
26891@item section-sent
26892The size of what has been sent so far for that section.
26893@item section-size
26894The size of the section.
26895@item total-sent
26896The total size of what was sent so far (the current and the previous sections).
26897@item total-size
26898The size of the overall executable to download.
26899@end table
26900
26901@noindent
26902Each message is sent as status record (@pxref{GDB/MI Output Syntax, ,
26903@sc{gdb/mi} Output Syntax}).
26904
26905In addition, it prints the name and size of the sections, as they are
26906downloaded. These messages include the following fields:
26907
26908@table @samp
26909@item section
26910The name of the section.
26911@item section-size
26912The size of the section.
26913@item total-size
26914The size of the overall executable to download.
26915@end table
26916
26917@noindent
26918At the end, a summary is printed.
26919
26920@subsubheading @value{GDBN} Command
26921
26922The corresponding @value{GDBN} command is @samp{load}.
26923
26924@subsubheading Example
26925
26926Note: each status message appears on a single line. Here the messages
26927have been broken down so that they can fit onto a page.
922fbb7b
AC
26928
26929@smallexample
594fe323 26930(gdb)
a2c02241
NR
26931-target-download
26932+download,@{section=".text",section-size="6668",total-size="9880"@}
26933+download,@{section=".text",section-sent="512",section-size="6668",
26934total-sent="512",total-size="9880"@}
26935+download,@{section=".text",section-sent="1024",section-size="6668",
26936total-sent="1024",total-size="9880"@}
26937+download,@{section=".text",section-sent="1536",section-size="6668",
26938total-sent="1536",total-size="9880"@}
26939+download,@{section=".text",section-sent="2048",section-size="6668",
26940total-sent="2048",total-size="9880"@}
26941+download,@{section=".text",section-sent="2560",section-size="6668",
26942total-sent="2560",total-size="9880"@}
26943+download,@{section=".text",section-sent="3072",section-size="6668",
26944total-sent="3072",total-size="9880"@}
26945+download,@{section=".text",section-sent="3584",section-size="6668",
26946total-sent="3584",total-size="9880"@}
26947+download,@{section=".text",section-sent="4096",section-size="6668",
26948total-sent="4096",total-size="9880"@}
26949+download,@{section=".text",section-sent="4608",section-size="6668",
26950total-sent="4608",total-size="9880"@}
26951+download,@{section=".text",section-sent="5120",section-size="6668",
26952total-sent="5120",total-size="9880"@}
26953+download,@{section=".text",section-sent="5632",section-size="6668",
26954total-sent="5632",total-size="9880"@}
26955+download,@{section=".text",section-sent="6144",section-size="6668",
26956total-sent="6144",total-size="9880"@}
26957+download,@{section=".text",section-sent="6656",section-size="6668",
26958total-sent="6656",total-size="9880"@}
26959+download,@{section=".init",section-size="28",total-size="9880"@}
26960+download,@{section=".fini",section-size="28",total-size="9880"@}
26961+download,@{section=".data",section-size="3156",total-size="9880"@}
26962+download,@{section=".data",section-sent="512",section-size="3156",
26963total-sent="7236",total-size="9880"@}
26964+download,@{section=".data",section-sent="1024",section-size="3156",
26965total-sent="7748",total-size="9880"@}
26966+download,@{section=".data",section-sent="1536",section-size="3156",
26967total-sent="8260",total-size="9880"@}
26968+download,@{section=".data",section-sent="2048",section-size="3156",
26969total-sent="8772",total-size="9880"@}
26970+download,@{section=".data",section-sent="2560",section-size="3156",
26971total-sent="9284",total-size="9880"@}
26972+download,@{section=".data",section-sent="3072",section-size="3156",
26973total-sent="9796",total-size="9880"@}
26974^done,address="0x10004",load-size="9880",transfer-rate="6586",
26975write-rate="429"
594fe323 26976(gdb)
922fbb7b
AC
26977@end smallexample
26978
26979
9901a55b 26980@ignore
a2c02241
NR
26981@subheading The @code{-target-exec-status} Command
26982@findex -target-exec-status
922fbb7b
AC
26983
26984@subsubheading Synopsis
26985
26986@smallexample
a2c02241 26987 -target-exec-status
922fbb7b
AC
26988@end smallexample
26989
a2c02241
NR
26990Provide information on the state of the target (whether it is running or
26991not, for instance).
922fbb7b 26992
a2c02241 26993@subsubheading @value{GDBN} Command
922fbb7b 26994
a2c02241
NR
26995There's no equivalent @value{GDBN} command.
26996
26997@subsubheading Example
26998N.A.
922fbb7b 26999
a2c02241
NR
27000
27001@subheading The @code{-target-list-available-targets} Command
27002@findex -target-list-available-targets
922fbb7b
AC
27003
27004@subsubheading Synopsis
27005
27006@smallexample
a2c02241 27007 -target-list-available-targets
922fbb7b
AC
27008@end smallexample
27009
a2c02241 27010List the possible targets to connect to.
922fbb7b 27011
a2c02241 27012@subsubheading @value{GDBN} Command
922fbb7b 27013
a2c02241 27014The corresponding @value{GDBN} command is @samp{help target}.
922fbb7b 27015
a2c02241
NR
27016@subsubheading Example
27017N.A.
27018
27019
27020@subheading The @code{-target-list-current-targets} Command
27021@findex -target-list-current-targets
922fbb7b
AC
27022
27023@subsubheading Synopsis
27024
27025@smallexample
a2c02241 27026 -target-list-current-targets
922fbb7b
AC
27027@end smallexample
27028
a2c02241 27029Describe the current target.
922fbb7b 27030
a2c02241 27031@subsubheading @value{GDBN} Command
922fbb7b 27032
a2c02241
NR
27033The corresponding information is printed by @samp{info file} (among
27034other things).
922fbb7b 27035
a2c02241
NR
27036@subsubheading Example
27037N.A.
27038
27039
27040@subheading The @code{-target-list-parameters} Command
27041@findex -target-list-parameters
922fbb7b
AC
27042
27043@subsubheading Synopsis
27044
27045@smallexample
a2c02241 27046 -target-list-parameters
922fbb7b
AC
27047@end smallexample
27048
a2c02241 27049@c ????
9901a55b 27050@end ignore
a2c02241
NR
27051
27052@subsubheading @value{GDBN} Command
27053
27054No equivalent.
922fbb7b
AC
27055
27056@subsubheading Example
a2c02241
NR
27057N.A.
27058
27059
27060@subheading The @code{-target-select} Command
27061@findex -target-select
27062
27063@subsubheading Synopsis
922fbb7b
AC
27064
27065@smallexample
a2c02241 27066 -target-select @var{type} @var{parameters @dots{}}
922fbb7b
AC
27067@end smallexample
27068
a2c02241 27069Connect @value{GDBN} to the remote target. This command takes two args:
922fbb7b 27070
a2c02241
NR
27071@table @samp
27072@item @var{type}
75c99385 27073The type of target, for instance @samp{remote}, etc.
a2c02241
NR
27074@item @var{parameters}
27075Device names, host names and the like. @xref{Target Commands, ,
79a6e687 27076Commands for Managing Targets}, for more details.
a2c02241
NR
27077@end table
27078
27079The output is a connection notification, followed by the address at
27080which the target program is, in the following form:
922fbb7b
AC
27081
27082@smallexample
a2c02241
NR
27083^connected,addr="@var{address}",func="@var{function name}",
27084 args=[@var{arg list}]
922fbb7b
AC
27085@end smallexample
27086
a2c02241
NR
27087@subsubheading @value{GDBN} Command
27088
27089The corresponding @value{GDBN} command is @samp{target}.
265eeb58
NR
27090
27091@subsubheading Example
922fbb7b 27092
265eeb58 27093@smallexample
594fe323 27094(gdb)
75c99385 27095-target-select remote /dev/ttya
a2c02241 27096^connected,addr="0xfe00a300",func="??",args=[]
594fe323 27097(gdb)
265eeb58 27098@end smallexample
ef21caaf 27099
a6b151f1
DJ
27100@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
27101@node GDB/MI File Transfer Commands
27102@section @sc{gdb/mi} File Transfer Commands
27103
27104
27105@subheading The @code{-target-file-put} Command
27106@findex -target-file-put
27107
27108@subsubheading Synopsis
27109
27110@smallexample
27111 -target-file-put @var{hostfile} @var{targetfile}
27112@end smallexample
27113
27114Copy file @var{hostfile} from the host system (the machine running
27115@value{GDBN}) to @var{targetfile} on the target system.
27116
27117@subsubheading @value{GDBN} Command
27118
27119The corresponding @value{GDBN} command is @samp{remote put}.
27120
27121@subsubheading Example
27122
27123@smallexample
27124(gdb)
27125-target-file-put localfile remotefile
27126^done
27127(gdb)
27128@end smallexample
27129
27130
1763a388 27131@subheading The @code{-target-file-get} Command
a6b151f1
DJ
27132@findex -target-file-get
27133
27134@subsubheading Synopsis
27135
27136@smallexample
27137 -target-file-get @var{targetfile} @var{hostfile}
27138@end smallexample
27139
27140Copy file @var{targetfile} from the target system to @var{hostfile}
27141on the host system.
27142
27143@subsubheading @value{GDBN} Command
27144
27145The corresponding @value{GDBN} command is @samp{remote get}.
27146
27147@subsubheading Example
27148
27149@smallexample
27150(gdb)
27151-target-file-get remotefile localfile
27152^done
27153(gdb)
27154@end smallexample
27155
27156
27157@subheading The @code{-target-file-delete} Command
27158@findex -target-file-delete
27159
27160@subsubheading Synopsis
27161
27162@smallexample
27163 -target-file-delete @var{targetfile}
27164@end smallexample
27165
27166Delete @var{targetfile} from the target system.
27167
27168@subsubheading @value{GDBN} Command
27169
27170The corresponding @value{GDBN} command is @samp{remote delete}.
27171
27172@subsubheading Example
27173
27174@smallexample
27175(gdb)
27176-target-file-delete remotefile
27177^done
27178(gdb)
27179@end smallexample
27180
27181
ef21caaf
NR
27182@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
27183@node GDB/MI Miscellaneous Commands
27184@section Miscellaneous @sc{gdb/mi} Commands
27185
27186@c @subheading -gdb-complete
27187
27188@subheading The @code{-gdb-exit} Command
27189@findex -gdb-exit
27190
27191@subsubheading Synopsis
27192
27193@smallexample
27194 -gdb-exit
27195@end smallexample
27196
27197Exit @value{GDBN} immediately.
27198
27199@subsubheading @value{GDBN} Command
27200
27201Approximately corresponds to @samp{quit}.
27202
27203@subsubheading Example
27204
27205@smallexample
594fe323 27206(gdb)
ef21caaf
NR
27207-gdb-exit
27208^exit
27209@end smallexample
27210
a2c02241 27211
9901a55b 27212@ignore
a2c02241
NR
27213@subheading The @code{-exec-abort} Command
27214@findex -exec-abort
27215
27216@subsubheading Synopsis
27217
27218@smallexample
27219 -exec-abort
27220@end smallexample
27221
27222Kill the inferior running program.
27223
27224@subsubheading @value{GDBN} Command
27225
27226The corresponding @value{GDBN} command is @samp{kill}.
27227
27228@subsubheading Example
27229N.A.
9901a55b 27230@end ignore
a2c02241
NR
27231
27232
ef21caaf
NR
27233@subheading The @code{-gdb-set} Command
27234@findex -gdb-set
27235
27236@subsubheading Synopsis
27237
27238@smallexample
27239 -gdb-set
27240@end smallexample
27241
27242Set an internal @value{GDBN} variable.
27243@c IS THIS A DOLLAR VARIABLE? OR SOMETHING LIKE ANNOTATE ?????
27244
27245@subsubheading @value{GDBN} Command
27246
27247The corresponding @value{GDBN} command is @samp{set}.
27248
27249@subsubheading Example
27250
27251@smallexample
594fe323 27252(gdb)
ef21caaf
NR
27253-gdb-set $foo=3
27254^done
594fe323 27255(gdb)
ef21caaf
NR
27256@end smallexample
27257
27258
27259@subheading The @code{-gdb-show} Command
27260@findex -gdb-show
27261
27262@subsubheading Synopsis
27263
27264@smallexample
27265 -gdb-show
27266@end smallexample
27267
27268Show the current value of a @value{GDBN} variable.
27269
79a6e687 27270@subsubheading @value{GDBN} Command
ef21caaf
NR
27271
27272The corresponding @value{GDBN} command is @samp{show}.
27273
27274@subsubheading Example
27275
27276@smallexample
594fe323 27277(gdb)
ef21caaf
NR
27278-gdb-show annotate
27279^done,value="0"
594fe323 27280(gdb)
ef21caaf
NR
27281@end smallexample
27282
27283@c @subheading -gdb-source
27284
27285
27286@subheading The @code{-gdb-version} Command
27287@findex -gdb-version
27288
27289@subsubheading Synopsis
27290
27291@smallexample
27292 -gdb-version
27293@end smallexample
27294
27295Show version information for @value{GDBN}. Used mostly in testing.
27296
27297@subsubheading @value{GDBN} Command
27298
27299The @value{GDBN} equivalent is @samp{show version}. @value{GDBN} by
27300default shows this information when you start an interactive session.
27301
27302@subsubheading Example
27303
27304@c This example modifies the actual output from GDB to avoid overfull
27305@c box in TeX.
27306@smallexample
594fe323 27307(gdb)
ef21caaf
NR
27308-gdb-version
27309~GNU gdb 5.2.1
27310~Copyright 2000 Free Software Foundation, Inc.
27311~GDB is free software, covered by the GNU General Public License, and
27312~you are welcome to change it and/or distribute copies of it under
27313~ certain conditions.
27314~Type "show copying" to see the conditions.
27315~There is absolutely no warranty for GDB. Type "show warranty" for
27316~ details.
27317~This GDB was configured as
27318 "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi".
27319^done
594fe323 27320(gdb)
ef21caaf
NR
27321@end smallexample
27322
084344da
VP
27323@subheading The @code{-list-features} Command
27324@findex -list-features
27325
27326Returns a list of particular features of the MI protocol that
27327this version of gdb implements. A feature can be a command,
27328or a new field in an output of some command, or even an
27329important bugfix. While a frontend can sometimes detect presence
27330of a feature at runtime, it is easier to perform detection at debugger
27331startup.
27332
27333The command returns a list of strings, with each string naming an
27334available feature. Each returned string is just a name, it does not
27335have any internal structure. The list of possible feature names
27336is given below.
27337
27338Example output:
27339
27340@smallexample
27341(gdb) -list-features
27342^done,result=["feature1","feature2"]
27343@end smallexample
27344
27345The current list of features is:
27346
30e026bb
VP
27347@table @samp
27348@item frozen-varobjs
27349Indicates presence of the @code{-var-set-frozen} command, as well
27350as possible presense of the @code{frozen} field in the output
27351of @code{-varobj-create}.
27352@item pending-breakpoints
27353Indicates presence of the @option{-f} option to the @code{-break-insert} command.
b6313243
TT
27354@item python
27355Indicates presence of Python scripting support, Python-based
27356pretty-printing commands, and possible presence of the
27357@samp{display_hint} field in the output of @code{-var-list-children}
30e026bb
VP
27358@item thread-info
27359Indicates presence of the @code{-thread-info} command.
8b4ed427 27360
30e026bb 27361@end table
084344da 27362
c6ebd6cf
VP
27363@subheading The @code{-list-target-features} Command
27364@findex -list-target-features
27365
27366Returns a list of particular features that are supported by the
27367target. Those features affect the permitted MI commands, but
27368unlike the features reported by the @code{-list-features} command, the
27369features depend on which target GDB is using at the moment. Whenever
27370a target can change, due to commands such as @code{-target-select},
27371@code{-target-attach} or @code{-exec-run}, the list of target features
27372may change, and the frontend should obtain it again.
27373Example output:
27374
27375@smallexample
27376(gdb) -list-features
27377^done,result=["async"]
27378@end smallexample
27379
27380The current list of features is:
27381
27382@table @samp
27383@item async
27384Indicates that the target is capable of asynchronous command
27385execution, which means that @value{GDBN} will accept further commands
27386while the target is running.
27387
27388@end table
27389
c3b108f7
VP
27390@subheading The @code{-list-thread-groups} Command
27391@findex -list-thread-groups
27392
27393@subheading Synopsis
27394
27395@smallexample
dc146f7c 27396-list-thread-groups [ --available ] [ --recurse 1 ] [ @var{group} ... ]
c3b108f7
VP
27397@end smallexample
27398
dc146f7c
VP
27399Lists thread groups (@pxref{Thread groups}). When a single thread
27400group is passed as the argument, lists the children of that group.
27401When several thread group are passed, lists information about those
27402thread groups. Without any parameters, lists information about all
27403top-level thread groups.
27404
27405Normally, thread groups that are being debugged are reported.
27406With the @samp{--available} option, @value{GDBN} reports thread groups
27407available on the target.
27408
27409The output of this command may have either a @samp{threads} result or
27410a @samp{groups} result. The @samp{thread} result has a list of tuples
27411as value, with each tuple describing a thread (@pxref{GDB/MI Thread
27412Information}). The @samp{groups} result has a list of tuples as value,
27413each tuple describing a thread group. If top-level groups are
27414requested (that is, no parameter is passed), or when several groups
27415are passed, the output always has a @samp{groups} result. The format
27416of the @samp{group} result is described below.
27417
27418To reduce the number of roundtrips it's possible to list thread groups
27419together with their children, by passing the @samp{--recurse} option
27420and the recursion depth. Presently, only recursion depth of 1 is
27421permitted. If this option is present, then every reported thread group
27422will also include its children, either as @samp{group} or
27423@samp{threads} field.
27424
27425In general, any combination of option and parameters is permitted, with
27426the following caveats:
27427
27428@itemize @bullet
27429@item
27430When a single thread group is passed, the output will typically
27431be the @samp{threads} result. Because threads may not contain
27432anything, the @samp{recurse} option will be ignored.
27433
27434@item
27435When the @samp{--available} option is passed, limited information may
27436be available. In particular, the list of threads of a process might
27437be inaccessible. Further, specifying specific thread groups might
27438not give any performance advantage over listing all thread groups.
27439The frontend should assume that @samp{-list-thread-groups --available}
27440is always an expensive operation and cache the results.
27441
27442@end itemize
27443
27444The @samp{groups} result is a list of tuples, where each tuple may
27445have the following fields:
27446
27447@table @code
27448@item id
27449Identifier of the thread group. This field is always present.
a79b8f6e
VP
27450The identifier is an opaque string; frontends should not try to
27451convert it to an integer, even though it might look like one.
dc146f7c
VP
27452
27453@item type
27454The type of the thread group. At present, only @samp{process} is a
27455valid type.
27456
27457@item pid
27458The target-specific process identifier. This field is only present
a79b8f6e 27459for thread groups of type @samp{process} and only if the process exists.
c3b108f7 27460
dc146f7c
VP
27461@item num_children
27462The number of children this thread group has. This field may be
27463absent for an available thread group.
27464
27465@item threads
27466This field has a list of tuples as value, each tuple describing a
27467thread. It may be present if the @samp{--recurse} option is
27468specified, and it's actually possible to obtain the threads.
27469
27470@item cores
27471This field is a list of integers, each identifying a core that one
27472thread of the group is running on. This field may be absent if
27473such information is not available.
27474
a79b8f6e
VP
27475@item executable
27476The name of the executable file that corresponds to this thread group.
27477The field is only present for thread groups of type @samp{process},
27478and only if there is a corresponding executable file.
27479
dc146f7c 27480@end table
c3b108f7
VP
27481
27482@subheading Example
27483
27484@smallexample
27485@value{GDBP}
27486-list-thread-groups
27487^done,groups=[@{id="17",type="process",pid="yyy",num_children="2"@}]
27488-list-thread-groups 17
27489^done,threads=[@{id="2",target-id="Thread 0xb7e14b90 (LWP 21257)",
27490 frame=@{level="0",addr="0xffffe410",func="__kernel_vsyscall",args=[]@},state="running"@},
27491@{id="1",target-id="Thread 0xb7e156b0 (LWP 21254)",
27492 frame=@{level="0",addr="0x0804891f",func="foo",args=[@{name="i",value="10"@}],
27493 file="/tmp/a.c",fullname="/tmp/a.c",line="158"@},state="running"@}]]
dc146f7c
VP
27494-list-thread-groups --available
27495^done,groups=[@{id="17",type="process",pid="yyy",num_children="2",cores=[1,2]@}]
27496-list-thread-groups --available --recurse 1
27497 ^done,groups=[@{id="17", types="process",pid="yyy",num_children="2",cores=[1,2],
27498 threads=[@{id="1",target-id="Thread 0xb7e14b90",cores=[1]@},
27499 @{id="2",target-id="Thread 0xb7e14b90",cores=[2]@}]@},..]
27500-list-thread-groups --available --recurse 1 17 18
27501^done,groups=[@{id="17", types="process",pid="yyy",num_children="2",cores=[1,2],
27502 threads=[@{id="1",target-id="Thread 0xb7e14b90",cores=[1]@},
27503 @{id="2",target-id="Thread 0xb7e14b90",cores=[2]@}]@},...]
c3b108f7 27504@end smallexample
c6ebd6cf 27505
a79b8f6e
VP
27506
27507@subheading The @code{-add-inferior} Command
27508@findex -add-inferior
27509
27510@subheading Synopsis
27511
27512@smallexample
27513-add-inferior
27514@end smallexample
27515
27516Creates a new inferior (@pxref{Inferiors and Programs}). The created
27517inferior is not associated with any executable. Such association may
27518be established with the @samp{-file-exec-and-symbols} command
27519(@pxref{GDB/MI File Commands}). The command response has a single
27520field, @samp{thread-group}, whose value is the identifier of the
27521thread group corresponding to the new inferior.
27522
27523@subheading Example
27524
27525@smallexample
27526@value{GDBP}
27527-add-inferior
27528^done,thread-group="i3"
27529@end smallexample
27530
ef21caaf
NR
27531@subheading The @code{-interpreter-exec} Command
27532@findex -interpreter-exec
27533
27534@subheading Synopsis
27535
27536@smallexample
27537-interpreter-exec @var{interpreter} @var{command}
27538@end smallexample
a2c02241 27539@anchor{-interpreter-exec}
ef21caaf
NR
27540
27541Execute the specified @var{command} in the given @var{interpreter}.
27542
27543@subheading @value{GDBN} Command
27544
27545The corresponding @value{GDBN} command is @samp{interpreter-exec}.
27546
27547@subheading Example
27548
27549@smallexample
594fe323 27550(gdb)
ef21caaf
NR
27551-interpreter-exec console "break main"
27552&"During symbol reading, couldn't parse type; debugger out of date?.\n"
27553&"During symbol reading, bad structure-type format.\n"
27554~"Breakpoint 1 at 0x8074fc6: file ../../src/gdb/main.c, line 743.\n"
27555^done
594fe323 27556(gdb)
ef21caaf
NR
27557@end smallexample
27558
27559@subheading The @code{-inferior-tty-set} Command
27560@findex -inferior-tty-set
27561
27562@subheading Synopsis
27563
27564@smallexample
27565-inferior-tty-set /dev/pts/1
27566@end smallexample
27567
27568Set terminal for future runs of the program being debugged.
27569
27570@subheading @value{GDBN} Command
27571
27572The corresponding @value{GDBN} command is @samp{set inferior-tty} /dev/pts/1.
27573
27574@subheading Example
27575
27576@smallexample
594fe323 27577(gdb)
ef21caaf
NR
27578-inferior-tty-set /dev/pts/1
27579^done
594fe323 27580(gdb)
ef21caaf
NR
27581@end smallexample
27582
27583@subheading The @code{-inferior-tty-show} Command
27584@findex -inferior-tty-show
27585
27586@subheading Synopsis
27587
27588@smallexample
27589-inferior-tty-show
27590@end smallexample
27591
27592Show terminal for future runs of program being debugged.
27593
27594@subheading @value{GDBN} Command
27595
27596The corresponding @value{GDBN} command is @samp{show inferior-tty}.
27597
27598@subheading Example
27599
27600@smallexample
594fe323 27601(gdb)
ef21caaf
NR
27602-inferior-tty-set /dev/pts/1
27603^done
594fe323 27604(gdb)
ef21caaf
NR
27605-inferior-tty-show
27606^done,inferior_tty_terminal="/dev/pts/1"
594fe323 27607(gdb)
ef21caaf 27608@end smallexample
922fbb7b 27609
a4eefcd8
NR
27610@subheading The @code{-enable-timings} Command
27611@findex -enable-timings
27612
27613@subheading Synopsis
27614
27615@smallexample
27616-enable-timings [yes | no]
27617@end smallexample
27618
27619Toggle the printing of the wallclock, user and system times for an MI
27620command as a field in its output. This command is to help frontend
27621developers optimize the performance of their code. No argument is
27622equivalent to @samp{yes}.
27623
27624@subheading @value{GDBN} Command
27625
27626No equivalent.
27627
27628@subheading Example
27629
27630@smallexample
27631(gdb)
27632-enable-timings
27633^done
27634(gdb)
27635-break-insert main
27636^done,bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
27637addr="0x080484ed",func="main",file="myprog.c",
27638fullname="/home/nickrob/myprog.c",line="73",times="0"@},
27639time=@{wallclock="0.05185",user="0.00800",system="0.00000"@}
27640(gdb)
27641-enable-timings no
27642^done
27643(gdb)
27644-exec-run
27645^running
27646(gdb)
a47ec5fe 27647*stopped,reason="breakpoint-hit",disp="keep",bkptno="1",thread-id="0",
a4eefcd8
NR
27648frame=@{addr="0x080484ed",func="main",args=[@{name="argc",value="1"@},
27649@{name="argv",value="0xbfb60364"@}],file="myprog.c",
27650fullname="/home/nickrob/myprog.c",line="73"@}
27651(gdb)
27652@end smallexample
27653
922fbb7b
AC
27654@node Annotations
27655@chapter @value{GDBN} Annotations
27656
086432e2
AC
27657This chapter describes annotations in @value{GDBN}. Annotations were
27658designed to interface @value{GDBN} to graphical user interfaces or other
27659similar programs which want to interact with @value{GDBN} at a
922fbb7b
AC
27660relatively high level.
27661
d3e8051b 27662The annotation mechanism has largely been superseded by @sc{gdb/mi}
086432e2
AC
27663(@pxref{GDB/MI}).
27664
922fbb7b
AC
27665@ignore
27666This is Edition @value{EDITION}, @value{DATE}.
27667@end ignore
27668
27669@menu
27670* Annotations Overview:: What annotations are; the general syntax.
9e6c4bd5 27671* Server Prefix:: Issuing a command without affecting user state.
922fbb7b
AC
27672* Prompting:: Annotations marking @value{GDBN}'s need for input.
27673* Errors:: Annotations for error messages.
922fbb7b
AC
27674* Invalidation:: Some annotations describe things now invalid.
27675* Annotations for Running::
27676 Whether the program is running, how it stopped, etc.
27677* Source Annotations:: Annotations describing source code.
922fbb7b
AC
27678@end menu
27679
27680@node Annotations Overview
27681@section What is an Annotation?
27682@cindex annotations
27683
922fbb7b
AC
27684Annotations start with a newline character, two @samp{control-z}
27685characters, and the name of the annotation. If there is no additional
27686information associated with this annotation, the name of the annotation
27687is followed immediately by a newline. If there is additional
27688information, the name of the annotation is followed by a space, the
27689additional information, and a newline. The additional information
27690cannot contain newline characters.
27691
27692Any output not beginning with a newline and two @samp{control-z}
27693characters denotes literal output from @value{GDBN}. Currently there is
27694no need for @value{GDBN} to output a newline followed by two
27695@samp{control-z} characters, but if there was such a need, the
27696annotations could be extended with an @samp{escape} annotation which
27697means those three characters as output.
27698
086432e2
AC
27699The annotation @var{level}, which is specified using the
27700@option{--annotate} command line option (@pxref{Mode Options}), controls
27701how much information @value{GDBN} prints together with its prompt,
27702values of expressions, source lines, and other types of output. Level 0
d3e8051b 27703is for no annotations, level 1 is for use when @value{GDBN} is run as a
086432e2
AC
27704subprocess of @sc{gnu} Emacs, level 3 is the maximum annotation suitable
27705for programs that control @value{GDBN}, and level 2 annotations have
27706been made obsolete (@pxref{Limitations, , Limitations of the Annotation
09d4efe1
EZ
27707Interface, annotate, GDB's Obsolete Annotations}).
27708
27709@table @code
27710@kindex set annotate
27711@item set annotate @var{level}
e09f16f9 27712The @value{GDBN} command @code{set annotate} sets the level of
09d4efe1 27713annotations to the specified @var{level}.
9c16f35a
EZ
27714
27715@item show annotate
27716@kindex show annotate
27717Show the current annotation level.
09d4efe1
EZ
27718@end table
27719
27720This chapter describes level 3 annotations.
086432e2 27721
922fbb7b
AC
27722A simple example of starting up @value{GDBN} with annotations is:
27723
27724@smallexample
086432e2
AC
27725$ @kbd{gdb --annotate=3}
27726GNU gdb 6.0
27727Copyright 2003 Free Software Foundation, Inc.
922fbb7b
AC
27728GDB is free software, covered by the GNU General Public License,
27729and you are welcome to change it and/or distribute copies of it
27730under certain conditions.
27731Type "show copying" to see the conditions.
27732There is absolutely no warranty for GDB. Type "show warranty"
27733for details.
086432e2 27734This GDB was configured as "i386-pc-linux-gnu"
922fbb7b
AC
27735
27736^Z^Zpre-prompt
f7dc1244 27737(@value{GDBP})
922fbb7b 27738^Z^Zprompt
086432e2 27739@kbd{quit}
922fbb7b
AC
27740
27741^Z^Zpost-prompt
b383017d 27742$
922fbb7b
AC
27743@end smallexample
27744
27745Here @samp{quit} is input to @value{GDBN}; the rest is output from
27746@value{GDBN}. The three lines beginning @samp{^Z^Z} (where @samp{^Z}
27747denotes a @samp{control-z} character) are annotations; the rest is
27748output from @value{GDBN}.
27749
9e6c4bd5
NR
27750@node Server Prefix
27751@section The Server Prefix
27752@cindex server prefix
27753
27754If you prefix a command with @samp{server } then it will not affect
27755the command history, nor will it affect @value{GDBN}'s notion of which
27756command to repeat if @key{RET} is pressed on a line by itself. This
27757means that commands can be run behind a user's back by a front-end in
27758a transparent manner.
27759
d837706a
NR
27760The @code{server } prefix does not affect the recording of values into
27761the value history; to print a value without recording it into the
27762value history, use the @code{output} command instead of the
27763@code{print} command.
27764
27765Using this prefix also disables confirmation requests
27766(@pxref{confirmation requests}).
9e6c4bd5 27767
922fbb7b
AC
27768@node Prompting
27769@section Annotation for @value{GDBN} Input
27770
27771@cindex annotations for prompts
27772When @value{GDBN} prompts for input, it annotates this fact so it is possible
27773to know when to send output, when the output from a given command is
27774over, etc.
27775
27776Different kinds of input each have a different @dfn{input type}. Each
27777input type has three annotations: a @code{pre-} annotation, which
27778denotes the beginning of any prompt which is being output, a plain
27779annotation, which denotes the end of the prompt, and then a @code{post-}
27780annotation which denotes the end of any echo which may (or may not) be
27781associated with the input. For example, the @code{prompt} input type
27782features the following annotations:
27783
27784@smallexample
27785^Z^Zpre-prompt
27786^Z^Zprompt
27787^Z^Zpost-prompt
27788@end smallexample
27789
27790The input types are
27791
27792@table @code
e5ac9b53
EZ
27793@findex pre-prompt annotation
27794@findex prompt annotation
27795@findex post-prompt annotation
922fbb7b
AC
27796@item prompt
27797When @value{GDBN} is prompting for a command (the main @value{GDBN} prompt).
27798
e5ac9b53
EZ
27799@findex pre-commands annotation
27800@findex commands annotation
27801@findex post-commands annotation
922fbb7b
AC
27802@item commands
27803When @value{GDBN} prompts for a set of commands, like in the @code{commands}
27804command. The annotations are repeated for each command which is input.
27805
e5ac9b53
EZ
27806@findex pre-overload-choice annotation
27807@findex overload-choice annotation
27808@findex post-overload-choice annotation
922fbb7b
AC
27809@item overload-choice
27810When @value{GDBN} wants the user to select between various overloaded functions.
27811
e5ac9b53
EZ
27812@findex pre-query annotation
27813@findex query annotation
27814@findex post-query annotation
922fbb7b
AC
27815@item query
27816When @value{GDBN} wants the user to confirm a potentially dangerous operation.
27817
e5ac9b53
EZ
27818@findex pre-prompt-for-continue annotation
27819@findex prompt-for-continue annotation
27820@findex post-prompt-for-continue annotation
922fbb7b
AC
27821@item prompt-for-continue
27822When @value{GDBN} is asking the user to press return to continue. Note: Don't
27823expect this to work well; instead use @code{set height 0} to disable
27824prompting. This is because the counting of lines is buggy in the
27825presence of annotations.
27826@end table
27827
27828@node Errors
27829@section Errors
27830@cindex annotations for errors, warnings and interrupts
27831
e5ac9b53 27832@findex quit annotation
922fbb7b
AC
27833@smallexample
27834^Z^Zquit
27835@end smallexample
27836
27837This annotation occurs right before @value{GDBN} responds to an interrupt.
27838
e5ac9b53 27839@findex error annotation
922fbb7b
AC
27840@smallexample
27841^Z^Zerror
27842@end smallexample
27843
27844This annotation occurs right before @value{GDBN} responds to an error.
27845
27846Quit and error annotations indicate that any annotations which @value{GDBN} was
27847in the middle of may end abruptly. For example, if a
27848@code{value-history-begin} annotation is followed by a @code{error}, one
27849cannot expect to receive the matching @code{value-history-end}. One
27850cannot expect not to receive it either, however; an error annotation
27851does not necessarily mean that @value{GDBN} is immediately returning all the way
27852to the top level.
27853
e5ac9b53 27854@findex error-begin annotation
922fbb7b
AC
27855A quit or error annotation may be preceded by
27856
27857@smallexample
27858^Z^Zerror-begin
27859@end smallexample
27860
27861Any output between that and the quit or error annotation is the error
27862message.
27863
27864Warning messages are not yet annotated.
27865@c If we want to change that, need to fix warning(), type_error(),
27866@c range_error(), and possibly other places.
27867
922fbb7b
AC
27868@node Invalidation
27869@section Invalidation Notices
27870
27871@cindex annotations for invalidation messages
27872The following annotations say that certain pieces of state may have
27873changed.
27874
27875@table @code
e5ac9b53 27876@findex frames-invalid annotation
922fbb7b
AC
27877@item ^Z^Zframes-invalid
27878
27879The frames (for example, output from the @code{backtrace} command) may
27880have changed.
27881
e5ac9b53 27882@findex breakpoints-invalid annotation
922fbb7b
AC
27883@item ^Z^Zbreakpoints-invalid
27884
27885The breakpoints may have changed. For example, the user just added or
27886deleted a breakpoint.
27887@end table
27888
27889@node Annotations for Running
27890@section Running the Program
27891@cindex annotations for running programs
27892
e5ac9b53
EZ
27893@findex starting annotation
27894@findex stopping annotation
922fbb7b 27895When the program starts executing due to a @value{GDBN} command such as
b383017d 27896@code{step} or @code{continue},
922fbb7b
AC
27897
27898@smallexample
27899^Z^Zstarting
27900@end smallexample
27901
b383017d 27902is output. When the program stops,
922fbb7b
AC
27903
27904@smallexample
27905^Z^Zstopped
27906@end smallexample
27907
27908is output. Before the @code{stopped} annotation, a variety of
27909annotations describe how the program stopped.
27910
27911@table @code
e5ac9b53 27912@findex exited annotation
922fbb7b
AC
27913@item ^Z^Zexited @var{exit-status}
27914The program exited, and @var{exit-status} is the exit status (zero for
27915successful exit, otherwise nonzero).
27916
e5ac9b53
EZ
27917@findex signalled annotation
27918@findex signal-name annotation
27919@findex signal-name-end annotation
27920@findex signal-string annotation
27921@findex signal-string-end annotation
922fbb7b
AC
27922@item ^Z^Zsignalled
27923The program exited with a signal. After the @code{^Z^Zsignalled}, the
27924annotation continues:
27925
27926@smallexample
27927@var{intro-text}
27928^Z^Zsignal-name
27929@var{name}
27930^Z^Zsignal-name-end
27931@var{middle-text}
27932^Z^Zsignal-string
27933@var{string}
27934^Z^Zsignal-string-end
27935@var{end-text}
27936@end smallexample
27937
27938@noindent
27939where @var{name} is the name of the signal, such as @code{SIGILL} or
27940@code{SIGSEGV}, and @var{string} is the explanation of the signal, such
27941as @code{Illegal Instruction} or @code{Segmentation fault}.
27942@var{intro-text}, @var{middle-text}, and @var{end-text} are for the
27943user's benefit and have no particular format.
27944
e5ac9b53 27945@findex signal annotation
922fbb7b
AC
27946@item ^Z^Zsignal
27947The syntax of this annotation is just like @code{signalled}, but @value{GDBN} is
27948just saying that the program received the signal, not that it was
27949terminated with it.
27950
e5ac9b53 27951@findex breakpoint annotation
922fbb7b
AC
27952@item ^Z^Zbreakpoint @var{number}
27953The program hit breakpoint number @var{number}.
27954
e5ac9b53 27955@findex watchpoint annotation
922fbb7b
AC
27956@item ^Z^Zwatchpoint @var{number}
27957The program hit watchpoint number @var{number}.
27958@end table
27959
27960@node Source Annotations
27961@section Displaying Source
27962@cindex annotations for source display
27963
e5ac9b53 27964@findex source annotation
922fbb7b
AC
27965The following annotation is used instead of displaying source code:
27966
27967@smallexample
27968^Z^Zsource @var{filename}:@var{line}:@var{character}:@var{middle}:@var{addr}
27969@end smallexample
27970
27971where @var{filename} is an absolute file name indicating which source
27972file, @var{line} is the line number within that file (where 1 is the
27973first line in the file), @var{character} is the character position
27974within the file (where 0 is the first character in the file) (for most
27975debug formats this will necessarily point to the beginning of a line),
27976@var{middle} is @samp{middle} if @var{addr} is in the middle of the
27977line, or @samp{beg} if @var{addr} is at the beginning of the line, and
27978@var{addr} is the address in the target program associated with the
27979source which is being displayed. @var{addr} is in the form @samp{0x}
27980followed by one or more lowercase hex digits (note that this does not
27981depend on the language).
27982
4efc6507
DE
27983@node JIT Interface
27984@chapter JIT Compilation Interface
27985@cindex just-in-time compilation
27986@cindex JIT compilation interface
27987
27988This chapter documents @value{GDBN}'s @dfn{just-in-time} (JIT) compilation
27989interface. A JIT compiler is a program or library that generates native
27990executable code at runtime and executes it, usually in order to achieve good
27991performance while maintaining platform independence.
27992
27993Programs that use JIT compilation are normally difficult to debug because
27994portions of their code are generated at runtime, instead of being loaded from
27995object files, which is where @value{GDBN} normally finds the program's symbols
27996and debug information. In order to debug programs that use JIT compilation,
27997@value{GDBN} has an interface that allows the program to register in-memory
27998symbol files with @value{GDBN} at runtime.
27999
28000If you are using @value{GDBN} to debug a program that uses this interface, then
28001it should work transparently so long as you have not stripped the binary. If
28002you are developing a JIT compiler, then the interface is documented in the rest
28003of this chapter. At this time, the only known client of this interface is the
28004LLVM JIT.
28005
28006Broadly speaking, the JIT interface mirrors the dynamic loader interface. The
28007JIT compiler communicates with @value{GDBN} by writing data into a global
28008variable and calling a fuction at a well-known symbol. When @value{GDBN}
28009attaches, it reads a linked list of symbol files from the global variable to
28010find existing code, and puts a breakpoint in the function so that it can find
28011out about additional code.
28012
28013@menu
28014* Declarations:: Relevant C struct declarations
28015* Registering Code:: Steps to register code
28016* Unregistering Code:: Steps to unregister code
28017@end menu
28018
28019@node Declarations
28020@section JIT Declarations
28021
28022These are the relevant struct declarations that a C program should include to
28023implement the interface:
28024
28025@smallexample
28026typedef enum
28027@{
28028 JIT_NOACTION = 0,
28029 JIT_REGISTER_FN,
28030 JIT_UNREGISTER_FN
28031@} jit_actions_t;
28032
28033struct jit_code_entry
28034@{
28035 struct jit_code_entry *next_entry;
28036 struct jit_code_entry *prev_entry;
28037 const char *symfile_addr;
28038 uint64_t symfile_size;
28039@};
28040
28041struct jit_descriptor
28042@{
28043 uint32_t version;
28044 /* This type should be jit_actions_t, but we use uint32_t
28045 to be explicit about the bitwidth. */
28046 uint32_t action_flag;
28047 struct jit_code_entry *relevant_entry;
28048 struct jit_code_entry *first_entry;
28049@};
28050
28051/* GDB puts a breakpoint in this function. */
28052void __attribute__((noinline)) __jit_debug_register_code() @{ @};
28053
28054/* Make sure to specify the version statically, because the
28055 debugger may check the version before we can set it. */
28056struct jit_descriptor __jit_debug_descriptor = @{ 1, 0, 0, 0 @};
28057@end smallexample
28058
28059If the JIT is multi-threaded, then it is important that the JIT synchronize any
28060modifications to this global data properly, which can easily be done by putting
28061a global mutex around modifications to these structures.
28062
28063@node Registering Code
28064@section Registering Code
28065
28066To register code with @value{GDBN}, the JIT should follow this protocol:
28067
28068@itemize @bullet
28069@item
28070Generate an object file in memory with symbols and other desired debug
28071information. The file must include the virtual addresses of the sections.
28072
28073@item
28074Create a code entry for the file, which gives the start and size of the symbol
28075file.
28076
28077@item
28078Add it to the linked list in the JIT descriptor.
28079
28080@item
28081Point the relevant_entry field of the descriptor at the entry.
28082
28083@item
28084Set @code{action_flag} to @code{JIT_REGISTER} and call
28085@code{__jit_debug_register_code}.
28086@end itemize
28087
28088When @value{GDBN} is attached and the breakpoint fires, @value{GDBN} uses the
28089@code{relevant_entry} pointer so it doesn't have to walk the list looking for
28090new code. However, the linked list must still be maintained in order to allow
28091@value{GDBN} to attach to a running process and still find the symbol files.
28092
28093@node Unregistering Code
28094@section Unregistering Code
28095
28096If code is freed, then the JIT should use the following protocol:
28097
28098@itemize @bullet
28099@item
28100Remove the code entry corresponding to the code from the linked list.
28101
28102@item
28103Point the @code{relevant_entry} field of the descriptor at the code entry.
28104
28105@item
28106Set @code{action_flag} to @code{JIT_UNREGISTER} and call
28107@code{__jit_debug_register_code}.
28108@end itemize
28109
28110If the JIT frees or recompiles code without unregistering it, then @value{GDBN}
28111and the JIT will leak the memory used for the associated symbol files.
28112
8e04817f
AC
28113@node GDB Bugs
28114@chapter Reporting Bugs in @value{GDBN}
28115@cindex bugs in @value{GDBN}
28116@cindex reporting bugs in @value{GDBN}
c906108c 28117
8e04817f 28118Your bug reports play an essential role in making @value{GDBN} reliable.
c906108c 28119
8e04817f
AC
28120Reporting a bug may help you by bringing a solution to your problem, or it
28121may not. But in any case the principal function of a bug report is to help
28122the entire community by making the next version of @value{GDBN} work better. Bug
28123reports are your contribution to the maintenance of @value{GDBN}.
c906108c 28124
8e04817f
AC
28125In order for a bug report to serve its purpose, you must include the
28126information that enables us to fix the bug.
c4555f82
SC
28127
28128@menu
8e04817f
AC
28129* Bug Criteria:: Have you found a bug?
28130* Bug Reporting:: How to report bugs
c4555f82
SC
28131@end menu
28132
8e04817f 28133@node Bug Criteria
79a6e687 28134@section Have You Found a Bug?
8e04817f 28135@cindex bug criteria
c4555f82 28136
8e04817f 28137If you are not sure whether you have found a bug, here are some guidelines:
c4555f82
SC
28138
28139@itemize @bullet
8e04817f
AC
28140@cindex fatal signal
28141@cindex debugger crash
28142@cindex crash of debugger
c4555f82 28143@item
8e04817f
AC
28144If the debugger gets a fatal signal, for any input whatever, that is a
28145@value{GDBN} bug. Reliable debuggers never crash.
28146
28147@cindex error on valid input
28148@item
28149If @value{GDBN} produces an error message for valid input, that is a
28150bug. (Note that if you're cross debugging, the problem may also be
28151somewhere in the connection to the target.)
c4555f82 28152
8e04817f 28153@cindex invalid input
c4555f82 28154@item
8e04817f
AC
28155If @value{GDBN} does not produce an error message for invalid input,
28156that is a bug. However, you should note that your idea of
28157``invalid input'' might be our idea of ``an extension'' or ``support
28158for traditional practice''.
28159
28160@item
28161If you are an experienced user of debugging tools, your suggestions
28162for improvement of @value{GDBN} are welcome in any case.
c4555f82
SC
28163@end itemize
28164
8e04817f 28165@node Bug Reporting
79a6e687 28166@section How to Report Bugs
8e04817f
AC
28167@cindex bug reports
28168@cindex @value{GDBN} bugs, reporting
28169
28170A number of companies and individuals offer support for @sc{gnu} products.
28171If you obtained @value{GDBN} from a support organization, we recommend you
28172contact that organization first.
28173
28174You can find contact information for many support companies and
28175individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs
28176distribution.
28177@c should add a web page ref...
28178
c16158bc
JM
28179@ifset BUGURL
28180@ifset BUGURL_DEFAULT
129188f6 28181In any event, we also recommend that you submit bug reports for
d3e8051b 28182@value{GDBN}. The preferred method is to submit them directly using
129188f6
AC
28183@uref{http://www.gnu.org/software/gdb/bugs/, @value{GDBN}'s Bugs web
28184page}. Alternatively, the @email{bug-gdb@@gnu.org, e-mail gateway} can
28185be used.
8e04817f
AC
28186
28187@strong{Do not send bug reports to @samp{info-gdb}, or to
28188@samp{help-gdb}, or to any newsgroups.} Most users of @value{GDBN} do
28189not want to receive bug reports. Those that do have arranged to receive
28190@samp{bug-gdb}.
28191
28192The mailing list @samp{bug-gdb} has a newsgroup @samp{gnu.gdb.bug} which
28193serves as a repeater. The mailing list and the newsgroup carry exactly
28194the same messages. Often people think of posting bug reports to the
28195newsgroup instead of mailing them. This appears to work, but it has one
28196problem which can be crucial: a newsgroup posting often lacks a mail
28197path back to the sender. Thus, if we need to ask for more information,
28198we may be unable to reach you. For this reason, it is better to send
28199bug reports to the mailing list.
c16158bc
JM
28200@end ifset
28201@ifclear BUGURL_DEFAULT
28202In any event, we also recommend that you submit bug reports for
28203@value{GDBN} to @value{BUGURL}.
28204@end ifclear
28205@end ifset
c4555f82 28206
8e04817f
AC
28207The fundamental principle of reporting bugs usefully is this:
28208@strong{report all the facts}. If you are not sure whether to state a
28209fact or leave it out, state it!
c4555f82 28210
8e04817f
AC
28211Often people omit facts because they think they know what causes the
28212problem and assume that some details do not matter. Thus, you might
28213assume that the name of the variable you use in an example does not matter.
28214Well, probably it does not, but one cannot be sure. Perhaps the bug is a
28215stray memory reference which happens to fetch from the location where that
28216name is stored in memory; perhaps, if the name were different, the contents
28217of that location would fool the debugger into doing the right thing despite
28218the bug. Play it safe and give a specific, complete example. That is the
28219easiest thing for you to do, and the most helpful.
c4555f82 28220
8e04817f
AC
28221Keep in mind that the purpose of a bug report is to enable us to fix the
28222bug. It may be that the bug has been reported previously, but neither
28223you nor we can know that unless your bug report is complete and
28224self-contained.
c4555f82 28225
8e04817f
AC
28226Sometimes people give a few sketchy facts and ask, ``Does this ring a
28227bell?'' Those bug reports are useless, and we urge everyone to
28228@emph{refuse to respond to them} except to chide the sender to report
28229bugs properly.
28230
28231To enable us to fix the bug, you should include all these things:
c4555f82
SC
28232
28233@itemize @bullet
28234@item
8e04817f
AC
28235The version of @value{GDBN}. @value{GDBN} announces it if you start
28236with no arguments; you can also print it at any time using @code{show
28237version}.
c4555f82 28238
8e04817f
AC
28239Without this, we will not know whether there is any point in looking for
28240the bug in the current version of @value{GDBN}.
c4555f82
SC
28241
28242@item
8e04817f
AC
28243The type of machine you are using, and the operating system name and
28244version number.
c4555f82
SC
28245
28246@item
c1468174 28247What compiler (and its version) was used to compile @value{GDBN}---e.g.@:
8e04817f 28248``@value{GCC}--2.8.1''.
c4555f82
SC
28249
28250@item
8e04817f 28251What compiler (and its version) was used to compile the program you are
c1468174 28252debugging---e.g.@: ``@value{GCC}--2.8.1'', or ``HP92453-01 A.10.32.03 HP
3f94c067
BW
28253C Compiler''. For @value{NGCC}, you can say @kbd{@value{GCC} --version}
28254to get this information; for other compilers, see the documentation for
28255those compilers.
c4555f82 28256
8e04817f
AC
28257@item
28258The command arguments you gave the compiler to compile your example and
28259observe the bug. For example, did you use @samp{-O}? To guarantee
28260you will not omit something important, list them all. A copy of the
28261Makefile (or the output from make) is sufficient.
c4555f82 28262
8e04817f
AC
28263If we were to try to guess the arguments, we would probably guess wrong
28264and then we might not encounter the bug.
c4555f82 28265
8e04817f
AC
28266@item
28267A complete input script, and all necessary source files, that will
28268reproduce the bug.
c4555f82 28269
8e04817f
AC
28270@item
28271A description of what behavior you observe that you believe is
28272incorrect. For example, ``It gets a fatal signal.''
c4555f82 28273
8e04817f
AC
28274Of course, if the bug is that @value{GDBN} gets a fatal signal, then we
28275will certainly notice it. But if the bug is incorrect output, we might
28276not notice unless it is glaringly wrong. You might as well not give us
28277a chance to make a mistake.
c4555f82 28278
8e04817f
AC
28279Even if the problem you experience is a fatal signal, you should still
28280say so explicitly. Suppose something strange is going on, such as, your
28281copy of @value{GDBN} is out of synch, or you have encountered a bug in
28282the C library on your system. (This has happened!) Your copy might
28283crash and ours would not. If you told us to expect a crash, then when
28284ours fails to crash, we would know that the bug was not happening for
28285us. If you had not told us to expect a crash, then we would not be able
28286to draw any conclusion from our observations.
c4555f82 28287
e0c07bf0
MC
28288@pindex script
28289@cindex recording a session script
28290To collect all this information, you can use a session recording program
28291such as @command{script}, which is available on many Unix systems.
28292Just run your @value{GDBN} session inside @command{script} and then
28293include the @file{typescript} file with your bug report.
28294
28295Another way to record a @value{GDBN} session is to run @value{GDBN}
28296inside Emacs and then save the entire buffer to a file.
28297
8e04817f
AC
28298@item
28299If you wish to suggest changes to the @value{GDBN} source, send us context
28300diffs. If you even discuss something in the @value{GDBN} source, refer to
28301it by context, not by line number.
c4555f82 28302
8e04817f
AC
28303The line numbers in our development sources will not match those in your
28304sources. Your line numbers would convey no useful information to us.
c4555f82 28305
8e04817f 28306@end itemize
c4555f82 28307
8e04817f 28308Here are some things that are not necessary:
c4555f82 28309
8e04817f
AC
28310@itemize @bullet
28311@item
28312A description of the envelope of the bug.
c4555f82 28313
8e04817f
AC
28314Often people who encounter a bug spend a lot of time investigating
28315which changes to the input file will make the bug go away and which
28316changes will not affect it.
c4555f82 28317
8e04817f
AC
28318This is often time consuming and not very useful, because the way we
28319will find the bug is by running a single example under the debugger
28320with breakpoints, not by pure deduction from a series of examples.
28321We recommend that you save your time for something else.
c4555f82 28322
8e04817f
AC
28323Of course, if you can find a simpler example to report @emph{instead}
28324of the original one, that is a convenience for us. Errors in the
28325output will be easier to spot, running under the debugger will take
28326less time, and so on.
c4555f82 28327
8e04817f
AC
28328However, simplification is not vital; if you do not want to do this,
28329report the bug anyway and send us the entire test case you used.
c4555f82 28330
8e04817f
AC
28331@item
28332A patch for the bug.
c4555f82 28333
8e04817f
AC
28334A patch for the bug does help us if it is a good one. But do not omit
28335the necessary information, such as the test case, on the assumption that
28336a patch is all we need. We might see problems with your patch and decide
28337to fix the problem another way, or we might not understand it at all.
c4555f82 28338
8e04817f
AC
28339Sometimes with a program as complicated as @value{GDBN} it is very hard to
28340construct an example that will make the program follow a certain path
28341through the code. If you do not send us the example, we will not be able
28342to construct one, so we will not be able to verify that the bug is fixed.
c4555f82 28343
8e04817f
AC
28344And if we cannot understand what bug you are trying to fix, or why your
28345patch should be an improvement, we will not install it. A test case will
28346help us to understand.
c4555f82 28347
8e04817f
AC
28348@item
28349A guess about what the bug is or what it depends on.
c4555f82 28350
8e04817f
AC
28351Such guesses are usually wrong. Even we cannot guess right about such
28352things without first using the debugger to find the facts.
28353@end itemize
c4555f82 28354
8e04817f
AC
28355@c The readline documentation is distributed with the readline code
28356@c and consists of the two following files:
28357@c rluser.texinfo
28358@c inc-hist.texinfo
28359@c Use -I with makeinfo to point to the appropriate directory,
28360@c environment var TEXINPUTS with TeX.
5bdf8622 28361@include rluser.texi
8e04817f 28362@include inc-hist.texinfo
c4555f82 28363
c4555f82 28364
8e04817f
AC
28365@node Formatting Documentation
28366@appendix Formatting Documentation
c4555f82 28367
8e04817f
AC
28368@cindex @value{GDBN} reference card
28369@cindex reference card
28370The @value{GDBN} 4 release includes an already-formatted reference card, ready
28371for printing with PostScript or Ghostscript, in the @file{gdb}
28372subdirectory of the main source directory@footnote{In
28373@file{gdb-@value{GDBVN}/gdb/refcard.ps} of the version @value{GDBVN}
28374release.}. If you can use PostScript or Ghostscript with your printer,
28375you can print the reference card immediately with @file{refcard.ps}.
c4555f82 28376
8e04817f
AC
28377The release also includes the source for the reference card. You
28378can format it, using @TeX{}, by typing:
c4555f82 28379
474c8240 28380@smallexample
8e04817f 28381make refcard.dvi
474c8240 28382@end smallexample
c4555f82 28383
8e04817f
AC
28384The @value{GDBN} reference card is designed to print in @dfn{landscape}
28385mode on US ``letter'' size paper;
28386that is, on a sheet 11 inches wide by 8.5 inches
28387high. You will need to specify this form of printing as an option to
28388your @sc{dvi} output program.
c4555f82 28389
8e04817f 28390@cindex documentation
c4555f82 28391
8e04817f
AC
28392All the documentation for @value{GDBN} comes as part of the machine-readable
28393distribution. The documentation is written in Texinfo format, which is
28394a documentation system that uses a single source file to produce both
28395on-line information and a printed manual. You can use one of the Info
28396formatting commands to create the on-line version of the documentation
28397and @TeX{} (or @code{texi2roff}) to typeset the printed version.
c4555f82 28398
8e04817f
AC
28399@value{GDBN} includes an already formatted copy of the on-line Info
28400version of this manual in the @file{gdb} subdirectory. The main Info
28401file is @file{gdb-@value{GDBVN}/gdb/gdb.info}, and it refers to
28402subordinate files matching @samp{gdb.info*} in the same directory. If
28403necessary, you can print out these files, or read them with any editor;
28404but they are easier to read using the @code{info} subsystem in @sc{gnu}
28405Emacs or the standalone @code{info} program, available as part of the
28406@sc{gnu} Texinfo distribution.
c4555f82 28407
8e04817f
AC
28408If you want to format these Info files yourself, you need one of the
28409Info formatting programs, such as @code{texinfo-format-buffer} or
28410@code{makeinfo}.
c4555f82 28411
8e04817f
AC
28412If you have @code{makeinfo} installed, and are in the top level
28413@value{GDBN} source directory (@file{gdb-@value{GDBVN}}, in the case of
28414version @value{GDBVN}), you can make the Info file by typing:
c4555f82 28415
474c8240 28416@smallexample
8e04817f
AC
28417cd gdb
28418make gdb.info
474c8240 28419@end smallexample
c4555f82 28420
8e04817f
AC
28421If you want to typeset and print copies of this manual, you need @TeX{},
28422a program to print its @sc{dvi} output files, and @file{texinfo.tex}, the
28423Texinfo definitions file.
c4555f82 28424
8e04817f
AC
28425@TeX{} is a typesetting program; it does not print files directly, but
28426produces output files called @sc{dvi} files. To print a typeset
28427document, you need a program to print @sc{dvi} files. If your system
28428has @TeX{} installed, chances are it has such a program. The precise
28429command to use depends on your system; @kbd{lpr -d} is common; another
28430(for PostScript devices) is @kbd{dvips}. The @sc{dvi} print command may
28431require a file name without any extension or a @samp{.dvi} extension.
c4555f82 28432
8e04817f
AC
28433@TeX{} also requires a macro definitions file called
28434@file{texinfo.tex}. This file tells @TeX{} how to typeset a document
28435written in Texinfo format. On its own, @TeX{} cannot either read or
28436typeset a Texinfo file. @file{texinfo.tex} is distributed with GDB
28437and is located in the @file{gdb-@var{version-number}/texinfo}
28438directory.
c4555f82 28439
8e04817f 28440If you have @TeX{} and a @sc{dvi} printer program installed, you can
d3e8051b 28441typeset and print this manual. First switch to the @file{gdb}
8e04817f
AC
28442subdirectory of the main source directory (for example, to
28443@file{gdb-@value{GDBVN}/gdb}) and type:
c4555f82 28444
474c8240 28445@smallexample
8e04817f 28446make gdb.dvi
474c8240 28447@end smallexample
c4555f82 28448
8e04817f 28449Then give @file{gdb.dvi} to your @sc{dvi} printing program.
c4555f82 28450
8e04817f
AC
28451@node Installing GDB
28452@appendix Installing @value{GDBN}
8e04817f 28453@cindex installation
c4555f82 28454
7fa2210b
DJ
28455@menu
28456* Requirements:: Requirements for building @value{GDBN}
db2e3e2e 28457* Running Configure:: Invoking the @value{GDBN} @file{configure} script
7fa2210b
DJ
28458* Separate Objdir:: Compiling @value{GDBN} in another directory
28459* Config Names:: Specifying names for hosts and targets
28460* Configure Options:: Summary of options for configure
098b41a6 28461* System-wide configuration:: Having a system-wide init file
7fa2210b
DJ
28462@end menu
28463
28464@node Requirements
79a6e687 28465@section Requirements for Building @value{GDBN}
7fa2210b
DJ
28466@cindex building @value{GDBN}, requirements for
28467
28468Building @value{GDBN} requires various tools and packages to be available.
28469Other packages will be used only if they are found.
28470
79a6e687 28471@heading Tools/Packages Necessary for Building @value{GDBN}
7fa2210b
DJ
28472@table @asis
28473@item ISO C90 compiler
28474@value{GDBN} is written in ISO C90. It should be buildable with any
28475working C90 compiler, e.g.@: GCC.
28476
28477@end table
28478
79a6e687 28479@heading Tools/Packages Optional for Building @value{GDBN}
7fa2210b
DJ
28480@table @asis
28481@item Expat
123dc839 28482@anchor{Expat}
7fa2210b
DJ
28483@value{GDBN} can use the Expat XML parsing library. This library may be
28484included with your operating system distribution; if it is not, you
28485can get the latest version from @url{http://expat.sourceforge.net}.
db2e3e2e 28486The @file{configure} script will search for this library in several
7fa2210b
DJ
28487standard locations; if it is installed in an unusual path, you can
28488use the @option{--with-libexpat-prefix} option to specify its location.
28489
9cceb671
DJ
28490Expat is used for:
28491
28492@itemize @bullet
28493@item
28494Remote protocol memory maps (@pxref{Memory Map Format})
28495@item
28496Target descriptions (@pxref{Target Descriptions})
28497@item
28498Remote shared library lists (@pxref{Library List Format})
28499@item
28500MS-Windows shared libraries (@pxref{Shared Libraries})
28501@end itemize
7fa2210b 28502
31fffb02
CS
28503@item zlib
28504@cindex compressed debug sections
28505@value{GDBN} will use the @samp{zlib} library, if available, to read
28506compressed debug sections. Some linkers, such as GNU gold, are capable
28507of producing binaries with compressed debug sections. If @value{GDBN}
28508is compiled with @samp{zlib}, it will be able to read the debug
28509information in such binaries.
28510
28511The @samp{zlib} library is likely included with your operating system
28512distribution; if it is not, you can get the latest version from
28513@url{http://zlib.net}.
28514
6c7a06a3
TT
28515@item iconv
28516@value{GDBN}'s features related to character sets (@pxref{Character
28517Sets}) require a functioning @code{iconv} implementation. If you are
28518on a GNU system, then this is provided by the GNU C Library. Some
28519other systems also provide a working @code{iconv}.
28520
28521On systems with @code{iconv}, you can install GNU Libiconv. If you
28522have previously installed Libiconv, you can use the
28523@option{--with-libiconv-prefix} option to configure.
28524
28525@value{GDBN}'s top-level @file{configure} and @file{Makefile} will
28526arrange to build Libiconv if a directory named @file{libiconv} appears
28527in the top-most source directory. If Libiconv is built this way, and
28528if the operating system does not provide a suitable @code{iconv}
28529implementation, then the just-built library will automatically be used
28530by @value{GDBN}. One easy way to set this up is to download GNU
28531Libiconv, unpack it, and then rename the directory holding the
28532Libiconv source code to @samp{libiconv}.
7fa2210b
DJ
28533@end table
28534
28535@node Running Configure
db2e3e2e 28536@section Invoking the @value{GDBN} @file{configure} Script
7fa2210b 28537@cindex configuring @value{GDBN}
db2e3e2e 28538@value{GDBN} comes with a @file{configure} script that automates the process
8e04817f
AC
28539of preparing @value{GDBN} for installation; you can then use @code{make} to
28540build the @code{gdb} program.
28541@iftex
28542@c irrelevant in info file; it's as current as the code it lives with.
28543@footnote{If you have a more recent version of @value{GDBN} than @value{GDBVN},
28544look at the @file{README} file in the sources; we may have improved the
28545installation procedures since publishing this manual.}
28546@end iftex
c4555f82 28547
8e04817f
AC
28548The @value{GDBN} distribution includes all the source code you need for
28549@value{GDBN} in a single directory, whose name is usually composed by
28550appending the version number to @samp{gdb}.
c4555f82 28551
8e04817f
AC
28552For example, the @value{GDBN} version @value{GDBVN} distribution is in the
28553@file{gdb-@value{GDBVN}} directory. That directory contains:
c4555f82 28554
8e04817f
AC
28555@table @code
28556@item gdb-@value{GDBVN}/configure @r{(and supporting files)}
28557script for configuring @value{GDBN} and all its supporting libraries
c4555f82 28558
8e04817f
AC
28559@item gdb-@value{GDBVN}/gdb
28560the source specific to @value{GDBN} itself
c4555f82 28561
8e04817f
AC
28562@item gdb-@value{GDBVN}/bfd
28563source for the Binary File Descriptor library
c906108c 28564
8e04817f
AC
28565@item gdb-@value{GDBVN}/include
28566@sc{gnu} include files
c906108c 28567
8e04817f
AC
28568@item gdb-@value{GDBVN}/libiberty
28569source for the @samp{-liberty} free software library
c906108c 28570
8e04817f
AC
28571@item gdb-@value{GDBVN}/opcodes
28572source for the library of opcode tables and disassemblers
c906108c 28573
8e04817f
AC
28574@item gdb-@value{GDBVN}/readline
28575source for the @sc{gnu} command-line interface
c906108c 28576
8e04817f
AC
28577@item gdb-@value{GDBVN}/glob
28578source for the @sc{gnu} filename pattern-matching subroutine
c906108c 28579
8e04817f
AC
28580@item gdb-@value{GDBVN}/mmalloc
28581source for the @sc{gnu} memory-mapped malloc package
28582@end table
c906108c 28583
db2e3e2e 28584The simplest way to configure and build @value{GDBN} is to run @file{configure}
8e04817f
AC
28585from the @file{gdb-@var{version-number}} source directory, which in
28586this example is the @file{gdb-@value{GDBVN}} directory.
c906108c 28587
8e04817f 28588First switch to the @file{gdb-@var{version-number}} source directory
db2e3e2e 28589if you are not already in it; then run @file{configure}. Pass the
8e04817f
AC
28590identifier for the platform on which @value{GDBN} will run as an
28591argument.
c906108c 28592
8e04817f 28593For example:
c906108c 28594
474c8240 28595@smallexample
8e04817f
AC
28596cd gdb-@value{GDBVN}
28597./configure @var{host}
28598make
474c8240 28599@end smallexample
c906108c 28600
8e04817f
AC
28601@noindent
28602where @var{host} is an identifier such as @samp{sun4} or
28603@samp{decstation}, that identifies the platform where @value{GDBN} will run.
db2e3e2e 28604(You can often leave off @var{host}; @file{configure} tries to guess the
8e04817f 28605correct value by examining your system.)
c906108c 28606
8e04817f
AC
28607Running @samp{configure @var{host}} and then running @code{make} builds the
28608@file{bfd}, @file{readline}, @file{mmalloc}, and @file{libiberty}
28609libraries, then @code{gdb} itself. The configured source files, and the
28610binaries, are left in the corresponding source directories.
c906108c 28611
8e04817f 28612@need 750
db2e3e2e 28613@file{configure} is a Bourne-shell (@code{/bin/sh}) script; if your
8e04817f
AC
28614system does not recognize this automatically when you run a different
28615shell, you may need to run @code{sh} on it explicitly:
c906108c 28616
474c8240 28617@smallexample
8e04817f 28618sh configure @var{host}
474c8240 28619@end smallexample
c906108c 28620
db2e3e2e 28621If you run @file{configure} from a directory that contains source
8e04817f 28622directories for multiple libraries or programs, such as the
db2e3e2e
BW
28623@file{gdb-@value{GDBVN}} source directory for version @value{GDBVN},
28624@file{configure}
8e04817f
AC
28625creates configuration files for every directory level underneath (unless
28626you tell it not to, with the @samp{--norecursion} option).
28627
db2e3e2e 28628You should run the @file{configure} script from the top directory in the
94e91d6d 28629source tree, the @file{gdb-@var{version-number}} directory. If you run
db2e3e2e 28630@file{configure} from one of the subdirectories, you will configure only
94e91d6d 28631that subdirectory. That is usually not what you want. In particular,
db2e3e2e 28632if you run the first @file{configure} from the @file{gdb} subdirectory
94e91d6d
MC
28633of the @file{gdb-@var{version-number}} directory, you will omit the
28634configuration of @file{bfd}, @file{readline}, and other sibling
28635directories of the @file{gdb} subdirectory. This leads to build errors
28636about missing include files such as @file{bfd/bfd.h}.
c906108c 28637
8e04817f
AC
28638You can install @code{@value{GDBP}} anywhere; it has no hardwired paths.
28639However, you should make sure that the shell on your path (named by
28640the @samp{SHELL} environment variable) is publicly readable. Remember
28641that @value{GDBN} uses the shell to start your program---some systems refuse to
28642let @value{GDBN} debug child processes whose programs are not readable.
c906108c 28643
8e04817f 28644@node Separate Objdir
79a6e687 28645@section Compiling @value{GDBN} in Another Directory
c906108c 28646
8e04817f
AC
28647If you want to run @value{GDBN} versions for several host or target machines,
28648you need a different @code{gdb} compiled for each combination of
db2e3e2e 28649host and target. @file{configure} is designed to make this easy by
8e04817f
AC
28650allowing you to generate each configuration in a separate subdirectory,
28651rather than in the source directory. If your @code{make} program
28652handles the @samp{VPATH} feature (@sc{gnu} @code{make} does), running
28653@code{make} in each of these directories builds the @code{gdb}
28654program specified there.
c906108c 28655
db2e3e2e 28656To build @code{gdb} in a separate directory, run @file{configure}
8e04817f 28657with the @samp{--srcdir} option to specify where to find the source.
db2e3e2e
BW
28658(You also need to specify a path to find @file{configure}
28659itself from your working directory. If the path to @file{configure}
8e04817f
AC
28660would be the same as the argument to @samp{--srcdir}, you can leave out
28661the @samp{--srcdir} option; it is assumed.)
c906108c 28662
8e04817f
AC
28663For example, with version @value{GDBVN}, you can build @value{GDBN} in a
28664separate directory for a Sun 4 like this:
c906108c 28665
474c8240 28666@smallexample
8e04817f
AC
28667@group
28668cd gdb-@value{GDBVN}
28669mkdir ../gdb-sun4
28670cd ../gdb-sun4
28671../gdb-@value{GDBVN}/configure sun4
28672make
28673@end group
474c8240 28674@end smallexample
c906108c 28675
db2e3e2e 28676When @file{configure} builds a configuration using a remote source
8e04817f
AC
28677directory, it creates a tree for the binaries with the same structure
28678(and using the same names) as the tree under the source directory. In
28679the example, you'd find the Sun 4 library @file{libiberty.a} in the
28680directory @file{gdb-sun4/libiberty}, and @value{GDBN} itself in
28681@file{gdb-sun4/gdb}.
c906108c 28682
94e91d6d
MC
28683Make sure that your path to the @file{configure} script has just one
28684instance of @file{gdb} in it. If your path to @file{configure} looks
28685like @file{../gdb-@value{GDBVN}/gdb/configure}, you are configuring only
28686one subdirectory of @value{GDBN}, not the whole package. This leads to
28687build errors about missing include files such as @file{bfd/bfd.h}.
28688
8e04817f
AC
28689One popular reason to build several @value{GDBN} configurations in separate
28690directories is to configure @value{GDBN} for cross-compiling (where
28691@value{GDBN} runs on one machine---the @dfn{host}---while debugging
28692programs that run on another machine---the @dfn{target}).
28693You specify a cross-debugging target by
db2e3e2e 28694giving the @samp{--target=@var{target}} option to @file{configure}.
c906108c 28695
8e04817f
AC
28696When you run @code{make} to build a program or library, you must run
28697it in a configured directory---whatever directory you were in when you
db2e3e2e 28698called @file{configure} (or one of its subdirectories).
c906108c 28699
db2e3e2e 28700The @code{Makefile} that @file{configure} generates in each source
8e04817f
AC
28701directory also runs recursively. If you type @code{make} in a source
28702directory such as @file{gdb-@value{GDBVN}} (or in a separate configured
28703directory configured with @samp{--srcdir=@var{dirname}/gdb-@value{GDBVN}}), you
28704will build all the required libraries, and then build GDB.
c906108c 28705
8e04817f
AC
28706When you have multiple hosts or targets configured in separate
28707directories, you can run @code{make} on them in parallel (for example,
28708if they are NFS-mounted on each of the hosts); they will not interfere
28709with each other.
c906108c 28710
8e04817f 28711@node Config Names
79a6e687 28712@section Specifying Names for Hosts and Targets
c906108c 28713
db2e3e2e 28714The specifications used for hosts and targets in the @file{configure}
8e04817f
AC
28715script are based on a three-part naming scheme, but some short predefined
28716aliases are also supported. The full naming scheme encodes three pieces
28717of information in the following pattern:
c906108c 28718
474c8240 28719@smallexample
8e04817f 28720@var{architecture}-@var{vendor}-@var{os}
474c8240 28721@end smallexample
c906108c 28722
8e04817f
AC
28723For example, you can use the alias @code{sun4} as a @var{host} argument,
28724or as the value for @var{target} in a @code{--target=@var{target}}
28725option. The equivalent full name is @samp{sparc-sun-sunos4}.
c906108c 28726
db2e3e2e 28727The @file{configure} script accompanying @value{GDBN} does not provide
8e04817f 28728any query facility to list all supported host and target names or
db2e3e2e 28729aliases. @file{configure} calls the Bourne shell script
8e04817f
AC
28730@code{config.sub} to map abbreviations to full names; you can read the
28731script, if you wish, or you can use it to test your guesses on
28732abbreviations---for example:
c906108c 28733
8e04817f
AC
28734@smallexample
28735% sh config.sub i386-linux
28736i386-pc-linux-gnu
28737% sh config.sub alpha-linux
28738alpha-unknown-linux-gnu
28739% sh config.sub hp9k700
28740hppa1.1-hp-hpux
28741% sh config.sub sun4
28742sparc-sun-sunos4.1.1
28743% sh config.sub sun3
28744m68k-sun-sunos4.1.1
28745% sh config.sub i986v
28746Invalid configuration `i986v': machine `i986v' not recognized
28747@end smallexample
c906108c 28748
8e04817f
AC
28749@noindent
28750@code{config.sub} is also distributed in the @value{GDBN} source
28751directory (@file{gdb-@value{GDBVN}}, for version @value{GDBVN}).
d700128c 28752
8e04817f 28753@node Configure Options
db2e3e2e 28754@section @file{configure} Options
c906108c 28755
db2e3e2e
BW
28756Here is a summary of the @file{configure} options and arguments that
28757are most often useful for building @value{GDBN}. @file{configure} also has
8e04817f 28758several other options not listed here. @inforef{What Configure
db2e3e2e 28759Does,,configure.info}, for a full explanation of @file{configure}.
c906108c 28760
474c8240 28761@smallexample
8e04817f
AC
28762configure @r{[}--help@r{]}
28763 @r{[}--prefix=@var{dir}@r{]}
28764 @r{[}--exec-prefix=@var{dir}@r{]}
28765 @r{[}--srcdir=@var{dirname}@r{]}
28766 @r{[}--norecursion@r{]} @r{[}--rm@r{]}
28767 @r{[}--target=@var{target}@r{]}
28768 @var{host}
474c8240 28769@end smallexample
c906108c 28770
8e04817f
AC
28771@noindent
28772You may introduce options with a single @samp{-} rather than
28773@samp{--} if you prefer; but you may abbreviate option names if you use
28774@samp{--}.
c906108c 28775
8e04817f
AC
28776@table @code
28777@item --help
db2e3e2e 28778Display a quick summary of how to invoke @file{configure}.
c906108c 28779
8e04817f
AC
28780@item --prefix=@var{dir}
28781Configure the source to install programs and files under directory
28782@file{@var{dir}}.
c906108c 28783
8e04817f
AC
28784@item --exec-prefix=@var{dir}
28785Configure the source to install programs under directory
28786@file{@var{dir}}.
c906108c 28787
8e04817f
AC
28788@c avoid splitting the warning from the explanation:
28789@need 2000
28790@item --srcdir=@var{dirname}
28791@strong{Warning: using this option requires @sc{gnu} @code{make}, or another
28792@code{make} that implements the @code{VPATH} feature.}@*
28793Use this option to make configurations in directories separate from the
28794@value{GDBN} source directories. Among other things, you can use this to
28795build (or maintain) several configurations simultaneously, in separate
db2e3e2e 28796directories. @file{configure} writes configuration-specific files in
8e04817f 28797the current directory, but arranges for them to use the source in the
db2e3e2e 28798directory @var{dirname}. @file{configure} creates directories under
8e04817f
AC
28799the working directory in parallel to the source directories below
28800@var{dirname}.
c906108c 28801
8e04817f 28802@item --norecursion
db2e3e2e 28803Configure only the directory level where @file{configure} is executed; do not
8e04817f 28804propagate configuration to subdirectories.
c906108c 28805
8e04817f
AC
28806@item --target=@var{target}
28807Configure @value{GDBN} for cross-debugging programs running on the specified
28808@var{target}. Without this option, @value{GDBN} is configured to debug
28809programs that run on the same machine (@var{host}) as @value{GDBN} itself.
c906108c 28810
8e04817f 28811There is no convenient way to generate a list of all available targets.
c906108c 28812
8e04817f
AC
28813@item @var{host} @dots{}
28814Configure @value{GDBN} to run on the specified @var{host}.
c906108c 28815
8e04817f
AC
28816There is no convenient way to generate a list of all available hosts.
28817@end table
c906108c 28818
8e04817f
AC
28819There are many other options available as well, but they are generally
28820needed for special purposes only.
c906108c 28821
098b41a6
JG
28822@node System-wide configuration
28823@section System-wide configuration and settings
28824@cindex system-wide init file
28825
28826@value{GDBN} can be configured to have a system-wide init file;
28827this file will be read and executed at startup (@pxref{Startup, , What
28828@value{GDBN} does during startup}).
28829
28830Here is the corresponding configure option:
28831
28832@table @code
28833@item --with-system-gdbinit=@var{file}
28834Specify that the default location of the system-wide init file is
28835@var{file}.
28836@end table
28837
28838If @value{GDBN} has been configured with the option @option{--prefix=$prefix},
28839it may be subject to relocation. Two possible cases:
28840
28841@itemize @bullet
28842@item
28843If the default location of this init file contains @file{$prefix},
28844it will be subject to relocation. Suppose that the configure options
28845are @option{--prefix=$prefix --with-system-gdbinit=$prefix/etc/gdbinit};
28846if @value{GDBN} is moved from @file{$prefix} to @file{$install}, the system
28847init file is looked for as @file{$install/etc/gdbinit} instead of
28848@file{$prefix/etc/gdbinit}.
28849
28850@item
28851By contrast, if the default location does not contain the prefix,
28852it will not be relocated. E.g.@: if @value{GDBN} has been configured with
28853@option{--prefix=/usr/local --with-system-gdbinit=/usr/share/gdb/gdbinit},
28854then @value{GDBN} will always look for @file{/usr/share/gdb/gdbinit},
28855wherever @value{GDBN} is installed.
28856@end itemize
28857
8e04817f
AC
28858@node Maintenance Commands
28859@appendix Maintenance Commands
28860@cindex maintenance commands
28861@cindex internal commands
c906108c 28862
8e04817f 28863In addition to commands intended for @value{GDBN} users, @value{GDBN}
09d4efe1
EZ
28864includes a number of commands intended for @value{GDBN} developers,
28865that are not documented elsewhere in this manual. These commands are
da316a69
EZ
28866provided here for reference. (For commands that turn on debugging
28867messages, see @ref{Debugging Output}.)
c906108c 28868
8e04817f 28869@table @code
09d4efe1 28870@kindex maint agent
782b2b07 28871@kindex maint agent-eval
09d4efe1 28872@item maint agent @var{expression}
782b2b07 28873@itemx maint agent-eval @var{expression}
09d4efe1
EZ
28874Translate the given @var{expression} into remote agent bytecodes.
28875This command is useful for debugging the Agent Expression mechanism
782b2b07
SS
28876(@pxref{Agent Expressions}). The @samp{agent} version produces an
28877expression useful for data collection, such as by tracepoints, while
28878@samp{maint agent-eval} produces an expression that evaluates directly
28879to a result. For instance, a collection expression for @code{globa +
28880globb} will include bytecodes to record four bytes of memory at each
28881of the addresses of @code{globa} and @code{globb}, while discarding
28882the result of the addition, while an evaluation expression will do the
28883addition and return the sum.
09d4efe1 28884
8e04817f
AC
28885@kindex maint info breakpoints
28886@item @anchor{maint info breakpoints}maint info breakpoints
28887Using the same format as @samp{info breakpoints}, display both the
28888breakpoints you've set explicitly, and those @value{GDBN} is using for
28889internal purposes. Internal breakpoints are shown with negative
28890breakpoint numbers. The type column identifies what kind of breakpoint
28891is shown:
c906108c 28892
8e04817f
AC
28893@table @code
28894@item breakpoint
28895Normal, explicitly set breakpoint.
c906108c 28896
8e04817f
AC
28897@item watchpoint
28898Normal, explicitly set watchpoint.
c906108c 28899
8e04817f
AC
28900@item longjmp
28901Internal breakpoint, used to handle correctly stepping through
28902@code{longjmp} calls.
c906108c 28903
8e04817f
AC
28904@item longjmp resume
28905Internal breakpoint at the target of a @code{longjmp}.
c906108c 28906
8e04817f
AC
28907@item until
28908Temporary internal breakpoint used by the @value{GDBN} @code{until} command.
c906108c 28909
8e04817f
AC
28910@item finish
28911Temporary internal breakpoint used by the @value{GDBN} @code{finish} command.
c906108c 28912
8e04817f
AC
28913@item shlib events
28914Shared library events.
c906108c 28915
8e04817f 28916@end table
c906108c 28917
fff08868
HZ
28918@kindex set displaced-stepping
28919@kindex show displaced-stepping
237fc4c9
PA
28920@cindex displaced stepping support
28921@cindex out-of-line single-stepping
fff08868
HZ
28922@item set displaced-stepping
28923@itemx show displaced-stepping
237fc4c9 28924Control whether or not @value{GDBN} will do @dfn{displaced stepping}
fff08868
HZ
28925if the target supports it. Displaced stepping is a way to single-step
28926over breakpoints without removing them from the inferior, by executing
28927an out-of-line copy of the instruction that was originally at the
28928breakpoint location. It is also known as out-of-line single-stepping.
28929
28930@table @code
28931@item set displaced-stepping on
28932If the target architecture supports it, @value{GDBN} will use
28933displaced stepping to step over breakpoints.
28934
28935@item set displaced-stepping off
28936@value{GDBN} will not use displaced stepping to step over breakpoints,
28937even if such is supported by the target architecture.
28938
28939@cindex non-stop mode, and @samp{set displaced-stepping}
28940@item set displaced-stepping auto
28941This is the default mode. @value{GDBN} will use displaced stepping
28942only if non-stop mode is active (@pxref{Non-Stop Mode}) and the target
28943architecture supports displaced stepping.
28944@end table
237fc4c9 28945
09d4efe1
EZ
28946@kindex maint check-symtabs
28947@item maint check-symtabs
28948Check the consistency of psymtabs and symtabs.
28949
28950@kindex maint cplus first_component
28951@item maint cplus first_component @var{name}
28952Print the first C@t{++} class/namespace component of @var{name}.
28953
28954@kindex maint cplus namespace
28955@item maint cplus namespace
28956Print the list of possible C@t{++} namespaces.
28957
28958@kindex maint demangle
28959@item maint demangle @var{name}
d3e8051b 28960Demangle a C@t{++} or Objective-C mangled @var{name}.
09d4efe1
EZ
28961
28962@kindex maint deprecate
28963@kindex maint undeprecate
28964@cindex deprecated commands
28965@item maint deprecate @var{command} @r{[}@var{replacement}@r{]}
28966@itemx maint undeprecate @var{command}
28967Deprecate or undeprecate the named @var{command}. Deprecated commands
28968cause @value{GDBN} to issue a warning when you use them. The optional
28969argument @var{replacement} says which newer command should be used in
28970favor of the deprecated one; if it is given, @value{GDBN} will mention
28971the replacement as part of the warning.
28972
28973@kindex maint dump-me
28974@item maint dump-me
721c2651 28975@cindex @code{SIGQUIT} signal, dump core of @value{GDBN}
09d4efe1 28976Cause a fatal signal in the debugger and force it to dump its core.
721c2651
EZ
28977This is supported only on systems which support aborting a program
28978with the @code{SIGQUIT} signal.
09d4efe1 28979
8d30a00d
AC
28980@kindex maint internal-error
28981@kindex maint internal-warning
09d4efe1
EZ
28982@item maint internal-error @r{[}@var{message-text}@r{]}
28983@itemx maint internal-warning @r{[}@var{message-text}@r{]}
8d30a00d
AC
28984Cause @value{GDBN} to call the internal function @code{internal_error}
28985or @code{internal_warning} and hence behave as though an internal error
28986or internal warning has been detected. In addition to reporting the
28987internal problem, these functions give the user the opportunity to
28988either quit @value{GDBN} or create a core file of the current
28989@value{GDBN} session.
28990
09d4efe1
EZ
28991These commands take an optional parameter @var{message-text} that is
28992used as the text of the error or warning message.
28993
d3e8051b 28994Here's an example of using @code{internal-error}:
09d4efe1 28995
8d30a00d 28996@smallexample
f7dc1244 28997(@value{GDBP}) @kbd{maint internal-error testing, 1, 2}
8d30a00d
AC
28998@dots{}/maint.c:121: internal-error: testing, 1, 2
28999A problem internal to GDB has been detected. Further
29000debugging may prove unreliable.
29001Quit this debugging session? (y or n) @kbd{n}
29002Create a core file? (y or n) @kbd{n}
f7dc1244 29003(@value{GDBP})
8d30a00d
AC
29004@end smallexample
29005
3c16cced
PA
29006@cindex @value{GDBN} internal error
29007@cindex internal errors, control of @value{GDBN} behavior
29008
29009@kindex maint set internal-error
29010@kindex maint show internal-error
29011@kindex maint set internal-warning
29012@kindex maint show internal-warning
29013@item maint set internal-error @var{action} [ask|yes|no]
29014@itemx maint show internal-error @var{action}
29015@itemx maint set internal-warning @var{action} [ask|yes|no]
29016@itemx maint show internal-warning @var{action}
29017When @value{GDBN} reports an internal problem (error or warning) it
29018gives the user the opportunity to both quit @value{GDBN} and create a
29019core file of the current @value{GDBN} session. These commands let you
29020override the default behaviour for each particular @var{action},
29021described in the table below.
29022
29023@table @samp
29024@item quit
29025You can specify that @value{GDBN} should always (yes) or never (no)
29026quit. The default is to ask the user what to do.
29027
29028@item corefile
29029You can specify that @value{GDBN} should always (yes) or never (no)
29030create a core file. The default is to ask the user what to do.
29031@end table
29032
09d4efe1
EZ
29033@kindex maint packet
29034@item maint packet @var{text}
29035If @value{GDBN} is talking to an inferior via the serial protocol,
29036then this command sends the string @var{text} to the inferior, and
29037displays the response packet. @value{GDBN} supplies the initial
29038@samp{$} character, the terminating @samp{#} character, and the
29039checksum.
29040
29041@kindex maint print architecture
29042@item maint print architecture @r{[}@var{file}@r{]}
29043Print the entire architecture configuration. The optional argument
29044@var{file} names the file where the output goes.
8d30a00d 29045
81adfced
DJ
29046@kindex maint print c-tdesc
29047@item maint print c-tdesc
29048Print the current target description (@pxref{Target Descriptions}) as
29049a C source file. The created source file can be used in @value{GDBN}
29050when an XML parser is not available to parse the description.
29051
00905d52
AC
29052@kindex maint print dummy-frames
29053@item maint print dummy-frames
00905d52
AC
29054Prints the contents of @value{GDBN}'s internal dummy-frame stack.
29055
29056@smallexample
f7dc1244 29057(@value{GDBP}) @kbd{b add}
00905d52 29058@dots{}
f7dc1244 29059(@value{GDBP}) @kbd{print add(2,3)}
00905d52
AC
29060Breakpoint 2, add (a=2, b=3) at @dots{}
2906158 return (a + b);
29062The program being debugged stopped while in a function called from GDB.
29063@dots{}
f7dc1244 29064(@value{GDBP}) @kbd{maint print dummy-frames}
00905d52
AC
290650x1a57c80: pc=0x01014068 fp=0x0200bddc sp=0x0200bdd6
29066 top=0x0200bdd4 id=@{stack=0x200bddc,code=0x101405c@}
29067 call_lo=0x01014000 call_hi=0x01014001
f7dc1244 29068(@value{GDBP})
00905d52
AC
29069@end smallexample
29070
29071Takes an optional file parameter.
29072
0680b120
AC
29073@kindex maint print registers
29074@kindex maint print raw-registers
29075@kindex maint print cooked-registers
617073a9 29076@kindex maint print register-groups
09d4efe1
EZ
29077@item maint print registers @r{[}@var{file}@r{]}
29078@itemx maint print raw-registers @r{[}@var{file}@r{]}
29079@itemx maint print cooked-registers @r{[}@var{file}@r{]}
29080@itemx maint print register-groups @r{[}@var{file}@r{]}
0680b120
AC
29081Print @value{GDBN}'s internal register data structures.
29082
617073a9
AC
29083The command @code{maint print raw-registers} includes the contents of
29084the raw register cache; the command @code{maint print cooked-registers}
29085includes the (cooked) value of all registers; and the command
29086@code{maint print register-groups} includes the groups that each
29087register is a member of. @xref{Registers,, Registers, gdbint,
29088@value{GDBN} Internals}.
0680b120 29089
09d4efe1
EZ
29090These commands take an optional parameter, a file name to which to
29091write the information.
0680b120 29092
617073a9 29093@kindex maint print reggroups
09d4efe1
EZ
29094@item maint print reggroups @r{[}@var{file}@r{]}
29095Print @value{GDBN}'s internal register group data structures. The
29096optional argument @var{file} tells to what file to write the
29097information.
617073a9 29098
09d4efe1 29099The register groups info looks like this:
617073a9
AC
29100
29101@smallexample
f7dc1244 29102(@value{GDBP}) @kbd{maint print reggroups}
b383017d
RM
29103 Group Type
29104 general user
29105 float user
29106 all user
29107 vector user
29108 system user
29109 save internal
29110 restore internal
617073a9
AC
29111@end smallexample
29112
09d4efe1
EZ
29113@kindex flushregs
29114@item flushregs
29115This command forces @value{GDBN} to flush its internal register cache.
29116
29117@kindex maint print objfiles
29118@cindex info for known object files
29119@item maint print objfiles
29120Print a dump of all known object files. For each object file, this
29121command prints its name, address in memory, and all of its psymtabs
29122and symtabs.
29123
29124@kindex maint print statistics
29125@cindex bcache statistics
29126@item maint print statistics
29127This command prints, for each object file in the program, various data
29128about that object file followed by the byte cache (@dfn{bcache})
29129statistics for the object file. The objfile data includes the number
d3e8051b 29130of minimal, partial, full, and stabs symbols, the number of types
09d4efe1
EZ
29131defined by the objfile, the number of as yet unexpanded psym tables,
29132the number of line tables and string tables, and the amount of memory
29133used by the various tables. The bcache statistics include the counts,
29134sizes, and counts of duplicates of all and unique objects, max,
29135average, and median entry size, total memory used and its overhead and
29136savings, and various measures of the hash table size and chain
29137lengths.
29138
c7ba131e
JB
29139@kindex maint print target-stack
29140@cindex target stack description
29141@item maint print target-stack
29142A @dfn{target} is an interface between the debugger and a particular
29143kind of file or process. Targets can be stacked in @dfn{strata},
29144so that more than one target can potentially respond to a request.
29145In particular, memory accesses will walk down the stack of targets
29146until they find a target that is interested in handling that particular
29147address.
29148
29149This command prints a short description of each layer that was pushed on
29150the @dfn{target stack}, starting from the top layer down to the bottom one.
29151
09d4efe1
EZ
29152@kindex maint print type
29153@cindex type chain of a data type
29154@item maint print type @var{expr}
29155Print the type chain for a type specified by @var{expr}. The argument
29156can be either a type name or a symbol. If it is a symbol, the type of
29157that symbol is described. The type chain produced by this command is
29158a recursive definition of the data type as stored in @value{GDBN}'s
29159data structures, including its flags and contained types.
29160
29161@kindex maint set dwarf2 max-cache-age
29162@kindex maint show dwarf2 max-cache-age
29163@item maint set dwarf2 max-cache-age
29164@itemx maint show dwarf2 max-cache-age
29165Control the DWARF 2 compilation unit cache.
29166
29167@cindex DWARF 2 compilation units cache
29168In object files with inter-compilation-unit references, such as those
29169produced by the GCC option @samp{-feliminate-dwarf2-dups}, the DWARF 2
29170reader needs to frequently refer to previously read compilation units.
29171This setting controls how long a compilation unit will remain in the
29172cache if it is not referenced. A higher limit means that cached
29173compilation units will be stored in memory longer, and more total
29174memory will be used. Setting it to zero disables caching, which will
29175slow down @value{GDBN} startup, but reduce memory consumption.
29176
e7ba9c65
DJ
29177@kindex maint set profile
29178@kindex maint show profile
29179@cindex profiling GDB
29180@item maint set profile
29181@itemx maint show profile
29182Control profiling of @value{GDBN}.
29183
29184Profiling will be disabled until you use the @samp{maint set profile}
29185command to enable it. When you enable profiling, the system will begin
29186collecting timing and execution count data; when you disable profiling or
29187exit @value{GDBN}, the results will be written to a log file. Remember that
29188if you use profiling, @value{GDBN} will overwrite the profiling log file
29189(often called @file{gmon.out}). If you have a record of important profiling
29190data in a @file{gmon.out} file, be sure to move it to a safe location.
29191
29192Configuring with @samp{--enable-profiling} arranges for @value{GDBN} to be
b383017d 29193compiled with the @samp{-pg} compiler option.
e7ba9c65 29194
cbe54154
PA
29195@kindex maint set show-debug-regs
29196@kindex maint show show-debug-regs
eac35c4e 29197@cindex hardware debug registers
cbe54154
PA
29198@item maint set show-debug-regs
29199@itemx maint show show-debug-regs
eac35c4e 29200Control whether to show variables that mirror the hardware debug
09d4efe1 29201registers. Use @code{ON} to enable, @code{OFF} to disable. If
3f94c067 29202enabled, the debug registers values are shown when @value{GDBN} inserts or
09d4efe1
EZ
29203removes a hardware breakpoint or watchpoint, and when the inferior
29204triggers a hardware-assisted breakpoint or watchpoint.
29205
29206@kindex maint space
29207@cindex memory used by commands
29208@item maint space
29209Control whether to display memory usage for each command. If set to a
29210nonzero value, @value{GDBN} will display how much memory each command
29211took, following the command's own output. This can also be requested
29212by invoking @value{GDBN} with the @option{--statistics} command-line
29213switch (@pxref{Mode Options}).
29214
29215@kindex maint time
29216@cindex time of command execution
29217@item maint time
29218Control whether to display the execution time for each command. If
29219set to a nonzero value, @value{GDBN} will display how much time it
29220took to execute each command, following the command's own output.
e2b7ddea
VP
29221The time is not printed for the commands that run the target, since
29222there's no mechanism currently to compute how much time was spend
29223by @value{GDBN} and how much time was spend by the program been debugged.
29224it's not possibly currently
09d4efe1
EZ
29225This can also be requested by invoking @value{GDBN} with the
29226@option{--statistics} command-line switch (@pxref{Mode Options}).
29227
29228@kindex maint translate-address
29229@item maint translate-address @r{[}@var{section}@r{]} @var{addr}
29230Find the symbol stored at the location specified by the address
29231@var{addr} and an optional section name @var{section}. If found,
29232@value{GDBN} prints the name of the closest symbol and an offset from
29233the symbol's location to the specified address. This is similar to
29234the @code{info address} command (@pxref{Symbols}), except that this
29235command also allows to find symbols in other sections.
ae038cb0 29236
c14c28ba
PP
29237If section was not specified, the section in which the symbol was found
29238is also printed. For dynamically linked executables, the name of
29239executable or shared library containing the symbol is printed as well.
29240
8e04817f 29241@end table
c906108c 29242
9c16f35a
EZ
29243The following command is useful for non-interactive invocations of
29244@value{GDBN}, such as in the test suite.
29245
29246@table @code
29247@item set watchdog @var{nsec}
29248@kindex set watchdog
29249@cindex watchdog timer
29250@cindex timeout for commands
29251Set the maximum number of seconds @value{GDBN} will wait for the
29252target operation to finish. If this time expires, @value{GDBN}
29253reports and error and the command is aborted.
29254
29255@item show watchdog
29256Show the current setting of the target wait timeout.
29257@end table
c906108c 29258
e0ce93ac 29259@node Remote Protocol
8e04817f 29260@appendix @value{GDBN} Remote Serial Protocol
c906108c 29261
ee2d5c50
AC
29262@menu
29263* Overview::
29264* Packets::
29265* Stop Reply Packets::
29266* General Query Packets::
a1dcb23a 29267* Architecture-Specific Protocol Details::
9d29849a 29268* Tracepoint Packets::
a6b151f1 29269* Host I/O Packets::
9a6253be 29270* Interrupts::
8b23ecc4
SL
29271* Notification Packets::
29272* Remote Non-Stop::
a6f3e723 29273* Packet Acknowledgment::
ee2d5c50 29274* Examples::
79a6e687 29275* File-I/O Remote Protocol Extension::
cfa9d6d9 29276* Library List Format::
79a6e687 29277* Memory Map Format::
dc146f7c 29278* Thread List Format::
ee2d5c50
AC
29279@end menu
29280
29281@node Overview
29282@section Overview
29283
8e04817f
AC
29284There may be occasions when you need to know something about the
29285protocol---for example, if there is only one serial port to your target
29286machine, you might want your program to do something special if it
29287recognizes a packet meant for @value{GDBN}.
c906108c 29288
d2c6833e 29289In the examples below, @samp{->} and @samp{<-} are used to indicate
bf06d120 29290transmitted and received data, respectively.
c906108c 29291
8e04817f
AC
29292@cindex protocol, @value{GDBN} remote serial
29293@cindex serial protocol, @value{GDBN} remote
29294@cindex remote serial protocol
8b23ecc4
SL
29295All @value{GDBN} commands and responses (other than acknowledgments
29296and notifications, see @ref{Notification Packets}) are sent as a
29297@var{packet}. A @var{packet} is introduced with the character
8e04817f
AC
29298@samp{$}, the actual @var{packet-data}, and the terminating character
29299@samp{#} followed by a two-digit @var{checksum}:
c906108c 29300
474c8240 29301@smallexample
8e04817f 29302@code{$}@var{packet-data}@code{#}@var{checksum}
474c8240 29303@end smallexample
8e04817f 29304@noindent
c906108c 29305
8e04817f
AC
29306@cindex checksum, for @value{GDBN} remote
29307@noindent
29308The two-digit @var{checksum} is computed as the modulo 256 sum of all
29309characters between the leading @samp{$} and the trailing @samp{#} (an
29310eight bit unsigned checksum).
c906108c 29311
8e04817f
AC
29312Implementors should note that prior to @value{GDBN} 5.0 the protocol
29313specification also included an optional two-digit @var{sequence-id}:
c906108c 29314
474c8240 29315@smallexample
8e04817f 29316@code{$}@var{sequence-id}@code{:}@var{packet-data}@code{#}@var{checksum}
474c8240 29317@end smallexample
c906108c 29318
8e04817f
AC
29319@cindex sequence-id, for @value{GDBN} remote
29320@noindent
29321That @var{sequence-id} was appended to the acknowledgment. @value{GDBN}
29322has never output @var{sequence-id}s. Stubs that handle packets added
29323since @value{GDBN} 5.0 must not accept @var{sequence-id}.
c906108c 29324
8e04817f
AC
29325When either the host or the target machine receives a packet, the first
29326response expected is an acknowledgment: either @samp{+} (to indicate
29327the package was received correctly) or @samp{-} (to request
29328retransmission):
c906108c 29329
474c8240 29330@smallexample
d2c6833e
AC
29331-> @code{$}@var{packet-data}@code{#}@var{checksum}
29332<- @code{+}
474c8240 29333@end smallexample
8e04817f 29334@noindent
53a5351d 29335
a6f3e723
SL
29336The @samp{+}/@samp{-} acknowledgments can be disabled
29337once a connection is established.
29338@xref{Packet Acknowledgment}, for details.
29339
8e04817f
AC
29340The host (@value{GDBN}) sends @var{command}s, and the target (the
29341debugging stub incorporated in your program) sends a @var{response}. In
29342the case of step and continue @var{command}s, the response is only sent
8b23ecc4
SL
29343when the operation has completed, and the target has again stopped all
29344threads in all attached processes. This is the default all-stop mode
29345behavior, but the remote protocol also supports @value{GDBN}'s non-stop
29346execution mode; see @ref{Remote Non-Stop}, for details.
c906108c 29347
8e04817f
AC
29348@var{packet-data} consists of a sequence of characters with the
29349exception of @samp{#} and @samp{$} (see @samp{X} packet for additional
29350exceptions).
c906108c 29351
ee2d5c50 29352@cindex remote protocol, field separator
0876f84a 29353Fields within the packet should be separated using @samp{,} @samp{;} or
8e04817f 29354@samp{:}. Except where otherwise noted all numbers are represented in
ee2d5c50 29355@sc{hex} with leading zeros suppressed.
c906108c 29356
8e04817f
AC
29357Implementors should note that prior to @value{GDBN} 5.0, the character
29358@samp{:} could not appear as the third character in a packet (as it
29359would potentially conflict with the @var{sequence-id}).
c906108c 29360
0876f84a
DJ
29361@cindex remote protocol, binary data
29362@anchor{Binary Data}
29363Binary data in most packets is encoded either as two hexadecimal
29364digits per byte of binary data. This allowed the traditional remote
29365protocol to work over connections which were only seven-bit clean.
29366Some packets designed more recently assume an eight-bit clean
29367connection, and use a more efficient encoding to send and receive
29368binary data.
29369
29370The binary data representation uses @code{7d} (@sc{ascii} @samp{@}})
29371as an escape character. Any escaped byte is transmitted as the escape
29372character followed by the original character XORed with @code{0x20}.
29373For example, the byte @code{0x7d} would be transmitted as the two
29374bytes @code{0x7d 0x5d}. The bytes @code{0x23} (@sc{ascii} @samp{#}),
29375@code{0x24} (@sc{ascii} @samp{$}), and @code{0x7d} (@sc{ascii}
29376@samp{@}}) must always be escaped. Responses sent by the stub
29377must also escape @code{0x2a} (@sc{ascii} @samp{*}), so that it
29378is not interpreted as the start of a run-length encoded sequence
29379(described next).
29380
1d3811f6
DJ
29381Response @var{data} can be run-length encoded to save space.
29382Run-length encoding replaces runs of identical characters with one
29383instance of the repeated character, followed by a @samp{*} and a
29384repeat count. The repeat count is itself sent encoded, to avoid
29385binary characters in @var{data}: a value of @var{n} is sent as
29386@code{@var{n}+29}. For a repeat count greater or equal to 3, this
29387produces a printable @sc{ascii} character, e.g.@: a space (@sc{ascii}
29388code 32) for a repeat count of 3. (This is because run-length
29389encoding starts to win for counts 3 or more.) Thus, for example,
29390@samp{0* } is a run-length encoding of ``0000'': the space character
29391after @samp{*} means repeat the leading @code{0} @w{@code{32 - 29 =
293923}} more times.
29393
29394The printable characters @samp{#} and @samp{$} or with a numeric value
29395greater than 126 must not be used. Runs of six repeats (@samp{#}) or
29396seven repeats (@samp{$}) can be expanded using a repeat count of only
29397five (@samp{"}). For example, @samp{00000000} can be encoded as
29398@samp{0*"00}.
c906108c 29399
8e04817f
AC
29400The error response returned for some packets includes a two character
29401error number. That number is not well defined.
c906108c 29402
f8da2bff 29403@cindex empty response, for unsupported packets
8e04817f
AC
29404For any @var{command} not supported by the stub, an empty response
29405(@samp{$#00}) should be returned. That way it is possible to extend the
29406protocol. A newer @value{GDBN} can tell if a packet is supported based
29407on that response.
c906108c 29408
b383017d
RM
29409A stub is required to support the @samp{g}, @samp{G}, @samp{m}, @samp{M},
29410@samp{c}, and @samp{s} @var{command}s. All other @var{command}s are
8e04817f 29411optional.
c906108c 29412
ee2d5c50
AC
29413@node Packets
29414@section Packets
29415
29416The following table provides a complete list of all currently defined
29417@var{command}s and their corresponding response @var{data}.
79a6e687 29418@xref{File-I/O Remote Protocol Extension}, for details about the File
9c16f35a 29419I/O extension of the remote protocol.
ee2d5c50 29420
b8ff78ce
JB
29421Each packet's description has a template showing the packet's overall
29422syntax, followed by an explanation of the packet's meaning. We
29423include spaces in some of the templates for clarity; these are not
29424part of the packet's syntax. No @value{GDBN} packet uses spaces to
29425separate its components. For example, a template like @samp{foo
29426@var{bar} @var{baz}} describes a packet beginning with the three ASCII
29427bytes @samp{foo}, followed by a @var{bar}, followed directly by a
3f94c067 29428@var{baz}. @value{GDBN} does not transmit a space character between the
b8ff78ce
JB
29429@samp{foo} and the @var{bar}, or between the @var{bar} and the
29430@var{baz}.
29431
b90a069a
SL
29432@cindex @var{thread-id}, in remote protocol
29433@anchor{thread-id syntax}
29434Several packets and replies include a @var{thread-id} field to identify
29435a thread. Normally these are positive numbers with a target-specific
29436interpretation, formatted as big-endian hex strings. A @var{thread-id}
29437can also be a literal @samp{-1} to indicate all threads, or @samp{0} to
29438pick any thread.
29439
29440In addition, the remote protocol supports a multiprocess feature in
29441which the @var{thread-id} syntax is extended to optionally include both
29442process and thread ID fields, as @samp{p@var{pid}.@var{tid}}.
29443The @var{pid} (process) and @var{tid} (thread) components each have the
29444format described above: a positive number with target-specific
29445interpretation formatted as a big-endian hex string, literal @samp{-1}
29446to indicate all processes or threads (respectively), or @samp{0} to
29447indicate an arbitrary process or thread. Specifying just a process, as
29448@samp{p@var{pid}}, is equivalent to @samp{p@var{pid}.-1}. It is an
29449error to specify all processes but a specific thread, such as
29450@samp{p-1.@var{tid}}. Note that the @samp{p} prefix is @emph{not} used
29451for those packets and replies explicitly documented to include a process
29452ID, rather than a @var{thread-id}.
29453
29454The multiprocess @var{thread-id} syntax extensions are only used if both
29455@value{GDBN} and the stub report support for the @samp{multiprocess}
29456feature using @samp{qSupported}. @xref{multiprocess extensions}, for
29457more information.
29458
8ffe2530
JB
29459Note that all packet forms beginning with an upper- or lower-case
29460letter, other than those described here, are reserved for future use.
29461
b8ff78ce 29462Here are the packet descriptions.
ee2d5c50 29463
b8ff78ce 29464@table @samp
ee2d5c50 29465
b8ff78ce
JB
29466@item !
29467@cindex @samp{!} packet
2d717e4f 29468@anchor{extended mode}
8e04817f
AC
29469Enable extended mode. In extended mode, the remote server is made
29470persistent. The @samp{R} packet is used to restart the program being
29471debugged.
ee2d5c50
AC
29472
29473Reply:
29474@table @samp
29475@item OK
8e04817f 29476The remote target both supports and has enabled extended mode.
ee2d5c50 29477@end table
c906108c 29478
b8ff78ce
JB
29479@item ?
29480@cindex @samp{?} packet
ee2d5c50 29481Indicate the reason the target halted. The reply is the same as for
8b23ecc4
SL
29482step and continue. This packet has a special interpretation when the
29483target is in non-stop mode; see @ref{Remote Non-Stop}.
c906108c 29484
ee2d5c50
AC
29485Reply:
29486@xref{Stop Reply Packets}, for the reply specifications.
29487
b8ff78ce
JB
29488@item A @var{arglen},@var{argnum},@var{arg},@dots{}
29489@cindex @samp{A} packet
29490Initialized @code{argv[]} array passed into program. @var{arglen}
29491specifies the number of bytes in the hex encoded byte stream
29492@var{arg}. See @code{gdbserver} for more details.
ee2d5c50
AC
29493
29494Reply:
29495@table @samp
29496@item OK
b8ff78ce
JB
29497The arguments were set.
29498@item E @var{NN}
29499An error occurred.
ee2d5c50
AC
29500@end table
29501
b8ff78ce
JB
29502@item b @var{baud}
29503@cindex @samp{b} packet
29504(Don't use this packet; its behavior is not well-defined.)
ee2d5c50
AC
29505Change the serial line speed to @var{baud}.
29506
29507JTC: @emph{When does the transport layer state change? When it's
29508received, or after the ACK is transmitted. In either case, there are
29509problems if the command or the acknowledgment packet is dropped.}
29510
29511Stan: @emph{If people really wanted to add something like this, and get
29512it working for the first time, they ought to modify ser-unix.c to send
29513some kind of out-of-band message to a specially-setup stub and have the
29514switch happen "in between" packets, so that from remote protocol's point
29515of view, nothing actually happened.}
29516
b8ff78ce
JB
29517@item B @var{addr},@var{mode}
29518@cindex @samp{B} packet
8e04817f 29519Set (@var{mode} is @samp{S}) or clear (@var{mode} is @samp{C}) a
2f870471
AC
29520breakpoint at @var{addr}.
29521
b8ff78ce 29522Don't use this packet. Use the @samp{Z} and @samp{z} packets instead
2f870471 29523(@pxref{insert breakpoint or watchpoint packet}).
c906108c 29524
bacec72f 29525@cindex @samp{bc} packet
0d772ac9
MS
29526@anchor{bc}
29527@item bc
bacec72f
MS
29528Backward continue. Execute the target system in reverse. No parameter.
29529@xref{Reverse Execution}, for more information.
29530
29531Reply:
29532@xref{Stop Reply Packets}, for the reply specifications.
29533
bacec72f 29534@cindex @samp{bs} packet
0d772ac9
MS
29535@anchor{bs}
29536@item bs
bacec72f
MS
29537Backward single step. Execute one instruction in reverse. No parameter.
29538@xref{Reverse Execution}, for more information.
29539
29540Reply:
29541@xref{Stop Reply Packets}, for the reply specifications.
29542
4f553f88 29543@item c @r{[}@var{addr}@r{]}
b8ff78ce
JB
29544@cindex @samp{c} packet
29545Continue. @var{addr} is address to resume. If @var{addr} is omitted,
29546resume at current address.
c906108c 29547
ee2d5c50
AC
29548Reply:
29549@xref{Stop Reply Packets}, for the reply specifications.
29550
4f553f88 29551@item C @var{sig}@r{[};@var{addr}@r{]}
b8ff78ce 29552@cindex @samp{C} packet
8e04817f 29553Continue with signal @var{sig} (hex signal number). If
b8ff78ce 29554@samp{;@var{addr}} is omitted, resume at same address.
c906108c 29555
ee2d5c50
AC
29556Reply:
29557@xref{Stop Reply Packets}, for the reply specifications.
c906108c 29558
b8ff78ce
JB
29559@item d
29560@cindex @samp{d} packet
ee2d5c50
AC
29561Toggle debug flag.
29562
b8ff78ce
JB
29563Don't use this packet; instead, define a general set packet
29564(@pxref{General Query Packets}).
ee2d5c50 29565
b8ff78ce 29566@item D
b90a069a 29567@itemx D;@var{pid}
b8ff78ce 29568@cindex @samp{D} packet
b90a069a
SL
29569The first form of the packet is used to detach @value{GDBN} from the
29570remote system. It is sent to the remote target
07f31aa6 29571before @value{GDBN} disconnects via the @code{detach} command.
ee2d5c50 29572
b90a069a
SL
29573The second form, including a process ID, is used when multiprocess
29574protocol extensions are enabled (@pxref{multiprocess extensions}), to
29575detach only a specific process. The @var{pid} is specified as a
29576big-endian hex string.
29577
ee2d5c50
AC
29578Reply:
29579@table @samp
10fac096
NW
29580@item OK
29581for success
b8ff78ce 29582@item E @var{NN}
10fac096 29583for an error
ee2d5c50 29584@end table
c906108c 29585
b8ff78ce
JB
29586@item F @var{RC},@var{EE},@var{CF};@var{XX}
29587@cindex @samp{F} packet
29588A reply from @value{GDBN} to an @samp{F} packet sent by the target.
29589This is part of the File-I/O protocol extension. @xref{File-I/O
79a6e687 29590Remote Protocol Extension}, for the specification.
ee2d5c50 29591
b8ff78ce 29592@item g
ee2d5c50 29593@anchor{read registers packet}
b8ff78ce 29594@cindex @samp{g} packet
ee2d5c50
AC
29595Read general registers.
29596
29597Reply:
29598@table @samp
29599@item @var{XX@dots{}}
8e04817f
AC
29600Each byte of register data is described by two hex digits. The bytes
29601with the register are transmitted in target byte order. The size of
b8ff78ce 29602each register and their position within the @samp{g} packet are
4a9bb1df
UW
29603determined by the @value{GDBN} internal gdbarch functions
29604@code{DEPRECATED_REGISTER_RAW_SIZE} and @code{gdbarch_register_name}. The
b8ff78ce
JB
29605specification of several standard @samp{g} packets is specified below.
29606@item E @var{NN}
ee2d5c50
AC
29607for an error.
29608@end table
c906108c 29609
b8ff78ce
JB
29610@item G @var{XX@dots{}}
29611@cindex @samp{G} packet
29612Write general registers. @xref{read registers packet}, for a
29613description of the @var{XX@dots{}} data.
ee2d5c50
AC
29614
29615Reply:
29616@table @samp
29617@item OK
29618for success
b8ff78ce 29619@item E @var{NN}
ee2d5c50
AC
29620for an error
29621@end table
29622
b90a069a 29623@item H @var{c} @var{thread-id}
b8ff78ce 29624@cindex @samp{H} packet
8e04817f 29625Set thread for subsequent operations (@samp{m}, @samp{M}, @samp{g},
ee2d5c50
AC
29626@samp{G}, et.al.). @var{c} depends on the operation to be performed: it
29627should be @samp{c} for step and continue operations, @samp{g} for other
b90a069a
SL
29628operations. The thread designator @var{thread-id} has the format and
29629interpretation described in @ref{thread-id syntax}.
ee2d5c50
AC
29630
29631Reply:
29632@table @samp
29633@item OK
29634for success
b8ff78ce 29635@item E @var{NN}
ee2d5c50
AC
29636for an error
29637@end table
c906108c 29638
8e04817f
AC
29639@c FIXME: JTC:
29640@c 'H': How restrictive (or permissive) is the thread model. If a
29641@c thread is selected and stopped, are other threads allowed
29642@c to continue to execute? As I mentioned above, I think the
29643@c semantics of each command when a thread is selected must be
29644@c described. For example:
29645@c
29646@c 'g': If the stub supports threads and a specific thread is
29647@c selected, returns the register block from that thread;
29648@c otherwise returns current registers.
29649@c
29650@c 'G' If the stub supports threads and a specific thread is
29651@c selected, sets the registers of the register block of
29652@c that thread; otherwise sets current registers.
c906108c 29653
b8ff78ce 29654@item i @r{[}@var{addr}@r{[},@var{nnn}@r{]]}
ee2d5c50 29655@anchor{cycle step packet}
b8ff78ce
JB
29656@cindex @samp{i} packet
29657Step the remote target by a single clock cycle. If @samp{,@var{nnn}} is
8e04817f
AC
29658present, cycle step @var{nnn} cycles. If @var{addr} is present, cycle
29659step starting at that address.
c906108c 29660
b8ff78ce
JB
29661@item I
29662@cindex @samp{I} packet
29663Signal, then cycle step. @xref{step with signal packet}. @xref{cycle
29664step packet}.
ee2d5c50 29665
b8ff78ce
JB
29666@item k
29667@cindex @samp{k} packet
29668Kill request.
c906108c 29669
ac282366 29670FIXME: @emph{There is no description of how to operate when a specific
ee2d5c50
AC
29671thread context has been selected (i.e.@: does 'k' kill only that
29672thread?)}.
c906108c 29673
b8ff78ce
JB
29674@item m @var{addr},@var{length}
29675@cindex @samp{m} packet
8e04817f 29676Read @var{length} bytes of memory starting at address @var{addr}.
fb031cdf
JB
29677Note that @var{addr} may not be aligned to any particular boundary.
29678
29679The stub need not use any particular size or alignment when gathering
29680data from memory for the response; even if @var{addr} is word-aligned
29681and @var{length} is a multiple of the word size, the stub is free to
29682use byte accesses, or not. For this reason, this packet may not be
29683suitable for accessing memory-mapped I/O devices.
c43c5473
JB
29684@cindex alignment of remote memory accesses
29685@cindex size of remote memory accesses
29686@cindex memory, alignment and size of remote accesses
c906108c 29687
ee2d5c50
AC
29688Reply:
29689@table @samp
29690@item @var{XX@dots{}}
599b237a 29691Memory contents; each byte is transmitted as a two-digit hexadecimal
b8ff78ce
JB
29692number. The reply may contain fewer bytes than requested if the
29693server was able to read only part of the region of memory.
29694@item E @var{NN}
ee2d5c50
AC
29695@var{NN} is errno
29696@end table
29697
b8ff78ce
JB
29698@item M @var{addr},@var{length}:@var{XX@dots{}}
29699@cindex @samp{M} packet
8e04817f 29700Write @var{length} bytes of memory starting at address @var{addr}.
b8ff78ce 29701@var{XX@dots{}} is the data; each byte is transmitted as a two-digit
599b237a 29702hexadecimal number.
ee2d5c50
AC
29703
29704Reply:
29705@table @samp
29706@item OK
29707for success
b8ff78ce 29708@item E @var{NN}
8e04817f
AC
29709for an error (this includes the case where only part of the data was
29710written).
ee2d5c50 29711@end table
c906108c 29712
b8ff78ce
JB
29713@item p @var{n}
29714@cindex @samp{p} packet
29715Read the value of register @var{n}; @var{n} is in hex.
2e868123
AC
29716@xref{read registers packet}, for a description of how the returned
29717register value is encoded.
ee2d5c50
AC
29718
29719Reply:
29720@table @samp
2e868123
AC
29721@item @var{XX@dots{}}
29722the register's value
b8ff78ce 29723@item E @var{NN}
2e868123
AC
29724for an error
29725@item
29726Indicating an unrecognized @var{query}.
ee2d5c50
AC
29727@end table
29728
b8ff78ce 29729@item P @var{n@dots{}}=@var{r@dots{}}
ee2d5c50 29730@anchor{write register packet}
b8ff78ce
JB
29731@cindex @samp{P} packet
29732Write register @var{n@dots{}} with value @var{r@dots{}}. The register
599b237a 29733number @var{n} is in hexadecimal, and @var{r@dots{}} contains two hex
8e04817f 29734digits for each byte in the register (target byte order).
c906108c 29735
ee2d5c50
AC
29736Reply:
29737@table @samp
29738@item OK
29739for success
b8ff78ce 29740@item E @var{NN}
ee2d5c50
AC
29741for an error
29742@end table
29743
5f3bebba
JB
29744@item q @var{name} @var{params}@dots{}
29745@itemx Q @var{name} @var{params}@dots{}
b8ff78ce 29746@cindex @samp{q} packet
b8ff78ce 29747@cindex @samp{Q} packet
5f3bebba
JB
29748General query (@samp{q}) and set (@samp{Q}). These packets are
29749described fully in @ref{General Query Packets}.
c906108c 29750
b8ff78ce
JB
29751@item r
29752@cindex @samp{r} packet
8e04817f 29753Reset the entire system.
c906108c 29754
b8ff78ce 29755Don't use this packet; use the @samp{R} packet instead.
ee2d5c50 29756
b8ff78ce
JB
29757@item R @var{XX}
29758@cindex @samp{R} packet
8e04817f 29759Restart the program being debugged. @var{XX}, while needed, is ignored.
2d717e4f 29760This packet is only available in extended mode (@pxref{extended mode}).
ee2d5c50 29761
8e04817f 29762The @samp{R} packet has no reply.
ee2d5c50 29763
4f553f88 29764@item s @r{[}@var{addr}@r{]}
b8ff78ce
JB
29765@cindex @samp{s} packet
29766Single step. @var{addr} is the address at which to resume. If
29767@var{addr} is omitted, resume at same address.
c906108c 29768
ee2d5c50
AC
29769Reply:
29770@xref{Stop Reply Packets}, for the reply specifications.
29771
4f553f88 29772@item S @var{sig}@r{[};@var{addr}@r{]}
ee2d5c50 29773@anchor{step with signal packet}
b8ff78ce
JB
29774@cindex @samp{S} packet
29775Step with signal. This is analogous to the @samp{C} packet, but
29776requests a single-step, rather than a normal resumption of execution.
c906108c 29777
ee2d5c50
AC
29778Reply:
29779@xref{Stop Reply Packets}, for the reply specifications.
29780
b8ff78ce
JB
29781@item t @var{addr}:@var{PP},@var{MM}
29782@cindex @samp{t} packet
8e04817f 29783Search backwards starting at address @var{addr} for a match with pattern
ee2d5c50
AC
29784@var{PP} and mask @var{MM}. @var{PP} and @var{MM} are 4 bytes.
29785@var{addr} must be at least 3 digits.
c906108c 29786
b90a069a 29787@item T @var{thread-id}
b8ff78ce 29788@cindex @samp{T} packet
b90a069a 29789Find out if the thread @var{thread-id} is alive. @xref{thread-id syntax}.
c906108c 29790
ee2d5c50
AC
29791Reply:
29792@table @samp
29793@item OK
29794thread is still alive
b8ff78ce 29795@item E @var{NN}
ee2d5c50
AC
29796thread is dead
29797@end table
29798
b8ff78ce
JB
29799@item v
29800Packets starting with @samp{v} are identified by a multi-letter name,
29801up to the first @samp{;} or @samp{?} (or the end of the packet).
86d30acc 29802
2d717e4f
DJ
29803@item vAttach;@var{pid}
29804@cindex @samp{vAttach} packet
8b23ecc4
SL
29805Attach to a new process with the specified process ID @var{pid}.
29806The process ID is a
29807hexadecimal integer identifying the process. In all-stop mode, all
29808threads in the attached process are stopped; in non-stop mode, it may be
29809attached without being stopped if that is supported by the target.
29810
29811@c In non-stop mode, on a successful vAttach, the stub should set the
29812@c current thread to a thread of the newly-attached process. After
29813@c attaching, GDB queries for the attached process's thread ID with qC.
29814@c Also note that, from a user perspective, whether or not the
29815@c target is stopped on attach in non-stop mode depends on whether you
29816@c use the foreground or background version of the attach command, not
29817@c on what vAttach does; GDB does the right thing with respect to either
29818@c stopping or restarting threads.
2d717e4f
DJ
29819
29820This packet is only available in extended mode (@pxref{extended mode}).
29821
29822Reply:
29823@table @samp
29824@item E @var{nn}
29825for an error
29826@item @r{Any stop packet}
8b23ecc4
SL
29827for success in all-stop mode (@pxref{Stop Reply Packets})
29828@item OK
29829for success in non-stop mode (@pxref{Remote Non-Stop})
2d717e4f
DJ
29830@end table
29831
b90a069a 29832@item vCont@r{[};@var{action}@r{[}:@var{thread-id}@r{]]}@dots{}
b8ff78ce
JB
29833@cindex @samp{vCont} packet
29834Resume the inferior, specifying different actions for each thread.
b90a069a 29835If an action is specified with no @var{thread-id}, then it is applied to any
86d30acc 29836threads that don't have a specific action specified; if no default action is
8b23ecc4
SL
29837specified then other threads should remain stopped in all-stop mode and
29838in their current state in non-stop mode.
29839Specifying multiple
86d30acc 29840default actions is an error; specifying no actions is also an error.
b90a069a
SL
29841Thread IDs are specified using the syntax described in @ref{thread-id syntax}.
29842
29843Currently supported actions are:
86d30acc 29844
b8ff78ce 29845@table @samp
86d30acc
DJ
29846@item c
29847Continue.
b8ff78ce 29848@item C @var{sig}
8b23ecc4 29849Continue with signal @var{sig}. The signal @var{sig} should be two hex digits.
86d30acc
DJ
29850@item s
29851Step.
b8ff78ce 29852@item S @var{sig}
8b23ecc4
SL
29853Step with signal @var{sig}. The signal @var{sig} should be two hex digits.
29854@item t
29855Stop.
86d30acc
DJ
29856@end table
29857
8b23ecc4
SL
29858The optional argument @var{addr} normally associated with the
29859@samp{c}, @samp{C}, @samp{s}, and @samp{S} packets is
b8ff78ce 29860not supported in @samp{vCont}.
86d30acc 29861
08a0efd0
PA
29862The @samp{t} action is only relevant in non-stop mode
29863(@pxref{Remote Non-Stop}) and may be ignored by the stub otherwise.
8b23ecc4
SL
29864A stop reply should be generated for any affected thread not already stopped.
29865When a thread is stopped by means of a @samp{t} action,
29866the corresponding stop reply should indicate that the thread has stopped with
29867signal @samp{0}, regardless of whether the target uses some other signal
29868as an implementation detail.
29869
86d30acc
DJ
29870Reply:
29871@xref{Stop Reply Packets}, for the reply specifications.
29872
b8ff78ce
JB
29873@item vCont?
29874@cindex @samp{vCont?} packet
d3e8051b 29875Request a list of actions supported by the @samp{vCont} packet.
86d30acc
DJ
29876
29877Reply:
29878@table @samp
b8ff78ce
JB
29879@item vCont@r{[};@var{action}@dots{}@r{]}
29880The @samp{vCont} packet is supported. Each @var{action} is a supported
29881command in the @samp{vCont} packet.
86d30acc 29882@item
b8ff78ce 29883The @samp{vCont} packet is not supported.
86d30acc 29884@end table
ee2d5c50 29885
a6b151f1
DJ
29886@item vFile:@var{operation}:@var{parameter}@dots{}
29887@cindex @samp{vFile} packet
29888Perform a file operation on the target system. For details,
29889see @ref{Host I/O Packets}.
29890
68437a39
DJ
29891@item vFlashErase:@var{addr},@var{length}
29892@cindex @samp{vFlashErase} packet
29893Direct the stub to erase @var{length} bytes of flash starting at
29894@var{addr}. The region may enclose any number of flash blocks, but
29895its start and end must fall on block boundaries, as indicated by the
79a6e687
BW
29896flash block size appearing in the memory map (@pxref{Memory Map
29897Format}). @value{GDBN} groups flash memory programming operations
68437a39
DJ
29898together, and sends a @samp{vFlashDone} request after each group; the
29899stub is allowed to delay erase operation until the @samp{vFlashDone}
29900packet is received.
29901
b90a069a
SL
29902The stub must support @samp{vCont} if it reports support for
29903multiprocess extensions (@pxref{multiprocess extensions}). Note that in
29904this case @samp{vCont} actions can be specified to apply to all threads
29905in a process by using the @samp{p@var{pid}.-1} form of the
29906@var{thread-id}.
29907
68437a39
DJ
29908Reply:
29909@table @samp
29910@item OK
29911for success
29912@item E @var{NN}
29913for an error
29914@end table
29915
29916@item vFlashWrite:@var{addr}:@var{XX@dots{}}
29917@cindex @samp{vFlashWrite} packet
29918Direct the stub to write data to flash address @var{addr}. The data
29919is passed in binary form using the same encoding as for the @samp{X}
29920packet (@pxref{Binary Data}). The memory ranges specified by
29921@samp{vFlashWrite} packets preceding a @samp{vFlashDone} packet must
29922not overlap, and must appear in order of increasing addresses
29923(although @samp{vFlashErase} packets for higher addresses may already
29924have been received; the ordering is guaranteed only between
29925@samp{vFlashWrite} packets). If a packet writes to an address that was
29926neither erased by a preceding @samp{vFlashErase} packet nor by some other
29927target-specific method, the results are unpredictable.
29928
29929
29930Reply:
29931@table @samp
29932@item OK
29933for success
29934@item E.memtype
29935for vFlashWrite addressing non-flash memory
29936@item E @var{NN}
29937for an error
29938@end table
29939
29940@item vFlashDone
29941@cindex @samp{vFlashDone} packet
29942Indicate to the stub that flash programming operation is finished.
29943The stub is permitted to delay or batch the effects of a group of
29944@samp{vFlashErase} and @samp{vFlashWrite} packets until a
29945@samp{vFlashDone} packet is received. The contents of the affected
29946regions of flash memory are unpredictable until the @samp{vFlashDone}
29947request is completed.
29948
b90a069a
SL
29949@item vKill;@var{pid}
29950@cindex @samp{vKill} packet
29951Kill the process with the specified process ID. @var{pid} is a
29952hexadecimal integer identifying the process. This packet is used in
29953preference to @samp{k} when multiprocess protocol extensions are
29954supported; see @ref{multiprocess extensions}.
29955
29956Reply:
29957@table @samp
29958@item E @var{nn}
29959for an error
29960@item OK
29961for success
29962@end table
29963
2d717e4f
DJ
29964@item vRun;@var{filename}@r{[};@var{argument}@r{]}@dots{}
29965@cindex @samp{vRun} packet
29966Run the program @var{filename}, passing it each @var{argument} on its
29967command line. The file and arguments are hex-encoded strings. If
29968@var{filename} is an empty string, the stub may use a default program
29969(e.g.@: the last program run). The program is created in the stopped
9b562ab8 29970state.
2d717e4f 29971
8b23ecc4
SL
29972@c FIXME: What about non-stop mode?
29973
2d717e4f
DJ
29974This packet is only available in extended mode (@pxref{extended mode}).
29975
29976Reply:
29977@table @samp
29978@item E @var{nn}
29979for an error
29980@item @r{Any stop packet}
29981for success (@pxref{Stop Reply Packets})
29982@end table
29983
8b23ecc4
SL
29984@item vStopped
29985@anchor{vStopped packet}
29986@cindex @samp{vStopped} packet
29987
29988In non-stop mode (@pxref{Remote Non-Stop}), acknowledge a previous stop
29989reply and prompt for the stub to report another one.
29990
29991Reply:
29992@table @samp
29993@item @r{Any stop packet}
29994if there is another unreported stop event (@pxref{Stop Reply Packets})
29995@item OK
29996if there are no unreported stop events
29997@end table
29998
b8ff78ce 29999@item X @var{addr},@var{length}:@var{XX@dots{}}
9a6253be 30000@anchor{X packet}
b8ff78ce
JB
30001@cindex @samp{X} packet
30002Write data to memory, where the data is transmitted in binary.
30003@var{addr} is address, @var{length} is number of bytes,
0876f84a 30004@samp{@var{XX}@dots{}} is binary data (@pxref{Binary Data}).
c906108c 30005
ee2d5c50
AC
30006Reply:
30007@table @samp
30008@item OK
30009for success
b8ff78ce 30010@item E @var{NN}
ee2d5c50
AC
30011for an error
30012@end table
30013
a1dcb23a
DJ
30014@item z @var{type},@var{addr},@var{kind}
30015@itemx Z @var{type},@var{addr},@var{kind}
2f870471 30016@anchor{insert breakpoint or watchpoint packet}
b8ff78ce
JB
30017@cindex @samp{z} packet
30018@cindex @samp{Z} packets
30019Insert (@samp{Z}) or remove (@samp{z}) a @var{type} breakpoint or
a1dcb23a 30020watchpoint starting at address @var{address} of kind @var{kind}.
ee2d5c50 30021
2f870471
AC
30022Each breakpoint and watchpoint packet @var{type} is documented
30023separately.
30024
512217c7
AC
30025@emph{Implementation notes: A remote target shall return an empty string
30026for an unrecognized breakpoint or watchpoint packet @var{type}. A
30027remote target shall support either both or neither of a given
b8ff78ce 30028@samp{Z@var{type}@dots{}} and @samp{z@var{type}@dots{}} packet pair. To
2f870471
AC
30029avoid potential problems with duplicate packets, the operations should
30030be implemented in an idempotent way.}
30031
a1dcb23a
DJ
30032@item z0,@var{addr},@var{kind}
30033@itemx Z0,@var{addr},@var{kind}
b8ff78ce
JB
30034@cindex @samp{z0} packet
30035@cindex @samp{Z0} packet
30036Insert (@samp{Z0}) or remove (@samp{z0}) a memory breakpoint at address
a1dcb23a 30037@var{addr} of type @var{kind}.
2f870471
AC
30038
30039A memory breakpoint is implemented by replacing the instruction at
30040@var{addr} with a software breakpoint or trap instruction. The
a1dcb23a
DJ
30041@var{kind} is target-specific and typically indicates the size of
30042the breakpoint in bytes that should be inserted. E.g., the @sc{arm}
30043and @sc{mips} can insert either a 2 or 4 byte breakpoint. Some
30044architectures have additional meanings for @var{kind};
30045see @ref{Architecture-Specific Protocol Details}.
c906108c 30046
2f870471
AC
30047@emph{Implementation note: It is possible for a target to copy or move
30048code that contains memory breakpoints (e.g., when implementing
30049overlays). The behavior of this packet, in the presence of such a
30050target, is not defined.}
c906108c 30051
ee2d5c50
AC
30052Reply:
30053@table @samp
2f870471
AC
30054@item OK
30055success
30056@item
30057not supported
b8ff78ce 30058@item E @var{NN}
ee2d5c50 30059for an error
2f870471
AC
30060@end table
30061
a1dcb23a
DJ
30062@item z1,@var{addr},@var{kind}
30063@itemx Z1,@var{addr},@var{kind}
b8ff78ce
JB
30064@cindex @samp{z1} packet
30065@cindex @samp{Z1} packet
30066Insert (@samp{Z1}) or remove (@samp{z1}) a hardware breakpoint at
a1dcb23a 30067address @var{addr}.
2f870471
AC
30068
30069A hardware breakpoint is implemented using a mechanism that is not
a1dcb23a
DJ
30070dependant on being able to modify the target's memory. @var{kind}
30071has the same meaning as in @samp{Z0} packets.
2f870471
AC
30072
30073@emph{Implementation note: A hardware breakpoint is not affected by code
30074movement.}
30075
30076Reply:
30077@table @samp
ee2d5c50 30078@item OK
2f870471
AC
30079success
30080@item
30081not supported
b8ff78ce 30082@item E @var{NN}
2f870471
AC
30083for an error
30084@end table
30085
a1dcb23a
DJ
30086@item z2,@var{addr},@var{kind}
30087@itemx Z2,@var{addr},@var{kind}
b8ff78ce
JB
30088@cindex @samp{z2} packet
30089@cindex @samp{Z2} packet
a1dcb23a
DJ
30090Insert (@samp{Z2}) or remove (@samp{z2}) a write watchpoint at @var{addr}.
30091@var{kind} is interpreted as the number of bytes to watch.
2f870471
AC
30092
30093Reply:
30094@table @samp
30095@item OK
30096success
30097@item
30098not supported
b8ff78ce 30099@item E @var{NN}
2f870471
AC
30100for an error
30101@end table
30102
a1dcb23a
DJ
30103@item z3,@var{addr},@var{kind}
30104@itemx Z3,@var{addr},@var{kind}
b8ff78ce
JB
30105@cindex @samp{z3} packet
30106@cindex @samp{Z3} packet
a1dcb23a
DJ
30107Insert (@samp{Z3}) or remove (@samp{z3}) a read watchpoint at @var{addr}.
30108@var{kind} is interpreted as the number of bytes to watch.
2f870471
AC
30109
30110Reply:
30111@table @samp
30112@item OK
30113success
30114@item
30115not supported
b8ff78ce 30116@item E @var{NN}
2f870471
AC
30117for an error
30118@end table
30119
a1dcb23a
DJ
30120@item z4,@var{addr},@var{kind}
30121@itemx Z4,@var{addr},@var{kind}
b8ff78ce
JB
30122@cindex @samp{z4} packet
30123@cindex @samp{Z4} packet
a1dcb23a
DJ
30124Insert (@samp{Z4}) or remove (@samp{z4}) an access watchpoint at @var{addr}.
30125@var{kind} is interpreted as the number of bytes to watch.
2f870471
AC
30126
30127Reply:
30128@table @samp
30129@item OK
30130success
30131@item
30132not supported
b8ff78ce 30133@item E @var{NN}
2f870471 30134for an error
ee2d5c50
AC
30135@end table
30136
30137@end table
c906108c 30138
ee2d5c50
AC
30139@node Stop Reply Packets
30140@section Stop Reply Packets
30141@cindex stop reply packets
c906108c 30142
8b23ecc4
SL
30143The @samp{C}, @samp{c}, @samp{S}, @samp{s}, @samp{vCont},
30144@samp{vAttach}, @samp{vRun}, @samp{vStopped}, and @samp{?} packets can
30145receive any of the below as a reply. Except for @samp{?}
30146and @samp{vStopped}, that reply is only returned
b8ff78ce 30147when the target halts. In the below the exact meaning of @dfn{signal
89be2091
DJ
30148number} is defined by the header @file{include/gdb/signals.h} in the
30149@value{GDBN} source code.
c906108c 30150
b8ff78ce
JB
30151As in the description of request packets, we include spaces in the
30152reply templates for clarity; these are not part of the reply packet's
30153syntax. No @value{GDBN} stop reply packet uses spaces to separate its
30154components.
c906108c 30155
b8ff78ce 30156@table @samp
ee2d5c50 30157
b8ff78ce 30158@item S @var{AA}
599b237a 30159The program received signal number @var{AA} (a two-digit hexadecimal
940178d3
JB
30160number). This is equivalent to a @samp{T} response with no
30161@var{n}:@var{r} pairs.
c906108c 30162
b8ff78ce
JB
30163@item T @var{AA} @var{n1}:@var{r1};@var{n2}:@var{r2};@dots{}
30164@cindex @samp{T} packet reply
599b237a 30165The program received signal number @var{AA} (a two-digit hexadecimal
940178d3
JB
30166number). This is equivalent to an @samp{S} response, except that the
30167@samp{@var{n}:@var{r}} pairs can carry values of important registers
30168and other information directly in the stop reply packet, reducing
30169round-trip latency. Single-step and breakpoint traps are reported
30170this way. Each @samp{@var{n}:@var{r}} pair is interpreted as follows:
cfa9d6d9
DJ
30171
30172@itemize @bullet
b8ff78ce 30173@item
599b237a 30174If @var{n} is a hexadecimal number, it is a register number, and the
b8ff78ce
JB
30175corresponding @var{r} gives that register's value. @var{r} is a
30176series of bytes in target byte order, with each byte given by a
30177two-digit hex number.
cfa9d6d9 30178
b8ff78ce 30179@item
b90a069a
SL
30180If @var{n} is @samp{thread}, then @var{r} is the @var{thread-id} of
30181the stopped thread, as specified in @ref{thread-id syntax}.
cfa9d6d9 30182
dc146f7c
VP
30183@item
30184If @var{n} is @samp{core}, then @var{r} is the hexadecimal number of
30185the core on which the stop event was detected.
30186
b8ff78ce 30187@item
cfa9d6d9
DJ
30188If @var{n} is a recognized @dfn{stop reason}, it describes a more
30189specific event that stopped the target. The currently defined stop
30190reasons are listed below. @var{aa} should be @samp{05}, the trap
30191signal. At most one stop reason should be present.
30192
b8ff78ce
JB
30193@item
30194Otherwise, @value{GDBN} should ignore this @samp{@var{n}:@var{r}} pair
30195and go on to the next; this allows us to extend the protocol in the
30196future.
cfa9d6d9
DJ
30197@end itemize
30198
30199The currently defined stop reasons are:
30200
30201@table @samp
30202@item watch
30203@itemx rwatch
30204@itemx awatch
30205The packet indicates a watchpoint hit, and @var{r} is the data address, in
30206hex.
30207
30208@cindex shared library events, remote reply
30209@item library
30210The packet indicates that the loaded libraries have changed.
30211@value{GDBN} should use @samp{qXfer:libraries:read} to fetch a new
30212list of loaded libraries. @var{r} is ignored.
bacec72f
MS
30213
30214@cindex replay log events, remote reply
30215@item replaylog
30216The packet indicates that the target cannot continue replaying
30217logged execution events, because it has reached the end (or the
30218beginning when executing backward) of the log. The value of @var{r}
30219will be either @samp{begin} or @samp{end}. @xref{Reverse Execution},
30220for more information.
cfa9d6d9 30221@end table
ee2d5c50 30222
b8ff78ce 30223@item W @var{AA}
b90a069a 30224@itemx W @var{AA} ; process:@var{pid}
8e04817f 30225The process exited, and @var{AA} is the exit status. This is only
ee2d5c50
AC
30226applicable to certain targets.
30227
b90a069a
SL
30228The second form of the response, including the process ID of the exited
30229process, can be used only when @value{GDBN} has reported support for
30230multiprocess protocol extensions; see @ref{multiprocess extensions}.
30231The @var{pid} is formatted as a big-endian hex string.
30232
b8ff78ce 30233@item X @var{AA}
b90a069a 30234@itemx X @var{AA} ; process:@var{pid}
8e04817f 30235The process terminated with signal @var{AA}.
c906108c 30236
b90a069a
SL
30237The second form of the response, including the process ID of the
30238terminated process, can be used only when @value{GDBN} has reported
30239support for multiprocess protocol extensions; see @ref{multiprocess
30240extensions}. The @var{pid} is formatted as a big-endian hex string.
30241
b8ff78ce
JB
30242@item O @var{XX}@dots{}
30243@samp{@var{XX}@dots{}} is hex encoding of @sc{ascii} data, to be
30244written as the program's console output. This can happen at any time
30245while the program is running and the debugger should continue to wait
8b23ecc4 30246for @samp{W}, @samp{T}, etc. This reply is not permitted in non-stop mode.
0ce1b118 30247
b8ff78ce 30248@item F @var{call-id},@var{parameter}@dots{}
0ce1b118
CV
30249@var{call-id} is the identifier which says which host system call should
30250be called. This is just the name of the function. Translation into the
30251correct system call is only applicable as it's defined in @value{GDBN}.
79a6e687 30252@xref{File-I/O Remote Protocol Extension}, for a list of implemented
0ce1b118
CV
30253system calls.
30254
b8ff78ce
JB
30255@samp{@var{parameter}@dots{}} is a list of parameters as defined for
30256this very system call.
0ce1b118 30257
b8ff78ce
JB
30258The target replies with this packet when it expects @value{GDBN} to
30259call a host system call on behalf of the target. @value{GDBN} replies
30260with an appropriate @samp{F} packet and keeps up waiting for the next
30261reply packet from the target. The latest @samp{C}, @samp{c}, @samp{S}
79a6e687
BW
30262or @samp{s} action is expected to be continued. @xref{File-I/O Remote
30263Protocol Extension}, for more details.
0ce1b118 30264
ee2d5c50
AC
30265@end table
30266
30267@node General Query Packets
30268@section General Query Packets
9c16f35a 30269@cindex remote query requests
c906108c 30270
5f3bebba
JB
30271Packets starting with @samp{q} are @dfn{general query packets};
30272packets starting with @samp{Q} are @dfn{general set packets}. General
30273query and set packets are a semi-unified form for retrieving and
30274sending information to and from the stub.
30275
30276The initial letter of a query or set packet is followed by a name
30277indicating what sort of thing the packet applies to. For example,
30278@value{GDBN} may use a @samp{qSymbol} packet to exchange symbol
30279definitions with the stub. These packet names follow some
30280conventions:
30281
30282@itemize @bullet
30283@item
30284The name must not contain commas, colons or semicolons.
30285@item
30286Most @value{GDBN} query and set packets have a leading upper case
30287letter.
30288@item
30289The names of custom vendor packets should use a company prefix, in
30290lower case, followed by a period. For example, packets designed at
30291the Acme Corporation might begin with @samp{qacme.foo} (for querying
30292foos) or @samp{Qacme.bar} (for setting bars).
30293@end itemize
30294
aa56d27a
JB
30295The name of a query or set packet should be separated from any
30296parameters by a @samp{:}; the parameters themselves should be
30297separated by @samp{,} or @samp{;}. Stubs must be careful to match the
369af7bd
DJ
30298full packet name, and check for a separator or the end of the packet,
30299in case two packet names share a common prefix. New packets should not begin
30300with @samp{qC}, @samp{qP}, or @samp{qL}@footnote{The @samp{qP} and @samp{qL}
30301packets predate these conventions, and have arguments without any terminator
30302for the packet name; we suspect they are in widespread use in places that
30303are difficult to upgrade. The @samp{qC} packet has no arguments, but some
30304existing stubs (e.g.@: RedBoot) are known to not check for the end of the
30305packet.}.
c906108c 30306
b8ff78ce
JB
30307Like the descriptions of the other packets, each description here
30308has a template showing the packet's overall syntax, followed by an
30309explanation of the packet's meaning. We include spaces in some of the
30310templates for clarity; these are not part of the packet's syntax. No
30311@value{GDBN} packet uses spaces to separate its components.
30312
5f3bebba
JB
30313Here are the currently defined query and set packets:
30314
b8ff78ce 30315@table @samp
c906108c 30316
b8ff78ce 30317@item qC
9c16f35a 30318@cindex current thread, remote request
b8ff78ce 30319@cindex @samp{qC} packet
b90a069a 30320Return the current thread ID.
ee2d5c50
AC
30321
30322Reply:
30323@table @samp
b90a069a
SL
30324@item QC @var{thread-id}
30325Where @var{thread-id} is a thread ID as documented in
30326@ref{thread-id syntax}.
b8ff78ce 30327@item @r{(anything else)}
b90a069a 30328Any other reply implies the old thread ID.
ee2d5c50
AC
30329@end table
30330
b8ff78ce 30331@item qCRC:@var{addr},@var{length}
ff2587ec 30332@cindex CRC of memory block, remote request
b8ff78ce 30333@cindex @samp{qCRC} packet
99e008fe
EZ
30334Compute the CRC checksum of a block of memory using CRC-32 defined in
30335IEEE 802.3. The CRC is computed byte at a time, taking the most
30336significant bit of each byte first. The initial pattern code
30337@code{0xffffffff} is used to ensure leading zeros affect the CRC.
30338
30339@emph{Note:} This is the same CRC used in validating separate debug
30340files (@pxref{Separate Debug Files, , Debugging Information in Separate
30341Files}). However the algorithm is slightly different. When validating
30342separate debug files, the CRC is computed taking the @emph{least}
30343significant bit of each byte first, and the final result is inverted to
30344detect trailing zeros.
30345
ff2587ec
WZ
30346Reply:
30347@table @samp
b8ff78ce 30348@item E @var{NN}
ff2587ec 30349An error (such as memory fault)
b8ff78ce
JB
30350@item C @var{crc32}
30351The specified memory region's checksum is @var{crc32}.
ff2587ec
WZ
30352@end table
30353
b8ff78ce
JB
30354@item qfThreadInfo
30355@itemx qsThreadInfo
9c16f35a 30356@cindex list active threads, remote request
b8ff78ce
JB
30357@cindex @samp{qfThreadInfo} packet
30358@cindex @samp{qsThreadInfo} packet
b90a069a 30359Obtain a list of all active thread IDs from the target (OS). Since there
8e04817f
AC
30360may be too many active threads to fit into one reply packet, this query
30361works iteratively: it may require more than one query/reply sequence to
30362obtain the entire list of threads. The first query of the sequence will
b8ff78ce
JB
30363be the @samp{qfThreadInfo} query; subsequent queries in the
30364sequence will be the @samp{qsThreadInfo} query.
ee2d5c50 30365
b8ff78ce 30366NOTE: This packet replaces the @samp{qL} query (see below).
ee2d5c50
AC
30367
30368Reply:
30369@table @samp
b90a069a
SL
30370@item m @var{thread-id}
30371A single thread ID
30372@item m @var{thread-id},@var{thread-id}@dots{}
30373a comma-separated list of thread IDs
b8ff78ce
JB
30374@item l
30375(lower case letter @samp{L}) denotes end of list.
ee2d5c50
AC
30376@end table
30377
30378In response to each query, the target will reply with a list of one or
b90a069a 30379more thread IDs, separated by commas.
e1aac25b 30380@value{GDBN} will respond to each reply with a request for more thread
b8ff78ce 30381ids (using the @samp{qs} form of the query), until the target responds
b90a069a
SL
30382with @samp{l} (lower-case el, for @dfn{last}).
30383Refer to @ref{thread-id syntax}, for the format of the @var{thread-id}
30384fields.
c906108c 30385
b8ff78ce 30386@item qGetTLSAddr:@var{thread-id},@var{offset},@var{lm}
ff2587ec 30387@cindex get thread-local storage address, remote request
b8ff78ce 30388@cindex @samp{qGetTLSAddr} packet
ff2587ec
WZ
30389Fetch the address associated with thread local storage specified
30390by @var{thread-id}, @var{offset}, and @var{lm}.
30391
b90a069a
SL
30392@var{thread-id} is the thread ID associated with the
30393thread for which to fetch the TLS address. @xref{thread-id syntax}.
ff2587ec
WZ
30394
30395@var{offset} is the (big endian, hex encoded) offset associated with the
30396thread local variable. (This offset is obtained from the debug
30397information associated with the variable.)
30398
db2e3e2e 30399@var{lm} is the (big endian, hex encoded) OS/ABI-specific encoding of the
ff2587ec
WZ
30400the load module associated with the thread local storage. For example,
30401a @sc{gnu}/Linux system will pass the link map address of the shared
30402object associated with the thread local storage under consideration.
30403Other operating environments may choose to represent the load module
30404differently, so the precise meaning of this parameter will vary.
ee2d5c50
AC
30405
30406Reply:
b8ff78ce
JB
30407@table @samp
30408@item @var{XX}@dots{}
ff2587ec
WZ
30409Hex encoded (big endian) bytes representing the address of the thread
30410local storage requested.
30411
b8ff78ce
JB
30412@item E @var{nn}
30413An error occurred. @var{nn} are hex digits.
ff2587ec 30414
b8ff78ce
JB
30415@item
30416An empty reply indicates that @samp{qGetTLSAddr} is not supported by the stub.
ee2d5c50
AC
30417@end table
30418
b8ff78ce 30419@item qL @var{startflag} @var{threadcount} @var{nextthread}
8e04817f
AC
30420Obtain thread information from RTOS. Where: @var{startflag} (one hex
30421digit) is one to indicate the first query and zero to indicate a
30422subsequent query; @var{threadcount} (two hex digits) is the maximum
30423number of threads the response packet can contain; and @var{nextthread}
30424(eight hex digits), for subsequent queries (@var{startflag} is zero), is
30425returned in the response as @var{argthread}.
ee2d5c50 30426
b8ff78ce 30427Don't use this packet; use the @samp{qfThreadInfo} query instead (see above).
ee2d5c50
AC
30428
30429Reply:
30430@table @samp
b8ff78ce 30431@item qM @var{count} @var{done} @var{argthread} @var{thread}@dots{}
8e04817f
AC
30432Where: @var{count} (two hex digits) is the number of threads being
30433returned; @var{done} (one hex digit) is zero to indicate more threads
30434and one indicates no further threads; @var{argthreadid} (eight hex
b8ff78ce 30435digits) is @var{nextthread} from the request packet; @var{thread}@dots{}
ee2d5c50 30436is a sequence of thread IDs from the target. @var{threadid} (eight hex
8e04817f 30437digits). See @code{remote.c:parse_threadlist_response()}.
ee2d5c50 30438@end table
c906108c 30439
b8ff78ce 30440@item qOffsets
9c16f35a 30441@cindex section offsets, remote request
b8ff78ce 30442@cindex @samp{qOffsets} packet
31d99776
DJ
30443Get section offsets that the target used when relocating the downloaded
30444image.
c906108c 30445
ee2d5c50
AC
30446Reply:
30447@table @samp
31d99776
DJ
30448@item Text=@var{xxx};Data=@var{yyy}@r{[};Bss=@var{zzz}@r{]}
30449Relocate the @code{Text} section by @var{xxx} from its original address.
30450Relocate the @code{Data} section by @var{yyy} from its original address.
30451If the object file format provides segment information (e.g.@: @sc{elf}
30452@samp{PT_LOAD} program headers), @value{GDBN} will relocate entire
30453segments by the supplied offsets.
30454
30455@emph{Note: while a @code{Bss} offset may be included in the response,
30456@value{GDBN} ignores this and instead applies the @code{Data} offset
30457to the @code{Bss} section.}
30458
30459@item TextSeg=@var{xxx}@r{[};DataSeg=@var{yyy}@r{]}
30460Relocate the first segment of the object file, which conventionally
30461contains program code, to a starting address of @var{xxx}. If
30462@samp{DataSeg} is specified, relocate the second segment, which
30463conventionally contains modifiable data, to a starting address of
30464@var{yyy}. @value{GDBN} will report an error if the object file
30465does not contain segment information, or does not contain at least
30466as many segments as mentioned in the reply. Extra segments are
30467kept at fixed offsets relative to the last relocated segment.
ee2d5c50
AC
30468@end table
30469
b90a069a 30470@item qP @var{mode} @var{thread-id}
9c16f35a 30471@cindex thread information, remote request
b8ff78ce 30472@cindex @samp{qP} packet
b90a069a
SL
30473Returns information on @var{thread-id}. Where: @var{mode} is a hex
30474encoded 32 bit mode; @var{thread-id} is a thread ID
30475(@pxref{thread-id syntax}).
ee2d5c50 30476
aa56d27a
JB
30477Don't use this packet; use the @samp{qThreadExtraInfo} query instead
30478(see below).
30479
b8ff78ce 30480Reply: see @code{remote.c:remote_unpack_thread_info_response()}.
c906108c 30481
8b23ecc4
SL
30482@item QNonStop:1
30483@item QNonStop:0
30484@cindex non-stop mode, remote request
30485@cindex @samp{QNonStop} packet
30486@anchor{QNonStop}
30487Enter non-stop (@samp{QNonStop:1}) or all-stop (@samp{QNonStop:0}) mode.
30488@xref{Remote Non-Stop}, for more information.
30489
30490Reply:
30491@table @samp
30492@item OK
30493The request succeeded.
30494
30495@item E @var{nn}
30496An error occurred. @var{nn} are hex digits.
30497
30498@item
30499An empty reply indicates that @samp{QNonStop} is not supported by
30500the stub.
30501@end table
30502
30503This packet is not probed by default; the remote stub must request it,
30504by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
30505Use of this packet is controlled by the @code{set non-stop} command;
30506@pxref{Non-Stop Mode}.
30507
89be2091
DJ
30508@item QPassSignals: @var{signal} @r{[};@var{signal}@r{]}@dots{}
30509@cindex pass signals to inferior, remote request
30510@cindex @samp{QPassSignals} packet
23181151 30511@anchor{QPassSignals}
89be2091
DJ
30512Each listed @var{signal} should be passed directly to the inferior process.
30513Signals are numbered identically to continue packets and stop replies
30514(@pxref{Stop Reply Packets}). Each @var{signal} list item should be
30515strictly greater than the previous item. These signals do not need to stop
30516the inferior, or be reported to @value{GDBN}. All other signals should be
30517reported to @value{GDBN}. Multiple @samp{QPassSignals} packets do not
30518combine; any earlier @samp{QPassSignals} list is completely replaced by the
30519new list. This packet improves performance when using @samp{handle
30520@var{signal} nostop noprint pass}.
30521
30522Reply:
30523@table @samp
30524@item OK
30525The request succeeded.
30526
30527@item E @var{nn}
30528An error occurred. @var{nn} are hex digits.
30529
30530@item
30531An empty reply indicates that @samp{QPassSignals} is not supported by
30532the stub.
30533@end table
30534
30535Use of this packet is controlled by the @code{set remote pass-signals}
79a6e687 30536command (@pxref{Remote Configuration, set remote pass-signals}).
89be2091
DJ
30537This packet is not probed by default; the remote stub must request it,
30538by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
30539
b8ff78ce 30540@item qRcmd,@var{command}
ff2587ec 30541@cindex execute remote command, remote request
b8ff78ce 30542@cindex @samp{qRcmd} packet
ff2587ec 30543@var{command} (hex encoded) is passed to the local interpreter for
b8ff78ce
JB
30544execution. Invalid commands should be reported using the output
30545string. Before the final result packet, the target may also respond
30546with a number of intermediate @samp{O@var{output}} console output
30547packets. @emph{Implementors should note that providing access to a
30548stubs's interpreter may have security implications}.
fa93a9d8 30549
ff2587ec
WZ
30550Reply:
30551@table @samp
30552@item OK
30553A command response with no output.
30554@item @var{OUTPUT}
30555A command response with the hex encoded output string @var{OUTPUT}.
b8ff78ce 30556@item E @var{NN}
ff2587ec 30557Indicate a badly formed request.
b8ff78ce
JB
30558@item
30559An empty reply indicates that @samp{qRcmd} is not recognized.
ff2587ec 30560@end table
fa93a9d8 30561
aa56d27a
JB
30562(Note that the @code{qRcmd} packet's name is separated from the
30563command by a @samp{,}, not a @samp{:}, contrary to the naming
30564conventions above. Please don't use this packet as a model for new
30565packets.)
30566
08388c79
DE
30567@item qSearch:memory:@var{address};@var{length};@var{search-pattern}
30568@cindex searching memory, in remote debugging
30569@cindex @samp{qSearch:memory} packet
30570@anchor{qSearch memory}
30571Search @var{length} bytes at @var{address} for @var{search-pattern}.
30572@var{address} and @var{length} are encoded in hex.
30573@var{search-pattern} is a sequence of bytes, hex encoded.
30574
30575Reply:
30576@table @samp
30577@item 0
30578The pattern was not found.
30579@item 1,address
30580The pattern was found at @var{address}.
30581@item E @var{NN}
30582A badly formed request or an error was encountered while searching memory.
30583@item
30584An empty reply indicates that @samp{qSearch:memory} is not recognized.
30585@end table
30586
a6f3e723
SL
30587@item QStartNoAckMode
30588@cindex @samp{QStartNoAckMode} packet
30589@anchor{QStartNoAckMode}
30590Request that the remote stub disable the normal @samp{+}/@samp{-}
30591protocol acknowledgments (@pxref{Packet Acknowledgment}).
30592
30593Reply:
30594@table @samp
30595@item OK
30596The stub has switched to no-acknowledgment mode.
30597@value{GDBN} acknowledges this reponse,
30598but neither the stub nor @value{GDBN} shall send or expect further
30599@samp{+}/@samp{-} acknowledgments in the current connection.
30600@item
30601An empty reply indicates that the stub does not support no-acknowledgment mode.
30602@end table
30603
be2a5f71
DJ
30604@item qSupported @r{[}:@var{gdbfeature} @r{[};@var{gdbfeature}@r{]}@dots{} @r{]}
30605@cindex supported packets, remote query
30606@cindex features of the remote protocol
30607@cindex @samp{qSupported} packet
0876f84a 30608@anchor{qSupported}
be2a5f71
DJ
30609Tell the remote stub about features supported by @value{GDBN}, and
30610query the stub for features it supports. This packet allows
30611@value{GDBN} and the remote stub to take advantage of each others'
30612features. @samp{qSupported} also consolidates multiple feature probes
30613at startup, to improve @value{GDBN} performance---a single larger
30614packet performs better than multiple smaller probe packets on
30615high-latency links. Some features may enable behavior which must not
30616be on by default, e.g.@: because it would confuse older clients or
30617stubs. Other features may describe packets which could be
30618automatically probed for, but are not. These features must be
30619reported before @value{GDBN} will use them. This ``default
30620unsupported'' behavior is not appropriate for all packets, but it
30621helps to keep the initial connection time under control with new
30622versions of @value{GDBN} which support increasing numbers of packets.
30623
30624Reply:
30625@table @samp
30626@item @var{stubfeature} @r{[};@var{stubfeature}@r{]}@dots{}
30627The stub supports or does not support each returned @var{stubfeature},
30628depending on the form of each @var{stubfeature} (see below for the
30629possible forms).
30630@item
30631An empty reply indicates that @samp{qSupported} is not recognized,
30632or that no features needed to be reported to @value{GDBN}.
30633@end table
30634
30635The allowed forms for each feature (either a @var{gdbfeature} in the
30636@samp{qSupported} packet, or a @var{stubfeature} in the response)
30637are:
30638
30639@table @samp
30640@item @var{name}=@var{value}
30641The remote protocol feature @var{name} is supported, and associated
30642with the specified @var{value}. The format of @var{value} depends
30643on the feature, but it must not include a semicolon.
30644@item @var{name}+
30645The remote protocol feature @var{name} is supported, and does not
30646need an associated value.
30647@item @var{name}-
30648The remote protocol feature @var{name} is not supported.
30649@item @var{name}?
30650The remote protocol feature @var{name} may be supported, and
30651@value{GDBN} should auto-detect support in some other way when it is
30652needed. This form will not be used for @var{gdbfeature} notifications,
30653but may be used for @var{stubfeature} responses.
30654@end table
30655
30656Whenever the stub receives a @samp{qSupported} request, the
30657supplied set of @value{GDBN} features should override any previous
30658request. This allows @value{GDBN} to put the stub in a known
30659state, even if the stub had previously been communicating with
30660a different version of @value{GDBN}.
30661
b90a069a
SL
30662The following values of @var{gdbfeature} (for the packet sent by @value{GDBN})
30663are defined:
30664
30665@table @samp
30666@item multiprocess
30667This feature indicates whether @value{GDBN} supports multiprocess
30668extensions to the remote protocol. @value{GDBN} does not use such
30669extensions unless the stub also reports that it supports them by
30670including @samp{multiprocess+} in its @samp{qSupported} reply.
30671@xref{multiprocess extensions}, for details.
c8d5aac9
L
30672
30673@item xmlRegisters
30674This feature indicates that @value{GDBN} supports the XML target
30675description. If the stub sees @samp{xmlRegisters=} with target
30676specific strings separated by a comma, it will report register
30677description.
b90a069a
SL
30678@end table
30679
30680Stubs should ignore any unknown values for
be2a5f71
DJ
30681@var{gdbfeature}. Any @value{GDBN} which sends a @samp{qSupported}
30682packet supports receiving packets of unlimited length (earlier
b90a069a 30683versions of @value{GDBN} may reject overly long responses). Additional values
be2a5f71
DJ
30684for @var{gdbfeature} may be defined in the future to let the stub take
30685advantage of new features in @value{GDBN}, e.g.@: incompatible
b90a069a
SL
30686improvements in the remote protocol---the @samp{multiprocess} feature is
30687an example of such a feature. The stub's reply should be independent
be2a5f71
DJ
30688of the @var{gdbfeature} entries sent by @value{GDBN}; first @value{GDBN}
30689describes all the features it supports, and then the stub replies with
30690all the features it supports.
30691
30692Similarly, @value{GDBN} will silently ignore unrecognized stub feature
30693responses, as long as each response uses one of the standard forms.
30694
30695Some features are flags. A stub which supports a flag feature
30696should respond with a @samp{+} form response. Other features
30697require values, and the stub should respond with an @samp{=}
30698form response.
30699
30700Each feature has a default value, which @value{GDBN} will use if
30701@samp{qSupported} is not available or if the feature is not mentioned
30702in the @samp{qSupported} response. The default values are fixed; a
30703stub is free to omit any feature responses that match the defaults.
30704
30705Not all features can be probed, but for those which can, the probing
30706mechanism is useful: in some cases, a stub's internal
30707architecture may not allow the protocol layer to know some information
30708about the underlying target in advance. This is especially common in
30709stubs which may be configured for multiple targets.
30710
30711These are the currently defined stub features and their properties:
30712
cfa9d6d9 30713@multitable @columnfractions 0.35 0.2 0.12 0.2
be2a5f71
DJ
30714@c NOTE: The first row should be @headitem, but we do not yet require
30715@c a new enough version of Texinfo (4.7) to use @headitem.
0876f84a 30716@item Feature Name
be2a5f71
DJ
30717@tab Value Required
30718@tab Default
30719@tab Probe Allowed
30720
30721@item @samp{PacketSize}
30722@tab Yes
30723@tab @samp{-}
30724@tab No
30725
0876f84a
DJ
30726@item @samp{qXfer:auxv:read}
30727@tab No
30728@tab @samp{-}
30729@tab Yes
30730
23181151
DJ
30731@item @samp{qXfer:features:read}
30732@tab No
30733@tab @samp{-}
30734@tab Yes
30735
cfa9d6d9
DJ
30736@item @samp{qXfer:libraries:read}
30737@tab No
30738@tab @samp{-}
30739@tab Yes
30740
68437a39
DJ
30741@item @samp{qXfer:memory-map:read}
30742@tab No
30743@tab @samp{-}
30744@tab Yes
30745
0e7f50da
UW
30746@item @samp{qXfer:spu:read}
30747@tab No
30748@tab @samp{-}
30749@tab Yes
30750
30751@item @samp{qXfer:spu:write}
30752@tab No
30753@tab @samp{-}
30754@tab Yes
30755
4aa995e1
PA
30756@item @samp{qXfer:siginfo:read}
30757@tab No
30758@tab @samp{-}
30759@tab Yes
30760
30761@item @samp{qXfer:siginfo:write}
30762@tab No
30763@tab @samp{-}
30764@tab Yes
30765
dc146f7c
VP
30766@item @samp{qXfer:threads:read}
30767@tab No
30768@tab @samp{-}
30769@tab Yes
30770
30771
8b23ecc4
SL
30772@item @samp{QNonStop}
30773@tab No
30774@tab @samp{-}
30775@tab Yes
30776
89be2091
DJ
30777@item @samp{QPassSignals}
30778@tab No
30779@tab @samp{-}
30780@tab Yes
30781
a6f3e723
SL
30782@item @samp{QStartNoAckMode}
30783@tab No
30784@tab @samp{-}
30785@tab Yes
30786
b90a069a
SL
30787@item @samp{multiprocess}
30788@tab No
30789@tab @samp{-}
30790@tab No
30791
782b2b07
SS
30792@item @samp{ConditionalTracepoints}
30793@tab No
30794@tab @samp{-}
30795@tab No
30796
0d772ac9
MS
30797@item @samp{ReverseContinue}
30798@tab No
2f8132f3 30799@tab @samp{-}
0d772ac9
MS
30800@tab No
30801
30802@item @samp{ReverseStep}
30803@tab No
2f8132f3 30804@tab @samp{-}
0d772ac9
MS
30805@tab No
30806
409873ef
SS
30807@item @samp{TracepointSource}
30808@tab No
30809@tab @samp{-}
30810@tab No
30811
be2a5f71
DJ
30812@end multitable
30813
30814These are the currently defined stub features, in more detail:
30815
30816@table @samp
30817@cindex packet size, remote protocol
30818@item PacketSize=@var{bytes}
30819The remote stub can accept packets up to at least @var{bytes} in
30820length. @value{GDBN} will send packets up to this size for bulk
30821transfers, and will never send larger packets. This is a limit on the
30822data characters in the packet, including the frame and checksum.
30823There is no trailing NUL byte in a remote protocol packet; if the stub
30824stores packets in a NUL-terminated format, it should allow an extra
30825byte in its buffer for the NUL. If this stub feature is not supported,
30826@value{GDBN} guesses based on the size of the @samp{g} packet response.
30827
0876f84a
DJ
30828@item qXfer:auxv:read
30829The remote stub understands the @samp{qXfer:auxv:read} packet
30830(@pxref{qXfer auxiliary vector read}).
30831
23181151
DJ
30832@item qXfer:features:read
30833The remote stub understands the @samp{qXfer:features:read} packet
30834(@pxref{qXfer target description read}).
30835
cfa9d6d9
DJ
30836@item qXfer:libraries:read
30837The remote stub understands the @samp{qXfer:libraries:read} packet
30838(@pxref{qXfer library list read}).
30839
23181151
DJ
30840@item qXfer:memory-map:read
30841The remote stub understands the @samp{qXfer:memory-map:read} packet
30842(@pxref{qXfer memory map read}).
30843
0e7f50da
UW
30844@item qXfer:spu:read
30845The remote stub understands the @samp{qXfer:spu:read} packet
30846(@pxref{qXfer spu read}).
30847
30848@item qXfer:spu:write
30849The remote stub understands the @samp{qXfer:spu:write} packet
30850(@pxref{qXfer spu write}).
30851
4aa995e1
PA
30852@item qXfer:siginfo:read
30853The remote stub understands the @samp{qXfer:siginfo:read} packet
30854(@pxref{qXfer siginfo read}).
30855
30856@item qXfer:siginfo:write
30857The remote stub understands the @samp{qXfer:siginfo:write} packet
30858(@pxref{qXfer siginfo write}).
30859
dc146f7c
VP
30860@item qXfer:threads:read
30861The remote stub understands the @samp{qXfer:threads:read} packet
30862(@pxref{qXfer threads read}).
30863
8b23ecc4
SL
30864@item QNonStop
30865The remote stub understands the @samp{QNonStop} packet
30866(@pxref{QNonStop}).
30867
23181151
DJ
30868@item QPassSignals
30869The remote stub understands the @samp{QPassSignals} packet
30870(@pxref{QPassSignals}).
30871
a6f3e723
SL
30872@item QStartNoAckMode
30873The remote stub understands the @samp{QStartNoAckMode} packet and
30874prefers to operate in no-acknowledgment mode. @xref{Packet Acknowledgment}.
30875
b90a069a
SL
30876@item multiprocess
30877@anchor{multiprocess extensions}
30878@cindex multiprocess extensions, in remote protocol
30879The remote stub understands the multiprocess extensions to the remote
30880protocol syntax. The multiprocess extensions affect the syntax of
30881thread IDs in both packets and replies (@pxref{thread-id syntax}), and
30882add process IDs to the @samp{D} packet and @samp{W} and @samp{X}
30883replies. Note that reporting this feature indicates support for the
30884syntactic extensions only, not that the stub necessarily supports
30885debugging of more than one process at a time. The stub must not use
30886multiprocess extensions in packet replies unless @value{GDBN} has also
30887indicated it supports them in its @samp{qSupported} request.
30888
07e059b5
VP
30889@item qXfer:osdata:read
30890The remote stub understands the @samp{qXfer:osdata:read} packet
30891((@pxref{qXfer osdata read}).
30892
782b2b07
SS
30893@item ConditionalTracepoints
30894The remote stub accepts and implements conditional expressions defined
30895for tracepoints (@pxref{Tracepoint Conditions}).
30896
0d772ac9
MS
30897@item ReverseContinue
30898The remote stub accepts and implements the reverse continue packet
30899(@pxref{bc}).
30900
30901@item ReverseStep
30902The remote stub accepts and implements the reverse step packet
30903(@pxref{bs}).
30904
409873ef
SS
30905@item TracepointSource
30906The remote stub understands the @samp{QTDPsrc} packet that supplies
30907the source form of tracepoint definitions.
30908
be2a5f71
DJ
30909@end table
30910
b8ff78ce 30911@item qSymbol::
ff2587ec 30912@cindex symbol lookup, remote request
b8ff78ce 30913@cindex @samp{qSymbol} packet
ff2587ec
WZ
30914Notify the target that @value{GDBN} is prepared to serve symbol lookup
30915requests. Accept requests from the target for the values of symbols.
fa93a9d8
JB
30916
30917Reply:
ff2587ec 30918@table @samp
b8ff78ce 30919@item OK
ff2587ec 30920The target does not need to look up any (more) symbols.
b8ff78ce 30921@item qSymbol:@var{sym_name}
ff2587ec
WZ
30922The target requests the value of symbol @var{sym_name} (hex encoded).
30923@value{GDBN} may provide the value by using the
b8ff78ce
JB
30924@samp{qSymbol:@var{sym_value}:@var{sym_name}} message, described
30925below.
ff2587ec 30926@end table
83761cbd 30927
b8ff78ce 30928@item qSymbol:@var{sym_value}:@var{sym_name}
ff2587ec
WZ
30929Set the value of @var{sym_name} to @var{sym_value}.
30930
30931@var{sym_name} (hex encoded) is the name of a symbol whose value the
30932target has previously requested.
30933
30934@var{sym_value} (hex) is the value for symbol @var{sym_name}. If
30935@value{GDBN} cannot supply a value for @var{sym_name}, then this field
30936will be empty.
30937
30938Reply:
30939@table @samp
b8ff78ce 30940@item OK
ff2587ec 30941The target does not need to look up any (more) symbols.
b8ff78ce 30942@item qSymbol:@var{sym_name}
ff2587ec
WZ
30943The target requests the value of a new symbol @var{sym_name} (hex
30944encoded). @value{GDBN} will continue to supply the values of symbols
30945(if available), until the target ceases to request them.
fa93a9d8 30946@end table
0abb7bc7 30947
00bf0b85 30948@item qTBuffer
4daf5ac0 30949@item QTBuffer
d5551862
SS
30950@item QTDisconnected
30951@itemx QTDP
409873ef 30952@itemx QTDPsrc
d5551862 30953@itemx QTDV
00bf0b85
SS
30954@itemx qTfP
30955@itemx qTfV
9d29849a
JB
30956@itemx QTFrame
30957@xref{Tracepoint Packets}.
30958
b90a069a 30959@item qThreadExtraInfo,@var{thread-id}
ff2587ec 30960@cindex thread attributes info, remote request
b8ff78ce
JB
30961@cindex @samp{qThreadExtraInfo} packet
30962Obtain a printable string description of a thread's attributes from
b90a069a
SL
30963the target OS. @var{thread-id} is a thread ID;
30964see @ref{thread-id syntax}. This
b8ff78ce
JB
30965string may contain anything that the target OS thinks is interesting
30966for @value{GDBN} to tell the user about the thread. The string is
30967displayed in @value{GDBN}'s @code{info threads} display. Some
30968examples of possible thread extra info strings are @samp{Runnable}, or
30969@samp{Blocked on Mutex}.
ff2587ec
WZ
30970
30971Reply:
30972@table @samp
b8ff78ce
JB
30973@item @var{XX}@dots{}
30974Where @samp{@var{XX}@dots{}} is a hex encoding of @sc{ascii} data,
30975comprising the printable string containing the extra information about
30976the thread's attributes.
ff2587ec 30977@end table
814e32d7 30978
aa56d27a
JB
30979(Note that the @code{qThreadExtraInfo} packet's name is separated from
30980the command by a @samp{,}, not a @samp{:}, contrary to the naming
30981conventions above. Please don't use this packet as a model for new
30982packets.)
30983
00bf0b85
SS
30984@item QTSave
30985@item qTsP
30986@item qTsV
d5551862 30987@itemx QTStart
9d29849a
JB
30988@itemx QTStop
30989@itemx QTinit
30990@itemx QTro
30991@itemx qTStatus
d5551862 30992@itemx qTV
9d29849a
JB
30993@xref{Tracepoint Packets}.
30994
0876f84a
DJ
30995@item qXfer:@var{object}:read:@var{annex}:@var{offset},@var{length}
30996@cindex read special object, remote request
30997@cindex @samp{qXfer} packet
68437a39 30998@anchor{qXfer read}
0876f84a
DJ
30999Read uninterpreted bytes from the target's special data area
31000identified by the keyword @var{object}. Request @var{length} bytes
31001starting at @var{offset} bytes into the data. The content and
0e7f50da 31002encoding of @var{annex} is specific to @var{object}; it can supply
0876f84a
DJ
31003additional details about what data to access.
31004
31005Here are the specific requests of this form defined so far. All
31006@samp{qXfer:@var{object}:read:@dots{}} requests use the same reply
31007formats, listed below.
31008
31009@table @samp
31010@item qXfer:auxv:read::@var{offset},@var{length}
31011@anchor{qXfer auxiliary vector read}
31012Access the target's @dfn{auxiliary vector}. @xref{OS Information,
427c3a89 31013auxiliary vector}. Note @var{annex} must be empty.
0876f84a
DJ
31014
31015This packet is not probed by default; the remote stub must request it,
89be2091 31016by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
0876f84a 31017
23181151
DJ
31018@item qXfer:features:read:@var{annex}:@var{offset},@var{length}
31019@anchor{qXfer target description read}
31020Access the @dfn{target description}. @xref{Target Descriptions}. The
31021annex specifies which XML document to access. The main description is
31022always loaded from the @samp{target.xml} annex.
31023
31024This packet is not probed by default; the remote stub must request it,
31025by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
31026
cfa9d6d9
DJ
31027@item qXfer:libraries:read:@var{annex}:@var{offset},@var{length}
31028@anchor{qXfer library list read}
31029Access the target's list of loaded libraries. @xref{Library List Format}.
31030The annex part of the generic @samp{qXfer} packet must be empty
31031(@pxref{qXfer read}).
31032
31033Targets which maintain a list of libraries in the program's memory do
31034not need to implement this packet; it is designed for platforms where
31035the operating system manages the list of loaded libraries.
31036
31037This packet is not probed by default; the remote stub must request it,
31038by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
31039
68437a39
DJ
31040@item qXfer:memory-map:read::@var{offset},@var{length}
31041@anchor{qXfer memory map read}
79a6e687 31042Access the target's @dfn{memory-map}. @xref{Memory Map Format}. The
68437a39
DJ
31043annex part of the generic @samp{qXfer} packet must be empty
31044(@pxref{qXfer read}).
31045
0e7f50da
UW
31046This packet is not probed by default; the remote stub must request it,
31047by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
31048
4aa995e1
PA
31049@item qXfer:siginfo:read::@var{offset},@var{length}
31050@anchor{qXfer siginfo read}
31051Read contents of the extra signal information on the target
31052system. The annex part of the generic @samp{qXfer} packet must be
31053empty (@pxref{qXfer read}).
31054
31055This packet is not probed by default; the remote stub must request it,
31056by supplying an appropriate @samp{qSupported} response
31057(@pxref{qSupported}).
31058
0e7f50da
UW
31059@item qXfer:spu:read:@var{annex}:@var{offset},@var{length}
31060@anchor{qXfer spu read}
31061Read contents of an @code{spufs} file on the target system. The
31062annex specifies which file to read; it must be of the form
31063@file{@var{id}/@var{name}}, where @var{id} specifies an SPU context ID
31064in the target process, and @var{name} identifes the @code{spufs} file
31065in that context to be accessed.
31066
68437a39 31067This packet is not probed by default; the remote stub must request it,
07e059b5
VP
31068by supplying an appropriate @samp{qSupported} response
31069(@pxref{qSupported}).
31070
dc146f7c
VP
31071@item qXfer:threads:read::@var{offset},@var{length}
31072@anchor{qXfer threads read}
31073Access the list of threads on target. @xref{Thread List Format}. The
31074annex part of the generic @samp{qXfer} packet must be empty
31075(@pxref{qXfer read}).
31076
31077This packet is not probed by default; the remote stub must request it,
31078by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
31079
07e059b5
VP
31080@item qXfer:osdata:read::@var{offset},@var{length}
31081@anchor{qXfer osdata read}
31082Access the target's @dfn{operating system information}.
31083@xref{Operating System Information}.
31084
68437a39
DJ
31085@end table
31086
0876f84a
DJ
31087Reply:
31088@table @samp
31089@item m @var{data}
31090Data @var{data} (@pxref{Binary Data}) has been read from the
31091target. There may be more data at a higher address (although
31092it is permitted to return @samp{m} even for the last valid
31093block of data, as long as at least one byte of data was read).
31094@var{data} may have fewer bytes than the @var{length} in the
31095request.
31096
31097@item l @var{data}
31098Data @var{data} (@pxref{Binary Data}) has been read from the target.
31099There is no more data to be read. @var{data} may have fewer bytes
31100than the @var{length} in the request.
31101
31102@item l
31103The @var{offset} in the request is at the end of the data.
31104There is no more data to be read.
31105
31106@item E00
31107The request was malformed, or @var{annex} was invalid.
31108
31109@item E @var{nn}
31110The offset was invalid, or there was an error encountered reading the data.
31111@var{nn} is a hex-encoded @code{errno} value.
31112
31113@item
31114An empty reply indicates the @var{object} string was not recognized by
31115the stub, or that the object does not support reading.
31116@end table
31117
31118@item qXfer:@var{object}:write:@var{annex}:@var{offset}:@var{data}@dots{}
31119@cindex write data into object, remote request
4aa995e1 31120@anchor{qXfer write}
0876f84a
DJ
31121Write uninterpreted bytes into the target's special data area
31122identified by the keyword @var{object}, starting at @var{offset} bytes
0e7f50da 31123into the data. @var{data}@dots{} is the binary-encoded data
0876f84a 31124(@pxref{Binary Data}) to be written. The content and encoding of @var{annex}
0e7f50da 31125is specific to @var{object}; it can supply additional details about what data
0876f84a
DJ
31126to access.
31127
0e7f50da
UW
31128Here are the specific requests of this form defined so far. All
31129@samp{qXfer:@var{object}:write:@dots{}} requests use the same reply
31130formats, listed below.
31131
31132@table @samp
4aa995e1
PA
31133@item qXfer:siginfo:write::@var{offset}:@var{data}@dots{}
31134@anchor{qXfer siginfo write}
31135Write @var{data} to the extra signal information on the target system.
31136The annex part of the generic @samp{qXfer} packet must be
31137empty (@pxref{qXfer write}).
31138
31139This packet is not probed by default; the remote stub must request it,
31140by supplying an appropriate @samp{qSupported} response
31141(@pxref{qSupported}).
31142
84fcdf95 31143@item qXfer:spu:write:@var{annex}:@var{offset}:@var{data}@dots{}
0e7f50da
UW
31144@anchor{qXfer spu write}
31145Write @var{data} to an @code{spufs} file on the target system. The
31146annex specifies which file to write; it must be of the form
31147@file{@var{id}/@var{name}}, where @var{id} specifies an SPU context ID
31148in the target process, and @var{name} identifes the @code{spufs} file
31149in that context to be accessed.
31150
31151This packet is not probed by default; the remote stub must request it,
31152by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
31153@end table
0876f84a
DJ
31154
31155Reply:
31156@table @samp
31157@item @var{nn}
31158@var{nn} (hex encoded) is the number of bytes written.
31159This may be fewer bytes than supplied in the request.
31160
31161@item E00
31162The request was malformed, or @var{annex} was invalid.
31163
31164@item E @var{nn}
31165The offset was invalid, or there was an error encountered writing the data.
31166@var{nn} is a hex-encoded @code{errno} value.
31167
31168@item
31169An empty reply indicates the @var{object} string was not
31170recognized by the stub, or that the object does not support writing.
31171@end table
31172
31173@item qXfer:@var{object}:@var{operation}:@dots{}
31174Requests of this form may be added in the future. When a stub does
31175not recognize the @var{object} keyword, or its support for
31176@var{object} does not recognize the @var{operation} keyword, the stub
31177must respond with an empty packet.
31178
0b16c5cf
PA
31179@item qAttached:@var{pid}
31180@cindex query attached, remote request
31181@cindex @samp{qAttached} packet
31182Return an indication of whether the remote server attached to an
31183existing process or created a new process. When the multiprocess
31184protocol extensions are supported (@pxref{multiprocess extensions}),
31185@var{pid} is an integer in hexadecimal format identifying the target
31186process. Otherwise, @value{GDBN} will omit the @var{pid} field and
31187the query packet will be simplified as @samp{qAttached}.
31188
31189This query is used, for example, to know whether the remote process
31190should be detached or killed when a @value{GDBN} session is ended with
31191the @code{quit} command.
31192
31193Reply:
31194@table @samp
31195@item 1
31196The remote server attached to an existing process.
31197@item 0
31198The remote server created a new process.
31199@item E @var{NN}
31200A badly formed request or an error was encountered.
31201@end table
31202
ee2d5c50
AC
31203@end table
31204
a1dcb23a
DJ
31205@node Architecture-Specific Protocol Details
31206@section Architecture-Specific Protocol Details
31207
31208This section describes how the remote protocol is applied to specific
31209target architectures. Also see @ref{Standard Target Features}, for
31210details of XML target descriptions for each architecture.
31211
31212@subsection ARM
31213
31214@subsubsection Breakpoint Kinds
31215
31216These breakpoint kinds are defined for the @samp{Z0} and @samp{Z1} packets.
31217
31218@table @r
31219
31220@item 2
3122116-bit Thumb mode breakpoint.
31222
31223@item 3
3122432-bit Thumb mode (Thumb-2) breakpoint.
31225
31226@item 4
3122732-bit ARM mode breakpoint.
31228
31229@end table
31230
31231@subsection MIPS
31232
31233@subsubsection Register Packet Format
eb12ee30 31234
b8ff78ce 31235The following @code{g}/@code{G} packets have previously been defined.
ee2d5c50
AC
31236In the below, some thirty-two bit registers are transferred as
31237sixty-four bits. Those registers should be zero/sign extended (which?)
599b237a
BW
31238to fill the space allocated. Register bytes are transferred in target
31239byte order. The two nibbles within a register byte are transferred
ee2d5c50 31240most-significant - least-significant.
eb12ee30 31241
ee2d5c50 31242@table @r
eb12ee30 31243
8e04817f 31244@item MIPS32
ee2d5c50 31245
599b237a 31246All registers are transferred as thirty-two bit quantities in the order:
8e04817f
AC
3124732 general-purpose; sr; lo; hi; bad; cause; pc; 32 floating-point
31248registers; fsr; fir; fp.
eb12ee30 31249
8e04817f 31250@item MIPS64
ee2d5c50 31251
599b237a 31252All registers are transferred as sixty-four bit quantities (including
8e04817f
AC
31253thirty-two bit registers such as @code{sr}). The ordering is the same
31254as @code{MIPS32}.
eb12ee30 31255
ee2d5c50
AC
31256@end table
31257
9d29849a
JB
31258@node Tracepoint Packets
31259@section Tracepoint Packets
31260@cindex tracepoint packets
31261@cindex packets, tracepoint
31262
31263Here we describe the packets @value{GDBN} uses to implement
31264tracepoints (@pxref{Tracepoints}).
31265
31266@table @samp
31267
7a697b8d 31268@item QTDP:@var{n}:@var{addr}:@var{ena}:@var{step}:@var{pass}[:F@var{flen}][:X@var{len},@var{bytes}]@r{[}-@r{]}
9d29849a
JB
31269Create a new tracepoint, number @var{n}, at @var{addr}. If @var{ena}
31270is @samp{E}, then the tracepoint is enabled; if it is @samp{D}, then
31271the tracepoint is disabled. @var{step} is the tracepoint's step
7a697b8d
SS
31272count, and @var{pass} is its pass count. If an @samp{F} is present,
31273then the tracepoint is to be a fast tracepoint, and the @var{flen} is
31274the number of bytes that the target should copy elsewhere to make room
31275for the tracepoint. If an @samp{X} is present, it introduces a
31276tracepoint condition, which consists of a hexadecimal length, followed
31277by a comma and hex-encoded bytes, in a manner similar to action
31278encodings as described below. If the trailing @samp{-} is present,
31279further @samp{QTDP} packets will follow to specify this tracepoint's
31280actions.
9d29849a
JB
31281
31282Replies:
31283@table @samp
31284@item OK
31285The packet was understood and carried out.
31286@item
31287The packet was not recognized.
31288@end table
31289
31290@item QTDP:-@var{n}:@var{addr}:@r{[}S@r{]}@var{action}@dots{}@r{[}-@r{]}
31291Define actions to be taken when a tracepoint is hit. @var{n} and
31292@var{addr} must be the same as in the initial @samp{QTDP} packet for
31293this tracepoint. This packet may only be sent immediately after
31294another @samp{QTDP} packet that ended with a @samp{-}. If the
31295trailing @samp{-} is present, further @samp{QTDP} packets will follow,
31296specifying more actions for this tracepoint.
31297
31298In the series of action packets for a given tracepoint, at most one
31299can have an @samp{S} before its first @var{action}. If such a packet
31300is sent, it and the following packets define ``while-stepping''
31301actions. Any prior packets define ordinary actions --- that is, those
31302taken when the tracepoint is first hit. If no action packet has an
31303@samp{S}, then all the packets in the series specify ordinary
31304tracepoint actions.
31305
31306The @samp{@var{action}@dots{}} portion of the packet is a series of
31307actions, concatenated without separators. Each action has one of the
31308following forms:
31309
31310@table @samp
31311
31312@item R @var{mask}
31313Collect the registers whose bits are set in @var{mask}. @var{mask} is
599b237a 31314a hexadecimal number whose @var{i}'th bit is set if register number
9d29849a
JB
31315@var{i} should be collected. (The least significant bit is numbered
31316zero.) Note that @var{mask} may be any number of digits long; it may
31317not fit in a 32-bit word.
31318
31319@item M @var{basereg},@var{offset},@var{len}
31320Collect @var{len} bytes of memory starting at the address in register
31321number @var{basereg}, plus @var{offset}. If @var{basereg} is
31322@samp{-1}, then the range has a fixed address: @var{offset} is the
31323address of the lowest byte to collect. The @var{basereg},
599b237a 31324@var{offset}, and @var{len} parameters are all unsigned hexadecimal
9d29849a
JB
31325values (the @samp{-1} value for @var{basereg} is a special case).
31326
31327@item X @var{len},@var{expr}
31328Evaluate @var{expr}, whose length is @var{len}, and collect memory as
31329it directs. @var{expr} is an agent expression, as described in
31330@ref{Agent Expressions}. Each byte of the expression is encoded as a
31331two-digit hex number in the packet; @var{len} is the number of bytes
31332in the expression (and thus one-half the number of hex digits in the
31333packet).
31334
31335@end table
31336
31337Any number of actions may be packed together in a single @samp{QTDP}
31338packet, as long as the packet does not exceed the maximum packet
c1947b85
JB
31339length (400 bytes, for many stubs). There may be only one @samp{R}
31340action per tracepoint, and it must precede any @samp{M} or @samp{X}
31341actions. Any registers referred to by @samp{M} and @samp{X} actions
31342must be collected by a preceding @samp{R} action. (The
31343``while-stepping'' actions are treated as if they were attached to a
31344separate tracepoint, as far as these restrictions are concerned.)
9d29849a
JB
31345
31346Replies:
31347@table @samp
31348@item OK
31349The packet was understood and carried out.
31350@item
31351The packet was not recognized.
31352@end table
31353
409873ef
SS
31354@item QTDPsrc:@var{n}:@var{addr}:@var{type}:@var{start}:@var{slen}:@var{bytes}
31355@cindex @samp{QTDPsrc} packet
31356Specify a source string of tracepoint @var{n} at address @var{addr}.
31357This is useful to get accurate reproduction of the tracepoints
31358originally downloaded at the beginning of the trace run. @var{type}
31359is the name of the tracepoint part, such as @samp{cond} for the
31360tracepoint's conditional expression (see below for a list of types), while
31361@var{bytes} is the string, encoded in hexadecimal.
31362
31363@var{start} is the offset of the @var{bytes} within the overall source
31364string, while @var{slen} is the total length of the source string.
31365This is intended for handling source strings that are longer than will
31366fit in a single packet.
31367@c Add detailed example when this info is moved into a dedicated
31368@c tracepoint descriptions section.
31369
31370The available string types are @samp{at} for the location,
31371@samp{cond} for the conditional, and @samp{cmd} for an action command.
31372@value{GDBN} sends a separate packet for each command in the action
31373list, in the same order in which the commands are stored in the list.
31374
31375The target does not need to do anything with source strings except
31376report them back as part of the replies to the @samp{qTfP}/@samp{qTsP}
31377query packets.
31378
31379Although this packet is optional, and @value{GDBN} will only send it
31380if the target replies with @samp{TracepointSource} @xref{General
31381Query Packets}, it makes both disconnected tracing and trace files
31382much easier to use. Otherwise the user must be careful that the
31383tracepoints in effect while looking at trace frames are identical to
31384the ones in effect during the trace run; even a small discrepancy
31385could cause @samp{tdump} not to work, or a particular trace frame not
31386be found.
31387
f61e138d
SS
31388@item QTDV:@var{n}:@var{value}
31389@cindex define trace state variable, remote request
31390@cindex @samp{QTDV} packet
31391Create a new trace state variable, number @var{n}, with an initial
31392value of @var{value}, which is a 64-bit signed integer. Both @var{n}
31393and @var{value} are encoded as hexadecimal values. @value{GDBN} has
31394the option of not using this packet for initial values of zero; the
31395target should simply create the trace state variables as they are
31396mentioned in expressions.
31397
9d29849a
JB
31398@item QTFrame:@var{n}
31399Select the @var{n}'th tracepoint frame from the buffer, and use the
31400register and memory contents recorded there to answer subsequent
31401request packets from @value{GDBN}.
31402
31403A successful reply from the stub indicates that the stub has found the
31404requested frame. The response is a series of parts, concatenated
31405without separators, describing the frame we selected. Each part has
31406one of the following forms:
31407
31408@table @samp
31409@item F @var{f}
31410The selected frame is number @var{n} in the trace frame buffer;
599b237a 31411@var{f} is a hexadecimal number. If @var{f} is @samp{-1}, then there
9d29849a
JB
31412was no frame matching the criteria in the request packet.
31413
31414@item T @var{t}
31415The selected trace frame records a hit of tracepoint number @var{t};
599b237a 31416@var{t} is a hexadecimal number.
9d29849a
JB
31417
31418@end table
31419
31420@item QTFrame:pc:@var{addr}
31421Like @samp{QTFrame:@var{n}}, but select the first tracepoint frame after the
31422currently selected frame whose PC is @var{addr};
599b237a 31423@var{addr} is a hexadecimal number.
9d29849a
JB
31424
31425@item QTFrame:tdp:@var{t}
31426Like @samp{QTFrame:@var{n}}, but select the first tracepoint frame after the
31427currently selected frame that is a hit of tracepoint @var{t}; @var{t}
599b237a 31428is a hexadecimal number.
9d29849a
JB
31429
31430@item QTFrame:range:@var{start}:@var{end}
31431Like @samp{QTFrame:@var{n}}, but select the first tracepoint frame after the
31432currently selected frame whose PC is between @var{start} (inclusive)
081dfbf7 31433and @var{end} (inclusive); @var{start} and @var{end} are hexadecimal
9d29849a
JB
31434numbers.
31435
31436@item QTFrame:outside:@var{start}:@var{end}
31437Like @samp{QTFrame:range:@var{start}:@var{end}}, but select the first
081dfbf7 31438frame @emph{outside} the given range of addresses (exclusive).
9d29849a
JB
31439
31440@item QTStart
31441Begin the tracepoint experiment. Begin collecting data from tracepoint
31442hits in the trace frame buffer.
31443
31444@item QTStop
31445End the tracepoint experiment. Stop collecting trace frames.
31446
31447@item QTinit
31448Clear the table of tracepoints, and empty the trace frame buffer.
31449
31450@item QTro:@var{start1},@var{end1}:@var{start2},@var{end2}:@dots{}
31451Establish the given ranges of memory as ``transparent''. The stub
31452will answer requests for these ranges from memory's current contents,
31453if they were not collected as part of the tracepoint hit.
31454
31455@value{GDBN} uses this to mark read-only regions of memory, like those
31456containing program code. Since these areas never change, they should
31457still have the same contents they did when the tracepoint was hit, so
31458there's no reason for the stub to refuse to provide their contents.
31459
d5551862
SS
31460@item QTDisconnected:@var{value}
31461Set the choice to what to do with the tracing run when @value{GDBN}
31462disconnects from the target. A @var{value} of 1 directs the target to
31463continue the tracing run, while 0 tells the target to stop tracing if
31464@value{GDBN} is no longer in the picture.
31465
9d29849a
JB
31466@item qTStatus
31467Ask the stub if there is a trace experiment running right now.
31468
4daf5ac0
SS
31469The reply has the form:
31470
31471@table @samp
31472
31473@item T@var{running}@r{[};@var{field}@r{]}@dots{}
31474@var{running} is a single digit @code{1} if the trace is presently
31475running, or @code{0} if not. It is followed by semicolon-separated
31476optional fields that an agent may use to report additional status.
31477
31478@end table
31479
31480If the trace is not running, the agent may report any of several
31481explanations as one of the optional fields:
31482
31483@table @samp
31484
31485@item tnotrun:0
31486No trace has been run yet.
31487
31488@item tstop:0
31489The trace was stopped by a user-originated stop command.
31490
31491@item tfull:0
31492The trace stopped because the trace buffer filled up.
31493
31494@item tdisconnected:0
31495The trace stopped because @value{GDBN} disconnected from the target.
31496
31497@item tpasscount:@var{tpnum}
31498The trace stopped because tracepoint @var{tpnum} exceeded its pass count.
31499
6c28cbf2
SS
31500@item terror:@var{text}:@var{tpnum}
31501The trace stopped because tracepoint @var{tpnum} had an error. The
31502string @var{text} is available to describe the nature of the error
31503(for instance, a divide by zero in the condition expression).
99b5e152 31504@var{text} is hex encoded.
6c28cbf2 31505
4daf5ac0
SS
31506@item tunknown:0
31507The trace stopped for some other reason.
31508
31509@end table
31510
33da3f1c
SS
31511Additional optional fields supply statistical and other information.
31512Although not required, they are extremely useful for users monitoring
31513the progress of a trace run. If a trace has stopped, and these
31514numbers are reported, they must reflect the state of the just-stopped
31515trace.
4daf5ac0 31516
9d29849a 31517@table @samp
4daf5ac0
SS
31518
31519@item tframes:@var{n}
31520The number of trace frames in the buffer.
31521
31522@item tcreated:@var{n}
31523The total number of trace frames created during the run. This may
31524be larger than the trace frame count, if the buffer is circular.
31525
31526@item tsize:@var{n}
31527The total size of the trace buffer, in bytes.
31528
31529@item tfree:@var{n}
31530The number of bytes still unused in the buffer.
31531
33da3f1c
SS
31532@item circular:@var{n}
31533The value of the circular trace buffer flag. @code{1} means that the
31534trace buffer is circular and old trace frames will be discarded if
31535necessary to make room, @code{0} means that the trace buffer is linear
31536and may fill up.
31537
31538@item disconn:@var{n}
31539The value of the disconnected tracing flag. @code{1} means that
31540tracing will continue after @value{GDBN} disconnects, @code{0} means
31541that the trace run will stop.
31542
9d29849a
JB
31543@end table
31544
f61e138d
SS
31545@item qTV:@var{var}
31546@cindex trace state variable value, remote request
31547@cindex @samp{qTV} packet
31548Ask the stub for the value of the trace state variable number @var{var}.
31549
31550Replies:
31551@table @samp
31552@item V@var{value}
31553The value of the variable is @var{value}. This will be the current
31554value of the variable if the user is examining a running target, or a
31555saved value if the variable was collected in the trace frame that the
31556user is looking at. Note that multiple requests may result in
31557different reply values, such as when requesting values while the
31558program is running.
31559
31560@item U
31561The value of the variable is unknown. This would occur, for example,
31562if the user is examining a trace frame in which the requested variable
31563was not collected.
9d29849a
JB
31564@end table
31565
d5551862
SS
31566@item qTfP
31567@itemx qTsP
31568These packets request data about tracepoints that are being used by
31569the target. @value{GDBN} sends @code{qTfP} to get the first piece
31570of data, and multiple @code{qTsP} to get additional pieces. Replies
31571to these packets generally take the form of the @code{QTDP} packets
31572that define tracepoints. (FIXME add detailed syntax)
31573
00bf0b85
SS
31574@item qTfV
31575@itemx qTsV
31576These packets request data about trace state variables that are on the
31577target. @value{GDBN} sends @code{qTfV} to get the first vari of data,
31578and multiple @code{qTsV} to get additional variables. Replies to
31579these packets follow the syntax of the @code{QTDV} packets that define
31580trace state variables.
31581
31582@item QTSave:@var{filename}
31583This packet directs the target to save trace data to the file name
31584@var{filename} in the target's filesystem. @var{filename} is encoded
31585as a hex string; the interpretation of the file name (relative vs
31586absolute, wild cards, etc) is up to the target.
31587
31588@item qTBuffer:@var{offset},@var{len}
31589Return up to @var{len} bytes of the current contents of trace buffer,
31590starting at @var{offset}. The trace buffer is treated as if it were
31591a contiguous collection of traceframes, as per the trace file format.
31592The reply consists as many hex-encoded bytes as the target can deliver
31593in a packet; it is not an error to return fewer than were asked for.
31594A reply consisting of just @code{l} indicates that no bytes are
31595available.
31596
4daf5ac0
SS
31597@item QTBuffer:circular:@var{value}
31598This packet directs the target to use a circular trace buffer if
31599@var{value} is 1, or a linear buffer if the value is 0.
31600
f61e138d 31601@end table
9d29849a 31602
a6b151f1
DJ
31603@node Host I/O Packets
31604@section Host I/O Packets
31605@cindex Host I/O, remote protocol
31606@cindex file transfer, remote protocol
31607
31608The @dfn{Host I/O} packets allow @value{GDBN} to perform I/O
31609operations on the far side of a remote link. For example, Host I/O is
31610used to upload and download files to a remote target with its own
31611filesystem. Host I/O uses the same constant values and data structure
31612layout as the target-initiated File-I/O protocol. However, the
31613Host I/O packets are structured differently. The target-initiated
31614protocol relies on target memory to store parameters and buffers.
31615Host I/O requests are initiated by @value{GDBN}, and the
31616target's memory is not involved. @xref{File-I/O Remote Protocol
31617Extension}, for more details on the target-initiated protocol.
31618
31619The Host I/O request packets all encode a single operation along with
31620its arguments. They have this format:
31621
31622@table @samp
31623
31624@item vFile:@var{operation}: @var{parameter}@dots{}
31625@var{operation} is the name of the particular request; the target
31626should compare the entire packet name up to the second colon when checking
31627for a supported operation. The format of @var{parameter} depends on
31628the operation. Numbers are always passed in hexadecimal. Negative
31629numbers have an explicit minus sign (i.e.@: two's complement is not
31630used). Strings (e.g.@: filenames) are encoded as a series of
31631hexadecimal bytes. The last argument to a system call may be a
31632buffer of escaped binary data (@pxref{Binary Data}).
31633
31634@end table
31635
31636The valid responses to Host I/O packets are:
31637
31638@table @samp
31639
31640@item F @var{result} [, @var{errno}] [; @var{attachment}]
31641@var{result} is the integer value returned by this operation, usually
31642non-negative for success and -1 for errors. If an error has occured,
31643@var{errno} will be included in the result. @var{errno} will have a
31644value defined by the File-I/O protocol (@pxref{Errno Values}). For
31645operations which return data, @var{attachment} supplies the data as a
31646binary buffer. Binary buffers in response packets are escaped in the
31647normal way (@pxref{Binary Data}). See the individual packet
31648documentation for the interpretation of @var{result} and
31649@var{attachment}.
31650
31651@item
31652An empty response indicates that this operation is not recognized.
31653
31654@end table
31655
31656These are the supported Host I/O operations:
31657
31658@table @samp
31659@item vFile:open: @var{pathname}, @var{flags}, @var{mode}
31660Open a file at @var{pathname} and return a file descriptor for it, or
31661return -1 if an error occurs. @var{pathname} is a string,
31662@var{flags} is an integer indicating a mask of open flags
31663(@pxref{Open Flags}), and @var{mode} is an integer indicating a mask
31664of mode bits to use if the file is created (@pxref{mode_t Values}).
c1c25a1a 31665@xref{open}, for details of the open flags and mode values.
a6b151f1
DJ
31666
31667@item vFile:close: @var{fd}
31668Close the open file corresponding to @var{fd} and return 0, or
31669-1 if an error occurs.
31670
31671@item vFile:pread: @var{fd}, @var{count}, @var{offset}
31672Read data from the open file corresponding to @var{fd}. Up to
31673@var{count} bytes will be read from the file, starting at @var{offset}
31674relative to the start of the file. The target may read fewer bytes;
31675common reasons include packet size limits and an end-of-file
31676condition. The number of bytes read is returned. Zero should only be
31677returned for a successful read at the end of the file, or if
31678@var{count} was zero.
31679
31680The data read should be returned as a binary attachment on success.
31681If zero bytes were read, the response should include an empty binary
31682attachment (i.e.@: a trailing semicolon). The return value is the
31683number of target bytes read; the binary attachment may be longer if
31684some characters were escaped.
31685
31686@item vFile:pwrite: @var{fd}, @var{offset}, @var{data}
31687Write @var{data} (a binary buffer) to the open file corresponding
31688to @var{fd}. Start the write at @var{offset} from the start of the
31689file. Unlike many @code{write} system calls, there is no
31690separate @var{count} argument; the length of @var{data} in the
31691packet is used. @samp{vFile:write} returns the number of bytes written,
31692which may be shorter than the length of @var{data}, or -1 if an
31693error occurred.
31694
31695@item vFile:unlink: @var{pathname}
31696Delete the file at @var{pathname} on the target. Return 0,
31697or -1 if an error occurs. @var{pathname} is a string.
31698
31699@end table
31700
9a6253be
KB
31701@node Interrupts
31702@section Interrupts
31703@cindex interrupts (remote protocol)
31704
31705When a program on the remote target is running, @value{GDBN} may
9a7071a8
JB
31706attempt to interrupt it by sending a @samp{Ctrl-C}, @code{BREAK} or
31707a @code{BREAK} followed by @code{g},
31708control of which is specified via @value{GDBN}'s @samp{interrupt-sequence}.
9a6253be
KB
31709
31710The precise meaning of @code{BREAK} is defined by the transport
8775bb90
MS
31711mechanism and may, in fact, be undefined. @value{GDBN} does not
31712currently define a @code{BREAK} mechanism for any of the network
31713interfaces except for TCP, in which case @value{GDBN} sends the
31714@code{telnet} BREAK sequence.
9a6253be
KB
31715
31716@samp{Ctrl-C}, on the other hand, is defined and implemented for all
31717transport mechanisms. It is represented by sending the single byte
31718@code{0x03} without any of the usual packet overhead described in
31719the Overview section (@pxref{Overview}). When a @code{0x03} byte is
31720transmitted as part of a packet, it is considered to be packet data
31721and does @emph{not} represent an interrupt. E.g., an @samp{X} packet
0876f84a 31722(@pxref{X packet}), used for binary downloads, may include an unescaped
9a6253be
KB
31723@code{0x03} as part of its packet.
31724
9a7071a8
JB
31725@code{BREAK} followed by @code{g} is also known as Magic SysRq g.
31726When Linux kernel receives this sequence from serial port,
31727it stops execution and connects to gdb.
31728
9a6253be
KB
31729Stubs are not required to recognize these interrupt mechanisms and the
31730precise meaning associated with receipt of the interrupt is
8b23ecc4
SL
31731implementation defined. If the target supports debugging of multiple
31732threads and/or processes, it should attempt to interrupt all
31733currently-executing threads and processes.
31734If the stub is successful at interrupting the
31735running program, it should send one of the stop
31736reply packets (@pxref{Stop Reply Packets}) to @value{GDBN} as a result
31737of successfully stopping the program in all-stop mode, and a stop reply
31738for each stopped thread in non-stop mode.
31739Interrupts received while the
31740program is stopped are discarded.
31741
31742@node Notification Packets
31743@section Notification Packets
31744@cindex notification packets
31745@cindex packets, notification
31746
31747The @value{GDBN} remote serial protocol includes @dfn{notifications},
31748packets that require no acknowledgment. Both the GDB and the stub
31749may send notifications (although the only notifications defined at
31750present are sent by the stub). Notifications carry information
31751without incurring the round-trip latency of an acknowledgment, and so
31752are useful for low-impact communications where occasional packet loss
31753is not a problem.
31754
31755A notification packet has the form @samp{% @var{data} #
31756@var{checksum}}, where @var{data} is the content of the notification,
31757and @var{checksum} is a checksum of @var{data}, computed and formatted
31758as for ordinary @value{GDBN} packets. A notification's @var{data}
31759never contains @samp{$}, @samp{%} or @samp{#} characters. Upon
31760receiving a notification, the recipient sends no @samp{+} or @samp{-}
31761to acknowledge the notification's receipt or to report its corruption.
31762
31763Every notification's @var{data} begins with a name, which contains no
31764colon characters, followed by a colon character.
31765
31766Recipients should silently ignore corrupted notifications and
31767notifications they do not understand. Recipients should restart
31768timeout periods on receipt of a well-formed notification, whether or
31769not they understand it.
31770
31771Senders should only send the notifications described here when this
31772protocol description specifies that they are permitted. In the
31773future, we may extend the protocol to permit existing notifications in
31774new contexts; this rule helps older senders avoid confusing newer
31775recipients.
31776
31777(Older versions of @value{GDBN} ignore bytes received until they see
31778the @samp{$} byte that begins an ordinary packet, so new stubs may
31779transmit notifications without fear of confusing older clients. There
31780are no notifications defined for @value{GDBN} to send at the moment, but we
31781assume that most older stubs would ignore them, as well.)
31782
31783The following notification packets from the stub to @value{GDBN} are
31784defined:
31785
31786@table @samp
31787@item Stop: @var{reply}
31788Report an asynchronous stop event in non-stop mode.
31789The @var{reply} has the form of a stop reply, as
31790described in @ref{Stop Reply Packets}. Refer to @ref{Remote Non-Stop},
31791for information on how these notifications are acknowledged by
31792@value{GDBN}.
31793@end table
31794
31795@node Remote Non-Stop
31796@section Remote Protocol Support for Non-Stop Mode
31797
31798@value{GDBN}'s remote protocol supports non-stop debugging of
31799multi-threaded programs, as described in @ref{Non-Stop Mode}. If the stub
31800supports non-stop mode, it should report that to @value{GDBN} by including
31801@samp{QNonStop+} in its @samp{qSupported} response (@pxref{qSupported}).
31802
31803@value{GDBN} typically sends a @samp{QNonStop} packet only when
31804establishing a new connection with the stub. Entering non-stop mode
31805does not alter the state of any currently-running threads, but targets
31806must stop all threads in any already-attached processes when entering
31807all-stop mode. @value{GDBN} uses the @samp{?} packet as necessary to
31808probe the target state after a mode change.
31809
31810In non-stop mode, when an attached process encounters an event that
31811would otherwise be reported with a stop reply, it uses the
31812asynchronous notification mechanism (@pxref{Notification Packets}) to
31813inform @value{GDBN}. In contrast to all-stop mode, where all threads
31814in all processes are stopped when a stop reply is sent, in non-stop
31815mode only the thread reporting the stop event is stopped. That is,
31816when reporting a @samp{S} or @samp{T} response to indicate completion
31817of a step operation, hitting a breakpoint, or a fault, only the
31818affected thread is stopped; any other still-running threads continue
31819to run. When reporting a @samp{W} or @samp{X} response, all running
31820threads belonging to other attached processes continue to run.
31821
31822Only one stop reply notification at a time may be pending; if
31823additional stop events occur before @value{GDBN} has acknowledged the
31824previous notification, they must be queued by the stub for later
31825synchronous transmission in response to @samp{vStopped} packets from
31826@value{GDBN}. Because the notification mechanism is unreliable,
31827the stub is permitted to resend a stop reply notification
31828if it believes @value{GDBN} may not have received it. @value{GDBN}
31829ignores additional stop reply notifications received before it has
31830finished processing a previous notification and the stub has completed
31831sending any queued stop events.
31832
31833Otherwise, @value{GDBN} must be prepared to receive a stop reply
31834notification at any time. Specifically, they may appear when
31835@value{GDBN} is not otherwise reading input from the stub, or when
31836@value{GDBN} is expecting to read a normal synchronous response or a
31837@samp{+}/@samp{-} acknowledgment to a packet it has sent.
31838Notification packets are distinct from any other communication from
31839the stub so there is no ambiguity.
31840
31841After receiving a stop reply notification, @value{GDBN} shall
31842acknowledge it by sending a @samp{vStopped} packet (@pxref{vStopped packet})
31843as a regular, synchronous request to the stub. Such acknowledgment
31844is not required to happen immediately, as @value{GDBN} is permitted to
31845send other, unrelated packets to the stub first, which the stub should
31846process normally.
31847
31848Upon receiving a @samp{vStopped} packet, if the stub has other queued
31849stop events to report to @value{GDBN}, it shall respond by sending a
31850normal stop reply response. @value{GDBN} shall then send another
31851@samp{vStopped} packet to solicit further responses; again, it is
31852permitted to send other, unrelated packets as well which the stub
31853should process normally.
31854
31855If the stub receives a @samp{vStopped} packet and there are no
31856additional stop events to report, the stub shall return an @samp{OK}
31857response. At this point, if further stop events occur, the stub shall
31858send a new stop reply notification, @value{GDBN} shall accept the
31859notification, and the process shall be repeated.
31860
31861In non-stop mode, the target shall respond to the @samp{?} packet as
31862follows. First, any incomplete stop reply notification/@samp{vStopped}
31863sequence in progress is abandoned. The target must begin a new
31864sequence reporting stop events for all stopped threads, whether or not
31865it has previously reported those events to @value{GDBN}. The first
31866stop reply is sent as a synchronous reply to the @samp{?} packet, and
31867subsequent stop replies are sent as responses to @samp{vStopped} packets
31868using the mechanism described above. The target must not send
31869asynchronous stop reply notifications until the sequence is complete.
31870If all threads are running when the target receives the @samp{?} packet,
31871or if the target is not attached to any process, it shall respond
31872@samp{OK}.
9a6253be 31873
a6f3e723
SL
31874@node Packet Acknowledgment
31875@section Packet Acknowledgment
31876
31877@cindex acknowledgment, for @value{GDBN} remote
31878@cindex packet acknowledgment, for @value{GDBN} remote
31879By default, when either the host or the target machine receives a packet,
31880the first response expected is an acknowledgment: either @samp{+} (to indicate
31881the package was received correctly) or @samp{-} (to request retransmission).
31882This mechanism allows the @value{GDBN} remote protocol to operate over
31883unreliable transport mechanisms, such as a serial line.
31884
31885In cases where the transport mechanism is itself reliable (such as a pipe or
31886TCP connection), the @samp{+}/@samp{-} acknowledgments are redundant.
31887It may be desirable to disable them in that case to reduce communication
31888overhead, or for other reasons. This can be accomplished by means of the
31889@samp{QStartNoAckMode} packet; @pxref{QStartNoAckMode}.
31890
31891When in no-acknowledgment mode, neither the stub nor @value{GDBN} shall send or
31892expect @samp{+}/@samp{-} protocol acknowledgments. The packet
31893and response format still includes the normal checksum, as described in
31894@ref{Overview}, but the checksum may be ignored by the receiver.
31895
31896If the stub supports @samp{QStartNoAckMode} and prefers to operate in
31897no-acknowledgment mode, it should report that to @value{GDBN}
31898by including @samp{QStartNoAckMode+} in its response to @samp{qSupported};
31899@pxref{qSupported}.
31900If @value{GDBN} also supports @samp{QStartNoAckMode} and it has not been
31901disabled via the @code{set remote noack-packet off} command
31902(@pxref{Remote Configuration}),
31903@value{GDBN} may then send a @samp{QStartNoAckMode} packet to the stub.
31904Only then may the stub actually turn off packet acknowledgments.
31905@value{GDBN} sends a final @samp{+} acknowledgment of the stub's @samp{OK}
31906response, which can be safely ignored by the stub.
31907
31908Note that @code{set remote noack-packet} command only affects negotiation
31909between @value{GDBN} and the stub when subsequent connections are made;
31910it does not affect the protocol acknowledgment state for any current
31911connection.
31912Since @samp{+}/@samp{-} acknowledgments are enabled by default when a
31913new connection is established,
31914there is also no protocol request to re-enable the acknowledgments
31915for the current connection, once disabled.
31916
ee2d5c50
AC
31917@node Examples
31918@section Examples
eb12ee30 31919
8e04817f
AC
31920Example sequence of a target being re-started. Notice how the restart
31921does not get any direct output:
eb12ee30 31922
474c8240 31923@smallexample
d2c6833e
AC
31924-> @code{R00}
31925<- @code{+}
8e04817f 31926@emph{target restarts}
d2c6833e 31927-> @code{?}
8e04817f 31928<- @code{+}
d2c6833e
AC
31929<- @code{T001:1234123412341234}
31930-> @code{+}
474c8240 31931@end smallexample
eb12ee30 31932
8e04817f 31933Example sequence of a target being stepped by a single instruction:
eb12ee30 31934
474c8240 31935@smallexample
d2c6833e 31936-> @code{G1445@dots{}}
8e04817f 31937<- @code{+}
d2c6833e
AC
31938-> @code{s}
31939<- @code{+}
31940@emph{time passes}
31941<- @code{T001:1234123412341234}
8e04817f 31942-> @code{+}
d2c6833e 31943-> @code{g}
8e04817f 31944<- @code{+}
d2c6833e
AC
31945<- @code{1455@dots{}}
31946-> @code{+}
474c8240 31947@end smallexample
eb12ee30 31948
79a6e687
BW
31949@node File-I/O Remote Protocol Extension
31950@section File-I/O Remote Protocol Extension
0ce1b118
CV
31951@cindex File-I/O remote protocol extension
31952
31953@menu
31954* File-I/O Overview::
79a6e687
BW
31955* Protocol Basics::
31956* The F Request Packet::
31957* The F Reply Packet::
31958* The Ctrl-C Message::
0ce1b118 31959* Console I/O::
79a6e687 31960* List of Supported Calls::
db2e3e2e 31961* Protocol-specific Representation of Datatypes::
0ce1b118
CV
31962* Constants::
31963* File-I/O Examples::
31964@end menu
31965
31966@node File-I/O Overview
31967@subsection File-I/O Overview
31968@cindex file-i/o overview
31969
9c16f35a 31970The @dfn{File I/O remote protocol extension} (short: File-I/O) allows the
fc320d37 31971target to use the host's file system and console I/O to perform various
0ce1b118 31972system calls. System calls on the target system are translated into a
fc320d37
SL
31973remote protocol packet to the host system, which then performs the needed
31974actions and returns a response packet to the target system.
0ce1b118
CV
31975This simulates file system operations even on targets that lack file systems.
31976
fc320d37
SL
31977The protocol is defined to be independent of both the host and target systems.
31978It uses its own internal representation of datatypes and values. Both
0ce1b118 31979@value{GDBN} and the target's @value{GDBN} stub are responsible for
fc320d37
SL
31980translating the system-dependent value representations into the internal
31981protocol representations when data is transmitted.
0ce1b118 31982
fc320d37
SL
31983The communication is synchronous. A system call is possible only when
31984@value{GDBN} is waiting for a response from the @samp{C}, @samp{c}, @samp{S}
31985or @samp{s} packets. While @value{GDBN} handles the request for a system call,
0ce1b118 31986the target is stopped to allow deterministic access to the target's
fc320d37
SL
31987memory. Therefore File-I/O is not interruptible by target signals. On
31988the other hand, it is possible to interrupt File-I/O by a user interrupt
c8aa23ab 31989(@samp{Ctrl-C}) within @value{GDBN}.
0ce1b118
CV
31990
31991The target's request to perform a host system call does not finish
31992the latest @samp{C}, @samp{c}, @samp{S} or @samp{s} action. That means,
31993after finishing the system call, the target returns to continuing the
31994previous activity (continue, step). No additional continue or step
31995request from @value{GDBN} is required.
31996
31997@smallexample
f7dc1244 31998(@value{GDBP}) continue
0ce1b118
CV
31999 <- target requests 'system call X'
32000 target is stopped, @value{GDBN} executes system call
3f94c067
BW
32001 -> @value{GDBN} returns result
32002 ... target continues, @value{GDBN} returns to wait for the target
0ce1b118
CV
32003 <- target hits breakpoint and sends a Txx packet
32004@end smallexample
32005
fc320d37
SL
32006The protocol only supports I/O on the console and to regular files on
32007the host file system. Character or block special devices, pipes,
32008named pipes, sockets or any other communication method on the host
0ce1b118
CV
32009system are not supported by this protocol.
32010
8b23ecc4
SL
32011File I/O is not supported in non-stop mode.
32012
79a6e687
BW
32013@node Protocol Basics
32014@subsection Protocol Basics
0ce1b118
CV
32015@cindex protocol basics, file-i/o
32016
fc320d37
SL
32017The File-I/O protocol uses the @code{F} packet as the request as well
32018as reply packet. Since a File-I/O system call can only occur when
32019@value{GDBN} is waiting for a response from the continuing or stepping target,
32020the File-I/O request is a reply that @value{GDBN} has to expect as a result
32021of a previous @samp{C}, @samp{c}, @samp{S} or @samp{s} packet.
0ce1b118
CV
32022This @code{F} packet contains all information needed to allow @value{GDBN}
32023to call the appropriate host system call:
32024
32025@itemize @bullet
b383017d 32026@item
0ce1b118
CV
32027A unique identifier for the requested system call.
32028
32029@item
32030All parameters to the system call. Pointers are given as addresses
32031in the target memory address space. Pointers to strings are given as
b383017d 32032pointer/length pair. Numerical values are given as they are.
db2e3e2e 32033Numerical control flags are given in a protocol-specific representation.
0ce1b118
CV
32034
32035@end itemize
32036
fc320d37 32037At this point, @value{GDBN} has to perform the following actions.
0ce1b118
CV
32038
32039@itemize @bullet
b383017d 32040@item
fc320d37
SL
32041If the parameters include pointer values to data needed as input to a
32042system call, @value{GDBN} requests this data from the target with a
0ce1b118
CV
32043standard @code{m} packet request. This additional communication has to be
32044expected by the target implementation and is handled as any other @code{m}
32045packet.
32046
32047@item
32048@value{GDBN} translates all value from protocol representation to host
32049representation as needed. Datatypes are coerced into the host types.
32050
32051@item
fc320d37 32052@value{GDBN} calls the system call.
0ce1b118
CV
32053
32054@item
32055It then coerces datatypes back to protocol representation.
32056
32057@item
fc320d37
SL
32058If the system call is expected to return data in buffer space specified
32059by pointer parameters to the call, the data is transmitted to the
0ce1b118
CV
32060target using a @code{M} or @code{X} packet. This packet has to be expected
32061by the target implementation and is handled as any other @code{M} or @code{X}
32062packet.
32063
32064@end itemize
32065
32066Eventually @value{GDBN} replies with another @code{F} packet which contains all
32067necessary information for the target to continue. This at least contains
32068
32069@itemize @bullet
32070@item
32071Return value.
32072
32073@item
32074@code{errno}, if has been changed by the system call.
32075
32076@item
32077``Ctrl-C'' flag.
32078
32079@end itemize
32080
32081After having done the needed type and value coercion, the target continues
32082the latest continue or step action.
32083
79a6e687
BW
32084@node The F Request Packet
32085@subsection The @code{F} Request Packet
0ce1b118
CV
32086@cindex file-i/o request packet
32087@cindex @code{F} request packet
32088
32089The @code{F} request packet has the following format:
32090
32091@table @samp
fc320d37 32092@item F@var{call-id},@var{parameter@dots{}}
0ce1b118
CV
32093
32094@var{call-id} is the identifier to indicate the host system call to be called.
32095This is just the name of the function.
32096
fc320d37
SL
32097@var{parameter@dots{}} are the parameters to the system call.
32098Parameters are hexadecimal integer values, either the actual values in case
32099of scalar datatypes, pointers to target buffer space in case of compound
32100datatypes and unspecified memory areas, or pointer/length pairs in case
32101of string parameters. These are appended to the @var{call-id} as a
32102comma-delimited list. All values are transmitted in ASCII
32103string representation, pointer/length pairs separated by a slash.
0ce1b118 32104
b383017d 32105@end table
0ce1b118 32106
fc320d37 32107
0ce1b118 32108
79a6e687
BW
32109@node The F Reply Packet
32110@subsection The @code{F} Reply Packet
0ce1b118
CV
32111@cindex file-i/o reply packet
32112@cindex @code{F} reply packet
32113
32114The @code{F} reply packet has the following format:
32115
32116@table @samp
32117
d3bdde98 32118@item F@var{retcode},@var{errno},@var{Ctrl-C flag};@var{call-specific attachment}
0ce1b118
CV
32119
32120@var{retcode} is the return code of the system call as hexadecimal value.
32121
db2e3e2e
BW
32122@var{errno} is the @code{errno} set by the call, in protocol-specific
32123representation.
0ce1b118
CV
32124This parameter can be omitted if the call was successful.
32125
fc320d37
SL
32126@var{Ctrl-C flag} is only sent if the user requested a break. In this
32127case, @var{errno} must be sent as well, even if the call was successful.
32128The @var{Ctrl-C flag} itself consists of the character @samp{C}:
0ce1b118
CV
32129
32130@smallexample
32131F0,0,C
32132@end smallexample
32133
32134@noindent
fc320d37 32135or, if the call was interrupted before the host call has been performed:
0ce1b118
CV
32136
32137@smallexample
32138F-1,4,C
32139@end smallexample
32140
32141@noindent
db2e3e2e 32142assuming 4 is the protocol-specific representation of @code{EINTR}.
0ce1b118
CV
32143
32144@end table
32145
0ce1b118 32146
79a6e687
BW
32147@node The Ctrl-C Message
32148@subsection The @samp{Ctrl-C} Message
0ce1b118
CV
32149@cindex ctrl-c message, in file-i/o protocol
32150
c8aa23ab 32151If the @samp{Ctrl-C} flag is set in the @value{GDBN}
79a6e687 32152reply packet (@pxref{The F Reply Packet}),
fc320d37 32153the target should behave as if it had
0ce1b118 32154gotten a break message. The meaning for the target is ``system call
fc320d37 32155interrupted by @code{SIGINT}''. Consequentially, the target should actually stop
0ce1b118 32156(as with a break message) and return to @value{GDBN} with a @code{T02}
c8aa23ab 32157packet.
fc320d37
SL
32158
32159It's important for the target to know in which
32160state the system call was interrupted. There are two possible cases:
0ce1b118
CV
32161
32162@itemize @bullet
32163@item
32164The system call hasn't been performed on the host yet.
32165
32166@item
32167The system call on the host has been finished.
32168
32169@end itemize
32170
32171These two states can be distinguished by the target by the value of the
32172returned @code{errno}. If it's the protocol representation of @code{EINTR}, the system
32173call hasn't been performed. This is equivalent to the @code{EINTR} handling
32174on POSIX systems. In any other case, the target may presume that the
fc320d37 32175system call has been finished --- successfully or not --- and should behave
0ce1b118
CV
32176as if the break message arrived right after the system call.
32177
fc320d37 32178@value{GDBN} must behave reliably. If the system call has not been called
0ce1b118
CV
32179yet, @value{GDBN} may send the @code{F} reply immediately, setting @code{EINTR} as
32180@code{errno} in the packet. If the system call on the host has been finished
fc320d37
SL
32181before the user requests a break, the full action must be finished by
32182@value{GDBN}. This requires sending @code{M} or @code{X} packets as necessary.
32183The @code{F} packet may only be sent when either nothing has happened
0ce1b118
CV
32184or the full action has been completed.
32185
32186@node Console I/O
32187@subsection Console I/O
32188@cindex console i/o as part of file-i/o
32189
d3e8051b 32190By default and if not explicitly closed by the target system, the file
0ce1b118
CV
32191descriptors 0, 1 and 2 are connected to the @value{GDBN} console. Output
32192on the @value{GDBN} console is handled as any other file output operation
32193(@code{write(1, @dots{})} or @code{write(2, @dots{})}). Console input is handled
32194by @value{GDBN} so that after the target read request from file descriptor
321950 all following typing is buffered until either one of the following
32196conditions is met:
32197
32198@itemize @bullet
32199@item
c8aa23ab 32200The user types @kbd{Ctrl-c}. The behaviour is as explained above, and the
0ce1b118
CV
32201@code{read}
32202system call is treated as finished.
32203
32204@item
7f9087cb 32205The user presses @key{RET}. This is treated as end of input with a trailing
fc320d37 32206newline.
0ce1b118
CV
32207
32208@item
c8aa23ab
EZ
32209The user types @kbd{Ctrl-d}. This is treated as end of input. No trailing
32210character (neither newline nor @samp{Ctrl-D}) is appended to the input.
0ce1b118
CV
32211
32212@end itemize
32213
fc320d37
SL
32214If the user has typed more characters than fit in the buffer given to
32215the @code{read} call, the trailing characters are buffered in @value{GDBN} until
32216either another @code{read(0, @dots{})} is requested by the target, or debugging
32217is stopped at the user's request.
0ce1b118 32218
0ce1b118 32219
79a6e687
BW
32220@node List of Supported Calls
32221@subsection List of Supported Calls
0ce1b118
CV
32222@cindex list of supported file-i/o calls
32223
32224@menu
32225* open::
32226* close::
32227* read::
32228* write::
32229* lseek::
32230* rename::
32231* unlink::
32232* stat/fstat::
32233* gettimeofday::
32234* isatty::
32235* system::
32236@end menu
32237
32238@node open
32239@unnumberedsubsubsec open
32240@cindex open, file-i/o system call
32241
fc320d37
SL
32242@table @asis
32243@item Synopsis:
0ce1b118 32244@smallexample
0ce1b118
CV
32245int open(const char *pathname, int flags);
32246int open(const char *pathname, int flags, mode_t mode);
0ce1b118
CV
32247@end smallexample
32248
fc320d37
SL
32249@item Request:
32250@samp{Fopen,@var{pathptr}/@var{len},@var{flags},@var{mode}}
32251
0ce1b118 32252@noindent
fc320d37 32253@var{flags} is the bitwise @code{OR} of the following values:
0ce1b118
CV
32254
32255@table @code
b383017d 32256@item O_CREAT
0ce1b118
CV
32257If the file does not exist it will be created. The host
32258rules apply as far as file ownership and time stamps
32259are concerned.
32260
b383017d 32261@item O_EXCL
fc320d37 32262When used with @code{O_CREAT}, if the file already exists it is
0ce1b118
CV
32263an error and open() fails.
32264
b383017d 32265@item O_TRUNC
0ce1b118 32266If the file already exists and the open mode allows
fc320d37
SL
32267writing (@code{O_RDWR} or @code{O_WRONLY} is given) it will be
32268truncated to zero length.
0ce1b118 32269
b383017d 32270@item O_APPEND
0ce1b118
CV
32271The file is opened in append mode.
32272
b383017d 32273@item O_RDONLY
0ce1b118
CV
32274The file is opened for reading only.
32275
b383017d 32276@item O_WRONLY
0ce1b118
CV
32277The file is opened for writing only.
32278
b383017d 32279@item O_RDWR
0ce1b118 32280The file is opened for reading and writing.
fc320d37 32281@end table
0ce1b118
CV
32282
32283@noindent
fc320d37 32284Other bits are silently ignored.
0ce1b118 32285
0ce1b118
CV
32286
32287@noindent
fc320d37 32288@var{mode} is the bitwise @code{OR} of the following values:
0ce1b118
CV
32289
32290@table @code
b383017d 32291@item S_IRUSR
0ce1b118
CV
32292User has read permission.
32293
b383017d 32294@item S_IWUSR
0ce1b118
CV
32295User has write permission.
32296
b383017d 32297@item S_IRGRP
0ce1b118
CV
32298Group has read permission.
32299
b383017d 32300@item S_IWGRP
0ce1b118
CV
32301Group has write permission.
32302
b383017d 32303@item S_IROTH
0ce1b118
CV
32304Others have read permission.
32305
b383017d 32306@item S_IWOTH
0ce1b118 32307Others have write permission.
fc320d37 32308@end table
0ce1b118
CV
32309
32310@noindent
fc320d37 32311Other bits are silently ignored.
0ce1b118 32312
0ce1b118 32313
fc320d37
SL
32314@item Return value:
32315@code{open} returns the new file descriptor or -1 if an error
32316occurred.
0ce1b118 32317
fc320d37 32318@item Errors:
0ce1b118
CV
32319
32320@table @code
b383017d 32321@item EEXIST
fc320d37 32322@var{pathname} already exists and @code{O_CREAT} and @code{O_EXCL} were used.
0ce1b118 32323
b383017d 32324@item EISDIR
fc320d37 32325@var{pathname} refers to a directory.
0ce1b118 32326
b383017d 32327@item EACCES
0ce1b118
CV
32328The requested access is not allowed.
32329
32330@item ENAMETOOLONG
fc320d37 32331@var{pathname} was too long.
0ce1b118 32332
b383017d 32333@item ENOENT
fc320d37 32334A directory component in @var{pathname} does not exist.
0ce1b118 32335
b383017d 32336@item ENODEV
fc320d37 32337@var{pathname} refers to a device, pipe, named pipe or socket.
0ce1b118 32338
b383017d 32339@item EROFS
fc320d37 32340@var{pathname} refers to a file on a read-only filesystem and
0ce1b118
CV
32341write access was requested.
32342
b383017d 32343@item EFAULT
fc320d37 32344@var{pathname} is an invalid pointer value.
0ce1b118 32345
b383017d 32346@item ENOSPC
0ce1b118
CV
32347No space on device to create the file.
32348
b383017d 32349@item EMFILE
0ce1b118
CV
32350The process already has the maximum number of files open.
32351
b383017d 32352@item ENFILE
0ce1b118
CV
32353The limit on the total number of files open on the system
32354has been reached.
32355
b383017d 32356@item EINTR
0ce1b118
CV
32357The call was interrupted by the user.
32358@end table
32359
fc320d37
SL
32360@end table
32361
0ce1b118
CV
32362@node close
32363@unnumberedsubsubsec close
32364@cindex close, file-i/o system call
32365
fc320d37
SL
32366@table @asis
32367@item Synopsis:
0ce1b118 32368@smallexample
0ce1b118 32369int close(int fd);
fc320d37 32370@end smallexample
0ce1b118 32371
fc320d37
SL
32372@item Request:
32373@samp{Fclose,@var{fd}}
0ce1b118 32374
fc320d37
SL
32375@item Return value:
32376@code{close} returns zero on success, or -1 if an error occurred.
0ce1b118 32377
fc320d37 32378@item Errors:
0ce1b118
CV
32379
32380@table @code
b383017d 32381@item EBADF
fc320d37 32382@var{fd} isn't a valid open file descriptor.
0ce1b118 32383
b383017d 32384@item EINTR
0ce1b118
CV
32385The call was interrupted by the user.
32386@end table
32387
fc320d37
SL
32388@end table
32389
0ce1b118
CV
32390@node read
32391@unnumberedsubsubsec read
32392@cindex read, file-i/o system call
32393
fc320d37
SL
32394@table @asis
32395@item Synopsis:
0ce1b118 32396@smallexample
0ce1b118 32397int read(int fd, void *buf, unsigned int count);
fc320d37 32398@end smallexample
0ce1b118 32399
fc320d37
SL
32400@item Request:
32401@samp{Fread,@var{fd},@var{bufptr},@var{count}}
0ce1b118 32402
fc320d37 32403@item Return value:
0ce1b118
CV
32404On success, the number of bytes read is returned.
32405Zero indicates end of file. If count is zero, read
b383017d 32406returns zero as well. On error, -1 is returned.
0ce1b118 32407
fc320d37 32408@item Errors:
0ce1b118
CV
32409
32410@table @code
b383017d 32411@item EBADF
fc320d37 32412@var{fd} is not a valid file descriptor or is not open for
0ce1b118
CV
32413reading.
32414
b383017d 32415@item EFAULT
fc320d37 32416@var{bufptr} is an invalid pointer value.
0ce1b118 32417
b383017d 32418@item EINTR
0ce1b118
CV
32419The call was interrupted by the user.
32420@end table
32421
fc320d37
SL
32422@end table
32423
0ce1b118
CV
32424@node write
32425@unnumberedsubsubsec write
32426@cindex write, file-i/o system call
32427
fc320d37
SL
32428@table @asis
32429@item Synopsis:
0ce1b118 32430@smallexample
0ce1b118 32431int write(int fd, const void *buf, unsigned int count);
fc320d37 32432@end smallexample
0ce1b118 32433
fc320d37
SL
32434@item Request:
32435@samp{Fwrite,@var{fd},@var{bufptr},@var{count}}
0ce1b118 32436
fc320d37 32437@item Return value:
0ce1b118
CV
32438On success, the number of bytes written are returned.
32439Zero indicates nothing was written. On error, -1
32440is returned.
32441
fc320d37 32442@item Errors:
0ce1b118
CV
32443
32444@table @code
b383017d 32445@item EBADF
fc320d37 32446@var{fd} is not a valid file descriptor or is not open for
0ce1b118
CV
32447writing.
32448
b383017d 32449@item EFAULT
fc320d37 32450@var{bufptr} is an invalid pointer value.
0ce1b118 32451
b383017d 32452@item EFBIG
0ce1b118 32453An attempt was made to write a file that exceeds the
db2e3e2e 32454host-specific maximum file size allowed.
0ce1b118 32455
b383017d 32456@item ENOSPC
0ce1b118
CV
32457No space on device to write the data.
32458
b383017d 32459@item EINTR
0ce1b118
CV
32460The call was interrupted by the user.
32461@end table
32462
fc320d37
SL
32463@end table
32464
0ce1b118
CV
32465@node lseek
32466@unnumberedsubsubsec lseek
32467@cindex lseek, file-i/o system call
32468
fc320d37
SL
32469@table @asis
32470@item Synopsis:
0ce1b118 32471@smallexample
0ce1b118 32472long lseek (int fd, long offset, int flag);
0ce1b118
CV
32473@end smallexample
32474
fc320d37
SL
32475@item Request:
32476@samp{Flseek,@var{fd},@var{offset},@var{flag}}
32477
32478@var{flag} is one of:
0ce1b118
CV
32479
32480@table @code
b383017d 32481@item SEEK_SET
fc320d37 32482The offset is set to @var{offset} bytes.
0ce1b118 32483
b383017d 32484@item SEEK_CUR
fc320d37 32485The offset is set to its current location plus @var{offset}
0ce1b118
CV
32486bytes.
32487
b383017d 32488@item SEEK_END
fc320d37 32489The offset is set to the size of the file plus @var{offset}
0ce1b118
CV
32490bytes.
32491@end table
32492
fc320d37 32493@item Return value:
0ce1b118
CV
32494On success, the resulting unsigned offset in bytes from
32495the beginning of the file is returned. Otherwise, a
32496value of -1 is returned.
32497
fc320d37 32498@item Errors:
0ce1b118
CV
32499
32500@table @code
b383017d 32501@item EBADF
fc320d37 32502@var{fd} is not a valid open file descriptor.
0ce1b118 32503
b383017d 32504@item ESPIPE
fc320d37 32505@var{fd} is associated with the @value{GDBN} console.
0ce1b118 32506
b383017d 32507@item EINVAL
fc320d37 32508@var{flag} is not a proper value.
0ce1b118 32509
b383017d 32510@item EINTR
0ce1b118
CV
32511The call was interrupted by the user.
32512@end table
32513
fc320d37
SL
32514@end table
32515
0ce1b118
CV
32516@node rename
32517@unnumberedsubsubsec rename
32518@cindex rename, file-i/o system call
32519
fc320d37
SL
32520@table @asis
32521@item Synopsis:
0ce1b118 32522@smallexample
0ce1b118 32523int rename(const char *oldpath, const char *newpath);
fc320d37 32524@end smallexample
0ce1b118 32525
fc320d37
SL
32526@item Request:
32527@samp{Frename,@var{oldpathptr}/@var{len},@var{newpathptr}/@var{len}}
0ce1b118 32528
fc320d37 32529@item Return value:
0ce1b118
CV
32530On success, zero is returned. On error, -1 is returned.
32531
fc320d37 32532@item Errors:
0ce1b118
CV
32533
32534@table @code
b383017d 32535@item EISDIR
fc320d37 32536@var{newpath} is an existing directory, but @var{oldpath} is not a
0ce1b118
CV
32537directory.
32538
b383017d 32539@item EEXIST
fc320d37 32540@var{newpath} is a non-empty directory.
0ce1b118 32541
b383017d 32542@item EBUSY
fc320d37 32543@var{oldpath} or @var{newpath} is a directory that is in use by some
0ce1b118
CV
32544process.
32545
b383017d 32546@item EINVAL
0ce1b118
CV
32547An attempt was made to make a directory a subdirectory
32548of itself.
32549
b383017d 32550@item ENOTDIR
fc320d37
SL
32551A component used as a directory in @var{oldpath} or new
32552path is not a directory. Or @var{oldpath} is a directory
32553and @var{newpath} exists but is not a directory.
0ce1b118 32554
b383017d 32555@item EFAULT
fc320d37 32556@var{oldpathptr} or @var{newpathptr} are invalid pointer values.
0ce1b118 32557
b383017d 32558@item EACCES
0ce1b118
CV
32559No access to the file or the path of the file.
32560
32561@item ENAMETOOLONG
b383017d 32562
fc320d37 32563@var{oldpath} or @var{newpath} was too long.
0ce1b118 32564
b383017d 32565@item ENOENT
fc320d37 32566A directory component in @var{oldpath} or @var{newpath} does not exist.
0ce1b118 32567
b383017d 32568@item EROFS
0ce1b118
CV
32569The file is on a read-only filesystem.
32570
b383017d 32571@item ENOSPC
0ce1b118
CV
32572The device containing the file has no room for the new
32573directory entry.
32574
b383017d 32575@item EINTR
0ce1b118
CV
32576The call was interrupted by the user.
32577@end table
32578
fc320d37
SL
32579@end table
32580
0ce1b118
CV
32581@node unlink
32582@unnumberedsubsubsec unlink
32583@cindex unlink, file-i/o system call
32584
fc320d37
SL
32585@table @asis
32586@item Synopsis:
0ce1b118 32587@smallexample
0ce1b118 32588int unlink(const char *pathname);
fc320d37 32589@end smallexample
0ce1b118 32590
fc320d37
SL
32591@item Request:
32592@samp{Funlink,@var{pathnameptr}/@var{len}}
0ce1b118 32593
fc320d37 32594@item Return value:
0ce1b118
CV
32595On success, zero is returned. On error, -1 is returned.
32596
fc320d37 32597@item Errors:
0ce1b118
CV
32598
32599@table @code
b383017d 32600@item EACCES
0ce1b118
CV
32601No access to the file or the path of the file.
32602
b383017d 32603@item EPERM
0ce1b118
CV
32604The system does not allow unlinking of directories.
32605
b383017d 32606@item EBUSY
fc320d37 32607The file @var{pathname} cannot be unlinked because it's
0ce1b118
CV
32608being used by another process.
32609
b383017d 32610@item EFAULT
fc320d37 32611@var{pathnameptr} is an invalid pointer value.
0ce1b118
CV
32612
32613@item ENAMETOOLONG
fc320d37 32614@var{pathname} was too long.
0ce1b118 32615
b383017d 32616@item ENOENT
fc320d37 32617A directory component in @var{pathname} does not exist.
0ce1b118 32618
b383017d 32619@item ENOTDIR
0ce1b118
CV
32620A component of the path is not a directory.
32621
b383017d 32622@item EROFS
0ce1b118
CV
32623The file is on a read-only filesystem.
32624
b383017d 32625@item EINTR
0ce1b118
CV
32626The call was interrupted by the user.
32627@end table
32628
fc320d37
SL
32629@end table
32630
0ce1b118
CV
32631@node stat/fstat
32632@unnumberedsubsubsec stat/fstat
32633@cindex fstat, file-i/o system call
32634@cindex stat, file-i/o system call
32635
fc320d37
SL
32636@table @asis
32637@item Synopsis:
0ce1b118 32638@smallexample
0ce1b118
CV
32639int stat(const char *pathname, struct stat *buf);
32640int fstat(int fd, struct stat *buf);
fc320d37 32641@end smallexample
0ce1b118 32642
fc320d37
SL
32643@item Request:
32644@samp{Fstat,@var{pathnameptr}/@var{len},@var{bufptr}}@*
32645@samp{Ffstat,@var{fd},@var{bufptr}}
0ce1b118 32646
fc320d37 32647@item Return value:
0ce1b118
CV
32648On success, zero is returned. On error, -1 is returned.
32649
fc320d37 32650@item Errors:
0ce1b118
CV
32651
32652@table @code
b383017d 32653@item EBADF
fc320d37 32654@var{fd} is not a valid open file.
0ce1b118 32655
b383017d 32656@item ENOENT
fc320d37 32657A directory component in @var{pathname} does not exist or the
0ce1b118
CV
32658path is an empty string.
32659
b383017d 32660@item ENOTDIR
0ce1b118
CV
32661A component of the path is not a directory.
32662
b383017d 32663@item EFAULT
fc320d37 32664@var{pathnameptr} is an invalid pointer value.
0ce1b118 32665
b383017d 32666@item EACCES
0ce1b118
CV
32667No access to the file or the path of the file.
32668
32669@item ENAMETOOLONG
fc320d37 32670@var{pathname} was too long.
0ce1b118 32671
b383017d 32672@item EINTR
0ce1b118
CV
32673The call was interrupted by the user.
32674@end table
32675
fc320d37
SL
32676@end table
32677
0ce1b118
CV
32678@node gettimeofday
32679@unnumberedsubsubsec gettimeofday
32680@cindex gettimeofday, file-i/o system call
32681
fc320d37
SL
32682@table @asis
32683@item Synopsis:
0ce1b118 32684@smallexample
0ce1b118 32685int gettimeofday(struct timeval *tv, void *tz);
fc320d37 32686@end smallexample
0ce1b118 32687
fc320d37
SL
32688@item Request:
32689@samp{Fgettimeofday,@var{tvptr},@var{tzptr}}
0ce1b118 32690
fc320d37 32691@item Return value:
0ce1b118
CV
32692On success, 0 is returned, -1 otherwise.
32693
fc320d37 32694@item Errors:
0ce1b118
CV
32695
32696@table @code
b383017d 32697@item EINVAL
fc320d37 32698@var{tz} is a non-NULL pointer.
0ce1b118 32699
b383017d 32700@item EFAULT
fc320d37
SL
32701@var{tvptr} and/or @var{tzptr} is an invalid pointer value.
32702@end table
32703
0ce1b118
CV
32704@end table
32705
32706@node isatty
32707@unnumberedsubsubsec isatty
32708@cindex isatty, file-i/o system call
32709
fc320d37
SL
32710@table @asis
32711@item Synopsis:
0ce1b118 32712@smallexample
0ce1b118 32713int isatty(int fd);
fc320d37 32714@end smallexample
0ce1b118 32715
fc320d37
SL
32716@item Request:
32717@samp{Fisatty,@var{fd}}
0ce1b118 32718
fc320d37
SL
32719@item Return value:
32720Returns 1 if @var{fd} refers to the @value{GDBN} console, 0 otherwise.
0ce1b118 32721
fc320d37 32722@item Errors:
0ce1b118
CV
32723
32724@table @code
b383017d 32725@item EINTR
0ce1b118
CV
32726The call was interrupted by the user.
32727@end table
32728
fc320d37
SL
32729@end table
32730
32731Note that the @code{isatty} call is treated as a special case: it returns
327321 to the target if the file descriptor is attached
32733to the @value{GDBN} console, 0 otherwise. Implementing through system calls
32734would require implementing @code{ioctl} and would be more complex than
32735needed.
32736
32737
0ce1b118
CV
32738@node system
32739@unnumberedsubsubsec system
32740@cindex system, file-i/o system call
32741
fc320d37
SL
32742@table @asis
32743@item Synopsis:
0ce1b118 32744@smallexample
0ce1b118 32745int system(const char *command);
fc320d37 32746@end smallexample
0ce1b118 32747
fc320d37
SL
32748@item Request:
32749@samp{Fsystem,@var{commandptr}/@var{len}}
0ce1b118 32750
fc320d37 32751@item Return value:
5600ea19
NS
32752If @var{len} is zero, the return value indicates whether a shell is
32753available. A zero return value indicates a shell is not available.
32754For non-zero @var{len}, the value returned is -1 on error and the
32755return status of the command otherwise. Only the exit status of the
32756command is returned, which is extracted from the host's @code{system}
32757return value by calling @code{WEXITSTATUS(retval)}. In case
32758@file{/bin/sh} could not be executed, 127 is returned.
0ce1b118 32759
fc320d37 32760@item Errors:
0ce1b118
CV
32761
32762@table @code
b383017d 32763@item EINTR
0ce1b118
CV
32764The call was interrupted by the user.
32765@end table
32766
fc320d37
SL
32767@end table
32768
32769@value{GDBN} takes over the full task of calling the necessary host calls
32770to perform the @code{system} call. The return value of @code{system} on
32771the host is simplified before it's returned
32772to the target. Any termination signal information from the child process
32773is discarded, and the return value consists
32774entirely of the exit status of the called command.
32775
32776Due to security concerns, the @code{system} call is by default refused
32777by @value{GDBN}. The user has to allow this call explicitly with the
32778@code{set remote system-call-allowed 1} command.
32779
32780@table @code
32781@item set remote system-call-allowed
32782@kindex set remote system-call-allowed
32783Control whether to allow the @code{system} calls in the File I/O
32784protocol for the remote target. The default is zero (disabled).
32785
32786@item show remote system-call-allowed
32787@kindex show remote system-call-allowed
32788Show whether the @code{system} calls are allowed in the File I/O
32789protocol.
32790@end table
32791
db2e3e2e
BW
32792@node Protocol-specific Representation of Datatypes
32793@subsection Protocol-specific Representation of Datatypes
32794@cindex protocol-specific representation of datatypes, in file-i/o protocol
0ce1b118
CV
32795
32796@menu
79a6e687
BW
32797* Integral Datatypes::
32798* Pointer Values::
32799* Memory Transfer::
0ce1b118
CV
32800* struct stat::
32801* struct timeval::
32802@end menu
32803
79a6e687
BW
32804@node Integral Datatypes
32805@unnumberedsubsubsec Integral Datatypes
0ce1b118
CV
32806@cindex integral datatypes, in file-i/o protocol
32807
fc320d37
SL
32808The integral datatypes used in the system calls are @code{int},
32809@code{unsigned int}, @code{long}, @code{unsigned long},
32810@code{mode_t}, and @code{time_t}.
0ce1b118 32811
fc320d37 32812@code{int}, @code{unsigned int}, @code{mode_t} and @code{time_t} are
0ce1b118
CV
32813implemented as 32 bit values in this protocol.
32814
fc320d37 32815@code{long} and @code{unsigned long} are implemented as 64 bit types.
b383017d 32816
0ce1b118
CV
32817@xref{Limits}, for corresponding MIN and MAX values (similar to those
32818in @file{limits.h}) to allow range checking on host and target.
32819
32820@code{time_t} datatypes are defined as seconds since the Epoch.
32821
32822All integral datatypes transferred as part of a memory read or write of a
32823structured datatype e.g.@: a @code{struct stat} have to be given in big endian
32824byte order.
32825
79a6e687
BW
32826@node Pointer Values
32827@unnumberedsubsubsec Pointer Values
0ce1b118
CV
32828@cindex pointer values, in file-i/o protocol
32829
32830Pointers to target data are transmitted as they are. An exception
32831is made for pointers to buffers for which the length isn't
32832transmitted as part of the function call, namely strings. Strings
32833are transmitted as a pointer/length pair, both as hex values, e.g.@:
32834
32835@smallexample
32836@code{1aaf/12}
32837@end smallexample
32838
32839@noindent
32840which is a pointer to data of length 18 bytes at position 0x1aaf.
32841The length is defined as the full string length in bytes, including
fc320d37
SL
32842the trailing null byte. For example, the string @code{"hello world"}
32843at address 0x123456 is transmitted as
0ce1b118
CV
32844
32845@smallexample
fc320d37 32846@code{123456/d}
0ce1b118
CV
32847@end smallexample
32848
79a6e687
BW
32849@node Memory Transfer
32850@unnumberedsubsubsec Memory Transfer
fc320d37
SL
32851@cindex memory transfer, in file-i/o protocol
32852
32853Structured data which is transferred using a memory read or write (for
db2e3e2e 32854example, a @code{struct stat}) is expected to be in a protocol-specific format
fc320d37
SL
32855with all scalar multibyte datatypes being big endian. Translation to
32856this representation needs to be done both by the target before the @code{F}
32857packet is sent, and by @value{GDBN} before
32858it transfers memory to the target. Transferred pointers to structured
32859data should point to the already-coerced data at any time.
0ce1b118 32860
0ce1b118
CV
32861
32862@node struct stat
32863@unnumberedsubsubsec struct stat
32864@cindex struct stat, in file-i/o protocol
32865
fc320d37
SL
32866The buffer of type @code{struct stat} used by the target and @value{GDBN}
32867is defined as follows:
0ce1b118
CV
32868
32869@smallexample
32870struct stat @{
32871 unsigned int st_dev; /* device */
32872 unsigned int st_ino; /* inode */
32873 mode_t st_mode; /* protection */
32874 unsigned int st_nlink; /* number of hard links */
32875 unsigned int st_uid; /* user ID of owner */
32876 unsigned int st_gid; /* group ID of owner */
32877 unsigned int st_rdev; /* device type (if inode device) */
32878 unsigned long st_size; /* total size, in bytes */
32879 unsigned long st_blksize; /* blocksize for filesystem I/O */
32880 unsigned long st_blocks; /* number of blocks allocated */
32881 time_t st_atime; /* time of last access */
32882 time_t st_mtime; /* time of last modification */
32883 time_t st_ctime; /* time of last change */
32884@};
32885@end smallexample
32886
fc320d37 32887The integral datatypes conform to the definitions given in the
79a6e687 32888appropriate section (see @ref{Integral Datatypes}, for details) so this
0ce1b118
CV
32889structure is of size 64 bytes.
32890
32891The values of several fields have a restricted meaning and/or
32892range of values.
32893
fc320d37 32894@table @code
0ce1b118 32895
fc320d37
SL
32896@item st_dev
32897A value of 0 represents a file, 1 the console.
0ce1b118 32898
fc320d37
SL
32899@item st_ino
32900No valid meaning for the target. Transmitted unchanged.
0ce1b118 32901
fc320d37
SL
32902@item st_mode
32903Valid mode bits are described in @ref{Constants}. Any other
32904bits have currently no meaning for the target.
0ce1b118 32905
fc320d37
SL
32906@item st_uid
32907@itemx st_gid
32908@itemx st_rdev
32909No valid meaning for the target. Transmitted unchanged.
0ce1b118 32910
fc320d37
SL
32911@item st_atime
32912@itemx st_mtime
32913@itemx st_ctime
32914These values have a host and file system dependent
32915accuracy. Especially on Windows hosts, the file system may not
32916support exact timing values.
32917@end table
0ce1b118 32918
fc320d37
SL
32919The target gets a @code{struct stat} of the above representation and is
32920responsible for coercing it to the target representation before
0ce1b118
CV
32921continuing.
32922
fc320d37
SL
32923Note that due to size differences between the host, target, and protocol
32924representations of @code{struct stat} members, these members could eventually
0ce1b118
CV
32925get truncated on the target.
32926
32927@node struct timeval
32928@unnumberedsubsubsec struct timeval
32929@cindex struct timeval, in file-i/o protocol
32930
fc320d37 32931The buffer of type @code{struct timeval} used by the File-I/O protocol
0ce1b118
CV
32932is defined as follows:
32933
32934@smallexample
b383017d 32935struct timeval @{
0ce1b118
CV
32936 time_t tv_sec; /* second */
32937 long tv_usec; /* microsecond */
32938@};
32939@end smallexample
32940
fc320d37 32941The integral datatypes conform to the definitions given in the
79a6e687 32942appropriate section (see @ref{Integral Datatypes}, for details) so this
0ce1b118
CV
32943structure is of size 8 bytes.
32944
32945@node Constants
32946@subsection Constants
32947@cindex constants, in file-i/o protocol
32948
32949The following values are used for the constants inside of the
fc320d37 32950protocol. @value{GDBN} and target are responsible for translating these
0ce1b118
CV
32951values before and after the call as needed.
32952
32953@menu
79a6e687
BW
32954* Open Flags::
32955* mode_t Values::
32956* Errno Values::
32957* Lseek Flags::
0ce1b118
CV
32958* Limits::
32959@end menu
32960
79a6e687
BW
32961@node Open Flags
32962@unnumberedsubsubsec Open Flags
0ce1b118
CV
32963@cindex open flags, in file-i/o protocol
32964
32965All values are given in hexadecimal representation.
32966
32967@smallexample
32968 O_RDONLY 0x0
32969 O_WRONLY 0x1
32970 O_RDWR 0x2
32971 O_APPEND 0x8
32972 O_CREAT 0x200
32973 O_TRUNC 0x400
32974 O_EXCL 0x800
32975@end smallexample
32976
79a6e687
BW
32977@node mode_t Values
32978@unnumberedsubsubsec mode_t Values
0ce1b118
CV
32979@cindex mode_t values, in file-i/o protocol
32980
32981All values are given in octal representation.
32982
32983@smallexample
32984 S_IFREG 0100000
32985 S_IFDIR 040000
32986 S_IRUSR 0400
32987 S_IWUSR 0200
32988 S_IXUSR 0100
32989 S_IRGRP 040
32990 S_IWGRP 020
32991 S_IXGRP 010
32992 S_IROTH 04
32993 S_IWOTH 02
32994 S_IXOTH 01
32995@end smallexample
32996
79a6e687
BW
32997@node Errno Values
32998@unnumberedsubsubsec Errno Values
0ce1b118
CV
32999@cindex errno values, in file-i/o protocol
33000
33001All values are given in decimal representation.
33002
33003@smallexample
33004 EPERM 1
33005 ENOENT 2
33006 EINTR 4
33007 EBADF 9
33008 EACCES 13
33009 EFAULT 14
33010 EBUSY 16
33011 EEXIST 17
33012 ENODEV 19
33013 ENOTDIR 20
33014 EISDIR 21
33015 EINVAL 22
33016 ENFILE 23
33017 EMFILE 24
33018 EFBIG 27
33019 ENOSPC 28
33020 ESPIPE 29
33021 EROFS 30
33022 ENAMETOOLONG 91
33023 EUNKNOWN 9999
33024@end smallexample
33025
fc320d37 33026 @code{EUNKNOWN} is used as a fallback error value if a host system returns
0ce1b118
CV
33027 any error value not in the list of supported error numbers.
33028
79a6e687
BW
33029@node Lseek Flags
33030@unnumberedsubsubsec Lseek Flags
0ce1b118
CV
33031@cindex lseek flags, in file-i/o protocol
33032
33033@smallexample
33034 SEEK_SET 0
33035 SEEK_CUR 1
33036 SEEK_END 2
33037@end smallexample
33038
33039@node Limits
33040@unnumberedsubsubsec Limits
33041@cindex limits, in file-i/o protocol
33042
33043All values are given in decimal representation.
33044
33045@smallexample
33046 INT_MIN -2147483648
33047 INT_MAX 2147483647
33048 UINT_MAX 4294967295
33049 LONG_MIN -9223372036854775808
33050 LONG_MAX 9223372036854775807
33051 ULONG_MAX 18446744073709551615
33052@end smallexample
33053
33054@node File-I/O Examples
33055@subsection File-I/O Examples
33056@cindex file-i/o examples
33057
33058Example sequence of a write call, file descriptor 3, buffer is at target
33059address 0x1234, 6 bytes should be written:
33060
33061@smallexample
33062<- @code{Fwrite,3,1234,6}
33063@emph{request memory read from target}
33064-> @code{m1234,6}
33065<- XXXXXX
33066@emph{return "6 bytes written"}
33067-> @code{F6}
33068@end smallexample
33069
33070Example sequence of a read call, file descriptor 3, buffer is at target
33071address 0x1234, 6 bytes should be read:
33072
33073@smallexample
33074<- @code{Fread,3,1234,6}
33075@emph{request memory write to target}
33076-> @code{X1234,6:XXXXXX}
33077@emph{return "6 bytes read"}
33078-> @code{F6}
33079@end smallexample
33080
33081Example sequence of a read call, call fails on the host due to invalid
fc320d37 33082file descriptor (@code{EBADF}):
0ce1b118
CV
33083
33084@smallexample
33085<- @code{Fread,3,1234,6}
33086-> @code{F-1,9}
33087@end smallexample
33088
c8aa23ab 33089Example sequence of a read call, user presses @kbd{Ctrl-c} before syscall on
0ce1b118
CV
33090host is called:
33091
33092@smallexample
33093<- @code{Fread,3,1234,6}
33094-> @code{F-1,4,C}
33095<- @code{T02}
33096@end smallexample
33097
c8aa23ab 33098Example sequence of a read call, user presses @kbd{Ctrl-c} after syscall on
0ce1b118
CV
33099host is called:
33100
33101@smallexample
33102<- @code{Fread,3,1234,6}
33103-> @code{X1234,6:XXXXXX}
33104<- @code{T02}
33105@end smallexample
33106
cfa9d6d9
DJ
33107@node Library List Format
33108@section Library List Format
33109@cindex library list format, remote protocol
33110
33111On some platforms, a dynamic loader (e.g.@: @file{ld.so}) runs in the
33112same process as your application to manage libraries. In this case,
33113@value{GDBN} can use the loader's symbol table and normal memory
33114operations to maintain a list of shared libraries. On other
33115platforms, the operating system manages loaded libraries.
33116@value{GDBN} can not retrieve the list of currently loaded libraries
33117through memory operations, so it uses the @samp{qXfer:libraries:read}
33118packet (@pxref{qXfer library list read}) instead. The remote stub
33119queries the target's operating system and reports which libraries
33120are loaded.
33121
33122The @samp{qXfer:libraries:read} packet returns an XML document which
33123lists loaded libraries and their offsets. Each library has an
1fddbabb
PA
33124associated name and one or more segment or section base addresses,
33125which report where the library was loaded in memory.
33126
33127For the common case of libraries that are fully linked binaries, the
33128library should have a list of segments. If the target supports
33129dynamic linking of a relocatable object file, its library XML element
33130should instead include a list of allocated sections. The segment or
33131section bases are start addresses, not relocation offsets; they do not
33132depend on the library's link-time base addresses.
cfa9d6d9 33133
9cceb671
DJ
33134@value{GDBN} must be linked with the Expat library to support XML
33135library lists. @xref{Expat}.
33136
cfa9d6d9
DJ
33137A simple memory map, with one loaded library relocated by a single
33138offset, looks like this:
33139
33140@smallexample
33141<library-list>
33142 <library name="/lib/libc.so.6">
33143 <segment address="0x10000000"/>
33144 </library>
33145</library-list>
33146@end smallexample
33147
1fddbabb
PA
33148Another simple memory map, with one loaded library with three
33149allocated sections (.text, .data, .bss), looks like this:
33150
33151@smallexample
33152<library-list>
33153 <library name="sharedlib.o">
33154 <section address="0x10000000"/>
33155 <section address="0x20000000"/>
33156 <section address="0x30000000"/>
33157 </library>
33158</library-list>
33159@end smallexample
33160
cfa9d6d9
DJ
33161The format of a library list is described by this DTD:
33162
33163@smallexample
33164<!-- library-list: Root element with versioning -->
33165<!ELEMENT library-list (library)*>
33166<!ATTLIST library-list version CDATA #FIXED "1.0">
1fddbabb 33167<!ELEMENT library (segment*, section*)>
cfa9d6d9
DJ
33168<!ATTLIST library name CDATA #REQUIRED>
33169<!ELEMENT segment EMPTY>
33170<!ATTLIST segment address CDATA #REQUIRED>
1fddbabb
PA
33171<!ELEMENT section EMPTY>
33172<!ATTLIST section address CDATA #REQUIRED>
cfa9d6d9
DJ
33173@end smallexample
33174
1fddbabb
PA
33175In addition, segments and section descriptors cannot be mixed within a
33176single library element, and you must supply at least one segment or
33177section for each library.
33178
79a6e687
BW
33179@node Memory Map Format
33180@section Memory Map Format
68437a39
DJ
33181@cindex memory map format
33182
33183To be able to write into flash memory, @value{GDBN} needs to obtain a
33184memory map from the target. This section describes the format of the
33185memory map.
33186
33187The memory map is obtained using the @samp{qXfer:memory-map:read}
33188(@pxref{qXfer memory map read}) packet and is an XML document that
9cceb671
DJ
33189lists memory regions.
33190
33191@value{GDBN} must be linked with the Expat library to support XML
33192memory maps. @xref{Expat}.
33193
33194The top-level structure of the document is shown below:
68437a39
DJ
33195
33196@smallexample
33197<?xml version="1.0"?>
33198<!DOCTYPE memory-map
33199 PUBLIC "+//IDN gnu.org//DTD GDB Memory Map V1.0//EN"
33200 "http://sourceware.org/gdb/gdb-memory-map.dtd">
33201<memory-map>
33202 region...
33203</memory-map>
33204@end smallexample
33205
33206Each region can be either:
33207
33208@itemize
33209
33210@item
33211A region of RAM starting at @var{addr} and extending for @var{length}
33212bytes from there:
33213
33214@smallexample
33215<memory type="ram" start="@var{addr}" length="@var{length}"/>
33216@end smallexample
33217
33218
33219@item
33220A region of read-only memory:
33221
33222@smallexample
33223<memory type="rom" start="@var{addr}" length="@var{length}"/>
33224@end smallexample
33225
33226
33227@item
33228A region of flash memory, with erasure blocks @var{blocksize}
33229bytes in length:
33230
33231@smallexample
33232<memory type="flash" start="@var{addr}" length="@var{length}">
33233 <property name="blocksize">@var{blocksize}</property>
33234</memory>
33235@end smallexample
33236
33237@end itemize
33238
33239Regions must not overlap. @value{GDBN} assumes that areas of memory not covered
33240by the memory map are RAM, and uses the ordinary @samp{M} and @samp{X}
33241packets to write to addresses in such ranges.
33242
33243The formal DTD for memory map format is given below:
33244
33245@smallexample
33246<!-- ................................................... -->
33247<!-- Memory Map XML DTD ................................ -->
33248<!-- File: memory-map.dtd .............................. -->
33249<!-- .................................... .............. -->
33250<!-- memory-map.dtd -->
33251<!-- memory-map: Root element with versioning -->
33252<!ELEMENT memory-map (memory | property)>
33253<!ATTLIST memory-map version CDATA #FIXED "1.0.0">
33254<!ELEMENT memory (property)>
33255<!-- memory: Specifies a memory region,
33256 and its type, or device. -->
33257<!ATTLIST memory type CDATA #REQUIRED
33258 start CDATA #REQUIRED
33259 length CDATA #REQUIRED
33260 device CDATA #IMPLIED>
33261<!-- property: Generic attribute tag -->
33262<!ELEMENT property (#PCDATA | property)*>
33263<!ATTLIST property name CDATA #REQUIRED>
33264@end smallexample
33265
dc146f7c
VP
33266@node Thread List Format
33267@section Thread List Format
33268@cindex thread list format
33269
33270To efficiently update the list of threads and their attributes,
33271@value{GDBN} issues the @samp{qXfer:threads:read} packet
33272(@pxref{qXfer threads read}) and obtains the XML document with
33273the following structure:
33274
33275@smallexample
33276<?xml version="1.0"?>
33277<threads>
33278 <thread id="id" core="0">
33279 ... description ...
33280 </thread>
33281</threads>
33282@end smallexample
33283
33284Each @samp{thread} element must have the @samp{id} attribute that
33285identifies the thread (@pxref{thread-id syntax}). The
33286@samp{core} attribute, if present, specifies which processor core
33287the thread was last executing on. The content of the of @samp{thread}
33288element is interpreted as human-readable auxilliary information.
33289
f418dd93
DJ
33290@include agentexpr.texi
33291
00bf0b85
SS
33292@node Trace File Format
33293@appendix Trace File Format
33294@cindex trace file format
33295
33296The trace file comes in three parts: a header, a textual description
33297section, and a trace frame section with binary data.
33298
33299The header has the form @code{\x7fTRACE0\n}. The first byte is
33300@code{0x7f} so as to indicate that the file contains binary data,
33301while the @code{0} is a version number that may have different values
33302in the future.
33303
33304The description section consists of multiple lines of @sc{ascii} text
33305separated by newline characters (@code{0xa}). The lines may include a
33306variety of optional descriptive or context-setting information, such
33307as tracepoint definitions or register set size. @value{GDBN} will
33308ignore any line that it does not recognize. An empty line marks the end
33309of this section.
33310
33311@c FIXME add some specific types of data
33312
33313The trace frame section consists of a number of consecutive frames.
33314Each frame begins with a two-byte tracepoint number, followed by a
33315four-byte size giving the amount of data in the frame. The data in
33316the frame consists of a number of blocks, each introduced by a
33317character indicating its type (at least register, memory, and trace
33318state variable). The data in this section is raw binary, not a
33319hexadecimal or other encoding; its endianness matches the target's
33320endianness.
33321
33322@c FIXME bi-arch may require endianness/arch info in description section
33323
33324@table @code
33325@item R @var{bytes}
33326Register block. The number and ordering of bytes matches that of a
33327@code{g} packet in the remote protocol. Note that these are the
33328actual bytes, in target order and @value{GDBN} register order, not a
33329hexadecimal encoding.
33330
33331@item M @var{address} @var{length} @var{bytes}...
33332Memory block. This is a contiguous block of memory, at the 8-byte
33333address @var{address}, with a 2-byte length @var{length}, followed by
33334@var{length} bytes.
33335
33336@item V @var{number} @var{value}
33337Trace state variable block. This records the 8-byte signed value
33338@var{value} of trace state variable numbered @var{number}.
33339
33340@end table
33341
33342Future enhancements of the trace file format may include additional types
33343of blocks.
33344
23181151
DJ
33345@node Target Descriptions
33346@appendix Target Descriptions
33347@cindex target descriptions
33348
33349@strong{Warning:} target descriptions are still under active development,
33350and the contents and format may change between @value{GDBN} releases.
33351The format is expected to stabilize in the future.
33352
33353One of the challenges of using @value{GDBN} to debug embedded systems
33354is that there are so many minor variants of each processor
33355architecture in use. It is common practice for vendors to start with
33356a standard processor core --- ARM, PowerPC, or MIPS, for example ---
33357and then make changes to adapt it to a particular market niche. Some
33358architectures have hundreds of variants, available from dozens of
33359vendors. This leads to a number of problems:
33360
33361@itemize @bullet
33362@item
33363With so many different customized processors, it is difficult for
33364the @value{GDBN} maintainers to keep up with the changes.
33365@item
33366Since individual variants may have short lifetimes or limited
33367audiences, it may not be worthwhile to carry information about every
33368variant in the @value{GDBN} source tree.
33369@item
33370When @value{GDBN} does support the architecture of the embedded system
33371at hand, the task of finding the correct architecture name to give the
33372@command{set architecture} command can be error-prone.
33373@end itemize
33374
33375To address these problems, the @value{GDBN} remote protocol allows a
33376target system to not only identify itself to @value{GDBN}, but to
33377actually describe its own features. This lets @value{GDBN} support
33378processor variants it has never seen before --- to the extent that the
33379descriptions are accurate, and that @value{GDBN} understands them.
33380
9cceb671
DJ
33381@value{GDBN} must be linked with the Expat library to support XML
33382target descriptions. @xref{Expat}.
123dc839 33383
23181151
DJ
33384@menu
33385* Retrieving Descriptions:: How descriptions are fetched from a target.
33386* Target Description Format:: The contents of a target description.
123dc839
DJ
33387* Predefined Target Types:: Standard types available for target
33388 descriptions.
33389* Standard Target Features:: Features @value{GDBN} knows about.
23181151
DJ
33390@end menu
33391
33392@node Retrieving Descriptions
33393@section Retrieving Descriptions
33394
33395Target descriptions can be read from the target automatically, or
33396specified by the user manually. The default behavior is to read the
33397description from the target. @value{GDBN} retrieves it via the remote
33398protocol using @samp{qXfer} requests (@pxref{General Query Packets,
33399qXfer}). The @var{annex} in the @samp{qXfer} packet will be
33400@samp{target.xml}. The contents of the @samp{target.xml} annex are an
33401XML document, of the form described in @ref{Target Description
33402Format}.
33403
33404Alternatively, you can specify a file to read for the target description.
33405If a file is set, the target will not be queried. The commands to
33406specify a file are:
33407
33408@table @code
33409@cindex set tdesc filename
33410@item set tdesc filename @var{path}
33411Read the target description from @var{path}.
33412
33413@cindex unset tdesc filename
33414@item unset tdesc filename
33415Do not read the XML target description from a file. @value{GDBN}
33416will use the description supplied by the current target.
33417
33418@cindex show tdesc filename
33419@item show tdesc filename
33420Show the filename to read for a target description, if any.
33421@end table
33422
33423
33424@node Target Description Format
33425@section Target Description Format
33426@cindex target descriptions, XML format
33427
33428A target description annex is an @uref{http://www.w3.org/XML/, XML}
33429document which complies with the Document Type Definition provided in
33430the @value{GDBN} sources in @file{gdb/features/gdb-target.dtd}. This
33431means you can use generally available tools like @command{xmllint} to
33432check that your feature descriptions are well-formed and valid.
33433However, to help people unfamiliar with XML write descriptions for
33434their targets, we also describe the grammar here.
33435
123dc839
DJ
33436Target descriptions can identify the architecture of the remote target
33437and (for some architectures) provide information about custom register
08d16641
PA
33438sets. They can also identify the OS ABI of the remote target.
33439@value{GDBN} can use this information to autoconfigure for your
123dc839 33440target, or to warn you if you connect to an unsupported target.
23181151
DJ
33441
33442Here is a simple target description:
33443
123dc839 33444@smallexample
1780a0ed 33445<target version="1.0">
23181151
DJ
33446 <architecture>i386:x86-64</architecture>
33447</target>
123dc839 33448@end smallexample
23181151
DJ
33449
33450@noindent
33451This minimal description only says that the target uses
33452the x86-64 architecture.
33453
123dc839
DJ
33454A target description has the following overall form, with [ ] marking
33455optional elements and @dots{} marking repeatable elements. The elements
33456are explained further below.
23181151 33457
123dc839 33458@smallexample
23181151
DJ
33459<?xml version="1.0"?>
33460<!DOCTYPE target SYSTEM "gdb-target.dtd">
1780a0ed 33461<target version="1.0">
123dc839 33462 @r{[}@var{architecture}@r{]}
08d16641 33463 @r{[}@var{osabi}@r{]}
e35359c5 33464 @r{[}@var{compatible}@r{]}
123dc839 33465 @r{[}@var{feature}@dots{}@r{]}
23181151 33466</target>
123dc839 33467@end smallexample
23181151
DJ
33468
33469@noindent
33470The description is generally insensitive to whitespace and line
33471breaks, under the usual common-sense rules. The XML version
33472declaration and document type declaration can generally be omitted
33473(@value{GDBN} does not require them), but specifying them may be
1780a0ed
DJ
33474useful for XML validation tools. The @samp{version} attribute for
33475@samp{<target>} may also be omitted, but we recommend
33476including it; if future versions of @value{GDBN} use an incompatible
33477revision of @file{gdb-target.dtd}, they will detect and report
33478the version mismatch.
23181151 33479
108546a0
DJ
33480@subsection Inclusion
33481@cindex target descriptions, inclusion
33482@cindex XInclude
33483@ifnotinfo
33484@cindex <xi:include>
33485@end ifnotinfo
33486
33487It can sometimes be valuable to split a target description up into
33488several different annexes, either for organizational purposes, or to
33489share files between different possible target descriptions. You can
33490divide a description into multiple files by replacing any element of
33491the target description with an inclusion directive of the form:
33492
123dc839 33493@smallexample
108546a0 33494<xi:include href="@var{document}"/>
123dc839 33495@end smallexample
108546a0
DJ
33496
33497@noindent
33498When @value{GDBN} encounters an element of this form, it will retrieve
33499the named XML @var{document}, and replace the inclusion directive with
33500the contents of that document. If the current description was read
33501using @samp{qXfer}, then so will be the included document;
33502@var{document} will be interpreted as the name of an annex. If the
33503current description was read from a file, @value{GDBN} will look for
33504@var{document} as a file in the same directory where it found the
33505original description.
33506
123dc839
DJ
33507@subsection Architecture
33508@cindex <architecture>
33509
33510An @samp{<architecture>} element has this form:
33511
33512@smallexample
33513 <architecture>@var{arch}</architecture>
33514@end smallexample
33515
e35359c5
UW
33516@var{arch} is one of the architectures from the set accepted by
33517@code{set architecture} (@pxref{Targets, ,Specifying a Debugging Target}).
123dc839 33518
08d16641
PA
33519@subsection OS ABI
33520@cindex @code{<osabi>}
33521
33522This optional field was introduced in @value{GDBN} version 7.0.
33523Previous versions of @value{GDBN} ignore it.
33524
33525An @samp{<osabi>} element has this form:
33526
33527@smallexample
33528 <osabi>@var{abi-name}</osabi>
33529@end smallexample
33530
33531@var{abi-name} is an OS ABI name from the same selection accepted by
33532@w{@code{set osabi}} (@pxref{ABI, ,Configuring the Current ABI}).
33533
e35359c5
UW
33534@subsection Compatible Architecture
33535@cindex @code{<compatible>}
33536
33537This optional field was introduced in @value{GDBN} version 7.0.
33538Previous versions of @value{GDBN} ignore it.
33539
33540A @samp{<compatible>} element has this form:
33541
33542@smallexample
33543 <compatible>@var{arch}</compatible>
33544@end smallexample
33545
33546@var{arch} is one of the architectures from the set accepted by
33547@code{set architecture} (@pxref{Targets, ,Specifying a Debugging Target}).
33548
33549A @samp{<compatible>} element is used to specify that the target
33550is able to run binaries in some other than the main target architecture
33551given by the @samp{<architecture>} element. For example, on the
33552Cell Broadband Engine, the main architecture is @code{powerpc:common}
33553or @code{powerpc:common64}, but the system is able to run binaries
33554in the @code{spu} architecture as well. The way to describe this
33555capability with @samp{<compatible>} is as follows:
33556
33557@smallexample
33558 <architecture>powerpc:common</architecture>
33559 <compatible>spu</compatible>
33560@end smallexample
33561
123dc839
DJ
33562@subsection Features
33563@cindex <feature>
33564
33565Each @samp{<feature>} describes some logical portion of the target
33566system. Features are currently used to describe available CPU
33567registers and the types of their contents. A @samp{<feature>} element
33568has this form:
33569
33570@smallexample
33571<feature name="@var{name}">
33572 @r{[}@var{type}@dots{}@r{]}
33573 @var{reg}@dots{}
33574</feature>
33575@end smallexample
33576
33577@noindent
33578Each feature's name should be unique within the description. The name
33579of a feature does not matter unless @value{GDBN} has some special
33580knowledge of the contents of that feature; if it does, the feature
33581should have its standard name. @xref{Standard Target Features}.
33582
33583@subsection Types
33584
33585Any register's value is a collection of bits which @value{GDBN} must
33586interpret. The default interpretation is a two's complement integer,
33587but other types can be requested by name in the register description.
33588Some predefined types are provided by @value{GDBN} (@pxref{Predefined
33589Target Types}), and the description can define additional composite types.
33590
33591Each type element must have an @samp{id} attribute, which gives
33592a unique (within the containing @samp{<feature>}) name to the type.
33593Types must be defined before they are used.
33594
33595@cindex <vector>
33596Some targets offer vector registers, which can be treated as arrays
33597of scalar elements. These types are written as @samp{<vector>} elements,
33598specifying the array element type, @var{type}, and the number of elements,
33599@var{count}:
33600
33601@smallexample
33602<vector id="@var{id}" type="@var{type}" count="@var{count}"/>
33603@end smallexample
33604
33605@cindex <union>
33606If a register's value is usefully viewed in multiple ways, define it
33607with a union type containing the useful representations. The
33608@samp{<union>} element contains one or more @samp{<field>} elements,
33609each of which has a @var{name} and a @var{type}:
33610
33611@smallexample
33612<union id="@var{id}">
33613 <field name="@var{name}" type="@var{type}"/>
33614 @dots{}
33615</union>
33616@end smallexample
33617
f5dff777
DJ
33618@cindex <struct>
33619If a register's value is composed from several separate values, define
33620it with a structure type. There are two forms of the @samp{<struct>}
33621element; a @samp{<struct>} element must either contain only bitfields
33622or contain no bitfields. If the structure contains only bitfields,
33623its total size in bytes must be specified, each bitfield must have an
33624explicit start and end, and bitfields are automatically assigned an
33625integer type. The field's @var{start} should be less than or
33626equal to its @var{end}, and zero represents the least significant bit.
33627
33628@smallexample
33629<struct id="@var{id}" size="@var{size}">
33630 <field name="@var{name}" start="@var{start}" end="@var{end}"/>
33631 @dots{}
33632</struct>
33633@end smallexample
33634
33635If the structure contains no bitfields, then each field has an
33636explicit type, and no implicit padding is added.
33637
33638@smallexample
33639<struct id="@var{id}">
33640 <field name="@var{name}" type="@var{type}"/>
33641 @dots{}
33642</struct>
33643@end smallexample
33644
33645@cindex <flags>
33646If a register's value is a series of single-bit flags, define it with
33647a flags type. The @samp{<flags>} element has an explicit @var{size}
33648and contains one or more @samp{<field>} elements. Each field has a
33649@var{name}, a @var{start}, and an @var{end}. Only single-bit flags
33650are supported.
33651
33652@smallexample
33653<flags id="@var{id}" size="@var{size}">
33654 <field name="@var{name}" start="@var{start}" end="@var{end}"/>
33655 @dots{}
33656</flags>
33657@end smallexample
33658
123dc839
DJ
33659@subsection Registers
33660@cindex <reg>
33661
33662Each register is represented as an element with this form:
33663
33664@smallexample
33665<reg name="@var{name}"
33666 bitsize="@var{size}"
33667 @r{[}regnum="@var{num}"@r{]}
33668 @r{[}save-restore="@var{save-restore}"@r{]}
33669 @r{[}type="@var{type}"@r{]}
33670 @r{[}group="@var{group}"@r{]}/>
33671@end smallexample
33672
33673@noindent
33674The components are as follows:
33675
33676@table @var
33677
33678@item name
33679The register's name; it must be unique within the target description.
33680
33681@item bitsize
33682The register's size, in bits.
33683
33684@item regnum
33685The register's number. If omitted, a register's number is one greater
33686than that of the previous register (either in the current feature or in
33687a preceeding feature); the first register in the target description
33688defaults to zero. This register number is used to read or write
33689the register; e.g.@: it is used in the remote @code{p} and @code{P}
33690packets, and registers appear in the @code{g} and @code{G} packets
33691in order of increasing register number.
33692
33693@item save-restore
33694Whether the register should be preserved across inferior function
33695calls; this must be either @code{yes} or @code{no}. The default is
33696@code{yes}, which is appropriate for most registers except for
33697some system control registers; this is not related to the target's
33698ABI.
33699
33700@item type
33701The type of the register. @var{type} may be a predefined type, a type
33702defined in the current feature, or one of the special types @code{int}
33703and @code{float}. @code{int} is an integer type of the correct size
33704for @var{bitsize}, and @code{float} is a floating point type (in the
33705architecture's normal floating point format) of the correct size for
33706@var{bitsize}. The default is @code{int}.
33707
33708@item group
33709The register group to which this register belongs. @var{group} must
33710be either @code{general}, @code{float}, or @code{vector}. If no
33711@var{group} is specified, @value{GDBN} will not display the register
33712in @code{info registers}.
33713
33714@end table
33715
33716@node Predefined Target Types
33717@section Predefined Target Types
33718@cindex target descriptions, predefined types
33719
33720Type definitions in the self-description can build up composite types
33721from basic building blocks, but can not define fundamental types. Instead,
33722standard identifiers are provided by @value{GDBN} for the fundamental
33723types. The currently supported types are:
33724
33725@table @code
33726
33727@item int8
33728@itemx int16
33729@itemx int32
33730@itemx int64
7cc46491 33731@itemx int128
123dc839
DJ
33732Signed integer types holding the specified number of bits.
33733
33734@item uint8
33735@itemx uint16
33736@itemx uint32
33737@itemx uint64
7cc46491 33738@itemx uint128
123dc839
DJ
33739Unsigned integer types holding the specified number of bits.
33740
33741@item code_ptr
33742@itemx data_ptr
33743Pointers to unspecified code and data. The program counter and
33744any dedicated return address register may be marked as code
33745pointers; printing a code pointer converts it into a symbolic
33746address. The stack pointer and any dedicated address registers
33747may be marked as data pointers.
33748
6e3bbd1a
PB
33749@item ieee_single
33750Single precision IEEE floating point.
33751
33752@item ieee_double
33753Double precision IEEE floating point.
33754
123dc839
DJ
33755@item arm_fpa_ext
33756The 12-byte extended precision format used by ARM FPA registers.
33757
075b51b7
L
33758@item i387_ext
33759The 10-byte extended precision format used by x87 registers.
33760
33761@item i386_eflags
3376232bit @sc{eflags} register used by x86.
33763
33764@item i386_mxcsr
3376532bit @sc{mxcsr} register used by x86.
33766
123dc839
DJ
33767@end table
33768
33769@node Standard Target Features
33770@section Standard Target Features
33771@cindex target descriptions, standard features
33772
33773A target description must contain either no registers or all the
33774target's registers. If the description contains no registers, then
33775@value{GDBN} will assume a default register layout, selected based on
33776the architecture. If the description contains any registers, the
33777default layout will not be used; the standard registers must be
33778described in the target description, in such a way that @value{GDBN}
33779can recognize them.
33780
33781This is accomplished by giving specific names to feature elements
33782which contain standard registers. @value{GDBN} will look for features
33783with those names and verify that they contain the expected registers;
33784if any known feature is missing required registers, or if any required
33785feature is missing, @value{GDBN} will reject the target
33786description. You can add additional registers to any of the
33787standard features --- @value{GDBN} will display them just as if
33788they were added to an unrecognized feature.
33789
33790This section lists the known features and their expected contents.
33791Sample XML documents for these features are included in the
33792@value{GDBN} source tree, in the directory @file{gdb/features}.
33793
33794Names recognized by @value{GDBN} should include the name of the
33795company or organization which selected the name, and the overall
33796architecture to which the feature applies; so e.g.@: the feature
33797containing ARM core registers is named @samp{org.gnu.gdb.arm.core}.
33798
ff6f572f
DJ
33799The names of registers are not case sensitive for the purpose
33800of recognizing standard features, but @value{GDBN} will only display
33801registers using the capitalization used in the description.
33802
e9c17194
VP
33803@menu
33804* ARM Features::
3bb8d5c3 33805* i386 Features::
1e26b4f8 33806* MIPS Features::
e9c17194 33807* M68K Features::
1e26b4f8 33808* PowerPC Features::
e9c17194
VP
33809@end menu
33810
33811
33812@node ARM Features
123dc839
DJ
33813@subsection ARM Features
33814@cindex target descriptions, ARM features
33815
33816The @samp{org.gnu.gdb.arm.core} feature is required for ARM targets.
33817It should contain registers @samp{r0} through @samp{r13}, @samp{sp},
33818@samp{lr}, @samp{pc}, and @samp{cpsr}.
33819
33820The @samp{org.gnu.gdb.arm.fpa} feature is optional. If present, it
33821should contain registers @samp{f0} through @samp{f7} and @samp{fps}.
33822
ff6f572f
DJ
33823The @samp{org.gnu.gdb.xscale.iwmmxt} feature is optional. If present,
33824it should contain at least registers @samp{wR0} through @samp{wR15} and
33825@samp{wCGR0} through @samp{wCGR3}. The @samp{wCID}, @samp{wCon},
33826@samp{wCSSF}, and @samp{wCASF} registers are optional.
23181151 33827
58d6951d
DJ
33828The @samp{org.gnu.gdb.arm.vfp} feature is optional. If present, it
33829should contain at least registers @samp{d0} through @samp{d15}. If
33830they are present, @samp{d16} through @samp{d31} should also be included.
33831@value{GDBN} will synthesize the single-precision registers from
33832halves of the double-precision registers.
33833
33834The @samp{org.gnu.gdb.arm.neon} feature is optional. It does not
33835need to contain registers; it instructs @value{GDBN} to display the
33836VFP double-precision registers as vectors and to synthesize the
33837quad-precision registers from pairs of double-precision registers.
33838If this feature is present, @samp{org.gnu.gdb.arm.vfp} must also
33839be present and include 32 double-precision registers.
33840
3bb8d5c3
L
33841@node i386 Features
33842@subsection i386 Features
33843@cindex target descriptions, i386 features
33844
33845The @samp{org.gnu.gdb.i386.core} feature is required for i386/amd64
33846targets. It should describe the following registers:
33847
33848@itemize @minus
33849@item
33850@samp{eax} through @samp{edi} plus @samp{eip} for i386
33851@item
33852@samp{rax} through @samp{r15} plus @samp{rip} for amd64
33853@item
33854@samp{eflags}, @samp{cs}, @samp{ss}, @samp{ds}, @samp{es},
33855@samp{fs}, @samp{gs}
33856@item
33857@samp{st0} through @samp{st7}
33858@item
33859@samp{fctrl}, @samp{fstat}, @samp{ftag}, @samp{fiseg}, @samp{fioff},
33860@samp{foseg}, @samp{fooff} and @samp{fop}
33861@end itemize
33862
33863The register sets may be different, depending on the target.
33864
3a13a53b 33865The @samp{org.gnu.gdb.i386.sse} feature is optional. It should
3bb8d5c3
L
33866describe registers:
33867
33868@itemize @minus
33869@item
33870@samp{xmm0} through @samp{xmm7} for i386
33871@item
33872@samp{xmm0} through @samp{xmm15} for amd64
33873@item
33874@samp{mxcsr}
33875@end itemize
33876
3a13a53b
L
33877The @samp{org.gnu.gdb.i386.avx} feature is optional and requires the
33878@samp{org.gnu.gdb.i386.sse} feature. It should
f68eb612
L
33879describe the upper 128 bits of @sc{ymm} registers:
33880
33881@itemize @minus
33882@item
33883@samp{ymm0h} through @samp{ymm7h} for i386
33884@item
33885@samp{ymm0h} through @samp{ymm15h} for amd64
33886@item
33887@end itemize
33888
3bb8d5c3
L
33889The @samp{org.gnu.gdb.i386.linux} feature is optional. It should
33890describe a single register, @samp{orig_eax}.
33891
1e26b4f8 33892@node MIPS Features
f8b73d13
DJ
33893@subsection MIPS Features
33894@cindex target descriptions, MIPS features
33895
33896The @samp{org.gnu.gdb.mips.cpu} feature is required for MIPS targets.
33897It should contain registers @samp{r0} through @samp{r31}, @samp{lo},
33898@samp{hi}, and @samp{pc}. They may be 32-bit or 64-bit depending
33899on the target.
33900
33901The @samp{org.gnu.gdb.mips.cp0} feature is also required. It should
33902contain at least the @samp{status}, @samp{badvaddr}, and @samp{cause}
33903registers. They may be 32-bit or 64-bit depending on the target.
33904
33905The @samp{org.gnu.gdb.mips.fpu} feature is currently required, though
33906it may be optional in a future version of @value{GDBN}. It should
33907contain registers @samp{f0} through @samp{f31}, @samp{fcsr}, and
33908@samp{fir}. They may be 32-bit or 64-bit depending on the target.
33909
822b6570
DJ
33910The @samp{org.gnu.gdb.mips.linux} feature is optional. It should
33911contain a single register, @samp{restart}, which is used by the
33912Linux kernel to control restartable syscalls.
33913
e9c17194
VP
33914@node M68K Features
33915@subsection M68K Features
33916@cindex target descriptions, M68K features
33917
33918@table @code
33919@item @samp{org.gnu.gdb.m68k.core}
33920@itemx @samp{org.gnu.gdb.coldfire.core}
33921@itemx @samp{org.gnu.gdb.fido.core}
33922One of those features must be always present.
249e1128 33923The feature that is present determines which flavor of m68k is
e9c17194
VP
33924used. The feature that is present should contain registers
33925@samp{d0} through @samp{d7}, @samp{a0} through @samp{a5}, @samp{fp},
33926@samp{sp}, @samp{ps} and @samp{pc}.
33927
33928@item @samp{org.gnu.gdb.coldfire.fp}
33929This feature is optional. If present, it should contain registers
33930@samp{fp0} through @samp{fp7}, @samp{fpcontrol}, @samp{fpstatus} and
33931@samp{fpiaddr}.
33932@end table
33933
1e26b4f8 33934@node PowerPC Features
7cc46491
DJ
33935@subsection PowerPC Features
33936@cindex target descriptions, PowerPC features
33937
33938The @samp{org.gnu.gdb.power.core} feature is required for PowerPC
33939targets. It should contain registers @samp{r0} through @samp{r31},
33940@samp{pc}, @samp{msr}, @samp{cr}, @samp{lr}, @samp{ctr}, and
33941@samp{xer}. They may be 32-bit or 64-bit depending on the target.
33942
33943The @samp{org.gnu.gdb.power.fpu} feature is optional. It should
33944contain registers @samp{f0} through @samp{f31} and @samp{fpscr}.
33945
33946The @samp{org.gnu.gdb.power.altivec} feature is optional. It should
33947contain registers @samp{vr0} through @samp{vr31}, @samp{vscr},
33948and @samp{vrsave}.
33949
677c5bb1
LM
33950The @samp{org.gnu.gdb.power.vsx} feature is optional. It should
33951contain registers @samp{vs0h} through @samp{vs31h}. @value{GDBN}
33952will combine these registers with the floating point registers
33953(@samp{f0} through @samp{f31}) and the altivec registers (@samp{vr0}
aeac0ff9 33954through @samp{vr31}) to present the 128-bit wide registers @samp{vs0}
677c5bb1
LM
33955through @samp{vs63}, the set of vector registers for POWER7.
33956
7cc46491
DJ
33957The @samp{org.gnu.gdb.power.spe} feature is optional. It should
33958contain registers @samp{ev0h} through @samp{ev31h}, @samp{acc}, and
33959@samp{spefscr}. SPE targets should provide 32-bit registers in
33960@samp{org.gnu.gdb.power.core} and provide the upper halves in
33961@samp{ev0h} through @samp{ev31h}. @value{GDBN} will combine
33962these to present registers @samp{ev0} through @samp{ev31} to the
33963user.
33964
07e059b5
VP
33965@node Operating System Information
33966@appendix Operating System Information
33967@cindex operating system information
33968
33969@menu
33970* Process list::
33971@end menu
33972
33973Users of @value{GDBN} often wish to obtain information about the state of
33974the operating system running on the target---for example the list of
33975processes, or the list of open files. This section describes the
33976mechanism that makes it possible. This mechanism is similar to the
33977target features mechanism (@pxref{Target Descriptions}), but focuses
33978on a different aspect of target.
33979
33980Operating system information is retrived from the target via the
33981remote protocol, using @samp{qXfer} requests (@pxref{qXfer osdata
33982read}). The object name in the request should be @samp{osdata}, and
33983the @var{annex} identifies the data to be fetched.
33984
33985@node Process list
33986@appendixsection Process list
33987@cindex operating system information, process list
33988
33989When requesting the process list, the @var{annex} field in the
33990@samp{qXfer} request should be @samp{processes}. The returned data is
33991an XML document. The formal syntax of this document is defined in
33992@file{gdb/features/osdata.dtd}.
33993
33994An example document is:
33995
33996@smallexample
33997<?xml version="1.0"?>
33998<!DOCTYPE target SYSTEM "osdata.dtd">
33999<osdata type="processes">
34000 <item>
34001 <column name="pid">1</column>
34002 <column name="user">root</column>
34003 <column name="command">/sbin/init</column>
dc146f7c 34004 <column name="cores">1,2,3</column>
07e059b5
VP
34005 </item>
34006</osdata>
34007@end smallexample
34008
34009Each item should include a column whose name is @samp{pid}. The value
34010of that column should identify the process on the target. The
34011@samp{user} and @samp{command} columns are optional, and will be
dc146f7c
VP
34012displayed by @value{GDBN}. The @samp{cores} column, if present,
34013should contain a comma-separated list of cores that this process
34014is running on. Target may provide additional columns,
07e059b5
VP
34015which @value{GDBN} currently ignores.
34016
aab4e0ec 34017@include gpl.texi
eb12ee30 34018
2154891a 34019@raisesections
6826cf00 34020@include fdl.texi
2154891a 34021@lowersections
6826cf00 34022
6d2ebf8b 34023@node Index
c906108c
SS
34024@unnumbered Index
34025
34026@printindex cp
34027
34028@tex
34029% I think something like @colophon should be in texinfo. In the
34030% meantime:
34031\long\def\colophon{\hbox to0pt{}\vfill
34032\centerline{The body of this manual is set in}
34033\centerline{\fontname\tenrm,}
34034\centerline{with headings in {\bf\fontname\tenbf}}
34035\centerline{and examples in {\tt\fontname\tentt}.}
34036\centerline{{\it\fontname\tenit\/},}
34037\centerline{{\bf\fontname\tenbf}, and}
34038\centerline{{\sl\fontname\tensl\/}}
34039\centerline{are used for emphasis.}\vfill}
34040\page\colophon
34041% Blame: doc@cygnus.com, 1991.
34042@end tex
34043
c906108c 34044@bye
This page took 4.019032 seconds and 4 git commands to generate.