Add moxie-rtems support
[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 52Permission is granted to copy, distribute and/or modify this document
4f5d9f07 53under the terms of the GNU Free Documentation License, Version 1.3 or
e9c75b65 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
6aecb9c2
JB
217Support for D is partial. For information on D, see
218@ref{D,,D}.
219
cce74817 220@cindex Modula-2
e632838e
AC
221Support for Modula-2 is partial. For information on Modula-2, see
222@ref{Modula-2,,Modula-2}.
c906108c 223
cce74817
JM
224@cindex Pascal
225Debugging Pascal programs which use sets, subranges, file variables, or
226nested functions does not currently work. @value{GDBN} does not support
227entering expressions, printing values, or similar features using Pascal
228syntax.
c906108c 229
c906108c
SS
230@cindex Fortran
231@value{GDBN} can be used to debug programs written in Fortran, although
53a5351d 232it may be necessary to refer to some variables with a trailing
cce74817 233underscore.
c906108c 234
b37303ee
AF
235@value{GDBN} can be used to debug programs written in Objective-C,
236using either the Apple/NeXT or the GNU Objective-C runtime.
237
c906108c
SS
238@menu
239* Free Software:: Freely redistributable software
240* Contributors:: Contributors to GDB
241@end menu
242
6d2ebf8b 243@node Free Software
79a6e687 244@unnumberedsec Free Software
c906108c 245
5d161b24 246@value{GDBN} is @dfn{free software}, protected by the @sc{gnu}
c906108c
SS
247General Public License
248(GPL). The GPL gives you the freedom to copy or adapt a licensed
249program---but every person getting a copy also gets with it the
250freedom to modify that copy (which means that they must get access to
251the source code), and the freedom to distribute further copies.
252Typical software companies use copyrights to limit your freedoms; the
253Free Software Foundation uses the GPL to preserve these freedoms.
254
255Fundamentally, the General Public License is a license which says that
256you have these freedoms and that you cannot take these freedoms away
257from anyone else.
258
2666264b 259@unnumberedsec Free Software Needs Free Documentation
959acfd1
EZ
260
261The biggest deficiency in the free software community today is not in
262the software---it is the lack of good free documentation that we can
263include with the free software. Many of our most important
264programs do not come with free reference manuals and free introductory
265texts. Documentation is an essential part of any software package;
266when an important free software package does not come with a free
267manual and a free tutorial, that is a major gap. We have many such
268gaps today.
269
270Consider Perl, for instance. The tutorial manuals that people
271normally use are non-free. How did this come about? Because the
272authors of those manuals published them with restrictive terms---no
273copying, no modification, source files not available---which exclude
274them from the free software world.
275
276That wasn't the first time this sort of thing happened, and it was far
277from the last. Many times we have heard a GNU user eagerly describe a
278manual that he is writing, his intended contribution to the community,
279only to learn that he had ruined everything by signing a publication
280contract to make it non-free.
281
282Free documentation, like free software, is a matter of freedom, not
283price. The problem with the non-free manual is not that publishers
284charge a price for printed copies---that in itself is fine. (The Free
285Software Foundation sells printed copies of manuals, too.) The
286problem is the restrictions on the use of the manual. Free manuals
287are available in source code form, and give you permission to copy and
288modify. Non-free manuals do not allow this.
289
290The criteria of freedom for a free manual are roughly the same as for
291free software. Redistribution (including the normal kinds of
292commercial redistribution) must be permitted, so that the manual can
293accompany every copy of the program, both on-line and on paper.
294
295Permission for modification of the technical content is crucial too.
296When people modify the software, adding or changing features, if they
297are conscientious they will change the manual too---so they can
298provide accurate and clear documentation for the modified program. A
299manual that leaves you no choice but to write a new manual to document
300a changed version of the program is not really available to our
301community.
302
303Some kinds of limits on the way modification is handled are
304acceptable. For example, requirements to preserve the original
305author's copyright notice, the distribution terms, or the list of
306authors, are ok. It is also no problem to require modified versions
307to include notice that they were modified. Even entire sections that
308may not be deleted or changed are acceptable, as long as they deal
309with nontechnical topics (like this one). These kinds of restrictions
310are acceptable because they don't obstruct the community's normal use
311of the manual.
312
313However, it must be possible to modify all the @emph{technical}
314content of the manual, and then distribute the result in all the usual
315media, through all the usual channels. Otherwise, the restrictions
316obstruct the use of the manual, it is not free, and we need another
317manual to replace it.
318
319Please spread the word about this issue. Our community continues to
320lose manuals to proprietary publishing. If we spread the word that
321free software needs free reference manuals and free tutorials, perhaps
322the next person who wants to contribute by writing documentation will
323realize, before it is too late, that only free manuals contribute to
324the free software community.
325
326If you are writing documentation, please insist on publishing it under
327the GNU Free Documentation License or another free documentation
328license. Remember that this decision requires your approval---you
329don't have to let the publisher decide. Some commercial publishers
330will use a free license if you insist, but they will not propose the
331option; it is up to you to raise the issue and say firmly that this is
332what you want. If the publisher you are dealing with refuses, please
333try other publishers. If you're not sure whether a proposed license
42584a72 334is free, write to @email{licensing@@gnu.org}.
959acfd1
EZ
335
336You can encourage commercial publishers to sell more free, copylefted
337manuals and tutorials by buying them, and particularly by buying
338copies from the publishers that paid for their writing or for major
339improvements. Meanwhile, try to avoid buying non-free documentation
340at all. Check the distribution terms of a manual before you buy it,
341and insist that whoever seeks your business must respect your freedom.
72c9928d
EZ
342Check the history of the book, and try to reward the publishers that
343have paid or pay the authors to work on it.
959acfd1
EZ
344
345The Free Software Foundation maintains a list of free documentation
346published by other publishers, at
347@url{http://www.fsf.org/doc/other-free-books.html}.
348
6d2ebf8b 349@node Contributors
96a2c332
SS
350@unnumberedsec Contributors to @value{GDBN}
351
352Richard Stallman was the original author of @value{GDBN}, and of many
353other @sc{gnu} programs. Many others have contributed to its
354development. This section attempts to credit major contributors. One
355of the virtues of free software is that everyone is free to contribute
356to it; with regret, we cannot actually acknowledge everyone here. The
357file @file{ChangeLog} in the @value{GDBN} distribution approximates a
c906108c
SS
358blow-by-blow account.
359
360Changes much prior to version 2.0 are lost in the mists of time.
361
362@quotation
363@emph{Plea:} Additions to this section are particularly welcome. If you
364or your friends (or enemies, to be evenhanded) have been unfairly
365omitted from this list, we would like to add your names!
366@end quotation
367
368So that they may not regard their many labors as thankless, we
369particularly thank those who shepherded @value{GDBN} through major
370releases:
7ba3cf9c 371Andrew Cagney (releases 6.3, 6.2, 6.1, 6.0, 5.3, 5.2, 5.1 and 5.0);
c906108c
SS
372Jim Blandy (release 4.18);
373Jason Molenda (release 4.17);
374Stan Shebs (release 4.14);
375Fred Fish (releases 4.16, 4.15, 4.13, 4.12, 4.11, 4.10, and 4.9);
376Stu Grossman and John Gilmore (releases 4.8, 4.7, 4.6, 4.5, and 4.4);
377John Gilmore (releases 4.3, 4.2, 4.1, 4.0, and 3.9);
378Jim Kingdon (releases 3.5, 3.4, and 3.3);
379and Randy Smith (releases 3.2, 3.1, and 3.0).
380
381Richard Stallman, assisted at various times by Peter TerMaat, Chris
382Hanson, and Richard Mlynarik, handled releases through 2.8.
383
b37052ae
EZ
384Michael Tiemann is the author of most of the @sc{gnu} C@t{++} support
385in @value{GDBN}, with significant additional contributions from Per
386Bothner and Daniel Berlin. James Clark wrote the @sc{gnu} C@t{++}
387demangler. Early work on C@t{++} was by Peter TerMaat (who also did
388much general update work leading to release 3.0).
c906108c 389
b37052ae 390@value{GDBN} uses the BFD subroutine library to examine multiple
c906108c
SS
391object-file formats; BFD was a joint project of David V.
392Henkel-Wallace, Rich Pixley, Steve Chamberlain, and John Gilmore.
393
394David Johnson wrote the original COFF support; Pace Willison did
395the original support for encapsulated COFF.
396
0179ffac 397Brent Benson of Harris Computer Systems contributed DWARF 2 support.
c906108c
SS
398
399Adam de Boor and Bradley Davis contributed the ISI Optimum V support.
400Per Bothner, Noboyuki Hikichi, and Alessandro Forin contributed MIPS
401support.
402Jean-Daniel Fekete contributed Sun 386i support.
403Chris Hanson improved the HP9000 support.
404Noboyuki Hikichi and Tomoyuki Hasei contributed Sony/News OS 3 support.
405David Johnson contributed Encore Umax support.
406Jyrki Kuoppala contributed Altos 3068 support.
407Jeff Law contributed HP PA and SOM support.
408Keith Packard contributed NS32K support.
409Doug Rabson contributed Acorn Risc Machine support.
410Bob Rusk contributed Harris Nighthawk CX-UX support.
411Chris Smith contributed Convex support (and Fortran debugging).
412Jonathan Stone contributed Pyramid support.
413Michael Tiemann contributed SPARC support.
414Tim Tucker contributed support for the Gould NP1 and Gould Powernode.
415Pace Willison contributed Intel 386 support.
416Jay Vosburgh contributed Symmetry support.
a37295f9 417Marko Mlinar contributed OpenRISC 1000 support.
c906108c 418
1104b9e7 419Andreas Schwab contributed M68K @sc{gnu}/Linux support.
c906108c
SS
420
421Rich Schaefer and Peter Schauer helped with support of SunOS shared
422libraries.
423
424Jay Fenlason and Roland McGrath ensured that @value{GDBN} and GAS agree
425about several machine instruction sets.
426
427Patrick Duval, Ted Goldstein, Vikram Koka and Glenn Engel helped develop
428remote debugging. Intel Corporation, Wind River Systems, AMD, and ARM
429contributed remote debugging modules for the i960, VxWorks, A29K UDI,
430and RDI targets, respectively.
431
432Brian Fox is the author of the readline libraries providing
433command-line editing and command history.
434
7a292a7a
SS
435Andrew Beers of SUNY Buffalo wrote the language-switching code, the
436Modula-2 support, and contributed the Languages chapter of this manual.
c906108c 437
5d161b24 438Fred Fish wrote most of the support for Unix System Vr4.
b37052ae 439He also enhanced the command-completion support to cover C@t{++} overloaded
c906108c 440symbols.
c906108c 441
f24c5e49
KI
442Hitachi America (now Renesas America), Ltd. sponsored the support for
443H8/300, H8/500, and Super-H processors.
c906108c
SS
444
445NEC sponsored the support for the v850, Vr4xxx, and Vr5xxx processors.
446
f24c5e49
KI
447Mitsubishi (now Renesas) sponsored the support for D10V, D30V, and M32R/D
448processors.
c906108c
SS
449
450Toshiba sponsored the support for the TX39 Mips processor.
451
452Matsushita sponsored the support for the MN10200 and MN10300 processors.
453
96a2c332 454Fujitsu sponsored the support for SPARClite and FR30 processors.
c906108c
SS
455
456Kung Hsu, Jeff Law, and Rick Sladkey added support for hardware
457watchpoints.
458
459Michael Snyder added support for tracepoints.
460
461Stu Grossman wrote gdbserver.
462
463Jim Kingdon, Peter Schauer, Ian Taylor, and Stu Grossman made
96a2c332 464nearly innumerable bug fixes and cleanups throughout @value{GDBN}.
c906108c
SS
465
466The following people at the Hewlett-Packard Company contributed
467support for the PA-RISC 2.0 architecture, HP-UX 10.20, 10.30, and 11.0
b37052ae 468(narrow mode), HP's implementation of kernel threads, HP's aC@t{++}
d0d5df6f
AC
469compiler, and the Text User Interface (nee Terminal User Interface):
470Ben Krepp, Richard Title, John Bishop, Susan Macchia, Kathy Mann,
471Satish Pai, India Paul, Steve Rehrauer, and Elena Zannoni. Kim Haase
472provided HP-specific information in this manual.
c906108c 473
b37052ae
EZ
474DJ Delorie ported @value{GDBN} to MS-DOS, for the DJGPP project.
475Robert Hoehne made significant contributions to the DJGPP port.
476
96a2c332
SS
477Cygnus Solutions has sponsored @value{GDBN} maintenance and much of its
478development since 1991. Cygnus engineers who have worked on @value{GDBN}
2df3850c
JM
479fulltime include Mark Alexander, Jim Blandy, Per Bothner, Kevin
480Buettner, Edith Epstein, Chris Faylor, Fred Fish, Martin Hunt, Jim
481Ingham, John Gilmore, Stu Grossman, Kung Hsu, Jim Kingdon, John Metzler,
482Fernando Nasser, Geoffrey Noer, Dawn Perchik, Rich Pixley, Zdenek
483Radouch, Keith Seitz, Stan Shebs, David Taylor, and Elena Zannoni. In
484addition, Dave Brolley, Ian Carmichael, Steve Chamberlain, Nick Clifton,
485JT Conklin, Stan Cox, DJ Delorie, Ulrich Drepper, Frank Eigler, Doug
486Evans, Sean Fagan, David Henkel-Wallace, Richard Henderson, Jeff
487Holcomb, Jeff Law, Jim Lemke, Tom Lord, Bob Manson, Michael Meissner,
488Jason Merrill, Catherine Moore, Drew Moseley, Ken Raeburn, Gavin
489Romig-Koch, Rob Savoye, Jamie Smith, Mike Stump, Ian Taylor, Angela
490Thomas, Michael Tiemann, Tom Tromey, Ron Unrau, Jim Wilson, and David
491Zuhn have made contributions both large and small.
c906108c 492
ffed4509
AC
493Andrew Cagney, Fernando Nasser, and Elena Zannoni, while working for
494Cygnus Solutions, implemented the original @sc{gdb/mi} interface.
495
e2e0bcd1
JB
496Jim Blandy added support for preprocessor macros, while working for Red
497Hat.
c906108c 498
a9967aef
AC
499Andrew Cagney designed @value{GDBN}'s architecture vector. Many
500people including Andrew Cagney, Stephane Carrez, Randolph Chung, Nick
501Duffek, Richard Henderson, Mark Kettenis, Grace Sainsbury, Kei
502Sakamoto, Yoshinori Sato, Michael Snyder, Andreas Schwab, Jason
503Thorpe, Corinna Vinschen, Ulrich Weigand, and Elena Zannoni, helped
504with the migration of old architectures to this new framework.
505
c5e30d01
AC
506Andrew Cagney completely re-designed and re-implemented @value{GDBN}'s
507unwinder framework, this consisting of a fresh new design featuring
508frame IDs, independent frame sniffers, and the sentinel frame. Mark
509Kettenis implemented the @sc{dwarf 2} unwinder, Jeff Johnston the
510libunwind unwinder, and Andrew Cagney the dummy, sentinel, tramp, and
db2e3e2e 511trad unwinders. The architecture-specific changes, each involving a
c5e30d01
AC
512complete rewrite of the architecture's frame code, were carried out by
513Jim Blandy, Joel Brobecker, Kevin Buettner, Andrew Cagney, Stephane
514Carrez, Randolph Chung, Orjan Friberg, Richard Henderson, Daniel
515Jacobowitz, Jeff Johnston, Mark Kettenis, Theodore A. Roth, Kei
516Sakamoto, Yoshinori Sato, Michael Snyder, Corinna Vinschen, and Ulrich
517Weigand.
518
ca3bf3bd
DJ
519Christian Zankel, Ross Morley, Bob Wilson, and Maxim Grigoriev from
520Tensilica, Inc.@: contributed support for Xtensa processors. Others
521who have worked on the Xtensa port of @value{GDBN} in the past include
522Steve Tjiang, John Newlin, and Scott Foehner.
523
08be9d71
ME
524Michael Eager and staff of Xilinx, Inc., contributed support for the
525Xilinx MicroBlaze architecture.
526
6d2ebf8b 527@node Sample Session
c906108c
SS
528@chapter A Sample @value{GDBN} Session
529
530You can use this manual at your leisure to read all about @value{GDBN}.
531However, a handful of commands are enough to get started using the
532debugger. This chapter illustrates those commands.
533
534@iftex
535In this sample session, we emphasize user input like this: @b{input},
536to make it easier to pick out from the surrounding output.
537@end iftex
538
539@c FIXME: this example may not be appropriate for some configs, where
540@c FIXME...primary interest is in remote use.
541
542One of the preliminary versions of @sc{gnu} @code{m4} (a generic macro
543processor) exhibits the following bug: sometimes, when we change its
544quote strings from the default, the commands used to capture one macro
545definition within another stop working. In the following short @code{m4}
546session, we define a macro @code{foo} which expands to @code{0000}; we
547then use the @code{m4} built-in @code{defn} to define @code{bar} as the
548same thing. However, when we change the open quote string to
549@code{<QUOTE>} and the close quote string to @code{<UNQUOTE>}, the same
550procedure fails to define a new synonym @code{baz}:
551
552@smallexample
553$ @b{cd gnu/m4}
554$ @b{./m4}
555@b{define(foo,0000)}
556
557@b{foo}
5580000
559@b{define(bar,defn(`foo'))}
560
561@b{bar}
5620000
563@b{changequote(<QUOTE>,<UNQUOTE>)}
564
565@b{define(baz,defn(<QUOTE>foo<UNQUOTE>))}
566@b{baz}
c8aa23ab 567@b{Ctrl-d}
c906108c
SS
568m4: End of input: 0: fatal error: EOF in string
569@end smallexample
570
571@noindent
572Let us use @value{GDBN} to try to see what is going on.
573
c906108c
SS
574@smallexample
575$ @b{@value{GDBP} m4}
576@c FIXME: this falsifies the exact text played out, to permit smallbook
577@c FIXME... format to come out better.
578@value{GDBN} is free software and you are welcome to distribute copies
5d161b24 579 of it under certain conditions; type "show copying" to see
c906108c 580 the conditions.
5d161b24 581There is absolutely no warranty for @value{GDBN}; type "show warranty"
c906108c
SS
582 for details.
583
584@value{GDBN} @value{GDBVN}, Copyright 1999 Free Software Foundation, Inc...
585(@value{GDBP})
586@end smallexample
c906108c
SS
587
588@noindent
589@value{GDBN} reads only enough symbol data to know where to find the
590rest when needed; as a result, the first prompt comes up very quickly.
591We now tell @value{GDBN} to use a narrower display width than usual, so
592that examples fit in this manual.
593
594@smallexample
595(@value{GDBP}) @b{set width 70}
596@end smallexample
597
598@noindent
599We need to see how the @code{m4} built-in @code{changequote} works.
600Having looked at the source, we know the relevant subroutine is
601@code{m4_changequote}, so we set a breakpoint there with the @value{GDBN}
602@code{break} command.
603
604@smallexample
605(@value{GDBP}) @b{break m4_changequote}
606Breakpoint 1 at 0x62f4: file builtin.c, line 879.
607@end smallexample
608
609@noindent
610Using the @code{run} command, we start @code{m4} running under @value{GDBN}
611control; as long as control does not reach the @code{m4_changequote}
612subroutine, the program runs as usual:
613
614@smallexample
615(@value{GDBP}) @b{run}
616Starting program: /work/Editorial/gdb/gnu/m4/m4
617@b{define(foo,0000)}
618
619@b{foo}
6200000
621@end smallexample
622
623@noindent
624To trigger the breakpoint, we call @code{changequote}. @value{GDBN}
625suspends execution of @code{m4}, displaying information about the
626context where it stops.
627
628@smallexample
629@b{changequote(<QUOTE>,<UNQUOTE>)}
630
5d161b24 631Breakpoint 1, m4_changequote (argc=3, argv=0x33c70)
c906108c
SS
632 at builtin.c:879
633879 if (bad_argc(TOKEN_DATA_TEXT(argv[0]),argc,1,3))
634@end smallexample
635
636@noindent
637Now we use the command @code{n} (@code{next}) to advance execution to
638the next line of the current function.
639
640@smallexample
641(@value{GDBP}) @b{n}
642882 set_quotes((argc >= 2) ? TOKEN_DATA_TEXT(argv[1])\
643 : nil,
644@end smallexample
645
646@noindent
647@code{set_quotes} looks like a promising subroutine. We can go into it
648by using the command @code{s} (@code{step}) instead of @code{next}.
649@code{step} goes to the next line to be executed in @emph{any}
650subroutine, so it steps into @code{set_quotes}.
651
652@smallexample
653(@value{GDBP}) @b{s}
654set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>")
655 at input.c:530
656530 if (lquote != def_lquote)
657@end smallexample
658
659@noindent
660The display that shows the subroutine where @code{m4} is now
661suspended (and its arguments) is called a stack frame display. It
662shows a summary of the stack. We can use the @code{backtrace}
663command (which can also be spelled @code{bt}), to see where we are
664in the stack as a whole: the @code{backtrace} command displays a
665stack frame for each active subroutine.
666
667@smallexample
668(@value{GDBP}) @b{bt}
669#0 set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>")
670 at input.c:530
5d161b24 671#1 0x6344 in m4_changequote (argc=3, argv=0x33c70)
c906108c
SS
672 at builtin.c:882
673#2 0x8174 in expand_macro (sym=0x33320) at macro.c:242
674#3 0x7a88 in expand_token (obs=0x0, t=209696, td=0xf7fffa30)
675 at macro.c:71
676#4 0x79dc in expand_input () at macro.c:40
677#5 0x2930 in main (argc=0, argv=0xf7fffb20) at m4.c:195
678@end smallexample
679
680@noindent
681We step through a few more lines to see what happens. The first two
682times, we can use @samp{s}; the next two times we use @code{n} to avoid
683falling into the @code{xstrdup} subroutine.
684
685@smallexample
686(@value{GDBP}) @b{s}
6870x3b5c 532 if (rquote != def_rquote)
688(@value{GDBP}) @b{s}
6890x3b80 535 lquote = (lq == nil || *lq == '\0') ? \
690def_lquote : xstrdup(lq);
691(@value{GDBP}) @b{n}
692536 rquote = (rq == nil || *rq == '\0') ? def_rquote\
693 : xstrdup(rq);
694(@value{GDBP}) @b{n}
695538 len_lquote = strlen(rquote);
696@end smallexample
697
698@noindent
699The last line displayed looks a little odd; we can examine the variables
700@code{lquote} and @code{rquote} to see if they are in fact the new left
701and right quotes we specified. We use the command @code{p}
702(@code{print}) to see their values.
703
704@smallexample
705(@value{GDBP}) @b{p lquote}
706$1 = 0x35d40 "<QUOTE>"
707(@value{GDBP}) @b{p rquote}
708$2 = 0x35d50 "<UNQUOTE>"
709@end smallexample
710
711@noindent
712@code{lquote} and @code{rquote} are indeed the new left and right quotes.
713To look at some context, we can display ten lines of source
714surrounding the current line with the @code{l} (@code{list}) command.
715
716@smallexample
717(@value{GDBP}) @b{l}
718533 xfree(rquote);
719534
720535 lquote = (lq == nil || *lq == '\0') ? def_lquote\
721 : xstrdup (lq);
722536 rquote = (rq == nil || *rq == '\0') ? def_rquote\
723 : xstrdup (rq);
724537
725538 len_lquote = strlen(rquote);
726539 len_rquote = strlen(lquote);
727540 @}
728541
729542 void
730@end smallexample
731
732@noindent
733Let us step past the two lines that set @code{len_lquote} and
734@code{len_rquote}, and then examine the values of those variables.
735
736@smallexample
737(@value{GDBP}) @b{n}
738539 len_rquote = strlen(lquote);
739(@value{GDBP}) @b{n}
740540 @}
741(@value{GDBP}) @b{p len_lquote}
742$3 = 9
743(@value{GDBP}) @b{p len_rquote}
744$4 = 7
745@end smallexample
746
747@noindent
748That certainly looks wrong, assuming @code{len_lquote} and
749@code{len_rquote} are meant to be the lengths of @code{lquote} and
750@code{rquote} respectively. We can set them to better values using
751the @code{p} command, since it can print the value of
752any expression---and that expression can include subroutine calls and
753assignments.
754
755@smallexample
756(@value{GDBP}) @b{p len_lquote=strlen(lquote)}
757$5 = 7
758(@value{GDBP}) @b{p len_rquote=strlen(rquote)}
759$6 = 9
760@end smallexample
761
762@noindent
763Is that enough to fix the problem of using the new quotes with the
764@code{m4} built-in @code{defn}? We can allow @code{m4} to continue
765executing with the @code{c} (@code{continue}) command, and then try the
766example that caused trouble initially:
767
768@smallexample
769(@value{GDBP}) @b{c}
770Continuing.
771
772@b{define(baz,defn(<QUOTE>foo<UNQUOTE>))}
773
774baz
7750000
776@end smallexample
777
778@noindent
779Success! The new quotes now work just as well as the default ones. The
780problem seems to have been just the two typos defining the wrong
781lengths. We allow @code{m4} exit by giving it an EOF as input:
782
783@smallexample
c8aa23ab 784@b{Ctrl-d}
c906108c
SS
785Program exited normally.
786@end smallexample
787
788@noindent
789The message @samp{Program exited normally.} is from @value{GDBN}; it
790indicates @code{m4} has finished executing. We can end our @value{GDBN}
791session with the @value{GDBN} @code{quit} command.
792
793@smallexample
794(@value{GDBP}) @b{quit}
795@end smallexample
c906108c 796
6d2ebf8b 797@node Invocation
c906108c
SS
798@chapter Getting In and Out of @value{GDBN}
799
800This chapter discusses how to start @value{GDBN}, and how to get out of it.
5d161b24 801The essentials are:
c906108c 802@itemize @bullet
5d161b24 803@item
53a5351d 804type @samp{@value{GDBP}} to start @value{GDBN}.
5d161b24 805@item
c8aa23ab 806type @kbd{quit} or @kbd{Ctrl-d} to exit.
c906108c
SS
807@end itemize
808
809@menu
810* Invoking GDB:: How to start @value{GDBN}
811* Quitting GDB:: How to quit @value{GDBN}
812* Shell Commands:: How to use shell commands inside @value{GDBN}
79a6e687 813* Logging Output:: How to log @value{GDBN}'s output to a file
c906108c
SS
814@end menu
815
6d2ebf8b 816@node Invoking GDB
c906108c
SS
817@section Invoking @value{GDBN}
818
c906108c
SS
819Invoke @value{GDBN} by running the program @code{@value{GDBP}}. Once started,
820@value{GDBN} reads commands from the terminal until you tell it to exit.
821
822You can also run @code{@value{GDBP}} with a variety of arguments and options,
823to specify more of your debugging environment at the outset.
824
c906108c
SS
825The command-line options described here are designed
826to cover a variety of situations; in some environments, some of these
5d161b24 827options may effectively be unavailable.
c906108c
SS
828
829The most usual way to start @value{GDBN} is with one argument,
830specifying an executable program:
831
474c8240 832@smallexample
c906108c 833@value{GDBP} @var{program}
474c8240 834@end smallexample
c906108c 835
c906108c
SS
836@noindent
837You can also start with both an executable program and a core file
838specified:
839
474c8240 840@smallexample
c906108c 841@value{GDBP} @var{program} @var{core}
474c8240 842@end smallexample
c906108c
SS
843
844You can, instead, specify a process ID as a second argument, if you want
845to debug a running process:
846
474c8240 847@smallexample
c906108c 848@value{GDBP} @var{program} 1234
474c8240 849@end smallexample
c906108c
SS
850
851@noindent
852would attach @value{GDBN} to process @code{1234} (unless you also have a file
853named @file{1234}; @value{GDBN} does check for a core file first).
854
c906108c 855Taking advantage of the second command-line argument requires a fairly
2df3850c
JM
856complete operating system; when you use @value{GDBN} as a remote
857debugger attached to a bare board, there may not be any notion of
858``process'', and there is often no way to get a core dump. @value{GDBN}
859will warn you if it is unable to attach or to read core dumps.
c906108c 860
aa26fa3a
TT
861You can optionally have @code{@value{GDBP}} pass any arguments after the
862executable file to the inferior using @code{--args}. This option stops
863option processing.
474c8240 864@smallexample
3f94c067 865@value{GDBP} --args gcc -O2 -c foo.c
474c8240 866@end smallexample
aa26fa3a
TT
867This will cause @code{@value{GDBP}} to debug @code{gcc}, and to set
868@code{gcc}'s command-line arguments (@pxref{Arguments}) to @samp{-O2 -c foo.c}.
869
96a2c332 870You can run @code{@value{GDBP}} without printing the front material, which describes
c906108c
SS
871@value{GDBN}'s non-warranty, by specifying @code{-silent}:
872
873@smallexample
874@value{GDBP} -silent
875@end smallexample
876
877@noindent
878You can further control how @value{GDBN} starts up by using command-line
879options. @value{GDBN} itself can remind you of the options available.
880
881@noindent
882Type
883
474c8240 884@smallexample
c906108c 885@value{GDBP} -help
474c8240 886@end smallexample
c906108c
SS
887
888@noindent
889to display all available options and briefly describe their use
890(@samp{@value{GDBP} -h} is a shorter equivalent).
891
892All options and command line arguments you give are processed
893in sequential order. The order makes a difference when the
894@samp{-x} option is used.
895
896
897@menu
c906108c
SS
898* File Options:: Choosing files
899* Mode Options:: Choosing modes
6fc08d32 900* Startup:: What @value{GDBN} does during startup
c906108c
SS
901@end menu
902
6d2ebf8b 903@node File Options
79a6e687 904@subsection Choosing Files
c906108c 905
2df3850c 906When @value{GDBN} starts, it reads any arguments other than options as
c906108c
SS
907specifying an executable file and core file (or process ID). This is
908the same as if the arguments were specified by the @samp{-se} and
d52fb0e9 909@samp{-c} (or @samp{-p}) options respectively. (@value{GDBN} reads the
19837790
MS
910first argument that does not have an associated option flag as
911equivalent to the @samp{-se} option followed by that argument; and the
912second argument that does not have an associated option flag, if any, as
913equivalent to the @samp{-c}/@samp{-p} option followed by that argument.)
914If the second argument begins with a decimal digit, @value{GDBN} will
915first attempt to attach to it as a process, and if that fails, attempt
916to open it as a corefile. If you have a corefile whose name begins with
b383017d 917a digit, you can prevent @value{GDBN} from treating it as a pid by
c1468174 918prefixing it with @file{./}, e.g.@: @file{./12345}.
7a292a7a
SS
919
920If @value{GDBN} has not been configured to included core file support,
921such as for most embedded targets, then it will complain about a second
922argument and ignore it.
c906108c
SS
923
924Many options have both long and short forms; both are shown in the
925following list. @value{GDBN} also recognizes the long forms if you truncate
926them, so long as enough of the option is present to be unambiguous.
927(If you prefer, you can flag option arguments with @samp{--} rather
928than @samp{-}, though we illustrate the more usual convention.)
929
d700128c
EZ
930@c NOTE: the @cindex entries here use double dashes ON PURPOSE. This
931@c way, both those who look for -foo and --foo in the index, will find
932@c it.
933
c906108c
SS
934@table @code
935@item -symbols @var{file}
936@itemx -s @var{file}
d700128c
EZ
937@cindex @code{--symbols}
938@cindex @code{-s}
c906108c
SS
939Read symbol table from file @var{file}.
940
941@item -exec @var{file}
942@itemx -e @var{file}
d700128c
EZ
943@cindex @code{--exec}
944@cindex @code{-e}
7a292a7a
SS
945Use file @var{file} as the executable file to execute when appropriate,
946and for examining pure data in conjunction with a core dump.
c906108c
SS
947
948@item -se @var{file}
d700128c 949@cindex @code{--se}
c906108c
SS
950Read symbol table from file @var{file} and use it as the executable
951file.
952
c906108c
SS
953@item -core @var{file}
954@itemx -c @var{file}
d700128c
EZ
955@cindex @code{--core}
956@cindex @code{-c}
b383017d 957Use file @var{file} as a core dump to examine.
c906108c 958
19837790
MS
959@item -pid @var{number}
960@itemx -p @var{number}
961@cindex @code{--pid}
962@cindex @code{-p}
963Connect to process ID @var{number}, as with the @code{attach} command.
c906108c
SS
964
965@item -command @var{file}
966@itemx -x @var{file}
d700128c
EZ
967@cindex @code{--command}
968@cindex @code{-x}
95433b34
JB
969Execute commands from file @var{file}. The contents of this file is
970evaluated exactly as the @code{source} command would.
8150ff9c 971@xref{Command Files,, Command files}.
c906108c 972
8a5a3c82
AS
973@item -eval-command @var{command}
974@itemx -ex @var{command}
975@cindex @code{--eval-command}
976@cindex @code{-ex}
977Execute a single @value{GDBN} command.
978
979This option may be used multiple times to call multiple commands. It may
980also be interleaved with @samp{-command} as required.
981
982@smallexample
983@value{GDBP} -ex 'target sim' -ex 'load' \
984 -x setbreakpoints -ex 'run' a.out
985@end smallexample
986
c906108c
SS
987@item -directory @var{directory}
988@itemx -d @var{directory}
d700128c
EZ
989@cindex @code{--directory}
990@cindex @code{-d}
4b505b12 991Add @var{directory} to the path to search for source and script files.
c906108c 992
c906108c
SS
993@item -r
994@itemx -readnow
d700128c
EZ
995@cindex @code{--readnow}
996@cindex @code{-r}
c906108c
SS
997Read each symbol file's entire symbol table immediately, rather than
998the default, which is to read it incrementally as it is needed.
999This makes startup slower, but makes future operations faster.
53a5351d 1000
c906108c
SS
1001@end table
1002
6d2ebf8b 1003@node Mode Options
79a6e687 1004@subsection Choosing Modes
c906108c
SS
1005
1006You can run @value{GDBN} in various alternative modes---for example, in
1007batch mode or quiet mode.
1008
1009@table @code
1010@item -nx
1011@itemx -n
d700128c
EZ
1012@cindex @code{--nx}
1013@cindex @code{-n}
96565e91 1014Do not execute commands found in any initialization files. Normally,
2df3850c
JM
1015@value{GDBN} executes the commands in these files after all the command
1016options and arguments have been processed. @xref{Command Files,,Command
79a6e687 1017Files}.
c906108c
SS
1018
1019@item -quiet
d700128c 1020@itemx -silent
c906108c 1021@itemx -q
d700128c
EZ
1022@cindex @code{--quiet}
1023@cindex @code{--silent}
1024@cindex @code{-q}
c906108c
SS
1025``Quiet''. Do not print the introductory and copyright messages. These
1026messages are also suppressed in batch mode.
1027
1028@item -batch
d700128c 1029@cindex @code{--batch}
c906108c
SS
1030Run in batch mode. Exit with status @code{0} after processing all the
1031command files specified with @samp{-x} (and all commands from
1032initialization files, if not inhibited with @samp{-n}). Exit with
1033nonzero status if an error occurs in executing the @value{GDBN} commands
7c953934
TT
1034in the command files. Batch mode also disables pagination;
1035@pxref{Screen Size} and acts as if @kbd{set confirm off} were in
1036effect (@pxref{Messages/Warnings}).
c906108c 1037
2df3850c
JM
1038Batch mode may be useful for running @value{GDBN} as a filter, for
1039example to download and run a program on another computer; in order to
1040make this more useful, the message
c906108c 1041
474c8240 1042@smallexample
c906108c 1043Program exited normally.
474c8240 1044@end smallexample
c906108c
SS
1045
1046@noindent
2df3850c
JM
1047(which is ordinarily issued whenever a program running under
1048@value{GDBN} control terminates) is not issued when running in batch
1049mode.
1050
1a088d06
AS
1051@item -batch-silent
1052@cindex @code{--batch-silent}
1053Run in batch mode exactly like @samp{-batch}, but totally silently. All
1054@value{GDBN} output to @code{stdout} is prevented (@code{stderr} is
1055unaffected). This is much quieter than @samp{-silent} and would be useless
1056for an interactive session.
1057
1058This is particularly useful when using targets that give @samp{Loading section}
1059messages, for example.
1060
1061Note that targets that give their output via @value{GDBN}, as opposed to
1062writing directly to @code{stdout}, will also be made silent.
1063
4b0ad762
AS
1064@item -return-child-result
1065@cindex @code{--return-child-result}
1066The return code from @value{GDBN} will be the return code from the child
1067process (the process being debugged), with the following exceptions:
1068
1069@itemize @bullet
1070@item
1071@value{GDBN} exits abnormally. E.g., due to an incorrect argument or an
1072internal error. In this case the exit code is the same as it would have been
1073without @samp{-return-child-result}.
1074@item
1075The user quits with an explicit value. E.g., @samp{quit 1}.
1076@item
1077The child process never runs, or is not allowed to terminate, in which case
1078the exit code will be -1.
1079@end itemize
1080
1081This option is useful in conjunction with @samp{-batch} or @samp{-batch-silent},
1082when @value{GDBN} is being used as a remote program loader or simulator
1083interface.
1084
2df3850c
JM
1085@item -nowindows
1086@itemx -nw
d700128c
EZ
1087@cindex @code{--nowindows}
1088@cindex @code{-nw}
2df3850c 1089``No windows''. If @value{GDBN} comes with a graphical user interface
96a2c332 1090(GUI) built in, then this option tells @value{GDBN} to only use the command-line
2df3850c
JM
1091interface. If no GUI is available, this option has no effect.
1092
1093@item -windows
1094@itemx -w
d700128c
EZ
1095@cindex @code{--windows}
1096@cindex @code{-w}
2df3850c
JM
1097If @value{GDBN} includes a GUI, then this option requires it to be
1098used if possible.
c906108c
SS
1099
1100@item -cd @var{directory}
d700128c 1101@cindex @code{--cd}
c906108c
SS
1102Run @value{GDBN} using @var{directory} as its working directory,
1103instead of the current directory.
1104
c906108c
SS
1105@item -fullname
1106@itemx -f
d700128c
EZ
1107@cindex @code{--fullname}
1108@cindex @code{-f}
7a292a7a
SS
1109@sc{gnu} Emacs sets this option when it runs @value{GDBN} as a
1110subprocess. It tells @value{GDBN} to output the full file name and line
1111number in a standard, recognizable fashion each time a stack frame is
1112displayed (which includes each time your program stops). This
1113recognizable format looks like two @samp{\032} characters, followed by
1114the file name, line number and character position separated by colons,
1115and a newline. The Emacs-to-@value{GDBN} interface program uses the two
1116@samp{\032} characters as a signal to display the source code for the
1117frame.
c906108c 1118
d700128c
EZ
1119@item -epoch
1120@cindex @code{--epoch}
1121The Epoch Emacs-@value{GDBN} interface sets this option when it runs
1122@value{GDBN} as a subprocess. It tells @value{GDBN} to modify its print
1123routines so as to allow Epoch to display values of expressions in a
1124separate window.
1125
1126@item -annotate @var{level}
1127@cindex @code{--annotate}
1128This option sets the @dfn{annotation level} inside @value{GDBN}. Its
1129effect is identical to using @samp{set annotate @var{level}}
086432e2
AC
1130(@pxref{Annotations}). The annotation @var{level} controls how much
1131information @value{GDBN} prints together with its prompt, values of
1132expressions, source lines, and other types of output. Level 0 is the
1133normal, level 1 is for use when @value{GDBN} is run as a subprocess of
1134@sc{gnu} Emacs, level 3 is the maximum annotation suitable for programs
1135that control @value{GDBN}, and level 2 has been deprecated.
1136
265eeb58 1137The annotation mechanism has largely been superseded by @sc{gdb/mi}
086432e2 1138(@pxref{GDB/MI}).
d700128c 1139
aa26fa3a
TT
1140@item --args
1141@cindex @code{--args}
1142Change interpretation of command line so that arguments following the
1143executable file are passed as command line arguments to the inferior.
1144This option stops option processing.
1145
2df3850c
JM
1146@item -baud @var{bps}
1147@itemx -b @var{bps}
d700128c
EZ
1148@cindex @code{--baud}
1149@cindex @code{-b}
c906108c
SS
1150Set the line speed (baud rate or bits per second) of any serial
1151interface used by @value{GDBN} for remote debugging.
c906108c 1152
f47b1503
AS
1153@item -l @var{timeout}
1154@cindex @code{-l}
1155Set the timeout (in seconds) of any communication used by @value{GDBN}
1156for remote debugging.
1157
c906108c 1158@item -tty @var{device}
d700128c
EZ
1159@itemx -t @var{device}
1160@cindex @code{--tty}
1161@cindex @code{-t}
c906108c
SS
1162Run using @var{device} for your program's standard input and output.
1163@c FIXME: kingdon thinks there is more to -tty. Investigate.
c906108c 1164
53a5351d 1165@c resolve the situation of these eventually
c4555f82
SC
1166@item -tui
1167@cindex @code{--tui}
d0d5df6f
AC
1168Activate the @dfn{Text User Interface} when starting. The Text User
1169Interface manages several text windows on the terminal, showing
1170source, assembly, registers and @value{GDBN} command outputs
1171(@pxref{TUI, ,@value{GDBN} Text User Interface}). Alternatively, the
1172Text User Interface can be enabled by invoking the program
46ba6afa 1173@samp{@value{GDBTUI}}. Do not use this option if you run @value{GDBN} from
d0d5df6f 1174Emacs (@pxref{Emacs, ,Using @value{GDBN} under @sc{gnu} Emacs}).
53a5351d
JM
1175
1176@c @item -xdb
d700128c 1177@c @cindex @code{--xdb}
53a5351d
JM
1178@c Run in XDB compatibility mode, allowing the use of certain XDB commands.
1179@c For information, see the file @file{xdb_trans.html}, which is usually
1180@c installed in the directory @code{/opt/langtools/wdb/doc} on HP-UX
1181@c systems.
1182
d700128c
EZ
1183@item -interpreter @var{interp}
1184@cindex @code{--interpreter}
1185Use the interpreter @var{interp} for interface with the controlling
1186program or device. This option is meant to be set by programs which
94bbb2c0 1187communicate with @value{GDBN} using it as a back end.
21c294e6 1188@xref{Interpreters, , Command Interpreters}.
94bbb2c0 1189
da0f9dcd 1190@samp{--interpreter=mi} (or @samp{--interpreter=mi2}) causes
2fcf52f0 1191@value{GDBN} to use the @dfn{@sc{gdb/mi} interface} (@pxref{GDB/MI, ,
6b5e8c01 1192The @sc{gdb/mi} Interface}) included since @value{GDBN} version 6.0. The
6c74ac8b
AC
1193previous @sc{gdb/mi} interface, included in @value{GDBN} version 5.3 and
1194selected with @samp{--interpreter=mi1}, is deprecated. Earlier
1195@sc{gdb/mi} interfaces are no longer supported.
d700128c
EZ
1196
1197@item -write
1198@cindex @code{--write}
1199Open the executable and core files for both reading and writing. This
1200is equivalent to the @samp{set write on} command inside @value{GDBN}
1201(@pxref{Patching}).
1202
1203@item -statistics
1204@cindex @code{--statistics}
1205This option causes @value{GDBN} to print statistics about time and
1206memory usage after it completes each command and returns to the prompt.
1207
1208@item -version
1209@cindex @code{--version}
1210This option causes @value{GDBN} to print its version number and
1211no-warranty blurb, and exit.
1212
c906108c
SS
1213@end table
1214
6fc08d32 1215@node Startup
79a6e687 1216@subsection What @value{GDBN} Does During Startup
6fc08d32
EZ
1217@cindex @value{GDBN} startup
1218
1219Here's the description of what @value{GDBN} does during session startup:
1220
1221@enumerate
1222@item
1223Sets up the command interpreter as specified by the command line
1224(@pxref{Mode Options, interpreter}).
1225
1226@item
1227@cindex init file
098b41a6
JG
1228Reads the system-wide @dfn{init file} (if @option{--with-system-gdbinit} was
1229used when building @value{GDBN}; @pxref{System-wide configuration,
1230 ,System-wide configuration and settings}) and executes all the commands in
1231that file.
1232
1233@item
1234Reads the init file (if any) in your home directory@footnote{On
6fc08d32
EZ
1235DOS/Windows systems, the home directory is the one pointed to by the
1236@code{HOME} environment variable.} and executes all the commands in
1237that file.
1238
1239@item
1240Processes command line options and operands.
1241
1242@item
1243Reads and executes the commands from init file (if any) in the current
119b882a
EZ
1244working directory. This is only done if the current directory is
1245different from your home directory. Thus, you can have more than one
1246init file, one generic in your home directory, and another, specific
1247to the program you are debugging, in the directory where you invoke
6fc08d32
EZ
1248@value{GDBN}.
1249
1250@item
1251Reads command files specified by the @samp{-x} option. @xref{Command
1252Files}, for more details about @value{GDBN} command files.
1253
1254@item
1255Reads the command history recorded in the @dfn{history file}.
d620b259 1256@xref{Command History}, for more details about the command history and the
6fc08d32
EZ
1257files where @value{GDBN} records it.
1258@end enumerate
1259
1260Init files use the same syntax as @dfn{command files} (@pxref{Command
1261Files}) and are processed by @value{GDBN} in the same way. The init
1262file in your home directory can set options (such as @samp{set
1263complaints}) that affect subsequent processing of command line options
1264and operands. Init files are not executed if you use the @samp{-nx}
79a6e687 1265option (@pxref{Mode Options, ,Choosing Modes}).
6fc08d32 1266
098b41a6
JG
1267To display the list of init files loaded by gdb at startup, you
1268can use @kbd{gdb --help}.
1269
6fc08d32
EZ
1270@cindex init file name
1271@cindex @file{.gdbinit}
119b882a 1272@cindex @file{gdb.ini}
8807d78b 1273The @value{GDBN} init files are normally called @file{.gdbinit}.
119b882a
EZ
1274The DJGPP port of @value{GDBN} uses the name @file{gdb.ini}, due to
1275the limitations of file names imposed by DOS filesystems. The Windows
1276ports of @value{GDBN} use the standard name, but if they find a
1277@file{gdb.ini} file, they warn you about that and suggest to rename
1278the file to the standard name.
1279
6fc08d32 1280
6d2ebf8b 1281@node Quitting GDB
c906108c
SS
1282@section Quitting @value{GDBN}
1283@cindex exiting @value{GDBN}
1284@cindex leaving @value{GDBN}
1285
1286@table @code
1287@kindex quit @r{[}@var{expression}@r{]}
41afff9a 1288@kindex q @r{(@code{quit})}
96a2c332
SS
1289@item quit @r{[}@var{expression}@r{]}
1290@itemx q
1291To exit @value{GDBN}, use the @code{quit} command (abbreviated
c8aa23ab 1292@code{q}), or type an end-of-file character (usually @kbd{Ctrl-d}). If you
96a2c332
SS
1293do not supply @var{expression}, @value{GDBN} will terminate normally;
1294otherwise it will terminate using the result of @var{expression} as the
1295error code.
c906108c
SS
1296@end table
1297
1298@cindex interrupt
c8aa23ab 1299An interrupt (often @kbd{Ctrl-c}) does not exit from @value{GDBN}, but rather
c906108c
SS
1300terminates the action of any @value{GDBN} command that is in progress and
1301returns to @value{GDBN} command level. It is safe to type the interrupt
1302character at any time because @value{GDBN} does not allow it to take effect
1303until a time when it is safe.
1304
c906108c
SS
1305If you have been using @value{GDBN} to control an attached process or
1306device, you can release it with the @code{detach} command
79a6e687 1307(@pxref{Attach, ,Debugging an Already-running Process}).
c906108c 1308
6d2ebf8b 1309@node Shell Commands
79a6e687 1310@section Shell Commands
c906108c
SS
1311
1312If you need to execute occasional shell commands during your
1313debugging session, there is no need to leave or suspend @value{GDBN}; you can
1314just use the @code{shell} command.
1315
1316@table @code
1317@kindex shell
1318@cindex shell escape
1319@item shell @var{command string}
1320Invoke a standard shell to execute @var{command string}.
c906108c 1321If it exists, the environment variable @code{SHELL} determines which
d4f3574e
SS
1322shell to run. Otherwise @value{GDBN} uses the default shell
1323(@file{/bin/sh} on Unix systems, @file{COMMAND.COM} on MS-DOS, etc.).
c906108c
SS
1324@end table
1325
1326The utility @code{make} is often needed in development environments.
1327You do not have to use the @code{shell} command for this purpose in
1328@value{GDBN}:
1329
1330@table @code
1331@kindex make
1332@cindex calling make
1333@item make @var{make-args}
1334Execute the @code{make} program with the specified
1335arguments. This is equivalent to @samp{shell make @var{make-args}}.
1336@end table
1337
79a6e687
BW
1338@node Logging Output
1339@section Logging Output
0fac0b41 1340@cindex logging @value{GDBN} output
9c16f35a 1341@cindex save @value{GDBN} output to a file
0fac0b41
DJ
1342
1343You may want to save the output of @value{GDBN} commands to a file.
1344There are several commands to control @value{GDBN}'s logging.
1345
1346@table @code
1347@kindex set logging
1348@item set logging on
1349Enable logging.
1350@item set logging off
1351Disable logging.
9c16f35a 1352@cindex logging file name
0fac0b41
DJ
1353@item set logging file @var{file}
1354Change the name of the current logfile. The default logfile is @file{gdb.txt}.
1355@item set logging overwrite [on|off]
1356By default, @value{GDBN} will append to the logfile. Set @code{overwrite} if
1357you want @code{set logging on} to overwrite the logfile instead.
1358@item set logging redirect [on|off]
1359By default, @value{GDBN} output will go to both the terminal and the logfile.
1360Set @code{redirect} if you want output to go only to the log file.
1361@kindex show logging
1362@item show logging
1363Show the current values of the logging settings.
1364@end table
1365
6d2ebf8b 1366@node Commands
c906108c
SS
1367@chapter @value{GDBN} Commands
1368
1369You can abbreviate a @value{GDBN} command to the first few letters of the command
1370name, if that abbreviation is unambiguous; and you can repeat certain
1371@value{GDBN} commands by typing just @key{RET}. You can also use the @key{TAB}
1372key to get @value{GDBN} to fill out the rest of a word in a command (or to
1373show you the alternatives available, if there is more than one possibility).
1374
1375@menu
1376* Command Syntax:: How to give commands to @value{GDBN}
1377* Completion:: Command completion
1378* Help:: How to ask @value{GDBN} for help
1379@end menu
1380
6d2ebf8b 1381@node Command Syntax
79a6e687 1382@section Command Syntax
c906108c
SS
1383
1384A @value{GDBN} command is a single line of input. There is no limit on
1385how long it can be. It starts with a command name, which is followed by
1386arguments whose meaning depends on the command name. For example, the
1387command @code{step} accepts an argument which is the number of times to
1388step, as in @samp{step 5}. You can also use the @code{step} command
96a2c332 1389with no arguments. Some commands do not allow any arguments.
c906108c
SS
1390
1391@cindex abbreviation
1392@value{GDBN} command names may always be truncated if that abbreviation is
1393unambiguous. Other possible command abbreviations are listed in the
1394documentation for individual commands. In some cases, even ambiguous
1395abbreviations are allowed; for example, @code{s} is specially defined as
1396equivalent to @code{step} even though there are other commands whose
1397names start with @code{s}. You can test abbreviations by using them as
1398arguments to the @code{help} command.
1399
1400@cindex repeating commands
41afff9a 1401@kindex RET @r{(repeat last command)}
c906108c 1402A blank line as input to @value{GDBN} (typing just @key{RET}) means to
96a2c332 1403repeat the previous command. Certain commands (for example, @code{run})
c906108c
SS
1404will not repeat this way; these are commands whose unintentional
1405repetition might cause trouble and which you are unlikely to want to
c45da7e6
EZ
1406repeat. User-defined commands can disable this feature; see
1407@ref{Define, dont-repeat}.
c906108c
SS
1408
1409The @code{list} and @code{x} commands, when you repeat them with
1410@key{RET}, construct new arguments rather than repeating
1411exactly as typed. This permits easy scanning of source or memory.
1412
1413@value{GDBN} can also use @key{RET} in another way: to partition lengthy
1414output, in a way similar to the common utility @code{more}
79a6e687 1415(@pxref{Screen Size,,Screen Size}). Since it is easy to press one
c906108c
SS
1416@key{RET} too many in this situation, @value{GDBN} disables command
1417repetition after any command that generates this sort of display.
1418
41afff9a 1419@kindex # @r{(a comment)}
c906108c
SS
1420@cindex comment
1421Any text from a @kbd{#} to the end of the line is a comment; it does
1422nothing. This is useful mainly in command files (@pxref{Command
79a6e687 1423Files,,Command Files}).
c906108c 1424
88118b3a 1425@cindex repeating command sequences
c8aa23ab
EZ
1426@kindex Ctrl-o @r{(operate-and-get-next)}
1427The @kbd{Ctrl-o} binding is useful for repeating a complex sequence of
7f9087cb 1428commands. This command accepts the current line, like @key{RET}, and
88118b3a
TT
1429then fetches the next line relative to the current line from the history
1430for editing.
1431
6d2ebf8b 1432@node Completion
79a6e687 1433@section Command Completion
c906108c
SS
1434
1435@cindex completion
1436@cindex word completion
1437@value{GDBN} can fill in the rest of a word in a command for you, if there is
1438only one possibility; it can also show you what the valid possibilities
1439are for the next word in a command, at any time. This works for @value{GDBN}
1440commands, @value{GDBN} subcommands, and the names of symbols in your program.
1441
1442Press the @key{TAB} key whenever you want @value{GDBN} to fill out the rest
1443of a word. If there is only one possibility, @value{GDBN} fills in the
1444word, and waits for you to finish the command (or press @key{RET} to
1445enter it). For example, if you type
1446
1447@c FIXME "@key" does not distinguish its argument sufficiently to permit
1448@c complete accuracy in these examples; space introduced for clarity.
1449@c If texinfo enhancements make it unnecessary, it would be nice to
1450@c replace " @key" by "@key" in the following...
474c8240 1451@smallexample
c906108c 1452(@value{GDBP}) info bre @key{TAB}
474c8240 1453@end smallexample
c906108c
SS
1454
1455@noindent
1456@value{GDBN} fills in the rest of the word @samp{breakpoints}, since that is
1457the only @code{info} subcommand beginning with @samp{bre}:
1458
474c8240 1459@smallexample
c906108c 1460(@value{GDBP}) info breakpoints
474c8240 1461@end smallexample
c906108c
SS
1462
1463@noindent
1464You can either press @key{RET} at this point, to run the @code{info
1465breakpoints} command, or backspace and enter something else, if
1466@samp{breakpoints} does not look like the command you expected. (If you
1467were sure you wanted @code{info breakpoints} in the first place, you
1468might as well just type @key{RET} immediately after @samp{info bre},
1469to exploit command abbreviations rather than command completion).
1470
1471If there is more than one possibility for the next word when you press
1472@key{TAB}, @value{GDBN} sounds a bell. You can either supply more
1473characters and try again, or just press @key{TAB} a second time;
1474@value{GDBN} displays all the possible completions for that word. For
1475example, you might want to set a breakpoint on a subroutine whose name
1476begins with @samp{make_}, but when you type @kbd{b make_@key{TAB}} @value{GDBN}
1477just sounds the bell. Typing @key{TAB} again displays all the
1478function names in your program that begin with those characters, for
1479example:
1480
474c8240 1481@smallexample
c906108c
SS
1482(@value{GDBP}) b make_ @key{TAB}
1483@exdent @value{GDBN} sounds bell; press @key{TAB} again, to see:
5d161b24
DB
1484make_a_section_from_file make_environ
1485make_abs_section make_function_type
1486make_blockvector make_pointer_type
1487make_cleanup make_reference_type
c906108c
SS
1488make_command make_symbol_completion_list
1489(@value{GDBP}) b make_
474c8240 1490@end smallexample
c906108c
SS
1491
1492@noindent
1493After displaying the available possibilities, @value{GDBN} copies your
1494partial input (@samp{b make_} in the example) so you can finish the
1495command.
1496
1497If you just want to see the list of alternatives in the first place, you
b37052ae 1498can press @kbd{M-?} rather than pressing @key{TAB} twice. @kbd{M-?}
7a292a7a 1499means @kbd{@key{META} ?}. You can type this either by holding down a
c906108c 1500key designated as the @key{META} shift on your keyboard (if there is
7a292a7a 1501one) while typing @kbd{?}, or as @key{ESC} followed by @kbd{?}.
c906108c
SS
1502
1503@cindex quotes in commands
1504@cindex completion of quoted strings
1505Sometimes the string you need, while logically a ``word'', may contain
7a292a7a
SS
1506parentheses or other characters that @value{GDBN} normally excludes from
1507its notion of a word. To permit word completion to work in this
1508situation, you may enclose words in @code{'} (single quote marks) in
1509@value{GDBN} commands.
c906108c 1510
c906108c 1511The most likely situation where you might need this is in typing the
b37052ae
EZ
1512name of a C@t{++} function. This is because C@t{++} allows function
1513overloading (multiple definitions of the same function, distinguished
1514by argument type). For example, when you want to set a breakpoint you
1515may need to distinguish whether you mean the version of @code{name}
1516that takes an @code{int} parameter, @code{name(int)}, or the version
1517that takes a @code{float} parameter, @code{name(float)}. To use the
1518word-completion facilities in this situation, type a single quote
1519@code{'} at the beginning of the function name. This alerts
1520@value{GDBN} that it may need to consider more information than usual
1521when you press @key{TAB} or @kbd{M-?} to request word completion:
c906108c 1522
474c8240 1523@smallexample
96a2c332 1524(@value{GDBP}) b 'bubble( @kbd{M-?}
c906108c
SS
1525bubble(double,double) bubble(int,int)
1526(@value{GDBP}) b 'bubble(
474c8240 1527@end smallexample
c906108c
SS
1528
1529In some cases, @value{GDBN} can tell that completing a name requires using
1530quotes. When this happens, @value{GDBN} inserts the quote for you (while
1531completing as much as it can) if you do not type the quote in the first
1532place:
1533
474c8240 1534@smallexample
c906108c
SS
1535(@value{GDBP}) b bub @key{TAB}
1536@exdent @value{GDBN} alters your input line to the following, and rings a bell:
1537(@value{GDBP}) b 'bubble(
474c8240 1538@end smallexample
c906108c
SS
1539
1540@noindent
1541In general, @value{GDBN} can tell that a quote is needed (and inserts it) if
1542you have not yet started typing the argument list when you ask for
1543completion on an overloaded symbol.
1544
79a6e687
BW
1545For more information about overloaded functions, see @ref{C Plus Plus
1546Expressions, ,C@t{++} Expressions}. You can use the command @code{set
c906108c 1547overload-resolution off} to disable overload resolution;
79a6e687 1548see @ref{Debugging C Plus Plus, ,@value{GDBN} Features for C@t{++}}.
c906108c 1549
65d12d83
TT
1550@cindex completion of structure field names
1551@cindex structure field name completion
1552@cindex completion of union field names
1553@cindex union field name completion
1554When completing in an expression which looks up a field in a
1555structure, @value{GDBN} also tries@footnote{The completer can be
1556confused by certain kinds of invalid expressions. Also, it only
1557examines the static type of the expression, not the dynamic type.} to
1558limit completions to the field names available in the type of the
1559left-hand-side:
1560
1561@smallexample
1562(@value{GDBP}) p gdb_stdout.@kbd{M-?}
1563magic to_delete to_fputs to_put to_rewind
1564to_data to_flush to_isatty to_read to_write
1565@end smallexample
1566
1567@noindent
1568This is because the @code{gdb_stdout} is a variable of the type
1569@code{struct ui_file} that is defined in @value{GDBN} sources as
1570follows:
1571
1572@smallexample
1573struct ui_file
1574@{
1575 int *magic;
1576 ui_file_flush_ftype *to_flush;
1577 ui_file_write_ftype *to_write;
1578 ui_file_fputs_ftype *to_fputs;
1579 ui_file_read_ftype *to_read;
1580 ui_file_delete_ftype *to_delete;
1581 ui_file_isatty_ftype *to_isatty;
1582 ui_file_rewind_ftype *to_rewind;
1583 ui_file_put_ftype *to_put;
1584 void *to_data;
1585@}
1586@end smallexample
1587
c906108c 1588
6d2ebf8b 1589@node Help
79a6e687 1590@section Getting Help
c906108c
SS
1591@cindex online documentation
1592@kindex help
1593
5d161b24 1594You can always ask @value{GDBN} itself for information on its commands,
c906108c
SS
1595using the command @code{help}.
1596
1597@table @code
41afff9a 1598@kindex h @r{(@code{help})}
c906108c
SS
1599@item help
1600@itemx h
1601You can use @code{help} (abbreviated @code{h}) with no arguments to
1602display a short list of named classes of commands:
1603
1604@smallexample
1605(@value{GDBP}) help
1606List of classes of commands:
1607
2df3850c 1608aliases -- Aliases of other commands
c906108c 1609breakpoints -- Making program stop at certain points
2df3850c 1610data -- Examining data
c906108c 1611files -- Specifying and examining files
2df3850c
JM
1612internals -- Maintenance commands
1613obscure -- Obscure features
1614running -- Running the program
1615stack -- Examining the stack
c906108c
SS
1616status -- Status inquiries
1617support -- Support facilities
12c27660 1618tracepoints -- Tracing of program execution without
96a2c332 1619 stopping the program
c906108c 1620user-defined -- User-defined commands
c906108c 1621
5d161b24 1622Type "help" followed by a class name for a list of
c906108c 1623commands in that class.
5d161b24 1624Type "help" followed by command name for full
c906108c
SS
1625documentation.
1626Command name abbreviations are allowed if unambiguous.
1627(@value{GDBP})
1628@end smallexample
96a2c332 1629@c the above line break eliminates huge line overfull...
c906108c
SS
1630
1631@item help @var{class}
1632Using one of the general help classes as an argument, you can get a
1633list of the individual commands in that class. For example, here is the
1634help display for the class @code{status}:
1635
1636@smallexample
1637(@value{GDBP}) help status
1638Status inquiries.
1639
1640List of commands:
1641
1642@c Line break in "show" line falsifies real output, but needed
1643@c to fit in smallbook page size.
2df3850c 1644info -- Generic command for showing things
12c27660 1645 about the program being debugged
2df3850c 1646show -- Generic command for showing things
12c27660 1647 about the debugger
c906108c 1648
5d161b24 1649Type "help" followed by command name for full
c906108c
SS
1650documentation.
1651Command name abbreviations are allowed if unambiguous.
1652(@value{GDBP})
1653@end smallexample
1654
1655@item help @var{command}
1656With a command name as @code{help} argument, @value{GDBN} displays a
1657short paragraph on how to use that command.
1658
6837a0a2
DB
1659@kindex apropos
1660@item apropos @var{args}
09d4efe1 1661The @code{apropos} command searches through all of the @value{GDBN}
6837a0a2 1662commands, and their documentation, for the regular expression specified in
99e008fe 1663@var{args}. It prints out all matches found. For example:
6837a0a2
DB
1664
1665@smallexample
1666apropos reload
1667@end smallexample
1668
b37052ae
EZ
1669@noindent
1670results in:
6837a0a2
DB
1671
1672@smallexample
6d2ebf8b
SS
1673@c @group
1674set symbol-reloading -- Set dynamic symbol table reloading
12c27660 1675 multiple times in one run
6d2ebf8b 1676show symbol-reloading -- Show dynamic symbol table reloading
12c27660 1677 multiple times in one run
6d2ebf8b 1678@c @end group
6837a0a2
DB
1679@end smallexample
1680
c906108c
SS
1681@kindex complete
1682@item complete @var{args}
1683The @code{complete @var{args}} command lists all the possible completions
1684for the beginning of a command. Use @var{args} to specify the beginning of the
1685command you want completed. For example:
1686
1687@smallexample
1688complete i
1689@end smallexample
1690
1691@noindent results in:
1692
1693@smallexample
1694@group
2df3850c
JM
1695if
1696ignore
c906108c
SS
1697info
1698inspect
c906108c
SS
1699@end group
1700@end smallexample
1701
1702@noindent This is intended for use by @sc{gnu} Emacs.
1703@end table
1704
1705In addition to @code{help}, you can use the @value{GDBN} commands @code{info}
1706and @code{show} to inquire about the state of your program, or the state
1707of @value{GDBN} itself. Each command supports many topics of inquiry; this
1708manual introduces each of them in the appropriate context. The listings
1709under @code{info} and under @code{show} in the Index point to
1710all the sub-commands. @xref{Index}.
1711
1712@c @group
1713@table @code
1714@kindex info
41afff9a 1715@kindex i @r{(@code{info})}
c906108c
SS
1716@item info
1717This command (abbreviated @code{i}) is for describing the state of your
cda4ce5a 1718program. For example, you can show the arguments passed to a function
c906108c
SS
1719with @code{info args}, list the registers currently in use with @code{info
1720registers}, or list the breakpoints you have set with @code{info breakpoints}.
1721You can get a complete list of the @code{info} sub-commands with
1722@w{@code{help info}}.
1723
1724@kindex set
1725@item set
5d161b24 1726You can assign the result of an expression to an environment variable with
c906108c
SS
1727@code{set}. For example, you can set the @value{GDBN} prompt to a $-sign with
1728@code{set prompt $}.
1729
1730@kindex show
1731@item show
5d161b24 1732In contrast to @code{info}, @code{show} is for describing the state of
c906108c
SS
1733@value{GDBN} itself.
1734You can change most of the things you can @code{show}, by using the
1735related command @code{set}; for example, you can control what number
1736system is used for displays with @code{set radix}, or simply inquire
1737which is currently in use with @code{show radix}.
1738
1739@kindex info set
1740To display all the settable parameters and their current
1741values, you can use @code{show} with no arguments; you may also use
1742@code{info set}. Both commands produce the same display.
1743@c FIXME: "info set" violates the rule that "info" is for state of
1744@c FIXME...program. Ck w/ GNU: "info set" to be called something else,
1745@c FIXME...or change desc of rule---eg "state of prog and debugging session"?
1746@end table
1747@c @end group
1748
1749Here are three miscellaneous @code{show} subcommands, all of which are
1750exceptional in lacking corresponding @code{set} commands:
1751
1752@table @code
1753@kindex show version
9c16f35a 1754@cindex @value{GDBN} version number
c906108c
SS
1755@item show version
1756Show what version of @value{GDBN} is running. You should include this
2df3850c
JM
1757information in @value{GDBN} bug-reports. If multiple versions of
1758@value{GDBN} are in use at your site, you may need to determine which
1759version of @value{GDBN} you are running; as @value{GDBN} evolves, new
1760commands are introduced, and old ones may wither away. Also, many
1761system vendors ship variant versions of @value{GDBN}, and there are
96a2c332 1762variant versions of @value{GDBN} in @sc{gnu}/Linux distributions as well.
2df3850c
JM
1763The version number is the same as the one announced when you start
1764@value{GDBN}.
c906108c
SS
1765
1766@kindex show copying
09d4efe1 1767@kindex info copying
9c16f35a 1768@cindex display @value{GDBN} copyright
c906108c 1769@item show copying
09d4efe1 1770@itemx info copying
c906108c
SS
1771Display information about permission for copying @value{GDBN}.
1772
1773@kindex show warranty
09d4efe1 1774@kindex info warranty
c906108c 1775@item show warranty
09d4efe1 1776@itemx info warranty
2df3850c 1777Display the @sc{gnu} ``NO WARRANTY'' statement, or a warranty,
96a2c332 1778if your version of @value{GDBN} comes with one.
2df3850c 1779
c906108c
SS
1780@end table
1781
6d2ebf8b 1782@node Running
c906108c
SS
1783@chapter Running Programs Under @value{GDBN}
1784
1785When you run a program under @value{GDBN}, you must first generate
1786debugging information when you compile it.
7a292a7a
SS
1787
1788You may start @value{GDBN} with its arguments, if any, in an environment
1789of your choice. If you are doing native debugging, you may redirect
1790your program's input and output, debug an already running process, or
1791kill a child process.
c906108c
SS
1792
1793@menu
1794* Compilation:: Compiling for debugging
1795* Starting:: Starting your program
c906108c
SS
1796* Arguments:: Your program's arguments
1797* Environment:: Your program's environment
c906108c
SS
1798
1799* Working Directory:: Your program's working directory
1800* Input/Output:: Your program's input and output
1801* Attach:: Debugging an already-running process
1802* Kill Process:: Killing the child process
c906108c 1803
6c95b8df 1804* Inferiors and Programs:: Debugging multiple inferiors and programs
c906108c 1805* Threads:: Debugging programs with multiple threads
6c95b8df 1806* Forks:: Debugging forks
5c95884b 1807* Checkpoint/Restart:: Setting a @emph{bookmark} to return to later
c906108c
SS
1808@end menu
1809
6d2ebf8b 1810@node Compilation
79a6e687 1811@section Compiling for Debugging
c906108c
SS
1812
1813In order to debug a program effectively, you need to generate
1814debugging information when you compile it. This debugging information
1815is stored in the object file; it describes the data type of each
1816variable or function and the correspondence between source line numbers
1817and addresses in the executable code.
1818
1819To request debugging information, specify the @samp{-g} option when you run
1820the compiler.
1821
514c4d71 1822Programs that are to be shipped to your customers are compiled with
edb3359d 1823optimizations, using the @samp{-O} compiler option. However, some
514c4d71
EZ
1824compilers are unable to handle the @samp{-g} and @samp{-O} options
1825together. Using those compilers, you cannot generate optimized
c906108c
SS
1826executables containing debugging information.
1827
514c4d71 1828@value{NGCC}, the @sc{gnu} C/C@t{++} compiler, supports @samp{-g} with or
53a5351d
JM
1829without @samp{-O}, making it possible to debug optimized code. We
1830recommend that you @emph{always} use @samp{-g} whenever you compile a
1831program. You may think your program is correct, but there is no sense
edb3359d 1832in pushing your luck. For more information, see @ref{Optimized Code}.
c906108c
SS
1833
1834Older versions of the @sc{gnu} C compiler permitted a variant option
1835@w{@samp{-gg}} for debugging information. @value{GDBN} no longer supports this
1836format; if your @sc{gnu} C compiler has this option, do not use it.
1837
514c4d71
EZ
1838@value{GDBN} knows about preprocessor macros and can show you their
1839expansion (@pxref{Macros}). Most compilers do not include information
1840about preprocessor macros in the debugging information if you specify
1841the @option{-g} flag alone, because this information is rather large.
1842Version 3.1 and later of @value{NGCC}, the @sc{gnu} C compiler,
1843provides macro information if you specify the options
1844@option{-gdwarf-2} and @option{-g3}; the former option requests
1845debugging information in the Dwarf 2 format, and the latter requests
1846``extra information''. In the future, we hope to find more compact
1847ways to represent macro information, so that it can be included with
1848@option{-g} alone.
1849
c906108c 1850@need 2000
6d2ebf8b 1851@node Starting
79a6e687 1852@section Starting your Program
c906108c
SS
1853@cindex starting
1854@cindex running
1855
1856@table @code
1857@kindex run
41afff9a 1858@kindex r @r{(@code{run})}
c906108c
SS
1859@item run
1860@itemx r
7a292a7a
SS
1861Use the @code{run} command to start your program under @value{GDBN}.
1862You must first specify the program name (except on VxWorks) with an
1863argument to @value{GDBN} (@pxref{Invocation, ,Getting In and Out of
1864@value{GDBN}}), or by using the @code{file} or @code{exec-file} command
79a6e687 1865(@pxref{Files, ,Commands to Specify Files}).
c906108c
SS
1866
1867@end table
1868
c906108c
SS
1869If you are running your program in an execution environment that
1870supports processes, @code{run} creates an inferior process and makes
8edfe269
DJ
1871that process run your program. In some environments without processes,
1872@code{run} jumps to the start of your program. Other targets,
1873like @samp{remote}, are always running. If you get an error
1874message like this one:
1875
1876@smallexample
1877The "remote" target does not support "run".
1878Try "help target" or "continue".
1879@end smallexample
1880
1881@noindent
1882then use @code{continue} to run your program. You may need @code{load}
1883first (@pxref{load}).
c906108c
SS
1884
1885The execution of a program is affected by certain information it
1886receives from its superior. @value{GDBN} provides ways to specify this
1887information, which you must do @emph{before} starting your program. (You
1888can change it after starting your program, but such changes only affect
1889your program the next time you start it.) This information may be
1890divided into four categories:
1891
1892@table @asis
1893@item The @emph{arguments.}
1894Specify the arguments to give your program as the arguments of the
1895@code{run} command. If a shell is available on your target, the shell
1896is used to pass the arguments, so that you may use normal conventions
1897(such as wildcard expansion or variable substitution) in describing
1898the arguments.
1899In Unix systems, you can control which shell is used with the
1900@code{SHELL} environment variable.
79a6e687 1901@xref{Arguments, ,Your Program's Arguments}.
c906108c
SS
1902
1903@item The @emph{environment.}
1904Your program normally inherits its environment from @value{GDBN}, but you can
1905use the @value{GDBN} commands @code{set environment} and @code{unset
1906environment} to change parts of the environment that affect
79a6e687 1907your program. @xref{Environment, ,Your Program's Environment}.
c906108c
SS
1908
1909@item The @emph{working directory.}
1910Your program inherits its working directory from @value{GDBN}. You can set
1911the @value{GDBN} working directory with the @code{cd} command in @value{GDBN}.
79a6e687 1912@xref{Working Directory, ,Your Program's Working Directory}.
c906108c
SS
1913
1914@item The @emph{standard input and output.}
1915Your program normally uses the same device for standard input and
1916standard output as @value{GDBN} is using. You can redirect input and output
1917in the @code{run} command line, or you can use the @code{tty} command to
1918set a different device for your program.
79a6e687 1919@xref{Input/Output, ,Your Program's Input and Output}.
c906108c
SS
1920
1921@cindex pipes
1922@emph{Warning:} While input and output redirection work, you cannot use
1923pipes to pass the output of the program you are debugging to another
1924program; if you attempt this, @value{GDBN} is likely to wind up debugging the
1925wrong program.
1926@end table
c906108c
SS
1927
1928When you issue the @code{run} command, your program begins to execute
79a6e687 1929immediately. @xref{Stopping, ,Stopping and Continuing}, for discussion
c906108c
SS
1930of how to arrange for your program to stop. Once your program has
1931stopped, you may call functions in your program, using the @code{print}
1932or @code{call} commands. @xref{Data, ,Examining Data}.
1933
1934If the modification time of your symbol file has changed since the last
1935time @value{GDBN} read its symbols, @value{GDBN} discards its symbol
1936table, and reads it again. When it does this, @value{GDBN} tries to retain
1937your current breakpoints.
1938
4e8b0763
JB
1939@table @code
1940@kindex start
1941@item start
1942@cindex run to main procedure
1943The name of the main procedure can vary from language to language.
1944With C or C@t{++}, the main procedure name is always @code{main}, but
1945other languages such as Ada do not require a specific name for their
1946main procedure. The debugger provides a convenient way to start the
1947execution of the program and to stop at the beginning of the main
1948procedure, depending on the language used.
1949
1950The @samp{start} command does the equivalent of setting a temporary
1951breakpoint at the beginning of the main procedure and then invoking
1952the @samp{run} command.
1953
f018e82f
EZ
1954@cindex elaboration phase
1955Some programs contain an @dfn{elaboration} phase where some startup code is
1956executed before the main procedure is called. This depends on the
1957languages used to write your program. In C@t{++}, for instance,
4e8b0763
JB
1958constructors for static and global objects are executed before
1959@code{main} is called. It is therefore possible that the debugger stops
1960before reaching the main procedure. However, the temporary breakpoint
1961will remain to halt execution.
1962
1963Specify the arguments to give to your program as arguments to the
1964@samp{start} command. These arguments will be given verbatim to the
1965underlying @samp{run} command. Note that the same arguments will be
1966reused if no argument is provided during subsequent calls to
1967@samp{start} or @samp{run}.
1968
1969It is sometimes necessary to debug the program during elaboration. In
1970these cases, using the @code{start} command would stop the execution of
1971your program too late, as the program would have already completed the
1972elaboration phase. Under these circumstances, insert breakpoints in your
1973elaboration code before running your program.
ccd213ac
DJ
1974
1975@kindex set exec-wrapper
1976@item set exec-wrapper @var{wrapper}
1977@itemx show exec-wrapper
1978@itemx unset exec-wrapper
1979When @samp{exec-wrapper} is set, the specified wrapper is used to
1980launch programs for debugging. @value{GDBN} starts your program
1981with a shell command of the form @kbd{exec @var{wrapper}
1982@var{program}}. Quoting is added to @var{program} and its
1983arguments, but not to @var{wrapper}, so you should add quotes if
1984appropriate for your shell. The wrapper runs until it executes
1985your program, and then @value{GDBN} takes control.
1986
1987You can use any program that eventually calls @code{execve} with
1988its arguments as a wrapper. Several standard Unix utilities do
1989this, e.g.@: @code{env} and @code{nohup}. Any Unix shell script ending
1990with @code{exec "$@@"} will also work.
1991
1992For example, you can use @code{env} to pass an environment variable to
1993the debugged program, without setting the variable in your shell's
1994environment:
1995
1996@smallexample
1997(@value{GDBP}) set exec-wrapper env 'LD_PRELOAD=libtest.so'
1998(@value{GDBP}) run
1999@end smallexample
2000
2001This command is available when debugging locally on most targets, excluding
2002@sc{djgpp}, Cygwin, MS Windows, and QNX Neutrino.
2003
10568435
JK
2004@kindex set disable-randomization
2005@item set disable-randomization
2006@itemx set disable-randomization on
2007This option (enabled by default in @value{GDBN}) will turn off the native
2008randomization of the virtual address space of the started program. This option
2009is useful for multiple debugging sessions to make the execution better
2010reproducible and memory addresses reusable across debugging sessions.
2011
2012This feature is implemented only on @sc{gnu}/Linux. You can get the same
2013behavior using
2014
2015@smallexample
2016(@value{GDBP}) set exec-wrapper setarch `uname -m` -R
2017@end smallexample
2018
2019@item set disable-randomization off
2020Leave the behavior of the started executable unchanged. Some bugs rear their
2021ugly heads only when the program is loaded at certain addresses. If your bug
2022disappears when you run the program under @value{GDBN}, that might be because
2023@value{GDBN} by default disables the address randomization on platforms, such
2024as @sc{gnu}/Linux, which do that for stand-alone programs. Use @kbd{set
2025disable-randomization off} to try to reproduce such elusive bugs.
2026
2027The virtual address space randomization is implemented only on @sc{gnu}/Linux.
2028It protects the programs against some kinds of security attacks. In these
2029cases the attacker needs to know the exact location of a concrete executable
2030code. Randomizing its location makes it impossible to inject jumps misusing
2031a code at its expected addresses.
2032
2033Prelinking shared libraries provides a startup performance advantage but it
2034makes addresses in these libraries predictable for privileged processes by
2035having just unprivileged access at the target system. Reading the shared
2036library binary gives enough information for assembling the malicious code
2037misusing it. Still even a prelinked shared library can get loaded at a new
2038random address just requiring the regular relocation process during the
2039startup. Shared libraries not already prelinked are always loaded at
2040a randomly chosen address.
2041
2042Position independent executables (PIE) contain position independent code
2043similar to the shared libraries and therefore such executables get loaded at
2044a randomly chosen address upon startup. PIE executables always load even
2045already prelinked shared libraries at a random address. You can build such
2046executable using @command{gcc -fPIE -pie}.
2047
2048Heap (malloc storage), stack and custom mmap areas are always placed randomly
2049(as long as the randomization is enabled).
2050
2051@item show disable-randomization
2052Show the current setting of the explicit disable of the native randomization of
2053the virtual address space of the started program.
2054
4e8b0763
JB
2055@end table
2056
6d2ebf8b 2057@node Arguments
79a6e687 2058@section Your Program's Arguments
c906108c
SS
2059
2060@cindex arguments (to your program)
2061The arguments to your program can be specified by the arguments of the
5d161b24 2062@code{run} command.
c906108c
SS
2063They are passed to a shell, which expands wildcard characters and
2064performs redirection of I/O, and thence to your program. Your
2065@code{SHELL} environment variable (if it exists) specifies what shell
2066@value{GDBN} uses. If you do not define @code{SHELL}, @value{GDBN} uses
d4f3574e
SS
2067the default shell (@file{/bin/sh} on Unix).
2068
2069On non-Unix systems, the program is usually invoked directly by
2070@value{GDBN}, which emulates I/O redirection via the appropriate system
2071calls, and the wildcard characters are expanded by the startup code of
2072the program, not by the shell.
c906108c
SS
2073
2074@code{run} with no arguments uses the same arguments used by the previous
2075@code{run}, or those set by the @code{set args} command.
2076
c906108c 2077@table @code
41afff9a 2078@kindex set args
c906108c
SS
2079@item set args
2080Specify the arguments to be used the next time your program is run. If
2081@code{set args} has no arguments, @code{run} executes your program
2082with no arguments. Once you have run your program with arguments,
2083using @code{set args} before the next @code{run} is the only way to run
2084it again without arguments.
2085
2086@kindex show args
2087@item show args
2088Show the arguments to give your program when it is started.
2089@end table
2090
6d2ebf8b 2091@node Environment
79a6e687 2092@section Your Program's Environment
c906108c
SS
2093
2094@cindex environment (of your program)
2095The @dfn{environment} consists of a set of environment variables and
2096their values. Environment variables conventionally record such things as
2097your user name, your home directory, your terminal type, and your search
2098path for programs to run. Usually you set up environment variables with
2099the shell and they are inherited by all the other programs you run. When
2100debugging, it can be useful to try running your program with a modified
2101environment without having to start @value{GDBN} over again.
2102
2103@table @code
2104@kindex path
2105@item path @var{directory}
2106Add @var{directory} to the front of the @code{PATH} environment variable
17cc6a06
EZ
2107(the search path for executables) that will be passed to your program.
2108The value of @code{PATH} used by @value{GDBN} does not change.
d4f3574e
SS
2109You may specify several directory names, separated by whitespace or by a
2110system-dependent separator character (@samp{:} on Unix, @samp{;} on
2111MS-DOS and MS-Windows). If @var{directory} is already in the path, it
2112is moved to the front, so it is searched sooner.
c906108c
SS
2113
2114You can use the string @samp{$cwd} to refer to whatever is the current
2115working directory at the time @value{GDBN} searches the path. If you
2116use @samp{.} instead, it refers to the directory where you executed the
2117@code{path} command. @value{GDBN} replaces @samp{.} in the
2118@var{directory} argument (with the current path) before adding
2119@var{directory} to the search path.
2120@c 'path' is explicitly nonrepeatable, but RMS points out it is silly to
2121@c document that, since repeating it would be a no-op.
2122
2123@kindex show paths
2124@item show paths
2125Display the list of search paths for executables (the @code{PATH}
2126environment variable).
2127
2128@kindex show environment
2129@item show environment @r{[}@var{varname}@r{]}
2130Print the value of environment variable @var{varname} to be given to
2131your program when it starts. If you do not supply @var{varname},
2132print the names and values of all environment variables to be given to
2133your program. You can abbreviate @code{environment} as @code{env}.
2134
2135@kindex set environment
53a5351d 2136@item set environment @var{varname} @r{[}=@var{value}@r{]}
c906108c
SS
2137Set environment variable @var{varname} to @var{value}. The value
2138changes for your program only, not for @value{GDBN} itself. @var{value} may
2139be any string; the values of environment variables are just strings, and
2140any interpretation is supplied by your program itself. The @var{value}
2141parameter is optional; if it is eliminated, the variable is set to a
2142null value.
2143@c "any string" here does not include leading, trailing
2144@c blanks. Gnu asks: does anyone care?
2145
2146For example, this command:
2147
474c8240 2148@smallexample
c906108c 2149set env USER = foo
474c8240 2150@end smallexample
c906108c
SS
2151
2152@noindent
d4f3574e 2153tells the debugged program, when subsequently run, that its user is named
c906108c
SS
2154@samp{foo}. (The spaces around @samp{=} are used for clarity here; they
2155are not actually required.)
2156
2157@kindex unset environment
2158@item unset environment @var{varname}
2159Remove variable @var{varname} from the environment to be passed to your
2160program. This is different from @samp{set env @var{varname} =};
2161@code{unset environment} removes the variable from the environment,
2162rather than assigning it an empty value.
2163@end table
2164
d4f3574e
SS
2165@emph{Warning:} On Unix systems, @value{GDBN} runs your program using
2166the shell indicated
c906108c
SS
2167by your @code{SHELL} environment variable if it exists (or
2168@code{/bin/sh} if not). If your @code{SHELL} variable names a shell
2169that runs an initialization file---such as @file{.cshrc} for C-shell, or
2170@file{.bashrc} for BASH---any variables you set in that file affect
2171your program. You may wish to move setting of environment variables to
2172files that are only run when you sign on, such as @file{.login} or
2173@file{.profile}.
2174
6d2ebf8b 2175@node Working Directory
79a6e687 2176@section Your Program's Working Directory
c906108c
SS
2177
2178@cindex working directory (of your program)
2179Each time you start your program with @code{run}, it inherits its
2180working directory from the current working directory of @value{GDBN}.
2181The @value{GDBN} working directory is initially whatever it inherited
2182from its parent process (typically the shell), but you can specify a new
2183working directory in @value{GDBN} with the @code{cd} command.
2184
2185The @value{GDBN} working directory also serves as a default for the commands
2186that specify files for @value{GDBN} to operate on. @xref{Files, ,Commands to
79a6e687 2187Specify Files}.
c906108c
SS
2188
2189@table @code
2190@kindex cd
721c2651 2191@cindex change working directory
c906108c
SS
2192@item cd @var{directory}
2193Set the @value{GDBN} working directory to @var{directory}.
2194
2195@kindex pwd
2196@item pwd
2197Print the @value{GDBN} working directory.
2198@end table
2199
60bf7e09
EZ
2200It is generally impossible to find the current working directory of
2201the process being debugged (since a program can change its directory
2202during its run). If you work on a system where @value{GDBN} is
2203configured with the @file{/proc} support, you can use the @code{info
2204proc} command (@pxref{SVR4 Process Information}) to find out the
2205current working directory of the debuggee.
2206
6d2ebf8b 2207@node Input/Output
79a6e687 2208@section Your Program's Input and Output
c906108c
SS
2209
2210@cindex redirection
2211@cindex i/o
2212@cindex terminal
2213By default, the program you run under @value{GDBN} does input and output to
5d161b24 2214the same terminal that @value{GDBN} uses. @value{GDBN} switches the terminal
c906108c
SS
2215to its own terminal modes to interact with you, but it records the terminal
2216modes your program was using and switches back to them when you continue
2217running your program.
2218
2219@table @code
2220@kindex info terminal
2221@item info terminal
2222Displays information recorded by @value{GDBN} about the terminal modes your
2223program is using.
2224@end table
2225
2226You can redirect your program's input and/or output using shell
2227redirection with the @code{run} command. For example,
2228
474c8240 2229@smallexample
c906108c 2230run > outfile
474c8240 2231@end smallexample
c906108c
SS
2232
2233@noindent
2234starts your program, diverting its output to the file @file{outfile}.
2235
2236@kindex tty
2237@cindex controlling terminal
2238Another way to specify where your program should do input and output is
2239with the @code{tty} command. This command accepts a file name as
2240argument, and causes this file to be the default for future @code{run}
2241commands. It also resets the controlling terminal for the child
2242process, for future @code{run} commands. For example,
2243
474c8240 2244@smallexample
c906108c 2245tty /dev/ttyb
474c8240 2246@end smallexample
c906108c
SS
2247
2248@noindent
2249directs that processes started with subsequent @code{run} commands
2250default to do input and output on the terminal @file{/dev/ttyb} and have
2251that as their controlling terminal.
2252
2253An explicit redirection in @code{run} overrides the @code{tty} command's
2254effect on the input/output device, but not its effect on the controlling
2255terminal.
2256
2257When you use the @code{tty} command or redirect input in the @code{run}
2258command, only the input @emph{for your program} is affected. The input
3cb3b8df
BR
2259for @value{GDBN} still comes from your terminal. @code{tty} is an alias
2260for @code{set inferior-tty}.
2261
2262@cindex inferior tty
2263@cindex set inferior controlling terminal
2264You can use the @code{show inferior-tty} command to tell @value{GDBN} to
2265display the name of the terminal that will be used for future runs of your
2266program.
2267
2268@table @code
2269@item set inferior-tty /dev/ttyb
2270@kindex set inferior-tty
2271Set the tty for the program being debugged to /dev/ttyb.
2272
2273@item show inferior-tty
2274@kindex show inferior-tty
2275Show the current tty for the program being debugged.
2276@end table
c906108c 2277
6d2ebf8b 2278@node Attach
79a6e687 2279@section Debugging an Already-running Process
c906108c
SS
2280@kindex attach
2281@cindex attach
2282
2283@table @code
2284@item attach @var{process-id}
2285This command attaches to a running process---one that was started
2286outside @value{GDBN}. (@code{info files} shows your active
2287targets.) The command takes as argument a process ID. The usual way to
09d4efe1 2288find out the @var{process-id} of a Unix process is with the @code{ps} utility,
c906108c
SS
2289or with the @samp{jobs -l} shell command.
2290
2291@code{attach} does not repeat if you press @key{RET} a second time after
2292executing the command.
2293@end table
2294
2295To use @code{attach}, your program must be running in an environment
2296which supports processes; for example, @code{attach} does not work for
2297programs on bare-board targets that lack an operating system. You must
2298also have permission to send the process a signal.
2299
2300When you use @code{attach}, the debugger finds the program running in
2301the process first by looking in the current working directory, then (if
2302the program is not found) by using the source file search path
79a6e687 2303(@pxref{Source Path, ,Specifying Source Directories}). You can also use
c906108c
SS
2304the @code{file} command to load the program. @xref{Files, ,Commands to
2305Specify Files}.
2306
2307The first thing @value{GDBN} does after arranging to debug the specified
2308process is to stop it. You can examine and modify an attached process
53a5351d
JM
2309with all the @value{GDBN} commands that are ordinarily available when
2310you start processes with @code{run}. You can insert breakpoints; you
2311can step and continue; you can modify storage. If you would rather the
2312process continue running, you may use the @code{continue} command after
c906108c
SS
2313attaching @value{GDBN} to the process.
2314
2315@table @code
2316@kindex detach
2317@item detach
2318When you have finished debugging the attached process, you can use the
2319@code{detach} command to release it from @value{GDBN} control. Detaching
2320the process continues its execution. After the @code{detach} command,
2321that process and @value{GDBN} become completely independent once more, and you
2322are ready to @code{attach} another process or start one with @code{run}.
2323@code{detach} does not repeat if you press @key{RET} again after
2324executing the command.
2325@end table
2326
159fcc13
JK
2327If you exit @value{GDBN} while you have an attached process, you detach
2328that process. If you use the @code{run} command, you kill that process.
2329By default, @value{GDBN} asks for confirmation if you try to do either of these
2330things; you can control whether or not you need to confirm by using the
2331@code{set confirm} command (@pxref{Messages/Warnings, ,Optional Warnings and
79a6e687 2332Messages}).
c906108c 2333
6d2ebf8b 2334@node Kill Process
79a6e687 2335@section Killing the Child Process
c906108c
SS
2336
2337@table @code
2338@kindex kill
2339@item kill
2340Kill the child process in which your program is running under @value{GDBN}.
2341@end table
2342
2343This command is useful if you wish to debug a core dump instead of a
2344running process. @value{GDBN} ignores any core dump file while your program
2345is running.
2346
2347On some operating systems, a program cannot be executed outside @value{GDBN}
2348while you have breakpoints set on it inside @value{GDBN}. You can use the
2349@code{kill} command in this situation to permit running your program
2350outside the debugger.
2351
2352The @code{kill} command is also useful if you wish to recompile and
2353relink your program, since on many systems it is impossible to modify an
2354executable file while it is running in a process. In this case, when you
2355next type @code{run}, @value{GDBN} notices that the file has changed, and
2356reads the symbol table again (while trying to preserve your current
2357breakpoint settings).
2358
6c95b8df
PA
2359@node Inferiors and Programs
2360@section Debugging Multiple Inferiors and Programs
b77209e0 2361
6c95b8df
PA
2362@value{GDBN} lets you run and debug multiple programs in a single
2363session. In addition, @value{GDBN} on some systems may let you run
2364several programs simultaneously (otherwise you have to exit from one
2365before starting another). In the most general case, you can have
2366multiple threads of execution in each of multiple processes, launched
2367from multiple executables.
b77209e0
PA
2368
2369@cindex inferior
2370@value{GDBN} represents the state of each program execution with an
2371object called an @dfn{inferior}. An inferior typically corresponds to
2372a process, but is more general and applies also to targets that do not
2373have processes. Inferiors may be created before a process runs, and
6c95b8df
PA
2374may be retained after a process exits. Inferiors have unique
2375identifiers that are different from process ids. Usually each
2376inferior will also have its own distinct address space, although some
2377embedded targets may have several inferiors running in different parts
2378of a single address space. Each inferior may in turn have multiple
2379threads running in it.
b77209e0 2380
6c95b8df
PA
2381To find out what inferiors exist at any moment, use @w{@code{info
2382inferiors}}:
b77209e0
PA
2383
2384@table @code
2385@kindex info inferiors
2386@item info inferiors
2387Print a list of all inferiors currently being managed by @value{GDBN}.
3a1ff0b6
PA
2388
2389@value{GDBN} displays for each inferior (in this order):
2390
2391@enumerate
2392@item
2393the inferior number assigned by @value{GDBN}
2394
2395@item
2396the target system's inferior identifier
6c95b8df
PA
2397
2398@item
2399the name of the executable the inferior is running.
2400
3a1ff0b6
PA
2401@end enumerate
2402
2403@noindent
2404An asterisk @samp{*} preceding the @value{GDBN} inferior number
2405indicates the current inferior.
2406
2407For example,
2277426b 2408@end table
3a1ff0b6
PA
2409@c end table here to get a little more width for example
2410
2411@smallexample
2412(@value{GDBP}) info inferiors
6c95b8df
PA
2413 Num Description Executable
2414 2 process 2307 hello
2415* 1 process 3401 goodbye
3a1ff0b6 2416@end smallexample
2277426b
PA
2417
2418To switch focus between inferiors, use the @code{inferior} command:
2419
2420@table @code
3a1ff0b6
PA
2421@kindex inferior @var{infno}
2422@item inferior @var{infno}
2423Make inferior number @var{infno} the current inferior. The argument
2424@var{infno} is the inferior number assigned by @value{GDBN}, as shown
2425in the first field of the @samp{info inferiors} display.
2277426b
PA
2426@end table
2427
6c95b8df
PA
2428
2429You can get multiple executables into a debugging session via the
2430@code{add-inferior} and @w{@code{clone-inferior}} commands. On some
2431systems @value{GDBN} can add inferiors to the debug session
2432automatically by following calls to @code{fork} and @code{exec}. To
2433remove inferiors from the debugging session use the
2434@w{@code{remove-inferior}} command.
2435
2436@table @code
2437@kindex add-inferior
2438@item add-inferior [ -copies @var{n} ] [ -exec @var{executable} ]
2439Adds @var{n} inferiors to be run using @var{executable} as the
2440executable. @var{n} defaults to 1. If no executable is specified,
2441the inferiors begins empty, with no program. You can still assign or
2442change the program assigned to the inferior at any time by using the
2443@code{file} command with the executable name as its argument.
2444
2445@kindex clone-inferior
2446@item clone-inferior [ -copies @var{n} ] [ @var{infno} ]
2447Adds @var{n} inferiors ready to execute the same program as inferior
2448@var{infno}. @var{n} defaults to 1. @var{infno} defaults to the
2449number of the current inferior. This is a convenient command when you
2450want to run another instance of the inferior you are debugging.
2451
2452@smallexample
2453(@value{GDBP}) info inferiors
2454 Num Description Executable
2455* 1 process 29964 helloworld
2456(@value{GDBP}) clone-inferior
2457Added inferior 2.
24581 inferiors added.
2459(@value{GDBP}) info inferiors
2460 Num Description Executable
2461 2 <null> helloworld
2462* 1 process 29964 helloworld
2463@end smallexample
2464
2465You can now simply switch focus to inferior 2 and run it.
2466
2467@kindex remove-inferior
2468@item remove-inferior @var{infno}
2469Removes the inferior @var{infno}. It is not possible to remove an
2470inferior that is running with this command. For those, use the
2471@code{kill} or @code{detach} command first.
2472
2473@end table
2474
2475To quit debugging one of the running inferiors that is not the current
2476inferior, you can either detach from it by using the @w{@code{detach
2477inferior}} command (allowing it to run independently), or kill it
2478using the @w{@code{kill inferior}} command:
2277426b
PA
2479
2480@table @code
3a1ff0b6
PA
2481@kindex detach inferior @var{infno}
2482@item detach inferior @var{infno}
2277426b 2483Detach from the inferior identified by @value{GDBN} inferior number
3a1ff0b6 2484@var{infno}, and remove it from the inferior list.
2277426b 2485
3a1ff0b6
PA
2486@kindex kill inferior @var{infno}
2487@item kill inferior @var{infno}
2277426b 2488Kill the inferior identified by @value{GDBN} inferior number
3a1ff0b6 2489@var{infno}, and remove it from the inferior list.
2277426b
PA
2490@end table
2491
6c95b8df
PA
2492After the successful completion of a command such as @code{detach},
2493@code{detach inferior}, @code{kill} or @code{kill inferior}, or after
2494a normal process exit, the inferior is still valid and listed with
2495@code{info inferiors}, ready to be restarted.
2496
2497
2277426b
PA
2498To be notified when inferiors are started or exit under @value{GDBN}'s
2499control use @w{@code{set print inferior-events}}:
b77209e0 2500
2277426b 2501@table @code
b77209e0
PA
2502@kindex set print inferior-events
2503@cindex print messages on inferior start and exit
2504@item set print inferior-events
2505@itemx set print inferior-events on
2506@itemx set print inferior-events off
2507The @code{set print inferior-events} command allows you to enable or
2508disable printing of messages when @value{GDBN} notices that new
2509inferiors have started or that inferiors have exited or have been
2510detached. By default, these messages will not be printed.
2511
2512@kindex show print inferior-events
2513@item show print inferior-events
2514Show whether messages will be printed when @value{GDBN} detects that
2515inferiors have started, exited or have been detached.
2516@end table
2517
6c95b8df
PA
2518Many commands will work the same with multiple programs as with a
2519single program: e.g., @code{print myglobal} will simply display the
2520value of @code{myglobal} in the current inferior.
2521
2522
2523Occasionaly, when debugging @value{GDBN} itself, it may be useful to
2524get more info about the relationship of inferiors, programs, address
2525spaces in a debug session. You can do that with the @w{@code{maint
2526info program-spaces}} command.
2527
2528@table @code
2529@kindex maint info program-spaces
2530@item maint info program-spaces
2531Print a list of all program spaces currently being managed by
2532@value{GDBN}.
2533
2534@value{GDBN} displays for each program space (in this order):
2535
2536@enumerate
2537@item
2538the program space number assigned by @value{GDBN}
2539
2540@item
2541the name of the executable loaded into the program space, with e.g.,
2542the @code{file} command.
2543
2544@end enumerate
2545
2546@noindent
2547An asterisk @samp{*} preceding the @value{GDBN} program space number
2548indicates the current program space.
2549
2550In addition, below each program space line, @value{GDBN} prints extra
2551information that isn't suitable to display in tabular form. For
2552example, the list of inferiors bound to the program space.
2553
2554@smallexample
2555(@value{GDBP}) maint info program-spaces
2556 Id Executable
2557 2 goodbye
2558 Bound inferiors: ID 1 (process 21561)
2559* 1 hello
2560@end smallexample
2561
2562Here we can see that no inferior is running the program @code{hello},
2563while @code{process 21561} is running the program @code{goodbye}. On
2564some targets, it is possible that multiple inferiors are bound to the
2565same program space. The most common example is that of debugging both
2566the parent and child processes of a @code{vfork} call. For example,
2567
2568@smallexample
2569(@value{GDBP}) maint info program-spaces
2570 Id Executable
2571* 1 vfork-test
2572 Bound inferiors: ID 2 (process 18050), ID 1 (process 18045)
2573@end smallexample
2574
2575Here, both inferior 2 and inferior 1 are running in the same program
2576space as a result of inferior 1 having executed a @code{vfork} call.
2577@end table
2578
6d2ebf8b 2579@node Threads
79a6e687 2580@section Debugging Programs with Multiple Threads
c906108c
SS
2581
2582@cindex threads of execution
2583@cindex multiple threads
2584@cindex switching threads
2585In some operating systems, such as HP-UX and Solaris, a single program
2586may have more than one @dfn{thread} of execution. The precise semantics
2587of threads differ from one operating system to another, but in general
2588the threads of a single program are akin to multiple processes---except
2589that they share one address space (that is, they can all examine and
2590modify the same variables). On the other hand, each thread has its own
2591registers and execution stack, and perhaps private memory.
2592
2593@value{GDBN} provides these facilities for debugging multi-thread
2594programs:
2595
2596@itemize @bullet
2597@item automatic notification of new threads
2598@item @samp{thread @var{threadno}}, a command to switch among threads
2599@item @samp{info threads}, a command to inquire about existing threads
5d161b24 2600@item @samp{thread apply [@var{threadno}] [@var{all}] @var{args}},
c906108c
SS
2601a command to apply a command to a list of threads
2602@item thread-specific breakpoints
93815fbf
VP
2603@item @samp{set print thread-events}, which controls printing of
2604messages on thread start and exit.
17a37d48
PP
2605@item @samp{set libthread-db-search-path @var{path}}, which lets
2606the user specify which @code{libthread_db} to use if the default choice
2607isn't compatible with the program.
c906108c
SS
2608@end itemize
2609
c906108c
SS
2610@quotation
2611@emph{Warning:} These facilities are not yet available on every
2612@value{GDBN} configuration where the operating system supports threads.
2613If your @value{GDBN} does not support threads, these commands have no
2614effect. For example, a system without thread support shows no output
2615from @samp{info threads}, and always rejects the @code{thread} command,
2616like this:
2617
2618@smallexample
2619(@value{GDBP}) info threads
2620(@value{GDBP}) thread 1
2621Thread ID 1 not known. Use the "info threads" command to
2622see the IDs of currently known threads.
2623@end smallexample
2624@c FIXME to implementors: how hard would it be to say "sorry, this GDB
2625@c doesn't support threads"?
2626@end quotation
c906108c
SS
2627
2628@cindex focus of debugging
2629@cindex current thread
2630The @value{GDBN} thread debugging facility allows you to observe all
2631threads while your program runs---but whenever @value{GDBN} takes
2632control, one thread in particular is always the focus of debugging.
2633This thread is called the @dfn{current thread}. Debugging commands show
2634program information from the perspective of the current thread.
2635
41afff9a 2636@cindex @code{New} @var{systag} message
c906108c
SS
2637@cindex thread identifier (system)
2638@c FIXME-implementors!! It would be more helpful if the [New...] message
2639@c included GDB's numeric thread handle, so you could just go to that
2640@c thread without first checking `info threads'.
2641Whenever @value{GDBN} detects a new thread in your program, it displays
2642the target system's identification for the thread with a message in the
2643form @samp{[New @var{systag}]}. @var{systag} is a thread identifier
2644whose form varies depending on the particular system. For example, on
8807d78b 2645@sc{gnu}/Linux, you might see
c906108c 2646
474c8240 2647@smallexample
8807d78b 2648[New Thread 46912507313328 (LWP 25582)]
474c8240 2649@end smallexample
c906108c
SS
2650
2651@noindent
2652when @value{GDBN} notices a new thread. In contrast, on an SGI system,
2653the @var{systag} is simply something like @samp{process 368}, with no
2654further qualifier.
2655
2656@c FIXME!! (1) Does the [New...] message appear even for the very first
2657@c thread of a program, or does it only appear for the
6ca652b0 2658@c second---i.e.@: when it becomes obvious we have a multithread
c906108c
SS
2659@c program?
2660@c (2) *Is* there necessarily a first thread always? Or do some
2661@c multithread systems permit starting a program with multiple
5d161b24 2662@c threads ab initio?
c906108c
SS
2663
2664@cindex thread number
2665@cindex thread identifier (GDB)
2666For debugging purposes, @value{GDBN} associates its own thread
2667number---always a single integer---with each thread in your program.
2668
2669@table @code
2670@kindex info threads
2671@item info threads
2672Display a summary of all threads currently in your
2673program. @value{GDBN} displays for each thread (in this order):
2674
2675@enumerate
09d4efe1
EZ
2676@item
2677the thread number assigned by @value{GDBN}
c906108c 2678
09d4efe1
EZ
2679@item
2680the target system's thread identifier (@var{systag})
c906108c 2681
09d4efe1
EZ
2682@item
2683the current stack frame summary for that thread
c906108c
SS
2684@end enumerate
2685
2686@noindent
2687An asterisk @samp{*} to the left of the @value{GDBN} thread number
2688indicates the current thread.
2689
5d161b24 2690For example,
c906108c
SS
2691@end table
2692@c end table here to get a little more width for example
2693
2694@smallexample
2695(@value{GDBP}) info threads
2696 3 process 35 thread 27 0x34e5 in sigpause ()
2697 2 process 35 thread 23 0x34e5 in sigpause ()
2698* 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8)
2699 at threadtest.c:68
2700@end smallexample
53a5351d
JM
2701
2702On HP-UX systems:
c906108c 2703
4644b6e3
EZ
2704@cindex debugging multithreaded programs (on HP-UX)
2705@cindex thread identifier (GDB), on HP-UX
c906108c
SS
2706For debugging purposes, @value{GDBN} associates its own thread
2707number---a small integer assigned in thread-creation order---with each
2708thread in your program.
2709
41afff9a
EZ
2710@cindex @code{New} @var{systag} message, on HP-UX
2711@cindex thread identifier (system), on HP-UX
c906108c
SS
2712@c FIXME-implementors!! It would be more helpful if the [New...] message
2713@c included GDB's numeric thread handle, so you could just go to that
2714@c thread without first checking `info threads'.
2715Whenever @value{GDBN} detects a new thread in your program, it displays
2716both @value{GDBN}'s thread number and the target system's identification for the thread with a message in the
2717form @samp{[New @var{systag}]}. @var{systag} is a thread identifier
2718whose form varies depending on the particular system. For example, on
2719HP-UX, you see
2720
474c8240 2721@smallexample
c906108c 2722[New thread 2 (system thread 26594)]
474c8240 2723@end smallexample
c906108c
SS
2724
2725@noindent
5d161b24 2726when @value{GDBN} notices a new thread.
c906108c
SS
2727
2728@table @code
4644b6e3 2729@kindex info threads (HP-UX)
c906108c
SS
2730@item info threads
2731Display a summary of all threads currently in your
2732program. @value{GDBN} displays for each thread (in this order):
2733
2734@enumerate
2735@item the thread number assigned by @value{GDBN}
2736
2737@item the target system's thread identifier (@var{systag})
2738
2739@item the current stack frame summary for that thread
2740@end enumerate
2741
2742@noindent
2743An asterisk @samp{*} to the left of the @value{GDBN} thread number
2744indicates the current thread.
2745
5d161b24 2746For example,
c906108c
SS
2747@end table
2748@c end table here to get a little more width for example
2749
474c8240 2750@smallexample
c906108c 2751(@value{GDBP}) info threads
6d2ebf8b
SS
2752 * 3 system thread 26607 worker (wptr=0x7b09c318 "@@") \@*
2753 at quicksort.c:137
2754 2 system thread 26606 0x7b0030d8 in __ksleep () \@*
2755 from /usr/lib/libc.2
2756 1 system thread 27905 0x7b003498 in _brk () \@*
2757 from /usr/lib/libc.2
474c8240 2758@end smallexample
c906108c 2759
c45da7e6
EZ
2760On Solaris, you can display more information about user threads with a
2761Solaris-specific command:
2762
2763@table @code
2764@item maint info sol-threads
2765@kindex maint info sol-threads
2766@cindex thread info (Solaris)
2767Display info on Solaris user threads.
2768@end table
2769
c906108c
SS
2770@table @code
2771@kindex thread @var{threadno}
2772@item thread @var{threadno}
2773Make thread number @var{threadno} the current thread. The command
2774argument @var{threadno} is the internal @value{GDBN} thread number, as
2775shown in the first field of the @samp{info threads} display.
2776@value{GDBN} responds by displaying the system identifier of the thread
2777you selected, and its current stack frame summary:
2778
2779@smallexample
2780@c FIXME!! This example made up; find a @value{GDBN} w/threads and get real one
2781(@value{GDBP}) thread 2
c906108c 2782[Switching to process 35 thread 23]
c906108c
SS
27830x34e5 in sigpause ()
2784@end smallexample
2785
2786@noindent
2787As with the @samp{[New @dots{}]} message, the form of the text after
2788@samp{Switching to} depends on your system's conventions for identifying
5d161b24 2789threads.
c906108c 2790
6aed2dbc
SS
2791@vindex $_thread@r{, convenience variable}
2792The debugger convenience variable @samp{$_thread} contains the number
2793of the current thread. You may find this useful in writing breakpoint
2794conditional expressions, command scripts, and so forth. See
2795@xref{Convenience Vars,, Convenience Variables}, for general
2796information on convenience variables.
2797
9c16f35a 2798@kindex thread apply
638ac427 2799@cindex apply command to several threads
839c27b7
EZ
2800@item thread apply [@var{threadno}] [@var{all}] @var{command}
2801The @code{thread apply} command allows you to apply the named
2802@var{command} to one or more threads. Specify the numbers of the
2803threads that you want affected with the command argument
2804@var{threadno}. It can be a single thread number, one of the numbers
2805shown in the first field of the @samp{info threads} display; or it
2806could be a range of thread numbers, as in @code{2-4}. To apply a
2807command to all threads, type @kbd{thread apply all @var{command}}.
93815fbf
VP
2808
2809@kindex set print thread-events
2810@cindex print messages on thread start and exit
2811@item set print thread-events
2812@itemx set print thread-events on
2813@itemx set print thread-events off
2814The @code{set print thread-events} command allows you to enable or
2815disable printing of messages when @value{GDBN} notices that new threads have
2816started or that threads have exited. By default, these messages will
2817be printed if detection of these events is supported by the target.
2818Note that these messages cannot be disabled on all targets.
2819
2820@kindex show print thread-events
2821@item show print thread-events
2822Show whether messages will be printed when @value{GDBN} detects that threads
2823have started and exited.
c906108c
SS
2824@end table
2825
79a6e687 2826@xref{Thread Stops,,Stopping and Starting Multi-thread Programs}, for
c906108c
SS
2827more information about how @value{GDBN} behaves when you stop and start
2828programs with multiple threads.
2829
79a6e687 2830@xref{Set Watchpoints,,Setting Watchpoints}, for information about
c906108c 2831watchpoints in programs with multiple threads.
c906108c 2832
17a37d48
PP
2833@table @code
2834@kindex set libthread-db-search-path
2835@cindex search path for @code{libthread_db}
2836@item set libthread-db-search-path @r{[}@var{path}@r{]}
2837If this variable is set, @var{path} is a colon-separated list of
2838directories @value{GDBN} will use to search for @code{libthread_db}.
2839If you omit @var{path}, @samp{libthread-db-search-path} will be reset to
2840an empty list.
2841
2842On @sc{gnu}/Linux and Solaris systems, @value{GDBN} uses a ``helper''
2843@code{libthread_db} library to obtain information about threads in the
2844inferior process. @value{GDBN} will use @samp{libthread-db-search-path}
2845to find @code{libthread_db}. If that fails, @value{GDBN} will continue
2846with default system shared library directories, and finally the directory
2847from which @code{libpthread} was loaded in the inferior process.
2848
2849For any @code{libthread_db} library @value{GDBN} finds in above directories,
2850@value{GDBN} attempts to initialize it with the current inferior process.
2851If this initialization fails (which could happen because of a version
2852mismatch between @code{libthread_db} and @code{libpthread}), @value{GDBN}
2853will unload @code{libthread_db}, and continue with the next directory.
2854If none of @code{libthread_db} libraries initialize successfully,
2855@value{GDBN} will issue a warning and thread debugging will be disabled.
2856
2857Setting @code{libthread-db-search-path} is currently implemented
2858only on some platforms.
2859
2860@kindex show libthread-db-search-path
2861@item show libthread-db-search-path
2862Display current libthread_db search path.
2863@end table
2864
6c95b8df
PA
2865@node Forks
2866@section Debugging Forks
c906108c
SS
2867
2868@cindex fork, debugging programs which call
2869@cindex multiple processes
2870@cindex processes, multiple
53a5351d
JM
2871On most systems, @value{GDBN} has no special support for debugging
2872programs which create additional processes using the @code{fork}
2873function. When a program forks, @value{GDBN} will continue to debug the
2874parent process and the child process will run unimpeded. If you have
2875set a breakpoint in any code which the child then executes, the child
2876will get a @code{SIGTRAP} signal which (unless it catches the signal)
2877will cause it to terminate.
c906108c
SS
2878
2879However, if you want to debug the child process there is a workaround
2880which isn't too painful. Put a call to @code{sleep} in the code which
2881the child process executes after the fork. It may be useful to sleep
2882only if a certain environment variable is set, or a certain file exists,
2883so that the delay need not occur when you don't want to run @value{GDBN}
2884on the child. While the child is sleeping, use the @code{ps} program to
2885get its process ID. Then tell @value{GDBN} (a new invocation of
2886@value{GDBN} if you are also debugging the parent process) to attach to
d4f3574e 2887the child process (@pxref{Attach}). From that point on you can debug
c906108c 2888the child process just like any other process which you attached to.
c906108c 2889
b51970ac
DJ
2890On some systems, @value{GDBN} provides support for debugging programs that
2891create additional processes using the @code{fork} or @code{vfork} functions.
2892Currently, the only platforms with this feature are HP-UX (11.x and later
a6b151f1 2893only?) and @sc{gnu}/Linux (kernel version 2.5.60 and later).
c906108c
SS
2894
2895By default, when a program forks, @value{GDBN} will continue to debug
2896the parent process and the child process will run unimpeded.
2897
2898If you want to follow the child process instead of the parent process,
2899use the command @w{@code{set follow-fork-mode}}.
2900
2901@table @code
2902@kindex set follow-fork-mode
2903@item set follow-fork-mode @var{mode}
2904Set the debugger response to a program call of @code{fork} or
2905@code{vfork}. A call to @code{fork} or @code{vfork} creates a new
9c16f35a 2906process. The @var{mode} argument can be:
c906108c
SS
2907
2908@table @code
2909@item parent
2910The original process is debugged after a fork. The child process runs
2df3850c 2911unimpeded. This is the default.
c906108c
SS
2912
2913@item child
2914The new process is debugged after a fork. The parent process runs
2915unimpeded.
2916
c906108c
SS
2917@end table
2918
9c16f35a 2919@kindex show follow-fork-mode
c906108c 2920@item show follow-fork-mode
2df3850c 2921Display the current debugger response to a @code{fork} or @code{vfork} call.
c906108c
SS
2922@end table
2923
5c95884b
MS
2924@cindex debugging multiple processes
2925On Linux, if you want to debug both the parent and child processes, use the
2926command @w{@code{set detach-on-fork}}.
2927
2928@table @code
2929@kindex set detach-on-fork
2930@item set detach-on-fork @var{mode}
2931Tells gdb whether to detach one of the processes after a fork, or
2932retain debugger control over them both.
2933
2934@table @code
2935@item on
2936The child process (or parent process, depending on the value of
2937@code{follow-fork-mode}) will be detached and allowed to run
2938independently. This is the default.
2939
2940@item off
2941Both processes will be held under the control of @value{GDBN}.
2942One process (child or parent, depending on the value of
2943@code{follow-fork-mode}) is debugged as usual, while the other
2944is held suspended.
2945
2946@end table
2947
11310833
NR
2948@kindex show detach-on-fork
2949@item show detach-on-fork
2950Show whether detach-on-fork mode is on/off.
5c95884b
MS
2951@end table
2952
2277426b
PA
2953If you choose to set @samp{detach-on-fork} mode off, then @value{GDBN}
2954will retain control of all forked processes (including nested forks).
2955You can list the forked processes under the control of @value{GDBN} by
2956using the @w{@code{info inferiors}} command, and switch from one fork
6c95b8df
PA
2957to another by using the @code{inferior} command (@pxref{Inferiors and
2958Programs, ,Debugging Multiple Inferiors and Programs}).
5c95884b
MS
2959
2960To quit debugging one of the forked processes, you can either detach
2277426b
PA
2961from it by using the @w{@code{detach inferior}} command (allowing it
2962to run independently), or kill it using the @w{@code{kill inferior}}
6c95b8df
PA
2963command. @xref{Inferiors and Programs, ,Debugging Multiple Inferiors
2964and Programs}.
5c95884b 2965
c906108c
SS
2966If you ask to debug a child process and a @code{vfork} is followed by an
2967@code{exec}, @value{GDBN} executes the new target up to the first
2968breakpoint in the new target. If you have a breakpoint set on
2969@code{main} in your original program, the breakpoint will also be set on
2970the child process's @code{main}.
2971
2277426b
PA
2972On some systems, when a child process is spawned by @code{vfork}, you
2973cannot debug the child or parent until an @code{exec} call completes.
c906108c
SS
2974
2975If you issue a @code{run} command to @value{GDBN} after an @code{exec}
6c95b8df
PA
2976call executes, the new target restarts. To restart the parent
2977process, use the @code{file} command with the parent executable name
2978as its argument. By default, after an @code{exec} call executes,
2979@value{GDBN} discards the symbols of the previous executable image.
2980You can change this behaviour with the @w{@code{set follow-exec-mode}}
2981command.
2982
2983@table @code
2984@kindex set follow-exec-mode
2985@item set follow-exec-mode @var{mode}
2986
2987Set debugger response to a program call of @code{exec}. An
2988@code{exec} call replaces the program image of a process.
2989
2990@code{follow-exec-mode} can be:
2991
2992@table @code
2993@item new
2994@value{GDBN} creates a new inferior and rebinds the process to this
2995new inferior. The program the process was running before the
2996@code{exec} call can be restarted afterwards by restarting the
2997original inferior.
2998
2999For example:
3000
3001@smallexample
3002(@value{GDBP}) info inferiors
3003(gdb) info inferior
3004 Id Description Executable
3005* 1 <null> prog1
3006(@value{GDBP}) run
3007process 12020 is executing new program: prog2
3008Program exited normally.
3009(@value{GDBP}) info inferiors
3010 Id Description Executable
3011* 2 <null> prog2
3012 1 <null> prog1
3013@end smallexample
3014
3015@item same
3016@value{GDBN} keeps the process bound to the same inferior. The new
3017executable image replaces the previous executable loaded in the
3018inferior. Restarting the inferior after the @code{exec} call, with
3019e.g., the @code{run} command, restarts the executable the process was
3020running after the @code{exec} call. This is the default mode.
3021
3022For example:
3023
3024@smallexample
3025(@value{GDBP}) info inferiors
3026 Id Description Executable
3027* 1 <null> prog1
3028(@value{GDBP}) run
3029process 12020 is executing new program: prog2
3030Program exited normally.
3031(@value{GDBP}) info inferiors
3032 Id Description Executable
3033* 1 <null> prog2
3034@end smallexample
3035
3036@end table
3037@end table
c906108c
SS
3038
3039You can use the @code{catch} command to make @value{GDBN} stop whenever
3040a @code{fork}, @code{vfork}, or @code{exec} call is made. @xref{Set
79a6e687 3041Catchpoints, ,Setting Catchpoints}.
c906108c 3042
5c95884b 3043@node Checkpoint/Restart
79a6e687 3044@section Setting a @emph{Bookmark} to Return to Later
5c95884b
MS
3045
3046@cindex checkpoint
3047@cindex restart
3048@cindex bookmark
3049@cindex snapshot of a process
3050@cindex rewind program state
3051
3052On certain operating systems@footnote{Currently, only
3053@sc{gnu}/Linux.}, @value{GDBN} is able to save a @dfn{snapshot} of a
3054program's state, called a @dfn{checkpoint}, and come back to it
3055later.
3056
3057Returning to a checkpoint effectively undoes everything that has
3058happened in the program since the @code{checkpoint} was saved. This
3059includes changes in memory, registers, and even (within some limits)
3060system state. Effectively, it is like going back in time to the
3061moment when the checkpoint was saved.
3062
3063Thus, if you're stepping thru a program and you think you're
3064getting close to the point where things go wrong, you can save
3065a checkpoint. Then, if you accidentally go too far and miss
3066the critical statement, instead of having to restart your program
3067from the beginning, you can just go back to the checkpoint and
3068start again from there.
3069
3070This can be especially useful if it takes a lot of time or
3071steps to reach the point where you think the bug occurs.
3072
3073To use the @code{checkpoint}/@code{restart} method of debugging:
3074
3075@table @code
3076@kindex checkpoint
3077@item checkpoint
3078Save a snapshot of the debugged program's current execution state.
3079The @code{checkpoint} command takes no arguments, but each checkpoint
3080is assigned a small integer id, similar to a breakpoint id.
3081
3082@kindex info checkpoints
3083@item info checkpoints
3084List the checkpoints that have been saved in the current debugging
3085session. For each checkpoint, the following information will be
3086listed:
3087
3088@table @code
3089@item Checkpoint ID
3090@item Process ID
3091@item Code Address
3092@item Source line, or label
3093@end table
3094
3095@kindex restart @var{checkpoint-id}
3096@item restart @var{checkpoint-id}
3097Restore the program state that was saved as checkpoint number
3098@var{checkpoint-id}. All program variables, registers, stack frames
3099etc.@: will be returned to the values that they had when the checkpoint
3100was saved. In essence, gdb will ``wind back the clock'' to the point
3101in time when the checkpoint was saved.
3102
3103Note that breakpoints, @value{GDBN} variables, command history etc.
3104are not affected by restoring a checkpoint. In general, a checkpoint
3105only restores things that reside in the program being debugged, not in
3106the debugger.
3107
b8db102d
MS
3108@kindex delete checkpoint @var{checkpoint-id}
3109@item delete checkpoint @var{checkpoint-id}
5c95884b
MS
3110Delete the previously-saved checkpoint identified by @var{checkpoint-id}.
3111
3112@end table
3113
3114Returning to a previously saved checkpoint will restore the user state
3115of the program being debugged, plus a significant subset of the system
3116(OS) state, including file pointers. It won't ``un-write'' data from
3117a file, but it will rewind the file pointer to the previous location,
3118so that the previously written data can be overwritten. For files
3119opened in read mode, the pointer will also be restored so that the
3120previously read data can be read again.
3121
3122Of course, characters that have been sent to a printer (or other
3123external device) cannot be ``snatched back'', and characters received
3124from eg.@: a serial device can be removed from internal program buffers,
3125but they cannot be ``pushed back'' into the serial pipeline, ready to
3126be received again. Similarly, the actual contents of files that have
3127been changed cannot be restored (at this time).
3128
3129However, within those constraints, you actually can ``rewind'' your
3130program to a previously saved point in time, and begin debugging it
3131again --- and you can change the course of events so as to debug a
3132different execution path this time.
3133
3134@cindex checkpoints and process id
3135Finally, there is one bit of internal program state that will be
3136different when you return to a checkpoint --- the program's process
3137id. Each checkpoint will have a unique process id (or @var{pid}),
3138and each will be different from the program's original @var{pid}.
3139If your program has saved a local copy of its process id, this could
3140potentially pose a problem.
3141
79a6e687 3142@subsection A Non-obvious Benefit of Using Checkpoints
5c95884b
MS
3143
3144On some systems such as @sc{gnu}/Linux, address space randomization
3145is performed on new processes for security reasons. This makes it
3146difficult or impossible to set a breakpoint, or watchpoint, on an
3147absolute address if you have to restart the program, since the
3148absolute location of a symbol will change from one execution to the
3149next.
3150
3151A checkpoint, however, is an @emph{identical} copy of a process.
3152Therefore if you create a checkpoint at (eg.@:) the start of main,
3153and simply return to that checkpoint instead of restarting the
3154process, you can avoid the effects of address randomization and
3155your symbols will all stay in the same place.
3156
6d2ebf8b 3157@node Stopping
c906108c
SS
3158@chapter Stopping and Continuing
3159
3160The principal purposes of using a debugger are so that you can stop your
3161program before it terminates; or so that, if your program runs into
3162trouble, you can investigate and find out why.
3163
7a292a7a
SS
3164Inside @value{GDBN}, your program may stop for any of several reasons,
3165such as a signal, a breakpoint, or reaching a new line after a
3166@value{GDBN} command such as @code{step}. You may then examine and
3167change variables, set new breakpoints or remove old ones, and then
3168continue execution. Usually, the messages shown by @value{GDBN} provide
3169ample explanation of the status of your program---but you can also
3170explicitly request this information at any time.
c906108c
SS
3171
3172@table @code
3173@kindex info program
3174@item info program
3175Display information about the status of your program: whether it is
7a292a7a 3176running or not, what process it is, and why it stopped.
c906108c
SS
3177@end table
3178
3179@menu
3180* Breakpoints:: Breakpoints, watchpoints, and catchpoints
3181* Continuing and Stepping:: Resuming execution
c906108c 3182* Signals:: Signals
c906108c 3183* Thread Stops:: Stopping and starting multi-thread programs
c906108c
SS
3184@end menu
3185
6d2ebf8b 3186@node Breakpoints
79a6e687 3187@section Breakpoints, Watchpoints, and Catchpoints
c906108c
SS
3188
3189@cindex breakpoints
3190A @dfn{breakpoint} makes your program stop whenever a certain point in
3191the program is reached. For each breakpoint, you can add conditions to
3192control in finer detail whether your program stops. You can set
3193breakpoints with the @code{break} command and its variants (@pxref{Set
79a6e687 3194Breaks, ,Setting Breakpoints}), to specify the place where your program
c906108c
SS
3195should stop by line number, function name or exact address in the
3196program.
3197
09d4efe1
EZ
3198On some systems, you can set breakpoints in shared libraries before
3199the executable is run. There is a minor limitation on HP-UX systems:
3200you must wait until the executable is run in order to set breakpoints
3201in shared library routines that are not called directly by the program
3202(for example, routines that are arguments in a @code{pthread_create}
3203call).
c906108c
SS
3204
3205@cindex watchpoints
fd60e0df 3206@cindex data breakpoints
c906108c
SS
3207@cindex memory tracing
3208@cindex breakpoint on memory address
3209@cindex breakpoint on variable modification
3210A @dfn{watchpoint} is a special breakpoint that stops your program
fd60e0df 3211when the value of an expression changes. The expression may be a value
0ced0c34 3212of a variable, or it could involve values of one or more variables
fd60e0df
EZ
3213combined by operators, such as @samp{a + b}. This is sometimes called
3214@dfn{data breakpoints}. You must use a different command to set
79a6e687 3215watchpoints (@pxref{Set Watchpoints, ,Setting Watchpoints}), but aside
fd60e0df
EZ
3216from that, you can manage a watchpoint like any other breakpoint: you
3217enable, disable, and delete both breakpoints and watchpoints using the
3218same commands.
c906108c
SS
3219
3220You can arrange to have values from your program displayed automatically
3221whenever @value{GDBN} stops at a breakpoint. @xref{Auto Display,,
79a6e687 3222Automatic Display}.
c906108c
SS
3223
3224@cindex catchpoints
3225@cindex breakpoint on events
3226A @dfn{catchpoint} is another special breakpoint that stops your program
b37052ae 3227when a certain kind of event occurs, such as the throwing of a C@t{++}
c906108c
SS
3228exception or the loading of a library. As with watchpoints, you use a
3229different command to set a catchpoint (@pxref{Set Catchpoints, ,Setting
79a6e687 3230Catchpoints}), but aside from that, you can manage a catchpoint like any
c906108c 3231other breakpoint. (To stop when your program receives a signal, use the
d4f3574e 3232@code{handle} command; see @ref{Signals, ,Signals}.)
c906108c
SS
3233
3234@cindex breakpoint numbers
3235@cindex numbers for breakpoints
3236@value{GDBN} assigns a number to each breakpoint, watchpoint, or
3237catchpoint when you create it; these numbers are successive integers
3238starting with one. In many of the commands for controlling various
3239features of breakpoints you use the breakpoint number to say which
3240breakpoint you want to change. Each breakpoint may be @dfn{enabled} or
3241@dfn{disabled}; if disabled, it has no effect on your program until you
3242enable it again.
3243
c5394b80
JM
3244@cindex breakpoint ranges
3245@cindex ranges of breakpoints
3246Some @value{GDBN} commands accept a range of breakpoints on which to
3247operate. A breakpoint range is either a single breakpoint number, like
3248@samp{5}, or two such numbers, in increasing order, separated by a
3249hyphen, like @samp{5-7}. When a breakpoint range is given to a command,
d52fb0e9 3250all breakpoints in that range are operated on.
c5394b80 3251
c906108c
SS
3252@menu
3253* Set Breaks:: Setting breakpoints
3254* Set Watchpoints:: Setting watchpoints
3255* Set Catchpoints:: Setting catchpoints
3256* Delete Breaks:: Deleting breakpoints
3257* Disabling:: Disabling breakpoints
3258* Conditions:: Break conditions
3259* Break Commands:: Breakpoint command lists
6149aea9 3260* Save Breakpoints:: How to save breakpoints in a file
d4f3574e 3261* Error in Breakpoints:: ``Cannot insert breakpoints''
79a6e687 3262* Breakpoint-related Warnings:: ``Breakpoint address adjusted...''
c906108c
SS
3263@end menu
3264
6d2ebf8b 3265@node Set Breaks
79a6e687 3266@subsection Setting Breakpoints
c906108c 3267
5d161b24 3268@c FIXME LMB what does GDB do if no code on line of breakpt?
c906108c
SS
3269@c consider in particular declaration with/without initialization.
3270@c
3271@c FIXME 2 is there stuff on this already? break at fun start, already init?
3272
3273@kindex break
41afff9a
EZ
3274@kindex b @r{(@code{break})}
3275@vindex $bpnum@r{, convenience variable}
c906108c
SS
3276@cindex latest breakpoint
3277Breakpoints are set with the @code{break} command (abbreviated
5d161b24 3278@code{b}). The debugger convenience variable @samp{$bpnum} records the
f3b28801 3279number of the breakpoint you've set most recently; see @ref{Convenience
79a6e687 3280Vars,, Convenience Variables}, for a discussion of what you can do with
c906108c
SS
3281convenience variables.
3282
c906108c 3283@table @code
2a25a5ba
EZ
3284@item break @var{location}
3285Set a breakpoint at the given @var{location}, which can specify a
3286function name, a line number, or an address of an instruction.
3287(@xref{Specify Location}, for a list of all the possible ways to
3288specify a @var{location}.) The breakpoint will stop your program just
3289before it executes any of the code in the specified @var{location}.
3290
c906108c 3291When using source languages that permit overloading of symbols, such as
2a25a5ba 3292C@t{++}, a function name may refer to more than one possible place to break.
6ba66d6a
JB
3293@xref{Ambiguous Expressions,,Ambiguous Expressions}, for a discussion of
3294that situation.
c906108c 3295
45ac276d 3296It is also possible to insert a breakpoint that will stop the program
2c88c651
JB
3297only if a specific thread (@pxref{Thread-Specific Breakpoints})
3298or a specific task (@pxref{Ada Tasks}) hits that breakpoint.
45ac276d 3299
c906108c
SS
3300@item break
3301When called without any arguments, @code{break} sets a breakpoint at
3302the next instruction to be executed in the selected stack frame
3303(@pxref{Stack, ,Examining the Stack}). In any selected frame but the
3304innermost, this makes your program stop as soon as control
3305returns to that frame. This is similar to the effect of a
3306@code{finish} command in the frame inside the selected frame---except
3307that @code{finish} does not leave an active breakpoint. If you use
3308@code{break} without an argument in the innermost frame, @value{GDBN} stops
3309the next time it reaches the current location; this may be useful
3310inside loops.
3311
3312@value{GDBN} normally ignores breakpoints when it resumes execution, until at
3313least one instruction has been executed. If it did not do this, you
3314would be unable to proceed past a breakpoint without first disabling the
3315breakpoint. This rule applies whether or not the breakpoint already
3316existed when your program stopped.
3317
3318@item break @dots{} if @var{cond}
3319Set a breakpoint with condition @var{cond}; evaluate the expression
3320@var{cond} each time the breakpoint is reached, and stop only if the
3321value is nonzero---that is, if @var{cond} evaluates as true.
3322@samp{@dots{}} stands for one of the possible arguments described
3323above (or no argument) specifying where to break. @xref{Conditions,
79a6e687 3324,Break Conditions}, for more information on breakpoint conditions.
c906108c
SS
3325
3326@kindex tbreak
3327@item tbreak @var{args}
3328Set a breakpoint enabled only for one stop. @var{args} are the
3329same as for the @code{break} command, and the breakpoint is set in the same
3330way, but the breakpoint is automatically deleted after the first time your
79a6e687 3331program stops there. @xref{Disabling, ,Disabling Breakpoints}.
c906108c 3332
c906108c 3333@kindex hbreak
ba04e063 3334@cindex hardware breakpoints
c906108c 3335@item hbreak @var{args}
d4f3574e
SS
3336Set a hardware-assisted breakpoint. @var{args} are the same as for the
3337@code{break} command and the breakpoint is set in the same way, but the
c906108c
SS
3338breakpoint requires hardware support and some target hardware may not
3339have this support. The main purpose of this is EPROM/ROM code
d4f3574e
SS
3340debugging, so you can set a breakpoint at an instruction without
3341changing the instruction. This can be used with the new trap-generation
09d4efe1 3342provided by SPARClite DSU and most x86-based targets. These targets
d4f3574e
SS
3343will generate traps when a program accesses some data or instruction
3344address that is assigned to the debug registers. However the hardware
3345breakpoint registers can take a limited number of breakpoints. For
3346example, on the DSU, only two data breakpoints can be set at a time, and
3347@value{GDBN} will reject this command if more than two are used. Delete
3348or disable unused hardware breakpoints before setting new ones
79a6e687
BW
3349(@pxref{Disabling, ,Disabling Breakpoints}).
3350@xref{Conditions, ,Break Conditions}.
9c16f35a
EZ
3351For remote targets, you can restrict the number of hardware
3352breakpoints @value{GDBN} will use, see @ref{set remote
3353hardware-breakpoint-limit}.
501eef12 3354
c906108c
SS
3355@kindex thbreak
3356@item thbreak @var{args}
3357Set a hardware-assisted breakpoint enabled only for one stop. @var{args}
3358are the same as for the @code{hbreak} command and the breakpoint is set in
5d161b24 3359the same way. However, like the @code{tbreak} command,
c906108c
SS
3360the breakpoint is automatically deleted after the
3361first time your program stops there. Also, like the @code{hbreak}
5d161b24 3362command, the breakpoint requires hardware support and some target hardware
79a6e687
BW
3363may not have this support. @xref{Disabling, ,Disabling Breakpoints}.
3364See also @ref{Conditions, ,Break Conditions}.
c906108c
SS
3365
3366@kindex rbreak
3367@cindex regular expression
8bd10a10 3368@cindex breakpoints at functions matching a regexp
c45da7e6 3369@cindex set breakpoints in many functions
c906108c 3370@item rbreak @var{regex}
c906108c 3371Set breakpoints on all functions matching the regular expression
11cf8741
JM
3372@var{regex}. This command sets an unconditional breakpoint on all
3373matches, printing a list of all breakpoints it set. Once these
3374breakpoints are set, they are treated just like the breakpoints set with
3375the @code{break} command. You can delete them, disable them, or make
3376them conditional the same way as any other breakpoint.
3377
3378The syntax of the regular expression is the standard one used with tools
3379like @file{grep}. Note that this is different from the syntax used by
3380shells, so for instance @code{foo*} matches all functions that include
3381an @code{fo} followed by zero or more @code{o}s. There is an implicit
3382@code{.*} leading and trailing the regular expression you supply, so to
3383match only functions that begin with @code{foo}, use @code{^foo}.
c906108c 3384
f7dc1244 3385@cindex non-member C@t{++} functions, set breakpoint in
b37052ae 3386When debugging C@t{++} programs, @code{rbreak} is useful for setting
c906108c
SS
3387breakpoints on overloaded functions that are not members of any special
3388classes.
c906108c 3389
f7dc1244
EZ
3390@cindex set breakpoints on all functions
3391The @code{rbreak} command can be used to set breakpoints in
3392@strong{all} the functions in a program, like this:
3393
3394@smallexample
3395(@value{GDBP}) rbreak .
3396@end smallexample
3397
8bd10a10
CM
3398@item rbreak @var{file}:@var{regex}
3399If @code{rbreak} is called with a filename qualification, it limits
3400the search for functions matching the given regular expression to the
3401specified @var{file}. This can be used, for example, to set breakpoints on
3402every function in a given file:
3403
3404@smallexample
3405(@value{GDBP}) rbreak file.c:.
3406@end smallexample
3407
3408The colon separating the filename qualifier from the regex may
3409optionally be surrounded by spaces.
3410
c906108c
SS
3411@kindex info breakpoints
3412@cindex @code{$_} and @code{info breakpoints}
3413@item info breakpoints @r{[}@var{n}@r{]}
3414@itemx info break @r{[}@var{n}@r{]}
c906108c 3415Print a table of all breakpoints, watchpoints, and catchpoints set and
45ac1734
EZ
3416not deleted. Optional argument @var{n} means print information only
3417about the specified breakpoint (or watchpoint or catchpoint). For
3418each breakpoint, following columns are printed:
c906108c
SS
3419
3420@table @emph
3421@item Breakpoint Numbers
3422@item Type
3423Breakpoint, watchpoint, or catchpoint.
3424@item Disposition
3425Whether the breakpoint is marked to be disabled or deleted when hit.
3426@item Enabled or Disabled
3427Enabled breakpoints are marked with @samp{y}. @samp{n} marks breakpoints
b3db7447 3428that are not enabled.
c906108c 3429@item Address
fe6fbf8b 3430Where the breakpoint is in your program, as a memory address. For a
b3db7447
NR
3431pending breakpoint whose address is not yet known, this field will
3432contain @samp{<PENDING>}. Such breakpoint won't fire until a shared
3433library that has the symbol or line referred by breakpoint is loaded.
3434See below for details. A breakpoint with several locations will
3b784c4f 3435have @samp{<MULTIPLE>} in this field---see below for details.
c906108c
SS
3436@item What
3437Where the breakpoint is in the source for your program, as a file and
2650777c
JJ
3438line number. For a pending breakpoint, the original string passed to
3439the breakpoint command will be listed as it cannot be resolved until
3440the appropriate shared library is loaded in the future.
c906108c
SS
3441@end table
3442
3443@noindent
3444If a breakpoint is conditional, @code{info break} shows the condition on
3445the line following the affected breakpoint; breakpoint commands, if any,
2650777c
JJ
3446are listed after that. A pending breakpoint is allowed to have a condition
3447specified for it. The condition is not parsed for validity until a shared
3448library is loaded that allows the pending breakpoint to resolve to a
3449valid location.
c906108c
SS
3450
3451@noindent
3452@code{info break} with a breakpoint
3453number @var{n} as argument lists only that breakpoint. The
3454convenience variable @code{$_} and the default examining-address for
3455the @code{x} command are set to the address of the last breakpoint
79a6e687 3456listed (@pxref{Memory, ,Examining Memory}).
c906108c
SS
3457
3458@noindent
3459@code{info break} displays a count of the number of times the breakpoint
3460has been hit. This is especially useful in conjunction with the
3461@code{ignore} command. You can ignore a large number of breakpoint
3462hits, look at the breakpoint info to see how many times the breakpoint
3463was hit, and then run again, ignoring one less than that number. This
3464will get you quickly to the last hit of that breakpoint.
3465@end table
3466
3467@value{GDBN} allows you to set any number of breakpoints at the same place in
3468your program. There is nothing silly or meaningless about this. When
3469the breakpoints are conditional, this is even useful
79a6e687 3470(@pxref{Conditions, ,Break Conditions}).
c906108c 3471
2e9132cc
EZ
3472@cindex multiple locations, breakpoints
3473@cindex breakpoints, multiple locations
fcda367b 3474It is possible that a breakpoint corresponds to several locations
fe6fbf8b
VP
3475in your program. Examples of this situation are:
3476
3477@itemize @bullet
fe6fbf8b
VP
3478@item
3479For a C@t{++} constructor, the @value{NGCC} compiler generates several
3480instances of the function body, used in different cases.
3481
3482@item
3483For a C@t{++} template function, a given line in the function can
3484correspond to any number of instantiations.
3485
3486@item
3487For an inlined function, a given source line can correspond to
3488several places where that function is inlined.
fe6fbf8b
VP
3489@end itemize
3490
3491In all those cases, @value{GDBN} will insert a breakpoint at all
2e9132cc
EZ
3492the relevant locations@footnote{
3493As of this writing, multiple-location breakpoints work only if there's
3494line number information for all the locations. This means that they
3495will generally not work in system libraries, unless you have debug
3496info with line numbers for them.}.
fe6fbf8b 3497
3b784c4f
EZ
3498A breakpoint with multiple locations is displayed in the breakpoint
3499table using several rows---one header row, followed by one row for
3500each breakpoint location. The header row has @samp{<MULTIPLE>} in the
3501address column. The rows for individual locations contain the actual
3502addresses for locations, and show the functions to which those
3503locations belong. The number column for a location is of the form
fe6fbf8b
VP
3504@var{breakpoint-number}.@var{location-number}.
3505
3506For example:
3b784c4f 3507
fe6fbf8b
VP
3508@smallexample
3509Num Type Disp Enb Address What
35101 breakpoint keep y <MULTIPLE>
3511 stop only if i==1
3512 breakpoint already hit 1 time
35131.1 y 0x080486a2 in void foo<int>() at t.cc:8
35141.2 y 0x080486ca in void foo<double>() at t.cc:8
3515@end smallexample
3516
3517Each location can be individually enabled or disabled by passing
3518@var{breakpoint-number}.@var{location-number} as argument to the
3b784c4f
EZ
3519@code{enable} and @code{disable} commands. Note that you cannot
3520delete the individual locations from the list, you can only delete the
16bfc218 3521entire list of locations that belong to their parent breakpoint (with
3b784c4f
EZ
3522the @kbd{delete @var{num}} command, where @var{num} is the number of
3523the parent breakpoint, 1 in the above example). Disabling or enabling
3524the parent breakpoint (@pxref{Disabling}) affects all of the locations
3525that belong to that breakpoint.
fe6fbf8b 3526
2650777c 3527@cindex pending breakpoints
fe6fbf8b 3528It's quite common to have a breakpoint inside a shared library.
3b784c4f 3529Shared libraries can be loaded and unloaded explicitly,
fe6fbf8b
VP
3530and possibly repeatedly, as the program is executed. To support
3531this use case, @value{GDBN} updates breakpoint locations whenever
3532any shared library is loaded or unloaded. Typically, you would
fcda367b 3533set a breakpoint in a shared library at the beginning of your
fe6fbf8b
VP
3534debugging session, when the library is not loaded, and when the
3535symbols from the library are not available. When you try to set
3536breakpoint, @value{GDBN} will ask you if you want to set
3b784c4f 3537a so called @dfn{pending breakpoint}---breakpoint whose address
fe6fbf8b
VP
3538is not yet resolved.
3539
3540After the program is run, whenever a new shared library is loaded,
3541@value{GDBN} reevaluates all the breakpoints. When a newly loaded
3542shared library contains the symbol or line referred to by some
3543pending breakpoint, that breakpoint is resolved and becomes an
3544ordinary breakpoint. When a library is unloaded, all breakpoints
3545that refer to its symbols or source lines become pending again.
3546
3547This logic works for breakpoints with multiple locations, too. For
3548example, if you have a breakpoint in a C@t{++} template function, and
3549a newly loaded shared library has an instantiation of that template,
3550a new location is added to the list of locations for the breakpoint.
3551
3552Except for having unresolved address, pending breakpoints do not
3553differ from regular breakpoints. You can set conditions or commands,
3554enable and disable them and perform other breakpoint operations.
3555
3556@value{GDBN} provides some additional commands for controlling what
3557happens when the @samp{break} command cannot resolve breakpoint
3558address specification to an address:
dd79a6cf
JJ
3559
3560@kindex set breakpoint pending
3561@kindex show breakpoint pending
3562@table @code
3563@item set breakpoint pending auto
3564This is the default behavior. When @value{GDBN} cannot find the breakpoint
3565location, it queries you whether a pending breakpoint should be created.
3566
3567@item set breakpoint pending on
3568This indicates that an unrecognized breakpoint location should automatically
3569result in a pending breakpoint being created.
3570
3571@item set breakpoint pending off
3572This indicates that pending breakpoints are not to be created. Any
3573unrecognized breakpoint location results in an error. This setting does
3574not affect any pending breakpoints previously created.
3575
3576@item show breakpoint pending
3577Show the current behavior setting for creating pending breakpoints.
3578@end table
2650777c 3579
fe6fbf8b
VP
3580The settings above only affect the @code{break} command and its
3581variants. Once breakpoint is set, it will be automatically updated
3582as shared libraries are loaded and unloaded.
2650777c 3583
765dc015
VP
3584@cindex automatic hardware breakpoints
3585For some targets, @value{GDBN} can automatically decide if hardware or
3586software breakpoints should be used, depending on whether the
3587breakpoint address is read-only or read-write. This applies to
3588breakpoints set with the @code{break} command as well as to internal
3589breakpoints set by commands like @code{next} and @code{finish}. For
fcda367b 3590breakpoints set with @code{hbreak}, @value{GDBN} will always use hardware
765dc015
VP
3591breakpoints.
3592
3593You can control this automatic behaviour with the following commands::
3594
3595@kindex set breakpoint auto-hw
3596@kindex show breakpoint auto-hw
3597@table @code
3598@item set breakpoint auto-hw on
3599This is the default behavior. When @value{GDBN} sets a breakpoint, it
3600will try to use the target memory map to decide if software or hardware
3601breakpoint must be used.
3602
3603@item set breakpoint auto-hw off
3604This indicates @value{GDBN} should not automatically select breakpoint
3605type. If the target provides a memory map, @value{GDBN} will warn when
3606trying to set software breakpoint at a read-only address.
3607@end table
3608
74960c60
VP
3609@value{GDBN} normally implements breakpoints by replacing the program code
3610at the breakpoint address with a special instruction, which, when
3611executed, given control to the debugger. By default, the program
3612code is so modified only when the program is resumed. As soon as
3613the program stops, @value{GDBN} restores the original instructions. This
3614behaviour guards against leaving breakpoints inserted in the
3615target should gdb abrubptly disconnect. However, with slow remote
3616targets, inserting and removing breakpoint can reduce the performance.
3617This behavior can be controlled with the following commands::
3618
3619@kindex set breakpoint always-inserted
3620@kindex show breakpoint always-inserted
3621@table @code
3622@item set breakpoint always-inserted off
33e5cbd6
PA
3623All breakpoints, including newly added by the user, are inserted in
3624the target only when the target is resumed. All breakpoints are
3625removed from the target when it stops.
74960c60
VP
3626
3627@item set breakpoint always-inserted on
3628Causes all breakpoints to be inserted in the target at all times. If
3629the user adds a new breakpoint, or changes an existing breakpoint, the
3630breakpoints in the target are updated immediately. A breakpoint is
3631removed from the target only when breakpoint itself is removed.
33e5cbd6
PA
3632
3633@cindex non-stop mode, and @code{breakpoint always-inserted}
3634@item set breakpoint always-inserted auto
3635This is the default mode. If @value{GDBN} is controlling the inferior
3636in non-stop mode (@pxref{Non-Stop Mode}), gdb behaves as if
3637@code{breakpoint always-inserted} mode is on. If @value{GDBN} is
3638controlling the inferior in all-stop mode, @value{GDBN} behaves as if
3639@code{breakpoint always-inserted} mode is off.
74960c60 3640@end table
765dc015 3641
c906108c
SS
3642@cindex negative breakpoint numbers
3643@cindex internal @value{GDBN} breakpoints
eb12ee30
AC
3644@value{GDBN} itself sometimes sets breakpoints in your program for
3645special purposes, such as proper handling of @code{longjmp} (in C
3646programs). These internal breakpoints are assigned negative numbers,
3647starting with @code{-1}; @samp{info breakpoints} does not display them.
c906108c 3648You can see these breakpoints with the @value{GDBN} maintenance command
eb12ee30 3649@samp{maint info breakpoints} (@pxref{maint info breakpoints}).
c906108c
SS
3650
3651
6d2ebf8b 3652@node Set Watchpoints
79a6e687 3653@subsection Setting Watchpoints
c906108c
SS
3654
3655@cindex setting watchpoints
c906108c
SS
3656You can use a watchpoint to stop execution whenever the value of an
3657expression changes, without having to predict a particular place where
fd60e0df
EZ
3658this may happen. (This is sometimes called a @dfn{data breakpoint}.)
3659The expression may be as simple as the value of a single variable, or
3660as complex as many variables combined by operators. Examples include:
3661
3662@itemize @bullet
3663@item
3664A reference to the value of a single variable.
3665
3666@item
3667An address cast to an appropriate data type. For example,
3668@samp{*(int *)0x12345678} will watch a 4-byte region at the specified
3669address (assuming an @code{int} occupies 4 bytes).
3670
3671@item
3672An arbitrarily complex expression, such as @samp{a*b + c/d}. The
3673expression can use any operators valid in the program's native
3674language (@pxref{Languages}).
3675@end itemize
c906108c 3676
fa4727a6
DJ
3677You can set a watchpoint on an expression even if the expression can
3678not be evaluated yet. For instance, you can set a watchpoint on
3679@samp{*global_ptr} before @samp{global_ptr} is initialized.
3680@value{GDBN} will stop when your program sets @samp{global_ptr} and
3681the expression produces a valid value. If the expression becomes
3682valid in some other way than changing a variable (e.g.@: if the memory
3683pointed to by @samp{*global_ptr} becomes readable as the result of a
3684@code{malloc} call), @value{GDBN} may not stop until the next time
3685the expression changes.
3686
82f2d802
EZ
3687@cindex software watchpoints
3688@cindex hardware watchpoints
c906108c 3689Depending on your system, watchpoints may be implemented in software or
2df3850c 3690hardware. @value{GDBN} does software watchpointing by single-stepping your
c906108c
SS
3691program and testing the variable's value each time, which is hundreds of
3692times slower than normal execution. (But this may still be worth it, to
3693catch errors where you have no clue what part of your program is the
3694culprit.)
3695
37e4754d 3696On some systems, such as HP-UX, PowerPC, @sc{gnu}/Linux and most other
82f2d802
EZ
3697x86-based targets, @value{GDBN} includes support for hardware
3698watchpoints, which do not slow down the running of your program.
c906108c
SS
3699
3700@table @code
3701@kindex watch
d8b2a693 3702@item watch @var{expr} @r{[}thread @var{threadnum}@r{]}
fd60e0df
EZ
3703Set a watchpoint for an expression. @value{GDBN} will break when the
3704expression @var{expr} is written into by the program and its value
3705changes. The simplest (and the most popular) use of this command is
3706to watch the value of a single variable:
3707
3708@smallexample
3709(@value{GDBP}) watch foo
3710@end smallexample
c906108c 3711
d8b2a693
JB
3712If the command includes a @code{@r{[}thread @var{threadnum}@r{]}}
3713clause, @value{GDBN} breaks only when the thread identified by
3714@var{threadnum} changes the value of @var{expr}. If any other threads
3715change the value of @var{expr}, @value{GDBN} will not break. Note
3716that watchpoints restricted to a single thread in this way only work
3717with Hardware Watchpoints.
3718
c906108c 3719@kindex rwatch
d8b2a693 3720@item rwatch @var{expr} @r{[}thread @var{threadnum}@r{]}
09d4efe1
EZ
3721Set a watchpoint that will break when the value of @var{expr} is read
3722by the program.
c906108c
SS
3723
3724@kindex awatch
d8b2a693 3725@item awatch @var{expr} @r{[}thread @var{threadnum}@r{]}
09d4efe1
EZ
3726Set a watchpoint that will break when @var{expr} is either read from
3727or written into by the program.
c906108c 3728
45ac1734 3729@kindex info watchpoints @r{[}@var{n}@r{]}
c906108c 3730@item info watchpoints
d77f58be
SS
3731This command prints a list of watchpoints, using the same format as
3732@code{info break} (@pxref{Set Breaks}).
c906108c
SS
3733@end table
3734
65d79d4b
SDJ
3735If you watch for a change in a numerically entered address you need to
3736dereference it, as the address itself is just a constant number which will
3737never change. @value{GDBN} refuses to create a watchpoint that watches
3738a never-changing value:
3739
3740@smallexample
3741(@value{GDBP}) watch 0x600850
3742Cannot watch constant value 0x600850.
3743(@value{GDBP}) watch *(int *) 0x600850
3744Watchpoint 1: *(int *) 6293584
3745@end smallexample
3746
c906108c
SS
3747@value{GDBN} sets a @dfn{hardware watchpoint} if possible. Hardware
3748watchpoints execute very quickly, and the debugger reports a change in
3749value at the exact instruction where the change occurs. If @value{GDBN}
3750cannot set a hardware watchpoint, it sets a software watchpoint, which
3751executes more slowly and reports the change in value at the next
82f2d802
EZ
3752@emph{statement}, not the instruction, after the change occurs.
3753
82f2d802
EZ
3754@cindex use only software watchpoints
3755You can force @value{GDBN} to use only software watchpoints with the
3756@kbd{set can-use-hw-watchpoints 0} command. With this variable set to
3757zero, @value{GDBN} will never try to use hardware watchpoints, even if
3758the underlying system supports them. (Note that hardware-assisted
3759watchpoints that were set @emph{before} setting
3760@code{can-use-hw-watchpoints} to zero will still use the hardware
d3e8051b 3761mechanism of watching expression values.)
c906108c 3762
9c16f35a
EZ
3763@table @code
3764@item set can-use-hw-watchpoints
3765@kindex set can-use-hw-watchpoints
3766Set whether or not to use hardware watchpoints.
3767
3768@item show can-use-hw-watchpoints
3769@kindex show can-use-hw-watchpoints
3770Show the current mode of using hardware watchpoints.
3771@end table
3772
3773For remote targets, you can restrict the number of hardware
3774watchpoints @value{GDBN} will use, see @ref{set remote
3775hardware-breakpoint-limit}.
3776
c906108c
SS
3777When you issue the @code{watch} command, @value{GDBN} reports
3778
474c8240 3779@smallexample
c906108c 3780Hardware watchpoint @var{num}: @var{expr}
474c8240 3781@end smallexample
c906108c
SS
3782
3783@noindent
3784if it was able to set a hardware watchpoint.
3785
7be570e7
JM
3786Currently, the @code{awatch} and @code{rwatch} commands can only set
3787hardware watchpoints, because accesses to data that don't change the
3788value of the watched expression cannot be detected without examining
3789every instruction as it is being executed, and @value{GDBN} does not do
3790that currently. If @value{GDBN} finds that it is unable to set a
3791hardware breakpoint with the @code{awatch} or @code{rwatch} command, it
3792will print a message like this:
3793
3794@smallexample
3795Expression cannot be implemented with read/access watchpoint.
3796@end smallexample
3797
3798Sometimes, @value{GDBN} cannot set a hardware watchpoint because the
3799data type of the watched expression is wider than what a hardware
3800watchpoint on the target machine can handle. For example, some systems
3801can only watch regions that are up to 4 bytes wide; on such systems you
3802cannot set hardware watchpoints for an expression that yields a
3803double-precision floating-point number (which is typically 8 bytes
3804wide). As a work-around, it might be possible to break the large region
3805into a series of smaller ones and watch them with separate watchpoints.
3806
3807If you set too many hardware watchpoints, @value{GDBN} might be unable
3808to insert all of them when you resume the execution of your program.
3809Since the precise number of active watchpoints is unknown until such
3810time as the program is about to be resumed, @value{GDBN} might not be
3811able to warn you about this when you set the watchpoints, and the
3812warning will be printed only when the program is resumed:
3813
3814@smallexample
3815Hardware watchpoint @var{num}: Could not insert watchpoint
3816@end smallexample
3817
3818@noindent
3819If this happens, delete or disable some of the watchpoints.
3820
fd60e0df
EZ
3821Watching complex expressions that reference many variables can also
3822exhaust the resources available for hardware-assisted watchpoints.
3823That's because @value{GDBN} needs to watch every variable in the
3824expression with separately allocated resources.
3825
c906108c 3826If you call a function interactively using @code{print} or @code{call},
2df3850c 3827any watchpoints you have set will be inactive until @value{GDBN} reaches another
c906108c
SS
3828kind of breakpoint or the call completes.
3829
7be570e7
JM
3830@value{GDBN} automatically deletes watchpoints that watch local
3831(automatic) variables, or expressions that involve such variables, when
3832they go out of scope, that is, when the execution leaves the block in
3833which these variables were defined. In particular, when the program
3834being debugged terminates, @emph{all} local variables go out of scope,
3835and so only watchpoints that watch global variables remain set. If you
3836rerun the program, you will need to set all such watchpoints again. One
3837way of doing that would be to set a code breakpoint at the entry to the
3838@code{main} function and when it breaks, set all the watchpoints.
3839
c906108c
SS
3840@cindex watchpoints and threads
3841@cindex threads and watchpoints
d983da9c
DJ
3842In multi-threaded programs, watchpoints will detect changes to the
3843watched expression from every thread.
3844
3845@quotation
3846@emph{Warning:} In multi-threaded programs, software watchpoints
53a5351d
JM
3847have only limited usefulness. If @value{GDBN} creates a software
3848watchpoint, it can only watch the value of an expression @emph{in a
3849single thread}. If you are confident that the expression can only
3850change due to the current thread's activity (and if you are also
3851confident that no other thread can become current), then you can use
3852software watchpoints as usual. However, @value{GDBN} may not notice
3853when a non-current thread's activity changes the expression. (Hardware
3854watchpoints, in contrast, watch an expression in all threads.)
c906108c 3855@end quotation
c906108c 3856
501eef12
AC
3857@xref{set remote hardware-watchpoint-limit}.
3858
6d2ebf8b 3859@node Set Catchpoints
79a6e687 3860@subsection Setting Catchpoints
d4f3574e 3861@cindex catchpoints, setting
c906108c
SS
3862@cindex exception handlers
3863@cindex event handling
3864
3865You can use @dfn{catchpoints} to cause the debugger to stop for certain
b37052ae 3866kinds of program events, such as C@t{++} exceptions or the loading of a
c906108c
SS
3867shared library. Use the @code{catch} command to set a catchpoint.
3868
3869@table @code
3870@kindex catch
3871@item catch @var{event}
3872Stop when @var{event} occurs. @var{event} can be any of the following:
3873@table @code
3874@item throw
4644b6e3 3875@cindex stop on C@t{++} exceptions
b37052ae 3876The throwing of a C@t{++} exception.
c906108c
SS
3877
3878@item catch
b37052ae 3879The catching of a C@t{++} exception.
c906108c 3880
8936fcda
JB
3881@item exception
3882@cindex Ada exception catching
3883@cindex catch Ada exceptions
3884An Ada exception being raised. If an exception name is specified
3885at the end of the command (eg @code{catch exception Program_Error}),
3886the debugger will stop only when this specific exception is raised.
3887Otherwise, the debugger stops execution when any Ada exception is raised.
3888
87f67dba
JB
3889When inserting an exception catchpoint on a user-defined exception whose
3890name is identical to one of the exceptions defined by the language, the
3891fully qualified name must be used as the exception name. Otherwise,
3892@value{GDBN} will assume that it should stop on the pre-defined exception
3893rather than the user-defined one. For instance, assuming an exception
3894called @code{Constraint_Error} is defined in package @code{Pck}, then
3895the command to use to catch such exceptions is @kbd{catch exception
3896Pck.Constraint_Error}.
3897
8936fcda
JB
3898@item exception unhandled
3899An exception that was raised but is not handled by the program.
3900
3901@item assert
3902A failed Ada assertion.
3903
c906108c 3904@item exec
4644b6e3 3905@cindex break on fork/exec
5ee187d7
DJ
3906A call to @code{exec}. This is currently only available for HP-UX
3907and @sc{gnu}/Linux.
c906108c 3908
a96d9b2e 3909@item syscall
ee8e71d4 3910@itemx syscall @r{[}@var{name} @r{|} @var{number}@r{]} @dots{}
a96d9b2e
SDJ
3911@cindex break on a system call.
3912A call to or return from a system call, a.k.a.@: @dfn{syscall}. A
3913syscall is a mechanism for application programs to request a service
3914from the operating system (OS) or one of the OS system services.
3915@value{GDBN} can catch some or all of the syscalls issued by the
3916debuggee, and show the related information for each syscall. If no
3917argument is specified, calls to and returns from all system calls
3918will be caught.
3919
3920@var{name} can be any system call name that is valid for the
3921underlying OS. Just what syscalls are valid depends on the OS. On
3922GNU and Unix systems, you can find the full list of valid syscall
3923names on @file{/usr/include/asm/unistd.h}.
3924
3925@c For MS-Windows, the syscall names and the corresponding numbers
3926@c can be found, e.g., on this URL:
3927@c http://www.metasploit.com/users/opcode/syscalls.html
3928@c but we don't support Windows syscalls yet.
3929
3930Normally, @value{GDBN} knows in advance which syscalls are valid for
3931each OS, so you can use the @value{GDBN} command-line completion
3932facilities (@pxref{Completion,, command completion}) to list the
3933available choices.
3934
3935You may also specify the system call numerically. A syscall's
3936number is the value passed to the OS's syscall dispatcher to
3937identify the requested service. When you specify the syscall by its
3938name, @value{GDBN} uses its database of syscalls to convert the name
3939into the corresponding numeric code, but using the number directly
3940may be useful if @value{GDBN}'s database does not have the complete
3941list of syscalls on your system (e.g., because @value{GDBN} lags
3942behind the OS upgrades).
3943
3944The example below illustrates how this command works if you don't provide
3945arguments to it:
3946
3947@smallexample
3948(@value{GDBP}) catch syscall
3949Catchpoint 1 (syscall)
3950(@value{GDBP}) r
3951Starting program: /tmp/catch-syscall
3952
3953Catchpoint 1 (call to syscall 'close'), \
3954 0xffffe424 in __kernel_vsyscall ()
3955(@value{GDBP}) c
3956Continuing.
3957
3958Catchpoint 1 (returned from syscall 'close'), \
3959 0xffffe424 in __kernel_vsyscall ()
3960(@value{GDBP})
3961@end smallexample
3962
3963Here is an example of catching a system call by name:
3964
3965@smallexample
3966(@value{GDBP}) catch syscall chroot
3967Catchpoint 1 (syscall 'chroot' [61])
3968(@value{GDBP}) r
3969Starting program: /tmp/catch-syscall
3970
3971Catchpoint 1 (call to syscall 'chroot'), \
3972 0xffffe424 in __kernel_vsyscall ()
3973(@value{GDBP}) c
3974Continuing.
3975
3976Catchpoint 1 (returned from syscall 'chroot'), \
3977 0xffffe424 in __kernel_vsyscall ()
3978(@value{GDBP})
3979@end smallexample
3980
3981An example of specifying a system call numerically. In the case
3982below, the syscall number has a corresponding entry in the XML
3983file, so @value{GDBN} finds its name and prints it:
3984
3985@smallexample
3986(@value{GDBP}) catch syscall 252
3987Catchpoint 1 (syscall(s) 'exit_group')
3988(@value{GDBP}) r
3989Starting program: /tmp/catch-syscall
3990
3991Catchpoint 1 (call to syscall 'exit_group'), \
3992 0xffffe424 in __kernel_vsyscall ()
3993(@value{GDBP}) c
3994Continuing.
3995
3996Program exited normally.
3997(@value{GDBP})
3998@end smallexample
3999
4000However, there can be situations when there is no corresponding name
4001in XML file for that syscall number. In this case, @value{GDBN} prints
4002a warning message saying that it was not able to find the syscall name,
4003but the catchpoint will be set anyway. See the example below:
4004
4005@smallexample
4006(@value{GDBP}) catch syscall 764
4007warning: The number '764' does not represent a known syscall.
4008Catchpoint 2 (syscall 764)
4009(@value{GDBP})
4010@end smallexample
4011
4012If you configure @value{GDBN} using the @samp{--without-expat} option,
4013it will not be able to display syscall names. Also, if your
4014architecture does not have an XML file describing its system calls,
4015you will not be able to see the syscall names. It is important to
4016notice that these two features are used for accessing the syscall
4017name database. In either case, you will see a warning like this:
4018
4019@smallexample
4020(@value{GDBP}) catch syscall
4021warning: Could not open "syscalls/i386-linux.xml"
4022warning: Could not load the syscall XML file 'syscalls/i386-linux.xml'.
4023GDB will not be able to display syscall names.
4024Catchpoint 1 (syscall)
4025(@value{GDBP})
4026@end smallexample
4027
4028Of course, the file name will change depending on your architecture and system.
4029
4030Still using the example above, you can also try to catch a syscall by its
4031number. In this case, you would see something like:
4032
4033@smallexample
4034(@value{GDBP}) catch syscall 252
4035Catchpoint 1 (syscall(s) 252)
4036@end smallexample
4037
4038Again, in this case @value{GDBN} would not be able to display syscall's names.
4039
c906108c 4040@item fork
5ee187d7
DJ
4041A call to @code{fork}. This is currently only available for HP-UX
4042and @sc{gnu}/Linux.
c906108c
SS
4043
4044@item vfork
5ee187d7
DJ
4045A call to @code{vfork}. This is currently only available for HP-UX
4046and @sc{gnu}/Linux.
c906108c 4047
c906108c
SS
4048@end table
4049
4050@item tcatch @var{event}
4051Set a catchpoint that is enabled only for one stop. The catchpoint is
4052automatically deleted after the first time the event is caught.
4053
4054@end table
4055
4056Use the @code{info break} command to list the current catchpoints.
4057
b37052ae 4058There are currently some limitations to C@t{++} exception handling
c906108c
SS
4059(@code{catch throw} and @code{catch catch}) in @value{GDBN}:
4060
4061@itemize @bullet
4062@item
4063If you call a function interactively, @value{GDBN} normally returns
4064control to you when the function has finished executing. If the call
4065raises an exception, however, the call may bypass the mechanism that
4066returns control to you and cause your program either to abort or to
4067simply continue running until it hits a breakpoint, catches a signal
4068that @value{GDBN} is listening for, or exits. This is the case even if
4069you set a catchpoint for the exception; catchpoints on exceptions are
4070disabled within interactive calls.
4071
4072@item
4073You cannot raise an exception interactively.
4074
4075@item
4076You cannot install an exception handler interactively.
4077@end itemize
4078
4079@cindex raise exceptions
4080Sometimes @code{catch} is not the best way to debug exception handling:
4081if you need to know exactly where an exception is raised, it is better to
4082stop @emph{before} the exception handler is called, since that way you
4083can see the stack before any unwinding takes place. If you set a
4084breakpoint in an exception handler instead, it may not be easy to find
4085out where the exception was raised.
4086
4087To stop just before an exception handler is called, you need some
b37052ae 4088knowledge of the implementation. In the case of @sc{gnu} C@t{++}, exceptions are
c906108c
SS
4089raised by calling a library function named @code{__raise_exception}
4090which has the following ANSI C interface:
4091
474c8240 4092@smallexample
c906108c 4093 /* @var{addr} is where the exception identifier is stored.
d4f3574e
SS
4094 @var{id} is the exception identifier. */
4095 void __raise_exception (void **addr, void *id);
474c8240 4096@end smallexample
c906108c
SS
4097
4098@noindent
4099To make the debugger catch all exceptions before any stack
4100unwinding takes place, set a breakpoint on @code{__raise_exception}
79a6e687 4101(@pxref{Breakpoints, ,Breakpoints; Watchpoints; and Exceptions}).
c906108c 4102
79a6e687 4103With a conditional breakpoint (@pxref{Conditions, ,Break Conditions})
c906108c
SS
4104that depends on the value of @var{id}, you can stop your program when
4105a specific exception is raised. You can use multiple conditional
4106breakpoints to stop your program when any of a number of exceptions are
4107raised.
4108
4109
6d2ebf8b 4110@node Delete Breaks
79a6e687 4111@subsection Deleting Breakpoints
c906108c
SS
4112
4113@cindex clearing breakpoints, watchpoints, catchpoints
4114@cindex deleting breakpoints, watchpoints, catchpoints
4115It is often necessary to eliminate a breakpoint, watchpoint, or
4116catchpoint once it has done its job and you no longer want your program
4117to stop there. This is called @dfn{deleting} the breakpoint. A
4118breakpoint that has been deleted no longer exists; it is forgotten.
4119
4120With the @code{clear} command you can delete breakpoints according to
4121where they are in your program. With the @code{delete} command you can
4122delete individual breakpoints, watchpoints, or catchpoints by specifying
4123their breakpoint numbers.
4124
4125It is not necessary to delete a breakpoint to proceed past it. @value{GDBN}
4126automatically ignores breakpoints on the first instruction to be executed
4127when you continue execution without changing the execution address.
4128
4129@table @code
4130@kindex clear
4131@item clear
4132Delete any breakpoints at the next instruction to be executed in the
79a6e687 4133selected stack frame (@pxref{Selection, ,Selecting a Frame}). When
c906108c
SS
4134the innermost frame is selected, this is a good way to delete a
4135breakpoint where your program just stopped.
4136
2a25a5ba
EZ
4137@item clear @var{location}
4138Delete any breakpoints set at the specified @var{location}.
4139@xref{Specify Location}, for the various forms of @var{location}; the
4140most useful ones are listed below:
4141
4142@table @code
c906108c
SS
4143@item clear @var{function}
4144@itemx clear @var{filename}:@var{function}
09d4efe1 4145Delete any breakpoints set at entry to the named @var{function}.
c906108c
SS
4146
4147@item clear @var{linenum}
4148@itemx clear @var{filename}:@var{linenum}
09d4efe1
EZ
4149Delete any breakpoints set at or within the code of the specified
4150@var{linenum} of the specified @var{filename}.
2a25a5ba 4151@end table
c906108c
SS
4152
4153@cindex delete breakpoints
4154@kindex delete
41afff9a 4155@kindex d @r{(@code{delete})}
c5394b80
JM
4156@item delete @r{[}breakpoints@r{]} @r{[}@var{range}@dots{}@r{]}
4157Delete the breakpoints, watchpoints, or catchpoints of the breakpoint
4158ranges specified as arguments. If no argument is specified, delete all
c906108c
SS
4159breakpoints (@value{GDBN} asks confirmation, unless you have @code{set
4160confirm off}). You can abbreviate this command as @code{d}.
4161@end table
4162
6d2ebf8b 4163@node Disabling
79a6e687 4164@subsection Disabling Breakpoints
c906108c 4165
4644b6e3 4166@cindex enable/disable a breakpoint
c906108c
SS
4167Rather than deleting a breakpoint, watchpoint, or catchpoint, you might
4168prefer to @dfn{disable} it. This makes the breakpoint inoperative as if
4169it had been deleted, but remembers the information on the breakpoint so
4170that you can @dfn{enable} it again later.
4171
4172You disable and enable breakpoints, watchpoints, and catchpoints with
d77f58be
SS
4173the @code{enable} and @code{disable} commands, optionally specifying
4174one or more breakpoint numbers as arguments. Use @code{info break} to
4175print a list of all breakpoints, watchpoints, and catchpoints if you
4176do not know which numbers to use.
c906108c 4177
3b784c4f
EZ
4178Disabling and enabling a breakpoint that has multiple locations
4179affects all of its locations.
4180
c906108c
SS
4181A breakpoint, watchpoint, or catchpoint can have any of four different
4182states of enablement:
4183
4184@itemize @bullet
4185@item
4186Enabled. The breakpoint stops your program. A breakpoint set
4187with the @code{break} command starts out in this state.
4188@item
4189Disabled. The breakpoint has no effect on your program.
4190@item
4191Enabled once. The breakpoint stops your program, but then becomes
d4f3574e 4192disabled.
c906108c
SS
4193@item
4194Enabled for deletion. The breakpoint stops your program, but
d4f3574e
SS
4195immediately after it does so it is deleted permanently. A breakpoint
4196set with the @code{tbreak} command starts out in this state.
c906108c
SS
4197@end itemize
4198
4199You can use the following commands to enable or disable breakpoints,
4200watchpoints, and catchpoints:
4201
4202@table @code
c906108c 4203@kindex disable
41afff9a 4204@kindex dis @r{(@code{disable})}
c5394b80 4205@item disable @r{[}breakpoints@r{]} @r{[}@var{range}@dots{}@r{]}
c906108c
SS
4206Disable the specified breakpoints---or all breakpoints, if none are
4207listed. A disabled breakpoint has no effect but is not forgotten. All
4208options such as ignore-counts, conditions and commands are remembered in
4209case the breakpoint is enabled again later. You may abbreviate
4210@code{disable} as @code{dis}.
4211
c906108c 4212@kindex enable
c5394b80 4213@item enable @r{[}breakpoints@r{]} @r{[}@var{range}@dots{}@r{]}
c906108c
SS
4214Enable the specified breakpoints (or all defined breakpoints). They
4215become effective once again in stopping your program.
4216
c5394b80 4217@item enable @r{[}breakpoints@r{]} once @var{range}@dots{}
c906108c
SS
4218Enable the specified breakpoints temporarily. @value{GDBN} disables any
4219of these breakpoints immediately after stopping your program.
4220
c5394b80 4221@item enable @r{[}breakpoints@r{]} delete @var{range}@dots{}
c906108c
SS
4222Enable the specified breakpoints to work once, then die. @value{GDBN}
4223deletes any of these breakpoints as soon as your program stops there.
09d4efe1 4224Breakpoints set by the @code{tbreak} command start out in this state.
c906108c
SS
4225@end table
4226
d4f3574e
SS
4227@c FIXME: I think the following ``Except for [...] @code{tbreak}'' is
4228@c confusing: tbreak is also initially enabled.
c906108c 4229Except for a breakpoint set with @code{tbreak} (@pxref{Set Breaks,
79a6e687 4230,Setting Breakpoints}), breakpoints that you set are initially enabled;
c906108c
SS
4231subsequently, they become disabled or enabled only when you use one of
4232the commands above. (The command @code{until} can set and delete a
4233breakpoint of its own, but it does not change the state of your other
4234breakpoints; see @ref{Continuing and Stepping, ,Continuing and
79a6e687 4235Stepping}.)
c906108c 4236
6d2ebf8b 4237@node Conditions
79a6e687 4238@subsection Break Conditions
c906108c
SS
4239@cindex conditional breakpoints
4240@cindex breakpoint conditions
4241
4242@c FIXME what is scope of break condition expr? Context where wanted?
5d161b24 4243@c in particular for a watchpoint?
c906108c
SS
4244The simplest sort of breakpoint breaks every time your program reaches a
4245specified place. You can also specify a @dfn{condition} for a
4246breakpoint. A condition is just a Boolean expression in your
4247programming language (@pxref{Expressions, ,Expressions}). A breakpoint with
4248a condition evaluates the expression each time your program reaches it,
4249and your program stops only if the condition is @emph{true}.
4250
4251This is the converse of using assertions for program validation; in that
4252situation, you want to stop when the assertion is violated---that is,
4253when the condition is false. In C, if you want to test an assertion expressed
4254by the condition @var{assert}, you should set the condition
4255@samp{! @var{assert}} on the appropriate breakpoint.
4256
4257Conditions are also accepted for watchpoints; you may not need them,
4258since a watchpoint is inspecting the value of an expression anyhow---but
4259it might be simpler, say, to just set a watchpoint on a variable name,
4260and specify a condition that tests whether the new value is an interesting
4261one.
4262
4263Break conditions can have side effects, and may even call functions in
4264your program. This can be useful, for example, to activate functions
4265that log program progress, or to use your own print functions to
99e008fe 4266format special data structures. The effects are completely predictable
c906108c
SS
4267unless there is another enabled breakpoint at the same address. (In
4268that case, @value{GDBN} might see the other breakpoint first and stop your
4269program without checking the condition of this one.) Note that
d4f3574e
SS
4270breakpoint commands are usually more convenient and flexible than break
4271conditions for the
c906108c 4272purpose of performing side effects when a breakpoint is reached
79a6e687 4273(@pxref{Break Commands, ,Breakpoint Command Lists}).
c906108c
SS
4274
4275Break conditions can be specified when a breakpoint is set, by using
4276@samp{if} in the arguments to the @code{break} command. @xref{Set
79a6e687 4277Breaks, ,Setting Breakpoints}. They can also be changed at any time
c906108c 4278with the @code{condition} command.
53a5351d 4279
c906108c
SS
4280You can also use the @code{if} keyword with the @code{watch} command.
4281The @code{catch} command does not recognize the @code{if} keyword;
4282@code{condition} is the only way to impose a further condition on a
4283catchpoint.
c906108c
SS
4284
4285@table @code
4286@kindex condition
4287@item condition @var{bnum} @var{expression}
4288Specify @var{expression} as the break condition for breakpoint,
4289watchpoint, or catchpoint number @var{bnum}. After you set a condition,
4290breakpoint @var{bnum} stops your program only if the value of
4291@var{expression} is true (nonzero, in C). When you use
4292@code{condition}, @value{GDBN} checks @var{expression} immediately for
4293syntactic correctness, and to determine whether symbols in it have
d4f3574e
SS
4294referents in the context of your breakpoint. If @var{expression} uses
4295symbols not referenced in the context of the breakpoint, @value{GDBN}
4296prints an error message:
4297
474c8240 4298@smallexample
d4f3574e 4299No symbol "foo" in current context.
474c8240 4300@end smallexample
d4f3574e
SS
4301
4302@noindent
c906108c
SS
4303@value{GDBN} does
4304not actually evaluate @var{expression} at the time the @code{condition}
d4f3574e
SS
4305command (or a command that sets a breakpoint with a condition, like
4306@code{break if @dots{}}) is given, however. @xref{Expressions, ,Expressions}.
c906108c
SS
4307
4308@item condition @var{bnum}
4309Remove the condition from breakpoint number @var{bnum}. It becomes
4310an ordinary unconditional breakpoint.
4311@end table
4312
4313@cindex ignore count (of breakpoint)
4314A special case of a breakpoint condition is to stop only when the
4315breakpoint has been reached a certain number of times. This is so
4316useful that there is a special way to do it, using the @dfn{ignore
4317count} of the breakpoint. Every breakpoint has an ignore count, which
4318is an integer. Most of the time, the ignore count is zero, and
4319therefore has no effect. But if your program reaches a breakpoint whose
4320ignore count is positive, then instead of stopping, it just decrements
4321the ignore count by one and continues. As a result, if the ignore count
4322value is @var{n}, the breakpoint does not stop the next @var{n} times
4323your program reaches it.
4324
4325@table @code
4326@kindex ignore
4327@item ignore @var{bnum} @var{count}
4328Set the ignore count of breakpoint number @var{bnum} to @var{count}.
4329The next @var{count} times the breakpoint is reached, your program's
4330execution does not stop; other than to decrement the ignore count, @value{GDBN}
4331takes no action.
4332
4333To make the breakpoint stop the next time it is reached, specify
4334a count of zero.
4335
4336When you use @code{continue} to resume execution of your program from a
4337breakpoint, you can specify an ignore count directly as an argument to
4338@code{continue}, rather than using @code{ignore}. @xref{Continuing and
79a6e687 4339Stepping,,Continuing and Stepping}.
c906108c
SS
4340
4341If a breakpoint has a positive ignore count and a condition, the
4342condition is not checked. Once the ignore count reaches zero,
4343@value{GDBN} resumes checking the condition.
4344
4345You could achieve the effect of the ignore count with a condition such
4346as @w{@samp{$foo-- <= 0}} using a debugger convenience variable that
4347is decremented each time. @xref{Convenience Vars, ,Convenience
79a6e687 4348Variables}.
c906108c
SS
4349@end table
4350
4351Ignore counts apply to breakpoints, watchpoints, and catchpoints.
4352
4353
6d2ebf8b 4354@node Break Commands
79a6e687 4355@subsection Breakpoint Command Lists
c906108c
SS
4356
4357@cindex breakpoint commands
4358You can give any breakpoint (or watchpoint or catchpoint) a series of
4359commands to execute when your program stops due to that breakpoint. For
4360example, you might want to print the values of certain expressions, or
4361enable other breakpoints.
4362
4363@table @code
4364@kindex commands
ca91424e 4365@kindex end@r{ (breakpoint commands)}
95a42b64 4366@item commands @r{[}@var{range}@dots{}@r{]}
c906108c
SS
4367@itemx @dots{} @var{command-list} @dots{}
4368@itemx end
95a42b64 4369Specify a list of commands for the given breakpoints. The commands
c906108c
SS
4370themselves appear on the following lines. Type a line containing just
4371@code{end} to terminate the commands.
4372
4373To remove all commands from a breakpoint, type @code{commands} and
4374follow it immediately with @code{end}; that is, give no commands.
4375
95a42b64
TT
4376With no argument, @code{commands} refers to the last breakpoint,
4377watchpoint, or catchpoint set (not to the breakpoint most recently
4378encountered). If the most recent breakpoints were set with a single
4379command, then the @code{commands} will apply to all the breakpoints
4380set by that command. This applies to breakpoints set by
86b17b60
PA
4381@code{rbreak}, and also applies when a single @code{break} command
4382creates multiple breakpoints (@pxref{Ambiguous Expressions,,Ambiguous
4383Expressions}).
c906108c
SS
4384@end table
4385
4386Pressing @key{RET} as a means of repeating the last @value{GDBN} command is
4387disabled within a @var{command-list}.
4388
4389You can use breakpoint commands to start your program up again. Simply
4390use the @code{continue} command, or @code{step}, or any other command
4391that resumes execution.
4392
4393Any other commands in the command list, after a command that resumes
4394execution, are ignored. This is because any time you resume execution
4395(even with a simple @code{next} or @code{step}), you may encounter
4396another breakpoint---which could have its own command list, leading to
4397ambiguities about which list to execute.
4398
4399@kindex silent
4400If the first command you specify in a command list is @code{silent}, the
4401usual message about stopping at a breakpoint is not printed. This may
4402be desirable for breakpoints that are to print a specific message and
4403then continue. If none of the remaining commands print anything, you
4404see no sign that the breakpoint was reached. @code{silent} is
4405meaningful only at the beginning of a breakpoint command list.
4406
4407The commands @code{echo}, @code{output}, and @code{printf} allow you to
4408print precisely controlled output, and are often useful in silent
79a6e687 4409breakpoints. @xref{Output, ,Commands for Controlled Output}.
c906108c
SS
4410
4411For example, here is how you could use breakpoint commands to print the
4412value of @code{x} at entry to @code{foo} whenever @code{x} is positive.
4413
474c8240 4414@smallexample
c906108c
SS
4415break foo if x>0
4416commands
4417silent
4418printf "x is %d\n",x
4419cont
4420end
474c8240 4421@end smallexample
c906108c
SS
4422
4423One application for breakpoint commands is to compensate for one bug so
4424you can test for another. Put a breakpoint just after the erroneous line
4425of code, give it a condition to detect the case in which something
4426erroneous has been done, and give it commands to assign correct values
4427to any variables that need them. End with the @code{continue} command
4428so that your program does not stop, and start with the @code{silent}
4429command so that no output is produced. Here is an example:
4430
474c8240 4431@smallexample
c906108c
SS
4432break 403
4433commands
4434silent
4435set x = y + 4
4436cont
4437end
474c8240 4438@end smallexample
c906108c 4439
6149aea9
PA
4440@node Save Breakpoints
4441@subsection How to save breakpoints to a file
4442
4443To save breakpoint definitions to a file use the @w{@code{save
4444breakpoints}} command.
4445
4446@table @code
4447@kindex save breakpoints
4448@cindex save breakpoints to a file for future sessions
4449@item save breakpoints [@var{filename}]
4450This command saves all current breakpoint definitions together with
4451their commands and ignore counts, into a file @file{@var{filename}}
4452suitable for use in a later debugging session. This includes all
4453types of breakpoints (breakpoints, watchpoints, catchpoints,
4454tracepoints). To read the saved breakpoint definitions, use the
4455@code{source} command (@pxref{Command Files}). Note that watchpoints
4456with expressions involving local variables may fail to be recreated
4457because it may not be possible to access the context where the
4458watchpoint is valid anymore. Because the saved breakpoint definitions
4459are simply a sequence of @value{GDBN} commands that recreate the
4460breakpoints, you can edit the file in your favorite editing program,
4461and remove the breakpoint definitions you're not interested in, or
4462that can no longer be recreated.
4463@end table
4464
c906108c 4465@c @ifclear BARETARGET
6d2ebf8b 4466@node Error in Breakpoints
d4f3574e 4467@subsection ``Cannot insert breakpoints''
c906108c 4468
fa3a767f
PA
4469If you request too many active hardware-assisted breakpoints and
4470watchpoints, you will see this error message:
d4f3574e
SS
4471
4472@c FIXME: the precise wording of this message may change; the relevant
4473@c source change is not committed yet (Sep 3, 1999).
4474@smallexample
4475Stopped; cannot insert breakpoints.
4476You may have requested too many hardware breakpoints and watchpoints.
4477@end smallexample
4478
4479@noindent
4480This message is printed when you attempt to resume the program, since
4481only then @value{GDBN} knows exactly how many hardware breakpoints and
4482watchpoints it needs to insert.
4483
4484When this message is printed, you need to disable or remove some of the
4485hardware-assisted breakpoints and watchpoints, and then continue.
4486
79a6e687 4487@node Breakpoint-related Warnings
1485d690
KB
4488@subsection ``Breakpoint address adjusted...''
4489@cindex breakpoint address adjusted
4490
4491Some processor architectures place constraints on the addresses at
4492which breakpoints may be placed. For architectures thus constrained,
4493@value{GDBN} will attempt to adjust the breakpoint's address to comply
4494with the constraints dictated by the architecture.
4495
4496One example of such an architecture is the Fujitsu FR-V. The FR-V is
4497a VLIW architecture in which a number of RISC-like instructions may be
4498bundled together for parallel execution. The FR-V architecture
4499constrains the location of a breakpoint instruction within such a
4500bundle to the instruction with the lowest address. @value{GDBN}
4501honors this constraint by adjusting a breakpoint's address to the
4502first in the bundle.
4503
4504It is not uncommon for optimized code to have bundles which contain
4505instructions from different source statements, thus it may happen that
4506a breakpoint's address will be adjusted from one source statement to
4507another. Since this adjustment may significantly alter @value{GDBN}'s
4508breakpoint related behavior from what the user expects, a warning is
4509printed when the breakpoint is first set and also when the breakpoint
4510is hit.
4511
4512A warning like the one below is printed when setting a breakpoint
4513that's been subject to address adjustment:
4514
4515@smallexample
4516warning: Breakpoint address adjusted from 0x00010414 to 0x00010410.
4517@end smallexample
4518
4519Such warnings are printed both for user settable and @value{GDBN}'s
4520internal breakpoints. If you see one of these warnings, you should
4521verify that a breakpoint set at the adjusted address will have the
4522desired affect. If not, the breakpoint in question may be removed and
b383017d 4523other breakpoints may be set which will have the desired behavior.
1485d690
KB
4524E.g., it may be sufficient to place the breakpoint at a later
4525instruction. A conditional breakpoint may also be useful in some
4526cases to prevent the breakpoint from triggering too often.
4527
4528@value{GDBN} will also issue a warning when stopping at one of these
4529adjusted breakpoints:
4530
4531@smallexample
4532warning: Breakpoint 1 address previously adjusted from 0x00010414
4533to 0x00010410.
4534@end smallexample
4535
4536When this warning is encountered, it may be too late to take remedial
4537action except in cases where the breakpoint is hit earlier or more
4538frequently than expected.
d4f3574e 4539
6d2ebf8b 4540@node Continuing and Stepping
79a6e687 4541@section Continuing and Stepping
c906108c
SS
4542
4543@cindex stepping
4544@cindex continuing
4545@cindex resuming execution
4546@dfn{Continuing} means resuming program execution until your program
4547completes normally. In contrast, @dfn{stepping} means executing just
4548one more ``step'' of your program, where ``step'' may mean either one
4549line of source code, or one machine instruction (depending on what
7a292a7a
SS
4550particular command you use). Either when continuing or when stepping,
4551your program may stop even sooner, due to a breakpoint or a signal. (If
d4f3574e
SS
4552it stops due to a signal, you may want to use @code{handle}, or use
4553@samp{signal 0} to resume execution. @xref{Signals, ,Signals}.)
c906108c
SS
4554
4555@table @code
4556@kindex continue
41afff9a
EZ
4557@kindex c @r{(@code{continue})}
4558@kindex fg @r{(resume foreground execution)}
c906108c
SS
4559@item continue @r{[}@var{ignore-count}@r{]}
4560@itemx c @r{[}@var{ignore-count}@r{]}
4561@itemx fg @r{[}@var{ignore-count}@r{]}
4562Resume program execution, at the address where your program last stopped;
4563any breakpoints set at that address are bypassed. The optional argument
4564@var{ignore-count} allows you to specify a further number of times to
4565ignore a breakpoint at this location; its effect is like that of
79a6e687 4566@code{ignore} (@pxref{Conditions, ,Break Conditions}).
c906108c
SS
4567
4568The argument @var{ignore-count} is meaningful only when your program
4569stopped due to a breakpoint. At other times, the argument to
4570@code{continue} is ignored.
4571
d4f3574e
SS
4572The synonyms @code{c} and @code{fg} (for @dfn{foreground}, as the
4573debugged program is deemed to be the foreground program) are provided
4574purely for convenience, and have exactly the same behavior as
4575@code{continue}.
c906108c
SS
4576@end table
4577
4578To resume execution at a different place, you can use @code{return}
79a6e687 4579(@pxref{Returning, ,Returning from a Function}) to go back to the
c906108c 4580calling function; or @code{jump} (@pxref{Jumping, ,Continuing at a
79a6e687 4581Different Address}) to go to an arbitrary location in your program.
c906108c
SS
4582
4583A typical technique for using stepping is to set a breakpoint
79a6e687 4584(@pxref{Breakpoints, ,Breakpoints; Watchpoints; and Catchpoints}) at the
c906108c
SS
4585beginning of the function or the section of your program where a problem
4586is believed to lie, run your program until it stops at that breakpoint,
4587and then step through the suspect area, examining the variables that are
4588interesting, until you see the problem happen.
4589
4590@table @code
4591@kindex step
41afff9a 4592@kindex s @r{(@code{step})}
c906108c
SS
4593@item step
4594Continue running your program until control reaches a different source
4595line, then stop it and return control to @value{GDBN}. This command is
4596abbreviated @code{s}.
4597
4598@quotation
4599@c "without debugging information" is imprecise; actually "without line
4600@c numbers in the debugging information". (gcc -g1 has debugging info but
4601@c not line numbers). But it seems complex to try to make that
4602@c distinction here.
4603@emph{Warning:} If you use the @code{step} command while control is
4604within a function that was compiled without debugging information,
4605execution proceeds until control reaches a function that does have
4606debugging information. Likewise, it will not step into a function which
4607is compiled without debugging information. To step through functions
4608without debugging information, use the @code{stepi} command, described
4609below.
4610@end quotation
4611
4a92d011
EZ
4612The @code{step} command only stops at the first instruction of a source
4613line. This prevents the multiple stops that could otherwise occur in
4614@code{switch} statements, @code{for} loops, etc. @code{step} continues
4615to stop if a function that has debugging information is called within
4616the line. In other words, @code{step} @emph{steps inside} any functions
4617called within the line.
c906108c 4618
d4f3574e
SS
4619Also, the @code{step} command only enters a function if there is line
4620number information for the function. Otherwise it acts like the
5d161b24 4621@code{next} command. This avoids problems when using @code{cc -gl}
c906108c 4622on MIPS machines. Previously, @code{step} entered subroutines if there
5d161b24 4623was any debugging information about the routine.
c906108c
SS
4624
4625@item step @var{count}
4626Continue running as in @code{step}, but do so @var{count} times. If a
7a292a7a
SS
4627breakpoint is reached, or a signal not related to stepping occurs before
4628@var{count} steps, stepping stops right away.
c906108c
SS
4629
4630@kindex next
41afff9a 4631@kindex n @r{(@code{next})}
c906108c
SS
4632@item next @r{[}@var{count}@r{]}
4633Continue to the next source line in the current (innermost) stack frame.
7a292a7a
SS
4634This is similar to @code{step}, but function calls that appear within
4635the line of code are executed without stopping. Execution stops when
4636control reaches a different line of code at the original stack level
4637that was executing when you gave the @code{next} command. This command
4638is abbreviated @code{n}.
c906108c
SS
4639
4640An argument @var{count} is a repeat count, as for @code{step}.
4641
4642
4643@c FIX ME!! Do we delete this, or is there a way it fits in with
4644@c the following paragraph? --- Vctoria
4645@c
4646@c @code{next} within a function that lacks debugging information acts like
4647@c @code{step}, but any function calls appearing within the code of the
4648@c function are executed without stopping.
4649
d4f3574e
SS
4650The @code{next} command only stops at the first instruction of a
4651source line. This prevents multiple stops that could otherwise occur in
4a92d011 4652@code{switch} statements, @code{for} loops, etc.
c906108c 4653
b90a5f51
CF
4654@kindex set step-mode
4655@item set step-mode
4656@cindex functions without line info, and stepping
4657@cindex stepping into functions with no line info
4658@itemx set step-mode on
4a92d011 4659The @code{set step-mode on} command causes the @code{step} command to
b90a5f51
CF
4660stop at the first instruction of a function which contains no debug line
4661information rather than stepping over it.
4662
4a92d011
EZ
4663This is useful in cases where you may be interested in inspecting the
4664machine instructions of a function which has no symbolic info and do not
4665want @value{GDBN} to automatically skip over this function.
b90a5f51
CF
4666
4667@item set step-mode off
4a92d011 4668Causes the @code{step} command to step over any functions which contains no
b90a5f51
CF
4669debug information. This is the default.
4670
9c16f35a
EZ
4671@item show step-mode
4672Show whether @value{GDBN} will stop in or step over functions without
4673source line debug information.
4674
c906108c 4675@kindex finish
8dfa32fc 4676@kindex fin @r{(@code{finish})}
c906108c
SS
4677@item finish
4678Continue running until just after function in the selected stack frame
8dfa32fc
JB
4679returns. Print the returned value (if any). This command can be
4680abbreviated as @code{fin}.
c906108c
SS
4681
4682Contrast this with the @code{return} command (@pxref{Returning,
79a6e687 4683,Returning from a Function}).
c906108c
SS
4684
4685@kindex until
41afff9a 4686@kindex u @r{(@code{until})}
09d4efe1 4687@cindex run until specified location
c906108c
SS
4688@item until
4689@itemx u
4690Continue running until a source line past the current line, in the
4691current stack frame, is reached. This command is used to avoid single
4692stepping through a loop more than once. It is like the @code{next}
4693command, except that when @code{until} encounters a jump, it
4694automatically continues execution until the program counter is greater
4695than the address of the jump.
4696
4697This means that when you reach the end of a loop after single stepping
4698though it, @code{until} makes your program continue execution until it
4699exits the loop. In contrast, a @code{next} command at the end of a loop
4700simply steps back to the beginning of the loop, which forces you to step
4701through the next iteration.
4702
4703@code{until} always stops your program if it attempts to exit the current
4704stack frame.
4705
4706@code{until} may produce somewhat counterintuitive results if the order
4707of machine code does not match the order of the source lines. For
4708example, in the following excerpt from a debugging session, the @code{f}
4709(@code{frame}) command shows that execution is stopped at line
4710@code{206}; yet when we use @code{until}, we get to line @code{195}:
4711
474c8240 4712@smallexample
c906108c
SS
4713(@value{GDBP}) f
4714#0 main (argc=4, argv=0xf7fffae8) at m4.c:206
4715206 expand_input();
4716(@value{GDBP}) until
4717195 for ( ; argc > 0; NEXTARG) @{
474c8240 4718@end smallexample
c906108c
SS
4719
4720This happened because, for execution efficiency, the compiler had
4721generated code for the loop closure test at the end, rather than the
4722start, of the loop---even though the test in a C @code{for}-loop is
4723written before the body of the loop. The @code{until} command appeared
4724to step back to the beginning of the loop when it advanced to this
4725expression; however, it has not really gone to an earlier
4726statement---not in terms of the actual machine code.
4727
4728@code{until} with no argument works by means of single
4729instruction stepping, and hence is slower than @code{until} with an
4730argument.
4731
4732@item until @var{location}
4733@itemx u @var{location}
4734Continue running your program until either the specified location is
4735reached, or the current stack frame returns. @var{location} is any of
2a25a5ba
EZ
4736the forms described in @ref{Specify Location}.
4737This form of the command uses temporary breakpoints, and
c60eb6f1
EZ
4738hence is quicker than @code{until} without an argument. The specified
4739location is actually reached only if it is in the current frame. This
4740implies that @code{until} can be used to skip over recursive function
4741invocations. For instance in the code below, if the current location is
4742line @code{96}, issuing @code{until 99} will execute the program up to
db2e3e2e 4743line @code{99} in the same invocation of factorial, i.e., after the inner
c60eb6f1
EZ
4744invocations have returned.
4745
4746@smallexample
474794 int factorial (int value)
474895 @{
474996 if (value > 1) @{
475097 value *= factorial (value - 1);
475198 @}
475299 return (value);
4753100 @}
4754@end smallexample
4755
4756
4757@kindex advance @var{location}
4758@itemx advance @var{location}
09d4efe1 4759Continue running the program up to the given @var{location}. An argument is
2a25a5ba
EZ
4760required, which should be of one of the forms described in
4761@ref{Specify Location}.
4762Execution will also stop upon exit from the current stack
c60eb6f1
EZ
4763frame. This command is similar to @code{until}, but @code{advance} will
4764not skip over recursive function calls, and the target location doesn't
4765have to be in the same frame as the current one.
4766
c906108c
SS
4767
4768@kindex stepi
41afff9a 4769@kindex si @r{(@code{stepi})}
c906108c 4770@item stepi
96a2c332 4771@itemx stepi @var{arg}
c906108c
SS
4772@itemx si
4773Execute one machine instruction, then stop and return to the debugger.
4774
4775It is often useful to do @samp{display/i $pc} when stepping by machine
4776instructions. This makes @value{GDBN} automatically display the next
4777instruction to be executed, each time your program stops. @xref{Auto
79a6e687 4778Display,, Automatic Display}.
c906108c
SS
4779
4780An argument is a repeat count, as in @code{step}.
4781
4782@need 750
4783@kindex nexti
41afff9a 4784@kindex ni @r{(@code{nexti})}
c906108c 4785@item nexti
96a2c332 4786@itemx nexti @var{arg}
c906108c
SS
4787@itemx ni
4788Execute one machine instruction, but if it is a function call,
4789proceed until the function returns.
4790
4791An argument is a repeat count, as in @code{next}.
4792@end table
4793
6d2ebf8b 4794@node Signals
c906108c
SS
4795@section Signals
4796@cindex signals
4797
4798A signal is an asynchronous event that can happen in a program. The
4799operating system defines the possible kinds of signals, and gives each
4800kind a name and a number. For example, in Unix @code{SIGINT} is the
c8aa23ab 4801signal a program gets when you type an interrupt character (often @kbd{Ctrl-c});
c906108c
SS
4802@code{SIGSEGV} is the signal a program gets from referencing a place in
4803memory far away from all the areas in use; @code{SIGALRM} occurs when
4804the alarm clock timer goes off (which happens only if your program has
4805requested an alarm).
4806
4807@cindex fatal signals
4808Some signals, including @code{SIGALRM}, are a normal part of the
4809functioning of your program. Others, such as @code{SIGSEGV}, indicate
d4f3574e 4810errors; these signals are @dfn{fatal} (they kill your program immediately) if the
c906108c
SS
4811program has not specified in advance some other way to handle the signal.
4812@code{SIGINT} does not indicate an error in your program, but it is normally
4813fatal so it can carry out the purpose of the interrupt: to kill the program.
4814
4815@value{GDBN} has the ability to detect any occurrence of a signal in your
4816program. You can tell @value{GDBN} in advance what to do for each kind of
4817signal.
4818
4819@cindex handling signals
24f93129
EZ
4820Normally, @value{GDBN} is set up to let the non-erroneous signals like
4821@code{SIGALRM} be silently passed to your program
4822(so as not to interfere with their role in the program's functioning)
c906108c
SS
4823but to stop your program immediately whenever an error signal happens.
4824You can change these settings with the @code{handle} command.
4825
4826@table @code
4827@kindex info signals
09d4efe1 4828@kindex info handle
c906108c 4829@item info signals
96a2c332 4830@itemx info handle
c906108c
SS
4831Print a table of all the kinds of signals and how @value{GDBN} has been told to
4832handle each one. You can use this to see the signal numbers of all
4833the defined types of signals.
4834
45ac1734
EZ
4835@item info signals @var{sig}
4836Similar, but print information only about the specified signal number.
4837
d4f3574e 4838@code{info handle} is an alias for @code{info signals}.
c906108c
SS
4839
4840@kindex handle
45ac1734 4841@item handle @var{signal} @r{[}@var{keywords}@dots{}@r{]}
5ece1a18
EZ
4842Change the way @value{GDBN} handles signal @var{signal}. @var{signal}
4843can be the number of a signal or its name (with or without the
24f93129 4844@samp{SIG} at the beginning); a list of signal numbers of the form
5ece1a18 4845@samp{@var{low}-@var{high}}; or the word @samp{all}, meaning all the
45ac1734
EZ
4846known signals. Optional arguments @var{keywords}, described below,
4847say what change to make.
c906108c
SS
4848@end table
4849
4850@c @group
4851The keywords allowed by the @code{handle} command can be abbreviated.
4852Their full names are:
4853
4854@table @code
4855@item nostop
4856@value{GDBN} should not stop your program when this signal happens. It may
4857still print a message telling you that the signal has come in.
4858
4859@item stop
4860@value{GDBN} should stop your program when this signal happens. This implies
4861the @code{print} keyword as well.
4862
4863@item print
4864@value{GDBN} should print a message when this signal happens.
4865
4866@item noprint
4867@value{GDBN} should not mention the occurrence of the signal at all. This
4868implies the @code{nostop} keyword as well.
4869
4870@item pass
5ece1a18 4871@itemx noignore
c906108c
SS
4872@value{GDBN} should allow your program to see this signal; your program
4873can handle the signal, or else it may terminate if the signal is fatal
5ece1a18 4874and not handled. @code{pass} and @code{noignore} are synonyms.
c906108c
SS
4875
4876@item nopass
5ece1a18 4877@itemx ignore
c906108c 4878@value{GDBN} should not allow your program to see this signal.
5ece1a18 4879@code{nopass} and @code{ignore} are synonyms.
c906108c
SS
4880@end table
4881@c @end group
4882
d4f3574e
SS
4883When a signal stops your program, the signal is not visible to the
4884program until you
c906108c
SS
4885continue. Your program sees the signal then, if @code{pass} is in
4886effect for the signal in question @emph{at that time}. In other words,
4887after @value{GDBN} reports a signal, you can use the @code{handle}
4888command with @code{pass} or @code{nopass} to control whether your
4889program sees that signal when you continue.
4890
24f93129
EZ
4891The default is set to @code{nostop}, @code{noprint}, @code{pass} for
4892non-erroneous signals such as @code{SIGALRM}, @code{SIGWINCH} and
4893@code{SIGCHLD}, and to @code{stop}, @code{print}, @code{pass} for the
4894erroneous signals.
4895
c906108c
SS
4896You can also use the @code{signal} command to prevent your program from
4897seeing a signal, or cause it to see a signal it normally would not see,
4898or to give it any signal at any time. For example, if your program stopped
4899due to some sort of memory reference error, you might store correct
4900values into the erroneous variables and continue, hoping to see more
4901execution; but your program would probably terminate immediately as
4902a result of the fatal signal once it saw the signal. To prevent this,
4903you can continue with @samp{signal 0}. @xref{Signaling, ,Giving your
79a6e687 4904Program a Signal}.
c906108c 4905
4aa995e1
PA
4906@cindex extra signal information
4907@anchor{extra signal information}
4908
4909On some targets, @value{GDBN} can inspect extra signal information
4910associated with the intercepted signal, before it is actually
4911delivered to the program being debugged. This information is exported
4912by the convenience variable @code{$_siginfo}, and consists of data
4913that is passed by the kernel to the signal handler at the time of the
4914receipt of a signal. The data type of the information itself is
4915target dependent. You can see the data type using the @code{ptype
4916$_siginfo} command. On Unix systems, it typically corresponds to the
4917standard @code{siginfo_t} type, as defined in the @file{signal.h}
4918system header.
4919
4920Here's an example, on a @sc{gnu}/Linux system, printing the stray
4921referenced address that raised a segmentation fault.
4922
4923@smallexample
4924@group
4925(@value{GDBP}) continue
4926Program received signal SIGSEGV, Segmentation fault.
49270x0000000000400766 in main ()
492869 *(int *)p = 0;
4929(@value{GDBP}) ptype $_siginfo
4930type = struct @{
4931 int si_signo;
4932 int si_errno;
4933 int si_code;
4934 union @{
4935 int _pad[28];
4936 struct @{...@} _kill;
4937 struct @{...@} _timer;
4938 struct @{...@} _rt;
4939 struct @{...@} _sigchld;
4940 struct @{...@} _sigfault;
4941 struct @{...@} _sigpoll;
4942 @} _sifields;
4943@}
4944(@value{GDBP}) ptype $_siginfo._sifields._sigfault
4945type = struct @{
4946 void *si_addr;
4947@}
4948(@value{GDBP}) p $_siginfo._sifields._sigfault.si_addr
4949$1 = (void *) 0x7ffff7ff7000
4950@end group
4951@end smallexample
4952
4953Depending on target support, @code{$_siginfo} may also be writable.
4954
6d2ebf8b 4955@node Thread Stops
79a6e687 4956@section Stopping and Starting Multi-thread Programs
c906108c 4957
0606b73b
SL
4958@cindex stopped threads
4959@cindex threads, stopped
4960
4961@cindex continuing threads
4962@cindex threads, continuing
4963
4964@value{GDBN} supports debugging programs with multiple threads
4965(@pxref{Threads,, Debugging Programs with Multiple Threads}). There
4966are two modes of controlling execution of your program within the
4967debugger. In the default mode, referred to as @dfn{all-stop mode},
4968when any thread in your program stops (for example, at a breakpoint
4969or while being stepped), all other threads in the program are also stopped by
4970@value{GDBN}. On some targets, @value{GDBN} also supports
4971@dfn{non-stop mode}, in which other threads can continue to run freely while
4972you examine the stopped thread in the debugger.
4973
4974@menu
4975* All-Stop Mode:: All threads stop when GDB takes control
4976* Non-Stop Mode:: Other threads continue to execute
4977* Background Execution:: Running your program asynchronously
4978* Thread-Specific Breakpoints:: Controlling breakpoints
4979* Interrupted System Calls:: GDB may interfere with system calls
d914c394 4980* Observer Mode:: GDB does not alter program behavior
0606b73b
SL
4981@end menu
4982
4983@node All-Stop Mode
4984@subsection All-Stop Mode
4985
4986@cindex all-stop mode
4987
4988In all-stop mode, whenever your program stops under @value{GDBN} for any reason,
4989@emph{all} threads of execution stop, not just the current thread. This
4990allows you to examine the overall state of the program, including
4991switching between threads, without worrying that things may change
4992underfoot.
4993
4994Conversely, whenever you restart the program, @emph{all} threads start
4995executing. @emph{This is true even when single-stepping} with commands
4996like @code{step} or @code{next}.
4997
4998In particular, @value{GDBN} cannot single-step all threads in lockstep.
4999Since thread scheduling is up to your debugging target's operating
5000system (not controlled by @value{GDBN}), other threads may
5001execute more than one statement while the current thread completes a
5002single step. Moreover, in general other threads stop in the middle of a
5003statement, rather than at a clean statement boundary, when the program
5004stops.
5005
5006You might even find your program stopped in another thread after
5007continuing or even single-stepping. This happens whenever some other
5008thread runs into a breakpoint, a signal, or an exception before the
5009first thread completes whatever you requested.
5010
5011@cindex automatic thread selection
5012@cindex switching threads automatically
5013@cindex threads, automatic switching
5014Whenever @value{GDBN} stops your program, due to a breakpoint or a
5015signal, it automatically selects the thread where that breakpoint or
5016signal happened. @value{GDBN} alerts you to the context switch with a
5017message such as @samp{[Switching to Thread @var{n}]} to identify the
5018thread.
5019
5020On some OSes, you can modify @value{GDBN}'s default behavior by
5021locking the OS scheduler to allow only a single thread to run.
5022
5023@table @code
5024@item set scheduler-locking @var{mode}
5025@cindex scheduler locking mode
5026@cindex lock scheduler
5027Set the scheduler locking mode. If it is @code{off}, then there is no
5028locking and any thread may run at any time. If @code{on}, then only the
5029current thread may run when the inferior is resumed. The @code{step}
5030mode optimizes for single-stepping; it prevents other threads
5031from preempting the current thread while you are stepping, so that
5032the focus of debugging does not change unexpectedly.
5033Other threads only rarely (or never) get a chance to run
5034when you step. They are more likely to run when you @samp{next} over a
5035function call, and they are completely free to run when you use commands
5036like @samp{continue}, @samp{until}, or @samp{finish}. However, unless another
5037thread hits a breakpoint during its timeslice, @value{GDBN} does not change
5038the current thread away from the thread that you are debugging.
5039
5040@item show scheduler-locking
5041Display the current scheduler locking mode.
5042@end table
5043
d4db2f36
PA
5044@cindex resume threads of multiple processes simultaneously
5045By default, when you issue one of the execution commands such as
5046@code{continue}, @code{next} or @code{step}, @value{GDBN} allows only
5047threads of the current inferior to run. For example, if @value{GDBN}
5048is attached to two inferiors, each with two threads, the
5049@code{continue} command resumes only the two threads of the current
5050inferior. This is useful, for example, when you debug a program that
5051forks and you want to hold the parent stopped (so that, for instance,
5052it doesn't run to exit), while you debug the child. In other
5053situations, you may not be interested in inspecting the current state
5054of any of the processes @value{GDBN} is attached to, and you may want
5055to resume them all until some breakpoint is hit. In the latter case,
5056you can instruct @value{GDBN} to allow all threads of all the
5057inferiors to run with the @w{@code{set schedule-multiple}} command.
5058
5059@table @code
5060@kindex set schedule-multiple
5061@item set schedule-multiple
5062Set the mode for allowing threads of multiple processes to be resumed
5063when an execution command is issued. When @code{on}, all threads of
5064all processes are allowed to run. When @code{off}, only the threads
5065of the current process are resumed. The default is @code{off}. The
5066@code{scheduler-locking} mode takes precedence when set to @code{on},
5067or while you are stepping and set to @code{step}.
5068
5069@item show schedule-multiple
5070Display the current mode for resuming the execution of threads of
5071multiple processes.
5072@end table
5073
0606b73b
SL
5074@node Non-Stop Mode
5075@subsection Non-Stop Mode
5076
5077@cindex non-stop mode
5078
5079@c This section is really only a place-holder, and needs to be expanded
5080@c with more details.
5081
5082For some multi-threaded targets, @value{GDBN} supports an optional
5083mode of operation in which you can examine stopped program threads in
5084the debugger while other threads continue to execute freely. This
5085minimizes intrusion when debugging live systems, such as programs
5086where some threads have real-time constraints or must continue to
5087respond to external events. This is referred to as @dfn{non-stop} mode.
5088
5089In non-stop mode, when a thread stops to report a debugging event,
5090@emph{only} that thread is stopped; @value{GDBN} does not stop other
5091threads as well, in contrast to the all-stop mode behavior. Additionally,
5092execution commands such as @code{continue} and @code{step} apply by default
5093only to the current thread in non-stop mode, rather than all threads as
5094in all-stop mode. This allows you to control threads explicitly in
5095ways that are not possible in all-stop mode --- for example, stepping
5096one thread while allowing others to run freely, stepping
5097one thread while holding all others stopped, or stepping several threads
5098independently and simultaneously.
5099
5100To enter non-stop mode, use this sequence of commands before you run
5101or attach to your program:
5102
0606b73b
SL
5103@smallexample
5104# Enable the async interface.
c6ebd6cf 5105set target-async 1
0606b73b 5106
0606b73b
SL
5107# If using the CLI, pagination breaks non-stop.
5108set pagination off
5109
5110# Finally, turn it on!
5111set non-stop on
5112@end smallexample
5113
5114You can use these commands to manipulate the non-stop mode setting:
5115
5116@table @code
5117@kindex set non-stop
5118@item set non-stop on
5119Enable selection of non-stop mode.
5120@item set non-stop off
5121Disable selection of non-stop mode.
5122@kindex show non-stop
5123@item show non-stop
5124Show the current non-stop enablement setting.
5125@end table
5126
5127Note these commands only reflect whether non-stop mode is enabled,
5128not whether the currently-executing program is being run in non-stop mode.
5129In particular, the @code{set non-stop} preference is only consulted when
5130@value{GDBN} starts or connects to the target program, and it is generally
5131not possible to switch modes once debugging has started. Furthermore,
5132since not all targets support non-stop mode, even when you have enabled
5133non-stop mode, @value{GDBN} may still fall back to all-stop operation by
5134default.
5135
5136In non-stop mode, all execution commands apply only to the current thread
5137by default. That is, @code{continue} only continues one thread.
5138To continue all threads, issue @code{continue -a} or @code{c -a}.
5139
5140You can use @value{GDBN}'s background execution commands
5141(@pxref{Background Execution}) to run some threads in the background
5142while you continue to examine or step others from @value{GDBN}.
5143The MI execution commands (@pxref{GDB/MI Program Execution}) are
5144always executed asynchronously in non-stop mode.
5145
5146Suspending execution is done with the @code{interrupt} command when
5147running in the background, or @kbd{Ctrl-c} during foreground execution.
5148In all-stop mode, this stops the whole process;
5149but in non-stop mode the interrupt applies only to the current thread.
5150To stop the whole program, use @code{interrupt -a}.
5151
5152Other execution commands do not currently support the @code{-a} option.
5153
5154In non-stop mode, when a thread stops, @value{GDBN} doesn't automatically make
5155that thread current, as it does in all-stop mode. This is because the
5156thread stop notifications are asynchronous with respect to @value{GDBN}'s
5157command interpreter, and it would be confusing if @value{GDBN} unexpectedly
5158changed to a different thread just as you entered a command to operate on the
5159previously current thread.
5160
5161@node Background Execution
5162@subsection Background Execution
5163
5164@cindex foreground execution
5165@cindex background execution
5166@cindex asynchronous execution
5167@cindex execution, foreground, background and asynchronous
5168
5169@value{GDBN}'s execution commands have two variants: the normal
5170foreground (synchronous) behavior, and a background
5171(asynchronous) behavior. In foreground execution, @value{GDBN} waits for
5172the program to report that some thread has stopped before prompting for
5173another command. In background execution, @value{GDBN} immediately gives
5174a command prompt so that you can issue other commands while your program runs.
5175
32fc0df9
PA
5176You need to explicitly enable asynchronous mode before you can use
5177background execution commands. You can use these commands to
5178manipulate the asynchronous mode setting:
5179
5180@table @code
5181@kindex set target-async
5182@item set target-async on
5183Enable asynchronous mode.
5184@item set target-async off
5185Disable asynchronous mode.
5186@kindex show target-async
5187@item show target-async
5188Show the current target-async setting.
5189@end table
5190
5191If the target doesn't support async mode, @value{GDBN} issues an error
5192message if you attempt to use the background execution commands.
5193
0606b73b
SL
5194To specify background execution, add a @code{&} to the command. For example,
5195the background form of the @code{continue} command is @code{continue&}, or
5196just @code{c&}. The execution commands that accept background execution
5197are:
5198
5199@table @code
5200@kindex run&
5201@item run
5202@xref{Starting, , Starting your Program}.
5203
5204@item attach
5205@kindex attach&
5206@xref{Attach, , Debugging an Already-running Process}.
5207
5208@item step
5209@kindex step&
5210@xref{Continuing and Stepping, step}.
5211
5212@item stepi
5213@kindex stepi&
5214@xref{Continuing and Stepping, stepi}.
5215
5216@item next
5217@kindex next&
5218@xref{Continuing and Stepping, next}.
5219
7ce58dd2
DE
5220@item nexti
5221@kindex nexti&
5222@xref{Continuing and Stepping, nexti}.
5223
0606b73b
SL
5224@item continue
5225@kindex continue&
5226@xref{Continuing and Stepping, continue}.
5227
5228@item finish
5229@kindex finish&
5230@xref{Continuing and Stepping, finish}.
5231
5232@item until
5233@kindex until&
5234@xref{Continuing and Stepping, until}.
5235
5236@end table
5237
5238Background execution is especially useful in conjunction with non-stop
5239mode for debugging programs with multiple threads; see @ref{Non-Stop Mode}.
5240However, you can also use these commands in the normal all-stop mode with
5241the restriction that you cannot issue another execution command until the
5242previous one finishes. Examples of commands that are valid in all-stop
5243mode while the program is running include @code{help} and @code{info break}.
5244
5245You can interrupt your program while it is running in the background by
5246using the @code{interrupt} command.
5247
5248@table @code
5249@kindex interrupt
5250@item interrupt
5251@itemx interrupt -a
5252
5253Suspend execution of the running program. In all-stop mode,
5254@code{interrupt} stops the whole process, but in non-stop mode, it stops
5255only the current thread. To stop the whole program in non-stop mode,
5256use @code{interrupt -a}.
5257@end table
5258
0606b73b
SL
5259@node Thread-Specific Breakpoints
5260@subsection Thread-Specific Breakpoints
5261
c906108c 5262When your program has multiple threads (@pxref{Threads,, Debugging
79a6e687 5263Programs with Multiple Threads}), you can choose whether to set
c906108c
SS
5264breakpoints on all threads, or on a particular thread.
5265
5266@table @code
5267@cindex breakpoints and threads
5268@cindex thread breakpoints
5269@kindex break @dots{} thread @var{threadno}
5270@item break @var{linespec} thread @var{threadno}
5271@itemx break @var{linespec} thread @var{threadno} if @dots{}
5272@var{linespec} specifies source lines; there are several ways of
2a25a5ba
EZ
5273writing them (@pxref{Specify Location}), but the effect is always to
5274specify some source line.
c906108c
SS
5275
5276Use the qualifier @samp{thread @var{threadno}} with a breakpoint command
5277to specify that you only want @value{GDBN} to stop the program when a
5278particular thread reaches this breakpoint. @var{threadno} is one of the
5279numeric thread identifiers assigned by @value{GDBN}, shown in the first
5280column of the @samp{info threads} display.
5281
5282If you do not specify @samp{thread @var{threadno}} when you set a
5283breakpoint, the breakpoint applies to @emph{all} threads of your
5284program.
5285
5286You can use the @code{thread} qualifier on conditional breakpoints as
b6199126
DJ
5287well; in this case, place @samp{thread @var{threadno}} before or
5288after the breakpoint condition, like this:
c906108c
SS
5289
5290@smallexample
2df3850c 5291(@value{GDBP}) break frik.c:13 thread 28 if bartab > lim
c906108c
SS
5292@end smallexample
5293
5294@end table
5295
0606b73b
SL
5296@node Interrupted System Calls
5297@subsection Interrupted System Calls
c906108c 5298
36d86913
MC
5299@cindex thread breakpoints and system calls
5300@cindex system calls and thread breakpoints
5301@cindex premature return from system calls
0606b73b
SL
5302There is an unfortunate side effect when using @value{GDBN} to debug
5303multi-threaded programs. If one thread stops for a
36d86913
MC
5304breakpoint, or for some other reason, and another thread is blocked in a
5305system call, then the system call may return prematurely. This is a
5306consequence of the interaction between multiple threads and the signals
5307that @value{GDBN} uses to implement breakpoints and other events that
5308stop execution.
5309
5310To handle this problem, your program should check the return value of
5311each system call and react appropriately. This is good programming
5312style anyways.
5313
5314For example, do not write code like this:
5315
5316@smallexample
5317 sleep (10);
5318@end smallexample
5319
5320The call to @code{sleep} will return early if a different thread stops
5321at a breakpoint or for some other reason.
5322
5323Instead, write this:
5324
5325@smallexample
5326 int unslept = 10;
5327 while (unslept > 0)
5328 unslept = sleep (unslept);
5329@end smallexample
5330
5331A system call is allowed to return early, so the system is still
5332conforming to its specification. But @value{GDBN} does cause your
5333multi-threaded program to behave differently than it would without
5334@value{GDBN}.
5335
5336Also, @value{GDBN} uses internal breakpoints in the thread library to
5337monitor certain events such as thread creation and thread destruction.
5338When such an event happens, a system call in another thread may return
5339prematurely, even though your program does not appear to stop.
5340
d914c394
SS
5341@node Observer Mode
5342@subsection Observer Mode
5343
5344If you want to build on non-stop mode and observe program behavior
5345without any chance of disruption by @value{GDBN}, you can set
5346variables to disable all of the debugger's attempts to modify state,
5347whether by writing memory, inserting breakpoints, etc. These operate
5348at a low level, intercepting operations from all commands.
5349
5350When all of these are set to @code{off}, then @value{GDBN} is said to
5351be @dfn{observer mode}. As a convenience, the variable
5352@code{observer} can be set to disable these, plus enable non-stop
5353mode.
5354
5355Note that @value{GDBN} will not prevent you from making nonsensical
5356combinations of these settings. For instance, if you have enabled
5357@code{may-insert-breakpoints} but disabled @code{may-write-memory},
5358then breakpoints that work by writing trap instructions into the code
5359stream will still not be able to be placed.
5360
5361@table @code
5362
5363@kindex observer
5364@item set observer on
5365@itemx set observer off
5366When set to @code{on}, this disables all the permission variables
5367below (except for @code{insert-fast-tracepoints}), plus enables
5368non-stop debugging. Setting this to @code{off} switches back to
5369normal debugging, though remaining in non-stop mode.
5370
5371@item show observer
5372Show whether observer mode is on or off.
5373
5374@kindex may-write-registers
5375@item set may-write-registers on
5376@itemx set may-write-registers off
5377This controls whether @value{GDBN} will attempt to alter the values of
5378registers, such as with assignment expressions in @code{print}, or the
5379@code{jump} command. It defaults to @code{on}.
5380
5381@item show may-write-registers
5382Show the current permission to write registers.
5383
5384@kindex may-write-memory
5385@item set may-write-memory on
5386@itemx set may-write-memory off
5387This controls whether @value{GDBN} will attempt to alter the contents
5388of memory, such as with assignment expressions in @code{print}. It
5389defaults to @code{on}.
5390
5391@item show may-write-memory
5392Show the current permission to write memory.
5393
5394@kindex may-insert-breakpoints
5395@item set may-insert-breakpoints on
5396@itemx set may-insert-breakpoints off
5397This controls whether @value{GDBN} will attempt to insert breakpoints.
5398This affects all breakpoints, including internal breakpoints defined
5399by @value{GDBN}. It defaults to @code{on}.
5400
5401@item show may-insert-breakpoints
5402Show the current permission to insert breakpoints.
5403
5404@kindex may-insert-tracepoints
5405@item set may-insert-tracepoints on
5406@itemx set may-insert-tracepoints off
5407This controls whether @value{GDBN} will attempt to insert (regular)
5408tracepoints at the beginning of a tracing experiment. It affects only
5409non-fast tracepoints, fast tracepoints being under the control of
5410@code{may-insert-fast-tracepoints}. It defaults to @code{on}.
5411
5412@item show may-insert-tracepoints
5413Show the current permission to insert tracepoints.
5414
5415@kindex may-insert-fast-tracepoints
5416@item set may-insert-fast-tracepoints on
5417@itemx set may-insert-fast-tracepoints off
5418This controls whether @value{GDBN} will attempt to insert fast
5419tracepoints at the beginning of a tracing experiment. It affects only
5420fast tracepoints, regular (non-fast) tracepoints being under the
5421control of @code{may-insert-tracepoints}. It defaults to @code{on}.
5422
5423@item show may-insert-fast-tracepoints
5424Show the current permission to insert fast tracepoints.
5425
5426@kindex may-interrupt
5427@item set may-interrupt on
5428@itemx set may-interrupt off
5429This controls whether @value{GDBN} will attempt to interrupt or stop
5430program execution. When this variable is @code{off}, the
5431@code{interrupt} command will have no effect, nor will
5432@kbd{Ctrl-c}. It defaults to @code{on}.
5433
5434@item show may-interrupt
5435Show the current permission to interrupt or stop the program.
5436
5437@end table
c906108c 5438
bacec72f
MS
5439@node Reverse Execution
5440@chapter Running programs backward
5441@cindex reverse execution
5442@cindex running programs backward
5443
5444When you are debugging a program, it is not unusual to realize that
5445you have gone too far, and some event of interest has already happened.
5446If the target environment supports it, @value{GDBN} can allow you to
5447``rewind'' the program by running it backward.
5448
5449A target environment that supports reverse execution should be able
5450to ``undo'' the changes in machine state that have taken place as the
5451program was executing normally. Variables, registers etc.@: should
5452revert to their previous values. Obviously this requires a great
5453deal of sophistication on the part of the target environment; not
5454all target environments can support reverse execution.
5455
5456When a program is executed in reverse, the instructions that
5457have most recently been executed are ``un-executed'', in reverse
5458order. The program counter runs backward, following the previous
5459thread of execution in reverse. As each instruction is ``un-executed'',
5460the values of memory and/or registers that were changed by that
5461instruction are reverted to their previous states. After executing
5462a piece of source code in reverse, all side effects of that code
5463should be ``undone'', and all variables should be returned to their
5464prior values@footnote{
5465Note that some side effects are easier to undo than others. For instance,
5466memory and registers are relatively easy, but device I/O is hard. Some
5467targets may be able undo things like device I/O, and some may not.
5468
5469The contract between @value{GDBN} and the reverse executing target
5470requires only that the target do something reasonable when
5471@value{GDBN} tells it to execute backwards, and then report the
5472results back to @value{GDBN}. Whatever the target reports back to
5473@value{GDBN}, @value{GDBN} will report back to the user. @value{GDBN}
5474assumes that the memory and registers that the target reports are in a
5475consistant state, but @value{GDBN} accepts whatever it is given.
5476}.
5477
5478If you are debugging in a target environment that supports
5479reverse execution, @value{GDBN} provides the following commands.
5480
5481@table @code
5482@kindex reverse-continue
5483@kindex rc @r{(@code{reverse-continue})}
5484@item reverse-continue @r{[}@var{ignore-count}@r{]}
5485@itemx rc @r{[}@var{ignore-count}@r{]}
5486Beginning at the point where your program last stopped, start executing
5487in reverse. Reverse execution will stop for breakpoints and synchronous
5488exceptions (signals), just like normal execution. Behavior of
5489asynchronous signals depends on the target environment.
5490
5491@kindex reverse-step
5492@kindex rs @r{(@code{step})}
5493@item reverse-step @r{[}@var{count}@r{]}
5494Run the program backward until control reaches the start of a
5495different source line; then stop it, and return control to @value{GDBN}.
5496
5497Like the @code{step} command, @code{reverse-step} will only stop
5498at the beginning of a source line. It ``un-executes'' the previously
5499executed source line. If the previous source line included calls to
5500debuggable functions, @code{reverse-step} will step (backward) into
5501the called function, stopping at the beginning of the @emph{last}
5502statement in the called function (typically a return statement).
5503
5504Also, as with the @code{step} command, if non-debuggable functions are
5505called, @code{reverse-step} will run thru them backward without stopping.
5506
5507@kindex reverse-stepi
5508@kindex rsi @r{(@code{reverse-stepi})}
5509@item reverse-stepi @r{[}@var{count}@r{]}
5510Reverse-execute one machine instruction. Note that the instruction
5511to be reverse-executed is @emph{not} the one pointed to by the program
5512counter, but the instruction executed prior to that one. For instance,
5513if the last instruction was a jump, @code{reverse-stepi} will take you
5514back from the destination of the jump to the jump instruction itself.
5515
5516@kindex reverse-next
5517@kindex rn @r{(@code{reverse-next})}
5518@item reverse-next @r{[}@var{count}@r{]}
5519Run backward to the beginning of the previous line executed in
5520the current (innermost) stack frame. If the line contains function
5521calls, they will be ``un-executed'' without stopping. Starting from
5522the first line of a function, @code{reverse-next} will take you back
5523to the caller of that function, @emph{before} the function was called,
5524just as the normal @code{next} command would take you from the last
5525line of a function back to its return to its caller
16af530a 5526@footnote{Unless the code is too heavily optimized.}.
bacec72f
MS
5527
5528@kindex reverse-nexti
5529@kindex rni @r{(@code{reverse-nexti})}
5530@item reverse-nexti @r{[}@var{count}@r{]}
5531Like @code{nexti}, @code{reverse-nexti} executes a single instruction
5532in reverse, except that called functions are ``un-executed'' atomically.
5533That is, if the previously executed instruction was a return from
540aa8e7 5534another function, @code{reverse-nexti} will continue to execute
bacec72f
MS
5535in reverse until the call to that function (from the current stack
5536frame) is reached.
5537
5538@kindex reverse-finish
5539@item reverse-finish
5540Just as the @code{finish} command takes you to the point where the
5541current function returns, @code{reverse-finish} takes you to the point
5542where it was called. Instead of ending up at the end of the current
5543function invocation, you end up at the beginning.
5544
5545@kindex set exec-direction
5546@item set exec-direction
5547Set the direction of target execution.
5548@itemx set exec-direction reverse
5549@cindex execute forward or backward in time
5550@value{GDBN} will perform all execution commands in reverse, until the
5551exec-direction mode is changed to ``forward''. Affected commands include
5552@code{step, stepi, next, nexti, continue, and finish}. The @code{return}
5553command cannot be used in reverse mode.
5554@item set exec-direction forward
5555@value{GDBN} will perform all execution commands in the normal fashion.
5556This is the default.
5557@end table
5558
c906108c 5559
a2311334
EZ
5560@node Process Record and Replay
5561@chapter Recording Inferior's Execution and Replaying It
53cc454a
HZ
5562@cindex process record and replay
5563@cindex recording inferior's execution and replaying it
5564
8e05493c
EZ
5565On some platforms, @value{GDBN} provides a special @dfn{process record
5566and replay} target that can record a log of the process execution, and
5567replay it later with both forward and reverse execution commands.
a2311334
EZ
5568
5569@cindex replay mode
5570When this target is in use, if the execution log includes the record
5571for the next instruction, @value{GDBN} will debug in @dfn{replay
5572mode}. In the replay mode, the inferior does not really execute code
5573instructions. Instead, all the events that normally happen during
5574code execution are taken from the execution log. While code is not
5575really executed in replay mode, the values of registers (including the
5576program counter register) and the memory of the inferior are still
8e05493c
EZ
5577changed as they normally would. Their contents are taken from the
5578execution log.
a2311334
EZ
5579
5580@cindex record mode
5581If the record for the next instruction is not in the execution log,
5582@value{GDBN} will debug in @dfn{record mode}. In this mode, the
5583inferior executes normally, and @value{GDBN} records the execution log
5584for future replay.
5585
8e05493c
EZ
5586The process record and replay target supports reverse execution
5587(@pxref{Reverse Execution}), even if the platform on which the
5588inferior runs does not. However, the reverse execution is limited in
5589this case by the range of the instructions recorded in the execution
5590log. In other words, reverse execution on platforms that don't
5591support it directly can only be done in the replay mode.
5592
5593When debugging in the reverse direction, @value{GDBN} will work in
5594replay mode as long as the execution log includes the record for the
5595previous instruction; otherwise, it will work in record mode, if the
5596platform supports reverse execution, or stop if not.
5597
a2311334
EZ
5598For architecture environments that support process record and replay,
5599@value{GDBN} provides the following commands:
53cc454a
HZ
5600
5601@table @code
5602@kindex target record
5603@kindex record
5604@kindex rec
5605@item target record
a2311334
EZ
5606This command starts the process record and replay target. The process
5607record and replay target can only debug a process that is already
5608running. Therefore, you need first to start the process with the
5609@kbd{run} or @kbd{start} commands, and then start the recording with
5610the @kbd{target record} command.
5611
5612Both @code{record} and @code{rec} are aliases of @code{target record}.
5613
5614@cindex displaced stepping, and process record and replay
5615Displaced stepping (@pxref{Maintenance Commands,, displaced stepping})
5616will be automatically disabled when process record and replay target
5617is started. That's because the process record and replay target
5618doesn't support displaced stepping.
5619
5620@cindex non-stop mode, and process record and replay
5621@cindex asynchronous execution, and process record and replay
5622If the inferior is in the non-stop mode (@pxref{Non-Stop Mode}) or in
5623the asynchronous execution mode (@pxref{Background Execution}), the
5624process record and replay target cannot be started because it doesn't
5625support these two modes.
53cc454a
HZ
5626
5627@kindex record stop
5628@kindex rec s
5629@item record stop
a2311334
EZ
5630Stop the process record and replay target. When process record and
5631replay target stops, the entire execution log will be deleted and the
5632inferior will either be terminated, or will remain in its final state.
53cc454a 5633
a2311334
EZ
5634When you stop the process record and replay target in record mode (at
5635the end of the execution log), the inferior will be stopped at the
5636next instruction that would have been recorded. In other words, if
5637you record for a while and then stop recording, the inferior process
5638will be left in the same state as if the recording never happened.
53cc454a 5639
a2311334
EZ
5640On the other hand, if the process record and replay target is stopped
5641while in replay mode (that is, not at the end of the execution log,
5642but at some earlier point), the inferior process will become ``live''
5643at that earlier state, and it will then be possible to continue the
5644usual ``live'' debugging of the process from that state.
53cc454a 5645
a2311334
EZ
5646When the inferior process exits, or @value{GDBN} detaches from it,
5647process record and replay target will automatically stop itself.
53cc454a 5648
24e933df
HZ
5649@kindex record save
5650@item record save @var{filename}
5651Save the execution log to a file @file{@var{filename}}.
5652Default filename is @file{gdb_record.@var{process_id}}, where
5653@var{process_id} is the process ID of the inferior.
5654
5655@kindex record restore
5656@item record restore @var{filename}
5657Restore the execution log from a file @file{@var{filename}}.
5658File must have been created with @code{record save}.
5659
53cc454a
HZ
5660@kindex set record insn-number-max
5661@item set record insn-number-max @var{limit}
5662Set the limit of instructions to be recorded. Default value is 200000.
5663
a2311334
EZ
5664If @var{limit} is a positive number, then @value{GDBN} will start
5665deleting instructions from the log once the number of the record
5666instructions becomes greater than @var{limit}. For every new recorded
5667instruction, @value{GDBN} will delete the earliest recorded
5668instruction to keep the number of recorded instructions at the limit.
5669(Since deleting recorded instructions loses information, @value{GDBN}
5670lets you control what happens when the limit is reached, by means of
5671the @code{stop-at-limit} option, described below.)
53cc454a 5672
a2311334
EZ
5673If @var{limit} is zero, @value{GDBN} will never delete recorded
5674instructions from the execution log. The number of recorded
5675instructions is unlimited in this case.
53cc454a
HZ
5676
5677@kindex show record insn-number-max
5678@item show record insn-number-max
a2311334 5679Show the limit of instructions to be recorded.
53cc454a
HZ
5680
5681@kindex set record stop-at-limit
a2311334
EZ
5682@item set record stop-at-limit
5683Control the behavior when the number of recorded instructions reaches
5684the limit. If ON (the default), @value{GDBN} will stop when the limit
5685is reached for the first time and ask you whether you want to stop the
5686inferior or continue running it and recording the execution log. If
5687you decide to continue recording, each new recorded instruction will
5688cause the oldest one to be deleted.
53cc454a 5689
a2311334
EZ
5690If this option is OFF, @value{GDBN} will automatically delete the
5691oldest record to make room for each new one, without asking.
53cc454a
HZ
5692
5693@kindex show record stop-at-limit
5694@item show record stop-at-limit
a2311334 5695Show the current setting of @code{stop-at-limit}.
53cc454a 5696
bb08c432
HZ
5697@kindex set record memory-query
5698@item set record memory-query
5699Control the behavior when @value{GDBN} is unable to record memory
5700changes caused by an instruction. If ON, @value{GDBN} will query
5701whether to stop the inferior in that case.
5702
5703If this option is OFF (the default), @value{GDBN} will automatically
5704ignore the effect of such instructions on memory. Later, when
5705@value{GDBN} replays this execution log, it will mark the log of this
5706instruction as not accessible, and it will not affect the replay
5707results.
5708
5709@kindex show record memory-query
5710@item show record memory-query
5711Show the current setting of @code{memory-query}.
5712
29153c24
MS
5713@kindex info record
5714@item info record
5715Show various statistics about the state of process record and its
5716in-memory execution log buffer, including:
5717
5718@itemize @bullet
5719@item
5720Whether in record mode or replay mode.
5721@item
5722Lowest recorded instruction number (counting from when the current execution log started recording instructions).
5723@item
5724Highest recorded instruction number.
5725@item
5726Current instruction about to be replayed (if in replay mode).
5727@item
5728Number of instructions contained in the execution log.
5729@item
5730Maximum number of instructions that may be contained in the execution log.
5731@end itemize
53cc454a
HZ
5732
5733@kindex record delete
5734@kindex rec del
5735@item record delete
a2311334 5736When record target runs in replay mode (``in the past''), delete the
53cc454a 5737subsequent execution log and begin to record a new execution log starting
a2311334 5738from the current address. This means you will abandon the previously
53cc454a
HZ
5739recorded ``future'' and begin recording a new ``future''.
5740@end table
5741
5742
6d2ebf8b 5743@node Stack
c906108c
SS
5744@chapter Examining the Stack
5745
5746When your program has stopped, the first thing you need to know is where it
5747stopped and how it got there.
5748
5749@cindex call stack
5d161b24
DB
5750Each time your program performs a function call, information about the call
5751is generated.
5752That information includes the location of the call in your program,
5753the arguments of the call,
c906108c 5754and the local variables of the function being called.
5d161b24 5755The information is saved in a block of data called a @dfn{stack frame}.
c906108c
SS
5756The stack frames are allocated in a region of memory called the @dfn{call
5757stack}.
5758
5759When your program stops, the @value{GDBN} commands for examining the
5760stack allow you to see all of this information.
5761
5762@cindex selected frame
5763One of the stack frames is @dfn{selected} by @value{GDBN} and many
5764@value{GDBN} commands refer implicitly to the selected frame. In
5765particular, whenever you ask @value{GDBN} for the value of a variable in
5766your program, the value is found in the selected frame. There are
5767special @value{GDBN} commands to select whichever frame you are
79a6e687 5768interested in. @xref{Selection, ,Selecting a Frame}.
c906108c
SS
5769
5770When your program stops, @value{GDBN} automatically selects the
5d161b24 5771currently executing frame and describes it briefly, similar to the
79a6e687 5772@code{frame} command (@pxref{Frame Info, ,Information about a Frame}).
c906108c
SS
5773
5774@menu
5775* Frames:: Stack frames
5776* Backtrace:: Backtraces
5777* Selection:: Selecting a frame
5778* Frame Info:: Information on a frame
c906108c
SS
5779
5780@end menu
5781
6d2ebf8b 5782@node Frames
79a6e687 5783@section Stack Frames
c906108c 5784
d4f3574e 5785@cindex frame, definition
c906108c
SS
5786@cindex stack frame
5787The call stack is divided up into contiguous pieces called @dfn{stack
5788frames}, or @dfn{frames} for short; each frame is the data associated
5789with one call to one function. The frame contains the arguments given
5790to the function, the function's local variables, and the address at
5791which the function is executing.
5792
5793@cindex initial frame
5794@cindex outermost frame
5795@cindex innermost frame
5796When your program is started, the stack has only one frame, that of the
5797function @code{main}. This is called the @dfn{initial} frame or the
5798@dfn{outermost} frame. Each time a function is called, a new frame is
5799made. Each time a function returns, the frame for that function invocation
5800is eliminated. If a function is recursive, there can be many frames for
5801the same function. The frame for the function in which execution is
5802actually occurring is called the @dfn{innermost} frame. This is the most
5803recently created of all the stack frames that still exist.
5804
5805@cindex frame pointer
5806Inside your program, stack frames are identified by their addresses. A
5807stack frame consists of many bytes, each of which has its own address; each
5808kind of computer has a convention for choosing one byte whose
5809address serves as the address of the frame. Usually this address is kept
e09f16f9
EZ
5810in a register called the @dfn{frame pointer register}
5811(@pxref{Registers, $fp}) while execution is going on in that frame.
c906108c
SS
5812
5813@cindex frame number
5814@value{GDBN} assigns numbers to all existing stack frames, starting with
5815zero for the innermost frame, one for the frame that called it,
5816and so on upward. These numbers do not really exist in your program;
5817they are assigned by @value{GDBN} to give you a way of designating stack
5818frames in @value{GDBN} commands.
5819
6d2ebf8b
SS
5820@c The -fomit-frame-pointer below perennially causes hbox overflow
5821@c underflow problems.
c906108c
SS
5822@cindex frameless execution
5823Some compilers provide a way to compile functions so that they operate
e22ea452 5824without stack frames. (For example, the @value{NGCC} option
474c8240 5825@smallexample
6d2ebf8b 5826@samp{-fomit-frame-pointer}
474c8240 5827@end smallexample
6d2ebf8b 5828generates functions without a frame.)
c906108c
SS
5829This is occasionally done with heavily used library functions to save
5830the frame setup time. @value{GDBN} has limited facilities for dealing
5831with these function invocations. If the innermost function invocation
5832has no stack frame, @value{GDBN} nevertheless regards it as though
5833it had a separate frame, which is numbered zero as usual, allowing
5834correct tracing of the function call chain. However, @value{GDBN} has
5835no provision for frameless functions elsewhere in the stack.
5836
5837@table @code
d4f3574e 5838@kindex frame@r{, command}
41afff9a 5839@cindex current stack frame
c906108c 5840@item frame @var{args}
5d161b24 5841The @code{frame} command allows you to move from one stack frame to another,
c906108c 5842and to print the stack frame you select. @var{args} may be either the
5d161b24
DB
5843address of the frame or the stack frame number. Without an argument,
5844@code{frame} prints the current stack frame.
c906108c
SS
5845
5846@kindex select-frame
41afff9a 5847@cindex selecting frame silently
c906108c
SS
5848@item select-frame
5849The @code{select-frame} command allows you to move from one stack frame
5850to another without printing the frame. This is the silent version of
5851@code{frame}.
5852@end table
5853
6d2ebf8b 5854@node Backtrace
c906108c
SS
5855@section Backtraces
5856
09d4efe1
EZ
5857@cindex traceback
5858@cindex call stack traces
c906108c
SS
5859A backtrace is a summary of how your program got where it is. It shows one
5860line per frame, for many frames, starting with the currently executing
5861frame (frame zero), followed by its caller (frame one), and on up the
5862stack.
5863
5864@table @code
5865@kindex backtrace
41afff9a 5866@kindex bt @r{(@code{backtrace})}
c906108c
SS
5867@item backtrace
5868@itemx bt
5869Print a backtrace of the entire stack: one line per frame for all
5870frames in the stack.
5871
5872You can stop the backtrace at any time by typing the system interrupt
c8aa23ab 5873character, normally @kbd{Ctrl-c}.
c906108c
SS
5874
5875@item backtrace @var{n}
5876@itemx bt @var{n}
5877Similar, but print only the innermost @var{n} frames.
5878
5879@item backtrace -@var{n}
5880@itemx bt -@var{n}
5881Similar, but print only the outermost @var{n} frames.
0f061b69
NR
5882
5883@item backtrace full
0f061b69 5884@itemx bt full
dd74f6ae
NR
5885@itemx bt full @var{n}
5886@itemx bt full -@var{n}
e7109c7e 5887Print the values of the local variables also. @var{n} specifies the
286ba84d 5888number of frames to print, as described above.
c906108c
SS
5889@end table
5890
5891@kindex where
5892@kindex info stack
c906108c
SS
5893The names @code{where} and @code{info stack} (abbreviated @code{info s})
5894are additional aliases for @code{backtrace}.
5895
839c27b7
EZ
5896@cindex multiple threads, backtrace
5897In a multi-threaded program, @value{GDBN} by default shows the
5898backtrace only for the current thread. To display the backtrace for
5899several or all of the threads, use the command @code{thread apply}
5900(@pxref{Threads, thread apply}). For example, if you type @kbd{thread
5901apply all backtrace}, @value{GDBN} will display the backtrace for all
5902the threads; this is handy when you debug a core dump of a
5903multi-threaded program.
5904
c906108c
SS
5905Each line in the backtrace shows the frame number and the function name.
5906The program counter value is also shown---unless you use @code{set
5907print address off}. The backtrace also shows the source file name and
5908line number, as well as the arguments to the function. The program
5909counter value is omitted if it is at the beginning of the code for that
5910line number.
5911
5912Here is an example of a backtrace. It was made with the command
5913@samp{bt 3}, so it shows the innermost three frames.
5914
5915@smallexample
5916@group
5d161b24 5917#0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8)
c906108c 5918 at builtin.c:993
4f5376b2 5919#1 0x6e38 in expand_macro (sym=0x2b600, data=...) at macro.c:242
c906108c
SS
5920#2 0x6840 in expand_token (obs=0x0, t=177664, td=0xf7fffb08)
5921 at macro.c:71
5922(More stack frames follow...)
5923@end group
5924@end smallexample
5925
5926@noindent
5927The display for frame zero does not begin with a program counter
5928value, indicating that your program has stopped at the beginning of the
5929code for line @code{993} of @code{builtin.c}.
5930
4f5376b2
JB
5931@noindent
5932The value of parameter @code{data} in frame 1 has been replaced by
5933@code{@dots{}}. By default, @value{GDBN} prints the value of a parameter
5934only if it is a scalar (integer, pointer, enumeration, etc). See command
5935@kbd{set print frame-arguments} in @ref{Print Settings} for more details
5936on how to configure the way function parameter values are printed.
5937
18999be5
EZ
5938@cindex value optimized out, in backtrace
5939@cindex function call arguments, optimized out
5940If your program was compiled with optimizations, some compilers will
5941optimize away arguments passed to functions if those arguments are
5942never used after the call. Such optimizations generate code that
5943passes arguments through registers, but doesn't store those arguments
5944in the stack frame. @value{GDBN} has no way of displaying such
5945arguments in stack frames other than the innermost one. Here's what
5946such a backtrace might look like:
5947
5948@smallexample
5949@group
5950#0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8)
5951 at builtin.c:993
5952#1 0x6e38 in expand_macro (sym=<value optimized out>) at macro.c:242
5953#2 0x6840 in expand_token (obs=0x0, t=<value optimized out>, td=0xf7fffb08)
5954 at macro.c:71
5955(More stack frames follow...)
5956@end group
5957@end smallexample
5958
5959@noindent
5960The values of arguments that were not saved in their stack frames are
5961shown as @samp{<value optimized out>}.
5962
5963If you need to display the values of such optimized-out arguments,
5964either deduce that from other variables whose values depend on the one
5965you are interested in, or recompile without optimizations.
5966
a8f24a35
EZ
5967@cindex backtrace beyond @code{main} function
5968@cindex program entry point
5969@cindex startup code, and backtrace
25d29d70
AC
5970Most programs have a standard user entry point---a place where system
5971libraries and startup code transition into user code. For C this is
d416eeec
EZ
5972@code{main}@footnote{
5973Note that embedded programs (the so-called ``free-standing''
5974environment) are not required to have a @code{main} function as the
5975entry point. They could even have multiple entry points.}.
5976When @value{GDBN} finds the entry function in a backtrace
25d29d70
AC
5977it will terminate the backtrace, to avoid tracing into highly
5978system-specific (and generally uninteresting) code.
5979
5980If you need to examine the startup code, or limit the number of levels
5981in a backtrace, you can change this behavior:
95f90d25
DJ
5982
5983@table @code
25d29d70
AC
5984@item set backtrace past-main
5985@itemx set backtrace past-main on
4644b6e3 5986@kindex set backtrace
25d29d70
AC
5987Backtraces will continue past the user entry point.
5988
5989@item set backtrace past-main off
95f90d25
DJ
5990Backtraces will stop when they encounter the user entry point. This is the
5991default.
5992
25d29d70 5993@item show backtrace past-main
4644b6e3 5994@kindex show backtrace
25d29d70
AC
5995Display the current user entry point backtrace policy.
5996
2315ffec
RC
5997@item set backtrace past-entry
5998@itemx set backtrace past-entry on
a8f24a35 5999Backtraces will continue past the internal entry point of an application.
2315ffec
RC
6000This entry point is encoded by the linker when the application is built,
6001and is likely before the user entry point @code{main} (or equivalent) is called.
6002
6003@item set backtrace past-entry off
d3e8051b 6004Backtraces will stop when they encounter the internal entry point of an
2315ffec
RC
6005application. This is the default.
6006
6007@item show backtrace past-entry
6008Display the current internal entry point backtrace policy.
6009
25d29d70
AC
6010@item set backtrace limit @var{n}
6011@itemx set backtrace limit 0
6012@cindex backtrace limit
6013Limit the backtrace to @var{n} levels. A value of zero means
6014unlimited.
95f90d25 6015
25d29d70
AC
6016@item show backtrace limit
6017Display the current limit on backtrace levels.
95f90d25
DJ
6018@end table
6019
6d2ebf8b 6020@node Selection
79a6e687 6021@section Selecting a Frame
c906108c
SS
6022
6023Most commands for examining the stack and other data in your program work on
6024whichever stack frame is selected at the moment. Here are the commands for
6025selecting a stack frame; all of them finish by printing a brief description
6026of the stack frame just selected.
6027
6028@table @code
d4f3574e 6029@kindex frame@r{, selecting}
41afff9a 6030@kindex f @r{(@code{frame})}
c906108c
SS
6031@item frame @var{n}
6032@itemx f @var{n}
6033Select frame number @var{n}. Recall that frame zero is the innermost
6034(currently executing) frame, frame one is the frame that called the
6035innermost one, and so on. The highest-numbered frame is the one for
6036@code{main}.
6037
6038@item frame @var{addr}
6039@itemx f @var{addr}
6040Select the frame at address @var{addr}. This is useful mainly if the
6041chaining of stack frames has been damaged by a bug, making it
6042impossible for @value{GDBN} to assign numbers properly to all frames. In
6043addition, this can be useful when your program has multiple stacks and
6044switches between them.
6045
c906108c
SS
6046On the SPARC architecture, @code{frame} needs two addresses to
6047select an arbitrary frame: a frame pointer and a stack pointer.
6048
6049On the MIPS and Alpha architecture, it needs two addresses: a stack
6050pointer and a program counter.
6051
6052On the 29k architecture, it needs three addresses: a register stack
6053pointer, a program counter, and a memory stack pointer.
c906108c
SS
6054
6055@kindex up
6056@item up @var{n}
6057Move @var{n} frames up the stack. For positive numbers @var{n}, this
6058advances toward the outermost frame, to higher frame numbers, to frames
6059that have existed longer. @var{n} defaults to one.
6060
6061@kindex down
41afff9a 6062@kindex do @r{(@code{down})}
c906108c
SS
6063@item down @var{n}
6064Move @var{n} frames down the stack. For positive numbers @var{n}, this
6065advances toward the innermost frame, to lower frame numbers, to frames
6066that were created more recently. @var{n} defaults to one. You may
6067abbreviate @code{down} as @code{do}.
6068@end table
6069
6070All of these commands end by printing two lines of output describing the
6071frame. The first line shows the frame number, the function name, the
6072arguments, and the source file and line number of execution in that
5d161b24 6073frame. The second line shows the text of that source line.
c906108c
SS
6074
6075@need 1000
6076For example:
6077
6078@smallexample
6079@group
6080(@value{GDBP}) up
6081#1 0x22f0 in main (argc=1, argv=0xf7fffbf4, env=0xf7fffbfc)
6082 at env.c:10
608310 read_input_file (argv[i]);
6084@end group
6085@end smallexample
6086
6087After such a printout, the @code{list} command with no arguments
6088prints ten lines centered on the point of execution in the frame.
87885426
FN
6089You can also edit the program at the point of execution with your favorite
6090editing program by typing @code{edit}.
79a6e687 6091@xref{List, ,Printing Source Lines},
87885426 6092for details.
c906108c
SS
6093
6094@table @code
6095@kindex down-silently
6096@kindex up-silently
6097@item up-silently @var{n}
6098@itemx down-silently @var{n}
6099These two commands are variants of @code{up} and @code{down},
6100respectively; they differ in that they do their work silently, without
6101causing display of the new frame. They are intended primarily for use
6102in @value{GDBN} command scripts, where the output might be unnecessary and
6103distracting.
6104@end table
6105
6d2ebf8b 6106@node Frame Info
79a6e687 6107@section Information About a Frame
c906108c
SS
6108
6109There are several other commands to print information about the selected
6110stack frame.
6111
6112@table @code
6113@item frame
6114@itemx f
6115When used without any argument, this command does not change which
6116frame is selected, but prints a brief description of the currently
6117selected stack frame. It can be abbreviated @code{f}. With an
6118argument, this command is used to select a stack frame.
79a6e687 6119@xref{Selection, ,Selecting a Frame}.
c906108c
SS
6120
6121@kindex info frame
41afff9a 6122@kindex info f @r{(@code{info frame})}
c906108c
SS
6123@item info frame
6124@itemx info f
6125This command prints a verbose description of the selected stack frame,
6126including:
6127
6128@itemize @bullet
5d161b24
DB
6129@item
6130the address of the frame
c906108c
SS
6131@item
6132the address of the next frame down (called by this frame)
6133@item
6134the address of the next frame up (caller of this frame)
6135@item
6136the language in which the source code corresponding to this frame is written
6137@item
6138the address of the frame's arguments
6139@item
d4f3574e
SS
6140the address of the frame's local variables
6141@item
c906108c
SS
6142the program counter saved in it (the address of execution in the caller frame)
6143@item
6144which registers were saved in the frame
6145@end itemize
6146
6147@noindent The verbose description is useful when
6148something has gone wrong that has made the stack format fail to fit
6149the usual conventions.
6150
6151@item info frame @var{addr}
6152@itemx info f @var{addr}
6153Print a verbose description of the frame at address @var{addr}, without
6154selecting that frame. The selected frame remains unchanged by this
6155command. This requires the same kind of address (more than one for some
6156architectures) that you specify in the @code{frame} command.
79a6e687 6157@xref{Selection, ,Selecting a Frame}.
c906108c
SS
6158
6159@kindex info args
6160@item info args
6161Print the arguments of the selected frame, each on a separate line.
6162
6163@item info locals
6164@kindex info locals
6165Print the local variables of the selected frame, each on a separate
6166line. These are all variables (declared either static or automatic)
6167accessible at the point of execution of the selected frame.
6168
c906108c 6169@kindex info catch
d4f3574e
SS
6170@cindex catch exceptions, list active handlers
6171@cindex exception handlers, how to list
c906108c
SS
6172@item info catch
6173Print a list of all the exception handlers that are active in the
6174current stack frame at the current point of execution. To see other
6175exception handlers, visit the associated frame (using the @code{up},
6176@code{down}, or @code{frame} commands); then type @code{info catch}.
79a6e687 6177@xref{Set Catchpoints, , Setting Catchpoints}.
53a5351d 6178
c906108c
SS
6179@end table
6180
c906108c 6181
6d2ebf8b 6182@node Source
c906108c
SS
6183@chapter Examining Source Files
6184
6185@value{GDBN} can print parts of your program's source, since the debugging
6186information recorded in the program tells @value{GDBN} what source files were
6187used to build it. When your program stops, @value{GDBN} spontaneously prints
6188the line where it stopped. Likewise, when you select a stack frame
79a6e687 6189(@pxref{Selection, ,Selecting a Frame}), @value{GDBN} prints the line where
c906108c
SS
6190execution in that frame has stopped. You can print other portions of
6191source files by explicit command.
6192
7a292a7a 6193If you use @value{GDBN} through its @sc{gnu} Emacs interface, you may
d4f3574e 6194prefer to use Emacs facilities to view source; see @ref{Emacs, ,Using
7a292a7a 6195@value{GDBN} under @sc{gnu} Emacs}.
c906108c
SS
6196
6197@menu
6198* List:: Printing source lines
2a25a5ba 6199* Specify Location:: How to specify code locations
87885426 6200* Edit:: Editing source files
c906108c 6201* Search:: Searching source files
c906108c
SS
6202* Source Path:: Specifying source directories
6203* Machine Code:: Source and machine code
6204@end menu
6205
6d2ebf8b 6206@node List
79a6e687 6207@section Printing Source Lines
c906108c
SS
6208
6209@kindex list
41afff9a 6210@kindex l @r{(@code{list})}
c906108c 6211To print lines from a source file, use the @code{list} command
5d161b24 6212(abbreviated @code{l}). By default, ten lines are printed.
2a25a5ba
EZ
6213There are several ways to specify what part of the file you want to
6214print; see @ref{Specify Location}, for the full list.
c906108c
SS
6215
6216Here are the forms of the @code{list} command most commonly used:
6217
6218@table @code
6219@item list @var{linenum}
6220Print lines centered around line number @var{linenum} in the
6221current source file.
6222
6223@item list @var{function}
6224Print lines centered around the beginning of function
6225@var{function}.
6226
6227@item list
6228Print more lines. If the last lines printed were printed with a
6229@code{list} command, this prints lines following the last lines
6230printed; however, if the last line printed was a solitary line printed
6231as part of displaying a stack frame (@pxref{Stack, ,Examining the
6232Stack}), this prints lines centered around that line.
6233
6234@item list -
6235Print lines just before the lines last printed.
6236@end table
6237
9c16f35a 6238@cindex @code{list}, how many lines to display
c906108c
SS
6239By default, @value{GDBN} prints ten source lines with any of these forms of
6240the @code{list} command. You can change this using @code{set listsize}:
6241
6242@table @code
6243@kindex set listsize
6244@item set listsize @var{count}
6245Make the @code{list} command display @var{count} source lines (unless
6246the @code{list} argument explicitly specifies some other number).
6247
6248@kindex show listsize
6249@item show listsize
6250Display the number of lines that @code{list} prints.
6251@end table
6252
6253Repeating a @code{list} command with @key{RET} discards the argument,
6254so it is equivalent to typing just @code{list}. This is more useful
6255than listing the same lines again. An exception is made for an
6256argument of @samp{-}; that argument is preserved in repetition so that
6257each repetition moves up in the source file.
6258
c906108c
SS
6259In general, the @code{list} command expects you to supply zero, one or two
6260@dfn{linespecs}. Linespecs specify source lines; there are several ways
2a25a5ba
EZ
6261of writing them (@pxref{Specify Location}), but the effect is always
6262to specify some source line.
6263
c906108c
SS
6264Here is a complete description of the possible arguments for @code{list}:
6265
6266@table @code
6267@item list @var{linespec}
6268Print lines centered around the line specified by @var{linespec}.
6269
6270@item list @var{first},@var{last}
6271Print lines from @var{first} to @var{last}. Both arguments are
2a25a5ba
EZ
6272linespecs. When a @code{list} command has two linespecs, and the
6273source file of the second linespec is omitted, this refers to
6274the same source file as the first linespec.
c906108c
SS
6275
6276@item list ,@var{last}
6277Print lines ending with @var{last}.
6278
6279@item list @var{first},
6280Print lines starting with @var{first}.
6281
6282@item list +
6283Print lines just after the lines last printed.
6284
6285@item list -
6286Print lines just before the lines last printed.
6287
6288@item list
6289As described in the preceding table.
6290@end table
6291
2a25a5ba
EZ
6292@node Specify Location
6293@section Specifying a Location
6294@cindex specifying location
6295@cindex linespec
c906108c 6296
2a25a5ba
EZ
6297Several @value{GDBN} commands accept arguments that specify a location
6298of your program's code. Since @value{GDBN} is a source-level
6299debugger, a location usually specifies some line in the source code;
6300for that reason, locations are also known as @dfn{linespecs}.
c906108c 6301
2a25a5ba
EZ
6302Here are all the different ways of specifying a code location that
6303@value{GDBN} understands:
c906108c 6304
2a25a5ba
EZ
6305@table @code
6306@item @var{linenum}
6307Specifies the line number @var{linenum} of the current source file.
c906108c 6308
2a25a5ba
EZ
6309@item -@var{offset}
6310@itemx +@var{offset}
6311Specifies the line @var{offset} lines before or after the @dfn{current
6312line}. For the @code{list} command, the current line is the last one
6313printed; for the breakpoint commands, this is the line at which
6314execution stopped in the currently selected @dfn{stack frame}
6315(@pxref{Frames, ,Frames}, for a description of stack frames.) When
6316used as the second of the two linespecs in a @code{list} command,
6317this specifies the line @var{offset} lines up or down from the first
6318linespec.
6319
6320@item @var{filename}:@var{linenum}
6321Specifies the line @var{linenum} in the source file @var{filename}.
c906108c
SS
6322
6323@item @var{function}
6324Specifies the line that begins the body of the function @var{function}.
2a25a5ba 6325For example, in C, this is the line with the open brace.
c906108c
SS
6326
6327@item @var{filename}:@var{function}
2a25a5ba
EZ
6328Specifies the line that begins the body of the function @var{function}
6329in the file @var{filename}. You only need the file name with a
6330function name to avoid ambiguity when there are identically named
6331functions in different source files.
c906108c 6332
0f5238ed
TT
6333@item @var{label}
6334Specifies the line at which the label named @var{label} appears.
6335@value{GDBN} searches for the label in the function corresponding to
6336the currently selected stack frame. If there is no current selected
6337stack frame (for instance, if the inferior is not running), then
6338@value{GDBN} will not search for a label.
6339
c906108c 6340@item *@var{address}
2a25a5ba
EZ
6341Specifies the program address @var{address}. For line-oriented
6342commands, such as @code{list} and @code{edit}, this specifies a source
6343line that contains @var{address}. For @code{break} and other
6344breakpoint oriented commands, this can be used to set breakpoints in
6345parts of your program which do not have debugging information or
6346source files.
6347
6348Here @var{address} may be any expression valid in the current working
6349language (@pxref{Languages, working language}) that specifies a code
5fa54e5d
EZ
6350address. In addition, as a convenience, @value{GDBN} extends the
6351semantics of expressions used in locations to cover the situations
6352that frequently happen during debugging. Here are the various forms
6353of @var{address}:
2a25a5ba
EZ
6354
6355@table @code
6356@item @var{expression}
6357Any expression valid in the current working language.
6358
6359@item @var{funcaddr}
6360An address of a function or procedure derived from its name. In C,
6361C@t{++}, Java, Objective-C, Fortran, minimal, and assembly, this is
6362simply the function's name @var{function} (and actually a special case
6363of a valid expression). In Pascal and Modula-2, this is
6364@code{&@var{function}}. In Ada, this is @code{@var{function}'Address}
6365(although the Pascal form also works).
6366
6367This form specifies the address of the function's first instruction,
6368before the stack frame and arguments have been set up.
6369
6370@item '@var{filename}'::@var{funcaddr}
6371Like @var{funcaddr} above, but also specifies the name of the source
6372file explicitly. This is useful if the name of the function does not
6373specify the function unambiguously, e.g., if there are several
6374functions with identical names in different source files.
c906108c
SS
6375@end table
6376
2a25a5ba
EZ
6377@end table
6378
6379
87885426 6380@node Edit
79a6e687 6381@section Editing Source Files
87885426
FN
6382@cindex editing source files
6383
6384@kindex edit
6385@kindex e @r{(@code{edit})}
6386To edit the lines in a source file, use the @code{edit} command.
6387The editing program of your choice
6388is invoked with the current line set to
6389the active line in the program.
6390Alternatively, there are several ways to specify what part of the file you
2a25a5ba 6391want to print if you want to see other parts of the program:
87885426
FN
6392
6393@table @code
2a25a5ba
EZ
6394@item edit @var{location}
6395Edit the source file specified by @code{location}. Editing starts at
6396that @var{location}, e.g., at the specified source line of the
6397specified file. @xref{Specify Location}, for all the possible forms
6398of the @var{location} argument; here are the forms of the @code{edit}
6399command most commonly used:
87885426 6400
2a25a5ba 6401@table @code
87885426
FN
6402@item edit @var{number}
6403Edit the current source file with @var{number} as the active line number.
6404
6405@item edit @var{function}
6406Edit the file containing @var{function} at the beginning of its definition.
2a25a5ba 6407@end table
87885426 6408
87885426
FN
6409@end table
6410
79a6e687 6411@subsection Choosing your Editor
87885426
FN
6412You can customize @value{GDBN} to use any editor you want
6413@footnote{
6414The only restriction is that your editor (say @code{ex}), recognizes the
6415following command-line syntax:
10998722 6416@smallexample
87885426 6417ex +@var{number} file
10998722 6418@end smallexample
15387254
EZ
6419The optional numeric value +@var{number} specifies the number of the line in
6420the file where to start editing.}.
6421By default, it is @file{@value{EDITOR}}, but you can change this
10998722
AC
6422by setting the environment variable @code{EDITOR} before using
6423@value{GDBN}. For example, to configure @value{GDBN} to use the
6424@code{vi} editor, you could use these commands with the @code{sh} shell:
6425@smallexample
87885426
FN
6426EDITOR=/usr/bin/vi
6427export EDITOR
15387254 6428gdb @dots{}
10998722 6429@end smallexample
87885426 6430or in the @code{csh} shell,
10998722 6431@smallexample
87885426 6432setenv EDITOR /usr/bin/vi
15387254 6433gdb @dots{}
10998722 6434@end smallexample
87885426 6435
6d2ebf8b 6436@node Search
79a6e687 6437@section Searching Source Files
15387254 6438@cindex searching source files
c906108c
SS
6439
6440There are two commands for searching through the current source file for a
6441regular expression.
6442
6443@table @code
6444@kindex search
6445@kindex forward-search
6446@item forward-search @var{regexp}
6447@itemx search @var{regexp}
6448The command @samp{forward-search @var{regexp}} checks each line,
6449starting with the one following the last line listed, for a match for
5d161b24 6450@var{regexp}. It lists the line that is found. You can use the
c906108c
SS
6451synonym @samp{search @var{regexp}} or abbreviate the command name as
6452@code{fo}.
6453
09d4efe1 6454@kindex reverse-search
c906108c
SS
6455@item reverse-search @var{regexp}
6456The command @samp{reverse-search @var{regexp}} checks each line, starting
6457with the one before the last line listed and going backward, for a match
6458for @var{regexp}. It lists the line that is found. You can abbreviate
6459this command as @code{rev}.
6460@end table
c906108c 6461
6d2ebf8b 6462@node Source Path
79a6e687 6463@section Specifying Source Directories
c906108c
SS
6464
6465@cindex source path
6466@cindex directories for source files
6467Executable programs sometimes do not record the directories of the source
6468files from which they were compiled, just the names. Even when they do,
6469the directories could be moved between the compilation and your debugging
6470session. @value{GDBN} has a list of directories to search for source files;
6471this is called the @dfn{source path}. Each time @value{GDBN} wants a source file,
6472it tries all the directories in the list, in the order they are present
0b66e38c
EZ
6473in the list, until it finds a file with the desired name.
6474
6475For example, suppose an executable references the file
6476@file{/usr/src/foo-1.0/lib/foo.c}, and our source path is
6477@file{/mnt/cross}. The file is first looked up literally; if this
6478fails, @file{/mnt/cross/usr/src/foo-1.0/lib/foo.c} is tried; if this
6479fails, @file{/mnt/cross/foo.c} is opened; if this fails, an error
6480message is printed. @value{GDBN} does not look up the parts of the
6481source file name, such as @file{/mnt/cross/src/foo-1.0/lib/foo.c}.
6482Likewise, the subdirectories of the source path are not searched: if
6483the source path is @file{/mnt/cross}, and the binary refers to
6484@file{foo.c}, @value{GDBN} would not find it under
6485@file{/mnt/cross/usr/src/foo-1.0/lib}.
6486
6487Plain file names, relative file names with leading directories, file
6488names containing dots, etc.@: are all treated as described above; for
6489instance, if the source path is @file{/mnt/cross}, and the source file
6490is recorded as @file{../lib/foo.c}, @value{GDBN} would first try
6491@file{../lib/foo.c}, then @file{/mnt/cross/../lib/foo.c}, and after
6492that---@file{/mnt/cross/foo.c}.
6493
6494Note that the executable search path is @emph{not} used to locate the
cd852561 6495source files.
c906108c
SS
6496
6497Whenever you reset or rearrange the source path, @value{GDBN} clears out
6498any information it has cached about where source files are found and where
6499each line is in the file.
6500
6501@kindex directory
6502@kindex dir
d4f3574e
SS
6503When you start @value{GDBN}, its source path includes only @samp{cdir}
6504and @samp{cwd}, in that order.
c906108c
SS
6505To add other directories, use the @code{directory} command.
6506
4b505b12
AS
6507The search path is used to find both program source files and @value{GDBN}
6508script files (read using the @samp{-command} option and @samp{source} command).
6509
30daae6c
JB
6510In addition to the source path, @value{GDBN} provides a set of commands
6511that manage a list of source path substitution rules. A @dfn{substitution
6512rule} specifies how to rewrite source directories stored in the program's
6513debug information in case the sources were moved to a different
6514directory between compilation and debugging. A rule is made of
6515two strings, the first specifying what needs to be rewritten in
6516the path, and the second specifying how it should be rewritten.
6517In @ref{set substitute-path}, we name these two parts @var{from} and
6518@var{to} respectively. @value{GDBN} does a simple string replacement
6519of @var{from} with @var{to} at the start of the directory part of the
6520source file name, and uses that result instead of the original file
6521name to look up the sources.
6522
6523Using the previous example, suppose the @file{foo-1.0} tree has been
6524moved from @file{/usr/src} to @file{/mnt/cross}, then you can tell
3f94c067 6525@value{GDBN} to replace @file{/usr/src} in all source path names with
30daae6c
JB
6526@file{/mnt/cross}. The first lookup will then be
6527@file{/mnt/cross/foo-1.0/lib/foo.c} in place of the original location
6528of @file{/usr/src/foo-1.0/lib/foo.c}. To define a source path
6529substitution rule, use the @code{set substitute-path} command
6530(@pxref{set substitute-path}).
6531
6532To avoid unexpected substitution results, a rule is applied only if the
6533@var{from} part of the directory name ends at a directory separator.
6534For instance, a rule substituting @file{/usr/source} into
6535@file{/mnt/cross} will be applied to @file{/usr/source/foo-1.0} but
6536not to @file{/usr/sourceware/foo-2.0}. And because the substitution
d3e8051b 6537is applied only at the beginning of the directory name, this rule will
30daae6c
JB
6538not be applied to @file{/root/usr/source/baz.c} either.
6539
6540In many cases, you can achieve the same result using the @code{directory}
6541command. However, @code{set substitute-path} can be more efficient in
6542the case where the sources are organized in a complex tree with multiple
6543subdirectories. With the @code{directory} command, you need to add each
6544subdirectory of your project. If you moved the entire tree while
6545preserving its internal organization, then @code{set substitute-path}
6546allows you to direct the debugger to all the sources with one single
6547command.
6548
6549@code{set substitute-path} is also more than just a shortcut command.
6550The source path is only used if the file at the original location no
6551longer exists. On the other hand, @code{set substitute-path} modifies
6552the debugger behavior to look at the rewritten location instead. So, if
6553for any reason a source file that is not relevant to your executable is
6554located at the original location, a substitution rule is the only
3f94c067 6555method available to point @value{GDBN} at the new location.
30daae6c 6556
29b0e8a2
JM
6557@cindex @samp{--with-relocated-sources}
6558@cindex default source path substitution
6559You can configure a default source path substitution rule by
6560configuring @value{GDBN} with the
6561@samp{--with-relocated-sources=@var{dir}} option. The @var{dir}
6562should be the name of a directory under @value{GDBN}'s configured
6563prefix (set with @samp{--prefix} or @samp{--exec-prefix}), and
6564directory names in debug information under @var{dir} will be adjusted
6565automatically if the installed @value{GDBN} is moved to a new
6566location. This is useful if @value{GDBN}, libraries or executables
6567with debug information and corresponding source code are being moved
6568together.
6569
c906108c
SS
6570@table @code
6571@item directory @var{dirname} @dots{}
6572@item dir @var{dirname} @dots{}
6573Add directory @var{dirname} to the front of the source path. Several
d4f3574e
SS
6574directory names may be given to this command, separated by @samp{:}
6575(@samp{;} on MS-DOS and MS-Windows, where @samp{:} usually appears as
6576part of absolute file names) or
c906108c
SS
6577whitespace. You may specify a directory that is already in the source
6578path; this moves it forward, so @value{GDBN} searches it sooner.
6579
6580@kindex cdir
6581@kindex cwd
41afff9a 6582@vindex $cdir@r{, convenience variable}
d3e8051b 6583@vindex $cwd@r{, convenience variable}
c906108c
SS
6584@cindex compilation directory
6585@cindex current directory
6586@cindex working directory
6587@cindex directory, current
6588@cindex directory, compilation
6589You can use the string @samp{$cdir} to refer to the compilation
6590directory (if one is recorded), and @samp{$cwd} to refer to the current
6591working directory. @samp{$cwd} is not the same as @samp{.}---the former
6592tracks the current working directory as it changes during your @value{GDBN}
6593session, while the latter is immediately expanded to the current
6594directory at the time you add an entry to the source path.
6595
6596@item directory
cd852561 6597Reset the source path to its default value (@samp{$cdir:$cwd} on Unix systems). This requires confirmation.
c906108c
SS
6598
6599@c RET-repeat for @code{directory} is explicitly disabled, but since
6600@c repeating it would be a no-op we do not say that. (thanks to RMS)
6601
6602@item show directories
6603@kindex show directories
6604Print the source path: show which directories it contains.
30daae6c
JB
6605
6606@anchor{set substitute-path}
6607@item set substitute-path @var{from} @var{to}
6608@kindex set substitute-path
6609Define a source path substitution rule, and add it at the end of the
6610current list of existing substitution rules. If a rule with the same
6611@var{from} was already defined, then the old rule is also deleted.
6612
6613For example, if the file @file{/foo/bar/baz.c} was moved to
6614@file{/mnt/cross/baz.c}, then the command
6615
6616@smallexample
6617(@value{GDBP}) set substitute-path /usr/src /mnt/cross
6618@end smallexample
6619
6620@noindent
6621will tell @value{GDBN} to replace @samp{/usr/src} with
6622@samp{/mnt/cross}, which will allow @value{GDBN} to find the file
6623@file{baz.c} even though it was moved.
6624
6625In the case when more than one substitution rule have been defined,
6626the rules are evaluated one by one in the order where they have been
6627defined. The first one matching, if any, is selected to perform
6628the substitution.
6629
6630For instance, if we had entered the following commands:
6631
6632@smallexample
6633(@value{GDBP}) set substitute-path /usr/src/include /mnt/include
6634(@value{GDBP}) set substitute-path /usr/src /mnt/src
6635@end smallexample
6636
6637@noindent
6638@value{GDBN} would then rewrite @file{/usr/src/include/defs.h} into
6639@file{/mnt/include/defs.h} by using the first rule. However, it would
6640use the second rule to rewrite @file{/usr/src/lib/foo.c} into
6641@file{/mnt/src/lib/foo.c}.
6642
6643
6644@item unset substitute-path [path]
6645@kindex unset substitute-path
6646If a path is specified, search the current list of substitution rules
6647for a rule that would rewrite that path. Delete that rule if found.
6648A warning is emitted by the debugger if no rule could be found.
6649
6650If no path is specified, then all substitution rules are deleted.
6651
6652@item show substitute-path [path]
6653@kindex show substitute-path
6654If a path is specified, then print the source path substitution rule
6655which would rewrite that path, if any.
6656
6657If no path is specified, then print all existing source path substitution
6658rules.
6659
c906108c
SS
6660@end table
6661
6662If your source path is cluttered with directories that are no longer of
6663interest, @value{GDBN} may sometimes cause confusion by finding the wrong
6664versions of source. You can correct the situation as follows:
6665
6666@enumerate
6667@item
cd852561 6668Use @code{directory} with no argument to reset the source path to its default value.
c906108c
SS
6669
6670@item
6671Use @code{directory} with suitable arguments to reinstall the
6672directories you want in the source path. You can add all the
6673directories in one command.
6674@end enumerate
6675
6d2ebf8b 6676@node Machine Code
79a6e687 6677@section Source and Machine Code
15387254 6678@cindex source line and its code address
c906108c
SS
6679
6680You can use the command @code{info line} to map source lines to program
6681addresses (and vice versa), and the command @code{disassemble} to display
91440f57
HZ
6682a range of addresses as machine instructions. You can use the command
6683@code{set disassemble-next-line} to set whether to disassemble next
6684source line when execution stops. When run under @sc{gnu} Emacs
d4f3574e 6685mode, the @code{info line} command causes the arrow to point to the
5d161b24 6686line specified. Also, @code{info line} prints addresses in symbolic form as
c906108c
SS
6687well as hex.
6688
6689@table @code
6690@kindex info line
6691@item info line @var{linespec}
6692Print the starting and ending addresses of the compiled code for
6693source line @var{linespec}. You can specify source lines in any of
2a25a5ba 6694the ways documented in @ref{Specify Location}.
c906108c
SS
6695@end table
6696
6697For example, we can use @code{info line} to discover the location of
6698the object code for the first line of function
6699@code{m4_changequote}:
6700
d4f3574e
SS
6701@c FIXME: I think this example should also show the addresses in
6702@c symbolic form, as they usually would be displayed.
c906108c 6703@smallexample
96a2c332 6704(@value{GDBP}) info line m4_changequote
c906108c
SS
6705Line 895 of "builtin.c" starts at pc 0x634c and ends at 0x6350.
6706@end smallexample
6707
6708@noindent
15387254 6709@cindex code address and its source line
c906108c
SS
6710We can also inquire (using @code{*@var{addr}} as the form for
6711@var{linespec}) what source line covers a particular address:
6712@smallexample
6713(@value{GDBP}) info line *0x63ff
6714Line 926 of "builtin.c" starts at pc 0x63e4 and ends at 0x6404.
6715@end smallexample
6716
6717@cindex @code{$_} and @code{info line}
15387254 6718@cindex @code{x} command, default address
41afff9a 6719@kindex x@r{(examine), and} info line
c906108c
SS
6720After @code{info line}, the default address for the @code{x} command
6721is changed to the starting address of the line, so that @samp{x/i} is
6722sufficient to begin examining the machine code (@pxref{Memory,
79a6e687 6723,Examining Memory}). Also, this address is saved as the value of the
c906108c 6724convenience variable @code{$_} (@pxref{Convenience Vars, ,Convenience
79a6e687 6725Variables}).
c906108c
SS
6726
6727@table @code
6728@kindex disassemble
6729@cindex assembly instructions
6730@cindex instructions, assembly
6731@cindex machine instructions
6732@cindex listing machine instructions
6733@item disassemble
d14508fe 6734@itemx disassemble /m
9b117ef3 6735@itemx disassemble /r
c906108c 6736This specialized command dumps a range of memory as machine
d14508fe 6737instructions. It can also print mixed source+disassembly by specifying
9b117ef3
HZ
6738the @code{/m} modifier and print the raw instructions in hex as well as
6739in symbolic form by specifying the @code{/r}.
d14508fe 6740The default memory range is the function surrounding the
c906108c
SS
6741program counter of the selected frame. A single argument to this
6742command is a program counter value; @value{GDBN} dumps the function
21a0512e
PP
6743surrounding this value. When two arguments are given, they should
6744be separated by a comma, possibly surrounded by whitespace. The
53a71c06
CR
6745arguments specify a range of addresses to dump, in one of two forms:
6746
6747@table @code
6748@item @var{start},@var{end}
6749the addresses from @var{start} (inclusive) to @var{end} (exclusive)
6750@item @var{start},+@var{length}
6751the addresses from @var{start} (inclusive) to
6752@code{@var{start}+@var{length}} (exclusive).
6753@end table
6754
6755@noindent
6756When 2 arguments are specified, the name of the function is also
6757printed (since there could be several functions in the given range).
21a0512e
PP
6758
6759The argument(s) can be any expression yielding a numeric value, such as
6760@samp{0x32c4}, @samp{&main+10} or @samp{$pc - 8}.
2b28d209
PP
6761
6762If the range of memory being disassembled contains current program counter,
6763the instruction at that location is shown with a @code{=>} marker.
c906108c
SS
6764@end table
6765
c906108c
SS
6766The following example shows the disassembly of a range of addresses of
6767HP PA-RISC 2.0 code:
6768
6769@smallexample
21a0512e 6770(@value{GDBP}) disas 0x32c4, 0x32e4
c906108c 6771Dump of assembler code from 0x32c4 to 0x32e4:
2b28d209
PP
6772 0x32c4 <main+204>: addil 0,dp
6773 0x32c8 <main+208>: ldw 0x22c(sr0,r1),r26
6774 0x32cc <main+212>: ldil 0x3000,r31
6775 0x32d0 <main+216>: ble 0x3f8(sr4,r31)
6776 0x32d4 <main+220>: ldo 0(r31),rp
6777 0x32d8 <main+224>: addil -0x800,dp
6778 0x32dc <main+228>: ldo 0x588(r1),r26
6779 0x32e0 <main+232>: ldil 0x3000,r31
c906108c
SS
6780End of assembler dump.
6781@end smallexample
c906108c 6782
2b28d209
PP
6783Here is an example showing mixed source+assembly for Intel x86, when the
6784program is stopped just after function prologue:
d14508fe
DE
6785
6786@smallexample
6787(@value{GDBP}) disas /m main
6788Dump of assembler code for function main:
67895 @{
9c419145
PP
6790 0x08048330 <+0>: push %ebp
6791 0x08048331 <+1>: mov %esp,%ebp
6792 0x08048333 <+3>: sub $0x8,%esp
6793 0x08048336 <+6>: and $0xfffffff0,%esp
6794 0x08048339 <+9>: sub $0x10,%esp
d14508fe
DE
6795
67966 printf ("Hello.\n");
9c419145
PP
6797=> 0x0804833c <+12>: movl $0x8048440,(%esp)
6798 0x08048343 <+19>: call 0x8048284 <puts@@plt>
d14508fe
DE
6799
68007 return 0;
68018 @}
9c419145
PP
6802 0x08048348 <+24>: mov $0x0,%eax
6803 0x0804834d <+29>: leave
6804 0x0804834e <+30>: ret
d14508fe
DE
6805
6806End of assembler dump.
6807@end smallexample
6808
53a71c06
CR
6809Here is another example showing raw instructions in hex for AMD x86-64,
6810
6811@smallexample
6812(gdb) disas /r 0x400281,+10
6813Dump of assembler code from 0x400281 to 0x40028b:
6814 0x0000000000400281: 38 36 cmp %dh,(%rsi)
6815 0x0000000000400283: 2d 36 34 2e 73 sub $0x732e3436,%eax
6816 0x0000000000400288: 6f outsl %ds:(%rsi),(%dx)
6817 0x0000000000400289: 2e 32 00 xor %cs:(%rax),%al
6818End of assembler dump.
6819@end smallexample
6820
c906108c
SS
6821Some architectures have more than one commonly-used set of instruction
6822mnemonics or other syntax.
6823
76d17f34
EZ
6824For programs that were dynamically linked and use shared libraries,
6825instructions that call functions or branch to locations in the shared
6826libraries might show a seemingly bogus location---it's actually a
6827location of the relocation table. On some architectures, @value{GDBN}
6828might be able to resolve these to actual function names.
6829
c906108c 6830@table @code
d4f3574e 6831@kindex set disassembly-flavor
d4f3574e
SS
6832@cindex Intel disassembly flavor
6833@cindex AT&T disassembly flavor
6834@item set disassembly-flavor @var{instruction-set}
c906108c
SS
6835Select the instruction set to use when disassembling the
6836program via the @code{disassemble} or @code{x/i} commands.
6837
6838Currently this command is only defined for the Intel x86 family. You
d4f3574e
SS
6839can set @var{instruction-set} to either @code{intel} or @code{att}.
6840The default is @code{att}, the AT&T flavor used by default by Unix
6841assemblers for x86-based targets.
9c16f35a
EZ
6842
6843@kindex show disassembly-flavor
6844@item show disassembly-flavor
6845Show the current setting of the disassembly flavor.
c906108c
SS
6846@end table
6847
91440f57
HZ
6848@table @code
6849@kindex set disassemble-next-line
6850@kindex show disassemble-next-line
6851@item set disassemble-next-line
6852@itemx show disassemble-next-line
32ae1842
EZ
6853Control whether or not @value{GDBN} will disassemble the next source
6854line or instruction when execution stops. If ON, @value{GDBN} will
6855display disassembly of the next source line when execution of the
6856program being debugged stops. This is @emph{in addition} to
6857displaying the source line itself, which @value{GDBN} always does if
6858possible. If the next source line cannot be displayed for some reason
6859(e.g., if @value{GDBN} cannot find the source file, or there's no line
6860info in the debug info), @value{GDBN} will display disassembly of the
6861next @emph{instruction} instead of showing the next source line. If
6862AUTO, @value{GDBN} will display disassembly of next instruction only
6863if the source line cannot be displayed. This setting causes
6864@value{GDBN} to display some feedback when you step through a function
6865with no line info or whose source file is unavailable. The default is
6866OFF, which means never display the disassembly of the next line or
6867instruction.
91440f57
HZ
6868@end table
6869
c906108c 6870
6d2ebf8b 6871@node Data
c906108c
SS
6872@chapter Examining Data
6873
6874@cindex printing data
6875@cindex examining data
6876@kindex print
6877@kindex inspect
6878@c "inspect" is not quite a synonym if you are using Epoch, which we do not
6879@c document because it is nonstandard... Under Epoch it displays in a
6880@c different window or something like that.
6881The usual way to examine data in your program is with the @code{print}
7a292a7a
SS
6882command (abbreviated @code{p}), or its synonym @code{inspect}. It
6883evaluates and prints the value of an expression of the language your
6884program is written in (@pxref{Languages, ,Using @value{GDBN} with
78e2826b
TT
6885Different Languages}). It may also print the expression using a
6886Python-based pretty-printer (@pxref{Pretty Printing}).
c906108c
SS
6887
6888@table @code
d4f3574e
SS
6889@item print @var{expr}
6890@itemx print /@var{f} @var{expr}
6891@var{expr} is an expression (in the source language). By default the
6892value of @var{expr} is printed in a format appropriate to its data type;
c906108c 6893you can choose a different format by specifying @samp{/@var{f}}, where
d4f3574e 6894@var{f} is a letter specifying the format; see @ref{Output Formats,,Output
79a6e687 6895Formats}.
c906108c
SS
6896
6897@item print
6898@itemx print /@var{f}
15387254 6899@cindex reprint the last value
d4f3574e 6900If you omit @var{expr}, @value{GDBN} displays the last value again (from the
79a6e687 6901@dfn{value history}; @pxref{Value History, ,Value History}). This allows you to
c906108c
SS
6902conveniently inspect the same value in an alternative format.
6903@end table
6904
6905A more low-level way of examining data is with the @code{x} command.
6906It examines data in memory at a specified address and prints it in a
79a6e687 6907specified format. @xref{Memory, ,Examining Memory}.
c906108c 6908
7a292a7a 6909If you are interested in information about types, or about how the
d4f3574e
SS
6910fields of a struct or a class are declared, use the @code{ptype @var{exp}}
6911command rather than @code{print}. @xref{Symbols, ,Examining the Symbol
7a292a7a 6912Table}.
c906108c
SS
6913
6914@menu
6915* Expressions:: Expressions
6ba66d6a 6916* Ambiguous Expressions:: Ambiguous Expressions
c906108c
SS
6917* Variables:: Program variables
6918* Arrays:: Artificial arrays
6919* Output Formats:: Output formats
6920* Memory:: Examining memory
6921* Auto Display:: Automatic display
6922* Print Settings:: Print settings
4c374409 6923* Pretty Printing:: Python pretty printing
c906108c
SS
6924* Value History:: Value history
6925* Convenience Vars:: Convenience variables
6926* Registers:: Registers
c906108c 6927* Floating Point Hardware:: Floating point hardware
53c69bd7 6928* Vector Unit:: Vector Unit
721c2651 6929* OS Information:: Auxiliary data provided by operating system
29e57380 6930* Memory Region Attributes:: Memory region attributes
16d9dec6 6931* Dump/Restore Files:: Copy between memory and a file
384ee23f 6932* Core File Generation:: Cause a program dump its core
a0eb71c5
KB
6933* Character Sets:: Debugging programs that use a different
6934 character set than GDB does
09d4efe1 6935* Caching Remote Data:: Data caching for remote targets
08388c79 6936* Searching Memory:: Searching memory for a sequence of bytes
c906108c
SS
6937@end menu
6938
6d2ebf8b 6939@node Expressions
c906108c
SS
6940@section Expressions
6941
6942@cindex expressions
6943@code{print} and many other @value{GDBN} commands accept an expression and
6944compute its value. Any kind of constant, variable or operator defined
6945by the programming language you are using is valid in an expression in
e2e0bcd1
JB
6946@value{GDBN}. This includes conditional expressions, function calls,
6947casts, and string constants. It also includes preprocessor macros, if
6948you compiled your program to include this information; see
6949@ref{Compilation}.
c906108c 6950
15387254 6951@cindex arrays in expressions
d4f3574e
SS
6952@value{GDBN} supports array constants in expressions input by
6953the user. The syntax is @{@var{element}, @var{element}@dots{}@}. For example,
63092375
DJ
6954you can use the command @code{print @{1, 2, 3@}} to create an array
6955of three integers. If you pass an array to a function or assign it
6956to a program variable, @value{GDBN} copies the array to memory that
6957is @code{malloc}ed in the target program.
c906108c 6958
c906108c
SS
6959Because C is so widespread, most of the expressions shown in examples in
6960this manual are in C. @xref{Languages, , Using @value{GDBN} with Different
6961Languages}, for information on how to use expressions in other
6962languages.
6963
6964In this section, we discuss operators that you can use in @value{GDBN}
6965expressions regardless of your programming language.
6966
15387254 6967@cindex casts, in expressions
c906108c
SS
6968Casts are supported in all languages, not just in C, because it is so
6969useful to cast a number into a pointer in order to examine a structure
6970at that address in memory.
6971@c FIXME: casts supported---Mod2 true?
c906108c
SS
6972
6973@value{GDBN} supports these operators, in addition to those common
6974to programming languages:
6975
6976@table @code
6977@item @@
6978@samp{@@} is a binary operator for treating parts of memory as arrays.
79a6e687 6979@xref{Arrays, ,Artificial Arrays}, for more information.
c906108c
SS
6980
6981@item ::
6982@samp{::} allows you to specify a variable in terms of the file or
79a6e687 6983function where it is defined. @xref{Variables, ,Program Variables}.
c906108c
SS
6984
6985@cindex @{@var{type}@}
6986@cindex type casting memory
6987@cindex memory, viewing as typed object
6988@cindex casts, to view memory
6989@item @{@var{type}@} @var{addr}
6990Refers to an object of type @var{type} stored at address @var{addr} in
6991memory. @var{addr} may be any expression whose value is an integer or
6992pointer (but parentheses are required around binary operators, just as in
6993a cast). This construct is allowed regardless of what kind of data is
6994normally supposed to reside at @var{addr}.
6995@end table
6996
6ba66d6a
JB
6997@node Ambiguous Expressions
6998@section Ambiguous Expressions
6999@cindex ambiguous expressions
7000
7001Expressions can sometimes contain some ambiguous elements. For instance,
7002some programming languages (notably Ada, C@t{++} and Objective-C) permit
7003a single function name to be defined several times, for application in
7004different contexts. This is called @dfn{overloading}. Another example
7005involving Ada is generics. A @dfn{generic package} is similar to C@t{++}
7006templates and is typically instantiated several times, resulting in
7007the same function name being defined in different contexts.
7008
7009In some cases and depending on the language, it is possible to adjust
7010the expression to remove the ambiguity. For instance in C@t{++}, you
7011can specify the signature of the function you want to break on, as in
7012@kbd{break @var{function}(@var{types})}. In Ada, using the fully
7013qualified name of your function often makes the expression unambiguous
7014as well.
7015
7016When an ambiguity that needs to be resolved is detected, the debugger
7017has the capability to display a menu of numbered choices for each
7018possibility, and then waits for the selection with the prompt @samp{>}.
7019The first option is always @samp{[0] cancel}, and typing @kbd{0 @key{RET}}
7020aborts the current command. If the command in which the expression was
7021used allows more than one choice to be selected, the next option in the
7022menu is @samp{[1] all}, and typing @kbd{1 @key{RET}} selects all possible
7023choices.
7024
7025For example, the following session excerpt shows an attempt to set a
7026breakpoint at the overloaded symbol @code{String::after}.
7027We choose three particular definitions of that function name:
7028
7029@c FIXME! This is likely to change to show arg type lists, at least
7030@smallexample
7031@group
7032(@value{GDBP}) b String::after
7033[0] cancel
7034[1] all
7035[2] file:String.cc; line number:867
7036[3] file:String.cc; line number:860
7037[4] file:String.cc; line number:875
7038[5] file:String.cc; line number:853
7039[6] file:String.cc; line number:846
7040[7] file:String.cc; line number:735
7041> 2 4 6
7042Breakpoint 1 at 0xb26c: file String.cc, line 867.
7043Breakpoint 2 at 0xb344: file String.cc, line 875.
7044Breakpoint 3 at 0xafcc: file String.cc, line 846.
7045Multiple breakpoints were set.
7046Use the "delete" command to delete unwanted
7047 breakpoints.
7048(@value{GDBP})
7049@end group
7050@end smallexample
7051
7052@table @code
7053@kindex set multiple-symbols
7054@item set multiple-symbols @var{mode}
7055@cindex multiple-symbols menu
7056
7057This option allows you to adjust the debugger behavior when an expression
7058is ambiguous.
7059
7060By default, @var{mode} is set to @code{all}. If the command with which
7061the expression is used allows more than one choice, then @value{GDBN}
7062automatically selects all possible choices. For instance, inserting
7063a breakpoint on a function using an ambiguous name results in a breakpoint
7064inserted on each possible match. However, if a unique choice must be made,
7065then @value{GDBN} uses the menu to help you disambiguate the expression.
7066For instance, printing the address of an overloaded function will result
7067in the use of the menu.
7068
7069When @var{mode} is set to @code{ask}, the debugger always uses the menu
7070when an ambiguity is detected.
7071
7072Finally, when @var{mode} is set to @code{cancel}, the debugger reports
7073an error due to the ambiguity and the command is aborted.
7074
7075@kindex show multiple-symbols
7076@item show multiple-symbols
7077Show the current value of the @code{multiple-symbols} setting.
7078@end table
7079
6d2ebf8b 7080@node Variables
79a6e687 7081@section Program Variables
c906108c
SS
7082
7083The most common kind of expression to use is the name of a variable
7084in your program.
7085
7086Variables in expressions are understood in the selected stack frame
79a6e687 7087(@pxref{Selection, ,Selecting a Frame}); they must be either:
c906108c
SS
7088
7089@itemize @bullet
7090@item
7091global (or file-static)
7092@end itemize
7093
5d161b24 7094@noindent or
c906108c
SS
7095
7096@itemize @bullet
7097@item
7098visible according to the scope rules of the
7099programming language from the point of execution in that frame
5d161b24 7100@end itemize
c906108c
SS
7101
7102@noindent This means that in the function
7103
474c8240 7104@smallexample
c906108c
SS
7105foo (a)
7106 int a;
7107@{
7108 bar (a);
7109 @{
7110 int b = test ();
7111 bar (b);
7112 @}
7113@}
474c8240 7114@end smallexample
c906108c
SS
7115
7116@noindent
7117you can examine and use the variable @code{a} whenever your program is
7118executing within the function @code{foo}, but you can only use or
7119examine the variable @code{b} while your program is executing inside
7120the block where @code{b} is declared.
7121
7122@cindex variable name conflict
7123There is an exception: you can refer to a variable or function whose
7124scope is a single source file even if the current execution point is not
7125in this file. But it is possible to have more than one such variable or
7126function with the same name (in different source files). If that
7127happens, referring to that name has unpredictable effects. If you wish,
7128you can specify a static variable in a particular function or file,
15387254 7129using the colon-colon (@code{::}) notation:
c906108c 7130
d4f3574e 7131@cindex colon-colon, context for variables/functions
12c27660 7132@ifnotinfo
c906108c 7133@c info cannot cope with a :: index entry, but why deprive hard copy readers?
41afff9a 7134@cindex @code{::}, context for variables/functions
12c27660 7135@end ifnotinfo
474c8240 7136@smallexample
c906108c
SS
7137@var{file}::@var{variable}
7138@var{function}::@var{variable}
474c8240 7139@end smallexample
c906108c
SS
7140
7141@noindent
7142Here @var{file} or @var{function} is the name of the context for the
7143static @var{variable}. In the case of file names, you can use quotes to
7144make sure @value{GDBN} parses the file name as a single word---for example,
7145to print a global value of @code{x} defined in @file{f2.c}:
7146
474c8240 7147@smallexample
c906108c 7148(@value{GDBP}) p 'f2.c'::x
474c8240 7149@end smallexample
c906108c 7150
b37052ae 7151@cindex C@t{++} scope resolution
c906108c 7152This use of @samp{::} is very rarely in conflict with the very similar
b37052ae 7153use of the same notation in C@t{++}. @value{GDBN} also supports use of the C@t{++}
c906108c
SS
7154scope resolution operator in @value{GDBN} expressions.
7155@c FIXME: Um, so what happens in one of those rare cases where it's in
7156@c conflict?? --mew
c906108c
SS
7157
7158@cindex wrong values
7159@cindex variable values, wrong
15387254
EZ
7160@cindex function entry/exit, wrong values of variables
7161@cindex optimized code, wrong values of variables
c906108c
SS
7162@quotation
7163@emph{Warning:} Occasionally, a local variable may appear to have the
7164wrong value at certain points in a function---just after entry to a new
7165scope, and just before exit.
7166@end quotation
7167You may see this problem when you are stepping by machine instructions.
7168This is because, on most machines, it takes more than one instruction to
7169set up a stack frame (including local variable definitions); if you are
7170stepping by machine instructions, variables may appear to have the wrong
7171values until the stack frame is completely built. On exit, it usually
7172also takes more than one machine instruction to destroy a stack frame;
7173after you begin stepping through that group of instructions, local
7174variable definitions may be gone.
7175
7176This may also happen when the compiler does significant optimizations.
7177To be sure of always seeing accurate values, turn off all optimization
7178when compiling.
7179
d4f3574e
SS
7180@cindex ``No symbol "foo" in current context''
7181Another possible effect of compiler optimizations is to optimize
7182unused variables out of existence, or assign variables to registers (as
7183opposed to memory addresses). Depending on the support for such cases
7184offered by the debug info format used by the compiler, @value{GDBN}
7185might not be able to display values for such local variables. If that
7186happens, @value{GDBN} will print a message like this:
7187
474c8240 7188@smallexample
d4f3574e 7189No symbol "foo" in current context.
474c8240 7190@end smallexample
d4f3574e
SS
7191
7192To solve such problems, either recompile without optimizations, or use a
7193different debug info format, if the compiler supports several such
15387254 7194formats. For example, @value{NGCC}, the @sc{gnu} C/C@t{++} compiler,
0179ffac
DC
7195usually supports the @option{-gstabs+} option. @option{-gstabs+}
7196produces debug info in a format that is superior to formats such as
7197COFF. You may be able to use DWARF 2 (@option{-gdwarf-2}), which is also
7198an effective form for debug info. @xref{Debugging Options,,Options
ce9341a1
BW
7199for Debugging Your Program or GCC, gcc.info, Using the @sc{gnu}
7200Compiler Collection (GCC)}.
79a6e687 7201@xref{C, ,C and C@t{++}}, for more information about debug info formats
15387254 7202that are best suited to C@t{++} programs.
d4f3574e 7203
ab1adacd
EZ
7204If you ask to print an object whose contents are unknown to
7205@value{GDBN}, e.g., because its data type is not completely specified
7206by the debug information, @value{GDBN} will say @samp{<incomplete
7207type>}. @xref{Symbols, incomplete type}, for more about this.
7208
3a60f64e
JK
7209Strings are identified as arrays of @code{char} values without specified
7210signedness. Arrays of either @code{signed char} or @code{unsigned char} get
7211printed as arrays of 1 byte sized integers. @code{-fsigned-char} or
7212@code{-funsigned-char} @value{NGCC} options have no effect as @value{GDBN}
7213defines literal string type @code{"char"} as @code{char} without a sign.
7214For program code
7215
7216@smallexample
7217char var0[] = "A";
7218signed char var1[] = "A";
7219@end smallexample
7220
7221You get during debugging
7222@smallexample
7223(gdb) print var0
7224$1 = "A"
7225(gdb) print var1
7226$2 = @{65 'A', 0 '\0'@}
7227@end smallexample
7228
6d2ebf8b 7229@node Arrays
79a6e687 7230@section Artificial Arrays
c906108c
SS
7231
7232@cindex artificial array
15387254 7233@cindex arrays
41afff9a 7234@kindex @@@r{, referencing memory as an array}
c906108c
SS
7235It is often useful to print out several successive objects of the
7236same type in memory; a section of an array, or an array of
7237dynamically determined size for which only a pointer exists in the
7238program.
7239
7240You can do this by referring to a contiguous span of memory as an
7241@dfn{artificial array}, using the binary operator @samp{@@}. The left
7242operand of @samp{@@} should be the first element of the desired array
7243and be an individual object. The right operand should be the desired length
7244of the array. The result is an array value whose elements are all of
7245the type of the left argument. The first element is actually the left
7246argument; the second element comes from bytes of memory immediately
7247following those that hold the first element, and so on. Here is an
7248example. If a program says
7249
474c8240 7250@smallexample
c906108c 7251int *array = (int *) malloc (len * sizeof (int));
474c8240 7252@end smallexample
c906108c
SS
7253
7254@noindent
7255you can print the contents of @code{array} with
7256
474c8240 7257@smallexample
c906108c 7258p *array@@len
474c8240 7259@end smallexample
c906108c
SS
7260
7261The left operand of @samp{@@} must reside in memory. Array values made
7262with @samp{@@} in this way behave just like other arrays in terms of
7263subscripting, and are coerced to pointers when used in expressions.
7264Artificial arrays most often appear in expressions via the value history
79a6e687 7265(@pxref{Value History, ,Value History}), after printing one out.
c906108c
SS
7266
7267Another way to create an artificial array is to use a cast.
7268This re-interprets a value as if it were an array.
7269The value need not be in memory:
474c8240 7270@smallexample
c906108c
SS
7271(@value{GDBP}) p/x (short[2])0x12345678
7272$1 = @{0x1234, 0x5678@}
474c8240 7273@end smallexample
c906108c
SS
7274
7275As a convenience, if you leave the array length out (as in
c3f6f71d 7276@samp{(@var{type}[])@var{value}}) @value{GDBN} calculates the size to fill
c906108c 7277the value (as @samp{sizeof(@var{value})/sizeof(@var{type})}:
474c8240 7278@smallexample
c906108c
SS
7279(@value{GDBP}) p/x (short[])0x12345678
7280$2 = @{0x1234, 0x5678@}
474c8240 7281@end smallexample
c906108c
SS
7282
7283Sometimes the artificial array mechanism is not quite enough; in
7284moderately complex data structures, the elements of interest may not
7285actually be adjacent---for example, if you are interested in the values
7286of pointers in an array. One useful work-around in this situation is
7287to use a convenience variable (@pxref{Convenience Vars, ,Convenience
79a6e687 7288Variables}) as a counter in an expression that prints the first
c906108c
SS
7289interesting value, and then repeat that expression via @key{RET}. For
7290instance, suppose you have an array @code{dtab} of pointers to
7291structures, and you are interested in the values of a field @code{fv}
7292in each structure. Here is an example of what you might type:
7293
474c8240 7294@smallexample
c906108c
SS
7295set $i = 0
7296p dtab[$i++]->fv
7297@key{RET}
7298@key{RET}
7299@dots{}
474c8240 7300@end smallexample
c906108c 7301
6d2ebf8b 7302@node Output Formats
79a6e687 7303@section Output Formats
c906108c
SS
7304
7305@cindex formatted output
7306@cindex output formats
7307By default, @value{GDBN} prints a value according to its data type. Sometimes
7308this is not what you want. For example, you might want to print a number
7309in hex, or a pointer in decimal. Or you might want to view data in memory
7310at a certain address as a character string or as an instruction. To do
7311these things, specify an @dfn{output format} when you print a value.
7312
7313The simplest use of output formats is to say how to print a value
7314already computed. This is done by starting the arguments of the
7315@code{print} command with a slash and a format letter. The format
7316letters supported are:
7317
7318@table @code
7319@item x
7320Regard the bits of the value as an integer, and print the integer in
7321hexadecimal.
7322
7323@item d
7324Print as integer in signed decimal.
7325
7326@item u
7327Print as integer in unsigned decimal.
7328
7329@item o
7330Print as integer in octal.
7331
7332@item t
7333Print as integer in binary. The letter @samp{t} stands for ``two''.
7334@footnote{@samp{b} cannot be used because these format letters are also
7335used with the @code{x} command, where @samp{b} stands for ``byte'';
79a6e687 7336see @ref{Memory,,Examining Memory}.}
c906108c
SS
7337
7338@item a
7339@cindex unknown address, locating
3d67e040 7340@cindex locate address
c906108c
SS
7341Print as an address, both absolute in hexadecimal and as an offset from
7342the nearest preceding symbol. You can use this format used to discover
7343where (in what function) an unknown address is located:
7344
474c8240 7345@smallexample
c906108c
SS
7346(@value{GDBP}) p/a 0x54320
7347$3 = 0x54320 <_initialize_vx+396>
474c8240 7348@end smallexample
c906108c 7349
3d67e040
EZ
7350@noindent
7351The command @code{info symbol 0x54320} yields similar results.
7352@xref{Symbols, info symbol}.
7353
c906108c 7354@item c
51274035
EZ
7355Regard as an integer and print it as a character constant. This
7356prints both the numerical value and its character representation. The
7357character representation is replaced with the octal escape @samp{\nnn}
7358for characters outside the 7-bit @sc{ascii} range.
c906108c 7359
ea37ba09
DJ
7360Without this format, @value{GDBN} displays @code{char},
7361@w{@code{unsigned char}}, and @w{@code{signed char}} data as character
7362constants. Single-byte members of vectors are displayed as integer
7363data.
7364
c906108c
SS
7365@item f
7366Regard the bits of the value as a floating point number and print
7367using typical floating point syntax.
ea37ba09
DJ
7368
7369@item s
7370@cindex printing strings
7371@cindex printing byte arrays
7372Regard as a string, if possible. With this format, pointers to single-byte
7373data are displayed as null-terminated strings and arrays of single-byte data
7374are displayed as fixed-length strings. Other values are displayed in their
7375natural types.
7376
7377Without this format, @value{GDBN} displays pointers to and arrays of
7378@code{char}, @w{@code{unsigned char}}, and @w{@code{signed char}} as
7379strings. Single-byte members of a vector are displayed as an integer
7380array.
a6bac58e
TT
7381
7382@item r
7383@cindex raw printing
7384Print using the @samp{raw} formatting. By default, @value{GDBN} will
78e2826b
TT
7385use a Python-based pretty-printer, if one is available (@pxref{Pretty
7386Printing}). This typically results in a higher-level display of the
7387value's contents. The @samp{r} format bypasses any Python
7388pretty-printer which might exist.
c906108c
SS
7389@end table
7390
7391For example, to print the program counter in hex (@pxref{Registers}), type
7392
474c8240 7393@smallexample
c906108c 7394p/x $pc
474c8240 7395@end smallexample
c906108c
SS
7396
7397@noindent
7398Note that no space is required before the slash; this is because command
7399names in @value{GDBN} cannot contain a slash.
7400
7401To reprint the last value in the value history with a different format,
7402you can use the @code{print} command with just a format and no
7403expression. For example, @samp{p/x} reprints the last value in hex.
7404
6d2ebf8b 7405@node Memory
79a6e687 7406@section Examining Memory
c906108c
SS
7407
7408You can use the command @code{x} (for ``examine'') to examine memory in
7409any of several formats, independently of your program's data types.
7410
7411@cindex examining memory
7412@table @code
41afff9a 7413@kindex x @r{(examine memory)}
c906108c
SS
7414@item x/@var{nfu} @var{addr}
7415@itemx x @var{addr}
7416@itemx x
7417Use the @code{x} command to examine memory.
7418@end table
7419
7420@var{n}, @var{f}, and @var{u} are all optional parameters that specify how
7421much memory to display and how to format it; @var{addr} is an
7422expression giving the address where you want to start displaying memory.
7423If you use defaults for @var{nfu}, you need not type the slash @samp{/}.
7424Several commands set convenient defaults for @var{addr}.
7425
7426@table @r
7427@item @var{n}, the repeat count
7428The repeat count is a decimal integer; the default is 1. It specifies
7429how much memory (counting by units @var{u}) to display.
7430@c This really is **decimal**; unaffected by 'set radix' as of GDB
7431@c 4.1.2.
7432
7433@item @var{f}, the display format
51274035
EZ
7434The display format is one of the formats used by @code{print}
7435(@samp{x}, @samp{d}, @samp{u}, @samp{o}, @samp{t}, @samp{a}, @samp{c},
ea37ba09
DJ
7436@samp{f}, @samp{s}), and in addition @samp{i} (for machine instructions).
7437The default is @samp{x} (hexadecimal) initially. The default changes
7438each time you use either @code{x} or @code{print}.
c906108c
SS
7439
7440@item @var{u}, the unit size
7441The unit size is any of
7442
7443@table @code
7444@item b
7445Bytes.
7446@item h
7447Halfwords (two bytes).
7448@item w
7449Words (four bytes). This is the initial default.
7450@item g
7451Giant words (eight bytes).
7452@end table
7453
7454Each time you specify a unit size with @code{x}, that size becomes the
9a22f0d0
PM
7455default unit the next time you use @code{x}. For the @samp{i} format,
7456the unit size is ignored and is normally not written. For the @samp{s} format,
7457the unit size defaults to @samp{b}, unless it is explicitly given.
7458Use @kbd{x /hs} to display 16-bit char strings and @kbd{x /ws} to display
745932-bit strings. The next use of @kbd{x /s} will again display 8-bit strings.
7460Note that the results depend on the programming language of the
7461current compilation unit. If the language is C, the @samp{s}
7462modifier will use the UTF-16 encoding while @samp{w} will use
7463UTF-32. The encoding is set by the programming language and cannot
7464be altered.
c906108c
SS
7465
7466@item @var{addr}, starting display address
7467@var{addr} is the address where you want @value{GDBN} to begin displaying
7468memory. The expression need not have a pointer value (though it may);
7469it is always interpreted as an integer address of a byte of memory.
7470@xref{Expressions, ,Expressions}, for more information on expressions. The default for
7471@var{addr} is usually just after the last address examined---but several
7472other commands also set the default address: @code{info breakpoints} (to
7473the address of the last breakpoint listed), @code{info line} (to the
7474starting address of a line), and @code{print} (if you use it to display
7475a value from memory).
7476@end table
7477
7478For example, @samp{x/3uh 0x54320} is a request to display three halfwords
7479(@code{h}) of memory, formatted as unsigned decimal integers (@samp{u}),
7480starting at address @code{0x54320}. @samp{x/4xw $sp} prints the four
7481words (@samp{w}) of memory above the stack pointer (here, @samp{$sp};
d4f3574e 7482@pxref{Registers, ,Registers}) in hexadecimal (@samp{x}).
c906108c
SS
7483
7484Since the letters indicating unit sizes are all distinct from the
7485letters specifying output formats, you do not have to remember whether
7486unit size or format comes first; either order works. The output
7487specifications @samp{4xw} and @samp{4wx} mean exactly the same thing.
7488(However, the count @var{n} must come first; @samp{wx4} does not work.)
7489
7490Even though the unit size @var{u} is ignored for the formats @samp{s}
7491and @samp{i}, you might still want to use a count @var{n}; for example,
7492@samp{3i} specifies that you want to see three machine instructions,
a4642986
MR
7493including any operands. For convenience, especially when used with
7494the @code{display} command, the @samp{i} format also prints branch delay
7495slot instructions, if any, beyond the count specified, which immediately
7496follow the last instruction that is within the count. The command
7497@code{disassemble} gives an alternative way of inspecting machine
7498instructions; see @ref{Machine Code,,Source and Machine Code}.
c906108c
SS
7499
7500All the defaults for the arguments to @code{x} are designed to make it
7501easy to continue scanning memory with minimal specifications each time
7502you use @code{x}. For example, after you have inspected three machine
7503instructions with @samp{x/3i @var{addr}}, you can inspect the next seven
7504with just @samp{x/7}. If you use @key{RET} to repeat the @code{x} command,
7505the repeat count @var{n} is used again; the other arguments default as
7506for successive uses of @code{x}.
7507
2b28d209
PP
7508When examining machine instructions, the instruction at current program
7509counter is shown with a @code{=>} marker. For example:
7510
7511@smallexample
7512(@value{GDBP}) x/5i $pc-6
7513 0x804837f <main+11>: mov %esp,%ebp
7514 0x8048381 <main+13>: push %ecx
7515 0x8048382 <main+14>: sub $0x4,%esp
7516=> 0x8048385 <main+17>: movl $0x8048460,(%esp)
7517 0x804838c <main+24>: call 0x80482d4 <puts@@plt>
7518@end smallexample
7519
c906108c
SS
7520@cindex @code{$_}, @code{$__}, and value history
7521The addresses and contents printed by the @code{x} command are not saved
7522in the value history because there is often too much of them and they
7523would get in the way. Instead, @value{GDBN} makes these values available for
7524subsequent use in expressions as values of the convenience variables
7525@code{$_} and @code{$__}. After an @code{x} command, the last address
7526examined is available for use in expressions in the convenience variable
7527@code{$_}. The contents of that address, as examined, are available in
7528the convenience variable @code{$__}.
7529
7530If the @code{x} command has a repeat count, the address and contents saved
7531are from the last memory unit printed; this is not the same as the last
7532address printed if several units were printed on the last line of output.
7533
09d4efe1
EZ
7534@cindex remote memory comparison
7535@cindex verify remote memory image
7536When you are debugging a program running on a remote target machine
ea35711c 7537(@pxref{Remote Debugging}), you may wish to verify the program's image in the
09d4efe1
EZ
7538remote machine's memory against the executable file you downloaded to
7539the target. The @code{compare-sections} command is provided for such
7540situations.
7541
7542@table @code
7543@kindex compare-sections
7544@item compare-sections @r{[}@var{section-name}@r{]}
7545Compare the data of a loadable section @var{section-name} in the
7546executable file of the program being debugged with the same section in
7547the remote machine's memory, and report any mismatches. With no
7548arguments, compares all loadable sections. This command's
7549availability depends on the target's support for the @code{"qCRC"}
7550remote request.
7551@end table
7552
6d2ebf8b 7553@node Auto Display
79a6e687 7554@section Automatic Display
c906108c
SS
7555@cindex automatic display
7556@cindex display of expressions
7557
7558If you find that you want to print the value of an expression frequently
7559(to see how it changes), you might want to add it to the @dfn{automatic
7560display list} so that @value{GDBN} prints its value each time your program stops.
7561Each expression added to the list is given a number to identify it;
7562to remove an expression from the list, you specify that number.
7563The automatic display looks like this:
7564
474c8240 7565@smallexample
c906108c
SS
75662: foo = 38
75673: bar[5] = (struct hack *) 0x3804
474c8240 7568@end smallexample
c906108c
SS
7569
7570@noindent
7571This display shows item numbers, expressions and their current values. As with
7572displays you request manually using @code{x} or @code{print}, you can
7573specify the output format you prefer; in fact, @code{display} decides
ea37ba09
DJ
7574whether to use @code{print} or @code{x} depending your format
7575specification---it uses @code{x} if you specify either the @samp{i}
7576or @samp{s} format, or a unit size; otherwise it uses @code{print}.
c906108c
SS
7577
7578@table @code
7579@kindex display
d4f3574e
SS
7580@item display @var{expr}
7581Add the expression @var{expr} to the list of expressions to display
c906108c
SS
7582each time your program stops. @xref{Expressions, ,Expressions}.
7583
7584@code{display} does not repeat if you press @key{RET} again after using it.
7585
d4f3574e 7586@item display/@var{fmt} @var{expr}
c906108c 7587For @var{fmt} specifying only a display format and not a size or
d4f3574e 7588count, add the expression @var{expr} to the auto-display list but
c906108c 7589arrange to display it each time in the specified format @var{fmt}.
79a6e687 7590@xref{Output Formats,,Output Formats}.
c906108c
SS
7591
7592@item display/@var{fmt} @var{addr}
7593For @var{fmt} @samp{i} or @samp{s}, or including a unit-size or a
7594number of units, add the expression @var{addr} as a memory address to
7595be examined each time your program stops. Examining means in effect
79a6e687 7596doing @samp{x/@var{fmt} @var{addr}}. @xref{Memory, ,Examining Memory}.
c906108c
SS
7597@end table
7598
7599For example, @samp{display/i $pc} can be helpful, to see the machine
7600instruction about to be executed each time execution stops (@samp{$pc}
d4f3574e 7601is a common name for the program counter; @pxref{Registers, ,Registers}).
c906108c
SS
7602
7603@table @code
7604@kindex delete display
7605@kindex undisplay
7606@item undisplay @var{dnums}@dots{}
7607@itemx delete display @var{dnums}@dots{}
7608Remove item numbers @var{dnums} from the list of expressions to display.
7609
7610@code{undisplay} does not repeat if you press @key{RET} after using it.
7611(Otherwise you would just get the error @samp{No display number @dots{}}.)
7612
7613@kindex disable display
7614@item disable display @var{dnums}@dots{}
7615Disable the display of item numbers @var{dnums}. A disabled display
7616item is not printed automatically, but is not forgotten. It may be
7617enabled again later.
7618
7619@kindex enable display
7620@item enable display @var{dnums}@dots{}
7621Enable display of item numbers @var{dnums}. It becomes effective once
7622again in auto display of its expression, until you specify otherwise.
7623
7624@item display
7625Display the current values of the expressions on the list, just as is
7626done when your program stops.
7627
7628@kindex info display
7629@item info display
7630Print the list of expressions previously set up to display
7631automatically, each one with its item number, but without showing the
7632values. This includes disabled expressions, which are marked as such.
7633It also includes expressions which would not be displayed right now
7634because they refer to automatic variables not currently available.
7635@end table
7636
15387254 7637@cindex display disabled out of scope
c906108c
SS
7638If a display expression refers to local variables, then it does not make
7639sense outside the lexical context for which it was set up. Such an
7640expression is disabled when execution enters a context where one of its
7641variables is not defined. For example, if you give the command
7642@code{display last_char} while inside a function with an argument
7643@code{last_char}, @value{GDBN} displays this argument while your program
7644continues to stop inside that function. When it stops elsewhere---where
7645there is no variable @code{last_char}---the display is disabled
7646automatically. The next time your program stops where @code{last_char}
7647is meaningful, you can enable the display expression once again.
7648
6d2ebf8b 7649@node Print Settings
79a6e687 7650@section Print Settings
c906108c
SS
7651
7652@cindex format options
7653@cindex print settings
7654@value{GDBN} provides the following ways to control how arrays, structures,
7655and symbols are printed.
7656
7657@noindent
7658These settings are useful for debugging programs in any language:
7659
7660@table @code
4644b6e3 7661@kindex set print
c906108c
SS
7662@item set print address
7663@itemx set print address on
4644b6e3 7664@cindex print/don't print memory addresses
c906108c
SS
7665@value{GDBN} prints memory addresses showing the location of stack
7666traces, structure values, pointer values, breakpoints, and so forth,
7667even when it also displays the contents of those addresses. The default
7668is @code{on}. For example, this is what a stack frame display looks like with
7669@code{set print address on}:
7670
7671@smallexample
7672@group
7673(@value{GDBP}) f
7674#0 set_quotes (lq=0x34c78 "<<", rq=0x34c88 ">>")
7675 at input.c:530
7676530 if (lquote != def_lquote)
7677@end group
7678@end smallexample
7679
7680@item set print address off
7681Do not print addresses when displaying their contents. For example,
7682this is the same stack frame displayed with @code{set print address off}:
7683
7684@smallexample
7685@group
7686(@value{GDBP}) set print addr off
7687(@value{GDBP}) f
7688#0 set_quotes (lq="<<", rq=">>") at input.c:530
7689530 if (lquote != def_lquote)
7690@end group
7691@end smallexample
7692
7693You can use @samp{set print address off} to eliminate all machine
7694dependent displays from the @value{GDBN} interface. For example, with
7695@code{print address off}, you should get the same text for backtraces on
7696all machines---whether or not they involve pointer arguments.
7697
4644b6e3 7698@kindex show print
c906108c
SS
7699@item show print address
7700Show whether or not addresses are to be printed.
7701@end table
7702
7703When @value{GDBN} prints a symbolic address, it normally prints the
7704closest earlier symbol plus an offset. If that symbol does not uniquely
7705identify the address (for example, it is a name whose scope is a single
7706source file), you may need to clarify. One way to do this is with
7707@code{info line}, for example @samp{info line *0x4537}. Alternately,
7708you can set @value{GDBN} to print the source file and line number when
7709it prints a symbolic address:
7710
7711@table @code
c906108c 7712@item set print symbol-filename on
9c16f35a
EZ
7713@cindex source file and line of a symbol
7714@cindex symbol, source file and line
c906108c
SS
7715Tell @value{GDBN} to print the source file name and line number of a
7716symbol in the symbolic form of an address.
7717
7718@item set print symbol-filename off
7719Do not print source file name and line number of a symbol. This is the
7720default.
7721
c906108c
SS
7722@item show print symbol-filename
7723Show whether or not @value{GDBN} will print the source file name and
7724line number of a symbol in the symbolic form of an address.
7725@end table
7726
7727Another situation where it is helpful to show symbol filenames and line
7728numbers is when disassembling code; @value{GDBN} shows you the line
7729number and source file that corresponds to each instruction.
7730
7731Also, you may wish to see the symbolic form only if the address being
7732printed is reasonably close to the closest earlier symbol:
7733
7734@table @code
c906108c 7735@item set print max-symbolic-offset @var{max-offset}
4644b6e3 7736@cindex maximum value for offset of closest symbol
c906108c
SS
7737Tell @value{GDBN} to only display the symbolic form of an address if the
7738offset between the closest earlier symbol and the address is less than
5d161b24 7739@var{max-offset}. The default is 0, which tells @value{GDBN}
c906108c
SS
7740to always print the symbolic form of an address if any symbol precedes it.
7741
c906108c
SS
7742@item show print max-symbolic-offset
7743Ask how large the maximum offset is that @value{GDBN} prints in a
7744symbolic address.
7745@end table
7746
7747@cindex wild pointer, interpreting
7748@cindex pointer, finding referent
7749If you have a pointer and you are not sure where it points, try
7750@samp{set print symbol-filename on}. Then you can determine the name
7751and source file location of the variable where it points, using
7752@samp{p/a @var{pointer}}. This interprets the address in symbolic form.
7753For example, here @value{GDBN} shows that a variable @code{ptt} points
7754at another variable @code{t}, defined in @file{hi2.c}:
7755
474c8240 7756@smallexample
c906108c
SS
7757(@value{GDBP}) set print symbol-filename on
7758(@value{GDBP}) p/a ptt
7759$4 = 0xe008 <t in hi2.c>
474c8240 7760@end smallexample
c906108c
SS
7761
7762@quotation
7763@emph{Warning:} For pointers that point to a local variable, @samp{p/a}
7764does not show the symbol name and filename of the referent, even with
7765the appropriate @code{set print} options turned on.
7766@end quotation
7767
7768Other settings control how different kinds of objects are printed:
7769
7770@table @code
c906108c
SS
7771@item set print array
7772@itemx set print array on
4644b6e3 7773@cindex pretty print arrays
c906108c
SS
7774Pretty print arrays. This format is more convenient to read,
7775but uses more space. The default is off.
7776
7777@item set print array off
7778Return to compressed format for arrays.
7779
c906108c
SS
7780@item show print array
7781Show whether compressed or pretty format is selected for displaying
7782arrays.
7783
3c9c013a
JB
7784@cindex print array indexes
7785@item set print array-indexes
7786@itemx set print array-indexes on
7787Print the index of each element when displaying arrays. May be more
7788convenient to locate a given element in the array or quickly find the
7789index of a given element in that printed array. The default is off.
7790
7791@item set print array-indexes off
7792Stop printing element indexes when displaying arrays.
7793
7794@item show print array-indexes
7795Show whether the index of each element is printed when displaying
7796arrays.
7797
c906108c 7798@item set print elements @var{number-of-elements}
4644b6e3 7799@cindex number of array elements to print
9c16f35a 7800@cindex limit on number of printed array elements
c906108c
SS
7801Set a limit on how many elements of an array @value{GDBN} will print.
7802If @value{GDBN} is printing a large array, it stops printing after it has
7803printed the number of elements set by the @code{set print elements} command.
7804This limit also applies to the display of strings.
d4f3574e 7805When @value{GDBN} starts, this limit is set to 200.
c906108c
SS
7806Setting @var{number-of-elements} to zero means that the printing is unlimited.
7807
c906108c
SS
7808@item show print elements
7809Display the number of elements of a large array that @value{GDBN} will print.
7810If the number is 0, then the printing is unlimited.
7811
b4740add 7812@item set print frame-arguments @var{value}
a0381d3a 7813@kindex set print frame-arguments
b4740add
JB
7814@cindex printing frame argument values
7815@cindex print all frame argument values
7816@cindex print frame argument values for scalars only
7817@cindex do not print frame argument values
7818This command allows to control how the values of arguments are printed
7819when the debugger prints a frame (@pxref{Frames}). The possible
7820values are:
7821
7822@table @code
7823@item all
4f5376b2 7824The values of all arguments are printed.
b4740add
JB
7825
7826@item scalars
7827Print the value of an argument only if it is a scalar. The value of more
7828complex arguments such as arrays, structures, unions, etc, is replaced
4f5376b2
JB
7829by @code{@dots{}}. This is the default. Here is an example where
7830only scalar arguments are shown:
b4740add
JB
7831
7832@smallexample
7833#1 0x08048361 in call_me (i=3, s=@dots{}, ss=0xbf8d508c, u=@dots{}, e=green)
7834 at frame-args.c:23
7835@end smallexample
7836
7837@item none
7838None of the argument values are printed. Instead, the value of each argument
7839is replaced by @code{@dots{}}. In this case, the example above now becomes:
7840
7841@smallexample
7842#1 0x08048361 in call_me (i=@dots{}, s=@dots{}, ss=@dots{}, u=@dots{}, e=@dots{})
7843 at frame-args.c:23
7844@end smallexample
7845@end table
7846
4f5376b2
JB
7847By default, only scalar arguments are printed. This command can be used
7848to configure the debugger to print the value of all arguments, regardless
7849of their type. However, it is often advantageous to not print the value
7850of more complex parameters. For instance, it reduces the amount of
7851information printed in each frame, making the backtrace more readable.
7852Also, it improves performance when displaying Ada frames, because
7853the computation of large arguments can sometimes be CPU-intensive,
7854especially in large applications. Setting @code{print frame-arguments}
7855to @code{scalars} (the default) or @code{none} avoids this computation,
7856thus speeding up the display of each Ada frame.
b4740add
JB
7857
7858@item show print frame-arguments
7859Show how the value of arguments should be displayed when printing a frame.
7860
9c16f35a
EZ
7861@item set print repeats
7862@cindex repeated array elements
7863Set the threshold for suppressing display of repeated array
d3e8051b 7864elements. When the number of consecutive identical elements of an
9c16f35a
EZ
7865array exceeds the threshold, @value{GDBN} prints the string
7866@code{"<repeats @var{n} times>"}, where @var{n} is the number of
7867identical repetitions, instead of displaying the identical elements
7868themselves. Setting the threshold to zero will cause all elements to
7869be individually printed. The default threshold is 10.
7870
7871@item show print repeats
7872Display the current threshold for printing repeated identical
7873elements.
7874
c906108c 7875@item set print null-stop
4644b6e3 7876@cindex @sc{null} elements in arrays
c906108c 7877Cause @value{GDBN} to stop printing the characters of an array when the first
d4f3574e 7878@sc{null} is encountered. This is useful when large arrays actually
c906108c 7879contain only short strings.
d4f3574e 7880The default is off.
c906108c 7881
9c16f35a
EZ
7882@item show print null-stop
7883Show whether @value{GDBN} stops printing an array on the first
7884@sc{null} character.
7885
c906108c 7886@item set print pretty on
9c16f35a
EZ
7887@cindex print structures in indented form
7888@cindex indentation in structure display
5d161b24 7889Cause @value{GDBN} to print structures in an indented format with one member
c906108c
SS
7890per line, like this:
7891
7892@smallexample
7893@group
7894$1 = @{
7895 next = 0x0,
7896 flags = @{
7897 sweet = 1,
7898 sour = 1
7899 @},
7900 meat = 0x54 "Pork"
7901@}
7902@end group
7903@end smallexample
7904
7905@item set print pretty off
7906Cause @value{GDBN} to print structures in a compact format, like this:
7907
7908@smallexample
7909@group
7910$1 = @{next = 0x0, flags = @{sweet = 1, sour = 1@}, \
7911meat = 0x54 "Pork"@}
7912@end group
7913@end smallexample
7914
7915@noindent
7916This is the default format.
7917
c906108c
SS
7918@item show print pretty
7919Show which format @value{GDBN} is using to print structures.
7920
c906108c 7921@item set print sevenbit-strings on
4644b6e3
EZ
7922@cindex eight-bit characters in strings
7923@cindex octal escapes in strings
c906108c
SS
7924Print using only seven-bit characters; if this option is set,
7925@value{GDBN} displays any eight-bit characters (in strings or
7926character values) using the notation @code{\}@var{nnn}. This setting is
7927best if you are working in English (@sc{ascii}) and you use the
7928high-order bit of characters as a marker or ``meta'' bit.
7929
7930@item set print sevenbit-strings off
7931Print full eight-bit characters. This allows the use of more
7932international character sets, and is the default.
7933
c906108c
SS
7934@item show print sevenbit-strings
7935Show whether or not @value{GDBN} is printing only seven-bit characters.
7936
c906108c 7937@item set print union on
4644b6e3 7938@cindex unions in structures, printing
9c16f35a
EZ
7939Tell @value{GDBN} to print unions which are contained in structures
7940and other unions. This is the default setting.
c906108c
SS
7941
7942@item set print union off
9c16f35a
EZ
7943Tell @value{GDBN} not to print unions which are contained in
7944structures and other unions. @value{GDBN} will print @code{"@{...@}"}
7945instead.
c906108c 7946
c906108c
SS
7947@item show print union
7948Ask @value{GDBN} whether or not it will print unions which are contained in
9c16f35a 7949structures and other unions.
c906108c
SS
7950
7951For example, given the declarations
7952
7953@smallexample
7954typedef enum @{Tree, Bug@} Species;
7955typedef enum @{Big_tree, Acorn, Seedling@} Tree_forms;
5d161b24 7956typedef enum @{Caterpillar, Cocoon, Butterfly@}
c906108c
SS
7957 Bug_forms;
7958
7959struct thing @{
7960 Species it;
7961 union @{
7962 Tree_forms tree;
7963 Bug_forms bug;
7964 @} form;
7965@};
7966
7967struct thing foo = @{Tree, @{Acorn@}@};
7968@end smallexample
7969
7970@noindent
7971with @code{set print union on} in effect @samp{p foo} would print
7972
7973@smallexample
7974$1 = @{it = Tree, form = @{tree = Acorn, bug = Cocoon@}@}
7975@end smallexample
7976
7977@noindent
7978and with @code{set print union off} in effect it would print
7979
7980@smallexample
7981$1 = @{it = Tree, form = @{...@}@}
7982@end smallexample
9c16f35a
EZ
7983
7984@noindent
7985@code{set print union} affects programs written in C-like languages
7986and in Pascal.
c906108c
SS
7987@end table
7988
c906108c
SS
7989@need 1000
7990@noindent
b37052ae 7991These settings are of interest when debugging C@t{++} programs:
c906108c
SS
7992
7993@table @code
4644b6e3 7994@cindex demangling C@t{++} names
c906108c
SS
7995@item set print demangle
7996@itemx set print demangle on
b37052ae 7997Print C@t{++} names in their source form rather than in the encoded
c906108c 7998(``mangled'') form passed to the assembler and linker for type-safe
d4f3574e 7999linkage. The default is on.
c906108c 8000
c906108c 8001@item show print demangle
b37052ae 8002Show whether C@t{++} names are printed in mangled or demangled form.
c906108c 8003
c906108c
SS
8004@item set print asm-demangle
8005@itemx set print asm-demangle on
b37052ae 8006Print C@t{++} names in their source form rather than their mangled form, even
c906108c
SS
8007in assembler code printouts such as instruction disassemblies.
8008The default is off.
8009
c906108c 8010@item show print asm-demangle
b37052ae 8011Show whether C@t{++} names in assembly listings are printed in mangled
c906108c
SS
8012or demangled form.
8013
b37052ae
EZ
8014@cindex C@t{++} symbol decoding style
8015@cindex symbol decoding style, C@t{++}
a8f24a35 8016@kindex set demangle-style
c906108c
SS
8017@item set demangle-style @var{style}
8018Choose among several encoding schemes used by different compilers to
b37052ae 8019represent C@t{++} names. The choices for @var{style} are currently:
c906108c
SS
8020
8021@table @code
8022@item auto
8023Allow @value{GDBN} to choose a decoding style by inspecting your program.
8024
8025@item gnu
b37052ae 8026Decode based on the @sc{gnu} C@t{++} compiler (@code{g++}) encoding algorithm.
c906108c 8027This is the default.
c906108c
SS
8028
8029@item hp
b37052ae 8030Decode based on the HP ANSI C@t{++} (@code{aCC}) encoding algorithm.
c906108c
SS
8031
8032@item lucid
b37052ae 8033Decode based on the Lucid C@t{++} compiler (@code{lcc}) encoding algorithm.
c906108c
SS
8034
8035@item arm
b37052ae 8036Decode using the algorithm in the @cite{C@t{++} Annotated Reference Manual}.
c906108c
SS
8037@strong{Warning:} this setting alone is not sufficient to allow
8038debugging @code{cfront}-generated executables. @value{GDBN} would
8039require further enhancement to permit that.
8040
8041@end table
8042If you omit @var{style}, you will see a list of possible formats.
8043
c906108c 8044@item show demangle-style
b37052ae 8045Display the encoding style currently in use for decoding C@t{++} symbols.
c906108c 8046
c906108c
SS
8047@item set print object
8048@itemx set print object on
4644b6e3 8049@cindex derived type of an object, printing
9c16f35a 8050@cindex display derived types
c906108c
SS
8051When displaying a pointer to an object, identify the @emph{actual}
8052(derived) type of the object rather than the @emph{declared} type, using
8053the virtual function table.
8054
8055@item set print object off
8056Display only the declared type of objects, without reference to the
8057virtual function table. This is the default setting.
8058
c906108c
SS
8059@item show print object
8060Show whether actual, or declared, object types are displayed.
8061
c906108c
SS
8062@item set print static-members
8063@itemx set print static-members on
4644b6e3 8064@cindex static members of C@t{++} objects
b37052ae 8065Print static members when displaying a C@t{++} object. The default is on.
c906108c
SS
8066
8067@item set print static-members off
b37052ae 8068Do not print static members when displaying a C@t{++} object.
c906108c 8069
c906108c 8070@item show print static-members
9c16f35a
EZ
8071Show whether C@t{++} static members are printed or not.
8072
8073@item set print pascal_static-members
8074@itemx set print pascal_static-members on
d3e8051b
EZ
8075@cindex static members of Pascal objects
8076@cindex Pascal objects, static members display
9c16f35a
EZ
8077Print static members when displaying a Pascal object. The default is on.
8078
8079@item set print pascal_static-members off
8080Do not print static members when displaying a Pascal object.
8081
8082@item show print pascal_static-members
8083Show whether Pascal static members are printed or not.
c906108c
SS
8084
8085@c These don't work with HP ANSI C++ yet.
c906108c
SS
8086@item set print vtbl
8087@itemx set print vtbl on
4644b6e3 8088@cindex pretty print C@t{++} virtual function tables
9c16f35a
EZ
8089@cindex virtual functions (C@t{++}) display
8090@cindex VTBL display
b37052ae 8091Pretty print C@t{++} virtual function tables. The default is off.
c906108c 8092(The @code{vtbl} commands do not work on programs compiled with the HP
b37052ae 8093ANSI C@t{++} compiler (@code{aCC}).)
c906108c
SS
8094
8095@item set print vtbl off
b37052ae 8096Do not pretty print C@t{++} virtual function tables.
c906108c 8097
c906108c 8098@item show print vtbl
b37052ae 8099Show whether C@t{++} virtual function tables are pretty printed, or not.
c906108c 8100@end table
c906108c 8101
4c374409
JK
8102@node Pretty Printing
8103@section Pretty Printing
8104
8105@value{GDBN} provides a mechanism to allow pretty-printing of values using
8106Python code. It greatly simplifies the display of complex objects. This
8107mechanism works for both MI and the CLI.
8108
8109For example, here is how a C@t{++} @code{std::string} looks without a
8110pretty-printer:
8111
8112@smallexample
8113(@value{GDBP}) print s
8114$1 = @{
8115 static npos = 4294967295,
8116 _M_dataplus = @{
8117 <std::allocator<char>> = @{
8118 <__gnu_cxx::new_allocator<char>> = @{
8119 <No data fields>@}, <No data fields>
8120 @},
8121 members of std::basic_string<char, std::char_traits<char>,
8122 std::allocator<char> >::_Alloc_hider:
8123 _M_p = 0x804a014 "abcd"
8124 @}
8125@}
8126@end smallexample
8127
8128With a pretty-printer for @code{std::string} only the contents are printed:
8129
8130@smallexample
8131(@value{GDBP}) print s
8132$2 = "abcd"
8133@end smallexample
8134
8135For implementing pretty printers for new types you should read the Python API
8136details (@pxref{Pretty Printing API}).
8137
6d2ebf8b 8138@node Value History
79a6e687 8139@section Value History
c906108c
SS
8140
8141@cindex value history
9c16f35a 8142@cindex history of values printed by @value{GDBN}
5d161b24
DB
8143Values printed by the @code{print} command are saved in the @value{GDBN}
8144@dfn{value history}. This allows you to refer to them in other expressions.
8145Values are kept until the symbol table is re-read or discarded
8146(for example with the @code{file} or @code{symbol-file} commands).
8147When the symbol table changes, the value history is discarded,
8148since the values may contain pointers back to the types defined in the
c906108c
SS
8149symbol table.
8150
8151@cindex @code{$}
8152@cindex @code{$$}
8153@cindex history number
8154The values printed are given @dfn{history numbers} by which you can
8155refer to them. These are successive integers starting with one.
8156@code{print} shows you the history number assigned to a value by
8157printing @samp{$@var{num} = } before the value; here @var{num} is the
8158history number.
8159
8160To refer to any previous value, use @samp{$} followed by the value's
8161history number. The way @code{print} labels its output is designed to
8162remind you of this. Just @code{$} refers to the most recent value in
8163the history, and @code{$$} refers to the value before that.
8164@code{$$@var{n}} refers to the @var{n}th value from the end; @code{$$2}
8165is the value just prior to @code{$$}, @code{$$1} is equivalent to
8166@code{$$}, and @code{$$0} is equivalent to @code{$}.
8167
8168For example, suppose you have just printed a pointer to a structure and
8169want to see the contents of the structure. It suffices to type
8170
474c8240 8171@smallexample
c906108c 8172p *$
474c8240 8173@end smallexample
c906108c
SS
8174
8175If you have a chain of structures where the component @code{next} points
8176to the next one, you can print the contents of the next one with this:
8177
474c8240 8178@smallexample
c906108c 8179p *$.next
474c8240 8180@end smallexample
c906108c
SS
8181
8182@noindent
8183You can print successive links in the chain by repeating this
8184command---which you can do by just typing @key{RET}.
8185
8186Note that the history records values, not expressions. If the value of
8187@code{x} is 4 and you type these commands:
8188
474c8240 8189@smallexample
c906108c
SS
8190print x
8191set x=5
474c8240 8192@end smallexample
c906108c
SS
8193
8194@noindent
8195then the value recorded in the value history by the @code{print} command
8196remains 4 even though the value of @code{x} has changed.
8197
8198@table @code
8199@kindex show values
8200@item show values
8201Print the last ten values in the value history, with their item numbers.
8202This is like @samp{p@ $$9} repeated ten times, except that @code{show
8203values} does not change the history.
8204
8205@item show values @var{n}
8206Print ten history values centered on history item number @var{n}.
8207
8208@item show values +
8209Print ten history values just after the values last printed. If no more
8210values are available, @code{show values +} produces no display.
8211@end table
8212
8213Pressing @key{RET} to repeat @code{show values @var{n}} has exactly the
8214same effect as @samp{show values +}.
8215
6d2ebf8b 8216@node Convenience Vars
79a6e687 8217@section Convenience Variables
c906108c
SS
8218
8219@cindex convenience variables
9c16f35a 8220@cindex user-defined variables
c906108c
SS
8221@value{GDBN} provides @dfn{convenience variables} that you can use within
8222@value{GDBN} to hold on to a value and refer to it later. These variables
8223exist entirely within @value{GDBN}; they are not part of your program, and
8224setting a convenience variable has no direct effect on further execution
8225of your program. That is why you can use them freely.
8226
8227Convenience variables are prefixed with @samp{$}. Any name preceded by
8228@samp{$} can be used for a convenience variable, unless it is one of
d4f3574e 8229the predefined machine-specific register names (@pxref{Registers, ,Registers}).
c906108c 8230(Value history references, in contrast, are @emph{numbers} preceded
79a6e687 8231by @samp{$}. @xref{Value History, ,Value History}.)
c906108c
SS
8232
8233You can save a value in a convenience variable with an assignment
8234expression, just as you would set a variable in your program.
8235For example:
8236
474c8240 8237@smallexample
c906108c 8238set $foo = *object_ptr
474c8240 8239@end smallexample
c906108c
SS
8240
8241@noindent
8242would save in @code{$foo} the value contained in the object pointed to by
8243@code{object_ptr}.
8244
8245Using a convenience variable for the first time creates it, but its
8246value is @code{void} until you assign a new value. You can alter the
8247value with another assignment at any time.
8248
8249Convenience variables have no fixed types. You can assign a convenience
8250variable any type of value, including structures and arrays, even if
8251that variable already has a value of a different type. The convenience
8252variable, when used as an expression, has the type of its current value.
8253
8254@table @code
8255@kindex show convenience
9c16f35a 8256@cindex show all user variables
c906108c
SS
8257@item show convenience
8258Print a list of convenience variables used so far, and their values.
d4f3574e 8259Abbreviated @code{show conv}.
53e5f3cf
AS
8260
8261@kindex init-if-undefined
8262@cindex convenience variables, initializing
8263@item init-if-undefined $@var{variable} = @var{expression}
8264Set a convenience variable if it has not already been set. This is useful
8265for user-defined commands that keep some state. It is similar, in concept,
8266to using local static variables with initializers in C (except that
8267convenience variables are global). It can also be used to allow users to
8268override default values used in a command script.
8269
8270If the variable is already defined then the expression is not evaluated so
8271any side-effects do not occur.
c906108c
SS
8272@end table
8273
8274One of the ways to use a convenience variable is as a counter to be
8275incremented or a pointer to be advanced. For example, to print
8276a field from successive elements of an array of structures:
8277
474c8240 8278@smallexample
c906108c
SS
8279set $i = 0
8280print bar[$i++]->contents
474c8240 8281@end smallexample
c906108c 8282
d4f3574e
SS
8283@noindent
8284Repeat that command by typing @key{RET}.
c906108c
SS
8285
8286Some convenience variables are created automatically by @value{GDBN} and given
8287values likely to be useful.
8288
8289@table @code
41afff9a 8290@vindex $_@r{, convenience variable}
c906108c
SS
8291@item $_
8292The variable @code{$_} is automatically set by the @code{x} command to
79a6e687 8293the last address examined (@pxref{Memory, ,Examining Memory}). Other
c906108c
SS
8294commands which provide a default address for @code{x} to examine also
8295set @code{$_} to that address; these commands include @code{info line}
8296and @code{info breakpoint}. The type of @code{$_} is @code{void *}
8297except when set by the @code{x} command, in which case it is a pointer
8298to the type of @code{$__}.
8299
41afff9a 8300@vindex $__@r{, convenience variable}
c906108c
SS
8301@item $__
8302The variable @code{$__} is automatically set by the @code{x} command
8303to the value found in the last address examined. Its type is chosen
8304to match the format in which the data was printed.
8305
8306@item $_exitcode
41afff9a 8307@vindex $_exitcode@r{, convenience variable}
c906108c
SS
8308The variable @code{$_exitcode} is automatically set to the exit code when
8309the program being debugged terminates.
4aa995e1 8310
0fb4aa4b
PA
8311@item $_sdata
8312@vindex $_sdata@r{, inspect, convenience variable}
8313The variable @code{$_sdata} contains extra collected static tracepoint
8314data. @xref{Tracepoint Actions,,Tracepoint Action Lists}. Note that
8315@code{$_sdata} could be empty, if not inspecting a trace buffer, or
8316if extra static tracepoint data has not been collected.
8317
4aa995e1
PA
8318@item $_siginfo
8319@vindex $_siginfo@r{, convenience variable}
ec7e75e7
PP
8320The variable @code{$_siginfo} contains extra signal information
8321(@pxref{extra signal information}). Note that @code{$_siginfo}
8322could be empty, if the application has not yet received any signals.
8323For example, it will be empty before you execute the @code{run} command.
711e434b
PM
8324
8325@item $_tlb
8326@vindex $_tlb@r{, convenience variable}
8327The variable @code{$_tlb} is automatically set when debugging
8328applications running on MS-Windows in native mode or connected to
8329gdbserver that supports the @code{qGetTIBAddr} request.
8330@xref{General Query Packets}.
8331This variable contains the address of the thread information block.
8332
c906108c
SS
8333@end table
8334
53a5351d
JM
8335On HP-UX systems, if you refer to a function or variable name that
8336begins with a dollar sign, @value{GDBN} searches for a user or system
8337name first, before it searches for a convenience variable.
c906108c 8338
bc3b79fd
TJB
8339@cindex convenience functions
8340@value{GDBN} also supplies some @dfn{convenience functions}. These
8341have a syntax similar to convenience variables. A convenience
8342function can be used in an expression just like an ordinary function;
8343however, a convenience function is implemented internally to
8344@value{GDBN}.
8345
8346@table @code
8347@item help function
8348@kindex help function
8349@cindex show all convenience functions
8350Print a list of all convenience functions.
8351@end table
8352
6d2ebf8b 8353@node Registers
c906108c
SS
8354@section Registers
8355
8356@cindex registers
8357You can refer to machine register contents, in expressions, as variables
8358with names starting with @samp{$}. The names of registers are different
8359for each machine; use @code{info registers} to see the names used on
8360your machine.
8361
8362@table @code
8363@kindex info registers
8364@item info registers
8365Print the names and values of all registers except floating-point
c85508ee 8366and vector registers (in the selected stack frame).
c906108c
SS
8367
8368@kindex info all-registers
8369@cindex floating point registers
8370@item info all-registers
8371Print the names and values of all registers, including floating-point
c85508ee 8372and vector registers (in the selected stack frame).
c906108c
SS
8373
8374@item info registers @var{regname} @dots{}
8375Print the @dfn{relativized} value of each specified register @var{regname}.
5d161b24
DB
8376As discussed in detail below, register values are normally relative to
8377the selected stack frame. @var{regname} may be any register name valid on
c906108c
SS
8378the machine you are using, with or without the initial @samp{$}.
8379@end table
8380
e09f16f9
EZ
8381@cindex stack pointer register
8382@cindex program counter register
8383@cindex process status register
8384@cindex frame pointer register
8385@cindex standard registers
c906108c
SS
8386@value{GDBN} has four ``standard'' register names that are available (in
8387expressions) on most machines---whenever they do not conflict with an
8388architecture's canonical mnemonics for registers. The register names
8389@code{$pc} and @code{$sp} are used for the program counter register and
8390the stack pointer. @code{$fp} is used for a register that contains a
8391pointer to the current stack frame, and @code{$ps} is used for a
8392register that contains the processor status. For example,
8393you could print the program counter in hex with
8394
474c8240 8395@smallexample
c906108c 8396p/x $pc
474c8240 8397@end smallexample
c906108c
SS
8398
8399@noindent
8400or print the instruction to be executed next with
8401
474c8240 8402@smallexample
c906108c 8403x/i $pc
474c8240 8404@end smallexample
c906108c
SS
8405
8406@noindent
8407or add four to the stack pointer@footnote{This is a way of removing
8408one word from the stack, on machines where stacks grow downward in
8409memory (most machines, nowadays). This assumes that the innermost
8410stack frame is selected; setting @code{$sp} is not allowed when other
8411stack frames are selected. To pop entire frames off the stack,
8412regardless of machine architecture, use @code{return};
79a6e687 8413see @ref{Returning, ,Returning from a Function}.} with
c906108c 8414
474c8240 8415@smallexample
c906108c 8416set $sp += 4
474c8240 8417@end smallexample
c906108c
SS
8418
8419Whenever possible, these four standard register names are available on
8420your machine even though the machine has different canonical mnemonics,
8421so long as there is no conflict. The @code{info registers} command
8422shows the canonical names. For example, on the SPARC, @code{info
8423registers} displays the processor status register as @code{$psr} but you
d4f3574e
SS
8424can also refer to it as @code{$ps}; and on x86-based machines @code{$ps}
8425is an alias for the @sc{eflags} register.
c906108c
SS
8426
8427@value{GDBN} always considers the contents of an ordinary register as an
8428integer when the register is examined in this way. Some machines have
8429special registers which can hold nothing but floating point; these
8430registers are considered to have floating point values. There is no way
8431to refer to the contents of an ordinary register as floating point value
8432(although you can @emph{print} it as a floating point value with
8433@samp{print/f $@var{regname}}).
8434
8435Some registers have distinct ``raw'' and ``virtual'' data formats. This
8436means that the data format in which the register contents are saved by
8437the operating system is not the same one that your program normally
8438sees. For example, the registers of the 68881 floating point
8439coprocessor are always saved in ``extended'' (raw) format, but all C
8440programs expect to work with ``double'' (virtual) format. In such
5d161b24 8441cases, @value{GDBN} normally works with the virtual format only (the format
c906108c
SS
8442that makes sense for your program), but the @code{info registers} command
8443prints the data in both formats.
8444
36b80e65
EZ
8445@cindex SSE registers (x86)
8446@cindex MMX registers (x86)
8447Some machines have special registers whose contents can be interpreted
8448in several different ways. For example, modern x86-based machines
8449have SSE and MMX registers that can hold several values packed
8450together in several different formats. @value{GDBN} refers to such
8451registers in @code{struct} notation:
8452
8453@smallexample
8454(@value{GDBP}) print $xmm1
8455$1 = @{
8456 v4_float = @{0, 3.43859137e-038, 1.54142831e-044, 1.821688e-044@},
8457 v2_double = @{9.92129282474342e-303, 2.7585945287983262e-313@},
8458 v16_int8 = "\000\000\000\000\3706;\001\v\000\000\000\r\000\000",
8459 v8_int16 = @{0, 0, 14072, 315, 11, 0, 13, 0@},
8460 v4_int32 = @{0, 20657912, 11, 13@},
8461 v2_int64 = @{88725056443645952, 55834574859@},
8462 uint128 = 0x0000000d0000000b013b36f800000000
8463@}
8464@end smallexample
8465
8466@noindent
8467To set values of such registers, you need to tell @value{GDBN} which
8468view of the register you wish to change, as if you were assigning
8469value to a @code{struct} member:
8470
8471@smallexample
8472 (@value{GDBP}) set $xmm1.uint128 = 0x000000000000000000000000FFFFFFFF
8473@end smallexample
8474
c906108c 8475Normally, register values are relative to the selected stack frame
79a6e687 8476(@pxref{Selection, ,Selecting a Frame}). This means that you get the
c906108c
SS
8477value that the register would contain if all stack frames farther in
8478were exited and their saved registers restored. In order to see the
8479true contents of hardware registers, you must select the innermost
8480frame (with @samp{frame 0}).
8481
8482However, @value{GDBN} must deduce where registers are saved, from the machine
8483code generated by your compiler. If some registers are not saved, or if
8484@value{GDBN} is unable to locate the saved registers, the selected stack
8485frame makes no difference.
8486
6d2ebf8b 8487@node Floating Point Hardware
79a6e687 8488@section Floating Point Hardware
c906108c
SS
8489@cindex floating point
8490
8491Depending on the configuration, @value{GDBN} may be able to give
8492you more information about the status of the floating point hardware.
8493
8494@table @code
8495@kindex info float
8496@item info float
8497Display hardware-dependent information about the floating
8498point unit. The exact contents and layout vary depending on the
8499floating point chip. Currently, @samp{info float} is supported on
8500the ARM and x86 machines.
8501@end table
c906108c 8502
e76f1f2e
AC
8503@node Vector Unit
8504@section Vector Unit
8505@cindex vector unit
8506
8507Depending on the configuration, @value{GDBN} may be able to give you
8508more information about the status of the vector unit.
8509
8510@table @code
8511@kindex info vector
8512@item info vector
8513Display information about the vector unit. The exact contents and
8514layout vary depending on the hardware.
8515@end table
8516
721c2651 8517@node OS Information
79a6e687 8518@section Operating System Auxiliary Information
721c2651
EZ
8519@cindex OS information
8520
8521@value{GDBN} provides interfaces to useful OS facilities that can help
8522you debug your program.
8523
8524@cindex @code{ptrace} system call
8525@cindex @code{struct user} contents
8526When @value{GDBN} runs on a @dfn{Posix system} (such as GNU or Unix
8527machines), it interfaces with the inferior via the @code{ptrace}
8528system call. The operating system creates a special sata structure,
8529called @code{struct user}, for this interface. You can use the
8530command @code{info udot} to display the contents of this data
8531structure.
8532
8533@table @code
8534@item info udot
8535@kindex info udot
8536Display the contents of the @code{struct user} maintained by the OS
8537kernel for the program being debugged. @value{GDBN} displays the
8538contents of @code{struct user} as a list of hex numbers, similar to
8539the @code{examine} command.
8540@end table
8541
b383017d
RM
8542@cindex auxiliary vector
8543@cindex vector, auxiliary
b383017d
RM
8544Some operating systems supply an @dfn{auxiliary vector} to programs at
8545startup. This is akin to the arguments and environment that you
8546specify for a program, but contains a system-dependent variety of
8547binary values that tell system libraries important details about the
8548hardware, operating system, and process. Each value's purpose is
8549identified by an integer tag; the meanings are well-known but system-specific.
8550Depending on the configuration and operating system facilities,
9c16f35a
EZ
8551@value{GDBN} may be able to show you this information. For remote
8552targets, this functionality may further depend on the remote stub's
427c3a89
DJ
8553support of the @samp{qXfer:auxv:read} packet, see
8554@ref{qXfer auxiliary vector read}.
b383017d
RM
8555
8556@table @code
8557@kindex info auxv
8558@item info auxv
8559Display the auxiliary vector of the inferior, which can be either a
e4937fc1 8560live process or a core dump file. @value{GDBN} prints each tag value
b383017d
RM
8561numerically, and also shows names and text descriptions for recognized
8562tags. Some values in the vector are numbers, some bit masks, and some
e4937fc1 8563pointers to strings or other data. @value{GDBN} displays each value in the
b383017d
RM
8564most appropriate form for a recognized tag, and in hexadecimal for
8565an unrecognized tag.
8566@end table
8567
07e059b5
VP
8568On some targets, @value{GDBN} can access operating-system-specific information
8569and display it to user, without interpretation. For remote targets,
8570this functionality depends on the remote stub's support of the
8571@samp{qXfer:osdata:read} packet, see @ref{qXfer osdata read}.
8572
8573@table @code
a61408f8
SS
8574@kindex info os
8575@item info os
8576List the types of OS information available for the target. If the
8577target does not return a list of possible types, this command will
8578report an error.
8579
07e059b5
VP
8580@kindex info os processes
8581@item info os processes
8582Display the list of processes on the target. For each process,
8583@value{GDBN} prints the process identifier, the name of the user, and
8584the command corresponding to the process.
8585@end table
721c2651 8586
29e57380 8587@node Memory Region Attributes
79a6e687 8588@section Memory Region Attributes
29e57380
C
8589@cindex memory region attributes
8590
b383017d 8591@dfn{Memory region attributes} allow you to describe special handling
fd79ecee
DJ
8592required by regions of your target's memory. @value{GDBN} uses
8593attributes to determine whether to allow certain types of memory
8594accesses; whether to use specific width accesses; and whether to cache
8595target memory. By default the description of memory regions is
8596fetched from the target (if the current target supports this), but the
8597user can override the fetched regions.
29e57380
C
8598
8599Defined memory regions can be individually enabled and disabled. When a
8600memory region is disabled, @value{GDBN} uses the default attributes when
8601accessing memory in that region. Similarly, if no memory regions have
8602been defined, @value{GDBN} uses the default attributes when accessing
8603all memory.
8604
b383017d 8605When a memory region is defined, it is given a number to identify it;
29e57380
C
8606to enable, disable, or remove a memory region, you specify that number.
8607
8608@table @code
8609@kindex mem
bfac230e 8610@item mem @var{lower} @var{upper} @var{attributes}@dots{}
09d4efe1
EZ
8611Define a memory region bounded by @var{lower} and @var{upper} with
8612attributes @var{attributes}@dots{}, and add it to the list of regions
8613monitored by @value{GDBN}. Note that @var{upper} == 0 is a special
d3e8051b 8614case: it is treated as the target's maximum memory address.
bfac230e 8615(0xffff on 16 bit targets, 0xffffffff on 32 bit targets, etc.)
29e57380 8616
fd79ecee
DJ
8617@item mem auto
8618Discard any user changes to the memory regions and use target-supplied
8619regions, if available, or no regions if the target does not support.
8620
29e57380
C
8621@kindex delete mem
8622@item delete mem @var{nums}@dots{}
09d4efe1
EZ
8623Remove memory regions @var{nums}@dots{} from the list of regions
8624monitored by @value{GDBN}.
29e57380
C
8625
8626@kindex disable mem
8627@item disable mem @var{nums}@dots{}
09d4efe1 8628Disable monitoring of memory regions @var{nums}@dots{}.
b383017d 8629A disabled memory region is not forgotten.
29e57380
C
8630It may be enabled again later.
8631
8632@kindex enable mem
8633@item enable mem @var{nums}@dots{}
09d4efe1 8634Enable monitoring of memory regions @var{nums}@dots{}.
29e57380
C
8635
8636@kindex info mem
8637@item info mem
8638Print a table of all defined memory regions, with the following columns
09d4efe1 8639for each region:
29e57380
C
8640
8641@table @emph
8642@item Memory Region Number
8643@item Enabled or Disabled.
b383017d 8644Enabled memory regions are marked with @samp{y}.
29e57380
C
8645Disabled memory regions are marked with @samp{n}.
8646
8647@item Lo Address
8648The address defining the inclusive lower bound of the memory region.
8649
8650@item Hi Address
8651The address defining the exclusive upper bound of the memory region.
8652
8653@item Attributes
8654The list of attributes set for this memory region.
8655@end table
8656@end table
8657
8658
8659@subsection Attributes
8660
b383017d 8661@subsubsection Memory Access Mode
29e57380
C
8662The access mode attributes set whether @value{GDBN} may make read or
8663write accesses to a memory region.
8664
8665While these attributes prevent @value{GDBN} from performing invalid
8666memory accesses, they do nothing to prevent the target system, I/O DMA,
359df76b 8667etc.@: from accessing memory.
29e57380
C
8668
8669@table @code
8670@item ro
8671Memory is read only.
8672@item wo
8673Memory is write only.
8674@item rw
6ca652b0 8675Memory is read/write. This is the default.
29e57380
C
8676@end table
8677
8678@subsubsection Memory Access Size
d3e8051b 8679The access size attribute tells @value{GDBN} to use specific sized
29e57380
C
8680accesses in the memory region. Often memory mapped device registers
8681require specific sized accesses. If no access size attribute is
8682specified, @value{GDBN} may use accesses of any size.
8683
8684@table @code
8685@item 8
8686Use 8 bit memory accesses.
8687@item 16
8688Use 16 bit memory accesses.
8689@item 32
8690Use 32 bit memory accesses.
8691@item 64
8692Use 64 bit memory accesses.
8693@end table
8694
8695@c @subsubsection Hardware/Software Breakpoints
8696@c The hardware/software breakpoint attributes set whether @value{GDBN}
8697@c will use hardware or software breakpoints for the internal breakpoints
8698@c used by the step, next, finish, until, etc. commands.
8699@c
8700@c @table @code
8701@c @item hwbreak
b383017d 8702@c Always use hardware breakpoints
29e57380
C
8703@c @item swbreak (default)
8704@c @end table
8705
8706@subsubsection Data Cache
8707The data cache attributes set whether @value{GDBN} will cache target
8708memory. While this generally improves performance by reducing debug
8709protocol overhead, it can lead to incorrect results because @value{GDBN}
8710does not know about volatile variables or memory mapped device
8711registers.
8712
8713@table @code
8714@item cache
b383017d 8715Enable @value{GDBN} to cache target memory.
6ca652b0
EZ
8716@item nocache
8717Disable @value{GDBN} from caching target memory. This is the default.
29e57380
C
8718@end table
8719
4b5752d0
VP
8720@subsection Memory Access Checking
8721@value{GDBN} can be instructed to refuse accesses to memory that is
8722not explicitly described. This can be useful if accessing such
8723regions has undesired effects for a specific target, or to provide
8724better error checking. The following commands control this behaviour.
8725
8726@table @code
8727@kindex set mem inaccessible-by-default
8728@item set mem inaccessible-by-default [on|off]
8729If @code{on} is specified, make @value{GDBN} treat memory not
8730explicitly described by the memory ranges as non-existent and refuse accesses
8731to such memory. The checks are only performed if there's at least one
8732memory range defined. If @code{off} is specified, make @value{GDBN}
8733treat the memory not explicitly described by the memory ranges as RAM.
56cf5405 8734The default value is @code{on}.
4b5752d0
VP
8735@kindex show mem inaccessible-by-default
8736@item show mem inaccessible-by-default
8737Show the current handling of accesses to unknown memory.
8738@end table
8739
8740
29e57380 8741@c @subsubsection Memory Write Verification
b383017d 8742@c The memory write verification attributes set whether @value{GDBN}
29e57380
C
8743@c will re-reads data after each write to verify the write was successful.
8744@c
8745@c @table @code
8746@c @item verify
8747@c @item noverify (default)
8748@c @end table
8749
16d9dec6 8750@node Dump/Restore Files
79a6e687 8751@section Copy Between Memory and a File
16d9dec6
MS
8752@cindex dump/restore files
8753@cindex append data to a file
8754@cindex dump data to a file
8755@cindex restore data from a file
16d9dec6 8756
df5215a6
JB
8757You can use the commands @code{dump}, @code{append}, and
8758@code{restore} to copy data between target memory and a file. The
8759@code{dump} and @code{append} commands write data to a file, and the
8760@code{restore} command reads data from a file back into the inferior's
8761memory. Files may be in binary, Motorola S-record, Intel hex, or
8762Tektronix Hex format; however, @value{GDBN} can only append to binary
8763files.
8764
8765@table @code
8766
8767@kindex dump
8768@item dump @r{[}@var{format}@r{]} memory @var{filename} @var{start_addr} @var{end_addr}
8769@itemx dump @r{[}@var{format}@r{]} value @var{filename} @var{expr}
8770Dump the contents of memory from @var{start_addr} to @var{end_addr},
8771or the value of @var{expr}, to @var{filename} in the given format.
16d9dec6 8772
df5215a6 8773The @var{format} parameter may be any one of:
16d9dec6 8774@table @code
df5215a6
JB
8775@item binary
8776Raw binary form.
8777@item ihex
8778Intel hex format.
8779@item srec
8780Motorola S-record format.
8781@item tekhex
8782Tektronix Hex format.
8783@end table
8784
8785@value{GDBN} uses the same definitions of these formats as the
8786@sc{gnu} binary utilities, like @samp{objdump} and @samp{objcopy}. If
8787@var{format} is omitted, @value{GDBN} dumps the data in raw binary
8788form.
8789
8790@kindex append
8791@item append @r{[}binary@r{]} memory @var{filename} @var{start_addr} @var{end_addr}
8792@itemx append @r{[}binary@r{]} value @var{filename} @var{expr}
8793Append the contents of memory from @var{start_addr} to @var{end_addr},
09d4efe1 8794or the value of @var{expr}, to the file @var{filename}, in raw binary form.
df5215a6
JB
8795(@value{GDBN} can only append data to files in raw binary form.)
8796
8797@kindex restore
8798@item restore @var{filename} @r{[}binary@r{]} @var{bias} @var{start} @var{end}
8799Restore the contents of file @var{filename} into memory. The
8800@code{restore} command can automatically recognize any known @sc{bfd}
8801file format, except for raw binary. To restore a raw binary file you
8802must specify the optional keyword @code{binary} after the filename.
16d9dec6 8803
b383017d 8804If @var{bias} is non-zero, its value will be added to the addresses
16d9dec6
MS
8805contained in the file. Binary files always start at address zero, so
8806they will be restored at address @var{bias}. Other bfd files have
8807a built-in location; they will be restored at offset @var{bias}
8808from that location.
8809
8810If @var{start} and/or @var{end} are non-zero, then only data between
8811file offset @var{start} and file offset @var{end} will be restored.
b383017d 8812These offsets are relative to the addresses in the file, before
16d9dec6
MS
8813the @var{bias} argument is applied.
8814
8815@end table
8816
384ee23f
EZ
8817@node Core File Generation
8818@section How to Produce a Core File from Your Program
8819@cindex dump core from inferior
8820
8821A @dfn{core file} or @dfn{core dump} is a file that records the memory
8822image of a running process and its process status (register values
8823etc.). Its primary use is post-mortem debugging of a program that
8824crashed while it ran outside a debugger. A program that crashes
8825automatically produces a core file, unless this feature is disabled by
8826the user. @xref{Files}, for information on invoking @value{GDBN} in
8827the post-mortem debugging mode.
8828
8829Occasionally, you may wish to produce a core file of the program you
8830are debugging in order to preserve a snapshot of its state.
8831@value{GDBN} has a special command for that.
8832
8833@table @code
8834@kindex gcore
8835@kindex generate-core-file
8836@item generate-core-file [@var{file}]
8837@itemx gcore [@var{file}]
8838Produce a core dump of the inferior process. The optional argument
8839@var{file} specifies the file name where to put the core dump. If not
8840specified, the file name defaults to @file{core.@var{pid}}, where
8841@var{pid} is the inferior process ID.
8842
8843Note that this command is implemented only for some systems (as of
8844this writing, @sc{gnu}/Linux, FreeBSD, Solaris, Unixware, and S390).
8845@end table
8846
a0eb71c5
KB
8847@node Character Sets
8848@section Character Sets
8849@cindex character sets
8850@cindex charset
8851@cindex translating between character sets
8852@cindex host character set
8853@cindex target character set
8854
8855If the program you are debugging uses a different character set to
8856represent characters and strings than the one @value{GDBN} uses itself,
8857@value{GDBN} can automatically translate between the character sets for
8858you. The character set @value{GDBN} uses we call the @dfn{host
8859character set}; the one the inferior program uses we call the
8860@dfn{target character set}.
8861
8862For example, if you are running @value{GDBN} on a @sc{gnu}/Linux system, which
8863uses the ISO Latin 1 character set, but you are using @value{GDBN}'s
ea35711c 8864remote protocol (@pxref{Remote Debugging}) to debug a program
a0eb71c5
KB
8865running on an IBM mainframe, which uses the @sc{ebcdic} character set,
8866then the host character set is Latin-1, and the target character set is
8867@sc{ebcdic}. If you give @value{GDBN} the command @code{set
e33d66ec 8868target-charset EBCDIC-US}, then @value{GDBN} translates between
a0eb71c5
KB
8869@sc{ebcdic} and Latin 1 as you print character or string values, or use
8870character and string literals in expressions.
8871
8872@value{GDBN} has no way to automatically recognize which character set
8873the inferior program uses; you must tell it, using the @code{set
8874target-charset} command, described below.
8875
8876Here are the commands for controlling @value{GDBN}'s character set
8877support:
8878
8879@table @code
8880@item set target-charset @var{charset}
8881@kindex set target-charset
10af6951
EZ
8882Set the current target character set to @var{charset}. To display the
8883list of supported target character sets, type
8884@kbd{@w{set target-charset @key{TAB}@key{TAB}}}.
a0eb71c5 8885
a0eb71c5
KB
8886@item set host-charset @var{charset}
8887@kindex set host-charset
8888Set the current host character set to @var{charset}.
8889
8890By default, @value{GDBN} uses a host character set appropriate to the
8891system it is running on; you can override that default using the
732f6a93
TT
8892@code{set host-charset} command. On some systems, @value{GDBN} cannot
8893automatically determine the appropriate host character set. In this
8894case, @value{GDBN} uses @samp{UTF-8}.
a0eb71c5
KB
8895
8896@value{GDBN} can only use certain character sets as its host character
10af6951
EZ
8897set. If you type @kbd{@w{set target-charset @key{TAB}@key{TAB}}},
8898@value{GDBN} will list the host character sets it supports.
a0eb71c5
KB
8899
8900@item set charset @var{charset}
8901@kindex set charset
e33d66ec 8902Set the current host and target character sets to @var{charset}. As
10af6951
EZ
8903above, if you type @kbd{@w{set charset @key{TAB}@key{TAB}}},
8904@value{GDBN} will list the names of the character sets that can be used
e33d66ec
EZ
8905for both host and target.
8906
a0eb71c5 8907@item show charset
a0eb71c5 8908@kindex show charset
10af6951 8909Show the names of the current host and target character sets.
e33d66ec 8910
10af6951 8911@item show host-charset
a0eb71c5 8912@kindex show host-charset
10af6951 8913Show the name of the current host character set.
e33d66ec 8914
10af6951 8915@item show target-charset
a0eb71c5 8916@kindex show target-charset
10af6951 8917Show the name of the current target character set.
a0eb71c5 8918
10af6951
EZ
8919@item set target-wide-charset @var{charset}
8920@kindex set target-wide-charset
8921Set the current target's wide character set to @var{charset}. This is
8922the character set used by the target's @code{wchar_t} type. To
8923display the list of supported wide character sets, type
8924@kbd{@w{set target-wide-charset @key{TAB}@key{TAB}}}.
8925
8926@item show target-wide-charset
8927@kindex show target-wide-charset
8928Show the name of the current target's wide character set.
a0eb71c5
KB
8929@end table
8930
a0eb71c5
KB
8931Here is an example of @value{GDBN}'s character set support in action.
8932Assume that the following source code has been placed in the file
8933@file{charset-test.c}:
8934
8935@smallexample
8936#include <stdio.h>
8937
8938char ascii_hello[]
8939 = @{72, 101, 108, 108, 111, 44, 32, 119,
8940 111, 114, 108, 100, 33, 10, 0@};
8941char ibm1047_hello[]
8942 = @{200, 133, 147, 147, 150, 107, 64, 166,
8943 150, 153, 147, 132, 90, 37, 0@};
8944
8945main ()
8946@{
8947 printf ("Hello, world!\n");
8948@}
10998722 8949@end smallexample
a0eb71c5
KB
8950
8951In this program, @code{ascii_hello} and @code{ibm1047_hello} are arrays
8952containing the string @samp{Hello, world!} followed by a newline,
8953encoded in the @sc{ascii} and @sc{ibm1047} character sets.
8954
8955We compile the program, and invoke the debugger on it:
8956
8957@smallexample
8958$ gcc -g charset-test.c -o charset-test
8959$ gdb -nw charset-test
8960GNU gdb 2001-12-19-cvs
8961Copyright 2001 Free Software Foundation, Inc.
8962@dots{}
f7dc1244 8963(@value{GDBP})
10998722 8964@end smallexample
a0eb71c5
KB
8965
8966We can use the @code{show charset} command to see what character sets
8967@value{GDBN} is currently using to interpret and display characters and
8968strings:
8969
8970@smallexample
f7dc1244 8971(@value{GDBP}) show charset
e33d66ec 8972The current host and target character set is `ISO-8859-1'.
f7dc1244 8973(@value{GDBP})
10998722 8974@end smallexample
a0eb71c5
KB
8975
8976For the sake of printing this manual, let's use @sc{ascii} as our
8977initial character set:
8978@smallexample
f7dc1244
EZ
8979(@value{GDBP}) set charset ASCII
8980(@value{GDBP}) show charset
e33d66ec 8981The current host and target character set is `ASCII'.
f7dc1244 8982(@value{GDBP})
10998722 8983@end smallexample
a0eb71c5
KB
8984
8985Let's assume that @sc{ascii} is indeed the correct character set for our
8986host system --- in other words, let's assume that if @value{GDBN} prints
8987characters using the @sc{ascii} character set, our terminal will display
8988them properly. Since our current target character set is also
8989@sc{ascii}, the contents of @code{ascii_hello} print legibly:
8990
8991@smallexample
f7dc1244 8992(@value{GDBP}) print ascii_hello
a0eb71c5 8993$1 = 0x401698 "Hello, world!\n"
f7dc1244 8994(@value{GDBP}) print ascii_hello[0]
a0eb71c5 8995$2 = 72 'H'
f7dc1244 8996(@value{GDBP})
10998722 8997@end smallexample
a0eb71c5
KB
8998
8999@value{GDBN} uses the target character set for character and string
9000literals you use in expressions:
9001
9002@smallexample
f7dc1244 9003(@value{GDBP}) print '+'
a0eb71c5 9004$3 = 43 '+'
f7dc1244 9005(@value{GDBP})
10998722 9006@end smallexample
a0eb71c5
KB
9007
9008The @sc{ascii} character set uses the number 43 to encode the @samp{+}
9009character.
9010
9011@value{GDBN} relies on the user to tell it which character set the
9012target program uses. If we print @code{ibm1047_hello} while our target
9013character set is still @sc{ascii}, we get jibberish:
9014
9015@smallexample
f7dc1244 9016(@value{GDBP}) print ibm1047_hello
a0eb71c5 9017$4 = 0x4016a8 "\310\205\223\223\226k@@\246\226\231\223\204Z%"
f7dc1244 9018(@value{GDBP}) print ibm1047_hello[0]
a0eb71c5 9019$5 = 200 '\310'
f7dc1244 9020(@value{GDBP})
10998722 9021@end smallexample
a0eb71c5 9022
e33d66ec 9023If we invoke the @code{set target-charset} followed by @key{TAB}@key{TAB},
a0eb71c5
KB
9024@value{GDBN} tells us the character sets it supports:
9025
9026@smallexample
f7dc1244 9027(@value{GDBP}) set target-charset
b383017d 9028ASCII EBCDIC-US IBM1047 ISO-8859-1
f7dc1244 9029(@value{GDBP}) set target-charset
10998722 9030@end smallexample
a0eb71c5
KB
9031
9032We can select @sc{ibm1047} as our target character set, and examine the
9033program's strings again. Now the @sc{ascii} string is wrong, but
9034@value{GDBN} translates the contents of @code{ibm1047_hello} from the
9035target character set, @sc{ibm1047}, to the host character set,
9036@sc{ascii}, and they display correctly:
9037
9038@smallexample
f7dc1244
EZ
9039(@value{GDBP}) set target-charset IBM1047
9040(@value{GDBP}) show charset
e33d66ec
EZ
9041The current host character set is `ASCII'.
9042The current target character set is `IBM1047'.
f7dc1244 9043(@value{GDBP}) print ascii_hello
a0eb71c5 9044$6 = 0x401698 "\110\145%%?\054\040\167?\162%\144\041\012"
f7dc1244 9045(@value{GDBP}) print ascii_hello[0]
a0eb71c5 9046$7 = 72 '\110'
f7dc1244 9047(@value{GDBP}) print ibm1047_hello
a0eb71c5 9048$8 = 0x4016a8 "Hello, world!\n"
f7dc1244 9049(@value{GDBP}) print ibm1047_hello[0]
a0eb71c5 9050$9 = 200 'H'
f7dc1244 9051(@value{GDBP})
10998722 9052@end smallexample
a0eb71c5
KB
9053
9054As above, @value{GDBN} uses the target character set for character and
9055string literals you use in expressions:
9056
9057@smallexample
f7dc1244 9058(@value{GDBP}) print '+'
a0eb71c5 9059$10 = 78 '+'
f7dc1244 9060(@value{GDBP})
10998722 9061@end smallexample
a0eb71c5 9062
e33d66ec 9063The @sc{ibm1047} character set uses the number 78 to encode the @samp{+}
a0eb71c5
KB
9064character.
9065
09d4efe1
EZ
9066@node Caching Remote Data
9067@section Caching Data of Remote Targets
9068@cindex caching data of remote targets
9069
4e5d721f 9070@value{GDBN} caches data exchanged between the debugger and a
ea35711c 9071remote target (@pxref{Remote Debugging}). Such caching generally improves
09d4efe1 9072performance, because it reduces the overhead of the remote protocol by
4e5d721f
DE
9073bundling memory reads and writes into large chunks. Unfortunately, simply
9074caching everything would lead to incorrect results, since @value{GDBN}
9075does not necessarily know anything about volatile values, memory-mapped I/O
29b090c0
DE
9076addresses, etc. Furthermore, in non-stop mode (@pxref{Non-Stop Mode})
9077memory can be changed @emph{while} a gdb command is executing.
9078Therefore, by default, @value{GDBN} only caches data
9079known to be on the stack@footnote{In non-stop mode, it is moderately
9080rare for a running thread to modify the stack of a stopped thread
9081in a way that would interfere with a backtrace, and caching of
9082stack reads provides a significant speed up of remote backtraces.}.
9083Other regions of memory can be explicitly marked as
4e5d721f 9084cacheable; see @pxref{Memory Region Attributes}.
09d4efe1
EZ
9085
9086@table @code
9087@kindex set remotecache
9088@item set remotecache on
9089@itemx set remotecache off
4e5d721f
DE
9090This option no longer does anything; it exists for compatibility
9091with old scripts.
09d4efe1
EZ
9092
9093@kindex show remotecache
9094@item show remotecache
4e5d721f
DE
9095Show the current state of the obsolete remotecache flag.
9096
9097@kindex set stack-cache
9098@item set stack-cache on
9099@itemx set stack-cache off
9100Enable or disable caching of stack accesses. When @code{ON}, use
9101caching. By default, this option is @code{ON}.
9102
9103@kindex show stack-cache
9104@item show stack-cache
9105Show the current state of data caching for memory accesses.
09d4efe1
EZ
9106
9107@kindex info dcache
4e5d721f 9108@item info dcache @r{[}line@r{]}
09d4efe1 9109Print the information about the data cache performance. The
4e5d721f
DE
9110information displayed includes the dcache width and depth, and for
9111each cache line, its number, address, and how many times it was
9112referenced. This command is useful for debugging the data cache
9113operation.
9114
9115If a line number is specified, the contents of that line will be
9116printed in hex.
09d4efe1
EZ
9117@end table
9118
08388c79
DE
9119@node Searching Memory
9120@section Search Memory
9121@cindex searching memory
9122
9123Memory can be searched for a particular sequence of bytes with the
9124@code{find} command.
9125
9126@table @code
9127@kindex find
9128@item find @r{[}/@var{sn}@r{]} @var{start_addr}, +@var{len}, @var{val1} @r{[}, @var{val2}, @dots{}@r{]}
9129@itemx find @r{[}/@var{sn}@r{]} @var{start_addr}, @var{end_addr}, @var{val1} @r{[}, @var{val2}, @dots{}@r{]}
9130Search memory for the sequence of bytes specified by @var{val1}, @var{val2},
9131etc. The search begins at address @var{start_addr} and continues for either
9132@var{len} bytes or through to @var{end_addr} inclusive.
9133@end table
9134
9135@var{s} and @var{n} are optional parameters.
9136They may be specified in either order, apart or together.
9137
9138@table @r
9139@item @var{s}, search query size
9140The size of each search query value.
9141
9142@table @code
9143@item b
9144bytes
9145@item h
9146halfwords (two bytes)
9147@item w
9148words (four bytes)
9149@item g
9150giant words (eight bytes)
9151@end table
9152
9153All values are interpreted in the current language.
9154This means, for example, that if the current source language is C/C@t{++}
9155then searching for the string ``hello'' includes the trailing '\0'.
9156
9157If the value size is not specified, it is taken from the
9158value's type in the current language.
9159This is useful when one wants to specify the search
9160pattern as a mixture of types.
9161Note that this means, for example, that in the case of C-like languages
9162a search for an untyped 0x42 will search for @samp{(int) 0x42}
9163which is typically four bytes.
9164
9165@item @var{n}, maximum number of finds
9166The maximum number of matches to print. The default is to print all finds.
9167@end table
9168
9169You can use strings as search values. Quote them with double-quotes
9170 (@code{"}).
9171The string value is copied into the search pattern byte by byte,
9172regardless of the endianness of the target and the size specification.
9173
9174The address of each match found is printed as well as a count of the
9175number of matches found.
9176
9177The address of the last value found is stored in convenience variable
9178@samp{$_}.
9179A count of the number of matches is stored in @samp{$numfound}.
9180
9181For example, if stopped at the @code{printf} in this function:
9182
9183@smallexample
9184void
9185hello ()
9186@{
9187 static char hello[] = "hello-hello";
9188 static struct @{ char c; short s; int i; @}
9189 __attribute__ ((packed)) mixed
9190 = @{ 'c', 0x1234, 0x87654321 @};
9191 printf ("%s\n", hello);
9192@}
9193@end smallexample
9194
9195@noindent
9196you get during debugging:
9197
9198@smallexample
9199(gdb) find &hello[0], +sizeof(hello), "hello"
92000x804956d <hello.1620+6>
92011 pattern found
9202(gdb) find &hello[0], +sizeof(hello), 'h', 'e', 'l', 'l', 'o'
92030x8049567 <hello.1620>
92040x804956d <hello.1620+6>
92052 patterns found
9206(gdb) find /b1 &hello[0], +sizeof(hello), 'h', 0x65, 'l'
92070x8049567 <hello.1620>
92081 pattern found
9209(gdb) find &mixed, +sizeof(mixed), (char) 'c', (short) 0x1234, (int) 0x87654321
92100x8049560 <mixed.1625>
92111 pattern found
9212(gdb) print $numfound
9213$1 = 1
9214(gdb) print $_
9215$2 = (void *) 0x8049560
9216@end smallexample
a0eb71c5 9217
edb3359d
DJ
9218@node Optimized Code
9219@chapter Debugging Optimized Code
9220@cindex optimized code, debugging
9221@cindex debugging optimized code
9222
9223Almost all compilers support optimization. With optimization
9224disabled, the compiler generates assembly code that corresponds
9225directly to your source code, in a simplistic way. As the compiler
9226applies more powerful optimizations, the generated assembly code
9227diverges from your original source code. With help from debugging
9228information generated by the compiler, @value{GDBN} can map from
9229the running program back to constructs from your original source.
9230
9231@value{GDBN} is more accurate with optimization disabled. If you
9232can recompile without optimization, it is easier to follow the
9233progress of your program during debugging. But, there are many cases
9234where you may need to debug an optimized version.
9235
9236When you debug a program compiled with @samp{-g -O}, remember that the
9237optimizer has rearranged your code; the debugger shows you what is
9238really there. Do not be too surprised when the execution path does not
9239exactly match your source file! An extreme example: if you define a
9240variable, but never use it, @value{GDBN} never sees that
9241variable---because the compiler optimizes it out of existence.
9242
9243Some things do not work as well with @samp{-g -O} as with just
9244@samp{-g}, particularly on machines with instruction scheduling. If in
9245doubt, recompile with @samp{-g} alone, and if this fixes the problem,
9246please report it to us as a bug (including a test case!).
9247@xref{Variables}, for more information about debugging optimized code.
9248
9249@menu
9250* Inline Functions:: How @value{GDBN} presents inlining
9251@end menu
9252
9253@node Inline Functions
9254@section Inline Functions
9255@cindex inline functions, debugging
9256
9257@dfn{Inlining} is an optimization that inserts a copy of the function
9258body directly at each call site, instead of jumping to a shared
9259routine. @value{GDBN} displays inlined functions just like
9260non-inlined functions. They appear in backtraces. You can view their
9261arguments and local variables, step into them with @code{step}, skip
9262them with @code{next}, and escape from them with @code{finish}.
9263You can check whether a function was inlined by using the
9264@code{info frame} command.
9265
9266For @value{GDBN} to support inlined functions, the compiler must
9267record information about inlining in the debug information ---
9268@value{NGCC} using the @sc{dwarf 2} format does this, and several
9269other compilers do also. @value{GDBN} only supports inlined functions
9270when using @sc{dwarf 2}. Versions of @value{NGCC} before 4.1
9271do not emit two required attributes (@samp{DW_AT_call_file} and
9272@samp{DW_AT_call_line}); @value{GDBN} does not display inlined
9273function calls with earlier versions of @value{NGCC}. It instead
9274displays the arguments and local variables of inlined functions as
9275local variables in the caller.
9276
9277The body of an inlined function is directly included at its call site;
9278unlike a non-inlined function, there are no instructions devoted to
9279the call. @value{GDBN} still pretends that the call site and the
9280start of the inlined function are different instructions. Stepping to
9281the call site shows the call site, and then stepping again shows
9282the first line of the inlined function, even though no additional
9283instructions are executed.
9284
9285This makes source-level debugging much clearer; you can see both the
9286context of the call and then the effect of the call. Only stepping by
9287a single instruction using @code{stepi} or @code{nexti} does not do
9288this; single instruction steps always show the inlined body.
9289
9290There are some ways that @value{GDBN} does not pretend that inlined
9291function calls are the same as normal calls:
9292
9293@itemize @bullet
9294@item
9295You cannot set breakpoints on inlined functions. @value{GDBN}
9296either reports that there is no symbol with that name, or else sets the
9297breakpoint only on non-inlined copies of the function. This limitation
9298will be removed in a future version of @value{GDBN}; until then,
9299set a breakpoint by line number on the first line of the inlined
9300function instead.
9301
9302@item
9303Setting breakpoints at the call site of an inlined function may not
9304work, because the call site does not contain any code. @value{GDBN}
9305may incorrectly move the breakpoint to the next line of the enclosing
9306function, after the call. This limitation will be removed in a future
9307version of @value{GDBN}; until then, set a breakpoint on an earlier line
9308or inside the inlined function instead.
9309
9310@item
9311@value{GDBN} cannot locate the return value of inlined calls after
9312using the @code{finish} command. This is a limitation of compiler-generated
9313debugging information; after @code{finish}, you can step to the next line
9314and print a variable where your program stored the return value.
9315
9316@end itemize
9317
9318
e2e0bcd1
JB
9319@node Macros
9320@chapter C Preprocessor Macros
9321
49efadf5 9322Some languages, such as C and C@t{++}, provide a way to define and invoke
e2e0bcd1
JB
9323``preprocessor macros'' which expand into strings of tokens.
9324@value{GDBN} can evaluate expressions containing macro invocations, show
9325the result of macro expansion, and show a macro's definition, including
9326where it was defined.
9327
9328You may need to compile your program specially to provide @value{GDBN}
9329with information about preprocessor macros. Most compilers do not
9330include macros in their debugging information, even when you compile
9331with the @option{-g} flag. @xref{Compilation}.
9332
9333A program may define a macro at one point, remove that definition later,
9334and then provide a different definition after that. Thus, at different
9335points in the program, a macro may have different definitions, or have
9336no definition at all. If there is a current stack frame, @value{GDBN}
9337uses the macros in scope at that frame's source code line. Otherwise,
9338@value{GDBN} uses the macros in scope at the current listing location;
9339see @ref{List}.
9340
e2e0bcd1
JB
9341Whenever @value{GDBN} evaluates an expression, it always expands any
9342macro invocations present in the expression. @value{GDBN} also provides
9343the following commands for working with macros explicitly.
9344
9345@table @code
9346
9347@kindex macro expand
9348@cindex macro expansion, showing the results of preprocessor
9349@cindex preprocessor macro expansion, showing the results of
9350@cindex expanding preprocessor macros
9351@item macro expand @var{expression}
9352@itemx macro exp @var{expression}
9353Show the results of expanding all preprocessor macro invocations in
9354@var{expression}. Since @value{GDBN} simply expands macros, but does
9355not parse the result, @var{expression} need not be a valid expression;
9356it can be any string of tokens.
9357
09d4efe1 9358@kindex macro exp1
e2e0bcd1
JB
9359@item macro expand-once @var{expression}
9360@itemx macro exp1 @var{expression}
4644b6e3 9361@cindex expand macro once
e2e0bcd1
JB
9362@i{(This command is not yet implemented.)} Show the results of
9363expanding those preprocessor macro invocations that appear explicitly in
9364@var{expression}. Macro invocations appearing in that expansion are
9365left unchanged. This command allows you to see the effect of a
9366particular macro more clearly, without being confused by further
9367expansions. Since @value{GDBN} simply expands macros, but does not
9368parse the result, @var{expression} need not be a valid expression; it
9369can be any string of tokens.
9370
475b0867 9371@kindex info macro
e2e0bcd1
JB
9372@cindex macro definition, showing
9373@cindex definition, showing a macro's
475b0867 9374@item info macro @var{macro}
e2e0bcd1 9375Show the definition of the macro named @var{macro}, and describe the
484086b7 9376source location or compiler command-line where that definition was established.
e2e0bcd1
JB
9377
9378@kindex macro define
9379@cindex user-defined macros
9380@cindex defining macros interactively
9381@cindex macros, user-defined
9382@item macro define @var{macro} @var{replacement-list}
9383@itemx macro define @var{macro}(@var{arglist}) @var{replacement-list}
d7d9f01e
TT
9384Introduce a definition for a preprocessor macro named @var{macro},
9385invocations of which are replaced by the tokens given in
9386@var{replacement-list}. The first form of this command defines an
9387``object-like'' macro, which takes no arguments; the second form
9388defines a ``function-like'' macro, which takes the arguments given in
9389@var{arglist}.
9390
9391A definition introduced by this command is in scope in every
9392expression evaluated in @value{GDBN}, until it is removed with the
9393@code{macro undef} command, described below. The definition overrides
9394all definitions for @var{macro} present in the program being debugged,
9395as well as any previous user-supplied definition.
e2e0bcd1
JB
9396
9397@kindex macro undef
9398@item macro undef @var{macro}
d7d9f01e
TT
9399Remove any user-supplied definition for the macro named @var{macro}.
9400This command only affects definitions provided with the @code{macro
9401define} command, described above; it cannot remove definitions present
9402in the program being debugged.
e2e0bcd1 9403
09d4efe1
EZ
9404@kindex macro list
9405@item macro list
d7d9f01e 9406List all the macros defined using the @code{macro define} command.
e2e0bcd1
JB
9407@end table
9408
9409@cindex macros, example of debugging with
9410Here is a transcript showing the above commands in action. First, we
9411show our source files:
9412
9413@smallexample
9414$ cat sample.c
9415#include <stdio.h>
9416#include "sample.h"
9417
9418#define M 42
9419#define ADD(x) (M + x)
9420
9421main ()
9422@{
9423#define N 28
9424 printf ("Hello, world!\n");
9425#undef N
9426 printf ("We're so creative.\n");
9427#define N 1729
9428 printf ("Goodbye, world!\n");
9429@}
9430$ cat sample.h
9431#define Q <
9432$
9433@end smallexample
9434
9435Now, we compile the program using the @sc{gnu} C compiler, @value{NGCC}.
9436We pass the @option{-gdwarf-2} and @option{-g3} flags to ensure the
9437compiler includes information about preprocessor macros in the debugging
9438information.
9439
9440@smallexample
9441$ gcc -gdwarf-2 -g3 sample.c -o sample
9442$
9443@end smallexample
9444
9445Now, we start @value{GDBN} on our sample program:
9446
9447@smallexample
9448$ gdb -nw sample
9449GNU gdb 2002-05-06-cvs
9450Copyright 2002 Free Software Foundation, Inc.
9451GDB is free software, @dots{}
f7dc1244 9452(@value{GDBP})
e2e0bcd1
JB
9453@end smallexample
9454
9455We can expand macros and examine their definitions, even when the
9456program is not running. @value{GDBN} uses the current listing position
9457to decide which macro definitions are in scope:
9458
9459@smallexample
f7dc1244 9460(@value{GDBP}) list main
e2e0bcd1
JB
94613
94624 #define M 42
94635 #define ADD(x) (M + x)
94646
94657 main ()
94668 @{
94679 #define N 28
946810 printf ("Hello, world!\n");
946911 #undef N
947012 printf ("We're so creative.\n");
f7dc1244 9471(@value{GDBP}) info macro ADD
e2e0bcd1
JB
9472Defined at /home/jimb/gdb/macros/play/sample.c:5
9473#define ADD(x) (M + x)
f7dc1244 9474(@value{GDBP}) info macro Q
e2e0bcd1
JB
9475Defined at /home/jimb/gdb/macros/play/sample.h:1
9476 included at /home/jimb/gdb/macros/play/sample.c:2
9477#define Q <
f7dc1244 9478(@value{GDBP}) macro expand ADD(1)
e2e0bcd1 9479expands to: (42 + 1)
f7dc1244 9480(@value{GDBP}) macro expand-once ADD(1)
e2e0bcd1 9481expands to: once (M + 1)
f7dc1244 9482(@value{GDBP})
e2e0bcd1
JB
9483@end smallexample
9484
d7d9f01e 9485In the example above, note that @code{macro expand-once} expands only
e2e0bcd1
JB
9486the macro invocation explicit in the original text --- the invocation of
9487@code{ADD} --- but does not expand the invocation of the macro @code{M},
9488which was introduced by @code{ADD}.
9489
3f94c067
BW
9490Once the program is running, @value{GDBN} uses the macro definitions in
9491force at the source line of the current stack frame:
e2e0bcd1
JB
9492
9493@smallexample
f7dc1244 9494(@value{GDBP}) break main
e2e0bcd1 9495Breakpoint 1 at 0x8048370: file sample.c, line 10.
f7dc1244 9496(@value{GDBP}) run
b383017d 9497Starting program: /home/jimb/gdb/macros/play/sample
e2e0bcd1
JB
9498
9499Breakpoint 1, main () at sample.c:10
950010 printf ("Hello, world!\n");
f7dc1244 9501(@value{GDBP})
e2e0bcd1
JB
9502@end smallexample
9503
9504At line 10, the definition of the macro @code{N} at line 9 is in force:
9505
9506@smallexample
f7dc1244 9507(@value{GDBP}) info macro N
e2e0bcd1
JB
9508Defined at /home/jimb/gdb/macros/play/sample.c:9
9509#define N 28
f7dc1244 9510(@value{GDBP}) macro expand N Q M
e2e0bcd1 9511expands to: 28 < 42
f7dc1244 9512(@value{GDBP}) print N Q M
e2e0bcd1 9513$1 = 1
f7dc1244 9514(@value{GDBP})
e2e0bcd1
JB
9515@end smallexample
9516
9517As we step over directives that remove @code{N}'s definition, and then
9518give it a new definition, @value{GDBN} finds the definition (or lack
9519thereof) in force at each point:
9520
9521@smallexample
f7dc1244 9522(@value{GDBP}) next
e2e0bcd1
JB
9523Hello, world!
952412 printf ("We're so creative.\n");
f7dc1244 9525(@value{GDBP}) info macro N
e2e0bcd1
JB
9526The symbol `N' has no definition as a C/C++ preprocessor macro
9527at /home/jimb/gdb/macros/play/sample.c:12
f7dc1244 9528(@value{GDBP}) next
e2e0bcd1
JB
9529We're so creative.
953014 printf ("Goodbye, world!\n");
f7dc1244 9531(@value{GDBP}) info macro N
e2e0bcd1
JB
9532Defined at /home/jimb/gdb/macros/play/sample.c:13
9533#define N 1729
f7dc1244 9534(@value{GDBP}) macro expand N Q M
e2e0bcd1 9535expands to: 1729 < 42
f7dc1244 9536(@value{GDBP}) print N Q M
e2e0bcd1 9537$2 = 0
f7dc1244 9538(@value{GDBP})
e2e0bcd1
JB
9539@end smallexample
9540
484086b7
JK
9541In addition to source files, macros can be defined on the compilation command
9542line using the @option{-D@var{name}=@var{value}} syntax. For macros defined in
9543such a way, @value{GDBN} displays the location of their definition as line zero
9544of the source file submitted to the compiler.
9545
9546@smallexample
9547(@value{GDBP}) info macro __STDC__
9548Defined at /home/jimb/gdb/macros/play/sample.c:0
9549-D__STDC__=1
9550(@value{GDBP})
9551@end smallexample
9552
e2e0bcd1 9553
b37052ae
EZ
9554@node Tracepoints
9555@chapter Tracepoints
9556@c This chapter is based on the documentation written by Michael
9557@c Snyder, David Taylor, Jim Blandy, and Elena Zannoni.
9558
9559@cindex tracepoints
9560In some applications, it is not feasible for the debugger to interrupt
9561the program's execution long enough for the developer to learn
9562anything helpful about its behavior. If the program's correctness
9563depends on its real-time behavior, delays introduced by a debugger
9564might cause the program to change its behavior drastically, or perhaps
9565fail, even when the code itself is correct. It is useful to be able
9566to observe the program's behavior without interrupting it.
9567
9568Using @value{GDBN}'s @code{trace} and @code{collect} commands, you can
9569specify locations in the program, called @dfn{tracepoints}, and
9570arbitrary expressions to evaluate when those tracepoints are reached.
9571Later, using the @code{tfind} command, you can examine the values
9572those expressions had when the program hit the tracepoints. The
9573expressions may also denote objects in memory---structures or arrays,
9574for example---whose values @value{GDBN} should record; while visiting
9575a particular tracepoint, you may inspect those objects as if they were
9576in memory at that moment. However, because @value{GDBN} records these
9577values without interacting with you, it can do so quickly and
9578unobtrusively, hopefully not disturbing the program's behavior.
9579
9580The tracepoint facility is currently available only for remote
9d29849a
JB
9581targets. @xref{Targets}. In addition, your remote target must know
9582how to collect trace data. This functionality is implemented in the
9583remote stub; however, none of the stubs distributed with @value{GDBN}
9584support tracepoints as of this writing. The format of the remote
9585packets used to implement tracepoints are described in @ref{Tracepoint
9586Packets}.
b37052ae 9587
00bf0b85
SS
9588It is also possible to get trace data from a file, in a manner reminiscent
9589of corefiles; you specify the filename, and use @code{tfind} to search
9590through the file. @xref{Trace Files}, for more details.
9591
b37052ae
EZ
9592This chapter describes the tracepoint commands and features.
9593
9594@menu
b383017d
RM
9595* Set Tracepoints::
9596* Analyze Collected Data::
9597* Tracepoint Variables::
00bf0b85 9598* Trace Files::
b37052ae
EZ
9599@end menu
9600
9601@node Set Tracepoints
9602@section Commands to Set Tracepoints
9603
9604Before running such a @dfn{trace experiment}, an arbitrary number of
1042e4c0
SS
9605tracepoints can be set. A tracepoint is actually a special type of
9606breakpoint (@pxref{Set Breaks}), so you can manipulate it using
9607standard breakpoint commands. For instance, as with breakpoints,
9608tracepoint numbers are successive integers starting from one, and many
9609of the commands associated with tracepoints take the tracepoint number
9610as their argument, to identify which tracepoint to work on.
b37052ae
EZ
9611
9612For each tracepoint, you can specify, in advance, some arbitrary set
9613of data that you want the target to collect in the trace buffer when
9614it hits that tracepoint. The collected data can include registers,
9615local variables, or global data. Later, you can use @value{GDBN}
9616commands to examine the values these data had at the time the
9617tracepoint was hit.
9618
7d13fe92
SS
9619Tracepoints do not support every breakpoint feature. Ignore counts on
9620tracepoints have no effect, and tracepoints cannot run @value{GDBN}
9621commands when they are hit. Tracepoints may not be thread-specific
9622either.
1042e4c0 9623
7a697b8d
SS
9624@cindex fast tracepoints
9625Some targets may support @dfn{fast tracepoints}, which are inserted in
9626a different way (such as with a jump instead of a trap), that is
9627faster but possibly restricted in where they may be installed.
9628
0fb4aa4b
PA
9629@cindex static tracepoints
9630@cindex markers, static tracepoints
9631@cindex probing markers, static tracepoints
9632Regular and fast tracepoints are dynamic tracing facilities, meaning
9633that they can be used to insert tracepoints at (almost) any location
9634in the target. Some targets may also support controlling @dfn{static
9635tracepoints} from @value{GDBN}. With static tracing, a set of
9636instrumentation points, also known as @dfn{markers}, are embedded in
9637the target program, and can be activated or deactivated by name or
9638address. These are usually placed at locations which facilitate
9639investigating what the target is actually doing. @value{GDBN}'s
9640support for static tracing includes being able to list instrumentation
9641points, and attach them with @value{GDBN} defined high level
9642tracepoints that expose the whole range of convenience of
9643@value{GDBN}'s tracepoints support. Namelly, support for collecting
9644registers values and values of global or local (to the instrumentation
9645point) variables; tracepoint conditions and trace state variables.
9646The act of installing a @value{GDBN} static tracepoint on an
9647instrumentation point, or marker, is referred to as @dfn{probing} a
9648static tracepoint marker.
9649
fa593d66
PA
9650@code{gdbserver} supports tracepoints on some target systems.
9651@xref{Server,,Tracepoints support in @code{gdbserver}}.
9652
b37052ae
EZ
9653This section describes commands to set tracepoints and associated
9654conditions and actions.
9655
9656@menu
b383017d
RM
9657* Create and Delete Tracepoints::
9658* Enable and Disable Tracepoints::
9659* Tracepoint Passcounts::
782b2b07 9660* Tracepoint Conditions::
f61e138d 9661* Trace State Variables::
b383017d
RM
9662* Tracepoint Actions::
9663* Listing Tracepoints::
0fb4aa4b 9664* Listing Static Tracepoint Markers::
79a6e687 9665* Starting and Stopping Trace Experiments::
c9429232 9666* Tracepoint Restrictions::
b37052ae
EZ
9667@end menu
9668
9669@node Create and Delete Tracepoints
9670@subsection Create and Delete Tracepoints
9671
9672@table @code
9673@cindex set tracepoint
9674@kindex trace
1042e4c0 9675@item trace @var{location}
b37052ae 9676The @code{trace} command is very similar to the @code{break} command.
1042e4c0
SS
9677Its argument @var{location} can be a source line, a function name, or
9678an address in the target program. @xref{Specify Location}. The
9679@code{trace} command defines a tracepoint, which is a point in the
9680target program where the debugger will briefly stop, collect some
9681data, and then allow the program to continue. Setting a tracepoint or
9682changing its actions doesn't take effect until the next @code{tstart}
9683command, and once a trace experiment is running, further changes will
9684not have any effect until the next trace experiment starts.
b37052ae
EZ
9685
9686Here are some examples of using the @code{trace} command:
9687
9688@smallexample
9689(@value{GDBP}) @b{trace foo.c:121} // a source file and line number
9690
9691(@value{GDBP}) @b{trace +2} // 2 lines forward
9692
9693(@value{GDBP}) @b{trace my_function} // first source line of function
9694
9695(@value{GDBP}) @b{trace *my_function} // EXACT start address of function
9696
9697(@value{GDBP}) @b{trace *0x2117c4} // an address
9698@end smallexample
9699
9700@noindent
9701You can abbreviate @code{trace} as @code{tr}.
9702
782b2b07
SS
9703@item trace @var{location} if @var{cond}
9704Set a tracepoint with condition @var{cond}; evaluate the expression
9705@var{cond} each time the tracepoint is reached, and collect data only
9706if the value is nonzero---that is, if @var{cond} evaluates as true.
9707@xref{Tracepoint Conditions, ,Tracepoint Conditions}, for more
9708information on tracepoint conditions.
9709
7a697b8d
SS
9710@item ftrace @var{location} [ if @var{cond} ]
9711@cindex set fast tracepoint
74c761c1 9712@cindex fast tracepoints, setting
7a697b8d
SS
9713@kindex ftrace
9714The @code{ftrace} command sets a fast tracepoint. For targets that
9715support them, fast tracepoints will use a more efficient but possibly
9716less general technique to trigger data collection, such as a jump
9717instruction instead of a trap, or some sort of hardware support. It
9718may not be possible to create a fast tracepoint at the desired
9719location, in which case the command will exit with an explanatory
9720message.
9721
9722@value{GDBN} handles arguments to @code{ftrace} exactly as for
9723@code{trace}.
9724
0fb4aa4b 9725@item strace @var{location} [ if @var{cond} ]
74c761c1
PA
9726@cindex set static tracepoint
9727@cindex static tracepoints, setting
9728@cindex probe static tracepoint marker
0fb4aa4b
PA
9729@kindex strace
9730The @code{strace} command sets a static tracepoint. For targets that
9731support it, setting a static tracepoint probes a static
9732instrumentation point, or marker, found at @var{location}. It may not
9733be possible to set a static tracepoint at the desired location, in
9734which case the command will exit with an explanatory message.
9735
9736@value{GDBN} handles arguments to @code{strace} exactly as for
9737@code{trace}, with the addition that the user can also specify
9738@code{-m @var{marker}} as @var{location}. This probes the marker
9739identified by the @var{marker} string identifier. This identifier
9740depends on the static tracepoint backend library your program is
9741using. You can find all the marker identifiers in the @samp{ID} field
9742of the @code{info static-tracepoint-markers} command output.
9743@xref{Listing Static Tracepoint Markers,,Listing Static Tracepoint
9744Markers}. For example, in the following small program using the UST
9745tracing engine:
9746
9747@smallexample
9748main ()
9749@{
9750 trace_mark(ust, bar33, "str %s", "FOOBAZ");
9751@}
9752@end smallexample
9753
9754@noindent
9755the marker id is composed of joining the first two arguments to the
9756@code{trace_mark} call with a slash, which translates to:
9757
9758@smallexample
9759(@value{GDBP}) info static-tracepoint-markers
9760Cnt Enb ID Address What
97611 n ust/bar33 0x0000000000400ddc in main at stexample.c:22
9762 Data: "str %s"
9763[etc...]
9764@end smallexample
9765
9766@noindent
9767so you may probe the marker above with:
9768
9769@smallexample
9770(@value{GDBP}) strace -m ust/bar33
9771@end smallexample
9772
9773Static tracepoints accept an extra collect action --- @code{collect
9774$_sdata}. This collects arbitrary user data passed in the probe point
9775call to the tracing library. In the UST example above, you'll see
9776that the third argument to @code{trace_mark} is a printf-like format
9777string. The user data is then the result of running that formating
9778string against the following arguments. Note that @code{info
9779static-tracepoint-markers} command output lists that format string in
9780the @samp{Data:} field.
9781
9782You can inspect this data when analyzing the trace buffer, by printing
9783the $_sdata variable like any other variable available to
9784@value{GDBN}. @xref{Tracepoint Actions,,Tracepoint Action Lists}.
9785
b37052ae
EZ
9786@vindex $tpnum
9787@cindex last tracepoint number
9788@cindex recent tracepoint number
9789@cindex tracepoint number
9790The convenience variable @code{$tpnum} records the tracepoint number
9791of the most recently set tracepoint.
9792
9793@kindex delete tracepoint
9794@cindex tracepoint deletion
9795@item delete tracepoint @r{[}@var{num}@r{]}
9796Permanently delete one or more tracepoints. With no argument, the
1042e4c0
SS
9797default is to delete all tracepoints. Note that the regular
9798@code{delete} command can remove tracepoints also.
b37052ae
EZ
9799
9800Examples:
9801
9802@smallexample
9803(@value{GDBP}) @b{delete trace 1 2 3} // remove three tracepoints
9804
9805(@value{GDBP}) @b{delete trace} // remove all tracepoints
9806@end smallexample
9807
9808@noindent
9809You can abbreviate this command as @code{del tr}.
9810@end table
9811
9812@node Enable and Disable Tracepoints
9813@subsection Enable and Disable Tracepoints
9814
1042e4c0
SS
9815These commands are deprecated; they are equivalent to plain @code{disable} and @code{enable}.
9816
b37052ae
EZ
9817@table @code
9818@kindex disable tracepoint
9819@item disable tracepoint @r{[}@var{num}@r{]}
9820Disable tracepoint @var{num}, or all tracepoints if no argument
9821@var{num} is given. A disabled tracepoint will have no effect during
9822the next trace experiment, but it is not forgotten. You can re-enable
9823a disabled tracepoint using the @code{enable tracepoint} command.
9824
9825@kindex enable tracepoint
9826@item enable tracepoint @r{[}@var{num}@r{]}
9827Enable tracepoint @var{num}, or all tracepoints. The enabled
9828tracepoints will become effective the next time a trace experiment is
9829run.
9830@end table
9831
9832@node Tracepoint Passcounts
9833@subsection Tracepoint Passcounts
9834
9835@table @code
9836@kindex passcount
9837@cindex tracepoint pass count
9838@item passcount @r{[}@var{n} @r{[}@var{num}@r{]]}
9839Set the @dfn{passcount} of a tracepoint. The passcount is a way to
9840automatically stop a trace experiment. If a tracepoint's passcount is
9841@var{n}, then the trace experiment will be automatically stopped on
9842the @var{n}'th time that tracepoint is hit. If the tracepoint number
9843@var{num} is not specified, the @code{passcount} command sets the
9844passcount of the most recently defined tracepoint. If no passcount is
9845given, the trace experiment will run until stopped explicitly by the
9846user.
9847
9848Examples:
9849
9850@smallexample
b383017d 9851(@value{GDBP}) @b{passcount 5 2} // Stop on the 5th execution of
6826cf00 9852@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// tracepoint 2}
b37052ae
EZ
9853
9854(@value{GDBP}) @b{passcount 12} // Stop on the 12th execution of the
6826cf00 9855@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// most recently defined tracepoint.}
b37052ae
EZ
9856(@value{GDBP}) @b{trace foo}
9857(@value{GDBP}) @b{pass 3}
9858(@value{GDBP}) @b{trace bar}
9859(@value{GDBP}) @b{pass 2}
9860(@value{GDBP}) @b{trace baz}
9861(@value{GDBP}) @b{pass 1} // Stop tracing when foo has been
6826cf00
EZ
9862@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// executed 3 times OR when bar has}
9863@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// been executed 2 times}
9864@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// OR when baz has been executed 1 time.}
b37052ae
EZ
9865@end smallexample
9866@end table
9867
782b2b07
SS
9868@node Tracepoint Conditions
9869@subsection Tracepoint Conditions
9870@cindex conditional tracepoints
9871@cindex tracepoint conditions
9872
9873The simplest sort of tracepoint collects data every time your program
9874reaches a specified place. You can also specify a @dfn{condition} for
9875a tracepoint. A condition is just a Boolean expression in your
9876programming language (@pxref{Expressions, ,Expressions}). A
9877tracepoint with a condition evaluates the expression each time your
9878program reaches it, and data collection happens only if the condition
9879is true.
9880
9881Tracepoint conditions can be specified when a tracepoint is set, by
9882using @samp{if} in the arguments to the @code{trace} command.
9883@xref{Create and Delete Tracepoints, ,Setting Tracepoints}. They can
9884also be set or changed at any time with the @code{condition} command,
9885just as with breakpoints.
9886
9887Unlike breakpoint conditions, @value{GDBN} does not actually evaluate
9888the conditional expression itself. Instead, @value{GDBN} encodes the
9889expression into an agent expression (@pxref{Agent Expressions}
9890suitable for execution on the target, independently of @value{GDBN}.
9891Global variables become raw memory locations, locals become stack
9892accesses, and so forth.
9893
9894For instance, suppose you have a function that is usually called
9895frequently, but should not be called after an error has occurred. You
9896could use the following tracepoint command to collect data about calls
9897of that function that happen while the error code is propagating
9898through the program; an unconditional tracepoint could end up
9899collecting thousands of useless trace frames that you would have to
9900search through.
9901
9902@smallexample
9903(@value{GDBP}) @kbd{trace normal_operation if errcode > 0}
9904@end smallexample
9905
f61e138d
SS
9906@node Trace State Variables
9907@subsection Trace State Variables
9908@cindex trace state variables
9909
9910A @dfn{trace state variable} is a special type of variable that is
9911created and managed by target-side code. The syntax is the same as
9912that for GDB's convenience variables (a string prefixed with ``$''),
9913but they are stored on the target. They must be created explicitly,
9914using a @code{tvariable} command. They are always 64-bit signed
9915integers.
9916
9917Trace state variables are remembered by @value{GDBN}, and downloaded
9918to the target along with tracepoint information when the trace
9919experiment starts. There are no intrinsic limits on the number of
9920trace state variables, beyond memory limitations of the target.
9921
9922@cindex convenience variables, and trace state variables
9923Although trace state variables are managed by the target, you can use
9924them in print commands and expressions as if they were convenience
9925variables; @value{GDBN} will get the current value from the target
9926while the trace experiment is running. Trace state variables share
9927the same namespace as other ``$'' variables, which means that you
9928cannot have trace state variables with names like @code{$23} or
9929@code{$pc}, nor can you have a trace state variable and a convenience
9930variable with the same name.
9931
9932@table @code
9933
9934@item tvariable $@var{name} [ = @var{expression} ]
9935@kindex tvariable
9936The @code{tvariable} command creates a new trace state variable named
9937@code{$@var{name}}, and optionally gives it an initial value of
9938@var{expression}. @var{expression} is evaluated when this command is
9939entered; the result will be converted to an integer if possible,
9940otherwise @value{GDBN} will report an error. A subsequent
9941@code{tvariable} command specifying the same name does not create a
9942variable, but instead assigns the supplied initial value to the
9943existing variable of that name, overwriting any previous initial
9944value. The default initial value is 0.
9945
9946@item info tvariables
9947@kindex info tvariables
9948List all the trace state variables along with their initial values.
9949Their current values may also be displayed, if the trace experiment is
9950currently running.
9951
9952@item delete tvariable @r{[} $@var{name} @dots{} @r{]}
9953@kindex delete tvariable
9954Delete the given trace state variables, or all of them if no arguments
9955are specified.
9956
9957@end table
9958
b37052ae
EZ
9959@node Tracepoint Actions
9960@subsection Tracepoint Action Lists
9961
9962@table @code
9963@kindex actions
9964@cindex tracepoint actions
9965@item actions @r{[}@var{num}@r{]}
9966This command will prompt for a list of actions to be taken when the
9967tracepoint is hit. If the tracepoint number @var{num} is not
9968specified, this command sets the actions for the one that was most
9969recently defined (so that you can define a tracepoint and then say
9970@code{actions} without bothering about its number). You specify the
9971actions themselves on the following lines, one action at a time, and
9972terminate the actions list with a line containing just @code{end}. So
7d13fe92 9973far, the only defined actions are @code{collect}, @code{teval}, and
b37052ae
EZ
9974@code{while-stepping}.
9975
5a9351ae
SS
9976@code{actions} is actually equivalent to @code{commands} (@pxref{Break
9977Commands, ,Breakpoint Command Lists}), except that only the defined
9978actions are allowed; any other @value{GDBN} command is rejected.
9979
b37052ae
EZ
9980@cindex remove actions from a tracepoint
9981To remove all actions from a tracepoint, type @samp{actions @var{num}}
9982and follow it immediately with @samp{end}.
9983
9984@smallexample
9985(@value{GDBP}) @b{collect @var{data}} // collect some data
9986
6826cf00 9987(@value{GDBP}) @b{while-stepping 5} // single-step 5 times, collect data
b37052ae 9988
6826cf00 9989(@value{GDBP}) @b{end} // signals the end of actions.
b37052ae
EZ
9990@end smallexample
9991
9992In the following example, the action list begins with @code{collect}
9993commands indicating the things to be collected when the tracepoint is
9994hit. Then, in order to single-step and collect additional data
9995following the tracepoint, a @code{while-stepping} command is used,
7d13fe92
SS
9996followed by the list of things to be collected after each step in a
9997sequence of single steps. The @code{while-stepping} command is
9998terminated by its own separate @code{end} command. Lastly, the action
9999list is terminated by an @code{end} command.
b37052ae
EZ
10000
10001@smallexample
10002(@value{GDBP}) @b{trace foo}
10003(@value{GDBP}) @b{actions}
10004Enter actions for tracepoint 1, one per line:
10005> collect bar,baz
10006> collect $regs
10007> while-stepping 12
5a9351ae 10008 > collect $pc, arr[i]
b37052ae
EZ
10009 > end
10010end
10011@end smallexample
10012
10013@kindex collect @r{(tracepoints)}
10014@item collect @var{expr1}, @var{expr2}, @dots{}
10015Collect values of the given expressions when the tracepoint is hit.
10016This command accepts a comma-separated list of any valid expressions.
10017In addition to global, static, or local variables, the following
10018special arguments are supported:
10019
10020@table @code
10021@item $regs
0fb4aa4b 10022Collect all registers.
b37052ae
EZ
10023
10024@item $args
0fb4aa4b 10025Collect all function arguments.
b37052ae
EZ
10026
10027@item $locals
0fb4aa4b
PA
10028Collect all local variables.
10029
10030@item $_sdata
10031@vindex $_sdata@r{, collect}
10032Collect static tracepoint marker specific data. Only available for
10033static tracepoints. @xref{Tracepoint Actions,,Tracepoint Action
10034Lists}. On the UST static tracepoints library backend, an
10035instrumentation point resembles a @code{printf} function call. The
10036tracing library is able to collect user specified data formatted to a
10037character string using the format provided by the programmer that
10038instrumented the program. Other backends have similar mechanisms.
10039Here's an example of a UST marker call:
10040
10041@smallexample
10042 const char master_name[] = "$your_name";
10043 trace_mark(channel1, marker1, "hello %s", master_name)
10044@end smallexample
10045
10046In this case, collecting @code{$_sdata} collects the string
10047@samp{hello $yourname}. When analyzing the trace buffer, you can
10048inspect @samp{$_sdata} like any other variable available to
10049@value{GDBN}.
b37052ae
EZ
10050@end table
10051
10052You can give several consecutive @code{collect} commands, each one
10053with a single argument, or one @code{collect} command with several
5a9351ae 10054arguments separated by commas; the effect is the same.
b37052ae 10055
f5c37c66
EZ
10056The command @code{info scope} (@pxref{Symbols, info scope}) is
10057particularly useful for figuring out what data to collect.
10058
6da95a67
SS
10059@kindex teval @r{(tracepoints)}
10060@item teval @var{expr1}, @var{expr2}, @dots{}
10061Evaluate the given expressions when the tracepoint is hit. This
10062command accepts a comma-separated list of expressions. The results
10063are discarded, so this is mainly useful for assigning values to trace
10064state variables (@pxref{Trace State Variables}) without adding those
10065values to the trace buffer, as would be the case if the @code{collect}
10066action were used.
10067
b37052ae
EZ
10068@kindex while-stepping @r{(tracepoints)}
10069@item while-stepping @var{n}
c9429232 10070Perform @var{n} single-step instruction traces after the tracepoint,
7d13fe92 10071collecting new data after each step. The @code{while-stepping}
c9429232
SS
10072command is followed by the list of what to collect while stepping
10073(followed by its own @code{end} command):
b37052ae
EZ
10074
10075@smallexample
10076> while-stepping 12
10077 > collect $regs, myglobal
10078 > end
10079>
10080@end smallexample
10081
10082@noindent
7d13fe92
SS
10083Note that @code{$pc} is not automatically collected by
10084@code{while-stepping}; you need to explicitly collect that register if
10085you need it. You may abbreviate @code{while-stepping} as @code{ws} or
b37052ae 10086@code{stepping}.
236f1d4d
SS
10087
10088@item set default-collect @var{expr1}, @var{expr2}, @dots{}
10089@kindex set default-collect
10090@cindex default collection action
10091This variable is a list of expressions to collect at each tracepoint
10092hit. It is effectively an additional @code{collect} action prepended
10093to every tracepoint action list. The expressions are parsed
10094individually for each tracepoint, so for instance a variable named
10095@code{xyz} may be interpreted as a global for one tracepoint, and a
10096local for another, as appropriate to the tracepoint's location.
10097
10098@item show default-collect
10099@kindex show default-collect
10100Show the list of expressions that are collected by default at each
10101tracepoint hit.
10102
b37052ae
EZ
10103@end table
10104
10105@node Listing Tracepoints
10106@subsection Listing Tracepoints
10107
10108@table @code
10109@kindex info tracepoints
09d4efe1 10110@kindex info tp
b37052ae
EZ
10111@cindex information about tracepoints
10112@item info tracepoints @r{[}@var{num}@r{]}
1042e4c0
SS
10113Display information about the tracepoint @var{num}. If you don't
10114specify a tracepoint number, displays information about all the
10115tracepoints defined so far. The format is similar to that used for
10116@code{info breakpoints}; in fact, @code{info tracepoints} is the same
10117command, simply restricting itself to tracepoints.
10118
10119A tracepoint's listing may include additional information specific to
10120tracing:
b37052ae
EZ
10121
10122@itemize @bullet
10123@item
b37052ae 10124its passcount as given by the @code{passcount @var{n}} command
b37052ae
EZ
10125@end itemize
10126
10127@smallexample
10128(@value{GDBP}) @b{info trace}
1042e4c0
SS
10129Num Type Disp Enb Address What
101301 tracepoint keep y 0x0804ab57 in foo() at main.cxx:7
5a9351ae
SS
10131 while-stepping 20
10132 collect globfoo, $regs
10133 end
10134 collect globfoo2
10135 end
1042e4c0 10136 pass count 1200
b37052ae
EZ
10137(@value{GDBP})
10138@end smallexample
10139
10140@noindent
10141This command can be abbreviated @code{info tp}.
10142@end table
10143
0fb4aa4b
PA
10144@node Listing Static Tracepoint Markers
10145@subsection Listing Static Tracepoint Markers
10146
10147@table @code
10148@kindex info static-tracepoint-markers
10149@cindex information about static tracepoint markers
10150@item info static-tracepoint-markers
10151Display information about all static tracepoint markers defined in the
10152program.
10153
10154For each marker, the following columns are printed:
10155
10156@table @emph
10157@item Count
10158An incrementing counter, output to help readability. This is not a
10159stable identifier.
10160@item ID
10161The marker ID, as reported by the target.
10162@item Enabled or Disabled
10163Probed markers are tagged with @samp{y}. @samp{n} identifies marks
10164that are not enabled.
10165@item Address
10166Where the marker is in your program, as a memory address.
10167@item What
10168Where the marker is in the source for your program, as a file and line
10169number. If the debug information included in the program does not
10170allow @value{GDBN} to locate the source of the marker, this column
10171will be left blank.
10172@end table
10173
10174@noindent
10175In addition, the following information may be printed for each marker:
10176
10177@table @emph
10178@item Data
10179User data passed to the tracing library by the marker call. In the
10180UST backend, this is the format string passed as argument to the
10181marker call.
10182@item Static tracepoints probing the marker
10183The list of static tracepoints attached to the marker.
10184@end table
10185
10186@smallexample
10187(@value{GDBP}) info static-tracepoint-markers
10188Cnt ID Enb Address What
101891 ust/bar2 y 0x0000000000400e1a in main at stexample.c:25
10190 Data: number1 %d number2 %d
10191 Probed by static tracepoints: #2
101922 ust/bar33 n 0x0000000000400c87 in main at stexample.c:24
10193 Data: str %s
10194(@value{GDBP})
10195@end smallexample
10196@end table
10197
79a6e687
BW
10198@node Starting and Stopping Trace Experiments
10199@subsection Starting and Stopping Trace Experiments
b37052ae
EZ
10200
10201@table @code
10202@kindex tstart
10203@cindex start a new trace experiment
10204@cindex collected data discarded
10205@item tstart
10206This command takes no arguments. It starts the trace experiment, and
10207begins collecting data. This has the side effect of discarding all
10208the data collected in the trace buffer during the previous trace
10209experiment.
10210
10211@kindex tstop
10212@cindex stop a running trace experiment
10213@item tstop
10214This command takes no arguments. It ends the trace experiment, and
10215stops collecting data.
10216
68c71a2e 10217@strong{Note}: a trace experiment and data collection may stop
b37052ae
EZ
10218automatically if any tracepoint's passcount is reached
10219(@pxref{Tracepoint Passcounts}), or if the trace buffer becomes full.
10220
10221@kindex tstatus
10222@cindex status of trace data collection
10223@cindex trace experiment, status of
10224@item tstatus
10225This command displays the status of the current trace data
10226collection.
10227@end table
10228
10229Here is an example of the commands we described so far:
10230
10231@smallexample
10232(@value{GDBP}) @b{trace gdb_c_test}
10233(@value{GDBP}) @b{actions}
10234Enter actions for tracepoint #1, one per line.
10235> collect $regs,$locals,$args
10236> while-stepping 11
10237 > collect $regs
10238 > end
10239> end
10240(@value{GDBP}) @b{tstart}
10241 [time passes @dots{}]
10242(@value{GDBP}) @b{tstop}
10243@end smallexample
10244
d5551862
SS
10245@cindex disconnected tracing
10246You can choose to continue running the trace experiment even if
10247@value{GDBN} disconnects from the target, voluntarily or
10248involuntarily. For commands such as @code{detach}, the debugger will
10249ask what you want to do with the trace. But for unexpected
10250terminations (@value{GDBN} crash, network outage), it would be
10251unfortunate to lose hard-won trace data, so the variable
10252@code{disconnected-tracing} lets you decide whether the trace should
10253continue running without @value{GDBN}.
10254
10255@table @code
10256@item set disconnected-tracing on
10257@itemx set disconnected-tracing off
10258@kindex set disconnected-tracing
10259Choose whether a tracing run should continue to run if @value{GDBN}
10260has disconnected from the target. Note that @code{detach} or
10261@code{quit} will ask you directly what to do about a running trace no
10262matter what this variable's setting, so the variable is mainly useful
10263for handling unexpected situations, such as loss of the network.
10264
10265@item show disconnected-tracing
10266@kindex show disconnected-tracing
10267Show the current choice for disconnected tracing.
10268
10269@end table
10270
10271When you reconnect to the target, the trace experiment may or may not
10272still be running; it might have filled the trace buffer in the
10273meantime, or stopped for one of the other reasons. If it is running,
10274it will continue after reconnection.
10275
10276Upon reconnection, the target will upload information about the
10277tracepoints in effect. @value{GDBN} will then compare that
10278information to the set of tracepoints currently defined, and attempt
10279to match them up, allowing for the possibility that the numbers may
10280have changed due to creation and deletion in the meantime. If one of
10281the target's tracepoints does not match any in @value{GDBN}, the
10282debugger will create a new tracepoint, so that you have a number with
10283which to specify that tracepoint. This matching-up process is
10284necessarily heuristic, and it may result in useless tracepoints being
10285created; you may simply delete them if they are of no use.
b37052ae 10286
4daf5ac0
SS
10287@cindex circular trace buffer
10288If your target agent supports a @dfn{circular trace buffer}, then you
10289can run a trace experiment indefinitely without filling the trace
10290buffer; when space runs out, the agent deletes already-collected trace
10291frames, oldest first, until there is enough room to continue
10292collecting. This is especially useful if your tracepoints are being
10293hit too often, and your trace gets terminated prematurely because the
10294buffer is full. To ask for a circular trace buffer, simply set
10295@samp{circular_trace_buffer} to on. You can set this at any time,
10296including during tracing; if the agent can do it, it will change
10297buffer handling on the fly, otherwise it will not take effect until
10298the next run.
10299
10300@table @code
10301@item set circular-trace-buffer on
10302@itemx set circular-trace-buffer off
10303@kindex set circular-trace-buffer
10304Choose whether a tracing run should use a linear or circular buffer
10305for trace data. A linear buffer will not lose any trace data, but may
10306fill up prematurely, while a circular buffer will discard old trace
10307data, but it will have always room for the latest tracepoint hits.
10308
10309@item show circular-trace-buffer
10310@kindex show circular-trace-buffer
10311Show the current choice for the trace buffer. Note that this may not
10312match the agent's current buffer handling, nor is it guaranteed to
10313match the setting that might have been in effect during a past run,
10314for instance if you are looking at frames from a trace file.
10315
10316@end table
10317
c9429232
SS
10318@node Tracepoint Restrictions
10319@subsection Tracepoint Restrictions
10320
10321@cindex tracepoint restrictions
10322There are a number of restrictions on the use of tracepoints. As
10323described above, tracepoint data gathering occurs on the target
10324without interaction from @value{GDBN}. Thus the full capabilities of
10325the debugger are not available during data gathering, and then at data
10326examination time, you will be limited by only having what was
10327collected. The following items describe some common problems, but it
10328is not exhaustive, and you may run into additional difficulties not
10329mentioned here.
10330
10331@itemize @bullet
10332
10333@item
10334Tracepoint expressions are intended to gather objects (lvalues). Thus
10335the full flexibility of GDB's expression evaluator is not available.
10336You cannot call functions, cast objects to aggregate types, access
10337convenience variables or modify values (except by assignment to trace
10338state variables). Some language features may implicitly call
10339functions (for instance Objective-C fields with accessors), and therefore
10340cannot be collected either.
10341
10342@item
10343Collection of local variables, either individually or in bulk with
10344@code{$locals} or @code{$args}, during @code{while-stepping} may
10345behave erratically. The stepping action may enter a new scope (for
10346instance by stepping into a function), or the location of the variable
10347may change (for instance it is loaded into a register). The
10348tracepoint data recorded uses the location information for the
10349variables that is correct for the tracepoint location. When the
10350tracepoint is created, it is not possible, in general, to determine
10351where the steps of a @code{while-stepping} sequence will advance the
10352program---particularly if a conditional branch is stepped.
10353
10354@item
10355Collection of an incompletely-initialized or partially-destroyed object
10356may result in something that @value{GDBN} cannot display, or displays
10357in a misleading way.
10358
10359@item
10360When @value{GDBN} displays a pointer to character it automatically
10361dereferences the pointer to also display characters of the string
10362being pointed to. However, collecting the pointer during tracing does
10363not automatically collect the string. You need to explicitly
10364dereference the pointer and provide size information if you want to
10365collect not only the pointer, but the memory pointed to. For example,
10366@code{*ptr@@50} can be used to collect the 50 element array pointed to
10367by @code{ptr}.
10368
10369@item
10370It is not possible to collect a complete stack backtrace at a
10371tracepoint. Instead, you may collect the registers and a few hundred
10372bytes from the stack pointer with something like @code{*$esp@@300}
10373(adjust to use the name of the actual stack pointer register on your
10374target architecture, and the amount of stack you wish to capture).
10375Then the @code{backtrace} command will show a partial backtrace when
10376using a trace frame. The number of stack frames that can be examined
10377depends on the sizes of the frames in the collected stack. Note that
10378if you ask for a block so large that it goes past the bottom of the
10379stack, the target agent may report an error trying to read from an
10380invalid address.
10381
af54718e
SS
10382@item
10383If you do not collect registers at a tracepoint, @value{GDBN} can
10384infer that the value of @code{$pc} must be the same as the address of
10385the tracepoint and use that when you are looking at a trace frame
10386for that tracepoint. However, this cannot work if the tracepoint has
10387multiple locations (for instance if it was set in a function that was
10388inlined), or if it has a @code{while-stepping} loop. In those cases
10389@value{GDBN} will warn you that it can't infer @code{$pc}, and default
10390it to zero.
10391
c9429232
SS
10392@end itemize
10393
b37052ae 10394@node Analyze Collected Data
79a6e687 10395@section Using the Collected Data
b37052ae
EZ
10396
10397After the tracepoint experiment ends, you use @value{GDBN} commands
10398for examining the trace data. The basic idea is that each tracepoint
10399collects a trace @dfn{snapshot} every time it is hit and another
10400snapshot every time it single-steps. All these snapshots are
10401consecutively numbered from zero and go into a buffer, and you can
10402examine them later. The way you examine them is to @dfn{focus} on a
10403specific trace snapshot. When the remote stub is focused on a trace
10404snapshot, it will respond to all @value{GDBN} requests for memory and
10405registers by reading from the buffer which belongs to that snapshot,
10406rather than from @emph{real} memory or registers of the program being
10407debugged. This means that @strong{all} @value{GDBN} commands
10408(@code{print}, @code{info registers}, @code{backtrace}, etc.) will
10409behave as if we were currently debugging the program state as it was
10410when the tracepoint occurred. Any requests for data that are not in
10411the buffer will fail.
10412
10413@menu
10414* tfind:: How to select a trace snapshot
10415* tdump:: How to display all data for a snapshot
6149aea9 10416* save tracepoints:: How to save tracepoints for a future run
b37052ae
EZ
10417@end menu
10418
10419@node tfind
10420@subsection @code{tfind @var{n}}
10421
10422@kindex tfind
10423@cindex select trace snapshot
10424@cindex find trace snapshot
10425The basic command for selecting a trace snapshot from the buffer is
10426@code{tfind @var{n}}, which finds trace snapshot number @var{n},
10427counting from zero. If no argument @var{n} is given, the next
10428snapshot is selected.
10429
10430Here are the various forms of using the @code{tfind} command.
10431
10432@table @code
10433@item tfind start
10434Find the first snapshot in the buffer. This is a synonym for
10435@code{tfind 0} (since 0 is the number of the first snapshot).
10436
10437@item tfind none
10438Stop debugging trace snapshots, resume @emph{live} debugging.
10439
10440@item tfind end
10441Same as @samp{tfind none}.
10442
10443@item tfind
10444No argument means find the next trace snapshot.
10445
10446@item tfind -
10447Find the previous trace snapshot before the current one. This permits
10448retracing earlier steps.
10449
10450@item tfind tracepoint @var{num}
10451Find the next snapshot associated with tracepoint @var{num}. Search
10452proceeds forward from the last examined trace snapshot. If no
10453argument @var{num} is given, it means find the next snapshot collected
10454for the same tracepoint as the current snapshot.
10455
10456@item tfind pc @var{addr}
10457Find the next snapshot associated with the value @var{addr} of the
10458program counter. Search proceeds forward from the last examined trace
10459snapshot. If no argument @var{addr} is given, it means find the next
10460snapshot with the same value of PC as the current snapshot.
10461
10462@item tfind outside @var{addr1}, @var{addr2}
10463Find the next snapshot whose PC is outside the given range of
081dfbf7 10464addresses (exclusive).
b37052ae
EZ
10465
10466@item tfind range @var{addr1}, @var{addr2}
10467Find the next snapshot whose PC is between @var{addr1} and
081dfbf7 10468@var{addr2} (inclusive).
b37052ae
EZ
10469
10470@item tfind line @r{[}@var{file}:@r{]}@var{n}
10471Find the next snapshot associated with the source line @var{n}. If
10472the optional argument @var{file} is given, refer to line @var{n} in
10473that source file. Search proceeds forward from the last examined
10474trace snapshot. If no argument @var{n} is given, it means find the
10475next line other than the one currently being examined; thus saying
10476@code{tfind line} repeatedly can appear to have the same effect as
10477stepping from line to line in a @emph{live} debugging session.
10478@end table
10479
10480The default arguments for the @code{tfind} commands are specifically
10481designed to make it easy to scan through the trace buffer. For
10482instance, @code{tfind} with no argument selects the next trace
10483snapshot, and @code{tfind -} with no argument selects the previous
10484trace snapshot. So, by giving one @code{tfind} command, and then
10485simply hitting @key{RET} repeatedly you can examine all the trace
10486snapshots in order. Or, by saying @code{tfind -} and then hitting
10487@key{RET} repeatedly you can examine the snapshots in reverse order.
10488The @code{tfind line} command with no argument selects the snapshot
10489for the next source line executed. The @code{tfind pc} command with
10490no argument selects the next snapshot with the same program counter
10491(PC) as the current frame. The @code{tfind tracepoint} command with
10492no argument selects the next trace snapshot collected by the same
10493tracepoint as the current one.
10494
10495In addition to letting you scan through the trace buffer manually,
10496these commands make it easy to construct @value{GDBN} scripts that
10497scan through the trace buffer and print out whatever collected data
10498you are interested in. Thus, if we want to examine the PC, FP, and SP
10499registers from each trace frame in the buffer, we can say this:
10500
10501@smallexample
10502(@value{GDBP}) @b{tfind start}
10503(@value{GDBP}) @b{while ($trace_frame != -1)}
10504> printf "Frame %d, PC = %08X, SP = %08X, FP = %08X\n", \
10505 $trace_frame, $pc, $sp, $fp
10506> tfind
10507> end
10508
10509Frame 0, PC = 0020DC64, SP = 0030BF3C, FP = 0030BF44
10510Frame 1, PC = 0020DC6C, SP = 0030BF38, FP = 0030BF44
10511Frame 2, PC = 0020DC70, SP = 0030BF34, FP = 0030BF44
10512Frame 3, PC = 0020DC74, SP = 0030BF30, FP = 0030BF44
10513Frame 4, PC = 0020DC78, SP = 0030BF2C, FP = 0030BF44
10514Frame 5, PC = 0020DC7C, SP = 0030BF28, FP = 0030BF44
10515Frame 6, PC = 0020DC80, SP = 0030BF24, FP = 0030BF44
10516Frame 7, PC = 0020DC84, SP = 0030BF20, FP = 0030BF44
10517Frame 8, PC = 0020DC88, SP = 0030BF1C, FP = 0030BF44
10518Frame 9, PC = 0020DC8E, SP = 0030BF18, FP = 0030BF44
10519Frame 10, PC = 00203F6C, SP = 0030BE3C, FP = 0030BF14
10520@end smallexample
10521
10522Or, if we want to examine the variable @code{X} at each source line in
10523the buffer:
10524
10525@smallexample
10526(@value{GDBP}) @b{tfind start}
10527(@value{GDBP}) @b{while ($trace_frame != -1)}
10528> printf "Frame %d, X == %d\n", $trace_frame, X
10529> tfind line
10530> end
10531
10532Frame 0, X = 1
10533Frame 7, X = 2
10534Frame 13, X = 255
10535@end smallexample
10536
10537@node tdump
10538@subsection @code{tdump}
10539@kindex tdump
10540@cindex dump all data collected at tracepoint
10541@cindex tracepoint data, display
10542
10543This command takes no arguments. It prints all the data collected at
10544the current trace snapshot.
10545
10546@smallexample
10547(@value{GDBP}) @b{trace 444}
10548(@value{GDBP}) @b{actions}
10549Enter actions for tracepoint #2, one per line:
10550> collect $regs, $locals, $args, gdb_long_test
10551> end
10552
10553(@value{GDBP}) @b{tstart}
10554
10555(@value{GDBP}) @b{tfind line 444}
10556#0 gdb_test (p1=0x11, p2=0x22, p3=0x33, p4=0x44, p5=0x55, p6=0x66)
10557at gdb_test.c:444
10558444 printp( "%s: arguments = 0x%X 0x%X 0x%X 0x%X 0x%X 0x%X\n", )
10559
10560(@value{GDBP}) @b{tdump}
10561Data collected at tracepoint 2, trace frame 1:
10562d0 0xc4aa0085 -995491707
10563d1 0x18 24
10564d2 0x80 128
10565d3 0x33 51
10566d4 0x71aea3d 119204413
10567d5 0x22 34
10568d6 0xe0 224
10569d7 0x380035 3670069
10570a0 0x19e24a 1696330
10571a1 0x3000668 50333288
10572a2 0x100 256
10573a3 0x322000 3284992
10574a4 0x3000698 50333336
10575a5 0x1ad3cc 1758156
10576fp 0x30bf3c 0x30bf3c
10577sp 0x30bf34 0x30bf34
10578ps 0x0 0
10579pc 0x20b2c8 0x20b2c8
10580fpcontrol 0x0 0
10581fpstatus 0x0 0
10582fpiaddr 0x0 0
10583p = 0x20e5b4 "gdb-test"
10584p1 = (void *) 0x11
10585p2 = (void *) 0x22
10586p3 = (void *) 0x33
10587p4 = (void *) 0x44
10588p5 = (void *) 0x55
10589p6 = (void *) 0x66
10590gdb_long_test = 17 '\021'
10591
10592(@value{GDBP})
10593@end smallexample
10594
af54718e
SS
10595@code{tdump} works by scanning the tracepoint's current collection
10596actions and printing the value of each expression listed. So
10597@code{tdump} can fail, if after a run, you change the tracepoint's
10598actions to mention variables that were not collected during the run.
10599
10600Also, for tracepoints with @code{while-stepping} loops, @code{tdump}
10601uses the collected value of @code{$pc} to distinguish between trace
10602frames that were collected at the tracepoint hit, and frames that were
10603collected while stepping. This allows it to correctly choose whether
10604to display the basic list of collections, or the collections from the
10605body of the while-stepping loop. However, if @code{$pc} was not collected,
10606then @code{tdump} will always attempt to dump using the basic collection
10607list, and may fail if a while-stepping frame does not include all the
10608same data that is collected at the tracepoint hit.
10609@c This is getting pretty arcane, example would be good.
10610
6149aea9
PA
10611@node save tracepoints
10612@subsection @code{save tracepoints @var{filename}}
10613@kindex save tracepoints
b37052ae
EZ
10614@kindex save-tracepoints
10615@cindex save tracepoints for future sessions
10616
10617This command saves all current tracepoint definitions together with
10618their actions and passcounts, into a file @file{@var{filename}}
10619suitable for use in a later debugging session. To read the saved
10620tracepoint definitions, use the @code{source} command (@pxref{Command
6149aea9
PA
10621Files}). The @w{@code{save-tracepoints}} command is a deprecated
10622alias for @w{@code{save tracepoints}}
b37052ae
EZ
10623
10624@node Tracepoint Variables
10625@section Convenience Variables for Tracepoints
10626@cindex tracepoint variables
10627@cindex convenience variables for tracepoints
10628
10629@table @code
10630@vindex $trace_frame
10631@item (int) $trace_frame
10632The current trace snapshot (a.k.a.@: @dfn{frame}) number, or -1 if no
10633snapshot is selected.
10634
10635@vindex $tracepoint
10636@item (int) $tracepoint
10637The tracepoint for the current trace snapshot.
10638
10639@vindex $trace_line
10640@item (int) $trace_line
10641The line number for the current trace snapshot.
10642
10643@vindex $trace_file
10644@item (char []) $trace_file
10645The source file for the current trace snapshot.
10646
10647@vindex $trace_func
10648@item (char []) $trace_func
10649The name of the function containing @code{$tracepoint}.
10650@end table
10651
10652Note: @code{$trace_file} is not suitable for use in @code{printf},
10653use @code{output} instead.
10654
10655Here's a simple example of using these convenience variables for
10656stepping through all the trace snapshots and printing some of their
f61e138d
SS
10657data. Note that these are not the same as trace state variables,
10658which are managed by the target.
b37052ae
EZ
10659
10660@smallexample
10661(@value{GDBP}) @b{tfind start}
10662
10663(@value{GDBP}) @b{while $trace_frame != -1}
10664> output $trace_file
10665> printf ", line %d (tracepoint #%d)\n", $trace_line, $tracepoint
10666> tfind
10667> end
10668@end smallexample
10669
00bf0b85
SS
10670@node Trace Files
10671@section Using Trace Files
10672@cindex trace files
10673
10674In some situations, the target running a trace experiment may no
10675longer be available; perhaps it crashed, or the hardware was needed
10676for a different activity. To handle these cases, you can arrange to
10677dump the trace data into a file, and later use that file as a source
10678of trace data, via the @code{target tfile} command.
10679
10680@table @code
10681
10682@kindex tsave
10683@item tsave [ -r ] @var{filename}
10684Save the trace data to @var{filename}. By default, this command
10685assumes that @var{filename} refers to the host filesystem, so if
10686necessary @value{GDBN} will copy raw trace data up from the target and
10687then save it. If the target supports it, you can also supply the
10688optional argument @code{-r} (``remote'') to direct the target to save
10689the data directly into @var{filename} in its own filesystem, which may be
10690more efficient if the trace buffer is very large. (Note, however, that
10691@code{target tfile} can only read from files accessible to the host.)
10692
10693@kindex target tfile
10694@kindex tfile
10695@item target tfile @var{filename}
10696Use the file named @var{filename} as a source of trace data. Commands
10697that examine data work as they do with a live target, but it is not
10698possible to run any new trace experiments. @code{tstatus} will report
10699the state of the trace run at the moment the data was saved, as well
10700as the current trace frame you are examining. @var{filename} must be
10701on a filesystem accessible to the host.
10702
10703@end table
10704
df0cd8c5
JB
10705@node Overlays
10706@chapter Debugging Programs That Use Overlays
10707@cindex overlays
10708
10709If your program is too large to fit completely in your target system's
10710memory, you can sometimes use @dfn{overlays} to work around this
10711problem. @value{GDBN} provides some support for debugging programs that
10712use overlays.
10713
10714@menu
10715* How Overlays Work:: A general explanation of overlays.
10716* Overlay Commands:: Managing overlays in @value{GDBN}.
10717* Automatic Overlay Debugging:: @value{GDBN} can find out which overlays are
10718 mapped by asking the inferior.
10719* Overlay Sample Program:: A sample program using overlays.
10720@end menu
10721
10722@node How Overlays Work
10723@section How Overlays Work
10724@cindex mapped overlays
10725@cindex unmapped overlays
10726@cindex load address, overlay's
10727@cindex mapped address
10728@cindex overlay area
10729
10730Suppose you have a computer whose instruction address space is only 64
10731kilobytes long, but which has much more memory which can be accessed by
10732other means: special instructions, segment registers, or memory
10733management hardware, for example. Suppose further that you want to
10734adapt a program which is larger than 64 kilobytes to run on this system.
10735
10736One solution is to identify modules of your program which are relatively
10737independent, and need not call each other directly; call these modules
10738@dfn{overlays}. Separate the overlays from the main program, and place
10739their machine code in the larger memory. Place your main program in
10740instruction memory, but leave at least enough space there to hold the
10741largest overlay as well.
10742
10743Now, to call a function located in an overlay, you must first copy that
10744overlay's machine code from the large memory into the space set aside
10745for it in the instruction memory, and then jump to its entry point
10746there.
10747
c928edc0
AC
10748@c NB: In the below the mapped area's size is greater or equal to the
10749@c size of all overlays. This is intentional to remind the developer
10750@c that overlays don't necessarily need to be the same size.
10751
474c8240 10752@smallexample
df0cd8c5 10753@group
c928edc0
AC
10754 Data Instruction Larger
10755Address Space Address Space Address Space
10756+-----------+ +-----------+ +-----------+
10757| | | | | |
10758+-----------+ +-----------+ +-----------+<-- overlay 1
10759| program | | main | .----| overlay 1 | load address
10760| variables | | program | | +-----------+
10761| and heap | | | | | |
10762+-----------+ | | | +-----------+<-- overlay 2
10763| | +-----------+ | | | load address
10764+-----------+ | | | .-| overlay 2 |
10765 | | | | | |
10766 mapped --->+-----------+ | | +-----------+
10767 address | | | | | |
10768 | overlay | <-' | | |
10769 | area | <---' +-----------+<-- overlay 3
10770 | | <---. | | load address
10771 +-----------+ `--| overlay 3 |
10772 | | | |
10773 +-----------+ | |
10774 +-----------+
10775 | |
10776 +-----------+
10777
10778 @anchor{A code overlay}A code overlay
df0cd8c5 10779@end group
474c8240 10780@end smallexample
df0cd8c5 10781
c928edc0
AC
10782The diagram (@pxref{A code overlay}) shows a system with separate data
10783and instruction address spaces. To map an overlay, the program copies
10784its code from the larger address space to the instruction address space.
10785Since the overlays shown here all use the same mapped address, only one
10786may be mapped at a time. For a system with a single address space for
10787data and instructions, the diagram would be similar, except that the
10788program variables and heap would share an address space with the main
10789program and the overlay area.
df0cd8c5
JB
10790
10791An overlay loaded into instruction memory and ready for use is called a
10792@dfn{mapped} overlay; its @dfn{mapped address} is its address in the
10793instruction memory. An overlay not present (or only partially present)
10794in instruction memory is called @dfn{unmapped}; its @dfn{load address}
10795is its address in the larger memory. The mapped address is also called
10796the @dfn{virtual memory address}, or @dfn{VMA}; the load address is also
10797called the @dfn{load memory address}, or @dfn{LMA}.
10798
10799Unfortunately, overlays are not a completely transparent way to adapt a
10800program to limited instruction memory. They introduce a new set of
10801global constraints you must keep in mind as you design your program:
10802
10803@itemize @bullet
10804
10805@item
10806Before calling or returning to a function in an overlay, your program
10807must make sure that overlay is actually mapped. Otherwise, the call or
10808return will transfer control to the right address, but in the wrong
10809overlay, and your program will probably crash.
10810
10811@item
10812If the process of mapping an overlay is expensive on your system, you
10813will need to choose your overlays carefully to minimize their effect on
10814your program's performance.
10815
10816@item
10817The executable file you load onto your system must contain each
10818overlay's instructions, appearing at the overlay's load address, not its
10819mapped address. However, each overlay's instructions must be relocated
10820and its symbols defined as if the overlay were at its mapped address.
10821You can use GNU linker scripts to specify different load and relocation
10822addresses for pieces of your program; see @ref{Overlay Description,,,
10823ld.info, Using ld: the GNU linker}.
10824
10825@item
10826The procedure for loading executable files onto your system must be able
10827to load their contents into the larger address space as well as the
10828instruction and data spaces.
10829
10830@end itemize
10831
10832The overlay system described above is rather simple, and could be
10833improved in many ways:
10834
10835@itemize @bullet
10836
10837@item
10838If your system has suitable bank switch registers or memory management
10839hardware, you could use those facilities to make an overlay's load area
10840contents simply appear at their mapped address in instruction space.
10841This would probably be faster than copying the overlay to its mapped
10842area in the usual way.
10843
10844@item
10845If your overlays are small enough, you could set aside more than one
10846overlay area, and have more than one overlay mapped at a time.
10847
10848@item
10849You can use overlays to manage data, as well as instructions. In
10850general, data overlays are even less transparent to your design than
10851code overlays: whereas code overlays only require care when you call or
10852return to functions, data overlays require care every time you access
10853the data. Also, if you change the contents of a data overlay, you
10854must copy its contents back out to its load address before you can copy a
10855different data overlay into the same mapped area.
10856
10857@end itemize
10858
10859
10860@node Overlay Commands
10861@section Overlay Commands
10862
10863To use @value{GDBN}'s overlay support, each overlay in your program must
10864correspond to a separate section of the executable file. The section's
10865virtual memory address and load memory address must be the overlay's
10866mapped and load addresses. Identifying overlays with sections allows
10867@value{GDBN} to determine the appropriate address of a function or
10868variable, depending on whether the overlay is mapped or not.
10869
10870@value{GDBN}'s overlay commands all start with the word @code{overlay};
10871you can abbreviate this as @code{ov} or @code{ovly}. The commands are:
10872
10873@table @code
10874@item overlay off
4644b6e3 10875@kindex overlay
df0cd8c5
JB
10876Disable @value{GDBN}'s overlay support. When overlay support is
10877disabled, @value{GDBN} assumes that all functions and variables are
10878always present at their mapped addresses. By default, @value{GDBN}'s
10879overlay support is disabled.
10880
10881@item overlay manual
df0cd8c5
JB
10882@cindex manual overlay debugging
10883Enable @dfn{manual} overlay debugging. In this mode, @value{GDBN}
10884relies on you to tell it which overlays are mapped, and which are not,
10885using the @code{overlay map-overlay} and @code{overlay unmap-overlay}
10886commands described below.
10887
10888@item overlay map-overlay @var{overlay}
10889@itemx overlay map @var{overlay}
df0cd8c5
JB
10890@cindex map an overlay
10891Tell @value{GDBN} that @var{overlay} is now mapped; @var{overlay} must
10892be the name of the object file section containing the overlay. When an
10893overlay is mapped, @value{GDBN} assumes it can find the overlay's
10894functions and variables at their mapped addresses. @value{GDBN} assumes
10895that any other overlays whose mapped ranges overlap that of
10896@var{overlay} are now unmapped.
10897
10898@item overlay unmap-overlay @var{overlay}
10899@itemx overlay unmap @var{overlay}
df0cd8c5
JB
10900@cindex unmap an overlay
10901Tell @value{GDBN} that @var{overlay} is no longer mapped; @var{overlay}
10902must be the name of the object file section containing the overlay.
10903When an overlay is unmapped, @value{GDBN} assumes it can find the
10904overlay's functions and variables at their load addresses.
10905
10906@item overlay auto
df0cd8c5
JB
10907Enable @dfn{automatic} overlay debugging. In this mode, @value{GDBN}
10908consults a data structure the overlay manager maintains in the inferior
10909to see which overlays are mapped. For details, see @ref{Automatic
10910Overlay Debugging}.
10911
10912@item overlay load-target
10913@itemx overlay load
df0cd8c5
JB
10914@cindex reloading the overlay table
10915Re-read the overlay table from the inferior. Normally, @value{GDBN}
10916re-reads the table @value{GDBN} automatically each time the inferior
10917stops, so this command should only be necessary if you have changed the
10918overlay mapping yourself using @value{GDBN}. This command is only
10919useful when using automatic overlay debugging.
10920
10921@item overlay list-overlays
10922@itemx overlay list
10923@cindex listing mapped overlays
10924Display a list of the overlays currently mapped, along with their mapped
10925addresses, load addresses, and sizes.
10926
10927@end table
10928
10929Normally, when @value{GDBN} prints a code address, it includes the name
10930of the function the address falls in:
10931
474c8240 10932@smallexample
f7dc1244 10933(@value{GDBP}) print main
df0cd8c5 10934$3 = @{int ()@} 0x11a0 <main>
474c8240 10935@end smallexample
df0cd8c5
JB
10936@noindent
10937When overlay debugging is enabled, @value{GDBN} recognizes code in
10938unmapped overlays, and prints the names of unmapped functions with
10939asterisks around them. For example, if @code{foo} is a function in an
10940unmapped overlay, @value{GDBN} prints it this way:
10941
474c8240 10942@smallexample
f7dc1244 10943(@value{GDBP}) overlay list
df0cd8c5 10944No sections are mapped.
f7dc1244 10945(@value{GDBP}) print foo
df0cd8c5 10946$5 = @{int (int)@} 0x100000 <*foo*>
474c8240 10947@end smallexample
df0cd8c5
JB
10948@noindent
10949When @code{foo}'s overlay is mapped, @value{GDBN} prints the function's
10950name normally:
10951
474c8240 10952@smallexample
f7dc1244 10953(@value{GDBP}) overlay list
b383017d 10954Section .ov.foo.text, loaded at 0x100000 - 0x100034,
df0cd8c5 10955 mapped at 0x1016 - 0x104a
f7dc1244 10956(@value{GDBP}) print foo
df0cd8c5 10957$6 = @{int (int)@} 0x1016 <foo>
474c8240 10958@end smallexample
df0cd8c5
JB
10959
10960When overlay debugging is enabled, @value{GDBN} can find the correct
10961address for functions and variables in an overlay, whether or not the
10962overlay is mapped. This allows most @value{GDBN} commands, like
10963@code{break} and @code{disassemble}, to work normally, even on unmapped
10964code. However, @value{GDBN}'s breakpoint support has some limitations:
10965
10966@itemize @bullet
10967@item
10968@cindex breakpoints in overlays
10969@cindex overlays, setting breakpoints in
10970You can set breakpoints in functions in unmapped overlays, as long as
10971@value{GDBN} can write to the overlay at its load address.
10972@item
10973@value{GDBN} can not set hardware or simulator-based breakpoints in
10974unmapped overlays. However, if you set a breakpoint at the end of your
10975overlay manager (and tell @value{GDBN} which overlays are now mapped, if
10976you are using manual overlay management), @value{GDBN} will re-set its
10977breakpoints properly.
10978@end itemize
10979
10980
10981@node Automatic Overlay Debugging
10982@section Automatic Overlay Debugging
10983@cindex automatic overlay debugging
10984
10985@value{GDBN} can automatically track which overlays are mapped and which
10986are not, given some simple co-operation from the overlay manager in the
10987inferior. If you enable automatic overlay debugging with the
10988@code{overlay auto} command (@pxref{Overlay Commands}), @value{GDBN}
10989looks in the inferior's memory for certain variables describing the
10990current state of the overlays.
10991
10992Here are the variables your overlay manager must define to support
10993@value{GDBN}'s automatic overlay debugging:
10994
10995@table @asis
10996
10997@item @code{_ovly_table}:
10998This variable must be an array of the following structures:
10999
474c8240 11000@smallexample
df0cd8c5
JB
11001struct
11002@{
11003 /* The overlay's mapped address. */
11004 unsigned long vma;
11005
11006 /* The size of the overlay, in bytes. */
11007 unsigned long size;
11008
11009 /* The overlay's load address. */
11010 unsigned long lma;
11011
11012 /* Non-zero if the overlay is currently mapped;
11013 zero otherwise. */
11014 unsigned long mapped;
11015@}
474c8240 11016@end smallexample
df0cd8c5
JB
11017
11018@item @code{_novlys}:
11019This variable must be a four-byte signed integer, holding the total
11020number of elements in @code{_ovly_table}.
11021
11022@end table
11023
11024To decide whether a particular overlay is mapped or not, @value{GDBN}
11025looks for an entry in @w{@code{_ovly_table}} whose @code{vma} and
11026@code{lma} members equal the VMA and LMA of the overlay's section in the
11027executable file. When @value{GDBN} finds a matching entry, it consults
11028the entry's @code{mapped} member to determine whether the overlay is
11029currently mapped.
11030
81d46470 11031In addition, your overlay manager may define a function called
def71bfa 11032@code{_ovly_debug_event}. If this function is defined, @value{GDBN}
81d46470
MS
11033will silently set a breakpoint there. If the overlay manager then
11034calls this function whenever it has changed the overlay table, this
11035will enable @value{GDBN} to accurately keep track of which overlays
11036are in program memory, and update any breakpoints that may be set
b383017d 11037in overlays. This will allow breakpoints to work even if the
81d46470
MS
11038overlays are kept in ROM or other non-writable memory while they
11039are not being executed.
df0cd8c5
JB
11040
11041@node Overlay Sample Program
11042@section Overlay Sample Program
11043@cindex overlay example program
11044
11045When linking a program which uses overlays, you must place the overlays
11046at their load addresses, while relocating them to run at their mapped
11047addresses. To do this, you must write a linker script (@pxref{Overlay
11048Description,,, ld.info, Using ld: the GNU linker}). Unfortunately,
11049since linker scripts are specific to a particular host system, target
11050architecture, and target memory layout, this manual cannot provide
11051portable sample code demonstrating @value{GDBN}'s overlay support.
11052
11053However, the @value{GDBN} source distribution does contain an overlaid
11054program, with linker scripts for a few systems, as part of its test
11055suite. The program consists of the following files from
11056@file{gdb/testsuite/gdb.base}:
11057
11058@table @file
11059@item overlays.c
11060The main program file.
11061@item ovlymgr.c
11062A simple overlay manager, used by @file{overlays.c}.
11063@item foo.c
11064@itemx bar.c
11065@itemx baz.c
11066@itemx grbx.c
11067Overlay modules, loaded and used by @file{overlays.c}.
11068@item d10v.ld
11069@itemx m32r.ld
11070Linker scripts for linking the test program on the @code{d10v-elf}
11071and @code{m32r-elf} targets.
11072@end table
11073
11074You can build the test program using the @code{d10v-elf} GCC
11075cross-compiler like this:
11076
474c8240 11077@smallexample
df0cd8c5
JB
11078$ d10v-elf-gcc -g -c overlays.c
11079$ d10v-elf-gcc -g -c ovlymgr.c
11080$ d10v-elf-gcc -g -c foo.c
11081$ d10v-elf-gcc -g -c bar.c
11082$ d10v-elf-gcc -g -c baz.c
11083$ d10v-elf-gcc -g -c grbx.c
11084$ d10v-elf-gcc -g overlays.o ovlymgr.o foo.o bar.o \
11085 baz.o grbx.o -Wl,-Td10v.ld -o overlays
474c8240 11086@end smallexample
df0cd8c5
JB
11087
11088The build process is identical for any other architecture, except that
11089you must substitute the appropriate compiler and linker script for the
11090target system for @code{d10v-elf-gcc} and @code{d10v.ld}.
11091
11092
6d2ebf8b 11093@node Languages
c906108c
SS
11094@chapter Using @value{GDBN} with Different Languages
11095@cindex languages
11096
c906108c
SS
11097Although programming languages generally have common aspects, they are
11098rarely expressed in the same manner. For instance, in ANSI C,
11099dereferencing a pointer @code{p} is accomplished by @code{*p}, but in
11100Modula-2, it is accomplished by @code{p^}. Values can also be
5d161b24 11101represented (and displayed) differently. Hex numbers in C appear as
c906108c 11102@samp{0x1ae}, while in Modula-2 they appear as @samp{1AEH}.
c906108c
SS
11103
11104@cindex working language
11105Language-specific information is built into @value{GDBN} for some languages,
11106allowing you to express operations like the above in your program's
11107native language, and allowing @value{GDBN} to output values in a manner
11108consistent with the syntax of your program's native language. The
11109language you use to build expressions is called the @dfn{working
11110language}.
11111
11112@menu
11113* Setting:: Switching between source languages
11114* Show:: Displaying the language
c906108c 11115* Checks:: Type and range checks
79a6e687
BW
11116* Supported Languages:: Supported languages
11117* Unsupported Languages:: Unsupported languages
c906108c
SS
11118@end menu
11119
6d2ebf8b 11120@node Setting
79a6e687 11121@section Switching Between Source Languages
c906108c
SS
11122
11123There are two ways to control the working language---either have @value{GDBN}
11124set it automatically, or select it manually yourself. You can use the
11125@code{set language} command for either purpose. On startup, @value{GDBN}
11126defaults to setting the language automatically. The working language is
11127used to determine how expressions you type are interpreted, how values
11128are printed, etc.
11129
11130In addition to the working language, every source file that
11131@value{GDBN} knows about has its own working language. For some object
11132file formats, the compiler might indicate which language a particular
11133source file is in. However, most of the time @value{GDBN} infers the
11134language from the name of the file. The language of a source file
b37052ae 11135controls whether C@t{++} names are demangled---this way @code{backtrace} can
c906108c 11136show each frame appropriately for its own language. There is no way to
d4f3574e
SS
11137set the language of a source file from within @value{GDBN}, but you can
11138set the language associated with a filename extension. @xref{Show, ,
79a6e687 11139Displaying the Language}.
c906108c
SS
11140
11141This is most commonly a problem when you use a program, such
5d161b24 11142as @code{cfront} or @code{f2c}, that generates C but is written in
c906108c
SS
11143another language. In that case, make the
11144program use @code{#line} directives in its C output; that way
11145@value{GDBN} will know the correct language of the source code of the original
11146program, and will display that source code, not the generated C code.
11147
11148@menu
11149* Filenames:: Filename extensions and languages.
11150* Manually:: Setting the working language manually
11151* Automatically:: Having @value{GDBN} infer the source language
11152@end menu
11153
6d2ebf8b 11154@node Filenames
79a6e687 11155@subsection List of Filename Extensions and Languages
c906108c
SS
11156
11157If a source file name ends in one of the following extensions, then
11158@value{GDBN} infers that its language is the one indicated.
11159
11160@table @file
e07c999f
PH
11161@item .ada
11162@itemx .ads
11163@itemx .adb
11164@itemx .a
11165Ada source file.
c906108c
SS
11166
11167@item .c
11168C source file
11169
11170@item .C
11171@itemx .cc
11172@itemx .cp
11173@itemx .cpp
11174@itemx .cxx
11175@itemx .c++
b37052ae 11176C@t{++} source file
c906108c 11177
6aecb9c2
JB
11178@item .d
11179D source file
11180
b37303ee
AF
11181@item .m
11182Objective-C source file
11183
c906108c
SS
11184@item .f
11185@itemx .F
11186Fortran source file
11187
c906108c
SS
11188@item .mod
11189Modula-2 source file
c906108c
SS
11190
11191@item .s
11192@itemx .S
11193Assembler source file. This actually behaves almost like C, but
11194@value{GDBN} does not skip over function prologues when stepping.
11195@end table
11196
11197In addition, you may set the language associated with a filename
79a6e687 11198extension. @xref{Show, , Displaying the Language}.
c906108c 11199
6d2ebf8b 11200@node Manually
79a6e687 11201@subsection Setting the Working Language
c906108c
SS
11202
11203If you allow @value{GDBN} to set the language automatically,
11204expressions are interpreted the same way in your debugging session and
11205your program.
11206
11207@kindex set language
11208If you wish, you may set the language manually. To do this, issue the
11209command @samp{set language @var{lang}}, where @var{lang} is the name of
5d161b24 11210a language, such as
c906108c 11211@code{c} or @code{modula-2}.
c906108c
SS
11212For a list of the supported languages, type @samp{set language}.
11213
c906108c
SS
11214Setting the language manually prevents @value{GDBN} from updating the working
11215language automatically. This can lead to confusion if you try
11216to debug a program when the working language is not the same as the
11217source language, when an expression is acceptable to both
11218languages---but means different things. For instance, if the current
11219source file were written in C, and @value{GDBN} was parsing Modula-2, a
11220command such as:
11221
474c8240 11222@smallexample
c906108c 11223print a = b + c
474c8240 11224@end smallexample
c906108c
SS
11225
11226@noindent
11227might not have the effect you intended. In C, this means to add
11228@code{b} and @code{c} and place the result in @code{a}. The result
11229printed would be the value of @code{a}. In Modula-2, this means to compare
11230@code{a} to the result of @code{b+c}, yielding a @code{BOOLEAN} value.
c906108c 11231
6d2ebf8b 11232@node Automatically
79a6e687 11233@subsection Having @value{GDBN} Infer the Source Language
c906108c
SS
11234
11235To have @value{GDBN} set the working language automatically, use
11236@samp{set language local} or @samp{set language auto}. @value{GDBN}
11237then infers the working language. That is, when your program stops in a
11238frame (usually by encountering a breakpoint), @value{GDBN} sets the
11239working language to the language recorded for the function in that
11240frame. If the language for a frame is unknown (that is, if the function
11241or block corresponding to the frame was defined in a source file that
11242does not have a recognized extension), the current working language is
11243not changed, and @value{GDBN} issues a warning.
11244
11245This may not seem necessary for most programs, which are written
11246entirely in one source language. However, program modules and libraries
11247written in one source language can be used by a main program written in
11248a different source language. Using @samp{set language auto} in this
11249case frees you from having to set the working language manually.
11250
6d2ebf8b 11251@node Show
79a6e687 11252@section Displaying the Language
c906108c
SS
11253
11254The following commands help you find out which language is the
11255working language, and also what language source files were written in.
11256
c906108c
SS
11257@table @code
11258@item show language
9c16f35a 11259@kindex show language
c906108c
SS
11260Display the current working language. This is the
11261language you can use with commands such as @code{print} to
11262build and compute expressions that may involve variables in your program.
11263
11264@item info frame
4644b6e3 11265@kindex info frame@r{, show the source language}
5d161b24 11266Display the source language for this frame. This language becomes the
c906108c 11267working language if you use an identifier from this frame.
79a6e687 11268@xref{Frame Info, ,Information about a Frame}, to identify the other
c906108c
SS
11269information listed here.
11270
11271@item info source
4644b6e3 11272@kindex info source@r{, show the source language}
c906108c 11273Display the source language of this source file.
5d161b24 11274@xref{Symbols, ,Examining the Symbol Table}, to identify the other
c906108c
SS
11275information listed here.
11276@end table
11277
11278In unusual circumstances, you may have source files with extensions
11279not in the standard list. You can then set the extension associated
11280with a language explicitly:
11281
c906108c 11282@table @code
09d4efe1 11283@item set extension-language @var{ext} @var{language}
9c16f35a 11284@kindex set extension-language
09d4efe1
EZ
11285Tell @value{GDBN} that source files with extension @var{ext} are to be
11286assumed as written in the source language @var{language}.
c906108c
SS
11287
11288@item info extensions
9c16f35a 11289@kindex info extensions
c906108c
SS
11290List all the filename extensions and the associated languages.
11291@end table
11292
6d2ebf8b 11293@node Checks
79a6e687 11294@section Type and Range Checking
c906108c
SS
11295
11296@quotation
11297@emph{Warning:} In this release, the @value{GDBN} commands for type and range
11298checking are included, but they do not yet have any effect. This
11299section documents the intended facilities.
11300@end quotation
11301@c FIXME remove warning when type/range code added
11302
11303Some languages are designed to guard you against making seemingly common
11304errors through a series of compile- and run-time checks. These include
11305checking the type of arguments to functions and operators, and making
11306sure mathematical overflows are caught at run time. Checks such as
11307these help to ensure a program's correctness once it has been compiled
11308by eliminating type mismatches, and providing active checks for range
11309errors when your program is running.
11310
11311@value{GDBN} can check for conditions like the above if you wish.
9c16f35a
EZ
11312Although @value{GDBN} does not check the statements in your program,
11313it can check expressions entered directly into @value{GDBN} for
11314evaluation via the @code{print} command, for example. As with the
11315working language, @value{GDBN} can also decide whether or not to check
11316automatically based on your program's source language.
79a6e687 11317@xref{Supported Languages, ,Supported Languages}, for the default
9c16f35a 11318settings of supported languages.
c906108c
SS
11319
11320@menu
11321* Type Checking:: An overview of type checking
11322* Range Checking:: An overview of range checking
11323@end menu
11324
11325@cindex type checking
11326@cindex checks, type
6d2ebf8b 11327@node Type Checking
79a6e687 11328@subsection An Overview of Type Checking
c906108c
SS
11329
11330Some languages, such as Modula-2, are strongly typed, meaning that the
11331arguments to operators and functions have to be of the correct type,
11332otherwise an error occurs. These checks prevent type mismatch
11333errors from ever causing any run-time problems. For example,
11334
11335@smallexample
113361 + 2 @result{} 3
11337@exdent but
11338@error{} 1 + 2.3
11339@end smallexample
11340
11341The second example fails because the @code{CARDINAL} 1 is not
11342type-compatible with the @code{REAL} 2.3.
11343
5d161b24
DB
11344For the expressions you use in @value{GDBN} commands, you can tell the
11345@value{GDBN} type checker to skip checking;
11346to treat any mismatches as errors and abandon the expression;
11347or to only issue warnings when type mismatches occur,
c906108c
SS
11348but evaluate the expression anyway. When you choose the last of
11349these, @value{GDBN} evaluates expressions like the second example above, but
11350also issues a warning.
11351
5d161b24
DB
11352Even if you turn type checking off, there may be other reasons
11353related to type that prevent @value{GDBN} from evaluating an expression.
11354For instance, @value{GDBN} does not know how to add an @code{int} and
11355a @code{struct foo}. These particular type errors have nothing to do
11356with the language in use, and usually arise from expressions, such as
c906108c
SS
11357the one described above, which make little sense to evaluate anyway.
11358
11359Each language defines to what degree it is strict about type. For
11360instance, both Modula-2 and C require the arguments to arithmetical
11361operators to be numbers. In C, enumerated types and pointers can be
11362represented as numbers, so that they are valid arguments to mathematical
79a6e687 11363operators. @xref{Supported Languages, ,Supported Languages}, for further
c906108c
SS
11364details on specific languages.
11365
11366@value{GDBN} provides some additional commands for controlling the type checker:
11367
c906108c
SS
11368@kindex set check type
11369@kindex show check type
11370@table @code
11371@item set check type auto
11372Set type checking on or off based on the current working language.
79a6e687 11373@xref{Supported Languages, ,Supported Languages}, for the default settings for
c906108c
SS
11374each language.
11375
11376@item set check type on
11377@itemx set check type off
11378Set type checking on or off, overriding the default setting for the
11379current working language. Issue a warning if the setting does not
11380match the language default. If any type mismatches occur in
d4f3574e 11381evaluating an expression while type checking is on, @value{GDBN} prints a
c906108c
SS
11382message and aborts evaluation of the expression.
11383
11384@item set check type warn
11385Cause the type checker to issue warnings, but to always attempt to
11386evaluate the expression. Evaluating the expression may still
11387be impossible for other reasons. For example, @value{GDBN} cannot add
11388numbers and structures.
11389
11390@item show type
5d161b24 11391Show the current setting of the type checker, and whether or not @value{GDBN}
c906108c
SS
11392is setting it automatically.
11393@end table
11394
11395@cindex range checking
11396@cindex checks, range
6d2ebf8b 11397@node Range Checking
79a6e687 11398@subsection An Overview of Range Checking
c906108c
SS
11399
11400In some languages (such as Modula-2), it is an error to exceed the
11401bounds of a type; this is enforced with run-time checks. Such range
11402checking is meant to ensure program correctness by making sure
11403computations do not overflow, or indices on an array element access do
11404not exceed the bounds of the array.
11405
11406For expressions you use in @value{GDBN} commands, you can tell
11407@value{GDBN} to treat range errors in one of three ways: ignore them,
11408always treat them as errors and abandon the expression, or issue
11409warnings but evaluate the expression anyway.
11410
11411A range error can result from numerical overflow, from exceeding an
11412array index bound, or when you type a constant that is not a member
11413of any type. Some languages, however, do not treat overflows as an
11414error. In many implementations of C, mathematical overflow causes the
11415result to ``wrap around'' to lower values---for example, if @var{m} is
11416the largest integer value, and @var{s} is the smallest, then
11417
474c8240 11418@smallexample
c906108c 11419@var{m} + 1 @result{} @var{s}
474c8240 11420@end smallexample
c906108c
SS
11421
11422This, too, is specific to individual languages, and in some cases
79a6e687
BW
11423specific to individual compilers or machines. @xref{Supported Languages, ,
11424Supported Languages}, for further details on specific languages.
c906108c
SS
11425
11426@value{GDBN} provides some additional commands for controlling the range checker:
11427
c906108c
SS
11428@kindex set check range
11429@kindex show check range
11430@table @code
11431@item set check range auto
11432Set range checking on or off based on the current working language.
79a6e687 11433@xref{Supported Languages, ,Supported Languages}, for the default settings for
c906108c
SS
11434each language.
11435
11436@item set check range on
11437@itemx set check range off
11438Set range checking on or off, overriding the default setting for the
11439current working language. A warning is issued if the setting does not
c3f6f71d
JM
11440match the language default. If a range error occurs and range checking is on,
11441then a message is printed and evaluation of the expression is aborted.
c906108c
SS
11442
11443@item set check range warn
11444Output messages when the @value{GDBN} range checker detects a range error,
11445but attempt to evaluate the expression anyway. Evaluating the
11446expression may still be impossible for other reasons, such as accessing
11447memory that the process does not own (a typical example from many Unix
11448systems).
11449
11450@item show range
11451Show the current setting of the range checker, and whether or not it is
11452being set automatically by @value{GDBN}.
11453@end table
c906108c 11454
79a6e687
BW
11455@node Supported Languages
11456@section Supported Languages
c906108c 11457
6aecb9c2 11458@value{GDBN} supports C, C@t{++}, D, Objective-C, Fortran, Java, Pascal,
9c16f35a 11459assembly, Modula-2, and Ada.
cce74817 11460@c This is false ...
c906108c
SS
11461Some @value{GDBN} features may be used in expressions regardless of the
11462language you use: the @value{GDBN} @code{@@} and @code{::} operators,
11463and the @samp{@{type@}addr} construct (@pxref{Expressions,
11464,Expressions}) can be used with the constructs of any supported
11465language.
11466
11467The following sections detail to what degree each source language is
11468supported by @value{GDBN}. These sections are not meant to be language
11469tutorials or references, but serve only as a reference guide to what the
11470@value{GDBN} expression parser accepts, and what input and output
11471formats should look like for different languages. There are many good
11472books written on each of these languages; please look to these for a
11473language reference or tutorial.
11474
c906108c 11475@menu
b37303ee 11476* C:: C and C@t{++}
6aecb9c2 11477* D:: D
b383017d 11478* Objective-C:: Objective-C
09d4efe1 11479* Fortran:: Fortran
9c16f35a 11480* Pascal:: Pascal
b37303ee 11481* Modula-2:: Modula-2
e07c999f 11482* Ada:: Ada
c906108c
SS
11483@end menu
11484
6d2ebf8b 11485@node C
b37052ae 11486@subsection C and C@t{++}
7a292a7a 11487
b37052ae
EZ
11488@cindex C and C@t{++}
11489@cindex expressions in C or C@t{++}
c906108c 11490
b37052ae 11491Since C and C@t{++} are so closely related, many features of @value{GDBN} apply
c906108c
SS
11492to both languages. Whenever this is the case, we discuss those languages
11493together.
11494
41afff9a
EZ
11495@cindex C@t{++}
11496@cindex @code{g++}, @sc{gnu} C@t{++} compiler
b37052ae
EZ
11497@cindex @sc{gnu} C@t{++}
11498The C@t{++} debugging facilities are jointly implemented by the C@t{++}
11499compiler and @value{GDBN}. Therefore, to debug your C@t{++} code
11500effectively, you must compile your C@t{++} programs with a supported
11501C@t{++} compiler, such as @sc{gnu} @code{g++}, or the HP ANSI C@t{++}
c906108c
SS
11502compiler (@code{aCC}).
11503
0179ffac
DC
11504For best results when using @sc{gnu} C@t{++}, use the DWARF 2 debugging
11505format; if it doesn't work on your system, try the stabs+ debugging
11506format. You can select those formats explicitly with the @code{g++}
11507command-line options @option{-gdwarf-2} and @option{-gstabs+}.
ce9341a1
BW
11508@xref{Debugging Options,,Options for Debugging Your Program or GCC,
11509gcc.info, Using the @sc{gnu} Compiler Collection (GCC)}.
c906108c 11510
c906108c 11511@menu
b37052ae
EZ
11512* C Operators:: C and C@t{++} operators
11513* C Constants:: C and C@t{++} constants
79a6e687 11514* C Plus Plus Expressions:: C@t{++} expressions
b37052ae
EZ
11515* C Defaults:: Default settings for C and C@t{++}
11516* C Checks:: C and C@t{++} type and range checks
c906108c 11517* Debugging C:: @value{GDBN} and C
79a6e687 11518* Debugging C Plus Plus:: @value{GDBN} features for C@t{++}
febe4383 11519* Decimal Floating Point:: Numbers in Decimal Floating Point format
c906108c 11520@end menu
c906108c 11521
6d2ebf8b 11522@node C Operators
79a6e687 11523@subsubsection C and C@t{++} Operators
7a292a7a 11524
b37052ae 11525@cindex C and C@t{++} operators
c906108c
SS
11526
11527Operators must be defined on values of specific types. For instance,
11528@code{+} is defined on numbers, but not on structures. Operators are
5d161b24 11529often defined on groups of types.
c906108c 11530
b37052ae 11531For the purposes of C and C@t{++}, the following definitions hold:
c906108c
SS
11532
11533@itemize @bullet
53a5351d 11534
c906108c 11535@item
c906108c 11536@emph{Integral types} include @code{int} with any of its storage-class
b37052ae 11537specifiers; @code{char}; @code{enum}; and, for C@t{++}, @code{bool}.
c906108c
SS
11538
11539@item
d4f3574e
SS
11540@emph{Floating-point types} include @code{float}, @code{double}, and
11541@code{long double} (if supported by the target platform).
c906108c
SS
11542
11543@item
53a5351d 11544@emph{Pointer types} include all types defined as @code{(@var{type} *)}.
c906108c
SS
11545
11546@item
11547@emph{Scalar types} include all of the above.
53a5351d 11548
c906108c
SS
11549@end itemize
11550
11551@noindent
11552The following operators are supported. They are listed here
11553in order of increasing precedence:
11554
11555@table @code
11556@item ,
11557The comma or sequencing operator. Expressions in a comma-separated list
11558are evaluated from left to right, with the result of the entire
11559expression being the last expression evaluated.
11560
11561@item =
11562Assignment. The value of an assignment expression is the value
11563assigned. Defined on scalar types.
11564
11565@item @var{op}=
11566Used in an expression of the form @w{@code{@var{a} @var{op}= @var{b}}},
11567and translated to @w{@code{@var{a} = @var{a op b}}}.
d4f3574e 11568@w{@code{@var{op}=}} and @code{=} have the same precedence.
c906108c
SS
11569@var{op} is any one of the operators @code{|}, @code{^}, @code{&},
11570@code{<<}, @code{>>}, @code{+}, @code{-}, @code{*}, @code{/}, @code{%}.
11571
11572@item ?:
11573The ternary operator. @code{@var{a} ? @var{b} : @var{c}} can be thought
11574of as: if @var{a} then @var{b} else @var{c}. @var{a} should be of an
11575integral type.
11576
11577@item ||
11578Logical @sc{or}. Defined on integral types.
11579
11580@item &&
11581Logical @sc{and}. Defined on integral types.
11582
11583@item |
11584Bitwise @sc{or}. Defined on integral types.
11585
11586@item ^
11587Bitwise exclusive-@sc{or}. Defined on integral types.
11588
11589@item &
11590Bitwise @sc{and}. Defined on integral types.
11591
11592@item ==@r{, }!=
11593Equality and inequality. Defined on scalar types. The value of these
11594expressions is 0 for false and non-zero for true.
11595
11596@item <@r{, }>@r{, }<=@r{, }>=
11597Less than, greater than, less than or equal, greater than or equal.
11598Defined on scalar types. The value of these expressions is 0 for false
11599and non-zero for true.
11600
11601@item <<@r{, }>>
11602left shift, and right shift. Defined on integral types.
11603
11604@item @@
11605The @value{GDBN} ``artificial array'' operator (@pxref{Expressions, ,Expressions}).
11606
11607@item +@r{, }-
11608Addition and subtraction. Defined on integral types, floating-point types and
11609pointer types.
11610
11611@item *@r{, }/@r{, }%
11612Multiplication, division, and modulus. Multiplication and division are
11613defined on integral and floating-point types. Modulus is defined on
11614integral types.
11615
11616@item ++@r{, }--
11617Increment and decrement. When appearing before a variable, the
11618operation is performed before the variable is used in an expression;
11619when appearing after it, the variable's value is used before the
11620operation takes place.
11621
11622@item *
11623Pointer dereferencing. Defined on pointer types. Same precedence as
11624@code{++}.
11625
11626@item &
11627Address operator. Defined on variables. Same precedence as @code{++}.
11628
b37052ae
EZ
11629For debugging C@t{++}, @value{GDBN} implements a use of @samp{&} beyond what is
11630allowed in the C@t{++} language itself: you can use @samp{&(&@var{ref})}
b17828ca 11631to examine the address
b37052ae 11632where a C@t{++} reference variable (declared with @samp{&@var{ref}}) is
c906108c 11633stored.
c906108c
SS
11634
11635@item -
11636Negative. Defined on integral and floating-point types. Same
11637precedence as @code{++}.
11638
11639@item !
11640Logical negation. Defined on integral types. Same precedence as
11641@code{++}.
11642
11643@item ~
11644Bitwise complement operator. Defined on integral types. Same precedence as
11645@code{++}.
11646
11647
11648@item .@r{, }->
11649Structure member, and pointer-to-structure member. For convenience,
11650@value{GDBN} regards the two as equivalent, choosing whether to dereference a
11651pointer based on the stored type information.
11652Defined on @code{struct} and @code{union} data.
11653
c906108c
SS
11654@item .*@r{, }->*
11655Dereferences of pointers to members.
c906108c
SS
11656
11657@item []
11658Array indexing. @code{@var{a}[@var{i}]} is defined as
11659@code{*(@var{a}+@var{i})}. Same precedence as @code{->}.
11660
11661@item ()
11662Function parameter list. Same precedence as @code{->}.
11663
c906108c 11664@item ::
b37052ae 11665C@t{++} scope resolution operator. Defined on @code{struct}, @code{union},
7a292a7a 11666and @code{class} types.
c906108c
SS
11667
11668@item ::
7a292a7a
SS
11669Doubled colons also represent the @value{GDBN} scope operator
11670(@pxref{Expressions, ,Expressions}). Same precedence as @code{::},
11671above.
c906108c
SS
11672@end table
11673
c906108c
SS
11674If an operator is redefined in the user code, @value{GDBN} usually
11675attempts to invoke the redefined version instead of using the operator's
11676predefined meaning.
c906108c 11677
6d2ebf8b 11678@node C Constants
79a6e687 11679@subsubsection C and C@t{++} Constants
c906108c 11680
b37052ae 11681@cindex C and C@t{++} constants
c906108c 11682
b37052ae 11683@value{GDBN} allows you to express the constants of C and C@t{++} in the
c906108c 11684following ways:
c906108c
SS
11685
11686@itemize @bullet
11687@item
11688Integer constants are a sequence of digits. Octal constants are
6ca652b0
EZ
11689specified by a leading @samp{0} (i.e.@: zero), and hexadecimal constants
11690by a leading @samp{0x} or @samp{0X}. Constants may also end with a letter
c906108c
SS
11691@samp{l}, specifying that the constant should be treated as a
11692@code{long} value.
11693
11694@item
11695Floating point constants are a sequence of digits, followed by a decimal
11696point, followed by a sequence of digits, and optionally followed by an
11697exponent. An exponent is of the form:
11698@samp{@w{e@r{[[}+@r{]|}-@r{]}@var{nnn}}}, where @var{nnn} is another
11699sequence of digits. The @samp{+} is optional for positive exponents.
d4f3574e
SS
11700A floating-point constant may also end with a letter @samp{f} or
11701@samp{F}, specifying that the constant should be treated as being of
11702the @code{float} (as opposed to the default @code{double}) type; or with
11703a letter @samp{l} or @samp{L}, which specifies a @code{long double}
11704constant.
c906108c
SS
11705
11706@item
11707Enumerated constants consist of enumerated identifiers, or their
11708integral equivalents.
11709
11710@item
11711Character constants are a single character surrounded by single quotes
11712(@code{'}), or a number---the ordinal value of the corresponding character
d4f3574e 11713(usually its @sc{ascii} value). Within quotes, the single character may
c906108c
SS
11714be represented by a letter or by @dfn{escape sequences}, which are of
11715the form @samp{\@var{nnn}}, where @var{nnn} is the octal representation
11716of the character's ordinal value; or of the form @samp{\@var{x}}, where
11717@samp{@var{x}} is a predefined special character---for example,
11718@samp{\n} for newline.
11719
11720@item
96a2c332
SS
11721String constants are a sequence of character constants surrounded by
11722double quotes (@code{"}). Any valid character constant (as described
11723above) may appear. Double quotes within the string must be preceded by
11724a backslash, so for instance @samp{"a\"b'c"} is a string of five
11725characters.
c906108c
SS
11726
11727@item
11728Pointer constants are an integral value. You can also write pointers
11729to constants using the C operator @samp{&}.
11730
11731@item
11732Array constants are comma-separated lists surrounded by braces @samp{@{}
11733and @samp{@}}; for example, @samp{@{1,2,3@}} is a three-element array of
11734integers, @samp{@{@{1,2@}, @{3,4@}, @{5,6@}@}} is a three-by-two array,
11735and @samp{@{&"hi", &"there", &"fred"@}} is a three-element array of pointers.
11736@end itemize
11737
79a6e687
BW
11738@node C Plus Plus Expressions
11739@subsubsection C@t{++} Expressions
b37052ae
EZ
11740
11741@cindex expressions in C@t{++}
11742@value{GDBN} expression handling can interpret most C@t{++} expressions.
11743
0179ffac
DC
11744@cindex debugging C@t{++} programs
11745@cindex C@t{++} compilers
11746@cindex debug formats and C@t{++}
11747@cindex @value{NGCC} and C@t{++}
c906108c 11748@quotation
b37052ae 11749@emph{Warning:} @value{GDBN} can only debug C@t{++} code if you use the
0179ffac
DC
11750proper compiler and the proper debug format. Currently, @value{GDBN}
11751works best when debugging C@t{++} code that is compiled with
11752@value{NGCC} 2.95.3 or with @value{NGCC} 3.1 or newer, using the options
11753@option{-gdwarf-2} or @option{-gstabs+}. DWARF 2 is preferred over
11754stabs+. Most configurations of @value{NGCC} emit either DWARF 2 or
11755stabs+ as their default debug format, so you usually don't need to
11756specify a debug format explicitly. Other compilers and/or debug formats
11757are likely to work badly or not at all when using @value{GDBN} to debug
11758C@t{++} code.
c906108c 11759@end quotation
c906108c
SS
11760
11761@enumerate
11762
11763@cindex member functions
11764@item
11765Member function calls are allowed; you can use expressions like
11766
474c8240 11767@smallexample
c906108c 11768count = aml->GetOriginal(x, y)
474c8240 11769@end smallexample
c906108c 11770
41afff9a 11771@vindex this@r{, inside C@t{++} member functions}
b37052ae 11772@cindex namespace in C@t{++}
c906108c
SS
11773@item
11774While a member function is active (in the selected stack frame), your
11775expressions have the same namespace available as the member function;
11776that is, @value{GDBN} allows implicit references to the class instance
b37052ae 11777pointer @code{this} following the same rules as C@t{++}.
c906108c 11778
c906108c 11779@cindex call overloaded functions
d4f3574e 11780@cindex overloaded functions, calling
b37052ae 11781@cindex type conversions in C@t{++}
c906108c
SS
11782@item
11783You can call overloaded functions; @value{GDBN} resolves the function
d4f3574e 11784call to the right definition, with some restrictions. @value{GDBN} does not
c906108c
SS
11785perform overload resolution involving user-defined type conversions,
11786calls to constructors, or instantiations of templates that do not exist
11787in the program. It also cannot handle ellipsis argument lists or
11788default arguments.
11789
11790It does perform integral conversions and promotions, floating-point
11791promotions, arithmetic conversions, pointer conversions, conversions of
11792class objects to base classes, and standard conversions such as those of
11793functions or arrays to pointers; it requires an exact match on the
11794number of function arguments.
11795
11796Overload resolution is always performed, unless you have specified
79a6e687
BW
11797@code{set overload-resolution off}. @xref{Debugging C Plus Plus,
11798,@value{GDBN} Features for C@t{++}}.
c906108c 11799
d4f3574e 11800You must specify @code{set overload-resolution off} in order to use an
c906108c
SS
11801explicit function signature to call an overloaded function, as in
11802@smallexample
11803p 'foo(char,int)'('x', 13)
11804@end smallexample
d4f3574e 11805
c906108c 11806The @value{GDBN} command-completion facility can simplify this;
79a6e687 11807see @ref{Completion, ,Command Completion}.
c906108c 11808
c906108c
SS
11809@cindex reference declarations
11810@item
b37052ae
EZ
11811@value{GDBN} understands variables declared as C@t{++} references; you can use
11812them in expressions just as you do in C@t{++} source---they are automatically
c906108c
SS
11813dereferenced.
11814
11815In the parameter list shown when @value{GDBN} displays a frame, the values of
11816reference variables are not displayed (unlike other variables); this
11817avoids clutter, since references are often used for large structures.
11818The @emph{address} of a reference variable is always shown, unless
11819you have specified @samp{set print address off}.
11820
11821@item
b37052ae 11822@value{GDBN} supports the C@t{++} name resolution operator @code{::}---your
c906108c
SS
11823expressions can use it just as expressions in your program do. Since
11824one scope may be defined in another, you can use @code{::} repeatedly if
11825necessary, for example in an expression like
11826@samp{@var{scope1}::@var{scope2}::@var{name}}. @value{GDBN} also allows
b37052ae 11827resolving name scope by reference to source files, in both C and C@t{++}
79a6e687 11828debugging (@pxref{Variables, ,Program Variables}).
c906108c
SS
11829@end enumerate
11830
b37052ae 11831In addition, when used with HP's C@t{++} compiler, @value{GDBN} supports
53a5351d
JM
11832calling virtual functions correctly, printing out virtual bases of
11833objects, calling functions in a base subobject, casting objects, and
11834invoking user-defined operators.
c906108c 11835
6d2ebf8b 11836@node C Defaults
79a6e687 11837@subsubsection C and C@t{++} Defaults
7a292a7a 11838
b37052ae 11839@cindex C and C@t{++} defaults
c906108c 11840
c906108c
SS
11841If you allow @value{GDBN} to set type and range checking automatically, they
11842both default to @code{off} whenever the working language changes to
b37052ae 11843C or C@t{++}. This happens regardless of whether you or @value{GDBN}
c906108c 11844selects the working language.
c906108c
SS
11845
11846If you allow @value{GDBN} to set the language automatically, it
11847recognizes source files whose names end with @file{.c}, @file{.C}, or
11848@file{.cc}, etc, and when @value{GDBN} enters code compiled from one of
b37052ae 11849these files, it sets the working language to C or C@t{++}.
79a6e687 11850@xref{Automatically, ,Having @value{GDBN} Infer the Source Language},
c906108c
SS
11851for further details.
11852
c906108c
SS
11853@c Type checking is (a) primarily motivated by Modula-2, and (b)
11854@c unimplemented. If (b) changes, it might make sense to let this node
11855@c appear even if Mod-2 does not, but meanwhile ignore it. roland 16jul93.
7a292a7a 11856
6d2ebf8b 11857@node C Checks
79a6e687 11858@subsubsection C and C@t{++} Type and Range Checks
7a292a7a 11859
b37052ae 11860@cindex C and C@t{++} checks
c906108c 11861
b37052ae 11862By default, when @value{GDBN} parses C or C@t{++} expressions, type checking
c906108c
SS
11863is not used. However, if you turn type checking on, @value{GDBN}
11864considers two variables type equivalent if:
11865
11866@itemize @bullet
11867@item
11868The two variables are structured and have the same structure, union, or
11869enumerated tag.
11870
11871@item
11872The two variables have the same type name, or types that have been
11873declared equivalent through @code{typedef}.
11874
11875@ignore
11876@c leaving this out because neither J Gilmore nor R Pesch understand it.
11877@c FIXME--beers?
11878@item
11879The two @code{struct}, @code{union}, or @code{enum} variables are
11880declared in the same declaration. (Note: this may not be true for all C
11881compilers.)
11882@end ignore
11883@end itemize
11884
11885Range checking, if turned on, is done on mathematical operations. Array
11886indices are not checked, since they are often used to index a pointer
11887that is not itself an array.
c906108c 11888
6d2ebf8b 11889@node Debugging C
c906108c 11890@subsubsection @value{GDBN} and C
c906108c
SS
11891
11892The @code{set print union} and @code{show print union} commands apply to
11893the @code{union} type. When set to @samp{on}, any @code{union} that is
7a292a7a
SS
11894inside a @code{struct} or @code{class} is also printed. Otherwise, it
11895appears as @samp{@{...@}}.
c906108c
SS
11896
11897The @code{@@} operator aids in the debugging of dynamic arrays, formed
11898with pointers and a memory allocation function. @xref{Expressions,
11899,Expressions}.
11900
79a6e687
BW
11901@node Debugging C Plus Plus
11902@subsubsection @value{GDBN} Features for C@t{++}
c906108c 11903
b37052ae 11904@cindex commands for C@t{++}
7a292a7a 11905
b37052ae
EZ
11906Some @value{GDBN} commands are particularly useful with C@t{++}, and some are
11907designed specifically for use with C@t{++}. Here is a summary:
c906108c
SS
11908
11909@table @code
11910@cindex break in overloaded functions
11911@item @r{breakpoint menus}
11912When you want a breakpoint in a function whose name is overloaded,
6ba66d6a
JB
11913@value{GDBN} has the capability to display a menu of possible breakpoint
11914locations to help you specify which function definition you want.
11915@xref{Ambiguous Expressions,,Ambiguous Expressions}.
c906108c 11916
b37052ae 11917@cindex overloading in C@t{++}
c906108c
SS
11918@item rbreak @var{regex}
11919Setting breakpoints using regular expressions is helpful for setting
11920breakpoints on overloaded functions that are not members of any special
11921classes.
79a6e687 11922@xref{Set Breaks, ,Setting Breakpoints}.
c906108c 11923
b37052ae 11924@cindex C@t{++} exception handling
c906108c
SS
11925@item catch throw
11926@itemx catch catch
b37052ae 11927Debug C@t{++} exception handling using these commands. @xref{Set
79a6e687 11928Catchpoints, , Setting Catchpoints}.
c906108c
SS
11929
11930@cindex inheritance
11931@item ptype @var{typename}
11932Print inheritance relationships as well as other information for type
11933@var{typename}.
11934@xref{Symbols, ,Examining the Symbol Table}.
11935
b37052ae 11936@cindex C@t{++} symbol display
c906108c
SS
11937@item set print demangle
11938@itemx show print demangle
11939@itemx set print asm-demangle
11940@itemx show print asm-demangle
b37052ae
EZ
11941Control whether C@t{++} symbols display in their source form, both when
11942displaying code as C@t{++} source and when displaying disassemblies.
79a6e687 11943@xref{Print Settings, ,Print Settings}.
c906108c
SS
11944
11945@item set print object
11946@itemx show print object
11947Choose whether to print derived (actual) or declared types of objects.
79a6e687 11948@xref{Print Settings, ,Print Settings}.
c906108c
SS
11949
11950@item set print vtbl
11951@itemx show print vtbl
11952Control the format for printing virtual function tables.
79a6e687 11953@xref{Print Settings, ,Print Settings}.
c906108c 11954(The @code{vtbl} commands do not work on programs compiled with the HP
b37052ae 11955ANSI C@t{++} compiler (@code{aCC}).)
c906108c
SS
11956
11957@kindex set overload-resolution
d4f3574e 11958@cindex overloaded functions, overload resolution
c906108c 11959@item set overload-resolution on
b37052ae 11960Enable overload resolution for C@t{++} expression evaluation. The default
c906108c
SS
11961is on. For overloaded functions, @value{GDBN} evaluates the arguments
11962and searches for a function whose signature matches the argument types,
79a6e687
BW
11963using the standard C@t{++} conversion rules (see @ref{C Plus Plus
11964Expressions, ,C@t{++} Expressions}, for details).
11965If it cannot find a match, it emits a message.
c906108c
SS
11966
11967@item set overload-resolution off
b37052ae 11968Disable overload resolution for C@t{++} expression evaluation. For
c906108c
SS
11969overloaded functions that are not class member functions, @value{GDBN}
11970chooses the first function of the specified name that it finds in the
11971symbol table, whether or not its arguments are of the correct type. For
11972overloaded functions that are class member functions, @value{GDBN}
11973searches for a function whose signature @emph{exactly} matches the
11974argument types.
c906108c 11975
9c16f35a
EZ
11976@kindex show overload-resolution
11977@item show overload-resolution
11978Show the current setting of overload resolution.
11979
c906108c
SS
11980@item @r{Overloaded symbol names}
11981You can specify a particular definition of an overloaded symbol, using
b37052ae 11982the same notation that is used to declare such symbols in C@t{++}: type
c906108c
SS
11983@code{@var{symbol}(@var{types})} rather than just @var{symbol}. You can
11984also use the @value{GDBN} command-line word completion facilities to list the
11985available choices, or to finish the type list for you.
79a6e687 11986@xref{Completion,, Command Completion}, for details on how to do this.
c906108c 11987@end table
c906108c 11988
febe4383
TJB
11989@node Decimal Floating Point
11990@subsubsection Decimal Floating Point format
11991@cindex decimal floating point format
11992
11993@value{GDBN} can examine, set and perform computations with numbers in
11994decimal floating point format, which in the C language correspond to the
11995@code{_Decimal32}, @code{_Decimal64} and @code{_Decimal128} types as
11996specified by the extension to support decimal floating-point arithmetic.
11997
11998There are two encodings in use, depending on the architecture: BID (Binary
11999Integer Decimal) for x86 and x86-64, and DPD (Densely Packed Decimal) for
99e008fe 12000PowerPC. @value{GDBN} will use the appropriate encoding for the configured
febe4383
TJB
12001target.
12002
12003Because of a limitation in @file{libdecnumber}, the library used by @value{GDBN}
12004to manipulate decimal floating point numbers, it is not possible to convert
12005(using a cast, for example) integers wider than 32-bit to decimal float.
12006
12007In addition, in order to imitate @value{GDBN}'s behaviour with binary floating
12008point computations, error checking in decimal float operations ignores
12009underflow, overflow and divide by zero exceptions.
12010
4acd40f3 12011In the PowerPC architecture, @value{GDBN} provides a set of pseudo-registers
99e008fe
EZ
12012to inspect @code{_Decimal128} values stored in floating point registers.
12013See @ref{PowerPC,,PowerPC} for more details.
4acd40f3 12014
6aecb9c2
JB
12015@node D
12016@subsection D
12017
12018@cindex D
12019@value{GDBN} can be used to debug programs written in D and compiled with
12020GDC, LDC or DMD compilers. Currently @value{GDBN} supports only one D
12021specific feature --- dynamic arrays.
12022
b37303ee
AF
12023@node Objective-C
12024@subsection Objective-C
12025
12026@cindex Objective-C
12027This section provides information about some commands and command
721c2651
EZ
12028options that are useful for debugging Objective-C code. See also
12029@ref{Symbols, info classes}, and @ref{Symbols, info selectors}, for a
12030few more commands specific to Objective-C support.
b37303ee
AF
12031
12032@menu
b383017d
RM
12033* Method Names in Commands::
12034* The Print Command with Objective-C::
b37303ee
AF
12035@end menu
12036
c8f4133a 12037@node Method Names in Commands
b37303ee
AF
12038@subsubsection Method Names in Commands
12039
12040The following commands have been extended to accept Objective-C method
12041names as line specifications:
12042
12043@kindex clear@r{, and Objective-C}
12044@kindex break@r{, and Objective-C}
12045@kindex info line@r{, and Objective-C}
12046@kindex jump@r{, and Objective-C}
12047@kindex list@r{, and Objective-C}
12048@itemize
12049@item @code{clear}
12050@item @code{break}
12051@item @code{info line}
12052@item @code{jump}
12053@item @code{list}
12054@end itemize
12055
12056A fully qualified Objective-C method name is specified as
12057
12058@smallexample
12059-[@var{Class} @var{methodName}]
12060@end smallexample
12061
c552b3bb
JM
12062where the minus sign is used to indicate an instance method and a
12063plus sign (not shown) is used to indicate a class method. The class
12064name @var{Class} and method name @var{methodName} are enclosed in
12065brackets, similar to the way messages are specified in Objective-C
12066source code. For example, to set a breakpoint at the @code{create}
12067instance method of class @code{Fruit} in the program currently being
12068debugged, enter:
b37303ee
AF
12069
12070@smallexample
12071break -[Fruit create]
12072@end smallexample
12073
12074To list ten program lines around the @code{initialize} class method,
12075enter:
12076
12077@smallexample
12078list +[NSText initialize]
12079@end smallexample
12080
c552b3bb
JM
12081In the current version of @value{GDBN}, the plus or minus sign is
12082required. In future versions of @value{GDBN}, the plus or minus
12083sign will be optional, but you can use it to narrow the search. It
12084is also possible to specify just a method name:
b37303ee
AF
12085
12086@smallexample
12087break create
12088@end smallexample
12089
12090You must specify the complete method name, including any colons. If
12091your program's source files contain more than one @code{create} method,
12092you'll be presented with a numbered list of classes that implement that
12093method. Indicate your choice by number, or type @samp{0} to exit if
12094none apply.
12095
12096As another example, to clear a breakpoint established at the
12097@code{makeKeyAndOrderFront:} method of the @code{NSWindow} class, enter:
12098
12099@smallexample
12100clear -[NSWindow makeKeyAndOrderFront:]
12101@end smallexample
12102
12103@node The Print Command with Objective-C
12104@subsubsection The Print Command With Objective-C
721c2651 12105@cindex Objective-C, print objects
c552b3bb
JM
12106@kindex print-object
12107@kindex po @r{(@code{print-object})}
b37303ee 12108
c552b3bb 12109The print command has also been extended to accept methods. For example:
b37303ee
AF
12110
12111@smallexample
c552b3bb 12112print -[@var{object} hash]
b37303ee
AF
12113@end smallexample
12114
12115@cindex print an Objective-C object description
c552b3bb
JM
12116@cindex @code{_NSPrintForDebugger}, and printing Objective-C objects
12117@noindent
12118will tell @value{GDBN} to send the @code{hash} message to @var{object}
12119and print the result. Also, an additional command has been added,
12120@code{print-object} or @code{po} for short, which is meant to print
12121the description of an object. However, this command may only work
12122with certain Objective-C libraries that have a particular hook
12123function, @code{_NSPrintForDebugger}, defined.
b37303ee 12124
09d4efe1
EZ
12125@node Fortran
12126@subsection Fortran
12127@cindex Fortran-specific support in @value{GDBN}
12128
814e32d7
WZ
12129@value{GDBN} can be used to debug programs written in Fortran, but it
12130currently supports only the features of Fortran 77 language.
12131
12132@cindex trailing underscore, in Fortran symbols
12133Some Fortran compilers (@sc{gnu} Fortran 77 and Fortran 95 compilers
12134among them) append an underscore to the names of variables and
12135functions. When you debug programs compiled by those compilers, you
12136will need to refer to variables and functions with a trailing
12137underscore.
12138
12139@menu
12140* Fortran Operators:: Fortran operators and expressions
12141* Fortran Defaults:: Default settings for Fortran
79a6e687 12142* Special Fortran Commands:: Special @value{GDBN} commands for Fortran
814e32d7
WZ
12143@end menu
12144
12145@node Fortran Operators
79a6e687 12146@subsubsection Fortran Operators and Expressions
814e32d7
WZ
12147
12148@cindex Fortran operators and expressions
12149
12150Operators must be defined on values of specific types. For instance,
12151@code{+} is defined on numbers, but not on characters or other non-
ff2587ec 12152arithmetic types. Operators are often defined on groups of types.
814e32d7
WZ
12153
12154@table @code
12155@item **
99e008fe 12156The exponentiation operator. It raises the first operand to the power
814e32d7
WZ
12157of the second one.
12158
12159@item :
12160The range operator. Normally used in the form of array(low:high) to
12161represent a section of array.
68837c9d
MD
12162
12163@item %
12164The access component operator. Normally used to access elements in derived
12165types. Also suitable for unions. As unions aren't part of regular Fortran,
12166this can only happen when accessing a register that uses a gdbarch-defined
12167union type.
814e32d7
WZ
12168@end table
12169
12170@node Fortran Defaults
12171@subsubsection Fortran Defaults
12172
12173@cindex Fortran Defaults
12174
12175Fortran symbols are usually case-insensitive, so @value{GDBN} by
12176default uses case-insensitive matches for Fortran symbols. You can
12177change that with the @samp{set case-insensitive} command, see
12178@ref{Symbols}, for the details.
12179
79a6e687
BW
12180@node Special Fortran Commands
12181@subsubsection Special Fortran Commands
814e32d7
WZ
12182
12183@cindex Special Fortran commands
12184
db2e3e2e
BW
12185@value{GDBN} has some commands to support Fortran-specific features,
12186such as displaying common blocks.
814e32d7 12187
09d4efe1
EZ
12188@table @code
12189@cindex @code{COMMON} blocks, Fortran
12190@kindex info common
12191@item info common @r{[}@var{common-name}@r{]}
12192This command prints the values contained in the Fortran @code{COMMON}
12193block whose name is @var{common-name}. With no argument, the names of
d52fb0e9 12194all @code{COMMON} blocks visible at the current program location are
09d4efe1
EZ
12195printed.
12196@end table
12197
9c16f35a
EZ
12198@node Pascal
12199@subsection Pascal
12200
12201@cindex Pascal support in @value{GDBN}, limitations
12202Debugging Pascal programs which use sets, subranges, file variables, or
12203nested functions does not currently work. @value{GDBN} does not support
12204entering expressions, printing values, or similar features using Pascal
12205syntax.
12206
12207The Pascal-specific command @code{set print pascal_static-members}
12208controls whether static members of Pascal objects are displayed.
12209@xref{Print Settings, pascal_static-members}.
12210
09d4efe1 12211@node Modula-2
c906108c 12212@subsection Modula-2
7a292a7a 12213
d4f3574e 12214@cindex Modula-2, @value{GDBN} support
c906108c
SS
12215
12216The extensions made to @value{GDBN} to support Modula-2 only support
12217output from the @sc{gnu} Modula-2 compiler (which is currently being
12218developed). Other Modula-2 compilers are not currently supported, and
12219attempting to debug executables produced by them is most likely
12220to give an error as @value{GDBN} reads in the executable's symbol
12221table.
12222
12223@cindex expressions in Modula-2
12224@menu
12225* M2 Operators:: Built-in operators
12226* Built-In Func/Proc:: Built-in functions and procedures
12227* M2 Constants:: Modula-2 constants
72019c9c 12228* M2 Types:: Modula-2 types
c906108c
SS
12229* M2 Defaults:: Default settings for Modula-2
12230* Deviations:: Deviations from standard Modula-2
12231* M2 Checks:: Modula-2 type and range checks
12232* M2 Scope:: The scope operators @code{::} and @code{.}
12233* GDB/M2:: @value{GDBN} and Modula-2
12234@end menu
12235
6d2ebf8b 12236@node M2 Operators
c906108c
SS
12237@subsubsection Operators
12238@cindex Modula-2 operators
12239
12240Operators must be defined on values of specific types. For instance,
12241@code{+} is defined on numbers, but not on structures. Operators are
12242often defined on groups of types. For the purposes of Modula-2, the
12243following definitions hold:
12244
12245@itemize @bullet
12246
12247@item
12248@emph{Integral types} consist of @code{INTEGER}, @code{CARDINAL}, and
12249their subranges.
12250
12251@item
12252@emph{Character types} consist of @code{CHAR} and its subranges.
12253
12254@item
12255@emph{Floating-point types} consist of @code{REAL}.
12256
12257@item
12258@emph{Pointer types} consist of anything declared as @code{POINTER TO
12259@var{type}}.
12260
12261@item
12262@emph{Scalar types} consist of all of the above.
12263
12264@item
12265@emph{Set types} consist of @code{SET} and @code{BITSET} types.
12266
12267@item
12268@emph{Boolean types} consist of @code{BOOLEAN}.
12269@end itemize
12270
12271@noindent
12272The following operators are supported, and appear in order of
12273increasing precedence:
12274
12275@table @code
12276@item ,
12277Function argument or array index separator.
12278
12279@item :=
12280Assignment. The value of @var{var} @code{:=} @var{value} is
12281@var{value}.
12282
12283@item <@r{, }>
12284Less than, greater than on integral, floating-point, or enumerated
12285types.
12286
12287@item <=@r{, }>=
96a2c332 12288Less than or equal to, greater than or equal to
c906108c
SS
12289on integral, floating-point and enumerated types, or set inclusion on
12290set types. Same precedence as @code{<}.
12291
12292@item =@r{, }<>@r{, }#
12293Equality and two ways of expressing inequality, valid on scalar types.
12294Same precedence as @code{<}. In @value{GDBN} scripts, only @code{<>} is
12295available for inequality, since @code{#} conflicts with the script
12296comment character.
12297
12298@item IN
12299Set membership. Defined on set types and the types of their members.
12300Same precedence as @code{<}.
12301
12302@item OR
12303Boolean disjunction. Defined on boolean types.
12304
12305@item AND@r{, }&
d4f3574e 12306Boolean conjunction. Defined on boolean types.
c906108c
SS
12307
12308@item @@
12309The @value{GDBN} ``artificial array'' operator (@pxref{Expressions, ,Expressions}).
12310
12311@item +@r{, }-
12312Addition and subtraction on integral and floating-point types, or union
12313and difference on set types.
12314
12315@item *
12316Multiplication on integral and floating-point types, or set intersection
12317on set types.
12318
12319@item /
12320Division on floating-point types, or symmetric set difference on set
12321types. Same precedence as @code{*}.
12322
12323@item DIV@r{, }MOD
12324Integer division and remainder. Defined on integral types. Same
12325precedence as @code{*}.
12326
12327@item -
99e008fe 12328Negative. Defined on @code{INTEGER} and @code{REAL} data.
c906108c
SS
12329
12330@item ^
12331Pointer dereferencing. Defined on pointer types.
12332
12333@item NOT
12334Boolean negation. Defined on boolean types. Same precedence as
12335@code{^}.
12336
12337@item .
12338@code{RECORD} field selector. Defined on @code{RECORD} data. Same
12339precedence as @code{^}.
12340
12341@item []
12342Array indexing. Defined on @code{ARRAY} data. Same precedence as @code{^}.
12343
12344@item ()
12345Procedure argument list. Defined on @code{PROCEDURE} objects. Same precedence
12346as @code{^}.
12347
12348@item ::@r{, }.
12349@value{GDBN} and Modula-2 scope operators.
12350@end table
12351
12352@quotation
72019c9c 12353@emph{Warning:} Set expressions and their operations are not yet supported, so @value{GDBN}
c906108c
SS
12354treats the use of the operator @code{IN}, or the use of operators
12355@code{+}, @code{-}, @code{*}, @code{/}, @code{=}, , @code{<>}, @code{#},
12356@code{<=}, and @code{>=} on sets as an error.
12357@end quotation
12358
cb51c4e0 12359
6d2ebf8b 12360@node Built-In Func/Proc
79a6e687 12361@subsubsection Built-in Functions and Procedures
cb51c4e0 12362@cindex Modula-2 built-ins
c906108c
SS
12363
12364Modula-2 also makes available several built-in procedures and functions.
12365In describing these, the following metavariables are used:
12366
12367@table @var
12368
12369@item a
12370represents an @code{ARRAY} variable.
12371
12372@item c
12373represents a @code{CHAR} constant or variable.
12374
12375@item i
12376represents a variable or constant of integral type.
12377
12378@item m
12379represents an identifier that belongs to a set. Generally used in the
12380same function with the metavariable @var{s}. The type of @var{s} should
12381be @code{SET OF @var{mtype}} (where @var{mtype} is the type of @var{m}).
12382
12383@item n
12384represents a variable or constant of integral or floating-point type.
12385
12386@item r
12387represents a variable or constant of floating-point type.
12388
12389@item t
12390represents a type.
12391
12392@item v
12393represents a variable.
12394
12395@item x
12396represents a variable or constant of one of many types. See the
12397explanation of the function for details.
12398@end table
12399
12400All Modula-2 built-in procedures also return a result, described below.
12401
12402@table @code
12403@item ABS(@var{n})
12404Returns the absolute value of @var{n}.
12405
12406@item CAP(@var{c})
12407If @var{c} is a lower case letter, it returns its upper case
c3f6f71d 12408equivalent, otherwise it returns its argument.
c906108c
SS
12409
12410@item CHR(@var{i})
12411Returns the character whose ordinal value is @var{i}.
12412
12413@item DEC(@var{v})
c3f6f71d 12414Decrements the value in the variable @var{v} by one. Returns the new value.
c906108c
SS
12415
12416@item DEC(@var{v},@var{i})
12417Decrements the value in the variable @var{v} by @var{i}. Returns the
12418new value.
12419
12420@item EXCL(@var{m},@var{s})
12421Removes the element @var{m} from the set @var{s}. Returns the new
12422set.
12423
12424@item FLOAT(@var{i})
12425Returns the floating point equivalent of the integer @var{i}.
12426
12427@item HIGH(@var{a})
12428Returns the index of the last member of @var{a}.
12429
12430@item INC(@var{v})
c3f6f71d 12431Increments the value in the variable @var{v} by one. Returns the new value.
c906108c
SS
12432
12433@item INC(@var{v},@var{i})
12434Increments the value in the variable @var{v} by @var{i}. Returns the
12435new value.
12436
12437@item INCL(@var{m},@var{s})
12438Adds the element @var{m} to the set @var{s} if it is not already
12439there. Returns the new set.
12440
12441@item MAX(@var{t})
12442Returns the maximum value of the type @var{t}.
12443
12444@item MIN(@var{t})
12445Returns the minimum value of the type @var{t}.
12446
12447@item ODD(@var{i})
12448Returns boolean TRUE if @var{i} is an odd number.
12449
12450@item ORD(@var{x})
12451Returns the ordinal value of its argument. For example, the ordinal
c3f6f71d
JM
12452value of a character is its @sc{ascii} value (on machines supporting the
12453@sc{ascii} character set). @var{x} must be of an ordered type, which include
c906108c
SS
12454integral, character and enumerated types.
12455
12456@item SIZE(@var{x})
12457Returns the size of its argument. @var{x} can be a variable or a type.
12458
12459@item TRUNC(@var{r})
12460Returns the integral part of @var{r}.
12461
844781a1
GM
12462@item TSIZE(@var{x})
12463Returns the size of its argument. @var{x} can be a variable or a type.
12464
c906108c
SS
12465@item VAL(@var{t},@var{i})
12466Returns the member of the type @var{t} whose ordinal value is @var{i}.
12467@end table
12468
12469@quotation
12470@emph{Warning:} Sets and their operations are not yet supported, so
12471@value{GDBN} treats the use of procedures @code{INCL} and @code{EXCL} as
12472an error.
12473@end quotation
12474
12475@cindex Modula-2 constants
6d2ebf8b 12476@node M2 Constants
c906108c
SS
12477@subsubsection Constants
12478
12479@value{GDBN} allows you to express the constants of Modula-2 in the following
12480ways:
12481
12482@itemize @bullet
12483
12484@item
12485Integer constants are simply a sequence of digits. When used in an
12486expression, a constant is interpreted to be type-compatible with the
12487rest of the expression. Hexadecimal integers are specified by a
12488trailing @samp{H}, and octal integers by a trailing @samp{B}.
12489
12490@item
12491Floating point constants appear as a sequence of digits, followed by a
12492decimal point and another sequence of digits. An optional exponent can
12493then be specified, in the form @samp{E@r{[}+@r{|}-@r{]}@var{nnn}}, where
12494@samp{@r{[}+@r{|}-@r{]}@var{nnn}} is the desired exponent. All of the
12495digits of the floating point constant must be valid decimal (base 10)
12496digits.
12497
12498@item
12499Character constants consist of a single character enclosed by a pair of
12500like quotes, either single (@code{'}) or double (@code{"}). They may
c3f6f71d 12501also be expressed by their ordinal value (their @sc{ascii} value, usually)
c906108c
SS
12502followed by a @samp{C}.
12503
12504@item
12505String constants consist of a sequence of characters enclosed by a
12506pair of like quotes, either single (@code{'}) or double (@code{"}).
12507Escape sequences in the style of C are also allowed. @xref{C
79a6e687 12508Constants, ,C and C@t{++} Constants}, for a brief explanation of escape
c906108c
SS
12509sequences.
12510
12511@item
12512Enumerated constants consist of an enumerated identifier.
12513
12514@item
12515Boolean constants consist of the identifiers @code{TRUE} and
12516@code{FALSE}.
12517
12518@item
12519Pointer constants consist of integral values only.
12520
12521@item
12522Set constants are not yet supported.
12523@end itemize
12524
72019c9c
GM
12525@node M2 Types
12526@subsubsection Modula-2 Types
12527@cindex Modula-2 types
12528
12529Currently @value{GDBN} can print the following data types in Modula-2
12530syntax: array types, record types, set types, pointer types, procedure
12531types, enumerated types, subrange types and base types. You can also
12532print the contents of variables declared using these type.
12533This section gives a number of simple source code examples together with
12534sample @value{GDBN} sessions.
12535
12536The first example contains the following section of code:
12537
12538@smallexample
12539VAR
12540 s: SET OF CHAR ;
12541 r: [20..40] ;
12542@end smallexample
12543
12544@noindent
12545and you can request @value{GDBN} to interrogate the type and value of
12546@code{r} and @code{s}.
12547
12548@smallexample
12549(@value{GDBP}) print s
12550@{'A'..'C', 'Z'@}
12551(@value{GDBP}) ptype s
12552SET OF CHAR
12553(@value{GDBP}) print r
1255421
12555(@value{GDBP}) ptype r
12556[20..40]
12557@end smallexample
12558
12559@noindent
12560Likewise if your source code declares @code{s} as:
12561
12562@smallexample
12563VAR
12564 s: SET ['A'..'Z'] ;
12565@end smallexample
12566
12567@noindent
12568then you may query the type of @code{s} by:
12569
12570@smallexample
12571(@value{GDBP}) ptype s
12572type = SET ['A'..'Z']
12573@end smallexample
12574
12575@noindent
12576Note that at present you cannot interactively manipulate set
12577expressions using the debugger.
12578
12579The following example shows how you might declare an array in Modula-2
12580and how you can interact with @value{GDBN} to print its type and contents:
12581
12582@smallexample
12583VAR
12584 s: ARRAY [-10..10] OF CHAR ;
12585@end smallexample
12586
12587@smallexample
12588(@value{GDBP}) ptype s
12589ARRAY [-10..10] OF CHAR
12590@end smallexample
12591
12592Note that the array handling is not yet complete and although the type
12593is printed correctly, expression handling still assumes that all
12594arrays have a lower bound of zero and not @code{-10} as in the example
844781a1 12595above.
72019c9c
GM
12596
12597Here are some more type related Modula-2 examples:
12598
12599@smallexample
12600TYPE
12601 colour = (blue, red, yellow, green) ;
12602 t = [blue..yellow] ;
12603VAR
12604 s: t ;
12605BEGIN
12606 s := blue ;
12607@end smallexample
12608
12609@noindent
12610The @value{GDBN} interaction shows how you can query the data type
12611and value of a variable.
12612
12613@smallexample
12614(@value{GDBP}) print s
12615$1 = blue
12616(@value{GDBP}) ptype t
12617type = [blue..yellow]
12618@end smallexample
12619
12620@noindent
12621In this example a Modula-2 array is declared and its contents
12622displayed. Observe that the contents are written in the same way as
12623their @code{C} counterparts.
12624
12625@smallexample
12626VAR
12627 s: ARRAY [1..5] OF CARDINAL ;
12628BEGIN
12629 s[1] := 1 ;
12630@end smallexample
12631
12632@smallexample
12633(@value{GDBP}) print s
12634$1 = @{1, 0, 0, 0, 0@}
12635(@value{GDBP}) ptype s
12636type = ARRAY [1..5] OF CARDINAL
12637@end smallexample
12638
12639The Modula-2 language interface to @value{GDBN} also understands
12640pointer types as shown in this example:
12641
12642@smallexample
12643VAR
12644 s: POINTER TO ARRAY [1..5] OF CARDINAL ;
12645BEGIN
12646 NEW(s) ;
12647 s^[1] := 1 ;
12648@end smallexample
12649
12650@noindent
12651and you can request that @value{GDBN} describes the type of @code{s}.
12652
12653@smallexample
12654(@value{GDBP}) ptype s
12655type = POINTER TO ARRAY [1..5] OF CARDINAL
12656@end smallexample
12657
12658@value{GDBN} handles compound types as we can see in this example.
12659Here we combine array types, record types, pointer types and subrange
12660types:
12661
12662@smallexample
12663TYPE
12664 foo = RECORD
12665 f1: CARDINAL ;
12666 f2: CHAR ;
12667 f3: myarray ;
12668 END ;
12669
12670 myarray = ARRAY myrange OF CARDINAL ;
12671 myrange = [-2..2] ;
12672VAR
12673 s: POINTER TO ARRAY myrange OF foo ;
12674@end smallexample
12675
12676@noindent
12677and you can ask @value{GDBN} to describe the type of @code{s} as shown
12678below.
12679
12680@smallexample
12681(@value{GDBP}) ptype s
12682type = POINTER TO ARRAY [-2..2] OF foo = RECORD
12683 f1 : CARDINAL;
12684 f2 : CHAR;
12685 f3 : ARRAY [-2..2] OF CARDINAL;
12686END
12687@end smallexample
12688
6d2ebf8b 12689@node M2 Defaults
79a6e687 12690@subsubsection Modula-2 Defaults
c906108c
SS
12691@cindex Modula-2 defaults
12692
12693If type and range checking are set automatically by @value{GDBN}, they
12694both default to @code{on} whenever the working language changes to
d4f3574e 12695Modula-2. This happens regardless of whether you or @value{GDBN}
c906108c
SS
12696selected the working language.
12697
12698If you allow @value{GDBN} to set the language automatically, then entering
12699code compiled from a file whose name ends with @file{.mod} sets the
79a6e687
BW
12700working language to Modula-2. @xref{Automatically, ,Having @value{GDBN}
12701Infer the Source Language}, for further details.
c906108c 12702
6d2ebf8b 12703@node Deviations
79a6e687 12704@subsubsection Deviations from Standard Modula-2
c906108c
SS
12705@cindex Modula-2, deviations from
12706
12707A few changes have been made to make Modula-2 programs easier to debug.
12708This is done primarily via loosening its type strictness:
12709
12710@itemize @bullet
12711@item
12712Unlike in standard Modula-2, pointer constants can be formed by
12713integers. This allows you to modify pointer variables during
12714debugging. (In standard Modula-2, the actual address contained in a
12715pointer variable is hidden from you; it can only be modified
12716through direct assignment to another pointer variable or expression that
12717returned a pointer.)
12718
12719@item
12720C escape sequences can be used in strings and characters to represent
12721non-printable characters. @value{GDBN} prints out strings with these
12722escape sequences embedded. Single non-printable characters are
12723printed using the @samp{CHR(@var{nnn})} format.
12724
12725@item
12726The assignment operator (@code{:=}) returns the value of its right-hand
12727argument.
12728
12729@item
12730All built-in procedures both modify @emph{and} return their argument.
12731@end itemize
12732
6d2ebf8b 12733@node M2 Checks
79a6e687 12734@subsubsection Modula-2 Type and Range Checks
c906108c
SS
12735@cindex Modula-2 checks
12736
12737@quotation
12738@emph{Warning:} in this release, @value{GDBN} does not yet perform type or
12739range checking.
12740@end quotation
12741@c FIXME remove warning when type/range checks added
12742
12743@value{GDBN} considers two Modula-2 variables type equivalent if:
12744
12745@itemize @bullet
12746@item
12747They are of types that have been declared equivalent via a @code{TYPE
12748@var{t1} = @var{t2}} statement
12749
12750@item
12751They have been declared on the same line. (Note: This is true of the
12752@sc{gnu} Modula-2 compiler, but it may not be true of other compilers.)
12753@end itemize
12754
12755As long as type checking is enabled, any attempt to combine variables
12756whose types are not equivalent is an error.
12757
12758Range checking is done on all mathematical operations, assignment, array
12759index bounds, and all built-in functions and procedures.
12760
6d2ebf8b 12761@node M2 Scope
79a6e687 12762@subsubsection The Scope Operators @code{::} and @code{.}
c906108c 12763@cindex scope
41afff9a 12764@cindex @code{.}, Modula-2 scope operator
c906108c
SS
12765@cindex colon, doubled as scope operator
12766@ifinfo
41afff9a 12767@vindex colon-colon@r{, in Modula-2}
c906108c
SS
12768@c Info cannot handle :: but TeX can.
12769@end ifinfo
a67ec3f4 12770@ifnotinfo
41afff9a 12771@vindex ::@r{, in Modula-2}
a67ec3f4 12772@end ifnotinfo
c906108c
SS
12773
12774There are a few subtle differences between the Modula-2 scope operator
12775(@code{.}) and the @value{GDBN} scope operator (@code{::}). The two have
12776similar syntax:
12777
474c8240 12778@smallexample
c906108c
SS
12779
12780@var{module} . @var{id}
12781@var{scope} :: @var{id}
474c8240 12782@end smallexample
c906108c
SS
12783
12784@noindent
12785where @var{scope} is the name of a module or a procedure,
12786@var{module} the name of a module, and @var{id} is any declared
12787identifier within your program, except another module.
12788
12789Using the @code{::} operator makes @value{GDBN} search the scope
12790specified by @var{scope} for the identifier @var{id}. If it is not
12791found in the specified scope, then @value{GDBN} searches all scopes
12792enclosing the one specified by @var{scope}.
12793
12794Using the @code{.} operator makes @value{GDBN} search the current scope for
12795the identifier specified by @var{id} that was imported from the
12796definition module specified by @var{module}. With this operator, it is
12797an error if the identifier @var{id} was not imported from definition
12798module @var{module}, or if @var{id} is not an identifier in
12799@var{module}.
12800
6d2ebf8b 12801@node GDB/M2
c906108c
SS
12802@subsubsection @value{GDBN} and Modula-2
12803
12804Some @value{GDBN} commands have little use when debugging Modula-2 programs.
12805Five subcommands of @code{set print} and @code{show print} apply
b37052ae 12806specifically to C and C@t{++}: @samp{vtbl}, @samp{demangle},
c906108c 12807@samp{asm-demangle}, @samp{object}, and @samp{union}. The first four
b37052ae 12808apply to C@t{++}, and the last to the C @code{union} type, which has no direct
c906108c
SS
12809analogue in Modula-2.
12810
12811The @code{@@} operator (@pxref{Expressions, ,Expressions}), while available
d4f3574e 12812with any language, is not useful with Modula-2. Its
c906108c 12813intent is to aid the debugging of @dfn{dynamic arrays}, which cannot be
b37052ae 12814created in Modula-2 as they can in C or C@t{++}. However, because an
c906108c 12815address can be specified by an integral constant, the construct
d4f3574e 12816@samp{@{@var{type}@}@var{adrexp}} is still useful.
c906108c
SS
12817
12818@cindex @code{#} in Modula-2
12819In @value{GDBN} scripts, the Modula-2 inequality operator @code{#} is
12820interpreted as the beginning of a comment. Use @code{<>} instead.
c906108c 12821
e07c999f
PH
12822@node Ada
12823@subsection Ada
12824@cindex Ada
12825
12826The extensions made to @value{GDBN} for Ada only support
12827output from the @sc{gnu} Ada (GNAT) compiler.
12828Other Ada compilers are not currently supported, and
12829attempting to debug executables produced by them is most likely
12830to be difficult.
12831
12832
12833@cindex expressions in Ada
12834@menu
12835* Ada Mode Intro:: General remarks on the Ada syntax
12836 and semantics supported by Ada mode
12837 in @value{GDBN}.
12838* Omissions from Ada:: Restrictions on the Ada expression syntax.
12839* Additions to Ada:: Extensions of the Ada expression syntax.
12840* Stopping Before Main Program:: Debugging the program during elaboration.
20924a55
JB
12841* Ada Tasks:: Listing and setting breakpoints in tasks.
12842* Ada Tasks and Core Files:: Tasking Support when Debugging Core Files
e07c999f
PH
12843* Ada Glitches:: Known peculiarities of Ada mode.
12844@end menu
12845
12846@node Ada Mode Intro
12847@subsubsection Introduction
12848@cindex Ada mode, general
12849
12850The Ada mode of @value{GDBN} supports a fairly large subset of Ada expression
12851syntax, with some extensions.
12852The philosophy behind the design of this subset is
12853
12854@itemize @bullet
12855@item
12856That @value{GDBN} should provide basic literals and access to operations for
12857arithmetic, dereferencing, field selection, indexing, and subprogram calls,
12858leaving more sophisticated computations to subprograms written into the
12859program (which therefore may be called from @value{GDBN}).
12860
12861@item
12862That type safety and strict adherence to Ada language restrictions
12863are not particularly important to the @value{GDBN} user.
12864
12865@item
12866That brevity is important to the @value{GDBN} user.
12867@end itemize
12868
f3a2dd1a
JB
12869Thus, for brevity, the debugger acts as if all names declared in
12870user-written packages are directly visible, even if they are not visible
12871according to Ada rules, thus making it unnecessary to fully qualify most
12872names with their packages, regardless of context. Where this causes
12873ambiguity, @value{GDBN} asks the user's intent.
e07c999f
PH
12874
12875The debugger will start in Ada mode if it detects an Ada main program.
12876As for other languages, it will enter Ada mode when stopped in a program that
12877was translated from an Ada source file.
12878
12879While in Ada mode, you may use `@t{--}' for comments. This is useful
12880mostly for documenting command files. The standard @value{GDBN} comment
12881(@samp{#}) still works at the beginning of a line in Ada mode, but not in the
12882middle (to allow based literals).
12883
12884The debugger supports limited overloading. Given a subprogram call in which
12885the function symbol has multiple definitions, it will use the number of
12886actual parameters and some information about their types to attempt to narrow
12887the set of definitions. It also makes very limited use of context, preferring
12888procedures to functions in the context of the @code{call} command, and
12889functions to procedures elsewhere.
12890
12891@node Omissions from Ada
12892@subsubsection Omissions from Ada
12893@cindex Ada, omissions from
12894
12895Here are the notable omissions from the subset:
12896
12897@itemize @bullet
12898@item
12899Only a subset of the attributes are supported:
12900
12901@itemize @minus
12902@item
12903@t{'First}, @t{'Last}, and @t{'Length}
12904 on array objects (not on types and subtypes).
12905
12906@item
12907@t{'Min} and @t{'Max}.
12908
12909@item
12910@t{'Pos} and @t{'Val}.
12911
12912@item
12913@t{'Tag}.
12914
12915@item
12916@t{'Range} on array objects (not subtypes), but only as the right
12917operand of the membership (@code{in}) operator.
12918
12919@item
12920@t{'Access}, @t{'Unchecked_Access}, and
12921@t{'Unrestricted_Access} (a GNAT extension).
12922
12923@item
12924@t{'Address}.
12925@end itemize
12926
12927@item
12928The names in
12929@code{Characters.Latin_1} are not available and
12930concatenation is not implemented. Thus, escape characters in strings are
12931not currently available.
12932
12933@item
12934Equality tests (@samp{=} and @samp{/=}) on arrays test for bitwise
12935equality of representations. They will generally work correctly
12936for strings and arrays whose elements have integer or enumeration types.
12937They may not work correctly for arrays whose element
12938types have user-defined equality, for arrays of real values
12939(in particular, IEEE-conformant floating point, because of negative
12940zeroes and NaNs), and for arrays whose elements contain unused bits with
12941indeterminate values.
12942
12943@item
12944The other component-by-component array operations (@code{and}, @code{or},
12945@code{xor}, @code{not}, and relational tests other than equality)
12946are not implemented.
12947
12948@item
860701dc
PH
12949@cindex array aggregates (Ada)
12950@cindex record aggregates (Ada)
12951@cindex aggregates (Ada)
12952There is limited support for array and record aggregates. They are
12953permitted only on the right sides of assignments, as in these examples:
12954
12955@smallexample
077e0a52
JB
12956(@value{GDBP}) set An_Array := (1, 2, 3, 4, 5, 6)
12957(@value{GDBP}) set An_Array := (1, others => 0)
12958(@value{GDBP}) set An_Array := (0|4 => 1, 1..3 => 2, 5 => 6)
12959(@value{GDBP}) set A_2D_Array := ((1, 2, 3), (4, 5, 6), (7, 8, 9))
12960(@value{GDBP}) set A_Record := (1, "Peter", True);
12961(@value{GDBP}) set A_Record := (Name => "Peter", Id => 1, Alive => True)
860701dc
PH
12962@end smallexample
12963
12964Changing a
12965discriminant's value by assigning an aggregate has an
12966undefined effect if that discriminant is used within the record.
12967However, you can first modify discriminants by directly assigning to
12968them (which normally would not be allowed in Ada), and then performing an
12969aggregate assignment. For example, given a variable @code{A_Rec}
12970declared to have a type such as:
12971
12972@smallexample
12973type Rec (Len : Small_Integer := 0) is record
12974 Id : Integer;
12975 Vals : IntArray (1 .. Len);
12976end record;
12977@end smallexample
12978
12979you can assign a value with a different size of @code{Vals} with two
12980assignments:
12981
12982@smallexample
077e0a52
JB
12983(@value{GDBP}) set A_Rec.Len := 4
12984(@value{GDBP}) set A_Rec := (Id => 42, Vals => (1, 2, 3, 4))
860701dc
PH
12985@end smallexample
12986
12987As this example also illustrates, @value{GDBN} is very loose about the usual
12988rules concerning aggregates. You may leave out some of the
12989components of an array or record aggregate (such as the @code{Len}
12990component in the assignment to @code{A_Rec} above); they will retain their
12991original values upon assignment. You may freely use dynamic values as
12992indices in component associations. You may even use overlapping or
12993redundant component associations, although which component values are
12994assigned in such cases is not defined.
e07c999f
PH
12995
12996@item
12997Calls to dispatching subprograms are not implemented.
12998
12999@item
13000The overloading algorithm is much more limited (i.e., less selective)
ae21e955
BW
13001than that of real Ada. It makes only limited use of the context in
13002which a subexpression appears to resolve its meaning, and it is much
13003looser in its rules for allowing type matches. As a result, some
13004function calls will be ambiguous, and the user will be asked to choose
13005the proper resolution.
e07c999f
PH
13006
13007@item
13008The @code{new} operator is not implemented.
13009
13010@item
13011Entry calls are not implemented.
13012
13013@item
13014Aside from printing, arithmetic operations on the native VAX floating-point
13015formats are not supported.
13016
13017@item
13018It is not possible to slice a packed array.
158c7665
PH
13019
13020@item
13021The names @code{True} and @code{False}, when not part of a qualified name,
13022are interpreted as if implicitly prefixed by @code{Standard}, regardless of
13023context.
13024Should your program
13025redefine these names in a package or procedure (at best a dubious practice),
13026you will have to use fully qualified names to access their new definitions.
e07c999f
PH
13027@end itemize
13028
13029@node Additions to Ada
13030@subsubsection Additions to Ada
13031@cindex Ada, deviations from
13032
13033As it does for other languages, @value{GDBN} makes certain generic
13034extensions to Ada (@pxref{Expressions}):
13035
13036@itemize @bullet
13037@item
ae21e955
BW
13038If the expression @var{E} is a variable residing in memory (typically
13039a local variable or array element) and @var{N} is a positive integer,
13040then @code{@var{E}@@@var{N}} displays the values of @var{E} and the
13041@var{N}-1 adjacent variables following it in memory as an array. In
13042Ada, this operator is generally not necessary, since its prime use is
13043in displaying parts of an array, and slicing will usually do this in
13044Ada. However, there are occasional uses when debugging programs in
13045which certain debugging information has been optimized away.
e07c999f
PH
13046
13047@item
ae21e955
BW
13048@code{@var{B}::@var{var}} means ``the variable named @var{var} that
13049appears in function or file @var{B}.'' When @var{B} is a file name,
13050you must typically surround it in single quotes.
e07c999f
PH
13051
13052@item
13053The expression @code{@{@var{type}@} @var{addr}} means ``the variable of type
13054@var{type} that appears at address @var{addr}.''
13055
13056@item
13057A name starting with @samp{$} is a convenience variable
13058(@pxref{Convenience Vars}) or a machine register (@pxref{Registers}).
13059@end itemize
13060
ae21e955
BW
13061In addition, @value{GDBN} provides a few other shortcuts and outright
13062additions specific to Ada:
e07c999f
PH
13063
13064@itemize @bullet
13065@item
13066The assignment statement is allowed as an expression, returning
13067its right-hand operand as its value. Thus, you may enter
13068
13069@smallexample
077e0a52
JB
13070(@value{GDBP}) set x := y + 3
13071(@value{GDBP}) print A(tmp := y + 1)
e07c999f
PH
13072@end smallexample
13073
13074@item
13075The semicolon is allowed as an ``operator,'' returning as its value
13076the value of its right-hand operand.
13077This allows, for example,
13078complex conditional breaks:
13079
13080@smallexample
077e0a52
JB
13081(@value{GDBP}) break f
13082(@value{GDBP}) condition 1 (report(i); k += 1; A(k) > 100)
e07c999f
PH
13083@end smallexample
13084
13085@item
13086Rather than use catenation and symbolic character names to introduce special
13087characters into strings, one may instead use a special bracket notation,
13088which is also used to print strings. A sequence of characters of the form
13089@samp{["@var{XX}"]} within a string or character literal denotes the
13090(single) character whose numeric encoding is @var{XX} in hexadecimal. The
13091sequence of characters @samp{["""]} also denotes a single quotation mark
13092in strings. For example,
13093@smallexample
13094 "One line.["0a"]Next line.["0a"]"
13095@end smallexample
13096@noindent
ae21e955
BW
13097contains an ASCII newline character (@code{Ada.Characters.Latin_1.LF})
13098after each period.
e07c999f
PH
13099
13100@item
13101The subtype used as a prefix for the attributes @t{'Pos}, @t{'Min}, and
13102@t{'Max} is optional (and is ignored in any case). For example, it is valid
13103to write
13104
13105@smallexample
077e0a52 13106(@value{GDBP}) print 'max(x, y)
e07c999f
PH
13107@end smallexample
13108
13109@item
13110When printing arrays, @value{GDBN} uses positional notation when the
13111array has a lower bound of 1, and uses a modified named notation otherwise.
ae21e955
BW
13112For example, a one-dimensional array of three integers with a lower bound
13113of 3 might print as
e07c999f
PH
13114
13115@smallexample
13116(3 => 10, 17, 1)
13117@end smallexample
13118
13119@noindent
13120That is, in contrast to valid Ada, only the first component has a @code{=>}
13121clause.
13122
13123@item
13124You may abbreviate attributes in expressions with any unique,
13125multi-character subsequence of
13126their names (an exact match gets preference).
13127For example, you may use @t{a'len}, @t{a'gth}, or @t{a'lh}
13128in place of @t{a'length}.
13129
13130@item
13131@cindex quoting Ada internal identifiers
13132Since Ada is case-insensitive, the debugger normally maps identifiers you type
13133to lower case. The GNAT compiler uses upper-case characters for
13134some of its internal identifiers, which are normally of no interest to users.
13135For the rare occasions when you actually have to look at them,
13136enclose them in angle brackets to avoid the lower-case mapping.
13137For example,
13138@smallexample
077e0a52 13139(@value{GDBP}) print <JMPBUF_SAVE>[0]
e07c999f
PH
13140@end smallexample
13141
13142@item
13143Printing an object of class-wide type or dereferencing an
13144access-to-class-wide value will display all the components of the object's
13145specific type (as indicated by its run-time tag). Likewise, component
13146selection on such a value will operate on the specific type of the
13147object.
13148
13149@end itemize
13150
13151@node Stopping Before Main Program
13152@subsubsection Stopping at the Very Beginning
13153
13154@cindex breakpointing Ada elaboration code
13155It is sometimes necessary to debug the program during elaboration, and
13156before reaching the main procedure.
13157As defined in the Ada Reference
13158Manual, the elaboration code is invoked from a procedure called
13159@code{adainit}. To run your program up to the beginning of
13160elaboration, simply use the following two commands:
13161@code{tbreak adainit} and @code{run}.
13162
20924a55
JB
13163@node Ada Tasks
13164@subsubsection Extensions for Ada Tasks
13165@cindex Ada, tasking
13166
13167Support for Ada tasks is analogous to that for threads (@pxref{Threads}).
13168@value{GDBN} provides the following task-related commands:
13169
13170@table @code
13171@kindex info tasks
13172@item info tasks
13173This command shows a list of current Ada tasks, as in the following example:
13174
13175
13176@smallexample
13177@iftex
13178@leftskip=0.5cm
13179@end iftex
13180(@value{GDBP}) info tasks
13181 ID TID P-ID Pri State Name
13182 1 8088000 0 15 Child Activation Wait main_task
13183 2 80a4000 1 15 Accept Statement b
13184 3 809a800 1 15 Child Activation Wait a
32cd1edc 13185* 4 80ae800 3 15 Runnable c
20924a55
JB
13186
13187@end smallexample
13188
13189@noindent
13190In this listing, the asterisk before the last task indicates it to be the
13191task currently being inspected.
13192
13193@table @asis
13194@item ID
13195Represents @value{GDBN}'s internal task number.
13196
13197@item TID
13198The Ada task ID.
13199
13200@item P-ID
13201The parent's task ID (@value{GDBN}'s internal task number).
13202
13203@item Pri
13204The base priority of the task.
13205
13206@item State
13207Current state of the task.
13208
13209@table @code
13210@item Unactivated
13211The task has been created but has not been activated. It cannot be
13212executing.
13213
20924a55
JB
13214@item Runnable
13215The task is not blocked for any reason known to Ada. (It may be waiting
13216for a mutex, though.) It is conceptually "executing" in normal mode.
13217
13218@item Terminated
13219The task is terminated, in the sense of ARM 9.3 (5). Any dependents
13220that were waiting on terminate alternatives have been awakened and have
13221terminated themselves.
13222
13223@item Child Activation Wait
13224The task is waiting for created tasks to complete activation.
13225
13226@item Accept Statement
13227The task is waiting on an accept or selective wait statement.
13228
13229@item Waiting on entry call
13230The task is waiting on an entry call.
13231
13232@item Async Select Wait
13233The task is waiting to start the abortable part of an asynchronous
13234select statement.
13235
13236@item Delay Sleep
13237The task is waiting on a select statement with only a delay
13238alternative open.
13239
13240@item Child Termination Wait
13241The task is sleeping having completed a master within itself, and is
13242waiting for the tasks dependent on that master to become terminated or
13243waiting on a terminate Phase.
13244
13245@item Wait Child in Term Alt
13246The task is sleeping waiting for tasks on terminate alternatives to
13247finish terminating.
13248
13249@item Accepting RV with @var{taskno}
13250The task is accepting a rendez-vous with the task @var{taskno}.
13251@end table
13252
13253@item Name
13254Name of the task in the program.
13255
13256@end table
13257
13258@kindex info task @var{taskno}
13259@item info task @var{taskno}
13260This command shows detailled informations on the specified task, as in
13261the following example:
13262@smallexample
13263@iftex
13264@leftskip=0.5cm
13265@end iftex
13266(@value{GDBP}) info tasks
13267 ID TID P-ID Pri State Name
13268 1 8077880 0 15 Child Activation Wait main_task
32cd1edc 13269* 2 807c468 1 15 Runnable task_1
20924a55
JB
13270(@value{GDBP}) info task 2
13271Ada Task: 0x807c468
13272Name: task_1
13273Thread: 0x807f378
13274Parent: 1 (main_task)
13275Base Priority: 15
13276State: Runnable
13277@end smallexample
13278
13279@item task
13280@kindex task@r{ (Ada)}
13281@cindex current Ada task ID
13282This command prints the ID of the current task.
13283
13284@smallexample
13285@iftex
13286@leftskip=0.5cm
13287@end iftex
13288(@value{GDBP}) info tasks
13289 ID TID P-ID Pri State Name
13290 1 8077870 0 15 Child Activation Wait main_task
32cd1edc 13291* 2 807c458 1 15 Runnable t
20924a55
JB
13292(@value{GDBP}) task
13293[Current task is 2]
13294@end smallexample
13295
13296@item task @var{taskno}
13297@cindex Ada task switching
13298This command is like the @code{thread @var{threadno}}
13299command (@pxref{Threads}). It switches the context of debugging
13300from the current task to the given task.
13301
13302@smallexample
13303@iftex
13304@leftskip=0.5cm
13305@end iftex
13306(@value{GDBP}) info tasks
13307 ID TID P-ID Pri State Name
13308 1 8077870 0 15 Child Activation Wait main_task
32cd1edc 13309* 2 807c458 1 15 Runnable t
20924a55
JB
13310(@value{GDBP}) task 1
13311[Switching to task 1]
13312#0 0x8067726 in pthread_cond_wait ()
13313(@value{GDBP}) bt
13314#0 0x8067726 in pthread_cond_wait ()
13315#1 0x8056714 in system.os_interface.pthread_cond_wait ()
13316#2 0x805cb63 in system.task_primitives.operations.sleep ()
13317#3 0x806153e in system.tasking.stages.activate_tasks ()
13318#4 0x804aacc in un () at un.adb:5
13319@end smallexample
13320
45ac276d
JB
13321@item break @var{linespec} task @var{taskno}
13322@itemx break @var{linespec} task @var{taskno} if @dots{}
13323@cindex breakpoints and tasks, in Ada
13324@cindex task breakpoints, in Ada
13325@kindex break @dots{} task @var{taskno}@r{ (Ada)}
13326These commands are like the @code{break @dots{} thread @dots{}}
13327command (@pxref{Thread Stops}).
13328@var{linespec} specifies source lines, as described
13329in @ref{Specify Location}.
13330
13331Use the qualifier @samp{task @var{taskno}} with a breakpoint command
13332to specify that you only want @value{GDBN} to stop the program when a
13333particular Ada task reaches this breakpoint. @var{taskno} is one of the
13334numeric task identifiers assigned by @value{GDBN}, shown in the first
13335column of the @samp{info tasks} display.
13336
13337If you do not specify @samp{task @var{taskno}} when you set a
13338breakpoint, the breakpoint applies to @emph{all} tasks of your
13339program.
13340
13341You can use the @code{task} qualifier on conditional breakpoints as
13342well; in this case, place @samp{task @var{taskno}} before the
13343breakpoint condition (before the @code{if}).
13344
13345For example,
13346
13347@smallexample
13348@iftex
13349@leftskip=0.5cm
13350@end iftex
13351(@value{GDBP}) info tasks
13352 ID TID P-ID Pri State Name
13353 1 140022020 0 15 Child Activation Wait main_task
13354 2 140045060 1 15 Accept/Select Wait t2
13355 3 140044840 1 15 Runnable t1
13356* 4 140056040 1 15 Runnable t3
13357(@value{GDBP}) b 15 task 2
13358Breakpoint 5 at 0x120044cb0: file test_task_debug.adb, line 15.
13359(@value{GDBP}) cont
13360Continuing.
13361task # 1 running
13362task # 2 running
13363
13364Breakpoint 5, test_task_debug () at test_task_debug.adb:15
1336515 flush;
13366(@value{GDBP}) info tasks
13367 ID TID P-ID Pri State Name
13368 1 140022020 0 15 Child Activation Wait main_task
13369* 2 140045060 1 15 Runnable t2
13370 3 140044840 1 15 Runnable t1
13371 4 140056040 1 15 Delay Sleep t3
13372@end smallexample
20924a55
JB
13373@end table
13374
13375@node Ada Tasks and Core Files
13376@subsubsection Tasking Support when Debugging Core Files
13377@cindex Ada tasking and core file debugging
13378
13379When inspecting a core file, as opposed to debugging a live program,
13380tasking support may be limited or even unavailable, depending on
13381the platform being used.
13382For instance, on x86-linux, the list of tasks is available, but task
13383switching is not supported. On Tru64, however, task switching will work
13384as usual.
13385
13386On certain platforms, including Tru64, the debugger needs to perform some
13387memory writes in order to provide Ada tasking support. When inspecting
13388a core file, this means that the core file must be opened with read-write
13389privileges, using the command @samp{"set write on"} (@pxref{Patching}).
13390Under these circumstances, you should make a backup copy of the core
13391file before inspecting it with @value{GDBN}.
13392
e07c999f
PH
13393@node Ada Glitches
13394@subsubsection Known Peculiarities of Ada Mode
13395@cindex Ada, problems
13396
13397Besides the omissions listed previously (@pxref{Omissions from Ada}),
13398we know of several problems with and limitations of Ada mode in
13399@value{GDBN},
13400some of which will be fixed with planned future releases of the debugger
13401and the GNU Ada compiler.
13402
13403@itemize @bullet
13404@item
13405Currently, the debugger
13406has insufficient information to determine whether certain pointers represent
13407pointers to objects or the objects themselves.
13408Thus, the user may have to tack an extra @code{.all} after an expression
13409to get it printed properly.
13410
13411@item
13412Static constants that the compiler chooses not to materialize as objects in
13413storage are invisible to the debugger.
13414
13415@item
13416Named parameter associations in function argument lists are ignored (the
13417argument lists are treated as positional).
13418
13419@item
13420Many useful library packages are currently invisible to the debugger.
13421
13422@item
13423Fixed-point arithmetic, conversions, input, and output is carried out using
13424floating-point arithmetic, and may give results that only approximate those on
13425the host machine.
13426
e07c999f
PH
13427@item
13428The GNAT compiler never generates the prefix @code{Standard} for any of
13429the standard symbols defined by the Ada language. @value{GDBN} knows about
13430this: it will strip the prefix from names when you use it, and will never
13431look for a name you have so qualified among local symbols, nor match against
13432symbols in other packages or subprograms. If you have
13433defined entities anywhere in your program other than parameters and
13434local variables whose simple names match names in @code{Standard},
13435GNAT's lack of qualification here can cause confusion. When this happens,
13436you can usually resolve the confusion
13437by qualifying the problematic names with package
13438@code{Standard} explicitly.
13439@end itemize
13440
95433b34
JB
13441Older versions of the compiler sometimes generate erroneous debugging
13442information, resulting in the debugger incorrectly printing the value
13443of affected entities. In some cases, the debugger is able to work
13444around an issue automatically. In other cases, the debugger is able
13445to work around the issue, but the work-around has to be specifically
13446enabled.
13447
13448@kindex set ada trust-PAD-over-XVS
13449@kindex show ada trust-PAD-over-XVS
13450@table @code
13451
13452@item set ada trust-PAD-over-XVS on
13453Configure GDB to strictly follow the GNAT encoding when computing the
13454value of Ada entities, particularly when @code{PAD} and @code{PAD___XVS}
13455types are involved (see @code{ada/exp_dbug.ads} in the GCC sources for
13456a complete description of the encoding used by the GNAT compiler).
13457This is the default.
13458
13459@item set ada trust-PAD-over-XVS off
13460This is related to the encoding using by the GNAT compiler. If @value{GDBN}
13461sometimes prints the wrong value for certain entities, changing @code{ada
13462trust-PAD-over-XVS} to @code{off} activates a work-around which may fix
13463the issue. It is always safe to set @code{ada trust-PAD-over-XVS} to
13464@code{off}, but this incurs a slight performance penalty, so it is
13465recommended to leave this setting to @code{on} unless necessary.
13466
13467@end table
13468
79a6e687
BW
13469@node Unsupported Languages
13470@section Unsupported Languages
4e562065
JB
13471
13472@cindex unsupported languages
13473@cindex minimal language
13474In addition to the other fully-supported programming languages,
13475@value{GDBN} also provides a pseudo-language, called @code{minimal}.
13476It does not represent a real programming language, but provides a set
13477of capabilities close to what the C or assembly languages provide.
13478This should allow most simple operations to be performed while debugging
13479an application that uses a language currently not supported by @value{GDBN}.
13480
13481If the language is set to @code{auto}, @value{GDBN} will automatically
13482select this language if the current frame corresponds to an unsupported
13483language.
13484
6d2ebf8b 13485@node Symbols
c906108c
SS
13486@chapter Examining the Symbol Table
13487
d4f3574e 13488The commands described in this chapter allow you to inquire about the
c906108c
SS
13489symbols (names of variables, functions and types) defined in your
13490program. This information is inherent in the text of your program and
13491does not change as your program executes. @value{GDBN} finds it in your
13492program's symbol table, in the file indicated when you started @value{GDBN}
79a6e687
BW
13493(@pxref{File Options, ,Choosing Files}), or by one of the
13494file-management commands (@pxref{Files, ,Commands to Specify Files}).
c906108c
SS
13495
13496@cindex symbol names
13497@cindex names of symbols
13498@cindex quoting names
13499Occasionally, you may need to refer to symbols that contain unusual
13500characters, which @value{GDBN} ordinarily treats as word delimiters. The
13501most frequent case is in referring to static variables in other
79a6e687 13502source files (@pxref{Variables,,Program Variables}). File names
c906108c
SS
13503are recorded in object files as debugging symbols, but @value{GDBN} would
13504ordinarily parse a typical file name, like @file{foo.c}, as the three words
13505@samp{foo} @samp{.} @samp{c}. To allow @value{GDBN} to recognize
13506@samp{foo.c} as a single symbol, enclose it in single quotes; for example,
13507
474c8240 13508@smallexample
c906108c 13509p 'foo.c'::x
474c8240 13510@end smallexample
c906108c
SS
13511
13512@noindent
13513looks up the value of @code{x} in the scope of the file @file{foo.c}.
13514
13515@table @code
a8f24a35
EZ
13516@cindex case-insensitive symbol names
13517@cindex case sensitivity in symbol names
13518@kindex set case-sensitive
13519@item set case-sensitive on
13520@itemx set case-sensitive off
13521@itemx set case-sensitive auto
13522Normally, when @value{GDBN} looks up symbols, it matches their names
13523with case sensitivity determined by the current source language.
13524Occasionally, you may wish to control that. The command @code{set
13525case-sensitive} lets you do that by specifying @code{on} for
13526case-sensitive matches or @code{off} for case-insensitive ones. If
13527you specify @code{auto}, case sensitivity is reset to the default
13528suitable for the source language. The default is case-sensitive
13529matches for all languages except for Fortran, for which the default is
13530case-insensitive matches.
13531
9c16f35a
EZ
13532@kindex show case-sensitive
13533@item show case-sensitive
a8f24a35
EZ
13534This command shows the current setting of case sensitivity for symbols
13535lookups.
13536
c906108c 13537@kindex info address
b37052ae 13538@cindex address of a symbol
c906108c
SS
13539@item info address @var{symbol}
13540Describe where the data for @var{symbol} is stored. For a register
13541variable, this says which register it is kept in. For a non-register
13542local variable, this prints the stack-frame offset at which the variable
13543is always stored.
13544
13545Note the contrast with @samp{print &@var{symbol}}, which does not work
13546at all for a register variable, and for a stack local variable prints
13547the exact address of the current instantiation of the variable.
13548
3d67e040 13549@kindex info symbol
b37052ae 13550@cindex symbol from address
9c16f35a 13551@cindex closest symbol and offset for an address
3d67e040
EZ
13552@item info symbol @var{addr}
13553Print the name of a symbol which is stored at the address @var{addr}.
13554If no symbol is stored exactly at @var{addr}, @value{GDBN} prints the
13555nearest symbol and an offset from it:
13556
474c8240 13557@smallexample
3d67e040
EZ
13558(@value{GDBP}) info symbol 0x54320
13559_initialize_vx + 396 in section .text
474c8240 13560@end smallexample
3d67e040
EZ
13561
13562@noindent
13563This is the opposite of the @code{info address} command. You can use
13564it to find out the name of a variable or a function given its address.
13565
c14c28ba
PP
13566For dynamically linked executables, the name of executable or shared
13567library containing the symbol is also printed:
13568
13569@smallexample
13570(@value{GDBP}) info symbol 0x400225
13571_start + 5 in section .text of /tmp/a.out
13572(@value{GDBP}) info symbol 0x2aaaac2811cf
13573__read_nocancel + 6 in section .text of /usr/lib64/libc.so.6
13574@end smallexample
13575
c906108c 13576@kindex whatis
62f3a2ba
FF
13577@item whatis [@var{arg}]
13578Print the data type of @var{arg}, which can be either an expression or
13579a data type. With no argument, print the data type of @code{$}, the
13580last value in the value history. If @var{arg} is an expression, it is
13581not actually evaluated, and any side-effecting operations (such as
13582assignments or function calls) inside it do not take place. If
13583@var{arg} is a type name, it may be the name of a type or typedef, or
13584for C code it may have the form @samp{class @var{class-name}},
13585@samp{struct @var{struct-tag}}, @samp{union @var{union-tag}} or
13586@samp{enum @var{enum-tag}}.
c906108c
SS
13587@xref{Expressions, ,Expressions}.
13588
c906108c 13589@kindex ptype
62f3a2ba
FF
13590@item ptype [@var{arg}]
13591@code{ptype} accepts the same arguments as @code{whatis}, but prints a
13592detailed description of the type, instead of just the name of the type.
13593@xref{Expressions, ,Expressions}.
c906108c
SS
13594
13595For example, for this variable declaration:
13596
474c8240 13597@smallexample
c906108c 13598struct complex @{double real; double imag;@} v;
474c8240 13599@end smallexample
c906108c
SS
13600
13601@noindent
13602the two commands give this output:
13603
474c8240 13604@smallexample
c906108c
SS
13605@group
13606(@value{GDBP}) whatis v
13607type = struct complex
13608(@value{GDBP}) ptype v
13609type = struct complex @{
13610 double real;
13611 double imag;
13612@}
13613@end group
474c8240 13614@end smallexample
c906108c
SS
13615
13616@noindent
13617As with @code{whatis}, using @code{ptype} without an argument refers to
13618the type of @code{$}, the last value in the value history.
13619
ab1adacd
EZ
13620@cindex incomplete type
13621Sometimes, programs use opaque data types or incomplete specifications
13622of complex data structure. If the debug information included in the
13623program does not allow @value{GDBN} to display a full declaration of
13624the data type, it will say @samp{<incomplete type>}. For example,
13625given these declarations:
13626
13627@smallexample
13628 struct foo;
13629 struct foo *fooptr;
13630@end smallexample
13631
13632@noindent
13633but no definition for @code{struct foo} itself, @value{GDBN} will say:
13634
13635@smallexample
ddb50cd7 13636 (@value{GDBP}) ptype foo
ab1adacd
EZ
13637 $1 = <incomplete type>
13638@end smallexample
13639
13640@noindent
13641``Incomplete type'' is C terminology for data types that are not
13642completely specified.
13643
c906108c
SS
13644@kindex info types
13645@item info types @var{regexp}
13646@itemx info types
09d4efe1
EZ
13647Print a brief description of all types whose names match the regular
13648expression @var{regexp} (or all types in your program, if you supply
13649no argument). Each complete typename is matched as though it were a
13650complete line; thus, @samp{i type value} gives information on all
13651types in your program whose names include the string @code{value}, but
13652@samp{i type ^value$} gives information only on types whose complete
13653name is @code{value}.
c906108c
SS
13654
13655This command differs from @code{ptype} in two ways: first, like
13656@code{whatis}, it does not print a detailed description; second, it
13657lists all source files where a type is defined.
13658
b37052ae
EZ
13659@kindex info scope
13660@cindex local variables
09d4efe1 13661@item info scope @var{location}
b37052ae 13662List all the variables local to a particular scope. This command
09d4efe1
EZ
13663accepts a @var{location} argument---a function name, a source line, or
13664an address preceded by a @samp{*}, and prints all the variables local
2a25a5ba
EZ
13665to the scope defined by that location. (@xref{Specify Location}, for
13666details about supported forms of @var{location}.) For example:
b37052ae
EZ
13667
13668@smallexample
13669(@value{GDBP}) @b{info scope command_line_handler}
13670Scope for command_line_handler:
13671Symbol rl is an argument at stack/frame offset 8, length 4.
13672Symbol linebuffer is in static storage at address 0x150a18, length 4.
13673Symbol linelength is in static storage at address 0x150a1c, length 4.
13674Symbol p is a local variable in register $esi, length 4.
13675Symbol p1 is a local variable in register $ebx, length 4.
13676Symbol nline is a local variable in register $edx, length 4.
13677Symbol repeat is a local variable at frame offset -8, length 4.
13678@end smallexample
13679
f5c37c66
EZ
13680@noindent
13681This command is especially useful for determining what data to collect
13682during a @dfn{trace experiment}, see @ref{Tracepoint Actions,
13683collect}.
13684
c906108c
SS
13685@kindex info source
13686@item info source
919d772c
JB
13687Show information about the current source file---that is, the source file for
13688the function containing the current point of execution:
13689@itemize @bullet
13690@item
13691the name of the source file, and the directory containing it,
13692@item
13693the directory it was compiled in,
13694@item
13695its length, in lines,
13696@item
13697which programming language it is written in,
13698@item
13699whether the executable includes debugging information for that file, and
13700if so, what format the information is in (e.g., STABS, Dwarf 2, etc.), and
13701@item
13702whether the debugging information includes information about
13703preprocessor macros.
13704@end itemize
13705
c906108c
SS
13706
13707@kindex info sources
13708@item info sources
13709Print the names of all source files in your program for which there is
13710debugging information, organized into two lists: files whose symbols
13711have already been read, and files whose symbols will be read when needed.
13712
13713@kindex info functions
13714@item info functions
13715Print the names and data types of all defined functions.
13716
13717@item info functions @var{regexp}
13718Print the names and data types of all defined functions
13719whose names contain a match for regular expression @var{regexp}.
13720Thus, @samp{info fun step} finds all functions whose names
13721include @code{step}; @samp{info fun ^step} finds those whose names
b383017d 13722start with @code{step}. If a function name contains characters
c1468174 13723that conflict with the regular expression language (e.g.@:
1c5dfdad 13724@samp{operator*()}), they may be quoted with a backslash.
c906108c
SS
13725
13726@kindex info variables
13727@item info variables
0fe7935b 13728Print the names and data types of all variables that are defined
6ca652b0 13729outside of functions (i.e.@: excluding local variables).
c906108c
SS
13730
13731@item info variables @var{regexp}
13732Print the names and data types of all variables (except for local
13733variables) whose names contain a match for regular expression
13734@var{regexp}.
13735
b37303ee 13736@kindex info classes
721c2651 13737@cindex Objective-C, classes and selectors
b37303ee
AF
13738@item info classes
13739@itemx info classes @var{regexp}
13740Display all Objective-C classes in your program, or
13741(with the @var{regexp} argument) all those matching a particular regular
13742expression.
13743
13744@kindex info selectors
13745@item info selectors
13746@itemx info selectors @var{regexp}
13747Display all Objective-C selectors in your program, or
13748(with the @var{regexp} argument) all those matching a particular regular
13749expression.
13750
c906108c
SS
13751@ignore
13752This was never implemented.
13753@kindex info methods
13754@item info methods
13755@itemx info methods @var{regexp}
13756The @code{info methods} command permits the user to examine all defined
b37052ae
EZ
13757methods within C@t{++} program, or (with the @var{regexp} argument) a
13758specific set of methods found in the various C@t{++} classes. Many
13759C@t{++} classes provide a large number of methods. Thus, the output
c906108c
SS
13760from the @code{ptype} command can be overwhelming and hard to use. The
13761@code{info-methods} command filters the methods, printing only those
13762which match the regular-expression @var{regexp}.
13763@end ignore
13764
c906108c
SS
13765@cindex reloading symbols
13766Some systems allow individual object files that make up your program to
7a292a7a
SS
13767be replaced without stopping and restarting your program. For example,
13768in VxWorks you can simply recompile a defective object file and keep on
13769running. If you are running on one of these systems, you can allow
13770@value{GDBN} to reload the symbols for automatically relinked modules:
c906108c
SS
13771
13772@table @code
13773@kindex set symbol-reloading
13774@item set symbol-reloading on
13775Replace symbol definitions for the corresponding source file when an
13776object file with a particular name is seen again.
13777
13778@item set symbol-reloading off
6d2ebf8b
SS
13779Do not replace symbol definitions when encountering object files of the
13780same name more than once. This is the default state; if you are not
13781running on a system that permits automatic relinking of modules, you
13782should leave @code{symbol-reloading} off, since otherwise @value{GDBN}
13783may discard symbols when linking large programs, that may contain
13784several modules (from different directories or libraries) with the same
13785name.
c906108c
SS
13786
13787@kindex show symbol-reloading
13788@item show symbol-reloading
13789Show the current @code{on} or @code{off} setting.
13790@end table
c906108c 13791
9c16f35a 13792@cindex opaque data types
c906108c
SS
13793@kindex set opaque-type-resolution
13794@item set opaque-type-resolution on
13795Tell @value{GDBN} to resolve opaque types. An opaque type is a type
13796declared as a pointer to a @code{struct}, @code{class}, or
13797@code{union}---for example, @code{struct MyType *}---that is used in one
13798source file although the full declaration of @code{struct MyType} is in
13799another source file. The default is on.
13800
13801A change in the setting of this subcommand will not take effect until
13802the next time symbols for a file are loaded.
13803
13804@item set opaque-type-resolution off
13805Tell @value{GDBN} not to resolve opaque types. In this case, the type
13806is printed as follows:
13807@smallexample
13808@{<no data fields>@}
13809@end smallexample
13810
13811@kindex show opaque-type-resolution
13812@item show opaque-type-resolution
13813Show whether opaque types are resolved or not.
c906108c
SS
13814
13815@kindex maint print symbols
13816@cindex symbol dump
13817@kindex maint print psymbols
13818@cindex partial symbol dump
13819@item maint print symbols @var{filename}
13820@itemx maint print psymbols @var{filename}
13821@itemx maint print msymbols @var{filename}
13822Write a dump of debugging symbol data into the file @var{filename}.
13823These commands are used to debug the @value{GDBN} symbol-reading code. Only
13824symbols with debugging data are included. If you use @samp{maint print
13825symbols}, @value{GDBN} includes all the symbols for which it has already
13826collected full details: that is, @var{filename} reflects symbols for
13827only those files whose symbols @value{GDBN} has read. You can use the
13828command @code{info sources} to find out which files these are. If you
13829use @samp{maint print psymbols} instead, the dump shows information about
13830symbols that @value{GDBN} only knows partially---that is, symbols defined in
13831files that @value{GDBN} has skimmed, but not yet read completely. Finally,
13832@samp{maint print msymbols} dumps just the minimal symbol information
13833required for each object file from which @value{GDBN} has read some symbols.
79a6e687 13834@xref{Files, ,Commands to Specify Files}, for a discussion of how
c906108c 13835@value{GDBN} reads symbols (in the description of @code{symbol-file}).
44ea7b70 13836
5e7b2f39
JB
13837@kindex maint info symtabs
13838@kindex maint info psymtabs
44ea7b70
JB
13839@cindex listing @value{GDBN}'s internal symbol tables
13840@cindex symbol tables, listing @value{GDBN}'s internal
13841@cindex full symbol tables, listing @value{GDBN}'s internal
13842@cindex partial symbol tables, listing @value{GDBN}'s internal
5e7b2f39
JB
13843@item maint info symtabs @r{[} @var{regexp} @r{]}
13844@itemx maint info psymtabs @r{[} @var{regexp} @r{]}
44ea7b70
JB
13845
13846List the @code{struct symtab} or @code{struct partial_symtab}
13847structures whose names match @var{regexp}. If @var{regexp} is not
13848given, list them all. The output includes expressions which you can
13849copy into a @value{GDBN} debugging this one to examine a particular
13850structure in more detail. For example:
13851
13852@smallexample
5e7b2f39 13853(@value{GDBP}) maint info psymtabs dwarf2read
44ea7b70
JB
13854@{ objfile /home/gnu/build/gdb/gdb
13855 ((struct objfile *) 0x82e69d0)
b383017d 13856 @{ psymtab /home/gnu/src/gdb/dwarf2read.c
44ea7b70
JB
13857 ((struct partial_symtab *) 0x8474b10)
13858 readin no
13859 fullname (null)
13860 text addresses 0x814d3c8 -- 0x8158074
13861 globals (* (struct partial_symbol **) 0x8507a08 @@ 9)
13862 statics (* (struct partial_symbol **) 0x40e95b78 @@ 2882)
13863 dependencies (none)
13864 @}
13865@}
5e7b2f39 13866(@value{GDBP}) maint info symtabs
44ea7b70
JB
13867(@value{GDBP})
13868@end smallexample
13869@noindent
13870We see that there is one partial symbol table whose filename contains
13871the string @samp{dwarf2read}, belonging to the @samp{gdb} executable;
13872and we see that @value{GDBN} has not read in any symtabs yet at all.
13873If we set a breakpoint on a function, that will cause @value{GDBN} to
13874read the symtab for the compilation unit containing that function:
13875
13876@smallexample
13877(@value{GDBP}) break dwarf2_psymtab_to_symtab
13878Breakpoint 1 at 0x814e5da: file /home/gnu/src/gdb/dwarf2read.c,
13879line 1574.
5e7b2f39 13880(@value{GDBP}) maint info symtabs
b383017d 13881@{ objfile /home/gnu/build/gdb/gdb
44ea7b70 13882 ((struct objfile *) 0x82e69d0)
b383017d 13883 @{ symtab /home/gnu/src/gdb/dwarf2read.c
44ea7b70
JB
13884 ((struct symtab *) 0x86c1f38)
13885 dirname (null)
13886 fullname (null)
13887 blockvector ((struct blockvector *) 0x86c1bd0) (primary)
1b39d5c0 13888 linetable ((struct linetable *) 0x8370fa0)
44ea7b70
JB
13889 debugformat DWARF 2
13890 @}
13891@}
b383017d 13892(@value{GDBP})
44ea7b70 13893@end smallexample
c906108c
SS
13894@end table
13895
44ea7b70 13896
6d2ebf8b 13897@node Altering
c906108c
SS
13898@chapter Altering Execution
13899
13900Once you think you have found an error in your program, you might want to
13901find out for certain whether correcting the apparent error would lead to
13902correct results in the rest of the run. You can find the answer by
13903experiment, using the @value{GDBN} features for altering execution of the
13904program.
13905
13906For example, you can store new values into variables or memory
7a292a7a
SS
13907locations, give your program a signal, restart it at a different
13908address, or even return prematurely from a function.
c906108c
SS
13909
13910@menu
13911* Assignment:: Assignment to variables
13912* Jumping:: Continuing at a different address
c906108c 13913* Signaling:: Giving your program a signal
c906108c
SS
13914* Returning:: Returning from a function
13915* Calling:: Calling your program's functions
13916* Patching:: Patching your program
13917@end menu
13918
6d2ebf8b 13919@node Assignment
79a6e687 13920@section Assignment to Variables
c906108c
SS
13921
13922@cindex assignment
13923@cindex setting variables
13924To alter the value of a variable, evaluate an assignment expression.
13925@xref{Expressions, ,Expressions}. For example,
13926
474c8240 13927@smallexample
c906108c 13928print x=4
474c8240 13929@end smallexample
c906108c
SS
13930
13931@noindent
13932stores the value 4 into the variable @code{x}, and then prints the
5d161b24 13933value of the assignment expression (which is 4).
c906108c
SS
13934@xref{Languages, ,Using @value{GDBN} with Different Languages}, for more
13935information on operators in supported languages.
c906108c
SS
13936
13937@kindex set variable
13938@cindex variables, setting
13939If you are not interested in seeing the value of the assignment, use the
13940@code{set} command instead of the @code{print} command. @code{set} is
13941really the same as @code{print} except that the expression's value is
13942not printed and is not put in the value history (@pxref{Value History,
79a6e687 13943,Value History}). The expression is evaluated only for its effects.
c906108c 13944
c906108c
SS
13945If the beginning of the argument string of the @code{set} command
13946appears identical to a @code{set} subcommand, use the @code{set
13947variable} command instead of just @code{set}. This command is identical
13948to @code{set} except for its lack of subcommands. For example, if your
13949program has a variable @code{width}, you get an error if you try to set
13950a new value with just @samp{set width=13}, because @value{GDBN} has the
13951command @code{set width}:
13952
474c8240 13953@smallexample
c906108c
SS
13954(@value{GDBP}) whatis width
13955type = double
13956(@value{GDBP}) p width
13957$4 = 13
13958(@value{GDBP}) set width=47
13959Invalid syntax in expression.
474c8240 13960@end smallexample
c906108c
SS
13961
13962@noindent
13963The invalid expression, of course, is @samp{=47}. In
13964order to actually set the program's variable @code{width}, use
13965
474c8240 13966@smallexample
c906108c 13967(@value{GDBP}) set var width=47
474c8240 13968@end smallexample
53a5351d 13969
c906108c
SS
13970Because the @code{set} command has many subcommands that can conflict
13971with the names of program variables, it is a good idea to use the
13972@code{set variable} command instead of just @code{set}. For example, if
13973your program has a variable @code{g}, you run into problems if you try
13974to set a new value with just @samp{set g=4}, because @value{GDBN} has
13975the command @code{set gnutarget}, abbreviated @code{set g}:
13976
474c8240 13977@smallexample
c906108c
SS
13978@group
13979(@value{GDBP}) whatis g
13980type = double
13981(@value{GDBP}) p g
13982$1 = 1
13983(@value{GDBP}) set g=4
2df3850c 13984(@value{GDBP}) p g
c906108c
SS
13985$2 = 1
13986(@value{GDBP}) r
13987The program being debugged has been started already.
13988Start it from the beginning? (y or n) y
13989Starting program: /home/smith/cc_progs/a.out
6d2ebf8b
SS
13990"/home/smith/cc_progs/a.out": can't open to read symbols:
13991 Invalid bfd target.
c906108c
SS
13992(@value{GDBP}) show g
13993The current BFD target is "=4".
13994@end group
474c8240 13995@end smallexample
c906108c
SS
13996
13997@noindent
13998The program variable @code{g} did not change, and you silently set the
13999@code{gnutarget} to an invalid value. In order to set the variable
14000@code{g}, use
14001
474c8240 14002@smallexample
c906108c 14003(@value{GDBP}) set var g=4
474c8240 14004@end smallexample
c906108c
SS
14005
14006@value{GDBN} allows more implicit conversions in assignments than C; you can
14007freely store an integer value into a pointer variable or vice versa,
14008and you can convert any structure to any other structure that is the
14009same length or shorter.
14010@comment FIXME: how do structs align/pad in these conversions?
14011@comment /doc@cygnus.com 18dec1990
14012
14013To store values into arbitrary places in memory, use the @samp{@{@dots{}@}}
14014construct to generate a value of specified type at a specified address
14015(@pxref{Expressions, ,Expressions}). For example, @code{@{int@}0x83040} refers
14016to memory location @code{0x83040} as an integer (which implies a certain size
14017and representation in memory), and
14018
474c8240 14019@smallexample
c906108c 14020set @{int@}0x83040 = 4
474c8240 14021@end smallexample
c906108c
SS
14022
14023@noindent
14024stores the value 4 into that memory location.
14025
6d2ebf8b 14026@node Jumping
79a6e687 14027@section Continuing at a Different Address
c906108c
SS
14028
14029Ordinarily, when you continue your program, you do so at the place where
14030it stopped, with the @code{continue} command. You can instead continue at
14031an address of your own choosing, with the following commands:
14032
14033@table @code
14034@kindex jump
14035@item jump @var{linespec}
2a25a5ba
EZ
14036@itemx jump @var{location}
14037Resume execution at line @var{linespec} or at address given by
14038@var{location}. Execution stops again immediately if there is a
14039breakpoint there. @xref{Specify Location}, for a description of the
14040different forms of @var{linespec} and @var{location}. It is common
14041practice to use the @code{tbreak} command in conjunction with
14042@code{jump}. @xref{Set Breaks, ,Setting Breakpoints}.
c906108c
SS
14043
14044The @code{jump} command does not change the current stack frame, or
14045the stack pointer, or the contents of any memory location or any
14046register other than the program counter. If line @var{linespec} is in
14047a different function from the one currently executing, the results may
14048be bizarre if the two functions expect different patterns of arguments or
14049of local variables. For this reason, the @code{jump} command requests
14050confirmation if the specified line is not in the function currently
14051executing. However, even bizarre results are predictable if you are
14052well acquainted with the machine-language code of your program.
c906108c
SS
14053@end table
14054
c906108c 14055@c Doesn't work on HP-UX; have to set $pcoqh and $pcoqt.
53a5351d
JM
14056On many systems, you can get much the same effect as the @code{jump}
14057command by storing a new value into the register @code{$pc}. The
14058difference is that this does not start your program running; it only
14059changes the address of where it @emph{will} run when you continue. For
14060example,
c906108c 14061
474c8240 14062@smallexample
c906108c 14063set $pc = 0x485
474c8240 14064@end smallexample
c906108c
SS
14065
14066@noindent
14067makes the next @code{continue} command or stepping command execute at
14068address @code{0x485}, rather than at the address where your program stopped.
79a6e687 14069@xref{Continuing and Stepping, ,Continuing and Stepping}.
c906108c
SS
14070
14071The most common occasion to use the @code{jump} command is to back
14072up---perhaps with more breakpoints set---over a portion of a program
14073that has already executed, in order to examine its execution in more
14074detail.
14075
c906108c 14076@c @group
6d2ebf8b 14077@node Signaling
79a6e687 14078@section Giving your Program a Signal
9c16f35a 14079@cindex deliver a signal to a program
c906108c
SS
14080
14081@table @code
14082@kindex signal
14083@item signal @var{signal}
14084Resume execution where your program stopped, but immediately give it the
14085signal @var{signal}. @var{signal} can be the name or the number of a
14086signal. For example, on many systems @code{signal 2} and @code{signal
14087SIGINT} are both ways of sending an interrupt signal.
14088
14089Alternatively, if @var{signal} is zero, continue execution without
14090giving a signal. This is useful when your program stopped on account of
14091a signal and would ordinary see the signal when resumed with the
14092@code{continue} command; @samp{signal 0} causes it to resume without a
14093signal.
14094
14095@code{signal} does not repeat when you press @key{RET} a second time
14096after executing the command.
14097@end table
14098@c @end group
14099
14100Invoking the @code{signal} command is not the same as invoking the
14101@code{kill} utility from the shell. Sending a signal with @code{kill}
14102causes @value{GDBN} to decide what to do with the signal depending on
14103the signal handling tables (@pxref{Signals}). The @code{signal} command
14104passes the signal directly to your program.
14105
c906108c 14106
6d2ebf8b 14107@node Returning
79a6e687 14108@section Returning from a Function
c906108c
SS
14109
14110@table @code
14111@cindex returning from a function
14112@kindex return
14113@item return
14114@itemx return @var{expression}
14115You can cancel execution of a function call with the @code{return}
14116command. If you give an
14117@var{expression} argument, its value is used as the function's return
14118value.
14119@end table
14120
14121When you use @code{return}, @value{GDBN} discards the selected stack frame
14122(and all frames within it). You can think of this as making the
14123discarded frame return prematurely. If you wish to specify a value to
14124be returned, give that value as the argument to @code{return}.
14125
14126This pops the selected stack frame (@pxref{Selection, ,Selecting a
79a6e687 14127Frame}), and any other frames inside of it, leaving its caller as the
c906108c
SS
14128innermost remaining frame. That frame becomes selected. The
14129specified value is stored in the registers used for returning values
14130of functions.
14131
14132The @code{return} command does not resume execution; it leaves the
14133program stopped in the state that would exist if the function had just
14134returned. In contrast, the @code{finish} command (@pxref{Continuing
79a6e687 14135and Stepping, ,Continuing and Stepping}) resumes execution until the
c906108c
SS
14136selected stack frame returns naturally.
14137
61ff14c6
JK
14138@value{GDBN} needs to know how the @var{expression} argument should be set for
14139the inferior. The concrete registers assignment depends on the OS ABI and the
14140type being returned by the selected stack frame. For example it is common for
14141OS ABI to return floating point values in FPU registers while integer values in
14142CPU registers. Still some ABIs return even floating point values in CPU
14143registers. Larger integer widths (such as @code{long long int}) also have
14144specific placement rules. @value{GDBN} already knows the OS ABI from its
14145current target so it needs to find out also the type being returned to make the
14146assignment into the right register(s).
14147
14148Normally, the selected stack frame has debug info. @value{GDBN} will always
14149use the debug info instead of the implicit type of @var{expression} when the
14150debug info is available. For example, if you type @kbd{return -1}, and the
14151function in the current stack frame is declared to return a @code{long long
14152int}, @value{GDBN} transparently converts the implicit @code{int} value of -1
14153into a @code{long long int}:
14154
14155@smallexample
14156Breakpoint 1, func () at gdb.base/return-nodebug.c:29
1415729 return 31;
14158(@value{GDBP}) return -1
14159Make func return now? (y or n) y
14160#0 0x004004f6 in main () at gdb.base/return-nodebug.c:43
1416143 printf ("result=%lld\n", func ());
14162(@value{GDBP})
14163@end smallexample
14164
14165However, if the selected stack frame does not have a debug info, e.g., if the
14166function was compiled without debug info, @value{GDBN} has to find out the type
14167to return from user. Specifying a different type by mistake may set the value
14168in different inferior registers than the caller code expects. For example,
14169typing @kbd{return -1} with its implicit type @code{int} would set only a part
14170of a @code{long long int} result for a debug info less function (on 32-bit
14171architectures). Therefore the user is required to specify the return type by
14172an appropriate cast explicitly:
14173
14174@smallexample
14175Breakpoint 2, 0x0040050b in func ()
14176(@value{GDBP}) return -1
14177Return value type not available for selected stack frame.
14178Please use an explicit cast of the value to return.
14179(@value{GDBP}) return (long long int) -1
14180Make selected stack frame return now? (y or n) y
14181#0 0x00400526 in main ()
14182(@value{GDBP})
14183@end smallexample
14184
6d2ebf8b 14185@node Calling
79a6e687 14186@section Calling Program Functions
c906108c 14187
f8568604 14188@table @code
c906108c 14189@cindex calling functions
f8568604
EZ
14190@cindex inferior functions, calling
14191@item print @var{expr}
d3e8051b 14192Evaluate the expression @var{expr} and display the resulting value.
f8568604
EZ
14193@var{expr} may include calls to functions in the program being
14194debugged.
14195
c906108c 14196@kindex call
c906108c
SS
14197@item call @var{expr}
14198Evaluate the expression @var{expr} without displaying @code{void}
14199returned values.
c906108c
SS
14200
14201You can use this variant of the @code{print} command if you want to
f8568604
EZ
14202execute a function from your program that does not return anything
14203(a.k.a.@: @dfn{a void function}), but without cluttering the output
14204with @code{void} returned values that @value{GDBN} will otherwise
14205print. If the result is not void, it is printed and saved in the
14206value history.
14207@end table
14208
9c16f35a
EZ
14209It is possible for the function you call via the @code{print} or
14210@code{call} command to generate a signal (e.g., if there's a bug in
14211the function, or if you passed it incorrect arguments). What happens
14212in that case is controlled by the @code{set unwindonsignal} command.
14213
7cd1089b
PM
14214Similarly, with a C@t{++} program it is possible for the function you
14215call via the @code{print} or @code{call} command to generate an
14216exception that is not handled due to the constraints of the dummy
14217frame. In this case, any exception that is raised in the frame, but has
14218an out-of-frame exception handler will not be found. GDB builds a
14219dummy-frame for the inferior function call, and the unwinder cannot
14220seek for exception handlers outside of this dummy-frame. What happens
14221in that case is controlled by the
14222@code{set unwind-on-terminating-exception} command.
14223
9c16f35a
EZ
14224@table @code
14225@item set unwindonsignal
14226@kindex set unwindonsignal
14227@cindex unwind stack in called functions
14228@cindex call dummy stack unwinding
14229Set unwinding of the stack if a signal is received while in a function
14230that @value{GDBN} called in the program being debugged. If set to on,
14231@value{GDBN} unwinds the stack it created for the call and restores
14232the context to what it was before the call. If set to off (the
14233default), @value{GDBN} stops in the frame where the signal was
14234received.
14235
14236@item show unwindonsignal
14237@kindex show unwindonsignal
14238Show the current setting of stack unwinding in the functions called by
14239@value{GDBN}.
7cd1089b
PM
14240
14241@item set unwind-on-terminating-exception
14242@kindex set unwind-on-terminating-exception
14243@cindex unwind stack in called functions with unhandled exceptions
14244@cindex call dummy stack unwinding on unhandled exception.
14245Set unwinding of the stack if a C@t{++} exception is raised, but left
14246unhandled while in a function that @value{GDBN} called in the program being
14247debugged. If set to on (the default), @value{GDBN} unwinds the stack
14248it created for the call and restores the context to what it was before
14249the call. If set to off, @value{GDBN} the exception is delivered to
14250the default C@t{++} exception handler and the inferior terminated.
14251
14252@item show unwind-on-terminating-exception
14253@kindex show unwind-on-terminating-exception
14254Show the current setting of stack unwinding in the functions called by
14255@value{GDBN}.
14256
9c16f35a
EZ
14257@end table
14258
f8568604
EZ
14259@cindex weak alias functions
14260Sometimes, a function you wish to call is actually a @dfn{weak alias}
14261for another function. In such case, @value{GDBN} might not pick up
14262the type information, including the types of the function arguments,
14263which causes @value{GDBN} to call the inferior function incorrectly.
14264As a result, the called function will function erroneously and may
14265even crash. A solution to that is to use the name of the aliased
14266function instead.
c906108c 14267
6d2ebf8b 14268@node Patching
79a6e687 14269@section Patching Programs
7a292a7a 14270
c906108c
SS
14271@cindex patching binaries
14272@cindex writing into executables
c906108c 14273@cindex writing into corefiles
c906108c 14274
7a292a7a
SS
14275By default, @value{GDBN} opens the file containing your program's
14276executable code (or the corefile) read-only. This prevents accidental
14277alterations to machine code; but it also prevents you from intentionally
14278patching your program's binary.
c906108c
SS
14279
14280If you'd like to be able to patch the binary, you can specify that
14281explicitly with the @code{set write} command. For example, you might
14282want to turn on internal debugging flags, or even to make emergency
14283repairs.
14284
14285@table @code
14286@kindex set write
14287@item set write on
14288@itemx set write off
7a292a7a 14289If you specify @samp{set write on}, @value{GDBN} opens executable and
20924a55 14290core files for both reading and writing; if you specify @kbd{set write
c906108c
SS
14291off} (the default), @value{GDBN} opens them read-only.
14292
14293If you have already loaded a file, you must load it again (using the
7a292a7a
SS
14294@code{exec-file} or @code{core-file} command) after changing @code{set
14295write}, for your new setting to take effect.
c906108c
SS
14296
14297@item show write
14298@kindex show write
7a292a7a
SS
14299Display whether executable files and core files are opened for writing
14300as well as reading.
c906108c
SS
14301@end table
14302
6d2ebf8b 14303@node GDB Files
c906108c
SS
14304@chapter @value{GDBN} Files
14305
7a292a7a
SS
14306@value{GDBN} needs to know the file name of the program to be debugged,
14307both in order to read its symbol table and in order to start your
14308program. To debug a core dump of a previous run, you must also tell
14309@value{GDBN} the name of the core dump file.
c906108c
SS
14310
14311@menu
14312* Files:: Commands to specify files
5b5d99cf 14313* Separate Debug Files:: Debugging information in separate files
9291a0cd 14314* Index Files:: Index files speed up GDB
c906108c 14315* Symbol Errors:: Errors reading symbol files
b14b1491 14316* Data Files:: GDB data files
c906108c
SS
14317@end menu
14318
6d2ebf8b 14319@node Files
79a6e687 14320@section Commands to Specify Files
c906108c 14321
7a292a7a 14322@cindex symbol table
c906108c 14323@cindex core dump file
7a292a7a
SS
14324
14325You may want to specify executable and core dump file names. The usual
14326way to do this is at start-up time, using the arguments to
14327@value{GDBN}'s start-up commands (@pxref{Invocation, , Getting In and
14328Out of @value{GDBN}}).
c906108c
SS
14329
14330Occasionally it is necessary to change to a different file during a
397ca115
EZ
14331@value{GDBN} session. Or you may run @value{GDBN} and forget to
14332specify a file you want to use. Or you are debugging a remote target
79a6e687
BW
14333via @code{gdbserver} (@pxref{Server, file, Using the @code{gdbserver}
14334Program}). In these situations the @value{GDBN} commands to specify
0869d01b 14335new files are useful.
c906108c
SS
14336
14337@table @code
14338@cindex executable file
14339@kindex file
14340@item file @var{filename}
14341Use @var{filename} as the program to be debugged. It is read for its
14342symbols and for the contents of pure memory. It is also the program
14343executed when you use the @code{run} command. If you do not specify a
5d161b24
DB
14344directory and the file is not found in the @value{GDBN} working directory,
14345@value{GDBN} uses the environment variable @code{PATH} as a list of
14346directories to search, just as the shell does when looking for a program
14347to run. You can change the value of this variable, for both @value{GDBN}
c906108c
SS
14348and your program, using the @code{path} command.
14349
fc8be69e
EZ
14350@cindex unlinked object files
14351@cindex patching object files
14352You can load unlinked object @file{.o} files into @value{GDBN} using
14353the @code{file} command. You will not be able to ``run'' an object
14354file, but you can disassemble functions and inspect variables. Also,
14355if the underlying BFD functionality supports it, you could use
14356@kbd{gdb -write} to patch object files using this technique. Note
14357that @value{GDBN} can neither interpret nor modify relocations in this
14358case, so branches and some initialized variables will appear to go to
14359the wrong place. But this feature is still handy from time to time.
14360
c906108c
SS
14361@item file
14362@code{file} with no argument makes @value{GDBN} discard any information it
14363has on both executable file and the symbol table.
14364
14365@kindex exec-file
14366@item exec-file @r{[} @var{filename} @r{]}
14367Specify that the program to be run (but not the symbol table) is found
14368in @var{filename}. @value{GDBN} searches the environment variable @code{PATH}
14369if necessary to locate your program. Omitting @var{filename} means to
14370discard information on the executable file.
14371
14372@kindex symbol-file
14373@item symbol-file @r{[} @var{filename} @r{]}
14374Read symbol table information from file @var{filename}. @code{PATH} is
14375searched when necessary. Use the @code{file} command to get both symbol
14376table and program to run from the same file.
14377
14378@code{symbol-file} with no argument clears out @value{GDBN} information on your
14379program's symbol table.
14380
ae5a43e0
DJ
14381The @code{symbol-file} command causes @value{GDBN} to forget the contents of
14382some breakpoints and auto-display expressions. This is because they may
14383contain pointers to the internal data recording symbols and data types,
14384which are part of the old symbol table data being discarded inside
14385@value{GDBN}.
c906108c
SS
14386
14387@code{symbol-file} does not repeat if you press @key{RET} again after
14388executing it once.
14389
14390When @value{GDBN} is configured for a particular environment, it
14391understands debugging information in whatever format is the standard
14392generated for that environment; you may use either a @sc{gnu} compiler, or
14393other compilers that adhere to the local conventions.
c906108c 14394Best results are usually obtained from @sc{gnu} compilers; for example,
e22ea452 14395using @code{@value{NGCC}} you can generate debugging information for
c906108c 14396optimized code.
c906108c
SS
14397
14398For most kinds of object files, with the exception of old SVR3 systems
14399using COFF, the @code{symbol-file} command does not normally read the
14400symbol table in full right away. Instead, it scans the symbol table
14401quickly to find which source files and which symbols are present. The
14402details are read later, one source file at a time, as they are needed.
14403
14404The purpose of this two-stage reading strategy is to make @value{GDBN}
14405start up faster. For the most part, it is invisible except for
14406occasional pauses while the symbol table details for a particular source
14407file are being read. (The @code{set verbose} command can turn these
14408pauses into messages if desired. @xref{Messages/Warnings, ,Optional
79a6e687 14409Warnings and Messages}.)
c906108c 14410
c906108c
SS
14411We have not implemented the two-stage strategy for COFF yet. When the
14412symbol table is stored in COFF format, @code{symbol-file} reads the
14413symbol table data in full right away. Note that ``stabs-in-COFF''
14414still does the two-stage strategy, since the debug info is actually
14415in stabs format.
14416
14417@kindex readnow
14418@cindex reading symbols immediately
14419@cindex symbols, reading immediately
6ac33a4e
TT
14420@item symbol-file @r{[} -readnow @r{]} @var{filename}
14421@itemx file @r{[} -readnow @r{]} @var{filename}
c906108c
SS
14422You can override the @value{GDBN} two-stage strategy for reading symbol
14423tables by using the @samp{-readnow} option with any of the commands that
14424load symbol table information, if you want to be sure @value{GDBN} has the
5d161b24 14425entire symbol table available.
c906108c 14426
c906108c
SS
14427@c FIXME: for now no mention of directories, since this seems to be in
14428@c flux. 13mar1992 status is that in theory GDB would look either in
14429@c current dir or in same dir as myprog; but issues like competing
14430@c GDB's, or clutter in system dirs, mean that in practice right now
14431@c only current dir is used. FFish says maybe a special GDB hierarchy
14432@c (eg rooted in val of env var GDBSYMS) could exist for mappable symbol
14433@c files.
14434
c906108c 14435@kindex core-file
09d4efe1 14436@item core-file @r{[}@var{filename}@r{]}
4644b6e3 14437@itemx core
c906108c
SS
14438Specify the whereabouts of a core dump file to be used as the ``contents
14439of memory''. Traditionally, core files contain only some parts of the
14440address space of the process that generated them; @value{GDBN} can access the
14441executable file itself for other parts.
14442
14443@code{core-file} with no argument specifies that no core file is
14444to be used.
14445
14446Note that the core file is ignored when your program is actually running
7a292a7a
SS
14447under @value{GDBN}. So, if you have been running your program and you
14448wish to debug a core file instead, you must kill the subprocess in which
14449the program is running. To do this, use the @code{kill} command
79a6e687 14450(@pxref{Kill Process, ,Killing the Child Process}).
c906108c 14451
c906108c
SS
14452@kindex add-symbol-file
14453@cindex dynamic linking
14454@item add-symbol-file @var{filename} @var{address}
a94ab193 14455@itemx add-symbol-file @var{filename} @var{address} @r{[} -readnow @r{]}
17d9d558 14456@itemx add-symbol-file @var{filename} @r{-s}@var{section} @var{address} @dots{}
96a2c332
SS
14457The @code{add-symbol-file} command reads additional symbol table
14458information from the file @var{filename}. You would use this command
14459when @var{filename} has been dynamically loaded (by some other means)
14460into the program that is running. @var{address} should be the memory
14461address at which the file has been loaded; @value{GDBN} cannot figure
d167840f
EZ
14462this out for itself. You can additionally specify an arbitrary number
14463of @samp{@r{-s}@var{section} @var{address}} pairs, to give an explicit
14464section name and base address for that section. You can specify any
14465@var{address} as an expression.
c906108c
SS
14466
14467The symbol table of the file @var{filename} is added to the symbol table
14468originally read with the @code{symbol-file} command. You can use the
96a2c332
SS
14469@code{add-symbol-file} command any number of times; the new symbol data
14470thus read keeps adding to the old. To discard all old symbol data
14471instead, use the @code{symbol-file} command without any arguments.
c906108c 14472
17d9d558
JB
14473@cindex relocatable object files, reading symbols from
14474@cindex object files, relocatable, reading symbols from
14475@cindex reading symbols from relocatable object files
14476@cindex symbols, reading from relocatable object files
14477@cindex @file{.o} files, reading symbols from
14478Although @var{filename} is typically a shared library file, an
14479executable file, or some other object file which has been fully
14480relocated for loading into a process, you can also load symbolic
14481information from relocatable @file{.o} files, as long as:
14482
14483@itemize @bullet
14484@item
14485the file's symbolic information refers only to linker symbols defined in
14486that file, not to symbols defined by other object files,
14487@item
14488every section the file's symbolic information refers to has actually
14489been loaded into the inferior, as it appears in the file, and
14490@item
14491you can determine the address at which every section was loaded, and
14492provide these to the @code{add-symbol-file} command.
14493@end itemize
14494
14495@noindent
14496Some embedded operating systems, like Sun Chorus and VxWorks, can load
14497relocatable files into an already running program; such systems
14498typically make the requirements above easy to meet. However, it's
14499important to recognize that many native systems use complex link
49efadf5 14500procedures (@code{.linkonce} section factoring and C@t{++} constructor table
17d9d558
JB
14501assembly, for example) that make the requirements difficult to meet. In
14502general, one cannot assume that using @code{add-symbol-file} to read a
14503relocatable object file's symbolic information will have the same effect
14504as linking the relocatable object file into the program in the normal
14505way.
14506
c906108c
SS
14507@code{add-symbol-file} does not repeat if you press @key{RET} after using it.
14508
c45da7e6
EZ
14509@kindex add-symbol-file-from-memory
14510@cindex @code{syscall DSO}
14511@cindex load symbols from memory
14512@item add-symbol-file-from-memory @var{address}
14513Load symbols from the given @var{address} in a dynamically loaded
14514object file whose image is mapped directly into the inferior's memory.
14515For example, the Linux kernel maps a @code{syscall DSO} into each
14516process's address space; this DSO provides kernel-specific code for
14517some system calls. The argument can be any expression whose
14518evaluation yields the address of the file's shared object file header.
14519For this command to work, you must have used @code{symbol-file} or
14520@code{exec-file} commands in advance.
14521
09d4efe1
EZ
14522@kindex add-shared-symbol-files
14523@kindex assf
14524@item add-shared-symbol-files @var{library-file}
14525@itemx assf @var{library-file}
14526The @code{add-shared-symbol-files} command can currently be used only
14527in the Cygwin build of @value{GDBN} on MS-Windows OS, where it is an
14528alias for the @code{dll-symbols} command (@pxref{Cygwin Native}).
14529@value{GDBN} automatically looks for shared libraries, however if
14530@value{GDBN} does not find yours, you can invoke
14531@code{add-shared-symbol-files}. It takes one argument: the shared
14532library's file name. @code{assf} is a shorthand alias for
14533@code{add-shared-symbol-files}.
c906108c 14534
c906108c 14535@kindex section
09d4efe1
EZ
14536@item section @var{section} @var{addr}
14537The @code{section} command changes the base address of the named
14538@var{section} of the exec file to @var{addr}. This can be used if the
14539exec file does not contain section addresses, (such as in the
14540@code{a.out} format), or when the addresses specified in the file
14541itself are wrong. Each section must be changed separately. The
14542@code{info files} command, described below, lists all the sections and
14543their addresses.
c906108c
SS
14544
14545@kindex info files
14546@kindex info target
14547@item info files
14548@itemx info target
7a292a7a
SS
14549@code{info files} and @code{info target} are synonymous; both print the
14550current target (@pxref{Targets, ,Specifying a Debugging Target}),
14551including the names of the executable and core dump files currently in
14552use by @value{GDBN}, and the files from which symbols were loaded. The
14553command @code{help target} lists all possible targets rather than
14554current ones.
14555
fe95c787
MS
14556@kindex maint info sections
14557@item maint info sections
14558Another command that can give you extra information about program sections
14559is @code{maint info sections}. In addition to the section information
14560displayed by @code{info files}, this command displays the flags and file
14561offset of each section in the executable and core dump files. In addition,
14562@code{maint info sections} provides the following command options (which
14563may be arbitrarily combined):
14564
14565@table @code
14566@item ALLOBJ
14567Display sections for all loaded object files, including shared libraries.
14568@item @var{sections}
6600abed 14569Display info only for named @var{sections}.
fe95c787
MS
14570@item @var{section-flags}
14571Display info only for sections for which @var{section-flags} are true.
14572The section flags that @value{GDBN} currently knows about are:
14573@table @code
14574@item ALLOC
14575Section will have space allocated in the process when loaded.
14576Set for all sections except those containing debug information.
14577@item LOAD
14578Section will be loaded from the file into the child process memory.
14579Set for pre-initialized code and data, clear for @code{.bss} sections.
14580@item RELOC
14581Section needs to be relocated before loading.
14582@item READONLY
14583Section cannot be modified by the child process.
14584@item CODE
14585Section contains executable code only.
6600abed 14586@item DATA
fe95c787
MS
14587Section contains data only (no executable code).
14588@item ROM
14589Section will reside in ROM.
14590@item CONSTRUCTOR
14591Section contains data for constructor/destructor lists.
14592@item HAS_CONTENTS
14593Section is not empty.
14594@item NEVER_LOAD
14595An instruction to the linker to not output the section.
14596@item COFF_SHARED_LIBRARY
14597A notification to the linker that the section contains
14598COFF shared library information.
14599@item IS_COMMON
14600Section contains common symbols.
14601@end table
14602@end table
6763aef9 14603@kindex set trust-readonly-sections
9c16f35a 14604@cindex read-only sections
6763aef9
MS
14605@item set trust-readonly-sections on
14606Tell @value{GDBN} that readonly sections in your object file
6ca652b0 14607really are read-only (i.e.@: that their contents will not change).
6763aef9
MS
14608In that case, @value{GDBN} can fetch values from these sections
14609out of the object file, rather than from the target program.
14610For some targets (notably embedded ones), this can be a significant
14611enhancement to debugging performance.
14612
14613The default is off.
14614
14615@item set trust-readonly-sections off
15110bc3 14616Tell @value{GDBN} not to trust readonly sections. This means that
6763aef9
MS
14617the contents of the section might change while the program is running,
14618and must therefore be fetched from the target when needed.
9c16f35a
EZ
14619
14620@item show trust-readonly-sections
14621Show the current setting of trusting readonly sections.
c906108c
SS
14622@end table
14623
14624All file-specifying commands allow both absolute and relative file names
14625as arguments. @value{GDBN} always converts the file name to an absolute file
14626name and remembers it that way.
14627
c906108c 14628@cindex shared libraries
9cceb671
DJ
14629@anchor{Shared Libraries}
14630@value{GDBN} supports @sc{gnu}/Linux, MS-Windows, HP-UX, SunOS, SVr4, Irix,
9c16f35a 14631and IBM RS/6000 AIX shared libraries.
53a5351d 14632
9cceb671
DJ
14633On MS-Windows @value{GDBN} must be linked with the Expat library to support
14634shared libraries. @xref{Expat}.
14635
c906108c
SS
14636@value{GDBN} automatically loads symbol definitions from shared libraries
14637when you use the @code{run} command, or when you examine a core file.
14638(Before you issue the @code{run} command, @value{GDBN} does not understand
14639references to a function in a shared library, however---unless you are
14640debugging a core file).
53a5351d
JM
14641
14642On HP-UX, if the program loads a library explicitly, @value{GDBN}
14643automatically loads the symbols at the time of the @code{shl_load} call.
14644
c906108c
SS
14645@c FIXME: some @value{GDBN} release may permit some refs to undef
14646@c FIXME...symbols---eg in a break cmd---assuming they are from a shared
14647@c FIXME...lib; check this from time to time when updating manual
14648
b7209cb4
FF
14649There are times, however, when you may wish to not automatically load
14650symbol definitions from shared libraries, such as when they are
14651particularly large or there are many of them.
14652
14653To control the automatic loading of shared library symbols, use the
14654commands:
14655
14656@table @code
14657@kindex set auto-solib-add
14658@item set auto-solib-add @var{mode}
14659If @var{mode} is @code{on}, symbols from all shared object libraries
14660will be loaded automatically when the inferior begins execution, you
14661attach to an independently started inferior, or when the dynamic linker
14662informs @value{GDBN} that a new library has been loaded. If @var{mode}
14663is @code{off}, symbols must be loaded manually, using the
14664@code{sharedlibrary} command. The default value is @code{on}.
14665
dcaf7c2c
EZ
14666@cindex memory used for symbol tables
14667If your program uses lots of shared libraries with debug info that
14668takes large amounts of memory, you can decrease the @value{GDBN}
14669memory footprint by preventing it from automatically loading the
14670symbols from shared libraries. To that end, type @kbd{set
14671auto-solib-add off} before running the inferior, then load each
14672library whose debug symbols you do need with @kbd{sharedlibrary
d3e8051b 14673@var{regexp}}, where @var{regexp} is a regular expression that matches
dcaf7c2c
EZ
14674the libraries whose symbols you want to be loaded.
14675
b7209cb4
FF
14676@kindex show auto-solib-add
14677@item show auto-solib-add
14678Display the current autoloading mode.
14679@end table
14680
c45da7e6 14681@cindex load shared library
b7209cb4
FF
14682To explicitly load shared library symbols, use the @code{sharedlibrary}
14683command:
14684
c906108c
SS
14685@table @code
14686@kindex info sharedlibrary
14687@kindex info share
55333a84
DE
14688@item info share @var{regex}
14689@itemx info sharedlibrary @var{regex}
14690Print the names of the shared libraries which are currently loaded
14691that match @var{regex}. If @var{regex} is omitted then print
14692all shared libraries that are loaded.
c906108c
SS
14693
14694@kindex sharedlibrary
14695@kindex share
14696@item sharedlibrary @var{regex}
14697@itemx share @var{regex}
c906108c
SS
14698Load shared object library symbols for files matching a
14699Unix regular expression.
14700As with files loaded automatically, it only loads shared libraries
14701required by your program for a core file or after typing @code{run}. If
14702@var{regex} is omitted all shared libraries required by your program are
14703loaded.
c45da7e6
EZ
14704
14705@item nosharedlibrary
14706@kindex nosharedlibrary
14707@cindex unload symbols from shared libraries
14708Unload all shared object library symbols. This discards all symbols
14709that have been loaded from all shared libraries. Symbols from shared
14710libraries that were loaded by explicit user requests are not
14711discarded.
c906108c
SS
14712@end table
14713
721c2651
EZ
14714Sometimes you may wish that @value{GDBN} stops and gives you control
14715when any of shared library events happen. Use the @code{set
14716stop-on-solib-events} command for this:
14717
14718@table @code
14719@item set stop-on-solib-events
14720@kindex set stop-on-solib-events
14721This command controls whether @value{GDBN} should give you control
14722when the dynamic linker notifies it about some shared library event.
14723The most common event of interest is loading or unloading of a new
14724shared library.
14725
14726@item show stop-on-solib-events
14727@kindex show stop-on-solib-events
14728Show whether @value{GDBN} stops and gives you control when shared
14729library events happen.
14730@end table
14731
f5ebfba0 14732Shared libraries are also supported in many cross or remote debugging
f1838a98
UW
14733configurations. @value{GDBN} needs to have access to the target's libraries;
14734this can be accomplished either by providing copies of the libraries
14735on the host system, or by asking @value{GDBN} to automatically retrieve the
14736libraries from the target. If copies of the target libraries are
14737provided, they need to be the same as the target libraries, although the
f5ebfba0
DJ
14738copies on the target can be stripped as long as the copies on the host are
14739not.
14740
59b7b46f
EZ
14741@cindex where to look for shared libraries
14742For remote debugging, you need to tell @value{GDBN} where the target
14743libraries are, so that it can load the correct copies---otherwise, it
14744may try to load the host's libraries. @value{GDBN} has two variables
14745to specify the search directories for target libraries.
f5ebfba0
DJ
14746
14747@table @code
59b7b46f 14748@cindex prefix for shared library file names
f822c95b 14749@cindex system root, alternate
f5ebfba0 14750@kindex set solib-absolute-prefix
f822c95b
DJ
14751@kindex set sysroot
14752@item set sysroot @var{path}
14753Use @var{path} as the system root for the program being debugged. Any
14754absolute shared library paths will be prefixed with @var{path}; many
14755runtime loaders store the absolute paths to the shared library in the
14756target program's memory. If you use @code{set sysroot} to find shared
14757libraries, they need to be laid out in the same way that they are on
14758the target, with e.g.@: a @file{/lib} and @file{/usr/lib} hierarchy
14759under @var{path}.
14760
f1838a98
UW
14761If @var{path} starts with the sequence @file{remote:}, @value{GDBN} will
14762retrieve the target libraries from the remote system. This is only
14763supported when using a remote target that supports the @code{remote get}
14764command (@pxref{File Transfer,,Sending files to a remote system}).
14765The part of @var{path} following the initial @file{remote:}
14766(if present) is used as system root prefix on the remote file system.
14767@footnote{If you want to specify a local system root using a directory
14768that happens to be named @file{remote:}, you need to use some equivalent
14769variant of the name like @file{./remote:}.}
14770
ab38a727
PA
14771For targets with an MS-DOS based filesystem, such as MS-Windows and
14772SymbianOS, @value{GDBN} tries prefixing a few variants of the target
14773absolute file name with @var{path}. But first, on Unix hosts,
14774@value{GDBN} converts all backslash directory separators into forward
14775slashes, because the backslash is not a directory separator on Unix:
14776
14777@smallexample
14778 c:\foo\bar.dll @result{} c:/foo/bar.dll
14779@end smallexample
14780
14781Then, @value{GDBN} attempts prefixing the target file name with
14782@var{path}, and looks for the resulting file name in the host file
14783system:
14784
14785@smallexample
14786 c:/foo/bar.dll @result{} /path/to/sysroot/c:/foo/bar.dll
14787@end smallexample
14788
14789If that does not find the shared library, @value{GDBN} tries removing
14790the @samp{:} character from the drive spec, both for convenience, and,
14791for the case of the host file system not supporting file names with
14792colons:
14793
14794@smallexample
14795 c:/foo/bar.dll @result{} /path/to/sysroot/c/foo/bar.dll
14796@end smallexample
14797
14798This makes it possible to have a system root that mirrors a target
14799with more than one drive. E.g., you may want to setup your local
14800copies of the target system shared libraries like so (note @samp{c} vs
14801@samp{z}):
14802
14803@smallexample
14804 @file{/path/to/sysroot/c/sys/bin/foo.dll}
14805 @file{/path/to/sysroot/c/sys/bin/bar.dll}
14806 @file{/path/to/sysroot/z/sys/bin/bar.dll}
14807@end smallexample
14808
14809@noindent
14810and point the system root at @file{/path/to/sysroot}, so that
14811@value{GDBN} can find the correct copies of both
14812@file{c:\sys\bin\foo.dll}, and @file{z:\sys\bin\bar.dll}.
14813
14814If that still does not find the shared library, @value{GDBN} tries
14815removing the whole drive spec from the target file name:
14816
14817@smallexample
14818 c:/foo/bar.dll @result{} /path/to/sysroot/foo/bar.dll
14819@end smallexample
14820
14821This last lookup makes it possible to not care about the drive name,
14822if you don't want or need to.
14823
f822c95b
DJ
14824The @code{set solib-absolute-prefix} command is an alias for @code{set
14825sysroot}.
14826
14827@cindex default system root
59b7b46f 14828@cindex @samp{--with-sysroot}
f822c95b
DJ
14829You can set the default system root by using the configure-time
14830@samp{--with-sysroot} option. If the system root is inside
14831@value{GDBN}'s configured binary prefix (set with @samp{--prefix} or
14832@samp{--exec-prefix}), then the default system root will be updated
14833automatically if the installed @value{GDBN} is moved to a new
14834location.
14835
14836@kindex show sysroot
14837@item show sysroot
f5ebfba0
DJ
14838Display the current shared library prefix.
14839
14840@kindex set solib-search-path
14841@item set solib-search-path @var{path}
f822c95b
DJ
14842If this variable is set, @var{path} is a colon-separated list of
14843directories to search for shared libraries. @samp{solib-search-path}
14844is used after @samp{sysroot} fails to locate the library, or if the
14845path to the library is relative instead of absolute. If you want to
14846use @samp{solib-search-path} instead of @samp{sysroot}, be sure to set
d3e8051b 14847@samp{sysroot} to a nonexistent directory to prevent @value{GDBN} from
f822c95b 14848finding your host's libraries. @samp{sysroot} is preferred; setting
d3e8051b 14849it to a nonexistent directory may interfere with automatic loading
f822c95b 14850of shared library symbols.
f5ebfba0
DJ
14851
14852@kindex show solib-search-path
14853@item show solib-search-path
14854Display the current shared library search path.
ab38a727
PA
14855
14856@cindex DOS file-name semantics of file names.
14857@kindex set target-file-system-kind (unix|dos-based|auto)
14858@kindex show target-file-system-kind
14859@item set target-file-system-kind @var{kind}
14860Set assumed file system kind for target reported file names.
14861
14862Shared library file names as reported by the target system may not
14863make sense as is on the system @value{GDBN} is running on. For
14864example, when remote debugging a target that has MS-DOS based file
14865system semantics, from a Unix host, the target may be reporting to
14866@value{GDBN} a list of loaded shared libraries with file names such as
14867@file{c:\Windows\kernel32.dll}. On Unix hosts, there's no concept of
14868drive letters, so the @samp{c:\} prefix is not normally understood as
14869indicating an absolute file name, and neither is the backslash
14870normally considered a directory separator character. In that case,
14871the native file system would interpret this whole absolute file name
14872as a relative file name with no directory components. This would make
14873it impossible to point @value{GDBN} at a copy of the remote target's
14874shared libraries on the host using @code{set sysroot}, and impractical
14875with @code{set solib-search-path}. Setting
14876@code{target-file-system-kind} to @code{dos-based} tells @value{GDBN}
14877to interpret such file names similarly to how the target would, and to
14878map them to file names valid on @value{GDBN}'s native file system
14879semantics. The value of @var{kind} can be @code{"auto"}, in addition
14880to one of the supported file system kinds. In that case, @value{GDBN}
14881tries to determine the appropriate file system variant based on the
14882current target's operating system (@pxref{ABI, ,Configuring the
14883Current ABI}). The supported file system settings are:
14884
14885@table @code
14886@item unix
14887Instruct @value{GDBN} to assume the target file system is of Unix
14888kind. Only file names starting the forward slash (@samp{/}) character
14889are considered absolute, and the directory separator character is also
14890the forward slash.
14891
14892@item dos-based
14893Instruct @value{GDBN} to assume the target file system is DOS based.
14894File names starting with either a forward slash, or a drive letter
14895followed by a colon (e.g., @samp{c:}), are considered absolute, and
14896both the slash (@samp{/}) and the backslash (@samp{\\}) characters are
14897considered directory separators.
14898
14899@item auto
14900Instruct @value{GDBN} to use the file system kind associated with the
14901target operating system (@pxref{ABI, ,Configuring the Current ABI}).
14902This is the default.
14903@end table
f5ebfba0
DJ
14904@end table
14905
5b5d99cf
JB
14906
14907@node Separate Debug Files
14908@section Debugging Information in Separate Files
14909@cindex separate debugging information files
14910@cindex debugging information in separate files
14911@cindex @file{.debug} subdirectories
14912@cindex debugging information directory, global
14913@cindex global debugging information directory
c7e83d54
EZ
14914@cindex build ID, and separate debugging files
14915@cindex @file{.build-id} directory
5b5d99cf
JB
14916
14917@value{GDBN} allows you to put a program's debugging information in a
14918file separate from the executable itself, in a way that allows
14919@value{GDBN} to find and load the debugging information automatically.
c7e83d54
EZ
14920Since debugging information can be very large---sometimes larger
14921than the executable code itself---some systems distribute debugging
5b5d99cf
JB
14922information for their executables in separate files, which users can
14923install only when they need to debug a problem.
14924
c7e83d54
EZ
14925@value{GDBN} supports two ways of specifying the separate debug info
14926file:
5b5d99cf
JB
14927
14928@itemize @bullet
14929@item
c7e83d54
EZ
14930The executable contains a @dfn{debug link} that specifies the name of
14931the separate debug info file. The separate debug file's name is
14932usually @file{@var{executable}.debug}, where @var{executable} is the
14933name of the corresponding executable file without leading directories
14934(e.g., @file{ls.debug} for @file{/usr/bin/ls}). In addition, the
99e008fe
EZ
14935debug link specifies a 32-bit @dfn{Cyclic Redundancy Check} (CRC)
14936checksum for the debug file, which @value{GDBN} uses to validate that
14937the executable and the debug file came from the same build.
c7e83d54
EZ
14938
14939@item
7e27a47a 14940The executable contains a @dfn{build ID}, a unique bit string that is
c7e83d54 14941also present in the corresponding debug info file. (This is supported
7e27a47a
EZ
14942only on some operating systems, notably those which use the ELF format
14943for binary files and the @sc{gnu} Binutils.) For more details about
14944this feature, see the description of the @option{--build-id}
14945command-line option in @ref{Options, , Command Line Options, ld.info,
14946The GNU Linker}. The debug info file's name is not specified
14947explicitly by the build ID, but can be computed from the build ID, see
14948below.
d3750b24
JK
14949@end itemize
14950
c7e83d54
EZ
14951Depending on the way the debug info file is specified, @value{GDBN}
14952uses two different methods of looking for the debug file:
d3750b24
JK
14953
14954@itemize @bullet
14955@item
c7e83d54
EZ
14956For the ``debug link'' method, @value{GDBN} looks up the named file in
14957the directory of the executable file, then in a subdirectory of that
14958directory named @file{.debug}, and finally under the global debug
14959directory, in a subdirectory whose name is identical to the leading
14960directories of the executable's absolute file name.
14961
14962@item
83f83d7f 14963For the ``build ID'' method, @value{GDBN} looks in the
c7e83d54
EZ
14964@file{.build-id} subdirectory of the global debug directory for a file
14965named @file{@var{nn}/@var{nnnnnnnn}.debug}, where @var{nn} are the
7e27a47a
EZ
14966first 2 hex characters of the build ID bit string, and @var{nnnnnnnn}
14967are the rest of the bit string. (Real build ID strings are 32 or more
14968hex characters, not 10.)
c7e83d54
EZ
14969@end itemize
14970
14971So, for example, suppose you ask @value{GDBN} to debug
7e27a47a
EZ
14972@file{/usr/bin/ls}, which has a debug link that specifies the
14973file @file{ls.debug}, and a build ID whose value in hex is
c7e83d54
EZ
14974@code{abcdef1234}. If the global debug directory is
14975@file{/usr/lib/debug}, then @value{GDBN} will look for the following
14976debug information files, in the indicated order:
14977
14978@itemize @minus
14979@item
14980@file{/usr/lib/debug/.build-id/ab/cdef1234.debug}
d3750b24 14981@item
c7e83d54 14982@file{/usr/bin/ls.debug}
5b5d99cf 14983@item
c7e83d54 14984@file{/usr/bin/.debug/ls.debug}
5b5d99cf 14985@item
c7e83d54 14986@file{/usr/lib/debug/usr/bin/ls.debug}.
5b5d99cf 14987@end itemize
5b5d99cf
JB
14988
14989You can set the global debugging info directory's name, and view the
14990name @value{GDBN} is currently using.
14991
14992@table @code
14993
14994@kindex set debug-file-directory
24ddea62
JK
14995@item set debug-file-directory @var{directories}
14996Set the directories which @value{GDBN} searches for separate debugging
14997information files to @var{directory}. Multiple directory components can be set
14998concatenating them by a directory separator.
5b5d99cf
JB
14999
15000@kindex show debug-file-directory
15001@item show debug-file-directory
24ddea62 15002Show the directories @value{GDBN} searches for separate debugging
5b5d99cf
JB
15003information files.
15004
15005@end table
15006
15007@cindex @code{.gnu_debuglink} sections
c7e83d54 15008@cindex debug link sections
5b5d99cf
JB
15009A debug link is a special section of the executable file named
15010@code{.gnu_debuglink}. The section must contain:
15011
15012@itemize
15013@item
15014A filename, with any leading directory components removed, followed by
15015a zero byte,
15016@item
15017zero to three bytes of padding, as needed to reach the next four-byte
15018boundary within the section, and
15019@item
15020a four-byte CRC checksum, stored in the same endianness used for the
15021executable file itself. The checksum is computed on the debugging
15022information file's full contents by the function given below, passing
15023zero as the @var{crc} argument.
15024@end itemize
15025
15026Any executable file format can carry a debug link, as long as it can
15027contain a section named @code{.gnu_debuglink} with the contents
15028described above.
15029
d3750b24 15030@cindex @code{.note.gnu.build-id} sections
c7e83d54 15031@cindex build ID sections
7e27a47a
EZ
15032The build ID is a special section in the executable file (and in other
15033ELF binary files that @value{GDBN} may consider). This section is
15034often named @code{.note.gnu.build-id}, but that name is not mandatory.
15035It contains unique identification for the built files---the ID remains
15036the same across multiple builds of the same build tree. The default
15037algorithm SHA1 produces 160 bits (40 hexadecimal characters) of the
15038content for the build ID string. The same section with an identical
15039value is present in the original built binary with symbols, in its
15040stripped variant, and in the separate debugging information file.
d3750b24 15041
5b5d99cf
JB
15042The debugging information file itself should be an ordinary
15043executable, containing a full set of linker symbols, sections, and
15044debugging information. The sections of the debugging information file
c7e83d54
EZ
15045should have the same names, addresses, and sizes as the original file,
15046but they need not contain any data---much like a @code{.bss} section
5b5d99cf
JB
15047in an ordinary executable.
15048
7e27a47a 15049The @sc{gnu} binary utilities (Binutils) package includes the
c7e83d54
EZ
15050@samp{objcopy} utility that can produce
15051the separated executable / debugging information file pairs using the
15052following commands:
15053
15054@smallexample
15055@kbd{objcopy --only-keep-debug foo foo.debug}
15056@kbd{strip -g foo}
c7e83d54
EZ
15057@end smallexample
15058
15059@noindent
15060These commands remove the debugging
83f83d7f
JK
15061information from the executable file @file{foo} and place it in the file
15062@file{foo.debug}. You can use the first, second or both methods to link the
15063two files:
15064
15065@itemize @bullet
15066@item
15067The debug link method needs the following additional command to also leave
15068behind a debug link in @file{foo}:
15069
15070@smallexample
15071@kbd{objcopy --add-gnu-debuglink=foo.debug foo}
15072@end smallexample
15073
15074Ulrich Drepper's @file{elfutils} package, starting with version 0.53, contains
d3750b24 15075a version of the @code{strip} command such that the command @kbd{strip foo -f
83f83d7f
JK
15076foo.debug} has the same functionality as the two @code{objcopy} commands and
15077the @code{ln -s} command above, together.
15078
15079@item
15080Build ID gets embedded into the main executable using @code{ld --build-id} or
15081the @value{NGCC} counterpart @code{gcc -Wl,--build-id}. Build ID support plus
15082compatibility fixes for debug files separation are present in @sc{gnu} binary
7e27a47a 15083utilities (Binutils) package since version 2.18.
83f83d7f
JK
15084@end itemize
15085
15086@noindent
d3750b24 15087
99e008fe
EZ
15088@cindex CRC algorithm definition
15089The CRC used in @code{.gnu_debuglink} is the CRC-32 defined in
15090IEEE 802.3 using the polynomial:
15091
15092@c TexInfo requires naked braces for multi-digit exponents for Tex
15093@c output, but this causes HTML output to barf. HTML has to be set using
15094@c raw commands. So we end up having to specify this equation in 2
15095@c different ways!
15096@ifhtml
15097@display
15098@html
15099 <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>
15100 + <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
15101@end html
15102@end display
15103@end ifhtml
15104@ifnothtml
15105@display
15106 @math{x^{32} + x^{26} + x^{23} + x^{22} + x^{16} + x^{12} + x^{11}}
15107 @math{+ x^{10} + x^8 + x^7 + x^5 + x^4 + x^2 + x + 1}
15108@end display
15109@end ifnothtml
15110
15111The function is computed byte at a time, taking the least
15112significant bit of each byte first. The initial pattern
15113@code{0xffffffff} is used, to ensure leading zeros affect the CRC and
15114the final result is inverted to ensure trailing zeros also affect the
15115CRC.
15116
15117@emph{Note:} This is the same CRC polynomial as used in handling the
15118@dfn{Remote Serial Protocol} @code{qCRC} packet (@pxref{Remote Protocol,
15119, @value{GDBN} Remote Serial Protocol}). However in the
15120case of the Remote Serial Protocol, the CRC is computed @emph{most}
15121significant bit first, and the result is not inverted, so trailing
15122zeros have no effect on the CRC value.
15123
15124To complete the description, we show below the code of the function
15125which produces the CRC used in @code{.gnu_debuglink}. Inverting the
15126initially supplied @code{crc} argument means that an initial call to
15127this function passing in zero will start computing the CRC using
15128@code{0xffffffff}.
5b5d99cf 15129
4644b6e3 15130@kindex gnu_debuglink_crc32
5b5d99cf
JB
15131@smallexample
15132unsigned long
15133gnu_debuglink_crc32 (unsigned long crc,
15134 unsigned char *buf, size_t len)
15135@{
15136 static const unsigned long crc32_table[256] =
15137 @{
15138 0x00000000, 0x77073096, 0xee0e612c, 0x990951ba, 0x076dc419,
15139 0x706af48f, 0xe963a535, 0x9e6495a3, 0x0edb8832, 0x79dcb8a4,
15140 0xe0d5e91e, 0x97d2d988, 0x09b64c2b, 0x7eb17cbd, 0xe7b82d07,
15141 0x90bf1d91, 0x1db71064, 0x6ab020f2, 0xf3b97148, 0x84be41de,
15142 0x1adad47d, 0x6ddde4eb, 0xf4d4b551, 0x83d385c7, 0x136c9856,
15143 0x646ba8c0, 0xfd62f97a, 0x8a65c9ec, 0x14015c4f, 0x63066cd9,
15144 0xfa0f3d63, 0x8d080df5, 0x3b6e20c8, 0x4c69105e, 0xd56041e4,
15145 0xa2677172, 0x3c03e4d1, 0x4b04d447, 0xd20d85fd, 0xa50ab56b,
15146 0x35b5a8fa, 0x42b2986c, 0xdbbbc9d6, 0xacbcf940, 0x32d86ce3,
15147 0x45df5c75, 0xdcd60dcf, 0xabd13d59, 0x26d930ac, 0x51de003a,
15148 0xc8d75180, 0xbfd06116, 0x21b4f4b5, 0x56b3c423, 0xcfba9599,
15149 0xb8bda50f, 0x2802b89e, 0x5f058808, 0xc60cd9b2, 0xb10be924,
15150 0x2f6f7c87, 0x58684c11, 0xc1611dab, 0xb6662d3d, 0x76dc4190,
15151 0x01db7106, 0x98d220bc, 0xefd5102a, 0x71b18589, 0x06b6b51f,
15152 0x9fbfe4a5, 0xe8b8d433, 0x7807c9a2, 0x0f00f934, 0x9609a88e,
15153 0xe10e9818, 0x7f6a0dbb, 0x086d3d2d, 0x91646c97, 0xe6635c01,
15154 0x6b6b51f4, 0x1c6c6162, 0x856530d8, 0xf262004e, 0x6c0695ed,
15155 0x1b01a57b, 0x8208f4c1, 0xf50fc457, 0x65b0d9c6, 0x12b7e950,
15156 0x8bbeb8ea, 0xfcb9887c, 0x62dd1ddf, 0x15da2d49, 0x8cd37cf3,
15157 0xfbd44c65, 0x4db26158, 0x3ab551ce, 0xa3bc0074, 0xd4bb30e2,
15158 0x4adfa541, 0x3dd895d7, 0xa4d1c46d, 0xd3d6f4fb, 0x4369e96a,
15159 0x346ed9fc, 0xad678846, 0xda60b8d0, 0x44042d73, 0x33031de5,
15160 0xaa0a4c5f, 0xdd0d7cc9, 0x5005713c, 0x270241aa, 0xbe0b1010,
15161 0xc90c2086, 0x5768b525, 0x206f85b3, 0xb966d409, 0xce61e49f,
15162 0x5edef90e, 0x29d9c998, 0xb0d09822, 0xc7d7a8b4, 0x59b33d17,
15163 0x2eb40d81, 0xb7bd5c3b, 0xc0ba6cad, 0xedb88320, 0x9abfb3b6,
15164 0x03b6e20c, 0x74b1d29a, 0xead54739, 0x9dd277af, 0x04db2615,
15165 0x73dc1683, 0xe3630b12, 0x94643b84, 0x0d6d6a3e, 0x7a6a5aa8,
15166 0xe40ecf0b, 0x9309ff9d, 0x0a00ae27, 0x7d079eb1, 0xf00f9344,
15167 0x8708a3d2, 0x1e01f268, 0x6906c2fe, 0xf762575d, 0x806567cb,
15168 0x196c3671, 0x6e6b06e7, 0xfed41b76, 0x89d32be0, 0x10da7a5a,
15169 0x67dd4acc, 0xf9b9df6f, 0x8ebeeff9, 0x17b7be43, 0x60b08ed5,
15170 0xd6d6a3e8, 0xa1d1937e, 0x38d8c2c4, 0x4fdff252, 0xd1bb67f1,
15171 0xa6bc5767, 0x3fb506dd, 0x48b2364b, 0xd80d2bda, 0xaf0a1b4c,
15172 0x36034af6, 0x41047a60, 0xdf60efc3, 0xa867df55, 0x316e8eef,
15173 0x4669be79, 0xcb61b38c, 0xbc66831a, 0x256fd2a0, 0x5268e236,
15174 0xcc0c7795, 0xbb0b4703, 0x220216b9, 0x5505262f, 0xc5ba3bbe,
15175 0xb2bd0b28, 0x2bb45a92, 0x5cb36a04, 0xc2d7ffa7, 0xb5d0cf31,
15176 0x2cd99e8b, 0x5bdeae1d, 0x9b64c2b0, 0xec63f226, 0x756aa39c,
15177 0x026d930a, 0x9c0906a9, 0xeb0e363f, 0x72076785, 0x05005713,
15178 0x95bf4a82, 0xe2b87a14, 0x7bb12bae, 0x0cb61b38, 0x92d28e9b,
15179 0xe5d5be0d, 0x7cdcefb7, 0x0bdbdf21, 0x86d3d2d4, 0xf1d4e242,
15180 0x68ddb3f8, 0x1fda836e, 0x81be16cd, 0xf6b9265b, 0x6fb077e1,
15181 0x18b74777, 0x88085ae6, 0xff0f6a70, 0x66063bca, 0x11010b5c,
15182 0x8f659eff, 0xf862ae69, 0x616bffd3, 0x166ccf45, 0xa00ae278,
15183 0xd70dd2ee, 0x4e048354, 0x3903b3c2, 0xa7672661, 0xd06016f7,
15184 0x4969474d, 0x3e6e77db, 0xaed16a4a, 0xd9d65adc, 0x40df0b66,
15185 0x37d83bf0, 0xa9bcae53, 0xdebb9ec5, 0x47b2cf7f, 0x30b5ffe9,
15186 0xbdbdf21c, 0xcabac28a, 0x53b39330, 0x24b4a3a6, 0xbad03605,
15187 0xcdd70693, 0x54de5729, 0x23d967bf, 0xb3667a2e, 0xc4614ab8,
15188 0x5d681b02, 0x2a6f2b94, 0xb40bbe37, 0xc30c8ea1, 0x5a05df1b,
15189 0x2d02ef8d
15190 @};
15191 unsigned char *end;
15192
15193 crc = ~crc & 0xffffffff;
15194 for (end = buf + len; buf < end; ++buf)
15195 crc = crc32_table[(crc ^ *buf) & 0xff] ^ (crc >> 8);
e7a3abfc 15196 return ~crc & 0xffffffff;
5b5d99cf
JB
15197@}
15198@end smallexample
15199
c7e83d54
EZ
15200@noindent
15201This computation does not apply to the ``build ID'' method.
15202
5b5d99cf 15203
9291a0cd
TT
15204@node Index Files
15205@section Index Files Speed Up @value{GDBN}
15206@cindex index files
15207@cindex @samp{.gdb_index} section
15208
15209When @value{GDBN} finds a symbol file, it scans the symbols in the
15210file in order to construct an internal symbol table. This lets most
15211@value{GDBN} operations work quickly---at the cost of a delay early
15212on. For large programs, this delay can be quite lengthy, so
15213@value{GDBN} provides a way to build an index, which speeds up
15214startup.
15215
15216The index is stored as a section in the symbol file. @value{GDBN} can
15217write the index to a file, then you can put it into the symbol file
15218using @command{objcopy}.
15219
15220To create an index file, use the @code{save gdb-index} command:
15221
15222@table @code
15223@item save gdb-index @var{directory}
15224@kindex save gdb-index
15225Create an index file for each symbol file currently known by
15226@value{GDBN}. Each file is named after its corresponding symbol file,
15227with @samp{.gdb-index} appended, and is written into the given
15228@var{directory}.
15229@end table
15230
15231Once you have created an index file you can merge it into your symbol
15232file, here named @file{symfile}, using @command{objcopy}:
15233
15234@smallexample
15235$ objcopy --add-section .gdb_index=symfile.gdb-index \
15236 --set-section-flags .gdb_index=readonly symfile symfile
15237@end smallexample
15238
15239There are currently some limitation on indices. They only work when
15240for DWARF debugging information, not stabs. And, they do not
15241currently work for programs using Ada.
15242
15243
6d2ebf8b 15244@node Symbol Errors
79a6e687 15245@section Errors Reading Symbol Files
c906108c
SS
15246
15247While reading a symbol file, @value{GDBN} occasionally encounters problems,
15248such as symbol types it does not recognize, or known bugs in compiler
15249output. By default, @value{GDBN} does not notify you of such problems, since
15250they are relatively common and primarily of interest to people
15251debugging compilers. If you are interested in seeing information
15252about ill-constructed symbol tables, you can either ask @value{GDBN} to print
15253only one message about each such type of problem, no matter how many
15254times the problem occurs; or you can ask @value{GDBN} to print more messages,
15255to see how many times the problems occur, with the @code{set
79a6e687
BW
15256complaints} command (@pxref{Messages/Warnings, ,Optional Warnings and
15257Messages}).
c906108c
SS
15258
15259The messages currently printed, and their meanings, include:
15260
15261@table @code
15262@item inner block not inside outer block in @var{symbol}
15263
15264The symbol information shows where symbol scopes begin and end
15265(such as at the start of a function or a block of statements). This
15266error indicates that an inner scope block is not fully contained
15267in its outer scope blocks.
15268
15269@value{GDBN} circumvents the problem by treating the inner block as if it had
15270the same scope as the outer block. In the error message, @var{symbol}
15271may be shown as ``@code{(don't know)}'' if the outer block is not a
15272function.
15273
15274@item block at @var{address} out of order
15275
15276The symbol information for symbol scope blocks should occur in
15277order of increasing addresses. This error indicates that it does not
15278do so.
15279
15280@value{GDBN} does not circumvent this problem, and has trouble
15281locating symbols in the source file whose symbols it is reading. (You
15282can often determine what source file is affected by specifying
79a6e687
BW
15283@code{set verbose on}. @xref{Messages/Warnings, ,Optional Warnings and
15284Messages}.)
c906108c
SS
15285
15286@item bad block start address patched
15287
15288The symbol information for a symbol scope block has a start address
15289smaller than the address of the preceding source line. This is known
15290to occur in the SunOS 4.1.1 (and earlier) C compiler.
15291
15292@value{GDBN} circumvents the problem by treating the symbol scope block as
15293starting on the previous source line.
15294
15295@item bad string table offset in symbol @var{n}
15296
15297@cindex foo
15298Symbol number @var{n} contains a pointer into the string table which is
15299larger than the size of the string table.
15300
15301@value{GDBN} circumvents the problem by considering the symbol to have the
15302name @code{foo}, which may cause other problems if many symbols end up
15303with this name.
15304
15305@item unknown symbol type @code{0x@var{nn}}
15306
7a292a7a
SS
15307The symbol information contains new data types that @value{GDBN} does
15308not yet know how to read. @code{0x@var{nn}} is the symbol type of the
d4f3574e 15309uncomprehended information, in hexadecimal.
c906108c 15310
7a292a7a
SS
15311@value{GDBN} circumvents the error by ignoring this symbol information.
15312This usually allows you to debug your program, though certain symbols
c906108c 15313are not accessible. If you encounter such a problem and feel like
7a292a7a
SS
15314debugging it, you can debug @code{@value{GDBP}} with itself, breakpoint
15315on @code{complain}, then go up to the function @code{read_dbx_symtab}
15316and examine @code{*bufp} to see the symbol.
c906108c
SS
15317
15318@item stub type has NULL name
c906108c 15319
7a292a7a 15320@value{GDBN} could not find the full definition for a struct or class.
c906108c 15321
7a292a7a 15322@item const/volatile indicator missing (ok if using g++ v1.x), got@dots{}
b37052ae 15323The symbol information for a C@t{++} member function is missing some
7a292a7a
SS
15324information that recent versions of the compiler should have output for
15325it.
c906108c
SS
15326
15327@item info mismatch between compiler and debugger
15328
15329@value{GDBN} could not parse a type specification output by the compiler.
7a292a7a 15330
c906108c
SS
15331@end table
15332
b14b1491
TT
15333@node Data Files
15334@section GDB Data Files
15335
15336@cindex prefix for data files
15337@value{GDBN} will sometimes read an auxiliary data file. These files
15338are kept in a directory known as the @dfn{data directory}.
15339
15340You can set the data directory's name, and view the name @value{GDBN}
15341is currently using.
15342
15343@table @code
15344@kindex set data-directory
15345@item set data-directory @var{directory}
15346Set the directory which @value{GDBN} searches for auxiliary data files
15347to @var{directory}.
15348
15349@kindex show data-directory
15350@item show data-directory
15351Show the directory @value{GDBN} searches for auxiliary data files.
15352@end table
15353
15354@cindex default data directory
15355@cindex @samp{--with-gdb-datadir}
15356You can set the default data directory by using the configure-time
15357@samp{--with-gdb-datadir} option. If the data directory is inside
15358@value{GDBN}'s configured binary prefix (set with @samp{--prefix} or
15359@samp{--exec-prefix}), then the default data directory will be updated
15360automatically if the installed @value{GDBN} is moved to a new
15361location.
15362
6d2ebf8b 15363@node Targets
c906108c 15364@chapter Specifying a Debugging Target
7a292a7a 15365
c906108c 15366@cindex debugging target
c906108c 15367A @dfn{target} is the execution environment occupied by your program.
53a5351d
JM
15368
15369Often, @value{GDBN} runs in the same host environment as your program;
15370in that case, the debugging target is specified as a side effect when
15371you use the @code{file} or @code{core} commands. When you need more
c906108c
SS
15372flexibility---for example, running @value{GDBN} on a physically separate
15373host, or controlling a standalone system over a serial port or a
53a5351d
JM
15374realtime system over a TCP/IP connection---you can use the @code{target}
15375command to specify one of the target types configured for @value{GDBN}
79a6e687 15376(@pxref{Target Commands, ,Commands for Managing Targets}).
c906108c 15377
a8f24a35
EZ
15378@cindex target architecture
15379It is possible to build @value{GDBN} for several different @dfn{target
15380architectures}. When @value{GDBN} is built like that, you can choose
15381one of the available architectures with the @kbd{set architecture}
15382command.
15383
15384@table @code
15385@kindex set architecture
15386@kindex show architecture
15387@item set architecture @var{arch}
15388This command sets the current target architecture to @var{arch}. The
15389value of @var{arch} can be @code{"auto"}, in addition to one of the
15390supported architectures.
15391
15392@item show architecture
15393Show the current target architecture.
9c16f35a
EZ
15394
15395@item set processor
15396@itemx processor
15397@kindex set processor
15398@kindex show processor
15399These are alias commands for, respectively, @code{set architecture}
15400and @code{show architecture}.
a8f24a35
EZ
15401@end table
15402
c906108c
SS
15403@menu
15404* Active Targets:: Active targets
15405* Target Commands:: Commands for managing targets
c906108c 15406* Byte Order:: Choosing target byte order
c906108c
SS
15407@end menu
15408
6d2ebf8b 15409@node Active Targets
79a6e687 15410@section Active Targets
7a292a7a 15411
c906108c
SS
15412@cindex stacking targets
15413@cindex active targets
15414@cindex multiple targets
15415
8ea5bce5 15416There are multiple classes of targets such as: processes, executable files or
c0edd9ed
JK
15417recording sessions. Core files belong to the process class, making core file
15418and process mutually exclusive. Otherwise, @value{GDBN} can work concurrently
15419on multiple active targets, one in each class. This allows you to (for
15420example) start a process and inspect its activity, while still having access to
15421the executable file after the process finishes. Or if you start process
15422recording (@pxref{Reverse Execution}) and @code{reverse-step} there, you are
15423presented a virtual layer of the recording target, while the process target
15424remains stopped at the chronologically last point of the process execution.
15425
15426Use the @code{core-file} and @code{exec-file} commands to select a new core
15427file or executable target (@pxref{Files, ,Commands to Specify Files}). To
15428specify as a target a process that is already running, use the @code{attach}
15429command (@pxref{Attach, ,Debugging an Already-running Process}).
c906108c 15430
6d2ebf8b 15431@node Target Commands
79a6e687 15432@section Commands for Managing Targets
c906108c
SS
15433
15434@table @code
15435@item target @var{type} @var{parameters}
7a292a7a
SS
15436Connects the @value{GDBN} host environment to a target machine or
15437process. A target is typically a protocol for talking to debugging
15438facilities. You use the argument @var{type} to specify the type or
15439protocol of the target machine.
c906108c
SS
15440
15441Further @var{parameters} are interpreted by the target protocol, but
15442typically include things like device names or host names to connect
15443with, process numbers, and baud rates.
c906108c
SS
15444
15445The @code{target} command does not repeat if you press @key{RET} again
15446after executing the command.
15447
15448@kindex help target
15449@item help target
15450Displays the names of all targets available. To display targets
15451currently selected, use either @code{info target} or @code{info files}
79a6e687 15452(@pxref{Files, ,Commands to Specify Files}).
c906108c
SS
15453
15454@item help target @var{name}
15455Describe a particular target, including any parameters necessary to
15456select it.
15457
15458@kindex set gnutarget
15459@item set gnutarget @var{args}
5d161b24 15460@value{GDBN} uses its own library BFD to read your files. @value{GDBN}
c906108c 15461knows whether it is reading an @dfn{executable},
5d161b24
DB
15462a @dfn{core}, or a @dfn{.o} file; however, you can specify the file format
15463with the @code{set gnutarget} command. Unlike most @code{target} commands,
c906108c
SS
15464with @code{gnutarget} the @code{target} refers to a program, not a machine.
15465
d4f3574e 15466@quotation
c906108c
SS
15467@emph{Warning:} To specify a file format with @code{set gnutarget},
15468you must know the actual BFD name.
d4f3574e 15469@end quotation
c906108c 15470
d4f3574e 15471@noindent
79a6e687 15472@xref{Files, , Commands to Specify Files}.
c906108c 15473
5d161b24 15474@kindex show gnutarget
c906108c
SS
15475@item show gnutarget
15476Use the @code{show gnutarget} command to display what file format
15477@code{gnutarget} is set to read. If you have not set @code{gnutarget},
15478@value{GDBN} will determine the file format for each file automatically,
15479and @code{show gnutarget} displays @samp{The current BDF target is "auto"}.
15480@end table
15481
4644b6e3 15482@cindex common targets
c906108c
SS
15483Here are some common targets (available, or not, depending on the GDB
15484configuration):
c906108c
SS
15485
15486@table @code
4644b6e3 15487@kindex target
c906108c 15488@item target exec @var{program}
4644b6e3 15489@cindex executable file target
c906108c
SS
15490An executable file. @samp{target exec @var{program}} is the same as
15491@samp{exec-file @var{program}}.
15492
c906108c 15493@item target core @var{filename}
4644b6e3 15494@cindex core dump file target
c906108c
SS
15495A core dump file. @samp{target core @var{filename}} is the same as
15496@samp{core-file @var{filename}}.
c906108c 15497
1a10341b 15498@item target remote @var{medium}
4644b6e3 15499@cindex remote target
1a10341b
JB
15500A remote system connected to @value{GDBN} via a serial line or network
15501connection. This command tells @value{GDBN} to use its own remote
15502protocol over @var{medium} for debugging. @xref{Remote Debugging}.
15503
15504For example, if you have a board connected to @file{/dev/ttya} on the
15505machine running @value{GDBN}, you could say:
15506
15507@smallexample
15508target remote /dev/ttya
15509@end smallexample
15510
15511@code{target remote} supports the @code{load} command. This is only
15512useful if you have some other way of getting the stub to the target
15513system, and you can put it somewhere in memory where it won't get
15514clobbered by the download.
c906108c 15515
ee8e71d4 15516@item target sim @r{[}@var{simargs}@r{]} @dots{}
4644b6e3 15517@cindex built-in simulator target
2df3850c 15518Builtin CPU simulator. @value{GDBN} includes simulators for most architectures.
104c1213 15519In general,
474c8240 15520@smallexample
104c1213
JM
15521 target sim
15522 load
15523 run
474c8240 15524@end smallexample
d4f3574e 15525@noindent
104c1213 15526works; however, you cannot assume that a specific memory map, device
d4f3574e 15527drivers, or even basic I/O is available, although some simulators do
104c1213
JM
15528provide these. For info about any processor-specific simulator details,
15529see the appropriate section in @ref{Embedded Processors, ,Embedded
15530Processors}.
15531
c906108c
SS
15532@end table
15533
104c1213 15534Some configurations may include these targets as well:
c906108c
SS
15535
15536@table @code
15537
c906108c 15538@item target nrom @var{dev}
4644b6e3 15539@cindex NetROM ROM emulator target
c906108c
SS
15540NetROM ROM emulator. This target only supports downloading.
15541
c906108c
SS
15542@end table
15543
5d161b24 15544Different targets are available on different configurations of @value{GDBN};
c906108c 15545your configuration may have more or fewer targets.
c906108c 15546
721c2651
EZ
15547Many remote targets require you to download the executable's code once
15548you've successfully established a connection. You may wish to control
3d00d119
DJ
15549various aspects of this process.
15550
15551@table @code
721c2651
EZ
15552
15553@item set hash
15554@kindex set hash@r{, for remote monitors}
15555@cindex hash mark while downloading
15556This command controls whether a hash mark @samp{#} is displayed while
15557downloading a file to the remote monitor. If on, a hash mark is
15558displayed after each S-record is successfully downloaded to the
15559monitor.
15560
15561@item show hash
15562@kindex show hash@r{, for remote monitors}
15563Show the current status of displaying the hash mark.
15564
15565@item set debug monitor
15566@kindex set debug monitor
15567@cindex display remote monitor communications
15568Enable or disable display of communications messages between
15569@value{GDBN} and the remote monitor.
15570
15571@item show debug monitor
15572@kindex show debug monitor
15573Show the current status of displaying communications between
15574@value{GDBN} and the remote monitor.
a8f24a35 15575@end table
c906108c
SS
15576
15577@table @code
15578
15579@kindex load @var{filename}
15580@item load @var{filename}
8edfe269 15581@anchor{load}
c906108c
SS
15582Depending on what remote debugging facilities are configured into
15583@value{GDBN}, the @code{load} command may be available. Where it exists, it
15584is meant to make @var{filename} (an executable) available for debugging
15585on the remote system---by downloading, or dynamic linking, for example.
15586@code{load} also records the @var{filename} symbol table in @value{GDBN}, like
15587the @code{add-symbol-file} command.
15588
15589If your @value{GDBN} does not have a @code{load} command, attempting to
15590execute it gets the error message ``@code{You can't do that when your
15591target is @dots{}}''
c906108c
SS
15592
15593The file is loaded at whatever address is specified in the executable.
15594For some object file formats, you can specify the load address when you
15595link the program; for other formats, like a.out, the object file format
15596specifies a fixed address.
15597@c FIXME! This would be a good place for an xref to the GNU linker doc.
15598
68437a39
DJ
15599Depending on the remote side capabilities, @value{GDBN} may be able to
15600load programs into flash memory.
15601
c906108c
SS
15602@code{load} does not repeat if you press @key{RET} again after using it.
15603@end table
15604
6d2ebf8b 15605@node Byte Order
79a6e687 15606@section Choosing Target Byte Order
7a292a7a 15607
c906108c
SS
15608@cindex choosing target byte order
15609@cindex target byte order
c906108c 15610
172c2a43 15611Some types of processors, such as the MIPS, PowerPC, and Renesas SH,
c906108c
SS
15612offer the ability to run either big-endian or little-endian byte
15613orders. Usually the executable or symbol will include a bit to
15614designate the endian-ness, and you will not need to worry about
15615which to use. However, you may still find it useful to adjust
d4f3574e 15616@value{GDBN}'s idea of processor endian-ness manually.
c906108c
SS
15617
15618@table @code
4644b6e3 15619@kindex set endian
c906108c
SS
15620@item set endian big
15621Instruct @value{GDBN} to assume the target is big-endian.
15622
c906108c
SS
15623@item set endian little
15624Instruct @value{GDBN} to assume the target is little-endian.
15625
c906108c
SS
15626@item set endian auto
15627Instruct @value{GDBN} to use the byte order associated with the
15628executable.
15629
15630@item show endian
15631Display @value{GDBN}'s current idea of the target byte order.
15632
15633@end table
15634
15635Note that these commands merely adjust interpretation of symbolic
15636data on the host, and that they have absolutely no effect on the
15637target system.
15638
ea35711c
DJ
15639
15640@node Remote Debugging
15641@chapter Debugging Remote Programs
c906108c
SS
15642@cindex remote debugging
15643
15644If you are trying to debug a program running on a machine that cannot run
5d161b24
DB
15645@value{GDBN} in the usual way, it is often useful to use remote debugging.
15646For example, you might use remote debugging on an operating system kernel,
c906108c
SS
15647or on a small system which does not have a general purpose operating system
15648powerful enough to run a full-featured debugger.
15649
15650Some configurations of @value{GDBN} have special serial or TCP/IP interfaces
15651to make this work with particular debugging targets. In addition,
5d161b24 15652@value{GDBN} comes with a generic serial protocol (specific to @value{GDBN},
c906108c
SS
15653but not specific to any particular target system) which you can use if you
15654write the remote stubs---the code that runs on the remote system to
15655communicate with @value{GDBN}.
15656
15657Other remote targets may be available in your
15658configuration of @value{GDBN}; use @code{help target} to list them.
c906108c 15659
6b2f586d 15660@menu
07f31aa6 15661* Connecting:: Connecting to a remote target
a6b151f1 15662* File Transfer:: Sending files to a remote system
6b2f586d 15663* Server:: Using the gdbserver program
79a6e687
BW
15664* Remote Configuration:: Remote configuration
15665* Remote Stub:: Implementing a remote stub
6b2f586d
AC
15666@end menu
15667
07f31aa6 15668@node Connecting
79a6e687 15669@section Connecting to a Remote Target
07f31aa6
DJ
15670
15671On the @value{GDBN} host machine, you will need an unstripped copy of
d3e8051b 15672your program, since @value{GDBN} needs symbol and debugging information.
07f31aa6
DJ
15673Start up @value{GDBN} as usual, using the name of the local copy of your
15674program as the first argument.
15675
86941c27
JB
15676@cindex @code{target remote}
15677@value{GDBN} can communicate with the target over a serial line, or
15678over an @acronym{IP} network using @acronym{TCP} or @acronym{UDP}. In
15679each case, @value{GDBN} uses the same protocol for debugging your
15680program; only the medium carrying the debugging packets varies. The
15681@code{target remote} command establishes a connection to the target.
15682Its arguments indicate which medium to use:
15683
15684@table @code
15685
15686@item target remote @var{serial-device}
07f31aa6 15687@cindex serial line, @code{target remote}
86941c27
JB
15688Use @var{serial-device} to communicate with the target. For example,
15689to use a serial line connected to the device named @file{/dev/ttyb}:
15690
15691@smallexample
15692target remote /dev/ttyb
15693@end smallexample
15694
07f31aa6
DJ
15695If you're using a serial line, you may want to give @value{GDBN} the
15696@w{@samp{--baud}} option, or use the @code{set remotebaud} command
79a6e687 15697(@pxref{Remote Configuration, set remotebaud}) before the
9c16f35a 15698@code{target} command.
07f31aa6 15699
86941c27
JB
15700@item target remote @code{@var{host}:@var{port}}
15701@itemx target remote @code{tcp:@var{host}:@var{port}}
15702@cindex @acronym{TCP} port, @code{target remote}
15703Debug using a @acronym{TCP} connection to @var{port} on @var{host}.
15704The @var{host} may be either a host name or a numeric @acronym{IP}
15705address; @var{port} must be a decimal number. The @var{host} could be
15706the target machine itself, if it is directly connected to the net, or
15707it might be a terminal server which in turn has a serial line to the
15708target.
07f31aa6 15709
86941c27
JB
15710For example, to connect to port 2828 on a terminal server named
15711@code{manyfarms}:
07f31aa6
DJ
15712
15713@smallexample
15714target remote manyfarms:2828
15715@end smallexample
15716
86941c27
JB
15717If your remote target is actually running on the same machine as your
15718debugger session (e.g.@: a simulator for your target running on the
15719same host), you can omit the hostname. For example, to connect to
15720port 1234 on your local machine:
07f31aa6
DJ
15721
15722@smallexample
15723target remote :1234
15724@end smallexample
15725@noindent
15726
15727Note that the colon is still required here.
15728
86941c27
JB
15729@item target remote @code{udp:@var{host}:@var{port}}
15730@cindex @acronym{UDP} port, @code{target remote}
15731Debug using @acronym{UDP} packets to @var{port} on @var{host}. For example, to
15732connect to @acronym{UDP} port 2828 on a terminal server named @code{manyfarms}:
07f31aa6
DJ
15733
15734@smallexample
15735target remote udp:manyfarms:2828
15736@end smallexample
15737
86941c27
JB
15738When using a @acronym{UDP} connection for remote debugging, you should
15739keep in mind that the `U' stands for ``Unreliable''. @acronym{UDP}
15740can silently drop packets on busy or unreliable networks, which will
15741cause havoc with your debugging session.
15742
66b8c7f6
JB
15743@item target remote | @var{command}
15744@cindex pipe, @code{target remote} to
15745Run @var{command} in the background and communicate with it using a
15746pipe. The @var{command} is a shell command, to be parsed and expanded
15747by the system's command shell, @code{/bin/sh}; it should expect remote
15748protocol packets on its standard input, and send replies on its
15749standard output. You could use this to run a stand-alone simulator
15750that speaks the remote debugging protocol, to make net connections
15751using programs like @code{ssh}, or for other similar tricks.
15752
15753If @var{command} closes its standard output (perhaps by exiting),
15754@value{GDBN} will try to send it a @code{SIGTERM} signal. (If the
15755program has already exited, this will have no effect.)
15756
86941c27 15757@end table
07f31aa6 15758
86941c27 15759Once the connection has been established, you can use all the usual
8edfe269
DJ
15760commands to examine and change data. The remote program is already
15761running; you can use @kbd{step} and @kbd{continue}, and you do not
15762need to use @kbd{run}.
07f31aa6
DJ
15763
15764@cindex interrupting remote programs
15765@cindex remote programs, interrupting
15766Whenever @value{GDBN} is waiting for the remote program, if you type the
c8aa23ab 15767interrupt character (often @kbd{Ctrl-c}), @value{GDBN} attempts to stop the
07f31aa6
DJ
15768program. This may or may not succeed, depending in part on the hardware
15769and the serial drivers the remote system uses. If you type the
15770interrupt character once again, @value{GDBN} displays this prompt:
15771
15772@smallexample
15773Interrupted while waiting for the program.
15774Give up (and stop debugging it)? (y or n)
15775@end smallexample
15776
15777If you type @kbd{y}, @value{GDBN} abandons the remote debugging session.
15778(If you decide you want to try again later, you can use @samp{target
15779remote} again to connect once more.) If you type @kbd{n}, @value{GDBN}
15780goes back to waiting.
15781
15782@table @code
15783@kindex detach (remote)
15784@item detach
15785When you have finished debugging the remote program, you can use the
15786@code{detach} command to release it from @value{GDBN} control.
15787Detaching from the target normally resumes its execution, but the results
15788will depend on your particular remote stub. After the @code{detach}
15789command, @value{GDBN} is free to connect to another target.
15790
15791@kindex disconnect
15792@item disconnect
15793The @code{disconnect} command behaves like @code{detach}, except that
15794the target is generally not resumed. It will wait for @value{GDBN}
15795(this instance or another one) to connect and continue debugging. After
15796the @code{disconnect} command, @value{GDBN} is again free to connect to
15797another target.
09d4efe1
EZ
15798
15799@cindex send command to remote monitor
fad38dfa
EZ
15800@cindex extend @value{GDBN} for remote targets
15801@cindex add new commands for external monitor
09d4efe1
EZ
15802@kindex monitor
15803@item monitor @var{cmd}
fad38dfa
EZ
15804This command allows you to send arbitrary commands directly to the
15805remote monitor. Since @value{GDBN} doesn't care about the commands it
15806sends like this, this command is the way to extend @value{GDBN}---you
15807can add new commands that only the external monitor will understand
15808and implement.
07f31aa6
DJ
15809@end table
15810
a6b151f1
DJ
15811@node File Transfer
15812@section Sending files to a remote system
15813@cindex remote target, file transfer
15814@cindex file transfer
15815@cindex sending files to remote systems
15816
15817Some remote targets offer the ability to transfer files over the same
15818connection used to communicate with @value{GDBN}. This is convenient
15819for targets accessible through other means, e.g.@: @sc{gnu}/Linux systems
15820running @code{gdbserver} over a network interface. For other targets,
15821e.g.@: embedded devices with only a single serial port, this may be
15822the only way to upload or download files.
15823
15824Not all remote targets support these commands.
15825
15826@table @code
15827@kindex remote put
15828@item remote put @var{hostfile} @var{targetfile}
15829Copy file @var{hostfile} from the host system (the machine running
15830@value{GDBN}) to @var{targetfile} on the target system.
15831
15832@kindex remote get
15833@item remote get @var{targetfile} @var{hostfile}
15834Copy file @var{targetfile} from the target system to @var{hostfile}
15835on the host system.
15836
15837@kindex remote delete
15838@item remote delete @var{targetfile}
15839Delete @var{targetfile} from the target system.
15840
15841@end table
15842
6f05cf9f 15843@node Server
79a6e687 15844@section Using the @code{gdbserver} Program
6f05cf9f
AC
15845
15846@kindex gdbserver
15847@cindex remote connection without stubs
15848@code{gdbserver} is a control program for Unix-like systems, which
15849allows you to connect your program with a remote @value{GDBN} via
15850@code{target remote}---but without linking in the usual debugging stub.
15851
15852@code{gdbserver} is not a complete replacement for the debugging stubs,
15853because it requires essentially the same operating-system facilities
15854that @value{GDBN} itself does. In fact, a system that can run
15855@code{gdbserver} to connect to a remote @value{GDBN} could also run
15856@value{GDBN} locally! @code{gdbserver} is sometimes useful nevertheless,
15857because it is a much smaller program than @value{GDBN} itself. It is
15858also easier to port than all of @value{GDBN}, so you may be able to get
15859started more quickly on a new system by using @code{gdbserver}.
15860Finally, if you develop code for real-time systems, you may find that
15861the tradeoffs involved in real-time operation make it more convenient to
15862do as much development work as possible on another system, for example
15863by cross-compiling. You can use @code{gdbserver} to make a similar
15864choice for debugging.
15865
15866@value{GDBN} and @code{gdbserver} communicate via either a serial line
15867or a TCP connection, using the standard @value{GDBN} remote serial
15868protocol.
15869
2d717e4f
DJ
15870@quotation
15871@emph{Warning:} @code{gdbserver} does not have any built-in security.
15872Do not run @code{gdbserver} connected to any public network; a
15873@value{GDBN} connection to @code{gdbserver} provides access to the
15874target system with the same privileges as the user running
15875@code{gdbserver}.
15876@end quotation
15877
15878@subsection Running @code{gdbserver}
15879@cindex arguments, to @code{gdbserver}
15880
15881Run @code{gdbserver} on the target system. You need a copy of the
15882program you want to debug, including any libraries it requires.
6f05cf9f
AC
15883@code{gdbserver} does not need your program's symbol table, so you can
15884strip the program if necessary to save space. @value{GDBN} on the host
15885system does all the symbol handling.
15886
15887To use the server, you must tell it how to communicate with @value{GDBN};
56460a61 15888the name of your program; and the arguments for your program. The usual
6f05cf9f
AC
15889syntax is:
15890
15891@smallexample
15892target> gdbserver @var{comm} @var{program} [ @var{args} @dots{} ]
15893@end smallexample
15894
15895@var{comm} is either a device name (to use a serial line) or a TCP
15896hostname and portnumber. For example, to debug Emacs with the argument
15897@samp{foo.txt} and communicate with @value{GDBN} over the serial port
15898@file{/dev/com1}:
15899
15900@smallexample
15901target> gdbserver /dev/com1 emacs foo.txt
15902@end smallexample
15903
15904@code{gdbserver} waits passively for the host @value{GDBN} to communicate
15905with it.
15906
15907To use a TCP connection instead of a serial line:
15908
15909@smallexample
15910target> gdbserver host:2345 emacs foo.txt
15911@end smallexample
15912
15913The only difference from the previous example is the first argument,
15914specifying that you are communicating with the host @value{GDBN} via
15915TCP. The @samp{host:2345} argument means that @code{gdbserver} is to
15916expect a TCP connection from machine @samp{host} to local TCP port 2345.
15917(Currently, the @samp{host} part is ignored.) You can choose any number
15918you want for the port number as long as it does not conflict with any
15919TCP ports already in use on the target system (for example, @code{23} is
15920reserved for @code{telnet}).@footnote{If you choose a port number that
15921conflicts with another service, @code{gdbserver} prints an error message
15922and exits.} You must use the same port number with the host @value{GDBN}
15923@code{target remote} command.
15924
2d717e4f
DJ
15925@subsubsection Attaching to a Running Program
15926
56460a61
DJ
15927On some targets, @code{gdbserver} can also attach to running programs.
15928This is accomplished via the @code{--attach} argument. The syntax is:
15929
15930@smallexample
2d717e4f 15931target> gdbserver --attach @var{comm} @var{pid}
56460a61
DJ
15932@end smallexample
15933
15934@var{pid} is the process ID of a currently running process. It isn't necessary
15935to point @code{gdbserver} at a binary for the running process.
15936
b1fe9455
DJ
15937@pindex pidof
15938@cindex attach to a program by name
15939You can debug processes by name instead of process ID if your target has the
15940@code{pidof} utility:
15941
15942@smallexample
2d717e4f 15943target> gdbserver --attach @var{comm} `pidof @var{program}`
b1fe9455
DJ
15944@end smallexample
15945
f822c95b 15946In case more than one copy of @var{program} is running, or @var{program}
b1fe9455
DJ
15947has multiple threads, most versions of @code{pidof} support the
15948@code{-s} option to only return the first process ID.
15949
2d717e4f
DJ
15950@subsubsection Multi-Process Mode for @code{gdbserver}
15951@cindex gdbserver, multiple processes
15952@cindex multiple processes with gdbserver
15953
15954When you connect to @code{gdbserver} using @code{target remote},
15955@code{gdbserver} debugs the specified program only once. When the
15956program exits, or you detach from it, @value{GDBN} closes the connection
15957and @code{gdbserver} exits.
15958
6e6c6f50 15959If you connect using @kbd{target extended-remote}, @code{gdbserver}
2d717e4f
DJ
15960enters multi-process mode. When the debugged program exits, or you
15961detach from it, @value{GDBN} stays connected to @code{gdbserver} even
15962though no program is running. The @code{run} and @code{attach}
15963commands instruct @code{gdbserver} to run or attach to a new program.
15964The @code{run} command uses @code{set remote exec-file} (@pxref{set
15965remote exec-file}) to select the program to run. Command line
15966arguments are supported, except for wildcard expansion and I/O
15967redirection (@pxref{Arguments}).
15968
15969To start @code{gdbserver} without supplying an initial command to run
15970or process ID to attach, use the @option{--multi} command line option.
6e6c6f50 15971Then you can connect using @kbd{target extended-remote} and start
2d717e4f
DJ
15972the program you want to debug.
15973
15974@code{gdbserver} does not automatically exit in multi-process mode.
15975You can terminate it by using @code{monitor exit}
15976(@pxref{Monitor Commands for gdbserver}).
15977
15978@subsubsection Other Command-Line Arguments for @code{gdbserver}
15979
62709adf
PA
15980The @option{--debug} option tells @code{gdbserver} to display extra
15981status information about the debugging process. The
15982@option{--remote-debug} option tells @code{gdbserver} to display
15983remote protocol debug output. These options are intended for
15984@code{gdbserver} development and for bug reports to the developers.
2d717e4f 15985
ccd213ac
DJ
15986The @option{--wrapper} option specifies a wrapper to launch programs
15987for debugging. The option should be followed by the name of the
15988wrapper, then any command-line arguments to pass to the wrapper, then
15989@kbd{--} indicating the end of the wrapper arguments.
15990
15991@code{gdbserver} runs the specified wrapper program with a combined
15992command line including the wrapper arguments, then the name of the
15993program to debug, then any arguments to the program. The wrapper
15994runs until it executes your program, and then @value{GDBN} gains control.
15995
15996You can use any program that eventually calls @code{execve} with
15997its arguments as a wrapper. Several standard Unix utilities do
15998this, e.g.@: @code{env} and @code{nohup}. Any Unix shell script ending
15999with @code{exec "$@@"} will also work.
16000
16001For example, you can use @code{env} to pass an environment variable to
16002the debugged program, without setting the variable in @code{gdbserver}'s
16003environment:
16004
16005@smallexample
16006$ gdbserver --wrapper env LD_PRELOAD=libtest.so -- :2222 ./testprog
16007@end smallexample
16008
2d717e4f
DJ
16009@subsection Connecting to @code{gdbserver}
16010
16011Run @value{GDBN} on the host system.
16012
16013First make sure you have the necessary symbol files. Load symbols for
f822c95b
DJ
16014your application using the @code{file} command before you connect. Use
16015@code{set sysroot} to locate target libraries (unless your @value{GDBN}
2d717e4f 16016was compiled with the correct sysroot using @code{--with-sysroot}).
f822c95b
DJ
16017
16018The symbol file and target libraries must exactly match the executable
16019and libraries on the target, with one exception: the files on the host
16020system should not be stripped, even if the files on the target system
16021are. Mismatched or missing files will lead to confusing results
16022during debugging. On @sc{gnu}/Linux targets, mismatched or missing
16023files may also prevent @code{gdbserver} from debugging multi-threaded
16024programs.
16025
79a6e687 16026Connect to your target (@pxref{Connecting,,Connecting to a Remote Target}).
6f05cf9f
AC
16027For TCP connections, you must start up @code{gdbserver} prior to using
16028the @code{target remote} command. Otherwise you may get an error whose
16029text depends on the host system, but which usually looks something like
2d717e4f 16030@samp{Connection refused}. Don't use the @code{load}
397ca115 16031command in @value{GDBN} when using @code{gdbserver}, since the program is
f822c95b 16032already on the target.
07f31aa6 16033
79a6e687 16034@subsection Monitor Commands for @code{gdbserver}
c74d0ad8 16035@cindex monitor commands, for @code{gdbserver}
2d717e4f 16036@anchor{Monitor Commands for gdbserver}
c74d0ad8
DJ
16037
16038During a @value{GDBN} session using @code{gdbserver}, you can use the
16039@code{monitor} command to send special requests to @code{gdbserver}.
2d717e4f 16040Here are the available commands.
c74d0ad8
DJ
16041
16042@table @code
16043@item monitor help
16044List the available monitor commands.
16045
16046@item monitor set debug 0
16047@itemx monitor set debug 1
16048Disable or enable general debugging messages.
16049
16050@item monitor set remote-debug 0
16051@itemx monitor set remote-debug 1
16052Disable or enable specific debugging messages associated with the remote
16053protocol (@pxref{Remote Protocol}).
16054
cdbfd419
PP
16055@item monitor set libthread-db-search-path [PATH]
16056@cindex gdbserver, search path for @code{libthread_db}
16057When this command is issued, @var{path} is a colon-separated list of
16058directories to search for @code{libthread_db} (@pxref{Threads,,set
16059libthread-db-search-path}). If you omit @var{path},
16060@samp{libthread-db-search-path} will be reset to an empty list.
16061
2d717e4f
DJ
16062@item monitor exit
16063Tell gdbserver to exit immediately. This command should be followed by
16064@code{disconnect} to close the debugging session. @code{gdbserver} will
16065detach from any attached processes and kill any processes it created.
16066Use @code{monitor exit} to terminate @code{gdbserver} at the end
16067of a multi-process mode debug session.
16068
c74d0ad8
DJ
16069@end table
16070
fa593d66
PA
16071@subsection Tracepoints support in @code{gdbserver}
16072@cindex tracepoints support in @code{gdbserver}
16073
0fb4aa4b
PA
16074On some targets, @code{gdbserver} supports tracepoints, fast
16075tracepoints and static tracepoints.
fa593d66 16076
0fb4aa4b 16077For fast or static tracepoints to work, a special library called the
fa593d66
PA
16078@dfn{in-process agent} (IPA), must be loaded in the inferior process.
16079This library is built and distributed as an integral part of
0fb4aa4b
PA
16080@code{gdbserver}. In addition, support for static tracepoints
16081requires building the in-process agent library with static tracepoints
16082support. At present, the UST (LTTng Userspace Tracer,
16083@url{http://lttng.org/ust}) tracing engine is supported. This support
16084is automatically available if UST development headers are found in the
16085standard include path when @code{gdbserver} is built, or if
16086@code{gdbserver} was explicitly configured using @option{--with-ust}
16087to point at such headers. You can explicitly disable the support
16088using @option{--with-ust=no}.
fa593d66
PA
16089
16090There are several ways to load the in-process agent in your program:
16091
16092@table @code
16093@item Specifying it as dependency at link time
16094
16095You can link your program dynamically with the in-process agent
16096library. On most systems, this is accomplished by adding
16097@code{-linproctrace} to the link command.
16098
16099@item Using the system's preloading mechanisms
16100
16101You can force loading the in-process agent at startup time by using
16102your system's support for preloading shared libraries. Many Unixes
16103support the concept of preloading user defined libraries. In most
16104cases, you do that by specifying @code{LD_PRELOAD=libinproctrace.so}
16105in the environment. See also the description of @code{gdbserver}'s
16106@option{--wrapper} command line option.
16107
16108@item Using @value{GDBN} to force loading the agent at run time
16109
16110On some systems, you can force the inferior to load a shared library,
16111by calling a dynamic loader function in the inferior that takes care
16112of dynamically looking up and loading a shared library. On most Unix
16113systems, the function is @code{dlopen}. You'll use the @code{call}
16114command for that. For example:
16115
16116@smallexample
16117(@value{GDBP}) call dlopen ("libinproctrace.so", ...)
16118@end smallexample
16119
16120Note that on most Unix systems, for the @code{dlopen} function to be
16121available, the program needs to be linked with @code{-ldl}.
16122@end table
16123
16124On systems that have a userspace dynamic loader, like most Unix
16125systems, when you connect to @code{gdbserver} using @code{target
16126remote}, you'll find that the program is stopped at the dynamic
16127loader's entry point, and no shared library has been loaded in the
16128program's address space yet, including the in-process agent. In that
0fb4aa4b
PA
16129case, before being able to use any of the fast or static tracepoints
16130features, you need to let the loader run and load the shared
16131libraries. The simplest way to do that is to run the program to the
16132main procedure. E.g., if debugging a C or C@t{++} program, start
fa593d66
PA
16133@code{gdbserver} like so:
16134
16135@smallexample
16136$ gdbserver :9999 myprogram
16137@end smallexample
16138
16139Start GDB and connect to @code{gdbserver} like so, and run to main:
16140
16141@smallexample
16142$ gdb myprogram
16143(@value{GDBP}) target remote myhost:9999
161440x00007f215893ba60 in ?? () from /lib64/ld-linux-x86-64.so.2
16145(@value{GDBP}) b main
16146(@value{GDBP}) continue
16147@end smallexample
16148
16149The in-process tracing agent library should now be loaded into the
16150process; you can confirm it with the @code{info sharedlibrary}
16151command, which will list @file{libinproctrace.so} as loaded in the
0fb4aa4b
PA
16152process. You are now ready to install fast tracepoints, list static
16153tracepoint markers, probe static tracepoints markers, and start
fa593d66
PA
16154tracing.
16155
79a6e687
BW
16156@node Remote Configuration
16157@section Remote Configuration
501eef12 16158
9c16f35a
EZ
16159@kindex set remote
16160@kindex show remote
16161This section documents the configuration options available when
16162debugging remote programs. For the options related to the File I/O
fc320d37 16163extensions of the remote protocol, see @ref{system,
9c16f35a 16164system-call-allowed}.
501eef12
AC
16165
16166@table @code
9c16f35a 16167@item set remoteaddresssize @var{bits}
d3e8051b 16168@cindex address size for remote targets
9c16f35a
EZ
16169@cindex bits in remote address
16170Set the maximum size of address in a memory packet to the specified
16171number of bits. @value{GDBN} will mask off the address bits above
16172that number, when it passes addresses to the remote target. The
16173default value is the number of bits in the target's address.
16174
16175@item show remoteaddresssize
16176Show the current value of remote address size in bits.
16177
16178@item set remotebaud @var{n}
16179@cindex baud rate for remote targets
16180Set the baud rate for the remote serial I/O to @var{n} baud. The
16181value is used to set the speed of the serial port used for debugging
16182remote targets.
16183
16184@item show remotebaud
16185Show the current speed of the remote connection.
16186
16187@item set remotebreak
16188@cindex interrupt remote programs
16189@cindex BREAK signal instead of Ctrl-C
9a6253be 16190@anchor{set remotebreak}
9c16f35a 16191If set to on, @value{GDBN} sends a @code{BREAK} signal to the remote
c8aa23ab 16192when you type @kbd{Ctrl-c} to interrupt the program running
9a7a1b36 16193on the remote. If set to off, @value{GDBN} sends the @samp{Ctrl-C}
9c16f35a
EZ
16194character instead. The default is off, since most remote systems
16195expect to see @samp{Ctrl-C} as the interrupt signal.
16196
16197@item show remotebreak
16198Show whether @value{GDBN} sends @code{BREAK} or @samp{Ctrl-C} to
16199interrupt the remote program.
16200
23776285
MR
16201@item set remoteflow on
16202@itemx set remoteflow off
16203@kindex set remoteflow
16204Enable or disable hardware flow control (@code{RTS}/@code{CTS})
16205on the serial port used to communicate to the remote target.
16206
16207@item show remoteflow
16208@kindex show remoteflow
16209Show the current setting of hardware flow control.
16210
9c16f35a
EZ
16211@item set remotelogbase @var{base}
16212Set the base (a.k.a.@: radix) of logging serial protocol
16213communications to @var{base}. Supported values of @var{base} are:
16214@code{ascii}, @code{octal}, and @code{hex}. The default is
16215@code{ascii}.
16216
16217@item show remotelogbase
16218Show the current setting of the radix for logging remote serial
16219protocol.
16220
16221@item set remotelogfile @var{file}
16222@cindex record serial communications on file
16223Record remote serial communications on the named @var{file}. The
16224default is not to record at all.
16225
16226@item show remotelogfile.
16227Show the current setting of the file name on which to record the
16228serial communications.
16229
16230@item set remotetimeout @var{num}
16231@cindex timeout for serial communications
16232@cindex remote timeout
16233Set the timeout limit to wait for the remote target to respond to
16234@var{num} seconds. The default is 2 seconds.
16235
16236@item show remotetimeout
16237Show the current number of seconds to wait for the remote target
16238responses.
16239
16240@cindex limit hardware breakpoints and watchpoints
16241@cindex remote target, limit break- and watchpoints
501eef12
AC
16242@anchor{set remote hardware-watchpoint-limit}
16243@anchor{set remote hardware-breakpoint-limit}
16244@item set remote hardware-watchpoint-limit @var{limit}
16245@itemx set remote hardware-breakpoint-limit @var{limit}
16246Restrict @value{GDBN} to using @var{limit} remote hardware breakpoint or
16247watchpoints. A limit of -1, the default, is treated as unlimited.
2d717e4f
DJ
16248
16249@item set remote exec-file @var{filename}
16250@itemx show remote exec-file
16251@anchor{set remote exec-file}
16252@cindex executable file, for remote target
16253Select the file used for @code{run} with @code{target
16254extended-remote}. This should be set to a filename valid on the
16255target system. If it is not set, the target will use a default
16256filename (e.g.@: the last program run).
84603566 16257
9a7071a8
JB
16258@item set remote interrupt-sequence
16259@cindex interrupt remote programs
16260@cindex select Ctrl-C, BREAK or BREAK-g
16261Allow the user to select one of @samp{Ctrl-C}, a @code{BREAK} or
16262@samp{BREAK-g} as the
16263sequence to the remote target in order to interrupt the execution.
16264@samp{Ctrl-C} is a default. Some system prefers @code{BREAK} which
16265is high level of serial line for some certain time.
16266Linux kernel prefers @samp{BREAK-g}, a.k.a Magic SysRq g.
16267It is @code{BREAK} signal followed by character @code{g}.
16268
16269@item show interrupt-sequence
16270Show which of @samp{Ctrl-C}, @code{BREAK} or @code{BREAK-g}
16271is sent by @value{GDBN} to interrupt the remote program.
16272@code{BREAK-g} is BREAK signal followed by @code{g} and
16273also known as Magic SysRq g.
16274
16275@item set remote interrupt-on-connect
16276@cindex send interrupt-sequence on start
16277Specify whether interrupt-sequence is sent to remote target when
16278@value{GDBN} connects to it. This is mostly needed when you debug
16279Linux kernel. Linux kernel expects @code{BREAK} followed by @code{g}
16280which is known as Magic SysRq g in order to connect @value{GDBN}.
16281
16282@item show interrupt-on-connect
16283Show whether interrupt-sequence is sent
16284to remote target when @value{GDBN} connects to it.
16285
84603566
SL
16286@kindex set tcp
16287@kindex show tcp
16288@item set tcp auto-retry on
16289@cindex auto-retry, for remote TCP target
16290Enable auto-retry for remote TCP connections. This is useful if the remote
16291debugging agent is launched in parallel with @value{GDBN}; there is a race
16292condition because the agent may not become ready to accept the connection
16293before @value{GDBN} attempts to connect. When auto-retry is
16294enabled, if the initial attempt to connect fails, @value{GDBN} reattempts
16295to establish the connection using the timeout specified by
16296@code{set tcp connect-timeout}.
16297
16298@item set tcp auto-retry off
16299Do not auto-retry failed TCP connections.
16300
16301@item show tcp auto-retry
16302Show the current auto-retry setting.
16303
16304@item set tcp connect-timeout @var{seconds}
16305@cindex connection timeout, for remote TCP target
16306@cindex timeout, for remote target connection
16307Set the timeout for establishing a TCP connection to the remote target to
16308@var{seconds}. The timeout affects both polling to retry failed connections
16309(enabled by @code{set tcp auto-retry on}) and waiting for connections
16310that are merely slow to complete, and represents an approximate cumulative
16311value.
16312
16313@item show tcp connect-timeout
16314Show the current connection timeout setting.
501eef12
AC
16315@end table
16316
427c3a89
DJ
16317@cindex remote packets, enabling and disabling
16318The @value{GDBN} remote protocol autodetects the packets supported by
16319your debugging stub. If you need to override the autodetection, you
16320can use these commands to enable or disable individual packets. Each
16321packet can be set to @samp{on} (the remote target supports this
16322packet), @samp{off} (the remote target does not support this packet),
16323or @samp{auto} (detect remote target support for this packet). They
16324all default to @samp{auto}. For more information about each packet,
16325see @ref{Remote Protocol}.
16326
16327During normal use, you should not have to use any of these commands.
16328If you do, that may be a bug in your remote debugging stub, or a bug
16329in @value{GDBN}. You may want to report the problem to the
16330@value{GDBN} developers.
16331
cfa9d6d9
DJ
16332For each packet @var{name}, the command to enable or disable the
16333packet is @code{set remote @var{name}-packet}. The available settings
16334are:
427c3a89 16335
cfa9d6d9 16336@multitable @columnfractions 0.28 0.32 0.25
427c3a89
DJ
16337@item Command Name
16338@tab Remote Packet
16339@tab Related Features
16340
cfa9d6d9 16341@item @code{fetch-register}
427c3a89
DJ
16342@tab @code{p}
16343@tab @code{info registers}
16344
cfa9d6d9 16345@item @code{set-register}
427c3a89
DJ
16346@tab @code{P}
16347@tab @code{set}
16348
cfa9d6d9 16349@item @code{binary-download}
427c3a89
DJ
16350@tab @code{X}
16351@tab @code{load}, @code{set}
16352
cfa9d6d9 16353@item @code{read-aux-vector}
427c3a89
DJ
16354@tab @code{qXfer:auxv:read}
16355@tab @code{info auxv}
16356
cfa9d6d9 16357@item @code{symbol-lookup}
427c3a89
DJ
16358@tab @code{qSymbol}
16359@tab Detecting multiple threads
16360
2d717e4f
DJ
16361@item @code{attach}
16362@tab @code{vAttach}
16363@tab @code{attach}
16364
cfa9d6d9 16365@item @code{verbose-resume}
427c3a89
DJ
16366@tab @code{vCont}
16367@tab Stepping or resuming multiple threads
16368
2d717e4f
DJ
16369@item @code{run}
16370@tab @code{vRun}
16371@tab @code{run}
16372
cfa9d6d9 16373@item @code{software-breakpoint}
427c3a89
DJ
16374@tab @code{Z0}
16375@tab @code{break}
16376
cfa9d6d9 16377@item @code{hardware-breakpoint}
427c3a89
DJ
16378@tab @code{Z1}
16379@tab @code{hbreak}
16380
cfa9d6d9 16381@item @code{write-watchpoint}
427c3a89
DJ
16382@tab @code{Z2}
16383@tab @code{watch}
16384
cfa9d6d9 16385@item @code{read-watchpoint}
427c3a89
DJ
16386@tab @code{Z3}
16387@tab @code{rwatch}
16388
cfa9d6d9 16389@item @code{access-watchpoint}
427c3a89
DJ
16390@tab @code{Z4}
16391@tab @code{awatch}
16392
cfa9d6d9
DJ
16393@item @code{target-features}
16394@tab @code{qXfer:features:read}
16395@tab @code{set architecture}
16396
16397@item @code{library-info}
16398@tab @code{qXfer:libraries:read}
16399@tab @code{info sharedlibrary}
16400
16401@item @code{memory-map}
16402@tab @code{qXfer:memory-map:read}
16403@tab @code{info mem}
16404
0fb4aa4b
PA
16405@item @code{read-sdata-object}
16406@tab @code{qXfer:sdata:read}
16407@tab @code{print $_sdata}
16408
cfa9d6d9
DJ
16409@item @code{read-spu-object}
16410@tab @code{qXfer:spu:read}
16411@tab @code{info spu}
16412
16413@item @code{write-spu-object}
16414@tab @code{qXfer:spu:write}
16415@tab @code{info spu}
16416
4aa995e1
PA
16417@item @code{read-siginfo-object}
16418@tab @code{qXfer:siginfo:read}
16419@tab @code{print $_siginfo}
16420
16421@item @code{write-siginfo-object}
16422@tab @code{qXfer:siginfo:write}
16423@tab @code{set $_siginfo}
16424
dc146f7c
VP
16425@item @code{threads}
16426@tab @code{qXfer:threads:read}
16427@tab @code{info threads}
16428
cfa9d6d9 16429@item @code{get-thread-local-@*storage-address}
427c3a89
DJ
16430@tab @code{qGetTLSAddr}
16431@tab Displaying @code{__thread} variables
16432
711e434b
PM
16433@item @code{get-thread-information-block-address}
16434@tab @code{qGetTIBAddr}
16435@tab Display MS-Windows Thread Information Block.
16436
08388c79
DE
16437@item @code{search-memory}
16438@tab @code{qSearch:memory}
16439@tab @code{find}
16440
427c3a89
DJ
16441@item @code{supported-packets}
16442@tab @code{qSupported}
16443@tab Remote communications parameters
16444
cfa9d6d9 16445@item @code{pass-signals}
89be2091
DJ
16446@tab @code{QPassSignals}
16447@tab @code{handle @var{signal}}
16448
a6b151f1
DJ
16449@item @code{hostio-close-packet}
16450@tab @code{vFile:close}
16451@tab @code{remote get}, @code{remote put}
16452
16453@item @code{hostio-open-packet}
16454@tab @code{vFile:open}
16455@tab @code{remote get}, @code{remote put}
16456
16457@item @code{hostio-pread-packet}
16458@tab @code{vFile:pread}
16459@tab @code{remote get}, @code{remote put}
16460
16461@item @code{hostio-pwrite-packet}
16462@tab @code{vFile:pwrite}
16463@tab @code{remote get}, @code{remote put}
16464
16465@item @code{hostio-unlink-packet}
16466@tab @code{vFile:unlink}
16467@tab @code{remote delete}
a6f3e723
SL
16468
16469@item @code{noack-packet}
16470@tab @code{QStartNoAckMode}
16471@tab Packet acknowledgment
07e059b5
VP
16472
16473@item @code{osdata}
16474@tab @code{qXfer:osdata:read}
16475@tab @code{info os}
0b16c5cf
PA
16476
16477@item @code{query-attached}
16478@tab @code{qAttached}
16479@tab Querying remote process attach state.
427c3a89
DJ
16480@end multitable
16481
79a6e687
BW
16482@node Remote Stub
16483@section Implementing a Remote Stub
7a292a7a 16484
8e04817f
AC
16485@cindex debugging stub, example
16486@cindex remote stub, example
16487@cindex stub example, remote debugging
16488The stub files provided with @value{GDBN} implement the target side of the
16489communication protocol, and the @value{GDBN} side is implemented in the
16490@value{GDBN} source file @file{remote.c}. Normally, you can simply allow
16491these subroutines to communicate, and ignore the details. (If you're
16492implementing your own stub file, you can still ignore the details: start
16493with one of the existing stub files. @file{sparc-stub.c} is the best
16494organized, and therefore the easiest to read.)
16495
104c1213
JM
16496@cindex remote serial debugging, overview
16497To debug a program running on another machine (the debugging
16498@dfn{target} machine), you must first arrange for all the usual
16499prerequisites for the program to run by itself. For example, for a C
16500program, you need:
c906108c 16501
104c1213
JM
16502@enumerate
16503@item
16504A startup routine to set up the C runtime environment; these usually
16505have a name like @file{crt0}. The startup routine may be supplied by
16506your hardware supplier, or you may have to write your own.
96baa820 16507
5d161b24 16508@item
d4f3574e 16509A C subroutine library to support your program's
104c1213 16510subroutine calls, notably managing input and output.
96baa820 16511
104c1213
JM
16512@item
16513A way of getting your program to the other machine---for example, a
16514download program. These are often supplied by the hardware
16515manufacturer, but you may have to write your own from hardware
16516documentation.
16517@end enumerate
96baa820 16518
104c1213
JM
16519The next step is to arrange for your program to use a serial port to
16520communicate with the machine where @value{GDBN} is running (the @dfn{host}
16521machine). In general terms, the scheme looks like this:
96baa820 16522
104c1213
JM
16523@table @emph
16524@item On the host,
16525@value{GDBN} already understands how to use this protocol; when everything
16526else is set up, you can simply use the @samp{target remote} command
16527(@pxref{Targets,,Specifying a Debugging Target}).
16528
16529@item On the target,
16530you must link with your program a few special-purpose subroutines that
16531implement the @value{GDBN} remote serial protocol. The file containing these
16532subroutines is called a @dfn{debugging stub}.
16533
16534On certain remote targets, you can use an auxiliary program
16535@code{gdbserver} instead of linking a stub into your program.
79a6e687 16536@xref{Server,,Using the @code{gdbserver} Program}, for details.
104c1213 16537@end table
96baa820 16538
104c1213
JM
16539The debugging stub is specific to the architecture of the remote
16540machine; for example, use @file{sparc-stub.c} to debug programs on
16541@sc{sparc} boards.
96baa820 16542
104c1213
JM
16543@cindex remote serial stub list
16544These working remote stubs are distributed with @value{GDBN}:
96baa820 16545
104c1213
JM
16546@table @code
16547
16548@item i386-stub.c
41afff9a 16549@cindex @file{i386-stub.c}
104c1213
JM
16550@cindex Intel
16551@cindex i386
16552For Intel 386 and compatible architectures.
16553
16554@item m68k-stub.c
41afff9a 16555@cindex @file{m68k-stub.c}
104c1213
JM
16556@cindex Motorola 680x0
16557@cindex m680x0
16558For Motorola 680x0 architectures.
16559
16560@item sh-stub.c
41afff9a 16561@cindex @file{sh-stub.c}
172c2a43 16562@cindex Renesas
104c1213 16563@cindex SH
172c2a43 16564For Renesas SH architectures.
104c1213
JM
16565
16566@item sparc-stub.c
41afff9a 16567@cindex @file{sparc-stub.c}
104c1213
JM
16568@cindex Sparc
16569For @sc{sparc} architectures.
16570
16571@item sparcl-stub.c
41afff9a 16572@cindex @file{sparcl-stub.c}
104c1213
JM
16573@cindex Fujitsu
16574@cindex SparcLite
16575For Fujitsu @sc{sparclite} architectures.
16576
16577@end table
16578
16579The @file{README} file in the @value{GDBN} distribution may list other
16580recently added stubs.
16581
16582@menu
16583* Stub Contents:: What the stub can do for you
16584* Bootstrapping:: What you must do for the stub
16585* Debug Session:: Putting it all together
104c1213
JM
16586@end menu
16587
6d2ebf8b 16588@node Stub Contents
79a6e687 16589@subsection What the Stub Can Do for You
104c1213
JM
16590
16591@cindex remote serial stub
16592The debugging stub for your architecture supplies these three
16593subroutines:
16594
16595@table @code
16596@item set_debug_traps
4644b6e3 16597@findex set_debug_traps
104c1213
JM
16598@cindex remote serial stub, initialization
16599This routine arranges for @code{handle_exception} to run when your
16600program stops. You must call this subroutine explicitly near the
16601beginning of your program.
16602
16603@item handle_exception
4644b6e3 16604@findex handle_exception
104c1213
JM
16605@cindex remote serial stub, main routine
16606This is the central workhorse, but your program never calls it
16607explicitly---the setup code arranges for @code{handle_exception} to
16608run when a trap is triggered.
16609
16610@code{handle_exception} takes control when your program stops during
16611execution (for example, on a breakpoint), and mediates communications
16612with @value{GDBN} on the host machine. This is where the communications
16613protocol is implemented; @code{handle_exception} acts as the @value{GDBN}
d4f3574e 16614representative on the target machine. It begins by sending summary
104c1213
JM
16615information on the state of your program, then continues to execute,
16616retrieving and transmitting any information @value{GDBN} needs, until you
16617execute a @value{GDBN} command that makes your program resume; at that point,
16618@code{handle_exception} returns control to your own code on the target
5d161b24 16619machine.
104c1213
JM
16620
16621@item breakpoint
16622@cindex @code{breakpoint} subroutine, remote
16623Use this auxiliary subroutine to make your program contain a
16624breakpoint. Depending on the particular situation, this may be the only
16625way for @value{GDBN} to get control. For instance, if your target
16626machine has some sort of interrupt button, you won't need to call this;
16627pressing the interrupt button transfers control to
16628@code{handle_exception}---in effect, to @value{GDBN}. On some machines,
16629simply receiving characters on the serial port may also trigger a trap;
16630again, in that situation, you don't need to call @code{breakpoint} from
16631your own program---simply running @samp{target remote} from the host
5d161b24 16632@value{GDBN} session gets control.
104c1213
JM
16633
16634Call @code{breakpoint} if none of these is true, or if you simply want
16635to make certain your program stops at a predetermined point for the
16636start of your debugging session.
16637@end table
16638
6d2ebf8b 16639@node Bootstrapping
79a6e687 16640@subsection What You Must Do for the Stub
104c1213
JM
16641
16642@cindex remote stub, support routines
16643The debugging stubs that come with @value{GDBN} are set up for a particular
16644chip architecture, but they have no information about the rest of your
16645debugging target machine.
16646
16647First of all you need to tell the stub how to communicate with the
16648serial port.
16649
16650@table @code
16651@item int getDebugChar()
4644b6e3 16652@findex getDebugChar
104c1213
JM
16653Write this subroutine to read a single character from the serial port.
16654It may be identical to @code{getchar} for your target system; a
16655different name is used to allow you to distinguish the two if you wish.
16656
16657@item void putDebugChar(int)
4644b6e3 16658@findex putDebugChar
104c1213 16659Write this subroutine to write a single character to the serial port.
5d161b24 16660It may be identical to @code{putchar} for your target system; a
104c1213
JM
16661different name is used to allow you to distinguish the two if you wish.
16662@end table
16663
16664@cindex control C, and remote debugging
16665@cindex interrupting remote targets
16666If you want @value{GDBN} to be able to stop your program while it is
16667running, you need to use an interrupt-driven serial driver, and arrange
16668for it to stop when it receives a @code{^C} (@samp{\003}, the control-C
16669character). That is the character which @value{GDBN} uses to tell the
16670remote system to stop.
16671
16672Getting the debugging target to return the proper status to @value{GDBN}
16673probably requires changes to the standard stub; one quick and dirty way
16674is to just execute a breakpoint instruction (the ``dirty'' part is that
16675@value{GDBN} reports a @code{SIGTRAP} instead of a @code{SIGINT}).
16676
16677Other routines you need to supply are:
16678
16679@table @code
16680@item void exceptionHandler (int @var{exception_number}, void *@var{exception_address})
4644b6e3 16681@findex exceptionHandler
104c1213
JM
16682Write this function to install @var{exception_address} in the exception
16683handling tables. You need to do this because the stub does not have any
16684way of knowing what the exception handling tables on your target system
16685are like (for example, the processor's table might be in @sc{rom},
16686containing entries which point to a table in @sc{ram}).
16687@var{exception_number} is the exception number which should be changed;
16688its meaning is architecture-dependent (for example, different numbers
16689might represent divide by zero, misaligned access, etc). When this
16690exception occurs, control should be transferred directly to
16691@var{exception_address}, and the processor state (stack, registers,
16692and so on) should be just as it is when a processor exception occurs. So if
16693you want to use a jump instruction to reach @var{exception_address}, it
16694should be a simple jump, not a jump to subroutine.
16695
16696For the 386, @var{exception_address} should be installed as an interrupt
16697gate so that interrupts are masked while the handler runs. The gate
16698should be at privilege level 0 (the most privileged level). The
16699@sc{sparc} and 68k stubs are able to mask interrupts themselves without
16700help from @code{exceptionHandler}.
16701
16702@item void flush_i_cache()
4644b6e3 16703@findex flush_i_cache
d4f3574e 16704On @sc{sparc} and @sc{sparclite} only, write this subroutine to flush the
104c1213
JM
16705instruction cache, if any, on your target machine. If there is no
16706instruction cache, this subroutine may be a no-op.
16707
16708On target machines that have instruction caches, @value{GDBN} requires this
16709function to make certain that the state of your program is stable.
16710@end table
16711
16712@noindent
16713You must also make sure this library routine is available:
16714
16715@table @code
16716@item void *memset(void *, int, int)
4644b6e3 16717@findex memset
104c1213
JM
16718This is the standard library function @code{memset} that sets an area of
16719memory to a known value. If you have one of the free versions of
16720@code{libc.a}, @code{memset} can be found there; otherwise, you must
16721either obtain it from your hardware manufacturer, or write your own.
16722@end table
16723
16724If you do not use the GNU C compiler, you may need other standard
16725library subroutines as well; this varies from one stub to another,
16726but in general the stubs are likely to use any of the common library
e22ea452 16727subroutines which @code{@value{NGCC}} generates as inline code.
104c1213
JM
16728
16729
6d2ebf8b 16730@node Debug Session
79a6e687 16731@subsection Putting it All Together
104c1213
JM
16732
16733@cindex remote serial debugging summary
16734In summary, when your program is ready to debug, you must follow these
16735steps.
16736
16737@enumerate
16738@item
6d2ebf8b 16739Make sure you have defined the supporting low-level routines
79a6e687 16740(@pxref{Bootstrapping,,What You Must Do for the Stub}):
104c1213
JM
16741@display
16742@code{getDebugChar}, @code{putDebugChar},
16743@code{flush_i_cache}, @code{memset}, @code{exceptionHandler}.
16744@end display
16745
16746@item
16747Insert these lines near the top of your program:
16748
474c8240 16749@smallexample
104c1213
JM
16750set_debug_traps();
16751breakpoint();
474c8240 16752@end smallexample
104c1213
JM
16753
16754@item
16755For the 680x0 stub only, you need to provide a variable called
16756@code{exceptionHook}. Normally you just use:
16757
474c8240 16758@smallexample
104c1213 16759void (*exceptionHook)() = 0;
474c8240 16760@end smallexample
104c1213 16761
d4f3574e 16762@noindent
104c1213 16763but if before calling @code{set_debug_traps}, you set it to point to a
598ca718 16764function in your program, that function is called when
104c1213
JM
16765@code{@value{GDBN}} continues after stopping on a trap (for example, bus
16766error). The function indicated by @code{exceptionHook} is called with
16767one parameter: an @code{int} which is the exception number.
16768
16769@item
16770Compile and link together: your program, the @value{GDBN} debugging stub for
16771your target architecture, and the supporting subroutines.
16772
16773@item
16774Make sure you have a serial connection between your target machine and
16775the @value{GDBN} host, and identify the serial port on the host.
16776
16777@item
16778@c The "remote" target now provides a `load' command, so we should
16779@c document that. FIXME.
16780Download your program to your target machine (or get it there by
16781whatever means the manufacturer provides), and start it.
16782
16783@item
07f31aa6 16784Start @value{GDBN} on the host, and connect to the target
79a6e687 16785(@pxref{Connecting,,Connecting to a Remote Target}).
9db8d71f 16786
104c1213
JM
16787@end enumerate
16788
8e04817f
AC
16789@node Configurations
16790@chapter Configuration-Specific Information
104c1213 16791
8e04817f
AC
16792While nearly all @value{GDBN} commands are available for all native and
16793cross versions of the debugger, there are some exceptions. This chapter
16794describes things that are only available in certain configurations.
104c1213 16795
8e04817f
AC
16796There are three major categories of configurations: native
16797configurations, where the host and target are the same, embedded
16798operating system configurations, which are usually the same for several
16799different processor architectures, and bare embedded processors, which
16800are quite different from each other.
104c1213 16801
8e04817f
AC
16802@menu
16803* Native::
16804* Embedded OS::
16805* Embedded Processors::
16806* Architectures::
16807@end menu
104c1213 16808
8e04817f
AC
16809@node Native
16810@section Native
104c1213 16811
8e04817f
AC
16812This section describes details specific to particular native
16813configurations.
6cf7e474 16814
8e04817f
AC
16815@menu
16816* HP-UX:: HP-UX
7561d450 16817* BSD libkvm Interface:: Debugging BSD kernel memory images
8e04817f
AC
16818* SVR4 Process Information:: SVR4 process information
16819* DJGPP Native:: Features specific to the DJGPP port
78c47bea 16820* Cygwin Native:: Features specific to the Cygwin port
14d6dd68 16821* Hurd Native:: Features specific to @sc{gnu} Hurd
a64548ea 16822* Neutrino:: Features specific to QNX Neutrino
a80b95ba 16823* Darwin:: Features specific to Darwin
8e04817f 16824@end menu
6cf7e474 16825
8e04817f
AC
16826@node HP-UX
16827@subsection HP-UX
104c1213 16828
8e04817f
AC
16829On HP-UX systems, if you refer to a function or variable name that
16830begins with a dollar sign, @value{GDBN} searches for a user or system
16831name first, before it searches for a convenience variable.
104c1213 16832
9c16f35a 16833
7561d450
MK
16834@node BSD libkvm Interface
16835@subsection BSD libkvm Interface
16836
16837@cindex libkvm
16838@cindex kernel memory image
16839@cindex kernel crash dump
16840
16841BSD-derived systems (FreeBSD/NetBSD/OpenBSD) have a kernel memory
16842interface that provides a uniform interface for accessing kernel virtual
16843memory images, including live systems and crash dumps. @value{GDBN}
16844uses this interface to allow you to debug live kernels and kernel crash
16845dumps on many native BSD configurations. This is implemented as a
16846special @code{kvm} debugging target. For debugging a live system, load
16847the currently running kernel into @value{GDBN} and connect to the
16848@code{kvm} target:
16849
16850@smallexample
16851(@value{GDBP}) @b{target kvm}
16852@end smallexample
16853
16854For debugging crash dumps, provide the file name of the crash dump as an
16855argument:
16856
16857@smallexample
16858(@value{GDBP}) @b{target kvm /var/crash/bsd.0}
16859@end smallexample
16860
16861Once connected to the @code{kvm} target, the following commands are
16862available:
16863
16864@table @code
16865@kindex kvm
16866@item kvm pcb
721c2651 16867Set current context from the @dfn{Process Control Block} (PCB) address.
7561d450
MK
16868
16869@item kvm proc
16870Set current context from proc address. This command isn't available on
16871modern FreeBSD systems.
16872@end table
16873
8e04817f 16874@node SVR4 Process Information
79a6e687 16875@subsection SVR4 Process Information
60bf7e09
EZ
16876@cindex /proc
16877@cindex examine process image
16878@cindex process info via @file{/proc}
104c1213 16879
60bf7e09
EZ
16880Many versions of SVR4 and compatible systems provide a facility called
16881@samp{/proc} that can be used to examine the image of a running
16882process using file-system subroutines. If @value{GDBN} is configured
16883for an operating system with this facility, the command @code{info
16884proc} is available to report information about the process running
16885your program, or about any process running on your system. @code{info
16886proc} works only on SVR4 systems that include the @code{procfs} code.
16887This includes, as of this writing, @sc{gnu}/Linux, OSF/1 (Digital
16888Unix), Solaris, Irix, and Unixware, but not HP-UX, for example.
104c1213 16889
8e04817f
AC
16890@table @code
16891@kindex info proc
60bf7e09 16892@cindex process ID
8e04817f 16893@item info proc
60bf7e09
EZ
16894@itemx info proc @var{process-id}
16895Summarize available information about any running process. If a
16896process ID is specified by @var{process-id}, display information about
16897that process; otherwise display information about the program being
16898debugged. The summary includes the debugged process ID, the command
16899line used to invoke it, its current working directory, and its
16900executable file's absolute file name.
16901
16902On some systems, @var{process-id} can be of the form
16903@samp{[@var{pid}]/@var{tid}} which specifies a certain thread ID
16904within a process. If the optional @var{pid} part is missing, it means
16905a thread from the process being debugged (the leading @samp{/} still
16906needs to be present, or else @value{GDBN} will interpret the number as
16907a process ID rather than a thread ID).
6cf7e474 16908
8e04817f 16909@item info proc mappings
60bf7e09
EZ
16910@cindex memory address space mappings
16911Report the memory address space ranges accessible in the program, with
16912information on whether the process has read, write, or execute access
16913rights to each range. On @sc{gnu}/Linux systems, each memory range
16914includes the object file which is mapped to that range, instead of the
16915memory access rights to that range.
16916
16917@item info proc stat
16918@itemx info proc status
16919@cindex process detailed status information
16920These subcommands are specific to @sc{gnu}/Linux systems. They show
16921the process-related information, including the user ID and group ID;
16922how many threads are there in the process; its virtual memory usage;
16923the signals that are pending, blocked, and ignored; its TTY; its
16924consumption of system and user time; its stack size; its @samp{nice}
2eecc4ab 16925value; etc. For more information, see the @samp{proc} man page
60bf7e09
EZ
16926(type @kbd{man 5 proc} from your shell prompt).
16927
16928@item info proc all
16929Show all the information about the process described under all of the
16930above @code{info proc} subcommands.
16931
8e04817f
AC
16932@ignore
16933@comment These sub-options of 'info proc' were not included when
16934@comment procfs.c was re-written. Keep their descriptions around
16935@comment against the day when someone finds the time to put them back in.
16936@kindex info proc times
16937@item info proc times
16938Starting time, user CPU time, and system CPU time for your program and
16939its children.
6cf7e474 16940
8e04817f
AC
16941@kindex info proc id
16942@item info proc id
16943Report on the process IDs related to your program: its own process ID,
16944the ID of its parent, the process group ID, and the session ID.
8e04817f 16945@end ignore
721c2651
EZ
16946
16947@item set procfs-trace
16948@kindex set procfs-trace
16949@cindex @code{procfs} API calls
16950This command enables and disables tracing of @code{procfs} API calls.
16951
16952@item show procfs-trace
16953@kindex show procfs-trace
16954Show the current state of @code{procfs} API call tracing.
16955
16956@item set procfs-file @var{file}
16957@kindex set procfs-file
16958Tell @value{GDBN} to write @code{procfs} API trace to the named
16959@var{file}. @value{GDBN} appends the trace info to the previous
16960contents of the file. The default is to display the trace on the
16961standard output.
16962
16963@item show procfs-file
16964@kindex show procfs-file
16965Show the file to which @code{procfs} API trace is written.
16966
16967@item proc-trace-entry
16968@itemx proc-trace-exit
16969@itemx proc-untrace-entry
16970@itemx proc-untrace-exit
16971@kindex proc-trace-entry
16972@kindex proc-trace-exit
16973@kindex proc-untrace-entry
16974@kindex proc-untrace-exit
16975These commands enable and disable tracing of entries into and exits
16976from the @code{syscall} interface.
16977
16978@item info pidlist
16979@kindex info pidlist
16980@cindex process list, QNX Neutrino
16981For QNX Neutrino only, this command displays the list of all the
16982processes and all the threads within each process.
16983
16984@item info meminfo
16985@kindex info meminfo
16986@cindex mapinfo list, QNX Neutrino
16987For QNX Neutrino only, this command displays the list of all mapinfos.
8e04817f 16988@end table
104c1213 16989
8e04817f
AC
16990@node DJGPP Native
16991@subsection Features for Debugging @sc{djgpp} Programs
16992@cindex @sc{djgpp} debugging
16993@cindex native @sc{djgpp} debugging
16994@cindex MS-DOS-specific commands
104c1213 16995
514c4d71
EZ
16996@cindex DPMI
16997@sc{djgpp} is a port of the @sc{gnu} development tools to MS-DOS and
8e04817f
AC
16998MS-Windows. @sc{djgpp} programs are 32-bit protected-mode programs
16999that use the @dfn{DPMI} (DOS Protected-Mode Interface) API to run on
17000top of real-mode DOS systems and their emulations.
104c1213 17001
8e04817f
AC
17002@value{GDBN} supports native debugging of @sc{djgpp} programs, and
17003defines a few commands specific to the @sc{djgpp} port. This
17004subsection describes those commands.
104c1213 17005
8e04817f
AC
17006@table @code
17007@kindex info dos
17008@item info dos
17009This is a prefix of @sc{djgpp}-specific commands which print
17010information about the target system and important OS structures.
f1251bdd 17011
8e04817f
AC
17012@kindex sysinfo
17013@cindex MS-DOS system info
17014@cindex free memory information (MS-DOS)
17015@item info dos sysinfo
17016This command displays assorted information about the underlying
17017platform: the CPU type and features, the OS version and flavor, the
17018DPMI version, and the available conventional and DPMI memory.
104c1213 17019
8e04817f
AC
17020@cindex GDT
17021@cindex LDT
17022@cindex IDT
17023@cindex segment descriptor tables
17024@cindex descriptor tables display
17025@item info dos gdt
17026@itemx info dos ldt
17027@itemx info dos idt
17028These 3 commands display entries from, respectively, Global, Local,
17029and Interrupt Descriptor Tables (GDT, LDT, and IDT). The descriptor
17030tables are data structures which store a descriptor for each segment
17031that is currently in use. The segment's selector is an index into a
17032descriptor table; the table entry for that index holds the
17033descriptor's base address and limit, and its attributes and access
17034rights.
104c1213 17035
8e04817f
AC
17036A typical @sc{djgpp} program uses 3 segments: a code segment, a data
17037segment (used for both data and the stack), and a DOS segment (which
17038allows access to DOS/BIOS data structures and absolute addresses in
17039conventional memory). However, the DPMI host will usually define
17040additional segments in order to support the DPMI environment.
d4f3574e 17041
8e04817f
AC
17042@cindex garbled pointers
17043These commands allow to display entries from the descriptor tables.
17044Without an argument, all entries from the specified table are
17045displayed. An argument, which should be an integer expression, means
17046display a single entry whose index is given by the argument. For
17047example, here's a convenient way to display information about the
17048debugged program's data segment:
104c1213 17049
8e04817f
AC
17050@smallexample
17051@exdent @code{(@value{GDBP}) info dos ldt $ds}
17052@exdent @code{0x13f: base=0x11970000 limit=0x0009ffff 32-Bit Data (Read/Write, Exp-up)}
17053@end smallexample
104c1213 17054
8e04817f
AC
17055@noindent
17056This comes in handy when you want to see whether a pointer is outside
17057the data segment's limit (i.e.@: @dfn{garbled}).
104c1213 17058
8e04817f
AC
17059@cindex page tables display (MS-DOS)
17060@item info dos pde
17061@itemx info dos pte
17062These two commands display entries from, respectively, the Page
17063Directory and the Page Tables. Page Directories and Page Tables are
17064data structures which control how virtual memory addresses are mapped
17065into physical addresses. A Page Table includes an entry for every
17066page of memory that is mapped into the program's address space; there
17067may be several Page Tables, each one holding up to 4096 entries. A
17068Page Directory has up to 4096 entries, one each for every Page Table
17069that is currently in use.
104c1213 17070
8e04817f
AC
17071Without an argument, @kbd{info dos pde} displays the entire Page
17072Directory, and @kbd{info dos pte} displays all the entries in all of
17073the Page Tables. An argument, an integer expression, given to the
17074@kbd{info dos pde} command means display only that entry from the Page
17075Directory table. An argument given to the @kbd{info dos pte} command
17076means display entries from a single Page Table, the one pointed to by
17077the specified entry in the Page Directory.
104c1213 17078
8e04817f
AC
17079@cindex direct memory access (DMA) on MS-DOS
17080These commands are useful when your program uses @dfn{DMA} (Direct
17081Memory Access), which needs physical addresses to program the DMA
17082controller.
104c1213 17083
8e04817f 17084These commands are supported only with some DPMI servers.
104c1213 17085
8e04817f
AC
17086@cindex physical address from linear address
17087@item info dos address-pte @var{addr}
17088This command displays the Page Table entry for a specified linear
514c4d71
EZ
17089address. The argument @var{addr} is a linear address which should
17090already have the appropriate segment's base address added to it,
17091because this command accepts addresses which may belong to @emph{any}
17092segment. For example, here's how to display the Page Table entry for
17093the page where a variable @code{i} is stored:
104c1213 17094
b383017d 17095@smallexample
8e04817f
AC
17096@exdent @code{(@value{GDBP}) info dos address-pte __djgpp_base_address + (char *)&i}
17097@exdent @code{Page Table entry for address 0x11a00d30:}
b383017d 17098@exdent @code{Base=0x02698000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0xd30}
8e04817f 17099@end smallexample
104c1213 17100
8e04817f
AC
17101@noindent
17102This says that @code{i} is stored at offset @code{0xd30} from the page
514c4d71 17103whose physical base address is @code{0x02698000}, and shows all the
8e04817f 17104attributes of that page.
104c1213 17105
8e04817f
AC
17106Note that you must cast the addresses of variables to a @code{char *},
17107since otherwise the value of @code{__djgpp_base_address}, the base
17108address of all variables and functions in a @sc{djgpp} program, will
17109be added using the rules of C pointer arithmetics: if @code{i} is
17110declared an @code{int}, @value{GDBN} will add 4 times the value of
17111@code{__djgpp_base_address} to the address of @code{i}.
104c1213 17112
8e04817f
AC
17113Here's another example, it displays the Page Table entry for the
17114transfer buffer:
104c1213 17115
8e04817f
AC
17116@smallexample
17117@exdent @code{(@value{GDBP}) info dos address-pte *((unsigned *)&_go32_info_block + 3)}
17118@exdent @code{Page Table entry for address 0x29110:}
17119@exdent @code{Base=0x00029000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0x110}
17120@end smallexample
104c1213 17121
8e04817f
AC
17122@noindent
17123(The @code{+ 3} offset is because the transfer buffer's address is the
514c4d71
EZ
171243rd member of the @code{_go32_info_block} structure.) The output
17125clearly shows that this DPMI server maps the addresses in conventional
17126memory 1:1, i.e.@: the physical (@code{0x00029000} + @code{0x110}) and
17127linear (@code{0x29110}) addresses are identical.
104c1213 17128
8e04817f
AC
17129This command is supported only with some DPMI servers.
17130@end table
104c1213 17131
c45da7e6 17132@cindex DOS serial data link, remote debugging
a8f24a35
EZ
17133In addition to native debugging, the DJGPP port supports remote
17134debugging via a serial data link. The following commands are specific
17135to remote serial debugging in the DJGPP port of @value{GDBN}.
17136
17137@table @code
17138@kindex set com1base
17139@kindex set com1irq
17140@kindex set com2base
17141@kindex set com2irq
17142@kindex set com3base
17143@kindex set com3irq
17144@kindex set com4base
17145@kindex set com4irq
17146@item set com1base @var{addr}
17147This command sets the base I/O port address of the @file{COM1} serial
17148port.
17149
17150@item set com1irq @var{irq}
17151This command sets the @dfn{Interrupt Request} (@code{IRQ}) line to use
17152for the @file{COM1} serial port.
17153
17154There are similar commands @samp{set com2base}, @samp{set com3irq},
17155etc.@: for setting the port address and the @code{IRQ} lines for the
17156other 3 COM ports.
17157
17158@kindex show com1base
17159@kindex show com1irq
17160@kindex show com2base
17161@kindex show com2irq
17162@kindex show com3base
17163@kindex show com3irq
17164@kindex show com4base
17165@kindex show com4irq
17166The related commands @samp{show com1base}, @samp{show com1irq} etc.@:
17167display the current settings of the base address and the @code{IRQ}
17168lines used by the COM ports.
c45da7e6
EZ
17169
17170@item info serial
17171@kindex info serial
17172@cindex DOS serial port status
17173This command prints the status of the 4 DOS serial ports. For each
17174port, it prints whether it's active or not, its I/O base address and
17175IRQ number, whether it uses a 16550-style FIFO, its baudrate, and the
17176counts of various errors encountered so far.
a8f24a35
EZ
17177@end table
17178
17179
78c47bea 17180@node Cygwin Native
79a6e687 17181@subsection Features for Debugging MS Windows PE Executables
78c47bea
PM
17182@cindex MS Windows debugging
17183@cindex native Cygwin debugging
17184@cindex Cygwin-specific commands
17185
be448670 17186@value{GDBN} supports native debugging of MS Windows programs, including
cbb8f428
EZ
17187DLLs with and without symbolic debugging information.
17188
17189@cindex Ctrl-BREAK, MS-Windows
17190@cindex interrupt debuggee on MS-Windows
17191MS-Windows programs that call @code{SetConsoleMode} to switch off the
17192special meaning of the @samp{Ctrl-C} keystroke cannot be interrupted
17193by typing @kbd{C-c}. For this reason, @value{GDBN} on MS-Windows
17194supports @kbd{C-@key{BREAK}} as an alternative interrupt key
17195sequence, which can be used to interrupt the debuggee even if it
17196ignores @kbd{C-c}.
17197
17198There are various additional Cygwin-specific commands, described in
17199this section. Working with DLLs that have no debugging symbols is
17200described in @ref{Non-debug DLL Symbols}.
78c47bea
PM
17201
17202@table @code
17203@kindex info w32
17204@item info w32
db2e3e2e 17205This is a prefix of MS Windows-specific commands which print
78c47bea
PM
17206information about the target system and important OS structures.
17207
17208@item info w32 selector
17209This command displays information returned by
17210the Win32 API @code{GetThreadSelectorEntry} function.
17211It takes an optional argument that is evaluated to
17212a long value to give the information about this given selector.
17213Without argument, this command displays information
d3e8051b 17214about the six segment registers.
78c47bea 17215
711e434b
PM
17216@item info w32 thread-information-block
17217This command displays thread specific information stored in the
17218Thread Information Block (readable on the X86 CPU family using @code{$fs}
17219selector for 32-bit programs and @code{$gs} for 64-bit programs).
17220
78c47bea
PM
17221@kindex info dll
17222@item info dll
db2e3e2e 17223This is a Cygwin-specific alias of @code{info shared}.
78c47bea
PM
17224
17225@kindex dll-symbols
17226@item dll-symbols
17227This command loads symbols from a dll similarly to
17228add-sym command but without the need to specify a base address.
17229
be90c084 17230@kindex set cygwin-exceptions
e16b02ee
EZ
17231@cindex debugging the Cygwin DLL
17232@cindex Cygwin DLL, debugging
be90c084 17233@item set cygwin-exceptions @var{mode}
e16b02ee
EZ
17234If @var{mode} is @code{on}, @value{GDBN} will break on exceptions that
17235happen inside the Cygwin DLL. If @var{mode} is @code{off},
17236@value{GDBN} will delay recognition of exceptions, and may ignore some
17237exceptions which seem to be caused by internal Cygwin DLL
17238``bookkeeping''. This option is meant primarily for debugging the
17239Cygwin DLL itself; the default value is @code{off} to avoid annoying
17240@value{GDBN} users with false @code{SIGSEGV} signals.
be90c084
CF
17241
17242@kindex show cygwin-exceptions
17243@item show cygwin-exceptions
e16b02ee
EZ
17244Displays whether @value{GDBN} will break on exceptions that happen
17245inside the Cygwin DLL itself.
be90c084 17246
b383017d 17247@kindex set new-console
78c47bea 17248@item set new-console @var{mode}
b383017d 17249If @var{mode} is @code{on} the debuggee will
78c47bea 17250be started in a new console on next start.
e03e5e7b 17251If @var{mode} is @code{off}, the debuggee will
78c47bea
PM
17252be started in the same console as the debugger.
17253
17254@kindex show new-console
17255@item show new-console
17256Displays whether a new console is used
17257when the debuggee is started.
17258
17259@kindex set new-group
17260@item set new-group @var{mode}
17261This boolean value controls whether the debuggee should
17262start a new group or stay in the same group as the debugger.
17263This affects the way the Windows OS handles
c8aa23ab 17264@samp{Ctrl-C}.
78c47bea
PM
17265
17266@kindex show new-group
17267@item show new-group
17268Displays current value of new-group boolean.
17269
17270@kindex set debugevents
17271@item set debugevents
219eec71
EZ
17272This boolean value adds debug output concerning kernel events related
17273to the debuggee seen by the debugger. This includes events that
17274signal thread and process creation and exit, DLL loading and
17275unloading, console interrupts, and debugging messages produced by the
17276Windows @code{OutputDebugString} API call.
78c47bea
PM
17277
17278@kindex set debugexec
17279@item set debugexec
b383017d 17280This boolean value adds debug output concerning execute events
219eec71 17281(such as resume thread) seen by the debugger.
78c47bea
PM
17282
17283@kindex set debugexceptions
17284@item set debugexceptions
219eec71
EZ
17285This boolean value adds debug output concerning exceptions in the
17286debuggee seen by the debugger.
78c47bea
PM
17287
17288@kindex set debugmemory
17289@item set debugmemory
219eec71
EZ
17290This boolean value adds debug output concerning debuggee memory reads
17291and writes by the debugger.
78c47bea
PM
17292
17293@kindex set shell
17294@item set shell
17295This boolean values specifies whether the debuggee is called
17296via a shell or directly (default value is on).
17297
17298@kindex show shell
17299@item show shell
17300Displays if the debuggee will be started with a shell.
17301
17302@end table
17303
be448670 17304@menu
79a6e687 17305* Non-debug DLL Symbols:: Support for DLLs without debugging symbols
be448670
CF
17306@end menu
17307
79a6e687
BW
17308@node Non-debug DLL Symbols
17309@subsubsection Support for DLLs without Debugging Symbols
be448670
CF
17310@cindex DLLs with no debugging symbols
17311@cindex Minimal symbols and DLLs
17312
17313Very often on windows, some of the DLLs that your program relies on do
17314not include symbolic debugging information (for example,
db2e3e2e 17315@file{kernel32.dll}). When @value{GDBN} doesn't recognize any debugging
be448670 17316symbols in a DLL, it relies on the minimal amount of symbolic
db2e3e2e 17317information contained in the DLL's export table. This section
be448670
CF
17318describes working with such symbols, known internally to @value{GDBN} as
17319``minimal symbols''.
17320
17321Note that before the debugged program has started execution, no DLLs
db2e3e2e 17322will have been loaded. The easiest way around this problem is simply to
be448670 17323start the program --- either by setting a breakpoint or letting the
db2e3e2e 17324program run once to completion. It is also possible to force
be448670 17325@value{GDBN} to load a particular DLL before starting the executable ---
12c27660 17326see the shared library information in @ref{Files}, or the
db2e3e2e 17327@code{dll-symbols} command in @ref{Cygwin Native}. Currently,
be448670
CF
17328explicitly loading symbols from a DLL with no debugging information will
17329cause the symbol names to be duplicated in @value{GDBN}'s lookup table,
17330which may adversely affect symbol lookup performance.
17331
79a6e687 17332@subsubsection DLL Name Prefixes
be448670
CF
17333
17334In keeping with the naming conventions used by the Microsoft debugging
17335tools, DLL export symbols are made available with a prefix based on the
17336DLL name, for instance @code{KERNEL32!CreateFileA}. The plain name is
17337also entered into the symbol table, so @code{CreateFileA} is often
99e008fe 17338sufficient. In some cases there will be name clashes within a program
be448670
CF
17339(particularly if the executable itself includes full debugging symbols)
17340necessitating the use of the fully qualified name when referring to the
99e008fe 17341contents of the DLL. Use single-quotes around the name to avoid the
be448670
CF
17342exclamation mark (``!'') being interpreted as a language operator.
17343
17344Note that the internal name of the DLL may be all upper-case, even
99e008fe 17345though the file name of the DLL is lower-case, or vice-versa. Since
be448670
CF
17346symbols within @value{GDBN} are @emph{case-sensitive} this may cause
17347some confusion. If in doubt, try the @code{info functions} and
0869d01b
NR
17348@code{info variables} commands or even @code{maint print msymbols}
17349(@pxref{Symbols}). Here's an example:
be448670
CF
17350
17351@smallexample
f7dc1244 17352(@value{GDBP}) info function CreateFileA
be448670
CF
17353All functions matching regular expression "CreateFileA":
17354
17355Non-debugging symbols:
173560x77e885f4 CreateFileA
173570x77e885f4 KERNEL32!CreateFileA
17358@end smallexample
17359
17360@smallexample
f7dc1244 17361(@value{GDBP}) info function !
be448670
CF
17362All functions matching regular expression "!":
17363
17364Non-debugging symbols:
173650x6100114c cygwin1!__assert
173660x61004034 cygwin1!_dll_crt0@@0
173670x61004240 cygwin1!dll_crt0(per_process *)
17368[etc...]
17369@end smallexample
17370
79a6e687 17371@subsubsection Working with Minimal Symbols
be448670
CF
17372
17373Symbols extracted from a DLL's export table do not contain very much
17374type information. All that @value{GDBN} can do is guess whether a symbol
17375refers to a function or variable depending on the linker section that
17376contains the symbol. Also note that the actual contents of the memory
17377contained in a DLL are not available unless the program is running. This
17378means that you cannot examine the contents of a variable or disassemble
17379a function within a DLL without a running program.
17380
17381Variables are generally treated as pointers and dereferenced
17382automatically. For this reason, it is often necessary to prefix a
17383variable name with the address-of operator (``&'') and provide explicit
17384type information in the command. Here's an example of the type of
17385problem:
17386
17387@smallexample
f7dc1244 17388(@value{GDBP}) print 'cygwin1!__argv'
be448670
CF
17389$1 = 268572168
17390@end smallexample
17391
17392@smallexample
f7dc1244 17393(@value{GDBP}) x 'cygwin1!__argv'
be448670
CF
173940x10021610: "\230y\""
17395@end smallexample
17396
17397And two possible solutions:
17398
17399@smallexample
f7dc1244 17400(@value{GDBP}) print ((char **)'cygwin1!__argv')[0]
be448670
CF
17401$2 = 0x22fd98 "/cygdrive/c/mydirectory/myprogram"
17402@end smallexample
17403
17404@smallexample
f7dc1244 17405(@value{GDBP}) x/2x &'cygwin1!__argv'
be448670 174060x610c0aa8 <cygwin1!__argv>: 0x10021608 0x00000000
f7dc1244 17407(@value{GDBP}) x/x 0x10021608
be448670 174080x10021608: 0x0022fd98
f7dc1244 17409(@value{GDBP}) x/s 0x0022fd98
be448670
CF
174100x22fd98: "/cygdrive/c/mydirectory/myprogram"
17411@end smallexample
17412
17413Setting a break point within a DLL is possible even before the program
17414starts execution. However, under these circumstances, @value{GDBN} can't
17415examine the initial instructions of the function in order to skip the
17416function's frame set-up code. You can work around this by using ``*&''
17417to set the breakpoint at a raw memory address:
17418
17419@smallexample
f7dc1244 17420(@value{GDBP}) break *&'python22!PyOS_Readline'
be448670
CF
17421Breakpoint 1 at 0x1e04eff0
17422@end smallexample
17423
17424The author of these extensions is not entirely convinced that setting a
17425break point within a shared DLL like @file{kernel32.dll} is completely
17426safe.
17427
14d6dd68 17428@node Hurd Native
79a6e687 17429@subsection Commands Specific to @sc{gnu} Hurd Systems
14d6dd68
EZ
17430@cindex @sc{gnu} Hurd debugging
17431
17432This subsection describes @value{GDBN} commands specific to the
17433@sc{gnu} Hurd native debugging.
17434
17435@table @code
17436@item set signals
17437@itemx set sigs
17438@kindex set signals@r{, Hurd command}
17439@kindex set sigs@r{, Hurd command}
17440This command toggles the state of inferior signal interception by
17441@value{GDBN}. Mach exceptions, such as breakpoint traps, are not
17442affected by this command. @code{sigs} is a shorthand alias for
17443@code{signals}.
17444
17445@item show signals
17446@itemx show sigs
17447@kindex show signals@r{, Hurd command}
17448@kindex show sigs@r{, Hurd command}
17449Show the current state of intercepting inferior's signals.
17450
17451@item set signal-thread
17452@itemx set sigthread
17453@kindex set signal-thread
17454@kindex set sigthread
17455This command tells @value{GDBN} which thread is the @code{libc} signal
17456thread. That thread is run when a signal is delivered to a running
17457process. @code{set sigthread} is the shorthand alias of @code{set
17458signal-thread}.
17459
17460@item show signal-thread
17461@itemx show sigthread
17462@kindex show signal-thread
17463@kindex show sigthread
17464These two commands show which thread will run when the inferior is
17465delivered a signal.
17466
17467@item set stopped
17468@kindex set stopped@r{, Hurd command}
17469This commands tells @value{GDBN} that the inferior process is stopped,
17470as with the @code{SIGSTOP} signal. The stopped process can be
17471continued by delivering a signal to it.
17472
17473@item show stopped
17474@kindex show stopped@r{, Hurd command}
17475This command shows whether @value{GDBN} thinks the debuggee is
17476stopped.
17477
17478@item set exceptions
17479@kindex set exceptions@r{, Hurd command}
17480Use this command to turn off trapping of exceptions in the inferior.
17481When exception trapping is off, neither breakpoints nor
17482single-stepping will work. To restore the default, set exception
17483trapping on.
17484
17485@item show exceptions
17486@kindex show exceptions@r{, Hurd command}
17487Show the current state of trapping exceptions in the inferior.
17488
17489@item set task pause
17490@kindex set task@r{, Hurd commands}
17491@cindex task attributes (@sc{gnu} Hurd)
17492@cindex pause current task (@sc{gnu} Hurd)
17493This command toggles task suspension when @value{GDBN} has control.
17494Setting it to on takes effect immediately, and the task is suspended
17495whenever @value{GDBN} gets control. Setting it to off will take
17496effect the next time the inferior is continued. If this option is set
17497to off, you can use @code{set thread default pause on} or @code{set
17498thread pause on} (see below) to pause individual threads.
17499
17500@item show task pause
17501@kindex show task@r{, Hurd commands}
17502Show the current state of task suspension.
17503
17504@item set task detach-suspend-count
17505@cindex task suspend count
17506@cindex detach from task, @sc{gnu} Hurd
17507This command sets the suspend count the task will be left with when
17508@value{GDBN} detaches from it.
17509
17510@item show task detach-suspend-count
17511Show the suspend count the task will be left with when detaching.
17512
17513@item set task exception-port
17514@itemx set task excp
17515@cindex task exception port, @sc{gnu} Hurd
17516This command sets the task exception port to which @value{GDBN} will
17517forward exceptions. The argument should be the value of the @dfn{send
17518rights} of the task. @code{set task excp} is a shorthand alias.
17519
17520@item set noninvasive
17521@cindex noninvasive task options
17522This command switches @value{GDBN} to a mode that is the least
17523invasive as far as interfering with the inferior is concerned. This
17524is the same as using @code{set task pause}, @code{set exceptions}, and
17525@code{set signals} to values opposite to the defaults.
17526
17527@item info send-rights
17528@itemx info receive-rights
17529@itemx info port-rights
17530@itemx info port-sets
17531@itemx info dead-names
17532@itemx info ports
17533@itemx info psets
17534@cindex send rights, @sc{gnu} Hurd
17535@cindex receive rights, @sc{gnu} Hurd
17536@cindex port rights, @sc{gnu} Hurd
17537@cindex port sets, @sc{gnu} Hurd
17538@cindex dead names, @sc{gnu} Hurd
17539These commands display information about, respectively, send rights,
17540receive rights, port rights, port sets, and dead names of a task.
17541There are also shorthand aliases: @code{info ports} for @code{info
17542port-rights} and @code{info psets} for @code{info port-sets}.
17543
17544@item set thread pause
17545@kindex set thread@r{, Hurd command}
17546@cindex thread properties, @sc{gnu} Hurd
17547@cindex pause current thread (@sc{gnu} Hurd)
17548This command toggles current thread suspension when @value{GDBN} has
17549control. Setting it to on takes effect immediately, and the current
17550thread is suspended whenever @value{GDBN} gets control. Setting it to
17551off will take effect the next time the inferior is continued.
17552Normally, this command has no effect, since when @value{GDBN} has
17553control, the whole task is suspended. However, if you used @code{set
17554task pause off} (see above), this command comes in handy to suspend
17555only the current thread.
17556
17557@item show thread pause
17558@kindex show thread@r{, Hurd command}
17559This command shows the state of current thread suspension.
17560
17561@item set thread run
d3e8051b 17562This command sets whether the current thread is allowed to run.
14d6dd68
EZ
17563
17564@item show thread run
17565Show whether the current thread is allowed to run.
17566
17567@item set thread detach-suspend-count
17568@cindex thread suspend count, @sc{gnu} Hurd
17569@cindex detach from thread, @sc{gnu} Hurd
17570This command sets the suspend count @value{GDBN} will leave on a
17571thread when detaching. This number is relative to the suspend count
17572found by @value{GDBN} when it notices the thread; use @code{set thread
17573takeover-suspend-count} to force it to an absolute value.
17574
17575@item show thread detach-suspend-count
17576Show the suspend count @value{GDBN} will leave on the thread when
17577detaching.
17578
17579@item set thread exception-port
17580@itemx set thread excp
17581Set the thread exception port to which to forward exceptions. This
17582overrides the port set by @code{set task exception-port} (see above).
17583@code{set thread excp} is the shorthand alias.
17584
17585@item set thread takeover-suspend-count
17586Normally, @value{GDBN}'s thread suspend counts are relative to the
17587value @value{GDBN} finds when it notices each thread. This command
17588changes the suspend counts to be absolute instead.
17589
17590@item set thread default
17591@itemx show thread default
17592@cindex thread default settings, @sc{gnu} Hurd
17593Each of the above @code{set thread} commands has a @code{set thread
17594default} counterpart (e.g., @code{set thread default pause}, @code{set
17595thread default exception-port}, etc.). The @code{thread default}
17596variety of commands sets the default thread properties for all
17597threads; you can then change the properties of individual threads with
17598the non-default commands.
17599@end table
17600
17601
a64548ea
EZ
17602@node Neutrino
17603@subsection QNX Neutrino
17604@cindex QNX Neutrino
17605
17606@value{GDBN} provides the following commands specific to the QNX
17607Neutrino target:
17608
17609@table @code
17610@item set debug nto-debug
17611@kindex set debug nto-debug
17612When set to on, enables debugging messages specific to the QNX
17613Neutrino support.
17614
17615@item show debug nto-debug
17616@kindex show debug nto-debug
17617Show the current state of QNX Neutrino messages.
17618@end table
17619
a80b95ba
TG
17620@node Darwin
17621@subsection Darwin
17622@cindex Darwin
17623
17624@value{GDBN} provides the following commands specific to the Darwin target:
17625
17626@table @code
17627@item set debug darwin @var{num}
17628@kindex set debug darwin
17629When set to a non zero value, enables debugging messages specific to
17630the Darwin support. Higher values produce more verbose output.
17631
17632@item show debug darwin
17633@kindex show debug darwin
17634Show the current state of Darwin messages.
17635
17636@item set debug mach-o @var{num}
17637@kindex set debug mach-o
17638When set to a non zero value, enables debugging messages while
17639@value{GDBN} is reading Darwin object files. (@dfn{Mach-O} is the
17640file format used on Darwin for object and executable files.) Higher
17641values produce more verbose output. This is a command to diagnose
17642problems internal to @value{GDBN} and should not be needed in normal
17643usage.
17644
17645@item show debug mach-o
17646@kindex show debug mach-o
17647Show the current state of Mach-O file messages.
17648
17649@item set mach-exceptions on
17650@itemx set mach-exceptions off
17651@kindex set mach-exceptions
17652On Darwin, faults are first reported as a Mach exception and are then
17653mapped to a Posix signal. Use this command to turn on trapping of
17654Mach exceptions in the inferior. This might be sometimes useful to
17655better understand the cause of a fault. The default is off.
17656
17657@item show mach-exceptions
17658@kindex show mach-exceptions
17659Show the current state of exceptions trapping.
17660@end table
17661
a64548ea 17662
8e04817f
AC
17663@node Embedded OS
17664@section Embedded Operating Systems
104c1213 17665
8e04817f
AC
17666This section describes configurations involving the debugging of
17667embedded operating systems that are available for several different
17668architectures.
d4f3574e 17669
8e04817f
AC
17670@menu
17671* VxWorks:: Using @value{GDBN} with VxWorks
17672@end menu
104c1213 17673
8e04817f
AC
17674@value{GDBN} includes the ability to debug programs running on
17675various real-time operating systems.
104c1213 17676
8e04817f
AC
17677@node VxWorks
17678@subsection Using @value{GDBN} with VxWorks
104c1213 17679
8e04817f 17680@cindex VxWorks
104c1213 17681
8e04817f 17682@table @code
104c1213 17683
8e04817f
AC
17684@kindex target vxworks
17685@item target vxworks @var{machinename}
17686A VxWorks system, attached via TCP/IP. The argument @var{machinename}
17687is the target system's machine name or IP address.
104c1213 17688
8e04817f 17689@end table
104c1213 17690
8e04817f
AC
17691On VxWorks, @code{load} links @var{filename} dynamically on the
17692current target system as well as adding its symbols in @value{GDBN}.
104c1213 17693
8e04817f
AC
17694@value{GDBN} enables developers to spawn and debug tasks running on networked
17695VxWorks targets from a Unix host. Already-running tasks spawned from
17696the VxWorks shell can also be debugged. @value{GDBN} uses code that runs on
17697both the Unix host and on the VxWorks target. The program
17698@code{@value{GDBP}} is installed and executed on the Unix host. (It may be
17699installed with the name @code{vxgdb}, to distinguish it from a
17700@value{GDBN} for debugging programs on the host itself.)
104c1213 17701
8e04817f
AC
17702@table @code
17703@item VxWorks-timeout @var{args}
17704@kindex vxworks-timeout
17705All VxWorks-based targets now support the option @code{vxworks-timeout}.
17706This option is set by the user, and @var{args} represents the number of
17707seconds @value{GDBN} waits for responses to rpc's. You might use this if
17708your VxWorks target is a slow software simulator or is on the far side
17709of a thin network line.
17710@end table
104c1213 17711
8e04817f
AC
17712The following information on connecting to VxWorks was current when
17713this manual was produced; newer releases of VxWorks may use revised
17714procedures.
104c1213 17715
4644b6e3 17716@findex INCLUDE_RDB
8e04817f
AC
17717To use @value{GDBN} with VxWorks, you must rebuild your VxWorks kernel
17718to include the remote debugging interface routines in the VxWorks
17719library @file{rdb.a}. To do this, define @code{INCLUDE_RDB} in the
17720VxWorks configuration file @file{configAll.h} and rebuild your VxWorks
17721kernel. The resulting kernel contains @file{rdb.a}, and spawns the
17722source debugging task @code{tRdbTask} when VxWorks is booted. For more
17723information on configuring and remaking VxWorks, see the manufacturer's
17724manual.
17725@c VxWorks, see the @cite{VxWorks Programmer's Guide}.
104c1213 17726
8e04817f
AC
17727Once you have included @file{rdb.a} in your VxWorks system image and set
17728your Unix execution search path to find @value{GDBN}, you are ready to
17729run @value{GDBN}. From your Unix host, run @code{@value{GDBP}} (or
17730@code{vxgdb}, depending on your installation).
104c1213 17731
8e04817f 17732@value{GDBN} comes up showing the prompt:
104c1213 17733
474c8240 17734@smallexample
8e04817f 17735(vxgdb)
474c8240 17736@end smallexample
104c1213 17737
8e04817f
AC
17738@menu
17739* VxWorks Connection:: Connecting to VxWorks
17740* VxWorks Download:: VxWorks download
17741* VxWorks Attach:: Running tasks
17742@end menu
104c1213 17743
8e04817f
AC
17744@node VxWorks Connection
17745@subsubsection Connecting to VxWorks
104c1213 17746
8e04817f
AC
17747The @value{GDBN} command @code{target} lets you connect to a VxWorks target on the
17748network. To connect to a target whose host name is ``@code{tt}'', type:
104c1213 17749
474c8240 17750@smallexample
8e04817f 17751(vxgdb) target vxworks tt
474c8240 17752@end smallexample
104c1213 17753
8e04817f
AC
17754@need 750
17755@value{GDBN} displays messages like these:
104c1213 17756
8e04817f
AC
17757@smallexample
17758Attaching remote machine across net...
17759Connected to tt.
17760@end smallexample
104c1213 17761
8e04817f
AC
17762@need 1000
17763@value{GDBN} then attempts to read the symbol tables of any object modules
17764loaded into the VxWorks target since it was last booted. @value{GDBN} locates
17765these files by searching the directories listed in the command search
79a6e687 17766path (@pxref{Environment, ,Your Program's Environment}); if it fails
8e04817f 17767to find an object file, it displays a message such as:
5d161b24 17768
474c8240 17769@smallexample
8e04817f 17770prog.o: No such file or directory.
474c8240 17771@end smallexample
104c1213 17772
8e04817f
AC
17773When this happens, add the appropriate directory to the search path with
17774the @value{GDBN} command @code{path}, and execute the @code{target}
17775command again.
104c1213 17776
8e04817f 17777@node VxWorks Download
79a6e687 17778@subsubsection VxWorks Download
104c1213 17779
8e04817f
AC
17780@cindex download to VxWorks
17781If you have connected to the VxWorks target and you want to debug an
17782object that has not yet been loaded, you can use the @value{GDBN}
17783@code{load} command to download a file from Unix to VxWorks
17784incrementally. The object file given as an argument to the @code{load}
17785command is actually opened twice: first by the VxWorks target in order
17786to download the code, then by @value{GDBN} in order to read the symbol
17787table. This can lead to problems if the current working directories on
17788the two systems differ. If both systems have NFS mounted the same
17789filesystems, you can avoid these problems by using absolute paths.
17790Otherwise, it is simplest to set the working directory on both systems
17791to the directory in which the object file resides, and then to reference
17792the file by its name, without any path. For instance, a program
17793@file{prog.o} may reside in @file{@var{vxpath}/vw/demo/rdb} in VxWorks
17794and in @file{@var{hostpath}/vw/demo/rdb} on the host. To load this
17795program, type this on VxWorks:
104c1213 17796
474c8240 17797@smallexample
8e04817f 17798-> cd "@var{vxpath}/vw/demo/rdb"
474c8240 17799@end smallexample
104c1213 17800
8e04817f
AC
17801@noindent
17802Then, in @value{GDBN}, type:
104c1213 17803
474c8240 17804@smallexample
8e04817f
AC
17805(vxgdb) cd @var{hostpath}/vw/demo/rdb
17806(vxgdb) load prog.o
474c8240 17807@end smallexample
104c1213 17808
8e04817f 17809@value{GDBN} displays a response similar to this:
104c1213 17810
8e04817f
AC
17811@smallexample
17812Reading symbol data from wherever/vw/demo/rdb/prog.o... done.
17813@end smallexample
104c1213 17814
8e04817f
AC
17815You can also use the @code{load} command to reload an object module
17816after editing and recompiling the corresponding source file. Note that
17817this makes @value{GDBN} delete all currently-defined breakpoints,
17818auto-displays, and convenience variables, and to clear the value
17819history. (This is necessary in order to preserve the integrity of
17820debugger's data structures that reference the target system's symbol
17821table.)
104c1213 17822
8e04817f 17823@node VxWorks Attach
79a6e687 17824@subsubsection Running Tasks
104c1213
JM
17825
17826@cindex running VxWorks tasks
17827You can also attach to an existing task using the @code{attach} command as
17828follows:
17829
474c8240 17830@smallexample
104c1213 17831(vxgdb) attach @var{task}
474c8240 17832@end smallexample
104c1213
JM
17833
17834@noindent
17835where @var{task} is the VxWorks hexadecimal task ID. The task can be running
17836or suspended when you attach to it. Running tasks are suspended at
17837the time of attachment.
17838
6d2ebf8b 17839@node Embedded Processors
104c1213
JM
17840@section Embedded Processors
17841
17842This section goes into details specific to particular embedded
17843configurations.
17844
c45da7e6
EZ
17845@cindex send command to simulator
17846Whenever a specific embedded processor has a simulator, @value{GDBN}
17847allows to send an arbitrary command to the simulator.
17848
17849@table @code
17850@item sim @var{command}
17851@kindex sim@r{, a command}
17852Send an arbitrary @var{command} string to the simulator. Consult the
17853documentation for the specific simulator in use for information about
17854acceptable commands.
17855@end table
17856
7d86b5d5 17857
104c1213 17858@menu
c45da7e6 17859* ARM:: ARM RDI
172c2a43 17860* M32R/D:: Renesas M32R/D
104c1213 17861* M68K:: Motorola M68K
08be9d71 17862* MicroBlaze:: Xilinx MicroBlaze
104c1213 17863* MIPS Embedded:: MIPS Embedded
a37295f9 17864* OpenRISC 1000:: OpenRisc 1000
104c1213 17865* PA:: HP PA Embedded
4acd40f3 17866* PowerPC Embedded:: PowerPC Embedded
104c1213
JM
17867* Sparclet:: Tsqware Sparclet
17868* Sparclite:: Fujitsu Sparclite
104c1213 17869* Z8000:: Zilog Z8000
a64548ea
EZ
17870* AVR:: Atmel AVR
17871* CRIS:: CRIS
17872* Super-H:: Renesas Super-H
104c1213
JM
17873@end menu
17874
6d2ebf8b 17875@node ARM
104c1213 17876@subsection ARM
c45da7e6 17877@cindex ARM RDI
104c1213
JM
17878
17879@table @code
8e04817f
AC
17880@kindex target rdi
17881@item target rdi @var{dev}
17882ARM Angel monitor, via RDI library interface to ADP protocol. You may
17883use this target to communicate with both boards running the Angel
17884monitor, or with the EmbeddedICE JTAG debug device.
17885
17886@kindex target rdp
17887@item target rdp @var{dev}
17888ARM Demon monitor.
17889
17890@end table
17891
e2f4edfd
EZ
17892@value{GDBN} provides the following ARM-specific commands:
17893
17894@table @code
17895@item set arm disassembler
17896@kindex set arm
17897This commands selects from a list of disassembly styles. The
17898@code{"std"} style is the standard style.
17899
17900@item show arm disassembler
17901@kindex show arm
17902Show the current disassembly style.
17903
17904@item set arm apcs32
17905@cindex ARM 32-bit mode
17906This command toggles ARM operation mode between 32-bit and 26-bit.
17907
17908@item show arm apcs32
17909Display the current usage of the ARM 32-bit mode.
17910
17911@item set arm fpu @var{fputype}
17912This command sets the ARM floating-point unit (FPU) type. The
17913argument @var{fputype} can be one of these:
17914
17915@table @code
17916@item auto
17917Determine the FPU type by querying the OS ABI.
17918@item softfpa
17919Software FPU, with mixed-endian doubles on little-endian ARM
17920processors.
17921@item fpa
17922GCC-compiled FPA co-processor.
17923@item softvfp
17924Software FPU with pure-endian doubles.
17925@item vfp
17926VFP co-processor.
17927@end table
17928
17929@item show arm fpu
17930Show the current type of the FPU.
17931
17932@item set arm abi
17933This command forces @value{GDBN} to use the specified ABI.
17934
17935@item show arm abi
17936Show the currently used ABI.
17937
0428b8f5
DJ
17938@item set arm fallback-mode (arm|thumb|auto)
17939@value{GDBN} uses the symbol table, when available, to determine
17940whether instructions are ARM or Thumb. This command controls
17941@value{GDBN}'s default behavior when the symbol table is not
17942available. The default is @samp{auto}, which causes @value{GDBN} to
17943use the current execution mode (from the @code{T} bit in the @code{CPSR}
17944register).
17945
17946@item show arm fallback-mode
17947Show the current fallback instruction mode.
17948
17949@item set arm force-mode (arm|thumb|auto)
17950This command overrides use of the symbol table to determine whether
17951instructions are ARM or Thumb. The default is @samp{auto}, which
17952causes @value{GDBN} to use the symbol table and then the setting
17953of @samp{set arm fallback-mode}.
17954
17955@item show arm force-mode
17956Show the current forced instruction mode.
17957
e2f4edfd
EZ
17958@item set debug arm
17959Toggle whether to display ARM-specific debugging messages from the ARM
17960target support subsystem.
17961
17962@item show debug arm
17963Show whether ARM-specific debugging messages are enabled.
17964@end table
17965
c45da7e6
EZ
17966The following commands are available when an ARM target is debugged
17967using the RDI interface:
17968
17969@table @code
17970@item rdilogfile @r{[}@var{file}@r{]}
17971@kindex rdilogfile
17972@cindex ADP (Angel Debugger Protocol) logging
17973Set the filename for the ADP (Angel Debugger Protocol) packet log.
17974With an argument, sets the log file to the specified @var{file}. With
17975no argument, show the current log file name. The default log file is
17976@file{rdi.log}.
17977
17978@item rdilogenable @r{[}@var{arg}@r{]}
17979@kindex rdilogenable
17980Control logging of ADP packets. With an argument of 1 or @code{"yes"}
17981enables logging, with an argument 0 or @code{"no"} disables it. With
17982no arguments displays the current setting. When logging is enabled,
17983ADP packets exchanged between @value{GDBN} and the RDI target device
17984are logged to a file.
17985
17986@item set rdiromatzero
17987@kindex set rdiromatzero
17988@cindex ROM at zero address, RDI
17989Tell @value{GDBN} whether the target has ROM at address 0. If on,
17990vector catching is disabled, so that zero address can be used. If off
17991(the default), vector catching is enabled. For this command to take
17992effect, it needs to be invoked prior to the @code{target rdi} command.
17993
17994@item show rdiromatzero
17995@kindex show rdiromatzero
17996Show the current setting of ROM at zero address.
17997
17998@item set rdiheartbeat
17999@kindex set rdiheartbeat
18000@cindex RDI heartbeat
18001Enable or disable RDI heartbeat packets. It is not recommended to
18002turn on this option, since it confuses ARM and EPI JTAG interface, as
18003well as the Angel monitor.
18004
18005@item show rdiheartbeat
18006@kindex show rdiheartbeat
18007Show the setting of RDI heartbeat packets.
18008@end table
18009
ee8e71d4
EZ
18010@table @code
18011@item target sim @r{[}@var{simargs}@r{]} @dots{}
18012The @value{GDBN} ARM simulator accepts the following optional arguments.
18013
18014@table @code
18015@item --swi-support=@var{type}
18016Tell the simulator which SWI interfaces to support.
18017@var{type} may be a comma separated list of the following values.
18018The default value is @code{all}.
18019
18020@table @code
18021@item none
18022@item demon
18023@item angel
18024@item redboot
18025@item all
18026@end table
18027@end table
18028@end table
e2f4edfd 18029
8e04817f 18030@node M32R/D
ba04e063 18031@subsection Renesas M32R/D and M32R/SDI
8e04817f
AC
18032
18033@table @code
8e04817f
AC
18034@kindex target m32r
18035@item target m32r @var{dev}
172c2a43 18036Renesas M32R/D ROM monitor.
8e04817f 18037
fb3e19c0
KI
18038@kindex target m32rsdi
18039@item target m32rsdi @var{dev}
18040Renesas M32R SDI server, connected via parallel port to the board.
721c2651
EZ
18041@end table
18042
18043The following @value{GDBN} commands are specific to the M32R monitor:
18044
18045@table @code
18046@item set download-path @var{path}
18047@kindex set download-path
18048@cindex find downloadable @sc{srec} files (M32R)
d3e8051b 18049Set the default path for finding downloadable @sc{srec} files.
721c2651
EZ
18050
18051@item show download-path
18052@kindex show download-path
18053Show the default path for downloadable @sc{srec} files.
fb3e19c0 18054
721c2651
EZ
18055@item set board-address @var{addr}
18056@kindex set board-address
18057@cindex M32-EVA target board address
18058Set the IP address for the M32R-EVA target board.
18059
18060@item show board-address
18061@kindex show board-address
18062Show the current IP address of the target board.
18063
18064@item set server-address @var{addr}
18065@kindex set server-address
18066@cindex download server address (M32R)
18067Set the IP address for the download server, which is the @value{GDBN}'s
18068host machine.
18069
18070@item show server-address
18071@kindex show server-address
18072Display the IP address of the download server.
18073
18074@item upload @r{[}@var{file}@r{]}
18075@kindex upload@r{, M32R}
18076Upload the specified @sc{srec} @var{file} via the monitor's Ethernet
18077upload capability. If no @var{file} argument is given, the current
18078executable file is uploaded.
18079
18080@item tload @r{[}@var{file}@r{]}
18081@kindex tload@r{, M32R}
18082Test the @code{upload} command.
8e04817f
AC
18083@end table
18084
ba04e063
EZ
18085The following commands are available for M32R/SDI:
18086
18087@table @code
18088@item sdireset
18089@kindex sdireset
18090@cindex reset SDI connection, M32R
18091This command resets the SDI connection.
18092
18093@item sdistatus
18094@kindex sdistatus
18095This command shows the SDI connection status.
18096
18097@item debug_chaos
18098@kindex debug_chaos
18099@cindex M32R/Chaos debugging
18100Instructs the remote that M32R/Chaos debugging is to be used.
18101
18102@item use_debug_dma
18103@kindex use_debug_dma
18104Instructs the remote to use the DEBUG_DMA method of accessing memory.
18105
18106@item use_mon_code
18107@kindex use_mon_code
18108Instructs the remote to use the MON_CODE method of accessing memory.
18109
18110@item use_ib_break
18111@kindex use_ib_break
18112Instructs the remote to set breakpoints by IB break.
18113
18114@item use_dbt_break
18115@kindex use_dbt_break
18116Instructs the remote to set breakpoints by DBT.
18117@end table
18118
8e04817f
AC
18119@node M68K
18120@subsection M68k
18121
7ce59000
DJ
18122The Motorola m68k configuration includes ColdFire support, and a
18123target command for the following ROM monitor.
8e04817f
AC
18124
18125@table @code
18126
8e04817f
AC
18127@kindex target dbug
18128@item target dbug @var{dev}
18129dBUG ROM monitor for Motorola ColdFire.
18130
8e04817f
AC
18131@end table
18132
08be9d71
ME
18133@node MicroBlaze
18134@subsection MicroBlaze
18135@cindex Xilinx MicroBlaze
18136@cindex XMD, Xilinx Microprocessor Debugger
18137
18138The MicroBlaze is a soft-core processor supported on various Xilinx
18139FPGAs, such as Spartan or Virtex series. Boards with these processors
18140usually have JTAG ports which connect to a host system running the Xilinx
18141Embedded Development Kit (EDK) or Software Development Kit (SDK).
18142This host system is used to download the configuration bitstream to
18143the target FPGA. The Xilinx Microprocessor Debugger (XMD) program
18144communicates with the target board using the JTAG interface and
18145presents a @code{gdbserver} interface to the board. By default
18146@code{xmd} uses port @code{1234}. (While it is possible to change
18147this default port, it requires the use of undocumented @code{xmd}
18148commands. Contact Xilinx support if you need to do this.)
18149
18150Use these GDB commands to connect to the MicroBlaze target processor.
18151
18152@table @code
18153@item target remote :1234
18154Use this command to connect to the target if you are running @value{GDBN}
18155on the same system as @code{xmd}.
18156
18157@item target remote @var{xmd-host}:1234
18158Use this command to connect to the target if it is connected to @code{xmd}
18159running on a different system named @var{xmd-host}.
18160
18161@item load
18162Use this command to download a program to the MicroBlaze target.
18163
18164@item set debug microblaze @var{n}
18165Enable MicroBlaze-specific debugging messages if non-zero.
18166
18167@item show debug microblaze @var{n}
18168Show MicroBlaze-specific debugging level.
18169@end table
18170
8e04817f
AC
18171@node MIPS Embedded
18172@subsection MIPS Embedded
18173
18174@cindex MIPS boards
18175@value{GDBN} can use the MIPS remote debugging protocol to talk to a
18176MIPS board attached to a serial line. This is available when
18177you configure @value{GDBN} with @samp{--target=mips-idt-ecoff}.
104c1213 18178
8e04817f
AC
18179@need 1000
18180Use these @value{GDBN} commands to specify the connection to your target board:
104c1213 18181
8e04817f
AC
18182@table @code
18183@item target mips @var{port}
18184@kindex target mips @var{port}
18185To run a program on the board, start up @code{@value{GDBP}} with the
18186name of your program as the argument. To connect to the board, use the
18187command @samp{target mips @var{port}}, where @var{port} is the name of
18188the serial port connected to the board. If the program has not already
18189been downloaded to the board, you may use the @code{load} command to
18190download it. You can then use all the usual @value{GDBN} commands.
104c1213 18191
8e04817f
AC
18192For example, this sequence connects to the target board through a serial
18193port, and loads and runs a program called @var{prog} through the
18194debugger:
104c1213 18195
474c8240 18196@smallexample
8e04817f
AC
18197host$ @value{GDBP} @var{prog}
18198@value{GDBN} is free software and @dots{}
18199(@value{GDBP}) target mips /dev/ttyb
18200(@value{GDBP}) load @var{prog}
18201(@value{GDBP}) run
474c8240 18202@end smallexample
104c1213 18203
8e04817f
AC
18204@item target mips @var{hostname}:@var{portnumber}
18205On some @value{GDBN} host configurations, you can specify a TCP
18206connection (for instance, to a serial line managed by a terminal
18207concentrator) instead of a serial port, using the syntax
18208@samp{@var{hostname}:@var{portnumber}}.
104c1213 18209
8e04817f
AC
18210@item target pmon @var{port}
18211@kindex target pmon @var{port}
18212PMON ROM monitor.
104c1213 18213
8e04817f
AC
18214@item target ddb @var{port}
18215@kindex target ddb @var{port}
18216NEC's DDB variant of PMON for Vr4300.
104c1213 18217
8e04817f
AC
18218@item target lsi @var{port}
18219@kindex target lsi @var{port}
18220LSI variant of PMON.
104c1213 18221
8e04817f
AC
18222@kindex target r3900
18223@item target r3900 @var{dev}
18224Densan DVE-R3900 ROM monitor for Toshiba R3900 Mips.
104c1213 18225
8e04817f
AC
18226@kindex target array
18227@item target array @var{dev}
18228Array Tech LSI33K RAID controller board.
104c1213 18229
8e04817f 18230@end table
104c1213 18231
104c1213 18232
8e04817f
AC
18233@noindent
18234@value{GDBN} also supports these special commands for MIPS targets:
104c1213 18235
8e04817f 18236@table @code
8e04817f
AC
18237@item set mipsfpu double
18238@itemx set mipsfpu single
18239@itemx set mipsfpu none
a64548ea 18240@itemx set mipsfpu auto
8e04817f
AC
18241@itemx show mipsfpu
18242@kindex set mipsfpu
18243@kindex show mipsfpu
18244@cindex MIPS remote floating point
18245@cindex floating point, MIPS remote
18246If your target board does not support the MIPS floating point
18247coprocessor, you should use the command @samp{set mipsfpu none} (if you
18248need this, you may wish to put the command in your @value{GDBN} init
18249file). This tells @value{GDBN} how to find the return value of
18250functions which return floating point values. It also allows
18251@value{GDBN} to avoid saving the floating point registers when calling
18252functions on the board. If you are using a floating point coprocessor
18253with only single precision floating point support, as on the @sc{r4650}
18254processor, use the command @samp{set mipsfpu single}. The default
18255double precision floating point coprocessor may be selected using
18256@samp{set mipsfpu double}.
104c1213 18257
8e04817f
AC
18258In previous versions the only choices were double precision or no
18259floating point, so @samp{set mipsfpu on} will select double precision
18260and @samp{set mipsfpu off} will select no floating point.
104c1213 18261
8e04817f
AC
18262As usual, you can inquire about the @code{mipsfpu} variable with
18263@samp{show mipsfpu}.
104c1213 18264
8e04817f
AC
18265@item set timeout @var{seconds}
18266@itemx set retransmit-timeout @var{seconds}
18267@itemx show timeout
18268@itemx show retransmit-timeout
18269@cindex @code{timeout}, MIPS protocol
18270@cindex @code{retransmit-timeout}, MIPS protocol
18271@kindex set timeout
18272@kindex show timeout
18273@kindex set retransmit-timeout
18274@kindex show retransmit-timeout
18275You can control the timeout used while waiting for a packet, in the MIPS
18276remote protocol, with the @code{set timeout @var{seconds}} command. The
18277default is 5 seconds. Similarly, you can control the timeout used while
a6f3e723 18278waiting for an acknowledgment of a packet with the @code{set
8e04817f
AC
18279retransmit-timeout @var{seconds}} command. The default is 3 seconds.
18280You can inspect both values with @code{show timeout} and @code{show
18281retransmit-timeout}. (These commands are @emph{only} available when
18282@value{GDBN} is configured for @samp{--target=mips-idt-ecoff}.)
104c1213 18283
8e04817f
AC
18284The timeout set by @code{set timeout} does not apply when @value{GDBN}
18285is waiting for your program to stop. In that case, @value{GDBN} waits
18286forever because it has no way of knowing how long the program is going
18287to run before stopping.
ba04e063
EZ
18288
18289@item set syn-garbage-limit @var{num}
18290@kindex set syn-garbage-limit@r{, MIPS remote}
18291@cindex synchronize with remote MIPS target
18292Limit the maximum number of characters @value{GDBN} should ignore when
18293it tries to synchronize with the remote target. The default is 10
18294characters. Setting the limit to -1 means there's no limit.
18295
18296@item show syn-garbage-limit
18297@kindex show syn-garbage-limit@r{, MIPS remote}
18298Show the current limit on the number of characters to ignore when
18299trying to synchronize with the remote system.
18300
18301@item set monitor-prompt @var{prompt}
18302@kindex set monitor-prompt@r{, MIPS remote}
18303@cindex remote monitor prompt
18304Tell @value{GDBN} to expect the specified @var{prompt} string from the
18305remote monitor. The default depends on the target:
18306@table @asis
18307@item pmon target
18308@samp{PMON}
18309@item ddb target
18310@samp{NEC010}
18311@item lsi target
18312@samp{PMON>}
18313@end table
18314
18315@item show monitor-prompt
18316@kindex show monitor-prompt@r{, MIPS remote}
18317Show the current strings @value{GDBN} expects as the prompt from the
18318remote monitor.
18319
18320@item set monitor-warnings
18321@kindex set monitor-warnings@r{, MIPS remote}
18322Enable or disable monitor warnings about hardware breakpoints. This
18323has effect only for the @code{lsi} target. When on, @value{GDBN} will
18324display warning messages whose codes are returned by the @code{lsi}
18325PMON monitor for breakpoint commands.
18326
18327@item show monitor-warnings
18328@kindex show monitor-warnings@r{, MIPS remote}
18329Show the current setting of printing monitor warnings.
18330
18331@item pmon @var{command}
18332@kindex pmon@r{, MIPS remote}
18333@cindex send PMON command
18334This command allows sending an arbitrary @var{command} string to the
18335monitor. The monitor must be in debug mode for this to work.
8e04817f 18336@end table
104c1213 18337
a37295f9
MM
18338@node OpenRISC 1000
18339@subsection OpenRISC 1000
18340@cindex OpenRISC 1000
18341
18342@cindex or1k boards
18343See OR1k Architecture document (@uref{www.opencores.org}) for more information
18344about platform and commands.
18345
18346@table @code
18347
18348@kindex target jtag
18349@item target jtag jtag://@var{host}:@var{port}
18350
18351Connects to remote JTAG server.
18352JTAG remote server can be either an or1ksim or JTAG server,
18353connected via parallel port to the board.
18354
18355Example: @code{target jtag jtag://localhost:9999}
18356
18357@kindex or1ksim
18358@item or1ksim @var{command}
18359If connected to @code{or1ksim} OpenRISC 1000 Architectural
18360Simulator, proprietary commands can be executed.
18361
18362@kindex info or1k spr
18363@item info or1k spr
18364Displays spr groups.
18365
18366@item info or1k spr @var{group}
18367@itemx info or1k spr @var{groupno}
18368Displays register names in selected group.
18369
18370@item info or1k spr @var{group} @var{register}
18371@itemx info or1k spr @var{register}
18372@itemx info or1k spr @var{groupno} @var{registerno}
18373@itemx info or1k spr @var{registerno}
18374Shows information about specified spr register.
18375
18376@kindex spr
18377@item spr @var{group} @var{register} @var{value}
18378@itemx spr @var{register @var{value}}
18379@itemx spr @var{groupno} @var{registerno @var{value}}
18380@itemx spr @var{registerno @var{value}}
18381Writes @var{value} to specified spr register.
18382@end table
18383
18384Some implementations of OpenRISC 1000 Architecture also have hardware trace.
18385It is very similar to @value{GDBN} trace, except it does not interfere with normal
18386program execution and is thus much faster. Hardware breakpoints/watchpoint
18387triggers can be set using:
18388@table @code
18389@item $LEA/$LDATA
18390Load effective address/data
18391@item $SEA/$SDATA
18392Store effective address/data
18393@item $AEA/$ADATA
18394Access effective address ($SEA or $LEA) or data ($SDATA/$LDATA)
18395@item $FETCH
18396Fetch data
18397@end table
18398
18399When triggered, it can capture low level data, like: @code{PC}, @code{LSEA},
18400@code{LDATA}, @code{SDATA}, @code{READSPR}, @code{WRITESPR}, @code{INSTR}.
18401
18402@code{htrace} commands:
18403@cindex OpenRISC 1000 htrace
18404@table @code
18405@kindex hwatch
18406@item hwatch @var{conditional}
d3e8051b 18407Set hardware watchpoint on combination of Load/Store Effective Address(es)
a37295f9
MM
18408or Data. For example:
18409
18410@code{hwatch ($LEA == my_var) && ($LDATA < 50) || ($SEA == my_var) && ($SDATA >= 50)}
18411
18412@code{hwatch ($LEA == my_var) && ($LDATA < 50) || ($SEA == my_var) && ($SDATA >= 50)}
18413
4644b6e3 18414@kindex htrace
a37295f9
MM
18415@item htrace info
18416Display information about current HW trace configuration.
18417
a37295f9
MM
18418@item htrace trigger @var{conditional}
18419Set starting criteria for HW trace.
18420
a37295f9
MM
18421@item htrace qualifier @var{conditional}
18422Set acquisition qualifier for HW trace.
18423
a37295f9
MM
18424@item htrace stop @var{conditional}
18425Set HW trace stopping criteria.
18426
f153cc92 18427@item htrace record [@var{data}]*
a37295f9
MM
18428Selects the data to be recorded, when qualifier is met and HW trace was
18429triggered.
18430
a37295f9 18431@item htrace enable
a37295f9
MM
18432@itemx htrace disable
18433Enables/disables the HW trace.
18434
f153cc92 18435@item htrace rewind [@var{filename}]
a37295f9
MM
18436Clears currently recorded trace data.
18437
18438If filename is specified, new trace file is made and any newly collected data
18439will be written there.
18440
f153cc92 18441@item htrace print [@var{start} [@var{len}]]
a37295f9
MM
18442Prints trace buffer, using current record configuration.
18443
a37295f9
MM
18444@item htrace mode continuous
18445Set continuous trace mode.
18446
a37295f9
MM
18447@item htrace mode suspend
18448Set suspend trace mode.
18449
18450@end table
18451
4acd40f3
TJB
18452@node PowerPC Embedded
18453@subsection PowerPC Embedded
104c1213 18454
55eddb0f
DJ
18455@value{GDBN} provides the following PowerPC-specific commands:
18456
104c1213 18457@table @code
55eddb0f
DJ
18458@kindex set powerpc
18459@item set powerpc soft-float
18460@itemx show powerpc soft-float
18461Force @value{GDBN} to use (or not use) a software floating point calling
18462convention. By default, @value{GDBN} selects the calling convention based
18463on the selected architecture and the provided executable file.
18464
18465@item set powerpc vector-abi
18466@itemx show powerpc vector-abi
18467Force @value{GDBN} to use the specified calling convention for vector
18468arguments and return values. The valid options are @samp{auto};
18469@samp{generic}, to avoid vector registers even if they are present;
18470@samp{altivec}, to use AltiVec registers; and @samp{spe} to use SPE
18471registers. By default, @value{GDBN} selects the calling convention
18472based on the selected architecture and the provided executable file.
18473
8e04817f
AC
18474@kindex target dink32
18475@item target dink32 @var{dev}
18476DINK32 ROM monitor.
104c1213 18477
8e04817f
AC
18478@kindex target ppcbug
18479@item target ppcbug @var{dev}
18480@kindex target ppcbug1
18481@item target ppcbug1 @var{dev}
18482PPCBUG ROM monitor for PowerPC.
104c1213 18483
8e04817f
AC
18484@kindex target sds
18485@item target sds @var{dev}
18486SDS monitor, running on a PowerPC board (such as Motorola's ADS).
c45da7e6 18487@end table
8e04817f 18488
c45da7e6 18489@cindex SDS protocol
d52fb0e9 18490The following commands specific to the SDS protocol are supported
55eddb0f 18491by @value{GDBN}:
c45da7e6
EZ
18492
18493@table @code
18494@item set sdstimeout @var{nsec}
18495@kindex set sdstimeout
18496Set the timeout for SDS protocol reads to be @var{nsec} seconds. The
18497default is 2 seconds.
18498
18499@item show sdstimeout
18500@kindex show sdstimeout
18501Show the current value of the SDS timeout.
18502
18503@item sds @var{command}
18504@kindex sds@r{, a command}
18505Send the specified @var{command} string to the SDS monitor.
8e04817f
AC
18506@end table
18507
c45da7e6 18508
8e04817f
AC
18509@node PA
18510@subsection HP PA Embedded
104c1213
JM
18511
18512@table @code
18513
8e04817f
AC
18514@kindex target op50n
18515@item target op50n @var{dev}
18516OP50N monitor, running on an OKI HPPA board.
18517
18518@kindex target w89k
18519@item target w89k @var{dev}
18520W89K monitor, running on a Winbond HPPA board.
104c1213
JM
18521
18522@end table
18523
8e04817f
AC
18524@node Sparclet
18525@subsection Tsqware Sparclet
104c1213 18526
8e04817f
AC
18527@cindex Sparclet
18528
18529@value{GDBN} enables developers to debug tasks running on
18530Sparclet targets from a Unix host.
18531@value{GDBN} uses code that runs on
18532both the Unix host and on the Sparclet target. The program
18533@code{@value{GDBP}} is installed and executed on the Unix host.
104c1213 18534
8e04817f
AC
18535@table @code
18536@item remotetimeout @var{args}
18537@kindex remotetimeout
18538@value{GDBN} supports the option @code{remotetimeout}.
18539This option is set by the user, and @var{args} represents the number of
18540seconds @value{GDBN} waits for responses.
104c1213
JM
18541@end table
18542
8e04817f
AC
18543@cindex compiling, on Sparclet
18544When compiling for debugging, include the options @samp{-g} to get debug
18545information and @samp{-Ttext} to relocate the program to where you wish to
18546load it on the target. You may also want to add the options @samp{-n} or
18547@samp{-N} in order to reduce the size of the sections. Example:
104c1213 18548
474c8240 18549@smallexample
8e04817f 18550sparclet-aout-gcc prog.c -Ttext 0x12010000 -g -o prog -N
474c8240 18551@end smallexample
104c1213 18552
8e04817f 18553You can use @code{objdump} to verify that the addresses are what you intended:
104c1213 18554
474c8240 18555@smallexample
8e04817f 18556sparclet-aout-objdump --headers --syms prog
474c8240 18557@end smallexample
104c1213 18558
8e04817f
AC
18559@cindex running, on Sparclet
18560Once you have set
18561your Unix execution search path to find @value{GDBN}, you are ready to
18562run @value{GDBN}. From your Unix host, run @code{@value{GDBP}}
18563(or @code{sparclet-aout-gdb}, depending on your installation).
104c1213 18564
8e04817f
AC
18565@value{GDBN} comes up showing the prompt:
18566
474c8240 18567@smallexample
8e04817f 18568(gdbslet)
474c8240 18569@end smallexample
104c1213
JM
18570
18571@menu
8e04817f
AC
18572* Sparclet File:: Setting the file to debug
18573* Sparclet Connection:: Connecting to Sparclet
18574* Sparclet Download:: Sparclet download
18575* Sparclet Execution:: Running and debugging
104c1213
JM
18576@end menu
18577
8e04817f 18578@node Sparclet File
79a6e687 18579@subsubsection Setting File to Debug
104c1213 18580
8e04817f 18581The @value{GDBN} command @code{file} lets you choose with program to debug.
104c1213 18582
474c8240 18583@smallexample
8e04817f 18584(gdbslet) file prog
474c8240 18585@end smallexample
104c1213 18586
8e04817f
AC
18587@need 1000
18588@value{GDBN} then attempts to read the symbol table of @file{prog}.
18589@value{GDBN} locates
18590the file by searching the directories listed in the command search
18591path.
12c27660 18592If the file was compiled with debug information (option @samp{-g}), source
8e04817f
AC
18593files will be searched as well.
18594@value{GDBN} locates
18595the source files by searching the directories listed in the directory search
79a6e687 18596path (@pxref{Environment, ,Your Program's Environment}).
8e04817f
AC
18597If it fails
18598to find a file, it displays a message such as:
104c1213 18599
474c8240 18600@smallexample
8e04817f 18601prog: No such file or directory.
474c8240 18602@end smallexample
104c1213 18603
8e04817f
AC
18604When this happens, add the appropriate directories to the search paths with
18605the @value{GDBN} commands @code{path} and @code{dir}, and execute the
18606@code{target} command again.
104c1213 18607
8e04817f
AC
18608@node Sparclet Connection
18609@subsubsection Connecting to Sparclet
104c1213 18610
8e04817f
AC
18611The @value{GDBN} command @code{target} lets you connect to a Sparclet target.
18612To connect to a target on serial port ``@code{ttya}'', type:
104c1213 18613
474c8240 18614@smallexample
8e04817f
AC
18615(gdbslet) target sparclet /dev/ttya
18616Remote target sparclet connected to /dev/ttya
18617main () at ../prog.c:3
474c8240 18618@end smallexample
104c1213 18619
8e04817f
AC
18620@need 750
18621@value{GDBN} displays messages like these:
104c1213 18622
474c8240 18623@smallexample
8e04817f 18624Connected to ttya.
474c8240 18625@end smallexample
104c1213 18626
8e04817f 18627@node Sparclet Download
79a6e687 18628@subsubsection Sparclet Download
104c1213 18629
8e04817f
AC
18630@cindex download to Sparclet
18631Once connected to the Sparclet target,
18632you can use the @value{GDBN}
18633@code{load} command to download the file from the host to the target.
18634The file name and load offset should be given as arguments to the @code{load}
18635command.
18636Since the file format is aout, the program must be loaded to the starting
18637address. You can use @code{objdump} to find out what this value is. The load
18638offset is an offset which is added to the VMA (virtual memory address)
18639of each of the file's sections.
18640For instance, if the program
18641@file{prog} was linked to text address 0x1201000, with data at 0x12010160
18642and bss at 0x12010170, in @value{GDBN}, type:
104c1213 18643
474c8240 18644@smallexample
8e04817f
AC
18645(gdbslet) load prog 0x12010000
18646Loading section .text, size 0xdb0 vma 0x12010000
474c8240 18647@end smallexample
104c1213 18648
8e04817f
AC
18649If the code is loaded at a different address then what the program was linked
18650to, you may need to use the @code{section} and @code{add-symbol-file} commands
18651to tell @value{GDBN} where to map the symbol table.
18652
18653@node Sparclet Execution
79a6e687 18654@subsubsection Running and Debugging
8e04817f
AC
18655
18656@cindex running and debugging Sparclet programs
18657You can now begin debugging the task using @value{GDBN}'s execution control
18658commands, @code{b}, @code{step}, @code{run}, etc. See the @value{GDBN}
18659manual for the list of commands.
18660
474c8240 18661@smallexample
8e04817f
AC
18662(gdbslet) b main
18663Breakpoint 1 at 0x12010000: file prog.c, line 3.
18664(gdbslet) run
18665Starting program: prog
18666Breakpoint 1, main (argc=1, argv=0xeffff21c) at prog.c:3
186673 char *symarg = 0;
18668(gdbslet) step
186694 char *execarg = "hello!";
18670(gdbslet)
474c8240 18671@end smallexample
8e04817f
AC
18672
18673@node Sparclite
18674@subsection Fujitsu Sparclite
104c1213
JM
18675
18676@table @code
18677
8e04817f
AC
18678@kindex target sparclite
18679@item target sparclite @var{dev}
18680Fujitsu sparclite boards, used only for the purpose of loading.
18681You must use an additional command to debug the program.
18682For example: target remote @var{dev} using @value{GDBN} standard
18683remote protocol.
104c1213
JM
18684
18685@end table
18686
8e04817f
AC
18687@node Z8000
18688@subsection Zilog Z8000
104c1213 18689
8e04817f
AC
18690@cindex Z8000
18691@cindex simulator, Z8000
18692@cindex Zilog Z8000 simulator
104c1213 18693
8e04817f
AC
18694When configured for debugging Zilog Z8000 targets, @value{GDBN} includes
18695a Z8000 simulator.
18696
18697For the Z8000 family, @samp{target sim} simulates either the Z8002 (the
18698unsegmented variant of the Z8000 architecture) or the Z8001 (the
18699segmented variant). The simulator recognizes which architecture is
18700appropriate by inspecting the object code.
104c1213 18701
8e04817f
AC
18702@table @code
18703@item target sim @var{args}
18704@kindex sim
18705@kindex target sim@r{, with Z8000}
18706Debug programs on a simulated CPU. If the simulator supports setup
18707options, specify them via @var{args}.
104c1213
JM
18708@end table
18709
8e04817f
AC
18710@noindent
18711After specifying this target, you can debug programs for the simulated
18712CPU in the same style as programs for your host computer; use the
18713@code{file} command to load a new program image, the @code{run} command
18714to run your program, and so on.
18715
18716As well as making available all the usual machine registers
18717(@pxref{Registers, ,Registers}), the Z8000 simulator provides three
18718additional items of information as specially named registers:
104c1213
JM
18719
18720@table @code
18721
8e04817f
AC
18722@item cycles
18723Counts clock-ticks in the simulator.
104c1213 18724
8e04817f
AC
18725@item insts
18726Counts instructions run in the simulator.
104c1213 18727
8e04817f
AC
18728@item time
18729Execution time in 60ths of a second.
104c1213 18730
8e04817f 18731@end table
104c1213 18732
8e04817f
AC
18733You can refer to these values in @value{GDBN} expressions with the usual
18734conventions; for example, @w{@samp{b fputc if $cycles>5000}} sets a
18735conditional breakpoint that suspends only after at least 5000
18736simulated clock ticks.
104c1213 18737
a64548ea
EZ
18738@node AVR
18739@subsection Atmel AVR
18740@cindex AVR
18741
18742When configured for debugging the Atmel AVR, @value{GDBN} supports the
18743following AVR-specific commands:
18744
18745@table @code
18746@item info io_registers
18747@kindex info io_registers@r{, AVR}
18748@cindex I/O registers (Atmel AVR)
18749This command displays information about the AVR I/O registers. For
18750each register, @value{GDBN} prints its number and value.
18751@end table
18752
18753@node CRIS
18754@subsection CRIS
18755@cindex CRIS
18756
18757When configured for debugging CRIS, @value{GDBN} provides the
18758following CRIS-specific commands:
18759
18760@table @code
18761@item set cris-version @var{ver}
18762@cindex CRIS version
e22e55c9
OF
18763Set the current CRIS version to @var{ver}, either @samp{10} or @samp{32}.
18764The CRIS version affects register names and sizes. This command is useful in
18765case autodetection of the CRIS version fails.
a64548ea
EZ
18766
18767@item show cris-version
18768Show the current CRIS version.
18769
18770@item set cris-dwarf2-cfi
18771@cindex DWARF-2 CFI and CRIS
e22e55c9
OF
18772Set the usage of DWARF-2 CFI for CRIS debugging. The default is @samp{on}.
18773Change to @samp{off} when using @code{gcc-cris} whose version is below
18774@code{R59}.
a64548ea
EZ
18775
18776@item show cris-dwarf2-cfi
18777Show the current state of using DWARF-2 CFI.
e22e55c9
OF
18778
18779@item set cris-mode @var{mode}
18780@cindex CRIS mode
18781Set the current CRIS mode to @var{mode}. It should only be changed when
18782debugging in guru mode, in which case it should be set to
18783@samp{guru} (the default is @samp{normal}).
18784
18785@item show cris-mode
18786Show the current CRIS mode.
a64548ea
EZ
18787@end table
18788
18789@node Super-H
18790@subsection Renesas Super-H
18791@cindex Super-H
18792
18793For the Renesas Super-H processor, @value{GDBN} provides these
18794commands:
18795
18796@table @code
18797@item regs
18798@kindex regs@r{, Super-H}
18799Show the values of all Super-H registers.
c055b101
CV
18800
18801@item set sh calling-convention @var{convention}
18802@kindex set sh calling-convention
18803Set the calling-convention used when calling functions from @value{GDBN}.
18804Allowed values are @samp{gcc}, which is the default setting, and @samp{renesas}.
18805With the @samp{gcc} setting, functions are called using the @value{NGCC} calling
18806convention. If the DWARF-2 information of the called function specifies
18807that the function follows the Renesas calling convention, the function
18808is called using the Renesas calling convention. If the calling convention
18809is set to @samp{renesas}, the Renesas calling convention is always used,
18810regardless of the DWARF-2 information. This can be used to override the
18811default of @samp{gcc} if debug information is missing, or the compiler
18812does not emit the DWARF-2 calling convention entry for a function.
18813
18814@item show sh calling-convention
18815@kindex show sh calling-convention
18816Show the current calling convention setting.
18817
a64548ea
EZ
18818@end table
18819
18820
8e04817f
AC
18821@node Architectures
18822@section Architectures
104c1213 18823
8e04817f
AC
18824This section describes characteristics of architectures that affect
18825all uses of @value{GDBN} with the architecture, both native and cross.
104c1213 18826
8e04817f 18827@menu
9c16f35a 18828* i386::
8e04817f
AC
18829* A29K::
18830* Alpha::
18831* MIPS::
a64548ea 18832* HPPA:: HP PA architecture
23d964e7 18833* SPU:: Cell Broadband Engine SPU architecture
4acd40f3 18834* PowerPC::
8e04817f 18835@end menu
104c1213 18836
9c16f35a 18837@node i386
db2e3e2e 18838@subsection x86 Architecture-specific Issues
9c16f35a
EZ
18839
18840@table @code
18841@item set struct-convention @var{mode}
18842@kindex set struct-convention
18843@cindex struct return convention
18844@cindex struct/union returned in registers
18845Set the convention used by the inferior to return @code{struct}s and
18846@code{union}s from functions to @var{mode}. Possible values of
18847@var{mode} are @code{"pcc"}, @code{"reg"}, and @code{"default"} (the
18848default). @code{"default"} or @code{"pcc"} means that @code{struct}s
18849are returned on the stack, while @code{"reg"} means that a
18850@code{struct} or a @code{union} whose size is 1, 2, 4, or 8 bytes will
18851be returned in a register.
18852
18853@item show struct-convention
18854@kindex show struct-convention
18855Show the current setting of the convention to return @code{struct}s
18856from functions.
18857@end table
18858
8e04817f
AC
18859@node A29K
18860@subsection A29K
104c1213
JM
18861
18862@table @code
104c1213 18863
8e04817f
AC
18864@kindex set rstack_high_address
18865@cindex AMD 29K register stack
18866@cindex register stack, AMD29K
18867@item set rstack_high_address @var{address}
18868On AMD 29000 family processors, registers are saved in a separate
18869@dfn{register stack}. There is no way for @value{GDBN} to determine the
18870extent of this stack. Normally, @value{GDBN} just assumes that the
18871stack is ``large enough''. This may result in @value{GDBN} referencing
18872memory locations that do not exist. If necessary, you can get around
18873this problem by specifying the ending address of the register stack with
18874the @code{set rstack_high_address} command. The argument should be an
18875address, which you probably want to precede with @samp{0x} to specify in
18876hexadecimal.
104c1213 18877
8e04817f
AC
18878@kindex show rstack_high_address
18879@item show rstack_high_address
18880Display the current limit of the register stack, on AMD 29000 family
18881processors.
104c1213 18882
8e04817f 18883@end table
104c1213 18884
8e04817f
AC
18885@node Alpha
18886@subsection Alpha
104c1213 18887
8e04817f 18888See the following section.
104c1213 18889
8e04817f
AC
18890@node MIPS
18891@subsection MIPS
104c1213 18892
8e04817f
AC
18893@cindex stack on Alpha
18894@cindex stack on MIPS
18895@cindex Alpha stack
18896@cindex MIPS stack
18897Alpha- and MIPS-based computers use an unusual stack frame, which
18898sometimes requires @value{GDBN} to search backward in the object code to
18899find the beginning of a function.
104c1213 18900
8e04817f
AC
18901@cindex response time, MIPS debugging
18902To improve response time (especially for embedded applications, where
18903@value{GDBN} may be restricted to a slow serial line for this search)
18904you may want to limit the size of this search, using one of these
18905commands:
104c1213 18906
8e04817f
AC
18907@table @code
18908@cindex @code{heuristic-fence-post} (Alpha, MIPS)
18909@item set heuristic-fence-post @var{limit}
18910Restrict @value{GDBN} to examining at most @var{limit} bytes in its
18911search for the beginning of a function. A value of @var{0} (the
18912default) means there is no limit. However, except for @var{0}, the
18913larger the limit the more bytes @code{heuristic-fence-post} must search
e2f4edfd
EZ
18914and therefore the longer it takes to run. You should only need to use
18915this command when debugging a stripped executable.
104c1213 18916
8e04817f
AC
18917@item show heuristic-fence-post
18918Display the current limit.
18919@end table
104c1213
JM
18920
18921@noindent
8e04817f
AC
18922These commands are available @emph{only} when @value{GDBN} is configured
18923for debugging programs on Alpha or MIPS processors.
104c1213 18924
a64548ea
EZ
18925Several MIPS-specific commands are available when debugging MIPS
18926programs:
18927
18928@table @code
a64548ea
EZ
18929@item set mips abi @var{arg}
18930@kindex set mips abi
18931@cindex set ABI for MIPS
18932Tell @value{GDBN} which MIPS ABI is used by the inferior. Possible
18933values of @var{arg} are:
18934
18935@table @samp
18936@item auto
18937The default ABI associated with the current binary (this is the
18938default).
18939@item o32
18940@item o64
18941@item n32
18942@item n64
18943@item eabi32
18944@item eabi64
18945@item auto
18946@end table
18947
18948@item show mips abi
18949@kindex show mips abi
18950Show the MIPS ABI used by @value{GDBN} to debug the inferior.
18951
18952@item set mipsfpu
18953@itemx show mipsfpu
18954@xref{MIPS Embedded, set mipsfpu}.
18955
18956@item set mips mask-address @var{arg}
18957@kindex set mips mask-address
18958@cindex MIPS addresses, masking
18959This command determines whether the most-significant 32 bits of 64-bit
18960MIPS addresses are masked off. The argument @var{arg} can be
18961@samp{on}, @samp{off}, or @samp{auto}. The latter is the default
18962setting, which lets @value{GDBN} determine the correct value.
18963
18964@item show mips mask-address
18965@kindex show mips mask-address
18966Show whether the upper 32 bits of MIPS addresses are masked off or
18967not.
18968
18969@item set remote-mips64-transfers-32bit-regs
18970@kindex set remote-mips64-transfers-32bit-regs
18971This command controls compatibility with 64-bit MIPS targets that
18972transfer data in 32-bit quantities. If you have an old MIPS 64 target
18973that transfers 32 bits for some registers, like @sc{sr} and @sc{fsr},
18974and 64 bits for other registers, set this option to @samp{on}.
18975
18976@item show remote-mips64-transfers-32bit-regs
18977@kindex show remote-mips64-transfers-32bit-regs
18978Show the current setting of compatibility with older MIPS 64 targets.
18979
18980@item set debug mips
18981@kindex set debug mips
18982This command turns on and off debugging messages for the MIPS-specific
18983target code in @value{GDBN}.
18984
18985@item show debug mips
18986@kindex show debug mips
18987Show the current setting of MIPS debugging messages.
18988@end table
18989
18990
18991@node HPPA
18992@subsection HPPA
18993@cindex HPPA support
18994
d3e8051b 18995When @value{GDBN} is debugging the HP PA architecture, it provides the
a64548ea
EZ
18996following special commands:
18997
18998@table @code
18999@item set debug hppa
19000@kindex set debug hppa
db2e3e2e 19001This command determines whether HPPA architecture-specific debugging
a64548ea
EZ
19002messages are to be displayed.
19003
19004@item show debug hppa
19005Show whether HPPA debugging messages are displayed.
19006
19007@item maint print unwind @var{address}
19008@kindex maint print unwind@r{, HPPA}
19009This command displays the contents of the unwind table entry at the
19010given @var{address}.
19011
19012@end table
19013
104c1213 19014
23d964e7
UW
19015@node SPU
19016@subsection Cell Broadband Engine SPU architecture
19017@cindex Cell Broadband Engine
19018@cindex SPU
19019
19020When @value{GDBN} is debugging the Cell Broadband Engine SPU architecture,
19021it provides the following special commands:
19022
19023@table @code
19024@item info spu event
19025@kindex info spu
19026Display SPU event facility status. Shows current event mask
19027and pending event status.
19028
19029@item info spu signal
19030Display SPU signal notification facility status. Shows pending
19031signal-control word and signal notification mode of both signal
19032notification channels.
19033
19034@item info spu mailbox
19035Display SPU mailbox facility status. Shows all pending entries,
19036in order of processing, in each of the SPU Write Outbound,
19037SPU Write Outbound Interrupt, and SPU Read Inbound mailboxes.
19038
19039@item info spu dma
19040Display MFC DMA status. Shows all pending commands in the MFC
19041DMA queue. For each entry, opcode, tag, class IDs, effective
19042and local store addresses and transfer size are shown.
19043
19044@item info spu proxydma
19045Display MFC Proxy-DMA status. Shows all pending commands in the MFC
19046Proxy-DMA queue. For each entry, opcode, tag, class IDs, effective
19047and local store addresses and transfer size are shown.
19048
19049@end table
19050
3285f3fe
UW
19051When @value{GDBN} is debugging a combined PowerPC/SPU application
19052on the Cell Broadband Engine, it provides in addition the following
19053special commands:
19054
19055@table @code
19056@item set spu stop-on-load @var{arg}
19057@kindex set spu
19058Set whether to stop for new SPE threads. When set to @code{on}, @value{GDBN}
19059will give control to the user when a new SPE thread enters its @code{main}
19060function. The default is @code{off}.
19061
19062@item show spu stop-on-load
19063@kindex show spu
19064Show whether to stop for new SPE threads.
19065
ff1a52c6
UW
19066@item set spu auto-flush-cache @var{arg}
19067Set whether to automatically flush the software-managed cache. When set to
19068@code{on}, @value{GDBN} will automatically cause the SPE software-managed
19069cache to be flushed whenever SPE execution stops. This provides a consistent
19070view of PowerPC memory that is accessed via the cache. If an application
19071does not use the software-managed cache, this option has no effect.
19072
19073@item show spu auto-flush-cache
19074Show whether to automatically flush the software-managed cache.
19075
3285f3fe
UW
19076@end table
19077
4acd40f3
TJB
19078@node PowerPC
19079@subsection PowerPC
19080@cindex PowerPC architecture
19081
19082When @value{GDBN} is debugging the PowerPC architecture, it provides a set of
19083pseudo-registers to enable inspection of 128-bit wide Decimal Floating Point
19084numbers stored in the floating point registers. These values must be stored
19085in two consecutive registers, always starting at an even register like
19086@code{f0} or @code{f2}.
19087
19088The pseudo-registers go from @code{$dl0} through @code{$dl15}, and are formed
19089by joining the even/odd register pairs @code{f0} and @code{f1} for @code{$dl0},
19090@code{f2} and @code{f3} for @code{$dl1} and so on.
19091
aeac0ff9 19092For POWER7 processors, @value{GDBN} provides a set of pseudo-registers, the 64-bit
677c5bb1
LM
19093wide Extended Floating Point Registers (@samp{f32} through @samp{f63}).
19094
23d964e7 19095
8e04817f
AC
19096@node Controlling GDB
19097@chapter Controlling @value{GDBN}
19098
19099You can alter the way @value{GDBN} interacts with you by using the
19100@code{set} command. For commands controlling how @value{GDBN} displays
79a6e687 19101data, see @ref{Print Settings, ,Print Settings}. Other settings are
8e04817f
AC
19102described here.
19103
19104@menu
19105* Prompt:: Prompt
19106* Editing:: Command editing
d620b259 19107* Command History:: Command history
8e04817f
AC
19108* Screen Size:: Screen size
19109* Numbers:: Numbers
1e698235 19110* ABI:: Configuring the current ABI
8e04817f
AC
19111* Messages/Warnings:: Optional warnings and messages
19112* Debugging Output:: Optional messages about internal happenings
14fb1bac 19113* Other Misc Settings:: Other Miscellaneous Settings
8e04817f
AC
19114@end menu
19115
19116@node Prompt
19117@section Prompt
104c1213 19118
8e04817f 19119@cindex prompt
104c1213 19120
8e04817f
AC
19121@value{GDBN} indicates its readiness to read a command by printing a string
19122called the @dfn{prompt}. This string is normally @samp{(@value{GDBP})}. You
19123can change the prompt string with the @code{set prompt} command. For
19124instance, when debugging @value{GDBN} with @value{GDBN}, it is useful to change
19125the prompt in one of the @value{GDBN} sessions so that you can always tell
19126which one you are talking to.
104c1213 19127
8e04817f
AC
19128@emph{Note:} @code{set prompt} does not add a space for you after the
19129prompt you set. This allows you to set a prompt which ends in a space
19130or a prompt that does not.
104c1213 19131
8e04817f
AC
19132@table @code
19133@kindex set prompt
19134@item set prompt @var{newprompt}
19135Directs @value{GDBN} to use @var{newprompt} as its prompt string henceforth.
104c1213 19136
8e04817f
AC
19137@kindex show prompt
19138@item show prompt
19139Prints a line of the form: @samp{Gdb's prompt is: @var{your-prompt}}
104c1213
JM
19140@end table
19141
8e04817f 19142@node Editing
79a6e687 19143@section Command Editing
8e04817f
AC
19144@cindex readline
19145@cindex command line editing
104c1213 19146
703663ab 19147@value{GDBN} reads its input commands via the @dfn{Readline} interface. This
8e04817f
AC
19148@sc{gnu} library provides consistent behavior for programs which provide a
19149command line interface to the user. Advantages are @sc{gnu} Emacs-style
19150or @dfn{vi}-style inline editing of commands, @code{csh}-like history
19151substitution, and a storage and recall of command history across
19152debugging sessions.
104c1213 19153
8e04817f
AC
19154You may control the behavior of command line editing in @value{GDBN} with the
19155command @code{set}.
104c1213 19156
8e04817f
AC
19157@table @code
19158@kindex set editing
19159@cindex editing
19160@item set editing
19161@itemx set editing on
19162Enable command line editing (enabled by default).
104c1213 19163
8e04817f
AC
19164@item set editing off
19165Disable command line editing.
104c1213 19166
8e04817f
AC
19167@kindex show editing
19168@item show editing
19169Show whether command line editing is enabled.
104c1213
JM
19170@end table
19171
703663ab
EZ
19172@xref{Command Line Editing}, for more details about the Readline
19173interface. Users unfamiliar with @sc{gnu} Emacs or @code{vi} are
19174encouraged to read that chapter.
19175
d620b259 19176@node Command History
79a6e687 19177@section Command History
703663ab 19178@cindex command history
8e04817f
AC
19179
19180@value{GDBN} can keep track of the commands you type during your
19181debugging sessions, so that you can be certain of precisely what
19182happened. Use these commands to manage the @value{GDBN} command
19183history facility.
104c1213 19184
703663ab
EZ
19185@value{GDBN} uses the @sc{gnu} History library, a part of the Readline
19186package, to provide the history facility. @xref{Using History
19187Interactively}, for the detailed description of the History library.
19188
d620b259 19189To issue a command to @value{GDBN} without affecting certain aspects of
9e6c4bd5
NR
19190the state which is seen by users, prefix it with @samp{server }
19191(@pxref{Server Prefix}). This
d620b259
NR
19192means that this command will not affect the command history, nor will it
19193affect @value{GDBN}'s notion of which command to repeat if @key{RET} is
19194pressed on a line by itself.
19195
19196@cindex @code{server}, command prefix
19197The server prefix does not affect the recording of values into the value
19198history; to print a value without recording it into the value history,
19199use the @code{output} command instead of the @code{print} command.
19200
703663ab
EZ
19201Here is the description of @value{GDBN} commands related to command
19202history.
19203
104c1213 19204@table @code
8e04817f
AC
19205@cindex history substitution
19206@cindex history file
19207@kindex set history filename
4644b6e3 19208@cindex @env{GDBHISTFILE}, environment variable
8e04817f
AC
19209@item set history filename @var{fname}
19210Set the name of the @value{GDBN} command history file to @var{fname}.
19211This is the file where @value{GDBN} reads an initial command history
19212list, and where it writes the command history from this session when it
19213exits. You can access this list through history expansion or through
19214the history command editing characters listed below. This file defaults
19215to the value of the environment variable @code{GDBHISTFILE}, or to
19216@file{./.gdb_history} (@file{./_gdb_history} on MS-DOS) if this variable
19217is not set.
104c1213 19218
9c16f35a
EZ
19219@cindex save command history
19220@kindex set history save
8e04817f
AC
19221@item set history save
19222@itemx set history save on
19223Record command history in a file, whose name may be specified with the
19224@code{set history filename} command. By default, this option is disabled.
104c1213 19225
8e04817f
AC
19226@item set history save off
19227Stop recording command history in a file.
104c1213 19228
8e04817f 19229@cindex history size
9c16f35a 19230@kindex set history size
6fc08d32 19231@cindex @env{HISTSIZE}, environment variable
8e04817f
AC
19232@item set history size @var{size}
19233Set the number of commands which @value{GDBN} keeps in its history list.
19234This defaults to the value of the environment variable
19235@code{HISTSIZE}, or to 256 if this variable is not set.
104c1213
JM
19236@end table
19237
8e04817f 19238History expansion assigns special meaning to the character @kbd{!}.
703663ab 19239@xref{Event Designators}, for more details.
8e04817f 19240
703663ab 19241@cindex history expansion, turn on/off
8e04817f
AC
19242Since @kbd{!} is also the logical not operator in C, history expansion
19243is off by default. If you decide to enable history expansion with the
19244@code{set history expansion on} command, you may sometimes need to
19245follow @kbd{!} (when it is used as logical not, in an expression) with
19246a space or a tab to prevent it from being expanded. The readline
19247history facilities do not attempt substitution on the strings
19248@kbd{!=} and @kbd{!(}, even when history expansion is enabled.
19249
19250The commands to control history expansion are:
104c1213
JM
19251
19252@table @code
8e04817f
AC
19253@item set history expansion on
19254@itemx set history expansion
703663ab 19255@kindex set history expansion
8e04817f 19256Enable history expansion. History expansion is off by default.
104c1213 19257
8e04817f
AC
19258@item set history expansion off
19259Disable history expansion.
104c1213 19260
8e04817f
AC
19261@c @group
19262@kindex show history
19263@item show history
19264@itemx show history filename
19265@itemx show history save
19266@itemx show history size
19267@itemx show history expansion
19268These commands display the state of the @value{GDBN} history parameters.
19269@code{show history} by itself displays all four states.
19270@c @end group
19271@end table
19272
19273@table @code
9c16f35a
EZ
19274@kindex show commands
19275@cindex show last commands
19276@cindex display command history
8e04817f
AC
19277@item show commands
19278Display the last ten commands in the command history.
104c1213 19279
8e04817f
AC
19280@item show commands @var{n}
19281Print ten commands centered on command number @var{n}.
19282
19283@item show commands +
19284Print ten commands just after the commands last printed.
104c1213
JM
19285@end table
19286
8e04817f 19287@node Screen Size
79a6e687 19288@section Screen Size
8e04817f
AC
19289@cindex size of screen
19290@cindex pauses in output
104c1213 19291
8e04817f
AC
19292Certain commands to @value{GDBN} may produce large amounts of
19293information output to the screen. To help you read all of it,
19294@value{GDBN} pauses and asks you for input at the end of each page of
19295output. Type @key{RET} when you want to continue the output, or @kbd{q}
19296to discard the remaining output. Also, the screen width setting
19297determines when to wrap lines of output. Depending on what is being
19298printed, @value{GDBN} tries to break the line at a readable place,
19299rather than simply letting it overflow onto the following line.
19300
19301Normally @value{GDBN} knows the size of the screen from the terminal
19302driver software. For example, on Unix @value{GDBN} uses the termcap data base
19303together with the value of the @code{TERM} environment variable and the
19304@code{stty rows} and @code{stty cols} settings. If this is not correct,
19305you can override it with the @code{set height} and @code{set
19306width} commands:
19307
19308@table @code
19309@kindex set height
19310@kindex set width
19311@kindex show width
19312@kindex show height
19313@item set height @var{lpp}
19314@itemx show height
19315@itemx set width @var{cpl}
19316@itemx show width
19317These @code{set} commands specify a screen height of @var{lpp} lines and
19318a screen width of @var{cpl} characters. The associated @code{show}
19319commands display the current settings.
104c1213 19320
8e04817f
AC
19321If you specify a height of zero lines, @value{GDBN} does not pause during
19322output no matter how long the output is. This is useful if output is to a
19323file or to an editor buffer.
104c1213 19324
8e04817f
AC
19325Likewise, you can specify @samp{set width 0} to prevent @value{GDBN}
19326from wrapping its output.
9c16f35a
EZ
19327
19328@item set pagination on
19329@itemx set pagination off
19330@kindex set pagination
19331Turn the output pagination on or off; the default is on. Turning
7c953934
TT
19332pagination off is the alternative to @code{set height 0}. Note that
19333running @value{GDBN} with the @option{--batch} option (@pxref{Mode
19334Options, -batch}) also automatically disables pagination.
9c16f35a
EZ
19335
19336@item show pagination
19337@kindex show pagination
19338Show the current pagination mode.
104c1213
JM
19339@end table
19340
8e04817f
AC
19341@node Numbers
19342@section Numbers
19343@cindex number representation
19344@cindex entering numbers
104c1213 19345
8e04817f
AC
19346You can always enter numbers in octal, decimal, or hexadecimal in
19347@value{GDBN} by the usual conventions: octal numbers begin with
19348@samp{0}, decimal numbers end with @samp{.}, and hexadecimal numbers
eb2dae08
EZ
19349begin with @samp{0x}. Numbers that neither begin with @samp{0} or
19350@samp{0x}, nor end with a @samp{.} are, by default, entered in base
1935110; likewise, the default display for numbers---when no particular
19352format is specified---is base 10. You can change the default base for
19353both input and output with the commands described below.
104c1213 19354
8e04817f
AC
19355@table @code
19356@kindex set input-radix
19357@item set input-radix @var{base}
19358Set the default base for numeric input. Supported choices
19359for @var{base} are decimal 8, 10, or 16. @var{base} must itself be
eb2dae08 19360specified either unambiguously or using the current input radix; for
8e04817f 19361example, any of
104c1213 19362
8e04817f 19363@smallexample
9c16f35a
EZ
19364set input-radix 012
19365set input-radix 10.
19366set input-radix 0xa
8e04817f 19367@end smallexample
104c1213 19368
8e04817f 19369@noindent
9c16f35a 19370sets the input base to decimal. On the other hand, @samp{set input-radix 10}
eb2dae08
EZ
19371leaves the input radix unchanged, no matter what it was, since
19372@samp{10}, being without any leading or trailing signs of its base, is
19373interpreted in the current radix. Thus, if the current radix is 16,
19374@samp{10} is interpreted in hex, i.e.@: as 16 decimal, which doesn't
19375change the radix.
104c1213 19376
8e04817f
AC
19377@kindex set output-radix
19378@item set output-radix @var{base}
19379Set the default base for numeric display. Supported choices
19380for @var{base} are decimal 8, 10, or 16. @var{base} must itself be
eb2dae08 19381specified either unambiguously or using the current input radix.
104c1213 19382
8e04817f
AC
19383@kindex show input-radix
19384@item show input-radix
19385Display the current default base for numeric input.
104c1213 19386
8e04817f
AC
19387@kindex show output-radix
19388@item show output-radix
19389Display the current default base for numeric display.
9c16f35a
EZ
19390
19391@item set radix @r{[}@var{base}@r{]}
19392@itemx show radix
19393@kindex set radix
19394@kindex show radix
19395These commands set and show the default base for both input and output
19396of numbers. @code{set radix} sets the radix of input and output to
19397the same base; without an argument, it resets the radix back to its
19398default value of 10.
19399
8e04817f 19400@end table
104c1213 19401
1e698235 19402@node ABI
79a6e687 19403@section Configuring the Current ABI
1e698235
DJ
19404
19405@value{GDBN} can determine the @dfn{ABI} (Application Binary Interface) of your
19406application automatically. However, sometimes you need to override its
19407conclusions. Use these commands to manage @value{GDBN}'s view of the
19408current ABI.
19409
98b45e30
DJ
19410@cindex OS ABI
19411@kindex set osabi
b4e9345d 19412@kindex show osabi
98b45e30
DJ
19413
19414One @value{GDBN} configuration can debug binaries for multiple operating
b383017d 19415system targets, either via remote debugging or native emulation.
98b45e30
DJ
19416@value{GDBN} will autodetect the @dfn{OS ABI} (Operating System ABI) in use,
19417but you can override its conclusion using the @code{set osabi} command.
19418One example where this is useful is in debugging of binaries which use
19419an alternate C library (e.g.@: @sc{uClibc} for @sc{gnu}/Linux) which does
19420not have the same identifying marks that the standard C library for your
19421platform provides.
19422
19423@table @code
19424@item show osabi
19425Show the OS ABI currently in use.
19426
19427@item set osabi
19428With no argument, show the list of registered available OS ABI's.
19429
19430@item set osabi @var{abi}
19431Set the current OS ABI to @var{abi}.
19432@end table
19433
1e698235 19434@cindex float promotion
1e698235
DJ
19435
19436Generally, the way that an argument of type @code{float} is passed to a
19437function depends on whether the function is prototyped. For a prototyped
19438(i.e.@: ANSI/ISO style) function, @code{float} arguments are passed unchanged,
19439according to the architecture's convention for @code{float}. For unprototyped
19440(i.e.@: K&R style) functions, @code{float} arguments are first promoted to type
19441@code{double} and then passed.
19442
19443Unfortunately, some forms of debug information do not reliably indicate whether
19444a function is prototyped. If @value{GDBN} calls a function that is not marked
19445as prototyped, it consults @kbd{set coerce-float-to-double}.
19446
19447@table @code
a8f24a35 19448@kindex set coerce-float-to-double
1e698235
DJ
19449@item set coerce-float-to-double
19450@itemx set coerce-float-to-double on
19451Arguments of type @code{float} will be promoted to @code{double} when passed
19452to an unprototyped function. This is the default setting.
19453
19454@item set coerce-float-to-double off
19455Arguments of type @code{float} will be passed directly to unprototyped
19456functions.
9c16f35a
EZ
19457
19458@kindex show coerce-float-to-double
19459@item show coerce-float-to-double
19460Show the current setting of promoting @code{float} to @code{double}.
1e698235
DJ
19461@end table
19462
f1212245
DJ
19463@kindex set cp-abi
19464@kindex show cp-abi
19465@value{GDBN} needs to know the ABI used for your program's C@t{++}
19466objects. The correct C@t{++} ABI depends on which C@t{++} compiler was
19467used to build your application. @value{GDBN} only fully supports
19468programs with a single C@t{++} ABI; if your program contains code using
19469multiple C@t{++} ABI's or if @value{GDBN} can not identify your
19470program's ABI correctly, you can tell @value{GDBN} which ABI to use.
19471Currently supported ABI's include ``gnu-v2'', for @code{g++} versions
19472before 3.0, ``gnu-v3'', for @code{g++} versions 3.0 and later, and
19473``hpaCC'' for the HP ANSI C@t{++} compiler. Other C@t{++} compilers may
19474use the ``gnu-v2'' or ``gnu-v3'' ABI's as well. The default setting is
19475``auto''.
19476
19477@table @code
19478@item show cp-abi
19479Show the C@t{++} ABI currently in use.
19480
19481@item set cp-abi
19482With no argument, show the list of supported C@t{++} ABI's.
19483
19484@item set cp-abi @var{abi}
19485@itemx set cp-abi auto
19486Set the current C@t{++} ABI to @var{abi}, or return to automatic detection.
19487@end table
19488
8e04817f 19489@node Messages/Warnings
79a6e687 19490@section Optional Warnings and Messages
104c1213 19491
9c16f35a
EZ
19492@cindex verbose operation
19493@cindex optional warnings
8e04817f
AC
19494By default, @value{GDBN} is silent about its inner workings. If you are
19495running on a slow machine, you may want to use the @code{set verbose}
19496command. This makes @value{GDBN} tell you when it does a lengthy
19497internal operation, so you will not think it has crashed.
104c1213 19498
8e04817f
AC
19499Currently, the messages controlled by @code{set verbose} are those
19500which announce that the symbol table for a source file is being read;
79a6e687 19501see @code{symbol-file} in @ref{Files, ,Commands to Specify Files}.
104c1213 19502
8e04817f
AC
19503@table @code
19504@kindex set verbose
19505@item set verbose on
19506Enables @value{GDBN} output of certain informational messages.
104c1213 19507
8e04817f
AC
19508@item set verbose off
19509Disables @value{GDBN} output of certain informational messages.
104c1213 19510
8e04817f
AC
19511@kindex show verbose
19512@item show verbose
19513Displays whether @code{set verbose} is on or off.
19514@end table
104c1213 19515
8e04817f
AC
19516By default, if @value{GDBN} encounters bugs in the symbol table of an
19517object file, it is silent; but if you are debugging a compiler, you may
79a6e687
BW
19518find this information useful (@pxref{Symbol Errors, ,Errors Reading
19519Symbol Files}).
104c1213 19520
8e04817f 19521@table @code
104c1213 19522
8e04817f
AC
19523@kindex set complaints
19524@item set complaints @var{limit}
19525Permits @value{GDBN} to output @var{limit} complaints about each type of
19526unusual symbols before becoming silent about the problem. Set
19527@var{limit} to zero to suppress all complaints; set it to a large number
19528to prevent complaints from being suppressed.
104c1213 19529
8e04817f
AC
19530@kindex show complaints
19531@item show complaints
19532Displays how many symbol complaints @value{GDBN} is permitted to produce.
104c1213 19533
8e04817f 19534@end table
104c1213 19535
d837706a 19536@anchor{confirmation requests}
8e04817f
AC
19537By default, @value{GDBN} is cautious, and asks what sometimes seems to be a
19538lot of stupid questions to confirm certain commands. For example, if
19539you try to run a program which is already running:
104c1213 19540
474c8240 19541@smallexample
8e04817f
AC
19542(@value{GDBP}) run
19543The program being debugged has been started already.
19544Start it from the beginning? (y or n)
474c8240 19545@end smallexample
104c1213 19546
8e04817f
AC
19547If you are willing to unflinchingly face the consequences of your own
19548commands, you can disable this ``feature'':
104c1213 19549
8e04817f 19550@table @code
104c1213 19551
8e04817f
AC
19552@kindex set confirm
19553@cindex flinching
19554@cindex confirmation
19555@cindex stupid questions
19556@item set confirm off
7c953934
TT
19557Disables confirmation requests. Note that running @value{GDBN} with
19558the @option{--batch} option (@pxref{Mode Options, -batch}) also
19559automatically disables confirmation requests.
104c1213 19560
8e04817f
AC
19561@item set confirm on
19562Enables confirmation requests (the default).
104c1213 19563
8e04817f
AC
19564@kindex show confirm
19565@item show confirm
19566Displays state of confirmation requests.
19567
19568@end table
104c1213 19569
16026cd7
AS
19570@cindex command tracing
19571If you need to debug user-defined commands or sourced files you may find it
19572useful to enable @dfn{command tracing}. In this mode each command will be
19573printed as it is executed, prefixed with one or more @samp{+} symbols, the
19574quantity denoting the call depth of each command.
19575
19576@table @code
19577@kindex set trace-commands
19578@cindex command scripts, debugging
19579@item set trace-commands on
19580Enable command tracing.
19581@item set trace-commands off
19582Disable command tracing.
19583@item show trace-commands
19584Display the current state of command tracing.
19585@end table
19586
8e04817f 19587@node Debugging Output
79a6e687 19588@section Optional Messages about Internal Happenings
4644b6e3
EZ
19589@cindex optional debugging messages
19590
da316a69
EZ
19591@value{GDBN} has commands that enable optional debugging messages from
19592various @value{GDBN} subsystems; normally these commands are of
19593interest to @value{GDBN} maintainers, or when reporting a bug. This
19594section documents those commands.
19595
104c1213 19596@table @code
a8f24a35
EZ
19597@kindex set exec-done-display
19598@item set exec-done-display
19599Turns on or off the notification of asynchronous commands'
19600completion. When on, @value{GDBN} will print a message when an
19601asynchronous command finishes its execution. The default is off.
19602@kindex show exec-done-display
19603@item show exec-done-display
19604Displays the current setting of asynchronous command completion
19605notification.
4644b6e3
EZ
19606@kindex set debug
19607@cindex gdbarch debugging info
a8f24a35 19608@cindex architecture debugging info
8e04817f 19609@item set debug arch
a8f24a35 19610Turns on or off display of gdbarch debugging info. The default is off
4644b6e3 19611@kindex show debug
8e04817f
AC
19612@item show debug arch
19613Displays the current state of displaying gdbarch debugging info.
721c2651
EZ
19614@item set debug aix-thread
19615@cindex AIX threads
19616Display debugging messages about inner workings of the AIX thread
19617module.
19618@item show debug aix-thread
19619Show the current state of AIX thread debugging info display.
d97bc12b
DE
19620@item set debug dwarf2-die
19621@cindex DWARF2 DIEs
19622Dump DWARF2 DIEs after they are read in.
19623The value is the number of nesting levels to print.
19624A value of zero turns off the display.
19625@item show debug dwarf2-die
19626Show the current state of DWARF2 DIE debugging.
237fc4c9
PA
19627@item set debug displaced
19628@cindex displaced stepping debugging info
19629Turns on or off display of @value{GDBN} debugging info for the
19630displaced stepping support. The default is off.
19631@item show debug displaced
19632Displays the current state of displaying @value{GDBN} debugging info
19633related to displaced stepping.
8e04817f 19634@item set debug event
4644b6e3 19635@cindex event debugging info
a8f24a35 19636Turns on or off display of @value{GDBN} event debugging info. The
8e04817f 19637default is off.
8e04817f
AC
19638@item show debug event
19639Displays the current state of displaying @value{GDBN} event debugging
19640info.
8e04817f 19641@item set debug expression
4644b6e3 19642@cindex expression debugging info
721c2651
EZ
19643Turns on or off display of debugging info about @value{GDBN}
19644expression parsing. The default is off.
8e04817f 19645@item show debug expression
721c2651
EZ
19646Displays the current state of displaying debugging info about
19647@value{GDBN} expression parsing.
7453dc06 19648@item set debug frame
4644b6e3 19649@cindex frame debugging info
7453dc06
AC
19650Turns on or off display of @value{GDBN} frame debugging info. The
19651default is off.
7453dc06
AC
19652@item show debug frame
19653Displays the current state of displaying @value{GDBN} frame debugging
19654info.
cbe54154
PA
19655@item set debug gnu-nat
19656@cindex @sc{gnu}/Hurd debug messages
19657Turns on or off debugging messages from the @sc{gnu}/Hurd debug support.
19658@item show debug gnu-nat
19659Show the current state of @sc{gnu}/Hurd debugging messages.
30e91e0b
RC
19660@item set debug infrun
19661@cindex inferior debugging info
19662Turns on or off display of @value{GDBN} debugging info for running the inferior.
19663The default is off. @file{infrun.c} contains GDB's runtime state machine used
19664for implementing operations such as single-stepping the inferior.
19665@item show debug infrun
19666Displays the current state of @value{GDBN} inferior debugging.
da316a69
EZ
19667@item set debug lin-lwp
19668@cindex @sc{gnu}/Linux LWP debug messages
19669@cindex Linux lightweight processes
721c2651 19670Turns on or off debugging messages from the Linux LWP debug support.
da316a69
EZ
19671@item show debug lin-lwp
19672Show the current state of Linux LWP debugging messages.
b84876c2
PA
19673@item set debug lin-lwp-async
19674@cindex @sc{gnu}/Linux LWP async debug messages
19675@cindex Linux lightweight processes
19676Turns on or off debugging messages from the Linux LWP async debug support.
19677@item show debug lin-lwp-async
19678Show the current state of Linux LWP async debugging messages.
2b4855ab 19679@item set debug observer
4644b6e3 19680@cindex observer debugging info
2b4855ab
AC
19681Turns on or off display of @value{GDBN} observer debugging. This
19682includes info such as the notification of observable events.
2b4855ab
AC
19683@item show debug observer
19684Displays the current state of observer debugging.
8e04817f 19685@item set debug overload
4644b6e3 19686@cindex C@t{++} overload debugging info
8e04817f 19687Turns on or off display of @value{GDBN} C@t{++} overload debugging
359df76b 19688info. This includes info such as ranking of functions, etc. The default
8e04817f 19689is off.
8e04817f
AC
19690@item show debug overload
19691Displays the current state of displaying @value{GDBN} C@t{++} overload
19692debugging info.
92981e24
TT
19693@cindex expression parser, debugging info
19694@cindex debug expression parser
19695@item set debug parser
19696Turns on or off the display of expression parser debugging output.
19697Internally, this sets the @code{yydebug} variable in the expression
19698parser. @xref{Tracing, , Tracing Your Parser, bison, Bison}, for
19699details. The default is off.
19700@item show debug parser
19701Show the current state of expression parser debugging.
8e04817f
AC
19702@cindex packets, reporting on stdout
19703@cindex serial connections, debugging
605a56cb
DJ
19704@cindex debug remote protocol
19705@cindex remote protocol debugging
19706@cindex display remote packets
8e04817f
AC
19707@item set debug remote
19708Turns on or off display of reports on all packets sent back and forth across
19709the serial line to the remote machine. The info is printed on the
19710@value{GDBN} standard output stream. The default is off.
8e04817f
AC
19711@item show debug remote
19712Displays the state of display of remote packets.
8e04817f
AC
19713@item set debug serial
19714Turns on or off display of @value{GDBN} serial debugging info. The
19715default is off.
8e04817f
AC
19716@item show debug serial
19717Displays the current state of displaying @value{GDBN} serial debugging
19718info.
c45da7e6
EZ
19719@item set debug solib-frv
19720@cindex FR-V shared-library debugging
19721Turns on or off debugging messages for FR-V shared-library code.
19722@item show debug solib-frv
19723Display the current state of FR-V shared-library code debugging
19724messages.
8e04817f 19725@item set debug target
4644b6e3 19726@cindex target debugging info
8e04817f
AC
19727Turns on or off display of @value{GDBN} target debugging info. This info
19728includes what is going on at the target level of GDB, as it happens. The
701b08bb
DJ
19729default is 0. Set it to 1 to track events, and to 2 to also track the
19730value of large memory transfers. Changes to this flag do not take effect
19731until the next time you connect to a target or use the @code{run} command.
8e04817f
AC
19732@item show debug target
19733Displays the current state of displaying @value{GDBN} target debugging
19734info.
75feb17d
DJ
19735@item set debug timestamp
19736@cindex timestampping debugging info
19737Turns on or off display of timestamps with @value{GDBN} debugging info.
19738When enabled, seconds and microseconds are displayed before each debugging
19739message.
19740@item show debug timestamp
19741Displays the current state of displaying timestamps with @value{GDBN}
19742debugging info.
c45da7e6 19743@item set debugvarobj
4644b6e3 19744@cindex variable object debugging info
8e04817f
AC
19745Turns on or off display of @value{GDBN} variable object debugging
19746info. The default is off.
c45da7e6 19747@item show debugvarobj
8e04817f
AC
19748Displays the current state of displaying @value{GDBN} variable object
19749debugging info.
e776119f
DJ
19750@item set debug xml
19751@cindex XML parser debugging
19752Turns on or off debugging messages for built-in XML parsers.
19753@item show debug xml
19754Displays the current state of XML debugging messages.
8e04817f 19755@end table
104c1213 19756
14fb1bac
JB
19757@node Other Misc Settings
19758@section Other Miscellaneous Settings
19759@cindex miscellaneous settings
19760
19761@table @code
19762@kindex set interactive-mode
19763@item set interactive-mode
19764If @code{on}, forces @value{GDBN} to operate interactively.
19765If @code{off}, forces @value{GDBN} to operate non-interactively,
19766If @code{auto} (the default), @value{GDBN} guesses which mode to use,
19767based on whether the debugger was started in a terminal or not.
19768
19769In the vast majority of cases, the debugger should be able to guess
19770correctly which mode should be used. But this setting can be useful
19771in certain specific cases, such as running a MinGW @value{GDBN}
19772inside a cygwin window.
19773
19774@kindex show interactive-mode
19775@item show interactive-mode
19776Displays whether the debugger is operating in interactive mode or not.
19777@end table
19778
d57a3c85
TJB
19779@node Extending GDB
19780@chapter Extending @value{GDBN}
19781@cindex extending GDB
19782
19783@value{GDBN} provides two mechanisms for extension. The first is based
19784on composition of @value{GDBN} commands, and the second is based on the
19785Python scripting language.
19786
95433b34
JB
19787To facilitate the use of these extensions, @value{GDBN} is capable
19788of evaluating the contents of a file. When doing so, @value{GDBN}
19789can recognize which scripting language is being used by looking at
19790the filename extension. Files with an unrecognized filename extension
19791are always treated as a @value{GDBN} Command Files.
19792@xref{Command Files,, Command files}.
19793
19794You can control how @value{GDBN} evaluates these files with the following
19795setting:
19796
19797@table @code
19798@kindex set script-extension
19799@kindex show script-extension
19800@item set script-extension off
19801All scripts are always evaluated as @value{GDBN} Command Files.
19802
19803@item set script-extension soft
19804The debugger determines the scripting language based on filename
19805extension. If this scripting language is supported, @value{GDBN}
19806evaluates the script using that language. Otherwise, it evaluates
19807the file as a @value{GDBN} Command File.
19808
19809@item set script-extension strict
19810The debugger determines the scripting language based on filename
19811extension, and evaluates the script using that language. If the
19812language is not supported, then the evaluation fails.
19813
19814@item show script-extension
19815Display the current value of the @code{script-extension} option.
19816
19817@end table
19818
d57a3c85
TJB
19819@menu
19820* Sequences:: Canned Sequences of Commands
19821* Python:: Scripting @value{GDBN} using Python
19822@end menu
19823
8e04817f 19824@node Sequences
d57a3c85 19825@section Canned Sequences of Commands
104c1213 19826
8e04817f 19827Aside from breakpoint commands (@pxref{Break Commands, ,Breakpoint
79a6e687 19828Command Lists}), @value{GDBN} provides two ways to store sequences of
8e04817f
AC
19829commands for execution as a unit: user-defined commands and command
19830files.
104c1213 19831
8e04817f 19832@menu
fcc73fe3
EZ
19833* Define:: How to define your own commands
19834* Hooks:: Hooks for user-defined commands
19835* Command Files:: How to write scripts of commands to be stored in a file
19836* Output:: Commands for controlled output
8e04817f 19837@end menu
104c1213 19838
8e04817f 19839@node Define
d57a3c85 19840@subsection User-defined Commands
104c1213 19841
8e04817f 19842@cindex user-defined command
fcc73fe3 19843@cindex arguments, to user-defined commands
8e04817f
AC
19844A @dfn{user-defined command} is a sequence of @value{GDBN} commands to
19845which you assign a new name as a command. This is done with the
19846@code{define} command. User commands may accept up to 10 arguments
19847separated by whitespace. Arguments are accessed within the user command
c03c782f 19848via @code{$arg0@dots{}$arg9}. A trivial example:
104c1213 19849
8e04817f
AC
19850@smallexample
19851define adder
19852 print $arg0 + $arg1 + $arg2
c03c782f 19853end
8e04817f 19854@end smallexample
104c1213
JM
19855
19856@noindent
8e04817f 19857To execute the command use:
104c1213 19858
8e04817f
AC
19859@smallexample
19860adder 1 2 3
19861@end smallexample
104c1213 19862
8e04817f
AC
19863@noindent
19864This defines the command @code{adder}, which prints the sum of
19865its three arguments. Note the arguments are text substitutions, so they may
19866reference variables, use complex expressions, or even perform inferior
19867functions calls.
104c1213 19868
fcc73fe3
EZ
19869@cindex argument count in user-defined commands
19870@cindex how many arguments (user-defined commands)
c03c782f
AS
19871In addition, @code{$argc} may be used to find out how many arguments have
19872been passed. This expands to a number in the range 0@dots{}10.
19873
19874@smallexample
19875define adder
19876 if $argc == 2
19877 print $arg0 + $arg1
19878 end
19879 if $argc == 3
19880 print $arg0 + $arg1 + $arg2
19881 end
19882end
19883@end smallexample
19884
104c1213 19885@table @code
104c1213 19886
8e04817f
AC
19887@kindex define
19888@item define @var{commandname}
19889Define a command named @var{commandname}. If there is already a command
19890by that name, you are asked to confirm that you want to redefine it.
adb483fe
DJ
19891@var{commandname} may be a bare command name consisting of letters,
19892numbers, dashes, and underscores. It may also start with any predefined
19893prefix command. For example, @samp{define target my-target} creates
19894a user-defined @samp{target my-target} command.
104c1213 19895
8e04817f
AC
19896The definition of the command is made up of other @value{GDBN} command lines,
19897which are given following the @code{define} command. The end of these
19898commands is marked by a line containing @code{end}.
104c1213 19899
8e04817f 19900@kindex document
ca91424e 19901@kindex end@r{ (user-defined commands)}
8e04817f
AC
19902@item document @var{commandname}
19903Document the user-defined command @var{commandname}, so that it can be
19904accessed by @code{help}. The command @var{commandname} must already be
19905defined. This command reads lines of documentation just as @code{define}
19906reads the lines of the command definition, ending with @code{end}.
19907After the @code{document} command is finished, @code{help} on command
19908@var{commandname} displays the documentation you have written.
104c1213 19909
8e04817f
AC
19910You may use the @code{document} command again to change the
19911documentation of a command. Redefining the command with @code{define}
19912does not change the documentation.
104c1213 19913
c45da7e6
EZ
19914@kindex dont-repeat
19915@cindex don't repeat command
19916@item dont-repeat
19917Used inside a user-defined command, this tells @value{GDBN} that this
19918command should not be repeated when the user hits @key{RET}
19919(@pxref{Command Syntax, repeat last command}).
19920
8e04817f
AC
19921@kindex help user-defined
19922@item help user-defined
19923List all user-defined commands, with the first line of the documentation
19924(if any) for each.
104c1213 19925
8e04817f
AC
19926@kindex show user
19927@item show user
19928@itemx show user @var{commandname}
19929Display the @value{GDBN} commands used to define @var{commandname} (but
19930not its documentation). If no @var{commandname} is given, display the
19931definitions for all user-defined commands.
104c1213 19932
fcc73fe3 19933@cindex infinite recursion in user-defined commands
20f01a46
DH
19934@kindex show max-user-call-depth
19935@kindex set max-user-call-depth
19936@item show max-user-call-depth
5ca0cb28
DH
19937@itemx set max-user-call-depth
19938The value of @code{max-user-call-depth} controls how many recursion
3f94c067 19939levels are allowed in user-defined commands before @value{GDBN} suspects an
5ca0cb28 19940infinite recursion and aborts the command.
104c1213
JM
19941@end table
19942
fcc73fe3
EZ
19943In addition to the above commands, user-defined commands frequently
19944use control flow commands, described in @ref{Command Files}.
19945
8e04817f
AC
19946When user-defined commands are executed, the
19947commands of the definition are not printed. An error in any command
19948stops execution of the user-defined command.
104c1213 19949
8e04817f
AC
19950If used interactively, commands that would ask for confirmation proceed
19951without asking when used inside a user-defined command. Many @value{GDBN}
19952commands that normally print messages to say what they are doing omit the
19953messages when used in a user-defined command.
104c1213 19954
8e04817f 19955@node Hooks
d57a3c85 19956@subsection User-defined Command Hooks
8e04817f
AC
19957@cindex command hooks
19958@cindex hooks, for commands
19959@cindex hooks, pre-command
104c1213 19960
8e04817f 19961@kindex hook
8e04817f
AC
19962You may define @dfn{hooks}, which are a special kind of user-defined
19963command. Whenever you run the command @samp{foo}, if the user-defined
19964command @samp{hook-foo} exists, it is executed (with no arguments)
19965before that command.
104c1213 19966
8e04817f
AC
19967@cindex hooks, post-command
19968@kindex hookpost
8e04817f
AC
19969A hook may also be defined which is run after the command you executed.
19970Whenever you run the command @samp{foo}, if the user-defined command
19971@samp{hookpost-foo} exists, it is executed (with no arguments) after
19972that command. Post-execution hooks may exist simultaneously with
19973pre-execution hooks, for the same command.
104c1213 19974
8e04817f 19975It is valid for a hook to call the command which it hooks. If this
9f1c6395 19976occurs, the hook is not re-executed, thereby avoiding infinite recursion.
104c1213 19977
8e04817f
AC
19978@c It would be nice if hookpost could be passed a parameter indicating
19979@c if the command it hooks executed properly or not. FIXME!
104c1213 19980
8e04817f
AC
19981@kindex stop@r{, a pseudo-command}
19982In addition, a pseudo-command, @samp{stop} exists. Defining
19983(@samp{hook-stop}) makes the associated commands execute every time
19984execution stops in your program: before breakpoint commands are run,
19985displays are printed, or the stack frame is printed.
104c1213 19986
8e04817f
AC
19987For example, to ignore @code{SIGALRM} signals while
19988single-stepping, but treat them normally during normal execution,
19989you could define:
104c1213 19990
474c8240 19991@smallexample
8e04817f
AC
19992define hook-stop
19993handle SIGALRM nopass
19994end
104c1213 19995
8e04817f
AC
19996define hook-run
19997handle SIGALRM pass
19998end
104c1213 19999
8e04817f 20000define hook-continue
d3e8051b 20001handle SIGALRM pass
8e04817f 20002end
474c8240 20003@end smallexample
104c1213 20004
d3e8051b 20005As a further example, to hook at the beginning and end of the @code{echo}
b383017d 20006command, and to add extra text to the beginning and end of the message,
8e04817f 20007you could define:
104c1213 20008
474c8240 20009@smallexample
8e04817f
AC
20010define hook-echo
20011echo <<<---
20012end
104c1213 20013
8e04817f
AC
20014define hookpost-echo
20015echo --->>>\n
20016end
104c1213 20017
8e04817f
AC
20018(@value{GDBP}) echo Hello World
20019<<<---Hello World--->>>
20020(@value{GDBP})
104c1213 20021
474c8240 20022@end smallexample
104c1213 20023
8e04817f
AC
20024You can define a hook for any single-word command in @value{GDBN}, but
20025not for command aliases; you should define a hook for the basic command
c1468174 20026name, e.g.@: @code{backtrace} rather than @code{bt}.
8e04817f
AC
20027@c FIXME! So how does Joe User discover whether a command is an alias
20028@c or not?
adb483fe
DJ
20029You can hook a multi-word command by adding @code{hook-} or
20030@code{hookpost-} to the last word of the command, e.g.@:
20031@samp{define target hook-remote} to add a hook to @samp{target remote}.
20032
8e04817f
AC
20033If an error occurs during the execution of your hook, execution of
20034@value{GDBN} commands stops and @value{GDBN} issues a prompt
20035(before the command that you actually typed had a chance to run).
104c1213 20036
8e04817f
AC
20037If you try to define a hook which does not match any known command, you
20038get a warning from the @code{define} command.
c906108c 20039
8e04817f 20040@node Command Files
d57a3c85 20041@subsection Command Files
c906108c 20042
8e04817f 20043@cindex command files
fcc73fe3 20044@cindex scripting commands
6fc08d32
EZ
20045A command file for @value{GDBN} is a text file made of lines that are
20046@value{GDBN} commands. Comments (lines starting with @kbd{#}) may
20047also be included. An empty line in a command file does nothing; it
20048does not mean to repeat the last command, as it would from the
20049terminal.
c906108c 20050
6fc08d32 20051You can request the execution of a command file with the @code{source}
95433b34
JB
20052command. Note that the @code{source} command is also used to evaluate
20053scripts that are not Command Files. The exact behavior can be configured
20054using the @code{script-extension} setting.
20055@xref{Extending GDB,, Extending GDB}.
c906108c 20056
8e04817f
AC
20057@table @code
20058@kindex source
ca91424e 20059@cindex execute commands from a file
3f7b2faa 20060@item source [-s] [-v] @var{filename}
8e04817f 20061Execute the command file @var{filename}.
c906108c
SS
20062@end table
20063
fcc73fe3
EZ
20064The lines in a command file are generally executed sequentially,
20065unless the order of execution is changed by one of the
20066@emph{flow-control commands} described below. The commands are not
a71ec265
DH
20067printed as they are executed. An error in any command terminates
20068execution of the command file and control is returned to the console.
c906108c 20069
08001717
DE
20070@value{GDBN} first searches for @var{filename} in the current directory.
20071If the file is not found there, and @var{filename} does not specify a
20072directory, then @value{GDBN} also looks for the file on the source search path
20073(specified with the @samp{directory} command);
20074except that @file{$cdir} is not searched because the compilation directory
20075is not relevant to scripts.
4b505b12 20076
3f7b2faa
DE
20077If @code{-s} is specified, then @value{GDBN} searches for @var{filename}
20078on the search path even if @var{filename} specifies a directory.
20079The search is done by appending @var{filename} to each element of the
20080search path. So, for example, if @var{filename} is @file{mylib/myscript}
20081and the search path contains @file{/home/user} then @value{GDBN} will
20082look for the script @file{/home/user/mylib/myscript}.
20083The search is also done if @var{filename} is an absolute path.
20084For example, if @var{filename} is @file{/tmp/myscript} and
20085the search path contains @file{/home/user} then @value{GDBN} will
20086look for the script @file{/home/user/tmp/myscript}.
20087For DOS-like systems, if @var{filename} contains a drive specification,
20088it is stripped before concatenation. For example, if @var{filename} is
20089@file{d:myscript} and the search path contains @file{c:/tmp} then @value{GDBN}
20090will look for the script @file{c:/tmp/myscript}.
20091
16026cd7
AS
20092If @code{-v}, for verbose mode, is given then @value{GDBN} displays
20093each command as it is executed. The option must be given before
20094@var{filename}, and is interpreted as part of the filename anywhere else.
20095
8e04817f
AC
20096Commands that would ask for confirmation if used interactively proceed
20097without asking when used in a command file. Many @value{GDBN} commands that
20098normally print messages to say what they are doing omit the messages
20099when called from command files.
c906108c 20100
8e04817f
AC
20101@value{GDBN} also accepts command input from standard input. In this
20102mode, normal output goes to standard output and error output goes to
20103standard error. Errors in a command file supplied on standard input do
6fc08d32 20104not terminate execution of the command file---execution continues with
8e04817f 20105the next command.
c906108c 20106
474c8240 20107@smallexample
8e04817f 20108gdb < cmds > log 2>&1
474c8240 20109@end smallexample
c906108c 20110
8e04817f
AC
20111(The syntax above will vary depending on the shell used.) This example
20112will execute commands from the file @file{cmds}. All output and errors
20113would be directed to @file{log}.
c906108c 20114
fcc73fe3
EZ
20115Since commands stored on command files tend to be more general than
20116commands typed interactively, they frequently need to deal with
20117complicated situations, such as different or unexpected values of
20118variables and symbols, changes in how the program being debugged is
20119built, etc. @value{GDBN} provides a set of flow-control commands to
20120deal with these complexities. Using these commands, you can write
20121complex scripts that loop over data structures, execute commands
20122conditionally, etc.
20123
20124@table @code
20125@kindex if
20126@kindex else
20127@item if
20128@itemx else
20129This command allows to include in your script conditionally executed
20130commands. The @code{if} command takes a single argument, which is an
20131expression to evaluate. It is followed by a series of commands that
20132are executed only if the expression is true (its value is nonzero).
20133There can then optionally be an @code{else} line, followed by a series
20134of commands that are only executed if the expression was false. The
20135end of the list is marked by a line containing @code{end}.
20136
20137@kindex while
20138@item while
20139This command allows to write loops. Its syntax is similar to
20140@code{if}: the command takes a single argument, which is an expression
20141to evaluate, and must be followed by the commands to execute, one per
20142line, terminated by an @code{end}. These commands are called the
20143@dfn{body} of the loop. The commands in the body of @code{while} are
20144executed repeatedly as long as the expression evaluates to true.
20145
20146@kindex loop_break
20147@item loop_break
20148This command exits the @code{while} loop in whose body it is included.
20149Execution of the script continues after that @code{while}s @code{end}
20150line.
20151
20152@kindex loop_continue
20153@item loop_continue
20154This command skips the execution of the rest of the body of commands
20155in the @code{while} loop in whose body it is included. Execution
20156branches to the beginning of the @code{while} loop, where it evaluates
20157the controlling expression.
ca91424e
EZ
20158
20159@kindex end@r{ (if/else/while commands)}
20160@item end
20161Terminate the block of commands that are the body of @code{if},
20162@code{else}, or @code{while} flow-control commands.
fcc73fe3
EZ
20163@end table
20164
20165
8e04817f 20166@node Output
d57a3c85 20167@subsection Commands for Controlled Output
c906108c 20168
8e04817f
AC
20169During the execution of a command file or a user-defined command, normal
20170@value{GDBN} output is suppressed; the only output that appears is what is
20171explicitly printed by the commands in the definition. This section
20172describes three commands useful for generating exactly the output you
20173want.
c906108c
SS
20174
20175@table @code
8e04817f
AC
20176@kindex echo
20177@item echo @var{text}
20178@c I do not consider backslash-space a standard C escape sequence
20179@c because it is not in ANSI.
20180Print @var{text}. Nonprinting characters can be included in
20181@var{text} using C escape sequences, such as @samp{\n} to print a
20182newline. @strong{No newline is printed unless you specify one.}
20183In addition to the standard C escape sequences, a backslash followed
20184by a space stands for a space. This is useful for displaying a
20185string with spaces at the beginning or the end, since leading and
20186trailing spaces are otherwise trimmed from all arguments.
20187To print @samp{@w{ }and foo =@w{ }}, use the command
20188@samp{echo \@w{ }and foo = \@w{ }}.
c906108c 20189
8e04817f
AC
20190A backslash at the end of @var{text} can be used, as in C, to continue
20191the command onto subsequent lines. For example,
c906108c 20192
474c8240 20193@smallexample
8e04817f
AC
20194echo This is some text\n\
20195which is continued\n\
20196onto several lines.\n
474c8240 20197@end smallexample
c906108c 20198
8e04817f 20199produces the same output as
c906108c 20200
474c8240 20201@smallexample
8e04817f
AC
20202echo This is some text\n
20203echo which is continued\n
20204echo onto several lines.\n
474c8240 20205@end smallexample
c906108c 20206
8e04817f
AC
20207@kindex output
20208@item output @var{expression}
20209Print the value of @var{expression} and nothing but that value: no
20210newlines, no @samp{$@var{nn} = }. The value is not entered in the
20211value history either. @xref{Expressions, ,Expressions}, for more information
20212on expressions.
c906108c 20213
8e04817f
AC
20214@item output/@var{fmt} @var{expression}
20215Print the value of @var{expression} in format @var{fmt}. You can use
20216the same formats as for @code{print}. @xref{Output Formats,,Output
79a6e687 20217Formats}, for more information.
c906108c 20218
8e04817f 20219@kindex printf
82160952
EZ
20220@item printf @var{template}, @var{expressions}@dots{}
20221Print the values of one or more @var{expressions} under the control of
20222the string @var{template}. To print several values, make
20223@var{expressions} be a comma-separated list of individual expressions,
20224which may be either numbers or pointers. Their values are printed as
20225specified by @var{template}, exactly as a C program would do by
20226executing the code below:
c906108c 20227
474c8240 20228@smallexample
82160952 20229printf (@var{template}, @var{expressions}@dots{});
474c8240 20230@end smallexample
c906108c 20231
82160952
EZ
20232As in @code{C} @code{printf}, ordinary characters in @var{template}
20233are printed verbatim, while @dfn{conversion specification} introduced
20234by the @samp{%} character cause subsequent @var{expressions} to be
20235evaluated, their values converted and formatted according to type and
20236style information encoded in the conversion specifications, and then
20237printed.
20238
8e04817f 20239For example, you can print two values in hex like this:
c906108c 20240
8e04817f
AC
20241@smallexample
20242printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo
20243@end smallexample
c906108c 20244
82160952
EZ
20245@code{printf} supports all the standard @code{C} conversion
20246specifications, including the flags and modifiers between the @samp{%}
20247character and the conversion letter, with the following exceptions:
20248
20249@itemize @bullet
20250@item
20251The argument-ordering modifiers, such as @samp{2$}, are not supported.
20252
20253@item
20254The modifier @samp{*} is not supported for specifying precision or
20255width.
20256
20257@item
20258The @samp{'} flag (for separation of digits into groups according to
20259@code{LC_NUMERIC'}) is not supported.
20260
20261@item
20262The type modifiers @samp{hh}, @samp{j}, @samp{t}, and @samp{z} are not
20263supported.
20264
20265@item
20266The conversion letter @samp{n} (as in @samp{%n}) is not supported.
20267
20268@item
20269The conversion letters @samp{a} and @samp{A} are not supported.
20270@end itemize
20271
20272@noindent
20273Note that the @samp{ll} type modifier is supported only if the
20274underlying @code{C} implementation used to build @value{GDBN} supports
20275the @code{long long int} type, and the @samp{L} type modifier is
20276supported only if @code{long double} type is available.
20277
20278As in @code{C}, @code{printf} supports simple backslash-escape
20279sequences, such as @code{\n}, @samp{\t}, @samp{\\}, @samp{\"},
20280@samp{\a}, and @samp{\f}, that consist of backslash followed by a
20281single character. Octal and hexadecimal escape sequences are not
20282supported.
1a619819
LM
20283
20284Additionally, @code{printf} supports conversion specifications for DFP
0aea4bf3
LM
20285(@dfn{Decimal Floating Point}) types using the following length modifiers
20286together with a floating point specifier.
1a619819
LM
20287letters:
20288
20289@itemize @bullet
20290@item
20291@samp{H} for printing @code{Decimal32} types.
20292
20293@item
20294@samp{D} for printing @code{Decimal64} types.
20295
20296@item
20297@samp{DD} for printing @code{Decimal128} types.
20298@end itemize
20299
20300If the underlying @code{C} implementation used to build @value{GDBN} has
0aea4bf3 20301support for the three length modifiers for DFP types, other modifiers
3b784c4f 20302such as width and precision will also be available for @value{GDBN} to use.
1a619819
LM
20303
20304In case there is no such @code{C} support, no additional modifiers will be
20305available and the value will be printed in the standard way.
20306
20307Here's an example of printing DFP types using the above conversion letters:
20308@smallexample
0aea4bf3 20309printf "D32: %Hf - D64: %Df - D128: %DDf\n",1.2345df,1.2E10dd,1.2E1dl
1a619819
LM
20310@end smallexample
20311
f1421989
HZ
20312@kindex eval
20313@item eval @var{template}, @var{expressions}@dots{}
20314Convert the values of one or more @var{expressions} under the control of
20315the string @var{template} to a command line, and call it.
20316
c906108c
SS
20317@end table
20318
d57a3c85
TJB
20319@node Python
20320@section Scripting @value{GDBN} using Python
20321@cindex python scripting
20322@cindex scripting with python
20323
20324You can script @value{GDBN} using the @uref{http://www.python.org/,
20325Python programming language}. This feature is available only if
20326@value{GDBN} was configured using @option{--with-python}.
20327
9279c692
JB
20328@cindex python directory
20329Python scripts used by @value{GDBN} should be installed in
20330@file{@var{data-directory}/python}, where @var{data-directory} is
20331the data directory as determined at @value{GDBN} startup (@pxref{Data Files}). This directory, known as the @dfn{python directory},
20332is automatically added to the Python Search Path in order to allow
20333the Python interpreter to locate all scripts installed at this location.
20334
d57a3c85
TJB
20335@menu
20336* Python Commands:: Accessing Python from @value{GDBN}.
20337* Python API:: Accessing @value{GDBN} from Python.
8a1ea21f 20338* Auto-loading:: Automatically loading Python code.
d57a3c85
TJB
20339@end menu
20340
20341@node Python Commands
20342@subsection Python Commands
20343@cindex python commands
20344@cindex commands to access python
20345
20346@value{GDBN} provides one command for accessing the Python interpreter,
20347and one related setting:
20348
20349@table @code
20350@kindex python
20351@item python @r{[}@var{code}@r{]}
20352The @code{python} command can be used to evaluate Python code.
20353
20354If given an argument, the @code{python} command will evaluate the
20355argument as a Python command. For example:
20356
20357@smallexample
20358(@value{GDBP}) python print 23
2035923
20360@end smallexample
20361
20362If you do not provide an argument to @code{python}, it will act as a
20363multi-line command, like @code{define}. In this case, the Python
20364script is made up of subsequent command lines, given after the
20365@code{python} command. This command list is terminated using a line
20366containing @code{end}. For example:
20367
20368@smallexample
20369(@value{GDBP}) python
20370Type python script
20371End with a line saying just "end".
20372>print 23
20373>end
2037423
20375@end smallexample
20376
20377@kindex maint set python print-stack
20378@item maint set python print-stack
20379By default, @value{GDBN} will print a stack trace when an error occurs
20380in a Python script. This can be controlled using @code{maint set
20381python print-stack}: if @code{on}, the default, then Python stack
20382printing is enabled; if @code{off}, then Python stack printing is
20383disabled.
20384@end table
20385
95433b34
JB
20386It is also possible to execute a Python script from the @value{GDBN}
20387interpreter:
20388
20389@table @code
20390@item source @file{script-name}
20391The script name must end with @samp{.py} and @value{GDBN} must be configured
20392to recognize the script language based on filename extension using
20393the @code{script-extension} setting. @xref{Extending GDB, ,Extending GDB}.
20394
20395@item python execfile ("script-name")
20396This method is based on the @code{execfile} Python built-in function,
20397and thus is always available.
20398@end table
20399
d57a3c85
TJB
20400@node Python API
20401@subsection Python API
20402@cindex python api
20403@cindex programming in python
20404
20405@cindex python stdout
20406@cindex python pagination
20407At startup, @value{GDBN} overrides Python's @code{sys.stdout} and
20408@code{sys.stderr} to print using @value{GDBN}'s output-paging streams.
20409A Python program which outputs to one of these streams may have its
20410output interrupted by the user (@pxref{Screen Size}). In this
20411situation, a Python @code{KeyboardInterrupt} exception is thrown.
20412
20413@menu
20414* Basic Python:: Basic Python Functions.
20415* Exception Handling::
a08702d6 20416* Values From Inferior::
4c374409
JK
20417* Types In Python:: Python representation of types.
20418* Pretty Printing API:: Pretty-printing values.
a6bac58e 20419* Selecting Pretty-Printers:: How GDB chooses a pretty-printer.
967cf477 20420* Disabling Pretty-Printers:: Disabling broken printers.
595939de
PM
20421* Inferiors In Python:: Python representation of inferiors (processes)
20422* Threads In Python:: Accessing inferior threads from Python.
d8906c6f 20423* Commands In Python:: Implementing new commands in Python.
d7b32ed3 20424* Parameters In Python:: Adding new @value{GDBN} parameters.
bc3b79fd 20425* Functions In Python:: Writing new convenience functions.
fa33c3cd 20426* Progspaces In Python:: Program spaces.
89c73ade 20427* Objfiles In Python:: Object files.
f3e9a817
PM
20428* Frames In Python:: Accessing inferior stack frames from Python.
20429* Blocks In Python:: Accessing frame blocks from Python.
20430* Symbols In Python:: Python representation of symbols.
20431* Symbol Tables In Python:: Python representation of symbol tables.
be759fcf 20432* Lazy Strings In Python:: Python representation of lazy strings.
adc36818 20433* Breakpoints In Python:: Manipulating breakpoints using Python.
d57a3c85
TJB
20434@end menu
20435
20436@node Basic Python
20437@subsubsection Basic Python
20438
20439@cindex python functions
20440@cindex python module
20441@cindex gdb module
20442@value{GDBN} introduces a new Python module, named @code{gdb}. All
20443methods and classes added by @value{GDBN} are placed in this module.
20444@value{GDBN} automatically @code{import}s the @code{gdb} module for
20445use in all scripts evaluated by the @code{python} command.
20446
9279c692
JB
20447@findex gdb.PYTHONDIR
20448@defvar PYTHONDIR
20449A string containing the python directory (@pxref{Python}).
20450@end defvar
20451
d57a3c85 20452@findex gdb.execute
bc9f0842 20453@defun execute command [from_tty] [to_string]
d57a3c85
TJB
20454Evaluate @var{command}, a string, as a @value{GDBN} CLI command.
20455If a GDB exception happens while @var{command} runs, it is
20456translated as described in @ref{Exception Handling,,Exception Handling}.
12453b93
TJB
20457
20458@var{from_tty} specifies whether @value{GDBN} ought to consider this
20459command as having originated from the user invoking it interactively.
20460It must be a boolean value. If omitted, it defaults to @code{False}.
bc9f0842
TT
20461
20462By default, any output produced by @var{command} is sent to
20463@value{GDBN}'s standard output. If the @var{to_string} parameter is
20464@code{True}, then output will be collected by @code{gdb.execute} and
20465returned as a string. The default is @code{False}, in which case the
20466return value is @code{None}.
d57a3c85
TJB
20467@end defun
20468
adc36818
PM
20469@findex gdb.breakpoints
20470@defun breakpoints
20471Return a sequence holding all of @value{GDBN}'s breakpoints.
20472@xref{Breakpoints In Python}, for more information.
20473@end defun
20474
8f500870
TT
20475@findex gdb.parameter
20476@defun parameter parameter
d57a3c85
TJB
20477Return the value of a @value{GDBN} parameter. @var{parameter} is a
20478string naming the parameter to look up; @var{parameter} may contain
20479spaces if the parameter has a multi-part name. For example,
20480@samp{print object} is a valid parameter name.
20481
20482If the named parameter does not exist, this function throws a
20483@code{RuntimeError}. Otherwise, the parameter's value is converted to
20484a Python value of the appropriate type, and returned.
20485@end defun
20486
08c637de
TJB
20487@findex gdb.history
20488@defun history number
20489Return a value from @value{GDBN}'s value history (@pxref{Value
20490History}). @var{number} indicates which history element to return.
20491If @var{number} is negative, then @value{GDBN} will take its absolute value
20492and count backward from the last element (i.e., the most recent element) to
20493find the value to return. If @var{number} is zero, then @value{GDBN} will
a0c36267 20494return the most recent element. If the element specified by @var{number}
08c637de
TJB
20495doesn't exist in the value history, a @code{RuntimeError} exception will be
20496raised.
20497
20498If no exception is raised, the return value is always an instance of
20499@code{gdb.Value} (@pxref{Values From Inferior}).
20500@end defun
20501
57a1d736
TT
20502@findex gdb.parse_and_eval
20503@defun parse_and_eval expression
20504Parse @var{expression} as an expression in the current language,
20505evaluate it, and return the result as a @code{gdb.Value}.
20506@var{expression} must be a string.
20507
20508This function can be useful when implementing a new command
20509(@pxref{Commands In Python}), as it provides a way to parse the
20510command's argument as an expression. It is also useful simply to
20511compute values, for example, it is the only way to get the value of a
20512convenience variable (@pxref{Convenience Vars}) as a @code{gdb.Value}.
20513@end defun
20514
d57a3c85
TJB
20515@findex gdb.write
20516@defun write string
20517Print a string to @value{GDBN}'s paginated standard output stream.
20518Writing to @code{sys.stdout} or @code{sys.stderr} will automatically
20519call this function.
20520@end defun
20521
20522@findex gdb.flush
20523@defun flush
20524Flush @value{GDBN}'s paginated standard output stream. Flushing
20525@code{sys.stdout} or @code{sys.stderr} will automatically call this
20526function.
20527@end defun
20528
f870a310
TT
20529@findex gdb.target_charset
20530@defun target_charset
20531Return the name of the current target character set (@pxref{Character
20532Sets}). This differs from @code{gdb.parameter('target-charset')} in
20533that @samp{auto} is never returned.
20534@end defun
20535
20536@findex gdb.target_wide_charset
20537@defun target_wide_charset
20538Return the name of the current target wide character set
20539(@pxref{Character Sets}). This differs from
20540@code{gdb.parameter('target-wide-charset')} in that @samp{auto} is
20541never returned.
20542@end defun
20543
d57a3c85
TJB
20544@node Exception Handling
20545@subsubsection Exception Handling
20546@cindex python exceptions
20547@cindex exceptions, python
20548
20549When executing the @code{python} command, Python exceptions
20550uncaught within the Python code are translated to calls to
20551@value{GDBN} error-reporting mechanism. If the command that called
20552@code{python} does not handle the error, @value{GDBN} will
20553terminate it and print an error message containing the Python
20554exception name, the associated value, and the Python call stack
20555backtrace at the point where the exception was raised. Example:
20556
20557@smallexample
20558(@value{GDBP}) python print foo
20559Traceback (most recent call last):
20560 File "<string>", line 1, in <module>
20561NameError: name 'foo' is not defined
20562@end smallexample
20563
20564@value{GDBN} errors that happen in @value{GDBN} commands invoked by Python
20565code are converted to Python @code{RuntimeError} exceptions. User
20566interrupt (via @kbd{C-c} or by typing @kbd{q} at a pagination
20567prompt) is translated to a Python @code{KeyboardInterrupt}
20568exception. If you catch these exceptions in your Python code, your
20569exception handler will see @code{RuntimeError} or
20570@code{KeyboardInterrupt} as the exception type, the @value{GDBN} error
20571message as its value, and the Python call stack backtrace at the
20572Python statement closest to where the @value{GDBN} error occured as the
20573traceback.
20574
07ca107c
DE
20575@findex gdb.GdbError
20576When implementing @value{GDBN} commands in Python via @code{gdb.Command},
20577it is useful to be able to throw an exception that doesn't cause a
20578traceback to be printed. For example, the user may have invoked the
20579command incorrectly. Use the @code{gdb.GdbError} exception
20580to handle this case. Example:
20581
20582@smallexample
20583(gdb) python
20584>class HelloWorld (gdb.Command):
20585> """Greet the whole world."""
20586> def __init__ (self):
20587> super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_OBSCURE)
20588> def invoke (self, args, from_tty):
20589> argv = gdb.string_to_argv (args)
20590> if len (argv) != 0:
20591> raise gdb.GdbError ("hello-world takes no arguments")
20592> print "Hello, World!"
20593>HelloWorld ()
20594>end
20595(gdb) hello-world 42
20596hello-world takes no arguments
20597@end smallexample
20598
a08702d6
TJB
20599@node Values From Inferior
20600@subsubsection Values From Inferior
20601@cindex values from inferior, with Python
20602@cindex python, working with values from inferior
20603
20604@cindex @code{gdb.Value}
20605@value{GDBN} provides values it obtains from the inferior program in
20606an object of type @code{gdb.Value}. @value{GDBN} uses this object
20607for its internal bookkeeping of the inferior's values, and for
20608fetching values when necessary.
20609
20610Inferior values that are simple scalars can be used directly in
20611Python expressions that are valid for the value's data type. Here's
20612an example for an integer or floating-point value @code{some_val}:
20613
20614@smallexample
20615bar = some_val + 2
20616@end smallexample
20617
20618@noindent
20619As result of this, @code{bar} will also be a @code{gdb.Value} object
20620whose values are of the same type as those of @code{some_val}.
20621
20622Inferior values that are structures or instances of some class can
20623be accessed using the Python @dfn{dictionary syntax}. For example, if
20624@code{some_val} is a @code{gdb.Value} instance holding a structure, you
20625can access its @code{foo} element with:
20626
20627@smallexample
20628bar = some_val['foo']
20629@end smallexample
20630
20631Again, @code{bar} will also be a @code{gdb.Value} object.
20632
5374244e
PM
20633A @code{gdb.Value} that represents a function can be executed via
20634inferior function call. Any arguments provided to the call must match
20635the function's prototype, and must be provided in the order specified
20636by that prototype.
20637
20638For example, @code{some_val} is a @code{gdb.Value} instance
20639representing a function that takes two integers as arguments. To
20640execute this function, call it like so:
20641
20642@smallexample
20643result = some_val (10,20)
20644@end smallexample
20645
20646Any values returned from a function call will be stored as a
20647@code{gdb.Value}.
20648
c0c6f777 20649The following attributes are provided:
a08702d6 20650
def2b000 20651@table @code
2c74e833 20652@defivar Value address
c0c6f777
TJB
20653If this object is addressable, this read-only attribute holds a
20654@code{gdb.Value} object representing the address. Otherwise,
20655this attribute holds @code{None}.
2c74e833 20656@end defivar
c0c6f777 20657
def2b000 20658@cindex optimized out value in Python
2c74e833 20659@defivar Value is_optimized_out
def2b000
TJB
20660This read-only boolean attribute is true if the compiler optimized out
20661this value, thus it is not available for fetching from the inferior.
2c74e833
TT
20662@end defivar
20663
20664@defivar Value type
20665The type of this @code{gdb.Value}. The value of this attribute is a
20666@code{gdb.Type} object.
20667@end defivar
def2b000
TJB
20668@end table
20669
20670The following methods are provided:
20671
20672@table @code
14ff2235
PM
20673@defmethod Value cast type
20674Return a new instance of @code{gdb.Value} that is the result of
20675casting this instance to the type described by @var{type}, which must
20676be a @code{gdb.Type} object. If the cast cannot be performed for some
20677reason, this method throws an exception.
20678@end defmethod
20679
a08702d6 20680@defmethod Value dereference
def2b000
TJB
20681For pointer data types, this method returns a new @code{gdb.Value} object
20682whose contents is the object pointed to by the pointer. For example, if
20683@code{foo} is a C pointer to an @code{int}, declared in your C program as
a08702d6
TJB
20684
20685@smallexample
20686int *foo;
20687@end smallexample
20688
20689@noindent
20690then you can use the corresponding @code{gdb.Value} to access what
20691@code{foo} points to like this:
20692
20693@smallexample
20694bar = foo.dereference ()
20695@end smallexample
20696
20697The result @code{bar} will be a @code{gdb.Value} object holding the
20698value pointed to by @code{foo}.
20699@end defmethod
20700
fbb8f299 20701@defmethod Value string @r{[}encoding@r{]} @r{[}errors@r{]} @r{[}length@r{]}
b6cb8e7d
TJB
20702If this @code{gdb.Value} represents a string, then this method
20703converts the contents to a Python string. Otherwise, this method will
20704throw an exception.
20705
20706Strings are recognized in a language-specific way; whether a given
20707@code{gdb.Value} represents a string is determined by the current
20708language.
20709
20710For C-like languages, a value is a string if it is a pointer to or an
20711array of characters or ints. The string is assumed to be terminated
fbb8f299
PM
20712by a zero of the appropriate width. However if the optional length
20713argument is given, the string will be converted to that given length,
20714ignoring any embedded zeros that the string may contain.
b6cb8e7d
TJB
20715
20716If the optional @var{encoding} argument is given, it must be a string
20717naming the encoding of the string in the @code{gdb.Value}, such as
20718@code{"ascii"}, @code{"iso-8859-6"} or @code{"utf-8"}. It accepts
20719the same encodings as the corresponding argument to Python's
20720@code{string.decode} method, and the Python codec machinery will be used
20721to convert the string. If @var{encoding} is not given, or if
20722@var{encoding} is the empty string, then either the @code{target-charset}
20723(@pxref{Character Sets}) will be used, or a language-specific encoding
20724will be used, if the current language is able to supply one.
20725
20726The optional @var{errors} argument is the same as the corresponding
20727argument to Python's @code{string.decode} method.
fbb8f299
PM
20728
20729If the optional @var{length} argument is given, the string will be
20730fetched and converted to the given length.
b6cb8e7d 20731@end defmethod
be759fcf
PM
20732
20733@defmethod Value lazy_string @r{[}encoding@r{]} @r{[}length@r{]}
20734If this @code{gdb.Value} represents a string, then this method
20735converts the contents to a @code{gdb.LazyString} (@pxref{Lazy Strings
20736In Python}). Otherwise, this method will throw an exception.
20737
20738If the optional @var{encoding} argument is given, it must be a string
20739naming the encoding of the @code{gdb.LazyString}. Some examples are:
20740@samp{ascii}, @samp{iso-8859-6} or @samp{utf-8}. If the
20741@var{encoding} argument is an encoding that @value{GDBN} does
20742recognize, @value{GDBN} will raise an error.
20743
20744When a lazy string is printed, the @value{GDBN} encoding machinery is
20745used to convert the string during printing. If the optional
20746@var{encoding} argument is not provided, or is an empty string,
20747@value{GDBN} will automatically select the encoding most suitable for
20748the string type. For further information on encoding in @value{GDBN}
20749please see @ref{Character Sets}.
20750
20751If the optional @var{length} argument is given, the string will be
20752fetched and encoded to the length of characters specified. If
20753the @var{length} argument is not provided, the string will be fetched
20754and encoded until a null of appropriate width is found.
20755@end defmethod
def2b000 20756@end table
b6cb8e7d 20757
2c74e833
TT
20758@node Types In Python
20759@subsubsection Types In Python
20760@cindex types in Python
20761@cindex Python, working with types
20762
20763@tindex gdb.Type
20764@value{GDBN} represents types from the inferior using the class
20765@code{gdb.Type}.
20766
20767The following type-related functions are available in the @code{gdb}
20768module:
20769
20770@findex gdb.lookup_type
20771@defun lookup_type name [block]
20772This function looks up a type by name. @var{name} is the name of the
20773type to look up. It must be a string.
20774
5107b149
PM
20775If @var{block} is given, then @var{name} is looked up in that scope.
20776Otherwise, it is searched for globally.
20777
2c74e833
TT
20778Ordinarily, this function will return an instance of @code{gdb.Type}.
20779If the named type cannot be found, it will throw an exception.
20780@end defun
20781
20782An instance of @code{Type} has the following attributes:
20783
20784@table @code
20785@defivar Type code
20786The type code for this type. The type code will be one of the
20787@code{TYPE_CODE_} constants defined below.
20788@end defivar
20789
20790@defivar Type sizeof
20791The size of this type, in target @code{char} units. Usually, a
20792target's @code{char} type will be an 8-bit byte. However, on some
20793unusual platforms, this type may have a different size.
20794@end defivar
20795
20796@defivar Type tag
20797The tag name for this type. The tag name is the name after
20798@code{struct}, @code{union}, or @code{enum} in C and C@t{++}; not all
20799languages have this concept. If this type has no tag name, then
20800@code{None} is returned.
20801@end defivar
20802@end table
20803
20804The following methods are provided:
20805
20806@table @code
20807@defmethod Type fields
20808For structure and union types, this method returns the fields. Range
20809types have two fields, the minimum and maximum values. Enum types
20810have one field per enum constant. Function and method types have one
20811field per parameter. The base types of C@t{++} classes are also
20812represented as fields. If the type has no fields, or does not fit
20813into one of these categories, an empty sequence will be returned.
20814
20815Each field is an object, with some pre-defined attributes:
20816@table @code
20817@item bitpos
20818This attribute is not available for @code{static} fields (as in
20819C@t{++} or Java). For non-@code{static} fields, the value is the bit
20820position of the field.
20821
20822@item name
20823The name of the field, or @code{None} for anonymous fields.
20824
20825@item artificial
20826This is @code{True} if the field is artificial, usually meaning that
20827it was provided by the compiler and not the user. This attribute is
20828always provided, and is @code{False} if the field is not artificial.
20829
bfd31e71
PM
20830@item is_base_class
20831This is @code{True} if the field represents a base class of a C@t{++}
20832structure. This attribute is always provided, and is @code{False}
20833if the field is not a base class of the type that is the argument of
20834@code{fields}, or if that type was not a C@t{++} class.
20835
2c74e833
TT
20836@item bitsize
20837If the field is packed, or is a bitfield, then this will have a
20838non-zero value, which is the size of the field in bits. Otherwise,
20839this will be zero; in this case the field's size is given by its type.
20840
20841@item type
20842The type of the field. This is usually an instance of @code{Type},
20843but it can be @code{None} in some situations.
20844@end table
20845@end defmethod
20846
20847@defmethod Type const
20848Return a new @code{gdb.Type} object which represents a
20849@code{const}-qualified variant of this type.
20850@end defmethod
20851
20852@defmethod Type volatile
20853Return a new @code{gdb.Type} object which represents a
20854@code{volatile}-qualified variant of this type.
20855@end defmethod
20856
20857@defmethod Type unqualified
20858Return a new @code{gdb.Type} object which represents an unqualified
20859variant of this type. That is, the result is neither @code{const} nor
20860@code{volatile}.
20861@end defmethod
20862
361ae042
PM
20863@defmethod Type range
20864Return a Python @code{Tuple} object that contains two elements: the
20865low bound of the argument type and the high bound of that type. If
20866the type does not have a range, @value{GDBN} will raise a
20867@code{RuntimeError} exception.
20868@end defmethod
20869
2c74e833
TT
20870@defmethod Type reference
20871Return a new @code{gdb.Type} object which represents a reference to this
20872type.
20873@end defmethod
20874
7a6973ad
TT
20875@defmethod Type pointer
20876Return a new @code{gdb.Type} object which represents a pointer to this
20877type.
20878@end defmethod
20879
2c74e833
TT
20880@defmethod Type strip_typedefs
20881Return a new @code{gdb.Type} that represents the real type,
20882after removing all layers of typedefs.
20883@end defmethod
20884
20885@defmethod Type target
20886Return a new @code{gdb.Type} object which represents the target type
20887of this type.
20888
20889For a pointer type, the target type is the type of the pointed-to
20890object. For an array type (meaning C-like arrays), the target type is
20891the type of the elements of the array. For a function or method type,
20892the target type is the type of the return value. For a complex type,
20893the target type is the type of the elements. For a typedef, the
20894target type is the aliased type.
20895
20896If the type does not have a target, this method will throw an
20897exception.
20898@end defmethod
20899
5107b149 20900@defmethod Type template_argument n [block]
2c74e833
TT
20901If this @code{gdb.Type} is an instantiation of a template, this will
20902return a new @code{gdb.Type} which represents the type of the
20903@var{n}th template argument.
20904
20905If this @code{gdb.Type} is not a template type, this will throw an
20906exception. Ordinarily, only C@t{++} code will have template types.
20907
5107b149
PM
20908If @var{block} is given, then @var{name} is looked up in that scope.
20909Otherwise, it is searched for globally.
2c74e833
TT
20910@end defmethod
20911@end table
20912
20913
20914Each type has a code, which indicates what category this type falls
20915into. The available type categories are represented by constants
20916defined in the @code{gdb} module:
20917
20918@table @code
20919@findex TYPE_CODE_PTR
20920@findex gdb.TYPE_CODE_PTR
20921@item TYPE_CODE_PTR
20922The type is a pointer.
20923
20924@findex TYPE_CODE_ARRAY
20925@findex gdb.TYPE_CODE_ARRAY
20926@item TYPE_CODE_ARRAY
20927The type is an array.
20928
20929@findex TYPE_CODE_STRUCT
20930@findex gdb.TYPE_CODE_STRUCT
20931@item TYPE_CODE_STRUCT
20932The type is a structure.
20933
20934@findex TYPE_CODE_UNION
20935@findex gdb.TYPE_CODE_UNION
20936@item TYPE_CODE_UNION
20937The type is a union.
20938
20939@findex TYPE_CODE_ENUM
20940@findex gdb.TYPE_CODE_ENUM
20941@item TYPE_CODE_ENUM
20942The type is an enum.
20943
20944@findex TYPE_CODE_FLAGS
20945@findex gdb.TYPE_CODE_FLAGS
20946@item TYPE_CODE_FLAGS
20947A bit flags type, used for things such as status registers.
20948
20949@findex TYPE_CODE_FUNC
20950@findex gdb.TYPE_CODE_FUNC
20951@item TYPE_CODE_FUNC
20952The type is a function.
20953
20954@findex TYPE_CODE_INT
20955@findex gdb.TYPE_CODE_INT
20956@item TYPE_CODE_INT
20957The type is an integer type.
20958
20959@findex TYPE_CODE_FLT
20960@findex gdb.TYPE_CODE_FLT
20961@item TYPE_CODE_FLT
20962A floating point type.
20963
20964@findex TYPE_CODE_VOID
20965@findex gdb.TYPE_CODE_VOID
20966@item TYPE_CODE_VOID
20967The special type @code{void}.
20968
20969@findex TYPE_CODE_SET
20970@findex gdb.TYPE_CODE_SET
20971@item TYPE_CODE_SET
20972A Pascal set type.
20973
20974@findex TYPE_CODE_RANGE
20975@findex gdb.TYPE_CODE_RANGE
20976@item TYPE_CODE_RANGE
20977A range type, that is, an integer type with bounds.
20978
20979@findex TYPE_CODE_STRING
20980@findex gdb.TYPE_CODE_STRING
20981@item TYPE_CODE_STRING
20982A string type. Note that this is only used for certain languages with
20983language-defined string types; C strings are not represented this way.
20984
20985@findex TYPE_CODE_BITSTRING
20986@findex gdb.TYPE_CODE_BITSTRING
20987@item TYPE_CODE_BITSTRING
20988A string of bits.
20989
20990@findex TYPE_CODE_ERROR
20991@findex gdb.TYPE_CODE_ERROR
20992@item TYPE_CODE_ERROR
20993An unknown or erroneous type.
20994
20995@findex TYPE_CODE_METHOD
20996@findex gdb.TYPE_CODE_METHOD
20997@item TYPE_CODE_METHOD
20998A method type, as found in C@t{++} or Java.
20999
21000@findex TYPE_CODE_METHODPTR
21001@findex gdb.TYPE_CODE_METHODPTR
21002@item TYPE_CODE_METHODPTR
21003A pointer-to-member-function.
21004
21005@findex TYPE_CODE_MEMBERPTR
21006@findex gdb.TYPE_CODE_MEMBERPTR
21007@item TYPE_CODE_MEMBERPTR
21008A pointer-to-member.
21009
21010@findex TYPE_CODE_REF
21011@findex gdb.TYPE_CODE_REF
21012@item TYPE_CODE_REF
21013A reference type.
21014
21015@findex TYPE_CODE_CHAR
21016@findex gdb.TYPE_CODE_CHAR
21017@item TYPE_CODE_CHAR
21018A character type.
21019
21020@findex TYPE_CODE_BOOL
21021@findex gdb.TYPE_CODE_BOOL
21022@item TYPE_CODE_BOOL
21023A boolean type.
21024
21025@findex TYPE_CODE_COMPLEX
21026@findex gdb.TYPE_CODE_COMPLEX
21027@item TYPE_CODE_COMPLEX
21028A complex float type.
21029
21030@findex TYPE_CODE_TYPEDEF
21031@findex gdb.TYPE_CODE_TYPEDEF
21032@item TYPE_CODE_TYPEDEF
21033A typedef to some other type.
21034
21035@findex TYPE_CODE_NAMESPACE
21036@findex gdb.TYPE_CODE_NAMESPACE
21037@item TYPE_CODE_NAMESPACE
21038A C@t{++} namespace.
21039
21040@findex TYPE_CODE_DECFLOAT
21041@findex gdb.TYPE_CODE_DECFLOAT
21042@item TYPE_CODE_DECFLOAT
21043A decimal floating point type.
21044
21045@findex TYPE_CODE_INTERNAL_FUNCTION
21046@findex gdb.TYPE_CODE_INTERNAL_FUNCTION
21047@item TYPE_CODE_INTERNAL_FUNCTION
21048A function internal to @value{GDBN}. This is the type used to represent
21049convenience functions.
21050@end table
21051
4c374409
JK
21052@node Pretty Printing API
21053@subsubsection Pretty Printing API
a6bac58e 21054
4c374409 21055An example output is provided (@pxref{Pretty Printing}).
a6bac58e
TT
21056
21057A pretty-printer is just an object that holds a value and implements a
21058specific interface, defined here.
21059
21060@defop Operation {pretty printer} children (self)
21061@value{GDBN} will call this method on a pretty-printer to compute the
21062children of the pretty-printer's value.
21063
21064This method must return an object conforming to the Python iterator
21065protocol. Each item returned by the iterator must be a tuple holding
21066two elements. The first element is the ``name'' of the child; the
21067second element is the child's value. The value can be any Python
21068object which is convertible to a @value{GDBN} value.
21069
21070This method is optional. If it does not exist, @value{GDBN} will act
21071as though the value has no children.
21072@end defop
21073
21074@defop Operation {pretty printer} display_hint (self)
21075The CLI may call this method and use its result to change the
21076formatting of a value. The result will also be supplied to an MI
21077consumer as a @samp{displayhint} attribute of the variable being
21078printed.
21079
21080This method is optional. If it does exist, this method must return a
21081string.
21082
21083Some display hints are predefined by @value{GDBN}:
21084
21085@table @samp
21086@item array
21087Indicate that the object being printed is ``array-like''. The CLI
21088uses this to respect parameters such as @code{set print elements} and
21089@code{set print array}.
21090
21091@item map
21092Indicate that the object being printed is ``map-like'', and that the
21093children of this value can be assumed to alternate between keys and
21094values.
21095
21096@item string
21097Indicate that the object being printed is ``string-like''. If the
21098printer's @code{to_string} method returns a Python string of some
21099kind, then @value{GDBN} will call its internal language-specific
21100string-printing function to format the string. For the CLI this means
21101adding quotation marks, possibly escaping some characters, respecting
21102@code{set print elements}, and the like.
21103@end table
21104@end defop
21105
21106@defop Operation {pretty printer} to_string (self)
21107@value{GDBN} will call this method to display the string
21108representation of the value passed to the object's constructor.
21109
21110When printing from the CLI, if the @code{to_string} method exists,
21111then @value{GDBN} will prepend its result to the values returned by
21112@code{children}. Exactly how this formatting is done is dependent on
21113the display hint, and may change as more hints are added. Also,
21114depending on the print settings (@pxref{Print Settings}), the CLI may
21115print just the result of @code{to_string} in a stack trace, omitting
21116the result of @code{children}.
21117
21118If this method returns a string, it is printed verbatim.
21119
21120Otherwise, if this method returns an instance of @code{gdb.Value},
21121then @value{GDBN} prints this value. This may result in a call to
21122another pretty-printer.
21123
21124If instead the method returns a Python value which is convertible to a
21125@code{gdb.Value}, then @value{GDBN} performs the conversion and prints
21126the resulting value. Again, this may result in a call to another
21127pretty-printer. Python scalars (integers, floats, and booleans) and
21128strings are convertible to @code{gdb.Value}; other types are not.
21129
79f283fe
PM
21130Finally, if this method returns @code{None} then no further operations
21131are peformed in this method and nothing is printed.
21132
a6bac58e
TT
21133If the result is not one of these types, an exception is raised.
21134@end defop
21135
21136@node Selecting Pretty-Printers
21137@subsubsection Selecting Pretty-Printers
21138
21139The Python list @code{gdb.pretty_printers} contains an array of
967cf477
DE
21140functions or callable objects that have been registered via addition
21141as a pretty-printer.
fa33c3cd 21142Each @code{gdb.Progspace} contains a @code{pretty_printers} attribute.
a6bac58e
TT
21143Each @code{gdb.Objfile} also contains a @code{pretty_printers}
21144attribute.
21145
21146A function on one of these lists is passed a single @code{gdb.Value}
21147argument and should return a pretty-printer object conforming to the
4c374409 21148interface definition above (@pxref{Pretty Printing API}). If a function
a6bac58e
TT
21149cannot create a pretty-printer for the value, it should return
21150@code{None}.
21151
21152@value{GDBN} first checks the @code{pretty_printers} attribute of each
fa33c3cd 21153@code{gdb.Objfile} in the current program space and iteratively calls
967cf477
DE
21154each enabled function (@pxref{Disabling Pretty-Printers})
21155in the list for that @code{gdb.Objfile} until it receives
fa33c3cd
DE
21156a pretty-printer object.
21157If no pretty-printer is found in the objfile lists, @value{GDBN} then
21158searches the pretty-printer list of the current program space,
967cf477 21159calling each enabled function until an object is returned.
a6bac58e 21160After these lists have been exhausted, it tries the global
967cf477 21161@code{gdb.pretty_printers} list, again calling each enabled function until an
a6bac58e
TT
21162object is returned.
21163
21164The order in which the objfiles are searched is not specified. For a
21165given list, functions are always invoked from the head of the list,
21166and iterated over sequentially until the end of the list, or a printer
21167object is returned.
21168
21169Here is an example showing how a @code{std::string} printer might be
21170written:
21171
21172@smallexample
21173class StdStringPrinter:
21174 "Print a std::string"
21175
21176 def __init__ (self, val):
21177 self.val = val
21178
21179 def to_string (self):
21180 return self.val['_M_dataplus']['_M_p']
21181
21182 def display_hint (self):
21183 return 'string'
21184@end smallexample
21185
21186And here is an example showing how a lookup function for the printer
21187example above might be written.
21188
21189@smallexample
21190def str_lookup_function (val):
21191
21192 lookup_tag = val.type.tag
21193 regex = re.compile ("^std::basic_string<char,.*>$")
21194 if lookup_tag == None:
21195 return None
21196 if regex.match (lookup_tag):
21197 return StdStringPrinter (val)
21198
21199 return None
21200@end smallexample
21201
21202The example lookup function extracts the value's type, and attempts to
21203match it to a type that it can pretty-print. If it is a type the
21204printer can pretty-print, it will return a printer object. If not, it
21205returns @code{None}.
21206
21207We recommend that you put your core pretty-printers into a Python
21208package. If your pretty-printers are for use with a library, we
21209further recommend embedding a version number into the package name.
21210This practice will enable @value{GDBN} to load multiple versions of
21211your pretty-printers at the same time, because they will have
21212different names.
21213
21214You should write auto-loaded code (@pxref{Auto-loading}) such that it
21215can be evaluated multiple times without changing its meaning. An
21216ideal auto-load file will consist solely of @code{import}s of your
21217printer modules, followed by a call to a register pretty-printers with
21218the current objfile.
21219
21220Taken as a whole, this approach will scale nicely to multiple
21221inferiors, each potentially using a different library version.
21222Embedding a version number in the Python package name will ensure that
21223@value{GDBN} is able to load both sets of printers simultaneously.
21224Then, because the search for pretty-printers is done by objfile, and
21225because your auto-loaded code took care to register your library's
21226printers with a specific objfile, @value{GDBN} will find the correct
21227printers for the specific version of the library used by each
21228inferior.
21229
4c374409 21230To continue the @code{std::string} example (@pxref{Pretty Printing API}),
a6bac58e
TT
21231this code might appear in @code{gdb.libstdcxx.v6}:
21232
21233@smallexample
21234def register_printers (objfile):
21235 objfile.pretty_printers.add (str_lookup_function)
21236@end smallexample
21237
21238@noindent
21239And then the corresponding contents of the auto-load file would be:
21240
21241@smallexample
21242import gdb.libstdcxx.v6
21243gdb.libstdcxx.v6.register_printers (gdb.current_objfile ())
21244@end smallexample
21245
967cf477
DE
21246@node Disabling Pretty-Printers
21247@subsubsection Disabling Pretty-Printers
21248@cindex disabling pretty-printers
21249
21250For various reasons a pretty-printer may not work.
21251For example, the underlying data structure may have changed and
21252the pretty-printer is out of date.
21253
21254The consequences of a broken pretty-printer are severe enough that
21255@value{GDBN} provides support for enabling and disabling individual
21256printers. For example, if @code{print frame-arguments} is on,
21257a backtrace can become highly illegible if any argument is printed
21258with a broken printer.
21259
21260Pretty-printers are enabled and disabled by attaching an @code{enabled}
21261attribute to the registered function or callable object. If this attribute
21262is present and its value is @code{False}, the printer is disabled, otherwise
21263the printer is enabled.
21264
595939de
PM
21265@node Inferiors In Python
21266@subsubsection Inferiors In Python
21267@cindex inferiors in python
21268
21269@findex gdb.Inferior
21270Programs which are being run under @value{GDBN} are called inferiors
21271(@pxref{Inferiors and Programs}). Python scripts can access
21272information about and manipulate inferiors controlled by @value{GDBN}
21273via objects of the @code{gdb.Inferior} class.
21274
21275The following inferior-related functions are available in the @code{gdb}
21276module:
21277
21278@defun inferiors
21279Return a tuple containing all inferior objects.
21280@end defun
21281
21282A @code{gdb.Inferior} object has the following attributes:
21283
21284@table @code
21285@defivar Inferior num
21286ID of inferior, as assigned by GDB.
21287@end defivar
21288
21289@defivar Inferior pid
21290Process ID of the inferior, as assigned by the underlying operating
21291system.
21292@end defivar
21293
21294@defivar Inferior was_attached
21295Boolean signaling whether the inferior was created using `attach', or
21296started by @value{GDBN} itself.
21297@end defivar
21298@end table
21299
21300A @code{gdb.Inferior} object has the following methods:
21301
21302@table @code
21303@defmethod Inferior threads
21304This method returns a tuple holding all the threads which are valid
21305when it is called. If there are no valid threads, the method will
21306return an empty tuple.
21307@end defmethod
21308
21309@findex gdb.read_memory
21310@defmethod Inferior read_memory address length
21311Read @var{length} bytes of memory from the inferior, starting at
21312@var{address}. Returns a buffer object, which behaves much like an array
21313or a string. It can be modified and given to the @code{gdb.write_memory}
21314function.
21315@end defmethod
21316
21317@findex gdb.write_memory
21318@defmethod Inferior write_memory address buffer @r{[}length@r{]}
21319Write the contents of @var{buffer} to the inferior, starting at
21320@var{address}. The @var{buffer} parameter must be a Python object
21321which supports the buffer protocol, i.e., a string, an array or the
21322object returned from @code{gdb.read_memory}. If given, @var{length}
21323determines the number of bytes from @var{buffer} to be written.
21324@end defmethod
21325
21326@findex gdb.search_memory
21327@defmethod Inferior search_memory address length pattern
21328Search a region of the inferior memory starting at @var{address} with
21329the given @var{length} using the search pattern supplied in
21330@var{pattern}. The @var{pattern} parameter must be a Python object
21331which supports the buffer protocol, i.e., a string, an array or the
21332object returned from @code{gdb.read_memory}. Returns a Python @code{Long}
21333containing the address where the pattern was found, or @code{None} if
21334the pattern could not be found.
21335@end defmethod
21336@end table
21337
21338@node Threads In Python
21339@subsubsection Threads In Python
21340@cindex threads in python
21341
21342@findex gdb.InferiorThread
21343Python scripts can access information about, and manipulate inferior threads
21344controlled by @value{GDBN}, via objects of the @code{gdb.InferiorThread} class.
21345
21346The following thread-related functions are available in the @code{gdb}
21347module:
21348
21349@findex gdb.selected_thread
21350@defun selected_thread
21351This function returns the thread object for the selected thread. If there
21352is no selected thread, this will return @code{None}.
21353@end defun
21354
21355A @code{gdb.InferiorThread} object has the following attributes:
21356
21357@table @code
21358@defivar InferiorThread num
21359ID of the thread, as assigned by GDB.
21360@end defivar
21361
21362@defivar InferiorThread ptid
21363ID of the thread, as assigned by the operating system. This attribute is a
21364tuple containing three integers. The first is the Process ID (PID); the second
21365is the Lightweight Process ID (LWPID), and the third is the Thread ID (TID).
21366Either the LWPID or TID may be 0, which indicates that the operating system
21367does not use that identifier.
21368@end defivar
21369@end table
21370
21371A @code{gdb.InferiorThread} object has the following methods:
21372
dc3b15be 21373@table @code
595939de
PM
21374@defmethod InferiorThread switch
21375This changes @value{GDBN}'s currently selected thread to the one represented
21376by this object.
21377@end defmethod
21378
21379@defmethod InferiorThread is_stopped
21380Return a Boolean indicating whether the thread is stopped.
21381@end defmethod
21382
21383@defmethod InferiorThread is_running
21384Return a Boolean indicating whether the thread is running.
21385@end defmethod
21386
21387@defmethod InferiorThread is_exited
21388Return a Boolean indicating whether the thread is exited.
21389@end defmethod
21390@end table
21391
d8906c6f
TJB
21392@node Commands In Python
21393@subsubsection Commands In Python
21394
21395@cindex commands in python
21396@cindex python commands
d8906c6f
TJB
21397You can implement new @value{GDBN} CLI commands in Python. A CLI
21398command is implemented using an instance of the @code{gdb.Command}
21399class, most commonly using a subclass.
21400
cc924cad 21401@defmethod Command __init__ name @var{command_class} @r{[}@var{completer_class}@r{]} @r{[}@var{prefix}@r{]}
d8906c6f
TJB
21402The object initializer for @code{Command} registers the new command
21403with @value{GDBN}. This initializer is normally invoked from the
21404subclass' own @code{__init__} method.
21405
21406@var{name} is the name of the command. If @var{name} consists of
21407multiple words, then the initial words are looked for as prefix
21408commands. In this case, if one of the prefix commands does not exist,
21409an exception is raised.
21410
21411There is no support for multi-line commands.
21412
cc924cad 21413@var{command_class} should be one of the @samp{COMMAND_} constants
d8906c6f
TJB
21414defined below. This argument tells @value{GDBN} how to categorize the
21415new command in the help system.
21416
cc924cad 21417@var{completer_class} is an optional argument. If given, it should be
d8906c6f
TJB
21418one of the @samp{COMPLETE_} constants defined below. This argument
21419tells @value{GDBN} how to perform completion for this command. If not
21420given, @value{GDBN} will attempt to complete using the object's
21421@code{complete} method (see below); if no such method is found, an
21422error will occur when completion is attempted.
21423
21424@var{prefix} is an optional argument. If @code{True}, then the new
21425command is a prefix command; sub-commands of this command may be
21426registered.
21427
21428The help text for the new command is taken from the Python
21429documentation string for the command's class, if there is one. If no
21430documentation string is provided, the default value ``This command is
21431not documented.'' is used.
21432@end defmethod
21433
a0c36267 21434@cindex don't repeat Python command
d8906c6f
TJB
21435@defmethod Command dont_repeat
21436By default, a @value{GDBN} command is repeated when the user enters a
21437blank line at the command prompt. A command can suppress this
21438behavior by invoking the @code{dont_repeat} method. This is similar
21439to the user command @code{dont-repeat}, see @ref{Define, dont-repeat}.
21440@end defmethod
21441
21442@defmethod Command invoke argument from_tty
21443This method is called by @value{GDBN} when this command is invoked.
21444
21445@var{argument} is a string. It is the argument to the command, after
21446leading and trailing whitespace has been stripped.
21447
21448@var{from_tty} is a boolean argument. When true, this means that the
21449command was entered by the user at the terminal; when false it means
21450that the command came from elsewhere.
21451
21452If this method throws an exception, it is turned into a @value{GDBN}
21453@code{error} call. Otherwise, the return value is ignored.
07ca107c
DE
21454
21455@findex gdb.string_to_argv
21456To break @var{argument} up into an argv-like string use
21457@code{gdb.string_to_argv}. This function behaves identically to
21458@value{GDBN}'s internal argument lexer @code{buildargv}.
21459It is recommended to use this for consistency.
21460Arguments are separated by spaces and may be quoted.
21461Example:
21462
21463@smallexample
21464print gdb.string_to_argv ("1 2\ \\\"3 '4 \"5' \"6 '7\"")
21465['1', '2 "3', '4 "5', "6 '7"]
21466@end smallexample
21467
d8906c6f
TJB
21468@end defmethod
21469
a0c36267 21470@cindex completion of Python commands
d8906c6f
TJB
21471@defmethod Command complete text word
21472This method is called by @value{GDBN} when the user attempts
21473completion on this command. All forms of completion are handled by
a0c36267
EZ
21474this method, that is, the @key{TAB} and @key{M-?} key bindings
21475(@pxref{Completion}), and the @code{complete} command (@pxref{Help,
21476complete}).
d8906c6f
TJB
21477
21478The arguments @var{text} and @var{word} are both strings. @var{text}
21479holds the complete command line up to the cursor's location.
21480@var{word} holds the last word of the command line; this is computed
21481using a word-breaking heuristic.
21482
21483The @code{complete} method can return several values:
21484@itemize @bullet
21485@item
21486If the return value is a sequence, the contents of the sequence are
21487used as the completions. It is up to @code{complete} to ensure that the
21488contents actually do complete the word. A zero-length sequence is
21489allowed, it means that there were no completions available. Only
21490string elements of the sequence are used; other elements in the
21491sequence are ignored.
21492
21493@item
21494If the return value is one of the @samp{COMPLETE_} constants defined
21495below, then the corresponding @value{GDBN}-internal completion
21496function is invoked, and its result is used.
21497
21498@item
21499All other results are treated as though there were no available
21500completions.
21501@end itemize
21502@end defmethod
21503
d8906c6f
TJB
21504When a new command is registered, it must be declared as a member of
21505some general class of commands. This is used to classify top-level
21506commands in the on-line help system; note that prefix commands are not
21507listed under their own category but rather that of their top-level
21508command. The available classifications are represented by constants
21509defined in the @code{gdb} module:
21510
21511@table @code
21512@findex COMMAND_NONE
21513@findex gdb.COMMAND_NONE
21514@item COMMAND_NONE
21515The command does not belong to any particular class. A command in
21516this category will not be displayed in any of the help categories.
21517
21518@findex COMMAND_RUNNING
21519@findex gdb.COMMAND_RUNNING
a0c36267 21520@item COMMAND_RUNNING
d8906c6f
TJB
21521The command is related to running the inferior. For example,
21522@code{start}, @code{step}, and @code{continue} are in this category.
a0c36267 21523Type @kbd{help running} at the @value{GDBN} prompt to see a list of
d8906c6f
TJB
21524commands in this category.
21525
21526@findex COMMAND_DATA
21527@findex gdb.COMMAND_DATA
a0c36267 21528@item COMMAND_DATA
d8906c6f
TJB
21529The command is related to data or variables. For example,
21530@code{call}, @code{find}, and @code{print} are in this category. Type
a0c36267 21531@kbd{help data} at the @value{GDBN} prompt to see a list of commands
d8906c6f
TJB
21532in this category.
21533
21534@findex COMMAND_STACK
21535@findex gdb.COMMAND_STACK
21536@item COMMAND_STACK
21537The command has to do with manipulation of the stack. For example,
21538@code{backtrace}, @code{frame}, and @code{return} are in this
a0c36267 21539category. Type @kbd{help stack} at the @value{GDBN} prompt to see a
d8906c6f
TJB
21540list of commands in this category.
21541
21542@findex COMMAND_FILES
21543@findex gdb.COMMAND_FILES
21544@item COMMAND_FILES
21545This class is used for file-related commands. For example,
21546@code{file}, @code{list} and @code{section} are in this category.
a0c36267 21547Type @kbd{help files} at the @value{GDBN} prompt to see a list of
d8906c6f
TJB
21548commands in this category.
21549
21550@findex COMMAND_SUPPORT
21551@findex gdb.COMMAND_SUPPORT
21552@item COMMAND_SUPPORT
21553This should be used for ``support facilities'', generally meaning
21554things that are useful to the user when interacting with @value{GDBN},
21555but not related to the state of the inferior. For example,
21556@code{help}, @code{make}, and @code{shell} are in this category. Type
a0c36267 21557@kbd{help support} at the @value{GDBN} prompt to see a list of
d8906c6f
TJB
21558commands in this category.
21559
21560@findex COMMAND_STATUS
21561@findex gdb.COMMAND_STATUS
a0c36267 21562@item COMMAND_STATUS
d8906c6f
TJB
21563The command is an @samp{info}-related command, that is, related to the
21564state of @value{GDBN} itself. For example, @code{info}, @code{macro},
a0c36267 21565and @code{show} are in this category. Type @kbd{help status} at the
d8906c6f
TJB
21566@value{GDBN} prompt to see a list of commands in this category.
21567
21568@findex COMMAND_BREAKPOINTS
21569@findex gdb.COMMAND_BREAKPOINTS
a0c36267 21570@item COMMAND_BREAKPOINTS
d8906c6f 21571The command has to do with breakpoints. For example, @code{break},
a0c36267 21572@code{clear}, and @code{delete} are in this category. Type @kbd{help
d8906c6f
TJB
21573breakpoints} at the @value{GDBN} prompt to see a list of commands in
21574this category.
21575
21576@findex COMMAND_TRACEPOINTS
21577@findex gdb.COMMAND_TRACEPOINTS
a0c36267 21578@item COMMAND_TRACEPOINTS
d8906c6f
TJB
21579The command has to do with tracepoints. For example, @code{trace},
21580@code{actions}, and @code{tfind} are in this category. Type
a0c36267 21581@kbd{help tracepoints} at the @value{GDBN} prompt to see a list of
d8906c6f
TJB
21582commands in this category.
21583
21584@findex COMMAND_OBSCURE
21585@findex gdb.COMMAND_OBSCURE
21586@item COMMAND_OBSCURE
21587The command is only used in unusual circumstances, or is not of
21588general interest to users. For example, @code{checkpoint},
a0c36267 21589@code{fork}, and @code{stop} are in this category. Type @kbd{help
d8906c6f
TJB
21590obscure} at the @value{GDBN} prompt to see a list of commands in this
21591category.
21592
21593@findex COMMAND_MAINTENANCE
21594@findex gdb.COMMAND_MAINTENANCE
21595@item COMMAND_MAINTENANCE
21596The command is only useful to @value{GDBN} maintainers. The
21597@code{maintenance} and @code{flushregs} commands are in this category.
a0c36267 21598Type @kbd{help internals} at the @value{GDBN} prompt to see a list of
d8906c6f
TJB
21599commands in this category.
21600@end table
21601
d8906c6f
TJB
21602A new command can use a predefined completion function, either by
21603specifying it via an argument at initialization, or by returning it
21604from the @code{complete} method. These predefined completion
21605constants are all defined in the @code{gdb} module:
21606
21607@table @code
21608@findex COMPLETE_NONE
21609@findex gdb.COMPLETE_NONE
21610@item COMPLETE_NONE
21611This constant means that no completion should be done.
21612
21613@findex COMPLETE_FILENAME
21614@findex gdb.COMPLETE_FILENAME
21615@item COMPLETE_FILENAME
21616This constant means that filename completion should be performed.
21617
21618@findex COMPLETE_LOCATION
21619@findex gdb.COMPLETE_LOCATION
21620@item COMPLETE_LOCATION
21621This constant means that location completion should be done.
21622@xref{Specify Location}.
21623
21624@findex COMPLETE_COMMAND
21625@findex gdb.COMPLETE_COMMAND
21626@item COMPLETE_COMMAND
21627This constant means that completion should examine @value{GDBN}
21628command names.
21629
21630@findex COMPLETE_SYMBOL
21631@findex gdb.COMPLETE_SYMBOL
21632@item COMPLETE_SYMBOL
21633This constant means that completion should be done using symbol names
21634as the source.
21635@end table
21636
21637The following code snippet shows how a trivial CLI command can be
21638implemented in Python:
21639
21640@smallexample
21641class HelloWorld (gdb.Command):
21642 """Greet the whole world."""
21643
21644 def __init__ (self):
21645 super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_OBSCURE)
21646
21647 def invoke (self, arg, from_tty):
21648 print "Hello, World!"
21649
21650HelloWorld ()
21651@end smallexample
21652
21653The last line instantiates the class, and is necessary to trigger the
21654registration of the command with @value{GDBN}. Depending on how the
21655Python code is read into @value{GDBN}, you may need to import the
21656@code{gdb} module explicitly.
21657
d7b32ed3
PM
21658@node Parameters In Python
21659@subsubsection Parameters In Python
21660
21661@cindex parameters in python
21662@cindex python parameters
21663@tindex gdb.Parameter
21664@tindex Parameter
21665You can implement new @value{GDBN} parameters using Python. A new
21666parameter is implemented as an instance of the @code{gdb.Parameter}
21667class.
21668
21669Parameters are exposed to the user via the @code{set} and
21670@code{show} commands. @xref{Help}.
21671
21672There are many parameters that already exist and can be set in
21673@value{GDBN}. Two examples are: @code{set follow fork} and
21674@code{set charset}. Setting these parameters influences certain
21675behavior in @value{GDBN}. Similarly, you can define parameters that
21676can be used to influence behavior in custom Python scripts and commands.
21677
21678@defmethod Parameter __init__ name @var{command-class} @var{parameter-class} @r{[}@var{enum-sequence}@r{]}
21679The object initializer for @code{Parameter} registers the new
21680parameter with @value{GDBN}. This initializer is normally invoked
21681from the subclass' own @code{__init__} method.
21682
21683@var{name} is the name of the new parameter. If @var{name} consists
21684of multiple words, then the initial words are looked for as prefix
21685parameters. An example of this can be illustrated with the
21686@code{set print} set of parameters. If @var{name} is
21687@code{print foo}, then @code{print} will be searched as the prefix
21688parameter. In this case the parameter can subsequently be accessed in
21689@value{GDBN} as @code{set print foo}.
21690
21691If @var{name} consists of multiple words, and no prefix parameter group
21692can be found, an exception is raised.
21693
21694@var{command-class} should be one of the @samp{COMMAND_} constants
21695(@pxref{Commands In Python}). This argument tells @value{GDBN} how to
21696categorize the new parameter in the help system.
21697
21698@var{parameter-class} should be one of the @samp{PARAM_} constants
21699defined below. This argument tells @value{GDBN} the type of the new
21700parameter; this information is used for input validation and
21701completion.
21702
21703If @var{parameter-class} is @code{PARAM_ENUM}, then
21704@var{enum-sequence} must be a sequence of strings. These strings
21705represent the possible values for the parameter.
21706
21707If @var{parameter-class} is not @code{PARAM_ENUM}, then the presence
21708of a fourth argument will cause an exception to be thrown.
21709
21710The help text for the new parameter is taken from the Python
21711documentation string for the parameter's class, if there is one. If
21712there is no documentation string, a default value is used.
21713@end defmethod
21714
21715@defivar Parameter set_doc
21716If this attribute exists, and is a string, then its value is used as
21717the help text for this parameter's @code{set} command. The value is
21718examined when @code{Parameter.__init__} is invoked; subsequent changes
21719have no effect.
21720@end defivar
21721
21722@defivar Parameter show_doc
21723If this attribute exists, and is a string, then its value is used as
21724the help text for this parameter's @code{show} command. The value is
21725examined when @code{Parameter.__init__} is invoked; subsequent changes
21726have no effect.
21727@end defivar
21728
21729@defivar Parameter value
21730The @code{value} attribute holds the underlying value of the
21731parameter. It can be read and assigned to just as any other
21732attribute. @value{GDBN} does validation when assignments are made.
21733@end defivar
21734
21735
21736When a new parameter is defined, its type must be specified. The
21737available types are represented by constants defined in the @code{gdb}
21738module:
21739
21740@table @code
21741@findex PARAM_BOOLEAN
21742@findex gdb.PARAM_BOOLEAN
21743@item PARAM_BOOLEAN
21744The value is a plain boolean. The Python boolean values, @code{True}
21745and @code{False} are the only valid values.
21746
21747@findex PARAM_AUTO_BOOLEAN
21748@findex gdb.PARAM_AUTO_BOOLEAN
21749@item PARAM_AUTO_BOOLEAN
21750The value has three possible states: true, false, and @samp{auto}. In
21751Python, true and false are represented using boolean constants, and
21752@samp{auto} is represented using @code{None}.
21753
21754@findex PARAM_UINTEGER
21755@findex gdb.PARAM_UINTEGER
21756@item PARAM_UINTEGER
21757The value is an unsigned integer. The value of 0 should be
21758interpreted to mean ``unlimited''.
21759
21760@findex PARAM_INTEGER
21761@findex gdb.PARAM_INTEGER
21762@item PARAM_INTEGER
21763The value is a signed integer. The value of 0 should be interpreted
21764to mean ``unlimited''.
21765
21766@findex PARAM_STRING
21767@findex gdb.PARAM_STRING
21768@item PARAM_STRING
21769The value is a string. When the user modifies the string, any escape
21770sequences, such as @samp{\t}, @samp{\f}, and octal escapes, are
21771translated into corresponding characters and encoded into the current
21772host charset.
21773
21774@findex PARAM_STRING_NOESCAPE
21775@findex gdb.PARAM_STRING_NOESCAPE
21776@item PARAM_STRING_NOESCAPE
21777The value is a string. When the user modifies the string, escapes are
21778passed through untranslated.
21779
21780@findex PARAM_OPTIONAL_FILENAME
21781@findex gdb.PARAM_OPTIONAL_FILENAME
21782@item PARAM_OPTIONAL_FILENAME
21783The value is a either a filename (a string), or @code{None}.
21784
21785@findex PARAM_FILENAME
21786@findex gdb.PARAM_FILENAME
21787@item PARAM_FILENAME
21788The value is a filename. This is just like
21789@code{PARAM_STRING_NOESCAPE}, but uses file names for completion.
21790
21791@findex PARAM_ZINTEGER
21792@findex gdb.PARAM_ZINTEGER
21793@item PARAM_ZINTEGER
21794The value is an integer. This is like @code{PARAM_INTEGER}, except 0
21795is interpreted as itself.
21796
21797@findex PARAM_ENUM
21798@findex gdb.PARAM_ENUM
21799@item PARAM_ENUM
21800The value is a string, which must be one of a collection string
21801constants provided when the parameter is created.
21802@end table
21803
bc3b79fd
TJB
21804@node Functions In Python
21805@subsubsection Writing new convenience functions
21806
21807@cindex writing convenience functions
21808@cindex convenience functions in python
21809@cindex python convenience functions
21810@tindex gdb.Function
21811@tindex Function
21812You can implement new convenience functions (@pxref{Convenience Vars})
21813in Python. A convenience function is an instance of a subclass of the
21814class @code{gdb.Function}.
21815
21816@defmethod Function __init__ name
21817The initializer for @code{Function} registers the new function with
21818@value{GDBN}. The argument @var{name} is the name of the function,
21819a string. The function will be visible to the user as a convenience
21820variable of type @code{internal function}, whose name is the same as
21821the given @var{name}.
21822
21823The documentation for the new function is taken from the documentation
21824string for the new class.
21825@end defmethod
21826
21827@defmethod Function invoke @var{*args}
21828When a convenience function is evaluated, its arguments are converted
21829to instances of @code{gdb.Value}, and then the function's
21830@code{invoke} method is called. Note that @value{GDBN} does not
21831predetermine the arity of convenience functions. Instead, all
21832available arguments are passed to @code{invoke}, following the
21833standard Python calling convention. In particular, a convenience
21834function can have default values for parameters without ill effect.
21835
21836The return value of this method is used as its value in the enclosing
21837expression. If an ordinary Python value is returned, it is converted
21838to a @code{gdb.Value} following the usual rules.
21839@end defmethod
21840
21841The following code snippet shows how a trivial convenience function can
21842be implemented in Python:
21843
21844@smallexample
21845class Greet (gdb.Function):
21846 """Return string to greet someone.
21847Takes a name as argument."""
21848
21849 def __init__ (self):
21850 super (Greet, self).__init__ ("greet")
21851
21852 def invoke (self, name):
21853 return "Hello, %s!" % name.string ()
21854
21855Greet ()
21856@end smallexample
21857
21858The last line instantiates the class, and is necessary to trigger the
21859registration of the function with @value{GDBN}. Depending on how the
21860Python code is read into @value{GDBN}, you may need to import the
21861@code{gdb} module explicitly.
21862
fa33c3cd
DE
21863@node Progspaces In Python
21864@subsubsection Program Spaces In Python
21865
21866@cindex progspaces in python
21867@tindex gdb.Progspace
21868@tindex Progspace
21869A program space, or @dfn{progspace}, represents a symbolic view
21870of an address space.
21871It consists of all of the objfiles of the program.
21872@xref{Objfiles In Python}.
21873@xref{Inferiors and Programs, program spaces}, for more details
21874about program spaces.
21875
21876The following progspace-related functions are available in the
21877@code{gdb} module:
21878
21879@findex gdb.current_progspace
21880@defun current_progspace
21881This function returns the program space of the currently selected inferior.
21882@xref{Inferiors and Programs}.
21883@end defun
21884
21885@findex gdb.progspaces
21886@defun progspaces
21887Return a sequence of all the progspaces currently known to @value{GDBN}.
21888@end defun
21889
21890Each progspace is represented by an instance of the @code{gdb.Progspace}
21891class.
21892
21893@defivar Progspace filename
21894The file name of the progspace as a string.
21895@end defivar
21896
21897@defivar Progspace pretty_printers
21898The @code{pretty_printers} attribute is a list of functions. It is
21899used to look up pretty-printers. A @code{Value} is passed to each
21900function in order; if the function returns @code{None}, then the
21901search continues. Otherwise, the return value should be an object
4c374409 21902which is used to format the value. @xref{Pretty Printing API}, for more
fa33c3cd
DE
21903information.
21904@end defivar
21905
89c73ade
TT
21906@node Objfiles In Python
21907@subsubsection Objfiles In Python
21908
21909@cindex objfiles in python
21910@tindex gdb.Objfile
21911@tindex Objfile
21912@value{GDBN} loads symbols for an inferior from various
21913symbol-containing files (@pxref{Files}). These include the primary
21914executable file, any shared libraries used by the inferior, and any
21915separate debug info files (@pxref{Separate Debug Files}).
21916@value{GDBN} calls these symbol-containing files @dfn{objfiles}.
21917
21918The following objfile-related functions are available in the
21919@code{gdb} module:
21920
21921@findex gdb.current_objfile
21922@defun current_objfile
21923When auto-loading a Python script (@pxref{Auto-loading}), @value{GDBN}
21924sets the ``current objfile'' to the corresponding objfile. This
21925function returns the current objfile. If there is no current objfile,
21926this function returns @code{None}.
21927@end defun
21928
21929@findex gdb.objfiles
21930@defun objfiles
21931Return a sequence of all the objfiles current known to @value{GDBN}.
21932@xref{Objfiles In Python}.
21933@end defun
21934
21935Each objfile is represented by an instance of the @code{gdb.Objfile}
21936class.
21937
21938@defivar Objfile filename
21939The file name of the objfile as a string.
21940@end defivar
21941
21942@defivar Objfile pretty_printers
21943The @code{pretty_printers} attribute is a list of functions. It is
21944used to look up pretty-printers. A @code{Value} is passed to each
21945function in order; if the function returns @code{None}, then the
21946search continues. Otherwise, the return value should be an object
4c374409 21947which is used to format the value. @xref{Pretty Printing API}, for more
a6bac58e 21948information.
89c73ade
TT
21949@end defivar
21950
f8f6f20b 21951@node Frames In Python
f3e9a817 21952@subsubsection Accessing inferior stack frames from Python.
f8f6f20b
TJB
21953
21954@cindex frames in python
21955When the debugged program stops, @value{GDBN} is able to analyze its call
21956stack (@pxref{Frames,,Stack frames}). The @code{gdb.Frame} class
21957represents a frame in the stack. A @code{gdb.Frame} object is only valid
21958while its corresponding frame exists in the inferior's stack. If you try
21959to use an invalid frame object, @value{GDBN} will throw a @code{RuntimeError}
21960exception.
21961
21962Two @code{gdb.Frame} objects can be compared for equality with the @code{==}
21963operator, like:
21964
21965@smallexample
21966(@value{GDBP}) python print gdb.newest_frame() == gdb.selected_frame ()
21967True
21968@end smallexample
21969
21970The following frame-related functions are available in the @code{gdb} module:
21971
21972@findex gdb.selected_frame
21973@defun selected_frame
21974Return the selected frame object. (@pxref{Selection,,Selecting a Frame}).
21975@end defun
21976
21977@defun frame_stop_reason_string reason
21978Return a string explaining the reason why @value{GDBN} stopped unwinding
21979frames, as expressed by the given @var{reason} code (an integer, see the
21980@code{unwind_stop_reason} method further down in this section).
21981@end defun
21982
21983A @code{gdb.Frame} object has the following methods:
21984
21985@table @code
21986@defmethod Frame is_valid
21987Returns true if the @code{gdb.Frame} object is valid, false if not.
21988A frame object can become invalid if the frame it refers to doesn't
21989exist anymore in the inferior. All @code{gdb.Frame} methods will throw
21990an exception if it is invalid at the time the method is called.
21991@end defmethod
21992
21993@defmethod Frame name
21994Returns the function name of the frame, or @code{None} if it can't be
21995obtained.
21996@end defmethod
21997
21998@defmethod Frame type
21999Returns the type of the frame. The value can be one of
22000@code{gdb.NORMAL_FRAME}, @code{gdb.DUMMY_FRAME}, @code{gdb.SIGTRAMP_FRAME}
22001or @code{gdb.SENTINEL_FRAME}.
22002@end defmethod
22003
22004@defmethod Frame unwind_stop_reason
22005Return an integer representing the reason why it's not possible to find
22006more frames toward the outermost frame. Use
22007@code{gdb.frame_stop_reason_string} to convert the value returned by this
22008function to a string.
22009@end defmethod
22010
22011@defmethod Frame pc
22012Returns the frame's resume address.
22013@end defmethod
22014
f3e9a817
PM
22015@defmethod Frame block
22016Return the frame's code block. @xref{Blocks In Python}.
22017@end defmethod
22018
22019@defmethod Frame function
22020Return the symbol for the function corresponding to this frame.
22021@xref{Symbols In Python}.
22022@end defmethod
22023
f8f6f20b
TJB
22024@defmethod Frame older
22025Return the frame that called this frame.
22026@end defmethod
22027
22028@defmethod Frame newer
22029Return the frame called by this frame.
22030@end defmethod
22031
f3e9a817
PM
22032@defmethod Frame find_sal
22033Return the frame's symtab and line object.
22034@xref{Symbol Tables In Python}.
22035@end defmethod
22036
dc00d89f
PM
22037@defmethod Frame read_var variable @r{[}block@r{]}
22038Return the value of @var{variable} in this frame. If the optional
22039argument @var{block} is provided, search for the variable from that
22040block; otherwise start at the frame's current block (which is
22041determined by the frame's current program counter). @var{variable}
22042must be a string or a @code{gdb.Symbol} object. @var{block} must be a
22043@code{gdb.Block} object.
f8f6f20b 22044@end defmethod
f3e9a817
PM
22045
22046@defmethod Frame select
22047Set this frame to be the selected frame. @xref{Stack, ,Examining the
22048Stack}.
22049@end defmethod
22050@end table
22051
22052@node Blocks In Python
22053@subsubsection Accessing frame blocks from Python.
22054
22055@cindex blocks in python
22056@tindex gdb.Block
22057
22058Within each frame, @value{GDBN} maintains information on each block
22059stored in that frame. These blocks are organized hierarchically, and
22060are represented individually in Python as a @code{gdb.Block}.
22061Please see @ref{Frames In Python}, for a more in-depth discussion on
22062frames. Furthermore, see @ref{Stack, ,Examining the Stack}, for more
22063detailed technical information on @value{GDBN}'s book-keeping of the
22064stack.
22065
22066The following block-related functions are available in the @code{gdb}
22067module:
22068
22069@findex gdb.block_for_pc
22070@defun block_for_pc pc
22071Return the @code{gdb.Block} containing the given @var{pc} value. If the
22072block cannot be found for the @var{pc} value specified, the function
22073will return @code{None}.
22074@end defun
22075
22076A @code{gdb.Block} object has the following attributes:
22077
22078@table @code
22079@defivar Block start
22080The start address of the block. This attribute is not writable.
22081@end defivar
22082
22083@defivar Block end
22084The end address of the block. This attribute is not writable.
22085@end defivar
22086
22087@defivar Block function
22088The name of the block represented as a @code{gdb.Symbol}. If the
22089block is not named, then this attribute holds @code{None}. This
22090attribute is not writable.
22091@end defivar
22092
22093@defivar Block superblock
22094The block containing this block. If this parent block does not exist,
22095this attribute holds @code{None}. This attribute is not writable.
22096@end defivar
22097@end table
22098
22099@node Symbols In Python
22100@subsubsection Python representation of Symbols.
22101
22102@cindex symbols in python
22103@tindex gdb.Symbol
22104
22105@value{GDBN} represents every variable, function and type as an
22106entry in a symbol table. @xref{Symbols, ,Examining the Symbol Table}.
22107Similarly, Python represents these symbols in @value{GDBN} with the
22108@code{gdb.Symbol} object.
22109
22110The following symbol-related functions are available in the @code{gdb}
22111module:
22112
22113@findex gdb.lookup_symbol
22114@defun lookup_symbol name [block] [domain]
22115This function searches for a symbol by name. The search scope can be
22116restricted to the parameters defined in the optional domain and block
22117arguments.
22118
22119@var{name} is the name of the symbol. It must be a string. The
22120optional @var{block} argument restricts the search to symbols visible
22121in that @var{block}. The @var{block} argument must be a
22122@code{gdb.Block} object. The optional @var{domain} argument restricts
22123the search to the domain type. The @var{domain} argument must be a
22124domain constant defined in the @code{gdb} module and described later
22125in this chapter.
22126@end defun
22127
22128A @code{gdb.Symbol} object has the following attributes:
22129
22130@table @code
22131@defivar Symbol symtab
22132The symbol table in which the symbol appears. This attribute is
22133represented as a @code{gdb.Symtab} object. @xref{Symbol Tables In
22134Python}. This attribute is not writable.
22135@end defivar
22136
22137@defivar Symbol name
22138The name of the symbol as a string. This attribute is not writable.
22139@end defivar
22140
22141@defivar Symbol linkage_name
22142The name of the symbol, as used by the linker (i.e., may be mangled).
22143This attribute is not writable.
22144@end defivar
22145
22146@defivar Symbol print_name
22147The name of the symbol in a form suitable for output. This is either
22148@code{name} or @code{linkage_name}, depending on whether the user
22149asked @value{GDBN} to display demangled or mangled names.
22150@end defivar
22151
22152@defivar Symbol addr_class
22153The address class of the symbol. This classifies how to find the value
22154of a symbol. Each address class is a constant defined in the
22155@code{gdb} module and described later in this chapter.
22156@end defivar
22157
22158@defivar Symbol is_argument
22159@code{True} if the symbol is an argument of a function.
22160@end defivar
22161
22162@defivar Symbol is_constant
22163@code{True} if the symbol is a constant.
22164@end defivar
22165
22166@defivar Symbol is_function
22167@code{True} if the symbol is a function or a method.
22168@end defivar
22169
22170@defivar Symbol is_variable
22171@code{True} if the symbol is a variable.
22172@end defivar
22173@end table
22174
22175The available domain categories in @code{gdb.Symbol} are represented
22176as constants in the @code{gdb} module:
22177
22178@table @code
22179@findex SYMBOL_UNDEF_DOMAIN
22180@findex gdb.SYMBOL_UNDEF_DOMAIN
22181@item SYMBOL_UNDEF_DOMAIN
22182This is used when a domain has not been discovered or none of the
22183following domains apply. This usually indicates an error either
22184in the symbol information or in @value{GDBN}'s handling of symbols.
22185@findex SYMBOL_VAR_DOMAIN
22186@findex gdb.SYMBOL_VAR_DOMAIN
22187@item SYMBOL_VAR_DOMAIN
22188This domain contains variables, function names, typedef names and enum
22189type values.
22190@findex SYMBOL_STRUCT_DOMAIN
22191@findex gdb.SYMBOL_STRUCT_DOMAIN
22192@item SYMBOL_STRUCT_DOMAIN
22193This domain holds struct, union and enum type names.
22194@findex SYMBOL_LABEL_DOMAIN
22195@findex gdb.SYMBOL_LABEL_DOMAIN
22196@item SYMBOL_LABEL_DOMAIN
22197This domain contains names of labels (for gotos).
22198@findex SYMBOL_VARIABLES_DOMAIN
22199@findex gdb.SYMBOL_VARIABLES_DOMAIN
22200@item SYMBOL_VARIABLES_DOMAIN
22201This domain holds a subset of the @code{SYMBOLS_VAR_DOMAIN}; it
22202contains everything minus functions and types.
22203@findex SYMBOL_FUNCTIONS_DOMAIN
22204@findex gdb.SYMBOL_FUNCTIONS_DOMAIN
22205@item SYMBOL_FUNCTION_DOMAIN
22206This domain contains all functions.
22207@findex SYMBOL_TYPES_DOMAIN
22208@findex gdb.SYMBOL_TYPES_DOMAIN
22209@item SYMBOL_TYPES_DOMAIN
22210This domain contains all types.
22211@end table
22212
22213The available address class categories in @code{gdb.Symbol} are represented
22214as constants in the @code{gdb} module:
22215
22216@table @code
22217@findex SYMBOL_LOC_UNDEF
22218@findex gdb.SYMBOL_LOC_UNDEF
22219@item SYMBOL_LOC_UNDEF
22220If this is returned by address class, it indicates an error either in
22221the symbol information or in @value{GDBN}'s handling of symbols.
22222@findex SYMBOL_LOC_CONST
22223@findex gdb.SYMBOL_LOC_CONST
22224@item SYMBOL_LOC_CONST
22225Value is constant int.
22226@findex SYMBOL_LOC_STATIC
22227@findex gdb.SYMBOL_LOC_STATIC
22228@item SYMBOL_LOC_STATIC
22229Value is at a fixed address.
22230@findex SYMBOL_LOC_REGISTER
22231@findex gdb.SYMBOL_LOC_REGISTER
22232@item SYMBOL_LOC_REGISTER
22233Value is in a register.
22234@findex SYMBOL_LOC_ARG
22235@findex gdb.SYMBOL_LOC_ARG
22236@item SYMBOL_LOC_ARG
22237Value is an argument. This value is at the offset stored within the
22238symbol inside the frame's argument list.
22239@findex SYMBOL_LOC_REF_ARG
22240@findex gdb.SYMBOL_LOC_REF_ARG
22241@item SYMBOL_LOC_REF_ARG
22242Value address is stored in the frame's argument list. Just like
22243@code{LOC_ARG} except that the value's address is stored at the
22244offset, not the value itself.
22245@findex SYMBOL_LOC_REGPARM_ADDR
22246@findex gdb.SYMBOL_LOC_REGPARM_ADDR
22247@item SYMBOL_LOC_REGPARM_ADDR
22248Value is a specified register. Just like @code{LOC_REGISTER} except
22249the register holds the address of the argument instead of the argument
22250itself.
22251@findex SYMBOL_LOC_LOCAL
22252@findex gdb.SYMBOL_LOC_LOCAL
22253@item SYMBOL_LOC_LOCAL
22254Value is a local variable.
22255@findex SYMBOL_LOC_TYPEDEF
22256@findex gdb.SYMBOL_LOC_TYPEDEF
22257@item SYMBOL_LOC_TYPEDEF
22258Value not used. Symbols in the domain @code{SYMBOL_STRUCT_DOMAIN} all
22259have this class.
22260@findex SYMBOL_LOC_BLOCK
22261@findex gdb.SYMBOL_LOC_BLOCK
22262@item SYMBOL_LOC_BLOCK
22263Value is a block.
22264@findex SYMBOL_LOC_CONST_BYTES
22265@findex gdb.SYMBOL_LOC_CONST_BYTES
22266@item SYMBOL_LOC_CONST_BYTES
22267Value is a byte-sequence.
22268@findex SYMBOL_LOC_UNRESOLVED
22269@findex gdb.SYMBOL_LOC_UNRESOLVED
22270@item SYMBOL_LOC_UNRESOLVED
22271Value is at a fixed address, but the address of the variable has to be
22272determined from the minimal symbol table whenever the variable is
22273referenced.
22274@findex SYMBOL_LOC_OPTIMIZED_OUT
22275@findex gdb.SYMBOL_LOC_OPTIMIZED_OUT
22276@item SYMBOL_LOC_OPTIMIZED_OUT
22277The value does not actually exist in the program.
22278@findex SYMBOL_LOC_COMPUTED
22279@findex gdb.SYMBOL_LOC_COMPUTED
22280@item SYMBOL_LOC_COMPUTED
22281The value's address is a computed location.
22282@end table
22283
22284@node Symbol Tables In Python
22285@subsubsection Symbol table representation in Python.
22286
22287@cindex symbol tables in python
22288@tindex gdb.Symtab
22289@tindex gdb.Symtab_and_line
22290
22291Access to symbol table data maintained by @value{GDBN} on the inferior
22292is exposed to Python via two objects: @code{gdb.Symtab_and_line} and
22293@code{gdb.Symtab}. Symbol table and line data for a frame is returned
22294from the @code{find_sal} method in @code{gdb.Frame} object.
22295@xref{Frames In Python}.
22296
22297For more information on @value{GDBN}'s symbol table management, see
22298@ref{Symbols, ,Examining the Symbol Table}, for more information.
22299
22300A @code{gdb.Symtab_and_line} object has the following attributes:
22301
22302@table @code
22303@defivar Symtab_and_line symtab
22304The symbol table object (@code{gdb.Symtab}) for this frame.
22305This attribute is not writable.
22306@end defivar
22307
22308@defivar Symtab_and_line pc
22309Indicates the current program counter address. This attribute is not
22310writable.
22311@end defivar
22312
22313@defivar Symtab_and_line line
22314Indicates the current line number for this object. This
22315attribute is not writable.
22316@end defivar
22317@end table
22318
22319A @code{gdb.Symtab} object has the following attributes:
22320
22321@table @code
22322@defivar Symtab filename
22323The symbol table's source filename. This attribute is not writable.
22324@end defivar
22325
22326@defivar Symtab objfile
22327The symbol table's backing object file. @xref{Objfiles In Python}.
22328This attribute is not writable.
22329@end defivar
22330@end table
22331
22332The following methods are provided:
22333
22334@table @code
22335@defmethod Symtab fullname
22336Return the symbol table's source absolute file name.
22337@end defmethod
f8f6f20b
TJB
22338@end table
22339
adc36818
PM
22340@node Breakpoints In Python
22341@subsubsection Manipulating breakpoints using Python
22342
22343@cindex breakpoints in python
22344@tindex gdb.Breakpoint
22345
22346Python code can manipulate breakpoints via the @code{gdb.Breakpoint}
22347class.
22348
22349@defmethod Breakpoint __init__ spec @r{[}type@r{]} @r{[}wp_class@r{]}
22350Create a new breakpoint. @var{spec} is a string naming the
22351location of the breakpoint, or an expression that defines a
22352watchpoint. The contents can be any location recognized by the
22353@code{break} command, or in the case of a watchpoint, by the @code{watch}
22354command. The optional @var{type} denotes the breakpoint to create
22355from the types defined later in this chapter. This argument can be
22356either: @code{BP_BREAKPOINT} or @code{BP_WATCHPOINT}. @var{type}
22357defaults to @code{BP_BREAKPOINT}. The optional @var{wp_class}
22358argument defines the class of watchpoint to create, if @var{type} is
22359defined as @code{BP_WATCHPOINT}. If a watchpoint class is not
22360provided, it is assumed to be a @var{WP_WRITE} class.
22361@end defmethod
22362
22363The available watchpoint types represented by constants are defined in the
22364@code{gdb} module:
22365
22366@table @code
22367@findex WP_READ
22368@findex gdb.WP_READ
22369@item WP_READ
22370Read only watchpoint.
22371
22372@findex WP_WRITE
22373@findex gdb.WP_WRITE
22374@item WP_WRITE
22375Write only watchpoint.
22376
22377@findex WP_ACCESS
22378@findex gdb.WP_ACCESS
22379@item WP_ACCESS
22380Read/Write watchpoint.
22381@end table
22382
22383@defmethod Breakpoint is_valid
22384Return @code{True} if this @code{Breakpoint} object is valid,
22385@code{False} otherwise. A @code{Breakpoint} object can become invalid
22386if the user deletes the breakpoint. In this case, the object still
22387exists, but the underlying breakpoint does not. In the cases of
22388watchpoint scope, the watchpoint remains valid even if execution of the
22389inferior leaves the scope of that watchpoint.
22390@end defmethod
22391
22392@defivar Breakpoint enabled
22393This attribute is @code{True} if the breakpoint is enabled, and
22394@code{False} otherwise. This attribute is writable.
22395@end defivar
22396
22397@defivar Breakpoint silent
22398This attribute is @code{True} if the breakpoint is silent, and
22399@code{False} otherwise. This attribute is writable.
22400
22401Note that a breakpoint can also be silent if it has commands and the
22402first command is @code{silent}. This is not reported by the
22403@code{silent} attribute.
22404@end defivar
22405
22406@defivar Breakpoint thread
22407If the breakpoint is thread-specific, this attribute holds the thread
22408id. If the breakpoint is not thread-specific, this attribute is
22409@code{None}. This attribute is writable.
22410@end defivar
22411
22412@defivar Breakpoint task
22413If the breakpoint is Ada task-specific, this attribute holds the Ada task
22414id. If the breakpoint is not task-specific (or the underlying
22415language is not Ada), this attribute is @code{None}. This attribute
22416is writable.
22417@end defivar
22418
22419@defivar Breakpoint ignore_count
22420This attribute holds the ignore count for the breakpoint, an integer.
22421This attribute is writable.
22422@end defivar
22423
22424@defivar Breakpoint number
22425This attribute holds the breakpoint's number --- the identifier used by
22426the user to manipulate the breakpoint. This attribute is not writable.
22427@end defivar
22428
22429@defivar Breakpoint type
22430This attribute holds the breakpoint's type --- the identifier used to
22431determine the actual breakpoint type or use-case. This attribute is not
22432writable.
22433@end defivar
22434
22435The available types are represented by constants defined in the @code{gdb}
22436module:
22437
22438@table @code
22439@findex BP_BREAKPOINT
22440@findex gdb.BP_BREAKPOINT
22441@item BP_BREAKPOINT
22442Normal code breakpoint.
22443
22444@findex BP_WATCHPOINT
22445@findex gdb.BP_WATCHPOINT
22446@item BP_WATCHPOINT
22447Watchpoint breakpoint.
22448
22449@findex BP_HARDWARE_WATCHPOINT
22450@findex gdb.BP_HARDWARE_WATCHPOINT
22451@item BP_HARDWARE_WATCHPOINT
22452Hardware assisted watchpoint.
22453
22454@findex BP_READ_WATCHPOINT
22455@findex gdb.BP_READ_WATCHPOINT
22456@item BP_READ_WATCHPOINT
22457Hardware assisted read watchpoint.
22458
22459@findex BP_ACCESS_WATCHPOINT
22460@findex gdb.BP_ACCESS_WATCHPOINT
22461@item BP_ACCESS_WATCHPOINT
22462Hardware assisted access watchpoint.
22463@end table
22464
22465@defivar Breakpoint hit_count
22466This attribute holds the hit count for the breakpoint, an integer.
22467This attribute is writable, but currently it can only be set to zero.
22468@end defivar
22469
22470@defivar Breakpoint location
22471This attribute holds the location of the breakpoint, as specified by
22472the user. It is a string. If the breakpoint does not have a location
22473(that is, it is a watchpoint) the attribute's value is @code{None}. This
22474attribute is not writable.
22475@end defivar
22476
22477@defivar Breakpoint expression
22478This attribute holds a breakpoint expression, as specified by
22479the user. It is a string. If the breakpoint does not have an
22480expression (the breakpoint is not a watchpoint) the attribute's value
22481is @code{None}. This attribute is not writable.
22482@end defivar
22483
22484@defivar Breakpoint condition
22485This attribute holds the condition of the breakpoint, as specified by
22486the user. It is a string. If there is no condition, this attribute's
22487value is @code{None}. This attribute is writable.
22488@end defivar
22489
22490@defivar Breakpoint commands
22491This attribute holds the commands attached to the breakpoint. If
22492there are commands, this attribute's value is a string holding all the
22493commands, separated by newlines. If there are no commands, this
22494attribute is @code{None}. This attribute is not writable.
22495@end defivar
22496
be759fcf
PM
22497@node Lazy Strings In Python
22498@subsubsection Python representation of lazy strings.
22499
22500@cindex lazy strings in python
22501@tindex gdb.LazyString
22502
22503A @dfn{lazy string} is a string whose contents is not retrieved or
22504encoded until it is needed.
22505
22506A @code{gdb.LazyString} is represented in @value{GDBN} as an
22507@code{address} that points to a region of memory, an @code{encoding}
22508that will be used to encode that region of memory, and a @code{length}
22509to delimit the region of memory that represents the string. The
22510difference between a @code{gdb.LazyString} and a string wrapped within
22511a @code{gdb.Value} is that a @code{gdb.LazyString} will be treated
22512differently by @value{GDBN} when printing. A @code{gdb.LazyString} is
22513retrieved and encoded during printing, while a @code{gdb.Value}
22514wrapping a string is immediately retrieved and encoded on creation.
22515
22516A @code{gdb.LazyString} object has the following functions:
22517
22518@defmethod LazyString value
22519Convert the @code{gdb.LazyString} to a @code{gdb.Value}. This value
22520will point to the string in memory, but will lose all the delayed
22521retrieval, encoding and handling that @value{GDBN} applies to a
22522@code{gdb.LazyString}.
22523@end defmethod
22524
22525@defivar LazyString address
22526This attribute holds the address of the string. This attribute is not
22527writable.
22528@end defivar
22529
22530@defivar LazyString length
22531This attribute holds the length of the string in characters. If the
22532length is -1, then the string will be fetched and encoded up to the
22533first null of appropriate width. This attribute is not writable.
22534@end defivar
22535
22536@defivar LazyString encoding
22537This attribute holds the encoding that will be applied to the string
22538when the string is printed by @value{GDBN}. If the encoding is not
22539set, or contains an empty string, then @value{GDBN} will select the
22540most appropriate encoding when the string is printed. This attribute
22541is not writable.
22542@end defivar
22543
22544@defivar LazyString type
22545This attribute holds the type that is represented by the lazy string's
22546type. For a lazy string this will always be a pointer type. To
22547resolve this to the lazy string's character type, use the type's
22548@code{target} method. @xref{Types In Python}. This attribute is not
22549writable.
22550@end defivar
22551
8a1ea21f
DE
22552@node Auto-loading
22553@subsection Auto-loading
22554@cindex auto-loading, Python
22555
22556When a new object file is read (for example, due to the @code{file}
22557command, or because the inferior has loaded a shared library),
22558@value{GDBN} will look for Python support scripts in several ways:
22559@file{@var{objfile}-gdb.py} and @code{.debug_gdb_scripts} section.
22560
22561@menu
22562* objfile-gdb.py file:: The @file{@var{objfile}-gdb.py} file
22563* .debug_gdb_scripts section:: The @code{.debug_gdb_scripts} section
22564* Which flavor to choose?::
22565@end menu
22566
22567The auto-loading feature is useful for supplying application-specific
22568debugging commands and scripts.
22569
22570Auto-loading can be enabled or disabled.
22571
22572@table @code
22573@kindex maint set python auto-load
22574@item maint set python auto-load [yes|no]
22575Enable or disable the Python auto-loading feature.
22576
22577@kindex maint show python auto-load
22578@item maint show python auto-load
22579Show whether Python auto-loading is enabled or disabled.
22580@end table
22581
22582When reading an auto-loaded file, @value{GDBN} sets the
22583@dfn{current objfile}. This is available via the @code{gdb.current_objfile}
22584function (@pxref{Objfiles In Python}). This can be useful for
22585registering objfile-specific pretty-printers.
22586
22587@node objfile-gdb.py file
22588@subsubsection The @file{@var{objfile}-gdb.py} file
22589@cindex @file{@var{objfile}-gdb.py}
22590
22591When a new object file is read, @value{GDBN} looks for
22592a file named @file{@var{objfile}-gdb.py},
22593where @var{objfile} is the object file's real name, formed by ensuring
22594that the file name is absolute, following all symlinks, and resolving
22595@code{.} and @code{..} components. If this file exists and is
22596readable, @value{GDBN} will evaluate it as a Python script.
22597
22598If this file does not exist, and if the parameter
22599@code{debug-file-directory} is set (@pxref{Separate Debug Files}),
22600then @value{GDBN} will look for @var{real-name} in all of the
22601directories mentioned in the value of @code{debug-file-directory}.
22602
22603Finally, if this file does not exist, then @value{GDBN} will look for
22604a file named @file{@var{data-directory}/python/auto-load/@var{real-name}}, where
22605@var{data-directory} is @value{GDBN}'s data directory (available via
22606@code{show data-directory}, @pxref{Data Files}), and @var{real-name}
22607is the object file's real name, as described above.
22608
22609@value{GDBN} does not track which files it has already auto-loaded this way.
22610@value{GDBN} will load the associated script every time the corresponding
22611@var{objfile} is opened.
22612So your @file{-gdb.py} file should be careful to avoid errors if it
22613is evaluated more than once.
22614
22615@node .debug_gdb_scripts section
22616@subsubsection The @code{.debug_gdb_scripts} section
22617@cindex @code{.debug_gdb_scripts} section
22618
22619For systems using file formats like ELF and COFF,
22620when @value{GDBN} loads a new object file
22621it will look for a special section named @samp{.debug_gdb_scripts}.
22622If this section exists, its contents is a list of names of scripts to load.
22623
22624@value{GDBN} will look for each specified script file first in the
22625current directory and then along the source search path
22626(@pxref{Source Path, ,Specifying Source Directories}),
22627except that @file{$cdir} is not searched, since the compilation
22628directory is not relevant to scripts.
22629
22630Entries can be placed in section @code{.debug_gdb_scripts} with,
22631for example, this GCC macro:
22632
22633@example
22634/* Note: The "MS" section flags are to remote duplicates. */
22635#define DEFINE_GDB_SCRIPT(script_name) \
22636 asm("\
22637.pushsection \".debug_gdb_scripts\", \"MS\",@@progbits,1\n\
22638.byte 1\n\
22639.asciz \"" script_name "\"\n\
22640.popsection \n\
22641");
22642@end example
22643
22644@noindent
22645Then one can reference the macro in a header or source file like this:
22646
22647@example
22648DEFINE_GDB_SCRIPT ("my-app-scripts.py")
22649@end example
22650
22651The script name may include directories if desired.
22652
22653If the macro is put in a header, any application or library
22654using this header will get a reference to the specified script.
22655
22656@node Which flavor to choose?
22657@subsubsection Which flavor to choose?
22658
22659Given the multiple ways of auto-loading Python scripts, it might not always
22660be clear which one to choose. This section provides some guidance.
22661
22662Benefits of the @file{-gdb.py} way:
22663
22664@itemize @bullet
22665@item
22666Can be used with file formats that don't support multiple sections.
22667
22668@item
22669Ease of finding scripts for public libraries.
22670
22671Scripts specified in the @code{.debug_gdb_scripts} section are searched for
22672in the source search path.
22673For publicly installed libraries, e.g., @file{libstdc++}, there typically
22674isn't a source directory in which to find the script.
22675
22676@item
22677Doesn't require source code additions.
22678@end itemize
22679
22680Benefits of the @code{.debug_gdb_scripts} way:
22681
22682@itemize @bullet
22683@item
22684Works with static linking.
22685
22686Scripts for libraries done the @file{-gdb.py} way require an objfile to
22687trigger their loading. When an application is statically linked the only
22688objfile available is the executable, and it is cumbersome to attach all the
22689scripts from all the input libraries to the executable's @file{-gdb.py} script.
22690
22691@item
22692Works with classes that are entirely inlined.
22693
22694Some classes can be entirely inlined, and thus there may not be an associated
22695shared library to attach a @file{-gdb.py} script to.
22696
22697@item
22698Scripts needn't be copied out of the source tree.
22699
22700In some circumstances, apps can be built out of large collections of internal
22701libraries, and the build infrastructure necessary to install the
22702@file{-gdb.py} scripts in a place where @value{GDBN} can find them is
22703cumbersome. It may be easier to specify the scripts in the
22704@code{.debug_gdb_scripts} section as relative paths, and add a path to the
22705top of the source tree to the source search path.
22706@end itemize
22707
21c294e6
AC
22708@node Interpreters
22709@chapter Command Interpreters
22710@cindex command interpreters
22711
22712@value{GDBN} supports multiple command interpreters, and some command
22713infrastructure to allow users or user interface writers to switch
22714between interpreters or run commands in other interpreters.
22715
22716@value{GDBN} currently supports two command interpreters, the console
22717interpreter (sometimes called the command-line interpreter or @sc{cli})
22718and the machine interface interpreter (or @sc{gdb/mi}). This manual
22719describes both of these interfaces in great detail.
22720
22721By default, @value{GDBN} will start with the console interpreter.
22722However, the user may choose to start @value{GDBN} with another
22723interpreter by specifying the @option{-i} or @option{--interpreter}
22724startup options. Defined interpreters include:
22725
22726@table @code
22727@item console
22728@cindex console interpreter
22729The traditional console or command-line interpreter. This is the most often
22730used interpreter with @value{GDBN}. With no interpreter specified at runtime,
22731@value{GDBN} will use this interpreter.
22732
22733@item mi
22734@cindex mi interpreter
22735The newest @sc{gdb/mi} interface (currently @code{mi2}). Used primarily
22736by programs wishing to use @value{GDBN} as a backend for a debugger GUI
22737or an IDE. For more information, see @ref{GDB/MI, ,The @sc{gdb/mi}
22738Interface}.
22739
22740@item mi2
22741@cindex mi2 interpreter
22742The current @sc{gdb/mi} interface.
22743
22744@item mi1
22745@cindex mi1 interpreter
22746The @sc{gdb/mi} interface included in @value{GDBN} 5.1, 5.2, and 5.3.
22747
22748@end table
22749
22750@cindex invoke another interpreter
22751The interpreter being used by @value{GDBN} may not be dynamically
22752switched at runtime. Although possible, this could lead to a very
22753precarious situation. Consider an IDE using @sc{gdb/mi}. If a user
22754enters the command "interpreter-set console" in a console view,
22755@value{GDBN} would switch to using the console interpreter, rendering
22756the IDE inoperable!
22757
22758@kindex interpreter-exec
22759Although you may only choose a single interpreter at startup, you may execute
22760commands in any interpreter from the current interpreter using the appropriate
22761command. If you are running the console interpreter, simply use the
22762@code{interpreter-exec} command:
22763
22764@smallexample
22765interpreter-exec mi "-data-list-register-names"
22766@end smallexample
22767
22768@sc{gdb/mi} has a similar command, although it is only available in versions of
22769@value{GDBN} which support @sc{gdb/mi} version 2 (or greater).
22770
8e04817f
AC
22771@node TUI
22772@chapter @value{GDBN} Text User Interface
22773@cindex TUI
d0d5df6f 22774@cindex Text User Interface
c906108c 22775
8e04817f
AC
22776@menu
22777* TUI Overview:: TUI overview
22778* TUI Keys:: TUI key bindings
7cf36c78 22779* TUI Single Key Mode:: TUI single key mode
db2e3e2e 22780* TUI Commands:: TUI-specific commands
8e04817f
AC
22781* TUI Configuration:: TUI configuration variables
22782@end menu
c906108c 22783
46ba6afa 22784The @value{GDBN} Text User Interface (TUI) is a terminal
d0d5df6f
AC
22785interface which uses the @code{curses} library to show the source
22786file, the assembly output, the program registers and @value{GDBN}
46ba6afa
BW
22787commands in separate text windows. The TUI mode is supported only
22788on platforms where a suitable version of the @code{curses} library
22789is available.
d0d5df6f 22790
46ba6afa
BW
22791@pindex @value{GDBTUI}
22792The TUI mode is enabled by default when you invoke @value{GDBN} as
22793either @samp{@value{GDBTUI}} or @samp{@value{GDBP} -tui}.
22794You can also switch in and out of TUI mode while @value{GDBN} runs by
22795using various TUI commands and key bindings, such as @kbd{C-x C-a}.
22796@xref{TUI Keys, ,TUI Key Bindings}.
c906108c 22797
8e04817f 22798@node TUI Overview
79a6e687 22799@section TUI Overview
c906108c 22800
46ba6afa 22801In TUI mode, @value{GDBN} can display several text windows:
c906108c 22802
8e04817f
AC
22803@table @emph
22804@item command
22805This window is the @value{GDBN} command window with the @value{GDBN}
46ba6afa
BW
22806prompt and the @value{GDBN} output. The @value{GDBN} input is still
22807managed using readline.
c906108c 22808
8e04817f
AC
22809@item source
22810The source window shows the source file of the program. The current
46ba6afa 22811line and active breakpoints are displayed in this window.
c906108c 22812
8e04817f
AC
22813@item assembly
22814The assembly window shows the disassembly output of the program.
c906108c 22815
8e04817f 22816@item register
46ba6afa
BW
22817This window shows the processor registers. Registers are highlighted
22818when their values change.
c906108c
SS
22819@end table
22820
269c21fe 22821The source and assembly windows show the current program position
46ba6afa
BW
22822by highlighting the current line and marking it with a @samp{>} marker.
22823Breakpoints are indicated with two markers. The first marker
269c21fe
SC
22824indicates the breakpoint type:
22825
22826@table @code
22827@item B
22828Breakpoint which was hit at least once.
22829
22830@item b
22831Breakpoint which was never hit.
22832
22833@item H
22834Hardware breakpoint which was hit at least once.
22835
22836@item h
22837Hardware breakpoint which was never hit.
269c21fe
SC
22838@end table
22839
22840The second marker indicates whether the breakpoint is enabled or not:
22841
22842@table @code
22843@item +
22844Breakpoint is enabled.
22845
22846@item -
22847Breakpoint is disabled.
269c21fe
SC
22848@end table
22849
46ba6afa
BW
22850The source, assembly and register windows are updated when the current
22851thread changes, when the frame changes, or when the program counter
22852changes.
22853
22854These windows are not all visible at the same time. The command
22855window is always visible. The others can be arranged in several
22856layouts:
c906108c 22857
8e04817f
AC
22858@itemize @bullet
22859@item
46ba6afa 22860source only,
2df3850c 22861
8e04817f 22862@item
46ba6afa 22863assembly only,
8e04817f
AC
22864
22865@item
46ba6afa 22866source and assembly,
8e04817f
AC
22867
22868@item
46ba6afa 22869source and registers, or
c906108c 22870
8e04817f 22871@item
46ba6afa 22872assembly and registers.
8e04817f 22873@end itemize
c906108c 22874
46ba6afa 22875A status line above the command window shows the following information:
b7bb15bc
SC
22876
22877@table @emph
22878@item target
46ba6afa 22879Indicates the current @value{GDBN} target.
b7bb15bc
SC
22880(@pxref{Targets, ,Specifying a Debugging Target}).
22881
22882@item process
46ba6afa 22883Gives the current process or thread number.
b7bb15bc
SC
22884When no process is being debugged, this field is set to @code{No process}.
22885
22886@item function
22887Gives the current function name for the selected frame.
22888The name is demangled if demangling is turned on (@pxref{Print Settings}).
46ba6afa 22889When there is no symbol corresponding to the current program counter,
b7bb15bc
SC
22890the string @code{??} is displayed.
22891
22892@item line
22893Indicates the current line number for the selected frame.
46ba6afa 22894When the current line number is not known, the string @code{??} is displayed.
b7bb15bc
SC
22895
22896@item pc
22897Indicates the current program counter address.
b7bb15bc
SC
22898@end table
22899
8e04817f
AC
22900@node TUI Keys
22901@section TUI Key Bindings
22902@cindex TUI key bindings
c906108c 22903
8e04817f 22904The TUI installs several key bindings in the readline keymaps
46ba6afa 22905(@pxref{Command Line Editing}). The following key bindings
8e04817f 22906are installed for both TUI mode and the @value{GDBN} standard mode.
c906108c 22907
8e04817f
AC
22908@table @kbd
22909@kindex C-x C-a
22910@item C-x C-a
22911@kindex C-x a
22912@itemx C-x a
22913@kindex C-x A
22914@itemx C-x A
46ba6afa
BW
22915Enter or leave the TUI mode. When leaving the TUI mode,
22916the curses window management stops and @value{GDBN} operates using
22917its standard mode, writing on the terminal directly. When reentering
22918the TUI mode, control is given back to the curses windows.
8e04817f 22919The screen is then refreshed.
c906108c 22920
8e04817f
AC
22921@kindex C-x 1
22922@item C-x 1
22923Use a TUI layout with only one window. The layout will
22924either be @samp{source} or @samp{assembly}. When the TUI mode
22925is not active, it will switch to the TUI mode.
2df3850c 22926
8e04817f 22927Think of this key binding as the Emacs @kbd{C-x 1} binding.
c906108c 22928
8e04817f
AC
22929@kindex C-x 2
22930@item C-x 2
22931Use a TUI layout with at least two windows. When the current
46ba6afa 22932layout already has two windows, the next layout with two windows is used.
8e04817f
AC
22933When a new layout is chosen, one window will always be common to the
22934previous layout and the new one.
c906108c 22935
8e04817f 22936Think of it as the Emacs @kbd{C-x 2} binding.
2df3850c 22937
72ffddc9
SC
22938@kindex C-x o
22939@item C-x o
22940Change the active window. The TUI associates several key bindings
46ba6afa 22941(like scrolling and arrow keys) with the active window. This command
72ffddc9
SC
22942gives the focus to the next TUI window.
22943
22944Think of it as the Emacs @kbd{C-x o} binding.
22945
7cf36c78
SC
22946@kindex C-x s
22947@item C-x s
46ba6afa
BW
22948Switch in and out of the TUI SingleKey mode that binds single
22949keys to @value{GDBN} commands (@pxref{TUI Single Key Mode}).
c906108c
SS
22950@end table
22951
46ba6afa 22952The following key bindings only work in the TUI mode:
5d161b24 22953
46ba6afa 22954@table @asis
8e04817f 22955@kindex PgUp
46ba6afa 22956@item @key{PgUp}
8e04817f 22957Scroll the active window one page up.
c906108c 22958
8e04817f 22959@kindex PgDn
46ba6afa 22960@item @key{PgDn}
8e04817f 22961Scroll the active window one page down.
c906108c 22962
8e04817f 22963@kindex Up
46ba6afa 22964@item @key{Up}
8e04817f 22965Scroll the active window one line up.
c906108c 22966
8e04817f 22967@kindex Down
46ba6afa 22968@item @key{Down}
8e04817f 22969Scroll the active window one line down.
c906108c 22970
8e04817f 22971@kindex Left
46ba6afa 22972@item @key{Left}
8e04817f 22973Scroll the active window one column left.
c906108c 22974
8e04817f 22975@kindex Right
46ba6afa 22976@item @key{Right}
8e04817f 22977Scroll the active window one column right.
c906108c 22978
8e04817f 22979@kindex C-L
46ba6afa 22980@item @kbd{C-L}
8e04817f 22981Refresh the screen.
8e04817f 22982@end table
c906108c 22983
46ba6afa
BW
22984Because the arrow keys scroll the active window in the TUI mode, they
22985are not available for their normal use by readline unless the command
22986window has the focus. When another window is active, you must use
22987other readline key bindings such as @kbd{C-p}, @kbd{C-n}, @kbd{C-b}
22988and @kbd{C-f} to control the command window.
8e04817f 22989
7cf36c78
SC
22990@node TUI Single Key Mode
22991@section TUI Single Key Mode
22992@cindex TUI single key mode
22993
46ba6afa
BW
22994The TUI also provides a @dfn{SingleKey} mode, which binds several
22995frequently used @value{GDBN} commands to single keys. Type @kbd{C-x s} to
22996switch into this mode, where the following key bindings are used:
7cf36c78
SC
22997
22998@table @kbd
22999@kindex c @r{(SingleKey TUI key)}
23000@item c
23001continue
23002
23003@kindex d @r{(SingleKey TUI key)}
23004@item d
23005down
23006
23007@kindex f @r{(SingleKey TUI key)}
23008@item f
23009finish
23010
23011@kindex n @r{(SingleKey TUI key)}
23012@item n
23013next
23014
23015@kindex q @r{(SingleKey TUI key)}
23016@item q
46ba6afa 23017exit the SingleKey mode.
7cf36c78
SC
23018
23019@kindex r @r{(SingleKey TUI key)}
23020@item r
23021run
23022
23023@kindex s @r{(SingleKey TUI key)}
23024@item s
23025step
23026
23027@kindex u @r{(SingleKey TUI key)}
23028@item u
23029up
23030
23031@kindex v @r{(SingleKey TUI key)}
23032@item v
23033info locals
23034
23035@kindex w @r{(SingleKey TUI key)}
23036@item w
23037where
7cf36c78
SC
23038@end table
23039
23040Other keys temporarily switch to the @value{GDBN} command prompt.
23041The key that was pressed is inserted in the editing buffer so that
23042it is possible to type most @value{GDBN} commands without interaction
46ba6afa
BW
23043with the TUI SingleKey mode. Once the command is entered the TUI
23044SingleKey mode is restored. The only way to permanently leave
7f9087cb 23045this mode is by typing @kbd{q} or @kbd{C-x s}.
7cf36c78
SC
23046
23047
8e04817f 23048@node TUI Commands
db2e3e2e 23049@section TUI-specific Commands
8e04817f
AC
23050@cindex TUI commands
23051
23052The TUI has specific commands to control the text windows.
46ba6afa
BW
23053These commands are always available, even when @value{GDBN} is not in
23054the TUI mode. When @value{GDBN} is in the standard mode, most
23055of these commands will automatically switch to the TUI mode.
c906108c 23056
ff12863f
PA
23057Note that if @value{GDBN}'s @code{stdout} is not connected to a
23058terminal, or @value{GDBN} has been started with the machine interface
23059interpreter (@pxref{GDB/MI, ,The @sc{gdb/mi} Interface}), most of
23060these commands will fail with an error, because it would not be
23061possible or desirable to enable curses window management.
23062
c906108c 23063@table @code
3d757584
SC
23064@item info win
23065@kindex info win
23066List and give the size of all displayed windows.
23067
8e04817f 23068@item layout next
4644b6e3 23069@kindex layout
8e04817f 23070Display the next layout.
2df3850c 23071
8e04817f 23072@item layout prev
8e04817f 23073Display the previous layout.
c906108c 23074
8e04817f 23075@item layout src
8e04817f 23076Display the source window only.
c906108c 23077
8e04817f 23078@item layout asm
8e04817f 23079Display the assembly window only.
c906108c 23080
8e04817f 23081@item layout split
8e04817f 23082Display the source and assembly window.
c906108c 23083
8e04817f 23084@item layout regs
8e04817f
AC
23085Display the register window together with the source or assembly window.
23086
46ba6afa 23087@item focus next
8e04817f 23088@kindex focus
46ba6afa
BW
23089Make the next window active for scrolling.
23090
23091@item focus prev
23092Make the previous window active for scrolling.
23093
23094@item focus src
23095Make the source window active for scrolling.
23096
23097@item focus asm
23098Make the assembly window active for scrolling.
23099
23100@item focus regs
23101Make the register window active for scrolling.
23102
23103@item focus cmd
23104Make the command window active for scrolling.
c906108c 23105
8e04817f
AC
23106@item refresh
23107@kindex refresh
7f9087cb 23108Refresh the screen. This is similar to typing @kbd{C-L}.
c906108c 23109
6a1b180d
SC
23110@item tui reg float
23111@kindex tui reg
23112Show the floating point registers in the register window.
23113
23114@item tui reg general
23115Show the general registers in the register window.
23116
23117@item tui reg next
23118Show the next register group. The list of register groups as well as
23119their order is target specific. The predefined register groups are the
23120following: @code{general}, @code{float}, @code{system}, @code{vector},
23121@code{all}, @code{save}, @code{restore}.
23122
23123@item tui reg system
23124Show the system registers in the register window.
23125
8e04817f
AC
23126@item update
23127@kindex update
23128Update the source window and the current execution point.
c906108c 23129
8e04817f
AC
23130@item winheight @var{name} +@var{count}
23131@itemx winheight @var{name} -@var{count}
23132@kindex winheight
23133Change the height of the window @var{name} by @var{count}
23134lines. Positive counts increase the height, while negative counts
23135decrease it.
2df3850c 23136
46ba6afa
BW
23137@item tabset @var{nchars}
23138@kindex tabset
c45da7e6 23139Set the width of tab stops to be @var{nchars} characters.
c906108c
SS
23140@end table
23141
8e04817f 23142@node TUI Configuration
79a6e687 23143@section TUI Configuration Variables
8e04817f 23144@cindex TUI configuration variables
c906108c 23145
46ba6afa 23146Several configuration variables control the appearance of TUI windows.
c906108c 23147
8e04817f
AC
23148@table @code
23149@item set tui border-kind @var{kind}
23150@kindex set tui border-kind
23151Select the border appearance for the source, assembly and register windows.
23152The possible values are the following:
23153@table @code
23154@item space
23155Use a space character to draw the border.
c906108c 23156
8e04817f 23157@item ascii
46ba6afa 23158Use @sc{ascii} characters @samp{+}, @samp{-} and @samp{|} to draw the border.
c906108c 23159
8e04817f
AC
23160@item acs
23161Use the Alternate Character Set to draw the border. The border is
23162drawn using character line graphics if the terminal supports them.
8e04817f 23163@end table
c78b4128 23164
8e04817f
AC
23165@item set tui border-mode @var{mode}
23166@kindex set tui border-mode
46ba6afa
BW
23167@itemx set tui active-border-mode @var{mode}
23168@kindex set tui active-border-mode
23169Select the display attributes for the borders of the inactive windows
23170or the active window. The @var{mode} can be one of the following:
8e04817f
AC
23171@table @code
23172@item normal
23173Use normal attributes to display the border.
c906108c 23174
8e04817f
AC
23175@item standout
23176Use standout mode.
c906108c 23177
8e04817f
AC
23178@item reverse
23179Use reverse video mode.
c906108c 23180
8e04817f
AC
23181@item half
23182Use half bright mode.
c906108c 23183
8e04817f
AC
23184@item half-standout
23185Use half bright and standout mode.
c906108c 23186
8e04817f
AC
23187@item bold
23188Use extra bright or bold mode.
c78b4128 23189
8e04817f
AC
23190@item bold-standout
23191Use extra bright or bold and standout mode.
8e04817f 23192@end table
8e04817f 23193@end table
c78b4128 23194
8e04817f
AC
23195@node Emacs
23196@chapter Using @value{GDBN} under @sc{gnu} Emacs
c78b4128 23197
8e04817f
AC
23198@cindex Emacs
23199@cindex @sc{gnu} Emacs
23200A special interface allows you to use @sc{gnu} Emacs to view (and
23201edit) the source files for the program you are debugging with
23202@value{GDBN}.
c906108c 23203
8e04817f
AC
23204To use this interface, use the command @kbd{M-x gdb} in Emacs. Give the
23205executable file you want to debug as an argument. This command starts
23206@value{GDBN} as a subprocess of Emacs, with input and output through a newly
23207created Emacs buffer.
23208@c (Do not use the @code{-tui} option to run @value{GDBN} from Emacs.)
c906108c 23209
5e252a2e 23210Running @value{GDBN} under Emacs can be just like running @value{GDBN} normally except for two
8e04817f 23211things:
c906108c 23212
8e04817f
AC
23213@itemize @bullet
23214@item
5e252a2e
NR
23215All ``terminal'' input and output goes through an Emacs buffer, called
23216the GUD buffer.
c906108c 23217
8e04817f
AC
23218This applies both to @value{GDBN} commands and their output, and to the input
23219and output done by the program you are debugging.
bf0184be 23220
8e04817f
AC
23221This is useful because it means that you can copy the text of previous
23222commands and input them again; you can even use parts of the output
23223in this way.
bf0184be 23224
8e04817f
AC
23225All the facilities of Emacs' Shell mode are available for interacting
23226with your program. In particular, you can send signals the usual
23227way---for example, @kbd{C-c C-c} for an interrupt, @kbd{C-c C-z} for a
23228stop.
bf0184be
ND
23229
23230@item
8e04817f 23231@value{GDBN} displays source code through Emacs.
bf0184be 23232
8e04817f
AC
23233Each time @value{GDBN} displays a stack frame, Emacs automatically finds the
23234source file for that frame and puts an arrow (@samp{=>}) at the
23235left margin of the current line. Emacs uses a separate buffer for
23236source display, and splits the screen to show both your @value{GDBN} session
23237and the source.
bf0184be 23238
8e04817f
AC
23239Explicit @value{GDBN} @code{list} or search commands still produce output as
23240usual, but you probably have no reason to use them from Emacs.
5e252a2e
NR
23241@end itemize
23242
23243We call this @dfn{text command mode}. Emacs 22.1, and later, also uses
23244a graphical mode, enabled by default, which provides further buffers
23245that can control the execution and describe the state of your program.
23246@xref{GDB Graphical Interface,,, Emacs, The @sc{gnu} Emacs Manual}.
c906108c 23247
64fabec2
AC
23248If you specify an absolute file name when prompted for the @kbd{M-x
23249gdb} argument, then Emacs sets your current working directory to where
23250your program resides. If you only specify the file name, then Emacs
23251sets your current working directory to to the directory associated
23252with the previous buffer. In this case, @value{GDBN} may find your
23253program by searching your environment's @code{PATH} variable, but on
23254some operating systems it might not find the source. So, although the
23255@value{GDBN} input and output session proceeds normally, the auxiliary
23256buffer does not display the current source and line of execution.
23257
23258The initial working directory of @value{GDBN} is printed on the top
5e252a2e
NR
23259line of the GUD buffer and this serves as a default for the commands
23260that specify files for @value{GDBN} to operate on. @xref{Files,
23261,Commands to Specify Files}.
64fabec2
AC
23262
23263By default, @kbd{M-x gdb} calls the program called @file{gdb}. If you
23264need to call @value{GDBN} by a different name (for example, if you
23265keep several configurations around, with different names) you can
23266customize the Emacs variable @code{gud-gdb-command-name} to run the
23267one you want.
8e04817f 23268
5e252a2e 23269In the GUD buffer, you can use these special Emacs commands in
8e04817f 23270addition to the standard Shell mode commands:
c906108c 23271
8e04817f
AC
23272@table @kbd
23273@item C-h m
5e252a2e 23274Describe the features of Emacs' GUD Mode.
c906108c 23275
64fabec2 23276@item C-c C-s
8e04817f
AC
23277Execute to another source line, like the @value{GDBN} @code{step} command; also
23278update the display window to show the current file and location.
c906108c 23279
64fabec2 23280@item C-c C-n
8e04817f
AC
23281Execute to next source line in this function, skipping all function
23282calls, like the @value{GDBN} @code{next} command. Then update the display window
23283to show the current file and location.
c906108c 23284
64fabec2 23285@item C-c C-i
8e04817f
AC
23286Execute one instruction, like the @value{GDBN} @code{stepi} command; update
23287display window accordingly.
c906108c 23288
8e04817f
AC
23289@item C-c C-f
23290Execute until exit from the selected stack frame, like the @value{GDBN}
23291@code{finish} command.
c906108c 23292
64fabec2 23293@item C-c C-r
8e04817f
AC
23294Continue execution of your program, like the @value{GDBN} @code{continue}
23295command.
b433d00b 23296
64fabec2 23297@item C-c <
8e04817f
AC
23298Go up the number of frames indicated by the numeric argument
23299(@pxref{Arguments, , Numeric Arguments, Emacs, The @sc{gnu} Emacs Manual}),
23300like the @value{GDBN} @code{up} command.
b433d00b 23301
64fabec2 23302@item C-c >
8e04817f
AC
23303Go down the number of frames indicated by the numeric argument, like the
23304@value{GDBN} @code{down} command.
8e04817f 23305@end table
c906108c 23306
7f9087cb 23307In any source file, the Emacs command @kbd{C-x @key{SPC}} (@code{gud-break})
8e04817f 23308tells @value{GDBN} to set a breakpoint on the source line point is on.
c906108c 23309
5e252a2e
NR
23310In text command mode, if you type @kbd{M-x speedbar}, Emacs displays a
23311separate frame which shows a backtrace when the GUD buffer is current.
23312Move point to any frame in the stack and type @key{RET} to make it
23313become the current frame and display the associated source in the
23314source buffer. Alternatively, click @kbd{Mouse-2} to make the
23315selected frame become the current one. In graphical mode, the
23316speedbar displays watch expressions.
64fabec2 23317
8e04817f
AC
23318If you accidentally delete the source-display buffer, an easy way to get
23319it back is to type the command @code{f} in the @value{GDBN} buffer, to
23320request a frame display; when you run under Emacs, this recreates
23321the source buffer if necessary to show you the context of the current
23322frame.
c906108c 23323
8e04817f
AC
23324The source files displayed in Emacs are in ordinary Emacs buffers
23325which are visiting the source files in the usual way. You can edit
23326the files with these buffers if you wish; but keep in mind that @value{GDBN}
23327communicates with Emacs in terms of line numbers. If you add or
23328delete lines from the text, the line numbers that @value{GDBN} knows cease
23329to correspond properly with the code.
b383017d 23330
5e252a2e
NR
23331A more detailed description of Emacs' interaction with @value{GDBN} is
23332given in the Emacs manual (@pxref{Debuggers,,, Emacs, The @sc{gnu}
23333Emacs Manual}).
c906108c 23334
8e04817f
AC
23335@c The following dropped because Epoch is nonstandard. Reactivate
23336@c if/when v19 does something similar. ---doc@cygnus.com 19dec1990
23337@ignore
23338@kindex Emacs Epoch environment
23339@kindex Epoch
23340@kindex inspect
c906108c 23341
8e04817f
AC
23342Version 18 of @sc{gnu} Emacs has a built-in window system
23343called the @code{epoch}
23344environment. Users of this environment can use a new command,
23345@code{inspect} which performs identically to @code{print} except that
23346each value is printed in its own window.
23347@end ignore
c906108c 23348
922fbb7b
AC
23349
23350@node GDB/MI
23351@chapter The @sc{gdb/mi} Interface
23352
23353@unnumberedsec Function and Purpose
23354
23355@cindex @sc{gdb/mi}, its purpose
6b5e8c01
NR
23356@sc{gdb/mi} is a line based machine oriented text interface to
23357@value{GDBN} and is activated by specifying using the
23358@option{--interpreter} command line option (@pxref{Mode Options}). It
23359is specifically intended to support the development of systems which
23360use the debugger as just one small component of a larger system.
922fbb7b
AC
23361
23362This chapter is a specification of the @sc{gdb/mi} interface. It is written
23363in the form of a reference manual.
23364
23365Note that @sc{gdb/mi} is still under construction, so some of the
af6eff6f
NR
23366features described below are incomplete and subject to change
23367(@pxref{GDB/MI Development and Front Ends, , @sc{gdb/mi} Development and Front Ends}).
922fbb7b
AC
23368
23369@unnumberedsec Notation and Terminology
23370
23371@cindex notational conventions, for @sc{gdb/mi}
23372This chapter uses the following notation:
23373
23374@itemize @bullet
23375@item
23376@code{|} separates two alternatives.
23377
23378@item
23379@code{[ @var{something} ]} indicates that @var{something} is optional:
23380it may or may not be given.
23381
23382@item
23383@code{( @var{group} )*} means that @var{group} inside the parentheses
23384may repeat zero or more times.
23385
23386@item
23387@code{( @var{group} )+} means that @var{group} inside the parentheses
23388may repeat one or more times.
23389
23390@item
23391@code{"@var{string}"} means a literal @var{string}.
23392@end itemize
23393
23394@ignore
23395@heading Dependencies
23396@end ignore
23397
922fbb7b 23398@menu
c3b108f7 23399* GDB/MI General Design::
922fbb7b
AC
23400* GDB/MI Command Syntax::
23401* GDB/MI Compatibility with CLI::
af6eff6f 23402* GDB/MI Development and Front Ends::
922fbb7b 23403* GDB/MI Output Records::
ef21caaf 23404* GDB/MI Simple Examples::
922fbb7b 23405* GDB/MI Command Description Format::
ef21caaf 23406* GDB/MI Breakpoint Commands::
a2c02241
NR
23407* GDB/MI Program Context::
23408* GDB/MI Thread Commands::
23409* GDB/MI Program Execution::
23410* GDB/MI Stack Manipulation::
23411* GDB/MI Variable Objects::
922fbb7b 23412* GDB/MI Data Manipulation::
a2c02241
NR
23413* GDB/MI Tracepoint Commands::
23414* GDB/MI Symbol Query::
351ff01a 23415* GDB/MI File Commands::
922fbb7b
AC
23416@ignore
23417* GDB/MI Kod Commands::
23418* GDB/MI Memory Overlay Commands::
23419* GDB/MI Signal Handling Commands::
23420@end ignore
922fbb7b 23421* GDB/MI Target Manipulation::
a6b151f1 23422* GDB/MI File Transfer Commands::
ef21caaf 23423* GDB/MI Miscellaneous Commands::
922fbb7b
AC
23424@end menu
23425
c3b108f7
VP
23426@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
23427@node GDB/MI General Design
23428@section @sc{gdb/mi} General Design
23429@cindex GDB/MI General Design
23430
23431Interaction of a @sc{GDB/MI} frontend with @value{GDBN} involves three
23432parts---commands sent to @value{GDBN}, responses to those commands
23433and notifications. Each command results in exactly one response,
23434indicating either successful completion of the command, or an error.
23435For the commands that do not resume the target, the response contains the
23436requested information. For the commands that resume the target, the
23437response only indicates whether the target was successfully resumed.
23438Notifications is the mechanism for reporting changes in the state of the
23439target, or in @value{GDBN} state, that cannot conveniently be associated with
23440a command and reported as part of that command response.
23441
23442The important examples of notifications are:
23443@itemize @bullet
23444
23445@item
23446Exec notifications. These are used to report changes in
23447target state---when a target is resumed, or stopped. It would not
23448be feasible to include this information in response of resuming
23449commands, because one resume commands can result in multiple events in
23450different threads. Also, quite some time may pass before any event
23451happens in the target, while a frontend needs to know whether the resuming
23452command itself was successfully executed.
23453
23454@item
23455Console output, and status notifications. Console output
23456notifications are used to report output of CLI commands, as well as
23457diagnostics for other commands. Status notifications are used to
23458report the progress of a long-running operation. Naturally, including
23459this information in command response would mean no output is produced
23460until the command is finished, which is undesirable.
23461
23462@item
23463General notifications. Commands may have various side effects on
23464the @value{GDBN} or target state beyond their official purpose. For example,
23465a command may change the selected thread. Although such changes can
23466be included in command response, using notification allows for more
23467orthogonal frontend design.
23468
23469@end itemize
23470
23471There's no guarantee that whenever an MI command reports an error,
23472@value{GDBN} or the target are in any specific state, and especially,
23473the state is not reverted to the state before the MI command was
23474processed. Therefore, whenever an MI command results in an error,
23475we recommend that the frontend refreshes all the information shown in
23476the user interface.
23477
508094de
NR
23478
23479@menu
23480* Context management::
23481* Asynchronous and non-stop modes::
23482* Thread groups::
23483@end menu
23484
23485@node Context management
c3b108f7
VP
23486@subsection Context management
23487
23488In most cases when @value{GDBN} accesses the target, this access is
23489done in context of a specific thread and frame (@pxref{Frames}).
23490Often, even when accessing global data, the target requires that a thread
23491be specified. The CLI interface maintains the selected thread and frame,
23492and supplies them to target on each command. This is convenient,
23493because a command line user would not want to specify that information
23494explicitly on each command, and because user interacts with
23495@value{GDBN} via a single terminal, so no confusion is possible as
23496to what thread and frame are the current ones.
23497
23498In the case of MI, the concept of selected thread and frame is less
23499useful. First, a frontend can easily remember this information
23500itself. Second, a graphical frontend can have more than one window,
23501each one used for debugging a different thread, and the frontend might
23502want to access additional threads for internal purposes. This
23503increases the risk that by relying on implicitly selected thread, the
23504frontend may be operating on a wrong one. Therefore, each MI command
23505should explicitly specify which thread and frame to operate on. To
23506make it possible, each MI command accepts the @samp{--thread} and
23507@samp{--frame} options, the value to each is @value{GDBN} identifier
23508for thread and frame to operate on.
23509
23510Usually, each top-level window in a frontend allows the user to select
23511a thread and a frame, and remembers the user selection for further
23512operations. However, in some cases @value{GDBN} may suggest that the
23513current thread be changed. For example, when stopping on a breakpoint
23514it is reasonable to switch to the thread where breakpoint is hit. For
23515another example, if the user issues the CLI @samp{thread} command via
23516the frontend, it is desirable to change the frontend's selected thread to the
23517one specified by user. @value{GDBN} communicates the suggestion to
23518change current thread using the @samp{=thread-selected} notification.
23519No such notification is available for the selected frame at the moment.
23520
23521Note that historically, MI shares the selected thread with CLI, so
23522frontends used the @code{-thread-select} to execute commands in the
23523right context. However, getting this to work right is cumbersome. The
23524simplest way is for frontend to emit @code{-thread-select} command
23525before every command. This doubles the number of commands that need
23526to be sent. The alternative approach is to suppress @code{-thread-select}
23527if the selected thread in @value{GDBN} is supposed to be identical to the
23528thread the frontend wants to operate on. However, getting this
23529optimization right can be tricky. In particular, if the frontend
23530sends several commands to @value{GDBN}, and one of the commands changes the
23531selected thread, then the behaviour of subsequent commands will
23532change. So, a frontend should either wait for response from such
23533problematic commands, or explicitly add @code{-thread-select} for
23534all subsequent commands. No frontend is known to do this exactly
23535right, so it is suggested to just always pass the @samp{--thread} and
23536@samp{--frame} options.
23537
508094de 23538@node Asynchronous and non-stop modes
c3b108f7
VP
23539@subsection Asynchronous command execution and non-stop mode
23540
23541On some targets, @value{GDBN} is capable of processing MI commands
23542even while the target is running. This is called @dfn{asynchronous
23543command execution} (@pxref{Background Execution}). The frontend may
23544specify a preferrence for asynchronous execution using the
23545@code{-gdb-set target-async 1} command, which should be emitted before
23546either running the executable or attaching to the target. After the
23547frontend has started the executable or attached to the target, it can
23548find if asynchronous execution is enabled using the
23549@code{-list-target-features} command.
23550
23551Even if @value{GDBN} can accept a command while target is running,
23552many commands that access the target do not work when the target is
23553running. Therefore, asynchronous command execution is most useful
23554when combined with non-stop mode (@pxref{Non-Stop Mode}). Then,
23555it is possible to examine the state of one thread, while other threads
23556are running.
23557
23558When a given thread is running, MI commands that try to access the
23559target in the context of that thread may not work, or may work only on
23560some targets. In particular, commands that try to operate on thread's
23561stack will not work, on any target. Commands that read memory, or
23562modify breakpoints, may work or not work, depending on the target. Note
23563that even commands that operate on global state, such as @code{print},
23564@code{set}, and breakpoint commands, still access the target in the
23565context of a specific thread, so frontend should try to find a
23566stopped thread and perform the operation on that thread (using the
23567@samp{--thread} option).
23568
23569Which commands will work in the context of a running thread is
23570highly target dependent. However, the two commands
23571@code{-exec-interrupt}, to stop a thread, and @code{-thread-info},
23572to find the state of a thread, will always work.
23573
508094de 23574@node Thread groups
c3b108f7
VP
23575@subsection Thread groups
23576@value{GDBN} may be used to debug several processes at the same time.
23577On some platfroms, @value{GDBN} may support debugging of several
23578hardware systems, each one having several cores with several different
23579processes running on each core. This section describes the MI
23580mechanism to support such debugging scenarios.
23581
23582The key observation is that regardless of the structure of the
23583target, MI can have a global list of threads, because most commands that
23584accept the @samp{--thread} option do not need to know what process that
23585thread belongs to. Therefore, it is not necessary to introduce
23586neither additional @samp{--process} option, nor an notion of the
23587current process in the MI interface. The only strictly new feature
23588that is required is the ability to find how the threads are grouped
23589into processes.
23590
23591To allow the user to discover such grouping, and to support arbitrary
23592hierarchy of machines/cores/processes, MI introduces the concept of a
23593@dfn{thread group}. Thread group is a collection of threads and other
23594thread groups. A thread group always has a string identifier, a type,
23595and may have additional attributes specific to the type. A new
23596command, @code{-list-thread-groups}, returns the list of top-level
23597thread groups, which correspond to processes that @value{GDBN} is
23598debugging at the moment. By passing an identifier of a thread group
23599to the @code{-list-thread-groups} command, it is possible to obtain
23600the members of specific thread group.
23601
23602To allow the user to easily discover processes, and other objects, he
23603wishes to debug, a concept of @dfn{available thread group} is
23604introduced. Available thread group is an thread group that
23605@value{GDBN} is not debugging, but that can be attached to, using the
23606@code{-target-attach} command. The list of available top-level thread
23607groups can be obtained using @samp{-list-thread-groups --available}.
23608In general, the content of a thread group may be only retrieved only
23609after attaching to that thread group.
23610
a79b8f6e
VP
23611Thread groups are related to inferiors (@pxref{Inferiors and
23612Programs}). Each inferior corresponds to a thread group of a special
23613type @samp{process}, and some additional operations are permitted on
23614such thread groups.
23615
922fbb7b
AC
23616@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
23617@node GDB/MI Command Syntax
23618@section @sc{gdb/mi} Command Syntax
23619
23620@menu
23621* GDB/MI Input Syntax::
23622* GDB/MI Output Syntax::
922fbb7b
AC
23623@end menu
23624
23625@node GDB/MI Input Syntax
23626@subsection @sc{gdb/mi} Input Syntax
23627
23628@cindex input syntax for @sc{gdb/mi}
23629@cindex @sc{gdb/mi}, input syntax
23630@table @code
23631@item @var{command} @expansion{}
23632@code{@var{cli-command} | @var{mi-command}}
23633
23634@item @var{cli-command} @expansion{}
23635@code{[ @var{token} ] @var{cli-command} @var{nl}}, where
23636@var{cli-command} is any existing @value{GDBN} CLI command.
23637
23638@item @var{mi-command} @expansion{}
23639@code{[ @var{token} ] "-" @var{operation} ( " " @var{option} )*
23640@code{[} " --" @code{]} ( " " @var{parameter} )* @var{nl}}
23641
23642@item @var{token} @expansion{}
23643"any sequence of digits"
23644
23645@item @var{option} @expansion{}
23646@code{"-" @var{parameter} [ " " @var{parameter} ]}
23647
23648@item @var{parameter} @expansion{}
23649@code{@var{non-blank-sequence} | @var{c-string}}
23650
23651@item @var{operation} @expansion{}
23652@emph{any of the operations described in this chapter}
23653
23654@item @var{non-blank-sequence} @expansion{}
23655@emph{anything, provided it doesn't contain special characters such as
23656"-", @var{nl}, """ and of course " "}
23657
23658@item @var{c-string} @expansion{}
23659@code{""" @var{seven-bit-iso-c-string-content} """}
23660
23661@item @var{nl} @expansion{}
23662@code{CR | CR-LF}
23663@end table
23664
23665@noindent
23666Notes:
23667
23668@itemize @bullet
23669@item
23670The CLI commands are still handled by the @sc{mi} interpreter; their
23671output is described below.
23672
23673@item
23674The @code{@var{token}}, when present, is passed back when the command
23675finishes.
23676
23677@item
23678Some @sc{mi} commands accept optional arguments as part of the parameter
23679list. Each option is identified by a leading @samp{-} (dash) and may be
23680followed by an optional argument parameter. Options occur first in the
23681parameter list and can be delimited from normal parameters using
23682@samp{--} (this is useful when some parameters begin with a dash).
23683@end itemize
23684
23685Pragmatics:
23686
23687@itemize @bullet
23688@item
23689We want easy access to the existing CLI syntax (for debugging).
23690
23691@item
23692We want it to be easy to spot a @sc{mi} operation.
23693@end itemize
23694
23695@node GDB/MI Output Syntax
23696@subsection @sc{gdb/mi} Output Syntax
23697
23698@cindex output syntax of @sc{gdb/mi}
23699@cindex @sc{gdb/mi}, output syntax
23700The output from @sc{gdb/mi} consists of zero or more out-of-band records
23701followed, optionally, by a single result record. This result record
23702is for the most recent command. The sequence of output records is
594fe323 23703terminated by @samp{(gdb)}.
922fbb7b
AC
23704
23705If an input command was prefixed with a @code{@var{token}} then the
23706corresponding output for that command will also be prefixed by that same
23707@var{token}.
23708
23709@table @code
23710@item @var{output} @expansion{}
594fe323 23711@code{( @var{out-of-band-record} )* [ @var{result-record} ] "(gdb)" @var{nl}}
922fbb7b
AC
23712
23713@item @var{result-record} @expansion{}
23714@code{ [ @var{token} ] "^" @var{result-class} ( "," @var{result} )* @var{nl}}
23715
23716@item @var{out-of-band-record} @expansion{}
23717@code{@var{async-record} | @var{stream-record}}
23718
23719@item @var{async-record} @expansion{}
23720@code{@var{exec-async-output} | @var{status-async-output} | @var{notify-async-output}}
23721
23722@item @var{exec-async-output} @expansion{}
23723@code{[ @var{token} ] "*" @var{async-output}}
23724
23725@item @var{status-async-output} @expansion{}
23726@code{[ @var{token} ] "+" @var{async-output}}
23727
23728@item @var{notify-async-output} @expansion{}
23729@code{[ @var{token} ] "=" @var{async-output}}
23730
23731@item @var{async-output} @expansion{}
23732@code{@var{async-class} ( "," @var{result} )* @var{nl}}
23733
23734@item @var{result-class} @expansion{}
23735@code{"done" | "running" | "connected" | "error" | "exit"}
23736
23737@item @var{async-class} @expansion{}
23738@code{"stopped" | @var{others}} (where @var{others} will be added
23739depending on the needs---this is still in development).
23740
23741@item @var{result} @expansion{}
23742@code{ @var{variable} "=" @var{value}}
23743
23744@item @var{variable} @expansion{}
23745@code{ @var{string} }
23746
23747@item @var{value} @expansion{}
23748@code{ @var{const} | @var{tuple} | @var{list} }
23749
23750@item @var{const} @expansion{}
23751@code{@var{c-string}}
23752
23753@item @var{tuple} @expansion{}
23754@code{ "@{@}" | "@{" @var{result} ( "," @var{result} )* "@}" }
23755
23756@item @var{list} @expansion{}
23757@code{ "[]" | "[" @var{value} ( "," @var{value} )* "]" | "["
23758@var{result} ( "," @var{result} )* "]" }
23759
23760@item @var{stream-record} @expansion{}
23761@code{@var{console-stream-output} | @var{target-stream-output} | @var{log-stream-output}}
23762
23763@item @var{console-stream-output} @expansion{}
23764@code{"~" @var{c-string}}
23765
23766@item @var{target-stream-output} @expansion{}
23767@code{"@@" @var{c-string}}
23768
23769@item @var{log-stream-output} @expansion{}
23770@code{"&" @var{c-string}}
23771
23772@item @var{nl} @expansion{}
23773@code{CR | CR-LF}
23774
23775@item @var{token} @expansion{}
23776@emph{any sequence of digits}.
23777@end table
23778
23779@noindent
23780Notes:
23781
23782@itemize @bullet
23783@item
23784All output sequences end in a single line containing a period.
23785
23786@item
721c02de
VP
23787The @code{@var{token}} is from the corresponding request. Note that
23788for all async output, while the token is allowed by the grammar and
23789may be output by future versions of @value{GDBN} for select async
23790output messages, it is generally omitted. Frontends should treat
23791all async output as reporting general changes in the state of the
23792target and there should be no need to associate async output to any
23793prior command.
922fbb7b
AC
23794
23795@item
23796@cindex status output in @sc{gdb/mi}
23797@var{status-async-output} contains on-going status information about the
23798progress of a slow operation. It can be discarded. All status output is
23799prefixed by @samp{+}.
23800
23801@item
23802@cindex async output in @sc{gdb/mi}
23803@var{exec-async-output} contains asynchronous state change on the target
23804(stopped, started, disappeared). All async output is prefixed by
23805@samp{*}.
23806
23807@item
23808@cindex notify output in @sc{gdb/mi}
23809@var{notify-async-output} contains supplementary information that the
23810client should handle (e.g., a new breakpoint information). All notify
23811output is prefixed by @samp{=}.
23812
23813@item
23814@cindex console output in @sc{gdb/mi}
23815@var{console-stream-output} is output that should be displayed as is in the
23816console. It is the textual response to a CLI command. All the console
23817output is prefixed by @samp{~}.
23818
23819@item
23820@cindex target output in @sc{gdb/mi}
23821@var{target-stream-output} is the output produced by the target program.
23822All the target output is prefixed by @samp{@@}.
23823
23824@item
23825@cindex log output in @sc{gdb/mi}
23826@var{log-stream-output} is output text coming from @value{GDBN}'s internals, for
23827instance messages that should be displayed as part of an error log. All
23828the log output is prefixed by @samp{&}.
23829
23830@item
23831@cindex list output in @sc{gdb/mi}
23832New @sc{gdb/mi} commands should only output @var{lists} containing
23833@var{values}.
23834
23835
23836@end itemize
23837
23838@xref{GDB/MI Stream Records, , @sc{gdb/mi} Stream Records}, for more
23839details about the various output records.
23840
922fbb7b
AC
23841@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
23842@node GDB/MI Compatibility with CLI
23843@section @sc{gdb/mi} Compatibility with CLI
23844
23845@cindex compatibility, @sc{gdb/mi} and CLI
23846@cindex @sc{gdb/mi}, compatibility with CLI
922fbb7b 23847
a2c02241
NR
23848For the developers convenience CLI commands can be entered directly,
23849but there may be some unexpected behaviour. For example, commands
23850that query the user will behave as if the user replied yes, breakpoint
23851command lists are not executed and some CLI commands, such as
23852@code{if}, @code{when} and @code{define}, prompt for further input with
23853@samp{>}, which is not valid MI output.
ef21caaf
NR
23854
23855This feature may be removed at some stage in the future and it is
a2c02241
NR
23856recommended that front ends use the @code{-interpreter-exec} command
23857(@pxref{-interpreter-exec}).
922fbb7b 23858
af6eff6f
NR
23859@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
23860@node GDB/MI Development and Front Ends
23861@section @sc{gdb/mi} Development and Front Ends
23862@cindex @sc{gdb/mi} development
23863
23864The application which takes the MI output and presents the state of the
23865program being debugged to the user is called a @dfn{front end}.
23866
23867Although @sc{gdb/mi} is still incomplete, it is currently being used
23868by a variety of front ends to @value{GDBN}. This makes it difficult
23869to introduce new functionality without breaking existing usage. This
23870section tries to minimize the problems by describing how the protocol
23871might change.
23872
23873Some changes in MI need not break a carefully designed front end, and
23874for these the MI version will remain unchanged. The following is a
23875list of changes that may occur within one level, so front ends should
23876parse MI output in a way that can handle them:
23877
23878@itemize @bullet
23879@item
23880New MI commands may be added.
23881
23882@item
23883New fields may be added to the output of any MI command.
23884
36ece8b3
NR
23885@item
23886The range of values for fields with specified values, e.g.,
9f708cb2 23887@code{in_scope} (@pxref{-var-update}) may be extended.
36ece8b3 23888
af6eff6f
NR
23889@c The format of field's content e.g type prefix, may change so parse it
23890@c at your own risk. Yes, in general?
23891
23892@c The order of fields may change? Shouldn't really matter but it might
23893@c resolve inconsistencies.
23894@end itemize
23895
23896If the changes are likely to break front ends, the MI version level
23897will be increased by one. This will allow the front end to parse the
23898output according to the MI version. Apart from mi0, new versions of
23899@value{GDBN} will not support old versions of MI and it will be the
23900responsibility of the front end to work with the new one.
23901
23902@c Starting with mi3, add a new command -mi-version that prints the MI
23903@c version?
23904
23905The best way to avoid unexpected changes in MI that might break your front
23906end is to make your project known to @value{GDBN} developers and
7a9a6b69 23907follow development on @email{gdb@@sourceware.org} and
fa0f268d 23908@email{gdb-patches@@sourceware.org}.
af6eff6f
NR
23909@cindex mailing lists
23910
922fbb7b
AC
23911@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
23912@node GDB/MI Output Records
23913@section @sc{gdb/mi} Output Records
23914
23915@menu
23916* GDB/MI Result Records::
23917* GDB/MI Stream Records::
82f68b1c 23918* GDB/MI Async Records::
c3b108f7 23919* GDB/MI Frame Information::
dc146f7c 23920* GDB/MI Thread Information::
922fbb7b
AC
23921@end menu
23922
23923@node GDB/MI Result Records
23924@subsection @sc{gdb/mi} Result Records
23925
23926@cindex result records in @sc{gdb/mi}
23927@cindex @sc{gdb/mi}, result records
23928In addition to a number of out-of-band notifications, the response to a
23929@sc{gdb/mi} command includes one of the following result indications:
23930
23931@table @code
23932@findex ^done
23933@item "^done" [ "," @var{results} ]
23934The synchronous operation was successful, @code{@var{results}} are the return
23935values.
23936
23937@item "^running"
23938@findex ^running
8e9c5e02
VP
23939This result record is equivalent to @samp{^done}. Historically, it
23940was output instead of @samp{^done} if the command has resumed the
23941target. This behaviour is maintained for backward compatibility, but
23942all frontends should treat @samp{^done} and @samp{^running}
23943identically and rely on the @samp{*running} output record to determine
23944which threads are resumed.
922fbb7b 23945
ef21caaf
NR
23946@item "^connected"
23947@findex ^connected
3f94c067 23948@value{GDBN} has connected to a remote target.
ef21caaf 23949
922fbb7b
AC
23950@item "^error" "," @var{c-string}
23951@findex ^error
23952The operation failed. The @code{@var{c-string}} contains the corresponding
23953error message.
ef21caaf
NR
23954
23955@item "^exit"
23956@findex ^exit
3f94c067 23957@value{GDBN} has terminated.
ef21caaf 23958
922fbb7b
AC
23959@end table
23960
23961@node GDB/MI Stream Records
23962@subsection @sc{gdb/mi} Stream Records
23963
23964@cindex @sc{gdb/mi}, stream records
23965@cindex stream records in @sc{gdb/mi}
23966@value{GDBN} internally maintains a number of output streams: the console, the
23967target, and the log. The output intended for each of these streams is
23968funneled through the @sc{gdb/mi} interface using @dfn{stream records}.
23969
23970Each stream record begins with a unique @dfn{prefix character} which
23971identifies its stream (@pxref{GDB/MI Output Syntax, , @sc{gdb/mi} Output
23972Syntax}). In addition to the prefix, each stream record contains a
23973@code{@var{string-output}}. This is either raw text (with an implicit new
23974line) or a quoted C string (which does not contain an implicit newline).
23975
23976@table @code
23977@item "~" @var{string-output}
23978The console output stream contains text that should be displayed in the
23979CLI console window. It contains the textual responses to CLI commands.
23980
23981@item "@@" @var{string-output}
23982The target output stream contains any textual output from the running
ef21caaf
NR
23983target. This is only present when GDB's event loop is truly
23984asynchronous, which is currently only the case for remote targets.
922fbb7b
AC
23985
23986@item "&" @var{string-output}
23987The log stream contains debugging messages being produced by @value{GDBN}'s
23988internals.
23989@end table
23990
82f68b1c
VP
23991@node GDB/MI Async Records
23992@subsection @sc{gdb/mi} Async Records
922fbb7b 23993
82f68b1c
VP
23994@cindex async records in @sc{gdb/mi}
23995@cindex @sc{gdb/mi}, async records
23996@dfn{Async} records are used to notify the @sc{gdb/mi} client of
922fbb7b 23997additional changes that have occurred. Those changes can either be a
82f68b1c 23998consequence of @sc{gdb/mi} commands (e.g., a breakpoint modified) or a result of
922fbb7b
AC
23999target activity (e.g., target stopped).
24000
8eb41542 24001The following is the list of possible async records:
922fbb7b
AC
24002
24003@table @code
034dad6f 24004
e1ac3328
VP
24005@item *running,thread-id="@var{thread}"
24006The target is now running. The @var{thread} field tells which
24007specific thread is now running, and can be @samp{all} if all threads
24008are running. The frontend should assume that no interaction with a
24009running thread is possible after this notification is produced.
24010The frontend should not assume that this notification is output
24011only once for any command. @value{GDBN} may emit this notification
24012several times, either for different threads, because it cannot resume
24013all threads together, or even for a single thread, if the thread must
24014be stepped though some code before letting it run freely.
24015
dc146f7c 24016@item *stopped,reason="@var{reason}",thread-id="@var{id}",stopped-threads="@var{stopped}",core="@var{core}"
82f68b1c
VP
24017The target has stopped. The @var{reason} field can have one of the
24018following values:
034dad6f
BR
24019
24020@table @code
24021@item breakpoint-hit
24022A breakpoint was reached.
24023@item watchpoint-trigger
24024A watchpoint was triggered.
24025@item read-watchpoint-trigger
24026A read watchpoint was triggered.
24027@item access-watchpoint-trigger
24028An access watchpoint was triggered.
24029@item function-finished
24030An -exec-finish or similar CLI command was accomplished.
24031@item location-reached
24032An -exec-until or similar CLI command was accomplished.
24033@item watchpoint-scope
24034A watchpoint has gone out of scope.
24035@item end-stepping-range
24036An -exec-next, -exec-next-instruction, -exec-step, -exec-step-instruction or
24037similar CLI command was accomplished.
24038@item exited-signalled
24039The inferior exited because of a signal.
24040@item exited
24041The inferior exited.
24042@item exited-normally
24043The inferior exited normally.
24044@item signal-received
24045A signal was received by the inferior.
922fbb7b
AC
24046@end table
24047
c3b108f7
VP
24048The @var{id} field identifies the thread that directly caused the stop
24049-- for example by hitting a breakpoint. Depending on whether all-stop
24050mode is in effect (@pxref{All-Stop Mode}), @value{GDBN} may either
24051stop all threads, or only the thread that directly triggered the stop.
24052If all threads are stopped, the @var{stopped} field will have the
24053value of @code{"all"}. Otherwise, the value of the @var{stopped}
24054field will be a list of thread identifiers. Presently, this list will
24055always include a single thread, but frontend should be prepared to see
dc146f7c
VP
24056several threads in the list. The @var{core} field reports the
24057processor core on which the stop event has happened. This field may be absent
24058if such information is not available.
c3b108f7 24059
a79b8f6e
VP
24060@item =thread-group-added,id="@var{id}"
24061@itemx =thread-group-removed,id="@var{id}"
24062A thread group was either added or removed. The @var{id} field
24063contains the @value{GDBN} identifier of the thread group. When a thread
24064group is added, it generally might not be associated with a running
24065process. When a thread group is removed, its id becomes invalid and
24066cannot be used in any way.
24067
24068@item =thread-group-started,id="@var{id}",pid="@var{pid}"
24069A thread group became associated with a running program,
24070either because the program was just started or the thread group
24071was attached to a program. The @var{id} field contains the
24072@value{GDBN} identifier of the thread group. The @var{pid} field
24073contains process identifier, specific to the operating system.
24074
c3b108f7 24075@itemx =thread-group-exited,id="@var{id}"
a79b8f6e
VP
24076A thread group is no longer associated with a running program,
24077either because the program has exited, or because it was detached
c3b108f7
VP
24078from. The @var{id} field contains the @value{GDBN} identifier of the
24079thread group.
24080
24081@item =thread-created,id="@var{id}",group-id="@var{gid}"
24082@itemx =thread-exited,id="@var{id}",group-id="@var{gid}"
82f68b1c 24083A thread either was created, or has exited. The @var{id} field
c3b108f7
VP
24084contains the @value{GDBN} identifier of the thread. The @var{gid}
24085field identifies the thread group this thread belongs to.
66bb093b
VP
24086
24087@item =thread-selected,id="@var{id}"
24088Informs that the selected thread was changed as result of the last
24089command. This notification is not emitted as result of @code{-thread-select}
24090command but is emitted whenever an MI command that is not documented
24091to change the selected thread actually changes it. In particular,
24092invoking, directly or indirectly (via user-defined command), the CLI
24093@code{thread} command, will generate this notification.
24094
24095We suggest that in response to this notification, front ends
24096highlight the selected thread and cause subsequent commands to apply to
24097that thread.
24098
c86cf029
VP
24099@item =library-loaded,...
24100Reports that a new library file was loaded by the program. This
24101notification has 4 fields---@var{id}, @var{target-name},
134eb42c 24102@var{host-name}, and @var{symbols-loaded}. The @var{id} field is an
c86cf029
VP
24103opaque identifier of the library. For remote debugging case,
24104@var{target-name} and @var{host-name} fields give the name of the
134eb42c
VP
24105library file on the target, and on the host respectively. For native
24106debugging, both those fields have the same value. The
c86cf029 24107@var{symbols-loaded} field reports if the debug symbols for this
a79b8f6e
VP
24108library are loaded. The @var{thread-group} field, if present,
24109specifies the id of the thread group in whose context the library was loaded.
24110If the field is absent, it means the library was loaded in the context
24111of all present thread groups.
c86cf029
VP
24112
24113@item =library-unloaded,...
134eb42c 24114Reports that a library was unloaded by the program. This notification
c86cf029 24115has 3 fields---@var{id}, @var{target-name} and @var{host-name} with
a79b8f6e
VP
24116the same meaning as for the @code{=library-loaded} notification.
24117The @var{thread-group} field, if present, specifies the id of the
24118thread group in whose context the library was unloaded. If the field is
24119absent, it means the library was unloaded in the context of all present
24120thread groups.
c86cf029 24121
82f68b1c
VP
24122@end table
24123
c3b108f7
VP
24124@node GDB/MI Frame Information
24125@subsection @sc{gdb/mi} Frame Information
24126
24127Response from many MI commands includes an information about stack
24128frame. This information is a tuple that may have the following
24129fields:
24130
24131@table @code
24132@item level
24133The level of the stack frame. The innermost frame has the level of
24134zero. This field is always present.
24135
24136@item func
24137The name of the function corresponding to the frame. This field may
24138be absent if @value{GDBN} is unable to determine the function name.
24139
24140@item addr
24141The code address for the frame. This field is always present.
24142
24143@item file
24144The name of the source files that correspond to the frame's code
24145address. This field may be absent.
24146
24147@item line
24148The source line corresponding to the frames' code address. This field
24149may be absent.
24150
24151@item from
24152The name of the binary file (either executable or shared library) the
24153corresponds to the frame's code address. This field may be absent.
24154
24155@end table
82f68b1c 24156
dc146f7c
VP
24157@node GDB/MI Thread Information
24158@subsection @sc{gdb/mi} Thread Information
24159
24160Whenever @value{GDBN} has to report an information about a thread, it
24161uses a tuple with the following fields:
24162
24163@table @code
24164@item id
24165The numeric id assigned to the thread by @value{GDBN}. This field is
24166always present.
24167
24168@item target-id
24169Target-specific string identifying the thread. This field is always present.
24170
24171@item details
24172Additional information about the thread provided by the target.
24173It is supposed to be human-readable and not interpreted by the
24174frontend. This field is optional.
24175
24176@item state
24177Either @samp{stopped} or @samp{running}, depending on whether the
24178thread is presently running. This field is always present.
24179
24180@item core
24181The value of this field is an integer number of the processor core the
24182thread was last seen on. This field is optional.
24183@end table
24184
922fbb7b 24185
ef21caaf
NR
24186@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
24187@node GDB/MI Simple Examples
24188@section Simple Examples of @sc{gdb/mi} Interaction
24189@cindex @sc{gdb/mi}, simple examples
24190
24191This subsection presents several simple examples of interaction using
24192the @sc{gdb/mi} interface. In these examples, @samp{->} means that the
24193following line is passed to @sc{gdb/mi} as input, while @samp{<-} means
24194the output received from @sc{gdb/mi}.
24195
d3e8051b 24196Note the line breaks shown in the examples are here only for
ef21caaf
NR
24197readability, they don't appear in the real output.
24198
79a6e687 24199@subheading Setting a Breakpoint
ef21caaf
NR
24200
24201Setting a breakpoint generates synchronous output which contains detailed
24202information of the breakpoint.
24203
24204@smallexample
24205-> -break-insert main
24206<- ^done,bkpt=@{number="1",type="breakpoint",disp="keep",
24207 enabled="y",addr="0x08048564",func="main",file="myprog.c",
24208 fullname="/home/nickrob/myprog.c",line="68",times="0"@}
24209<- (gdb)
24210@end smallexample
24211
24212@subheading Program Execution
24213
24214Program execution generates asynchronous records and MI gives the
24215reason that execution stopped.
24216
24217@smallexample
24218-> -exec-run
24219<- ^running
24220<- (gdb)
a47ec5fe 24221<- *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",thread-id="0",
ef21caaf
NR
24222 frame=@{addr="0x08048564",func="main",
24223 args=[@{name="argc",value="1"@},@{name="argv",value="0xbfc4d4d4"@}],
24224 file="myprog.c",fullname="/home/nickrob/myprog.c",line="68"@}
24225<- (gdb)
24226-> -exec-continue
24227<- ^running
24228<- (gdb)
24229<- *stopped,reason="exited-normally"
24230<- (gdb)
24231@end smallexample
24232
3f94c067 24233@subheading Quitting @value{GDBN}
ef21caaf 24234
3f94c067 24235Quitting @value{GDBN} just prints the result class @samp{^exit}.
ef21caaf
NR
24236
24237@smallexample
24238-> (gdb)
24239<- -gdb-exit
24240<- ^exit
24241@end smallexample
24242
a6b29f87
VP
24243Please note that @samp{^exit} is printed immediately, but it might
24244take some time for @value{GDBN} to actually exit. During that time, @value{GDBN}
24245performs necessary cleanups, including killing programs being debugged
24246or disconnecting from debug hardware, so the frontend should wait till
24247@value{GDBN} exits and should only forcibly kill @value{GDBN} if it
24248fails to exit in reasonable time.
24249
a2c02241 24250@subheading A Bad Command
ef21caaf
NR
24251
24252Here's what happens if you pass a non-existent command:
24253
24254@smallexample
24255-> -rubbish
24256<- ^error,msg="Undefined MI command: rubbish"
594fe323 24257<- (gdb)
ef21caaf
NR
24258@end smallexample
24259
24260
922fbb7b
AC
24261@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
24262@node GDB/MI Command Description Format
24263@section @sc{gdb/mi} Command Description Format
24264
24265The remaining sections describe blocks of commands. Each block of
24266commands is laid out in a fashion similar to this section.
24267
922fbb7b
AC
24268@subheading Motivation
24269
24270The motivation for this collection of commands.
24271
24272@subheading Introduction
24273
24274A brief introduction to this collection of commands as a whole.
24275
24276@subheading Commands
24277
24278For each command in the block, the following is described:
24279
24280@subsubheading Synopsis
24281
24282@smallexample
24283 -command @var{args}@dots{}
24284@end smallexample
24285
922fbb7b
AC
24286@subsubheading Result
24287
265eeb58 24288@subsubheading @value{GDBN} Command
922fbb7b 24289
265eeb58 24290The corresponding @value{GDBN} CLI command(s), if any.
922fbb7b
AC
24291
24292@subsubheading Example
24293
ef21caaf
NR
24294Example(s) formatted for readability. Some of the described commands have
24295not been implemented yet and these are labeled N.A.@: (not available).
24296
24297
922fbb7b 24298@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
ef21caaf
NR
24299@node GDB/MI Breakpoint Commands
24300@section @sc{gdb/mi} Breakpoint Commands
922fbb7b
AC
24301
24302@cindex breakpoint commands for @sc{gdb/mi}
24303@cindex @sc{gdb/mi}, breakpoint commands
24304This section documents @sc{gdb/mi} commands for manipulating
24305breakpoints.
24306
24307@subheading The @code{-break-after} Command
24308@findex -break-after
24309
24310@subsubheading Synopsis
24311
24312@smallexample
24313 -break-after @var{number} @var{count}
24314@end smallexample
24315
24316The breakpoint number @var{number} is not in effect until it has been
24317hit @var{count} times. To see how this is reflected in the output of
24318the @samp{-break-list} command, see the description of the
24319@samp{-break-list} command below.
24320
24321@subsubheading @value{GDBN} Command
24322
24323The corresponding @value{GDBN} command is @samp{ignore}.
24324
24325@subsubheading Example
24326
24327@smallexample
594fe323 24328(gdb)
922fbb7b 24329-break-insert main
a47ec5fe
AR
24330^done,bkpt=@{number="1",type="breakpoint",disp="keep",
24331enabled="y",addr="0x000100d0",func="main",file="hello.c",
948d5102 24332fullname="/home/foo/hello.c",line="5",times="0"@}
594fe323 24333(gdb)
922fbb7b
AC
24334-break-after 1 3
24335~
24336^done
594fe323 24337(gdb)
922fbb7b
AC
24338-break-list
24339^done,BreakpointTable=@{nr_rows="1",nr_cols="6",
24340hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
24341@{width="14",alignment="-1",col_name="type",colhdr="Type"@},
24342@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
24343@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
24344@{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
24345@{width="40",alignment="2",col_name="what",colhdr="What"@}],
24346body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
948d5102
NR
24347addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
24348line="5",times="0",ignore="3"@}]@}
594fe323 24349(gdb)
922fbb7b
AC
24350@end smallexample
24351
24352@ignore
24353@subheading The @code{-break-catch} Command
24354@findex -break-catch
48cb2d85 24355@end ignore
922fbb7b
AC
24356
24357@subheading The @code{-break-commands} Command
24358@findex -break-commands
922fbb7b 24359
48cb2d85
VP
24360@subsubheading Synopsis
24361
24362@smallexample
24363 -break-commands @var{number} [ @var{command1} ... @var{commandN} ]
24364@end smallexample
24365
24366Specifies the CLI commands that should be executed when breakpoint
24367@var{number} is hit. The parameters @var{command1} to @var{commandN}
24368are the commands. If no command is specified, any previously-set
24369commands are cleared. @xref{Break Commands}. Typical use of this
24370functionality is tracing a program, that is, printing of values of
24371some variables whenever breakpoint is hit and then continuing.
24372
24373@subsubheading @value{GDBN} Command
24374
24375The corresponding @value{GDBN} command is @samp{commands}.
24376
24377@subsubheading Example
24378
24379@smallexample
24380(gdb)
24381-break-insert main
24382^done,bkpt=@{number="1",type="breakpoint",disp="keep",
24383enabled="y",addr="0x000100d0",func="main",file="hello.c",
24384fullname="/home/foo/hello.c",line="5",times="0"@}
24385(gdb)
24386-break-commands 1 "print v" "continue"
24387^done
24388(gdb)
24389@end smallexample
922fbb7b
AC
24390
24391@subheading The @code{-break-condition} Command
24392@findex -break-condition
24393
24394@subsubheading Synopsis
24395
24396@smallexample
24397 -break-condition @var{number} @var{expr}
24398@end smallexample
24399
24400Breakpoint @var{number} will stop the program only if the condition in
24401@var{expr} is true. The condition becomes part of the
24402@samp{-break-list} output (see the description of the @samp{-break-list}
24403command below).
24404
24405@subsubheading @value{GDBN} Command
24406
24407The corresponding @value{GDBN} command is @samp{condition}.
24408
24409@subsubheading Example
24410
24411@smallexample
594fe323 24412(gdb)
922fbb7b
AC
24413-break-condition 1 1
24414^done
594fe323 24415(gdb)
922fbb7b
AC
24416-break-list
24417^done,BreakpointTable=@{nr_rows="1",nr_cols="6",
24418hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
24419@{width="14",alignment="-1",col_name="type",colhdr="Type"@},
24420@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
24421@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
24422@{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
24423@{width="40",alignment="2",col_name="what",colhdr="What"@}],
24424body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
948d5102
NR
24425addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
24426line="5",cond="1",times="0",ignore="3"@}]@}
594fe323 24427(gdb)
922fbb7b
AC
24428@end smallexample
24429
24430@subheading The @code{-break-delete} Command
24431@findex -break-delete
24432
24433@subsubheading Synopsis
24434
24435@smallexample
24436 -break-delete ( @var{breakpoint} )+
24437@end smallexample
24438
24439Delete the breakpoint(s) whose number(s) are specified in the argument
24440list. This is obviously reflected in the breakpoint list.
24441
79a6e687 24442@subsubheading @value{GDBN} Command
922fbb7b
AC
24443
24444The corresponding @value{GDBN} command is @samp{delete}.
24445
24446@subsubheading Example
24447
24448@smallexample
594fe323 24449(gdb)
922fbb7b
AC
24450-break-delete 1
24451^done
594fe323 24452(gdb)
922fbb7b
AC
24453-break-list
24454^done,BreakpointTable=@{nr_rows="0",nr_cols="6",
24455hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
24456@{width="14",alignment="-1",col_name="type",colhdr="Type"@},
24457@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
24458@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
24459@{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
24460@{width="40",alignment="2",col_name="what",colhdr="What"@}],
24461body=[]@}
594fe323 24462(gdb)
922fbb7b
AC
24463@end smallexample
24464
24465@subheading The @code{-break-disable} Command
24466@findex -break-disable
24467
24468@subsubheading Synopsis
24469
24470@smallexample
24471 -break-disable ( @var{breakpoint} )+
24472@end smallexample
24473
24474Disable the named @var{breakpoint}(s). The field @samp{enabled} in the
24475break list is now set to @samp{n} for the named @var{breakpoint}(s).
24476
24477@subsubheading @value{GDBN} Command
24478
24479The corresponding @value{GDBN} command is @samp{disable}.
24480
24481@subsubheading Example
24482
24483@smallexample
594fe323 24484(gdb)
922fbb7b
AC
24485-break-disable 2
24486^done
594fe323 24487(gdb)
922fbb7b
AC
24488-break-list
24489^done,BreakpointTable=@{nr_rows="1",nr_cols="6",
24490hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
24491@{width="14",alignment="-1",col_name="type",colhdr="Type"@},
24492@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
24493@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
24494@{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
24495@{width="40",alignment="2",col_name="what",colhdr="What"@}],
24496body=[bkpt=@{number="2",type="breakpoint",disp="keep",enabled="n",
948d5102
NR
24497addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
24498line="5",times="0"@}]@}
594fe323 24499(gdb)
922fbb7b
AC
24500@end smallexample
24501
24502@subheading The @code{-break-enable} Command
24503@findex -break-enable
24504
24505@subsubheading Synopsis
24506
24507@smallexample
24508 -break-enable ( @var{breakpoint} )+
24509@end smallexample
24510
24511Enable (previously disabled) @var{breakpoint}(s).
24512
24513@subsubheading @value{GDBN} Command
24514
24515The corresponding @value{GDBN} command is @samp{enable}.
24516
24517@subsubheading Example
24518
24519@smallexample
594fe323 24520(gdb)
922fbb7b
AC
24521-break-enable 2
24522^done
594fe323 24523(gdb)
922fbb7b
AC
24524-break-list
24525^done,BreakpointTable=@{nr_rows="1",nr_cols="6",
24526hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
24527@{width="14",alignment="-1",col_name="type",colhdr="Type"@},
24528@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
24529@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
24530@{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
24531@{width="40",alignment="2",col_name="what",colhdr="What"@}],
24532body=[bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y",
948d5102
NR
24533addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
24534line="5",times="0"@}]@}
594fe323 24535(gdb)
922fbb7b
AC
24536@end smallexample
24537
24538@subheading The @code{-break-info} Command
24539@findex -break-info
24540
24541@subsubheading Synopsis
24542
24543@smallexample
24544 -break-info @var{breakpoint}
24545@end smallexample
24546
24547@c REDUNDANT???
24548Get information about a single breakpoint.
24549
79a6e687 24550@subsubheading @value{GDBN} Command
922fbb7b
AC
24551
24552The corresponding @value{GDBN} command is @samp{info break @var{breakpoint}}.
24553
24554@subsubheading Example
24555N.A.
24556
24557@subheading The @code{-break-insert} Command
24558@findex -break-insert
24559
24560@subsubheading Synopsis
24561
24562@smallexample
18148017 24563 -break-insert [ -t ] [ -h ] [ -f ] [ -d ] [ -a ]
922fbb7b 24564 [ -c @var{condition} ] [ -i @var{ignore-count} ]
afe8ab22 24565 [ -p @var{thread} ] [ @var{location} ]
922fbb7b
AC
24566@end smallexample
24567
24568@noindent
afe8ab22 24569If specified, @var{location}, can be one of:
922fbb7b
AC
24570
24571@itemize @bullet
24572@item function
24573@c @item +offset
24574@c @item -offset
24575@c @item linenum
24576@item filename:linenum
24577@item filename:function
24578@item *address
24579@end itemize
24580
24581The possible optional parameters of this command are:
24582
24583@table @samp
24584@item -t
948d5102 24585Insert a temporary breakpoint.
922fbb7b
AC
24586@item -h
24587Insert a hardware breakpoint.
24588@item -c @var{condition}
24589Make the breakpoint conditional on @var{condition}.
24590@item -i @var{ignore-count}
24591Initialize the @var{ignore-count}.
afe8ab22
VP
24592@item -f
24593If @var{location} cannot be parsed (for example if it
24594refers to unknown files or functions), create a pending
24595breakpoint. Without this flag, @value{GDBN} will report
24596an error, and won't create a breakpoint, if @var{location}
24597cannot be parsed.
41447f92
VP
24598@item -d
24599Create a disabled breakpoint.
18148017
VP
24600@item -a
24601Create a tracepoint. @xref{Tracepoints}. When this parameter
24602is used together with @samp{-h}, a fast tracepoint is created.
922fbb7b
AC
24603@end table
24604
24605@subsubheading Result
24606
24607The result is in the form:
24608
24609@smallexample
948d5102
NR
24610^done,bkpt=@{number="@var{number}",type="@var{type}",disp="del"|"keep",
24611enabled="y"|"n",addr="@var{hex}",func="@var{funcname}",file="@var{filename}",
ef21caaf
NR
24612fullname="@var{full_filename}",line="@var{lineno}",[thread="@var{threadno},]
24613times="@var{times}"@}
922fbb7b
AC
24614@end smallexample
24615
24616@noindent
948d5102
NR
24617where @var{number} is the @value{GDBN} number for this breakpoint,
24618@var{funcname} is the name of the function where the breakpoint was
24619inserted, @var{filename} is the name of the source file which contains
24620this function, @var{lineno} is the source line number within that file
24621and @var{times} the number of times that the breakpoint has been hit
24622(always 0 for -break-insert but may be greater for -break-info or -break-list
24623which use the same output).
922fbb7b
AC
24624
24625Note: this format is open to change.
24626@c An out-of-band breakpoint instead of part of the result?
24627
24628@subsubheading @value{GDBN} Command
24629
24630The corresponding @value{GDBN} commands are @samp{break}, @samp{tbreak},
24631@samp{hbreak}, @samp{thbreak}, and @samp{rbreak}.
24632
24633@subsubheading Example
24634
24635@smallexample
594fe323 24636(gdb)
922fbb7b 24637-break-insert main
948d5102
NR
24638^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",
24639fullname="/home/foo/recursive2.c,line="4",times="0"@}
594fe323 24640(gdb)
922fbb7b 24641-break-insert -t foo
948d5102
NR
24642^done,bkpt=@{number="2",addr="0x00010774",file="recursive2.c",
24643fullname="/home/foo/recursive2.c,line="11",times="0"@}
594fe323 24644(gdb)
922fbb7b
AC
24645-break-list
24646^done,BreakpointTable=@{nr_rows="2",nr_cols="6",
24647hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
24648@{width="14",alignment="-1",col_name="type",colhdr="Type"@},
24649@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
24650@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
24651@{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
24652@{width="40",alignment="2",col_name="what",colhdr="What"@}],
24653body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
948d5102
NR
24654addr="0x0001072c", func="main",file="recursive2.c",
24655fullname="/home/foo/recursive2.c,"line="4",times="0"@},
922fbb7b 24656bkpt=@{number="2",type="breakpoint",disp="del",enabled="y",
948d5102
NR
24657addr="0x00010774",func="foo",file="recursive2.c",
24658fullname="/home/foo/recursive2.c",line="11",times="0"@}]@}
594fe323 24659(gdb)
922fbb7b
AC
24660-break-insert -r foo.*
24661~int foo(int, int);
948d5102
NR
24662^done,bkpt=@{number="3",addr="0x00010774",file="recursive2.c,
24663"fullname="/home/foo/recursive2.c",line="11",times="0"@}
594fe323 24664(gdb)
922fbb7b
AC
24665@end smallexample
24666
24667@subheading The @code{-break-list} Command
24668@findex -break-list
24669
24670@subsubheading Synopsis
24671
24672@smallexample
24673 -break-list
24674@end smallexample
24675
24676Displays the list of inserted breakpoints, showing the following fields:
24677
24678@table @samp
24679@item Number
24680number of the breakpoint
24681@item Type
24682type of the breakpoint: @samp{breakpoint} or @samp{watchpoint}
24683@item Disposition
24684should the breakpoint be deleted or disabled when it is hit: @samp{keep}
24685or @samp{nokeep}
24686@item Enabled
24687is the breakpoint enabled or no: @samp{y} or @samp{n}
24688@item Address
24689memory location at which the breakpoint is set
24690@item What
24691logical location of the breakpoint, expressed by function name, file
24692name, line number
24693@item Times
24694number of times the breakpoint has been hit
24695@end table
24696
24697If there are no breakpoints or watchpoints, the @code{BreakpointTable}
24698@code{body} field is an empty list.
24699
24700@subsubheading @value{GDBN} Command
24701
24702The corresponding @value{GDBN} command is @samp{info break}.
24703
24704@subsubheading Example
24705
24706@smallexample
594fe323 24707(gdb)
922fbb7b
AC
24708-break-list
24709^done,BreakpointTable=@{nr_rows="2",nr_cols="6",
24710hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
24711@{width="14",alignment="-1",col_name="type",colhdr="Type"@},
24712@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
24713@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
24714@{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
24715@{width="40",alignment="2",col_name="what",colhdr="What"@}],
24716body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
24717addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@},
24718bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y",
948d5102
NR
24719addr="0x00010114",func="foo",file="hello.c",fullname="/home/foo/hello.c",
24720line="13",times="0"@}]@}
594fe323 24721(gdb)
922fbb7b
AC
24722@end smallexample
24723
24724Here's an example of the result when there are no breakpoints:
24725
24726@smallexample
594fe323 24727(gdb)
922fbb7b
AC
24728-break-list
24729^done,BreakpointTable=@{nr_rows="0",nr_cols="6",
24730hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
24731@{width="14",alignment="-1",col_name="type",colhdr="Type"@},
24732@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
24733@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
24734@{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
24735@{width="40",alignment="2",col_name="what",colhdr="What"@}],
24736body=[]@}
594fe323 24737(gdb)
922fbb7b
AC
24738@end smallexample
24739
18148017
VP
24740@subheading The @code{-break-passcount} Command
24741@findex -break-passcount
24742
24743@subsubheading Synopsis
24744
24745@smallexample
24746 -break-passcount @var{tracepoint-number} @var{passcount}
24747@end smallexample
24748
24749Set the passcount for tracepoint @var{tracepoint-number} to
24750@var{passcount}. If the breakpoint referred to by @var{tracepoint-number}
24751is not a tracepoint, error is emitted. This corresponds to CLI
24752command @samp{passcount}.
24753
922fbb7b
AC
24754@subheading The @code{-break-watch} Command
24755@findex -break-watch
24756
24757@subsubheading Synopsis
24758
24759@smallexample
24760 -break-watch [ -a | -r ]
24761@end smallexample
24762
24763Create a watchpoint. With the @samp{-a} option it will create an
d3e8051b 24764@dfn{access} watchpoint, i.e., a watchpoint that triggers either on a
922fbb7b 24765read from or on a write to the memory location. With the @samp{-r}
d3e8051b 24766option, the watchpoint created is a @dfn{read} watchpoint, i.e., it will
922fbb7b
AC
24767trigger only when the memory location is accessed for reading. Without
24768either of the options, the watchpoint created is a regular watchpoint,
d3e8051b 24769i.e., it will trigger when the memory location is accessed for writing.
79a6e687 24770@xref{Set Watchpoints, , Setting Watchpoints}.
922fbb7b
AC
24771
24772Note that @samp{-break-list} will report a single list of watchpoints and
24773breakpoints inserted.
24774
24775@subsubheading @value{GDBN} Command
24776
24777The corresponding @value{GDBN} commands are @samp{watch}, @samp{awatch}, and
24778@samp{rwatch}.
24779
24780@subsubheading Example
24781
24782Setting a watchpoint on a variable in the @code{main} function:
24783
24784@smallexample
594fe323 24785(gdb)
922fbb7b
AC
24786-break-watch x
24787^done,wpt=@{number="2",exp="x"@}
594fe323 24788(gdb)
922fbb7b
AC
24789-exec-continue
24790^running
0869d01b
NR
24791(gdb)
24792*stopped,reason="watchpoint-trigger",wpt=@{number="2",exp="x"@},
922fbb7b 24793value=@{old="-268439212",new="55"@},
76ff342d 24794frame=@{func="main",args=[],file="recursive2.c",
948d5102 24795fullname="/home/foo/bar/recursive2.c",line="5"@}
594fe323 24796(gdb)
922fbb7b
AC
24797@end smallexample
24798
24799Setting a watchpoint on a variable local to a function. @value{GDBN} will stop
24800the program execution twice: first for the variable changing value, then
24801for the watchpoint going out of scope.
24802
24803@smallexample
594fe323 24804(gdb)
922fbb7b
AC
24805-break-watch C
24806^done,wpt=@{number="5",exp="C"@}
594fe323 24807(gdb)
922fbb7b
AC
24808-exec-continue
24809^running
0869d01b
NR
24810(gdb)
24811*stopped,reason="watchpoint-trigger",
922fbb7b
AC
24812wpt=@{number="5",exp="C"@},value=@{old="-276895068",new="3"@},
24813frame=@{func="callee4",args=[],
76ff342d
DJ
24814file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
24815fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13"@}
594fe323 24816(gdb)
922fbb7b
AC
24817-exec-continue
24818^running
0869d01b
NR
24819(gdb)
24820*stopped,reason="watchpoint-scope",wpnum="5",
922fbb7b
AC
24821frame=@{func="callee3",args=[@{name="strarg",
24822value="0x11940 \"A string argument.\""@}],
76ff342d
DJ
24823file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
24824fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
594fe323 24825(gdb)
922fbb7b
AC
24826@end smallexample
24827
24828Listing breakpoints and watchpoints, at different points in the program
24829execution. Note that once the watchpoint goes out of scope, it is
24830deleted.
24831
24832@smallexample
594fe323 24833(gdb)
922fbb7b
AC
24834-break-watch C
24835^done,wpt=@{number="2",exp="C"@}
594fe323 24836(gdb)
922fbb7b
AC
24837-break-list
24838^done,BreakpointTable=@{nr_rows="2",nr_cols="6",
24839hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
24840@{width="14",alignment="-1",col_name="type",colhdr="Type"@},
24841@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
24842@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
24843@{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
24844@{width="40",alignment="2",col_name="what",colhdr="What"@}],
24845body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
24846addr="0x00010734",func="callee4",
948d5102
NR
24847file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
24848fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c"line="8",times="1"@},
922fbb7b
AC
24849bkpt=@{number="2",type="watchpoint",disp="keep",
24850enabled="y",addr="",what="C",times="0"@}]@}
594fe323 24851(gdb)
922fbb7b
AC
24852-exec-continue
24853^running
0869d01b
NR
24854(gdb)
24855*stopped,reason="watchpoint-trigger",wpt=@{number="2",exp="C"@},
922fbb7b
AC
24856value=@{old="-276895068",new="3"@},
24857frame=@{func="callee4",args=[],
76ff342d
DJ
24858file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
24859fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13"@}
594fe323 24860(gdb)
922fbb7b
AC
24861-break-list
24862^done,BreakpointTable=@{nr_rows="2",nr_cols="6",
24863hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
24864@{width="14",alignment="-1",col_name="type",colhdr="Type"@},
24865@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
24866@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
24867@{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
24868@{width="40",alignment="2",col_name="what",colhdr="What"@}],
24869body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
24870addr="0x00010734",func="callee4",
948d5102
NR
24871file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
24872fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"@},
922fbb7b
AC
24873bkpt=@{number="2",type="watchpoint",disp="keep",
24874enabled="y",addr="",what="C",times="-5"@}]@}
594fe323 24875(gdb)
922fbb7b
AC
24876-exec-continue
24877^running
24878^done,reason="watchpoint-scope",wpnum="2",
24879frame=@{func="callee3",args=[@{name="strarg",
24880value="0x11940 \"A string argument.\""@}],
76ff342d
DJ
24881file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
24882fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
594fe323 24883(gdb)
922fbb7b
AC
24884-break-list
24885^done,BreakpointTable=@{nr_rows="1",nr_cols="6",
24886hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
24887@{width="14",alignment="-1",col_name="type",colhdr="Type"@},
24888@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
24889@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
24890@{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
24891@{width="40",alignment="2",col_name="what",colhdr="What"@}],
24892body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
24893addr="0x00010734",func="callee4",
948d5102
NR
24894file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
24895fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8",
24896times="1"@}]@}
594fe323 24897(gdb)
922fbb7b
AC
24898@end smallexample
24899
24900@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
a2c02241
NR
24901@node GDB/MI Program Context
24902@section @sc{gdb/mi} Program Context
922fbb7b 24903
a2c02241
NR
24904@subheading The @code{-exec-arguments} Command
24905@findex -exec-arguments
922fbb7b 24906
922fbb7b
AC
24907
24908@subsubheading Synopsis
24909
24910@smallexample
a2c02241 24911 -exec-arguments @var{args}
922fbb7b
AC
24912@end smallexample
24913
a2c02241
NR
24914Set the inferior program arguments, to be used in the next
24915@samp{-exec-run}.
922fbb7b 24916
a2c02241 24917@subsubheading @value{GDBN} Command
922fbb7b 24918
a2c02241 24919The corresponding @value{GDBN} command is @samp{set args}.
922fbb7b 24920
a2c02241 24921@subsubheading Example
922fbb7b 24922
fbc5282e
MK
24923@smallexample
24924(gdb)
24925-exec-arguments -v word
24926^done
24927(gdb)
24928@end smallexample
922fbb7b 24929
a2c02241 24930
9901a55b 24931@ignore
a2c02241
NR
24932@subheading The @code{-exec-show-arguments} Command
24933@findex -exec-show-arguments
24934
24935@subsubheading Synopsis
24936
24937@smallexample
24938 -exec-show-arguments
24939@end smallexample
24940
24941Print the arguments of the program.
922fbb7b
AC
24942
24943@subsubheading @value{GDBN} Command
24944
a2c02241 24945The corresponding @value{GDBN} command is @samp{show args}.
922fbb7b
AC
24946
24947@subsubheading Example
a2c02241 24948N.A.
9901a55b 24949@end ignore
922fbb7b 24950
922fbb7b 24951
a2c02241
NR
24952@subheading The @code{-environment-cd} Command
24953@findex -environment-cd
922fbb7b 24954
a2c02241 24955@subsubheading Synopsis
922fbb7b
AC
24956
24957@smallexample
a2c02241 24958 -environment-cd @var{pathdir}
922fbb7b
AC
24959@end smallexample
24960
a2c02241 24961Set @value{GDBN}'s working directory.
922fbb7b 24962
a2c02241 24963@subsubheading @value{GDBN} Command
922fbb7b 24964
a2c02241
NR
24965The corresponding @value{GDBN} command is @samp{cd}.
24966
24967@subsubheading Example
922fbb7b
AC
24968
24969@smallexample
594fe323 24970(gdb)
a2c02241
NR
24971-environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
24972^done
594fe323 24973(gdb)
922fbb7b
AC
24974@end smallexample
24975
24976
a2c02241
NR
24977@subheading The @code{-environment-directory} Command
24978@findex -environment-directory
922fbb7b
AC
24979
24980@subsubheading Synopsis
24981
24982@smallexample
a2c02241 24983 -environment-directory [ -r ] [ @var{pathdir} ]+
922fbb7b
AC
24984@end smallexample
24985
a2c02241
NR
24986Add directories @var{pathdir} to beginning of search path for source files.
24987If the @samp{-r} option is used, the search path is reset to the default
24988search path. If directories @var{pathdir} are supplied in addition to the
24989@samp{-r} option, the search path is first reset and then addition
24990occurs as normal.
24991Multiple directories may be specified, separated by blanks. Specifying
24992multiple directories in a single command
24993results in the directories added to the beginning of the
24994search path in the same order they were presented in the command.
24995If blanks are needed as
24996part of a directory name, double-quotes should be used around
24997the name. In the command output, the path will show up separated
d3e8051b 24998by the system directory-separator character. The directory-separator
a2c02241
NR
24999character must not be used
25000in any directory name.
25001If no directories are specified, the current search path is displayed.
922fbb7b
AC
25002
25003@subsubheading @value{GDBN} Command
25004
a2c02241 25005The corresponding @value{GDBN} command is @samp{dir}.
922fbb7b
AC
25006
25007@subsubheading Example
25008
922fbb7b 25009@smallexample
594fe323 25010(gdb)
a2c02241
NR
25011-environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
25012^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd"
594fe323 25013(gdb)
a2c02241
NR
25014-environment-directory ""
25015^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd"
594fe323 25016(gdb)
a2c02241
NR
25017-environment-directory -r /home/jjohnstn/src/gdb /usr/src
25018^done,source-path="/home/jjohnstn/src/gdb:/usr/src:$cdir:$cwd"
594fe323 25019(gdb)
a2c02241
NR
25020-environment-directory -r
25021^done,source-path="$cdir:$cwd"
594fe323 25022(gdb)
922fbb7b
AC
25023@end smallexample
25024
25025
a2c02241
NR
25026@subheading The @code{-environment-path} Command
25027@findex -environment-path
922fbb7b
AC
25028
25029@subsubheading Synopsis
25030
25031@smallexample
a2c02241 25032 -environment-path [ -r ] [ @var{pathdir} ]+
922fbb7b
AC
25033@end smallexample
25034
a2c02241
NR
25035Add directories @var{pathdir} to beginning of search path for object files.
25036If the @samp{-r} option is used, the search path is reset to the original
25037search path that existed at gdb start-up. If directories @var{pathdir} are
25038supplied in addition to the
25039@samp{-r} option, the search path is first reset and then addition
25040occurs as normal.
25041Multiple directories may be specified, separated by blanks. Specifying
25042multiple directories in a single command
25043results in the directories added to the beginning of the
25044search path in the same order they were presented in the command.
25045If blanks are needed as
25046part of a directory name, double-quotes should be used around
25047the name. In the command output, the path will show up separated
d3e8051b 25048by the system directory-separator character. The directory-separator
a2c02241
NR
25049character must not be used
25050in any directory name.
25051If no directories are specified, the current path is displayed.
25052
922fbb7b
AC
25053
25054@subsubheading @value{GDBN} Command
25055
a2c02241 25056The corresponding @value{GDBN} command is @samp{path}.
922fbb7b
AC
25057
25058@subsubheading Example
25059
922fbb7b 25060@smallexample
594fe323 25061(gdb)
a2c02241
NR
25062-environment-path
25063^done,path="/usr/bin"
594fe323 25064(gdb)
a2c02241
NR
25065-environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb /bin
25066^done,path="/kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb:/bin:/usr/bin"
594fe323 25067(gdb)
a2c02241
NR
25068-environment-path -r /usr/local/bin
25069^done,path="/usr/local/bin:/usr/bin"
594fe323 25070(gdb)
922fbb7b
AC
25071@end smallexample
25072
25073
a2c02241
NR
25074@subheading The @code{-environment-pwd} Command
25075@findex -environment-pwd
922fbb7b
AC
25076
25077@subsubheading Synopsis
25078
25079@smallexample
a2c02241 25080 -environment-pwd
922fbb7b
AC
25081@end smallexample
25082
a2c02241 25083Show the current working directory.
922fbb7b 25084
79a6e687 25085@subsubheading @value{GDBN} Command
922fbb7b 25086
a2c02241 25087The corresponding @value{GDBN} command is @samp{pwd}.
922fbb7b
AC
25088
25089@subsubheading Example
25090
922fbb7b 25091@smallexample
594fe323 25092(gdb)
a2c02241
NR
25093-environment-pwd
25094^done,cwd="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb"
594fe323 25095(gdb)
922fbb7b
AC
25096@end smallexample
25097
a2c02241
NR
25098@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
25099@node GDB/MI Thread Commands
25100@section @sc{gdb/mi} Thread Commands
25101
25102
25103@subheading The @code{-thread-info} Command
25104@findex -thread-info
922fbb7b
AC
25105
25106@subsubheading Synopsis
25107
25108@smallexample
8e8901c5 25109 -thread-info [ @var{thread-id} ]
922fbb7b
AC
25110@end smallexample
25111
8e8901c5
VP
25112Reports information about either a specific thread, if
25113the @var{thread-id} parameter is present, or about all
25114threads. When printing information about all threads,
25115also reports the current thread.
25116
79a6e687 25117@subsubheading @value{GDBN} Command
922fbb7b 25118
8e8901c5
VP
25119The @samp{info thread} command prints the same information
25120about all threads.
922fbb7b
AC
25121
25122@subsubheading Example
922fbb7b
AC
25123
25124@smallexample
8e8901c5
VP
25125-thread-info
25126^done,threads=[
25127@{id="2",target-id="Thread 0xb7e14b90 (LWP 21257)",
c3b108f7 25128 frame=@{level="0",addr="0xffffe410",func="__kernel_vsyscall",args=[]@},state="running"@},
8e8901c5
VP
25129@{id="1",target-id="Thread 0xb7e156b0 (LWP 21254)",
25130 frame=@{level="0",addr="0x0804891f",func="foo",args=[@{name="i",value="10"@}],
c3b108f7 25131 file="/tmp/a.c",fullname="/tmp/a.c",line="158"@},state="running"@}],
8e8901c5
VP
25132current-thread-id="1"
25133(gdb)
922fbb7b
AC
25134@end smallexample
25135
c3b108f7
VP
25136The @samp{state} field may have the following values:
25137
25138@table @code
25139@item stopped
25140The thread is stopped. Frame information is available for stopped
25141threads.
25142
25143@item running
25144The thread is running. There's no frame information for running
25145threads.
25146
25147@end table
25148
a2c02241
NR
25149@subheading The @code{-thread-list-ids} Command
25150@findex -thread-list-ids
922fbb7b 25151
a2c02241 25152@subsubheading Synopsis
922fbb7b 25153
a2c02241
NR
25154@smallexample
25155 -thread-list-ids
25156@end smallexample
922fbb7b 25157
a2c02241
NR
25158Produces a list of the currently known @value{GDBN} thread ids. At the
25159end of the list it also prints the total number of such threads.
922fbb7b 25160
c3b108f7
VP
25161This command is retained for historical reasons, the
25162@code{-thread-info} command should be used instead.
25163
922fbb7b
AC
25164@subsubheading @value{GDBN} Command
25165
a2c02241 25166Part of @samp{info threads} supplies the same information.
922fbb7b
AC
25167
25168@subsubheading Example
25169
922fbb7b 25170@smallexample
594fe323 25171(gdb)
a2c02241
NR
25172-thread-list-ids
25173^done,thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@},
592375cd 25174current-thread-id="1",number-of-threads="3"
594fe323 25175(gdb)
922fbb7b
AC
25176@end smallexample
25177
a2c02241
NR
25178
25179@subheading The @code{-thread-select} Command
25180@findex -thread-select
922fbb7b
AC
25181
25182@subsubheading Synopsis
25183
25184@smallexample
a2c02241 25185 -thread-select @var{threadnum}
922fbb7b
AC
25186@end smallexample
25187
a2c02241
NR
25188Make @var{threadnum} the current thread. It prints the number of the new
25189current thread, and the topmost frame for that thread.
922fbb7b 25190
c3b108f7
VP
25191This command is deprecated in favor of explicitly using the
25192@samp{--thread} option to each command.
25193
922fbb7b
AC
25194@subsubheading @value{GDBN} Command
25195
a2c02241 25196The corresponding @value{GDBN} command is @samp{thread}.
922fbb7b
AC
25197
25198@subsubheading Example
922fbb7b
AC
25199
25200@smallexample
594fe323 25201(gdb)
a2c02241
NR
25202-exec-next
25203^running
594fe323 25204(gdb)
a2c02241
NR
25205*stopped,reason="end-stepping-range",thread-id="2",line="187",
25206file="../../../devo/gdb/testsuite/gdb.threads/linux-dp.c"
594fe323 25207(gdb)
a2c02241
NR
25208-thread-list-ids
25209^done,
25210thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@},
25211number-of-threads="3"
594fe323 25212(gdb)
a2c02241
NR
25213-thread-select 3
25214^done,new-thread-id="3",
25215frame=@{level="0",func="vprintf",
25216args=[@{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""@},
25217@{name="arg",value="0x2"@}],file="vprintf.c",line="31"@}
594fe323 25218(gdb)
922fbb7b
AC
25219@end smallexample
25220
a2c02241
NR
25221@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
25222@node GDB/MI Program Execution
25223@section @sc{gdb/mi} Program Execution
922fbb7b 25224
ef21caaf 25225These are the asynchronous commands which generate the out-of-band
3f94c067 25226record @samp{*stopped}. Currently @value{GDBN} only really executes
ef21caaf
NR
25227asynchronously with remote targets and this interaction is mimicked in
25228other cases.
922fbb7b 25229
922fbb7b
AC
25230@subheading The @code{-exec-continue} Command
25231@findex -exec-continue
25232
25233@subsubheading Synopsis
25234
25235@smallexample
540aa8e7 25236 -exec-continue [--reverse] [--all|--thread-group N]
922fbb7b
AC
25237@end smallexample
25238
540aa8e7
MS
25239Resumes the execution of the inferior program, which will continue
25240to execute until it reaches a debugger stop event. If the
25241@samp{--reverse} option is specified, execution resumes in reverse until
25242it reaches a stop event. Stop events may include
25243@itemize @bullet
25244@item
25245breakpoints or watchpoints
25246@item
25247signals or exceptions
25248@item
25249the end of the process (or its beginning under @samp{--reverse})
25250@item
25251the end or beginning of a replay log if one is being used.
25252@end itemize
25253In all-stop mode (@pxref{All-Stop
25254Mode}), may resume only one thread, or all threads, depending on the
25255value of the @samp{scheduler-locking} variable. If @samp{--all} is
a79b8f6e 25256specified, all threads (in all inferiors) will be resumed. The @samp{--all} option is
540aa8e7
MS
25257ignored in all-stop mode. If the @samp{--thread-group} options is
25258specified, then all threads in that thread group are resumed.
922fbb7b
AC
25259
25260@subsubheading @value{GDBN} Command
25261
25262The corresponding @value{GDBN} corresponding is @samp{continue}.
25263
25264@subsubheading Example
25265
25266@smallexample
25267-exec-continue
25268^running
594fe323 25269(gdb)
922fbb7b 25270@@Hello world
a47ec5fe
AR
25271*stopped,reason="breakpoint-hit",disp="keep",bkptno="2",frame=@{
25272func="foo",args=[],file="hello.c",fullname="/home/foo/bar/hello.c",
25273line="13"@}
594fe323 25274(gdb)
922fbb7b
AC
25275@end smallexample
25276
25277
25278@subheading The @code{-exec-finish} Command
25279@findex -exec-finish
25280
25281@subsubheading Synopsis
25282
25283@smallexample
540aa8e7 25284 -exec-finish [--reverse]
922fbb7b
AC
25285@end smallexample
25286
ef21caaf
NR
25287Resumes the execution of the inferior program until the current
25288function is exited. Displays the results returned by the function.
540aa8e7
MS
25289If the @samp{--reverse} option is specified, resumes the reverse
25290execution of the inferior program until the point where current
25291function was called.
922fbb7b
AC
25292
25293@subsubheading @value{GDBN} Command
25294
25295The corresponding @value{GDBN} command is @samp{finish}.
25296
25297@subsubheading Example
25298
25299Function returning @code{void}.
25300
25301@smallexample
25302-exec-finish
25303^running
594fe323 25304(gdb)
922fbb7b
AC
25305@@hello from foo
25306*stopped,reason="function-finished",frame=@{func="main",args=[],
948d5102 25307file="hello.c",fullname="/home/foo/bar/hello.c",line="7"@}
594fe323 25308(gdb)
922fbb7b
AC
25309@end smallexample
25310
25311Function returning other than @code{void}. The name of the internal
25312@value{GDBN} variable storing the result is printed, together with the
25313value itself.
25314
25315@smallexample
25316-exec-finish
25317^running
594fe323 25318(gdb)
922fbb7b
AC
25319*stopped,reason="function-finished",frame=@{addr="0x000107b0",func="foo",
25320args=[@{name="a",value="1"],@{name="b",value="9"@}@},
948d5102 25321file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
922fbb7b 25322gdb-result-var="$1",return-value="0"
594fe323 25323(gdb)
922fbb7b
AC
25324@end smallexample
25325
25326
25327@subheading The @code{-exec-interrupt} Command
25328@findex -exec-interrupt
25329
25330@subsubheading Synopsis
25331
25332@smallexample
c3b108f7 25333 -exec-interrupt [--all|--thread-group N]
922fbb7b
AC
25334@end smallexample
25335
ef21caaf
NR
25336Interrupts the background execution of the target. Note how the token
25337associated with the stop message is the one for the execution command
25338that has been interrupted. The token for the interrupt itself only
25339appears in the @samp{^done} output. If the user is trying to
922fbb7b
AC
25340interrupt a non-running program, an error message will be printed.
25341
c3b108f7
VP
25342Note that when asynchronous execution is enabled, this command is
25343asynchronous just like other execution commands. That is, first the
25344@samp{^done} response will be printed, and the target stop will be
25345reported after that using the @samp{*stopped} notification.
25346
25347In non-stop mode, only the context thread is interrupted by default.
a79b8f6e
VP
25348All threads (in all inferiors) will be interrupted if the
25349@samp{--all} option is specified. If the @samp{--thread-group}
25350option is specified, all threads in that group will be interrupted.
c3b108f7 25351
922fbb7b
AC
25352@subsubheading @value{GDBN} Command
25353
25354The corresponding @value{GDBN} command is @samp{interrupt}.
25355
25356@subsubheading Example
25357
25358@smallexample
594fe323 25359(gdb)
922fbb7b
AC
25360111-exec-continue
25361111^running
25362
594fe323 25363(gdb)
922fbb7b
AC
25364222-exec-interrupt
25365222^done
594fe323 25366(gdb)
922fbb7b 25367111*stopped,signal-name="SIGINT",signal-meaning="Interrupt",
76ff342d 25368frame=@{addr="0x00010140",func="foo",args=[],file="try.c",
948d5102 25369fullname="/home/foo/bar/try.c",line="13"@}
594fe323 25370(gdb)
922fbb7b 25371
594fe323 25372(gdb)
922fbb7b
AC
25373-exec-interrupt
25374^error,msg="mi_cmd_exec_interrupt: Inferior not executing."
594fe323 25375(gdb)
922fbb7b
AC
25376@end smallexample
25377
83eba9b7
VP
25378@subheading The @code{-exec-jump} Command
25379@findex -exec-jump
25380
25381@subsubheading Synopsis
25382
25383@smallexample
25384 -exec-jump @var{location}
25385@end smallexample
25386
25387Resumes execution of the inferior program at the location specified by
25388parameter. @xref{Specify Location}, for a description of the
25389different forms of @var{location}.
25390
25391@subsubheading @value{GDBN} Command
25392
25393The corresponding @value{GDBN} command is @samp{jump}.
25394
25395@subsubheading Example
25396
25397@smallexample
25398-exec-jump foo.c:10
25399*running,thread-id="all"
25400^running
25401@end smallexample
25402
922fbb7b
AC
25403
25404@subheading The @code{-exec-next} Command
25405@findex -exec-next
25406
25407@subsubheading Synopsis
25408
25409@smallexample
540aa8e7 25410 -exec-next [--reverse]
922fbb7b
AC
25411@end smallexample
25412
ef21caaf
NR
25413Resumes execution of the inferior program, stopping when the beginning
25414of the next source line is reached.
922fbb7b 25415
540aa8e7
MS
25416If the @samp{--reverse} option is specified, resumes reverse execution
25417of the inferior program, stopping at the beginning of the previous
25418source line. If you issue this command on the first line of a
25419function, it will take you back to the caller of that function, to the
25420source line where the function was called.
25421
25422
922fbb7b
AC
25423@subsubheading @value{GDBN} Command
25424
25425The corresponding @value{GDBN} command is @samp{next}.
25426
25427@subsubheading Example
25428
25429@smallexample
25430-exec-next
25431^running
594fe323 25432(gdb)
922fbb7b 25433*stopped,reason="end-stepping-range",line="8",file="hello.c"
594fe323 25434(gdb)
922fbb7b
AC
25435@end smallexample
25436
25437
25438@subheading The @code{-exec-next-instruction} Command
25439@findex -exec-next-instruction
25440
25441@subsubheading Synopsis
25442
25443@smallexample
540aa8e7 25444 -exec-next-instruction [--reverse]
922fbb7b
AC
25445@end smallexample
25446
ef21caaf
NR
25447Executes one machine instruction. If the instruction is a function
25448call, continues until the function returns. If the program stops at an
25449instruction in the middle of a source line, the address will be
25450printed as well.
922fbb7b 25451
540aa8e7
MS
25452If the @samp{--reverse} option is specified, resumes reverse execution
25453of the inferior program, stopping at the previous instruction. If the
25454previously executed instruction was a return from another function,
25455it will continue to execute in reverse until the call to that function
25456(from the current stack frame) is reached.
25457
922fbb7b
AC
25458@subsubheading @value{GDBN} Command
25459
25460The corresponding @value{GDBN} command is @samp{nexti}.
25461
25462@subsubheading Example
25463
25464@smallexample
594fe323 25465(gdb)
922fbb7b
AC
25466-exec-next-instruction
25467^running
25468
594fe323 25469(gdb)
922fbb7b
AC
25470*stopped,reason="end-stepping-range",
25471addr="0x000100d4",line="5",file="hello.c"
594fe323 25472(gdb)
922fbb7b
AC
25473@end smallexample
25474
25475
25476@subheading The @code{-exec-return} Command
25477@findex -exec-return
25478
25479@subsubheading Synopsis
25480
25481@smallexample
25482 -exec-return
25483@end smallexample
25484
25485Makes current function return immediately. Doesn't execute the inferior.
25486Displays the new current frame.
25487
25488@subsubheading @value{GDBN} Command
25489
25490The corresponding @value{GDBN} command is @samp{return}.
25491
25492@subsubheading Example
25493
25494@smallexample
594fe323 25495(gdb)
922fbb7b
AC
25496200-break-insert callee4
25497200^done,bkpt=@{number="1",addr="0x00010734",
25498file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@}
594fe323 25499(gdb)
922fbb7b
AC
25500000-exec-run
25501000^running
594fe323 25502(gdb)
a47ec5fe 25503000*stopped,reason="breakpoint-hit",disp="keep",bkptno="1",
922fbb7b 25504frame=@{func="callee4",args=[],
76ff342d
DJ
25505file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
25506fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8"@}
594fe323 25507(gdb)
922fbb7b
AC
25508205-break-delete
25509205^done
594fe323 25510(gdb)
922fbb7b
AC
25511111-exec-return
25512111^done,frame=@{level="0",func="callee3",
25513args=[@{name="strarg",
25514value="0x11940 \"A string argument.\""@}],
76ff342d
DJ
25515file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
25516fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
594fe323 25517(gdb)
922fbb7b
AC
25518@end smallexample
25519
25520
25521@subheading The @code{-exec-run} Command
25522@findex -exec-run
25523
25524@subsubheading Synopsis
25525
25526@smallexample
a79b8f6e 25527 -exec-run [--all | --thread-group N]
922fbb7b
AC
25528@end smallexample
25529
ef21caaf
NR
25530Starts execution of the inferior from the beginning. The inferior
25531executes until either a breakpoint is encountered or the program
25532exits. In the latter case the output will include an exit code, if
25533the program has exited exceptionally.
922fbb7b 25534
a79b8f6e
VP
25535When no option is specified, the current inferior is started. If the
25536@samp{--thread-group} option is specified, it should refer to a thread
25537group of type @samp{process}, and that thread group will be started.
25538If the @samp{--all} option is specified, then all inferiors will be started.
25539
922fbb7b
AC
25540@subsubheading @value{GDBN} Command
25541
25542The corresponding @value{GDBN} command is @samp{run}.
25543
ef21caaf 25544@subsubheading Examples
922fbb7b
AC
25545
25546@smallexample
594fe323 25547(gdb)
922fbb7b
AC
25548-break-insert main
25549^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",line="4"@}
594fe323 25550(gdb)
922fbb7b
AC
25551-exec-run
25552^running
594fe323 25553(gdb)
a47ec5fe 25554*stopped,reason="breakpoint-hit",disp="keep",bkptno="1",
76ff342d 25555frame=@{func="main",args=[],file="recursive2.c",
948d5102 25556fullname="/home/foo/bar/recursive2.c",line="4"@}
594fe323 25557(gdb)
922fbb7b
AC
25558@end smallexample
25559
ef21caaf
NR
25560@noindent
25561Program exited normally:
25562
25563@smallexample
594fe323 25564(gdb)
ef21caaf
NR
25565-exec-run
25566^running
594fe323 25567(gdb)
ef21caaf
NR
25568x = 55
25569*stopped,reason="exited-normally"
594fe323 25570(gdb)
ef21caaf
NR
25571@end smallexample
25572
25573@noindent
25574Program exited exceptionally:
25575
25576@smallexample
594fe323 25577(gdb)
ef21caaf
NR
25578-exec-run
25579^running
594fe323 25580(gdb)
ef21caaf
NR
25581x = 55
25582*stopped,reason="exited",exit-code="01"
594fe323 25583(gdb)
ef21caaf
NR
25584@end smallexample
25585
25586Another way the program can terminate is if it receives a signal such as
25587@code{SIGINT}. In this case, @sc{gdb/mi} displays this:
25588
25589@smallexample
594fe323 25590(gdb)
ef21caaf
NR
25591*stopped,reason="exited-signalled",signal-name="SIGINT",
25592signal-meaning="Interrupt"
25593@end smallexample
25594
922fbb7b 25595
a2c02241
NR
25596@c @subheading -exec-signal
25597
25598
25599@subheading The @code{-exec-step} Command
25600@findex -exec-step
922fbb7b
AC
25601
25602@subsubheading Synopsis
25603
25604@smallexample
540aa8e7 25605 -exec-step [--reverse]
922fbb7b
AC
25606@end smallexample
25607
a2c02241
NR
25608Resumes execution of the inferior program, stopping when the beginning
25609of the next source line is reached, if the next source line is not a
25610function call. If it is, stop at the first instruction of the called
540aa8e7
MS
25611function. If the @samp{--reverse} option is specified, resumes reverse
25612execution of the inferior program, stopping at the beginning of the
25613previously executed source line.
922fbb7b
AC
25614
25615@subsubheading @value{GDBN} Command
25616
a2c02241 25617The corresponding @value{GDBN} command is @samp{step}.
922fbb7b
AC
25618
25619@subsubheading Example
25620
25621Stepping into a function:
25622
25623@smallexample
25624-exec-step
25625^running
594fe323 25626(gdb)
922fbb7b
AC
25627*stopped,reason="end-stepping-range",
25628frame=@{func="foo",args=[@{name="a",value="10"@},
76ff342d 25629@{name="b",value="0"@}],file="recursive2.c",
948d5102 25630fullname="/home/foo/bar/recursive2.c",line="11"@}
594fe323 25631(gdb)
922fbb7b
AC
25632@end smallexample
25633
25634Regular stepping:
25635
25636@smallexample
25637-exec-step
25638^running
594fe323 25639(gdb)
922fbb7b 25640*stopped,reason="end-stepping-range",line="14",file="recursive2.c"
594fe323 25641(gdb)
922fbb7b
AC
25642@end smallexample
25643
25644
25645@subheading The @code{-exec-step-instruction} Command
25646@findex -exec-step-instruction
25647
25648@subsubheading Synopsis
25649
25650@smallexample
540aa8e7 25651 -exec-step-instruction [--reverse]
922fbb7b
AC
25652@end smallexample
25653
540aa8e7
MS
25654Resumes the inferior which executes one machine instruction. If the
25655@samp{--reverse} option is specified, resumes reverse execution of the
25656inferior program, stopping at the previously executed instruction.
25657The output, once @value{GDBN} has stopped, will vary depending on
25658whether we have stopped in the middle of a source line or not. In the
25659former case, the address at which the program stopped will be printed
25660as well.
922fbb7b
AC
25661
25662@subsubheading @value{GDBN} Command
25663
25664The corresponding @value{GDBN} command is @samp{stepi}.
25665
25666@subsubheading Example
25667
25668@smallexample
594fe323 25669(gdb)
922fbb7b
AC
25670-exec-step-instruction
25671^running
25672
594fe323 25673(gdb)
922fbb7b 25674*stopped,reason="end-stepping-range",
76ff342d 25675frame=@{func="foo",args=[],file="try.c",
948d5102 25676fullname="/home/foo/bar/try.c",line="10"@}
594fe323 25677(gdb)
922fbb7b
AC
25678-exec-step-instruction
25679^running
25680
594fe323 25681(gdb)
922fbb7b 25682*stopped,reason="end-stepping-range",
76ff342d 25683frame=@{addr="0x000100f4",func="foo",args=[],file="try.c",
948d5102 25684fullname="/home/foo/bar/try.c",line="10"@}
594fe323 25685(gdb)
922fbb7b
AC
25686@end smallexample
25687
25688
25689@subheading The @code{-exec-until} Command
25690@findex -exec-until
25691
25692@subsubheading Synopsis
25693
25694@smallexample
25695 -exec-until [ @var{location} ]
25696@end smallexample
25697
ef21caaf
NR
25698Executes the inferior until the @var{location} specified in the
25699argument is reached. If there is no argument, the inferior executes
25700until a source line greater than the current one is reached. The
25701reason for stopping in this case will be @samp{location-reached}.
922fbb7b
AC
25702
25703@subsubheading @value{GDBN} Command
25704
25705The corresponding @value{GDBN} command is @samp{until}.
25706
25707@subsubheading Example
25708
25709@smallexample
594fe323 25710(gdb)
922fbb7b
AC
25711-exec-until recursive2.c:6
25712^running
594fe323 25713(gdb)
922fbb7b
AC
25714x = 55
25715*stopped,reason="location-reached",frame=@{func="main",args=[],
948d5102 25716file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="6"@}
594fe323 25717(gdb)
922fbb7b
AC
25718@end smallexample
25719
25720@ignore
25721@subheading -file-clear
25722Is this going away????
25723@end ignore
25724
351ff01a 25725@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
a2c02241
NR
25726@node GDB/MI Stack Manipulation
25727@section @sc{gdb/mi} Stack Manipulation Commands
351ff01a 25728
922fbb7b 25729
a2c02241
NR
25730@subheading The @code{-stack-info-frame} Command
25731@findex -stack-info-frame
922fbb7b
AC
25732
25733@subsubheading Synopsis
25734
25735@smallexample
a2c02241 25736 -stack-info-frame
922fbb7b
AC
25737@end smallexample
25738
a2c02241 25739Get info on the selected frame.
922fbb7b
AC
25740
25741@subsubheading @value{GDBN} Command
25742
a2c02241
NR
25743The corresponding @value{GDBN} command is @samp{info frame} or @samp{frame}
25744(without arguments).
922fbb7b
AC
25745
25746@subsubheading Example
25747
25748@smallexample
594fe323 25749(gdb)
a2c02241
NR
25750-stack-info-frame
25751^done,frame=@{level="1",addr="0x0001076c",func="callee3",
25752file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
25753fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"@}
594fe323 25754(gdb)
922fbb7b
AC
25755@end smallexample
25756
a2c02241
NR
25757@subheading The @code{-stack-info-depth} Command
25758@findex -stack-info-depth
922fbb7b
AC
25759
25760@subsubheading Synopsis
25761
25762@smallexample
a2c02241 25763 -stack-info-depth [ @var{max-depth} ]
922fbb7b
AC
25764@end smallexample
25765
a2c02241
NR
25766Return the depth of the stack. If the integer argument @var{max-depth}
25767is specified, do not count beyond @var{max-depth} frames.
922fbb7b
AC
25768
25769@subsubheading @value{GDBN} Command
25770
a2c02241 25771There's no equivalent @value{GDBN} command.
922fbb7b
AC
25772
25773@subsubheading Example
25774
a2c02241
NR
25775For a stack with frame levels 0 through 11:
25776
922fbb7b 25777@smallexample
594fe323 25778(gdb)
a2c02241
NR
25779-stack-info-depth
25780^done,depth="12"
594fe323 25781(gdb)
a2c02241
NR
25782-stack-info-depth 4
25783^done,depth="4"
594fe323 25784(gdb)
a2c02241
NR
25785-stack-info-depth 12
25786^done,depth="12"
594fe323 25787(gdb)
a2c02241
NR
25788-stack-info-depth 11
25789^done,depth="11"
594fe323 25790(gdb)
a2c02241
NR
25791-stack-info-depth 13
25792^done,depth="12"
594fe323 25793(gdb)
922fbb7b
AC
25794@end smallexample
25795
a2c02241
NR
25796@subheading The @code{-stack-list-arguments} Command
25797@findex -stack-list-arguments
922fbb7b
AC
25798
25799@subsubheading Synopsis
25800
25801@smallexample
3afae151 25802 -stack-list-arguments @var{print-values}
a2c02241 25803 [ @var{low-frame} @var{high-frame} ]
922fbb7b
AC
25804@end smallexample
25805
a2c02241
NR
25806Display a list of the arguments for the frames between @var{low-frame}
25807and @var{high-frame} (inclusive). If @var{low-frame} and
2f1acb09
VP
25808@var{high-frame} are not provided, list the arguments for the whole
25809call stack. If the two arguments are equal, show the single frame
25810at the corresponding level. It is an error if @var{low-frame} is
25811larger than the actual number of frames. On the other hand,
25812@var{high-frame} may be larger than the actual number of frames, in
25813which case only existing frames will be returned.
a2c02241 25814
3afae151
VP
25815If @var{print-values} is 0 or @code{--no-values}, print only the names of
25816the variables; if it is 1 or @code{--all-values}, print also their
25817values; and if it is 2 or @code{--simple-values}, print the name,
25818type and value for simple data types, and the name and type for arrays,
25819structures and unions.
922fbb7b 25820
b3372f91
VP
25821Use of this command to obtain arguments in a single frame is
25822deprecated in favor of the @samp{-stack-list-variables} command.
25823
922fbb7b
AC
25824@subsubheading @value{GDBN} Command
25825
a2c02241
NR
25826@value{GDBN} does not have an equivalent command. @code{gdbtk} has a
25827@samp{gdb_get_args} command which partially overlaps with the
25828functionality of @samp{-stack-list-arguments}.
922fbb7b
AC
25829
25830@subsubheading Example
922fbb7b 25831
a2c02241 25832@smallexample
594fe323 25833(gdb)
a2c02241
NR
25834-stack-list-frames
25835^done,
25836stack=[
25837frame=@{level="0",addr="0x00010734",func="callee4",
25838file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
25839fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8"@},
25840frame=@{level="1",addr="0x0001076c",func="callee3",
25841file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
25842fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"@},
25843frame=@{level="2",addr="0x0001078c",func="callee2",
25844file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
25845fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="22"@},
25846frame=@{level="3",addr="0x000107b4",func="callee1",
25847file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
25848fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="27"@},
25849frame=@{level="4",addr="0x000107e0",func="main",
25850file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
25851fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="32"@}]
594fe323 25852(gdb)
a2c02241
NR
25853-stack-list-arguments 0
25854^done,
25855stack-args=[
25856frame=@{level="0",args=[]@},
25857frame=@{level="1",args=[name="strarg"]@},
25858frame=@{level="2",args=[name="intarg",name="strarg"]@},
25859frame=@{level="3",args=[name="intarg",name="strarg",name="fltarg"]@},
25860frame=@{level="4",args=[]@}]
594fe323 25861(gdb)
a2c02241
NR
25862-stack-list-arguments 1
25863^done,
25864stack-args=[
25865frame=@{level="0",args=[]@},
25866frame=@{level="1",
25867 args=[@{name="strarg",value="0x11940 \"A string argument.\""@}]@},
25868frame=@{level="2",args=[
25869@{name="intarg",value="2"@},
25870@{name="strarg",value="0x11940 \"A string argument.\""@}]@},
25871@{frame=@{level="3",args=[
25872@{name="intarg",value="2"@},
25873@{name="strarg",value="0x11940 \"A string argument.\""@},
25874@{name="fltarg",value="3.5"@}]@},
25875frame=@{level="4",args=[]@}]
594fe323 25876(gdb)
a2c02241
NR
25877-stack-list-arguments 0 2 2
25878^done,stack-args=[frame=@{level="2",args=[name="intarg",name="strarg"]@}]
594fe323 25879(gdb)
a2c02241
NR
25880-stack-list-arguments 1 2 2
25881^done,stack-args=[frame=@{level="2",
25882args=[@{name="intarg",value="2"@},
25883@{name="strarg",value="0x11940 \"A string argument.\""@}]@}]
594fe323 25884(gdb)
a2c02241
NR
25885@end smallexample
25886
25887@c @subheading -stack-list-exception-handlers
922fbb7b 25888
a2c02241
NR
25889
25890@subheading The @code{-stack-list-frames} Command
25891@findex -stack-list-frames
1abaf70c
BR
25892
25893@subsubheading Synopsis
25894
25895@smallexample
a2c02241 25896 -stack-list-frames [ @var{low-frame} @var{high-frame} ]
1abaf70c
BR
25897@end smallexample
25898
a2c02241
NR
25899List the frames currently on the stack. For each frame it displays the
25900following info:
25901
25902@table @samp
25903@item @var{level}
d3e8051b 25904The frame number, 0 being the topmost frame, i.e., the innermost function.
a2c02241
NR
25905@item @var{addr}
25906The @code{$pc} value for that frame.
25907@item @var{func}
25908Function name.
25909@item @var{file}
25910File name of the source file where the function lives.
25911@item @var{line}
25912Line number corresponding to the @code{$pc}.
25913@end table
25914
25915If invoked without arguments, this command prints a backtrace for the
25916whole stack. If given two integer arguments, it shows the frames whose
25917levels are between the two arguments (inclusive). If the two arguments
2ab1eb7a
VP
25918are equal, it shows the single frame at the corresponding level. It is
25919an error if @var{low-frame} is larger than the actual number of
a5451f4e 25920frames. On the other hand, @var{high-frame} may be larger than the
2ab1eb7a 25921actual number of frames, in which case only existing frames will be returned.
1abaf70c
BR
25922
25923@subsubheading @value{GDBN} Command
25924
a2c02241 25925The corresponding @value{GDBN} commands are @samp{backtrace} and @samp{where}.
1abaf70c
BR
25926
25927@subsubheading Example
25928
a2c02241
NR
25929Full stack backtrace:
25930
1abaf70c 25931@smallexample
594fe323 25932(gdb)
a2c02241
NR
25933-stack-list-frames
25934^done,stack=
25935[frame=@{level="0",addr="0x0001076c",func="foo",
25936 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="11"@},
25937frame=@{level="1",addr="0x000107a4",func="foo",
25938 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
25939frame=@{level="2",addr="0x000107a4",func="foo",
25940 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
25941frame=@{level="3",addr="0x000107a4",func="foo",
25942 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
25943frame=@{level="4",addr="0x000107a4",func="foo",
25944 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
25945frame=@{level="5",addr="0x000107a4",func="foo",
25946 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
25947frame=@{level="6",addr="0x000107a4",func="foo",
25948 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
25949frame=@{level="7",addr="0x000107a4",func="foo",
25950 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
25951frame=@{level="8",addr="0x000107a4",func="foo",
25952 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
25953frame=@{level="9",addr="0x000107a4",func="foo",
25954 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
25955frame=@{level="10",addr="0x000107a4",func="foo",
25956 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
25957frame=@{level="11",addr="0x00010738",func="main",
25958 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="4"@}]
594fe323 25959(gdb)
1abaf70c
BR
25960@end smallexample
25961
a2c02241 25962Show frames between @var{low_frame} and @var{high_frame}:
1abaf70c 25963
a2c02241 25964@smallexample
594fe323 25965(gdb)
a2c02241
NR
25966-stack-list-frames 3 5
25967^done,stack=
25968[frame=@{level="3",addr="0x000107a4",func="foo",
25969 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
25970frame=@{level="4",addr="0x000107a4",func="foo",
25971 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
25972frame=@{level="5",addr="0x000107a4",func="foo",
25973 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@}]
594fe323 25974(gdb)
a2c02241 25975@end smallexample
922fbb7b 25976
a2c02241 25977Show a single frame:
922fbb7b
AC
25978
25979@smallexample
594fe323 25980(gdb)
a2c02241
NR
25981-stack-list-frames 3 3
25982^done,stack=
25983[frame=@{level="3",addr="0x000107a4",func="foo",
25984 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@}]
594fe323 25985(gdb)
922fbb7b
AC
25986@end smallexample
25987
922fbb7b 25988
a2c02241
NR
25989@subheading The @code{-stack-list-locals} Command
25990@findex -stack-list-locals
57c22c6c 25991
a2c02241 25992@subsubheading Synopsis
922fbb7b
AC
25993
25994@smallexample
a2c02241 25995 -stack-list-locals @var{print-values}
922fbb7b
AC
25996@end smallexample
25997
a2c02241
NR
25998Display the local variable names for the selected frame. If
25999@var{print-values} is 0 or @code{--no-values}, print only the names of
26000the variables; if it is 1 or @code{--all-values}, print also their
26001values; and if it is 2 or @code{--simple-values}, print the name,
3afae151 26002type and value for simple data types, and the name and type for arrays,
a2c02241
NR
26003structures and unions. In this last case, a frontend can immediately
26004display the value of simple data types and create variable objects for
d3e8051b 26005other data types when the user wishes to explore their values in
a2c02241 26006more detail.
922fbb7b 26007
b3372f91
VP
26008This command is deprecated in favor of the
26009@samp{-stack-list-variables} command.
26010
922fbb7b
AC
26011@subsubheading @value{GDBN} Command
26012
a2c02241 26013@samp{info locals} in @value{GDBN}, @samp{gdb_get_locals} in @code{gdbtk}.
922fbb7b
AC
26014
26015@subsubheading Example
922fbb7b
AC
26016
26017@smallexample
594fe323 26018(gdb)
a2c02241
NR
26019-stack-list-locals 0
26020^done,locals=[name="A",name="B",name="C"]
594fe323 26021(gdb)
a2c02241
NR
26022-stack-list-locals --all-values
26023^done,locals=[@{name="A",value="1"@},@{name="B",value="2"@},
26024 @{name="C",value="@{1, 2, 3@}"@}]
26025-stack-list-locals --simple-values
26026^done,locals=[@{name="A",type="int",value="1"@},
26027 @{name="B",type="int",value="2"@},@{name="C",type="int [3]"@}]
594fe323 26028(gdb)
922fbb7b
AC
26029@end smallexample
26030
b3372f91
VP
26031@subheading The @code{-stack-list-variables} Command
26032@findex -stack-list-variables
26033
26034@subsubheading Synopsis
26035
26036@smallexample
26037 -stack-list-variables @var{print-values}
26038@end smallexample
26039
26040Display the names of local variables and function arguments for the selected frame. If
26041@var{print-values} is 0 or @code{--no-values}, print only the names of
26042the variables; if it is 1 or @code{--all-values}, print also their
26043values; and if it is 2 or @code{--simple-values}, print the name,
3afae151 26044type and value for simple data types, and the name and type for arrays,
b3372f91
VP
26045structures and unions.
26046
26047@subsubheading Example
26048
26049@smallexample
26050(gdb)
26051-stack-list-variables --thread 1 --frame 0 --all-values
4f412fd0 26052^done,variables=[@{name="x",value="11"@},@{name="s",value="@{a = 1, b = 2@}"@}]
b3372f91
VP
26053(gdb)
26054@end smallexample
26055
922fbb7b 26056
a2c02241
NR
26057@subheading The @code{-stack-select-frame} Command
26058@findex -stack-select-frame
922fbb7b
AC
26059
26060@subsubheading Synopsis
26061
26062@smallexample
a2c02241 26063 -stack-select-frame @var{framenum}
922fbb7b
AC
26064@end smallexample
26065
a2c02241
NR
26066Change the selected frame. Select a different frame @var{framenum} on
26067the stack.
922fbb7b 26068
c3b108f7
VP
26069This command in deprecated in favor of passing the @samp{--frame}
26070option to every command.
26071
922fbb7b
AC
26072@subsubheading @value{GDBN} Command
26073
a2c02241
NR
26074The corresponding @value{GDBN} commands are @samp{frame}, @samp{up},
26075@samp{down}, @samp{select-frame}, @samp{up-silent}, and @samp{down-silent}.
922fbb7b
AC
26076
26077@subsubheading Example
26078
26079@smallexample
594fe323 26080(gdb)
a2c02241 26081-stack-select-frame 2
922fbb7b 26082^done
594fe323 26083(gdb)
922fbb7b
AC
26084@end smallexample
26085
26086@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
a2c02241
NR
26087@node GDB/MI Variable Objects
26088@section @sc{gdb/mi} Variable Objects
922fbb7b 26089
a1b5960f 26090@ignore
922fbb7b 26091
a2c02241 26092@subheading Motivation for Variable Objects in @sc{gdb/mi}
922fbb7b 26093
a2c02241
NR
26094For the implementation of a variable debugger window (locals, watched
26095expressions, etc.), we are proposing the adaptation of the existing code
26096used by @code{Insight}.
922fbb7b 26097
a2c02241 26098The two main reasons for that are:
922fbb7b 26099
a2c02241
NR
26100@enumerate 1
26101@item
26102It has been proven in practice (it is already on its second generation).
922fbb7b 26103
a2c02241
NR
26104@item
26105It will shorten development time (needless to say how important it is
26106now).
26107@end enumerate
922fbb7b 26108
a2c02241
NR
26109The original interface was designed to be used by Tcl code, so it was
26110slightly changed so it could be used through @sc{gdb/mi}. This section
26111describes the @sc{gdb/mi} operations that will be available and gives some
26112hints about their use.
922fbb7b 26113
a2c02241
NR
26114@emph{Note}: In addition to the set of operations described here, we
26115expect the @sc{gui} implementation of a variable window to require, at
26116least, the following operations:
922fbb7b 26117
a2c02241
NR
26118@itemize @bullet
26119@item @code{-gdb-show} @code{output-radix}
26120@item @code{-stack-list-arguments}
26121@item @code{-stack-list-locals}
26122@item @code{-stack-select-frame}
26123@end itemize
922fbb7b 26124
a1b5960f
VP
26125@end ignore
26126
c8b2f53c 26127@subheading Introduction to Variable Objects
922fbb7b 26128
a2c02241 26129@cindex variable objects in @sc{gdb/mi}
c8b2f53c
VP
26130
26131Variable objects are "object-oriented" MI interface for examining and
26132changing values of expressions. Unlike some other MI interfaces that
26133work with expressions, variable objects are specifically designed for
26134simple and efficient presentation in the frontend. A variable object
26135is identified by string name. When a variable object is created, the
26136frontend specifies the expression for that variable object. The
26137expression can be a simple variable, or it can be an arbitrary complex
26138expression, and can even involve CPU registers. After creating a
26139variable object, the frontend can invoke other variable object
26140operations---for example to obtain or change the value of a variable
26141object, or to change display format.
26142
26143Variable objects have hierarchical tree structure. Any variable object
26144that corresponds to a composite type, such as structure in C, has
26145a number of child variable objects, for example corresponding to each
26146element of a structure. A child variable object can itself have
26147children, recursively. Recursion ends when we reach
25d5ea92
VP
26148leaf variable objects, which always have built-in types. Child variable
26149objects are created only by explicit request, so if a frontend
26150is not interested in the children of a particular variable object, no
26151child will be created.
c8b2f53c
VP
26152
26153For a leaf variable object it is possible to obtain its value as a
26154string, or set the value from a string. String value can be also
26155obtained for a non-leaf variable object, but it's generally a string
26156that only indicates the type of the object, and does not list its
26157contents. Assignment to a non-leaf variable object is not allowed.
26158
26159A frontend does not need to read the values of all variable objects each time
26160the program stops. Instead, MI provides an update command that lists all
26161variable objects whose values has changed since the last update
26162operation. This considerably reduces the amount of data that must
25d5ea92
VP
26163be transferred to the frontend. As noted above, children variable
26164objects are created on demand, and only leaf variable objects have a
26165real value. As result, gdb will read target memory only for leaf
26166variables that frontend has created.
26167
26168The automatic update is not always desirable. For example, a frontend
26169might want to keep a value of some expression for future reference,
26170and never update it. For another example, fetching memory is
26171relatively slow for embedded targets, so a frontend might want
26172to disable automatic update for the variables that are either not
26173visible on the screen, or ``closed''. This is possible using so
26174called ``frozen variable objects''. Such variable objects are never
26175implicitly updated.
922fbb7b 26176
c3b108f7
VP
26177Variable objects can be either @dfn{fixed} or @dfn{floating}. For the
26178fixed variable object, the expression is parsed when the variable
26179object is created, including associating identifiers to specific
26180variables. The meaning of expression never changes. For a floating
26181variable object the values of variables whose names appear in the
26182expressions are re-evaluated every time in the context of the current
26183frame. Consider this example:
26184
26185@smallexample
26186void do_work(...)
26187@{
26188 struct work_state state;
26189
26190 if (...)
26191 do_work(...);
26192@}
26193@end smallexample
26194
26195If a fixed variable object for the @code{state} variable is created in
26196this function, and we enter the recursive call, the the variable
26197object will report the value of @code{state} in the top-level
26198@code{do_work} invocation. On the other hand, a floating variable
26199object will report the value of @code{state} in the current frame.
26200
26201If an expression specified when creating a fixed variable object
26202refers to a local variable, the variable object becomes bound to the
26203thread and frame in which the variable object is created. When such
26204variable object is updated, @value{GDBN} makes sure that the
26205thread/frame combination the variable object is bound to still exists,
26206and re-evaluates the variable object in context of that thread/frame.
26207
a2c02241
NR
26208The following is the complete set of @sc{gdb/mi} operations defined to
26209access this functionality:
922fbb7b 26210
a2c02241
NR
26211@multitable @columnfractions .4 .6
26212@item @strong{Operation}
26213@tab @strong{Description}
922fbb7b 26214
0cc7d26f
TT
26215@item @code{-enable-pretty-printing}
26216@tab enable Python-based pretty-printing
a2c02241
NR
26217@item @code{-var-create}
26218@tab create a variable object
26219@item @code{-var-delete}
22d8a470 26220@tab delete the variable object and/or its children
a2c02241
NR
26221@item @code{-var-set-format}
26222@tab set the display format of this variable
26223@item @code{-var-show-format}
26224@tab show the display format of this variable
26225@item @code{-var-info-num-children}
26226@tab tells how many children this object has
26227@item @code{-var-list-children}
26228@tab return a list of the object's children
26229@item @code{-var-info-type}
26230@tab show the type of this variable object
26231@item @code{-var-info-expression}
02142340
VP
26232@tab print parent-relative expression that this variable object represents
26233@item @code{-var-info-path-expression}
26234@tab print full expression that this variable object represents
a2c02241
NR
26235@item @code{-var-show-attributes}
26236@tab is this variable editable? does it exist here?
26237@item @code{-var-evaluate-expression}
26238@tab get the value of this variable
26239@item @code{-var-assign}
26240@tab set the value of this variable
26241@item @code{-var-update}
26242@tab update the variable and its children
25d5ea92
VP
26243@item @code{-var-set-frozen}
26244@tab set frozeness attribute
0cc7d26f
TT
26245@item @code{-var-set-update-range}
26246@tab set range of children to display on update
a2c02241 26247@end multitable
922fbb7b 26248
a2c02241
NR
26249In the next subsection we describe each operation in detail and suggest
26250how it can be used.
922fbb7b 26251
a2c02241 26252@subheading Description And Use of Operations on Variable Objects
922fbb7b 26253
0cc7d26f
TT
26254@subheading The @code{-enable-pretty-printing} Command
26255@findex -enable-pretty-printing
26256
26257@smallexample
26258-enable-pretty-printing
26259@end smallexample
26260
26261@value{GDBN} allows Python-based visualizers to affect the output of the
26262MI variable object commands. However, because there was no way to
26263implement this in a fully backward-compatible way, a front end must
26264request that this functionality be enabled.
26265
26266Once enabled, this feature cannot be disabled.
26267
26268Note that if Python support has not been compiled into @value{GDBN},
26269this command will still succeed (and do nothing).
26270
f43030c4
TT
26271This feature is currently (as of @value{GDBN} 7.0) experimental, and
26272may work differently in future versions of @value{GDBN}.
26273
a2c02241
NR
26274@subheading The @code{-var-create} Command
26275@findex -var-create
ef21caaf 26276
a2c02241 26277@subsubheading Synopsis
ef21caaf 26278
a2c02241
NR
26279@smallexample
26280 -var-create @{@var{name} | "-"@}
c3b108f7 26281 @{@var{frame-addr} | "*" | "@@"@} @var{expression}
a2c02241
NR
26282@end smallexample
26283
26284This operation creates a variable object, which allows the monitoring of
26285a variable, the result of an expression, a memory cell or a CPU
26286register.
ef21caaf 26287
a2c02241
NR
26288The @var{name} parameter is the string by which the object can be
26289referenced. It must be unique. If @samp{-} is specified, the varobj
26290system will generate a string ``varNNNNNN'' automatically. It will be
c3b108f7 26291unique provided that one does not specify @var{name} of that format.
a2c02241 26292The command fails if a duplicate name is found.
ef21caaf 26293
a2c02241
NR
26294The frame under which the expression should be evaluated can be
26295specified by @var{frame-addr}. A @samp{*} indicates that the current
c3b108f7
VP
26296frame should be used. A @samp{@@} indicates that a floating variable
26297object must be created.
922fbb7b 26298
a2c02241
NR
26299@var{expression} is any expression valid on the current language set (must not
26300begin with a @samp{*}), or one of the following:
922fbb7b 26301
a2c02241
NR
26302@itemize @bullet
26303@item
26304@samp{*@var{addr}}, where @var{addr} is the address of a memory cell
922fbb7b 26305
a2c02241
NR
26306@item
26307@samp{*@var{addr}-@var{addr}} --- a memory address range (TBD)
922fbb7b 26308
a2c02241
NR
26309@item
26310@samp{$@var{regname}} --- a CPU register name
26311@end itemize
922fbb7b 26312
0cc7d26f
TT
26313@cindex dynamic varobj
26314A varobj's contents may be provided by a Python-based pretty-printer. In this
26315case the varobj is known as a @dfn{dynamic varobj}. Dynamic varobjs
26316have slightly different semantics in some cases. If the
26317@code{-enable-pretty-printing} command is not sent, then @value{GDBN}
26318will never create a dynamic varobj. This ensures backward
26319compatibility for existing clients.
26320
a2c02241 26321@subsubheading Result
922fbb7b 26322
0cc7d26f
TT
26323This operation returns attributes of the newly-created varobj. These
26324are:
26325
26326@table @samp
26327@item name
26328The name of the varobj.
26329
26330@item numchild
26331The number of children of the varobj. This number is not necessarily
26332reliable for a dynamic varobj. Instead, you must examine the
26333@samp{has_more} attribute.
26334
26335@item value
26336The varobj's scalar value. For a varobj whose type is some sort of
26337aggregate (e.g., a @code{struct}), or for a dynamic varobj, this value
26338will not be interesting.
26339
26340@item type
26341The varobj's type. This is a string representation of the type, as
26342would be printed by the @value{GDBN} CLI.
26343
26344@item thread-id
26345If a variable object is bound to a specific thread, then this is the
26346thread's identifier.
26347
26348@item has_more
26349For a dynamic varobj, this indicates whether there appear to be any
26350children available. For a non-dynamic varobj, this will be 0.
26351
26352@item dynamic
26353This attribute will be present and have the value @samp{1} if the
26354varobj is a dynamic varobj. If the varobj is not a dynamic varobj,
26355then this attribute will not be present.
26356
26357@item displayhint
26358A dynamic varobj can supply a display hint to the front end. The
26359value comes directly from the Python pretty-printer object's
4c374409 26360@code{display_hint} method. @xref{Pretty Printing API}.
0cc7d26f
TT
26361@end table
26362
26363Typical output will look like this:
922fbb7b
AC
26364
26365@smallexample
0cc7d26f
TT
26366 name="@var{name}",numchild="@var{N}",type="@var{type}",thread-id="@var{M}",
26367 has_more="@var{has_more}"
dcaaae04
NR
26368@end smallexample
26369
a2c02241
NR
26370
26371@subheading The @code{-var-delete} Command
26372@findex -var-delete
922fbb7b
AC
26373
26374@subsubheading Synopsis
26375
26376@smallexample
22d8a470 26377 -var-delete [ -c ] @var{name}
922fbb7b
AC
26378@end smallexample
26379
a2c02241 26380Deletes a previously created variable object and all of its children.
22d8a470 26381With the @samp{-c} option, just deletes the children.
922fbb7b 26382
a2c02241 26383Returns an error if the object @var{name} is not found.
922fbb7b 26384
922fbb7b 26385
a2c02241
NR
26386@subheading The @code{-var-set-format} Command
26387@findex -var-set-format
922fbb7b 26388
a2c02241 26389@subsubheading Synopsis
922fbb7b
AC
26390
26391@smallexample
a2c02241 26392 -var-set-format @var{name} @var{format-spec}
922fbb7b
AC
26393@end smallexample
26394
a2c02241
NR
26395Sets the output format for the value of the object @var{name} to be
26396@var{format-spec}.
26397
de051565 26398@anchor{-var-set-format}
a2c02241
NR
26399The syntax for the @var{format-spec} is as follows:
26400
26401@smallexample
26402 @var{format-spec} @expansion{}
26403 @{binary | decimal | hexadecimal | octal | natural@}
26404@end smallexample
26405
c8b2f53c
VP
26406The natural format is the default format choosen automatically
26407based on the variable type (like decimal for an @code{int}, hex
26408for pointers, etc.).
26409
26410For a variable with children, the format is set only on the
26411variable itself, and the children are not affected.
a2c02241
NR
26412
26413@subheading The @code{-var-show-format} Command
26414@findex -var-show-format
922fbb7b
AC
26415
26416@subsubheading Synopsis
26417
26418@smallexample
a2c02241 26419 -var-show-format @var{name}
922fbb7b
AC
26420@end smallexample
26421
a2c02241 26422Returns the format used to display the value of the object @var{name}.
922fbb7b 26423
a2c02241
NR
26424@smallexample
26425 @var{format} @expansion{}
26426 @var{format-spec}
26427@end smallexample
922fbb7b 26428
922fbb7b 26429
a2c02241
NR
26430@subheading The @code{-var-info-num-children} Command
26431@findex -var-info-num-children
26432
26433@subsubheading Synopsis
26434
26435@smallexample
26436 -var-info-num-children @var{name}
26437@end smallexample
26438
26439Returns the number of children of a variable object @var{name}:
26440
26441@smallexample
26442 numchild=@var{n}
26443@end smallexample
26444
0cc7d26f
TT
26445Note that this number is not completely reliable for a dynamic varobj.
26446It will return the current number of children, but more children may
26447be available.
26448
a2c02241
NR
26449
26450@subheading The @code{-var-list-children} Command
26451@findex -var-list-children
26452
26453@subsubheading Synopsis
26454
26455@smallexample
0cc7d26f 26456 -var-list-children [@var{print-values}] @var{name} [@var{from} @var{to}]
a2c02241 26457@end smallexample
b569d230 26458@anchor{-var-list-children}
a2c02241
NR
26459
26460Return a list of the children of the specified variable object and
26461create variable objects for them, if they do not already exist. With
f5011d11 26462a single argument or if @var{print-values} has a value of 0 or
a2c02241
NR
26463@code{--no-values}, print only the names of the variables; if
26464@var{print-values} is 1 or @code{--all-values}, also print their
26465values; and if it is 2 or @code{--simple-values} print the name and
26466value for simple data types and just the name for arrays, structures
26467and unions.
922fbb7b 26468
0cc7d26f
TT
26469@var{from} and @var{to}, if specified, indicate the range of children
26470to report. If @var{from} or @var{to} is less than zero, the range is
26471reset and all children will be reported. Otherwise, children starting
26472at @var{from} (zero-based) and up to and excluding @var{to} will be
26473reported.
26474
26475If a child range is requested, it will only affect the current call to
26476@code{-var-list-children}, but not future calls to @code{-var-update}.
26477For this, you must instead use @code{-var-set-update-range}. The
26478intent of this approach is to enable a front end to implement any
26479update approach it likes; for example, scrolling a view may cause the
26480front end to request more children with @code{-var-list-children}, and
26481then the front end could call @code{-var-set-update-range} with a
26482different range to ensure that future updates are restricted to just
26483the visible items.
26484
b569d230
EZ
26485For each child the following results are returned:
26486
26487@table @var
26488
26489@item name
26490Name of the variable object created for this child.
26491
26492@item exp
26493The expression to be shown to the user by the front end to designate this child.
26494For example this may be the name of a structure member.
26495
0cc7d26f
TT
26496For a dynamic varobj, this value cannot be used to form an
26497expression. There is no way to do this at all with a dynamic varobj.
26498
b569d230
EZ
26499For C/C@t{++} structures there are several pseudo children returned to
26500designate access qualifiers. For these pseudo children @var{exp} is
26501@samp{public}, @samp{private}, or @samp{protected}. In this case the
26502type and value are not present.
26503
0cc7d26f
TT
26504A dynamic varobj will not report the access qualifying
26505pseudo-children, regardless of the language. This information is not
26506available at all with a dynamic varobj.
26507
b569d230 26508@item numchild
0cc7d26f
TT
26509Number of children this child has. For a dynamic varobj, this will be
265100.
b569d230
EZ
26511
26512@item type
26513The type of the child.
26514
26515@item value
26516If values were requested, this is the value.
26517
26518@item thread-id
26519If this variable object is associated with a thread, this is the thread id.
26520Otherwise this result is not present.
26521
26522@item frozen
26523If the variable object is frozen, this variable will be present with a value of 1.
26524@end table
26525
0cc7d26f
TT
26526The result may have its own attributes:
26527
26528@table @samp
26529@item displayhint
26530A dynamic varobj can supply a display hint to the front end. The
26531value comes directly from the Python pretty-printer object's
4c374409 26532@code{display_hint} method. @xref{Pretty Printing API}.
0cc7d26f
TT
26533
26534@item has_more
26535This is an integer attribute which is nonzero if there are children
26536remaining after the end of the selected range.
26537@end table
26538
922fbb7b
AC
26539@subsubheading Example
26540
26541@smallexample
594fe323 26542(gdb)
a2c02241 26543 -var-list-children n
b569d230 26544 ^done,numchild=@var{n},children=[child=@{name=@var{name},exp=@var{exp},
a2c02241 26545 numchild=@var{n},type=@var{type}@},@r{(repeats N times)}]
594fe323 26546(gdb)
a2c02241 26547 -var-list-children --all-values n
b569d230 26548 ^done,numchild=@var{n},children=[child=@{name=@var{name},exp=@var{exp},
a2c02241 26549 numchild=@var{n},value=@var{value},type=@var{type}@},@r{(repeats N times)}]
922fbb7b
AC
26550@end smallexample
26551
922fbb7b 26552
a2c02241
NR
26553@subheading The @code{-var-info-type} Command
26554@findex -var-info-type
922fbb7b 26555
a2c02241
NR
26556@subsubheading Synopsis
26557
26558@smallexample
26559 -var-info-type @var{name}
26560@end smallexample
26561
26562Returns the type of the specified variable @var{name}. The type is
26563returned as a string in the same format as it is output by the
26564@value{GDBN} CLI:
26565
26566@smallexample
26567 type=@var{typename}
26568@end smallexample
26569
26570
26571@subheading The @code{-var-info-expression} Command
26572@findex -var-info-expression
922fbb7b
AC
26573
26574@subsubheading Synopsis
26575
26576@smallexample
a2c02241 26577 -var-info-expression @var{name}
922fbb7b
AC
26578@end smallexample
26579
02142340
VP
26580Returns a string that is suitable for presenting this
26581variable object in user interface. The string is generally
26582not valid expression in the current language, and cannot be evaluated.
26583
26584For example, if @code{a} is an array, and variable object
26585@code{A} was created for @code{a}, then we'll get this output:
922fbb7b 26586
a2c02241 26587@smallexample
02142340
VP
26588(gdb) -var-info-expression A.1
26589^done,lang="C",exp="1"
a2c02241 26590@end smallexample
922fbb7b 26591
a2c02241 26592@noindent
02142340
VP
26593Here, the values of @code{lang} can be @code{@{"C" | "C++" | "Java"@}}.
26594
26595Note that the output of the @code{-var-list-children} command also
26596includes those expressions, so the @code{-var-info-expression} command
26597is of limited use.
26598
26599@subheading The @code{-var-info-path-expression} Command
26600@findex -var-info-path-expression
26601
26602@subsubheading Synopsis
26603
26604@smallexample
26605 -var-info-path-expression @var{name}
26606@end smallexample
26607
26608Returns an expression that can be evaluated in the current
26609context and will yield the same value that a variable object has.
26610Compare this with the @code{-var-info-expression} command, which
26611result can be used only for UI presentation. Typical use of
26612the @code{-var-info-path-expression} command is creating a
26613watchpoint from a variable object.
26614
0cc7d26f
TT
26615This command is currently not valid for children of a dynamic varobj,
26616and will give an error when invoked on one.
26617
02142340
VP
26618For example, suppose @code{C} is a C@t{++} class, derived from class
26619@code{Base}, and that the @code{Base} class has a member called
26620@code{m_size}. Assume a variable @code{c} is has the type of
26621@code{C} and a variable object @code{C} was created for variable
26622@code{c}. Then, we'll get this output:
26623@smallexample
26624(gdb) -var-info-path-expression C.Base.public.m_size
26625^done,path_expr=((Base)c).m_size)
26626@end smallexample
922fbb7b 26627
a2c02241
NR
26628@subheading The @code{-var-show-attributes} Command
26629@findex -var-show-attributes
922fbb7b 26630
a2c02241 26631@subsubheading Synopsis
922fbb7b 26632
a2c02241
NR
26633@smallexample
26634 -var-show-attributes @var{name}
26635@end smallexample
922fbb7b 26636
a2c02241 26637List attributes of the specified variable object @var{name}:
922fbb7b
AC
26638
26639@smallexample
a2c02241 26640 status=@var{attr} [ ( ,@var{attr} )* ]
922fbb7b
AC
26641@end smallexample
26642
a2c02241
NR
26643@noindent
26644where @var{attr} is @code{@{ @{ editable | noneditable @} | TBD @}}.
26645
26646@subheading The @code{-var-evaluate-expression} Command
26647@findex -var-evaluate-expression
26648
26649@subsubheading Synopsis
26650
26651@smallexample
de051565 26652 -var-evaluate-expression [-f @var{format-spec}] @var{name}
a2c02241
NR
26653@end smallexample
26654
26655Evaluates the expression that is represented by the specified variable
de051565
MK
26656object and returns its value as a string. The format of the string
26657can be specified with the @samp{-f} option. The possible values of
26658this option are the same as for @code{-var-set-format}
26659(@pxref{-var-set-format}). If the @samp{-f} option is not specified,
26660the current display format will be used. The current display format
26661can be changed using the @code{-var-set-format} command.
a2c02241
NR
26662
26663@smallexample
26664 value=@var{value}
26665@end smallexample
26666
26667Note that one must invoke @code{-var-list-children} for a variable
26668before the value of a child variable can be evaluated.
26669
26670@subheading The @code{-var-assign} Command
26671@findex -var-assign
26672
26673@subsubheading Synopsis
26674
26675@smallexample
26676 -var-assign @var{name} @var{expression}
26677@end smallexample
26678
26679Assigns the value of @var{expression} to the variable object specified
26680by @var{name}. The object must be @samp{editable}. If the variable's
26681value is altered by the assign, the variable will show up in any
26682subsequent @code{-var-update} list.
26683
26684@subsubheading Example
922fbb7b
AC
26685
26686@smallexample
594fe323 26687(gdb)
a2c02241
NR
26688-var-assign var1 3
26689^done,value="3"
594fe323 26690(gdb)
a2c02241
NR
26691-var-update *
26692^done,changelist=[@{name="var1",in_scope="true",type_changed="false"@}]
594fe323 26693(gdb)
922fbb7b
AC
26694@end smallexample
26695
a2c02241
NR
26696@subheading The @code{-var-update} Command
26697@findex -var-update
26698
26699@subsubheading Synopsis
26700
26701@smallexample
26702 -var-update [@var{print-values}] @{@var{name} | "*"@}
26703@end smallexample
26704
c8b2f53c
VP
26705Reevaluate the expressions corresponding to the variable object
26706@var{name} and all its direct and indirect children, and return the
36ece8b3
NR
26707list of variable objects whose values have changed; @var{name} must
26708be a root variable object. Here, ``changed'' means that the result of
26709@code{-var-evaluate-expression} before and after the
26710@code{-var-update} is different. If @samp{*} is used as the variable
9f708cb2
VP
26711object names, all existing variable objects are updated, except
26712for frozen ones (@pxref{-var-set-frozen}). The option
36ece8b3 26713@var{print-values} determines whether both names and values, or just
de051565 26714names are printed. The possible values of this option are the same
36ece8b3
NR
26715as for @code{-var-list-children} (@pxref{-var-list-children}). It is
26716recommended to use the @samp{--all-values} option, to reduce the
26717number of MI commands needed on each program stop.
c8b2f53c 26718
c3b108f7
VP
26719With the @samp{*} parameter, if a variable object is bound to a
26720currently running thread, it will not be updated, without any
26721diagnostic.
a2c02241 26722
0cc7d26f
TT
26723If @code{-var-set-update-range} was previously used on a varobj, then
26724only the selected range of children will be reported.
922fbb7b 26725
0cc7d26f
TT
26726@code{-var-update} reports all the changed varobjs in a tuple named
26727@samp{changelist}.
26728
26729Each item in the change list is itself a tuple holding:
26730
26731@table @samp
26732@item name
26733The name of the varobj.
26734
26735@item value
26736If values were requested for this update, then this field will be
26737present and will hold the value of the varobj.
922fbb7b 26738
0cc7d26f 26739@item in_scope
9f708cb2 26740@anchor{-var-update}
0cc7d26f 26741This field is a string which may take one of three values:
36ece8b3
NR
26742
26743@table @code
26744@item "true"
26745The variable object's current value is valid.
26746
26747@item "false"
26748The variable object does not currently hold a valid value but it may
26749hold one in the future if its associated expression comes back into
26750scope.
26751
26752@item "invalid"
26753The variable object no longer holds a valid value.
26754This can occur when the executable file being debugged has changed,
26755either through recompilation or by using the @value{GDBN} @code{file}
26756command. The front end should normally choose to delete these variable
26757objects.
26758@end table
26759
26760In the future new values may be added to this list so the front should
26761be prepared for this possibility. @xref{GDB/MI Development and Front Ends, ,@sc{GDB/MI} Development and Front Ends}.
26762
0cc7d26f
TT
26763@item type_changed
26764This is only present if the varobj is still valid. If the type
26765changed, then this will be the string @samp{true}; otherwise it will
26766be @samp{false}.
26767
26768@item new_type
26769If the varobj's type changed, then this field will be present and will
26770hold the new type.
26771
26772@item new_num_children
26773For a dynamic varobj, if the number of children changed, or if the
26774type changed, this will be the new number of children.
26775
26776The @samp{numchild} field in other varobj responses is generally not
26777valid for a dynamic varobj -- it will show the number of children that
26778@value{GDBN} knows about, but because dynamic varobjs lazily
26779instantiate their children, this will not reflect the number of
26780children which may be available.
26781
26782The @samp{new_num_children} attribute only reports changes to the
26783number of children known by @value{GDBN}. This is the only way to
26784detect whether an update has removed children (which necessarily can
26785only happen at the end of the update range).
26786
26787@item displayhint
26788The display hint, if any.
26789
26790@item has_more
26791This is an integer value, which will be 1 if there are more children
26792available outside the varobj's update range.
26793
26794@item dynamic
26795This attribute will be present and have the value @samp{1} if the
26796varobj is a dynamic varobj. If the varobj is not a dynamic varobj,
26797then this attribute will not be present.
26798
26799@item new_children
26800If new children were added to a dynamic varobj within the selected
26801update range (as set by @code{-var-set-update-range}), then they will
26802be listed in this attribute.
26803@end table
26804
26805@subsubheading Example
26806
26807@smallexample
26808(gdb)
26809-var-assign var1 3
26810^done,value="3"
26811(gdb)
26812-var-update --all-values var1
26813^done,changelist=[@{name="var1",value="3",in_scope="true",
26814type_changed="false"@}]
26815(gdb)
26816@end smallexample
26817
25d5ea92
VP
26818@subheading The @code{-var-set-frozen} Command
26819@findex -var-set-frozen
9f708cb2 26820@anchor{-var-set-frozen}
25d5ea92
VP
26821
26822@subsubheading Synopsis
26823
26824@smallexample
9f708cb2 26825 -var-set-frozen @var{name} @var{flag}
25d5ea92
VP
26826@end smallexample
26827
9f708cb2 26828Set the frozenness flag on the variable object @var{name}. The
25d5ea92 26829@var{flag} parameter should be either @samp{1} to make the variable
9f708cb2 26830frozen or @samp{0} to make it unfrozen. If a variable object is
25d5ea92 26831frozen, then neither itself, nor any of its children, are
9f708cb2 26832implicitly updated by @code{-var-update} of
25d5ea92
VP
26833a parent variable or by @code{-var-update *}. Only
26834@code{-var-update} of the variable itself will update its value and
26835values of its children. After a variable object is unfrozen, it is
26836implicitly updated by all subsequent @code{-var-update} operations.
26837Unfreezing a variable does not update it, only subsequent
26838@code{-var-update} does.
26839
26840@subsubheading Example
26841
26842@smallexample
26843(gdb)
26844-var-set-frozen V 1
26845^done
26846(gdb)
26847@end smallexample
26848
0cc7d26f
TT
26849@subheading The @code{-var-set-update-range} command
26850@findex -var-set-update-range
26851@anchor{-var-set-update-range}
26852
26853@subsubheading Synopsis
26854
26855@smallexample
26856 -var-set-update-range @var{name} @var{from} @var{to}
26857@end smallexample
26858
26859Set the range of children to be returned by future invocations of
26860@code{-var-update}.
26861
26862@var{from} and @var{to} indicate the range of children to report. If
26863@var{from} or @var{to} is less than zero, the range is reset and all
26864children will be reported. Otherwise, children starting at @var{from}
26865(zero-based) and up to and excluding @var{to} will be reported.
26866
26867@subsubheading Example
26868
26869@smallexample
26870(gdb)
26871-var-set-update-range V 1 2
26872^done
26873@end smallexample
26874
b6313243
TT
26875@subheading The @code{-var-set-visualizer} command
26876@findex -var-set-visualizer
26877@anchor{-var-set-visualizer}
26878
26879@subsubheading Synopsis
26880
26881@smallexample
26882 -var-set-visualizer @var{name} @var{visualizer}
26883@end smallexample
26884
26885Set a visualizer for the variable object @var{name}.
26886
26887@var{visualizer} is the visualizer to use. The special value
26888@samp{None} means to disable any visualizer in use.
26889
26890If not @samp{None}, @var{visualizer} must be a Python expression.
26891This expression must evaluate to a callable object which accepts a
26892single argument. @value{GDBN} will call this object with the value of
26893the varobj @var{name} as an argument (this is done so that the same
26894Python pretty-printing code can be used for both the CLI and MI).
26895When called, this object must return an object which conforms to the
4c374409 26896pretty-printing interface (@pxref{Pretty Printing API}).
b6313243
TT
26897
26898The pre-defined function @code{gdb.default_visualizer} may be used to
26899select a visualizer by following the built-in process
26900(@pxref{Selecting Pretty-Printers}). This is done automatically when
26901a varobj is created, and so ordinarily is not needed.
26902
26903This feature is only available if Python support is enabled. The MI
26904command @code{-list-features} (@pxref{GDB/MI Miscellaneous Commands})
26905can be used to check this.
26906
26907@subsubheading Example
26908
26909Resetting the visualizer:
26910
26911@smallexample
26912(gdb)
26913-var-set-visualizer V None
26914^done
26915@end smallexample
26916
26917Reselecting the default (type-based) visualizer:
26918
26919@smallexample
26920(gdb)
26921-var-set-visualizer V gdb.default_visualizer
26922^done
26923@end smallexample
26924
26925Suppose @code{SomeClass} is a visualizer class. A lambda expression
26926can be used to instantiate this class for a varobj:
26927
26928@smallexample
26929(gdb)
26930-var-set-visualizer V "lambda val: SomeClass()"
26931^done
26932@end smallexample
25d5ea92 26933
a2c02241
NR
26934@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
26935@node GDB/MI Data Manipulation
26936@section @sc{gdb/mi} Data Manipulation
922fbb7b 26937
a2c02241
NR
26938@cindex data manipulation, in @sc{gdb/mi}
26939@cindex @sc{gdb/mi}, data manipulation
26940This section describes the @sc{gdb/mi} commands that manipulate data:
26941examine memory and registers, evaluate expressions, etc.
26942
26943@c REMOVED FROM THE INTERFACE.
26944@c @subheading -data-assign
26945@c Change the value of a program variable. Plenty of side effects.
79a6e687 26946@c @subsubheading GDB Command
a2c02241
NR
26947@c set variable
26948@c @subsubheading Example
26949@c N.A.
26950
26951@subheading The @code{-data-disassemble} Command
26952@findex -data-disassemble
922fbb7b
AC
26953
26954@subsubheading Synopsis
26955
26956@smallexample
a2c02241
NR
26957 -data-disassemble
26958 [ -s @var{start-addr} -e @var{end-addr} ]
26959 | [ -f @var{filename} -l @var{linenum} [ -n @var{lines} ] ]
26960 -- @var{mode}
922fbb7b
AC
26961@end smallexample
26962
a2c02241
NR
26963@noindent
26964Where:
26965
26966@table @samp
26967@item @var{start-addr}
26968is the beginning address (or @code{$pc})
26969@item @var{end-addr}
26970is the end address
26971@item @var{filename}
26972is the name of the file to disassemble
26973@item @var{linenum}
26974is the line number to disassemble around
26975@item @var{lines}
d3e8051b 26976is the number of disassembly lines to be produced. If it is -1,
a2c02241
NR
26977the whole function will be disassembled, in case no @var{end-addr} is
26978specified. If @var{end-addr} is specified as a non-zero value, and
26979@var{lines} is lower than the number of disassembly lines between
26980@var{start-addr} and @var{end-addr}, only @var{lines} lines are
26981displayed; if @var{lines} is higher than the number of lines between
26982@var{start-addr} and @var{end-addr}, only the lines up to @var{end-addr}
26983are displayed.
26984@item @var{mode}
26985is either 0 (meaning only disassembly) or 1 (meaning mixed source and
26986disassembly).
26987@end table
26988
26989@subsubheading Result
26990
26991The output for each instruction is composed of four fields:
26992
26993@itemize @bullet
26994@item Address
26995@item Func-name
26996@item Offset
26997@item Instruction
26998@end itemize
26999
27000Note that whatever included in the instruction field, is not manipulated
d3e8051b 27001directly by @sc{gdb/mi}, i.e., it is not possible to adjust its format.
922fbb7b
AC
27002
27003@subsubheading @value{GDBN} Command
27004
a2c02241 27005There's no direct mapping from this command to the CLI.
922fbb7b
AC
27006
27007@subsubheading Example
27008
a2c02241
NR
27009Disassemble from the current value of @code{$pc} to @code{$pc + 20}:
27010
922fbb7b 27011@smallexample
594fe323 27012(gdb)
a2c02241
NR
27013-data-disassemble -s $pc -e "$pc + 20" -- 0
27014^done,
27015asm_insns=[
27016@{address="0x000107c0",func-name="main",offset="4",
27017inst="mov 2, %o0"@},
27018@{address="0x000107c4",func-name="main",offset="8",
27019inst="sethi %hi(0x11800), %o2"@},
27020@{address="0x000107c8",func-name="main",offset="12",
27021inst="or %o2, 0x140, %o1\t! 0x11940 <_lib_version+8>"@},
27022@{address="0x000107cc",func-name="main",offset="16",
27023inst="sethi %hi(0x11800), %o2"@},
27024@{address="0x000107d0",func-name="main",offset="20",
27025inst="or %o2, 0x168, %o4\t! 0x11968 <_lib_version+48>"@}]
594fe323 27026(gdb)
a2c02241
NR
27027@end smallexample
27028
27029Disassemble the whole @code{main} function. Line 32 is part of
27030@code{main}.
27031
27032@smallexample
27033-data-disassemble -f basics.c -l 32 -- 0
27034^done,asm_insns=[
27035@{address="0x000107bc",func-name="main",offset="0",
27036inst="save %sp, -112, %sp"@},
27037@{address="0x000107c0",func-name="main",offset="4",
27038inst="mov 2, %o0"@},
27039@{address="0x000107c4",func-name="main",offset="8",
27040inst="sethi %hi(0x11800), %o2"@},
27041[@dots{}]
27042@{address="0x0001081c",func-name="main",offset="96",inst="ret "@},
27043@{address="0x00010820",func-name="main",offset="100",inst="restore "@}]
594fe323 27044(gdb)
922fbb7b
AC
27045@end smallexample
27046
a2c02241 27047Disassemble 3 instructions from the start of @code{main}:
922fbb7b 27048
a2c02241 27049@smallexample
594fe323 27050(gdb)
a2c02241
NR
27051-data-disassemble -f basics.c -l 32 -n 3 -- 0
27052^done,asm_insns=[
27053@{address="0x000107bc",func-name="main",offset="0",
27054inst="save %sp, -112, %sp"@},
27055@{address="0x000107c0",func-name="main",offset="4",
27056inst="mov 2, %o0"@},
27057@{address="0x000107c4",func-name="main",offset="8",
27058inst="sethi %hi(0x11800), %o2"@}]
594fe323 27059(gdb)
a2c02241
NR
27060@end smallexample
27061
27062Disassemble 3 instructions from the start of @code{main} in mixed mode:
27063
27064@smallexample
594fe323 27065(gdb)
a2c02241
NR
27066-data-disassemble -f basics.c -l 32 -n 3 -- 1
27067^done,asm_insns=[
27068src_and_asm_line=@{line="31",
27069file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \
27070 testsuite/gdb.mi/basics.c",line_asm_insn=[
27071@{address="0x000107bc",func-name="main",offset="0",
27072inst="save %sp, -112, %sp"@}]@},
27073src_and_asm_line=@{line="32",
27074file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \
27075 testsuite/gdb.mi/basics.c",line_asm_insn=[
27076@{address="0x000107c0",func-name="main",offset="4",
27077inst="mov 2, %o0"@},
27078@{address="0x000107c4",func-name="main",offset="8",
27079inst="sethi %hi(0x11800), %o2"@}]@}]
594fe323 27080(gdb)
a2c02241
NR
27081@end smallexample
27082
27083
27084@subheading The @code{-data-evaluate-expression} Command
27085@findex -data-evaluate-expression
922fbb7b
AC
27086
27087@subsubheading Synopsis
27088
27089@smallexample
a2c02241 27090 -data-evaluate-expression @var{expr}
922fbb7b
AC
27091@end smallexample
27092
a2c02241
NR
27093Evaluate @var{expr} as an expression. The expression could contain an
27094inferior function call. The function call will execute synchronously.
27095If the expression contains spaces, it must be enclosed in double quotes.
922fbb7b
AC
27096
27097@subsubheading @value{GDBN} Command
27098
a2c02241
NR
27099The corresponding @value{GDBN} commands are @samp{print}, @samp{output}, and
27100@samp{call}. In @code{gdbtk} only, there's a corresponding
27101@samp{gdb_eval} command.
922fbb7b
AC
27102
27103@subsubheading Example
27104
a2c02241
NR
27105In the following example, the numbers that precede the commands are the
27106@dfn{tokens} described in @ref{GDB/MI Command Syntax, ,@sc{gdb/mi}
27107Command Syntax}. Notice how @sc{gdb/mi} returns the same tokens in its
27108output.
27109
922fbb7b 27110@smallexample
a2c02241
NR
27111211-data-evaluate-expression A
27112211^done,value="1"
594fe323 27113(gdb)
a2c02241
NR
27114311-data-evaluate-expression &A
27115311^done,value="0xefffeb7c"
594fe323 27116(gdb)
a2c02241
NR
27117411-data-evaluate-expression A+3
27118411^done,value="4"
594fe323 27119(gdb)
a2c02241
NR
27120511-data-evaluate-expression "A + 3"
27121511^done,value="4"
594fe323 27122(gdb)
a2c02241 27123@end smallexample
922fbb7b
AC
27124
27125
a2c02241
NR
27126@subheading The @code{-data-list-changed-registers} Command
27127@findex -data-list-changed-registers
922fbb7b
AC
27128
27129@subsubheading Synopsis
27130
27131@smallexample
a2c02241 27132 -data-list-changed-registers
922fbb7b
AC
27133@end smallexample
27134
a2c02241 27135Display a list of the registers that have changed.
922fbb7b
AC
27136
27137@subsubheading @value{GDBN} Command
27138
a2c02241
NR
27139@value{GDBN} doesn't have a direct analog for this command; @code{gdbtk}
27140has the corresponding command @samp{gdb_changed_register_list}.
922fbb7b
AC
27141
27142@subsubheading Example
922fbb7b 27143
a2c02241 27144On a PPC MBX board:
922fbb7b
AC
27145
27146@smallexample
594fe323 27147(gdb)
a2c02241
NR
27148-exec-continue
27149^running
922fbb7b 27150
594fe323 27151(gdb)
a47ec5fe
AR
27152*stopped,reason="breakpoint-hit",disp="keep",bkptno="1",frame=@{
27153func="main",args=[],file="try.c",fullname="/home/foo/bar/try.c",
27154line="5"@}
594fe323 27155(gdb)
a2c02241
NR
27156-data-list-changed-registers
27157^done,changed-registers=["0","1","2","4","5","6","7","8","9",
27158"10","11","13","14","15","16","17","18","19","20","21","22","23",
27159"24","25","26","27","28","30","31","64","65","66","67","69"]
594fe323 27160(gdb)
a2c02241 27161@end smallexample
922fbb7b
AC
27162
27163
a2c02241
NR
27164@subheading The @code{-data-list-register-names} Command
27165@findex -data-list-register-names
922fbb7b
AC
27166
27167@subsubheading Synopsis
27168
27169@smallexample
a2c02241 27170 -data-list-register-names [ ( @var{regno} )+ ]
922fbb7b
AC
27171@end smallexample
27172
a2c02241
NR
27173Show a list of register names for the current target. If no arguments
27174are given, it shows a list of the names of all the registers. If
27175integer numbers are given as arguments, it will print a list of the
27176names of the registers corresponding to the arguments. To ensure
27177consistency between a register name and its number, the output list may
27178include empty register names.
922fbb7b
AC
27179
27180@subsubheading @value{GDBN} Command
27181
a2c02241
NR
27182@value{GDBN} does not have a command which corresponds to
27183@samp{-data-list-register-names}. In @code{gdbtk} there is a
27184corresponding command @samp{gdb_regnames}.
922fbb7b
AC
27185
27186@subsubheading Example
922fbb7b 27187
a2c02241
NR
27188For the PPC MBX board:
27189@smallexample
594fe323 27190(gdb)
a2c02241
NR
27191-data-list-register-names
27192^done,register-names=["r0","r1","r2","r3","r4","r5","r6","r7",
27193"r8","r9","r10","r11","r12","r13","r14","r15","r16","r17","r18",
27194"r19","r20","r21","r22","r23","r24","r25","r26","r27","r28","r29",
27195"r30","r31","f0","f1","f2","f3","f4","f5","f6","f7","f8","f9",
27196"f10","f11","f12","f13","f14","f15","f16","f17","f18","f19","f20",
27197"f21","f22","f23","f24","f25","f26","f27","f28","f29","f30","f31",
27198"", "pc","ps","cr","lr","ctr","xer"]
594fe323 27199(gdb)
a2c02241
NR
27200-data-list-register-names 1 2 3
27201^done,register-names=["r1","r2","r3"]
594fe323 27202(gdb)
a2c02241 27203@end smallexample
922fbb7b 27204
a2c02241
NR
27205@subheading The @code{-data-list-register-values} Command
27206@findex -data-list-register-values
922fbb7b
AC
27207
27208@subsubheading Synopsis
27209
27210@smallexample
a2c02241 27211 -data-list-register-values @var{fmt} [ ( @var{regno} )*]
922fbb7b
AC
27212@end smallexample
27213
a2c02241
NR
27214Display the registers' contents. @var{fmt} is the format according to
27215which the registers' contents are to be returned, followed by an optional
27216list of numbers specifying the registers to display. A missing list of
27217numbers indicates that the contents of all the registers must be returned.
27218
27219Allowed formats for @var{fmt} are:
27220
27221@table @code
27222@item x
27223Hexadecimal
27224@item o
27225Octal
27226@item t
27227Binary
27228@item d
27229Decimal
27230@item r
27231Raw
27232@item N
27233Natural
27234@end table
922fbb7b
AC
27235
27236@subsubheading @value{GDBN} Command
27237
a2c02241
NR
27238The corresponding @value{GDBN} commands are @samp{info reg}, @samp{info
27239all-reg}, and (in @code{gdbtk}) @samp{gdb_fetch_registers}.
922fbb7b
AC
27240
27241@subsubheading Example
922fbb7b 27242
a2c02241
NR
27243For a PPC MBX board (note: line breaks are for readability only, they
27244don't appear in the actual output):
27245
27246@smallexample
594fe323 27247(gdb)
a2c02241
NR
27248-data-list-register-values r 64 65
27249^done,register-values=[@{number="64",value="0xfe00a300"@},
27250@{number="65",value="0x00029002"@}]
594fe323 27251(gdb)
a2c02241
NR
27252-data-list-register-values x
27253^done,register-values=[@{number="0",value="0xfe0043c8"@},
27254@{number="1",value="0x3fff88"@},@{number="2",value="0xfffffffe"@},
27255@{number="3",value="0x0"@},@{number="4",value="0xa"@},
27256@{number="5",value="0x3fff68"@},@{number="6",value="0x3fff58"@},
27257@{number="7",value="0xfe011e98"@},@{number="8",value="0x2"@},
27258@{number="9",value="0xfa202820"@},@{number="10",value="0xfa202808"@},
27259@{number="11",value="0x1"@},@{number="12",value="0x0"@},
27260@{number="13",value="0x4544"@},@{number="14",value="0xffdfffff"@},
27261@{number="15",value="0xffffffff"@},@{number="16",value="0xfffffeff"@},
27262@{number="17",value="0xefffffed"@},@{number="18",value="0xfffffffe"@},
27263@{number="19",value="0xffffffff"@},@{number="20",value="0xffffffff"@},
27264@{number="21",value="0xffffffff"@},@{number="22",value="0xfffffff7"@},
27265@{number="23",value="0xffffffff"@},@{number="24",value="0xffffffff"@},
27266@{number="25",value="0xffffffff"@},@{number="26",value="0xfffffffb"@},
27267@{number="27",value="0xffffffff"@},@{number="28",value="0xf7bfffff"@},
27268@{number="29",value="0x0"@},@{number="30",value="0xfe010000"@},
27269@{number="31",value="0x0"@},@{number="32",value="0x0"@},
27270@{number="33",value="0x0"@},@{number="34",value="0x0"@},
27271@{number="35",value="0x0"@},@{number="36",value="0x0"@},
27272@{number="37",value="0x0"@},@{number="38",value="0x0"@},
27273@{number="39",value="0x0"@},@{number="40",value="0x0"@},
27274@{number="41",value="0x0"@},@{number="42",value="0x0"@},
27275@{number="43",value="0x0"@},@{number="44",value="0x0"@},
27276@{number="45",value="0x0"@},@{number="46",value="0x0"@},
27277@{number="47",value="0x0"@},@{number="48",value="0x0"@},
27278@{number="49",value="0x0"@},@{number="50",value="0x0"@},
27279@{number="51",value="0x0"@},@{number="52",value="0x0"@},
27280@{number="53",value="0x0"@},@{number="54",value="0x0"@},
27281@{number="55",value="0x0"@},@{number="56",value="0x0"@},
27282@{number="57",value="0x0"@},@{number="58",value="0x0"@},
27283@{number="59",value="0x0"@},@{number="60",value="0x0"@},
27284@{number="61",value="0x0"@},@{number="62",value="0x0"@},
27285@{number="63",value="0x0"@},@{number="64",value="0xfe00a300"@},
27286@{number="65",value="0x29002"@},@{number="66",value="0x202f04b5"@},
27287@{number="67",value="0xfe0043b0"@},@{number="68",value="0xfe00b3e4"@},
27288@{number="69",value="0x20002b03"@}]
594fe323 27289(gdb)
a2c02241 27290@end smallexample
922fbb7b 27291
a2c02241
NR
27292
27293@subheading The @code{-data-read-memory} Command
27294@findex -data-read-memory
922fbb7b
AC
27295
27296@subsubheading Synopsis
27297
27298@smallexample
a2c02241
NR
27299 -data-read-memory [ -o @var{byte-offset} ]
27300 @var{address} @var{word-format} @var{word-size}
27301 @var{nr-rows} @var{nr-cols} [ @var{aschar} ]
922fbb7b
AC
27302@end smallexample
27303
a2c02241
NR
27304@noindent
27305where:
922fbb7b 27306
a2c02241
NR
27307@table @samp
27308@item @var{address}
27309An expression specifying the address of the first memory word to be
27310read. Complex expressions containing embedded white space should be
27311quoted using the C convention.
922fbb7b 27312
a2c02241
NR
27313@item @var{word-format}
27314The format to be used to print the memory words. The notation is the
27315same as for @value{GDBN}'s @code{print} command (@pxref{Output Formats,
79a6e687 27316,Output Formats}).
922fbb7b 27317
a2c02241
NR
27318@item @var{word-size}
27319The size of each memory word in bytes.
922fbb7b 27320
a2c02241
NR
27321@item @var{nr-rows}
27322The number of rows in the output table.
922fbb7b 27323
a2c02241
NR
27324@item @var{nr-cols}
27325The number of columns in the output table.
922fbb7b 27326
a2c02241
NR
27327@item @var{aschar}
27328If present, indicates that each row should include an @sc{ascii} dump. The
27329value of @var{aschar} is used as a padding character when a byte is not a
27330member of the printable @sc{ascii} character set (printable @sc{ascii}
27331characters are those whose code is between 32 and 126, inclusively).
922fbb7b 27332
a2c02241
NR
27333@item @var{byte-offset}
27334An offset to add to the @var{address} before fetching memory.
27335@end table
922fbb7b 27336
a2c02241
NR
27337This command displays memory contents as a table of @var{nr-rows} by
27338@var{nr-cols} words, each word being @var{word-size} bytes. In total,
27339@code{@var{nr-rows} * @var{nr-cols} * @var{word-size}} bytes are read
27340(returned as @samp{total-bytes}). Should less than the requested number
27341of bytes be returned by the target, the missing words are identified
27342using @samp{N/A}. The number of bytes read from the target is returned
27343in @samp{nr-bytes} and the starting address used to read memory in
27344@samp{addr}.
27345
27346The address of the next/previous row or page is available in
27347@samp{next-row} and @samp{prev-row}, @samp{next-page} and
27348@samp{prev-page}.
922fbb7b
AC
27349
27350@subsubheading @value{GDBN} Command
27351
a2c02241
NR
27352The corresponding @value{GDBN} command is @samp{x}. @code{gdbtk} has
27353@samp{gdb_get_mem} memory read command.
922fbb7b
AC
27354
27355@subsubheading Example
32e7087d 27356
a2c02241
NR
27357Read six bytes of memory starting at @code{bytes+6} but then offset by
27358@code{-6} bytes. Format as three rows of two columns. One byte per
27359word. Display each word in hex.
32e7087d
JB
27360
27361@smallexample
594fe323 27362(gdb)
a2c02241
NR
273639-data-read-memory -o -6 -- bytes+6 x 1 3 2
273649^done,addr="0x00001390",nr-bytes="6",total-bytes="6",
27365next-row="0x00001396",prev-row="0x0000138e",next-page="0x00001396",
27366prev-page="0x0000138a",memory=[
27367@{addr="0x00001390",data=["0x00","0x01"]@},
27368@{addr="0x00001392",data=["0x02","0x03"]@},
27369@{addr="0x00001394",data=["0x04","0x05"]@}]
594fe323 27370(gdb)
32e7087d
JB
27371@end smallexample
27372
a2c02241
NR
27373Read two bytes of memory starting at address @code{shorts + 64} and
27374display as a single word formatted in decimal.
32e7087d 27375
32e7087d 27376@smallexample
594fe323 27377(gdb)
a2c02241
NR
273785-data-read-memory shorts+64 d 2 1 1
273795^done,addr="0x00001510",nr-bytes="2",total-bytes="2",
27380next-row="0x00001512",prev-row="0x0000150e",
27381next-page="0x00001512",prev-page="0x0000150e",memory=[
27382@{addr="0x00001510",data=["128"]@}]
594fe323 27383(gdb)
32e7087d
JB
27384@end smallexample
27385
a2c02241
NR
27386Read thirty two bytes of memory starting at @code{bytes+16} and format
27387as eight rows of four columns. Include a string encoding with @samp{x}
27388used as the non-printable character.
922fbb7b
AC
27389
27390@smallexample
594fe323 27391(gdb)
a2c02241
NR
273924-data-read-memory bytes+16 x 1 8 4 x
273934^done,addr="0x000013a0",nr-bytes="32",total-bytes="32",
27394next-row="0x000013c0",prev-row="0x0000139c",
27395next-page="0x000013c0",prev-page="0x00001380",memory=[
27396@{addr="0x000013a0",data=["0x10","0x11","0x12","0x13"],ascii="xxxx"@},
27397@{addr="0x000013a4",data=["0x14","0x15","0x16","0x17"],ascii="xxxx"@},
27398@{addr="0x000013a8",data=["0x18","0x19","0x1a","0x1b"],ascii="xxxx"@},
27399@{addr="0x000013ac",data=["0x1c","0x1d","0x1e","0x1f"],ascii="xxxx"@},
27400@{addr="0x000013b0",data=["0x20","0x21","0x22","0x23"],ascii=" !\"#"@},
27401@{addr="0x000013b4",data=["0x24","0x25","0x26","0x27"],ascii="$%&'"@},
27402@{addr="0x000013b8",data=["0x28","0x29","0x2a","0x2b"],ascii="()*+"@},
27403@{addr="0x000013bc",data=["0x2c","0x2d","0x2e","0x2f"],ascii=",-./"@}]
594fe323 27404(gdb)
922fbb7b
AC
27405@end smallexample
27406
a2c02241
NR
27407@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
27408@node GDB/MI Tracepoint Commands
27409@section @sc{gdb/mi} Tracepoint Commands
922fbb7b 27410
18148017
VP
27411The commands defined in this section implement MI support for
27412tracepoints. For detailed introduction, see @ref{Tracepoints}.
27413
27414@subheading The @code{-trace-find} Command
27415@findex -trace-find
27416
27417@subsubheading Synopsis
27418
27419@smallexample
27420 -trace-find @var{mode} [@var{parameters}@dots{}]
27421@end smallexample
27422
27423Find a trace frame using criteria defined by @var{mode} and
27424@var{parameters}. The following table lists permissible
27425modes and their parameters. For details of operation, see @ref{tfind}.
27426
27427@table @samp
27428
27429@item none
27430No parameters are required. Stops examining trace frames.
27431
27432@item frame-number
27433An integer is required as parameter. Selects tracepoint frame with
27434that index.
27435
27436@item tracepoint-number
27437An integer is required as parameter. Finds next
27438trace frame that corresponds to tracepoint with the specified number.
27439
27440@item pc
27441An address is required as parameter. Finds
27442next trace frame that corresponds to any tracepoint at the specified
27443address.
27444
27445@item pc-inside-range
27446Two addresses are required as parameters. Finds next trace
27447frame that corresponds to a tracepoint at an address inside the
27448specified range. Both bounds are considered to be inside the range.
27449
27450@item pc-outside-range
27451Two addresses are required as parameters. Finds
27452next trace frame that corresponds to a tracepoint at an address outside
27453the specified range. Both bounds are considered to be inside the range.
27454
27455@item line
27456Line specification is required as parameter. @xref{Specify Location}.
27457Finds next trace frame that corresponds to a tracepoint at
27458the specified location.
27459
27460@end table
27461
27462If @samp{none} was passed as @var{mode}, the response does not
27463have fields. Otherwise, the response may have the following fields:
27464
27465@table @samp
27466@item found
27467This field has either @samp{0} or @samp{1} as the value, depending
27468on whether a matching tracepoint was found.
27469
27470@item traceframe
27471The index of the found traceframe. This field is present iff
27472the @samp{found} field has value of @samp{1}.
27473
27474@item tracepoint
27475The index of the found tracepoint. This field is present iff
27476the @samp{found} field has value of @samp{1}.
27477
27478@item frame
27479The information about the frame corresponding to the found trace
27480frame. This field is present only if a trace frame was found.
cd64ee31 27481@xref{GDB/MI Frame Information}, for description of this field.
18148017
VP
27482
27483@end table
27484
7d13fe92
SS
27485@subsubheading @value{GDBN} Command
27486
27487The corresponding @value{GDBN} command is @samp{tfind}.
27488
18148017
VP
27489@subheading -trace-define-variable
27490@findex -trace-define-variable
27491
27492@subsubheading Synopsis
27493
27494@smallexample
27495 -trace-define-variable @var{name} [ @var{value} ]
27496@end smallexample
27497
27498Create trace variable @var{name} if it does not exist. If
27499@var{value} is specified, sets the initial value of the specified
27500trace variable to that value. Note that the @var{name} should start
27501with the @samp{$} character.
27502
7d13fe92
SS
27503@subsubheading @value{GDBN} Command
27504
27505The corresponding @value{GDBN} command is @samp{tvariable}.
27506
18148017
VP
27507@subheading -trace-list-variables
27508@findex -trace-list-variables
922fbb7b 27509
18148017 27510@subsubheading Synopsis
922fbb7b 27511
18148017
VP
27512@smallexample
27513 -trace-list-variables
27514@end smallexample
922fbb7b 27515
18148017
VP
27516Return a table of all defined trace variables. Each element of the
27517table has the following fields:
922fbb7b 27518
18148017
VP
27519@table @samp
27520@item name
27521The name of the trace variable. This field is always present.
922fbb7b 27522
18148017
VP
27523@item initial
27524The initial value. This is a 64-bit signed integer. This
27525field is always present.
922fbb7b 27526
18148017
VP
27527@item current
27528The value the trace variable has at the moment. This is a 64-bit
27529signed integer. This field is absent iff current value is
27530not defined, for example if the trace was never run, or is
27531presently running.
922fbb7b 27532
18148017 27533@end table
922fbb7b 27534
7d13fe92
SS
27535@subsubheading @value{GDBN} Command
27536
27537The corresponding @value{GDBN} command is @samp{tvariables}.
27538
18148017 27539@subsubheading Example
922fbb7b 27540
18148017
VP
27541@smallexample
27542(gdb)
27543-trace-list-variables
27544^done,trace-variables=@{nr_rows="1",nr_cols="3",
27545hdr=[@{width="15",alignment="-1",col_name="name",colhdr="Name"@},
27546 @{width="11",alignment="-1",col_name="initial",colhdr="Initial"@},
27547 @{width="11",alignment="-1",col_name="current",colhdr="Current"@}],
27548body=[variable=@{name="$trace_timestamp",initial="0"@}
27549 variable=@{name="$foo",initial="10",current="15"@}]@}
27550(gdb)
27551@end smallexample
922fbb7b 27552
18148017
VP
27553@subheading -trace-save
27554@findex -trace-save
922fbb7b 27555
18148017
VP
27556@subsubheading Synopsis
27557
27558@smallexample
27559 -trace-save [-r ] @var{filename}
27560@end smallexample
27561
27562Saves the collected trace data to @var{filename}. Without the
27563@samp{-r} option, the data is downloaded from the target and saved
27564in a local file. With the @samp{-r} option the target is asked
27565to perform the save.
27566
7d13fe92
SS
27567@subsubheading @value{GDBN} Command
27568
27569The corresponding @value{GDBN} command is @samp{tsave}.
27570
18148017
VP
27571
27572@subheading -trace-start
27573@findex -trace-start
27574
27575@subsubheading Synopsis
27576
27577@smallexample
27578 -trace-start
27579@end smallexample
922fbb7b 27580
18148017
VP
27581Starts a tracing experiments. The result of this command does not
27582have any fields.
922fbb7b 27583
7d13fe92
SS
27584@subsubheading @value{GDBN} Command
27585
27586The corresponding @value{GDBN} command is @samp{tstart}.
27587
18148017
VP
27588@subheading -trace-status
27589@findex -trace-status
922fbb7b 27590
18148017
VP
27591@subsubheading Synopsis
27592
27593@smallexample
27594 -trace-status
27595@end smallexample
27596
a97153c7 27597Obtains the status of a tracing experiment. The result may include
18148017
VP
27598the following fields:
27599
27600@table @samp
27601
27602@item supported
27603May have a value of either @samp{0}, when no tracing operations are
27604supported, @samp{1}, when all tracing operations are supported, or
27605@samp{file} when examining trace file. In the latter case, examining
27606of trace frame is possible but new tracing experiement cannot be
27607started. This field is always present.
27608
27609@item running
27610May have a value of either @samp{0} or @samp{1} depending on whether
27611tracing experiement is in progress on target. This field is present
27612if @samp{supported} field is not @samp{0}.
27613
27614@item stop-reason
27615Report the reason why the tracing was stopped last time. This field
27616may be absent iff tracing was never stopped on target yet. The
27617value of @samp{request} means the tracing was stopped as result of
27618the @code{-trace-stop} command. The value of @samp{overflow} means
27619the tracing buffer is full. The value of @samp{disconnection} means
27620tracing was automatically stopped when @value{GDBN} has disconnected.
27621The value of @samp{passcount} means tracing was stopped when a
27622tracepoint was passed a maximal number of times for that tracepoint.
27623This field is present if @samp{supported} field is not @samp{0}.
27624
27625@item stopping-tracepoint
27626The number of tracepoint whose passcount as exceeded. This field is
27627present iff the @samp{stop-reason} field has the value of
27628@samp{passcount}.
27629
27630@item frames
87290684
SS
27631@itemx frames-created
27632The @samp{frames} field is a count of the total number of trace frames
27633in the trace buffer, while @samp{frames-created} is the total created
27634during the run, including ones that were discarded, such as when a
27635circular trace buffer filled up. Both fields are optional.
18148017
VP
27636
27637@item buffer-size
27638@itemx buffer-free
27639These fields tell the current size of the tracing buffer and the
87290684 27640remaining space. These fields are optional.
18148017 27641
a97153c7
PA
27642@item circular
27643The value of the circular trace buffer flag. @code{1} means that the
27644trace buffer is circular and old trace frames will be discarded if
27645necessary to make room, @code{0} means that the trace buffer is linear
27646and may fill up.
27647
27648@item disconnected
27649The value of the disconnected tracing flag. @code{1} means that
27650tracing will continue after @value{GDBN} disconnects, @code{0} means
27651that the trace run will stop.
27652
18148017
VP
27653@end table
27654
7d13fe92
SS
27655@subsubheading @value{GDBN} Command
27656
27657The corresponding @value{GDBN} command is @samp{tstatus}.
27658
18148017
VP
27659@subheading -trace-stop
27660@findex -trace-stop
27661
27662@subsubheading Synopsis
27663
27664@smallexample
27665 -trace-stop
27666@end smallexample
922fbb7b 27667
18148017
VP
27668Stops a tracing experiment. The result of this command has the same
27669fields as @code{-trace-status}, except that the @samp{supported} and
27670@samp{running} fields are not output.
922fbb7b 27671
7d13fe92
SS
27672@subsubheading @value{GDBN} Command
27673
27674The corresponding @value{GDBN} command is @samp{tstop}.
27675
922fbb7b 27676
a2c02241
NR
27677@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
27678@node GDB/MI Symbol Query
27679@section @sc{gdb/mi} Symbol Query Commands
922fbb7b
AC
27680
27681
9901a55b 27682@ignore
a2c02241
NR
27683@subheading The @code{-symbol-info-address} Command
27684@findex -symbol-info-address
922fbb7b
AC
27685
27686@subsubheading Synopsis
27687
27688@smallexample
a2c02241 27689 -symbol-info-address @var{symbol}
922fbb7b
AC
27690@end smallexample
27691
a2c02241 27692Describe where @var{symbol} is stored.
922fbb7b
AC
27693
27694@subsubheading @value{GDBN} Command
27695
a2c02241 27696The corresponding @value{GDBN} command is @samp{info address}.
922fbb7b
AC
27697
27698@subsubheading Example
27699N.A.
27700
27701
a2c02241
NR
27702@subheading The @code{-symbol-info-file} Command
27703@findex -symbol-info-file
922fbb7b
AC
27704
27705@subsubheading Synopsis
27706
27707@smallexample
a2c02241 27708 -symbol-info-file
922fbb7b
AC
27709@end smallexample
27710
a2c02241 27711Show the file for the symbol.
922fbb7b 27712
a2c02241 27713@subsubheading @value{GDBN} Command
922fbb7b 27714
a2c02241
NR
27715There's no equivalent @value{GDBN} command. @code{gdbtk} has
27716@samp{gdb_find_file}.
922fbb7b
AC
27717
27718@subsubheading Example
27719N.A.
27720
27721
a2c02241
NR
27722@subheading The @code{-symbol-info-function} Command
27723@findex -symbol-info-function
922fbb7b
AC
27724
27725@subsubheading Synopsis
27726
27727@smallexample
a2c02241 27728 -symbol-info-function
922fbb7b
AC
27729@end smallexample
27730
a2c02241 27731Show which function the symbol lives in.
922fbb7b
AC
27732
27733@subsubheading @value{GDBN} Command
27734
a2c02241 27735@samp{gdb_get_function} in @code{gdbtk}.
922fbb7b
AC
27736
27737@subsubheading Example
27738N.A.
27739
27740
a2c02241
NR
27741@subheading The @code{-symbol-info-line} Command
27742@findex -symbol-info-line
922fbb7b
AC
27743
27744@subsubheading Synopsis
27745
27746@smallexample
a2c02241 27747 -symbol-info-line
922fbb7b
AC
27748@end smallexample
27749
a2c02241 27750Show the core addresses of the code for a source line.
922fbb7b 27751
a2c02241 27752@subsubheading @value{GDBN} Command
922fbb7b 27753
a2c02241
NR
27754The corresponding @value{GDBN} command is @samp{info line}.
27755@code{gdbtk} has the @samp{gdb_get_line} and @samp{gdb_get_file} commands.
922fbb7b
AC
27756
27757@subsubheading Example
a2c02241 27758N.A.
922fbb7b
AC
27759
27760
a2c02241
NR
27761@subheading The @code{-symbol-info-symbol} Command
27762@findex -symbol-info-symbol
07f31aa6
DJ
27763
27764@subsubheading Synopsis
27765
a2c02241
NR
27766@smallexample
27767 -symbol-info-symbol @var{addr}
27768@end smallexample
07f31aa6 27769
a2c02241 27770Describe what symbol is at location @var{addr}.
07f31aa6 27771
a2c02241 27772@subsubheading @value{GDBN} Command
07f31aa6 27773
a2c02241 27774The corresponding @value{GDBN} command is @samp{info symbol}.
07f31aa6
DJ
27775
27776@subsubheading Example
a2c02241 27777N.A.
07f31aa6
DJ
27778
27779
a2c02241
NR
27780@subheading The @code{-symbol-list-functions} Command
27781@findex -symbol-list-functions
922fbb7b
AC
27782
27783@subsubheading Synopsis
27784
27785@smallexample
a2c02241 27786 -symbol-list-functions
922fbb7b
AC
27787@end smallexample
27788
a2c02241 27789List the functions in the executable.
922fbb7b
AC
27790
27791@subsubheading @value{GDBN} Command
27792
a2c02241
NR
27793@samp{info functions} in @value{GDBN}, @samp{gdb_listfunc} and
27794@samp{gdb_search} in @code{gdbtk}.
922fbb7b
AC
27795
27796@subsubheading Example
a2c02241 27797N.A.
9901a55b 27798@end ignore
922fbb7b
AC
27799
27800
a2c02241
NR
27801@subheading The @code{-symbol-list-lines} Command
27802@findex -symbol-list-lines
922fbb7b
AC
27803
27804@subsubheading Synopsis
27805
27806@smallexample
a2c02241 27807 -symbol-list-lines @var{filename}
922fbb7b
AC
27808@end smallexample
27809
a2c02241
NR
27810Print the list of lines that contain code and their associated program
27811addresses for the given source filename. The entries are sorted in
27812ascending PC order.
922fbb7b
AC
27813
27814@subsubheading @value{GDBN} Command
27815
a2c02241 27816There is no corresponding @value{GDBN} command.
922fbb7b
AC
27817
27818@subsubheading Example
a2c02241 27819@smallexample
594fe323 27820(gdb)
a2c02241
NR
27821-symbol-list-lines basics.c
27822^done,lines=[@{pc="0x08048554",line="7"@},@{pc="0x0804855a",line="8"@}]
594fe323 27823(gdb)
a2c02241 27824@end smallexample
922fbb7b
AC
27825
27826
9901a55b 27827@ignore
a2c02241
NR
27828@subheading The @code{-symbol-list-types} Command
27829@findex -symbol-list-types
922fbb7b
AC
27830
27831@subsubheading Synopsis
27832
27833@smallexample
a2c02241 27834 -symbol-list-types
922fbb7b
AC
27835@end smallexample
27836
a2c02241 27837List all the type names.
922fbb7b
AC
27838
27839@subsubheading @value{GDBN} Command
27840
a2c02241
NR
27841The corresponding commands are @samp{info types} in @value{GDBN},
27842@samp{gdb_search} in @code{gdbtk}.
922fbb7b
AC
27843
27844@subsubheading Example
27845N.A.
27846
27847
a2c02241
NR
27848@subheading The @code{-symbol-list-variables} Command
27849@findex -symbol-list-variables
922fbb7b
AC
27850
27851@subsubheading Synopsis
27852
27853@smallexample
a2c02241 27854 -symbol-list-variables
922fbb7b
AC
27855@end smallexample
27856
a2c02241 27857List all the global and static variable names.
922fbb7b
AC
27858
27859@subsubheading @value{GDBN} Command
27860
a2c02241 27861@samp{info variables} in @value{GDBN}, @samp{gdb_search} in @code{gdbtk}.
922fbb7b
AC
27862
27863@subsubheading Example
27864N.A.
27865
27866
a2c02241
NR
27867@subheading The @code{-symbol-locate} Command
27868@findex -symbol-locate
922fbb7b
AC
27869
27870@subsubheading Synopsis
27871
27872@smallexample
a2c02241 27873 -symbol-locate
922fbb7b
AC
27874@end smallexample
27875
922fbb7b
AC
27876@subsubheading @value{GDBN} Command
27877
a2c02241 27878@samp{gdb_loc} in @code{gdbtk}.
922fbb7b
AC
27879
27880@subsubheading Example
27881N.A.
27882
27883
a2c02241
NR
27884@subheading The @code{-symbol-type} Command
27885@findex -symbol-type
922fbb7b
AC
27886
27887@subsubheading Synopsis
27888
27889@smallexample
a2c02241 27890 -symbol-type @var{variable}
922fbb7b
AC
27891@end smallexample
27892
a2c02241 27893Show type of @var{variable}.
922fbb7b 27894
a2c02241 27895@subsubheading @value{GDBN} Command
922fbb7b 27896
a2c02241
NR
27897The corresponding @value{GDBN} command is @samp{ptype}, @code{gdbtk} has
27898@samp{gdb_obj_variable}.
27899
27900@subsubheading Example
27901N.A.
9901a55b 27902@end ignore
a2c02241
NR
27903
27904
27905@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
27906@node GDB/MI File Commands
27907@section @sc{gdb/mi} File Commands
27908
27909This section describes the GDB/MI commands to specify executable file names
27910and to read in and obtain symbol table information.
27911
27912@subheading The @code{-file-exec-and-symbols} Command
27913@findex -file-exec-and-symbols
27914
27915@subsubheading Synopsis
922fbb7b
AC
27916
27917@smallexample
a2c02241 27918 -file-exec-and-symbols @var{file}
922fbb7b
AC
27919@end smallexample
27920
a2c02241
NR
27921Specify the executable file to be debugged. This file is the one from
27922which the symbol table is also read. If no file is specified, the
27923command clears the executable and symbol information. If breakpoints
27924are set when using this command with no arguments, @value{GDBN} will produce
27925error messages. Otherwise, no output is produced, except a completion
27926notification.
27927
922fbb7b
AC
27928@subsubheading @value{GDBN} Command
27929
a2c02241 27930The corresponding @value{GDBN} command is @samp{file}.
922fbb7b
AC
27931
27932@subsubheading Example
27933
27934@smallexample
594fe323 27935(gdb)
a2c02241
NR
27936-file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
27937^done
594fe323 27938(gdb)
922fbb7b
AC
27939@end smallexample
27940
922fbb7b 27941
a2c02241
NR
27942@subheading The @code{-file-exec-file} Command
27943@findex -file-exec-file
922fbb7b
AC
27944
27945@subsubheading Synopsis
27946
27947@smallexample
a2c02241 27948 -file-exec-file @var{file}
922fbb7b
AC
27949@end smallexample
27950
a2c02241
NR
27951Specify the executable file to be debugged. Unlike
27952@samp{-file-exec-and-symbols}, the symbol table is @emph{not} read
27953from this file. If used without argument, @value{GDBN} clears the information
27954about the executable file. No output is produced, except a completion
27955notification.
922fbb7b 27956
a2c02241
NR
27957@subsubheading @value{GDBN} Command
27958
27959The corresponding @value{GDBN} command is @samp{exec-file}.
922fbb7b
AC
27960
27961@subsubheading Example
a2c02241
NR
27962
27963@smallexample
594fe323 27964(gdb)
a2c02241
NR
27965-file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
27966^done
594fe323 27967(gdb)
a2c02241 27968@end smallexample
922fbb7b
AC
27969
27970
9901a55b 27971@ignore
a2c02241
NR
27972@subheading The @code{-file-list-exec-sections} Command
27973@findex -file-list-exec-sections
922fbb7b
AC
27974
27975@subsubheading Synopsis
27976
27977@smallexample
a2c02241 27978 -file-list-exec-sections
922fbb7b
AC
27979@end smallexample
27980
a2c02241
NR
27981List the sections of the current executable file.
27982
922fbb7b
AC
27983@subsubheading @value{GDBN} Command
27984
a2c02241
NR
27985The @value{GDBN} command @samp{info file} shows, among the rest, the same
27986information as this command. @code{gdbtk} has a corresponding command
27987@samp{gdb_load_info}.
922fbb7b
AC
27988
27989@subsubheading Example
27990N.A.
9901a55b 27991@end ignore
922fbb7b
AC
27992
27993
a2c02241
NR
27994@subheading The @code{-file-list-exec-source-file} Command
27995@findex -file-list-exec-source-file
922fbb7b
AC
27996
27997@subsubheading Synopsis
27998
27999@smallexample
a2c02241 28000 -file-list-exec-source-file
922fbb7b
AC
28001@end smallexample
28002
a2c02241 28003List the line number, the current source file, and the absolute path
44288b44
NR
28004to the current source file for the current executable. The macro
28005information field has a value of @samp{1} or @samp{0} depending on
28006whether or not the file includes preprocessor macro information.
922fbb7b
AC
28007
28008@subsubheading @value{GDBN} Command
28009
a2c02241 28010The @value{GDBN} equivalent is @samp{info source}
922fbb7b
AC
28011
28012@subsubheading Example
28013
922fbb7b 28014@smallexample
594fe323 28015(gdb)
a2c02241 28016123-file-list-exec-source-file
44288b44 28017123^done,line="1",file="foo.c",fullname="/home/bar/foo.c,macro-info="1"
594fe323 28018(gdb)
922fbb7b
AC
28019@end smallexample
28020
28021
a2c02241
NR
28022@subheading The @code{-file-list-exec-source-files} Command
28023@findex -file-list-exec-source-files
922fbb7b
AC
28024
28025@subsubheading Synopsis
28026
28027@smallexample
a2c02241 28028 -file-list-exec-source-files
922fbb7b
AC
28029@end smallexample
28030
a2c02241
NR
28031List the source files for the current executable.
28032
3f94c067
BW
28033It will always output the filename, but only when @value{GDBN} can find
28034the absolute file name of a source file, will it output the fullname.
922fbb7b
AC
28035
28036@subsubheading @value{GDBN} Command
28037
a2c02241
NR
28038The @value{GDBN} equivalent is @samp{info sources}.
28039@code{gdbtk} has an analogous command @samp{gdb_listfiles}.
922fbb7b
AC
28040
28041@subsubheading Example
922fbb7b 28042@smallexample
594fe323 28043(gdb)
a2c02241
NR
28044-file-list-exec-source-files
28045^done,files=[
28046@{file=foo.c,fullname=/home/foo.c@},
28047@{file=/home/bar.c,fullname=/home/bar.c@},
28048@{file=gdb_could_not_find_fullpath.c@}]
594fe323 28049(gdb)
922fbb7b
AC
28050@end smallexample
28051
9901a55b 28052@ignore
a2c02241
NR
28053@subheading The @code{-file-list-shared-libraries} Command
28054@findex -file-list-shared-libraries
922fbb7b 28055
a2c02241 28056@subsubheading Synopsis
922fbb7b 28057
a2c02241
NR
28058@smallexample
28059 -file-list-shared-libraries
28060@end smallexample
922fbb7b 28061
a2c02241 28062List the shared libraries in the program.
922fbb7b 28063
a2c02241 28064@subsubheading @value{GDBN} Command
922fbb7b 28065
a2c02241 28066The corresponding @value{GDBN} command is @samp{info shared}.
922fbb7b 28067
a2c02241
NR
28068@subsubheading Example
28069N.A.
922fbb7b
AC
28070
28071
a2c02241
NR
28072@subheading The @code{-file-list-symbol-files} Command
28073@findex -file-list-symbol-files
922fbb7b 28074
a2c02241 28075@subsubheading Synopsis
922fbb7b 28076
a2c02241
NR
28077@smallexample
28078 -file-list-symbol-files
28079@end smallexample
922fbb7b 28080
a2c02241 28081List symbol files.
922fbb7b 28082
a2c02241 28083@subsubheading @value{GDBN} Command
922fbb7b 28084
a2c02241 28085The corresponding @value{GDBN} command is @samp{info file} (part of it).
922fbb7b 28086
a2c02241
NR
28087@subsubheading Example
28088N.A.
9901a55b 28089@end ignore
922fbb7b 28090
922fbb7b 28091
a2c02241
NR
28092@subheading The @code{-file-symbol-file} Command
28093@findex -file-symbol-file
922fbb7b 28094
a2c02241 28095@subsubheading Synopsis
922fbb7b 28096
a2c02241
NR
28097@smallexample
28098 -file-symbol-file @var{file}
28099@end smallexample
922fbb7b 28100
a2c02241
NR
28101Read symbol table info from the specified @var{file} argument. When
28102used without arguments, clears @value{GDBN}'s symbol table info. No output is
28103produced, except for a completion notification.
922fbb7b 28104
a2c02241 28105@subsubheading @value{GDBN} Command
922fbb7b 28106
a2c02241 28107The corresponding @value{GDBN} command is @samp{symbol-file}.
922fbb7b 28108
a2c02241 28109@subsubheading Example
922fbb7b 28110
a2c02241 28111@smallexample
594fe323 28112(gdb)
a2c02241
NR
28113-file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
28114^done
594fe323 28115(gdb)
a2c02241 28116@end smallexample
922fbb7b 28117
a2c02241 28118@ignore
a2c02241
NR
28119@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
28120@node GDB/MI Memory Overlay Commands
28121@section @sc{gdb/mi} Memory Overlay Commands
922fbb7b 28122
a2c02241 28123The memory overlay commands are not implemented.
922fbb7b 28124
a2c02241 28125@c @subheading -overlay-auto
922fbb7b 28126
a2c02241 28127@c @subheading -overlay-list-mapping-state
922fbb7b 28128
a2c02241 28129@c @subheading -overlay-list-overlays
922fbb7b 28130
a2c02241 28131@c @subheading -overlay-map
922fbb7b 28132
a2c02241 28133@c @subheading -overlay-off
922fbb7b 28134
a2c02241 28135@c @subheading -overlay-on
922fbb7b 28136
a2c02241 28137@c @subheading -overlay-unmap
922fbb7b 28138
a2c02241
NR
28139@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
28140@node GDB/MI Signal Handling Commands
28141@section @sc{gdb/mi} Signal Handling Commands
922fbb7b 28142
a2c02241 28143Signal handling commands are not implemented.
922fbb7b 28144
a2c02241 28145@c @subheading -signal-handle
922fbb7b 28146
a2c02241 28147@c @subheading -signal-list-handle-actions
922fbb7b 28148
a2c02241
NR
28149@c @subheading -signal-list-signal-types
28150@end ignore
922fbb7b 28151
922fbb7b 28152
a2c02241
NR
28153@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
28154@node GDB/MI Target Manipulation
28155@section @sc{gdb/mi} Target Manipulation Commands
922fbb7b
AC
28156
28157
a2c02241
NR
28158@subheading The @code{-target-attach} Command
28159@findex -target-attach
922fbb7b
AC
28160
28161@subsubheading Synopsis
28162
28163@smallexample
c3b108f7 28164 -target-attach @var{pid} | @var{gid} | @var{file}
922fbb7b
AC
28165@end smallexample
28166
c3b108f7
VP
28167Attach to a process @var{pid} or a file @var{file} outside of
28168@value{GDBN}, or a thread group @var{gid}. If attaching to a thread
28169group, the id previously returned by
28170@samp{-list-thread-groups --available} must be used.
922fbb7b 28171
79a6e687 28172@subsubheading @value{GDBN} Command
922fbb7b 28173
a2c02241 28174The corresponding @value{GDBN} command is @samp{attach}.
922fbb7b 28175
a2c02241 28176@subsubheading Example
b56e7235
VP
28177@smallexample
28178(gdb)
28179-target-attach 34
28180=thread-created,id="1"
5ae4183a 28181*stopped,thread-id="1",frame=@{addr="0xb7f7e410",func="bar",args=[]@}
b56e7235
VP
28182^done
28183(gdb)
28184@end smallexample
a2c02241 28185
9901a55b 28186@ignore
a2c02241
NR
28187@subheading The @code{-target-compare-sections} Command
28188@findex -target-compare-sections
922fbb7b
AC
28189
28190@subsubheading Synopsis
28191
28192@smallexample
a2c02241 28193 -target-compare-sections [ @var{section} ]
922fbb7b
AC
28194@end smallexample
28195
a2c02241
NR
28196Compare data of section @var{section} on target to the exec file.
28197Without the argument, all sections are compared.
922fbb7b 28198
a2c02241 28199@subsubheading @value{GDBN} Command
922fbb7b 28200
a2c02241 28201The @value{GDBN} equivalent is @samp{compare-sections}.
922fbb7b 28202
a2c02241
NR
28203@subsubheading Example
28204N.A.
9901a55b 28205@end ignore
a2c02241
NR
28206
28207
28208@subheading The @code{-target-detach} Command
28209@findex -target-detach
922fbb7b
AC
28210
28211@subsubheading Synopsis
28212
28213@smallexample
c3b108f7 28214 -target-detach [ @var{pid} | @var{gid} ]
922fbb7b
AC
28215@end smallexample
28216
a2c02241 28217Detach from the remote target which normally resumes its execution.
c3b108f7
VP
28218If either @var{pid} or @var{gid} is specified, detaches from either
28219the specified process, or specified thread group. There's no output.
a2c02241 28220
79a6e687 28221@subsubheading @value{GDBN} Command
a2c02241
NR
28222
28223The corresponding @value{GDBN} command is @samp{detach}.
28224
28225@subsubheading Example
922fbb7b
AC
28226
28227@smallexample
594fe323 28228(gdb)
a2c02241
NR
28229-target-detach
28230^done
594fe323 28231(gdb)
922fbb7b
AC
28232@end smallexample
28233
28234
a2c02241
NR
28235@subheading The @code{-target-disconnect} Command
28236@findex -target-disconnect
922fbb7b
AC
28237
28238@subsubheading Synopsis
28239
123dc839 28240@smallexample
a2c02241 28241 -target-disconnect
123dc839 28242@end smallexample
922fbb7b 28243
a2c02241
NR
28244Disconnect from the remote target. There's no output and the target is
28245generally not resumed.
28246
79a6e687 28247@subsubheading @value{GDBN} Command
a2c02241
NR
28248
28249The corresponding @value{GDBN} command is @samp{disconnect}.
bc8ced35
NR
28250
28251@subsubheading Example
922fbb7b
AC
28252
28253@smallexample
594fe323 28254(gdb)
a2c02241
NR
28255-target-disconnect
28256^done
594fe323 28257(gdb)
922fbb7b
AC
28258@end smallexample
28259
28260
a2c02241
NR
28261@subheading The @code{-target-download} Command
28262@findex -target-download
922fbb7b
AC
28263
28264@subsubheading Synopsis
28265
28266@smallexample
a2c02241 28267 -target-download
922fbb7b
AC
28268@end smallexample
28269
a2c02241
NR
28270Loads the executable onto the remote target.
28271It prints out an update message every half second, which includes the fields:
28272
28273@table @samp
28274@item section
28275The name of the section.
28276@item section-sent
28277The size of what has been sent so far for that section.
28278@item section-size
28279The size of the section.
28280@item total-sent
28281The total size of what was sent so far (the current and the previous sections).
28282@item total-size
28283The size of the overall executable to download.
28284@end table
28285
28286@noindent
28287Each message is sent as status record (@pxref{GDB/MI Output Syntax, ,
28288@sc{gdb/mi} Output Syntax}).
28289
28290In addition, it prints the name and size of the sections, as they are
28291downloaded. These messages include the following fields:
28292
28293@table @samp
28294@item section
28295The name of the section.
28296@item section-size
28297The size of the section.
28298@item total-size
28299The size of the overall executable to download.
28300@end table
28301
28302@noindent
28303At the end, a summary is printed.
28304
28305@subsubheading @value{GDBN} Command
28306
28307The corresponding @value{GDBN} command is @samp{load}.
28308
28309@subsubheading Example
28310
28311Note: each status message appears on a single line. Here the messages
28312have been broken down so that they can fit onto a page.
922fbb7b
AC
28313
28314@smallexample
594fe323 28315(gdb)
a2c02241
NR
28316-target-download
28317+download,@{section=".text",section-size="6668",total-size="9880"@}
28318+download,@{section=".text",section-sent="512",section-size="6668",
28319total-sent="512",total-size="9880"@}
28320+download,@{section=".text",section-sent="1024",section-size="6668",
28321total-sent="1024",total-size="9880"@}
28322+download,@{section=".text",section-sent="1536",section-size="6668",
28323total-sent="1536",total-size="9880"@}
28324+download,@{section=".text",section-sent="2048",section-size="6668",
28325total-sent="2048",total-size="9880"@}
28326+download,@{section=".text",section-sent="2560",section-size="6668",
28327total-sent="2560",total-size="9880"@}
28328+download,@{section=".text",section-sent="3072",section-size="6668",
28329total-sent="3072",total-size="9880"@}
28330+download,@{section=".text",section-sent="3584",section-size="6668",
28331total-sent="3584",total-size="9880"@}
28332+download,@{section=".text",section-sent="4096",section-size="6668",
28333total-sent="4096",total-size="9880"@}
28334+download,@{section=".text",section-sent="4608",section-size="6668",
28335total-sent="4608",total-size="9880"@}
28336+download,@{section=".text",section-sent="5120",section-size="6668",
28337total-sent="5120",total-size="9880"@}
28338+download,@{section=".text",section-sent="5632",section-size="6668",
28339total-sent="5632",total-size="9880"@}
28340+download,@{section=".text",section-sent="6144",section-size="6668",
28341total-sent="6144",total-size="9880"@}
28342+download,@{section=".text",section-sent="6656",section-size="6668",
28343total-sent="6656",total-size="9880"@}
28344+download,@{section=".init",section-size="28",total-size="9880"@}
28345+download,@{section=".fini",section-size="28",total-size="9880"@}
28346+download,@{section=".data",section-size="3156",total-size="9880"@}
28347+download,@{section=".data",section-sent="512",section-size="3156",
28348total-sent="7236",total-size="9880"@}
28349+download,@{section=".data",section-sent="1024",section-size="3156",
28350total-sent="7748",total-size="9880"@}
28351+download,@{section=".data",section-sent="1536",section-size="3156",
28352total-sent="8260",total-size="9880"@}
28353+download,@{section=".data",section-sent="2048",section-size="3156",
28354total-sent="8772",total-size="9880"@}
28355+download,@{section=".data",section-sent="2560",section-size="3156",
28356total-sent="9284",total-size="9880"@}
28357+download,@{section=".data",section-sent="3072",section-size="3156",
28358total-sent="9796",total-size="9880"@}
28359^done,address="0x10004",load-size="9880",transfer-rate="6586",
28360write-rate="429"
594fe323 28361(gdb)
922fbb7b
AC
28362@end smallexample
28363
28364
9901a55b 28365@ignore
a2c02241
NR
28366@subheading The @code{-target-exec-status} Command
28367@findex -target-exec-status
922fbb7b
AC
28368
28369@subsubheading Synopsis
28370
28371@smallexample
a2c02241 28372 -target-exec-status
922fbb7b
AC
28373@end smallexample
28374
a2c02241
NR
28375Provide information on the state of the target (whether it is running or
28376not, for instance).
922fbb7b 28377
a2c02241 28378@subsubheading @value{GDBN} Command
922fbb7b 28379
a2c02241
NR
28380There's no equivalent @value{GDBN} command.
28381
28382@subsubheading Example
28383N.A.
922fbb7b 28384
a2c02241
NR
28385
28386@subheading The @code{-target-list-available-targets} Command
28387@findex -target-list-available-targets
922fbb7b
AC
28388
28389@subsubheading Synopsis
28390
28391@smallexample
a2c02241 28392 -target-list-available-targets
922fbb7b
AC
28393@end smallexample
28394
a2c02241 28395List the possible targets to connect to.
922fbb7b 28396
a2c02241 28397@subsubheading @value{GDBN} Command
922fbb7b 28398
a2c02241 28399The corresponding @value{GDBN} command is @samp{help target}.
922fbb7b 28400
a2c02241
NR
28401@subsubheading Example
28402N.A.
28403
28404
28405@subheading The @code{-target-list-current-targets} Command
28406@findex -target-list-current-targets
922fbb7b
AC
28407
28408@subsubheading Synopsis
28409
28410@smallexample
a2c02241 28411 -target-list-current-targets
922fbb7b
AC
28412@end smallexample
28413
a2c02241 28414Describe the current target.
922fbb7b 28415
a2c02241 28416@subsubheading @value{GDBN} Command
922fbb7b 28417
a2c02241
NR
28418The corresponding information is printed by @samp{info file} (among
28419other things).
922fbb7b 28420
a2c02241
NR
28421@subsubheading Example
28422N.A.
28423
28424
28425@subheading The @code{-target-list-parameters} Command
28426@findex -target-list-parameters
922fbb7b
AC
28427
28428@subsubheading Synopsis
28429
28430@smallexample
a2c02241 28431 -target-list-parameters
922fbb7b
AC
28432@end smallexample
28433
a2c02241 28434@c ????
9901a55b 28435@end ignore
a2c02241
NR
28436
28437@subsubheading @value{GDBN} Command
28438
28439No equivalent.
922fbb7b
AC
28440
28441@subsubheading Example
a2c02241
NR
28442N.A.
28443
28444
28445@subheading The @code{-target-select} Command
28446@findex -target-select
28447
28448@subsubheading Synopsis
922fbb7b
AC
28449
28450@smallexample
a2c02241 28451 -target-select @var{type} @var{parameters @dots{}}
922fbb7b
AC
28452@end smallexample
28453
a2c02241 28454Connect @value{GDBN} to the remote target. This command takes two args:
922fbb7b 28455
a2c02241
NR
28456@table @samp
28457@item @var{type}
75c99385 28458The type of target, for instance @samp{remote}, etc.
a2c02241
NR
28459@item @var{parameters}
28460Device names, host names and the like. @xref{Target Commands, ,
79a6e687 28461Commands for Managing Targets}, for more details.
a2c02241
NR
28462@end table
28463
28464The output is a connection notification, followed by the address at
28465which the target program is, in the following form:
922fbb7b
AC
28466
28467@smallexample
a2c02241
NR
28468^connected,addr="@var{address}",func="@var{function name}",
28469 args=[@var{arg list}]
922fbb7b
AC
28470@end smallexample
28471
a2c02241
NR
28472@subsubheading @value{GDBN} Command
28473
28474The corresponding @value{GDBN} command is @samp{target}.
265eeb58
NR
28475
28476@subsubheading Example
922fbb7b 28477
265eeb58 28478@smallexample
594fe323 28479(gdb)
75c99385 28480-target-select remote /dev/ttya
a2c02241 28481^connected,addr="0xfe00a300",func="??",args=[]
594fe323 28482(gdb)
265eeb58 28483@end smallexample
ef21caaf 28484
a6b151f1
DJ
28485@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
28486@node GDB/MI File Transfer Commands
28487@section @sc{gdb/mi} File Transfer Commands
28488
28489
28490@subheading The @code{-target-file-put} Command
28491@findex -target-file-put
28492
28493@subsubheading Synopsis
28494
28495@smallexample
28496 -target-file-put @var{hostfile} @var{targetfile}
28497@end smallexample
28498
28499Copy file @var{hostfile} from the host system (the machine running
28500@value{GDBN}) to @var{targetfile} on the target system.
28501
28502@subsubheading @value{GDBN} Command
28503
28504The corresponding @value{GDBN} command is @samp{remote put}.
28505
28506@subsubheading Example
28507
28508@smallexample
28509(gdb)
28510-target-file-put localfile remotefile
28511^done
28512(gdb)
28513@end smallexample
28514
28515
1763a388 28516@subheading The @code{-target-file-get} Command
a6b151f1
DJ
28517@findex -target-file-get
28518
28519@subsubheading Synopsis
28520
28521@smallexample
28522 -target-file-get @var{targetfile} @var{hostfile}
28523@end smallexample
28524
28525Copy file @var{targetfile} from the target system to @var{hostfile}
28526on the host system.
28527
28528@subsubheading @value{GDBN} Command
28529
28530The corresponding @value{GDBN} command is @samp{remote get}.
28531
28532@subsubheading Example
28533
28534@smallexample
28535(gdb)
28536-target-file-get remotefile localfile
28537^done
28538(gdb)
28539@end smallexample
28540
28541
28542@subheading The @code{-target-file-delete} Command
28543@findex -target-file-delete
28544
28545@subsubheading Synopsis
28546
28547@smallexample
28548 -target-file-delete @var{targetfile}
28549@end smallexample
28550
28551Delete @var{targetfile} from the target system.
28552
28553@subsubheading @value{GDBN} Command
28554
28555The corresponding @value{GDBN} command is @samp{remote delete}.
28556
28557@subsubheading Example
28558
28559@smallexample
28560(gdb)
28561-target-file-delete remotefile
28562^done
28563(gdb)
28564@end smallexample
28565
28566
ef21caaf
NR
28567@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
28568@node GDB/MI Miscellaneous Commands
28569@section Miscellaneous @sc{gdb/mi} Commands
28570
28571@c @subheading -gdb-complete
28572
28573@subheading The @code{-gdb-exit} Command
28574@findex -gdb-exit
28575
28576@subsubheading Synopsis
28577
28578@smallexample
28579 -gdb-exit
28580@end smallexample
28581
28582Exit @value{GDBN} immediately.
28583
28584@subsubheading @value{GDBN} Command
28585
28586Approximately corresponds to @samp{quit}.
28587
28588@subsubheading Example
28589
28590@smallexample
594fe323 28591(gdb)
ef21caaf
NR
28592-gdb-exit
28593^exit
28594@end smallexample
28595
a2c02241 28596
9901a55b 28597@ignore
a2c02241
NR
28598@subheading The @code{-exec-abort} Command
28599@findex -exec-abort
28600
28601@subsubheading Synopsis
28602
28603@smallexample
28604 -exec-abort
28605@end smallexample
28606
28607Kill the inferior running program.
28608
28609@subsubheading @value{GDBN} Command
28610
28611The corresponding @value{GDBN} command is @samp{kill}.
28612
28613@subsubheading Example
28614N.A.
9901a55b 28615@end ignore
a2c02241
NR
28616
28617
ef21caaf
NR
28618@subheading The @code{-gdb-set} Command
28619@findex -gdb-set
28620
28621@subsubheading Synopsis
28622
28623@smallexample
28624 -gdb-set
28625@end smallexample
28626
28627Set an internal @value{GDBN} variable.
28628@c IS THIS A DOLLAR VARIABLE? OR SOMETHING LIKE ANNOTATE ?????
28629
28630@subsubheading @value{GDBN} Command
28631
28632The corresponding @value{GDBN} command is @samp{set}.
28633
28634@subsubheading Example
28635
28636@smallexample
594fe323 28637(gdb)
ef21caaf
NR
28638-gdb-set $foo=3
28639^done
594fe323 28640(gdb)
ef21caaf
NR
28641@end smallexample
28642
28643
28644@subheading The @code{-gdb-show} Command
28645@findex -gdb-show
28646
28647@subsubheading Synopsis
28648
28649@smallexample
28650 -gdb-show
28651@end smallexample
28652
28653Show the current value of a @value{GDBN} variable.
28654
79a6e687 28655@subsubheading @value{GDBN} Command
ef21caaf
NR
28656
28657The corresponding @value{GDBN} command is @samp{show}.
28658
28659@subsubheading Example
28660
28661@smallexample
594fe323 28662(gdb)
ef21caaf
NR
28663-gdb-show annotate
28664^done,value="0"
594fe323 28665(gdb)
ef21caaf
NR
28666@end smallexample
28667
28668@c @subheading -gdb-source
28669
28670
28671@subheading The @code{-gdb-version} Command
28672@findex -gdb-version
28673
28674@subsubheading Synopsis
28675
28676@smallexample
28677 -gdb-version
28678@end smallexample
28679
28680Show version information for @value{GDBN}. Used mostly in testing.
28681
28682@subsubheading @value{GDBN} Command
28683
28684The @value{GDBN} equivalent is @samp{show version}. @value{GDBN} by
28685default shows this information when you start an interactive session.
28686
28687@subsubheading Example
28688
28689@c This example modifies the actual output from GDB to avoid overfull
28690@c box in TeX.
28691@smallexample
594fe323 28692(gdb)
ef21caaf
NR
28693-gdb-version
28694~GNU gdb 5.2.1
28695~Copyright 2000 Free Software Foundation, Inc.
28696~GDB is free software, covered by the GNU General Public License, and
28697~you are welcome to change it and/or distribute copies of it under
28698~ certain conditions.
28699~Type "show copying" to see the conditions.
28700~There is absolutely no warranty for GDB. Type "show warranty" for
28701~ details.
28702~This GDB was configured as
28703 "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi".
28704^done
594fe323 28705(gdb)
ef21caaf
NR
28706@end smallexample
28707
084344da
VP
28708@subheading The @code{-list-features} Command
28709@findex -list-features
28710
28711Returns a list of particular features of the MI protocol that
28712this version of gdb implements. A feature can be a command,
28713or a new field in an output of some command, or even an
28714important bugfix. While a frontend can sometimes detect presence
28715of a feature at runtime, it is easier to perform detection at debugger
28716startup.
28717
28718The command returns a list of strings, with each string naming an
28719available feature. Each returned string is just a name, it does not
28720have any internal structure. The list of possible feature names
28721is given below.
28722
28723Example output:
28724
28725@smallexample
28726(gdb) -list-features
28727^done,result=["feature1","feature2"]
28728@end smallexample
28729
28730The current list of features is:
28731
30e026bb
VP
28732@table @samp
28733@item frozen-varobjs
28734Indicates presence of the @code{-var-set-frozen} command, as well
28735as possible presense of the @code{frozen} field in the output
28736of @code{-varobj-create}.
28737@item pending-breakpoints
28738Indicates presence of the @option{-f} option to the @code{-break-insert} command.
b6313243
TT
28739@item python
28740Indicates presence of Python scripting support, Python-based
28741pretty-printing commands, and possible presence of the
28742@samp{display_hint} field in the output of @code{-var-list-children}
30e026bb
VP
28743@item thread-info
28744Indicates presence of the @code{-thread-info} command.
8b4ed427 28745
30e026bb 28746@end table
084344da 28747
c6ebd6cf
VP
28748@subheading The @code{-list-target-features} Command
28749@findex -list-target-features
28750
28751Returns a list of particular features that are supported by the
28752target. Those features affect the permitted MI commands, but
28753unlike the features reported by the @code{-list-features} command, the
28754features depend on which target GDB is using at the moment. Whenever
28755a target can change, due to commands such as @code{-target-select},
28756@code{-target-attach} or @code{-exec-run}, the list of target features
28757may change, and the frontend should obtain it again.
28758Example output:
28759
28760@smallexample
28761(gdb) -list-features
28762^done,result=["async"]
28763@end smallexample
28764
28765The current list of features is:
28766
28767@table @samp
28768@item async
28769Indicates that the target is capable of asynchronous command
28770execution, which means that @value{GDBN} will accept further commands
28771while the target is running.
28772
28773@end table
28774
c3b108f7
VP
28775@subheading The @code{-list-thread-groups} Command
28776@findex -list-thread-groups
28777
28778@subheading Synopsis
28779
28780@smallexample
dc146f7c 28781-list-thread-groups [ --available ] [ --recurse 1 ] [ @var{group} ... ]
c3b108f7
VP
28782@end smallexample
28783
dc146f7c
VP
28784Lists thread groups (@pxref{Thread groups}). When a single thread
28785group is passed as the argument, lists the children of that group.
28786When several thread group are passed, lists information about those
28787thread groups. Without any parameters, lists information about all
28788top-level thread groups.
28789
28790Normally, thread groups that are being debugged are reported.
28791With the @samp{--available} option, @value{GDBN} reports thread groups
28792available on the target.
28793
28794The output of this command may have either a @samp{threads} result or
28795a @samp{groups} result. The @samp{thread} result has a list of tuples
28796as value, with each tuple describing a thread (@pxref{GDB/MI Thread
28797Information}). The @samp{groups} result has a list of tuples as value,
28798each tuple describing a thread group. If top-level groups are
28799requested (that is, no parameter is passed), or when several groups
28800are passed, the output always has a @samp{groups} result. The format
28801of the @samp{group} result is described below.
28802
28803To reduce the number of roundtrips it's possible to list thread groups
28804together with their children, by passing the @samp{--recurse} option
28805and the recursion depth. Presently, only recursion depth of 1 is
28806permitted. If this option is present, then every reported thread group
28807will also include its children, either as @samp{group} or
28808@samp{threads} field.
28809
28810In general, any combination of option and parameters is permitted, with
28811the following caveats:
28812
28813@itemize @bullet
28814@item
28815When a single thread group is passed, the output will typically
28816be the @samp{threads} result. Because threads may not contain
28817anything, the @samp{recurse} option will be ignored.
28818
28819@item
28820When the @samp{--available} option is passed, limited information may
28821be available. In particular, the list of threads of a process might
28822be inaccessible. Further, specifying specific thread groups might
28823not give any performance advantage over listing all thread groups.
28824The frontend should assume that @samp{-list-thread-groups --available}
28825is always an expensive operation and cache the results.
28826
28827@end itemize
28828
28829The @samp{groups} result is a list of tuples, where each tuple may
28830have the following fields:
28831
28832@table @code
28833@item id
28834Identifier of the thread group. This field is always present.
a79b8f6e
VP
28835The identifier is an opaque string; frontends should not try to
28836convert it to an integer, even though it might look like one.
dc146f7c
VP
28837
28838@item type
28839The type of the thread group. At present, only @samp{process} is a
28840valid type.
28841
28842@item pid
28843The target-specific process identifier. This field is only present
a79b8f6e 28844for thread groups of type @samp{process} and only if the process exists.
c3b108f7 28845
dc146f7c
VP
28846@item num_children
28847The number of children this thread group has. This field may be
28848absent for an available thread group.
28849
28850@item threads
28851This field has a list of tuples as value, each tuple describing a
28852thread. It may be present if the @samp{--recurse} option is
28853specified, and it's actually possible to obtain the threads.
28854
28855@item cores
28856This field is a list of integers, each identifying a core that one
28857thread of the group is running on. This field may be absent if
28858such information is not available.
28859
a79b8f6e
VP
28860@item executable
28861The name of the executable file that corresponds to this thread group.
28862The field is only present for thread groups of type @samp{process},
28863and only if there is a corresponding executable file.
28864
dc146f7c 28865@end table
c3b108f7
VP
28866
28867@subheading Example
28868
28869@smallexample
28870@value{GDBP}
28871-list-thread-groups
28872^done,groups=[@{id="17",type="process",pid="yyy",num_children="2"@}]
28873-list-thread-groups 17
28874^done,threads=[@{id="2",target-id="Thread 0xb7e14b90 (LWP 21257)",
28875 frame=@{level="0",addr="0xffffe410",func="__kernel_vsyscall",args=[]@},state="running"@},
28876@{id="1",target-id="Thread 0xb7e156b0 (LWP 21254)",
28877 frame=@{level="0",addr="0x0804891f",func="foo",args=[@{name="i",value="10"@}],
28878 file="/tmp/a.c",fullname="/tmp/a.c",line="158"@},state="running"@}]]
dc146f7c
VP
28879-list-thread-groups --available
28880^done,groups=[@{id="17",type="process",pid="yyy",num_children="2",cores=[1,2]@}]
28881-list-thread-groups --available --recurse 1
28882 ^done,groups=[@{id="17", types="process",pid="yyy",num_children="2",cores=[1,2],
28883 threads=[@{id="1",target-id="Thread 0xb7e14b90",cores=[1]@},
28884 @{id="2",target-id="Thread 0xb7e14b90",cores=[2]@}]@},..]
28885-list-thread-groups --available --recurse 1 17 18
28886^done,groups=[@{id="17", types="process",pid="yyy",num_children="2",cores=[1,2],
28887 threads=[@{id="1",target-id="Thread 0xb7e14b90",cores=[1]@},
28888 @{id="2",target-id="Thread 0xb7e14b90",cores=[2]@}]@},...]
c3b108f7 28889@end smallexample
c6ebd6cf 28890
a79b8f6e
VP
28891
28892@subheading The @code{-add-inferior} Command
28893@findex -add-inferior
28894
28895@subheading Synopsis
28896
28897@smallexample
28898-add-inferior
28899@end smallexample
28900
28901Creates a new inferior (@pxref{Inferiors and Programs}). The created
28902inferior is not associated with any executable. Such association may
28903be established with the @samp{-file-exec-and-symbols} command
28904(@pxref{GDB/MI File Commands}). The command response has a single
28905field, @samp{thread-group}, whose value is the identifier of the
28906thread group corresponding to the new inferior.
28907
28908@subheading Example
28909
28910@smallexample
28911@value{GDBP}
28912-add-inferior
28913^done,thread-group="i3"
28914@end smallexample
28915
ef21caaf
NR
28916@subheading The @code{-interpreter-exec} Command
28917@findex -interpreter-exec
28918
28919@subheading Synopsis
28920
28921@smallexample
28922-interpreter-exec @var{interpreter} @var{command}
28923@end smallexample
a2c02241 28924@anchor{-interpreter-exec}
ef21caaf
NR
28925
28926Execute the specified @var{command} in the given @var{interpreter}.
28927
28928@subheading @value{GDBN} Command
28929
28930The corresponding @value{GDBN} command is @samp{interpreter-exec}.
28931
28932@subheading Example
28933
28934@smallexample
594fe323 28935(gdb)
ef21caaf
NR
28936-interpreter-exec console "break main"
28937&"During symbol reading, couldn't parse type; debugger out of date?.\n"
28938&"During symbol reading, bad structure-type format.\n"
28939~"Breakpoint 1 at 0x8074fc6: file ../../src/gdb/main.c, line 743.\n"
28940^done
594fe323 28941(gdb)
ef21caaf
NR
28942@end smallexample
28943
28944@subheading The @code{-inferior-tty-set} Command
28945@findex -inferior-tty-set
28946
28947@subheading Synopsis
28948
28949@smallexample
28950-inferior-tty-set /dev/pts/1
28951@end smallexample
28952
28953Set terminal for future runs of the program being debugged.
28954
28955@subheading @value{GDBN} Command
28956
28957The corresponding @value{GDBN} command is @samp{set inferior-tty} /dev/pts/1.
28958
28959@subheading Example
28960
28961@smallexample
594fe323 28962(gdb)
ef21caaf
NR
28963-inferior-tty-set /dev/pts/1
28964^done
594fe323 28965(gdb)
ef21caaf
NR
28966@end smallexample
28967
28968@subheading The @code{-inferior-tty-show} Command
28969@findex -inferior-tty-show
28970
28971@subheading Synopsis
28972
28973@smallexample
28974-inferior-tty-show
28975@end smallexample
28976
28977Show terminal for future runs of program being debugged.
28978
28979@subheading @value{GDBN} Command
28980
28981The corresponding @value{GDBN} command is @samp{show inferior-tty}.
28982
28983@subheading Example
28984
28985@smallexample
594fe323 28986(gdb)
ef21caaf
NR
28987-inferior-tty-set /dev/pts/1
28988^done
594fe323 28989(gdb)
ef21caaf
NR
28990-inferior-tty-show
28991^done,inferior_tty_terminal="/dev/pts/1"
594fe323 28992(gdb)
ef21caaf 28993@end smallexample
922fbb7b 28994
a4eefcd8
NR
28995@subheading The @code{-enable-timings} Command
28996@findex -enable-timings
28997
28998@subheading Synopsis
28999
29000@smallexample
29001-enable-timings [yes | no]
29002@end smallexample
29003
29004Toggle the printing of the wallclock, user and system times for an MI
29005command as a field in its output. This command is to help frontend
29006developers optimize the performance of their code. No argument is
29007equivalent to @samp{yes}.
29008
29009@subheading @value{GDBN} Command
29010
29011No equivalent.
29012
29013@subheading Example
29014
29015@smallexample
29016(gdb)
29017-enable-timings
29018^done
29019(gdb)
29020-break-insert main
29021^done,bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
29022addr="0x080484ed",func="main",file="myprog.c",
29023fullname="/home/nickrob/myprog.c",line="73",times="0"@},
29024time=@{wallclock="0.05185",user="0.00800",system="0.00000"@}
29025(gdb)
29026-enable-timings no
29027^done
29028(gdb)
29029-exec-run
29030^running
29031(gdb)
a47ec5fe 29032*stopped,reason="breakpoint-hit",disp="keep",bkptno="1",thread-id="0",
a4eefcd8
NR
29033frame=@{addr="0x080484ed",func="main",args=[@{name="argc",value="1"@},
29034@{name="argv",value="0xbfb60364"@}],file="myprog.c",
29035fullname="/home/nickrob/myprog.c",line="73"@}
29036(gdb)
29037@end smallexample
29038
922fbb7b
AC
29039@node Annotations
29040@chapter @value{GDBN} Annotations
29041
086432e2
AC
29042This chapter describes annotations in @value{GDBN}. Annotations were
29043designed to interface @value{GDBN} to graphical user interfaces or other
29044similar programs which want to interact with @value{GDBN} at a
922fbb7b
AC
29045relatively high level.
29046
d3e8051b 29047The annotation mechanism has largely been superseded by @sc{gdb/mi}
086432e2
AC
29048(@pxref{GDB/MI}).
29049
922fbb7b
AC
29050@ignore
29051This is Edition @value{EDITION}, @value{DATE}.
29052@end ignore
29053
29054@menu
29055* Annotations Overview:: What annotations are; the general syntax.
9e6c4bd5 29056* Server Prefix:: Issuing a command without affecting user state.
922fbb7b
AC
29057* Prompting:: Annotations marking @value{GDBN}'s need for input.
29058* Errors:: Annotations for error messages.
922fbb7b
AC
29059* Invalidation:: Some annotations describe things now invalid.
29060* Annotations for Running::
29061 Whether the program is running, how it stopped, etc.
29062* Source Annotations:: Annotations describing source code.
922fbb7b
AC
29063@end menu
29064
29065@node Annotations Overview
29066@section What is an Annotation?
29067@cindex annotations
29068
922fbb7b
AC
29069Annotations start with a newline character, two @samp{control-z}
29070characters, and the name of the annotation. If there is no additional
29071information associated with this annotation, the name of the annotation
29072is followed immediately by a newline. If there is additional
29073information, the name of the annotation is followed by a space, the
29074additional information, and a newline. The additional information
29075cannot contain newline characters.
29076
29077Any output not beginning with a newline and two @samp{control-z}
29078characters denotes literal output from @value{GDBN}. Currently there is
29079no need for @value{GDBN} to output a newline followed by two
29080@samp{control-z} characters, but if there was such a need, the
29081annotations could be extended with an @samp{escape} annotation which
29082means those three characters as output.
29083
086432e2
AC
29084The annotation @var{level}, which is specified using the
29085@option{--annotate} command line option (@pxref{Mode Options}), controls
29086how much information @value{GDBN} prints together with its prompt,
29087values of expressions, source lines, and other types of output. Level 0
d3e8051b 29088is for no annotations, level 1 is for use when @value{GDBN} is run as a
086432e2
AC
29089subprocess of @sc{gnu} Emacs, level 3 is the maximum annotation suitable
29090for programs that control @value{GDBN}, and level 2 annotations have
29091been made obsolete (@pxref{Limitations, , Limitations of the Annotation
09d4efe1
EZ
29092Interface, annotate, GDB's Obsolete Annotations}).
29093
29094@table @code
29095@kindex set annotate
29096@item set annotate @var{level}
e09f16f9 29097The @value{GDBN} command @code{set annotate} sets the level of
09d4efe1 29098annotations to the specified @var{level}.
9c16f35a
EZ
29099
29100@item show annotate
29101@kindex show annotate
29102Show the current annotation level.
09d4efe1
EZ
29103@end table
29104
29105This chapter describes level 3 annotations.
086432e2 29106
922fbb7b
AC
29107A simple example of starting up @value{GDBN} with annotations is:
29108
29109@smallexample
086432e2
AC
29110$ @kbd{gdb --annotate=3}
29111GNU gdb 6.0
29112Copyright 2003 Free Software Foundation, Inc.
922fbb7b
AC
29113GDB is free software, covered by the GNU General Public License,
29114and you are welcome to change it and/or distribute copies of it
29115under certain conditions.
29116Type "show copying" to see the conditions.
29117There is absolutely no warranty for GDB. Type "show warranty"
29118for details.
086432e2 29119This GDB was configured as "i386-pc-linux-gnu"
922fbb7b
AC
29120
29121^Z^Zpre-prompt
f7dc1244 29122(@value{GDBP})
922fbb7b 29123^Z^Zprompt
086432e2 29124@kbd{quit}
922fbb7b
AC
29125
29126^Z^Zpost-prompt
b383017d 29127$
922fbb7b
AC
29128@end smallexample
29129
29130Here @samp{quit} is input to @value{GDBN}; the rest is output from
29131@value{GDBN}. The three lines beginning @samp{^Z^Z} (where @samp{^Z}
29132denotes a @samp{control-z} character) are annotations; the rest is
29133output from @value{GDBN}.
29134
9e6c4bd5
NR
29135@node Server Prefix
29136@section The Server Prefix
29137@cindex server prefix
29138
29139If you prefix a command with @samp{server } then it will not affect
29140the command history, nor will it affect @value{GDBN}'s notion of which
29141command to repeat if @key{RET} is pressed on a line by itself. This
29142means that commands can be run behind a user's back by a front-end in
29143a transparent manner.
29144
d837706a
NR
29145The @code{server } prefix does not affect the recording of values into
29146the value history; to print a value without recording it into the
29147value history, use the @code{output} command instead of the
29148@code{print} command.
29149
29150Using this prefix also disables confirmation requests
29151(@pxref{confirmation requests}).
9e6c4bd5 29152
922fbb7b
AC
29153@node Prompting
29154@section Annotation for @value{GDBN} Input
29155
29156@cindex annotations for prompts
29157When @value{GDBN} prompts for input, it annotates this fact so it is possible
29158to know when to send output, when the output from a given command is
29159over, etc.
29160
29161Different kinds of input each have a different @dfn{input type}. Each
29162input type has three annotations: a @code{pre-} annotation, which
29163denotes the beginning of any prompt which is being output, a plain
29164annotation, which denotes the end of the prompt, and then a @code{post-}
29165annotation which denotes the end of any echo which may (or may not) be
29166associated with the input. For example, the @code{prompt} input type
29167features the following annotations:
29168
29169@smallexample
29170^Z^Zpre-prompt
29171^Z^Zprompt
29172^Z^Zpost-prompt
29173@end smallexample
29174
29175The input types are
29176
29177@table @code
e5ac9b53
EZ
29178@findex pre-prompt annotation
29179@findex prompt annotation
29180@findex post-prompt annotation
922fbb7b
AC
29181@item prompt
29182When @value{GDBN} is prompting for a command (the main @value{GDBN} prompt).
29183
e5ac9b53
EZ
29184@findex pre-commands annotation
29185@findex commands annotation
29186@findex post-commands annotation
922fbb7b
AC
29187@item commands
29188When @value{GDBN} prompts for a set of commands, like in the @code{commands}
29189command. The annotations are repeated for each command which is input.
29190
e5ac9b53
EZ
29191@findex pre-overload-choice annotation
29192@findex overload-choice annotation
29193@findex post-overload-choice annotation
922fbb7b
AC
29194@item overload-choice
29195When @value{GDBN} wants the user to select between various overloaded functions.
29196
e5ac9b53
EZ
29197@findex pre-query annotation
29198@findex query annotation
29199@findex post-query annotation
922fbb7b
AC
29200@item query
29201When @value{GDBN} wants the user to confirm a potentially dangerous operation.
29202
e5ac9b53
EZ
29203@findex pre-prompt-for-continue annotation
29204@findex prompt-for-continue annotation
29205@findex post-prompt-for-continue annotation
922fbb7b
AC
29206@item prompt-for-continue
29207When @value{GDBN} is asking the user to press return to continue. Note: Don't
29208expect this to work well; instead use @code{set height 0} to disable
29209prompting. This is because the counting of lines is buggy in the
29210presence of annotations.
29211@end table
29212
29213@node Errors
29214@section Errors
29215@cindex annotations for errors, warnings and interrupts
29216
e5ac9b53 29217@findex quit annotation
922fbb7b
AC
29218@smallexample
29219^Z^Zquit
29220@end smallexample
29221
29222This annotation occurs right before @value{GDBN} responds to an interrupt.
29223
e5ac9b53 29224@findex error annotation
922fbb7b
AC
29225@smallexample
29226^Z^Zerror
29227@end smallexample
29228
29229This annotation occurs right before @value{GDBN} responds to an error.
29230
29231Quit and error annotations indicate that any annotations which @value{GDBN} was
29232in the middle of may end abruptly. For example, if a
29233@code{value-history-begin} annotation is followed by a @code{error}, one
29234cannot expect to receive the matching @code{value-history-end}. One
29235cannot expect not to receive it either, however; an error annotation
29236does not necessarily mean that @value{GDBN} is immediately returning all the way
29237to the top level.
29238
e5ac9b53 29239@findex error-begin annotation
922fbb7b
AC
29240A quit or error annotation may be preceded by
29241
29242@smallexample
29243^Z^Zerror-begin
29244@end smallexample
29245
29246Any output between that and the quit or error annotation is the error
29247message.
29248
29249Warning messages are not yet annotated.
29250@c If we want to change that, need to fix warning(), type_error(),
29251@c range_error(), and possibly other places.
29252
922fbb7b
AC
29253@node Invalidation
29254@section Invalidation Notices
29255
29256@cindex annotations for invalidation messages
29257The following annotations say that certain pieces of state may have
29258changed.
29259
29260@table @code
e5ac9b53 29261@findex frames-invalid annotation
922fbb7b
AC
29262@item ^Z^Zframes-invalid
29263
29264The frames (for example, output from the @code{backtrace} command) may
29265have changed.
29266
e5ac9b53 29267@findex breakpoints-invalid annotation
922fbb7b
AC
29268@item ^Z^Zbreakpoints-invalid
29269
29270The breakpoints may have changed. For example, the user just added or
29271deleted a breakpoint.
29272@end table
29273
29274@node Annotations for Running
29275@section Running the Program
29276@cindex annotations for running programs
29277
e5ac9b53
EZ
29278@findex starting annotation
29279@findex stopping annotation
922fbb7b 29280When the program starts executing due to a @value{GDBN} command such as
b383017d 29281@code{step} or @code{continue},
922fbb7b
AC
29282
29283@smallexample
29284^Z^Zstarting
29285@end smallexample
29286
b383017d 29287is output. When the program stops,
922fbb7b
AC
29288
29289@smallexample
29290^Z^Zstopped
29291@end smallexample
29292
29293is output. Before the @code{stopped} annotation, a variety of
29294annotations describe how the program stopped.
29295
29296@table @code
e5ac9b53 29297@findex exited annotation
922fbb7b
AC
29298@item ^Z^Zexited @var{exit-status}
29299The program exited, and @var{exit-status} is the exit status (zero for
29300successful exit, otherwise nonzero).
29301
e5ac9b53
EZ
29302@findex signalled annotation
29303@findex signal-name annotation
29304@findex signal-name-end annotation
29305@findex signal-string annotation
29306@findex signal-string-end annotation
922fbb7b
AC
29307@item ^Z^Zsignalled
29308The program exited with a signal. After the @code{^Z^Zsignalled}, the
29309annotation continues:
29310
29311@smallexample
29312@var{intro-text}
29313^Z^Zsignal-name
29314@var{name}
29315^Z^Zsignal-name-end
29316@var{middle-text}
29317^Z^Zsignal-string
29318@var{string}
29319^Z^Zsignal-string-end
29320@var{end-text}
29321@end smallexample
29322
29323@noindent
29324where @var{name} is the name of the signal, such as @code{SIGILL} or
29325@code{SIGSEGV}, and @var{string} is the explanation of the signal, such
29326as @code{Illegal Instruction} or @code{Segmentation fault}.
29327@var{intro-text}, @var{middle-text}, and @var{end-text} are for the
29328user's benefit and have no particular format.
29329
e5ac9b53 29330@findex signal annotation
922fbb7b
AC
29331@item ^Z^Zsignal
29332The syntax of this annotation is just like @code{signalled}, but @value{GDBN} is
29333just saying that the program received the signal, not that it was
29334terminated with it.
29335
e5ac9b53 29336@findex breakpoint annotation
922fbb7b
AC
29337@item ^Z^Zbreakpoint @var{number}
29338The program hit breakpoint number @var{number}.
29339
e5ac9b53 29340@findex watchpoint annotation
922fbb7b
AC
29341@item ^Z^Zwatchpoint @var{number}
29342The program hit watchpoint number @var{number}.
29343@end table
29344
29345@node Source Annotations
29346@section Displaying Source
29347@cindex annotations for source display
29348
e5ac9b53 29349@findex source annotation
922fbb7b
AC
29350The following annotation is used instead of displaying source code:
29351
29352@smallexample
29353^Z^Zsource @var{filename}:@var{line}:@var{character}:@var{middle}:@var{addr}
29354@end smallexample
29355
29356where @var{filename} is an absolute file name indicating which source
29357file, @var{line} is the line number within that file (where 1 is the
29358first line in the file), @var{character} is the character position
29359within the file (where 0 is the first character in the file) (for most
29360debug formats this will necessarily point to the beginning of a line),
29361@var{middle} is @samp{middle} if @var{addr} is in the middle of the
29362line, or @samp{beg} if @var{addr} is at the beginning of the line, and
29363@var{addr} is the address in the target program associated with the
29364source which is being displayed. @var{addr} is in the form @samp{0x}
29365followed by one or more lowercase hex digits (note that this does not
29366depend on the language).
29367
4efc6507
DE
29368@node JIT Interface
29369@chapter JIT Compilation Interface
29370@cindex just-in-time compilation
29371@cindex JIT compilation interface
29372
29373This chapter documents @value{GDBN}'s @dfn{just-in-time} (JIT) compilation
29374interface. A JIT compiler is a program or library that generates native
29375executable code at runtime and executes it, usually in order to achieve good
29376performance while maintaining platform independence.
29377
29378Programs that use JIT compilation are normally difficult to debug because
29379portions of their code are generated at runtime, instead of being loaded from
29380object files, which is where @value{GDBN} normally finds the program's symbols
29381and debug information. In order to debug programs that use JIT compilation,
29382@value{GDBN} has an interface that allows the program to register in-memory
29383symbol files with @value{GDBN} at runtime.
29384
29385If you are using @value{GDBN} to debug a program that uses this interface, then
29386it should work transparently so long as you have not stripped the binary. If
29387you are developing a JIT compiler, then the interface is documented in the rest
29388of this chapter. At this time, the only known client of this interface is the
29389LLVM JIT.
29390
29391Broadly speaking, the JIT interface mirrors the dynamic loader interface. The
29392JIT compiler communicates with @value{GDBN} by writing data into a global
29393variable and calling a fuction at a well-known symbol. When @value{GDBN}
29394attaches, it reads a linked list of symbol files from the global variable to
29395find existing code, and puts a breakpoint in the function so that it can find
29396out about additional code.
29397
29398@menu
29399* Declarations:: Relevant C struct declarations
29400* Registering Code:: Steps to register code
29401* Unregistering Code:: Steps to unregister code
29402@end menu
29403
29404@node Declarations
29405@section JIT Declarations
29406
29407These are the relevant struct declarations that a C program should include to
29408implement the interface:
29409
29410@smallexample
29411typedef enum
29412@{
29413 JIT_NOACTION = 0,
29414 JIT_REGISTER_FN,
29415 JIT_UNREGISTER_FN
29416@} jit_actions_t;
29417
29418struct jit_code_entry
29419@{
29420 struct jit_code_entry *next_entry;
29421 struct jit_code_entry *prev_entry;
29422 const char *symfile_addr;
29423 uint64_t symfile_size;
29424@};
29425
29426struct jit_descriptor
29427@{
29428 uint32_t version;
29429 /* This type should be jit_actions_t, but we use uint32_t
29430 to be explicit about the bitwidth. */
29431 uint32_t action_flag;
29432 struct jit_code_entry *relevant_entry;
29433 struct jit_code_entry *first_entry;
29434@};
29435
29436/* GDB puts a breakpoint in this function. */
29437void __attribute__((noinline)) __jit_debug_register_code() @{ @};
29438
29439/* Make sure to specify the version statically, because the
29440 debugger may check the version before we can set it. */
29441struct jit_descriptor __jit_debug_descriptor = @{ 1, 0, 0, 0 @};
29442@end smallexample
29443
29444If the JIT is multi-threaded, then it is important that the JIT synchronize any
29445modifications to this global data properly, which can easily be done by putting
29446a global mutex around modifications to these structures.
29447
29448@node Registering Code
29449@section Registering Code
29450
29451To register code with @value{GDBN}, the JIT should follow this protocol:
29452
29453@itemize @bullet
29454@item
29455Generate an object file in memory with symbols and other desired debug
29456information. The file must include the virtual addresses of the sections.
29457
29458@item
29459Create a code entry for the file, which gives the start and size of the symbol
29460file.
29461
29462@item
29463Add it to the linked list in the JIT descriptor.
29464
29465@item
29466Point the relevant_entry field of the descriptor at the entry.
29467
29468@item
29469Set @code{action_flag} to @code{JIT_REGISTER} and call
29470@code{__jit_debug_register_code}.
29471@end itemize
29472
29473When @value{GDBN} is attached and the breakpoint fires, @value{GDBN} uses the
29474@code{relevant_entry} pointer so it doesn't have to walk the list looking for
29475new code. However, the linked list must still be maintained in order to allow
29476@value{GDBN} to attach to a running process and still find the symbol files.
29477
29478@node Unregistering Code
29479@section Unregistering Code
29480
29481If code is freed, then the JIT should use the following protocol:
29482
29483@itemize @bullet
29484@item
29485Remove the code entry corresponding to the code from the linked list.
29486
29487@item
29488Point the @code{relevant_entry} field of the descriptor at the code entry.
29489
29490@item
29491Set @code{action_flag} to @code{JIT_UNREGISTER} and call
29492@code{__jit_debug_register_code}.
29493@end itemize
29494
29495If the JIT frees or recompiles code without unregistering it, then @value{GDBN}
29496and the JIT will leak the memory used for the associated symbol files.
29497
8e04817f
AC
29498@node GDB Bugs
29499@chapter Reporting Bugs in @value{GDBN}
29500@cindex bugs in @value{GDBN}
29501@cindex reporting bugs in @value{GDBN}
c906108c 29502
8e04817f 29503Your bug reports play an essential role in making @value{GDBN} reliable.
c906108c 29504
8e04817f
AC
29505Reporting a bug may help you by bringing a solution to your problem, or it
29506may not. But in any case the principal function of a bug report is to help
29507the entire community by making the next version of @value{GDBN} work better. Bug
29508reports are your contribution to the maintenance of @value{GDBN}.
c906108c 29509
8e04817f
AC
29510In order for a bug report to serve its purpose, you must include the
29511information that enables us to fix the bug.
c4555f82
SC
29512
29513@menu
8e04817f
AC
29514* Bug Criteria:: Have you found a bug?
29515* Bug Reporting:: How to report bugs
c4555f82
SC
29516@end menu
29517
8e04817f 29518@node Bug Criteria
79a6e687 29519@section Have You Found a Bug?
8e04817f 29520@cindex bug criteria
c4555f82 29521
8e04817f 29522If you are not sure whether you have found a bug, here are some guidelines:
c4555f82
SC
29523
29524@itemize @bullet
8e04817f
AC
29525@cindex fatal signal
29526@cindex debugger crash
29527@cindex crash of debugger
c4555f82 29528@item
8e04817f
AC
29529If the debugger gets a fatal signal, for any input whatever, that is a
29530@value{GDBN} bug. Reliable debuggers never crash.
29531
29532@cindex error on valid input
29533@item
29534If @value{GDBN} produces an error message for valid input, that is a
29535bug. (Note that if you're cross debugging, the problem may also be
29536somewhere in the connection to the target.)
c4555f82 29537
8e04817f 29538@cindex invalid input
c4555f82 29539@item
8e04817f
AC
29540If @value{GDBN} does not produce an error message for invalid input,
29541that is a bug. However, you should note that your idea of
29542``invalid input'' might be our idea of ``an extension'' or ``support
29543for traditional practice''.
29544
29545@item
29546If you are an experienced user of debugging tools, your suggestions
29547for improvement of @value{GDBN} are welcome in any case.
c4555f82
SC
29548@end itemize
29549
8e04817f 29550@node Bug Reporting
79a6e687 29551@section How to Report Bugs
8e04817f
AC
29552@cindex bug reports
29553@cindex @value{GDBN} bugs, reporting
29554
29555A number of companies and individuals offer support for @sc{gnu} products.
29556If you obtained @value{GDBN} from a support organization, we recommend you
29557contact that organization first.
29558
29559You can find contact information for many support companies and
29560individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs
29561distribution.
29562@c should add a web page ref...
29563
c16158bc
JM
29564@ifset BUGURL
29565@ifset BUGURL_DEFAULT
129188f6 29566In any event, we also recommend that you submit bug reports for
d3e8051b 29567@value{GDBN}. The preferred method is to submit them directly using
129188f6
AC
29568@uref{http://www.gnu.org/software/gdb/bugs/, @value{GDBN}'s Bugs web
29569page}. Alternatively, the @email{bug-gdb@@gnu.org, e-mail gateway} can
29570be used.
8e04817f
AC
29571
29572@strong{Do not send bug reports to @samp{info-gdb}, or to
29573@samp{help-gdb}, or to any newsgroups.} Most users of @value{GDBN} do
29574not want to receive bug reports. Those that do have arranged to receive
29575@samp{bug-gdb}.
29576
29577The mailing list @samp{bug-gdb} has a newsgroup @samp{gnu.gdb.bug} which
29578serves as a repeater. The mailing list and the newsgroup carry exactly
29579the same messages. Often people think of posting bug reports to the
29580newsgroup instead of mailing them. This appears to work, but it has one
29581problem which can be crucial: a newsgroup posting often lacks a mail
29582path back to the sender. Thus, if we need to ask for more information,
29583we may be unable to reach you. For this reason, it is better to send
29584bug reports to the mailing list.
c16158bc
JM
29585@end ifset
29586@ifclear BUGURL_DEFAULT
29587In any event, we also recommend that you submit bug reports for
29588@value{GDBN} to @value{BUGURL}.
29589@end ifclear
29590@end ifset
c4555f82 29591
8e04817f
AC
29592The fundamental principle of reporting bugs usefully is this:
29593@strong{report all the facts}. If you are not sure whether to state a
29594fact or leave it out, state it!
c4555f82 29595
8e04817f
AC
29596Often people omit facts because they think they know what causes the
29597problem and assume that some details do not matter. Thus, you might
29598assume that the name of the variable you use in an example does not matter.
29599Well, probably it does not, but one cannot be sure. Perhaps the bug is a
29600stray memory reference which happens to fetch from the location where that
29601name is stored in memory; perhaps, if the name were different, the contents
29602of that location would fool the debugger into doing the right thing despite
29603the bug. Play it safe and give a specific, complete example. That is the
29604easiest thing for you to do, and the most helpful.
c4555f82 29605
8e04817f
AC
29606Keep in mind that the purpose of a bug report is to enable us to fix the
29607bug. It may be that the bug has been reported previously, but neither
29608you nor we can know that unless your bug report is complete and
29609self-contained.
c4555f82 29610
8e04817f
AC
29611Sometimes people give a few sketchy facts and ask, ``Does this ring a
29612bell?'' Those bug reports are useless, and we urge everyone to
29613@emph{refuse to respond to them} except to chide the sender to report
29614bugs properly.
29615
29616To enable us to fix the bug, you should include all these things:
c4555f82
SC
29617
29618@itemize @bullet
29619@item
8e04817f
AC
29620The version of @value{GDBN}. @value{GDBN} announces it if you start
29621with no arguments; you can also print it at any time using @code{show
29622version}.
c4555f82 29623
8e04817f
AC
29624Without this, we will not know whether there is any point in looking for
29625the bug in the current version of @value{GDBN}.
c4555f82
SC
29626
29627@item
8e04817f
AC
29628The type of machine you are using, and the operating system name and
29629version number.
c4555f82
SC
29630
29631@item
c1468174 29632What compiler (and its version) was used to compile @value{GDBN}---e.g.@:
8e04817f 29633``@value{GCC}--2.8.1''.
c4555f82
SC
29634
29635@item
8e04817f 29636What compiler (and its version) was used to compile the program you are
c1468174 29637debugging---e.g.@: ``@value{GCC}--2.8.1'', or ``HP92453-01 A.10.32.03 HP
3f94c067
BW
29638C Compiler''. For @value{NGCC}, you can say @kbd{@value{GCC} --version}
29639to get this information; for other compilers, see the documentation for
29640those compilers.
c4555f82 29641
8e04817f
AC
29642@item
29643The command arguments you gave the compiler to compile your example and
29644observe the bug. For example, did you use @samp{-O}? To guarantee
29645you will not omit something important, list them all. A copy of the
29646Makefile (or the output from make) is sufficient.
c4555f82 29647
8e04817f
AC
29648If we were to try to guess the arguments, we would probably guess wrong
29649and then we might not encounter the bug.
c4555f82 29650
8e04817f
AC
29651@item
29652A complete input script, and all necessary source files, that will
29653reproduce the bug.
c4555f82 29654
8e04817f
AC
29655@item
29656A description of what behavior you observe that you believe is
29657incorrect. For example, ``It gets a fatal signal.''
c4555f82 29658
8e04817f
AC
29659Of course, if the bug is that @value{GDBN} gets a fatal signal, then we
29660will certainly notice it. But if the bug is incorrect output, we might
29661not notice unless it is glaringly wrong. You might as well not give us
29662a chance to make a mistake.
c4555f82 29663
8e04817f
AC
29664Even if the problem you experience is a fatal signal, you should still
29665say so explicitly. Suppose something strange is going on, such as, your
29666copy of @value{GDBN} is out of synch, or you have encountered a bug in
29667the C library on your system. (This has happened!) Your copy might
29668crash and ours would not. If you told us to expect a crash, then when
29669ours fails to crash, we would know that the bug was not happening for
29670us. If you had not told us to expect a crash, then we would not be able
29671to draw any conclusion from our observations.
c4555f82 29672
e0c07bf0
MC
29673@pindex script
29674@cindex recording a session script
29675To collect all this information, you can use a session recording program
29676such as @command{script}, which is available on many Unix systems.
29677Just run your @value{GDBN} session inside @command{script} and then
29678include the @file{typescript} file with your bug report.
29679
29680Another way to record a @value{GDBN} session is to run @value{GDBN}
29681inside Emacs and then save the entire buffer to a file.
29682
8e04817f
AC
29683@item
29684If you wish to suggest changes to the @value{GDBN} source, send us context
29685diffs. If you even discuss something in the @value{GDBN} source, refer to
29686it by context, not by line number.
c4555f82 29687
8e04817f
AC
29688The line numbers in our development sources will not match those in your
29689sources. Your line numbers would convey no useful information to us.
c4555f82 29690
8e04817f 29691@end itemize
c4555f82 29692
8e04817f 29693Here are some things that are not necessary:
c4555f82 29694
8e04817f
AC
29695@itemize @bullet
29696@item
29697A description of the envelope of the bug.
c4555f82 29698
8e04817f
AC
29699Often people who encounter a bug spend a lot of time investigating
29700which changes to the input file will make the bug go away and which
29701changes will not affect it.
c4555f82 29702
8e04817f
AC
29703This is often time consuming and not very useful, because the way we
29704will find the bug is by running a single example under the debugger
29705with breakpoints, not by pure deduction from a series of examples.
29706We recommend that you save your time for something else.
c4555f82 29707
8e04817f
AC
29708Of course, if you can find a simpler example to report @emph{instead}
29709of the original one, that is a convenience for us. Errors in the
29710output will be easier to spot, running under the debugger will take
29711less time, and so on.
c4555f82 29712
8e04817f
AC
29713However, simplification is not vital; if you do not want to do this,
29714report the bug anyway and send us the entire test case you used.
c4555f82 29715
8e04817f
AC
29716@item
29717A patch for the bug.
c4555f82 29718
8e04817f
AC
29719A patch for the bug does help us if it is a good one. But do not omit
29720the necessary information, such as the test case, on the assumption that
29721a patch is all we need. We might see problems with your patch and decide
29722to fix the problem another way, or we might not understand it at all.
c4555f82 29723
8e04817f
AC
29724Sometimes with a program as complicated as @value{GDBN} it is very hard to
29725construct an example that will make the program follow a certain path
29726through the code. If you do not send us the example, we will not be able
29727to construct one, so we will not be able to verify that the bug is fixed.
c4555f82 29728
8e04817f
AC
29729And if we cannot understand what bug you are trying to fix, or why your
29730patch should be an improvement, we will not install it. A test case will
29731help us to understand.
c4555f82 29732
8e04817f
AC
29733@item
29734A guess about what the bug is or what it depends on.
c4555f82 29735
8e04817f
AC
29736Such guesses are usually wrong. Even we cannot guess right about such
29737things without first using the debugger to find the facts.
29738@end itemize
c4555f82 29739
8e04817f
AC
29740@c The readline documentation is distributed with the readline code
29741@c and consists of the two following files:
29742@c rluser.texinfo
29743@c inc-hist.texinfo
29744@c Use -I with makeinfo to point to the appropriate directory,
29745@c environment var TEXINPUTS with TeX.
5bdf8622 29746@include rluser.texi
8e04817f 29747@include inc-hist.texinfo
c4555f82 29748
c4555f82 29749
8e04817f
AC
29750@node Formatting Documentation
29751@appendix Formatting Documentation
c4555f82 29752
8e04817f
AC
29753@cindex @value{GDBN} reference card
29754@cindex reference card
29755The @value{GDBN} 4 release includes an already-formatted reference card, ready
29756for printing with PostScript or Ghostscript, in the @file{gdb}
29757subdirectory of the main source directory@footnote{In
29758@file{gdb-@value{GDBVN}/gdb/refcard.ps} of the version @value{GDBVN}
29759release.}. If you can use PostScript or Ghostscript with your printer,
29760you can print the reference card immediately with @file{refcard.ps}.
c4555f82 29761
8e04817f
AC
29762The release also includes the source for the reference card. You
29763can format it, using @TeX{}, by typing:
c4555f82 29764
474c8240 29765@smallexample
8e04817f 29766make refcard.dvi
474c8240 29767@end smallexample
c4555f82 29768
8e04817f
AC
29769The @value{GDBN} reference card is designed to print in @dfn{landscape}
29770mode on US ``letter'' size paper;
29771that is, on a sheet 11 inches wide by 8.5 inches
29772high. You will need to specify this form of printing as an option to
29773your @sc{dvi} output program.
c4555f82 29774
8e04817f 29775@cindex documentation
c4555f82 29776
8e04817f
AC
29777All the documentation for @value{GDBN} comes as part of the machine-readable
29778distribution. The documentation is written in Texinfo format, which is
29779a documentation system that uses a single source file to produce both
29780on-line information and a printed manual. You can use one of the Info
29781formatting commands to create the on-line version of the documentation
29782and @TeX{} (or @code{texi2roff}) to typeset the printed version.
c4555f82 29783
8e04817f
AC
29784@value{GDBN} includes an already formatted copy of the on-line Info
29785version of this manual in the @file{gdb} subdirectory. The main Info
29786file is @file{gdb-@value{GDBVN}/gdb/gdb.info}, and it refers to
29787subordinate files matching @samp{gdb.info*} in the same directory. If
29788necessary, you can print out these files, or read them with any editor;
29789but they are easier to read using the @code{info} subsystem in @sc{gnu}
29790Emacs or the standalone @code{info} program, available as part of the
29791@sc{gnu} Texinfo distribution.
c4555f82 29792
8e04817f
AC
29793If you want to format these Info files yourself, you need one of the
29794Info formatting programs, such as @code{texinfo-format-buffer} or
29795@code{makeinfo}.
c4555f82 29796
8e04817f
AC
29797If you have @code{makeinfo} installed, and are in the top level
29798@value{GDBN} source directory (@file{gdb-@value{GDBVN}}, in the case of
29799version @value{GDBVN}), you can make the Info file by typing:
c4555f82 29800
474c8240 29801@smallexample
8e04817f
AC
29802cd gdb
29803make gdb.info
474c8240 29804@end smallexample
c4555f82 29805
8e04817f
AC
29806If you want to typeset and print copies of this manual, you need @TeX{},
29807a program to print its @sc{dvi} output files, and @file{texinfo.tex}, the
29808Texinfo definitions file.
c4555f82 29809
8e04817f
AC
29810@TeX{} is a typesetting program; it does not print files directly, but
29811produces output files called @sc{dvi} files. To print a typeset
29812document, you need a program to print @sc{dvi} files. If your system
29813has @TeX{} installed, chances are it has such a program. The precise
29814command to use depends on your system; @kbd{lpr -d} is common; another
29815(for PostScript devices) is @kbd{dvips}. The @sc{dvi} print command may
29816require a file name without any extension or a @samp{.dvi} extension.
c4555f82 29817
8e04817f
AC
29818@TeX{} also requires a macro definitions file called
29819@file{texinfo.tex}. This file tells @TeX{} how to typeset a document
29820written in Texinfo format. On its own, @TeX{} cannot either read or
29821typeset a Texinfo file. @file{texinfo.tex} is distributed with GDB
29822and is located in the @file{gdb-@var{version-number}/texinfo}
29823directory.
c4555f82 29824
8e04817f 29825If you have @TeX{} and a @sc{dvi} printer program installed, you can
d3e8051b 29826typeset and print this manual. First switch to the @file{gdb}
8e04817f
AC
29827subdirectory of the main source directory (for example, to
29828@file{gdb-@value{GDBVN}/gdb}) and type:
c4555f82 29829
474c8240 29830@smallexample
8e04817f 29831make gdb.dvi
474c8240 29832@end smallexample
c4555f82 29833
8e04817f 29834Then give @file{gdb.dvi} to your @sc{dvi} printing program.
c4555f82 29835
8e04817f
AC
29836@node Installing GDB
29837@appendix Installing @value{GDBN}
8e04817f 29838@cindex installation
c4555f82 29839
7fa2210b
DJ
29840@menu
29841* Requirements:: Requirements for building @value{GDBN}
db2e3e2e 29842* Running Configure:: Invoking the @value{GDBN} @file{configure} script
7fa2210b
DJ
29843* Separate Objdir:: Compiling @value{GDBN} in another directory
29844* Config Names:: Specifying names for hosts and targets
29845* Configure Options:: Summary of options for configure
098b41a6 29846* System-wide configuration:: Having a system-wide init file
7fa2210b
DJ
29847@end menu
29848
29849@node Requirements
79a6e687 29850@section Requirements for Building @value{GDBN}
7fa2210b
DJ
29851@cindex building @value{GDBN}, requirements for
29852
29853Building @value{GDBN} requires various tools and packages to be available.
29854Other packages will be used only if they are found.
29855
79a6e687 29856@heading Tools/Packages Necessary for Building @value{GDBN}
7fa2210b
DJ
29857@table @asis
29858@item ISO C90 compiler
29859@value{GDBN} is written in ISO C90. It should be buildable with any
29860working C90 compiler, e.g.@: GCC.
29861
29862@end table
29863
79a6e687 29864@heading Tools/Packages Optional for Building @value{GDBN}
7fa2210b
DJ
29865@table @asis
29866@item Expat
123dc839 29867@anchor{Expat}
7fa2210b
DJ
29868@value{GDBN} can use the Expat XML parsing library. This library may be
29869included with your operating system distribution; if it is not, you
29870can get the latest version from @url{http://expat.sourceforge.net}.
db2e3e2e 29871The @file{configure} script will search for this library in several
7fa2210b
DJ
29872standard locations; if it is installed in an unusual path, you can
29873use the @option{--with-libexpat-prefix} option to specify its location.
29874
9cceb671
DJ
29875Expat is used for:
29876
29877@itemize @bullet
29878@item
29879Remote protocol memory maps (@pxref{Memory Map Format})
29880@item
29881Target descriptions (@pxref{Target Descriptions})
29882@item
29883Remote shared library lists (@pxref{Library List Format})
29884@item
29885MS-Windows shared libraries (@pxref{Shared Libraries})
29886@end itemize
7fa2210b 29887
31fffb02
CS
29888@item zlib
29889@cindex compressed debug sections
29890@value{GDBN} will use the @samp{zlib} library, if available, to read
29891compressed debug sections. Some linkers, such as GNU gold, are capable
29892of producing binaries with compressed debug sections. If @value{GDBN}
29893is compiled with @samp{zlib}, it will be able to read the debug
29894information in such binaries.
29895
29896The @samp{zlib} library is likely included with your operating system
29897distribution; if it is not, you can get the latest version from
29898@url{http://zlib.net}.
29899
6c7a06a3
TT
29900@item iconv
29901@value{GDBN}'s features related to character sets (@pxref{Character
29902Sets}) require a functioning @code{iconv} implementation. If you are
29903on a GNU system, then this is provided by the GNU C Library. Some
29904other systems also provide a working @code{iconv}.
29905
29906On systems with @code{iconv}, you can install GNU Libiconv. If you
29907have previously installed Libiconv, you can use the
29908@option{--with-libiconv-prefix} option to configure.
29909
29910@value{GDBN}'s top-level @file{configure} and @file{Makefile} will
29911arrange to build Libiconv if a directory named @file{libiconv} appears
29912in the top-most source directory. If Libiconv is built this way, and
29913if the operating system does not provide a suitable @code{iconv}
29914implementation, then the just-built library will automatically be used
29915by @value{GDBN}. One easy way to set this up is to download GNU
29916Libiconv, unpack it, and then rename the directory holding the
29917Libiconv source code to @samp{libiconv}.
7fa2210b
DJ
29918@end table
29919
29920@node Running Configure
db2e3e2e 29921@section Invoking the @value{GDBN} @file{configure} Script
7fa2210b 29922@cindex configuring @value{GDBN}
db2e3e2e 29923@value{GDBN} comes with a @file{configure} script that automates the process
8e04817f
AC
29924of preparing @value{GDBN} for installation; you can then use @code{make} to
29925build the @code{gdb} program.
29926@iftex
29927@c irrelevant in info file; it's as current as the code it lives with.
29928@footnote{If you have a more recent version of @value{GDBN} than @value{GDBVN},
29929look at the @file{README} file in the sources; we may have improved the
29930installation procedures since publishing this manual.}
29931@end iftex
c4555f82 29932
8e04817f
AC
29933The @value{GDBN} distribution includes all the source code you need for
29934@value{GDBN} in a single directory, whose name is usually composed by
29935appending the version number to @samp{gdb}.
c4555f82 29936
8e04817f
AC
29937For example, the @value{GDBN} version @value{GDBVN} distribution is in the
29938@file{gdb-@value{GDBVN}} directory. That directory contains:
c4555f82 29939
8e04817f
AC
29940@table @code
29941@item gdb-@value{GDBVN}/configure @r{(and supporting files)}
29942script for configuring @value{GDBN} and all its supporting libraries
c4555f82 29943
8e04817f
AC
29944@item gdb-@value{GDBVN}/gdb
29945the source specific to @value{GDBN} itself
c4555f82 29946
8e04817f
AC
29947@item gdb-@value{GDBVN}/bfd
29948source for the Binary File Descriptor library
c906108c 29949
8e04817f
AC
29950@item gdb-@value{GDBVN}/include
29951@sc{gnu} include files
c906108c 29952
8e04817f
AC
29953@item gdb-@value{GDBVN}/libiberty
29954source for the @samp{-liberty} free software library
c906108c 29955
8e04817f
AC
29956@item gdb-@value{GDBVN}/opcodes
29957source for the library of opcode tables and disassemblers
c906108c 29958
8e04817f
AC
29959@item gdb-@value{GDBVN}/readline
29960source for the @sc{gnu} command-line interface
c906108c 29961
8e04817f
AC
29962@item gdb-@value{GDBVN}/glob
29963source for the @sc{gnu} filename pattern-matching subroutine
c906108c 29964
8e04817f
AC
29965@item gdb-@value{GDBVN}/mmalloc
29966source for the @sc{gnu} memory-mapped malloc package
29967@end table
c906108c 29968
db2e3e2e 29969The simplest way to configure and build @value{GDBN} is to run @file{configure}
8e04817f
AC
29970from the @file{gdb-@var{version-number}} source directory, which in
29971this example is the @file{gdb-@value{GDBVN}} directory.
c906108c 29972
8e04817f 29973First switch to the @file{gdb-@var{version-number}} source directory
db2e3e2e 29974if you are not already in it; then run @file{configure}. Pass the
8e04817f
AC
29975identifier for the platform on which @value{GDBN} will run as an
29976argument.
c906108c 29977
8e04817f 29978For example:
c906108c 29979
474c8240 29980@smallexample
8e04817f
AC
29981cd gdb-@value{GDBVN}
29982./configure @var{host}
29983make
474c8240 29984@end smallexample
c906108c 29985
8e04817f
AC
29986@noindent
29987where @var{host} is an identifier such as @samp{sun4} or
29988@samp{decstation}, that identifies the platform where @value{GDBN} will run.
db2e3e2e 29989(You can often leave off @var{host}; @file{configure} tries to guess the
8e04817f 29990correct value by examining your system.)
c906108c 29991
8e04817f
AC
29992Running @samp{configure @var{host}} and then running @code{make} builds the
29993@file{bfd}, @file{readline}, @file{mmalloc}, and @file{libiberty}
29994libraries, then @code{gdb} itself. The configured source files, and the
29995binaries, are left in the corresponding source directories.
c906108c 29996
8e04817f 29997@need 750
db2e3e2e 29998@file{configure} is a Bourne-shell (@code{/bin/sh}) script; if your
8e04817f
AC
29999system does not recognize this automatically when you run a different
30000shell, you may need to run @code{sh} on it explicitly:
c906108c 30001
474c8240 30002@smallexample
8e04817f 30003sh configure @var{host}
474c8240 30004@end smallexample
c906108c 30005
db2e3e2e 30006If you run @file{configure} from a directory that contains source
8e04817f 30007directories for multiple libraries or programs, such as the
db2e3e2e
BW
30008@file{gdb-@value{GDBVN}} source directory for version @value{GDBVN},
30009@file{configure}
8e04817f
AC
30010creates configuration files for every directory level underneath (unless
30011you tell it not to, with the @samp{--norecursion} option).
30012
db2e3e2e 30013You should run the @file{configure} script from the top directory in the
94e91d6d 30014source tree, the @file{gdb-@var{version-number}} directory. If you run
db2e3e2e 30015@file{configure} from one of the subdirectories, you will configure only
94e91d6d 30016that subdirectory. That is usually not what you want. In particular,
db2e3e2e 30017if you run the first @file{configure} from the @file{gdb} subdirectory
94e91d6d
MC
30018of the @file{gdb-@var{version-number}} directory, you will omit the
30019configuration of @file{bfd}, @file{readline}, and other sibling
30020directories of the @file{gdb} subdirectory. This leads to build errors
30021about missing include files such as @file{bfd/bfd.h}.
c906108c 30022
8e04817f
AC
30023You can install @code{@value{GDBP}} anywhere; it has no hardwired paths.
30024However, you should make sure that the shell on your path (named by
30025the @samp{SHELL} environment variable) is publicly readable. Remember
30026that @value{GDBN} uses the shell to start your program---some systems refuse to
30027let @value{GDBN} debug child processes whose programs are not readable.
c906108c 30028
8e04817f 30029@node Separate Objdir
79a6e687 30030@section Compiling @value{GDBN} in Another Directory
c906108c 30031
8e04817f
AC
30032If you want to run @value{GDBN} versions for several host or target machines,
30033you need a different @code{gdb} compiled for each combination of
db2e3e2e 30034host and target. @file{configure} is designed to make this easy by
8e04817f
AC
30035allowing you to generate each configuration in a separate subdirectory,
30036rather than in the source directory. If your @code{make} program
30037handles the @samp{VPATH} feature (@sc{gnu} @code{make} does), running
30038@code{make} in each of these directories builds the @code{gdb}
30039program specified there.
c906108c 30040
db2e3e2e 30041To build @code{gdb} in a separate directory, run @file{configure}
8e04817f 30042with the @samp{--srcdir} option to specify where to find the source.
db2e3e2e
BW
30043(You also need to specify a path to find @file{configure}
30044itself from your working directory. If the path to @file{configure}
8e04817f
AC
30045would be the same as the argument to @samp{--srcdir}, you can leave out
30046the @samp{--srcdir} option; it is assumed.)
c906108c 30047
8e04817f
AC
30048For example, with version @value{GDBVN}, you can build @value{GDBN} in a
30049separate directory for a Sun 4 like this:
c906108c 30050
474c8240 30051@smallexample
8e04817f
AC
30052@group
30053cd gdb-@value{GDBVN}
30054mkdir ../gdb-sun4
30055cd ../gdb-sun4
30056../gdb-@value{GDBVN}/configure sun4
30057make
30058@end group
474c8240 30059@end smallexample
c906108c 30060
db2e3e2e 30061When @file{configure} builds a configuration using a remote source
8e04817f
AC
30062directory, it creates a tree for the binaries with the same structure
30063(and using the same names) as the tree under the source directory. In
30064the example, you'd find the Sun 4 library @file{libiberty.a} in the
30065directory @file{gdb-sun4/libiberty}, and @value{GDBN} itself in
30066@file{gdb-sun4/gdb}.
c906108c 30067
94e91d6d
MC
30068Make sure that your path to the @file{configure} script has just one
30069instance of @file{gdb} in it. If your path to @file{configure} looks
30070like @file{../gdb-@value{GDBVN}/gdb/configure}, you are configuring only
30071one subdirectory of @value{GDBN}, not the whole package. This leads to
30072build errors about missing include files such as @file{bfd/bfd.h}.
30073
8e04817f
AC
30074One popular reason to build several @value{GDBN} configurations in separate
30075directories is to configure @value{GDBN} for cross-compiling (where
30076@value{GDBN} runs on one machine---the @dfn{host}---while debugging
30077programs that run on another machine---the @dfn{target}).
30078You specify a cross-debugging target by
db2e3e2e 30079giving the @samp{--target=@var{target}} option to @file{configure}.
c906108c 30080
8e04817f
AC
30081When you run @code{make} to build a program or library, you must run
30082it in a configured directory---whatever directory you were in when you
db2e3e2e 30083called @file{configure} (or one of its subdirectories).
c906108c 30084
db2e3e2e 30085The @code{Makefile} that @file{configure} generates in each source
8e04817f
AC
30086directory also runs recursively. If you type @code{make} in a source
30087directory such as @file{gdb-@value{GDBVN}} (or in a separate configured
30088directory configured with @samp{--srcdir=@var{dirname}/gdb-@value{GDBVN}}), you
30089will build all the required libraries, and then build GDB.
c906108c 30090
8e04817f
AC
30091When you have multiple hosts or targets configured in separate
30092directories, you can run @code{make} on them in parallel (for example,
30093if they are NFS-mounted on each of the hosts); they will not interfere
30094with each other.
c906108c 30095
8e04817f 30096@node Config Names
79a6e687 30097@section Specifying Names for Hosts and Targets
c906108c 30098
db2e3e2e 30099The specifications used for hosts and targets in the @file{configure}
8e04817f
AC
30100script are based on a three-part naming scheme, but some short predefined
30101aliases are also supported. The full naming scheme encodes three pieces
30102of information in the following pattern:
c906108c 30103
474c8240 30104@smallexample
8e04817f 30105@var{architecture}-@var{vendor}-@var{os}
474c8240 30106@end smallexample
c906108c 30107
8e04817f
AC
30108For example, you can use the alias @code{sun4} as a @var{host} argument,
30109or as the value for @var{target} in a @code{--target=@var{target}}
30110option. The equivalent full name is @samp{sparc-sun-sunos4}.
c906108c 30111
db2e3e2e 30112The @file{configure} script accompanying @value{GDBN} does not provide
8e04817f 30113any query facility to list all supported host and target names or
db2e3e2e 30114aliases. @file{configure} calls the Bourne shell script
8e04817f
AC
30115@code{config.sub} to map abbreviations to full names; you can read the
30116script, if you wish, or you can use it to test your guesses on
30117abbreviations---for example:
c906108c 30118
8e04817f
AC
30119@smallexample
30120% sh config.sub i386-linux
30121i386-pc-linux-gnu
30122% sh config.sub alpha-linux
30123alpha-unknown-linux-gnu
30124% sh config.sub hp9k700
30125hppa1.1-hp-hpux
30126% sh config.sub sun4
30127sparc-sun-sunos4.1.1
30128% sh config.sub sun3
30129m68k-sun-sunos4.1.1
30130% sh config.sub i986v
30131Invalid configuration `i986v': machine `i986v' not recognized
30132@end smallexample
c906108c 30133
8e04817f
AC
30134@noindent
30135@code{config.sub} is also distributed in the @value{GDBN} source
30136directory (@file{gdb-@value{GDBVN}}, for version @value{GDBVN}).
d700128c 30137
8e04817f 30138@node Configure Options
db2e3e2e 30139@section @file{configure} Options
c906108c 30140
db2e3e2e
BW
30141Here is a summary of the @file{configure} options and arguments that
30142are most often useful for building @value{GDBN}. @file{configure} also has
8e04817f 30143several other options not listed here. @inforef{What Configure
db2e3e2e 30144Does,,configure.info}, for a full explanation of @file{configure}.
c906108c 30145
474c8240 30146@smallexample
8e04817f
AC
30147configure @r{[}--help@r{]}
30148 @r{[}--prefix=@var{dir}@r{]}
30149 @r{[}--exec-prefix=@var{dir}@r{]}
30150 @r{[}--srcdir=@var{dirname}@r{]}
30151 @r{[}--norecursion@r{]} @r{[}--rm@r{]}
30152 @r{[}--target=@var{target}@r{]}
30153 @var{host}
474c8240 30154@end smallexample
c906108c 30155
8e04817f
AC
30156@noindent
30157You may introduce options with a single @samp{-} rather than
30158@samp{--} if you prefer; but you may abbreviate option names if you use
30159@samp{--}.
c906108c 30160
8e04817f
AC
30161@table @code
30162@item --help
db2e3e2e 30163Display a quick summary of how to invoke @file{configure}.
c906108c 30164
8e04817f
AC
30165@item --prefix=@var{dir}
30166Configure the source to install programs and files under directory
30167@file{@var{dir}}.
c906108c 30168
8e04817f
AC
30169@item --exec-prefix=@var{dir}
30170Configure the source to install programs under directory
30171@file{@var{dir}}.
c906108c 30172
8e04817f
AC
30173@c avoid splitting the warning from the explanation:
30174@need 2000
30175@item --srcdir=@var{dirname}
30176@strong{Warning: using this option requires @sc{gnu} @code{make}, or another
30177@code{make} that implements the @code{VPATH} feature.}@*
30178Use this option to make configurations in directories separate from the
30179@value{GDBN} source directories. Among other things, you can use this to
30180build (or maintain) several configurations simultaneously, in separate
db2e3e2e 30181directories. @file{configure} writes configuration-specific files in
8e04817f 30182the current directory, but arranges for them to use the source in the
db2e3e2e 30183directory @var{dirname}. @file{configure} creates directories under
8e04817f
AC
30184the working directory in parallel to the source directories below
30185@var{dirname}.
c906108c 30186
8e04817f 30187@item --norecursion
db2e3e2e 30188Configure only the directory level where @file{configure} is executed; do not
8e04817f 30189propagate configuration to subdirectories.
c906108c 30190
8e04817f
AC
30191@item --target=@var{target}
30192Configure @value{GDBN} for cross-debugging programs running on the specified
30193@var{target}. Without this option, @value{GDBN} is configured to debug
30194programs that run on the same machine (@var{host}) as @value{GDBN} itself.
c906108c 30195
8e04817f 30196There is no convenient way to generate a list of all available targets.
c906108c 30197
8e04817f
AC
30198@item @var{host} @dots{}
30199Configure @value{GDBN} to run on the specified @var{host}.
c906108c 30200
8e04817f
AC
30201There is no convenient way to generate a list of all available hosts.
30202@end table
c906108c 30203
8e04817f
AC
30204There are many other options available as well, but they are generally
30205needed for special purposes only.
c906108c 30206
098b41a6
JG
30207@node System-wide configuration
30208@section System-wide configuration and settings
30209@cindex system-wide init file
30210
30211@value{GDBN} can be configured to have a system-wide init file;
30212this file will be read and executed at startup (@pxref{Startup, , What
30213@value{GDBN} does during startup}).
30214
30215Here is the corresponding configure option:
30216
30217@table @code
30218@item --with-system-gdbinit=@var{file}
30219Specify that the default location of the system-wide init file is
30220@var{file}.
30221@end table
30222
30223If @value{GDBN} has been configured with the option @option{--prefix=$prefix},
30224it may be subject to relocation. Two possible cases:
30225
30226@itemize @bullet
30227@item
30228If the default location of this init file contains @file{$prefix},
30229it will be subject to relocation. Suppose that the configure options
30230are @option{--prefix=$prefix --with-system-gdbinit=$prefix/etc/gdbinit};
30231if @value{GDBN} is moved from @file{$prefix} to @file{$install}, the system
30232init file is looked for as @file{$install/etc/gdbinit} instead of
30233@file{$prefix/etc/gdbinit}.
30234
30235@item
30236By contrast, if the default location does not contain the prefix,
30237it will not be relocated. E.g.@: if @value{GDBN} has been configured with
30238@option{--prefix=/usr/local --with-system-gdbinit=/usr/share/gdb/gdbinit},
30239then @value{GDBN} will always look for @file{/usr/share/gdb/gdbinit},
30240wherever @value{GDBN} is installed.
30241@end itemize
30242
8e04817f
AC
30243@node Maintenance Commands
30244@appendix Maintenance Commands
30245@cindex maintenance commands
30246@cindex internal commands
c906108c 30247
8e04817f 30248In addition to commands intended for @value{GDBN} users, @value{GDBN}
09d4efe1
EZ
30249includes a number of commands intended for @value{GDBN} developers,
30250that are not documented elsewhere in this manual. These commands are
da316a69
EZ
30251provided here for reference. (For commands that turn on debugging
30252messages, see @ref{Debugging Output}.)
c906108c 30253
8e04817f 30254@table @code
09d4efe1 30255@kindex maint agent
782b2b07 30256@kindex maint agent-eval
09d4efe1 30257@item maint agent @var{expression}
782b2b07 30258@itemx maint agent-eval @var{expression}
09d4efe1
EZ
30259Translate the given @var{expression} into remote agent bytecodes.
30260This command is useful for debugging the Agent Expression mechanism
782b2b07
SS
30261(@pxref{Agent Expressions}). The @samp{agent} version produces an
30262expression useful for data collection, such as by tracepoints, while
30263@samp{maint agent-eval} produces an expression that evaluates directly
30264to a result. For instance, a collection expression for @code{globa +
30265globb} will include bytecodes to record four bytes of memory at each
30266of the addresses of @code{globa} and @code{globb}, while discarding
30267the result of the addition, while an evaluation expression will do the
30268addition and return the sum.
09d4efe1 30269
8e04817f
AC
30270@kindex maint info breakpoints
30271@item @anchor{maint info breakpoints}maint info breakpoints
30272Using the same format as @samp{info breakpoints}, display both the
30273breakpoints you've set explicitly, and those @value{GDBN} is using for
30274internal purposes. Internal breakpoints are shown with negative
30275breakpoint numbers. The type column identifies what kind of breakpoint
30276is shown:
c906108c 30277
8e04817f
AC
30278@table @code
30279@item breakpoint
30280Normal, explicitly set breakpoint.
c906108c 30281
8e04817f
AC
30282@item watchpoint
30283Normal, explicitly set watchpoint.
c906108c 30284
8e04817f
AC
30285@item longjmp
30286Internal breakpoint, used to handle correctly stepping through
30287@code{longjmp} calls.
c906108c 30288
8e04817f
AC
30289@item longjmp resume
30290Internal breakpoint at the target of a @code{longjmp}.
c906108c 30291
8e04817f
AC
30292@item until
30293Temporary internal breakpoint used by the @value{GDBN} @code{until} command.
c906108c 30294
8e04817f
AC
30295@item finish
30296Temporary internal breakpoint used by the @value{GDBN} @code{finish} command.
c906108c 30297
8e04817f
AC
30298@item shlib events
30299Shared library events.
c906108c 30300
8e04817f 30301@end table
c906108c 30302
fff08868
HZ
30303@kindex set displaced-stepping
30304@kindex show displaced-stepping
237fc4c9
PA
30305@cindex displaced stepping support
30306@cindex out-of-line single-stepping
fff08868
HZ
30307@item set displaced-stepping
30308@itemx show displaced-stepping
237fc4c9 30309Control whether or not @value{GDBN} will do @dfn{displaced stepping}
fff08868
HZ
30310if the target supports it. Displaced stepping is a way to single-step
30311over breakpoints without removing them from the inferior, by executing
30312an out-of-line copy of the instruction that was originally at the
30313breakpoint location. It is also known as out-of-line single-stepping.
30314
30315@table @code
30316@item set displaced-stepping on
30317If the target architecture supports it, @value{GDBN} will use
30318displaced stepping to step over breakpoints.
30319
30320@item set displaced-stepping off
30321@value{GDBN} will not use displaced stepping to step over breakpoints,
30322even if such is supported by the target architecture.
30323
30324@cindex non-stop mode, and @samp{set displaced-stepping}
30325@item set displaced-stepping auto
30326This is the default mode. @value{GDBN} will use displaced stepping
30327only if non-stop mode is active (@pxref{Non-Stop Mode}) and the target
30328architecture supports displaced stepping.
30329@end table
237fc4c9 30330
09d4efe1
EZ
30331@kindex maint check-symtabs
30332@item maint check-symtabs
30333Check the consistency of psymtabs and symtabs.
30334
30335@kindex maint cplus first_component
30336@item maint cplus first_component @var{name}
30337Print the first C@t{++} class/namespace component of @var{name}.
30338
30339@kindex maint cplus namespace
30340@item maint cplus namespace
30341Print the list of possible C@t{++} namespaces.
30342
30343@kindex maint demangle
30344@item maint demangle @var{name}
d3e8051b 30345Demangle a C@t{++} or Objective-C mangled @var{name}.
09d4efe1
EZ
30346
30347@kindex maint deprecate
30348@kindex maint undeprecate
30349@cindex deprecated commands
30350@item maint deprecate @var{command} @r{[}@var{replacement}@r{]}
30351@itemx maint undeprecate @var{command}
30352Deprecate or undeprecate the named @var{command}. Deprecated commands
30353cause @value{GDBN} to issue a warning when you use them. The optional
30354argument @var{replacement} says which newer command should be used in
30355favor of the deprecated one; if it is given, @value{GDBN} will mention
30356the replacement as part of the warning.
30357
30358@kindex maint dump-me
30359@item maint dump-me
721c2651 30360@cindex @code{SIGQUIT} signal, dump core of @value{GDBN}
09d4efe1 30361Cause a fatal signal in the debugger and force it to dump its core.
721c2651
EZ
30362This is supported only on systems which support aborting a program
30363with the @code{SIGQUIT} signal.
09d4efe1 30364
8d30a00d
AC
30365@kindex maint internal-error
30366@kindex maint internal-warning
09d4efe1
EZ
30367@item maint internal-error @r{[}@var{message-text}@r{]}
30368@itemx maint internal-warning @r{[}@var{message-text}@r{]}
8d30a00d
AC
30369Cause @value{GDBN} to call the internal function @code{internal_error}
30370or @code{internal_warning} and hence behave as though an internal error
30371or internal warning has been detected. In addition to reporting the
30372internal problem, these functions give the user the opportunity to
30373either quit @value{GDBN} or create a core file of the current
30374@value{GDBN} session.
30375
09d4efe1
EZ
30376These commands take an optional parameter @var{message-text} that is
30377used as the text of the error or warning message.
30378
d3e8051b 30379Here's an example of using @code{internal-error}:
09d4efe1 30380
8d30a00d 30381@smallexample
f7dc1244 30382(@value{GDBP}) @kbd{maint internal-error testing, 1, 2}
8d30a00d
AC
30383@dots{}/maint.c:121: internal-error: testing, 1, 2
30384A problem internal to GDB has been detected. Further
30385debugging may prove unreliable.
30386Quit this debugging session? (y or n) @kbd{n}
30387Create a core file? (y or n) @kbd{n}
f7dc1244 30388(@value{GDBP})
8d30a00d
AC
30389@end smallexample
30390
3c16cced
PA
30391@cindex @value{GDBN} internal error
30392@cindex internal errors, control of @value{GDBN} behavior
30393
30394@kindex maint set internal-error
30395@kindex maint show internal-error
30396@kindex maint set internal-warning
30397@kindex maint show internal-warning
30398@item maint set internal-error @var{action} [ask|yes|no]
30399@itemx maint show internal-error @var{action}
30400@itemx maint set internal-warning @var{action} [ask|yes|no]
30401@itemx maint show internal-warning @var{action}
30402When @value{GDBN} reports an internal problem (error or warning) it
30403gives the user the opportunity to both quit @value{GDBN} and create a
30404core file of the current @value{GDBN} session. These commands let you
30405override the default behaviour for each particular @var{action},
30406described in the table below.
30407
30408@table @samp
30409@item quit
30410You can specify that @value{GDBN} should always (yes) or never (no)
30411quit. The default is to ask the user what to do.
30412
30413@item corefile
30414You can specify that @value{GDBN} should always (yes) or never (no)
30415create a core file. The default is to ask the user what to do.
30416@end table
30417
09d4efe1
EZ
30418@kindex maint packet
30419@item maint packet @var{text}
30420If @value{GDBN} is talking to an inferior via the serial protocol,
30421then this command sends the string @var{text} to the inferior, and
30422displays the response packet. @value{GDBN} supplies the initial
30423@samp{$} character, the terminating @samp{#} character, and the
30424checksum.
30425
30426@kindex maint print architecture
30427@item maint print architecture @r{[}@var{file}@r{]}
30428Print the entire architecture configuration. The optional argument
30429@var{file} names the file where the output goes.
8d30a00d 30430
81adfced
DJ
30431@kindex maint print c-tdesc
30432@item maint print c-tdesc
30433Print the current target description (@pxref{Target Descriptions}) as
30434a C source file. The created source file can be used in @value{GDBN}
30435when an XML parser is not available to parse the description.
30436
00905d52
AC
30437@kindex maint print dummy-frames
30438@item maint print dummy-frames
00905d52
AC
30439Prints the contents of @value{GDBN}'s internal dummy-frame stack.
30440
30441@smallexample
f7dc1244 30442(@value{GDBP}) @kbd{b add}
00905d52 30443@dots{}
f7dc1244 30444(@value{GDBP}) @kbd{print add(2,3)}
00905d52
AC
30445Breakpoint 2, add (a=2, b=3) at @dots{}
3044658 return (a + b);
30447The program being debugged stopped while in a function called from GDB.
30448@dots{}
f7dc1244 30449(@value{GDBP}) @kbd{maint print dummy-frames}
00905d52
AC
304500x1a57c80: pc=0x01014068 fp=0x0200bddc sp=0x0200bdd6
30451 top=0x0200bdd4 id=@{stack=0x200bddc,code=0x101405c@}
30452 call_lo=0x01014000 call_hi=0x01014001
f7dc1244 30453(@value{GDBP})
00905d52
AC
30454@end smallexample
30455
30456Takes an optional file parameter.
30457
0680b120
AC
30458@kindex maint print registers
30459@kindex maint print raw-registers
30460@kindex maint print cooked-registers
617073a9 30461@kindex maint print register-groups
09d4efe1
EZ
30462@item maint print registers @r{[}@var{file}@r{]}
30463@itemx maint print raw-registers @r{[}@var{file}@r{]}
30464@itemx maint print cooked-registers @r{[}@var{file}@r{]}
30465@itemx maint print register-groups @r{[}@var{file}@r{]}
0680b120
AC
30466Print @value{GDBN}'s internal register data structures.
30467
617073a9
AC
30468The command @code{maint print raw-registers} includes the contents of
30469the raw register cache; the command @code{maint print cooked-registers}
5c5dcc1b
L
30470includes the (cooked) value of all registers, including registers which
30471aren't available on the target nor visible to user; and the
30472command @code{maint print register-groups} includes the groups that each
617073a9
AC
30473register is a member of. @xref{Registers,, Registers, gdbint,
30474@value{GDBN} Internals}.
0680b120 30475
09d4efe1
EZ
30476These commands take an optional parameter, a file name to which to
30477write the information.
0680b120 30478
617073a9 30479@kindex maint print reggroups
09d4efe1
EZ
30480@item maint print reggroups @r{[}@var{file}@r{]}
30481Print @value{GDBN}'s internal register group data structures. The
30482optional argument @var{file} tells to what file to write the
30483information.
617073a9 30484
09d4efe1 30485The register groups info looks like this:
617073a9
AC
30486
30487@smallexample
f7dc1244 30488(@value{GDBP}) @kbd{maint print reggroups}
b383017d
RM
30489 Group Type
30490 general user
30491 float user
30492 all user
30493 vector user
30494 system user
30495 save internal
30496 restore internal
617073a9
AC
30497@end smallexample
30498
09d4efe1
EZ
30499@kindex flushregs
30500@item flushregs
30501This command forces @value{GDBN} to flush its internal register cache.
30502
30503@kindex maint print objfiles
30504@cindex info for known object files
30505@item maint print objfiles
30506Print a dump of all known object files. For each object file, this
30507command prints its name, address in memory, and all of its psymtabs
30508and symtabs.
30509
8a1ea21f
DE
30510@kindex maint print section-scripts
30511@cindex info for known .debug_gdb_scripts-loaded scripts
30512@item maint print section-scripts [@var{regexp}]
30513Print a dump of scripts specified in the @code{.debug_gdb_section} section.
30514If @var{regexp} is specified, only print scripts loaded by object files
30515matching @var{regexp}.
30516For each script, this command prints its name as specified in the objfile,
30517and the full path if known.
30518@xref{.debug_gdb_scripts section}.
30519
09d4efe1
EZ
30520@kindex maint print statistics
30521@cindex bcache statistics
30522@item maint print statistics
30523This command prints, for each object file in the program, various data
30524about that object file followed by the byte cache (@dfn{bcache})
30525statistics for the object file. The objfile data includes the number
d3e8051b 30526of minimal, partial, full, and stabs symbols, the number of types
09d4efe1
EZ
30527defined by the objfile, the number of as yet unexpanded psym tables,
30528the number of line tables and string tables, and the amount of memory
30529used by the various tables. The bcache statistics include the counts,
30530sizes, and counts of duplicates of all and unique objects, max,
30531average, and median entry size, total memory used and its overhead and
30532savings, and various measures of the hash table size and chain
30533lengths.
30534
c7ba131e
JB
30535@kindex maint print target-stack
30536@cindex target stack description
30537@item maint print target-stack
30538A @dfn{target} is an interface between the debugger and a particular
30539kind of file or process. Targets can be stacked in @dfn{strata},
30540so that more than one target can potentially respond to a request.
30541In particular, memory accesses will walk down the stack of targets
30542until they find a target that is interested in handling that particular
30543address.
30544
30545This command prints a short description of each layer that was pushed on
30546the @dfn{target stack}, starting from the top layer down to the bottom one.
30547
09d4efe1
EZ
30548@kindex maint print type
30549@cindex type chain of a data type
30550@item maint print type @var{expr}
30551Print the type chain for a type specified by @var{expr}. The argument
30552can be either a type name or a symbol. If it is a symbol, the type of
30553that symbol is described. The type chain produced by this command is
30554a recursive definition of the data type as stored in @value{GDBN}'s
30555data structures, including its flags and contained types.
30556
9eae7c52
TT
30557@kindex maint set dwarf2 always-disassemble
30558@kindex maint show dwarf2 always-disassemble
30559@item maint set dwarf2 always-disassemble
30560@item maint show dwarf2 always-disassemble
30561Control the behavior of @code{info address} when using DWARF debugging
30562information.
30563
30564The default is @code{off}, which means that @value{GDBN} should try to
30565describe a variable's location in an easily readable format. When
30566@code{on}, @value{GDBN} will instead display the DWARF location
30567expression in an assembly-like format. Note that some locations are
30568too complex for @value{GDBN} to describe simply; in this case you will
30569always see the disassembly form.
30570
30571Here is an example of the resulting disassembly:
30572
30573@smallexample
30574(gdb) info addr argc
30575Symbol "argc" is a complex DWARF expression:
30576 1: DW_OP_fbreg 0
30577@end smallexample
30578
30579For more information on these expressions, see
30580@uref{http://www.dwarfstd.org/, the DWARF standard}.
30581
09d4efe1
EZ
30582@kindex maint set dwarf2 max-cache-age
30583@kindex maint show dwarf2 max-cache-age
30584@item maint set dwarf2 max-cache-age
30585@itemx maint show dwarf2 max-cache-age
30586Control the DWARF 2 compilation unit cache.
30587
30588@cindex DWARF 2 compilation units cache
30589In object files with inter-compilation-unit references, such as those
30590produced by the GCC option @samp{-feliminate-dwarf2-dups}, the DWARF 2
30591reader needs to frequently refer to previously read compilation units.
30592This setting controls how long a compilation unit will remain in the
30593cache if it is not referenced. A higher limit means that cached
30594compilation units will be stored in memory longer, and more total
30595memory will be used. Setting it to zero disables caching, which will
30596slow down @value{GDBN} startup, but reduce memory consumption.
30597
e7ba9c65
DJ
30598@kindex maint set profile
30599@kindex maint show profile
30600@cindex profiling GDB
30601@item maint set profile
30602@itemx maint show profile
30603Control profiling of @value{GDBN}.
30604
30605Profiling will be disabled until you use the @samp{maint set profile}
30606command to enable it. When you enable profiling, the system will begin
30607collecting timing and execution count data; when you disable profiling or
30608exit @value{GDBN}, the results will be written to a log file. Remember that
30609if you use profiling, @value{GDBN} will overwrite the profiling log file
30610(often called @file{gmon.out}). If you have a record of important profiling
30611data in a @file{gmon.out} file, be sure to move it to a safe location.
30612
30613Configuring with @samp{--enable-profiling} arranges for @value{GDBN} to be
b383017d 30614compiled with the @samp{-pg} compiler option.
e7ba9c65 30615
cbe54154
PA
30616@kindex maint set show-debug-regs
30617@kindex maint show show-debug-regs
eac35c4e 30618@cindex hardware debug registers
cbe54154
PA
30619@item maint set show-debug-regs
30620@itemx maint show show-debug-regs
eac35c4e 30621Control whether to show variables that mirror the hardware debug
09d4efe1 30622registers. Use @code{ON} to enable, @code{OFF} to disable. If
3f94c067 30623enabled, the debug registers values are shown when @value{GDBN} inserts or
09d4efe1
EZ
30624removes a hardware breakpoint or watchpoint, and when the inferior
30625triggers a hardware-assisted breakpoint or watchpoint.
30626
711e434b
PM
30627@kindex maint set show-all-tib
30628@kindex maint show show-all-tib
30629@item maint set show-all-tib
30630@itemx maint show show-all-tib
30631Control whether to show all non zero areas within a 1k block starting
30632at thread local base, when using the @samp{info w32 thread-information-block}
30633command.
30634
09d4efe1
EZ
30635@kindex maint space
30636@cindex memory used by commands
30637@item maint space
30638Control whether to display memory usage for each command. If set to a
30639nonzero value, @value{GDBN} will display how much memory each command
30640took, following the command's own output. This can also be requested
30641by invoking @value{GDBN} with the @option{--statistics} command-line
30642switch (@pxref{Mode Options}).
30643
30644@kindex maint time
30645@cindex time of command execution
30646@item maint time
30647Control whether to display the execution time for each command. If
30648set to a nonzero value, @value{GDBN} will display how much time it
30649took to execute each command, following the command's own output.
e2b7ddea
VP
30650The time is not printed for the commands that run the target, since
30651there's no mechanism currently to compute how much time was spend
30652by @value{GDBN} and how much time was spend by the program been debugged.
30653it's not possibly currently
09d4efe1
EZ
30654This can also be requested by invoking @value{GDBN} with the
30655@option{--statistics} command-line switch (@pxref{Mode Options}).
30656
30657@kindex maint translate-address
30658@item maint translate-address @r{[}@var{section}@r{]} @var{addr}
30659Find the symbol stored at the location specified by the address
30660@var{addr} and an optional section name @var{section}. If found,
30661@value{GDBN} prints the name of the closest symbol and an offset from
30662the symbol's location to the specified address. This is similar to
30663the @code{info address} command (@pxref{Symbols}), except that this
30664command also allows to find symbols in other sections.
ae038cb0 30665
c14c28ba
PP
30666If section was not specified, the section in which the symbol was found
30667is also printed. For dynamically linked executables, the name of
30668executable or shared library containing the symbol is printed as well.
30669
8e04817f 30670@end table
c906108c 30671
9c16f35a
EZ
30672The following command is useful for non-interactive invocations of
30673@value{GDBN}, such as in the test suite.
30674
30675@table @code
30676@item set watchdog @var{nsec}
30677@kindex set watchdog
30678@cindex watchdog timer
30679@cindex timeout for commands
30680Set the maximum number of seconds @value{GDBN} will wait for the
30681target operation to finish. If this time expires, @value{GDBN}
30682reports and error and the command is aborted.
30683
30684@item show watchdog
30685Show the current setting of the target wait timeout.
30686@end table
c906108c 30687
e0ce93ac 30688@node Remote Protocol
8e04817f 30689@appendix @value{GDBN} Remote Serial Protocol
c906108c 30690
ee2d5c50
AC
30691@menu
30692* Overview::
30693* Packets::
30694* Stop Reply Packets::
30695* General Query Packets::
a1dcb23a 30696* Architecture-Specific Protocol Details::
9d29849a 30697* Tracepoint Packets::
a6b151f1 30698* Host I/O Packets::
9a6253be 30699* Interrupts::
8b23ecc4
SL
30700* Notification Packets::
30701* Remote Non-Stop::
a6f3e723 30702* Packet Acknowledgment::
ee2d5c50 30703* Examples::
79a6e687 30704* File-I/O Remote Protocol Extension::
cfa9d6d9 30705* Library List Format::
79a6e687 30706* Memory Map Format::
dc146f7c 30707* Thread List Format::
ee2d5c50
AC
30708@end menu
30709
30710@node Overview
30711@section Overview
30712
8e04817f
AC
30713There may be occasions when you need to know something about the
30714protocol---for example, if there is only one serial port to your target
30715machine, you might want your program to do something special if it
30716recognizes a packet meant for @value{GDBN}.
c906108c 30717
d2c6833e 30718In the examples below, @samp{->} and @samp{<-} are used to indicate
bf06d120 30719transmitted and received data, respectively.
c906108c 30720
8e04817f
AC
30721@cindex protocol, @value{GDBN} remote serial
30722@cindex serial protocol, @value{GDBN} remote
30723@cindex remote serial protocol
8b23ecc4
SL
30724All @value{GDBN} commands and responses (other than acknowledgments
30725and notifications, see @ref{Notification Packets}) are sent as a
30726@var{packet}. A @var{packet} is introduced with the character
8e04817f
AC
30727@samp{$}, the actual @var{packet-data}, and the terminating character
30728@samp{#} followed by a two-digit @var{checksum}:
c906108c 30729
474c8240 30730@smallexample
8e04817f 30731@code{$}@var{packet-data}@code{#}@var{checksum}
474c8240 30732@end smallexample
8e04817f 30733@noindent
c906108c 30734
8e04817f
AC
30735@cindex checksum, for @value{GDBN} remote
30736@noindent
30737The two-digit @var{checksum} is computed as the modulo 256 sum of all
30738characters between the leading @samp{$} and the trailing @samp{#} (an
30739eight bit unsigned checksum).
c906108c 30740
8e04817f
AC
30741Implementors should note that prior to @value{GDBN} 5.0 the protocol
30742specification also included an optional two-digit @var{sequence-id}:
c906108c 30743
474c8240 30744@smallexample
8e04817f 30745@code{$}@var{sequence-id}@code{:}@var{packet-data}@code{#}@var{checksum}
474c8240 30746@end smallexample
c906108c 30747
8e04817f
AC
30748@cindex sequence-id, for @value{GDBN} remote
30749@noindent
30750That @var{sequence-id} was appended to the acknowledgment. @value{GDBN}
30751has never output @var{sequence-id}s. Stubs that handle packets added
30752since @value{GDBN} 5.0 must not accept @var{sequence-id}.
c906108c 30753
8e04817f
AC
30754When either the host or the target machine receives a packet, the first
30755response expected is an acknowledgment: either @samp{+} (to indicate
30756the package was received correctly) or @samp{-} (to request
30757retransmission):
c906108c 30758
474c8240 30759@smallexample
d2c6833e
AC
30760-> @code{$}@var{packet-data}@code{#}@var{checksum}
30761<- @code{+}
474c8240 30762@end smallexample
8e04817f 30763@noindent
53a5351d 30764
a6f3e723
SL
30765The @samp{+}/@samp{-} acknowledgments can be disabled
30766once a connection is established.
30767@xref{Packet Acknowledgment}, for details.
30768
8e04817f
AC
30769The host (@value{GDBN}) sends @var{command}s, and the target (the
30770debugging stub incorporated in your program) sends a @var{response}. In
30771the case of step and continue @var{command}s, the response is only sent
8b23ecc4
SL
30772when the operation has completed, and the target has again stopped all
30773threads in all attached processes. This is the default all-stop mode
30774behavior, but the remote protocol also supports @value{GDBN}'s non-stop
30775execution mode; see @ref{Remote Non-Stop}, for details.
c906108c 30776
8e04817f
AC
30777@var{packet-data} consists of a sequence of characters with the
30778exception of @samp{#} and @samp{$} (see @samp{X} packet for additional
30779exceptions).
c906108c 30780
ee2d5c50 30781@cindex remote protocol, field separator
0876f84a 30782Fields within the packet should be separated using @samp{,} @samp{;} or
8e04817f 30783@samp{:}. Except where otherwise noted all numbers are represented in
ee2d5c50 30784@sc{hex} with leading zeros suppressed.
c906108c 30785
8e04817f
AC
30786Implementors should note that prior to @value{GDBN} 5.0, the character
30787@samp{:} could not appear as the third character in a packet (as it
30788would potentially conflict with the @var{sequence-id}).
c906108c 30789
0876f84a
DJ
30790@cindex remote protocol, binary data
30791@anchor{Binary Data}
30792Binary data in most packets is encoded either as two hexadecimal
30793digits per byte of binary data. This allowed the traditional remote
30794protocol to work over connections which were only seven-bit clean.
30795Some packets designed more recently assume an eight-bit clean
30796connection, and use a more efficient encoding to send and receive
30797binary data.
30798
30799The binary data representation uses @code{7d} (@sc{ascii} @samp{@}})
30800as an escape character. Any escaped byte is transmitted as the escape
30801character followed by the original character XORed with @code{0x20}.
30802For example, the byte @code{0x7d} would be transmitted as the two
30803bytes @code{0x7d 0x5d}. The bytes @code{0x23} (@sc{ascii} @samp{#}),
30804@code{0x24} (@sc{ascii} @samp{$}), and @code{0x7d} (@sc{ascii}
30805@samp{@}}) must always be escaped. Responses sent by the stub
30806must also escape @code{0x2a} (@sc{ascii} @samp{*}), so that it
30807is not interpreted as the start of a run-length encoded sequence
30808(described next).
30809
1d3811f6
DJ
30810Response @var{data} can be run-length encoded to save space.
30811Run-length encoding replaces runs of identical characters with one
30812instance of the repeated character, followed by a @samp{*} and a
30813repeat count. The repeat count is itself sent encoded, to avoid
30814binary characters in @var{data}: a value of @var{n} is sent as
30815@code{@var{n}+29}. For a repeat count greater or equal to 3, this
30816produces a printable @sc{ascii} character, e.g.@: a space (@sc{ascii}
30817code 32) for a repeat count of 3. (This is because run-length
30818encoding starts to win for counts 3 or more.) Thus, for example,
30819@samp{0* } is a run-length encoding of ``0000'': the space character
30820after @samp{*} means repeat the leading @code{0} @w{@code{32 - 29 =
308213}} more times.
30822
30823The printable characters @samp{#} and @samp{$} or with a numeric value
30824greater than 126 must not be used. Runs of six repeats (@samp{#}) or
30825seven repeats (@samp{$}) can be expanded using a repeat count of only
30826five (@samp{"}). For example, @samp{00000000} can be encoded as
30827@samp{0*"00}.
c906108c 30828
8e04817f
AC
30829The error response returned for some packets includes a two character
30830error number. That number is not well defined.
c906108c 30831
f8da2bff 30832@cindex empty response, for unsupported packets
8e04817f
AC
30833For any @var{command} not supported by the stub, an empty response
30834(@samp{$#00}) should be returned. That way it is possible to extend the
30835protocol. A newer @value{GDBN} can tell if a packet is supported based
30836on that response.
c906108c 30837
b383017d
RM
30838A stub is required to support the @samp{g}, @samp{G}, @samp{m}, @samp{M},
30839@samp{c}, and @samp{s} @var{command}s. All other @var{command}s are
8e04817f 30840optional.
c906108c 30841
ee2d5c50
AC
30842@node Packets
30843@section Packets
30844
30845The following table provides a complete list of all currently defined
30846@var{command}s and their corresponding response @var{data}.
79a6e687 30847@xref{File-I/O Remote Protocol Extension}, for details about the File
9c16f35a 30848I/O extension of the remote protocol.
ee2d5c50 30849
b8ff78ce
JB
30850Each packet's description has a template showing the packet's overall
30851syntax, followed by an explanation of the packet's meaning. We
30852include spaces in some of the templates for clarity; these are not
30853part of the packet's syntax. No @value{GDBN} packet uses spaces to
30854separate its components. For example, a template like @samp{foo
30855@var{bar} @var{baz}} describes a packet beginning with the three ASCII
30856bytes @samp{foo}, followed by a @var{bar}, followed directly by a
3f94c067 30857@var{baz}. @value{GDBN} does not transmit a space character between the
b8ff78ce
JB
30858@samp{foo} and the @var{bar}, or between the @var{bar} and the
30859@var{baz}.
30860
b90a069a
SL
30861@cindex @var{thread-id}, in remote protocol
30862@anchor{thread-id syntax}
30863Several packets and replies include a @var{thread-id} field to identify
30864a thread. Normally these are positive numbers with a target-specific
30865interpretation, formatted as big-endian hex strings. A @var{thread-id}
30866can also be a literal @samp{-1} to indicate all threads, or @samp{0} to
30867pick any thread.
30868
30869In addition, the remote protocol supports a multiprocess feature in
30870which the @var{thread-id} syntax is extended to optionally include both
30871process and thread ID fields, as @samp{p@var{pid}.@var{tid}}.
30872The @var{pid} (process) and @var{tid} (thread) components each have the
30873format described above: a positive number with target-specific
30874interpretation formatted as a big-endian hex string, literal @samp{-1}
30875to indicate all processes or threads (respectively), or @samp{0} to
30876indicate an arbitrary process or thread. Specifying just a process, as
30877@samp{p@var{pid}}, is equivalent to @samp{p@var{pid}.-1}. It is an
30878error to specify all processes but a specific thread, such as
30879@samp{p-1.@var{tid}}. Note that the @samp{p} prefix is @emph{not} used
30880for those packets and replies explicitly documented to include a process
30881ID, rather than a @var{thread-id}.
30882
30883The multiprocess @var{thread-id} syntax extensions are only used if both
30884@value{GDBN} and the stub report support for the @samp{multiprocess}
30885feature using @samp{qSupported}. @xref{multiprocess extensions}, for
30886more information.
30887
8ffe2530
JB
30888Note that all packet forms beginning with an upper- or lower-case
30889letter, other than those described here, are reserved for future use.
30890
b8ff78ce 30891Here are the packet descriptions.
ee2d5c50 30892
b8ff78ce 30893@table @samp
ee2d5c50 30894
b8ff78ce
JB
30895@item !
30896@cindex @samp{!} packet
2d717e4f 30897@anchor{extended mode}
8e04817f
AC
30898Enable extended mode. In extended mode, the remote server is made
30899persistent. The @samp{R} packet is used to restart the program being
30900debugged.
ee2d5c50
AC
30901
30902Reply:
30903@table @samp
30904@item OK
8e04817f 30905The remote target both supports and has enabled extended mode.
ee2d5c50 30906@end table
c906108c 30907
b8ff78ce
JB
30908@item ?
30909@cindex @samp{?} packet
ee2d5c50 30910Indicate the reason the target halted. The reply is the same as for
8b23ecc4
SL
30911step and continue. This packet has a special interpretation when the
30912target is in non-stop mode; see @ref{Remote Non-Stop}.
c906108c 30913
ee2d5c50
AC
30914Reply:
30915@xref{Stop Reply Packets}, for the reply specifications.
30916
b8ff78ce
JB
30917@item A @var{arglen},@var{argnum},@var{arg},@dots{}
30918@cindex @samp{A} packet
30919Initialized @code{argv[]} array passed into program. @var{arglen}
30920specifies the number of bytes in the hex encoded byte stream
30921@var{arg}. See @code{gdbserver} for more details.
ee2d5c50
AC
30922
30923Reply:
30924@table @samp
30925@item OK
b8ff78ce
JB
30926The arguments were set.
30927@item E @var{NN}
30928An error occurred.
ee2d5c50
AC
30929@end table
30930
b8ff78ce
JB
30931@item b @var{baud}
30932@cindex @samp{b} packet
30933(Don't use this packet; its behavior is not well-defined.)
ee2d5c50
AC
30934Change the serial line speed to @var{baud}.
30935
30936JTC: @emph{When does the transport layer state change? When it's
30937received, or after the ACK is transmitted. In either case, there are
30938problems if the command or the acknowledgment packet is dropped.}
30939
30940Stan: @emph{If people really wanted to add something like this, and get
30941it working for the first time, they ought to modify ser-unix.c to send
30942some kind of out-of-band message to a specially-setup stub and have the
30943switch happen "in between" packets, so that from remote protocol's point
30944of view, nothing actually happened.}
30945
b8ff78ce
JB
30946@item B @var{addr},@var{mode}
30947@cindex @samp{B} packet
8e04817f 30948Set (@var{mode} is @samp{S}) or clear (@var{mode} is @samp{C}) a
2f870471
AC
30949breakpoint at @var{addr}.
30950
b8ff78ce 30951Don't use this packet. Use the @samp{Z} and @samp{z} packets instead
2f870471 30952(@pxref{insert breakpoint or watchpoint packet}).
c906108c 30953
bacec72f 30954@cindex @samp{bc} packet
0d772ac9
MS
30955@anchor{bc}
30956@item bc
bacec72f
MS
30957Backward continue. Execute the target system in reverse. No parameter.
30958@xref{Reverse Execution}, for more information.
30959
30960Reply:
30961@xref{Stop Reply Packets}, for the reply specifications.
30962
bacec72f 30963@cindex @samp{bs} packet
0d772ac9
MS
30964@anchor{bs}
30965@item bs
bacec72f
MS
30966Backward single step. Execute one instruction in reverse. No parameter.
30967@xref{Reverse Execution}, for more information.
30968
30969Reply:
30970@xref{Stop Reply Packets}, for the reply specifications.
30971
4f553f88 30972@item c @r{[}@var{addr}@r{]}
b8ff78ce
JB
30973@cindex @samp{c} packet
30974Continue. @var{addr} is address to resume. If @var{addr} is omitted,
30975resume at current address.
c906108c 30976
ee2d5c50
AC
30977Reply:
30978@xref{Stop Reply Packets}, for the reply specifications.
30979
4f553f88 30980@item C @var{sig}@r{[};@var{addr}@r{]}
b8ff78ce 30981@cindex @samp{C} packet
8e04817f 30982Continue with signal @var{sig} (hex signal number). If
b8ff78ce 30983@samp{;@var{addr}} is omitted, resume at same address.
c906108c 30984
ee2d5c50
AC
30985Reply:
30986@xref{Stop Reply Packets}, for the reply specifications.
c906108c 30987
b8ff78ce
JB
30988@item d
30989@cindex @samp{d} packet
ee2d5c50
AC
30990Toggle debug flag.
30991
b8ff78ce
JB
30992Don't use this packet; instead, define a general set packet
30993(@pxref{General Query Packets}).
ee2d5c50 30994
b8ff78ce 30995@item D
b90a069a 30996@itemx D;@var{pid}
b8ff78ce 30997@cindex @samp{D} packet
b90a069a
SL
30998The first form of the packet is used to detach @value{GDBN} from the
30999remote system. It is sent to the remote target
07f31aa6 31000before @value{GDBN} disconnects via the @code{detach} command.
ee2d5c50 31001
b90a069a
SL
31002The second form, including a process ID, is used when multiprocess
31003protocol extensions are enabled (@pxref{multiprocess extensions}), to
31004detach only a specific process. The @var{pid} is specified as a
31005big-endian hex string.
31006
ee2d5c50
AC
31007Reply:
31008@table @samp
10fac096
NW
31009@item OK
31010for success
b8ff78ce 31011@item E @var{NN}
10fac096 31012for an error
ee2d5c50 31013@end table
c906108c 31014
b8ff78ce
JB
31015@item F @var{RC},@var{EE},@var{CF};@var{XX}
31016@cindex @samp{F} packet
31017A reply from @value{GDBN} to an @samp{F} packet sent by the target.
31018This is part of the File-I/O protocol extension. @xref{File-I/O
79a6e687 31019Remote Protocol Extension}, for the specification.
ee2d5c50 31020
b8ff78ce 31021@item g
ee2d5c50 31022@anchor{read registers packet}
b8ff78ce 31023@cindex @samp{g} packet
ee2d5c50
AC
31024Read general registers.
31025
31026Reply:
31027@table @samp
31028@item @var{XX@dots{}}
8e04817f
AC
31029Each byte of register data is described by two hex digits. The bytes
31030with the register are transmitted in target byte order. The size of
b8ff78ce 31031each register and their position within the @samp{g} packet are
4a9bb1df
UW
31032determined by the @value{GDBN} internal gdbarch functions
31033@code{DEPRECATED_REGISTER_RAW_SIZE} and @code{gdbarch_register_name}. The
b8ff78ce
JB
31034specification of several standard @samp{g} packets is specified below.
31035@item E @var{NN}
ee2d5c50
AC
31036for an error.
31037@end table
c906108c 31038
b8ff78ce
JB
31039@item G @var{XX@dots{}}
31040@cindex @samp{G} packet
31041Write general registers. @xref{read registers packet}, for a
31042description of the @var{XX@dots{}} data.
ee2d5c50
AC
31043
31044Reply:
31045@table @samp
31046@item OK
31047for success
b8ff78ce 31048@item E @var{NN}
ee2d5c50
AC
31049for an error
31050@end table
31051
b90a069a 31052@item H @var{c} @var{thread-id}
b8ff78ce 31053@cindex @samp{H} packet
8e04817f 31054Set thread for subsequent operations (@samp{m}, @samp{M}, @samp{g},
ee2d5c50
AC
31055@samp{G}, et.al.). @var{c} depends on the operation to be performed: it
31056should be @samp{c} for step and continue operations, @samp{g} for other
b90a069a
SL
31057operations. The thread designator @var{thread-id} has the format and
31058interpretation described in @ref{thread-id syntax}.
ee2d5c50
AC
31059
31060Reply:
31061@table @samp
31062@item OK
31063for success
b8ff78ce 31064@item E @var{NN}
ee2d5c50
AC
31065for an error
31066@end table
c906108c 31067
8e04817f
AC
31068@c FIXME: JTC:
31069@c 'H': How restrictive (or permissive) is the thread model. If a
31070@c thread is selected and stopped, are other threads allowed
31071@c to continue to execute? As I mentioned above, I think the
31072@c semantics of each command when a thread is selected must be
31073@c described. For example:
31074@c
31075@c 'g': If the stub supports threads and a specific thread is
31076@c selected, returns the register block from that thread;
31077@c otherwise returns current registers.
31078@c
31079@c 'G' If the stub supports threads and a specific thread is
31080@c selected, sets the registers of the register block of
31081@c that thread; otherwise sets current registers.
c906108c 31082
b8ff78ce 31083@item i @r{[}@var{addr}@r{[},@var{nnn}@r{]]}
ee2d5c50 31084@anchor{cycle step packet}
b8ff78ce
JB
31085@cindex @samp{i} packet
31086Step the remote target by a single clock cycle. If @samp{,@var{nnn}} is
8e04817f
AC
31087present, cycle step @var{nnn} cycles. If @var{addr} is present, cycle
31088step starting at that address.
c906108c 31089
b8ff78ce
JB
31090@item I
31091@cindex @samp{I} packet
31092Signal, then cycle step. @xref{step with signal packet}. @xref{cycle
31093step packet}.
ee2d5c50 31094
b8ff78ce
JB
31095@item k
31096@cindex @samp{k} packet
31097Kill request.
c906108c 31098
ac282366 31099FIXME: @emph{There is no description of how to operate when a specific
ee2d5c50
AC
31100thread context has been selected (i.e.@: does 'k' kill only that
31101thread?)}.
c906108c 31102
b8ff78ce
JB
31103@item m @var{addr},@var{length}
31104@cindex @samp{m} packet
8e04817f 31105Read @var{length} bytes of memory starting at address @var{addr}.
fb031cdf
JB
31106Note that @var{addr} may not be aligned to any particular boundary.
31107
31108The stub need not use any particular size or alignment when gathering
31109data from memory for the response; even if @var{addr} is word-aligned
31110and @var{length} is a multiple of the word size, the stub is free to
31111use byte accesses, or not. For this reason, this packet may not be
31112suitable for accessing memory-mapped I/O devices.
c43c5473
JB
31113@cindex alignment of remote memory accesses
31114@cindex size of remote memory accesses
31115@cindex memory, alignment and size of remote accesses
c906108c 31116
ee2d5c50
AC
31117Reply:
31118@table @samp
31119@item @var{XX@dots{}}
599b237a 31120Memory contents; each byte is transmitted as a two-digit hexadecimal
b8ff78ce
JB
31121number. The reply may contain fewer bytes than requested if the
31122server was able to read only part of the region of memory.
31123@item E @var{NN}
ee2d5c50
AC
31124@var{NN} is errno
31125@end table
31126
b8ff78ce
JB
31127@item M @var{addr},@var{length}:@var{XX@dots{}}
31128@cindex @samp{M} packet
8e04817f 31129Write @var{length} bytes of memory starting at address @var{addr}.
b8ff78ce 31130@var{XX@dots{}} is the data; each byte is transmitted as a two-digit
599b237a 31131hexadecimal number.
ee2d5c50
AC
31132
31133Reply:
31134@table @samp
31135@item OK
31136for success
b8ff78ce 31137@item E @var{NN}
8e04817f
AC
31138for an error (this includes the case where only part of the data was
31139written).
ee2d5c50 31140@end table
c906108c 31141
b8ff78ce
JB
31142@item p @var{n}
31143@cindex @samp{p} packet
31144Read the value of register @var{n}; @var{n} is in hex.
2e868123
AC
31145@xref{read registers packet}, for a description of how the returned
31146register value is encoded.
ee2d5c50
AC
31147
31148Reply:
31149@table @samp
2e868123
AC
31150@item @var{XX@dots{}}
31151the register's value
b8ff78ce 31152@item E @var{NN}
2e868123
AC
31153for an error
31154@item
31155Indicating an unrecognized @var{query}.
ee2d5c50
AC
31156@end table
31157
b8ff78ce 31158@item P @var{n@dots{}}=@var{r@dots{}}
ee2d5c50 31159@anchor{write register packet}
b8ff78ce
JB
31160@cindex @samp{P} packet
31161Write register @var{n@dots{}} with value @var{r@dots{}}. The register
599b237a 31162number @var{n} is in hexadecimal, and @var{r@dots{}} contains two hex
8e04817f 31163digits for each byte in the register (target byte order).
c906108c 31164
ee2d5c50
AC
31165Reply:
31166@table @samp
31167@item OK
31168for success
b8ff78ce 31169@item E @var{NN}
ee2d5c50
AC
31170for an error
31171@end table
31172
5f3bebba
JB
31173@item q @var{name} @var{params}@dots{}
31174@itemx Q @var{name} @var{params}@dots{}
b8ff78ce 31175@cindex @samp{q} packet
b8ff78ce 31176@cindex @samp{Q} packet
5f3bebba
JB
31177General query (@samp{q}) and set (@samp{Q}). These packets are
31178described fully in @ref{General Query Packets}.
c906108c 31179
b8ff78ce
JB
31180@item r
31181@cindex @samp{r} packet
8e04817f 31182Reset the entire system.
c906108c 31183
b8ff78ce 31184Don't use this packet; use the @samp{R} packet instead.
ee2d5c50 31185
b8ff78ce
JB
31186@item R @var{XX}
31187@cindex @samp{R} packet
8e04817f 31188Restart the program being debugged. @var{XX}, while needed, is ignored.
2d717e4f 31189This packet is only available in extended mode (@pxref{extended mode}).
ee2d5c50 31190
8e04817f 31191The @samp{R} packet has no reply.
ee2d5c50 31192
4f553f88 31193@item s @r{[}@var{addr}@r{]}
b8ff78ce
JB
31194@cindex @samp{s} packet
31195Single step. @var{addr} is the address at which to resume. If
31196@var{addr} is omitted, resume at same address.
c906108c 31197
ee2d5c50
AC
31198Reply:
31199@xref{Stop Reply Packets}, for the reply specifications.
31200
4f553f88 31201@item S @var{sig}@r{[};@var{addr}@r{]}
ee2d5c50 31202@anchor{step with signal packet}
b8ff78ce
JB
31203@cindex @samp{S} packet
31204Step with signal. This is analogous to the @samp{C} packet, but
31205requests a single-step, rather than a normal resumption of execution.
c906108c 31206
ee2d5c50
AC
31207Reply:
31208@xref{Stop Reply Packets}, for the reply specifications.
31209
b8ff78ce
JB
31210@item t @var{addr}:@var{PP},@var{MM}
31211@cindex @samp{t} packet
8e04817f 31212Search backwards starting at address @var{addr} for a match with pattern
ee2d5c50
AC
31213@var{PP} and mask @var{MM}. @var{PP} and @var{MM} are 4 bytes.
31214@var{addr} must be at least 3 digits.
c906108c 31215
b90a069a 31216@item T @var{thread-id}
b8ff78ce 31217@cindex @samp{T} packet
b90a069a 31218Find out if the thread @var{thread-id} is alive. @xref{thread-id syntax}.
c906108c 31219
ee2d5c50
AC
31220Reply:
31221@table @samp
31222@item OK
31223thread is still alive
b8ff78ce 31224@item E @var{NN}
ee2d5c50
AC
31225thread is dead
31226@end table
31227
b8ff78ce
JB
31228@item v
31229Packets starting with @samp{v} are identified by a multi-letter name,
31230up to the first @samp{;} or @samp{?} (or the end of the packet).
86d30acc 31231
2d717e4f
DJ
31232@item vAttach;@var{pid}
31233@cindex @samp{vAttach} packet
8b23ecc4
SL
31234Attach to a new process with the specified process ID @var{pid}.
31235The process ID is a
31236hexadecimal integer identifying the process. In all-stop mode, all
31237threads in the attached process are stopped; in non-stop mode, it may be
31238attached without being stopped if that is supported by the target.
31239
31240@c In non-stop mode, on a successful vAttach, the stub should set the
31241@c current thread to a thread of the newly-attached process. After
31242@c attaching, GDB queries for the attached process's thread ID with qC.
31243@c Also note that, from a user perspective, whether or not the
31244@c target is stopped on attach in non-stop mode depends on whether you
31245@c use the foreground or background version of the attach command, not
31246@c on what vAttach does; GDB does the right thing with respect to either
31247@c stopping or restarting threads.
2d717e4f
DJ
31248
31249This packet is only available in extended mode (@pxref{extended mode}).
31250
31251Reply:
31252@table @samp
31253@item E @var{nn}
31254for an error
31255@item @r{Any stop packet}
8b23ecc4
SL
31256for success in all-stop mode (@pxref{Stop Reply Packets})
31257@item OK
31258for success in non-stop mode (@pxref{Remote Non-Stop})
2d717e4f
DJ
31259@end table
31260
b90a069a 31261@item vCont@r{[};@var{action}@r{[}:@var{thread-id}@r{]]}@dots{}
b8ff78ce
JB
31262@cindex @samp{vCont} packet
31263Resume the inferior, specifying different actions for each thread.
b90a069a 31264If an action is specified with no @var{thread-id}, then it is applied to any
86d30acc 31265threads that don't have a specific action specified; if no default action is
8b23ecc4
SL
31266specified then other threads should remain stopped in all-stop mode and
31267in their current state in non-stop mode.
31268Specifying multiple
86d30acc 31269default actions is an error; specifying no actions is also an error.
b90a069a
SL
31270Thread IDs are specified using the syntax described in @ref{thread-id syntax}.
31271
31272Currently supported actions are:
86d30acc 31273
b8ff78ce 31274@table @samp
86d30acc
DJ
31275@item c
31276Continue.
b8ff78ce 31277@item C @var{sig}
8b23ecc4 31278Continue with signal @var{sig}. The signal @var{sig} should be two hex digits.
86d30acc
DJ
31279@item s
31280Step.
b8ff78ce 31281@item S @var{sig}
8b23ecc4
SL
31282Step with signal @var{sig}. The signal @var{sig} should be two hex digits.
31283@item t
31284Stop.
86d30acc
DJ
31285@end table
31286
8b23ecc4
SL
31287The optional argument @var{addr} normally associated with the
31288@samp{c}, @samp{C}, @samp{s}, and @samp{S} packets is
b8ff78ce 31289not supported in @samp{vCont}.
86d30acc 31290
08a0efd0
PA
31291The @samp{t} action is only relevant in non-stop mode
31292(@pxref{Remote Non-Stop}) and may be ignored by the stub otherwise.
8b23ecc4
SL
31293A stop reply should be generated for any affected thread not already stopped.
31294When a thread is stopped by means of a @samp{t} action,
31295the corresponding stop reply should indicate that the thread has stopped with
31296signal @samp{0}, regardless of whether the target uses some other signal
31297as an implementation detail.
31298
86d30acc
DJ
31299Reply:
31300@xref{Stop Reply Packets}, for the reply specifications.
31301
b8ff78ce
JB
31302@item vCont?
31303@cindex @samp{vCont?} packet
d3e8051b 31304Request a list of actions supported by the @samp{vCont} packet.
86d30acc
DJ
31305
31306Reply:
31307@table @samp
b8ff78ce
JB
31308@item vCont@r{[};@var{action}@dots{}@r{]}
31309The @samp{vCont} packet is supported. Each @var{action} is a supported
31310command in the @samp{vCont} packet.
86d30acc 31311@item
b8ff78ce 31312The @samp{vCont} packet is not supported.
86d30acc 31313@end table
ee2d5c50 31314
a6b151f1
DJ
31315@item vFile:@var{operation}:@var{parameter}@dots{}
31316@cindex @samp{vFile} packet
31317Perform a file operation on the target system. For details,
31318see @ref{Host I/O Packets}.
31319
68437a39
DJ
31320@item vFlashErase:@var{addr},@var{length}
31321@cindex @samp{vFlashErase} packet
31322Direct the stub to erase @var{length} bytes of flash starting at
31323@var{addr}. The region may enclose any number of flash blocks, but
31324its start and end must fall on block boundaries, as indicated by the
79a6e687
BW
31325flash block size appearing in the memory map (@pxref{Memory Map
31326Format}). @value{GDBN} groups flash memory programming operations
68437a39
DJ
31327together, and sends a @samp{vFlashDone} request after each group; the
31328stub is allowed to delay erase operation until the @samp{vFlashDone}
31329packet is received.
31330
b90a069a
SL
31331The stub must support @samp{vCont} if it reports support for
31332multiprocess extensions (@pxref{multiprocess extensions}). Note that in
31333this case @samp{vCont} actions can be specified to apply to all threads
31334in a process by using the @samp{p@var{pid}.-1} form of the
31335@var{thread-id}.
31336
68437a39
DJ
31337Reply:
31338@table @samp
31339@item OK
31340for success
31341@item E @var{NN}
31342for an error
31343@end table
31344
31345@item vFlashWrite:@var{addr}:@var{XX@dots{}}
31346@cindex @samp{vFlashWrite} packet
31347Direct the stub to write data to flash address @var{addr}. The data
31348is passed in binary form using the same encoding as for the @samp{X}
31349packet (@pxref{Binary Data}). The memory ranges specified by
31350@samp{vFlashWrite} packets preceding a @samp{vFlashDone} packet must
31351not overlap, and must appear in order of increasing addresses
31352(although @samp{vFlashErase} packets for higher addresses may already
31353have been received; the ordering is guaranteed only between
31354@samp{vFlashWrite} packets). If a packet writes to an address that was
31355neither erased by a preceding @samp{vFlashErase} packet nor by some other
31356target-specific method, the results are unpredictable.
31357
31358
31359Reply:
31360@table @samp
31361@item OK
31362for success
31363@item E.memtype
31364for vFlashWrite addressing non-flash memory
31365@item E @var{NN}
31366for an error
31367@end table
31368
31369@item vFlashDone
31370@cindex @samp{vFlashDone} packet
31371Indicate to the stub that flash programming operation is finished.
31372The stub is permitted to delay or batch the effects of a group of
31373@samp{vFlashErase} and @samp{vFlashWrite} packets until a
31374@samp{vFlashDone} packet is received. The contents of the affected
31375regions of flash memory are unpredictable until the @samp{vFlashDone}
31376request is completed.
31377
b90a069a
SL
31378@item vKill;@var{pid}
31379@cindex @samp{vKill} packet
31380Kill the process with the specified process ID. @var{pid} is a
31381hexadecimal integer identifying the process. This packet is used in
31382preference to @samp{k} when multiprocess protocol extensions are
31383supported; see @ref{multiprocess extensions}.
31384
31385Reply:
31386@table @samp
31387@item E @var{nn}
31388for an error
31389@item OK
31390for success
31391@end table
31392
2d717e4f
DJ
31393@item vRun;@var{filename}@r{[};@var{argument}@r{]}@dots{}
31394@cindex @samp{vRun} packet
31395Run the program @var{filename}, passing it each @var{argument} on its
31396command line. The file and arguments are hex-encoded strings. If
31397@var{filename} is an empty string, the stub may use a default program
31398(e.g.@: the last program run). The program is created in the stopped
9b562ab8 31399state.
2d717e4f 31400
8b23ecc4
SL
31401@c FIXME: What about non-stop mode?
31402
2d717e4f
DJ
31403This packet is only available in extended mode (@pxref{extended mode}).
31404
31405Reply:
31406@table @samp
31407@item E @var{nn}
31408for an error
31409@item @r{Any stop packet}
31410for success (@pxref{Stop Reply Packets})
31411@end table
31412
8b23ecc4
SL
31413@item vStopped
31414@anchor{vStopped packet}
31415@cindex @samp{vStopped} packet
31416
31417In non-stop mode (@pxref{Remote Non-Stop}), acknowledge a previous stop
31418reply and prompt for the stub to report another one.
31419
31420Reply:
31421@table @samp
31422@item @r{Any stop packet}
31423if there is another unreported stop event (@pxref{Stop Reply Packets})
31424@item OK
31425if there are no unreported stop events
31426@end table
31427
b8ff78ce 31428@item X @var{addr},@var{length}:@var{XX@dots{}}
9a6253be 31429@anchor{X packet}
b8ff78ce
JB
31430@cindex @samp{X} packet
31431Write data to memory, where the data is transmitted in binary.
31432@var{addr} is address, @var{length} is number of bytes,
0876f84a 31433@samp{@var{XX}@dots{}} is binary data (@pxref{Binary Data}).
c906108c 31434
ee2d5c50
AC
31435Reply:
31436@table @samp
31437@item OK
31438for success
b8ff78ce 31439@item E @var{NN}
ee2d5c50
AC
31440for an error
31441@end table
31442
a1dcb23a
DJ
31443@item z @var{type},@var{addr},@var{kind}
31444@itemx Z @var{type},@var{addr},@var{kind}
2f870471 31445@anchor{insert breakpoint or watchpoint packet}
b8ff78ce
JB
31446@cindex @samp{z} packet
31447@cindex @samp{Z} packets
31448Insert (@samp{Z}) or remove (@samp{z}) a @var{type} breakpoint or
a1dcb23a 31449watchpoint starting at address @var{address} of kind @var{kind}.
ee2d5c50 31450
2f870471
AC
31451Each breakpoint and watchpoint packet @var{type} is documented
31452separately.
31453
512217c7
AC
31454@emph{Implementation notes: A remote target shall return an empty string
31455for an unrecognized breakpoint or watchpoint packet @var{type}. A
31456remote target shall support either both or neither of a given
b8ff78ce 31457@samp{Z@var{type}@dots{}} and @samp{z@var{type}@dots{}} packet pair. To
2f870471
AC
31458avoid potential problems with duplicate packets, the operations should
31459be implemented in an idempotent way.}
31460
a1dcb23a
DJ
31461@item z0,@var{addr},@var{kind}
31462@itemx Z0,@var{addr},@var{kind}
b8ff78ce
JB
31463@cindex @samp{z0} packet
31464@cindex @samp{Z0} packet
31465Insert (@samp{Z0}) or remove (@samp{z0}) a memory breakpoint at address
a1dcb23a 31466@var{addr} of type @var{kind}.
2f870471
AC
31467
31468A memory breakpoint is implemented by replacing the instruction at
31469@var{addr} with a software breakpoint or trap instruction. The
a1dcb23a
DJ
31470@var{kind} is target-specific and typically indicates the size of
31471the breakpoint in bytes that should be inserted. E.g., the @sc{arm}
31472and @sc{mips} can insert either a 2 or 4 byte breakpoint. Some
31473architectures have additional meanings for @var{kind};
31474see @ref{Architecture-Specific Protocol Details}.
c906108c 31475
2f870471
AC
31476@emph{Implementation note: It is possible for a target to copy or move
31477code that contains memory breakpoints (e.g., when implementing
31478overlays). The behavior of this packet, in the presence of such a
31479target, is not defined.}
c906108c 31480
ee2d5c50
AC
31481Reply:
31482@table @samp
2f870471
AC
31483@item OK
31484success
31485@item
31486not supported
b8ff78ce 31487@item E @var{NN}
ee2d5c50 31488for an error
2f870471
AC
31489@end table
31490
a1dcb23a
DJ
31491@item z1,@var{addr},@var{kind}
31492@itemx Z1,@var{addr},@var{kind}
b8ff78ce
JB
31493@cindex @samp{z1} packet
31494@cindex @samp{Z1} packet
31495Insert (@samp{Z1}) or remove (@samp{z1}) a hardware breakpoint at
a1dcb23a 31496address @var{addr}.
2f870471
AC
31497
31498A hardware breakpoint is implemented using a mechanism that is not
a1dcb23a
DJ
31499dependant on being able to modify the target's memory. @var{kind}
31500has the same meaning as in @samp{Z0} packets.
2f870471
AC
31501
31502@emph{Implementation note: A hardware breakpoint is not affected by code
31503movement.}
31504
31505Reply:
31506@table @samp
ee2d5c50 31507@item OK
2f870471
AC
31508success
31509@item
31510not supported
b8ff78ce 31511@item E @var{NN}
2f870471
AC
31512for an error
31513@end table
31514
a1dcb23a
DJ
31515@item z2,@var{addr},@var{kind}
31516@itemx Z2,@var{addr},@var{kind}
b8ff78ce
JB
31517@cindex @samp{z2} packet
31518@cindex @samp{Z2} packet
a1dcb23a
DJ
31519Insert (@samp{Z2}) or remove (@samp{z2}) a write watchpoint at @var{addr}.
31520@var{kind} is interpreted as the number of bytes to watch.
2f870471
AC
31521
31522Reply:
31523@table @samp
31524@item OK
31525success
31526@item
31527not supported
b8ff78ce 31528@item E @var{NN}
2f870471
AC
31529for an error
31530@end table
31531
a1dcb23a
DJ
31532@item z3,@var{addr},@var{kind}
31533@itemx Z3,@var{addr},@var{kind}
b8ff78ce
JB
31534@cindex @samp{z3} packet
31535@cindex @samp{Z3} packet
a1dcb23a
DJ
31536Insert (@samp{Z3}) or remove (@samp{z3}) a read watchpoint at @var{addr}.
31537@var{kind} is interpreted as the number of bytes to watch.
2f870471
AC
31538
31539Reply:
31540@table @samp
31541@item OK
31542success
31543@item
31544not supported
b8ff78ce 31545@item E @var{NN}
2f870471
AC
31546for an error
31547@end table
31548
a1dcb23a
DJ
31549@item z4,@var{addr},@var{kind}
31550@itemx Z4,@var{addr},@var{kind}
b8ff78ce
JB
31551@cindex @samp{z4} packet
31552@cindex @samp{Z4} packet
a1dcb23a
DJ
31553Insert (@samp{Z4}) or remove (@samp{z4}) an access watchpoint at @var{addr}.
31554@var{kind} is interpreted as the number of bytes to watch.
2f870471
AC
31555
31556Reply:
31557@table @samp
31558@item OK
31559success
31560@item
31561not supported
b8ff78ce 31562@item E @var{NN}
2f870471 31563for an error
ee2d5c50
AC
31564@end table
31565
31566@end table
c906108c 31567
ee2d5c50
AC
31568@node Stop Reply Packets
31569@section Stop Reply Packets
31570@cindex stop reply packets
c906108c 31571
8b23ecc4
SL
31572The @samp{C}, @samp{c}, @samp{S}, @samp{s}, @samp{vCont},
31573@samp{vAttach}, @samp{vRun}, @samp{vStopped}, and @samp{?} packets can
31574receive any of the below as a reply. Except for @samp{?}
31575and @samp{vStopped}, that reply is only returned
b8ff78ce 31576when the target halts. In the below the exact meaning of @dfn{signal
89be2091
DJ
31577number} is defined by the header @file{include/gdb/signals.h} in the
31578@value{GDBN} source code.
c906108c 31579
b8ff78ce
JB
31580As in the description of request packets, we include spaces in the
31581reply templates for clarity; these are not part of the reply packet's
31582syntax. No @value{GDBN} stop reply packet uses spaces to separate its
31583components.
c906108c 31584
b8ff78ce 31585@table @samp
ee2d5c50 31586
b8ff78ce 31587@item S @var{AA}
599b237a 31588The program received signal number @var{AA} (a two-digit hexadecimal
940178d3
JB
31589number). This is equivalent to a @samp{T} response with no
31590@var{n}:@var{r} pairs.
c906108c 31591
b8ff78ce
JB
31592@item T @var{AA} @var{n1}:@var{r1};@var{n2}:@var{r2};@dots{}
31593@cindex @samp{T} packet reply
599b237a 31594The program received signal number @var{AA} (a two-digit hexadecimal
940178d3
JB
31595number). This is equivalent to an @samp{S} response, except that the
31596@samp{@var{n}:@var{r}} pairs can carry values of important registers
31597and other information directly in the stop reply packet, reducing
31598round-trip latency. Single-step and breakpoint traps are reported
31599this way. Each @samp{@var{n}:@var{r}} pair is interpreted as follows:
cfa9d6d9
DJ
31600
31601@itemize @bullet
b8ff78ce 31602@item
599b237a 31603If @var{n} is a hexadecimal number, it is a register number, and the
b8ff78ce
JB
31604corresponding @var{r} gives that register's value. @var{r} is a
31605series of bytes in target byte order, with each byte given by a
31606two-digit hex number.
cfa9d6d9 31607
b8ff78ce 31608@item
b90a069a
SL
31609If @var{n} is @samp{thread}, then @var{r} is the @var{thread-id} of
31610the stopped thread, as specified in @ref{thread-id syntax}.
cfa9d6d9 31611
dc146f7c
VP
31612@item
31613If @var{n} is @samp{core}, then @var{r} is the hexadecimal number of
31614the core on which the stop event was detected.
31615
b8ff78ce 31616@item
cfa9d6d9
DJ
31617If @var{n} is a recognized @dfn{stop reason}, it describes a more
31618specific event that stopped the target. The currently defined stop
31619reasons are listed below. @var{aa} should be @samp{05}, the trap
31620signal. At most one stop reason should be present.
31621
b8ff78ce
JB
31622@item
31623Otherwise, @value{GDBN} should ignore this @samp{@var{n}:@var{r}} pair
31624and go on to the next; this allows us to extend the protocol in the
31625future.
cfa9d6d9
DJ
31626@end itemize
31627
31628The currently defined stop reasons are:
31629
31630@table @samp
31631@item watch
31632@itemx rwatch
31633@itemx awatch
31634The packet indicates a watchpoint hit, and @var{r} is the data address, in
31635hex.
31636
31637@cindex shared library events, remote reply
31638@item library
31639The packet indicates that the loaded libraries have changed.
31640@value{GDBN} should use @samp{qXfer:libraries:read} to fetch a new
31641list of loaded libraries. @var{r} is ignored.
bacec72f
MS
31642
31643@cindex replay log events, remote reply
31644@item replaylog
31645The packet indicates that the target cannot continue replaying
31646logged execution events, because it has reached the end (or the
31647beginning when executing backward) of the log. The value of @var{r}
31648will be either @samp{begin} or @samp{end}. @xref{Reverse Execution},
31649for more information.
cfa9d6d9 31650@end table
ee2d5c50 31651
b8ff78ce 31652@item W @var{AA}
b90a069a 31653@itemx W @var{AA} ; process:@var{pid}
8e04817f 31654The process exited, and @var{AA} is the exit status. This is only
ee2d5c50
AC
31655applicable to certain targets.
31656
b90a069a
SL
31657The second form of the response, including the process ID of the exited
31658process, can be used only when @value{GDBN} has reported support for
31659multiprocess protocol extensions; see @ref{multiprocess extensions}.
31660The @var{pid} is formatted as a big-endian hex string.
31661
b8ff78ce 31662@item X @var{AA}
b90a069a 31663@itemx X @var{AA} ; process:@var{pid}
8e04817f 31664The process terminated with signal @var{AA}.
c906108c 31665
b90a069a
SL
31666The second form of the response, including the process ID of the
31667terminated process, can be used only when @value{GDBN} has reported
31668support for multiprocess protocol extensions; see @ref{multiprocess
31669extensions}. The @var{pid} is formatted as a big-endian hex string.
31670
b8ff78ce
JB
31671@item O @var{XX}@dots{}
31672@samp{@var{XX}@dots{}} is hex encoding of @sc{ascii} data, to be
31673written as the program's console output. This can happen at any time
31674while the program is running and the debugger should continue to wait
8b23ecc4 31675for @samp{W}, @samp{T}, etc. This reply is not permitted in non-stop mode.
0ce1b118 31676
b8ff78ce 31677@item F @var{call-id},@var{parameter}@dots{}
0ce1b118
CV
31678@var{call-id} is the identifier which says which host system call should
31679be called. This is just the name of the function. Translation into the
31680correct system call is only applicable as it's defined in @value{GDBN}.
79a6e687 31681@xref{File-I/O Remote Protocol Extension}, for a list of implemented
0ce1b118
CV
31682system calls.
31683
b8ff78ce
JB
31684@samp{@var{parameter}@dots{}} is a list of parameters as defined for
31685this very system call.
0ce1b118 31686
b8ff78ce
JB
31687The target replies with this packet when it expects @value{GDBN} to
31688call a host system call on behalf of the target. @value{GDBN} replies
31689with an appropriate @samp{F} packet and keeps up waiting for the next
31690reply packet from the target. The latest @samp{C}, @samp{c}, @samp{S}
79a6e687
BW
31691or @samp{s} action is expected to be continued. @xref{File-I/O Remote
31692Protocol Extension}, for more details.
0ce1b118 31693
ee2d5c50
AC
31694@end table
31695
31696@node General Query Packets
31697@section General Query Packets
9c16f35a 31698@cindex remote query requests
c906108c 31699
5f3bebba
JB
31700Packets starting with @samp{q} are @dfn{general query packets};
31701packets starting with @samp{Q} are @dfn{general set packets}. General
31702query and set packets are a semi-unified form for retrieving and
31703sending information to and from the stub.
31704
31705The initial letter of a query or set packet is followed by a name
31706indicating what sort of thing the packet applies to. For example,
31707@value{GDBN} may use a @samp{qSymbol} packet to exchange symbol
31708definitions with the stub. These packet names follow some
31709conventions:
31710
31711@itemize @bullet
31712@item
31713The name must not contain commas, colons or semicolons.
31714@item
31715Most @value{GDBN} query and set packets have a leading upper case
31716letter.
31717@item
31718The names of custom vendor packets should use a company prefix, in
31719lower case, followed by a period. For example, packets designed at
31720the Acme Corporation might begin with @samp{qacme.foo} (for querying
31721foos) or @samp{Qacme.bar} (for setting bars).
31722@end itemize
31723
aa56d27a
JB
31724The name of a query or set packet should be separated from any
31725parameters by a @samp{:}; the parameters themselves should be
31726separated by @samp{,} or @samp{;}. Stubs must be careful to match the
369af7bd
DJ
31727full packet name, and check for a separator or the end of the packet,
31728in case two packet names share a common prefix. New packets should not begin
31729with @samp{qC}, @samp{qP}, or @samp{qL}@footnote{The @samp{qP} and @samp{qL}
31730packets predate these conventions, and have arguments without any terminator
31731for the packet name; we suspect they are in widespread use in places that
31732are difficult to upgrade. The @samp{qC} packet has no arguments, but some
31733existing stubs (e.g.@: RedBoot) are known to not check for the end of the
31734packet.}.
c906108c 31735
b8ff78ce
JB
31736Like the descriptions of the other packets, each description here
31737has a template showing the packet's overall syntax, followed by an
31738explanation of the packet's meaning. We include spaces in some of the
31739templates for clarity; these are not part of the packet's syntax. No
31740@value{GDBN} packet uses spaces to separate its components.
31741
5f3bebba
JB
31742Here are the currently defined query and set packets:
31743
b8ff78ce 31744@table @samp
c906108c 31745
d914c394
SS
31746@item QAllow:@var{op}:@var{val}@dots{}
31747@cindex @samp{QAllow} packet
31748Specify which operations @value{GDBN} expects to request of the
31749target, as a semicolon-separated list of operation name and value
31750pairs. Possible values for @var{op} include @samp{WriteReg},
31751@samp{WriteMem}, @samp{InsertBreak}, @samp{InsertTrace},
31752@samp{InsertFastTrace}, and @samp{Stop}. @var{val} is either 0,
31753indicating that @value{GDBN} will not request the operation, or 1,
31754indicating that it may. (The target can then use this to set up its
31755own internals optimally, for instance if the debugger never expects to
31756insert breakpoints, it may not need to install its own trap handler.)
31757
b8ff78ce 31758@item qC
9c16f35a 31759@cindex current thread, remote request
b8ff78ce 31760@cindex @samp{qC} packet
b90a069a 31761Return the current thread ID.
ee2d5c50
AC
31762
31763Reply:
31764@table @samp
b90a069a
SL
31765@item QC @var{thread-id}
31766Where @var{thread-id} is a thread ID as documented in
31767@ref{thread-id syntax}.
b8ff78ce 31768@item @r{(anything else)}
b90a069a 31769Any other reply implies the old thread ID.
ee2d5c50
AC
31770@end table
31771
b8ff78ce 31772@item qCRC:@var{addr},@var{length}
ff2587ec 31773@cindex CRC of memory block, remote request
b8ff78ce 31774@cindex @samp{qCRC} packet
99e008fe
EZ
31775Compute the CRC checksum of a block of memory using CRC-32 defined in
31776IEEE 802.3. The CRC is computed byte at a time, taking the most
31777significant bit of each byte first. The initial pattern code
31778@code{0xffffffff} is used to ensure leading zeros affect the CRC.
31779
31780@emph{Note:} This is the same CRC used in validating separate debug
31781files (@pxref{Separate Debug Files, , Debugging Information in Separate
31782Files}). However the algorithm is slightly different. When validating
31783separate debug files, the CRC is computed taking the @emph{least}
31784significant bit of each byte first, and the final result is inverted to
31785detect trailing zeros.
31786
ff2587ec
WZ
31787Reply:
31788@table @samp
b8ff78ce 31789@item E @var{NN}
ff2587ec 31790An error (such as memory fault)
b8ff78ce
JB
31791@item C @var{crc32}
31792The specified memory region's checksum is @var{crc32}.
ff2587ec
WZ
31793@end table
31794
b8ff78ce
JB
31795@item qfThreadInfo
31796@itemx qsThreadInfo
9c16f35a 31797@cindex list active threads, remote request
b8ff78ce
JB
31798@cindex @samp{qfThreadInfo} packet
31799@cindex @samp{qsThreadInfo} packet
b90a069a 31800Obtain a list of all active thread IDs from the target (OS). Since there
8e04817f
AC
31801may be too many active threads to fit into one reply packet, this query
31802works iteratively: it may require more than one query/reply sequence to
31803obtain the entire list of threads. The first query of the sequence will
b8ff78ce
JB
31804be the @samp{qfThreadInfo} query; subsequent queries in the
31805sequence will be the @samp{qsThreadInfo} query.
ee2d5c50 31806
b8ff78ce 31807NOTE: This packet replaces the @samp{qL} query (see below).
ee2d5c50
AC
31808
31809Reply:
31810@table @samp
b90a069a
SL
31811@item m @var{thread-id}
31812A single thread ID
31813@item m @var{thread-id},@var{thread-id}@dots{}
31814a comma-separated list of thread IDs
b8ff78ce
JB
31815@item l
31816(lower case letter @samp{L}) denotes end of list.
ee2d5c50
AC
31817@end table
31818
31819In response to each query, the target will reply with a list of one or
b90a069a 31820more thread IDs, separated by commas.
e1aac25b 31821@value{GDBN} will respond to each reply with a request for more thread
b8ff78ce 31822ids (using the @samp{qs} form of the query), until the target responds
501994c0 31823with @samp{l} (lower-case ell, for @dfn{last}).
b90a069a
SL
31824Refer to @ref{thread-id syntax}, for the format of the @var{thread-id}
31825fields.
c906108c 31826
b8ff78ce 31827@item qGetTLSAddr:@var{thread-id},@var{offset},@var{lm}
ff2587ec 31828@cindex get thread-local storage address, remote request
b8ff78ce 31829@cindex @samp{qGetTLSAddr} packet
ff2587ec
WZ
31830Fetch the address associated with thread local storage specified
31831by @var{thread-id}, @var{offset}, and @var{lm}.
31832
b90a069a
SL
31833@var{thread-id} is the thread ID associated with the
31834thread for which to fetch the TLS address. @xref{thread-id syntax}.
ff2587ec
WZ
31835
31836@var{offset} is the (big endian, hex encoded) offset associated with the
31837thread local variable. (This offset is obtained from the debug
31838information associated with the variable.)
31839
db2e3e2e 31840@var{lm} is the (big endian, hex encoded) OS/ABI-specific encoding of the
ff2587ec
WZ
31841the load module associated with the thread local storage. For example,
31842a @sc{gnu}/Linux system will pass the link map address of the shared
31843object associated with the thread local storage under consideration.
31844Other operating environments may choose to represent the load module
31845differently, so the precise meaning of this parameter will vary.
ee2d5c50
AC
31846
31847Reply:
b8ff78ce
JB
31848@table @samp
31849@item @var{XX}@dots{}
ff2587ec
WZ
31850Hex encoded (big endian) bytes representing the address of the thread
31851local storage requested.
31852
b8ff78ce
JB
31853@item E @var{nn}
31854An error occurred. @var{nn} are hex digits.
ff2587ec 31855
b8ff78ce
JB
31856@item
31857An empty reply indicates that @samp{qGetTLSAddr} is not supported by the stub.
ee2d5c50
AC
31858@end table
31859
711e434b
PM
31860@item qGetTIBAddr:@var{thread-id}
31861@cindex get thread information block address
31862@cindex @samp{qGetTIBAddr} packet
31863Fetch address of the Windows OS specific Thread Information Block.
31864
31865@var{thread-id} is the thread ID associated with the thread.
31866
31867Reply:
31868@table @samp
31869@item @var{XX}@dots{}
31870Hex encoded (big endian) bytes representing the linear address of the
31871thread information block.
31872
31873@item E @var{nn}
31874An error occured. This means that either the thread was not found, or the
31875address could not be retrieved.
31876
31877@item
31878An empty reply indicates that @samp{qGetTIBAddr} is not supported by the stub.
31879@end table
31880
b8ff78ce 31881@item qL @var{startflag} @var{threadcount} @var{nextthread}
8e04817f
AC
31882Obtain thread information from RTOS. Where: @var{startflag} (one hex
31883digit) is one to indicate the first query and zero to indicate a
31884subsequent query; @var{threadcount} (two hex digits) is the maximum
31885number of threads the response packet can contain; and @var{nextthread}
31886(eight hex digits), for subsequent queries (@var{startflag} is zero), is
31887returned in the response as @var{argthread}.
ee2d5c50 31888
b8ff78ce 31889Don't use this packet; use the @samp{qfThreadInfo} query instead (see above).
ee2d5c50
AC
31890
31891Reply:
31892@table @samp
b8ff78ce 31893@item qM @var{count} @var{done} @var{argthread} @var{thread}@dots{}
8e04817f
AC
31894Where: @var{count} (two hex digits) is the number of threads being
31895returned; @var{done} (one hex digit) is zero to indicate more threads
31896and one indicates no further threads; @var{argthreadid} (eight hex
b8ff78ce 31897digits) is @var{nextthread} from the request packet; @var{thread}@dots{}
ee2d5c50 31898is a sequence of thread IDs from the target. @var{threadid} (eight hex
8e04817f 31899digits). See @code{remote.c:parse_threadlist_response()}.
ee2d5c50 31900@end table
c906108c 31901
b8ff78ce 31902@item qOffsets
9c16f35a 31903@cindex section offsets, remote request
b8ff78ce 31904@cindex @samp{qOffsets} packet
31d99776
DJ
31905Get section offsets that the target used when relocating the downloaded
31906image.
c906108c 31907
ee2d5c50
AC
31908Reply:
31909@table @samp
31d99776
DJ
31910@item Text=@var{xxx};Data=@var{yyy}@r{[};Bss=@var{zzz}@r{]}
31911Relocate the @code{Text} section by @var{xxx} from its original address.
31912Relocate the @code{Data} section by @var{yyy} from its original address.
31913If the object file format provides segment information (e.g.@: @sc{elf}
31914@samp{PT_LOAD} program headers), @value{GDBN} will relocate entire
31915segments by the supplied offsets.
31916
31917@emph{Note: while a @code{Bss} offset may be included in the response,
31918@value{GDBN} ignores this and instead applies the @code{Data} offset
31919to the @code{Bss} section.}
31920
31921@item TextSeg=@var{xxx}@r{[};DataSeg=@var{yyy}@r{]}
31922Relocate the first segment of the object file, which conventionally
31923contains program code, to a starting address of @var{xxx}. If
31924@samp{DataSeg} is specified, relocate the second segment, which
31925conventionally contains modifiable data, to a starting address of
31926@var{yyy}. @value{GDBN} will report an error if the object file
31927does not contain segment information, or does not contain at least
31928as many segments as mentioned in the reply. Extra segments are
31929kept at fixed offsets relative to the last relocated segment.
ee2d5c50
AC
31930@end table
31931
b90a069a 31932@item qP @var{mode} @var{thread-id}
9c16f35a 31933@cindex thread information, remote request
b8ff78ce 31934@cindex @samp{qP} packet
b90a069a
SL
31935Returns information on @var{thread-id}. Where: @var{mode} is a hex
31936encoded 32 bit mode; @var{thread-id} is a thread ID
31937(@pxref{thread-id syntax}).
ee2d5c50 31938
aa56d27a
JB
31939Don't use this packet; use the @samp{qThreadExtraInfo} query instead
31940(see below).
31941
b8ff78ce 31942Reply: see @code{remote.c:remote_unpack_thread_info_response()}.
c906108c 31943
8b23ecc4
SL
31944@item QNonStop:1
31945@item QNonStop:0
31946@cindex non-stop mode, remote request
31947@cindex @samp{QNonStop} packet
31948@anchor{QNonStop}
31949Enter non-stop (@samp{QNonStop:1}) or all-stop (@samp{QNonStop:0}) mode.
31950@xref{Remote Non-Stop}, for more information.
31951
31952Reply:
31953@table @samp
31954@item OK
31955The request succeeded.
31956
31957@item E @var{nn}
31958An error occurred. @var{nn} are hex digits.
31959
31960@item
31961An empty reply indicates that @samp{QNonStop} is not supported by
31962the stub.
31963@end table
31964
31965This packet is not probed by default; the remote stub must request it,
31966by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
31967Use of this packet is controlled by the @code{set non-stop} command;
31968@pxref{Non-Stop Mode}.
31969
89be2091
DJ
31970@item QPassSignals: @var{signal} @r{[};@var{signal}@r{]}@dots{}
31971@cindex pass signals to inferior, remote request
31972@cindex @samp{QPassSignals} packet
23181151 31973@anchor{QPassSignals}
89be2091
DJ
31974Each listed @var{signal} should be passed directly to the inferior process.
31975Signals are numbered identically to continue packets and stop replies
31976(@pxref{Stop Reply Packets}). Each @var{signal} list item should be
31977strictly greater than the previous item. These signals do not need to stop
31978the inferior, or be reported to @value{GDBN}. All other signals should be
31979reported to @value{GDBN}. Multiple @samp{QPassSignals} packets do not
31980combine; any earlier @samp{QPassSignals} list is completely replaced by the
31981new list. This packet improves performance when using @samp{handle
31982@var{signal} nostop noprint pass}.
31983
31984Reply:
31985@table @samp
31986@item OK
31987The request succeeded.
31988
31989@item E @var{nn}
31990An error occurred. @var{nn} are hex digits.
31991
31992@item
31993An empty reply indicates that @samp{QPassSignals} is not supported by
31994the stub.
31995@end table
31996
31997Use of this packet is controlled by the @code{set remote pass-signals}
79a6e687 31998command (@pxref{Remote Configuration, set remote pass-signals}).
89be2091
DJ
31999This packet is not probed by default; the remote stub must request it,
32000by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
32001
b8ff78ce 32002@item qRcmd,@var{command}
ff2587ec 32003@cindex execute remote command, remote request
b8ff78ce 32004@cindex @samp{qRcmd} packet
ff2587ec 32005@var{command} (hex encoded) is passed to the local interpreter for
b8ff78ce
JB
32006execution. Invalid commands should be reported using the output
32007string. Before the final result packet, the target may also respond
32008with a number of intermediate @samp{O@var{output}} console output
32009packets. @emph{Implementors should note that providing access to a
32010stubs's interpreter may have security implications}.
fa93a9d8 32011
ff2587ec
WZ
32012Reply:
32013@table @samp
32014@item OK
32015A command response with no output.
32016@item @var{OUTPUT}
32017A command response with the hex encoded output string @var{OUTPUT}.
b8ff78ce 32018@item E @var{NN}
ff2587ec 32019Indicate a badly formed request.
b8ff78ce
JB
32020@item
32021An empty reply indicates that @samp{qRcmd} is not recognized.
ff2587ec 32022@end table
fa93a9d8 32023
aa56d27a
JB
32024(Note that the @code{qRcmd} packet's name is separated from the
32025command by a @samp{,}, not a @samp{:}, contrary to the naming
32026conventions above. Please don't use this packet as a model for new
32027packets.)
32028
08388c79
DE
32029@item qSearch:memory:@var{address};@var{length};@var{search-pattern}
32030@cindex searching memory, in remote debugging
32031@cindex @samp{qSearch:memory} packet
32032@anchor{qSearch memory}
32033Search @var{length} bytes at @var{address} for @var{search-pattern}.
32034@var{address} and @var{length} are encoded in hex.
32035@var{search-pattern} is a sequence of bytes, hex encoded.
32036
32037Reply:
32038@table @samp
32039@item 0
32040The pattern was not found.
32041@item 1,address
32042The pattern was found at @var{address}.
32043@item E @var{NN}
32044A badly formed request or an error was encountered while searching memory.
32045@item
32046An empty reply indicates that @samp{qSearch:memory} is not recognized.
32047@end table
32048
a6f3e723
SL
32049@item QStartNoAckMode
32050@cindex @samp{QStartNoAckMode} packet
32051@anchor{QStartNoAckMode}
32052Request that the remote stub disable the normal @samp{+}/@samp{-}
32053protocol acknowledgments (@pxref{Packet Acknowledgment}).
32054
32055Reply:
32056@table @samp
32057@item OK
32058The stub has switched to no-acknowledgment mode.
32059@value{GDBN} acknowledges this reponse,
32060but neither the stub nor @value{GDBN} shall send or expect further
32061@samp{+}/@samp{-} acknowledgments in the current connection.
32062@item
32063An empty reply indicates that the stub does not support no-acknowledgment mode.
32064@end table
32065
be2a5f71
DJ
32066@item qSupported @r{[}:@var{gdbfeature} @r{[};@var{gdbfeature}@r{]}@dots{} @r{]}
32067@cindex supported packets, remote query
32068@cindex features of the remote protocol
32069@cindex @samp{qSupported} packet
0876f84a 32070@anchor{qSupported}
be2a5f71
DJ
32071Tell the remote stub about features supported by @value{GDBN}, and
32072query the stub for features it supports. This packet allows
32073@value{GDBN} and the remote stub to take advantage of each others'
32074features. @samp{qSupported} also consolidates multiple feature probes
32075at startup, to improve @value{GDBN} performance---a single larger
32076packet performs better than multiple smaller probe packets on
32077high-latency links. Some features may enable behavior which must not
32078be on by default, e.g.@: because it would confuse older clients or
32079stubs. Other features may describe packets which could be
32080automatically probed for, but are not. These features must be
32081reported before @value{GDBN} will use them. This ``default
32082unsupported'' behavior is not appropriate for all packets, but it
32083helps to keep the initial connection time under control with new
32084versions of @value{GDBN} which support increasing numbers of packets.
32085
32086Reply:
32087@table @samp
32088@item @var{stubfeature} @r{[};@var{stubfeature}@r{]}@dots{}
32089The stub supports or does not support each returned @var{stubfeature},
32090depending on the form of each @var{stubfeature} (see below for the
32091possible forms).
32092@item
32093An empty reply indicates that @samp{qSupported} is not recognized,
32094or that no features needed to be reported to @value{GDBN}.
32095@end table
32096
32097The allowed forms for each feature (either a @var{gdbfeature} in the
32098@samp{qSupported} packet, or a @var{stubfeature} in the response)
32099are:
32100
32101@table @samp
32102@item @var{name}=@var{value}
32103The remote protocol feature @var{name} is supported, and associated
32104with the specified @var{value}. The format of @var{value} depends
32105on the feature, but it must not include a semicolon.
32106@item @var{name}+
32107The remote protocol feature @var{name} is supported, and does not
32108need an associated value.
32109@item @var{name}-
32110The remote protocol feature @var{name} is not supported.
32111@item @var{name}?
32112The remote protocol feature @var{name} may be supported, and
32113@value{GDBN} should auto-detect support in some other way when it is
32114needed. This form will not be used for @var{gdbfeature} notifications,
32115but may be used for @var{stubfeature} responses.
32116@end table
32117
32118Whenever the stub receives a @samp{qSupported} request, the
32119supplied set of @value{GDBN} features should override any previous
32120request. This allows @value{GDBN} to put the stub in a known
32121state, even if the stub had previously been communicating with
32122a different version of @value{GDBN}.
32123
b90a069a
SL
32124The following values of @var{gdbfeature} (for the packet sent by @value{GDBN})
32125are defined:
32126
32127@table @samp
32128@item multiprocess
32129This feature indicates whether @value{GDBN} supports multiprocess
32130extensions to the remote protocol. @value{GDBN} does not use such
32131extensions unless the stub also reports that it supports them by
32132including @samp{multiprocess+} in its @samp{qSupported} reply.
32133@xref{multiprocess extensions}, for details.
c8d5aac9
L
32134
32135@item xmlRegisters
32136This feature indicates that @value{GDBN} supports the XML target
32137description. If the stub sees @samp{xmlRegisters=} with target
32138specific strings separated by a comma, it will report register
32139description.
dde08ee1
PA
32140
32141@item qRelocInsn
32142This feature indicates whether @value{GDBN} supports the
32143@samp{qRelocInsn} packet (@pxref{Tracepoint Packets,,Relocate
32144instruction reply packet}).
b90a069a
SL
32145@end table
32146
32147Stubs should ignore any unknown values for
be2a5f71
DJ
32148@var{gdbfeature}. Any @value{GDBN} which sends a @samp{qSupported}
32149packet supports receiving packets of unlimited length (earlier
b90a069a 32150versions of @value{GDBN} may reject overly long responses). Additional values
be2a5f71
DJ
32151for @var{gdbfeature} may be defined in the future to let the stub take
32152advantage of new features in @value{GDBN}, e.g.@: incompatible
b90a069a
SL
32153improvements in the remote protocol---the @samp{multiprocess} feature is
32154an example of such a feature. The stub's reply should be independent
be2a5f71
DJ
32155of the @var{gdbfeature} entries sent by @value{GDBN}; first @value{GDBN}
32156describes all the features it supports, and then the stub replies with
32157all the features it supports.
32158
32159Similarly, @value{GDBN} will silently ignore unrecognized stub feature
32160responses, as long as each response uses one of the standard forms.
32161
32162Some features are flags. A stub which supports a flag feature
32163should respond with a @samp{+} form response. Other features
32164require values, and the stub should respond with an @samp{=}
32165form response.
32166
32167Each feature has a default value, which @value{GDBN} will use if
32168@samp{qSupported} is not available or if the feature is not mentioned
32169in the @samp{qSupported} response. The default values are fixed; a
32170stub is free to omit any feature responses that match the defaults.
32171
32172Not all features can be probed, but for those which can, the probing
32173mechanism is useful: in some cases, a stub's internal
32174architecture may not allow the protocol layer to know some information
32175about the underlying target in advance. This is especially common in
32176stubs which may be configured for multiple targets.
32177
32178These are the currently defined stub features and their properties:
32179
cfa9d6d9 32180@multitable @columnfractions 0.35 0.2 0.12 0.2
be2a5f71
DJ
32181@c NOTE: The first row should be @headitem, but we do not yet require
32182@c a new enough version of Texinfo (4.7) to use @headitem.
0876f84a 32183@item Feature Name
be2a5f71
DJ
32184@tab Value Required
32185@tab Default
32186@tab Probe Allowed
32187
32188@item @samp{PacketSize}
32189@tab Yes
32190@tab @samp{-}
32191@tab No
32192
0876f84a
DJ
32193@item @samp{qXfer:auxv:read}
32194@tab No
32195@tab @samp{-}
32196@tab Yes
32197
23181151
DJ
32198@item @samp{qXfer:features:read}
32199@tab No
32200@tab @samp{-}
32201@tab Yes
32202
cfa9d6d9
DJ
32203@item @samp{qXfer:libraries:read}
32204@tab No
32205@tab @samp{-}
32206@tab Yes
32207
68437a39
DJ
32208@item @samp{qXfer:memory-map:read}
32209@tab No
32210@tab @samp{-}
32211@tab Yes
32212
0fb4aa4b
PA
32213@item @samp{qXfer:sdata:read}
32214@tab No
32215@tab @samp{-}
32216@tab Yes
32217
0e7f50da
UW
32218@item @samp{qXfer:spu:read}
32219@tab No
32220@tab @samp{-}
32221@tab Yes
32222
32223@item @samp{qXfer:spu:write}
32224@tab No
32225@tab @samp{-}
32226@tab Yes
32227
4aa995e1
PA
32228@item @samp{qXfer:siginfo:read}
32229@tab No
32230@tab @samp{-}
32231@tab Yes
32232
32233@item @samp{qXfer:siginfo:write}
32234@tab No
32235@tab @samp{-}
32236@tab Yes
32237
dc146f7c
VP
32238@item @samp{qXfer:threads:read}
32239@tab No
32240@tab @samp{-}
32241@tab Yes
32242
32243
8b23ecc4
SL
32244@item @samp{QNonStop}
32245@tab No
32246@tab @samp{-}
32247@tab Yes
32248
89be2091
DJ
32249@item @samp{QPassSignals}
32250@tab No
32251@tab @samp{-}
32252@tab Yes
32253
a6f3e723
SL
32254@item @samp{QStartNoAckMode}
32255@tab No
32256@tab @samp{-}
32257@tab Yes
32258
b90a069a
SL
32259@item @samp{multiprocess}
32260@tab No
32261@tab @samp{-}
32262@tab No
32263
782b2b07
SS
32264@item @samp{ConditionalTracepoints}
32265@tab No
32266@tab @samp{-}
32267@tab No
32268
0d772ac9
MS
32269@item @samp{ReverseContinue}
32270@tab No
2f8132f3 32271@tab @samp{-}
0d772ac9
MS
32272@tab No
32273
32274@item @samp{ReverseStep}
32275@tab No
2f8132f3 32276@tab @samp{-}
0d772ac9
MS
32277@tab No
32278
409873ef
SS
32279@item @samp{TracepointSource}
32280@tab No
32281@tab @samp{-}
32282@tab No
32283
d914c394
SS
32284@item @samp{QAllow}
32285@tab No
32286@tab @samp{-}
32287@tab No
32288
be2a5f71
DJ
32289@end multitable
32290
32291These are the currently defined stub features, in more detail:
32292
32293@table @samp
32294@cindex packet size, remote protocol
32295@item PacketSize=@var{bytes}
32296The remote stub can accept packets up to at least @var{bytes} in
32297length. @value{GDBN} will send packets up to this size for bulk
32298transfers, and will never send larger packets. This is a limit on the
32299data characters in the packet, including the frame and checksum.
32300There is no trailing NUL byte in a remote protocol packet; if the stub
32301stores packets in a NUL-terminated format, it should allow an extra
32302byte in its buffer for the NUL. If this stub feature is not supported,
32303@value{GDBN} guesses based on the size of the @samp{g} packet response.
32304
0876f84a
DJ
32305@item qXfer:auxv:read
32306The remote stub understands the @samp{qXfer:auxv:read} packet
32307(@pxref{qXfer auxiliary vector read}).
32308
23181151
DJ
32309@item qXfer:features:read
32310The remote stub understands the @samp{qXfer:features:read} packet
32311(@pxref{qXfer target description read}).
32312
cfa9d6d9
DJ
32313@item qXfer:libraries:read
32314The remote stub understands the @samp{qXfer:libraries:read} packet
32315(@pxref{qXfer library list read}).
32316
23181151
DJ
32317@item qXfer:memory-map:read
32318The remote stub understands the @samp{qXfer:memory-map:read} packet
32319(@pxref{qXfer memory map read}).
32320
0fb4aa4b
PA
32321@item qXfer:sdata:read
32322The remote stub understands the @samp{qXfer:sdata:read} packet
32323(@pxref{qXfer sdata read}).
32324
0e7f50da
UW
32325@item qXfer:spu:read
32326The remote stub understands the @samp{qXfer:spu:read} packet
32327(@pxref{qXfer spu read}).
32328
32329@item qXfer:spu:write
32330The remote stub understands the @samp{qXfer:spu:write} packet
32331(@pxref{qXfer spu write}).
32332
4aa995e1
PA
32333@item qXfer:siginfo:read
32334The remote stub understands the @samp{qXfer:siginfo:read} packet
32335(@pxref{qXfer siginfo read}).
32336
32337@item qXfer:siginfo:write
32338The remote stub understands the @samp{qXfer:siginfo:write} packet
32339(@pxref{qXfer siginfo write}).
32340
dc146f7c
VP
32341@item qXfer:threads:read
32342The remote stub understands the @samp{qXfer:threads:read} packet
32343(@pxref{qXfer threads read}).
32344
8b23ecc4
SL
32345@item QNonStop
32346The remote stub understands the @samp{QNonStop} packet
32347(@pxref{QNonStop}).
32348
23181151
DJ
32349@item QPassSignals
32350The remote stub understands the @samp{QPassSignals} packet
32351(@pxref{QPassSignals}).
32352
a6f3e723
SL
32353@item QStartNoAckMode
32354The remote stub understands the @samp{QStartNoAckMode} packet and
32355prefers to operate in no-acknowledgment mode. @xref{Packet Acknowledgment}.
32356
b90a069a
SL
32357@item multiprocess
32358@anchor{multiprocess extensions}
32359@cindex multiprocess extensions, in remote protocol
32360The remote stub understands the multiprocess extensions to the remote
32361protocol syntax. The multiprocess extensions affect the syntax of
32362thread IDs in both packets and replies (@pxref{thread-id syntax}), and
32363add process IDs to the @samp{D} packet and @samp{W} and @samp{X}
32364replies. Note that reporting this feature indicates support for the
32365syntactic extensions only, not that the stub necessarily supports
32366debugging of more than one process at a time. The stub must not use
32367multiprocess extensions in packet replies unless @value{GDBN} has also
32368indicated it supports them in its @samp{qSupported} request.
32369
07e059b5
VP
32370@item qXfer:osdata:read
32371The remote stub understands the @samp{qXfer:osdata:read} packet
32372((@pxref{qXfer osdata read}).
32373
782b2b07
SS
32374@item ConditionalTracepoints
32375The remote stub accepts and implements conditional expressions defined
32376for tracepoints (@pxref{Tracepoint Conditions}).
32377
0d772ac9
MS
32378@item ReverseContinue
32379The remote stub accepts and implements the reverse continue packet
32380(@pxref{bc}).
32381
32382@item ReverseStep
32383The remote stub accepts and implements the reverse step packet
32384(@pxref{bs}).
32385
409873ef
SS
32386@item TracepointSource
32387The remote stub understands the @samp{QTDPsrc} packet that supplies
32388the source form of tracepoint definitions.
32389
d914c394
SS
32390@item QAllow
32391The remote stub understands the @samp{QAllow} packet.
32392
0fb4aa4b
PA
32393@item StaticTracepoint
32394@cindex static tracepoints, in remote protocol
32395The remote stub supports static tracepoints.
32396
be2a5f71
DJ
32397@end table
32398
b8ff78ce 32399@item qSymbol::
ff2587ec 32400@cindex symbol lookup, remote request
b8ff78ce 32401@cindex @samp{qSymbol} packet
ff2587ec
WZ
32402Notify the target that @value{GDBN} is prepared to serve symbol lookup
32403requests. Accept requests from the target for the values of symbols.
fa93a9d8
JB
32404
32405Reply:
ff2587ec 32406@table @samp
b8ff78ce 32407@item OK
ff2587ec 32408The target does not need to look up any (more) symbols.
b8ff78ce 32409@item qSymbol:@var{sym_name}
ff2587ec
WZ
32410The target requests the value of symbol @var{sym_name} (hex encoded).
32411@value{GDBN} may provide the value by using the
b8ff78ce
JB
32412@samp{qSymbol:@var{sym_value}:@var{sym_name}} message, described
32413below.
ff2587ec 32414@end table
83761cbd 32415
b8ff78ce 32416@item qSymbol:@var{sym_value}:@var{sym_name}
ff2587ec
WZ
32417Set the value of @var{sym_name} to @var{sym_value}.
32418
32419@var{sym_name} (hex encoded) is the name of a symbol whose value the
32420target has previously requested.
32421
32422@var{sym_value} (hex) is the value for symbol @var{sym_name}. If
32423@value{GDBN} cannot supply a value for @var{sym_name}, then this field
32424will be empty.
32425
32426Reply:
32427@table @samp
b8ff78ce 32428@item OK
ff2587ec 32429The target does not need to look up any (more) symbols.
b8ff78ce 32430@item qSymbol:@var{sym_name}
ff2587ec
WZ
32431The target requests the value of a new symbol @var{sym_name} (hex
32432encoded). @value{GDBN} will continue to supply the values of symbols
32433(if available), until the target ceases to request them.
fa93a9d8 32434@end table
0abb7bc7 32435
00bf0b85 32436@item qTBuffer
4daf5ac0 32437@item QTBuffer
d5551862
SS
32438@item QTDisconnected
32439@itemx QTDP
409873ef 32440@itemx QTDPsrc
d5551862 32441@itemx QTDV
00bf0b85
SS
32442@itemx qTfP
32443@itemx qTfV
9d29849a
JB
32444@itemx QTFrame
32445@xref{Tracepoint Packets}.
32446
b90a069a 32447@item qThreadExtraInfo,@var{thread-id}
ff2587ec 32448@cindex thread attributes info, remote request
b8ff78ce
JB
32449@cindex @samp{qThreadExtraInfo} packet
32450Obtain a printable string description of a thread's attributes from
b90a069a
SL
32451the target OS. @var{thread-id} is a thread ID;
32452see @ref{thread-id syntax}. This
b8ff78ce
JB
32453string may contain anything that the target OS thinks is interesting
32454for @value{GDBN} to tell the user about the thread. The string is
32455displayed in @value{GDBN}'s @code{info threads} display. Some
32456examples of possible thread extra info strings are @samp{Runnable}, or
32457@samp{Blocked on Mutex}.
ff2587ec
WZ
32458
32459Reply:
32460@table @samp
b8ff78ce
JB
32461@item @var{XX}@dots{}
32462Where @samp{@var{XX}@dots{}} is a hex encoding of @sc{ascii} data,
32463comprising the printable string containing the extra information about
32464the thread's attributes.
ff2587ec 32465@end table
814e32d7 32466
aa56d27a
JB
32467(Note that the @code{qThreadExtraInfo} packet's name is separated from
32468the command by a @samp{,}, not a @samp{:}, contrary to the naming
32469conventions above. Please don't use this packet as a model for new
32470packets.)
32471
00bf0b85
SS
32472@item QTSave
32473@item qTsP
32474@item qTsV
d5551862 32475@itemx QTStart
9d29849a
JB
32476@itemx QTStop
32477@itemx QTinit
32478@itemx QTro
32479@itemx qTStatus
d5551862 32480@itemx qTV
0fb4aa4b
PA
32481@itemx qTfSTM
32482@itemx qTsSTM
32483@itemx qTSTMat
9d29849a
JB
32484@xref{Tracepoint Packets}.
32485
0876f84a
DJ
32486@item qXfer:@var{object}:read:@var{annex}:@var{offset},@var{length}
32487@cindex read special object, remote request
32488@cindex @samp{qXfer} packet
68437a39 32489@anchor{qXfer read}
0876f84a
DJ
32490Read uninterpreted bytes from the target's special data area
32491identified by the keyword @var{object}. Request @var{length} bytes
32492starting at @var{offset} bytes into the data. The content and
0e7f50da 32493encoding of @var{annex} is specific to @var{object}; it can supply
0876f84a
DJ
32494additional details about what data to access.
32495
32496Here are the specific requests of this form defined so far. All
32497@samp{qXfer:@var{object}:read:@dots{}} requests use the same reply
32498formats, listed below.
32499
32500@table @samp
32501@item qXfer:auxv:read::@var{offset},@var{length}
32502@anchor{qXfer auxiliary vector read}
32503Access the target's @dfn{auxiliary vector}. @xref{OS Information,
427c3a89 32504auxiliary vector}. Note @var{annex} must be empty.
0876f84a
DJ
32505
32506This packet is not probed by default; the remote stub must request it,
89be2091 32507by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
0876f84a 32508
23181151
DJ
32509@item qXfer:features:read:@var{annex}:@var{offset},@var{length}
32510@anchor{qXfer target description read}
32511Access the @dfn{target description}. @xref{Target Descriptions}. The
32512annex specifies which XML document to access. The main description is
32513always loaded from the @samp{target.xml} annex.
32514
32515This packet is not probed by default; the remote stub must request it,
32516by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
32517
cfa9d6d9
DJ
32518@item qXfer:libraries:read:@var{annex}:@var{offset},@var{length}
32519@anchor{qXfer library list read}
32520Access the target's list of loaded libraries. @xref{Library List Format}.
32521The annex part of the generic @samp{qXfer} packet must be empty
32522(@pxref{qXfer read}).
32523
32524Targets which maintain a list of libraries in the program's memory do
32525not need to implement this packet; it is designed for platforms where
32526the operating system manages the list of loaded libraries.
32527
32528This packet is not probed by default; the remote stub must request it,
32529by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
32530
68437a39
DJ
32531@item qXfer:memory-map:read::@var{offset},@var{length}
32532@anchor{qXfer memory map read}
79a6e687 32533Access the target's @dfn{memory-map}. @xref{Memory Map Format}. The
68437a39
DJ
32534annex part of the generic @samp{qXfer} packet must be empty
32535(@pxref{qXfer read}).
32536
0e7f50da
UW
32537This packet is not probed by default; the remote stub must request it,
32538by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
32539
0fb4aa4b
PA
32540@item qXfer:sdata:read::@var{offset},@var{length}
32541@anchor{qXfer sdata read}
32542
32543Read contents of the extra collected static tracepoint marker
32544information. The annex part of the generic @samp{qXfer} packet must
32545be empty (@pxref{qXfer read}). @xref{Tracepoint Actions,,Tracepoint
32546Action Lists}.
32547
32548This packet is not probed by default; the remote stub must request it,
32549by supplying an appropriate @samp{qSupported} response
32550(@pxref{qSupported}).
32551
4aa995e1
PA
32552@item qXfer:siginfo:read::@var{offset},@var{length}
32553@anchor{qXfer siginfo read}
32554Read contents of the extra signal information on the target
32555system. The annex part of the generic @samp{qXfer} packet must be
32556empty (@pxref{qXfer read}).
32557
32558This packet is not probed by default; the remote stub must request it,
32559by supplying an appropriate @samp{qSupported} response
32560(@pxref{qSupported}).
32561
0e7f50da
UW
32562@item qXfer:spu:read:@var{annex}:@var{offset},@var{length}
32563@anchor{qXfer spu read}
32564Read contents of an @code{spufs} file on the target system. The
32565annex specifies which file to read; it must be of the form
32566@file{@var{id}/@var{name}}, where @var{id} specifies an SPU context ID
32567in the target process, and @var{name} identifes the @code{spufs} file
32568in that context to be accessed.
32569
68437a39 32570This packet is not probed by default; the remote stub must request it,
07e059b5
VP
32571by supplying an appropriate @samp{qSupported} response
32572(@pxref{qSupported}).
32573
dc146f7c
VP
32574@item qXfer:threads:read::@var{offset},@var{length}
32575@anchor{qXfer threads read}
32576Access the list of threads on target. @xref{Thread List Format}. The
32577annex part of the generic @samp{qXfer} packet must be empty
32578(@pxref{qXfer read}).
32579
32580This packet is not probed by default; the remote stub must request it,
32581by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
32582
07e059b5
VP
32583@item qXfer:osdata:read::@var{offset},@var{length}
32584@anchor{qXfer osdata read}
32585Access the target's @dfn{operating system information}.
32586@xref{Operating System Information}.
32587
68437a39
DJ
32588@end table
32589
0876f84a
DJ
32590Reply:
32591@table @samp
32592@item m @var{data}
32593Data @var{data} (@pxref{Binary Data}) has been read from the
32594target. There may be more data at a higher address (although
32595it is permitted to return @samp{m} even for the last valid
32596block of data, as long as at least one byte of data was read).
32597@var{data} may have fewer bytes than the @var{length} in the
32598request.
32599
32600@item l @var{data}
32601Data @var{data} (@pxref{Binary Data}) has been read from the target.
32602There is no more data to be read. @var{data} may have fewer bytes
32603than the @var{length} in the request.
32604
32605@item l
32606The @var{offset} in the request is at the end of the data.
32607There is no more data to be read.
32608
32609@item E00
32610The request was malformed, or @var{annex} was invalid.
32611
32612@item E @var{nn}
32613The offset was invalid, or there was an error encountered reading the data.
32614@var{nn} is a hex-encoded @code{errno} value.
32615
32616@item
32617An empty reply indicates the @var{object} string was not recognized by
32618the stub, or that the object does not support reading.
32619@end table
32620
32621@item qXfer:@var{object}:write:@var{annex}:@var{offset}:@var{data}@dots{}
32622@cindex write data into object, remote request
4aa995e1 32623@anchor{qXfer write}
0876f84a
DJ
32624Write uninterpreted bytes into the target's special data area
32625identified by the keyword @var{object}, starting at @var{offset} bytes
0e7f50da 32626into the data. @var{data}@dots{} is the binary-encoded data
0876f84a 32627(@pxref{Binary Data}) to be written. The content and encoding of @var{annex}
0e7f50da 32628is specific to @var{object}; it can supply additional details about what data
0876f84a
DJ
32629to access.
32630
0e7f50da
UW
32631Here are the specific requests of this form defined so far. All
32632@samp{qXfer:@var{object}:write:@dots{}} requests use the same reply
32633formats, listed below.
32634
32635@table @samp
4aa995e1
PA
32636@item qXfer:siginfo:write::@var{offset}:@var{data}@dots{}
32637@anchor{qXfer siginfo write}
32638Write @var{data} to the extra signal information on the target system.
32639The annex part of the generic @samp{qXfer} packet must be
32640empty (@pxref{qXfer write}).
32641
32642This packet is not probed by default; the remote stub must request it,
32643by supplying an appropriate @samp{qSupported} response
32644(@pxref{qSupported}).
32645
84fcdf95 32646@item qXfer:spu:write:@var{annex}:@var{offset}:@var{data}@dots{}
0e7f50da
UW
32647@anchor{qXfer spu write}
32648Write @var{data} to an @code{spufs} file on the target system. The
32649annex specifies which file to write; it must be of the form
32650@file{@var{id}/@var{name}}, where @var{id} specifies an SPU context ID
32651in the target process, and @var{name} identifes the @code{spufs} file
32652in that context to be accessed.
32653
32654This packet is not probed by default; the remote stub must request it,
32655by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
32656@end table
0876f84a
DJ
32657
32658Reply:
32659@table @samp
32660@item @var{nn}
32661@var{nn} (hex encoded) is the number of bytes written.
32662This may be fewer bytes than supplied in the request.
32663
32664@item E00
32665The request was malformed, or @var{annex} was invalid.
32666
32667@item E @var{nn}
32668The offset was invalid, or there was an error encountered writing the data.
32669@var{nn} is a hex-encoded @code{errno} value.
32670
32671@item
32672An empty reply indicates the @var{object} string was not
32673recognized by the stub, or that the object does not support writing.
32674@end table
32675
32676@item qXfer:@var{object}:@var{operation}:@dots{}
32677Requests of this form may be added in the future. When a stub does
32678not recognize the @var{object} keyword, or its support for
32679@var{object} does not recognize the @var{operation} keyword, the stub
32680must respond with an empty packet.
32681
0b16c5cf
PA
32682@item qAttached:@var{pid}
32683@cindex query attached, remote request
32684@cindex @samp{qAttached} packet
32685Return an indication of whether the remote server attached to an
32686existing process or created a new process. When the multiprocess
32687protocol extensions are supported (@pxref{multiprocess extensions}),
32688@var{pid} is an integer in hexadecimal format identifying the target
32689process. Otherwise, @value{GDBN} will omit the @var{pid} field and
32690the query packet will be simplified as @samp{qAttached}.
32691
32692This query is used, for example, to know whether the remote process
32693should be detached or killed when a @value{GDBN} session is ended with
32694the @code{quit} command.
32695
32696Reply:
32697@table @samp
32698@item 1
32699The remote server attached to an existing process.
32700@item 0
32701The remote server created a new process.
32702@item E @var{NN}
32703A badly formed request or an error was encountered.
32704@end table
32705
ee2d5c50
AC
32706@end table
32707
a1dcb23a
DJ
32708@node Architecture-Specific Protocol Details
32709@section Architecture-Specific Protocol Details
32710
32711This section describes how the remote protocol is applied to specific
32712target architectures. Also see @ref{Standard Target Features}, for
32713details of XML target descriptions for each architecture.
32714
32715@subsection ARM
32716
32717@subsubsection Breakpoint Kinds
32718
32719These breakpoint kinds are defined for the @samp{Z0} and @samp{Z1} packets.
32720
32721@table @r
32722
32723@item 2
3272416-bit Thumb mode breakpoint.
32725
32726@item 3
3272732-bit Thumb mode (Thumb-2) breakpoint.
32728
32729@item 4
3273032-bit ARM mode breakpoint.
32731
32732@end table
32733
32734@subsection MIPS
32735
32736@subsubsection Register Packet Format
eb12ee30 32737
b8ff78ce 32738The following @code{g}/@code{G} packets have previously been defined.
ee2d5c50
AC
32739In the below, some thirty-two bit registers are transferred as
32740sixty-four bits. Those registers should be zero/sign extended (which?)
599b237a
BW
32741to fill the space allocated. Register bytes are transferred in target
32742byte order. The two nibbles within a register byte are transferred
ee2d5c50 32743most-significant - least-significant.
eb12ee30 32744
ee2d5c50 32745@table @r
eb12ee30 32746
8e04817f 32747@item MIPS32
ee2d5c50 32748
599b237a 32749All registers are transferred as thirty-two bit quantities in the order:
8e04817f
AC
3275032 general-purpose; sr; lo; hi; bad; cause; pc; 32 floating-point
32751registers; fsr; fir; fp.
eb12ee30 32752
8e04817f 32753@item MIPS64
ee2d5c50 32754
599b237a 32755All registers are transferred as sixty-four bit quantities (including
8e04817f
AC
32756thirty-two bit registers such as @code{sr}). The ordering is the same
32757as @code{MIPS32}.
eb12ee30 32758
ee2d5c50
AC
32759@end table
32760
9d29849a
JB
32761@node Tracepoint Packets
32762@section Tracepoint Packets
32763@cindex tracepoint packets
32764@cindex packets, tracepoint
32765
32766Here we describe the packets @value{GDBN} uses to implement
32767tracepoints (@pxref{Tracepoints}).
32768
32769@table @samp
32770
7a697b8d 32771@item QTDP:@var{n}:@var{addr}:@var{ena}:@var{step}:@var{pass}[:F@var{flen}][:X@var{len},@var{bytes}]@r{[}-@r{]}
9d29849a
JB
32772Create a new tracepoint, number @var{n}, at @var{addr}. If @var{ena}
32773is @samp{E}, then the tracepoint is enabled; if it is @samp{D}, then
32774the tracepoint is disabled. @var{step} is the tracepoint's step
7a697b8d
SS
32775count, and @var{pass} is its pass count. If an @samp{F} is present,
32776then the tracepoint is to be a fast tracepoint, and the @var{flen} is
32777the number of bytes that the target should copy elsewhere to make room
32778for the tracepoint. If an @samp{X} is present, it introduces a
32779tracepoint condition, which consists of a hexadecimal length, followed
32780by a comma and hex-encoded bytes, in a manner similar to action
32781encodings as described below. If the trailing @samp{-} is present,
32782further @samp{QTDP} packets will follow to specify this tracepoint's
32783actions.
9d29849a
JB
32784
32785Replies:
32786@table @samp
32787@item OK
32788The packet was understood and carried out.
dde08ee1
PA
32789@item qRelocInsn
32790@xref{Tracepoint Packets,,Relocate instruction reply packet}.
9d29849a
JB
32791@item
32792The packet was not recognized.
32793@end table
32794
32795@item QTDP:-@var{n}:@var{addr}:@r{[}S@r{]}@var{action}@dots{}@r{[}-@r{]}
32796Define actions to be taken when a tracepoint is hit. @var{n} and
32797@var{addr} must be the same as in the initial @samp{QTDP} packet for
32798this tracepoint. This packet may only be sent immediately after
32799another @samp{QTDP} packet that ended with a @samp{-}. If the
32800trailing @samp{-} is present, further @samp{QTDP} packets will follow,
32801specifying more actions for this tracepoint.
32802
32803In the series of action packets for a given tracepoint, at most one
32804can have an @samp{S} before its first @var{action}. If such a packet
32805is sent, it and the following packets define ``while-stepping''
32806actions. Any prior packets define ordinary actions --- that is, those
32807taken when the tracepoint is first hit. If no action packet has an
32808@samp{S}, then all the packets in the series specify ordinary
32809tracepoint actions.
32810
32811The @samp{@var{action}@dots{}} portion of the packet is a series of
32812actions, concatenated without separators. Each action has one of the
32813following forms:
32814
32815@table @samp
32816
32817@item R @var{mask}
32818Collect the registers whose bits are set in @var{mask}. @var{mask} is
599b237a 32819a hexadecimal number whose @var{i}'th bit is set if register number
9d29849a
JB
32820@var{i} should be collected. (The least significant bit is numbered
32821zero.) Note that @var{mask} may be any number of digits long; it may
32822not fit in a 32-bit word.
32823
32824@item M @var{basereg},@var{offset},@var{len}
32825Collect @var{len} bytes of memory starting at the address in register
32826number @var{basereg}, plus @var{offset}. If @var{basereg} is
32827@samp{-1}, then the range has a fixed address: @var{offset} is the
32828address of the lowest byte to collect. The @var{basereg},
599b237a 32829@var{offset}, and @var{len} parameters are all unsigned hexadecimal
9d29849a
JB
32830values (the @samp{-1} value for @var{basereg} is a special case).
32831
32832@item X @var{len},@var{expr}
32833Evaluate @var{expr}, whose length is @var{len}, and collect memory as
32834it directs. @var{expr} is an agent expression, as described in
32835@ref{Agent Expressions}. Each byte of the expression is encoded as a
32836two-digit hex number in the packet; @var{len} is the number of bytes
32837in the expression (and thus one-half the number of hex digits in the
32838packet).
32839
32840@end table
32841
32842Any number of actions may be packed together in a single @samp{QTDP}
32843packet, as long as the packet does not exceed the maximum packet
c1947b85
JB
32844length (400 bytes, for many stubs). There may be only one @samp{R}
32845action per tracepoint, and it must precede any @samp{M} or @samp{X}
32846actions. Any registers referred to by @samp{M} and @samp{X} actions
32847must be collected by a preceding @samp{R} action. (The
32848``while-stepping'' actions are treated as if they were attached to a
32849separate tracepoint, as far as these restrictions are concerned.)
9d29849a
JB
32850
32851Replies:
32852@table @samp
32853@item OK
32854The packet was understood and carried out.
dde08ee1
PA
32855@item qRelocInsn
32856@xref{Tracepoint Packets,,Relocate instruction reply packet}.
9d29849a
JB
32857@item
32858The packet was not recognized.
32859@end table
32860
409873ef
SS
32861@item QTDPsrc:@var{n}:@var{addr}:@var{type}:@var{start}:@var{slen}:@var{bytes}
32862@cindex @samp{QTDPsrc} packet
32863Specify a source string of tracepoint @var{n} at address @var{addr}.
32864This is useful to get accurate reproduction of the tracepoints
32865originally downloaded at the beginning of the trace run. @var{type}
32866is the name of the tracepoint part, such as @samp{cond} for the
32867tracepoint's conditional expression (see below for a list of types), while
32868@var{bytes} is the string, encoded in hexadecimal.
32869
32870@var{start} is the offset of the @var{bytes} within the overall source
32871string, while @var{slen} is the total length of the source string.
32872This is intended for handling source strings that are longer than will
32873fit in a single packet.
32874@c Add detailed example when this info is moved into a dedicated
32875@c tracepoint descriptions section.
32876
32877The available string types are @samp{at} for the location,
32878@samp{cond} for the conditional, and @samp{cmd} for an action command.
32879@value{GDBN} sends a separate packet for each command in the action
32880list, in the same order in which the commands are stored in the list.
32881
32882The target does not need to do anything with source strings except
32883report them back as part of the replies to the @samp{qTfP}/@samp{qTsP}
32884query packets.
32885
32886Although this packet is optional, and @value{GDBN} will only send it
32887if the target replies with @samp{TracepointSource} @xref{General
32888Query Packets}, it makes both disconnected tracing and trace files
32889much easier to use. Otherwise the user must be careful that the
32890tracepoints in effect while looking at trace frames are identical to
32891the ones in effect during the trace run; even a small discrepancy
32892could cause @samp{tdump} not to work, or a particular trace frame not
32893be found.
32894
f61e138d
SS
32895@item QTDV:@var{n}:@var{value}
32896@cindex define trace state variable, remote request
32897@cindex @samp{QTDV} packet
32898Create a new trace state variable, number @var{n}, with an initial
32899value of @var{value}, which is a 64-bit signed integer. Both @var{n}
32900and @var{value} are encoded as hexadecimal values. @value{GDBN} has
32901the option of not using this packet for initial values of zero; the
32902target should simply create the trace state variables as they are
32903mentioned in expressions.
32904
9d29849a
JB
32905@item QTFrame:@var{n}
32906Select the @var{n}'th tracepoint frame from the buffer, and use the
32907register and memory contents recorded there to answer subsequent
32908request packets from @value{GDBN}.
32909
32910A successful reply from the stub indicates that the stub has found the
32911requested frame. The response is a series of parts, concatenated
32912without separators, describing the frame we selected. Each part has
32913one of the following forms:
32914
32915@table @samp
32916@item F @var{f}
32917The selected frame is number @var{n} in the trace frame buffer;
599b237a 32918@var{f} is a hexadecimal number. If @var{f} is @samp{-1}, then there
9d29849a
JB
32919was no frame matching the criteria in the request packet.
32920
32921@item T @var{t}
32922The selected trace frame records a hit of tracepoint number @var{t};
599b237a 32923@var{t} is a hexadecimal number.
9d29849a
JB
32924
32925@end table
32926
32927@item QTFrame:pc:@var{addr}
32928Like @samp{QTFrame:@var{n}}, but select the first tracepoint frame after the
32929currently selected frame whose PC is @var{addr};
599b237a 32930@var{addr} is a hexadecimal number.
9d29849a
JB
32931
32932@item QTFrame:tdp:@var{t}
32933Like @samp{QTFrame:@var{n}}, but select the first tracepoint frame after the
32934currently selected frame that is a hit of tracepoint @var{t}; @var{t}
599b237a 32935is a hexadecimal number.
9d29849a
JB
32936
32937@item QTFrame:range:@var{start}:@var{end}
32938Like @samp{QTFrame:@var{n}}, but select the first tracepoint frame after the
32939currently selected frame whose PC is between @var{start} (inclusive)
081dfbf7 32940and @var{end} (inclusive); @var{start} and @var{end} are hexadecimal
9d29849a
JB
32941numbers.
32942
32943@item QTFrame:outside:@var{start}:@var{end}
32944Like @samp{QTFrame:range:@var{start}:@var{end}}, but select the first
081dfbf7 32945frame @emph{outside} the given range of addresses (exclusive).
9d29849a
JB
32946
32947@item QTStart
dde08ee1
PA
32948Begin the tracepoint experiment. Begin collecting data from
32949tracepoint hits in the trace frame buffer. This packet supports the
32950@samp{qRelocInsn} reply (@pxref{Tracepoint Packets,,Relocate
32951instruction reply packet}).
9d29849a
JB
32952
32953@item QTStop
32954End the tracepoint experiment. Stop collecting trace frames.
32955
32956@item QTinit
32957Clear the table of tracepoints, and empty the trace frame buffer.
32958
32959@item QTro:@var{start1},@var{end1}:@var{start2},@var{end2}:@dots{}
32960Establish the given ranges of memory as ``transparent''. The stub
32961will answer requests for these ranges from memory's current contents,
32962if they were not collected as part of the tracepoint hit.
32963
32964@value{GDBN} uses this to mark read-only regions of memory, like those
32965containing program code. Since these areas never change, they should
32966still have the same contents they did when the tracepoint was hit, so
32967there's no reason for the stub to refuse to provide their contents.
32968
d5551862
SS
32969@item QTDisconnected:@var{value}
32970Set the choice to what to do with the tracing run when @value{GDBN}
32971disconnects from the target. A @var{value} of 1 directs the target to
32972continue the tracing run, while 0 tells the target to stop tracing if
32973@value{GDBN} is no longer in the picture.
32974
9d29849a
JB
32975@item qTStatus
32976Ask the stub if there is a trace experiment running right now.
32977
4daf5ac0
SS
32978The reply has the form:
32979
32980@table @samp
32981
32982@item T@var{running}@r{[};@var{field}@r{]}@dots{}
32983@var{running} is a single digit @code{1} if the trace is presently
32984running, or @code{0} if not. It is followed by semicolon-separated
32985optional fields that an agent may use to report additional status.
32986
32987@end table
32988
32989If the trace is not running, the agent may report any of several
32990explanations as one of the optional fields:
32991
32992@table @samp
32993
32994@item tnotrun:0
32995No trace has been run yet.
32996
32997@item tstop:0
32998The trace was stopped by a user-originated stop command.
32999
33000@item tfull:0
33001The trace stopped because the trace buffer filled up.
33002
33003@item tdisconnected:0
33004The trace stopped because @value{GDBN} disconnected from the target.
33005
33006@item tpasscount:@var{tpnum}
33007The trace stopped because tracepoint @var{tpnum} exceeded its pass count.
33008
6c28cbf2
SS
33009@item terror:@var{text}:@var{tpnum}
33010The trace stopped because tracepoint @var{tpnum} had an error. The
33011string @var{text} is available to describe the nature of the error
33012(for instance, a divide by zero in the condition expression).
99b5e152 33013@var{text} is hex encoded.
6c28cbf2 33014
4daf5ac0
SS
33015@item tunknown:0
33016The trace stopped for some other reason.
33017
33018@end table
33019
33da3f1c
SS
33020Additional optional fields supply statistical and other information.
33021Although not required, they are extremely useful for users monitoring
33022the progress of a trace run. If a trace has stopped, and these
33023numbers are reported, they must reflect the state of the just-stopped
33024trace.
4daf5ac0 33025
9d29849a 33026@table @samp
4daf5ac0
SS
33027
33028@item tframes:@var{n}
33029The number of trace frames in the buffer.
33030
33031@item tcreated:@var{n}
33032The total number of trace frames created during the run. This may
33033be larger than the trace frame count, if the buffer is circular.
33034
33035@item tsize:@var{n}
33036The total size of the trace buffer, in bytes.
33037
33038@item tfree:@var{n}
33039The number of bytes still unused in the buffer.
33040
33da3f1c
SS
33041@item circular:@var{n}
33042The value of the circular trace buffer flag. @code{1} means that the
33043trace buffer is circular and old trace frames will be discarded if
33044necessary to make room, @code{0} means that the trace buffer is linear
33045and may fill up.
33046
33047@item disconn:@var{n}
33048The value of the disconnected tracing flag. @code{1} means that
33049tracing will continue after @value{GDBN} disconnects, @code{0} means
33050that the trace run will stop.
33051
9d29849a
JB
33052@end table
33053
f61e138d
SS
33054@item qTV:@var{var}
33055@cindex trace state variable value, remote request
33056@cindex @samp{qTV} packet
33057Ask the stub for the value of the trace state variable number @var{var}.
33058
33059Replies:
33060@table @samp
33061@item V@var{value}
33062The value of the variable is @var{value}. This will be the current
33063value of the variable if the user is examining a running target, or a
33064saved value if the variable was collected in the trace frame that the
33065user is looking at. Note that multiple requests may result in
33066different reply values, such as when requesting values while the
33067program is running.
33068
33069@item U
33070The value of the variable is unknown. This would occur, for example,
33071if the user is examining a trace frame in which the requested variable
33072was not collected.
9d29849a
JB
33073@end table
33074
d5551862
SS
33075@item qTfP
33076@itemx qTsP
33077These packets request data about tracepoints that are being used by
33078the target. @value{GDBN} sends @code{qTfP} to get the first piece
33079of data, and multiple @code{qTsP} to get additional pieces. Replies
33080to these packets generally take the form of the @code{QTDP} packets
33081that define tracepoints. (FIXME add detailed syntax)
33082
00bf0b85
SS
33083@item qTfV
33084@itemx qTsV
33085These packets request data about trace state variables that are on the
33086target. @value{GDBN} sends @code{qTfV} to get the first vari of data,
33087and multiple @code{qTsV} to get additional variables. Replies to
33088these packets follow the syntax of the @code{QTDV} packets that define
33089trace state variables.
33090
0fb4aa4b
PA
33091@item qTfSTM
33092@itemx qTsSTM
33093These packets request data about static tracepoint markers that exist
33094in the target program. @value{GDBN} sends @code{qTfSTM} to get the
33095first piece of data, and multiple @code{qTsSTM} to get additional
33096pieces. Replies to these packets take the following form:
33097
33098Reply:
33099@table @samp
33100@item m @var{address}:@var{id}:@var{extra}
33101A single marker
33102@item m @var{address}:@var{id}:@var{extra},@var{address}:@var{id}:@var{extra}@dots{}
33103a comma-separated list of markers
33104@item l
33105(lower case letter @samp{L}) denotes end of list.
33106@item E @var{nn}
33107An error occurred. @var{nn} are hex digits.
33108@item
33109An empty reply indicates that the request is not supported by the
33110stub.
33111@end table
33112
33113@var{address} is encoded in hex.
33114@var{id} and @var{extra} are strings encoded in hex.
33115
33116In response to each query, the target will reply with a list of one or
33117more markers, separated by commas. @value{GDBN} will respond to each
33118reply with a request for more markers (using the @samp{qs} form of the
33119query), until the target responds with @samp{l} (lower-case ell, for
33120@dfn{last}).
33121
33122@item qTSTMat:@var{address}
33123This packets requests data about static tracepoint markers in the
33124target program at @var{address}. Replies to this packet follow the
33125syntax of the @samp{qTfSTM} and @code{qTsSTM} packets that list static
33126tracepoint markers.
33127
00bf0b85
SS
33128@item QTSave:@var{filename}
33129This packet directs the target to save trace data to the file name
33130@var{filename} in the target's filesystem. @var{filename} is encoded
33131as a hex string; the interpretation of the file name (relative vs
33132absolute, wild cards, etc) is up to the target.
33133
33134@item qTBuffer:@var{offset},@var{len}
33135Return up to @var{len} bytes of the current contents of trace buffer,
33136starting at @var{offset}. The trace buffer is treated as if it were
33137a contiguous collection of traceframes, as per the trace file format.
33138The reply consists as many hex-encoded bytes as the target can deliver
33139in a packet; it is not an error to return fewer than were asked for.
33140A reply consisting of just @code{l} indicates that no bytes are
33141available.
33142
4daf5ac0
SS
33143@item QTBuffer:circular:@var{value}
33144This packet directs the target to use a circular trace buffer if
33145@var{value} is 1, or a linear buffer if the value is 0.
33146
f61e138d 33147@end table
9d29849a 33148
dde08ee1
PA
33149@subsection Relocate instruction reply packet
33150When installing fast tracepoints in memory, the target may need to
33151relocate the instruction currently at the tracepoint address to a
33152different address in memory. For most instructions, a simple copy is
33153enough, but, for example, call instructions that implicitly push the
33154return address on the stack, and relative branches or other
33155PC-relative instructions require offset adjustment, so that the effect
33156of executing the instruction at a different address is the same as if
33157it had executed in the original location.
33158
33159In response to several of the tracepoint packets, the target may also
33160respond with a number of intermediate @samp{qRelocInsn} request
33161packets before the final result packet, to have @value{GDBN} handle
33162this relocation operation. If a packet supports this mechanism, its
33163documentation will explicitly say so. See for example the above
33164descriptions for the @samp{QTStart} and @samp{QTDP} packets. The
33165format of the request is:
33166
33167@table @samp
33168@item qRelocInsn:@var{from};@var{to}
33169
33170This requests @value{GDBN} to copy instruction at address @var{from}
33171to address @var{to}, possibly adjusted so that executing the
33172instruction at @var{to} has the same effect as executing it at
33173@var{from}. @value{GDBN} writes the adjusted instruction to target
33174memory starting at @var{to}.
33175@end table
33176
33177Replies:
33178@table @samp
33179@item qRelocInsn:@var{adjusted_size}
33180Informs the stub the relocation is complete. @var{adjusted_size} is
33181the length in bytes of resulting relocated instruction sequence.
33182@item E @var{NN}
33183A badly formed request was detected, or an error was encountered while
33184relocating the instruction.
33185@end table
33186
a6b151f1
DJ
33187@node Host I/O Packets
33188@section Host I/O Packets
33189@cindex Host I/O, remote protocol
33190@cindex file transfer, remote protocol
33191
33192The @dfn{Host I/O} packets allow @value{GDBN} to perform I/O
33193operations on the far side of a remote link. For example, Host I/O is
33194used to upload and download files to a remote target with its own
33195filesystem. Host I/O uses the same constant values and data structure
33196layout as the target-initiated File-I/O protocol. However, the
33197Host I/O packets are structured differently. The target-initiated
33198protocol relies on target memory to store parameters and buffers.
33199Host I/O requests are initiated by @value{GDBN}, and the
33200target's memory is not involved. @xref{File-I/O Remote Protocol
33201Extension}, for more details on the target-initiated protocol.
33202
33203The Host I/O request packets all encode a single operation along with
33204its arguments. They have this format:
33205
33206@table @samp
33207
33208@item vFile:@var{operation}: @var{parameter}@dots{}
33209@var{operation} is the name of the particular request; the target
33210should compare the entire packet name up to the second colon when checking
33211for a supported operation. The format of @var{parameter} depends on
33212the operation. Numbers are always passed in hexadecimal. Negative
33213numbers have an explicit minus sign (i.e.@: two's complement is not
33214used). Strings (e.g.@: filenames) are encoded as a series of
33215hexadecimal bytes. The last argument to a system call may be a
33216buffer of escaped binary data (@pxref{Binary Data}).
33217
33218@end table
33219
33220The valid responses to Host I/O packets are:
33221
33222@table @samp
33223
33224@item F @var{result} [, @var{errno}] [; @var{attachment}]
33225@var{result} is the integer value returned by this operation, usually
33226non-negative for success and -1 for errors. If an error has occured,
33227@var{errno} will be included in the result. @var{errno} will have a
33228value defined by the File-I/O protocol (@pxref{Errno Values}). For
33229operations which return data, @var{attachment} supplies the data as a
33230binary buffer. Binary buffers in response packets are escaped in the
33231normal way (@pxref{Binary Data}). See the individual packet
33232documentation for the interpretation of @var{result} and
33233@var{attachment}.
33234
33235@item
33236An empty response indicates that this operation is not recognized.
33237
33238@end table
33239
33240These are the supported Host I/O operations:
33241
33242@table @samp
33243@item vFile:open: @var{pathname}, @var{flags}, @var{mode}
33244Open a file at @var{pathname} and return a file descriptor for it, or
33245return -1 if an error occurs. @var{pathname} is a string,
33246@var{flags} is an integer indicating a mask of open flags
33247(@pxref{Open Flags}), and @var{mode} is an integer indicating a mask
33248of mode bits to use if the file is created (@pxref{mode_t Values}).
c1c25a1a 33249@xref{open}, for details of the open flags and mode values.
a6b151f1
DJ
33250
33251@item vFile:close: @var{fd}
33252Close the open file corresponding to @var{fd} and return 0, or
33253-1 if an error occurs.
33254
33255@item vFile:pread: @var{fd}, @var{count}, @var{offset}
33256Read data from the open file corresponding to @var{fd}. Up to
33257@var{count} bytes will be read from the file, starting at @var{offset}
33258relative to the start of the file. The target may read fewer bytes;
33259common reasons include packet size limits and an end-of-file
33260condition. The number of bytes read is returned. Zero should only be
33261returned for a successful read at the end of the file, or if
33262@var{count} was zero.
33263
33264The data read should be returned as a binary attachment on success.
33265If zero bytes were read, the response should include an empty binary
33266attachment (i.e.@: a trailing semicolon). The return value is the
33267number of target bytes read; the binary attachment may be longer if
33268some characters were escaped.
33269
33270@item vFile:pwrite: @var{fd}, @var{offset}, @var{data}
33271Write @var{data} (a binary buffer) to the open file corresponding
33272to @var{fd}. Start the write at @var{offset} from the start of the
33273file. Unlike many @code{write} system calls, there is no
33274separate @var{count} argument; the length of @var{data} in the
33275packet is used. @samp{vFile:write} returns the number of bytes written,
33276which may be shorter than the length of @var{data}, or -1 if an
33277error occurred.
33278
33279@item vFile:unlink: @var{pathname}
33280Delete the file at @var{pathname} on the target. Return 0,
33281or -1 if an error occurs. @var{pathname} is a string.
33282
33283@end table
33284
9a6253be
KB
33285@node Interrupts
33286@section Interrupts
33287@cindex interrupts (remote protocol)
33288
33289When a program on the remote target is running, @value{GDBN} may
9a7071a8
JB
33290attempt to interrupt it by sending a @samp{Ctrl-C}, @code{BREAK} or
33291a @code{BREAK} followed by @code{g},
33292control of which is specified via @value{GDBN}'s @samp{interrupt-sequence}.
9a6253be
KB
33293
33294The precise meaning of @code{BREAK} is defined by the transport
8775bb90
MS
33295mechanism and may, in fact, be undefined. @value{GDBN} does not
33296currently define a @code{BREAK} mechanism for any of the network
33297interfaces except for TCP, in which case @value{GDBN} sends the
33298@code{telnet} BREAK sequence.
9a6253be
KB
33299
33300@samp{Ctrl-C}, on the other hand, is defined and implemented for all
33301transport mechanisms. It is represented by sending the single byte
33302@code{0x03} without any of the usual packet overhead described in
33303the Overview section (@pxref{Overview}). When a @code{0x03} byte is
33304transmitted as part of a packet, it is considered to be packet data
33305and does @emph{not} represent an interrupt. E.g., an @samp{X} packet
0876f84a 33306(@pxref{X packet}), used for binary downloads, may include an unescaped
9a6253be
KB
33307@code{0x03} as part of its packet.
33308
9a7071a8
JB
33309@code{BREAK} followed by @code{g} is also known as Magic SysRq g.
33310When Linux kernel receives this sequence from serial port,
33311it stops execution and connects to gdb.
33312
9a6253be
KB
33313Stubs are not required to recognize these interrupt mechanisms and the
33314precise meaning associated with receipt of the interrupt is
8b23ecc4
SL
33315implementation defined. If the target supports debugging of multiple
33316threads and/or processes, it should attempt to interrupt all
33317currently-executing threads and processes.
33318If the stub is successful at interrupting the
33319running program, it should send one of the stop
33320reply packets (@pxref{Stop Reply Packets}) to @value{GDBN} as a result
33321of successfully stopping the program in all-stop mode, and a stop reply
33322for each stopped thread in non-stop mode.
33323Interrupts received while the
33324program is stopped are discarded.
33325
33326@node Notification Packets
33327@section Notification Packets
33328@cindex notification packets
33329@cindex packets, notification
33330
33331The @value{GDBN} remote serial protocol includes @dfn{notifications},
33332packets that require no acknowledgment. Both the GDB and the stub
33333may send notifications (although the only notifications defined at
33334present are sent by the stub). Notifications carry information
33335without incurring the round-trip latency of an acknowledgment, and so
33336are useful for low-impact communications where occasional packet loss
33337is not a problem.
33338
33339A notification packet has the form @samp{% @var{data} #
33340@var{checksum}}, where @var{data} is the content of the notification,
33341and @var{checksum} is a checksum of @var{data}, computed and formatted
33342as for ordinary @value{GDBN} packets. A notification's @var{data}
33343never contains @samp{$}, @samp{%} or @samp{#} characters. Upon
33344receiving a notification, the recipient sends no @samp{+} or @samp{-}
33345to acknowledge the notification's receipt or to report its corruption.
33346
33347Every notification's @var{data} begins with a name, which contains no
33348colon characters, followed by a colon character.
33349
33350Recipients should silently ignore corrupted notifications and
33351notifications they do not understand. Recipients should restart
33352timeout periods on receipt of a well-formed notification, whether or
33353not they understand it.
33354
33355Senders should only send the notifications described here when this
33356protocol description specifies that they are permitted. In the
33357future, we may extend the protocol to permit existing notifications in
33358new contexts; this rule helps older senders avoid confusing newer
33359recipients.
33360
33361(Older versions of @value{GDBN} ignore bytes received until they see
33362the @samp{$} byte that begins an ordinary packet, so new stubs may
33363transmit notifications without fear of confusing older clients. There
33364are no notifications defined for @value{GDBN} to send at the moment, but we
33365assume that most older stubs would ignore them, as well.)
33366
33367The following notification packets from the stub to @value{GDBN} are
33368defined:
33369
33370@table @samp
33371@item Stop: @var{reply}
33372Report an asynchronous stop event in non-stop mode.
33373The @var{reply} has the form of a stop reply, as
33374described in @ref{Stop Reply Packets}. Refer to @ref{Remote Non-Stop},
33375for information on how these notifications are acknowledged by
33376@value{GDBN}.
33377@end table
33378
33379@node Remote Non-Stop
33380@section Remote Protocol Support for Non-Stop Mode
33381
33382@value{GDBN}'s remote protocol supports non-stop debugging of
33383multi-threaded programs, as described in @ref{Non-Stop Mode}. If the stub
33384supports non-stop mode, it should report that to @value{GDBN} by including
33385@samp{QNonStop+} in its @samp{qSupported} response (@pxref{qSupported}).
33386
33387@value{GDBN} typically sends a @samp{QNonStop} packet only when
33388establishing a new connection with the stub. Entering non-stop mode
33389does not alter the state of any currently-running threads, but targets
33390must stop all threads in any already-attached processes when entering
33391all-stop mode. @value{GDBN} uses the @samp{?} packet as necessary to
33392probe the target state after a mode change.
33393
33394In non-stop mode, when an attached process encounters an event that
33395would otherwise be reported with a stop reply, it uses the
33396asynchronous notification mechanism (@pxref{Notification Packets}) to
33397inform @value{GDBN}. In contrast to all-stop mode, where all threads
33398in all processes are stopped when a stop reply is sent, in non-stop
33399mode only the thread reporting the stop event is stopped. That is,
33400when reporting a @samp{S} or @samp{T} response to indicate completion
33401of a step operation, hitting a breakpoint, or a fault, only the
33402affected thread is stopped; any other still-running threads continue
33403to run. When reporting a @samp{W} or @samp{X} response, all running
33404threads belonging to other attached processes continue to run.
33405
33406Only one stop reply notification at a time may be pending; if
33407additional stop events occur before @value{GDBN} has acknowledged the
33408previous notification, they must be queued by the stub for later
33409synchronous transmission in response to @samp{vStopped} packets from
33410@value{GDBN}. Because the notification mechanism is unreliable,
33411the stub is permitted to resend a stop reply notification
33412if it believes @value{GDBN} may not have received it. @value{GDBN}
33413ignores additional stop reply notifications received before it has
33414finished processing a previous notification and the stub has completed
33415sending any queued stop events.
33416
33417Otherwise, @value{GDBN} must be prepared to receive a stop reply
33418notification at any time. Specifically, they may appear when
33419@value{GDBN} is not otherwise reading input from the stub, or when
33420@value{GDBN} is expecting to read a normal synchronous response or a
33421@samp{+}/@samp{-} acknowledgment to a packet it has sent.
33422Notification packets are distinct from any other communication from
33423the stub so there is no ambiguity.
33424
33425After receiving a stop reply notification, @value{GDBN} shall
33426acknowledge it by sending a @samp{vStopped} packet (@pxref{vStopped packet})
33427as a regular, synchronous request to the stub. Such acknowledgment
33428is not required to happen immediately, as @value{GDBN} is permitted to
33429send other, unrelated packets to the stub first, which the stub should
33430process normally.
33431
33432Upon receiving a @samp{vStopped} packet, if the stub has other queued
33433stop events to report to @value{GDBN}, it shall respond by sending a
33434normal stop reply response. @value{GDBN} shall then send another
33435@samp{vStopped} packet to solicit further responses; again, it is
33436permitted to send other, unrelated packets as well which the stub
33437should process normally.
33438
33439If the stub receives a @samp{vStopped} packet and there are no
33440additional stop events to report, the stub shall return an @samp{OK}
33441response. At this point, if further stop events occur, the stub shall
33442send a new stop reply notification, @value{GDBN} shall accept the
33443notification, and the process shall be repeated.
33444
33445In non-stop mode, the target shall respond to the @samp{?} packet as
33446follows. First, any incomplete stop reply notification/@samp{vStopped}
33447sequence in progress is abandoned. The target must begin a new
33448sequence reporting stop events for all stopped threads, whether or not
33449it has previously reported those events to @value{GDBN}. The first
33450stop reply is sent as a synchronous reply to the @samp{?} packet, and
33451subsequent stop replies are sent as responses to @samp{vStopped} packets
33452using the mechanism described above. The target must not send
33453asynchronous stop reply notifications until the sequence is complete.
33454If all threads are running when the target receives the @samp{?} packet,
33455or if the target is not attached to any process, it shall respond
33456@samp{OK}.
9a6253be 33457
a6f3e723
SL
33458@node Packet Acknowledgment
33459@section Packet Acknowledgment
33460
33461@cindex acknowledgment, for @value{GDBN} remote
33462@cindex packet acknowledgment, for @value{GDBN} remote
33463By default, when either the host or the target machine receives a packet,
33464the first response expected is an acknowledgment: either @samp{+} (to indicate
33465the package was received correctly) or @samp{-} (to request retransmission).
33466This mechanism allows the @value{GDBN} remote protocol to operate over
33467unreliable transport mechanisms, such as a serial line.
33468
33469In cases where the transport mechanism is itself reliable (such as a pipe or
33470TCP connection), the @samp{+}/@samp{-} acknowledgments are redundant.
33471It may be desirable to disable them in that case to reduce communication
33472overhead, or for other reasons. This can be accomplished by means of the
33473@samp{QStartNoAckMode} packet; @pxref{QStartNoAckMode}.
33474
33475When in no-acknowledgment mode, neither the stub nor @value{GDBN} shall send or
33476expect @samp{+}/@samp{-} protocol acknowledgments. The packet
33477and response format still includes the normal checksum, as described in
33478@ref{Overview}, but the checksum may be ignored by the receiver.
33479
33480If the stub supports @samp{QStartNoAckMode} and prefers to operate in
33481no-acknowledgment mode, it should report that to @value{GDBN}
33482by including @samp{QStartNoAckMode+} in its response to @samp{qSupported};
33483@pxref{qSupported}.
33484If @value{GDBN} also supports @samp{QStartNoAckMode} and it has not been
33485disabled via the @code{set remote noack-packet off} command
33486(@pxref{Remote Configuration}),
33487@value{GDBN} may then send a @samp{QStartNoAckMode} packet to the stub.
33488Only then may the stub actually turn off packet acknowledgments.
33489@value{GDBN} sends a final @samp{+} acknowledgment of the stub's @samp{OK}
33490response, which can be safely ignored by the stub.
33491
33492Note that @code{set remote noack-packet} command only affects negotiation
33493between @value{GDBN} and the stub when subsequent connections are made;
33494it does not affect the protocol acknowledgment state for any current
33495connection.
33496Since @samp{+}/@samp{-} acknowledgments are enabled by default when a
33497new connection is established,
33498there is also no protocol request to re-enable the acknowledgments
33499for the current connection, once disabled.
33500
ee2d5c50
AC
33501@node Examples
33502@section Examples
eb12ee30 33503
8e04817f
AC
33504Example sequence of a target being re-started. Notice how the restart
33505does not get any direct output:
eb12ee30 33506
474c8240 33507@smallexample
d2c6833e
AC
33508-> @code{R00}
33509<- @code{+}
8e04817f 33510@emph{target restarts}
d2c6833e 33511-> @code{?}
8e04817f 33512<- @code{+}
d2c6833e
AC
33513<- @code{T001:1234123412341234}
33514-> @code{+}
474c8240 33515@end smallexample
eb12ee30 33516
8e04817f 33517Example sequence of a target being stepped by a single instruction:
eb12ee30 33518
474c8240 33519@smallexample
d2c6833e 33520-> @code{G1445@dots{}}
8e04817f 33521<- @code{+}
d2c6833e
AC
33522-> @code{s}
33523<- @code{+}
33524@emph{time passes}
33525<- @code{T001:1234123412341234}
8e04817f 33526-> @code{+}
d2c6833e 33527-> @code{g}
8e04817f 33528<- @code{+}
d2c6833e
AC
33529<- @code{1455@dots{}}
33530-> @code{+}
474c8240 33531@end smallexample
eb12ee30 33532
79a6e687
BW
33533@node File-I/O Remote Protocol Extension
33534@section File-I/O Remote Protocol Extension
0ce1b118
CV
33535@cindex File-I/O remote protocol extension
33536
33537@menu
33538* File-I/O Overview::
79a6e687
BW
33539* Protocol Basics::
33540* The F Request Packet::
33541* The F Reply Packet::
33542* The Ctrl-C Message::
0ce1b118 33543* Console I/O::
79a6e687 33544* List of Supported Calls::
db2e3e2e 33545* Protocol-specific Representation of Datatypes::
0ce1b118
CV
33546* Constants::
33547* File-I/O Examples::
33548@end menu
33549
33550@node File-I/O Overview
33551@subsection File-I/O Overview
33552@cindex file-i/o overview
33553
9c16f35a 33554The @dfn{File I/O remote protocol extension} (short: File-I/O) allows the
fc320d37 33555target to use the host's file system and console I/O to perform various
0ce1b118 33556system calls. System calls on the target system are translated into a
fc320d37
SL
33557remote protocol packet to the host system, which then performs the needed
33558actions and returns a response packet to the target system.
0ce1b118
CV
33559This simulates file system operations even on targets that lack file systems.
33560
fc320d37
SL
33561The protocol is defined to be independent of both the host and target systems.
33562It uses its own internal representation of datatypes and values. Both
0ce1b118 33563@value{GDBN} and the target's @value{GDBN} stub are responsible for
fc320d37
SL
33564translating the system-dependent value representations into the internal
33565protocol representations when data is transmitted.
0ce1b118 33566
fc320d37
SL
33567The communication is synchronous. A system call is possible only when
33568@value{GDBN} is waiting for a response from the @samp{C}, @samp{c}, @samp{S}
33569or @samp{s} packets. While @value{GDBN} handles the request for a system call,
0ce1b118 33570the target is stopped to allow deterministic access to the target's
fc320d37
SL
33571memory. Therefore File-I/O is not interruptible by target signals. On
33572the other hand, it is possible to interrupt File-I/O by a user interrupt
c8aa23ab 33573(@samp{Ctrl-C}) within @value{GDBN}.
0ce1b118
CV
33574
33575The target's request to perform a host system call does not finish
33576the latest @samp{C}, @samp{c}, @samp{S} or @samp{s} action. That means,
33577after finishing the system call, the target returns to continuing the
33578previous activity (continue, step). No additional continue or step
33579request from @value{GDBN} is required.
33580
33581@smallexample
f7dc1244 33582(@value{GDBP}) continue
0ce1b118
CV
33583 <- target requests 'system call X'
33584 target is stopped, @value{GDBN} executes system call
3f94c067
BW
33585 -> @value{GDBN} returns result
33586 ... target continues, @value{GDBN} returns to wait for the target
0ce1b118
CV
33587 <- target hits breakpoint and sends a Txx packet
33588@end smallexample
33589
fc320d37
SL
33590The protocol only supports I/O on the console and to regular files on
33591the host file system. Character or block special devices, pipes,
33592named pipes, sockets or any other communication method on the host
0ce1b118
CV
33593system are not supported by this protocol.
33594
8b23ecc4
SL
33595File I/O is not supported in non-stop mode.
33596
79a6e687
BW
33597@node Protocol Basics
33598@subsection Protocol Basics
0ce1b118
CV
33599@cindex protocol basics, file-i/o
33600
fc320d37
SL
33601The File-I/O protocol uses the @code{F} packet as the request as well
33602as reply packet. Since a File-I/O system call can only occur when
33603@value{GDBN} is waiting for a response from the continuing or stepping target,
33604the File-I/O request is a reply that @value{GDBN} has to expect as a result
33605of a previous @samp{C}, @samp{c}, @samp{S} or @samp{s} packet.
0ce1b118
CV
33606This @code{F} packet contains all information needed to allow @value{GDBN}
33607to call the appropriate host system call:
33608
33609@itemize @bullet
b383017d 33610@item
0ce1b118
CV
33611A unique identifier for the requested system call.
33612
33613@item
33614All parameters to the system call. Pointers are given as addresses
33615in the target memory address space. Pointers to strings are given as
b383017d 33616pointer/length pair. Numerical values are given as they are.
db2e3e2e 33617Numerical control flags are given in a protocol-specific representation.
0ce1b118
CV
33618
33619@end itemize
33620
fc320d37 33621At this point, @value{GDBN} has to perform the following actions.
0ce1b118
CV
33622
33623@itemize @bullet
b383017d 33624@item
fc320d37
SL
33625If the parameters include pointer values to data needed as input to a
33626system call, @value{GDBN} requests this data from the target with a
0ce1b118
CV
33627standard @code{m} packet request. This additional communication has to be
33628expected by the target implementation and is handled as any other @code{m}
33629packet.
33630
33631@item
33632@value{GDBN} translates all value from protocol representation to host
33633representation as needed. Datatypes are coerced into the host types.
33634
33635@item
fc320d37 33636@value{GDBN} calls the system call.
0ce1b118
CV
33637
33638@item
33639It then coerces datatypes back to protocol representation.
33640
33641@item
fc320d37
SL
33642If the system call is expected to return data in buffer space specified
33643by pointer parameters to the call, the data is transmitted to the
0ce1b118
CV
33644target using a @code{M} or @code{X} packet. This packet has to be expected
33645by the target implementation and is handled as any other @code{M} or @code{X}
33646packet.
33647
33648@end itemize
33649
33650Eventually @value{GDBN} replies with another @code{F} packet which contains all
33651necessary information for the target to continue. This at least contains
33652
33653@itemize @bullet
33654@item
33655Return value.
33656
33657@item
33658@code{errno}, if has been changed by the system call.
33659
33660@item
33661``Ctrl-C'' flag.
33662
33663@end itemize
33664
33665After having done the needed type and value coercion, the target continues
33666the latest continue or step action.
33667
79a6e687
BW
33668@node The F Request Packet
33669@subsection The @code{F} Request Packet
0ce1b118
CV
33670@cindex file-i/o request packet
33671@cindex @code{F} request packet
33672
33673The @code{F} request packet has the following format:
33674
33675@table @samp
fc320d37 33676@item F@var{call-id},@var{parameter@dots{}}
0ce1b118
CV
33677
33678@var{call-id} is the identifier to indicate the host system call to be called.
33679This is just the name of the function.
33680
fc320d37
SL
33681@var{parameter@dots{}} are the parameters to the system call.
33682Parameters are hexadecimal integer values, either the actual values in case
33683of scalar datatypes, pointers to target buffer space in case of compound
33684datatypes and unspecified memory areas, or pointer/length pairs in case
33685of string parameters. These are appended to the @var{call-id} as a
33686comma-delimited list. All values are transmitted in ASCII
33687string representation, pointer/length pairs separated by a slash.
0ce1b118 33688
b383017d 33689@end table
0ce1b118 33690
fc320d37 33691
0ce1b118 33692
79a6e687
BW
33693@node The F Reply Packet
33694@subsection The @code{F} Reply Packet
0ce1b118
CV
33695@cindex file-i/o reply packet
33696@cindex @code{F} reply packet
33697
33698The @code{F} reply packet has the following format:
33699
33700@table @samp
33701
d3bdde98 33702@item F@var{retcode},@var{errno},@var{Ctrl-C flag};@var{call-specific attachment}
0ce1b118
CV
33703
33704@var{retcode} is the return code of the system call as hexadecimal value.
33705
db2e3e2e
BW
33706@var{errno} is the @code{errno} set by the call, in protocol-specific
33707representation.
0ce1b118
CV
33708This parameter can be omitted if the call was successful.
33709
fc320d37
SL
33710@var{Ctrl-C flag} is only sent if the user requested a break. In this
33711case, @var{errno} must be sent as well, even if the call was successful.
33712The @var{Ctrl-C flag} itself consists of the character @samp{C}:
0ce1b118
CV
33713
33714@smallexample
33715F0,0,C
33716@end smallexample
33717
33718@noindent
fc320d37 33719or, if the call was interrupted before the host call has been performed:
0ce1b118
CV
33720
33721@smallexample
33722F-1,4,C
33723@end smallexample
33724
33725@noindent
db2e3e2e 33726assuming 4 is the protocol-specific representation of @code{EINTR}.
0ce1b118
CV
33727
33728@end table
33729
0ce1b118 33730
79a6e687
BW
33731@node The Ctrl-C Message
33732@subsection The @samp{Ctrl-C} Message
0ce1b118
CV
33733@cindex ctrl-c message, in file-i/o protocol
33734
c8aa23ab 33735If the @samp{Ctrl-C} flag is set in the @value{GDBN}
79a6e687 33736reply packet (@pxref{The F Reply Packet}),
fc320d37 33737the target should behave as if it had
0ce1b118 33738gotten a break message. The meaning for the target is ``system call
fc320d37 33739interrupted by @code{SIGINT}''. Consequentially, the target should actually stop
0ce1b118 33740(as with a break message) and return to @value{GDBN} with a @code{T02}
c8aa23ab 33741packet.
fc320d37
SL
33742
33743It's important for the target to know in which
33744state the system call was interrupted. There are two possible cases:
0ce1b118
CV
33745
33746@itemize @bullet
33747@item
33748The system call hasn't been performed on the host yet.
33749
33750@item
33751The system call on the host has been finished.
33752
33753@end itemize
33754
33755These two states can be distinguished by the target by the value of the
33756returned @code{errno}. If it's the protocol representation of @code{EINTR}, the system
33757call hasn't been performed. This is equivalent to the @code{EINTR} handling
33758on POSIX systems. In any other case, the target may presume that the
fc320d37 33759system call has been finished --- successfully or not --- and should behave
0ce1b118
CV
33760as if the break message arrived right after the system call.
33761
fc320d37 33762@value{GDBN} must behave reliably. If the system call has not been called
0ce1b118
CV
33763yet, @value{GDBN} may send the @code{F} reply immediately, setting @code{EINTR} as
33764@code{errno} in the packet. If the system call on the host has been finished
fc320d37
SL
33765before the user requests a break, the full action must be finished by
33766@value{GDBN}. This requires sending @code{M} or @code{X} packets as necessary.
33767The @code{F} packet may only be sent when either nothing has happened
0ce1b118
CV
33768or the full action has been completed.
33769
33770@node Console I/O
33771@subsection Console I/O
33772@cindex console i/o as part of file-i/o
33773
d3e8051b 33774By default and if not explicitly closed by the target system, the file
0ce1b118
CV
33775descriptors 0, 1 and 2 are connected to the @value{GDBN} console. Output
33776on the @value{GDBN} console is handled as any other file output operation
33777(@code{write(1, @dots{})} or @code{write(2, @dots{})}). Console input is handled
33778by @value{GDBN} so that after the target read request from file descriptor
337790 all following typing is buffered until either one of the following
33780conditions is met:
33781
33782@itemize @bullet
33783@item
c8aa23ab 33784The user types @kbd{Ctrl-c}. The behaviour is as explained above, and the
0ce1b118
CV
33785@code{read}
33786system call is treated as finished.
33787
33788@item
7f9087cb 33789The user presses @key{RET}. This is treated as end of input with a trailing
fc320d37 33790newline.
0ce1b118
CV
33791
33792@item
c8aa23ab
EZ
33793The user types @kbd{Ctrl-d}. This is treated as end of input. No trailing
33794character (neither newline nor @samp{Ctrl-D}) is appended to the input.
0ce1b118
CV
33795
33796@end itemize
33797
fc320d37
SL
33798If the user has typed more characters than fit in the buffer given to
33799the @code{read} call, the trailing characters are buffered in @value{GDBN} until
33800either another @code{read(0, @dots{})} is requested by the target, or debugging
33801is stopped at the user's request.
0ce1b118 33802
0ce1b118 33803
79a6e687
BW
33804@node List of Supported Calls
33805@subsection List of Supported Calls
0ce1b118
CV
33806@cindex list of supported file-i/o calls
33807
33808@menu
33809* open::
33810* close::
33811* read::
33812* write::
33813* lseek::
33814* rename::
33815* unlink::
33816* stat/fstat::
33817* gettimeofday::
33818* isatty::
33819* system::
33820@end menu
33821
33822@node open
33823@unnumberedsubsubsec open
33824@cindex open, file-i/o system call
33825
fc320d37
SL
33826@table @asis
33827@item Synopsis:
0ce1b118 33828@smallexample
0ce1b118
CV
33829int open(const char *pathname, int flags);
33830int open(const char *pathname, int flags, mode_t mode);
0ce1b118
CV
33831@end smallexample
33832
fc320d37
SL
33833@item Request:
33834@samp{Fopen,@var{pathptr}/@var{len},@var{flags},@var{mode}}
33835
0ce1b118 33836@noindent
fc320d37 33837@var{flags} is the bitwise @code{OR} of the following values:
0ce1b118
CV
33838
33839@table @code
b383017d 33840@item O_CREAT
0ce1b118
CV
33841If the file does not exist it will be created. The host
33842rules apply as far as file ownership and time stamps
33843are concerned.
33844
b383017d 33845@item O_EXCL
fc320d37 33846When used with @code{O_CREAT}, if the file already exists it is
0ce1b118
CV
33847an error and open() fails.
33848
b383017d 33849@item O_TRUNC
0ce1b118 33850If the file already exists and the open mode allows
fc320d37
SL
33851writing (@code{O_RDWR} or @code{O_WRONLY} is given) it will be
33852truncated to zero length.
0ce1b118 33853
b383017d 33854@item O_APPEND
0ce1b118
CV
33855The file is opened in append mode.
33856
b383017d 33857@item O_RDONLY
0ce1b118
CV
33858The file is opened for reading only.
33859
b383017d 33860@item O_WRONLY
0ce1b118
CV
33861The file is opened for writing only.
33862
b383017d 33863@item O_RDWR
0ce1b118 33864The file is opened for reading and writing.
fc320d37 33865@end table
0ce1b118
CV
33866
33867@noindent
fc320d37 33868Other bits are silently ignored.
0ce1b118 33869
0ce1b118
CV
33870
33871@noindent
fc320d37 33872@var{mode} is the bitwise @code{OR} of the following values:
0ce1b118
CV
33873
33874@table @code
b383017d 33875@item S_IRUSR
0ce1b118
CV
33876User has read permission.
33877
b383017d 33878@item S_IWUSR
0ce1b118
CV
33879User has write permission.
33880
b383017d 33881@item S_IRGRP
0ce1b118
CV
33882Group has read permission.
33883
b383017d 33884@item S_IWGRP
0ce1b118
CV
33885Group has write permission.
33886
b383017d 33887@item S_IROTH
0ce1b118
CV
33888Others have read permission.
33889
b383017d 33890@item S_IWOTH
0ce1b118 33891Others have write permission.
fc320d37 33892@end table
0ce1b118
CV
33893
33894@noindent
fc320d37 33895Other bits are silently ignored.
0ce1b118 33896
0ce1b118 33897
fc320d37
SL
33898@item Return value:
33899@code{open} returns the new file descriptor or -1 if an error
33900occurred.
0ce1b118 33901
fc320d37 33902@item Errors:
0ce1b118
CV
33903
33904@table @code
b383017d 33905@item EEXIST
fc320d37 33906@var{pathname} already exists and @code{O_CREAT} and @code{O_EXCL} were used.
0ce1b118 33907
b383017d 33908@item EISDIR
fc320d37 33909@var{pathname} refers to a directory.
0ce1b118 33910
b383017d 33911@item EACCES
0ce1b118
CV
33912The requested access is not allowed.
33913
33914@item ENAMETOOLONG
fc320d37 33915@var{pathname} was too long.
0ce1b118 33916
b383017d 33917@item ENOENT
fc320d37 33918A directory component in @var{pathname} does not exist.
0ce1b118 33919
b383017d 33920@item ENODEV
fc320d37 33921@var{pathname} refers to a device, pipe, named pipe or socket.
0ce1b118 33922
b383017d 33923@item EROFS
fc320d37 33924@var{pathname} refers to a file on a read-only filesystem and
0ce1b118
CV
33925write access was requested.
33926
b383017d 33927@item EFAULT
fc320d37 33928@var{pathname} is an invalid pointer value.
0ce1b118 33929
b383017d 33930@item ENOSPC
0ce1b118
CV
33931No space on device to create the file.
33932
b383017d 33933@item EMFILE
0ce1b118
CV
33934The process already has the maximum number of files open.
33935
b383017d 33936@item ENFILE
0ce1b118
CV
33937The limit on the total number of files open on the system
33938has been reached.
33939
b383017d 33940@item EINTR
0ce1b118
CV
33941The call was interrupted by the user.
33942@end table
33943
fc320d37
SL
33944@end table
33945
0ce1b118
CV
33946@node close
33947@unnumberedsubsubsec close
33948@cindex close, file-i/o system call
33949
fc320d37
SL
33950@table @asis
33951@item Synopsis:
0ce1b118 33952@smallexample
0ce1b118 33953int close(int fd);
fc320d37 33954@end smallexample
0ce1b118 33955
fc320d37
SL
33956@item Request:
33957@samp{Fclose,@var{fd}}
0ce1b118 33958
fc320d37
SL
33959@item Return value:
33960@code{close} returns zero on success, or -1 if an error occurred.
0ce1b118 33961
fc320d37 33962@item Errors:
0ce1b118
CV
33963
33964@table @code
b383017d 33965@item EBADF
fc320d37 33966@var{fd} isn't a valid open file descriptor.
0ce1b118 33967
b383017d 33968@item EINTR
0ce1b118
CV
33969The call was interrupted by the user.
33970@end table
33971
fc320d37
SL
33972@end table
33973
0ce1b118
CV
33974@node read
33975@unnumberedsubsubsec read
33976@cindex read, file-i/o system call
33977
fc320d37
SL
33978@table @asis
33979@item Synopsis:
0ce1b118 33980@smallexample
0ce1b118 33981int read(int fd, void *buf, unsigned int count);
fc320d37 33982@end smallexample
0ce1b118 33983
fc320d37
SL
33984@item Request:
33985@samp{Fread,@var{fd},@var{bufptr},@var{count}}
0ce1b118 33986
fc320d37 33987@item Return value:
0ce1b118
CV
33988On success, the number of bytes read is returned.
33989Zero indicates end of file. If count is zero, read
b383017d 33990returns zero as well. On error, -1 is returned.
0ce1b118 33991
fc320d37 33992@item Errors:
0ce1b118
CV
33993
33994@table @code
b383017d 33995@item EBADF
fc320d37 33996@var{fd} is not a valid file descriptor or is not open for
0ce1b118
CV
33997reading.
33998
b383017d 33999@item EFAULT
fc320d37 34000@var{bufptr} is an invalid pointer value.
0ce1b118 34001
b383017d 34002@item EINTR
0ce1b118
CV
34003The call was interrupted by the user.
34004@end table
34005
fc320d37
SL
34006@end table
34007
0ce1b118
CV
34008@node write
34009@unnumberedsubsubsec write
34010@cindex write, file-i/o system call
34011
fc320d37
SL
34012@table @asis
34013@item Synopsis:
0ce1b118 34014@smallexample
0ce1b118 34015int write(int fd, const void *buf, unsigned int count);
fc320d37 34016@end smallexample
0ce1b118 34017
fc320d37
SL
34018@item Request:
34019@samp{Fwrite,@var{fd},@var{bufptr},@var{count}}
0ce1b118 34020
fc320d37 34021@item Return value:
0ce1b118
CV
34022On success, the number of bytes written are returned.
34023Zero indicates nothing was written. On error, -1
34024is returned.
34025
fc320d37 34026@item Errors:
0ce1b118
CV
34027
34028@table @code
b383017d 34029@item EBADF
fc320d37 34030@var{fd} is not a valid file descriptor or is not open for
0ce1b118
CV
34031writing.
34032
b383017d 34033@item EFAULT
fc320d37 34034@var{bufptr} is an invalid pointer value.
0ce1b118 34035
b383017d 34036@item EFBIG
0ce1b118 34037An attempt was made to write a file that exceeds the
db2e3e2e 34038host-specific maximum file size allowed.
0ce1b118 34039
b383017d 34040@item ENOSPC
0ce1b118
CV
34041No space on device to write the data.
34042
b383017d 34043@item EINTR
0ce1b118
CV
34044The call was interrupted by the user.
34045@end table
34046
fc320d37
SL
34047@end table
34048
0ce1b118
CV
34049@node lseek
34050@unnumberedsubsubsec lseek
34051@cindex lseek, file-i/o system call
34052
fc320d37
SL
34053@table @asis
34054@item Synopsis:
0ce1b118 34055@smallexample
0ce1b118 34056long lseek (int fd, long offset, int flag);
0ce1b118
CV
34057@end smallexample
34058
fc320d37
SL
34059@item Request:
34060@samp{Flseek,@var{fd},@var{offset},@var{flag}}
34061
34062@var{flag} is one of:
0ce1b118
CV
34063
34064@table @code
b383017d 34065@item SEEK_SET
fc320d37 34066The offset is set to @var{offset} bytes.
0ce1b118 34067
b383017d 34068@item SEEK_CUR
fc320d37 34069The offset is set to its current location plus @var{offset}
0ce1b118
CV
34070bytes.
34071
b383017d 34072@item SEEK_END
fc320d37 34073The offset is set to the size of the file plus @var{offset}
0ce1b118
CV
34074bytes.
34075@end table
34076
fc320d37 34077@item Return value:
0ce1b118
CV
34078On success, the resulting unsigned offset in bytes from
34079the beginning of the file is returned. Otherwise, a
34080value of -1 is returned.
34081
fc320d37 34082@item Errors:
0ce1b118
CV
34083
34084@table @code
b383017d 34085@item EBADF
fc320d37 34086@var{fd} is not a valid open file descriptor.
0ce1b118 34087
b383017d 34088@item ESPIPE
fc320d37 34089@var{fd} is associated with the @value{GDBN} console.
0ce1b118 34090
b383017d 34091@item EINVAL
fc320d37 34092@var{flag} is not a proper value.
0ce1b118 34093
b383017d 34094@item EINTR
0ce1b118
CV
34095The call was interrupted by the user.
34096@end table
34097
fc320d37
SL
34098@end table
34099
0ce1b118
CV
34100@node rename
34101@unnumberedsubsubsec rename
34102@cindex rename, file-i/o system call
34103
fc320d37
SL
34104@table @asis
34105@item Synopsis:
0ce1b118 34106@smallexample
0ce1b118 34107int rename(const char *oldpath, const char *newpath);
fc320d37 34108@end smallexample
0ce1b118 34109
fc320d37
SL
34110@item Request:
34111@samp{Frename,@var{oldpathptr}/@var{len},@var{newpathptr}/@var{len}}
0ce1b118 34112
fc320d37 34113@item Return value:
0ce1b118
CV
34114On success, zero is returned. On error, -1 is returned.
34115
fc320d37 34116@item Errors:
0ce1b118
CV
34117
34118@table @code
b383017d 34119@item EISDIR
fc320d37 34120@var{newpath} is an existing directory, but @var{oldpath} is not a
0ce1b118
CV
34121directory.
34122
b383017d 34123@item EEXIST
fc320d37 34124@var{newpath} is a non-empty directory.
0ce1b118 34125
b383017d 34126@item EBUSY
fc320d37 34127@var{oldpath} or @var{newpath} is a directory that is in use by some
0ce1b118
CV
34128process.
34129
b383017d 34130@item EINVAL
0ce1b118
CV
34131An attempt was made to make a directory a subdirectory
34132of itself.
34133
b383017d 34134@item ENOTDIR
fc320d37
SL
34135A component used as a directory in @var{oldpath} or new
34136path is not a directory. Or @var{oldpath} is a directory
34137and @var{newpath} exists but is not a directory.
0ce1b118 34138
b383017d 34139@item EFAULT
fc320d37 34140@var{oldpathptr} or @var{newpathptr} are invalid pointer values.
0ce1b118 34141
b383017d 34142@item EACCES
0ce1b118
CV
34143No access to the file or the path of the file.
34144
34145@item ENAMETOOLONG
b383017d 34146
fc320d37 34147@var{oldpath} or @var{newpath} was too long.
0ce1b118 34148
b383017d 34149@item ENOENT
fc320d37 34150A directory component in @var{oldpath} or @var{newpath} does not exist.
0ce1b118 34151
b383017d 34152@item EROFS
0ce1b118
CV
34153The file is on a read-only filesystem.
34154
b383017d 34155@item ENOSPC
0ce1b118
CV
34156The device containing the file has no room for the new
34157directory entry.
34158
b383017d 34159@item EINTR
0ce1b118
CV
34160The call was interrupted by the user.
34161@end table
34162
fc320d37
SL
34163@end table
34164
0ce1b118
CV
34165@node unlink
34166@unnumberedsubsubsec unlink
34167@cindex unlink, file-i/o system call
34168
fc320d37
SL
34169@table @asis
34170@item Synopsis:
0ce1b118 34171@smallexample
0ce1b118 34172int unlink(const char *pathname);
fc320d37 34173@end smallexample
0ce1b118 34174
fc320d37
SL
34175@item Request:
34176@samp{Funlink,@var{pathnameptr}/@var{len}}
0ce1b118 34177
fc320d37 34178@item Return value:
0ce1b118
CV
34179On success, zero is returned. On error, -1 is returned.
34180
fc320d37 34181@item Errors:
0ce1b118
CV
34182
34183@table @code
b383017d 34184@item EACCES
0ce1b118
CV
34185No access to the file or the path of the file.
34186
b383017d 34187@item EPERM
0ce1b118
CV
34188The system does not allow unlinking of directories.
34189
b383017d 34190@item EBUSY
fc320d37 34191The file @var{pathname} cannot be unlinked because it's
0ce1b118
CV
34192being used by another process.
34193
b383017d 34194@item EFAULT
fc320d37 34195@var{pathnameptr} is an invalid pointer value.
0ce1b118
CV
34196
34197@item ENAMETOOLONG
fc320d37 34198@var{pathname} was too long.
0ce1b118 34199
b383017d 34200@item ENOENT
fc320d37 34201A directory component in @var{pathname} does not exist.
0ce1b118 34202
b383017d 34203@item ENOTDIR
0ce1b118
CV
34204A component of the path is not a directory.
34205
b383017d 34206@item EROFS
0ce1b118
CV
34207The file is on a read-only filesystem.
34208
b383017d 34209@item EINTR
0ce1b118
CV
34210The call was interrupted by the user.
34211@end table
34212
fc320d37
SL
34213@end table
34214
0ce1b118
CV
34215@node stat/fstat
34216@unnumberedsubsubsec stat/fstat
34217@cindex fstat, file-i/o system call
34218@cindex stat, file-i/o system call
34219
fc320d37
SL
34220@table @asis
34221@item Synopsis:
0ce1b118 34222@smallexample
0ce1b118
CV
34223int stat(const char *pathname, struct stat *buf);
34224int fstat(int fd, struct stat *buf);
fc320d37 34225@end smallexample
0ce1b118 34226
fc320d37
SL
34227@item Request:
34228@samp{Fstat,@var{pathnameptr}/@var{len},@var{bufptr}}@*
34229@samp{Ffstat,@var{fd},@var{bufptr}}
0ce1b118 34230
fc320d37 34231@item Return value:
0ce1b118
CV
34232On success, zero is returned. On error, -1 is returned.
34233
fc320d37 34234@item Errors:
0ce1b118
CV
34235
34236@table @code
b383017d 34237@item EBADF
fc320d37 34238@var{fd} is not a valid open file.
0ce1b118 34239
b383017d 34240@item ENOENT
fc320d37 34241A directory component in @var{pathname} does not exist or the
0ce1b118
CV
34242path is an empty string.
34243
b383017d 34244@item ENOTDIR
0ce1b118
CV
34245A component of the path is not a directory.
34246
b383017d 34247@item EFAULT
fc320d37 34248@var{pathnameptr} is an invalid pointer value.
0ce1b118 34249
b383017d 34250@item EACCES
0ce1b118
CV
34251No access to the file or the path of the file.
34252
34253@item ENAMETOOLONG
fc320d37 34254@var{pathname} was too long.
0ce1b118 34255
b383017d 34256@item EINTR
0ce1b118
CV
34257The call was interrupted by the user.
34258@end table
34259
fc320d37
SL
34260@end table
34261
0ce1b118
CV
34262@node gettimeofday
34263@unnumberedsubsubsec gettimeofday
34264@cindex gettimeofday, file-i/o system call
34265
fc320d37
SL
34266@table @asis
34267@item Synopsis:
0ce1b118 34268@smallexample
0ce1b118 34269int gettimeofday(struct timeval *tv, void *tz);
fc320d37 34270@end smallexample
0ce1b118 34271
fc320d37
SL
34272@item Request:
34273@samp{Fgettimeofday,@var{tvptr},@var{tzptr}}
0ce1b118 34274
fc320d37 34275@item Return value:
0ce1b118
CV
34276On success, 0 is returned, -1 otherwise.
34277
fc320d37 34278@item Errors:
0ce1b118
CV
34279
34280@table @code
b383017d 34281@item EINVAL
fc320d37 34282@var{tz} is a non-NULL pointer.
0ce1b118 34283
b383017d 34284@item EFAULT
fc320d37
SL
34285@var{tvptr} and/or @var{tzptr} is an invalid pointer value.
34286@end table
34287
0ce1b118
CV
34288@end table
34289
34290@node isatty
34291@unnumberedsubsubsec isatty
34292@cindex isatty, file-i/o system call
34293
fc320d37
SL
34294@table @asis
34295@item Synopsis:
0ce1b118 34296@smallexample
0ce1b118 34297int isatty(int fd);
fc320d37 34298@end smallexample
0ce1b118 34299
fc320d37
SL
34300@item Request:
34301@samp{Fisatty,@var{fd}}
0ce1b118 34302
fc320d37
SL
34303@item Return value:
34304Returns 1 if @var{fd} refers to the @value{GDBN} console, 0 otherwise.
0ce1b118 34305
fc320d37 34306@item Errors:
0ce1b118
CV
34307
34308@table @code
b383017d 34309@item EINTR
0ce1b118
CV
34310The call was interrupted by the user.
34311@end table
34312
fc320d37
SL
34313@end table
34314
34315Note that the @code{isatty} call is treated as a special case: it returns
343161 to the target if the file descriptor is attached
34317to the @value{GDBN} console, 0 otherwise. Implementing through system calls
34318would require implementing @code{ioctl} and would be more complex than
34319needed.
34320
34321
0ce1b118
CV
34322@node system
34323@unnumberedsubsubsec system
34324@cindex system, file-i/o system call
34325
fc320d37
SL
34326@table @asis
34327@item Synopsis:
0ce1b118 34328@smallexample
0ce1b118 34329int system(const char *command);
fc320d37 34330@end smallexample
0ce1b118 34331
fc320d37
SL
34332@item Request:
34333@samp{Fsystem,@var{commandptr}/@var{len}}
0ce1b118 34334
fc320d37 34335@item Return value:
5600ea19
NS
34336If @var{len} is zero, the return value indicates whether a shell is
34337available. A zero return value indicates a shell is not available.
34338For non-zero @var{len}, the value returned is -1 on error and the
34339return status of the command otherwise. Only the exit status of the
34340command is returned, which is extracted from the host's @code{system}
34341return value by calling @code{WEXITSTATUS(retval)}. In case
34342@file{/bin/sh} could not be executed, 127 is returned.
0ce1b118 34343
fc320d37 34344@item Errors:
0ce1b118
CV
34345
34346@table @code
b383017d 34347@item EINTR
0ce1b118
CV
34348The call was interrupted by the user.
34349@end table
34350
fc320d37
SL
34351@end table
34352
34353@value{GDBN} takes over the full task of calling the necessary host calls
34354to perform the @code{system} call. The return value of @code{system} on
34355the host is simplified before it's returned
34356to the target. Any termination signal information from the child process
34357is discarded, and the return value consists
34358entirely of the exit status of the called command.
34359
34360Due to security concerns, the @code{system} call is by default refused
34361by @value{GDBN}. The user has to allow this call explicitly with the
34362@code{set remote system-call-allowed 1} command.
34363
34364@table @code
34365@item set remote system-call-allowed
34366@kindex set remote system-call-allowed
34367Control whether to allow the @code{system} calls in the File I/O
34368protocol for the remote target. The default is zero (disabled).
34369
34370@item show remote system-call-allowed
34371@kindex show remote system-call-allowed
34372Show whether the @code{system} calls are allowed in the File I/O
34373protocol.
34374@end table
34375
db2e3e2e
BW
34376@node Protocol-specific Representation of Datatypes
34377@subsection Protocol-specific Representation of Datatypes
34378@cindex protocol-specific representation of datatypes, in file-i/o protocol
0ce1b118
CV
34379
34380@menu
79a6e687
BW
34381* Integral Datatypes::
34382* Pointer Values::
34383* Memory Transfer::
0ce1b118
CV
34384* struct stat::
34385* struct timeval::
34386@end menu
34387
79a6e687
BW
34388@node Integral Datatypes
34389@unnumberedsubsubsec Integral Datatypes
0ce1b118
CV
34390@cindex integral datatypes, in file-i/o protocol
34391
fc320d37
SL
34392The integral datatypes used in the system calls are @code{int},
34393@code{unsigned int}, @code{long}, @code{unsigned long},
34394@code{mode_t}, and @code{time_t}.
0ce1b118 34395
fc320d37 34396@code{int}, @code{unsigned int}, @code{mode_t} and @code{time_t} are
0ce1b118
CV
34397implemented as 32 bit values in this protocol.
34398
fc320d37 34399@code{long} and @code{unsigned long} are implemented as 64 bit types.
b383017d 34400
0ce1b118
CV
34401@xref{Limits}, for corresponding MIN and MAX values (similar to those
34402in @file{limits.h}) to allow range checking on host and target.
34403
34404@code{time_t} datatypes are defined as seconds since the Epoch.
34405
34406All integral datatypes transferred as part of a memory read or write of a
34407structured datatype e.g.@: a @code{struct stat} have to be given in big endian
34408byte order.
34409
79a6e687
BW
34410@node Pointer Values
34411@unnumberedsubsubsec Pointer Values
0ce1b118
CV
34412@cindex pointer values, in file-i/o protocol
34413
34414Pointers to target data are transmitted as they are. An exception
34415is made for pointers to buffers for which the length isn't
34416transmitted as part of the function call, namely strings. Strings
34417are transmitted as a pointer/length pair, both as hex values, e.g.@:
34418
34419@smallexample
34420@code{1aaf/12}
34421@end smallexample
34422
34423@noindent
34424which is a pointer to data of length 18 bytes at position 0x1aaf.
34425The length is defined as the full string length in bytes, including
fc320d37
SL
34426the trailing null byte. For example, the string @code{"hello world"}
34427at address 0x123456 is transmitted as
0ce1b118
CV
34428
34429@smallexample
fc320d37 34430@code{123456/d}
0ce1b118
CV
34431@end smallexample
34432
79a6e687
BW
34433@node Memory Transfer
34434@unnumberedsubsubsec Memory Transfer
fc320d37
SL
34435@cindex memory transfer, in file-i/o protocol
34436
34437Structured data which is transferred using a memory read or write (for
db2e3e2e 34438example, a @code{struct stat}) is expected to be in a protocol-specific format
fc320d37
SL
34439with all scalar multibyte datatypes being big endian. Translation to
34440this representation needs to be done both by the target before the @code{F}
34441packet is sent, and by @value{GDBN} before
34442it transfers memory to the target. Transferred pointers to structured
34443data should point to the already-coerced data at any time.
0ce1b118 34444
0ce1b118
CV
34445
34446@node struct stat
34447@unnumberedsubsubsec struct stat
34448@cindex struct stat, in file-i/o protocol
34449
fc320d37
SL
34450The buffer of type @code{struct stat} used by the target and @value{GDBN}
34451is defined as follows:
0ce1b118
CV
34452
34453@smallexample
34454struct stat @{
34455 unsigned int st_dev; /* device */
34456 unsigned int st_ino; /* inode */
34457 mode_t st_mode; /* protection */
34458 unsigned int st_nlink; /* number of hard links */
34459 unsigned int st_uid; /* user ID of owner */
34460 unsigned int st_gid; /* group ID of owner */
34461 unsigned int st_rdev; /* device type (if inode device) */
34462 unsigned long st_size; /* total size, in bytes */
34463 unsigned long st_blksize; /* blocksize for filesystem I/O */
34464 unsigned long st_blocks; /* number of blocks allocated */
34465 time_t st_atime; /* time of last access */
34466 time_t st_mtime; /* time of last modification */
34467 time_t st_ctime; /* time of last change */
34468@};
34469@end smallexample
34470
fc320d37 34471The integral datatypes conform to the definitions given in the
79a6e687 34472appropriate section (see @ref{Integral Datatypes}, for details) so this
0ce1b118
CV
34473structure is of size 64 bytes.
34474
34475The values of several fields have a restricted meaning and/or
34476range of values.
34477
fc320d37 34478@table @code
0ce1b118 34479
fc320d37
SL
34480@item st_dev
34481A value of 0 represents a file, 1 the console.
0ce1b118 34482
fc320d37
SL
34483@item st_ino
34484No valid meaning for the target. Transmitted unchanged.
0ce1b118 34485
fc320d37
SL
34486@item st_mode
34487Valid mode bits are described in @ref{Constants}. Any other
34488bits have currently no meaning for the target.
0ce1b118 34489
fc320d37
SL
34490@item st_uid
34491@itemx st_gid
34492@itemx st_rdev
34493No valid meaning for the target. Transmitted unchanged.
0ce1b118 34494
fc320d37
SL
34495@item st_atime
34496@itemx st_mtime
34497@itemx st_ctime
34498These values have a host and file system dependent
34499accuracy. Especially on Windows hosts, the file system may not
34500support exact timing values.
34501@end table
0ce1b118 34502
fc320d37
SL
34503The target gets a @code{struct stat} of the above representation and is
34504responsible for coercing it to the target representation before
0ce1b118
CV
34505continuing.
34506
fc320d37
SL
34507Note that due to size differences between the host, target, and protocol
34508representations of @code{struct stat} members, these members could eventually
0ce1b118
CV
34509get truncated on the target.
34510
34511@node struct timeval
34512@unnumberedsubsubsec struct timeval
34513@cindex struct timeval, in file-i/o protocol
34514
fc320d37 34515The buffer of type @code{struct timeval} used by the File-I/O protocol
0ce1b118
CV
34516is defined as follows:
34517
34518@smallexample
b383017d 34519struct timeval @{
0ce1b118
CV
34520 time_t tv_sec; /* second */
34521 long tv_usec; /* microsecond */
34522@};
34523@end smallexample
34524
fc320d37 34525The integral datatypes conform to the definitions given in the
79a6e687 34526appropriate section (see @ref{Integral Datatypes}, for details) so this
0ce1b118
CV
34527structure is of size 8 bytes.
34528
34529@node Constants
34530@subsection Constants
34531@cindex constants, in file-i/o protocol
34532
34533The following values are used for the constants inside of the
fc320d37 34534protocol. @value{GDBN} and target are responsible for translating these
0ce1b118
CV
34535values before and after the call as needed.
34536
34537@menu
79a6e687
BW
34538* Open Flags::
34539* mode_t Values::
34540* Errno Values::
34541* Lseek Flags::
0ce1b118
CV
34542* Limits::
34543@end menu
34544
79a6e687
BW
34545@node Open Flags
34546@unnumberedsubsubsec Open Flags
0ce1b118
CV
34547@cindex open flags, in file-i/o protocol
34548
34549All values are given in hexadecimal representation.
34550
34551@smallexample
34552 O_RDONLY 0x0
34553 O_WRONLY 0x1
34554 O_RDWR 0x2
34555 O_APPEND 0x8
34556 O_CREAT 0x200
34557 O_TRUNC 0x400
34558 O_EXCL 0x800
34559@end smallexample
34560
79a6e687
BW
34561@node mode_t Values
34562@unnumberedsubsubsec mode_t Values
0ce1b118
CV
34563@cindex mode_t values, in file-i/o protocol
34564
34565All values are given in octal representation.
34566
34567@smallexample
34568 S_IFREG 0100000
34569 S_IFDIR 040000
34570 S_IRUSR 0400
34571 S_IWUSR 0200
34572 S_IXUSR 0100
34573 S_IRGRP 040
34574 S_IWGRP 020
34575 S_IXGRP 010
34576 S_IROTH 04
34577 S_IWOTH 02
34578 S_IXOTH 01
34579@end smallexample
34580
79a6e687
BW
34581@node Errno Values
34582@unnumberedsubsubsec Errno Values
0ce1b118
CV
34583@cindex errno values, in file-i/o protocol
34584
34585All values are given in decimal representation.
34586
34587@smallexample
34588 EPERM 1
34589 ENOENT 2
34590 EINTR 4
34591 EBADF 9
34592 EACCES 13
34593 EFAULT 14
34594 EBUSY 16
34595 EEXIST 17
34596 ENODEV 19
34597 ENOTDIR 20
34598 EISDIR 21
34599 EINVAL 22
34600 ENFILE 23
34601 EMFILE 24
34602 EFBIG 27
34603 ENOSPC 28
34604 ESPIPE 29
34605 EROFS 30
34606 ENAMETOOLONG 91
34607 EUNKNOWN 9999
34608@end smallexample
34609
fc320d37 34610 @code{EUNKNOWN} is used as a fallback error value if a host system returns
0ce1b118
CV
34611 any error value not in the list of supported error numbers.
34612
79a6e687
BW
34613@node Lseek Flags
34614@unnumberedsubsubsec Lseek Flags
0ce1b118
CV
34615@cindex lseek flags, in file-i/o protocol
34616
34617@smallexample
34618 SEEK_SET 0
34619 SEEK_CUR 1
34620 SEEK_END 2
34621@end smallexample
34622
34623@node Limits
34624@unnumberedsubsubsec Limits
34625@cindex limits, in file-i/o protocol
34626
34627All values are given in decimal representation.
34628
34629@smallexample
34630 INT_MIN -2147483648
34631 INT_MAX 2147483647
34632 UINT_MAX 4294967295
34633 LONG_MIN -9223372036854775808
34634 LONG_MAX 9223372036854775807
34635 ULONG_MAX 18446744073709551615
34636@end smallexample
34637
34638@node File-I/O Examples
34639@subsection File-I/O Examples
34640@cindex file-i/o examples
34641
34642Example sequence of a write call, file descriptor 3, buffer is at target
34643address 0x1234, 6 bytes should be written:
34644
34645@smallexample
34646<- @code{Fwrite,3,1234,6}
34647@emph{request memory read from target}
34648-> @code{m1234,6}
34649<- XXXXXX
34650@emph{return "6 bytes written"}
34651-> @code{F6}
34652@end smallexample
34653
34654Example sequence of a read call, file descriptor 3, buffer is at target
34655address 0x1234, 6 bytes should be read:
34656
34657@smallexample
34658<- @code{Fread,3,1234,6}
34659@emph{request memory write to target}
34660-> @code{X1234,6:XXXXXX}
34661@emph{return "6 bytes read"}
34662-> @code{F6}
34663@end smallexample
34664
34665Example sequence of a read call, call fails on the host due to invalid
fc320d37 34666file descriptor (@code{EBADF}):
0ce1b118
CV
34667
34668@smallexample
34669<- @code{Fread,3,1234,6}
34670-> @code{F-1,9}
34671@end smallexample
34672
c8aa23ab 34673Example sequence of a read call, user presses @kbd{Ctrl-c} before syscall on
0ce1b118
CV
34674host is called:
34675
34676@smallexample
34677<- @code{Fread,3,1234,6}
34678-> @code{F-1,4,C}
34679<- @code{T02}
34680@end smallexample
34681
c8aa23ab 34682Example sequence of a read call, user presses @kbd{Ctrl-c} after syscall on
0ce1b118
CV
34683host is called:
34684
34685@smallexample
34686<- @code{Fread,3,1234,6}
34687-> @code{X1234,6:XXXXXX}
34688<- @code{T02}
34689@end smallexample
34690
cfa9d6d9
DJ
34691@node Library List Format
34692@section Library List Format
34693@cindex library list format, remote protocol
34694
34695On some platforms, a dynamic loader (e.g.@: @file{ld.so}) runs in the
34696same process as your application to manage libraries. In this case,
34697@value{GDBN} can use the loader's symbol table and normal memory
34698operations to maintain a list of shared libraries. On other
34699platforms, the operating system manages loaded libraries.
34700@value{GDBN} can not retrieve the list of currently loaded libraries
34701through memory operations, so it uses the @samp{qXfer:libraries:read}
34702packet (@pxref{qXfer library list read}) instead. The remote stub
34703queries the target's operating system and reports which libraries
34704are loaded.
34705
34706The @samp{qXfer:libraries:read} packet returns an XML document which
34707lists loaded libraries and their offsets. Each library has an
1fddbabb
PA
34708associated name and one or more segment or section base addresses,
34709which report where the library was loaded in memory.
34710
34711For the common case of libraries that are fully linked binaries, the
34712library should have a list of segments. If the target supports
34713dynamic linking of a relocatable object file, its library XML element
34714should instead include a list of allocated sections. The segment or
34715section bases are start addresses, not relocation offsets; they do not
34716depend on the library's link-time base addresses.
cfa9d6d9 34717
9cceb671
DJ
34718@value{GDBN} must be linked with the Expat library to support XML
34719library lists. @xref{Expat}.
34720
cfa9d6d9
DJ
34721A simple memory map, with one loaded library relocated by a single
34722offset, looks like this:
34723
34724@smallexample
34725<library-list>
34726 <library name="/lib/libc.so.6">
34727 <segment address="0x10000000"/>
34728 </library>
34729</library-list>
34730@end smallexample
34731
1fddbabb
PA
34732Another simple memory map, with one loaded library with three
34733allocated sections (.text, .data, .bss), looks like this:
34734
34735@smallexample
34736<library-list>
34737 <library name="sharedlib.o">
34738 <section address="0x10000000"/>
34739 <section address="0x20000000"/>
34740 <section address="0x30000000"/>
34741 </library>
34742</library-list>
34743@end smallexample
34744
cfa9d6d9
DJ
34745The format of a library list is described by this DTD:
34746
34747@smallexample
34748<!-- library-list: Root element with versioning -->
34749<!ELEMENT library-list (library)*>
34750<!ATTLIST library-list version CDATA #FIXED "1.0">
1fddbabb 34751<!ELEMENT library (segment*, section*)>
cfa9d6d9
DJ
34752<!ATTLIST library name CDATA #REQUIRED>
34753<!ELEMENT segment EMPTY>
34754<!ATTLIST segment address CDATA #REQUIRED>
1fddbabb
PA
34755<!ELEMENT section EMPTY>
34756<!ATTLIST section address CDATA #REQUIRED>
cfa9d6d9
DJ
34757@end smallexample
34758
1fddbabb
PA
34759In addition, segments and section descriptors cannot be mixed within a
34760single library element, and you must supply at least one segment or
34761section for each library.
34762
79a6e687
BW
34763@node Memory Map Format
34764@section Memory Map Format
68437a39
DJ
34765@cindex memory map format
34766
34767To be able to write into flash memory, @value{GDBN} needs to obtain a
34768memory map from the target. This section describes the format of the
34769memory map.
34770
34771The memory map is obtained using the @samp{qXfer:memory-map:read}
34772(@pxref{qXfer memory map read}) packet and is an XML document that
9cceb671
DJ
34773lists memory regions.
34774
34775@value{GDBN} must be linked with the Expat library to support XML
34776memory maps. @xref{Expat}.
34777
34778The top-level structure of the document is shown below:
68437a39
DJ
34779
34780@smallexample
34781<?xml version="1.0"?>
34782<!DOCTYPE memory-map
34783 PUBLIC "+//IDN gnu.org//DTD GDB Memory Map V1.0//EN"
34784 "http://sourceware.org/gdb/gdb-memory-map.dtd">
34785<memory-map>
34786 region...
34787</memory-map>
34788@end smallexample
34789
34790Each region can be either:
34791
34792@itemize
34793
34794@item
34795A region of RAM starting at @var{addr} and extending for @var{length}
34796bytes from there:
34797
34798@smallexample
34799<memory type="ram" start="@var{addr}" length="@var{length}"/>
34800@end smallexample
34801
34802
34803@item
34804A region of read-only memory:
34805
34806@smallexample
34807<memory type="rom" start="@var{addr}" length="@var{length}"/>
34808@end smallexample
34809
34810
34811@item
34812A region of flash memory, with erasure blocks @var{blocksize}
34813bytes in length:
34814
34815@smallexample
34816<memory type="flash" start="@var{addr}" length="@var{length}">
34817 <property name="blocksize">@var{blocksize}</property>
34818</memory>
34819@end smallexample
34820
34821@end itemize
34822
34823Regions must not overlap. @value{GDBN} assumes that areas of memory not covered
34824by the memory map are RAM, and uses the ordinary @samp{M} and @samp{X}
34825packets to write to addresses in such ranges.
34826
34827The formal DTD for memory map format is given below:
34828
34829@smallexample
34830<!-- ................................................... -->
34831<!-- Memory Map XML DTD ................................ -->
34832<!-- File: memory-map.dtd .............................. -->
34833<!-- .................................... .............. -->
34834<!-- memory-map.dtd -->
34835<!-- memory-map: Root element with versioning -->
34836<!ELEMENT memory-map (memory | property)>
34837<!ATTLIST memory-map version CDATA #FIXED "1.0.0">
34838<!ELEMENT memory (property)>
34839<!-- memory: Specifies a memory region,
34840 and its type, or device. -->
34841<!ATTLIST memory type CDATA #REQUIRED
34842 start CDATA #REQUIRED
34843 length CDATA #REQUIRED
34844 device CDATA #IMPLIED>
34845<!-- property: Generic attribute tag -->
34846<!ELEMENT property (#PCDATA | property)*>
34847<!ATTLIST property name CDATA #REQUIRED>
34848@end smallexample
34849
dc146f7c
VP
34850@node Thread List Format
34851@section Thread List Format
34852@cindex thread list format
34853
34854To efficiently update the list of threads and their attributes,
34855@value{GDBN} issues the @samp{qXfer:threads:read} packet
34856(@pxref{qXfer threads read}) and obtains the XML document with
34857the following structure:
34858
34859@smallexample
34860<?xml version="1.0"?>
34861<threads>
34862 <thread id="id" core="0">
34863 ... description ...
34864 </thread>
34865</threads>
34866@end smallexample
34867
34868Each @samp{thread} element must have the @samp{id} attribute that
34869identifies the thread (@pxref{thread-id syntax}). The
34870@samp{core} attribute, if present, specifies which processor core
34871the thread was last executing on. The content of the of @samp{thread}
34872element is interpreted as human-readable auxilliary information.
34873
f418dd93
DJ
34874@include agentexpr.texi
34875
00bf0b85
SS
34876@node Trace File Format
34877@appendix Trace File Format
34878@cindex trace file format
34879
34880The trace file comes in three parts: a header, a textual description
34881section, and a trace frame section with binary data.
34882
34883The header has the form @code{\x7fTRACE0\n}. The first byte is
34884@code{0x7f} so as to indicate that the file contains binary data,
34885while the @code{0} is a version number that may have different values
34886in the future.
34887
34888The description section consists of multiple lines of @sc{ascii} text
34889separated by newline characters (@code{0xa}). The lines may include a
34890variety of optional descriptive or context-setting information, such
34891as tracepoint definitions or register set size. @value{GDBN} will
34892ignore any line that it does not recognize. An empty line marks the end
34893of this section.
34894
34895@c FIXME add some specific types of data
34896
34897The trace frame section consists of a number of consecutive frames.
34898Each frame begins with a two-byte tracepoint number, followed by a
34899four-byte size giving the amount of data in the frame. The data in
34900the frame consists of a number of blocks, each introduced by a
34901character indicating its type (at least register, memory, and trace
34902state variable). The data in this section is raw binary, not a
34903hexadecimal or other encoding; its endianness matches the target's
34904endianness.
34905
34906@c FIXME bi-arch may require endianness/arch info in description section
34907
34908@table @code
34909@item R @var{bytes}
34910Register block. The number and ordering of bytes matches that of a
34911@code{g} packet in the remote protocol. Note that these are the
34912actual bytes, in target order and @value{GDBN} register order, not a
34913hexadecimal encoding.
34914
34915@item M @var{address} @var{length} @var{bytes}...
34916Memory block. This is a contiguous block of memory, at the 8-byte
34917address @var{address}, with a 2-byte length @var{length}, followed by
34918@var{length} bytes.
34919
34920@item V @var{number} @var{value}
34921Trace state variable block. This records the 8-byte signed value
34922@var{value} of trace state variable numbered @var{number}.
34923
34924@end table
34925
34926Future enhancements of the trace file format may include additional types
34927of blocks.
34928
23181151
DJ
34929@node Target Descriptions
34930@appendix Target Descriptions
34931@cindex target descriptions
34932
34933@strong{Warning:} target descriptions are still under active development,
34934and the contents and format may change between @value{GDBN} releases.
34935The format is expected to stabilize in the future.
34936
34937One of the challenges of using @value{GDBN} to debug embedded systems
34938is that there are so many minor variants of each processor
34939architecture in use. It is common practice for vendors to start with
34940a standard processor core --- ARM, PowerPC, or MIPS, for example ---
34941and then make changes to adapt it to a particular market niche. Some
34942architectures have hundreds of variants, available from dozens of
34943vendors. This leads to a number of problems:
34944
34945@itemize @bullet
34946@item
34947With so many different customized processors, it is difficult for
34948the @value{GDBN} maintainers to keep up with the changes.
34949@item
34950Since individual variants may have short lifetimes or limited
34951audiences, it may not be worthwhile to carry information about every
34952variant in the @value{GDBN} source tree.
34953@item
34954When @value{GDBN} does support the architecture of the embedded system
34955at hand, the task of finding the correct architecture name to give the
34956@command{set architecture} command can be error-prone.
34957@end itemize
34958
34959To address these problems, the @value{GDBN} remote protocol allows a
34960target system to not only identify itself to @value{GDBN}, but to
34961actually describe its own features. This lets @value{GDBN} support
34962processor variants it has never seen before --- to the extent that the
34963descriptions are accurate, and that @value{GDBN} understands them.
34964
9cceb671
DJ
34965@value{GDBN} must be linked with the Expat library to support XML
34966target descriptions. @xref{Expat}.
123dc839 34967
23181151
DJ
34968@menu
34969* Retrieving Descriptions:: How descriptions are fetched from a target.
34970* Target Description Format:: The contents of a target description.
123dc839
DJ
34971* Predefined Target Types:: Standard types available for target
34972 descriptions.
34973* Standard Target Features:: Features @value{GDBN} knows about.
23181151
DJ
34974@end menu
34975
34976@node Retrieving Descriptions
34977@section Retrieving Descriptions
34978
34979Target descriptions can be read from the target automatically, or
34980specified by the user manually. The default behavior is to read the
34981description from the target. @value{GDBN} retrieves it via the remote
34982protocol using @samp{qXfer} requests (@pxref{General Query Packets,
34983qXfer}). The @var{annex} in the @samp{qXfer} packet will be
34984@samp{target.xml}. The contents of the @samp{target.xml} annex are an
34985XML document, of the form described in @ref{Target Description
34986Format}.
34987
34988Alternatively, you can specify a file to read for the target description.
34989If a file is set, the target will not be queried. The commands to
34990specify a file are:
34991
34992@table @code
34993@cindex set tdesc filename
34994@item set tdesc filename @var{path}
34995Read the target description from @var{path}.
34996
34997@cindex unset tdesc filename
34998@item unset tdesc filename
34999Do not read the XML target description from a file. @value{GDBN}
35000will use the description supplied by the current target.
35001
35002@cindex show tdesc filename
35003@item show tdesc filename
35004Show the filename to read for a target description, if any.
35005@end table
35006
35007
35008@node Target Description Format
35009@section Target Description Format
35010@cindex target descriptions, XML format
35011
35012A target description annex is an @uref{http://www.w3.org/XML/, XML}
35013document which complies with the Document Type Definition provided in
35014the @value{GDBN} sources in @file{gdb/features/gdb-target.dtd}. This
35015means you can use generally available tools like @command{xmllint} to
35016check that your feature descriptions are well-formed and valid.
35017However, to help people unfamiliar with XML write descriptions for
35018their targets, we also describe the grammar here.
35019
123dc839
DJ
35020Target descriptions can identify the architecture of the remote target
35021and (for some architectures) provide information about custom register
08d16641
PA
35022sets. They can also identify the OS ABI of the remote target.
35023@value{GDBN} can use this information to autoconfigure for your
123dc839 35024target, or to warn you if you connect to an unsupported target.
23181151
DJ
35025
35026Here is a simple target description:
35027
123dc839 35028@smallexample
1780a0ed 35029<target version="1.0">
23181151
DJ
35030 <architecture>i386:x86-64</architecture>
35031</target>
123dc839 35032@end smallexample
23181151
DJ
35033
35034@noindent
35035This minimal description only says that the target uses
35036the x86-64 architecture.
35037
123dc839
DJ
35038A target description has the following overall form, with [ ] marking
35039optional elements and @dots{} marking repeatable elements. The elements
35040are explained further below.
23181151 35041
123dc839 35042@smallexample
23181151
DJ
35043<?xml version="1.0"?>
35044<!DOCTYPE target SYSTEM "gdb-target.dtd">
1780a0ed 35045<target version="1.0">
123dc839 35046 @r{[}@var{architecture}@r{]}
08d16641 35047 @r{[}@var{osabi}@r{]}
e35359c5 35048 @r{[}@var{compatible}@r{]}
123dc839 35049 @r{[}@var{feature}@dots{}@r{]}
23181151 35050</target>
123dc839 35051@end smallexample
23181151
DJ
35052
35053@noindent
35054The description is generally insensitive to whitespace and line
35055breaks, under the usual common-sense rules. The XML version
35056declaration and document type declaration can generally be omitted
35057(@value{GDBN} does not require them), but specifying them may be
1780a0ed
DJ
35058useful for XML validation tools. The @samp{version} attribute for
35059@samp{<target>} may also be omitted, but we recommend
35060including it; if future versions of @value{GDBN} use an incompatible
35061revision of @file{gdb-target.dtd}, they will detect and report
35062the version mismatch.
23181151 35063
108546a0
DJ
35064@subsection Inclusion
35065@cindex target descriptions, inclusion
35066@cindex XInclude
35067@ifnotinfo
35068@cindex <xi:include>
35069@end ifnotinfo
35070
35071It can sometimes be valuable to split a target description up into
35072several different annexes, either for organizational purposes, or to
35073share files between different possible target descriptions. You can
35074divide a description into multiple files by replacing any element of
35075the target description with an inclusion directive of the form:
35076
123dc839 35077@smallexample
108546a0 35078<xi:include href="@var{document}"/>
123dc839 35079@end smallexample
108546a0
DJ
35080
35081@noindent
35082When @value{GDBN} encounters an element of this form, it will retrieve
35083the named XML @var{document}, and replace the inclusion directive with
35084the contents of that document. If the current description was read
35085using @samp{qXfer}, then so will be the included document;
35086@var{document} will be interpreted as the name of an annex. If the
35087current description was read from a file, @value{GDBN} will look for
35088@var{document} as a file in the same directory where it found the
35089original description.
35090
123dc839
DJ
35091@subsection Architecture
35092@cindex <architecture>
35093
35094An @samp{<architecture>} element has this form:
35095
35096@smallexample
35097 <architecture>@var{arch}</architecture>
35098@end smallexample
35099
e35359c5
UW
35100@var{arch} is one of the architectures from the set accepted by
35101@code{set architecture} (@pxref{Targets, ,Specifying a Debugging Target}).
123dc839 35102
08d16641
PA
35103@subsection OS ABI
35104@cindex @code{<osabi>}
35105
35106This optional field was introduced in @value{GDBN} version 7.0.
35107Previous versions of @value{GDBN} ignore it.
35108
35109An @samp{<osabi>} element has this form:
35110
35111@smallexample
35112 <osabi>@var{abi-name}</osabi>
35113@end smallexample
35114
35115@var{abi-name} is an OS ABI name from the same selection accepted by
35116@w{@code{set osabi}} (@pxref{ABI, ,Configuring the Current ABI}).
35117
e35359c5
UW
35118@subsection Compatible Architecture
35119@cindex @code{<compatible>}
35120
35121This optional field was introduced in @value{GDBN} version 7.0.
35122Previous versions of @value{GDBN} ignore it.
35123
35124A @samp{<compatible>} element has this form:
35125
35126@smallexample
35127 <compatible>@var{arch}</compatible>
35128@end smallexample
35129
35130@var{arch} is one of the architectures from the set accepted by
35131@code{set architecture} (@pxref{Targets, ,Specifying a Debugging Target}).
35132
35133A @samp{<compatible>} element is used to specify that the target
35134is able to run binaries in some other than the main target architecture
35135given by the @samp{<architecture>} element. For example, on the
35136Cell Broadband Engine, the main architecture is @code{powerpc:common}
35137or @code{powerpc:common64}, but the system is able to run binaries
35138in the @code{spu} architecture as well. The way to describe this
35139capability with @samp{<compatible>} is as follows:
35140
35141@smallexample
35142 <architecture>powerpc:common</architecture>
35143 <compatible>spu</compatible>
35144@end smallexample
35145
123dc839
DJ
35146@subsection Features
35147@cindex <feature>
35148
35149Each @samp{<feature>} describes some logical portion of the target
35150system. Features are currently used to describe available CPU
35151registers and the types of their contents. A @samp{<feature>} element
35152has this form:
35153
35154@smallexample
35155<feature name="@var{name}">
35156 @r{[}@var{type}@dots{}@r{]}
35157 @var{reg}@dots{}
35158</feature>
35159@end smallexample
35160
35161@noindent
35162Each feature's name should be unique within the description. The name
35163of a feature does not matter unless @value{GDBN} has some special
35164knowledge of the contents of that feature; if it does, the feature
35165should have its standard name. @xref{Standard Target Features}.
35166
35167@subsection Types
35168
35169Any register's value is a collection of bits which @value{GDBN} must
35170interpret. The default interpretation is a two's complement integer,
35171but other types can be requested by name in the register description.
35172Some predefined types are provided by @value{GDBN} (@pxref{Predefined
35173Target Types}), and the description can define additional composite types.
35174
35175Each type element must have an @samp{id} attribute, which gives
35176a unique (within the containing @samp{<feature>}) name to the type.
35177Types must be defined before they are used.
35178
35179@cindex <vector>
35180Some targets offer vector registers, which can be treated as arrays
35181of scalar elements. These types are written as @samp{<vector>} elements,
35182specifying the array element type, @var{type}, and the number of elements,
35183@var{count}:
35184
35185@smallexample
35186<vector id="@var{id}" type="@var{type}" count="@var{count}"/>
35187@end smallexample
35188
35189@cindex <union>
35190If a register's value is usefully viewed in multiple ways, define it
35191with a union type containing the useful representations. The
35192@samp{<union>} element contains one or more @samp{<field>} elements,
35193each of which has a @var{name} and a @var{type}:
35194
35195@smallexample
35196<union id="@var{id}">
35197 <field name="@var{name}" type="@var{type}"/>
35198 @dots{}
35199</union>
35200@end smallexample
35201
f5dff777
DJ
35202@cindex <struct>
35203If a register's value is composed from several separate values, define
35204it with a structure type. There are two forms of the @samp{<struct>}
35205element; a @samp{<struct>} element must either contain only bitfields
35206or contain no bitfields. If the structure contains only bitfields,
35207its total size in bytes must be specified, each bitfield must have an
35208explicit start and end, and bitfields are automatically assigned an
35209integer type. The field's @var{start} should be less than or
35210equal to its @var{end}, and zero represents the least significant bit.
35211
35212@smallexample
35213<struct id="@var{id}" size="@var{size}">
35214 <field name="@var{name}" start="@var{start}" end="@var{end}"/>
35215 @dots{}
35216</struct>
35217@end smallexample
35218
35219If the structure contains no bitfields, then each field has an
35220explicit type, and no implicit padding is added.
35221
35222@smallexample
35223<struct id="@var{id}">
35224 <field name="@var{name}" type="@var{type}"/>
35225 @dots{}
35226</struct>
35227@end smallexample
35228
35229@cindex <flags>
35230If a register's value is a series of single-bit flags, define it with
35231a flags type. The @samp{<flags>} element has an explicit @var{size}
35232and contains one or more @samp{<field>} elements. Each field has a
35233@var{name}, a @var{start}, and an @var{end}. Only single-bit flags
35234are supported.
35235
35236@smallexample
35237<flags id="@var{id}" size="@var{size}">
35238 <field name="@var{name}" start="@var{start}" end="@var{end}"/>
35239 @dots{}
35240</flags>
35241@end smallexample
35242
123dc839
DJ
35243@subsection Registers
35244@cindex <reg>
35245
35246Each register is represented as an element with this form:
35247
35248@smallexample
35249<reg name="@var{name}"
35250 bitsize="@var{size}"
35251 @r{[}regnum="@var{num}"@r{]}
35252 @r{[}save-restore="@var{save-restore}"@r{]}
35253 @r{[}type="@var{type}"@r{]}
35254 @r{[}group="@var{group}"@r{]}/>
35255@end smallexample
35256
35257@noindent
35258The components are as follows:
35259
35260@table @var
35261
35262@item name
35263The register's name; it must be unique within the target description.
35264
35265@item bitsize
35266The register's size, in bits.
35267
35268@item regnum
35269The register's number. If omitted, a register's number is one greater
35270than that of the previous register (either in the current feature or in
35271a preceeding feature); the first register in the target description
35272defaults to zero. This register number is used to read or write
35273the register; e.g.@: it is used in the remote @code{p} and @code{P}
35274packets, and registers appear in the @code{g} and @code{G} packets
35275in order of increasing register number.
35276
35277@item save-restore
35278Whether the register should be preserved across inferior function
35279calls; this must be either @code{yes} or @code{no}. The default is
35280@code{yes}, which is appropriate for most registers except for
35281some system control registers; this is not related to the target's
35282ABI.
35283
35284@item type
35285The type of the register. @var{type} may be a predefined type, a type
35286defined in the current feature, or one of the special types @code{int}
35287and @code{float}. @code{int} is an integer type of the correct size
35288for @var{bitsize}, and @code{float} is a floating point type (in the
35289architecture's normal floating point format) of the correct size for
35290@var{bitsize}. The default is @code{int}.
35291
35292@item group
35293The register group to which this register belongs. @var{group} must
35294be either @code{general}, @code{float}, or @code{vector}. If no
35295@var{group} is specified, @value{GDBN} will not display the register
35296in @code{info registers}.
35297
35298@end table
35299
35300@node Predefined Target Types
35301@section Predefined Target Types
35302@cindex target descriptions, predefined types
35303
35304Type definitions in the self-description can build up composite types
35305from basic building blocks, but can not define fundamental types. Instead,
35306standard identifiers are provided by @value{GDBN} for the fundamental
35307types. The currently supported types are:
35308
35309@table @code
35310
35311@item int8
35312@itemx int16
35313@itemx int32
35314@itemx int64
7cc46491 35315@itemx int128
123dc839
DJ
35316Signed integer types holding the specified number of bits.
35317
35318@item uint8
35319@itemx uint16
35320@itemx uint32
35321@itemx uint64
7cc46491 35322@itemx uint128
123dc839
DJ
35323Unsigned integer types holding the specified number of bits.
35324
35325@item code_ptr
35326@itemx data_ptr
35327Pointers to unspecified code and data. The program counter and
35328any dedicated return address register may be marked as code
35329pointers; printing a code pointer converts it into a symbolic
35330address. The stack pointer and any dedicated address registers
35331may be marked as data pointers.
35332
6e3bbd1a
PB
35333@item ieee_single
35334Single precision IEEE floating point.
35335
35336@item ieee_double
35337Double precision IEEE floating point.
35338
123dc839
DJ
35339@item arm_fpa_ext
35340The 12-byte extended precision format used by ARM FPA registers.
35341
075b51b7
L
35342@item i387_ext
35343The 10-byte extended precision format used by x87 registers.
35344
35345@item i386_eflags
3534632bit @sc{eflags} register used by x86.
35347
35348@item i386_mxcsr
3534932bit @sc{mxcsr} register used by x86.
35350
123dc839
DJ
35351@end table
35352
35353@node Standard Target Features
35354@section Standard Target Features
35355@cindex target descriptions, standard features
35356
35357A target description must contain either no registers or all the
35358target's registers. If the description contains no registers, then
35359@value{GDBN} will assume a default register layout, selected based on
35360the architecture. If the description contains any registers, the
35361default layout will not be used; the standard registers must be
35362described in the target description, in such a way that @value{GDBN}
35363can recognize them.
35364
35365This is accomplished by giving specific names to feature elements
35366which contain standard registers. @value{GDBN} will look for features
35367with those names and verify that they contain the expected registers;
35368if any known feature is missing required registers, or if any required
35369feature is missing, @value{GDBN} will reject the target
35370description. You can add additional registers to any of the
35371standard features --- @value{GDBN} will display them just as if
35372they were added to an unrecognized feature.
35373
35374This section lists the known features and their expected contents.
35375Sample XML documents for these features are included in the
35376@value{GDBN} source tree, in the directory @file{gdb/features}.
35377
35378Names recognized by @value{GDBN} should include the name of the
35379company or organization which selected the name, and the overall
35380architecture to which the feature applies; so e.g.@: the feature
35381containing ARM core registers is named @samp{org.gnu.gdb.arm.core}.
35382
ff6f572f
DJ
35383The names of registers are not case sensitive for the purpose
35384of recognizing standard features, but @value{GDBN} will only display
35385registers using the capitalization used in the description.
35386
e9c17194
VP
35387@menu
35388* ARM Features::
3bb8d5c3 35389* i386 Features::
1e26b4f8 35390* MIPS Features::
e9c17194 35391* M68K Features::
1e26b4f8 35392* PowerPC Features::
e9c17194
VP
35393@end menu
35394
35395
35396@node ARM Features
123dc839
DJ
35397@subsection ARM Features
35398@cindex target descriptions, ARM features
35399
35400The @samp{org.gnu.gdb.arm.core} feature is required for ARM targets.
35401It should contain registers @samp{r0} through @samp{r13}, @samp{sp},
35402@samp{lr}, @samp{pc}, and @samp{cpsr}.
35403
35404The @samp{org.gnu.gdb.arm.fpa} feature is optional. If present, it
35405should contain registers @samp{f0} through @samp{f7} and @samp{fps}.
35406
ff6f572f
DJ
35407The @samp{org.gnu.gdb.xscale.iwmmxt} feature is optional. If present,
35408it should contain at least registers @samp{wR0} through @samp{wR15} and
35409@samp{wCGR0} through @samp{wCGR3}. The @samp{wCID}, @samp{wCon},
35410@samp{wCSSF}, and @samp{wCASF} registers are optional.
23181151 35411
58d6951d
DJ
35412The @samp{org.gnu.gdb.arm.vfp} feature is optional. If present, it
35413should contain at least registers @samp{d0} through @samp{d15}. If
35414they are present, @samp{d16} through @samp{d31} should also be included.
35415@value{GDBN} will synthesize the single-precision registers from
35416halves of the double-precision registers.
35417
35418The @samp{org.gnu.gdb.arm.neon} feature is optional. It does not
35419need to contain registers; it instructs @value{GDBN} to display the
35420VFP double-precision registers as vectors and to synthesize the
35421quad-precision registers from pairs of double-precision registers.
35422If this feature is present, @samp{org.gnu.gdb.arm.vfp} must also
35423be present and include 32 double-precision registers.
35424
3bb8d5c3
L
35425@node i386 Features
35426@subsection i386 Features
35427@cindex target descriptions, i386 features
35428
35429The @samp{org.gnu.gdb.i386.core} feature is required for i386/amd64
35430targets. It should describe the following registers:
35431
35432@itemize @minus
35433@item
35434@samp{eax} through @samp{edi} plus @samp{eip} for i386
35435@item
35436@samp{rax} through @samp{r15} plus @samp{rip} for amd64
35437@item
35438@samp{eflags}, @samp{cs}, @samp{ss}, @samp{ds}, @samp{es},
35439@samp{fs}, @samp{gs}
35440@item
35441@samp{st0} through @samp{st7}
35442@item
35443@samp{fctrl}, @samp{fstat}, @samp{ftag}, @samp{fiseg}, @samp{fioff},
35444@samp{foseg}, @samp{fooff} and @samp{fop}
35445@end itemize
35446
35447The register sets may be different, depending on the target.
35448
3a13a53b 35449The @samp{org.gnu.gdb.i386.sse} feature is optional. It should
3bb8d5c3
L
35450describe registers:
35451
35452@itemize @minus
35453@item
35454@samp{xmm0} through @samp{xmm7} for i386
35455@item
35456@samp{xmm0} through @samp{xmm15} for amd64
35457@item
35458@samp{mxcsr}
35459@end itemize
35460
3a13a53b
L
35461The @samp{org.gnu.gdb.i386.avx} feature is optional and requires the
35462@samp{org.gnu.gdb.i386.sse} feature. It should
f68eb612
L
35463describe the upper 128 bits of @sc{ymm} registers:
35464
35465@itemize @minus
35466@item
35467@samp{ymm0h} through @samp{ymm7h} for i386
35468@item
35469@samp{ymm0h} through @samp{ymm15h} for amd64
35470@item
35471@end itemize
35472
3bb8d5c3
L
35473The @samp{org.gnu.gdb.i386.linux} feature is optional. It should
35474describe a single register, @samp{orig_eax}.
35475
1e26b4f8 35476@node MIPS Features
f8b73d13
DJ
35477@subsection MIPS Features
35478@cindex target descriptions, MIPS features
35479
35480The @samp{org.gnu.gdb.mips.cpu} feature is required for MIPS targets.
35481It should contain registers @samp{r0} through @samp{r31}, @samp{lo},
35482@samp{hi}, and @samp{pc}. They may be 32-bit or 64-bit depending
35483on the target.
35484
35485The @samp{org.gnu.gdb.mips.cp0} feature is also required. It should
35486contain at least the @samp{status}, @samp{badvaddr}, and @samp{cause}
35487registers. They may be 32-bit or 64-bit depending on the target.
35488
35489The @samp{org.gnu.gdb.mips.fpu} feature is currently required, though
35490it may be optional in a future version of @value{GDBN}. It should
35491contain registers @samp{f0} through @samp{f31}, @samp{fcsr}, and
35492@samp{fir}. They may be 32-bit or 64-bit depending on the target.
35493
822b6570
DJ
35494The @samp{org.gnu.gdb.mips.linux} feature is optional. It should
35495contain a single register, @samp{restart}, which is used by the
35496Linux kernel to control restartable syscalls.
35497
e9c17194
VP
35498@node M68K Features
35499@subsection M68K Features
35500@cindex target descriptions, M68K features
35501
35502@table @code
35503@item @samp{org.gnu.gdb.m68k.core}
35504@itemx @samp{org.gnu.gdb.coldfire.core}
35505@itemx @samp{org.gnu.gdb.fido.core}
35506One of those features must be always present.
249e1128 35507The feature that is present determines which flavor of m68k is
e9c17194
VP
35508used. The feature that is present should contain registers
35509@samp{d0} through @samp{d7}, @samp{a0} through @samp{a5}, @samp{fp},
35510@samp{sp}, @samp{ps} and @samp{pc}.
35511
35512@item @samp{org.gnu.gdb.coldfire.fp}
35513This feature is optional. If present, it should contain registers
35514@samp{fp0} through @samp{fp7}, @samp{fpcontrol}, @samp{fpstatus} and
35515@samp{fpiaddr}.
35516@end table
35517
1e26b4f8 35518@node PowerPC Features
7cc46491
DJ
35519@subsection PowerPC Features
35520@cindex target descriptions, PowerPC features
35521
35522The @samp{org.gnu.gdb.power.core} feature is required for PowerPC
35523targets. It should contain registers @samp{r0} through @samp{r31},
35524@samp{pc}, @samp{msr}, @samp{cr}, @samp{lr}, @samp{ctr}, and
35525@samp{xer}. They may be 32-bit or 64-bit depending on the target.
35526
35527The @samp{org.gnu.gdb.power.fpu} feature is optional. It should
35528contain registers @samp{f0} through @samp{f31} and @samp{fpscr}.
35529
35530The @samp{org.gnu.gdb.power.altivec} feature is optional. It should
35531contain registers @samp{vr0} through @samp{vr31}, @samp{vscr},
35532and @samp{vrsave}.
35533
677c5bb1
LM
35534The @samp{org.gnu.gdb.power.vsx} feature is optional. It should
35535contain registers @samp{vs0h} through @samp{vs31h}. @value{GDBN}
35536will combine these registers with the floating point registers
35537(@samp{f0} through @samp{f31}) and the altivec registers (@samp{vr0}
aeac0ff9 35538through @samp{vr31}) to present the 128-bit wide registers @samp{vs0}
677c5bb1
LM
35539through @samp{vs63}, the set of vector registers for POWER7.
35540
7cc46491
DJ
35541The @samp{org.gnu.gdb.power.spe} feature is optional. It should
35542contain registers @samp{ev0h} through @samp{ev31h}, @samp{acc}, and
35543@samp{spefscr}. SPE targets should provide 32-bit registers in
35544@samp{org.gnu.gdb.power.core} and provide the upper halves in
35545@samp{ev0h} through @samp{ev31h}. @value{GDBN} will combine
35546these to present registers @samp{ev0} through @samp{ev31} to the
35547user.
35548
07e059b5
VP
35549@node Operating System Information
35550@appendix Operating System Information
35551@cindex operating system information
35552
35553@menu
35554* Process list::
35555@end menu
35556
35557Users of @value{GDBN} often wish to obtain information about the state of
35558the operating system running on the target---for example the list of
35559processes, or the list of open files. This section describes the
35560mechanism that makes it possible. This mechanism is similar to the
35561target features mechanism (@pxref{Target Descriptions}), but focuses
35562on a different aspect of target.
35563
35564Operating system information is retrived from the target via the
35565remote protocol, using @samp{qXfer} requests (@pxref{qXfer osdata
35566read}). The object name in the request should be @samp{osdata}, and
35567the @var{annex} identifies the data to be fetched.
35568
35569@node Process list
35570@appendixsection Process list
35571@cindex operating system information, process list
35572
35573When requesting the process list, the @var{annex} field in the
35574@samp{qXfer} request should be @samp{processes}. The returned data is
35575an XML document. The formal syntax of this document is defined in
35576@file{gdb/features/osdata.dtd}.
35577
35578An example document is:
35579
35580@smallexample
35581<?xml version="1.0"?>
35582<!DOCTYPE target SYSTEM "osdata.dtd">
35583<osdata type="processes">
35584 <item>
35585 <column name="pid">1</column>
35586 <column name="user">root</column>
35587 <column name="command">/sbin/init</column>
dc146f7c 35588 <column name="cores">1,2,3</column>
07e059b5
VP
35589 </item>
35590</osdata>
35591@end smallexample
35592
35593Each item should include a column whose name is @samp{pid}. The value
35594of that column should identify the process on the target. The
35595@samp{user} and @samp{command} columns are optional, and will be
dc146f7c
VP
35596displayed by @value{GDBN}. The @samp{cores} column, if present,
35597should contain a comma-separated list of cores that this process
35598is running on. Target may provide additional columns,
07e059b5
VP
35599which @value{GDBN} currently ignores.
35600
aab4e0ec 35601@include gpl.texi
eb12ee30 35602
e4c0cfae
SS
35603@node GNU Free Documentation License
35604@appendix GNU Free Documentation License
6826cf00
EZ
35605@include fdl.texi
35606
6d2ebf8b 35607@node Index
c906108c
SS
35608@unnumbered Index
35609
35610@printindex cp
35611
35612@tex
35613% I think something like @colophon should be in texinfo. In the
35614% meantime:
35615\long\def\colophon{\hbox to0pt{}\vfill
35616\centerline{The body of this manual is set in}
35617\centerline{\fontname\tenrm,}
35618\centerline{with headings in {\bf\fontname\tenbf}}
35619\centerline{and examples in {\tt\fontname\tentt}.}
35620\centerline{{\it\fontname\tenit\/},}
35621\centerline{{\bf\fontname\tenbf}, and}
35622\centerline{{\sl\fontname\tensl\/}}
35623\centerline{are used for emphasis.}\vfill}
35624\page\colophon
35625% Blame: doc@cygnus.com, 1991.
35626@end tex
35627
c906108c 35628@bye
This page took 5.271065 seconds and 4 git commands to generate.