* gdb.texinfo (Sample Session, Invocation, Quitting GDB)
[deliverable/binutils-gdb.git] / gdb / doc / gdb.texinfo
1 \input texinfo @c -*-texinfo-*-
2 @c Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998,
3 @c 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006
4 @c Free Software Foundation, Inc.
5 @c
6 @c %**start of header
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
13 @settitle Debugging with @value{GDBN}
14 @setchapternewpage odd
15 @c %**end of header
16
17 @iftex
18 @c @smallbook
19 @c @cropmarks
20 @end iftex
21
22 @finalout
23 @syncodeindex ky cp
24
25 @c readline appendices use @vindex, @findex and @ftable,
26 @c annotate.texi and gdbmi use @findex.
27 @syncodeindex vr cp
28 @syncodeindex fn cp
29
30 @c !!set GDB manual's edition---not the same as GDB version!
31 @c This is updated by GNU Press.
32 @set EDITION Ninth
33
34 @c !!set GDB edit command default editor
35 @set EDITOR /bin/ex
36
37 @c THIS MANUAL REQUIRES TEXINFO 4.0 OR LATER.
38
39 @c This is a dir.info fragment to support semi-automated addition of
40 @c manuals to an info tree.
41 @dircategory Software development
42 @direntry
43 * Gdb: (gdb). The GNU debugger.
44 @end direntry
45
46 @ifinfo
47 This file documents the @sc{gnu} debugger @value{GDBN}.
48
49
50 This is the @value{EDITION} Edition, of @cite{Debugging with
51 @value{GDBN}: the @sc{gnu} Source-Level Debugger} for @value{GDBN}
52 Version @value{GDBVN}.
53
54 Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998,@*
55 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006@*
56 Free Software Foundation, Inc.
57
58 Permission is granted to copy, distribute and/or modify this document
59 under the terms of the GNU Free Documentation License, Version 1.1 or
60 any later version published by the Free Software Foundation; with the
61 Invariant Sections being ``Free Software'' and ``Free Software Needs
62 Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,''
63 and with the Back-Cover Texts as in (a) below.
64
65 (a) The Free Software Foundation's Back-Cover Text is: ``You have
66 freedom to copy and modify this GNU Manual, like GNU software. Copies
67 published by the Free Software Foundation raise funds for GNU
68 development.''
69 @end ifinfo
70
71 @titlepage
72 @title Debugging with @value{GDBN}
73 @subtitle The @sc{gnu} Source-Level Debugger
74 @sp 1
75 @subtitle @value{EDITION} Edition, for @value{GDBN} version @value{GDBVN}
76 @author Richard Stallman, Roland Pesch, Stan Shebs, et al.
77 @page
78 @tex
79 {\parskip=0pt
80 \hfill (Send bugs and comments on @value{GDBN} to bug-gdb\@gnu.org.)\par
81 \hfill {\it Debugging with @value{GDBN}}\par
82 \hfill \TeX{}info \texinfoversion\par
83 }
84 @end tex
85
86 @vskip 0pt plus 1filll
87 Copyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995,
88 1996, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2006
89 Free Software Foundation, Inc.
90 @sp 2
91 Published by the Free Software Foundation @*
92 51 Franklin Street, Fifth Floor,
93 Boston, MA 02110-1301, USA@*
94 ISBN 1-882114-77-9 @*
95
96 Permission is granted to copy, distribute and/or modify this document
97 under the terms of the GNU Free Documentation License, Version 1.1 or
98 any later version published by the Free Software Foundation; with the
99 Invariant Sections being ``Free Software'' and ``Free Software Needs
100 Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,''
101 and with the Back-Cover Texts as in (a) below.
102
103 (a) The Free Software Foundation's Back-Cover Text is: ``You have
104 freedom to copy and modify this GNU Manual, like GNU software. Copies
105 published by the Free Software Foundation raise funds for GNU
106 development.''
107 @end titlepage
108 @page
109
110 @ifnottex
111 @node Top, Summary, (dir), (dir)
112
113 @top Debugging with @value{GDBN}
114
115 This file describes @value{GDBN}, the @sc{gnu} symbolic debugger.
116
117 This is the @value{EDITION} Edition, for @value{GDBN} Version
118 @value{GDBVN}.
119
120 Copyright (C) 1988-2006 Free Software Foundation, Inc.
121
122 @menu
123 * Summary:: Summary of @value{GDBN}
124 * Sample Session:: A sample @value{GDBN} session
125
126 * Invocation:: Getting in and out of @value{GDBN}
127 * Commands:: @value{GDBN} commands
128 * Running:: Running programs under @value{GDBN}
129 * Stopping:: Stopping and continuing
130 * Stack:: Examining the stack
131 * Source:: Examining source files
132 * Data:: Examining data
133 * Macros:: Preprocessor Macros
134 * Tracepoints:: Debugging remote targets non-intrusively
135 * Overlays:: Debugging programs that use overlays
136
137 * Languages:: Using @value{GDBN} with different languages
138
139 * Symbols:: Examining the symbol table
140 * Altering:: Altering execution
141 * GDB Files:: @value{GDBN} files
142 * Targets:: Specifying a debugging target
143 * Remote Debugging:: Debugging remote programs
144 * Configurations:: Configuration-specific information
145 * Controlling GDB:: Controlling @value{GDBN}
146 * Sequences:: Canned sequences of commands
147 * TUI:: @value{GDBN} Text User Interface
148 * Interpreters:: Command Interpreters
149 * Emacs:: Using @value{GDBN} under @sc{gnu} Emacs
150 * Annotations:: @value{GDBN}'s annotation interface.
151 * GDB/MI:: @value{GDBN}'s Machine Interface.
152
153 * GDB Bugs:: Reporting bugs in @value{GDBN}
154 * Formatting Documentation:: How to format and print @value{GDBN} documentation
155
156 * Command Line Editing:: Command Line Editing
157 * Using History Interactively:: Using History Interactively
158 * Installing GDB:: Installing GDB
159 * Maintenance Commands:: Maintenance Commands
160 * Remote Protocol:: GDB Remote Serial Protocol
161 * Agent Expressions:: The GDB Agent Expression Mechanism
162 * Copying:: GNU General Public License says
163 how you can copy and share GDB
164 * GNU Free Documentation License:: The license for this documentation
165 * Index:: Index
166 @end menu
167
168 @end ifnottex
169
170 @contents
171
172 @node Summary
173 @unnumbered Summary of @value{GDBN}
174
175 The purpose of a debugger such as @value{GDBN} is to allow you to see what is
176 going on ``inside'' another program while it executes---or what another
177 program was doing at the moment it crashed.
178
179 @value{GDBN} can do four main kinds of things (plus other things in support of
180 these) to help you catch bugs in the act:
181
182 @itemize @bullet
183 @item
184 Start your program, specifying anything that might affect its behavior.
185
186 @item
187 Make your program stop on specified conditions.
188
189 @item
190 Examine what has happened, when your program has stopped.
191
192 @item
193 Change things in your program, so you can experiment with correcting the
194 effects of one bug and go on to learn about another.
195 @end itemize
196
197 You can use @value{GDBN} to debug programs written in C and C@t{++}.
198 For more information, see @ref{Supported languages,,Supported languages}.
199 For more information, see @ref{C,,C and C++}.
200
201 @cindex Modula-2
202 Support for Modula-2 is partial. For information on Modula-2, see
203 @ref{Modula-2,,Modula-2}.
204
205 @cindex Pascal
206 Debugging Pascal programs which use sets, subranges, file variables, or
207 nested functions does not currently work. @value{GDBN} does not support
208 entering expressions, printing values, or similar features using Pascal
209 syntax.
210
211 @cindex Fortran
212 @value{GDBN} can be used to debug programs written in Fortran, although
213 it may be necessary to refer to some variables with a trailing
214 underscore.
215
216 @value{GDBN} can be used to debug programs written in Objective-C,
217 using either the Apple/NeXT or the GNU Objective-C runtime.
218
219 @menu
220 * Free Software:: Freely redistributable software
221 * Contributors:: Contributors to GDB
222 @end menu
223
224 @node Free Software
225 @unnumberedsec Free software
226
227 @value{GDBN} is @dfn{free software}, protected by the @sc{gnu}
228 General Public License
229 (GPL). The GPL gives you the freedom to copy or adapt a licensed
230 program---but every person getting a copy also gets with it the
231 freedom to modify that copy (which means that they must get access to
232 the source code), and the freedom to distribute further copies.
233 Typical software companies use copyrights to limit your freedoms; the
234 Free Software Foundation uses the GPL to preserve these freedoms.
235
236 Fundamentally, the General Public License is a license which says that
237 you have these freedoms and that you cannot take these freedoms away
238 from anyone else.
239
240 @unnumberedsec Free Software Needs Free Documentation
241
242 The biggest deficiency in the free software community today is not in
243 the software---it is the lack of good free documentation that we can
244 include with the free software. Many of our most important
245 programs do not come with free reference manuals and free introductory
246 texts. Documentation is an essential part of any software package;
247 when an important free software package does not come with a free
248 manual and a free tutorial, that is a major gap. We have many such
249 gaps today.
250
251 Consider Perl, for instance. The tutorial manuals that people
252 normally use are non-free. How did this come about? Because the
253 authors of those manuals published them with restrictive terms---no
254 copying, no modification, source files not available---which exclude
255 them from the free software world.
256
257 That wasn't the first time this sort of thing happened, and it was far
258 from the last. Many times we have heard a GNU user eagerly describe a
259 manual that he is writing, his intended contribution to the community,
260 only to learn that he had ruined everything by signing a publication
261 contract to make it non-free.
262
263 Free documentation, like free software, is a matter of freedom, not
264 price. The problem with the non-free manual is not that publishers
265 charge a price for printed copies---that in itself is fine. (The Free
266 Software Foundation sells printed copies of manuals, too.) The
267 problem is the restrictions on the use of the manual. Free manuals
268 are available in source code form, and give you permission to copy and
269 modify. Non-free manuals do not allow this.
270
271 The criteria of freedom for a free manual are roughly the same as for
272 free software. Redistribution (including the normal kinds of
273 commercial redistribution) must be permitted, so that the manual can
274 accompany every copy of the program, both on-line and on paper.
275
276 Permission for modification of the technical content is crucial too.
277 When people modify the software, adding or changing features, if they
278 are conscientious they will change the manual too---so they can
279 provide accurate and clear documentation for the modified program. A
280 manual that leaves you no choice but to write a new manual to document
281 a changed version of the program is not really available to our
282 community.
283
284 Some kinds of limits on the way modification is handled are
285 acceptable. For example, requirements to preserve the original
286 author's copyright notice, the distribution terms, or the list of
287 authors, are ok. It is also no problem to require modified versions
288 to include notice that they were modified. Even entire sections that
289 may not be deleted or changed are acceptable, as long as they deal
290 with nontechnical topics (like this one). These kinds of restrictions
291 are acceptable because they don't obstruct the community's normal use
292 of the manual.
293
294 However, it must be possible to modify all the @emph{technical}
295 content of the manual, and then distribute the result in all the usual
296 media, through all the usual channels. Otherwise, the restrictions
297 obstruct the use of the manual, it is not free, and we need another
298 manual to replace it.
299
300 Please spread the word about this issue. Our community continues to
301 lose manuals to proprietary publishing. If we spread the word that
302 free software needs free reference manuals and free tutorials, perhaps
303 the next person who wants to contribute by writing documentation will
304 realize, before it is too late, that only free manuals contribute to
305 the free software community.
306
307 If you are writing documentation, please insist on publishing it under
308 the GNU Free Documentation License or another free documentation
309 license. Remember that this decision requires your approval---you
310 don't have to let the publisher decide. Some commercial publishers
311 will use a free license if you insist, but they will not propose the
312 option; it is up to you to raise the issue and say firmly that this is
313 what you want. If the publisher you are dealing with refuses, please
314 try other publishers. If you're not sure whether a proposed license
315 is free, write to @email{licensing@@gnu.org}.
316
317 You can encourage commercial publishers to sell more free, copylefted
318 manuals and tutorials by buying them, and particularly by buying
319 copies from the publishers that paid for their writing or for major
320 improvements. Meanwhile, try to avoid buying non-free documentation
321 at all. Check the distribution terms of a manual before you buy it,
322 and insist that whoever seeks your business must respect your freedom.
323 Check the history of the book, and try to reward the publishers that
324 have paid or pay the authors to work on it.
325
326 The Free Software Foundation maintains a list of free documentation
327 published by other publishers, at
328 @url{http://www.fsf.org/doc/other-free-books.html}.
329
330 @node Contributors
331 @unnumberedsec Contributors to @value{GDBN}
332
333 Richard Stallman was the original author of @value{GDBN}, and of many
334 other @sc{gnu} programs. Many others have contributed to its
335 development. This section attempts to credit major contributors. One
336 of the virtues of free software is that everyone is free to contribute
337 to it; with regret, we cannot actually acknowledge everyone here. The
338 file @file{ChangeLog} in the @value{GDBN} distribution approximates a
339 blow-by-blow account.
340
341 Changes much prior to version 2.0 are lost in the mists of time.
342
343 @quotation
344 @emph{Plea:} Additions to this section are particularly welcome. If you
345 or your friends (or enemies, to be evenhanded) have been unfairly
346 omitted from this list, we would like to add your names!
347 @end quotation
348
349 So that they may not regard their many labors as thankless, we
350 particularly thank those who shepherded @value{GDBN} through major
351 releases:
352 Andrew Cagney (releases 6.3, 6.2, 6.1, 6.0, 5.3, 5.2, 5.1 and 5.0);
353 Jim Blandy (release 4.18);
354 Jason Molenda (release 4.17);
355 Stan Shebs (release 4.14);
356 Fred Fish (releases 4.16, 4.15, 4.13, 4.12, 4.11, 4.10, and 4.9);
357 Stu Grossman and John Gilmore (releases 4.8, 4.7, 4.6, 4.5, and 4.4);
358 John Gilmore (releases 4.3, 4.2, 4.1, 4.0, and 3.9);
359 Jim Kingdon (releases 3.5, 3.4, and 3.3);
360 and Randy Smith (releases 3.2, 3.1, and 3.0).
361
362 Richard Stallman, assisted at various times by Peter TerMaat, Chris
363 Hanson, and Richard Mlynarik, handled releases through 2.8.
364
365 Michael Tiemann is the author of most of the @sc{gnu} C@t{++} support
366 in @value{GDBN}, with significant additional contributions from Per
367 Bothner and Daniel Berlin. James Clark wrote the @sc{gnu} C@t{++}
368 demangler. Early work on C@t{++} was by Peter TerMaat (who also did
369 much general update work leading to release 3.0).
370
371 @value{GDBN} uses the BFD subroutine library to examine multiple
372 object-file formats; BFD was a joint project of David V.
373 Henkel-Wallace, Rich Pixley, Steve Chamberlain, and John Gilmore.
374
375 David Johnson wrote the original COFF support; Pace Willison did
376 the original support for encapsulated COFF.
377
378 Brent Benson of Harris Computer Systems contributed DWARF 2 support.
379
380 Adam de Boor and Bradley Davis contributed the ISI Optimum V support.
381 Per Bothner, Noboyuki Hikichi, and Alessandro Forin contributed MIPS
382 support.
383 Jean-Daniel Fekete contributed Sun 386i support.
384 Chris Hanson improved the HP9000 support.
385 Noboyuki Hikichi and Tomoyuki Hasei contributed Sony/News OS 3 support.
386 David Johnson contributed Encore Umax support.
387 Jyrki Kuoppala contributed Altos 3068 support.
388 Jeff Law contributed HP PA and SOM support.
389 Keith Packard contributed NS32K support.
390 Doug Rabson contributed Acorn Risc Machine support.
391 Bob Rusk contributed Harris Nighthawk CX-UX support.
392 Chris Smith contributed Convex support (and Fortran debugging).
393 Jonathan Stone contributed Pyramid support.
394 Michael Tiemann contributed SPARC support.
395 Tim Tucker contributed support for the Gould NP1 and Gould Powernode.
396 Pace Willison contributed Intel 386 support.
397 Jay Vosburgh contributed Symmetry support.
398 Marko Mlinar contributed OpenRISC 1000 support.
399
400 Andreas Schwab contributed M68K @sc{gnu}/Linux support.
401
402 Rich Schaefer and Peter Schauer helped with support of SunOS shared
403 libraries.
404
405 Jay Fenlason and Roland McGrath ensured that @value{GDBN} and GAS agree
406 about several machine instruction sets.
407
408 Patrick Duval, Ted Goldstein, Vikram Koka and Glenn Engel helped develop
409 remote debugging. Intel Corporation, Wind River Systems, AMD, and ARM
410 contributed remote debugging modules for the i960, VxWorks, A29K UDI,
411 and RDI targets, respectively.
412
413 Brian Fox is the author of the readline libraries providing
414 command-line editing and command history.
415
416 Andrew Beers of SUNY Buffalo wrote the language-switching code, the
417 Modula-2 support, and contributed the Languages chapter of this manual.
418
419 Fred Fish wrote most of the support for Unix System Vr4.
420 He also enhanced the command-completion support to cover C@t{++} overloaded
421 symbols.
422
423 Hitachi America (now Renesas America), Ltd. sponsored the support for
424 H8/300, H8/500, and Super-H processors.
425
426 NEC sponsored the support for the v850, Vr4xxx, and Vr5xxx processors.
427
428 Mitsubishi (now Renesas) sponsored the support for D10V, D30V, and M32R/D
429 processors.
430
431 Toshiba sponsored the support for the TX39 Mips processor.
432
433 Matsushita sponsored the support for the MN10200 and MN10300 processors.
434
435 Fujitsu sponsored the support for SPARClite and FR30 processors.
436
437 Kung Hsu, Jeff Law, and Rick Sladkey added support for hardware
438 watchpoints.
439
440 Michael Snyder added support for tracepoints.
441
442 Stu Grossman wrote gdbserver.
443
444 Jim Kingdon, Peter Schauer, Ian Taylor, and Stu Grossman made
445 nearly innumerable bug fixes and cleanups throughout @value{GDBN}.
446
447 The following people at the Hewlett-Packard Company contributed
448 support for the PA-RISC 2.0 architecture, HP-UX 10.20, 10.30, and 11.0
449 (narrow mode), HP's implementation of kernel threads, HP's aC@t{++}
450 compiler, and the Text User Interface (nee Terminal User Interface):
451 Ben Krepp, Richard Title, John Bishop, Susan Macchia, Kathy Mann,
452 Satish Pai, India Paul, Steve Rehrauer, and Elena Zannoni. Kim Haase
453 provided HP-specific information in this manual.
454
455 DJ Delorie ported @value{GDBN} to MS-DOS, for the DJGPP project.
456 Robert Hoehne made significant contributions to the DJGPP port.
457
458 Cygnus Solutions has sponsored @value{GDBN} maintenance and much of its
459 development since 1991. Cygnus engineers who have worked on @value{GDBN}
460 fulltime include Mark Alexander, Jim Blandy, Per Bothner, Kevin
461 Buettner, Edith Epstein, Chris Faylor, Fred Fish, Martin Hunt, Jim
462 Ingham, John Gilmore, Stu Grossman, Kung Hsu, Jim Kingdon, John Metzler,
463 Fernando Nasser, Geoffrey Noer, Dawn Perchik, Rich Pixley, Zdenek
464 Radouch, Keith Seitz, Stan Shebs, David Taylor, and Elena Zannoni. In
465 addition, Dave Brolley, Ian Carmichael, Steve Chamberlain, Nick Clifton,
466 JT Conklin, Stan Cox, DJ Delorie, Ulrich Drepper, Frank Eigler, Doug
467 Evans, Sean Fagan, David Henkel-Wallace, Richard Henderson, Jeff
468 Holcomb, Jeff Law, Jim Lemke, Tom Lord, Bob Manson, Michael Meissner,
469 Jason Merrill, Catherine Moore, Drew Moseley, Ken Raeburn, Gavin
470 Romig-Koch, Rob Savoye, Jamie Smith, Mike Stump, Ian Taylor, Angela
471 Thomas, Michael Tiemann, Tom Tromey, Ron Unrau, Jim Wilson, and David
472 Zuhn have made contributions both large and small.
473
474 Andrew Cagney, Fernando Nasser, and Elena Zannoni, while working for
475 Cygnus Solutions, implemented the original @sc{gdb/mi} interface.
476
477 Jim Blandy added support for preprocessor macros, while working for Red
478 Hat.
479
480 Andrew Cagney designed @value{GDBN}'s architecture vector. Many
481 people including Andrew Cagney, Stephane Carrez, Randolph Chung, Nick
482 Duffek, Richard Henderson, Mark Kettenis, Grace Sainsbury, Kei
483 Sakamoto, Yoshinori Sato, Michael Snyder, Andreas Schwab, Jason
484 Thorpe, Corinna Vinschen, Ulrich Weigand, and Elena Zannoni, helped
485 with the migration of old architectures to this new framework.
486
487 Andrew Cagney completely re-designed and re-implemented @value{GDBN}'s
488 unwinder framework, this consisting of a fresh new design featuring
489 frame IDs, independent frame sniffers, and the sentinel frame. Mark
490 Kettenis implemented the @sc{dwarf 2} unwinder, Jeff Johnston the
491 libunwind unwinder, and Andrew Cagney the dummy, sentinel, tramp, and
492 trad unwinders. The architecture specific changes, each involving a
493 complete rewrite of the architecture's frame code, were carried out by
494 Jim Blandy, Joel Brobecker, Kevin Buettner, Andrew Cagney, Stephane
495 Carrez, Randolph Chung, Orjan Friberg, Richard Henderson, Daniel
496 Jacobowitz, Jeff Johnston, Mark Kettenis, Theodore A. Roth, Kei
497 Sakamoto, Yoshinori Sato, Michael Snyder, Corinna Vinschen, and Ulrich
498 Weigand.
499
500 @node Sample Session
501 @chapter A Sample @value{GDBN} Session
502
503 You can use this manual at your leisure to read all about @value{GDBN}.
504 However, a handful of commands are enough to get started using the
505 debugger. This chapter illustrates those commands.
506
507 @iftex
508 In this sample session, we emphasize user input like this: @b{input},
509 to make it easier to pick out from the surrounding output.
510 @end iftex
511
512 @c FIXME: this example may not be appropriate for some configs, where
513 @c FIXME...primary interest is in remote use.
514
515 One of the preliminary versions of @sc{gnu} @code{m4} (a generic macro
516 processor) exhibits the following bug: sometimes, when we change its
517 quote strings from the default, the commands used to capture one macro
518 definition within another stop working. In the following short @code{m4}
519 session, we define a macro @code{foo} which expands to @code{0000}; we
520 then use the @code{m4} built-in @code{defn} to define @code{bar} as the
521 same thing. However, when we change the open quote string to
522 @code{<QUOTE>} and the close quote string to @code{<UNQUOTE>}, the same
523 procedure fails to define a new synonym @code{baz}:
524
525 @smallexample
526 $ @b{cd gnu/m4}
527 $ @b{./m4}
528 @b{define(foo,0000)}
529
530 @b{foo}
531 0000
532 @b{define(bar,defn(`foo'))}
533
534 @b{bar}
535 0000
536 @b{changequote(<QUOTE>,<UNQUOTE>)}
537
538 @b{define(baz,defn(<QUOTE>foo<UNQUOTE>))}
539 @b{baz}
540 @b{Ctrl-d}
541 m4: End of input: 0: fatal error: EOF in string
542 @end smallexample
543
544 @noindent
545 Let us use @value{GDBN} to try to see what is going on.
546
547 @smallexample
548 $ @b{@value{GDBP} m4}
549 @c FIXME: this falsifies the exact text played out, to permit smallbook
550 @c FIXME... format to come out better.
551 @value{GDBN} is free software and you are welcome to distribute copies
552 of it under certain conditions; type "show copying" to see
553 the conditions.
554 There is absolutely no warranty for @value{GDBN}; type "show warranty"
555 for details.
556
557 @value{GDBN} @value{GDBVN}, Copyright 1999 Free Software Foundation, Inc...
558 (@value{GDBP})
559 @end smallexample
560
561 @noindent
562 @value{GDBN} reads only enough symbol data to know where to find the
563 rest when needed; as a result, the first prompt comes up very quickly.
564 We now tell @value{GDBN} to use a narrower display width than usual, so
565 that examples fit in this manual.
566
567 @smallexample
568 (@value{GDBP}) @b{set width 70}
569 @end smallexample
570
571 @noindent
572 We need to see how the @code{m4} built-in @code{changequote} works.
573 Having looked at the source, we know the relevant subroutine is
574 @code{m4_changequote}, so we set a breakpoint there with the @value{GDBN}
575 @code{break} command.
576
577 @smallexample
578 (@value{GDBP}) @b{break m4_changequote}
579 Breakpoint 1 at 0x62f4: file builtin.c, line 879.
580 @end smallexample
581
582 @noindent
583 Using the @code{run} command, we start @code{m4} running under @value{GDBN}
584 control; as long as control does not reach the @code{m4_changequote}
585 subroutine, the program runs as usual:
586
587 @smallexample
588 (@value{GDBP}) @b{run}
589 Starting program: /work/Editorial/gdb/gnu/m4/m4
590 @b{define(foo,0000)}
591
592 @b{foo}
593 0000
594 @end smallexample
595
596 @noindent
597 To trigger the breakpoint, we call @code{changequote}. @value{GDBN}
598 suspends execution of @code{m4}, displaying information about the
599 context where it stops.
600
601 @smallexample
602 @b{changequote(<QUOTE>,<UNQUOTE>)}
603
604 Breakpoint 1, m4_changequote (argc=3, argv=0x33c70)
605 at builtin.c:879
606 879 if (bad_argc(TOKEN_DATA_TEXT(argv[0]),argc,1,3))
607 @end smallexample
608
609 @noindent
610 Now we use the command @code{n} (@code{next}) to advance execution to
611 the next line of the current function.
612
613 @smallexample
614 (@value{GDBP}) @b{n}
615 882 set_quotes((argc >= 2) ? TOKEN_DATA_TEXT(argv[1])\
616 : nil,
617 @end smallexample
618
619 @noindent
620 @code{set_quotes} looks like a promising subroutine. We can go into it
621 by using the command @code{s} (@code{step}) instead of @code{next}.
622 @code{step} goes to the next line to be executed in @emph{any}
623 subroutine, so it steps into @code{set_quotes}.
624
625 @smallexample
626 (@value{GDBP}) @b{s}
627 set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>")
628 at input.c:530
629 530 if (lquote != def_lquote)
630 @end smallexample
631
632 @noindent
633 The display that shows the subroutine where @code{m4} is now
634 suspended (and its arguments) is called a stack frame display. It
635 shows a summary of the stack. We can use the @code{backtrace}
636 command (which can also be spelled @code{bt}), to see where we are
637 in the stack as a whole: the @code{backtrace} command displays a
638 stack frame for each active subroutine.
639
640 @smallexample
641 (@value{GDBP}) @b{bt}
642 #0 set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>")
643 at input.c:530
644 #1 0x6344 in m4_changequote (argc=3, argv=0x33c70)
645 at builtin.c:882
646 #2 0x8174 in expand_macro (sym=0x33320) at macro.c:242
647 #3 0x7a88 in expand_token (obs=0x0, t=209696, td=0xf7fffa30)
648 at macro.c:71
649 #4 0x79dc in expand_input () at macro.c:40
650 #5 0x2930 in main (argc=0, argv=0xf7fffb20) at m4.c:195
651 @end smallexample
652
653 @noindent
654 We step through a few more lines to see what happens. The first two
655 times, we can use @samp{s}; the next two times we use @code{n} to avoid
656 falling into the @code{xstrdup} subroutine.
657
658 @smallexample
659 (@value{GDBP}) @b{s}
660 0x3b5c 532 if (rquote != def_rquote)
661 (@value{GDBP}) @b{s}
662 0x3b80 535 lquote = (lq == nil || *lq == '\0') ? \
663 def_lquote : xstrdup(lq);
664 (@value{GDBP}) @b{n}
665 536 rquote = (rq == nil || *rq == '\0') ? def_rquote\
666 : xstrdup(rq);
667 (@value{GDBP}) @b{n}
668 538 len_lquote = strlen(rquote);
669 @end smallexample
670
671 @noindent
672 The last line displayed looks a little odd; we can examine the variables
673 @code{lquote} and @code{rquote} to see if they are in fact the new left
674 and right quotes we specified. We use the command @code{p}
675 (@code{print}) to see their values.
676
677 @smallexample
678 (@value{GDBP}) @b{p lquote}
679 $1 = 0x35d40 "<QUOTE>"
680 (@value{GDBP}) @b{p rquote}
681 $2 = 0x35d50 "<UNQUOTE>"
682 @end smallexample
683
684 @noindent
685 @code{lquote} and @code{rquote} are indeed the new left and right quotes.
686 To look at some context, we can display ten lines of source
687 surrounding the current line with the @code{l} (@code{list}) command.
688
689 @smallexample
690 (@value{GDBP}) @b{l}
691 533 xfree(rquote);
692 534
693 535 lquote = (lq == nil || *lq == '\0') ? def_lquote\
694 : xstrdup (lq);
695 536 rquote = (rq == nil || *rq == '\0') ? def_rquote\
696 : xstrdup (rq);
697 537
698 538 len_lquote = strlen(rquote);
699 539 len_rquote = strlen(lquote);
700 540 @}
701 541
702 542 void
703 @end smallexample
704
705 @noindent
706 Let us step past the two lines that set @code{len_lquote} and
707 @code{len_rquote}, and then examine the values of those variables.
708
709 @smallexample
710 (@value{GDBP}) @b{n}
711 539 len_rquote = strlen(lquote);
712 (@value{GDBP}) @b{n}
713 540 @}
714 (@value{GDBP}) @b{p len_lquote}
715 $3 = 9
716 (@value{GDBP}) @b{p len_rquote}
717 $4 = 7
718 @end smallexample
719
720 @noindent
721 That certainly looks wrong, assuming @code{len_lquote} and
722 @code{len_rquote} are meant to be the lengths of @code{lquote} and
723 @code{rquote} respectively. We can set them to better values using
724 the @code{p} command, since it can print the value of
725 any expression---and that expression can include subroutine calls and
726 assignments.
727
728 @smallexample
729 (@value{GDBP}) @b{p len_lquote=strlen(lquote)}
730 $5 = 7
731 (@value{GDBP}) @b{p len_rquote=strlen(rquote)}
732 $6 = 9
733 @end smallexample
734
735 @noindent
736 Is that enough to fix the problem of using the new quotes with the
737 @code{m4} built-in @code{defn}? We can allow @code{m4} to continue
738 executing with the @code{c} (@code{continue}) command, and then try the
739 example that caused trouble initially:
740
741 @smallexample
742 (@value{GDBP}) @b{c}
743 Continuing.
744
745 @b{define(baz,defn(<QUOTE>foo<UNQUOTE>))}
746
747 baz
748 0000
749 @end smallexample
750
751 @noindent
752 Success! The new quotes now work just as well as the default ones. The
753 problem seems to have been just the two typos defining the wrong
754 lengths. We allow @code{m4} exit by giving it an EOF as input:
755
756 @smallexample
757 @b{Ctrl-d}
758 Program exited normally.
759 @end smallexample
760
761 @noindent
762 The message @samp{Program exited normally.} is from @value{GDBN}; it
763 indicates @code{m4} has finished executing. We can end our @value{GDBN}
764 session with the @value{GDBN} @code{quit} command.
765
766 @smallexample
767 (@value{GDBP}) @b{quit}
768 @end smallexample
769
770 @node Invocation
771 @chapter Getting In and Out of @value{GDBN}
772
773 This chapter discusses how to start @value{GDBN}, and how to get out of it.
774 The essentials are:
775 @itemize @bullet
776 @item
777 type @samp{@value{GDBP}} to start @value{GDBN}.
778 @item
779 type @kbd{quit} or @kbd{Ctrl-d} to exit.
780 @end itemize
781
782 @menu
783 * Invoking GDB:: How to start @value{GDBN}
784 * Quitting GDB:: How to quit @value{GDBN}
785 * Shell Commands:: How to use shell commands inside @value{GDBN}
786 * Logging output:: How to log @value{GDBN}'s output to a file
787 @end menu
788
789 @node Invoking GDB
790 @section Invoking @value{GDBN}
791
792 Invoke @value{GDBN} by running the program @code{@value{GDBP}}. Once started,
793 @value{GDBN} reads commands from the terminal until you tell it to exit.
794
795 You can also run @code{@value{GDBP}} with a variety of arguments and options,
796 to specify more of your debugging environment at the outset.
797
798 The command-line options described here are designed
799 to cover a variety of situations; in some environments, some of these
800 options may effectively be unavailable.
801
802 The most usual way to start @value{GDBN} is with one argument,
803 specifying an executable program:
804
805 @smallexample
806 @value{GDBP} @var{program}
807 @end smallexample
808
809 @noindent
810 You can also start with both an executable program and a core file
811 specified:
812
813 @smallexample
814 @value{GDBP} @var{program} @var{core}
815 @end smallexample
816
817 You can, instead, specify a process ID as a second argument, if you want
818 to debug a running process:
819
820 @smallexample
821 @value{GDBP} @var{program} 1234
822 @end smallexample
823
824 @noindent
825 would attach @value{GDBN} to process @code{1234} (unless you also have a file
826 named @file{1234}; @value{GDBN} does check for a core file first).
827
828 Taking advantage of the second command-line argument requires a fairly
829 complete operating system; when you use @value{GDBN} as a remote
830 debugger attached to a bare board, there may not be any notion of
831 ``process'', and there is often no way to get a core dump. @value{GDBN}
832 will warn you if it is unable to attach or to read core dumps.
833
834 You can optionally have @code{@value{GDBP}} pass any arguments after the
835 executable file to the inferior using @code{--args}. This option stops
836 option processing.
837 @smallexample
838 gdb --args gcc -O2 -c foo.c
839 @end smallexample
840 This will cause @code{@value{GDBP}} to debug @code{gcc}, and to set
841 @code{gcc}'s command-line arguments (@pxref{Arguments}) to @samp{-O2 -c foo.c}.
842
843 You can run @code{@value{GDBP}} without printing the front material, which describes
844 @value{GDBN}'s non-warranty, by specifying @code{-silent}:
845
846 @smallexample
847 @value{GDBP} -silent
848 @end smallexample
849
850 @noindent
851 You can further control how @value{GDBN} starts up by using command-line
852 options. @value{GDBN} itself can remind you of the options available.
853
854 @noindent
855 Type
856
857 @smallexample
858 @value{GDBP} -help
859 @end smallexample
860
861 @noindent
862 to display all available options and briefly describe their use
863 (@samp{@value{GDBP} -h} is a shorter equivalent).
864
865 All options and command line arguments you give are processed
866 in sequential order. The order makes a difference when the
867 @samp{-x} option is used.
868
869
870 @menu
871 * File Options:: Choosing files
872 * Mode Options:: Choosing modes
873 * Startup:: What @value{GDBN} does during startup
874 @end menu
875
876 @node File Options
877 @subsection Choosing files
878
879 When @value{GDBN} starts, it reads any arguments other than options as
880 specifying an executable file and core file (or process ID). This is
881 the same as if the arguments were specified by the @samp{-se} and
882 @samp{-c} (or @samp{-p} options respectively. (@value{GDBN} reads the
883 first argument that does not have an associated option flag as
884 equivalent to the @samp{-se} option followed by that argument; and the
885 second argument that does not have an associated option flag, if any, as
886 equivalent to the @samp{-c}/@samp{-p} option followed by that argument.)
887 If the second argument begins with a decimal digit, @value{GDBN} will
888 first attempt to attach to it as a process, and if that fails, attempt
889 to open it as a corefile. If you have a corefile whose name begins with
890 a digit, you can prevent @value{GDBN} from treating it as a pid by
891 prefixing it with @file{./}, e.g.@: @file{./12345}.
892
893 If @value{GDBN} has not been configured to included core file support,
894 such as for most embedded targets, then it will complain about a second
895 argument and ignore it.
896
897 Many options have both long and short forms; both are shown in the
898 following list. @value{GDBN} also recognizes the long forms if you truncate
899 them, so long as enough of the option is present to be unambiguous.
900 (If you prefer, you can flag option arguments with @samp{--} rather
901 than @samp{-}, though we illustrate the more usual convention.)
902
903 @c NOTE: the @cindex entries here use double dashes ON PURPOSE. This
904 @c way, both those who look for -foo and --foo in the index, will find
905 @c it.
906
907 @table @code
908 @item -symbols @var{file}
909 @itemx -s @var{file}
910 @cindex @code{--symbols}
911 @cindex @code{-s}
912 Read symbol table from file @var{file}.
913
914 @item -exec @var{file}
915 @itemx -e @var{file}
916 @cindex @code{--exec}
917 @cindex @code{-e}
918 Use file @var{file} as the executable file to execute when appropriate,
919 and for examining pure data in conjunction with a core dump.
920
921 @item -se @var{file}
922 @cindex @code{--se}
923 Read symbol table from file @var{file} and use it as the executable
924 file.
925
926 @item -core @var{file}
927 @itemx -c @var{file}
928 @cindex @code{--core}
929 @cindex @code{-c}
930 Use file @var{file} as a core dump to examine.
931
932 @item -c @var{number}
933 @item -pid @var{number}
934 @itemx -p @var{number}
935 @cindex @code{--pid}
936 @cindex @code{-p}
937 Connect to process ID @var{number}, as with the @code{attach} command.
938 If there is no such process, @value{GDBN} will attempt to open a core
939 file named @var{number}.
940
941 @item -command @var{file}
942 @itemx -x @var{file}
943 @cindex @code{--command}
944 @cindex @code{-x}
945 Execute @value{GDBN} commands from file @var{file}. @xref{Command
946 Files,, Command files}.
947
948 @item -eval-command @var{command}
949 @itemx -ex @var{command}
950 @cindex @code{--eval-command}
951 @cindex @code{-ex}
952 Execute a single @value{GDBN} command.
953
954 This option may be used multiple times to call multiple commands. It may
955 also be interleaved with @samp{-command} as required.
956
957 @smallexample
958 @value{GDBP} -ex 'target sim' -ex 'load' \
959 -x setbreakpoints -ex 'run' a.out
960 @end smallexample
961
962 @item -directory @var{directory}
963 @itemx -d @var{directory}
964 @cindex @code{--directory}
965 @cindex @code{-d}
966 Add @var{directory} to the path to search for source and script files.
967
968 @item -r
969 @itemx -readnow
970 @cindex @code{--readnow}
971 @cindex @code{-r}
972 Read each symbol file's entire symbol table immediately, rather than
973 the default, which is to read it incrementally as it is needed.
974 This makes startup slower, but makes future operations faster.
975
976 @end table
977
978 @node Mode Options
979 @subsection Choosing modes
980
981 You can run @value{GDBN} in various alternative modes---for example, in
982 batch mode or quiet mode.
983
984 @table @code
985 @item -nx
986 @itemx -n
987 @cindex @code{--nx}
988 @cindex @code{-n}
989 Do not execute commands found in any initialization files. Normally,
990 @value{GDBN} executes the commands in these files after all the command
991 options and arguments have been processed. @xref{Command Files,,Command
992 files}.
993
994 @item -quiet
995 @itemx -silent
996 @itemx -q
997 @cindex @code{--quiet}
998 @cindex @code{--silent}
999 @cindex @code{-q}
1000 ``Quiet''. Do not print the introductory and copyright messages. These
1001 messages are also suppressed in batch mode.
1002
1003 @item -batch
1004 @cindex @code{--batch}
1005 Run in batch mode. Exit with status @code{0} after processing all the
1006 command files specified with @samp{-x} (and all commands from
1007 initialization files, if not inhibited with @samp{-n}). Exit with
1008 nonzero status if an error occurs in executing the @value{GDBN} commands
1009 in the command files.
1010
1011 Batch mode may be useful for running @value{GDBN} as a filter, for
1012 example to download and run a program on another computer; in order to
1013 make this more useful, the message
1014
1015 @smallexample
1016 Program exited normally.
1017 @end smallexample
1018
1019 @noindent
1020 (which is ordinarily issued whenever a program running under
1021 @value{GDBN} control terminates) is not issued when running in batch
1022 mode.
1023
1024 @item -batch-silent
1025 @cindex @code{--batch-silent}
1026 Run in batch mode exactly like @samp{-batch}, but totally silently. All
1027 @value{GDBN} output to @code{stdout} is prevented (@code{stderr} is
1028 unaffected). This is much quieter than @samp{-silent} and would be useless
1029 for an interactive session.
1030
1031 This is particularly useful when using targets that give @samp{Loading section}
1032 messages, for example.
1033
1034 Note that targets that give their output via @value{GDBN}, as opposed to
1035 writing directly to @code{stdout}, will also be made silent.
1036
1037 @item -return-child-result
1038 @cindex @code{--return-child-result}
1039 The return code from @value{GDBN} will be the return code from the child
1040 process (the process being debugged), with the following exceptions:
1041
1042 @itemize @bullet
1043 @item
1044 @value{GDBN} exits abnormally. E.g., due to an incorrect argument or an
1045 internal error. In this case the exit code is the same as it would have been
1046 without @samp{-return-child-result}.
1047 @item
1048 The user quits with an explicit value. E.g., @samp{quit 1}.
1049 @item
1050 The child process never runs, or is not allowed to terminate, in which case
1051 the exit code will be -1.
1052 @end itemize
1053
1054 This option is useful in conjunction with @samp{-batch} or @samp{-batch-silent},
1055 when @value{GDBN} is being used as a remote program loader or simulator
1056 interface.
1057
1058 @item -nowindows
1059 @itemx -nw
1060 @cindex @code{--nowindows}
1061 @cindex @code{-nw}
1062 ``No windows''. If @value{GDBN} comes with a graphical user interface
1063 (GUI) built in, then this option tells @value{GDBN} to only use the command-line
1064 interface. If no GUI is available, this option has no effect.
1065
1066 @item -windows
1067 @itemx -w
1068 @cindex @code{--windows}
1069 @cindex @code{-w}
1070 If @value{GDBN} includes a GUI, then this option requires it to be
1071 used if possible.
1072
1073 @item -cd @var{directory}
1074 @cindex @code{--cd}
1075 Run @value{GDBN} using @var{directory} as its working directory,
1076 instead of the current directory.
1077
1078 @item -fullname
1079 @itemx -f
1080 @cindex @code{--fullname}
1081 @cindex @code{-f}
1082 @sc{gnu} Emacs sets this option when it runs @value{GDBN} as a
1083 subprocess. It tells @value{GDBN} to output the full file name and line
1084 number in a standard, recognizable fashion each time a stack frame is
1085 displayed (which includes each time your program stops). This
1086 recognizable format looks like two @samp{\032} characters, followed by
1087 the file name, line number and character position separated by colons,
1088 and a newline. The Emacs-to-@value{GDBN} interface program uses the two
1089 @samp{\032} characters as a signal to display the source code for the
1090 frame.
1091
1092 @item -epoch
1093 @cindex @code{--epoch}
1094 The Epoch Emacs-@value{GDBN} interface sets this option when it runs
1095 @value{GDBN} as a subprocess. It tells @value{GDBN} to modify its print
1096 routines so as to allow Epoch to display values of expressions in a
1097 separate window.
1098
1099 @item -annotate @var{level}
1100 @cindex @code{--annotate}
1101 This option sets the @dfn{annotation level} inside @value{GDBN}. Its
1102 effect is identical to using @samp{set annotate @var{level}}
1103 (@pxref{Annotations}). The annotation @var{level} controls how much
1104 information @value{GDBN} prints together with its prompt, values of
1105 expressions, source lines, and other types of output. Level 0 is the
1106 normal, level 1 is for use when @value{GDBN} is run as a subprocess of
1107 @sc{gnu} Emacs, level 3 is the maximum annotation suitable for programs
1108 that control @value{GDBN}, and level 2 has been deprecated.
1109
1110 The annotation mechanism has largely been superseded by @sc{gdb/mi}
1111 (@pxref{GDB/MI}).
1112
1113 @item --args
1114 @cindex @code{--args}
1115 Change interpretation of command line so that arguments following the
1116 executable file are passed as command line arguments to the inferior.
1117 This option stops option processing.
1118
1119 @item -baud @var{bps}
1120 @itemx -b @var{bps}
1121 @cindex @code{--baud}
1122 @cindex @code{-b}
1123 Set the line speed (baud rate or bits per second) of any serial
1124 interface used by @value{GDBN} for remote debugging.
1125
1126 @item -l @var{timeout}
1127 @cindex @code{-l}
1128 Set the timeout (in seconds) of any communication used by @value{GDBN}
1129 for remote debugging.
1130
1131 @item -tty @var{device}
1132 @itemx -t @var{device}
1133 @cindex @code{--tty}
1134 @cindex @code{-t}
1135 Run using @var{device} for your program's standard input and output.
1136 @c FIXME: kingdon thinks there is more to -tty. Investigate.
1137
1138 @c resolve the situation of these eventually
1139 @item -tui
1140 @cindex @code{--tui}
1141 Activate the @dfn{Text User Interface} when starting. The Text User
1142 Interface manages several text windows on the terminal, showing
1143 source, assembly, registers and @value{GDBN} command outputs
1144 (@pxref{TUI, ,@value{GDBN} Text User Interface}). Alternatively, the
1145 Text User Interface can be enabled by invoking the program
1146 @samp{gdbtui}. Do not use this option if you run @value{GDBN} from
1147 Emacs (@pxref{Emacs, ,Using @value{GDBN} under @sc{gnu} Emacs}).
1148
1149 @c @item -xdb
1150 @c @cindex @code{--xdb}
1151 @c Run in XDB compatibility mode, allowing the use of certain XDB commands.
1152 @c For information, see the file @file{xdb_trans.html}, which is usually
1153 @c installed in the directory @code{/opt/langtools/wdb/doc} on HP-UX
1154 @c systems.
1155
1156 @item -interpreter @var{interp}
1157 @cindex @code{--interpreter}
1158 Use the interpreter @var{interp} for interface with the controlling
1159 program or device. This option is meant to be set by programs which
1160 communicate with @value{GDBN} using it as a back end.
1161 @xref{Interpreters, , Command Interpreters}.
1162
1163 @samp{--interpreter=mi} (or @samp{--interpreter=mi2}) causes
1164 @value{GDBN} to use the @dfn{@sc{gdb/mi} interface} (@pxref{GDB/MI, ,
1165 The @sc{gdb/mi} Interface}) included since @value{GDBN} version 6.0. The
1166 previous @sc{gdb/mi} interface, included in @value{GDBN} version 5.3 and
1167 selected with @samp{--interpreter=mi1}, is deprecated. Earlier
1168 @sc{gdb/mi} interfaces are no longer supported.
1169
1170 @item -write
1171 @cindex @code{--write}
1172 Open the executable and core files for both reading and writing. This
1173 is equivalent to the @samp{set write on} command inside @value{GDBN}
1174 (@pxref{Patching}).
1175
1176 @item -statistics
1177 @cindex @code{--statistics}
1178 This option causes @value{GDBN} to print statistics about time and
1179 memory usage after it completes each command and returns to the prompt.
1180
1181 @item -version
1182 @cindex @code{--version}
1183 This option causes @value{GDBN} to print its version number and
1184 no-warranty blurb, and exit.
1185
1186 @end table
1187
1188 @node Startup
1189 @subsection What @value{GDBN} does during startup
1190 @cindex @value{GDBN} startup
1191
1192 Here's the description of what @value{GDBN} does during session startup:
1193
1194 @enumerate
1195 @item
1196 Sets up the command interpreter as specified by the command line
1197 (@pxref{Mode Options, interpreter}).
1198
1199 @item
1200 @cindex init file
1201 Reads the @dfn{init file} (if any) in your home directory@footnote{On
1202 DOS/Windows systems, the home directory is the one pointed to by the
1203 @code{HOME} environment variable.} and executes all the commands in
1204 that file.
1205
1206 @item
1207 Processes command line options and operands.
1208
1209 @item
1210 Reads and executes the commands from init file (if any) in the current
1211 working directory. This is only done if the current directory is
1212 different from your home directory. Thus, you can have more than one
1213 init file, one generic in your home directory, and another, specific
1214 to the program you are debugging, in the directory where you invoke
1215 @value{GDBN}.
1216
1217 @item
1218 Reads command files specified by the @samp{-x} option. @xref{Command
1219 Files}, for more details about @value{GDBN} command files.
1220
1221 @item
1222 Reads the command history recorded in the @dfn{history file}.
1223 @xref{Command History}, for more details about the command history and the
1224 files where @value{GDBN} records it.
1225 @end enumerate
1226
1227 Init files use the same syntax as @dfn{command files} (@pxref{Command
1228 Files}) and are processed by @value{GDBN} in the same way. The init
1229 file in your home directory can set options (such as @samp{set
1230 complaints}) that affect subsequent processing of command line options
1231 and operands. Init files are not executed if you use the @samp{-nx}
1232 option (@pxref{Mode Options, ,Choosing modes}).
1233
1234 @cindex init file name
1235 @cindex @file{.gdbinit}
1236 The @value{GDBN} init files are normally called @file{.gdbinit}.
1237 On some configurations of @value{GDBN}, the init file is known by a
1238 different name (these are typically environments where a specialized
1239 form of @value{GDBN} may need to coexist with other forms, hence a
1240 different name for the specialized version's init file). These are the
1241 environments with special init file names:
1242
1243 @itemize @bullet
1244 @cindex @file{gdb.ini}
1245 @item
1246 The DJGPP port of @value{GDBN} uses the name @file{gdb.ini}, due to
1247 the limitations of file names imposed by DOS filesystems. The Windows
1248 ports of @value{GDBN} use the standard name, but if they find a
1249 @file{gdb.ini} file, they warn you about that and suggest to rename
1250 the file to the standard name.
1251
1252 @cindex @file{.vxgdbinit}
1253 @item
1254 VxWorks (Wind River Systems real-time OS): @file{.vxgdbinit}
1255
1256 @cindex @file{.os68gdbinit}
1257 @item
1258 OS68K (Enea Data Systems real-time OS): @file{.os68gdbinit}
1259
1260 @cindex @file{.esgdbinit}
1261 @item
1262 ES-1800 (Ericsson Telecom AB M68000 emulator): @file{.esgdbinit}
1263
1264 @item
1265 CISCO 68k: @file{.cisco-gdbinit}
1266 @end itemize
1267
1268
1269 @node Quitting GDB
1270 @section Quitting @value{GDBN}
1271 @cindex exiting @value{GDBN}
1272 @cindex leaving @value{GDBN}
1273
1274 @table @code
1275 @kindex quit @r{[}@var{expression}@r{]}
1276 @kindex q @r{(@code{quit})}
1277 @item quit @r{[}@var{expression}@r{]}
1278 @itemx q
1279 To exit @value{GDBN}, use the @code{quit} command (abbreviated
1280 @code{q}), or type an end-of-file character (usually @kbd{Ctrl-d}). If you
1281 do not supply @var{expression}, @value{GDBN} will terminate normally;
1282 otherwise it will terminate using the result of @var{expression} as the
1283 error code.
1284 @end table
1285
1286 @cindex interrupt
1287 An interrupt (often @kbd{Ctrl-c}) does not exit from @value{GDBN}, but rather
1288 terminates the action of any @value{GDBN} command that is in progress and
1289 returns to @value{GDBN} command level. It is safe to type the interrupt
1290 character at any time because @value{GDBN} does not allow it to take effect
1291 until a time when it is safe.
1292
1293 If you have been using @value{GDBN} to control an attached process or
1294 device, you can release it with the @code{detach} command
1295 (@pxref{Attach, ,Debugging an already-running process}).
1296
1297 @node Shell Commands
1298 @section Shell commands
1299
1300 If you need to execute occasional shell commands during your
1301 debugging session, there is no need to leave or suspend @value{GDBN}; you can
1302 just use the @code{shell} command.
1303
1304 @table @code
1305 @kindex shell
1306 @cindex shell escape
1307 @item shell @var{command string}
1308 Invoke a standard shell to execute @var{command string}.
1309 If it exists, the environment variable @code{SHELL} determines which
1310 shell to run. Otherwise @value{GDBN} uses the default shell
1311 (@file{/bin/sh} on Unix systems, @file{COMMAND.COM} on MS-DOS, etc.).
1312 @end table
1313
1314 The utility @code{make} is often needed in development environments.
1315 You do not have to use the @code{shell} command for this purpose in
1316 @value{GDBN}:
1317
1318 @table @code
1319 @kindex make
1320 @cindex calling make
1321 @item make @var{make-args}
1322 Execute the @code{make} program with the specified
1323 arguments. This is equivalent to @samp{shell make @var{make-args}}.
1324 @end table
1325
1326 @node Logging output
1327 @section Logging output
1328 @cindex logging @value{GDBN} output
1329 @cindex save @value{GDBN} output to a file
1330
1331 You may want to save the output of @value{GDBN} commands to a file.
1332 There are several commands to control @value{GDBN}'s logging.
1333
1334 @table @code
1335 @kindex set logging
1336 @item set logging on
1337 Enable logging.
1338 @item set logging off
1339 Disable logging.
1340 @cindex logging file name
1341 @item set logging file @var{file}
1342 Change the name of the current logfile. The default logfile is @file{gdb.txt}.
1343 @item set logging overwrite [on|off]
1344 By default, @value{GDBN} will append to the logfile. Set @code{overwrite} if
1345 you want @code{set logging on} to overwrite the logfile instead.
1346 @item set logging redirect [on|off]
1347 By default, @value{GDBN} output will go to both the terminal and the logfile.
1348 Set @code{redirect} if you want output to go only to the log file.
1349 @kindex show logging
1350 @item show logging
1351 Show the current values of the logging settings.
1352 @end table
1353
1354 @node Commands
1355 @chapter @value{GDBN} Commands
1356
1357 You can abbreviate a @value{GDBN} command to the first few letters of the command
1358 name, if that abbreviation is unambiguous; and you can repeat certain
1359 @value{GDBN} commands by typing just @key{RET}. You can also use the @key{TAB}
1360 key to get @value{GDBN} to fill out the rest of a word in a command (or to
1361 show you the alternatives available, if there is more than one possibility).
1362
1363 @menu
1364 * Command Syntax:: How to give commands to @value{GDBN}
1365 * Completion:: Command completion
1366 * Help:: How to ask @value{GDBN} for help
1367 @end menu
1368
1369 @node Command Syntax
1370 @section Command syntax
1371
1372 A @value{GDBN} command is a single line of input. There is no limit on
1373 how long it can be. It starts with a command name, which is followed by
1374 arguments whose meaning depends on the command name. For example, the
1375 command @code{step} accepts an argument which is the number of times to
1376 step, as in @samp{step 5}. You can also use the @code{step} command
1377 with no arguments. Some commands do not allow any arguments.
1378
1379 @cindex abbreviation
1380 @value{GDBN} command names may always be truncated if that abbreviation is
1381 unambiguous. Other possible command abbreviations are listed in the
1382 documentation for individual commands. In some cases, even ambiguous
1383 abbreviations are allowed; for example, @code{s} is specially defined as
1384 equivalent to @code{step} even though there are other commands whose
1385 names start with @code{s}. You can test abbreviations by using them as
1386 arguments to the @code{help} command.
1387
1388 @cindex repeating commands
1389 @kindex RET @r{(repeat last command)}
1390 A blank line as input to @value{GDBN} (typing just @key{RET}) means to
1391 repeat the previous command. Certain commands (for example, @code{run})
1392 will not repeat this way; these are commands whose unintentional
1393 repetition might cause trouble and which you are unlikely to want to
1394 repeat. User-defined commands can disable this feature; see
1395 @ref{Define, dont-repeat}.
1396
1397 The @code{list} and @code{x} commands, when you repeat them with
1398 @key{RET}, construct new arguments rather than repeating
1399 exactly as typed. This permits easy scanning of source or memory.
1400
1401 @value{GDBN} can also use @key{RET} in another way: to partition lengthy
1402 output, in a way similar to the common utility @code{more}
1403 (@pxref{Screen Size,,Screen size}). Since it is easy to press one
1404 @key{RET} too many in this situation, @value{GDBN} disables command
1405 repetition after any command that generates this sort of display.
1406
1407 @kindex # @r{(a comment)}
1408 @cindex comment
1409 Any text from a @kbd{#} to the end of the line is a comment; it does
1410 nothing. This is useful mainly in command files (@pxref{Command
1411 Files,,Command files}).
1412
1413 @cindex repeating command sequences
1414 @kindex Ctrl-o @r{(operate-and-get-next)}
1415 The @kbd{Ctrl-o} binding is useful for repeating a complex sequence of
1416 commands. This command accepts the current line, like @key{RET}, and
1417 then fetches the next line relative to the current line from the history
1418 for editing.
1419
1420 @node Completion
1421 @section Command completion
1422
1423 @cindex completion
1424 @cindex word completion
1425 @value{GDBN} can fill in the rest of a word in a command for you, if there is
1426 only one possibility; it can also show you what the valid possibilities
1427 are for the next word in a command, at any time. This works for @value{GDBN}
1428 commands, @value{GDBN} subcommands, and the names of symbols in your program.
1429
1430 Press the @key{TAB} key whenever you want @value{GDBN} to fill out the rest
1431 of a word. If there is only one possibility, @value{GDBN} fills in the
1432 word, and waits for you to finish the command (or press @key{RET} to
1433 enter it). For example, if you type
1434
1435 @c FIXME "@key" does not distinguish its argument sufficiently to permit
1436 @c complete accuracy in these examples; space introduced for clarity.
1437 @c If texinfo enhancements make it unnecessary, it would be nice to
1438 @c replace " @key" by "@key" in the following...
1439 @smallexample
1440 (@value{GDBP}) info bre @key{TAB}
1441 @end smallexample
1442
1443 @noindent
1444 @value{GDBN} fills in the rest of the word @samp{breakpoints}, since that is
1445 the only @code{info} subcommand beginning with @samp{bre}:
1446
1447 @smallexample
1448 (@value{GDBP}) info breakpoints
1449 @end smallexample
1450
1451 @noindent
1452 You can either press @key{RET} at this point, to run the @code{info
1453 breakpoints} command, or backspace and enter something else, if
1454 @samp{breakpoints} does not look like the command you expected. (If you
1455 were sure you wanted @code{info breakpoints} in the first place, you
1456 might as well just type @key{RET} immediately after @samp{info bre},
1457 to exploit command abbreviations rather than command completion).
1458
1459 If there is more than one possibility for the next word when you press
1460 @key{TAB}, @value{GDBN} sounds a bell. You can either supply more
1461 characters and try again, or just press @key{TAB} a second time;
1462 @value{GDBN} displays all the possible completions for that word. For
1463 example, you might want to set a breakpoint on a subroutine whose name
1464 begins with @samp{make_}, but when you type @kbd{b make_@key{TAB}} @value{GDBN}
1465 just sounds the bell. Typing @key{TAB} again displays all the
1466 function names in your program that begin with those characters, for
1467 example:
1468
1469 @smallexample
1470 (@value{GDBP}) b make_ @key{TAB}
1471 @exdent @value{GDBN} sounds bell; press @key{TAB} again, to see:
1472 make_a_section_from_file make_environ
1473 make_abs_section make_function_type
1474 make_blockvector make_pointer_type
1475 make_cleanup make_reference_type
1476 make_command make_symbol_completion_list
1477 (@value{GDBP}) b make_
1478 @end smallexample
1479
1480 @noindent
1481 After displaying the available possibilities, @value{GDBN} copies your
1482 partial input (@samp{b make_} in the example) so you can finish the
1483 command.
1484
1485 If you just want to see the list of alternatives in the first place, you
1486 can press @kbd{M-?} rather than pressing @key{TAB} twice. @kbd{M-?}
1487 means @kbd{@key{META} ?}. You can type this either by holding down a
1488 key designated as the @key{META} shift on your keyboard (if there is
1489 one) while typing @kbd{?}, or as @key{ESC} followed by @kbd{?}.
1490
1491 @cindex quotes in commands
1492 @cindex completion of quoted strings
1493 Sometimes the string you need, while logically a ``word'', may contain
1494 parentheses or other characters that @value{GDBN} normally excludes from
1495 its notion of a word. To permit word completion to work in this
1496 situation, you may enclose words in @code{'} (single quote marks) in
1497 @value{GDBN} commands.
1498
1499 The most likely situation where you might need this is in typing the
1500 name of a C@t{++} function. This is because C@t{++} allows function
1501 overloading (multiple definitions of the same function, distinguished
1502 by argument type). For example, when you want to set a breakpoint you
1503 may need to distinguish whether you mean the version of @code{name}
1504 that takes an @code{int} parameter, @code{name(int)}, or the version
1505 that takes a @code{float} parameter, @code{name(float)}. To use the
1506 word-completion facilities in this situation, type a single quote
1507 @code{'} at the beginning of the function name. This alerts
1508 @value{GDBN} that it may need to consider more information than usual
1509 when you press @key{TAB} or @kbd{M-?} to request word completion:
1510
1511 @smallexample
1512 (@value{GDBP}) b 'bubble( @kbd{M-?}
1513 bubble(double,double) bubble(int,int)
1514 (@value{GDBP}) b 'bubble(
1515 @end smallexample
1516
1517 In some cases, @value{GDBN} can tell that completing a name requires using
1518 quotes. When this happens, @value{GDBN} inserts the quote for you (while
1519 completing as much as it can) if you do not type the quote in the first
1520 place:
1521
1522 @smallexample
1523 (@value{GDBP}) b bub @key{TAB}
1524 @exdent @value{GDBN} alters your input line to the following, and rings a bell:
1525 (@value{GDBP}) b 'bubble(
1526 @end smallexample
1527
1528 @noindent
1529 In general, @value{GDBN} can tell that a quote is needed (and inserts it) if
1530 you have not yet started typing the argument list when you ask for
1531 completion on an overloaded symbol.
1532
1533 For more information about overloaded functions, see @ref{C plus plus
1534 expressions, ,C@t{++} expressions}. You can use the command @code{set
1535 overload-resolution off} to disable overload resolution;
1536 see @ref{Debugging C plus plus, ,@value{GDBN} features for C@t{++}}.
1537
1538
1539 @node Help
1540 @section Getting help
1541 @cindex online documentation
1542 @kindex help
1543
1544 You can always ask @value{GDBN} itself for information on its commands,
1545 using the command @code{help}.
1546
1547 @table @code
1548 @kindex h @r{(@code{help})}
1549 @item help
1550 @itemx h
1551 You can use @code{help} (abbreviated @code{h}) with no arguments to
1552 display a short list of named classes of commands:
1553
1554 @smallexample
1555 (@value{GDBP}) help
1556 List of classes of commands:
1557
1558 aliases -- Aliases of other commands
1559 breakpoints -- Making program stop at certain points
1560 data -- Examining data
1561 files -- Specifying and examining files
1562 internals -- Maintenance commands
1563 obscure -- Obscure features
1564 running -- Running the program
1565 stack -- Examining the stack
1566 status -- Status inquiries
1567 support -- Support facilities
1568 tracepoints -- Tracing of program execution without@*
1569 stopping the program
1570 user-defined -- User-defined commands
1571
1572 Type "help" followed by a class name for a list of
1573 commands in that class.
1574 Type "help" followed by command name for full
1575 documentation.
1576 Command name abbreviations are allowed if unambiguous.
1577 (@value{GDBP})
1578 @end smallexample
1579 @c the above line break eliminates huge line overfull...
1580
1581 @item help @var{class}
1582 Using one of the general help classes as an argument, you can get a
1583 list of the individual commands in that class. For example, here is the
1584 help display for the class @code{status}:
1585
1586 @smallexample
1587 (@value{GDBP}) help status
1588 Status inquiries.
1589
1590 List of commands:
1591
1592 @c Line break in "show" line falsifies real output, but needed
1593 @c to fit in smallbook page size.
1594 info -- Generic command for showing things
1595 about the program being debugged
1596 show -- Generic command for showing things
1597 about the debugger
1598
1599 Type "help" followed by command name for full
1600 documentation.
1601 Command name abbreviations are allowed if unambiguous.
1602 (@value{GDBP})
1603 @end smallexample
1604
1605 @item help @var{command}
1606 With a command name as @code{help} argument, @value{GDBN} displays a
1607 short paragraph on how to use that command.
1608
1609 @kindex apropos
1610 @item apropos @var{args}
1611 The @code{apropos} command searches through all of the @value{GDBN}
1612 commands, and their documentation, for the regular expression specified in
1613 @var{args}. It prints out all matches found. For example:
1614
1615 @smallexample
1616 apropos reload
1617 @end smallexample
1618
1619 @noindent
1620 results in:
1621
1622 @smallexample
1623 @c @group
1624 set symbol-reloading -- Set dynamic symbol table reloading
1625 multiple times in one run
1626 show symbol-reloading -- Show dynamic symbol table reloading
1627 multiple times in one run
1628 @c @end group
1629 @end smallexample
1630
1631 @kindex complete
1632 @item complete @var{args}
1633 The @code{complete @var{args}} command lists all the possible completions
1634 for the beginning of a command. Use @var{args} to specify the beginning of the
1635 command you want completed. For example:
1636
1637 @smallexample
1638 complete i
1639 @end smallexample
1640
1641 @noindent results in:
1642
1643 @smallexample
1644 @group
1645 if
1646 ignore
1647 info
1648 inspect
1649 @end group
1650 @end smallexample
1651
1652 @noindent This is intended for use by @sc{gnu} Emacs.
1653 @end table
1654
1655 In addition to @code{help}, you can use the @value{GDBN} commands @code{info}
1656 and @code{show} to inquire about the state of your program, or the state
1657 of @value{GDBN} itself. Each command supports many topics of inquiry; this
1658 manual introduces each of them in the appropriate context. The listings
1659 under @code{info} and under @code{show} in the Index point to
1660 all the sub-commands. @xref{Index}.
1661
1662 @c @group
1663 @table @code
1664 @kindex info
1665 @kindex i @r{(@code{info})}
1666 @item info
1667 This command (abbreviated @code{i}) is for describing the state of your
1668 program. For example, you can list the arguments given to your program
1669 with @code{info args}, list the registers currently in use with @code{info
1670 registers}, or list the breakpoints you have set with @code{info breakpoints}.
1671 You can get a complete list of the @code{info} sub-commands with
1672 @w{@code{help info}}.
1673
1674 @kindex set
1675 @item set
1676 You can assign the result of an expression to an environment variable with
1677 @code{set}. For example, you can set the @value{GDBN} prompt to a $-sign with
1678 @code{set prompt $}.
1679
1680 @kindex show
1681 @item show
1682 In contrast to @code{info}, @code{show} is for describing the state of
1683 @value{GDBN} itself.
1684 You can change most of the things you can @code{show}, by using the
1685 related command @code{set}; for example, you can control what number
1686 system is used for displays with @code{set radix}, or simply inquire
1687 which is currently in use with @code{show radix}.
1688
1689 @kindex info set
1690 To display all the settable parameters and their current
1691 values, you can use @code{show} with no arguments; you may also use
1692 @code{info set}. Both commands produce the same display.
1693 @c FIXME: "info set" violates the rule that "info" is for state of
1694 @c FIXME...program. Ck w/ GNU: "info set" to be called something else,
1695 @c FIXME...or change desc of rule---eg "state of prog and debugging session"?
1696 @end table
1697 @c @end group
1698
1699 Here are three miscellaneous @code{show} subcommands, all of which are
1700 exceptional in lacking corresponding @code{set} commands:
1701
1702 @table @code
1703 @kindex show version
1704 @cindex @value{GDBN} version number
1705 @item show version
1706 Show what version of @value{GDBN} is running. You should include this
1707 information in @value{GDBN} bug-reports. If multiple versions of
1708 @value{GDBN} are in use at your site, you may need to determine which
1709 version of @value{GDBN} you are running; as @value{GDBN} evolves, new
1710 commands are introduced, and old ones may wither away. Also, many
1711 system vendors ship variant versions of @value{GDBN}, and there are
1712 variant versions of @value{GDBN} in @sc{gnu}/Linux distributions as well.
1713 The version number is the same as the one announced when you start
1714 @value{GDBN}.
1715
1716 @kindex show copying
1717 @kindex info copying
1718 @cindex display @value{GDBN} copyright
1719 @item show copying
1720 @itemx info copying
1721 Display information about permission for copying @value{GDBN}.
1722
1723 @kindex show warranty
1724 @kindex info warranty
1725 @item show warranty
1726 @itemx info warranty
1727 Display the @sc{gnu} ``NO WARRANTY'' statement, or a warranty,
1728 if your version of @value{GDBN} comes with one.
1729
1730 @end table
1731
1732 @node Running
1733 @chapter Running Programs Under @value{GDBN}
1734
1735 When you run a program under @value{GDBN}, you must first generate
1736 debugging information when you compile it.
1737
1738 You may start @value{GDBN} with its arguments, if any, in an environment
1739 of your choice. If you are doing native debugging, you may redirect
1740 your program's input and output, debug an already running process, or
1741 kill a child process.
1742
1743 @menu
1744 * Compilation:: Compiling for debugging
1745 * Starting:: Starting your program
1746 * Arguments:: Your program's arguments
1747 * Environment:: Your program's environment
1748
1749 * Working Directory:: Your program's working directory
1750 * Input/Output:: Your program's input and output
1751 * Attach:: Debugging an already-running process
1752 * Kill Process:: Killing the child process
1753
1754 * Threads:: Debugging programs with multiple threads
1755 * Processes:: Debugging programs with multiple processes
1756 * Checkpoint/Restart:: Setting a @emph{bookmark} to return to later
1757 @end menu
1758
1759 @node Compilation
1760 @section Compiling for debugging
1761
1762 In order to debug a program effectively, you need to generate
1763 debugging information when you compile it. This debugging information
1764 is stored in the object file; it describes the data type of each
1765 variable or function and the correspondence between source line numbers
1766 and addresses in the executable code.
1767
1768 To request debugging information, specify the @samp{-g} option when you run
1769 the compiler.
1770
1771 Programs that are to be shipped to your customers are compiled with
1772 optimizations, using the @samp{-O} compiler option. However, many
1773 compilers are unable to handle the @samp{-g} and @samp{-O} options
1774 together. Using those compilers, you cannot generate optimized
1775 executables containing debugging information.
1776
1777 @value{NGCC}, the @sc{gnu} C/C@t{++} compiler, supports @samp{-g} with or
1778 without @samp{-O}, making it possible to debug optimized code. We
1779 recommend that you @emph{always} use @samp{-g} whenever you compile a
1780 program. You may think your program is correct, but there is no sense
1781 in pushing your luck.
1782
1783 @cindex optimized code, debugging
1784 @cindex debugging optimized code
1785 When you debug a program compiled with @samp{-g -O}, remember that the
1786 optimizer is rearranging your code; the debugger shows you what is
1787 really there. Do not be too surprised when the execution path does not
1788 exactly match your source file! An extreme example: if you define a
1789 variable, but never use it, @value{GDBN} never sees that
1790 variable---because the compiler optimizes it out of existence.
1791
1792 Some things do not work as well with @samp{-g -O} as with just
1793 @samp{-g}, particularly on machines with instruction scheduling. If in
1794 doubt, recompile with @samp{-g} alone, and if this fixes the problem,
1795 please report it to us as a bug (including a test case!).
1796 @xref{Variables}, for more information about debugging optimized code.
1797
1798 Older versions of the @sc{gnu} C compiler permitted a variant option
1799 @w{@samp{-gg}} for debugging information. @value{GDBN} no longer supports this
1800 format; if your @sc{gnu} C compiler has this option, do not use it.
1801
1802 @value{GDBN} knows about preprocessor macros and can show you their
1803 expansion (@pxref{Macros}). Most compilers do not include information
1804 about preprocessor macros in the debugging information if you specify
1805 the @option{-g} flag alone, because this information is rather large.
1806 Version 3.1 and later of @value{NGCC}, the @sc{gnu} C compiler,
1807 provides macro information if you specify the options
1808 @option{-gdwarf-2} and @option{-g3}; the former option requests
1809 debugging information in the Dwarf 2 format, and the latter requests
1810 ``extra information''. In the future, we hope to find more compact
1811 ways to represent macro information, so that it can be included with
1812 @option{-g} alone.
1813
1814 @need 2000
1815 @node Starting
1816 @section Starting your program
1817 @cindex starting
1818 @cindex running
1819
1820 @table @code
1821 @kindex run
1822 @kindex r @r{(@code{run})}
1823 @item run
1824 @itemx r
1825 Use the @code{run} command to start your program under @value{GDBN}.
1826 You must first specify the program name (except on VxWorks) with an
1827 argument to @value{GDBN} (@pxref{Invocation, ,Getting In and Out of
1828 @value{GDBN}}), or by using the @code{file} or @code{exec-file} command
1829 (@pxref{Files, ,Commands to specify files}).
1830
1831 @end table
1832
1833 If you are running your program in an execution environment that
1834 supports processes, @code{run} creates an inferior process and makes
1835 that process run your program. (In environments without processes,
1836 @code{run} jumps to the start of your program.)
1837
1838 The execution of a program is affected by certain information it
1839 receives from its superior. @value{GDBN} provides ways to specify this
1840 information, which you must do @emph{before} starting your program. (You
1841 can change it after starting your program, but such changes only affect
1842 your program the next time you start it.) This information may be
1843 divided into four categories:
1844
1845 @table @asis
1846 @item The @emph{arguments.}
1847 Specify the arguments to give your program as the arguments of the
1848 @code{run} command. If a shell is available on your target, the shell
1849 is used to pass the arguments, so that you may use normal conventions
1850 (such as wildcard expansion or variable substitution) in describing
1851 the arguments.
1852 In Unix systems, you can control which shell is used with the
1853 @code{SHELL} environment variable.
1854 @xref{Arguments, ,Your program's arguments}.
1855
1856 @item The @emph{environment.}
1857 Your program normally inherits its environment from @value{GDBN}, but you can
1858 use the @value{GDBN} commands @code{set environment} and @code{unset
1859 environment} to change parts of the environment that affect
1860 your program. @xref{Environment, ,Your program's environment}.
1861
1862 @item The @emph{working directory.}
1863 Your program inherits its working directory from @value{GDBN}. You can set
1864 the @value{GDBN} working directory with the @code{cd} command in @value{GDBN}.
1865 @xref{Working Directory, ,Your program's working directory}.
1866
1867 @item The @emph{standard input and output.}
1868 Your program normally uses the same device for standard input and
1869 standard output as @value{GDBN} is using. You can redirect input and output
1870 in the @code{run} command line, or you can use the @code{tty} command to
1871 set a different device for your program.
1872 @xref{Input/Output, ,Your program's input and output}.
1873
1874 @cindex pipes
1875 @emph{Warning:} While input and output redirection work, you cannot use
1876 pipes to pass the output of the program you are debugging to another
1877 program; if you attempt this, @value{GDBN} is likely to wind up debugging the
1878 wrong program.
1879 @end table
1880
1881 When you issue the @code{run} command, your program begins to execute
1882 immediately. @xref{Stopping, ,Stopping and continuing}, for discussion
1883 of how to arrange for your program to stop. Once your program has
1884 stopped, you may call functions in your program, using the @code{print}
1885 or @code{call} commands. @xref{Data, ,Examining Data}.
1886
1887 If the modification time of your symbol file has changed since the last
1888 time @value{GDBN} read its symbols, @value{GDBN} discards its symbol
1889 table, and reads it again. When it does this, @value{GDBN} tries to retain
1890 your current breakpoints.
1891
1892 @table @code
1893 @kindex start
1894 @item start
1895 @cindex run to main procedure
1896 The name of the main procedure can vary from language to language.
1897 With C or C@t{++}, the main procedure name is always @code{main}, but
1898 other languages such as Ada do not require a specific name for their
1899 main procedure. The debugger provides a convenient way to start the
1900 execution of the program and to stop at the beginning of the main
1901 procedure, depending on the language used.
1902
1903 The @samp{start} command does the equivalent of setting a temporary
1904 breakpoint at the beginning of the main procedure and then invoking
1905 the @samp{run} command.
1906
1907 @cindex elaboration phase
1908 Some programs contain an @dfn{elaboration} phase where some startup code is
1909 executed before the main procedure is called. This depends on the
1910 languages used to write your program. In C@t{++}, for instance,
1911 constructors for static and global objects are executed before
1912 @code{main} is called. It is therefore possible that the debugger stops
1913 before reaching the main procedure. However, the temporary breakpoint
1914 will remain to halt execution.
1915
1916 Specify the arguments to give to your program as arguments to the
1917 @samp{start} command. These arguments will be given verbatim to the
1918 underlying @samp{run} command. Note that the same arguments will be
1919 reused if no argument is provided during subsequent calls to
1920 @samp{start} or @samp{run}.
1921
1922 It is sometimes necessary to debug the program during elaboration. In
1923 these cases, using the @code{start} command would stop the execution of
1924 your program too late, as the program would have already completed the
1925 elaboration phase. Under these circumstances, insert breakpoints in your
1926 elaboration code before running your program.
1927 @end table
1928
1929 @node Arguments
1930 @section Your program's arguments
1931
1932 @cindex arguments (to your program)
1933 The arguments to your program can be specified by the arguments of the
1934 @code{run} command.
1935 They are passed to a shell, which expands wildcard characters and
1936 performs redirection of I/O, and thence to your program. Your
1937 @code{SHELL} environment variable (if it exists) specifies what shell
1938 @value{GDBN} uses. If you do not define @code{SHELL}, @value{GDBN} uses
1939 the default shell (@file{/bin/sh} on Unix).
1940
1941 On non-Unix systems, the program is usually invoked directly by
1942 @value{GDBN}, which emulates I/O redirection via the appropriate system
1943 calls, and the wildcard characters are expanded by the startup code of
1944 the program, not by the shell.
1945
1946 @code{run} with no arguments uses the same arguments used by the previous
1947 @code{run}, or those set by the @code{set args} command.
1948
1949 @table @code
1950 @kindex set args
1951 @item set args
1952 Specify the arguments to be used the next time your program is run. If
1953 @code{set args} has no arguments, @code{run} executes your program
1954 with no arguments. Once you have run your program with arguments,
1955 using @code{set args} before the next @code{run} is the only way to run
1956 it again without arguments.
1957
1958 @kindex show args
1959 @item show args
1960 Show the arguments to give your program when it is started.
1961 @end table
1962
1963 @node Environment
1964 @section Your program's environment
1965
1966 @cindex environment (of your program)
1967 The @dfn{environment} consists of a set of environment variables and
1968 their values. Environment variables conventionally record such things as
1969 your user name, your home directory, your terminal type, and your search
1970 path for programs to run. Usually you set up environment variables with
1971 the shell and they are inherited by all the other programs you run. When
1972 debugging, it can be useful to try running your program with a modified
1973 environment without having to start @value{GDBN} over again.
1974
1975 @table @code
1976 @kindex path
1977 @item path @var{directory}
1978 Add @var{directory} to the front of the @code{PATH} environment variable
1979 (the search path for executables) that will be passed to your program.
1980 The value of @code{PATH} used by @value{GDBN} does not change.
1981 You may specify several directory names, separated by whitespace or by a
1982 system-dependent separator character (@samp{:} on Unix, @samp{;} on
1983 MS-DOS and MS-Windows). If @var{directory} is already in the path, it
1984 is moved to the front, so it is searched sooner.
1985
1986 You can use the string @samp{$cwd} to refer to whatever is the current
1987 working directory at the time @value{GDBN} searches the path. If you
1988 use @samp{.} instead, it refers to the directory where you executed the
1989 @code{path} command. @value{GDBN} replaces @samp{.} in the
1990 @var{directory} argument (with the current path) before adding
1991 @var{directory} to the search path.
1992 @c 'path' is explicitly nonrepeatable, but RMS points out it is silly to
1993 @c document that, since repeating it would be a no-op.
1994
1995 @kindex show paths
1996 @item show paths
1997 Display the list of search paths for executables (the @code{PATH}
1998 environment variable).
1999
2000 @kindex show environment
2001 @item show environment @r{[}@var{varname}@r{]}
2002 Print the value of environment variable @var{varname} to be given to
2003 your program when it starts. If you do not supply @var{varname},
2004 print the names and values of all environment variables to be given to
2005 your program. You can abbreviate @code{environment} as @code{env}.
2006
2007 @kindex set environment
2008 @item set environment @var{varname} @r{[}=@var{value}@r{]}
2009 Set environment variable @var{varname} to @var{value}. The value
2010 changes for your program only, not for @value{GDBN} itself. @var{value} may
2011 be any string; the values of environment variables are just strings, and
2012 any interpretation is supplied by your program itself. The @var{value}
2013 parameter is optional; if it is eliminated, the variable is set to a
2014 null value.
2015 @c "any string" here does not include leading, trailing
2016 @c blanks. Gnu asks: does anyone care?
2017
2018 For example, this command:
2019
2020 @smallexample
2021 set env USER = foo
2022 @end smallexample
2023
2024 @noindent
2025 tells the debugged program, when subsequently run, that its user is named
2026 @samp{foo}. (The spaces around @samp{=} are used for clarity here; they
2027 are not actually required.)
2028
2029 @kindex unset environment
2030 @item unset environment @var{varname}
2031 Remove variable @var{varname} from the environment to be passed to your
2032 program. This is different from @samp{set env @var{varname} =};
2033 @code{unset environment} removes the variable from the environment,
2034 rather than assigning it an empty value.
2035 @end table
2036
2037 @emph{Warning:} On Unix systems, @value{GDBN} runs your program using
2038 the shell indicated
2039 by your @code{SHELL} environment variable if it exists (or
2040 @code{/bin/sh} if not). If your @code{SHELL} variable names a shell
2041 that runs an initialization file---such as @file{.cshrc} for C-shell, or
2042 @file{.bashrc} for BASH---any variables you set in that file affect
2043 your program. You may wish to move setting of environment variables to
2044 files that are only run when you sign on, such as @file{.login} or
2045 @file{.profile}.
2046
2047 @node Working Directory
2048 @section Your program's working directory
2049
2050 @cindex working directory (of your program)
2051 Each time you start your program with @code{run}, it inherits its
2052 working directory from the current working directory of @value{GDBN}.
2053 The @value{GDBN} working directory is initially whatever it inherited
2054 from its parent process (typically the shell), but you can specify a new
2055 working directory in @value{GDBN} with the @code{cd} command.
2056
2057 The @value{GDBN} working directory also serves as a default for the commands
2058 that specify files for @value{GDBN} to operate on. @xref{Files, ,Commands to
2059 specify files}.
2060
2061 @table @code
2062 @kindex cd
2063 @cindex change working directory
2064 @item cd @var{directory}
2065 Set the @value{GDBN} working directory to @var{directory}.
2066
2067 @kindex pwd
2068 @item pwd
2069 Print the @value{GDBN} working directory.
2070 @end table
2071
2072 It is generally impossible to find the current working directory of
2073 the process being debugged (since a program can change its directory
2074 during its run). If you work on a system where @value{GDBN} is
2075 configured with the @file{/proc} support, you can use the @code{info
2076 proc} command (@pxref{SVR4 Process Information}) to find out the
2077 current working directory of the debuggee.
2078
2079 @node Input/Output
2080 @section Your program's input and output
2081
2082 @cindex redirection
2083 @cindex i/o
2084 @cindex terminal
2085 By default, the program you run under @value{GDBN} does input and output to
2086 the same terminal that @value{GDBN} uses. @value{GDBN} switches the terminal
2087 to its own terminal modes to interact with you, but it records the terminal
2088 modes your program was using and switches back to them when you continue
2089 running your program.
2090
2091 @table @code
2092 @kindex info terminal
2093 @item info terminal
2094 Displays information recorded by @value{GDBN} about the terminal modes your
2095 program is using.
2096 @end table
2097
2098 You can redirect your program's input and/or output using shell
2099 redirection with the @code{run} command. For example,
2100
2101 @smallexample
2102 run > outfile
2103 @end smallexample
2104
2105 @noindent
2106 starts your program, diverting its output to the file @file{outfile}.
2107
2108 @kindex tty
2109 @cindex controlling terminal
2110 Another way to specify where your program should do input and output is
2111 with the @code{tty} command. This command accepts a file name as
2112 argument, and causes this file to be the default for future @code{run}
2113 commands. It also resets the controlling terminal for the child
2114 process, for future @code{run} commands. For example,
2115
2116 @smallexample
2117 tty /dev/ttyb
2118 @end smallexample
2119
2120 @noindent
2121 directs that processes started with subsequent @code{run} commands
2122 default to do input and output on the terminal @file{/dev/ttyb} and have
2123 that as their controlling terminal.
2124
2125 An explicit redirection in @code{run} overrides the @code{tty} command's
2126 effect on the input/output device, but not its effect on the controlling
2127 terminal.
2128
2129 When you use the @code{tty} command or redirect input in the @code{run}
2130 command, only the input @emph{for your program} is affected. The input
2131 for @value{GDBN} still comes from your terminal. @code{tty} is an alias
2132 for @code{set inferior-tty}.
2133
2134 @cindex inferior tty
2135 @cindex set inferior controlling terminal
2136 You can use the @code{show inferior-tty} command to tell @value{GDBN} to
2137 display the name of the terminal that will be used for future runs of your
2138 program.
2139
2140 @table @code
2141 @item set inferior-tty /dev/ttyb
2142 @kindex set inferior-tty
2143 Set the tty for the program being debugged to /dev/ttyb.
2144
2145 @item show inferior-tty
2146 @kindex show inferior-tty
2147 Show the current tty for the program being debugged.
2148 @end table
2149
2150 @node Attach
2151 @section Debugging an already-running process
2152 @kindex attach
2153 @cindex attach
2154
2155 @table @code
2156 @item attach @var{process-id}
2157 This command attaches to a running process---one that was started
2158 outside @value{GDBN}. (@code{info files} shows your active
2159 targets.) The command takes as argument a process ID. The usual way to
2160 find out the @var{process-id} of a Unix process is with the @code{ps} utility,
2161 or with the @samp{jobs -l} shell command.
2162
2163 @code{attach} does not repeat if you press @key{RET} a second time after
2164 executing the command.
2165 @end table
2166
2167 To use @code{attach}, your program must be running in an environment
2168 which supports processes; for example, @code{attach} does not work for
2169 programs on bare-board targets that lack an operating system. You must
2170 also have permission to send the process a signal.
2171
2172 When you use @code{attach}, the debugger finds the program running in
2173 the process first by looking in the current working directory, then (if
2174 the program is not found) by using the source file search path
2175 (@pxref{Source Path, ,Specifying source directories}). You can also use
2176 the @code{file} command to load the program. @xref{Files, ,Commands to
2177 Specify Files}.
2178
2179 The first thing @value{GDBN} does after arranging to debug the specified
2180 process is to stop it. You can examine and modify an attached process
2181 with all the @value{GDBN} commands that are ordinarily available when
2182 you start processes with @code{run}. You can insert breakpoints; you
2183 can step and continue; you can modify storage. If you would rather the
2184 process continue running, you may use the @code{continue} command after
2185 attaching @value{GDBN} to the process.
2186
2187 @table @code
2188 @kindex detach
2189 @item detach
2190 When you have finished debugging the attached process, you can use the
2191 @code{detach} command to release it from @value{GDBN} control. Detaching
2192 the process continues its execution. After the @code{detach} command,
2193 that process and @value{GDBN} become completely independent once more, and you
2194 are ready to @code{attach} another process or start one with @code{run}.
2195 @code{detach} does not repeat if you press @key{RET} again after
2196 executing the command.
2197 @end table
2198
2199 If you exit @value{GDBN} or use the @code{run} command while you have an
2200 attached process, you kill that process. By default, @value{GDBN} asks
2201 for confirmation if you try to do either of these things; you can
2202 control whether or not you need to confirm by using the @code{set
2203 confirm} command (@pxref{Messages/Warnings, ,Optional warnings and
2204 messages}).
2205
2206 @node Kill Process
2207 @section Killing the child process
2208
2209 @table @code
2210 @kindex kill
2211 @item kill
2212 Kill the child process in which your program is running under @value{GDBN}.
2213 @end table
2214
2215 This command is useful if you wish to debug a core dump instead of a
2216 running process. @value{GDBN} ignores any core dump file while your program
2217 is running.
2218
2219 On some operating systems, a program cannot be executed outside @value{GDBN}
2220 while you have breakpoints set on it inside @value{GDBN}. You can use the
2221 @code{kill} command in this situation to permit running your program
2222 outside the debugger.
2223
2224 The @code{kill} command is also useful if you wish to recompile and
2225 relink your program, since on many systems it is impossible to modify an
2226 executable file while it is running in a process. In this case, when you
2227 next type @code{run}, @value{GDBN} notices that the file has changed, and
2228 reads the symbol table again (while trying to preserve your current
2229 breakpoint settings).
2230
2231 @node Threads
2232 @section Debugging programs with multiple threads
2233
2234 @cindex threads of execution
2235 @cindex multiple threads
2236 @cindex switching threads
2237 In some operating systems, such as HP-UX and Solaris, a single program
2238 may have more than one @dfn{thread} of execution. The precise semantics
2239 of threads differ from one operating system to another, but in general
2240 the threads of a single program are akin to multiple processes---except
2241 that they share one address space (that is, they can all examine and
2242 modify the same variables). On the other hand, each thread has its own
2243 registers and execution stack, and perhaps private memory.
2244
2245 @value{GDBN} provides these facilities for debugging multi-thread
2246 programs:
2247
2248 @itemize @bullet
2249 @item automatic notification of new threads
2250 @item @samp{thread @var{threadno}}, a command to switch among threads
2251 @item @samp{info threads}, a command to inquire about existing threads
2252 @item @samp{thread apply [@var{threadno}] [@var{all}] @var{args}},
2253 a command to apply a command to a list of threads
2254 @item thread-specific breakpoints
2255 @end itemize
2256
2257 @quotation
2258 @emph{Warning:} These facilities are not yet available on every
2259 @value{GDBN} configuration where the operating system supports threads.
2260 If your @value{GDBN} does not support threads, these commands have no
2261 effect. For example, a system without thread support shows no output
2262 from @samp{info threads}, and always rejects the @code{thread} command,
2263 like this:
2264
2265 @smallexample
2266 (@value{GDBP}) info threads
2267 (@value{GDBP}) thread 1
2268 Thread ID 1 not known. Use the "info threads" command to
2269 see the IDs of currently known threads.
2270 @end smallexample
2271 @c FIXME to implementors: how hard would it be to say "sorry, this GDB
2272 @c doesn't support threads"?
2273 @end quotation
2274
2275 @cindex focus of debugging
2276 @cindex current thread
2277 The @value{GDBN} thread debugging facility allows you to observe all
2278 threads while your program runs---but whenever @value{GDBN} takes
2279 control, one thread in particular is always the focus of debugging.
2280 This thread is called the @dfn{current thread}. Debugging commands show
2281 program information from the perspective of the current thread.
2282
2283 @cindex @code{New} @var{systag} message
2284 @cindex thread identifier (system)
2285 @c FIXME-implementors!! It would be more helpful if the [New...] message
2286 @c included GDB's numeric thread handle, so you could just go to that
2287 @c thread without first checking `info threads'.
2288 Whenever @value{GDBN} detects a new thread in your program, it displays
2289 the target system's identification for the thread with a message in the
2290 form @samp{[New @var{systag}]}. @var{systag} is a thread identifier
2291 whose form varies depending on the particular system. For example, on
2292 LynxOS, you might see
2293
2294 @smallexample
2295 [New process 35 thread 27]
2296 @end smallexample
2297
2298 @noindent
2299 when @value{GDBN} notices a new thread. In contrast, on an SGI system,
2300 the @var{systag} is simply something like @samp{process 368}, with no
2301 further qualifier.
2302
2303 @c FIXME!! (1) Does the [New...] message appear even for the very first
2304 @c thread of a program, or does it only appear for the
2305 @c second---i.e.@: when it becomes obvious we have a multithread
2306 @c program?
2307 @c (2) *Is* there necessarily a first thread always? Or do some
2308 @c multithread systems permit starting a program with multiple
2309 @c threads ab initio?
2310
2311 @cindex thread number
2312 @cindex thread identifier (GDB)
2313 For debugging purposes, @value{GDBN} associates its own thread
2314 number---always a single integer---with each thread in your program.
2315
2316 @table @code
2317 @kindex info threads
2318 @item info threads
2319 Display a summary of all threads currently in your
2320 program. @value{GDBN} displays for each thread (in this order):
2321
2322 @enumerate
2323 @item
2324 the thread number assigned by @value{GDBN}
2325
2326 @item
2327 the target system's thread identifier (@var{systag})
2328
2329 @item
2330 the current stack frame summary for that thread
2331 @end enumerate
2332
2333 @noindent
2334 An asterisk @samp{*} to the left of the @value{GDBN} thread number
2335 indicates the current thread.
2336
2337 For example,
2338 @end table
2339 @c end table here to get a little more width for example
2340
2341 @smallexample
2342 (@value{GDBP}) info threads
2343 3 process 35 thread 27 0x34e5 in sigpause ()
2344 2 process 35 thread 23 0x34e5 in sigpause ()
2345 * 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8)
2346 at threadtest.c:68
2347 @end smallexample
2348
2349 On HP-UX systems:
2350
2351 @cindex debugging multithreaded programs (on HP-UX)
2352 @cindex thread identifier (GDB), on HP-UX
2353 For debugging purposes, @value{GDBN} associates its own thread
2354 number---a small integer assigned in thread-creation order---with each
2355 thread in your program.
2356
2357 @cindex @code{New} @var{systag} message, on HP-UX
2358 @cindex thread identifier (system), on HP-UX
2359 @c FIXME-implementors!! It would be more helpful if the [New...] message
2360 @c included GDB's numeric thread handle, so you could just go to that
2361 @c thread without first checking `info threads'.
2362 Whenever @value{GDBN} detects a new thread in your program, it displays
2363 both @value{GDBN}'s thread number and the target system's identification for the thread with a message in the
2364 form @samp{[New @var{systag}]}. @var{systag} is a thread identifier
2365 whose form varies depending on the particular system. For example, on
2366 HP-UX, you see
2367
2368 @smallexample
2369 [New thread 2 (system thread 26594)]
2370 @end smallexample
2371
2372 @noindent
2373 when @value{GDBN} notices a new thread.
2374
2375 @table @code
2376 @kindex info threads (HP-UX)
2377 @item info threads
2378 Display a summary of all threads currently in your
2379 program. @value{GDBN} displays for each thread (in this order):
2380
2381 @enumerate
2382 @item the thread number assigned by @value{GDBN}
2383
2384 @item the target system's thread identifier (@var{systag})
2385
2386 @item the current stack frame summary for that thread
2387 @end enumerate
2388
2389 @noindent
2390 An asterisk @samp{*} to the left of the @value{GDBN} thread number
2391 indicates the current thread.
2392
2393 For example,
2394 @end table
2395 @c end table here to get a little more width for example
2396
2397 @smallexample
2398 (@value{GDBP}) info threads
2399 * 3 system thread 26607 worker (wptr=0x7b09c318 "@@") \@*
2400 at quicksort.c:137
2401 2 system thread 26606 0x7b0030d8 in __ksleep () \@*
2402 from /usr/lib/libc.2
2403 1 system thread 27905 0x7b003498 in _brk () \@*
2404 from /usr/lib/libc.2
2405 @end smallexample
2406
2407 On Solaris, you can display more information about user threads with a
2408 Solaris-specific command:
2409
2410 @table @code
2411 @item maint info sol-threads
2412 @kindex maint info sol-threads
2413 @cindex thread info (Solaris)
2414 Display info on Solaris user threads.
2415 @end table
2416
2417 @table @code
2418 @kindex thread @var{threadno}
2419 @item thread @var{threadno}
2420 Make thread number @var{threadno} the current thread. The command
2421 argument @var{threadno} is the internal @value{GDBN} thread number, as
2422 shown in the first field of the @samp{info threads} display.
2423 @value{GDBN} responds by displaying the system identifier of the thread
2424 you selected, and its current stack frame summary:
2425
2426 @smallexample
2427 @c FIXME!! This example made up; find a @value{GDBN} w/threads and get real one
2428 (@value{GDBP}) thread 2
2429 [Switching to process 35 thread 23]
2430 0x34e5 in sigpause ()
2431 @end smallexample
2432
2433 @noindent
2434 As with the @samp{[New @dots{}]} message, the form of the text after
2435 @samp{Switching to} depends on your system's conventions for identifying
2436 threads.
2437
2438 @kindex thread apply
2439 @cindex apply command to several threads
2440 @item thread apply [@var{threadno}] [@var{all}] @var{command}
2441 The @code{thread apply} command allows you to apply the named
2442 @var{command} to one or more threads. Specify the numbers of the
2443 threads that you want affected with the command argument
2444 @var{threadno}. It can be a single thread number, one of the numbers
2445 shown in the first field of the @samp{info threads} display; or it
2446 could be a range of thread numbers, as in @code{2-4}. To apply a
2447 command to all threads, type @kbd{thread apply all @var{command}}.
2448 @end table
2449
2450 @cindex automatic thread selection
2451 @cindex switching threads automatically
2452 @cindex threads, automatic switching
2453 Whenever @value{GDBN} stops your program, due to a breakpoint or a
2454 signal, it automatically selects the thread where that breakpoint or
2455 signal happened. @value{GDBN} alerts you to the context switch with a
2456 message of the form @samp{[Switching to @var{systag}]} to identify the
2457 thread.
2458
2459 @xref{Thread Stops,,Stopping and starting multi-thread programs}, for
2460 more information about how @value{GDBN} behaves when you stop and start
2461 programs with multiple threads.
2462
2463 @xref{Set Watchpoints,,Setting watchpoints}, for information about
2464 watchpoints in programs with multiple threads.
2465
2466 @node Processes
2467 @section Debugging programs with multiple processes
2468
2469 @cindex fork, debugging programs which call
2470 @cindex multiple processes
2471 @cindex processes, multiple
2472 On most systems, @value{GDBN} has no special support for debugging
2473 programs which create additional processes using the @code{fork}
2474 function. When a program forks, @value{GDBN} will continue to debug the
2475 parent process and the child process will run unimpeded. If you have
2476 set a breakpoint in any code which the child then executes, the child
2477 will get a @code{SIGTRAP} signal which (unless it catches the signal)
2478 will cause it to terminate.
2479
2480 However, if you want to debug the child process there is a workaround
2481 which isn't too painful. Put a call to @code{sleep} in the code which
2482 the child process executes after the fork. It may be useful to sleep
2483 only if a certain environment variable is set, or a certain file exists,
2484 so that the delay need not occur when you don't want to run @value{GDBN}
2485 on the child. While the child is sleeping, use the @code{ps} program to
2486 get its process ID. Then tell @value{GDBN} (a new invocation of
2487 @value{GDBN} if you are also debugging the parent process) to attach to
2488 the child process (@pxref{Attach}). From that point on you can debug
2489 the child process just like any other process which you attached to.
2490
2491 On some systems, @value{GDBN} provides support for debugging programs that
2492 create additional processes using the @code{fork} or @code{vfork} functions.
2493 Currently, the only platforms with this feature are HP-UX (11.x and later
2494 only?) and GNU/Linux (kernel version 2.5.60 and later).
2495
2496 By default, when a program forks, @value{GDBN} will continue to debug
2497 the parent process and the child process will run unimpeded.
2498
2499 If you want to follow the child process instead of the parent process,
2500 use the command @w{@code{set follow-fork-mode}}.
2501
2502 @table @code
2503 @kindex set follow-fork-mode
2504 @item set follow-fork-mode @var{mode}
2505 Set the debugger response to a program call of @code{fork} or
2506 @code{vfork}. A call to @code{fork} or @code{vfork} creates a new
2507 process. The @var{mode} argument can be:
2508
2509 @table @code
2510 @item parent
2511 The original process is debugged after a fork. The child process runs
2512 unimpeded. This is the default.
2513
2514 @item child
2515 The new process is debugged after a fork. The parent process runs
2516 unimpeded.
2517
2518 @end table
2519
2520 @kindex show follow-fork-mode
2521 @item show follow-fork-mode
2522 Display the current debugger response to a @code{fork} or @code{vfork} call.
2523 @end table
2524
2525 @cindex debugging multiple processes
2526 On Linux, if you want to debug both the parent and child processes, use the
2527 command @w{@code{set detach-on-fork}}.
2528
2529 @table @code
2530 @kindex set detach-on-fork
2531 @item set detach-on-fork @var{mode}
2532 Tells gdb whether to detach one of the processes after a fork, or
2533 retain debugger control over them both.
2534
2535 @table @code
2536 @item on
2537 The child process (or parent process, depending on the value of
2538 @code{follow-fork-mode}) will be detached and allowed to run
2539 independently. This is the default.
2540
2541 @item off
2542 Both processes will be held under the control of @value{GDBN}.
2543 One process (child or parent, depending on the value of
2544 @code{follow-fork-mode}) is debugged as usual, while the other
2545 is held suspended.
2546
2547 @end table
2548
2549 @kindex show detach-on-follow
2550 @item show detach-on-follow
2551 Show whether detach-on-follow mode is on/off.
2552 @end table
2553
2554 If you choose to set @var{detach-on-follow} mode off, then
2555 @value{GDBN} will retain control of all forked processes (including
2556 nested forks). You can list the forked processes under the control of
2557 @value{GDBN} by using the @w{@code{info forks}} command, and switch
2558 from one fork to another by using the @w{@code{fork}} command.
2559
2560 @table @code
2561 @kindex info forks
2562 @item info forks
2563 Print a list of all forked processes under the control of @value{GDBN}.
2564 The listing will include a fork id, a process id, and the current
2565 position (program counter) of the process.
2566
2567
2568 @kindex fork @var{fork-id}
2569 @item fork @var{fork-id}
2570 Make fork number @var{fork-id} the current process. The argument
2571 @var{fork-id} is the internal fork number assigned by @value{GDBN},
2572 as shown in the first field of the @samp{info forks} display.
2573
2574 @end table
2575
2576 To quit debugging one of the forked processes, you can either detach
2577 from it by using the @w{@code{detach-fork}} command (allowing it to
2578 run independently), or delete (and kill) it using the
2579 @w{@code{delete fork}} command.
2580
2581 @table @code
2582 @kindex detach-fork @var{fork-id}
2583 @item detach-fork @var{fork-id}
2584 Detach from the process identified by @value{GDBN} fork number
2585 @var{fork-id}, and remove it from the fork list. The process will be
2586 allowed to run independently.
2587
2588 @kindex delete fork @var{fork-id}
2589 @item delete fork @var{fork-id}
2590 Kill the process identified by @value{GDBN} fork number @var{fork-id},
2591 and remove it from the fork list.
2592
2593 @end table
2594
2595 If you ask to debug a child process and a @code{vfork} is followed by an
2596 @code{exec}, @value{GDBN} executes the new target up to the first
2597 breakpoint in the new target. If you have a breakpoint set on
2598 @code{main} in your original program, the breakpoint will also be set on
2599 the child process's @code{main}.
2600
2601 When a child process is spawned by @code{vfork}, you cannot debug the
2602 child or parent until an @code{exec} call completes.
2603
2604 If you issue a @code{run} command to @value{GDBN} after an @code{exec}
2605 call executes, the new target restarts. To restart the parent process,
2606 use the @code{file} command with the parent executable name as its
2607 argument.
2608
2609 You can use the @code{catch} command to make @value{GDBN} stop whenever
2610 a @code{fork}, @code{vfork}, or @code{exec} call is made. @xref{Set
2611 Catchpoints, ,Setting catchpoints}.
2612
2613 @node Checkpoint/Restart
2614 @section Setting a @emph{bookmark} to return to later
2615
2616 @cindex checkpoint
2617 @cindex restart
2618 @cindex bookmark
2619 @cindex snapshot of a process
2620 @cindex rewind program state
2621
2622 On certain operating systems@footnote{Currently, only
2623 @sc{gnu}/Linux.}, @value{GDBN} is able to save a @dfn{snapshot} of a
2624 program's state, called a @dfn{checkpoint}, and come back to it
2625 later.
2626
2627 Returning to a checkpoint effectively undoes everything that has
2628 happened in the program since the @code{checkpoint} was saved. This
2629 includes changes in memory, registers, and even (within some limits)
2630 system state. Effectively, it is like going back in time to the
2631 moment when the checkpoint was saved.
2632
2633 Thus, if you're stepping thru a program and you think you're
2634 getting close to the point where things go wrong, you can save
2635 a checkpoint. Then, if you accidentally go too far and miss
2636 the critical statement, instead of having to restart your program
2637 from the beginning, you can just go back to the checkpoint and
2638 start again from there.
2639
2640 This can be especially useful if it takes a lot of time or
2641 steps to reach the point where you think the bug occurs.
2642
2643 To use the @code{checkpoint}/@code{restart} method of debugging:
2644
2645 @table @code
2646 @kindex checkpoint
2647 @item checkpoint
2648 Save a snapshot of the debugged program's current execution state.
2649 The @code{checkpoint} command takes no arguments, but each checkpoint
2650 is assigned a small integer id, similar to a breakpoint id.
2651
2652 @kindex info checkpoints
2653 @item info checkpoints
2654 List the checkpoints that have been saved in the current debugging
2655 session. For each checkpoint, the following information will be
2656 listed:
2657
2658 @table @code
2659 @item Checkpoint ID
2660 @item Process ID
2661 @item Code Address
2662 @item Source line, or label
2663 @end table
2664
2665 @kindex restart @var{checkpoint-id}
2666 @item restart @var{checkpoint-id}
2667 Restore the program state that was saved as checkpoint number
2668 @var{checkpoint-id}. All program variables, registers, stack frames
2669 etc.@: will be returned to the values that they had when the checkpoint
2670 was saved. In essence, gdb will ``wind back the clock'' to the point
2671 in time when the checkpoint was saved.
2672
2673 Note that breakpoints, @value{GDBN} variables, command history etc.
2674 are not affected by restoring a checkpoint. In general, a checkpoint
2675 only restores things that reside in the program being debugged, not in
2676 the debugger.
2677
2678 @kindex delete checkpoint @var{checkpoint-id}
2679 @item delete checkpoint @var{checkpoint-id}
2680 Delete the previously-saved checkpoint identified by @var{checkpoint-id}.
2681
2682 @end table
2683
2684 Returning to a previously saved checkpoint will restore the user state
2685 of the program being debugged, plus a significant subset of the system
2686 (OS) state, including file pointers. It won't ``un-write'' data from
2687 a file, but it will rewind the file pointer to the previous location,
2688 so that the previously written data can be overwritten. For files
2689 opened in read mode, the pointer will also be restored so that the
2690 previously read data can be read again.
2691
2692 Of course, characters that have been sent to a printer (or other
2693 external device) cannot be ``snatched back'', and characters received
2694 from eg.@: a serial device can be removed from internal program buffers,
2695 but they cannot be ``pushed back'' into the serial pipeline, ready to
2696 be received again. Similarly, the actual contents of files that have
2697 been changed cannot be restored (at this time).
2698
2699 However, within those constraints, you actually can ``rewind'' your
2700 program to a previously saved point in time, and begin debugging it
2701 again --- and you can change the course of events so as to debug a
2702 different execution path this time.
2703
2704 @cindex checkpoints and process id
2705 Finally, there is one bit of internal program state that will be
2706 different when you return to a checkpoint --- the program's process
2707 id. Each checkpoint will have a unique process id (or @var{pid}),
2708 and each will be different from the program's original @var{pid}.
2709 If your program has saved a local copy of its process id, this could
2710 potentially pose a problem.
2711
2712 @subsection A non-obvious benefit of using checkpoints
2713
2714 On some systems such as @sc{gnu}/Linux, address space randomization
2715 is performed on new processes for security reasons. This makes it
2716 difficult or impossible to set a breakpoint, or watchpoint, on an
2717 absolute address if you have to restart the program, since the
2718 absolute location of a symbol will change from one execution to the
2719 next.
2720
2721 A checkpoint, however, is an @emph{identical} copy of a process.
2722 Therefore if you create a checkpoint at (eg.@:) the start of main,
2723 and simply return to that checkpoint instead of restarting the
2724 process, you can avoid the effects of address randomization and
2725 your symbols will all stay in the same place.
2726
2727 @node Stopping
2728 @chapter Stopping and Continuing
2729
2730 The principal purposes of using a debugger are so that you can stop your
2731 program before it terminates; or so that, if your program runs into
2732 trouble, you can investigate and find out why.
2733
2734 Inside @value{GDBN}, your program may stop for any of several reasons,
2735 such as a signal, a breakpoint, or reaching a new line after a
2736 @value{GDBN} command such as @code{step}. You may then examine and
2737 change variables, set new breakpoints or remove old ones, and then
2738 continue execution. Usually, the messages shown by @value{GDBN} provide
2739 ample explanation of the status of your program---but you can also
2740 explicitly request this information at any time.
2741
2742 @table @code
2743 @kindex info program
2744 @item info program
2745 Display information about the status of your program: whether it is
2746 running or not, what process it is, and why it stopped.
2747 @end table
2748
2749 @menu
2750 * Breakpoints:: Breakpoints, watchpoints, and catchpoints
2751 * Continuing and Stepping:: Resuming execution
2752 * Signals:: Signals
2753 * Thread Stops:: Stopping and starting multi-thread programs
2754 @end menu
2755
2756 @node Breakpoints
2757 @section Breakpoints, watchpoints, and catchpoints
2758
2759 @cindex breakpoints
2760 A @dfn{breakpoint} makes your program stop whenever a certain point in
2761 the program is reached. For each breakpoint, you can add conditions to
2762 control in finer detail whether your program stops. You can set
2763 breakpoints with the @code{break} command and its variants (@pxref{Set
2764 Breaks, ,Setting breakpoints}), to specify the place where your program
2765 should stop by line number, function name or exact address in the
2766 program.
2767
2768 On some systems, you can set breakpoints in shared libraries before
2769 the executable is run. There is a minor limitation on HP-UX systems:
2770 you must wait until the executable is run in order to set breakpoints
2771 in shared library routines that are not called directly by the program
2772 (for example, routines that are arguments in a @code{pthread_create}
2773 call).
2774
2775 @cindex watchpoints
2776 @cindex memory tracing
2777 @cindex breakpoint on memory address
2778 @cindex breakpoint on variable modification
2779 A @dfn{watchpoint} is a special breakpoint that stops your program
2780 when the value of an expression changes. You must use a different
2781 command to set watchpoints (@pxref{Set Watchpoints, ,Setting
2782 watchpoints}), but aside from that, you can manage a watchpoint like
2783 any other breakpoint: you enable, disable, and delete both breakpoints
2784 and watchpoints using the same commands.
2785
2786 You can arrange to have values from your program displayed automatically
2787 whenever @value{GDBN} stops at a breakpoint. @xref{Auto Display,,
2788 Automatic display}.
2789
2790 @cindex catchpoints
2791 @cindex breakpoint on events
2792 A @dfn{catchpoint} is another special breakpoint that stops your program
2793 when a certain kind of event occurs, such as the throwing of a C@t{++}
2794 exception or the loading of a library. As with watchpoints, you use a
2795 different command to set a catchpoint (@pxref{Set Catchpoints, ,Setting
2796 catchpoints}), but aside from that, you can manage a catchpoint like any
2797 other breakpoint. (To stop when your program receives a signal, use the
2798 @code{handle} command; see @ref{Signals, ,Signals}.)
2799
2800 @cindex breakpoint numbers
2801 @cindex numbers for breakpoints
2802 @value{GDBN} assigns a number to each breakpoint, watchpoint, or
2803 catchpoint when you create it; these numbers are successive integers
2804 starting with one. In many of the commands for controlling various
2805 features of breakpoints you use the breakpoint number to say which
2806 breakpoint you want to change. Each breakpoint may be @dfn{enabled} or
2807 @dfn{disabled}; if disabled, it has no effect on your program until you
2808 enable it again.
2809
2810 @cindex breakpoint ranges
2811 @cindex ranges of breakpoints
2812 Some @value{GDBN} commands accept a range of breakpoints on which to
2813 operate. A breakpoint range is either a single breakpoint number, like
2814 @samp{5}, or two such numbers, in increasing order, separated by a
2815 hyphen, like @samp{5-7}. When a breakpoint range is given to a command,
2816 all breakpoint in that range are operated on.
2817
2818 @menu
2819 * Set Breaks:: Setting breakpoints
2820 * Set Watchpoints:: Setting watchpoints
2821 * Set Catchpoints:: Setting catchpoints
2822 * Delete Breaks:: Deleting breakpoints
2823 * Disabling:: Disabling breakpoints
2824 * Conditions:: Break conditions
2825 * Break Commands:: Breakpoint command lists
2826 * Breakpoint Menus:: Breakpoint menus
2827 * Error in Breakpoints:: ``Cannot insert breakpoints''
2828 * Breakpoint related warnings:: ``Breakpoint address adjusted...''
2829 @end menu
2830
2831 @node Set Breaks
2832 @subsection Setting breakpoints
2833
2834 @c FIXME LMB what does GDB do if no code on line of breakpt?
2835 @c consider in particular declaration with/without initialization.
2836 @c
2837 @c FIXME 2 is there stuff on this already? break at fun start, already init?
2838
2839 @kindex break
2840 @kindex b @r{(@code{break})}
2841 @vindex $bpnum@r{, convenience variable}
2842 @cindex latest breakpoint
2843 Breakpoints are set with the @code{break} command (abbreviated
2844 @code{b}). The debugger convenience variable @samp{$bpnum} records the
2845 number of the breakpoint you've set most recently; see @ref{Convenience
2846 Vars,, Convenience variables}, for a discussion of what you can do with
2847 convenience variables.
2848
2849 You have several ways to say where the breakpoint should go.
2850
2851 @table @code
2852 @item break @var{function}
2853 Set a breakpoint at entry to function @var{function}.
2854 When using source languages that permit overloading of symbols, such as
2855 C@t{++}, @var{function} may refer to more than one possible place to break.
2856 @xref{Breakpoint Menus,,Breakpoint menus}, for a discussion of that situation.
2857
2858 @item break +@var{offset}
2859 @itemx break -@var{offset}
2860 Set a breakpoint some number of lines forward or back from the position
2861 at which execution stopped in the currently selected @dfn{stack frame}.
2862 (@xref{Frames, ,Frames}, for a description of stack frames.)
2863
2864 @item break @var{linenum}
2865 Set a breakpoint at line @var{linenum} in the current source file.
2866 The current source file is the last file whose source text was printed.
2867 The breakpoint will stop your program just before it executes any of the
2868 code on that line.
2869
2870 @item break @var{filename}:@var{linenum}
2871 Set a breakpoint at line @var{linenum} in source file @var{filename}.
2872
2873 @item break @var{filename}:@var{function}
2874 Set a breakpoint at entry to function @var{function} found in file
2875 @var{filename}. Specifying a file name as well as a function name is
2876 superfluous except when multiple files contain similarly named
2877 functions.
2878
2879 @item break *@var{address}
2880 Set a breakpoint at address @var{address}. You can use this to set
2881 breakpoints in parts of your program which do not have debugging
2882 information or source files.
2883
2884 @item break
2885 When called without any arguments, @code{break} sets a breakpoint at
2886 the next instruction to be executed in the selected stack frame
2887 (@pxref{Stack, ,Examining the Stack}). In any selected frame but the
2888 innermost, this makes your program stop as soon as control
2889 returns to that frame. This is similar to the effect of a
2890 @code{finish} command in the frame inside the selected frame---except
2891 that @code{finish} does not leave an active breakpoint. If you use
2892 @code{break} without an argument in the innermost frame, @value{GDBN} stops
2893 the next time it reaches the current location; this may be useful
2894 inside loops.
2895
2896 @value{GDBN} normally ignores breakpoints when it resumes execution, until at
2897 least one instruction has been executed. If it did not do this, you
2898 would be unable to proceed past a breakpoint without first disabling the
2899 breakpoint. This rule applies whether or not the breakpoint already
2900 existed when your program stopped.
2901
2902 @item break @dots{} if @var{cond}
2903 Set a breakpoint with condition @var{cond}; evaluate the expression
2904 @var{cond} each time the breakpoint is reached, and stop only if the
2905 value is nonzero---that is, if @var{cond} evaluates as true.
2906 @samp{@dots{}} stands for one of the possible arguments described
2907 above (or no argument) specifying where to break. @xref{Conditions,
2908 ,Break conditions}, for more information on breakpoint conditions.
2909
2910 @kindex tbreak
2911 @item tbreak @var{args}
2912 Set a breakpoint enabled only for one stop. @var{args} are the
2913 same as for the @code{break} command, and the breakpoint is set in the same
2914 way, but the breakpoint is automatically deleted after the first time your
2915 program stops there. @xref{Disabling, ,Disabling breakpoints}.
2916
2917 @kindex hbreak
2918 @cindex hardware breakpoints
2919 @item hbreak @var{args}
2920 Set a hardware-assisted breakpoint. @var{args} are the same as for the
2921 @code{break} command and the breakpoint is set in the same way, but the
2922 breakpoint requires hardware support and some target hardware may not
2923 have this support. The main purpose of this is EPROM/ROM code
2924 debugging, so you can set a breakpoint at an instruction without
2925 changing the instruction. This can be used with the new trap-generation
2926 provided by SPARClite DSU and most x86-based targets. These targets
2927 will generate traps when a program accesses some data or instruction
2928 address that is assigned to the debug registers. However the hardware
2929 breakpoint registers can take a limited number of breakpoints. For
2930 example, on the DSU, only two data breakpoints can be set at a time, and
2931 @value{GDBN} will reject this command if more than two are used. Delete
2932 or disable unused hardware breakpoints before setting new ones
2933 (@pxref{Disabling, ,Disabling}). @xref{Conditions, ,Break conditions}.
2934 For remote targets, you can restrict the number of hardware
2935 breakpoints @value{GDBN} will use, see @ref{set remote
2936 hardware-breakpoint-limit}.
2937
2938
2939 @kindex thbreak
2940 @item thbreak @var{args}
2941 Set a hardware-assisted breakpoint enabled only for one stop. @var{args}
2942 are the same as for the @code{hbreak} command and the breakpoint is set in
2943 the same way. However, like the @code{tbreak} command,
2944 the breakpoint is automatically deleted after the
2945 first time your program stops there. Also, like the @code{hbreak}
2946 command, the breakpoint requires hardware support and some target hardware
2947 may not have this support. @xref{Disabling, ,Disabling breakpoints}.
2948 See also @ref{Conditions, ,Break conditions}.
2949
2950 @kindex rbreak
2951 @cindex regular expression
2952 @cindex breakpoints in functions matching a regexp
2953 @cindex set breakpoints in many functions
2954 @item rbreak @var{regex}
2955 Set breakpoints on all functions matching the regular expression
2956 @var{regex}. This command sets an unconditional breakpoint on all
2957 matches, printing a list of all breakpoints it set. Once these
2958 breakpoints are set, they are treated just like the breakpoints set with
2959 the @code{break} command. You can delete them, disable them, or make
2960 them conditional the same way as any other breakpoint.
2961
2962 The syntax of the regular expression is the standard one used with tools
2963 like @file{grep}. Note that this is different from the syntax used by
2964 shells, so for instance @code{foo*} matches all functions that include
2965 an @code{fo} followed by zero or more @code{o}s. There is an implicit
2966 @code{.*} leading and trailing the regular expression you supply, so to
2967 match only functions that begin with @code{foo}, use @code{^foo}.
2968
2969 @cindex non-member C@t{++} functions, set breakpoint in
2970 When debugging C@t{++} programs, @code{rbreak} is useful for setting
2971 breakpoints on overloaded functions that are not members of any special
2972 classes.
2973
2974 @cindex set breakpoints on all functions
2975 The @code{rbreak} command can be used to set breakpoints in
2976 @strong{all} the functions in a program, like this:
2977
2978 @smallexample
2979 (@value{GDBP}) rbreak .
2980 @end smallexample
2981
2982 @kindex info breakpoints
2983 @cindex @code{$_} and @code{info breakpoints}
2984 @item info breakpoints @r{[}@var{n}@r{]}
2985 @itemx info break @r{[}@var{n}@r{]}
2986 @itemx info watchpoints @r{[}@var{n}@r{]}
2987 Print a table of all breakpoints, watchpoints, and catchpoints set and
2988 not deleted, with the following columns for each breakpoint:
2989
2990 @table @emph
2991 @item Breakpoint Numbers
2992 @item Type
2993 Breakpoint, watchpoint, or catchpoint.
2994 @item Disposition
2995 Whether the breakpoint is marked to be disabled or deleted when hit.
2996 @item Enabled or Disabled
2997 Enabled breakpoints are marked with @samp{y}. @samp{n} marks breakpoints
2998 that are not enabled.
2999 @item Address
3000 Where the breakpoint is in your program, as a memory address. If the
3001 breakpoint is pending (see below for details) on a future load of a shared library, the address
3002 will be listed as @samp{<PENDING>}.
3003 @item What
3004 Where the breakpoint is in the source for your program, as a file and
3005 line number. For a pending breakpoint, the original string passed to
3006 the breakpoint command will be listed as it cannot be resolved until
3007 the appropriate shared library is loaded in the future.
3008 @end table
3009
3010 @noindent
3011 If a breakpoint is conditional, @code{info break} shows the condition on
3012 the line following the affected breakpoint; breakpoint commands, if any,
3013 are listed after that. A pending breakpoint is allowed to have a condition
3014 specified for it. The condition is not parsed for validity until a shared
3015 library is loaded that allows the pending breakpoint to resolve to a
3016 valid location.
3017
3018 @noindent
3019 @code{info break} with a breakpoint
3020 number @var{n} as argument lists only that breakpoint. The
3021 convenience variable @code{$_} and the default examining-address for
3022 the @code{x} command are set to the address of the last breakpoint
3023 listed (@pxref{Memory, ,Examining memory}).
3024
3025 @noindent
3026 @code{info break} displays a count of the number of times the breakpoint
3027 has been hit. This is especially useful in conjunction with the
3028 @code{ignore} command. You can ignore a large number of breakpoint
3029 hits, look at the breakpoint info to see how many times the breakpoint
3030 was hit, and then run again, ignoring one less than that number. This
3031 will get you quickly to the last hit of that breakpoint.
3032 @end table
3033
3034 @value{GDBN} allows you to set any number of breakpoints at the same place in
3035 your program. There is nothing silly or meaningless about this. When
3036 the breakpoints are conditional, this is even useful
3037 (@pxref{Conditions, ,Break conditions}).
3038
3039 @cindex pending breakpoints
3040 If a specified breakpoint location cannot be found, it may be due to the fact
3041 that the location is in a shared library that is yet to be loaded. In such
3042 a case, you may want @value{GDBN} to create a special breakpoint (known as
3043 a @dfn{pending breakpoint}) that
3044 attempts to resolve itself in the future when an appropriate shared library
3045 gets loaded.
3046
3047 Pending breakpoints are useful to set at the start of your
3048 @value{GDBN} session for locations that you know will be dynamically loaded
3049 later by the program being debugged. When shared libraries are loaded,
3050 a check is made to see if the load resolves any pending breakpoint locations.
3051 If a pending breakpoint location gets resolved,
3052 a regular breakpoint is created and the original pending breakpoint is removed.
3053
3054 @value{GDBN} provides some additional commands for controlling pending
3055 breakpoint support:
3056
3057 @kindex set breakpoint pending
3058 @kindex show breakpoint pending
3059 @table @code
3060 @item set breakpoint pending auto
3061 This is the default behavior. When @value{GDBN} cannot find the breakpoint
3062 location, it queries you whether a pending breakpoint should be created.
3063
3064 @item set breakpoint pending on
3065 This indicates that an unrecognized breakpoint location should automatically
3066 result in a pending breakpoint being created.
3067
3068 @item set breakpoint pending off
3069 This indicates that pending breakpoints are not to be created. Any
3070 unrecognized breakpoint location results in an error. This setting does
3071 not affect any pending breakpoints previously created.
3072
3073 @item show breakpoint pending
3074 Show the current behavior setting for creating pending breakpoints.
3075 @end table
3076
3077 @cindex operations allowed on pending breakpoints
3078 Normal breakpoint operations apply to pending breakpoints as well. You may
3079 specify a condition for a pending breakpoint and/or commands to run when the
3080 breakpoint is reached. You can also enable or disable
3081 the pending breakpoint. When you specify a condition for a pending breakpoint,
3082 the parsing of the condition will be deferred until the point where the
3083 pending breakpoint location is resolved. Disabling a pending breakpoint
3084 tells @value{GDBN} to not attempt to resolve the breakpoint on any subsequent
3085 shared library load. When a pending breakpoint is re-enabled,
3086 @value{GDBN} checks to see if the location is already resolved.
3087 This is done because any number of shared library loads could have
3088 occurred since the time the breakpoint was disabled and one or more
3089 of these loads could resolve the location.
3090
3091 @cindex negative breakpoint numbers
3092 @cindex internal @value{GDBN} breakpoints
3093 @value{GDBN} itself sometimes sets breakpoints in your program for
3094 special purposes, such as proper handling of @code{longjmp} (in C
3095 programs). These internal breakpoints are assigned negative numbers,
3096 starting with @code{-1}; @samp{info breakpoints} does not display them.
3097 You can see these breakpoints with the @value{GDBN} maintenance command
3098 @samp{maint info breakpoints} (@pxref{maint info breakpoints}).
3099
3100
3101 @node Set Watchpoints
3102 @subsection Setting watchpoints
3103
3104 @cindex setting watchpoints
3105 You can use a watchpoint to stop execution whenever the value of an
3106 expression changes, without having to predict a particular place where
3107 this may happen.
3108
3109 @cindex software watchpoints
3110 @cindex hardware watchpoints
3111 Depending on your system, watchpoints may be implemented in software or
3112 hardware. @value{GDBN} does software watchpointing by single-stepping your
3113 program and testing the variable's value each time, which is hundreds of
3114 times slower than normal execution. (But this may still be worth it, to
3115 catch errors where you have no clue what part of your program is the
3116 culprit.)
3117
3118 On some systems, such as HP-UX, @sc{gnu}/Linux and most other
3119 x86-based targets, @value{GDBN} includes support for hardware
3120 watchpoints, which do not slow down the running of your program.
3121
3122 @table @code
3123 @kindex watch
3124 @item watch @var{expr}
3125 Set a watchpoint for an expression. @value{GDBN} will break when @var{expr}
3126 is written into by the program and its value changes.
3127
3128 @kindex rwatch
3129 @item rwatch @var{expr}
3130 Set a watchpoint that will break when the value of @var{expr} is read
3131 by the program.
3132
3133 @kindex awatch
3134 @item awatch @var{expr}
3135 Set a watchpoint that will break when @var{expr} is either read from
3136 or written into by the program.
3137
3138 @kindex info watchpoints
3139 @item info watchpoints
3140 This command prints a list of watchpoints, breakpoints, and catchpoints;
3141 it is the same as @code{info break} (@pxref{Set Breaks}).
3142 @end table
3143
3144 @value{GDBN} sets a @dfn{hardware watchpoint} if possible. Hardware
3145 watchpoints execute very quickly, and the debugger reports a change in
3146 value at the exact instruction where the change occurs. If @value{GDBN}
3147 cannot set a hardware watchpoint, it sets a software watchpoint, which
3148 executes more slowly and reports the change in value at the next
3149 @emph{statement}, not the instruction, after the change occurs.
3150
3151 @cindex use only software watchpoints
3152 You can force @value{GDBN} to use only software watchpoints with the
3153 @kbd{set can-use-hw-watchpoints 0} command. With this variable set to
3154 zero, @value{GDBN} will never try to use hardware watchpoints, even if
3155 the underlying system supports them. (Note that hardware-assisted
3156 watchpoints that were set @emph{before} setting
3157 @code{can-use-hw-watchpoints} to zero will still use the hardware
3158 mechanism of watching expressiion values.)
3159
3160 @table @code
3161 @item set can-use-hw-watchpoints
3162 @kindex set can-use-hw-watchpoints
3163 Set whether or not to use hardware watchpoints.
3164
3165 @item show can-use-hw-watchpoints
3166 @kindex show can-use-hw-watchpoints
3167 Show the current mode of using hardware watchpoints.
3168 @end table
3169
3170 For remote targets, you can restrict the number of hardware
3171 watchpoints @value{GDBN} will use, see @ref{set remote
3172 hardware-breakpoint-limit}.
3173
3174 When you issue the @code{watch} command, @value{GDBN} reports
3175
3176 @smallexample
3177 Hardware watchpoint @var{num}: @var{expr}
3178 @end smallexample
3179
3180 @noindent
3181 if it was able to set a hardware watchpoint.
3182
3183 Currently, the @code{awatch} and @code{rwatch} commands can only set
3184 hardware watchpoints, because accesses to data that don't change the
3185 value of the watched expression cannot be detected without examining
3186 every instruction as it is being executed, and @value{GDBN} does not do
3187 that currently. If @value{GDBN} finds that it is unable to set a
3188 hardware breakpoint with the @code{awatch} or @code{rwatch} command, it
3189 will print a message like this:
3190
3191 @smallexample
3192 Expression cannot be implemented with read/access watchpoint.
3193 @end smallexample
3194
3195 Sometimes, @value{GDBN} cannot set a hardware watchpoint because the
3196 data type of the watched expression is wider than what a hardware
3197 watchpoint on the target machine can handle. For example, some systems
3198 can only watch regions that are up to 4 bytes wide; on such systems you
3199 cannot set hardware watchpoints for an expression that yields a
3200 double-precision floating-point number (which is typically 8 bytes
3201 wide). As a work-around, it might be possible to break the large region
3202 into a series of smaller ones and watch them with separate watchpoints.
3203
3204 If you set too many hardware watchpoints, @value{GDBN} might be unable
3205 to insert all of them when you resume the execution of your program.
3206 Since the precise number of active watchpoints is unknown until such
3207 time as the program is about to be resumed, @value{GDBN} might not be
3208 able to warn you about this when you set the watchpoints, and the
3209 warning will be printed only when the program is resumed:
3210
3211 @smallexample
3212 Hardware watchpoint @var{num}: Could not insert watchpoint
3213 @end smallexample
3214
3215 @noindent
3216 If this happens, delete or disable some of the watchpoints.
3217
3218 The SPARClite DSU will generate traps when a program accesses some data
3219 or instruction address that is assigned to the debug registers. For the
3220 data addresses, DSU facilitates the @code{watch} command. However the
3221 hardware breakpoint registers can only take two data watchpoints, and
3222 both watchpoints must be the same kind. For example, you can set two
3223 watchpoints with @code{watch} commands, two with @code{rwatch} commands,
3224 @strong{or} two with @code{awatch} commands, but you cannot set one
3225 watchpoint with one command and the other with a different command.
3226 @value{GDBN} will reject the command if you try to mix watchpoints.
3227 Delete or disable unused watchpoint commands before setting new ones.
3228
3229 If you call a function interactively using @code{print} or @code{call},
3230 any watchpoints you have set will be inactive until @value{GDBN} reaches another
3231 kind of breakpoint or the call completes.
3232
3233 @value{GDBN} automatically deletes watchpoints that watch local
3234 (automatic) variables, or expressions that involve such variables, when
3235 they go out of scope, that is, when the execution leaves the block in
3236 which these variables were defined. In particular, when the program
3237 being debugged terminates, @emph{all} local variables go out of scope,
3238 and so only watchpoints that watch global variables remain set. If you
3239 rerun the program, you will need to set all such watchpoints again. One
3240 way of doing that would be to set a code breakpoint at the entry to the
3241 @code{main} function and when it breaks, set all the watchpoints.
3242
3243 @quotation
3244 @cindex watchpoints and threads
3245 @cindex threads and watchpoints
3246 @emph{Warning:} In multi-thread programs, watchpoints have only limited
3247 usefulness. With the current watchpoint implementation, @value{GDBN}
3248 can only watch the value of an expression @emph{in a single thread}. If
3249 you are confident that the expression can only change due to the current
3250 thread's activity (and if you are also confident that no other thread
3251 can become current), then you can use watchpoints as usual. However,
3252 @value{GDBN} may not notice when a non-current thread's activity changes
3253 the expression.
3254
3255 @c FIXME: this is almost identical to the previous paragraph.
3256 @emph{HP-UX Warning:} In multi-thread programs, software watchpoints
3257 have only limited usefulness. If @value{GDBN} creates a software
3258 watchpoint, it can only watch the value of an expression @emph{in a
3259 single thread}. If you are confident that the expression can only
3260 change due to the current thread's activity (and if you are also
3261 confident that no other thread can become current), then you can use
3262 software watchpoints as usual. However, @value{GDBN} may not notice
3263 when a non-current thread's activity changes the expression. (Hardware
3264 watchpoints, in contrast, watch an expression in all threads.)
3265 @end quotation
3266
3267 @xref{set remote hardware-watchpoint-limit}.
3268
3269 @node Set Catchpoints
3270 @subsection Setting catchpoints
3271 @cindex catchpoints, setting
3272 @cindex exception handlers
3273 @cindex event handling
3274
3275 You can use @dfn{catchpoints} to cause the debugger to stop for certain
3276 kinds of program events, such as C@t{++} exceptions or the loading of a
3277 shared library. Use the @code{catch} command to set a catchpoint.
3278
3279 @table @code
3280 @kindex catch
3281 @item catch @var{event}
3282 Stop when @var{event} occurs. @var{event} can be any of the following:
3283 @table @code
3284 @item throw
3285 @cindex stop on C@t{++} exceptions
3286 The throwing of a C@t{++} exception.
3287
3288 @item catch
3289 The catching of a C@t{++} exception.
3290
3291 @item exec
3292 @cindex break on fork/exec
3293 A call to @code{exec}. This is currently only available for HP-UX.
3294
3295 @item fork
3296 A call to @code{fork}. This is currently only available for HP-UX.
3297
3298 @item vfork
3299 A call to @code{vfork}. This is currently only available for HP-UX.
3300
3301 @item load
3302 @itemx load @var{libname}
3303 @cindex break on load/unload of shared library
3304 The dynamic loading of any shared library, or the loading of the library
3305 @var{libname}. This is currently only available for HP-UX.
3306
3307 @item unload
3308 @itemx unload @var{libname}
3309 The unloading of any dynamically loaded shared library, or the unloading
3310 of the library @var{libname}. This is currently only available for HP-UX.
3311 @end table
3312
3313 @item tcatch @var{event}
3314 Set a catchpoint that is enabled only for one stop. The catchpoint is
3315 automatically deleted after the first time the event is caught.
3316
3317 @end table
3318
3319 Use the @code{info break} command to list the current catchpoints.
3320
3321 There are currently some limitations to C@t{++} exception handling
3322 (@code{catch throw} and @code{catch catch}) in @value{GDBN}:
3323
3324 @itemize @bullet
3325 @item
3326 If you call a function interactively, @value{GDBN} normally returns
3327 control to you when the function has finished executing. If the call
3328 raises an exception, however, the call may bypass the mechanism that
3329 returns control to you and cause your program either to abort or to
3330 simply continue running until it hits a breakpoint, catches a signal
3331 that @value{GDBN} is listening for, or exits. This is the case even if
3332 you set a catchpoint for the exception; catchpoints on exceptions are
3333 disabled within interactive calls.
3334
3335 @item
3336 You cannot raise an exception interactively.
3337
3338 @item
3339 You cannot install an exception handler interactively.
3340 @end itemize
3341
3342 @cindex raise exceptions
3343 Sometimes @code{catch} is not the best way to debug exception handling:
3344 if you need to know exactly where an exception is raised, it is better to
3345 stop @emph{before} the exception handler is called, since that way you
3346 can see the stack before any unwinding takes place. If you set a
3347 breakpoint in an exception handler instead, it may not be easy to find
3348 out where the exception was raised.
3349
3350 To stop just before an exception handler is called, you need some
3351 knowledge of the implementation. In the case of @sc{gnu} C@t{++}, exceptions are
3352 raised by calling a library function named @code{__raise_exception}
3353 which has the following ANSI C interface:
3354
3355 @smallexample
3356 /* @var{addr} is where the exception identifier is stored.
3357 @var{id} is the exception identifier. */
3358 void __raise_exception (void **addr, void *id);
3359 @end smallexample
3360
3361 @noindent
3362 To make the debugger catch all exceptions before any stack
3363 unwinding takes place, set a breakpoint on @code{__raise_exception}
3364 (@pxref{Breakpoints, ,Breakpoints; watchpoints; and exceptions}).
3365
3366 With a conditional breakpoint (@pxref{Conditions, ,Break conditions})
3367 that depends on the value of @var{id}, you can stop your program when
3368 a specific exception is raised. You can use multiple conditional
3369 breakpoints to stop your program when any of a number of exceptions are
3370 raised.
3371
3372
3373 @node Delete Breaks
3374 @subsection Deleting breakpoints
3375
3376 @cindex clearing breakpoints, watchpoints, catchpoints
3377 @cindex deleting breakpoints, watchpoints, catchpoints
3378 It is often necessary to eliminate a breakpoint, watchpoint, or
3379 catchpoint once it has done its job and you no longer want your program
3380 to stop there. This is called @dfn{deleting} the breakpoint. A
3381 breakpoint that has been deleted no longer exists; it is forgotten.
3382
3383 With the @code{clear} command you can delete breakpoints according to
3384 where they are in your program. With the @code{delete} command you can
3385 delete individual breakpoints, watchpoints, or catchpoints by specifying
3386 their breakpoint numbers.
3387
3388 It is not necessary to delete a breakpoint to proceed past it. @value{GDBN}
3389 automatically ignores breakpoints on the first instruction to be executed
3390 when you continue execution without changing the execution address.
3391
3392 @table @code
3393 @kindex clear
3394 @item clear
3395 Delete any breakpoints at the next instruction to be executed in the
3396 selected stack frame (@pxref{Selection, ,Selecting a frame}). When
3397 the innermost frame is selected, this is a good way to delete a
3398 breakpoint where your program just stopped.
3399
3400 @item clear @var{function}
3401 @itemx clear @var{filename}:@var{function}
3402 Delete any breakpoints set at entry to the named @var{function}.
3403
3404 @item clear @var{linenum}
3405 @itemx clear @var{filename}:@var{linenum}
3406 Delete any breakpoints set at or within the code of the specified
3407 @var{linenum} of the specified @var{filename}.
3408
3409 @cindex delete breakpoints
3410 @kindex delete
3411 @kindex d @r{(@code{delete})}
3412 @item delete @r{[}breakpoints@r{]} @r{[}@var{range}@dots{}@r{]}
3413 Delete the breakpoints, watchpoints, or catchpoints of the breakpoint
3414 ranges specified as arguments. If no argument is specified, delete all
3415 breakpoints (@value{GDBN} asks confirmation, unless you have @code{set
3416 confirm off}). You can abbreviate this command as @code{d}.
3417 @end table
3418
3419 @node Disabling
3420 @subsection Disabling breakpoints
3421
3422 @cindex enable/disable a breakpoint
3423 Rather than deleting a breakpoint, watchpoint, or catchpoint, you might
3424 prefer to @dfn{disable} it. This makes the breakpoint inoperative as if
3425 it had been deleted, but remembers the information on the breakpoint so
3426 that you can @dfn{enable} it again later.
3427
3428 You disable and enable breakpoints, watchpoints, and catchpoints with
3429 the @code{enable} and @code{disable} commands, optionally specifying one
3430 or more breakpoint numbers as arguments. Use @code{info break} or
3431 @code{info watch} to print a list of breakpoints, watchpoints, and
3432 catchpoints if you do not know which numbers to use.
3433
3434 A breakpoint, watchpoint, or catchpoint can have any of four different
3435 states of enablement:
3436
3437 @itemize @bullet
3438 @item
3439 Enabled. The breakpoint stops your program. A breakpoint set
3440 with the @code{break} command starts out in this state.
3441 @item
3442 Disabled. The breakpoint has no effect on your program.
3443 @item
3444 Enabled once. The breakpoint stops your program, but then becomes
3445 disabled.
3446 @item
3447 Enabled for deletion. The breakpoint stops your program, but
3448 immediately after it does so it is deleted permanently. A breakpoint
3449 set with the @code{tbreak} command starts out in this state.
3450 @end itemize
3451
3452 You can use the following commands to enable or disable breakpoints,
3453 watchpoints, and catchpoints:
3454
3455 @table @code
3456 @kindex disable
3457 @kindex dis @r{(@code{disable})}
3458 @item disable @r{[}breakpoints@r{]} @r{[}@var{range}@dots{}@r{]}
3459 Disable the specified breakpoints---or all breakpoints, if none are
3460 listed. A disabled breakpoint has no effect but is not forgotten. All
3461 options such as ignore-counts, conditions and commands are remembered in
3462 case the breakpoint is enabled again later. You may abbreviate
3463 @code{disable} as @code{dis}.
3464
3465 @kindex enable
3466 @item enable @r{[}breakpoints@r{]} @r{[}@var{range}@dots{}@r{]}
3467 Enable the specified breakpoints (or all defined breakpoints). They
3468 become effective once again in stopping your program.
3469
3470 @item enable @r{[}breakpoints@r{]} once @var{range}@dots{}
3471 Enable the specified breakpoints temporarily. @value{GDBN} disables any
3472 of these breakpoints immediately after stopping your program.
3473
3474 @item enable @r{[}breakpoints@r{]} delete @var{range}@dots{}
3475 Enable the specified breakpoints to work once, then die. @value{GDBN}
3476 deletes any of these breakpoints as soon as your program stops there.
3477 Breakpoints set by the @code{tbreak} command start out in this state.
3478 @end table
3479
3480 @c FIXME: I think the following ``Except for [...] @code{tbreak}'' is
3481 @c confusing: tbreak is also initially enabled.
3482 Except for a breakpoint set with @code{tbreak} (@pxref{Set Breaks,
3483 ,Setting breakpoints}), breakpoints that you set are initially enabled;
3484 subsequently, they become disabled or enabled only when you use one of
3485 the commands above. (The command @code{until} can set and delete a
3486 breakpoint of its own, but it does not change the state of your other
3487 breakpoints; see @ref{Continuing and Stepping, ,Continuing and
3488 stepping}.)
3489
3490 @node Conditions
3491 @subsection Break conditions
3492 @cindex conditional breakpoints
3493 @cindex breakpoint conditions
3494
3495 @c FIXME what is scope of break condition expr? Context where wanted?
3496 @c in particular for a watchpoint?
3497 The simplest sort of breakpoint breaks every time your program reaches a
3498 specified place. You can also specify a @dfn{condition} for a
3499 breakpoint. A condition is just a Boolean expression in your
3500 programming language (@pxref{Expressions, ,Expressions}). A breakpoint with
3501 a condition evaluates the expression each time your program reaches it,
3502 and your program stops only if the condition is @emph{true}.
3503
3504 This is the converse of using assertions for program validation; in that
3505 situation, you want to stop when the assertion is violated---that is,
3506 when the condition is false. In C, if you want to test an assertion expressed
3507 by the condition @var{assert}, you should set the condition
3508 @samp{! @var{assert}} on the appropriate breakpoint.
3509
3510 Conditions are also accepted for watchpoints; you may not need them,
3511 since a watchpoint is inspecting the value of an expression anyhow---but
3512 it might be simpler, say, to just set a watchpoint on a variable name,
3513 and specify a condition that tests whether the new value is an interesting
3514 one.
3515
3516 Break conditions can have side effects, and may even call functions in
3517 your program. This can be useful, for example, to activate functions
3518 that log program progress, or to use your own print functions to
3519 format special data structures. The effects are completely predictable
3520 unless there is another enabled breakpoint at the same address. (In
3521 that case, @value{GDBN} might see the other breakpoint first and stop your
3522 program without checking the condition of this one.) Note that
3523 breakpoint commands are usually more convenient and flexible than break
3524 conditions for the
3525 purpose of performing side effects when a breakpoint is reached
3526 (@pxref{Break Commands, ,Breakpoint command lists}).
3527
3528 Break conditions can be specified when a breakpoint is set, by using
3529 @samp{if} in the arguments to the @code{break} command. @xref{Set
3530 Breaks, ,Setting breakpoints}. They can also be changed at any time
3531 with the @code{condition} command.
3532
3533 You can also use the @code{if} keyword with the @code{watch} command.
3534 The @code{catch} command does not recognize the @code{if} keyword;
3535 @code{condition} is the only way to impose a further condition on a
3536 catchpoint.
3537
3538 @table @code
3539 @kindex condition
3540 @item condition @var{bnum} @var{expression}
3541 Specify @var{expression} as the break condition for breakpoint,
3542 watchpoint, or catchpoint number @var{bnum}. After you set a condition,
3543 breakpoint @var{bnum} stops your program only if the value of
3544 @var{expression} is true (nonzero, in C). When you use
3545 @code{condition}, @value{GDBN} checks @var{expression} immediately for
3546 syntactic correctness, and to determine whether symbols in it have
3547 referents in the context of your breakpoint. If @var{expression} uses
3548 symbols not referenced in the context of the breakpoint, @value{GDBN}
3549 prints an error message:
3550
3551 @smallexample
3552 No symbol "foo" in current context.
3553 @end smallexample
3554
3555 @noindent
3556 @value{GDBN} does
3557 not actually evaluate @var{expression} at the time the @code{condition}
3558 command (or a command that sets a breakpoint with a condition, like
3559 @code{break if @dots{}}) is given, however. @xref{Expressions, ,Expressions}.
3560
3561 @item condition @var{bnum}
3562 Remove the condition from breakpoint number @var{bnum}. It becomes
3563 an ordinary unconditional breakpoint.
3564 @end table
3565
3566 @cindex ignore count (of breakpoint)
3567 A special case of a breakpoint condition is to stop only when the
3568 breakpoint has been reached a certain number of times. This is so
3569 useful that there is a special way to do it, using the @dfn{ignore
3570 count} of the breakpoint. Every breakpoint has an ignore count, which
3571 is an integer. Most of the time, the ignore count is zero, and
3572 therefore has no effect. But if your program reaches a breakpoint whose
3573 ignore count is positive, then instead of stopping, it just decrements
3574 the ignore count by one and continues. As a result, if the ignore count
3575 value is @var{n}, the breakpoint does not stop the next @var{n} times
3576 your program reaches it.
3577
3578 @table @code
3579 @kindex ignore
3580 @item ignore @var{bnum} @var{count}
3581 Set the ignore count of breakpoint number @var{bnum} to @var{count}.
3582 The next @var{count} times the breakpoint is reached, your program's
3583 execution does not stop; other than to decrement the ignore count, @value{GDBN}
3584 takes no action.
3585
3586 To make the breakpoint stop the next time it is reached, specify
3587 a count of zero.
3588
3589 When you use @code{continue} to resume execution of your program from a
3590 breakpoint, you can specify an ignore count directly as an argument to
3591 @code{continue}, rather than using @code{ignore}. @xref{Continuing and
3592 Stepping,,Continuing and stepping}.
3593
3594 If a breakpoint has a positive ignore count and a condition, the
3595 condition is not checked. Once the ignore count reaches zero,
3596 @value{GDBN} resumes checking the condition.
3597
3598 You could achieve the effect of the ignore count with a condition such
3599 as @w{@samp{$foo-- <= 0}} using a debugger convenience variable that
3600 is decremented each time. @xref{Convenience Vars, ,Convenience
3601 variables}.
3602 @end table
3603
3604 Ignore counts apply to breakpoints, watchpoints, and catchpoints.
3605
3606
3607 @node Break Commands
3608 @subsection Breakpoint command lists
3609
3610 @cindex breakpoint commands
3611 You can give any breakpoint (or watchpoint or catchpoint) a series of
3612 commands to execute when your program stops due to that breakpoint. For
3613 example, you might want to print the values of certain expressions, or
3614 enable other breakpoints.
3615
3616 @table @code
3617 @kindex commands
3618 @kindex end@r{ (breakpoint commands)}
3619 @item commands @r{[}@var{bnum}@r{]}
3620 @itemx @dots{} @var{command-list} @dots{}
3621 @itemx end
3622 Specify a list of commands for breakpoint number @var{bnum}. The commands
3623 themselves appear on the following lines. Type a line containing just
3624 @code{end} to terminate the commands.
3625
3626 To remove all commands from a breakpoint, type @code{commands} and
3627 follow it immediately with @code{end}; that is, give no commands.
3628
3629 With no @var{bnum} argument, @code{commands} refers to the last
3630 breakpoint, watchpoint, or catchpoint set (not to the breakpoint most
3631 recently encountered).
3632 @end table
3633
3634 Pressing @key{RET} as a means of repeating the last @value{GDBN} command is
3635 disabled within a @var{command-list}.
3636
3637 You can use breakpoint commands to start your program up again. Simply
3638 use the @code{continue} command, or @code{step}, or any other command
3639 that resumes execution.
3640
3641 Any other commands in the command list, after a command that resumes
3642 execution, are ignored. This is because any time you resume execution
3643 (even with a simple @code{next} or @code{step}), you may encounter
3644 another breakpoint---which could have its own command list, leading to
3645 ambiguities about which list to execute.
3646
3647 @kindex silent
3648 If the first command you specify in a command list is @code{silent}, the
3649 usual message about stopping at a breakpoint is not printed. This may
3650 be desirable for breakpoints that are to print a specific message and
3651 then continue. If none of the remaining commands print anything, you
3652 see no sign that the breakpoint was reached. @code{silent} is
3653 meaningful only at the beginning of a breakpoint command list.
3654
3655 The commands @code{echo}, @code{output}, and @code{printf} allow you to
3656 print precisely controlled output, and are often useful in silent
3657 breakpoints. @xref{Output, ,Commands for controlled output}.
3658
3659 For example, here is how you could use breakpoint commands to print the
3660 value of @code{x} at entry to @code{foo} whenever @code{x} is positive.
3661
3662 @smallexample
3663 break foo if x>0
3664 commands
3665 silent
3666 printf "x is %d\n",x
3667 cont
3668 end
3669 @end smallexample
3670
3671 One application for breakpoint commands is to compensate for one bug so
3672 you can test for another. Put a breakpoint just after the erroneous line
3673 of code, give it a condition to detect the case in which something
3674 erroneous has been done, and give it commands to assign correct values
3675 to any variables that need them. End with the @code{continue} command
3676 so that your program does not stop, and start with the @code{silent}
3677 command so that no output is produced. Here is an example:
3678
3679 @smallexample
3680 break 403
3681 commands
3682 silent
3683 set x = y + 4
3684 cont
3685 end
3686 @end smallexample
3687
3688 @node Breakpoint Menus
3689 @subsection Breakpoint menus
3690 @cindex overloading
3691 @cindex symbol overloading
3692
3693 Some programming languages (notably C@t{++} and Objective-C) permit a
3694 single function name
3695 to be defined several times, for application in different contexts.
3696 This is called @dfn{overloading}. When a function name is overloaded,
3697 @samp{break @var{function}} is not enough to tell @value{GDBN} where you want
3698 a breakpoint. If you realize this is a problem, you can use
3699 something like @samp{break @var{function}(@var{types})} to specify which
3700 particular version of the function you want. Otherwise, @value{GDBN} offers
3701 you a menu of numbered choices for different possible breakpoints, and
3702 waits for your selection with the prompt @samp{>}. The first two
3703 options are always @samp{[0] cancel} and @samp{[1] all}. Typing @kbd{1}
3704 sets a breakpoint at each definition of @var{function}, and typing
3705 @kbd{0} aborts the @code{break} command without setting any new
3706 breakpoints.
3707
3708 For example, the following session excerpt shows an attempt to set a
3709 breakpoint at the overloaded symbol @code{String::after}.
3710 We choose three particular definitions of that function name:
3711
3712 @c FIXME! This is likely to change to show arg type lists, at least
3713 @smallexample
3714 @group
3715 (@value{GDBP}) b String::after
3716 [0] cancel
3717 [1] all
3718 [2] file:String.cc; line number:867
3719 [3] file:String.cc; line number:860
3720 [4] file:String.cc; line number:875
3721 [5] file:String.cc; line number:853
3722 [6] file:String.cc; line number:846
3723 [7] file:String.cc; line number:735
3724 > 2 4 6
3725 Breakpoint 1 at 0xb26c: file String.cc, line 867.
3726 Breakpoint 2 at 0xb344: file String.cc, line 875.
3727 Breakpoint 3 at 0xafcc: file String.cc, line 846.
3728 Multiple breakpoints were set.
3729 Use the "delete" command to delete unwanted
3730 breakpoints.
3731 (@value{GDBP})
3732 @end group
3733 @end smallexample
3734
3735 @c @ifclear BARETARGET
3736 @node Error in Breakpoints
3737 @subsection ``Cannot insert breakpoints''
3738 @c
3739 @c FIXME!! 14/6/95 Is there a real example of this? Let's use it.
3740 @c
3741 Under some operating systems, breakpoints cannot be used in a program if
3742 any other process is running that program. In this situation,
3743 attempting to run or continue a program with a breakpoint causes
3744 @value{GDBN} to print an error message:
3745
3746 @smallexample
3747 Cannot insert breakpoints.
3748 The same program may be running in another process.
3749 @end smallexample
3750
3751 When this happens, you have three ways to proceed:
3752
3753 @enumerate
3754 @item
3755 Remove or disable the breakpoints, then continue.
3756
3757 @item
3758 Suspend @value{GDBN}, and copy the file containing your program to a new
3759 name. Resume @value{GDBN} and use the @code{exec-file} command to specify
3760 that @value{GDBN} should run your program under that name.
3761 Then start your program again.
3762
3763 @item
3764 Relink your program so that the text segment is nonsharable, using the
3765 linker option @samp{-N}. The operating system limitation may not apply
3766 to nonsharable executables.
3767 @end enumerate
3768 @c @end ifclear
3769
3770 A similar message can be printed if you request too many active
3771 hardware-assisted breakpoints and watchpoints:
3772
3773 @c FIXME: the precise wording of this message may change; the relevant
3774 @c source change is not committed yet (Sep 3, 1999).
3775 @smallexample
3776 Stopped; cannot insert breakpoints.
3777 You may have requested too many hardware breakpoints and watchpoints.
3778 @end smallexample
3779
3780 @noindent
3781 This message is printed when you attempt to resume the program, since
3782 only then @value{GDBN} knows exactly how many hardware breakpoints and
3783 watchpoints it needs to insert.
3784
3785 When this message is printed, you need to disable or remove some of the
3786 hardware-assisted breakpoints and watchpoints, and then continue.
3787
3788 @node Breakpoint related warnings
3789 @subsection ``Breakpoint address adjusted...''
3790 @cindex breakpoint address adjusted
3791
3792 Some processor architectures place constraints on the addresses at
3793 which breakpoints may be placed. For architectures thus constrained,
3794 @value{GDBN} will attempt to adjust the breakpoint's address to comply
3795 with the constraints dictated by the architecture.
3796
3797 One example of such an architecture is the Fujitsu FR-V. The FR-V is
3798 a VLIW architecture in which a number of RISC-like instructions may be
3799 bundled together for parallel execution. The FR-V architecture
3800 constrains the location of a breakpoint instruction within such a
3801 bundle to the instruction with the lowest address. @value{GDBN}
3802 honors this constraint by adjusting a breakpoint's address to the
3803 first in the bundle.
3804
3805 It is not uncommon for optimized code to have bundles which contain
3806 instructions from different source statements, thus it may happen that
3807 a breakpoint's address will be adjusted from one source statement to
3808 another. Since this adjustment may significantly alter @value{GDBN}'s
3809 breakpoint related behavior from what the user expects, a warning is
3810 printed when the breakpoint is first set and also when the breakpoint
3811 is hit.
3812
3813 A warning like the one below is printed when setting a breakpoint
3814 that's been subject to address adjustment:
3815
3816 @smallexample
3817 warning: Breakpoint address adjusted from 0x00010414 to 0x00010410.
3818 @end smallexample
3819
3820 Such warnings are printed both for user settable and @value{GDBN}'s
3821 internal breakpoints. If you see one of these warnings, you should
3822 verify that a breakpoint set at the adjusted address will have the
3823 desired affect. If not, the breakpoint in question may be removed and
3824 other breakpoints may be set which will have the desired behavior.
3825 E.g., it may be sufficient to place the breakpoint at a later
3826 instruction. A conditional breakpoint may also be useful in some
3827 cases to prevent the breakpoint from triggering too often.
3828
3829 @value{GDBN} will also issue a warning when stopping at one of these
3830 adjusted breakpoints:
3831
3832 @smallexample
3833 warning: Breakpoint 1 address previously adjusted from 0x00010414
3834 to 0x00010410.
3835 @end smallexample
3836
3837 When this warning is encountered, it may be too late to take remedial
3838 action except in cases where the breakpoint is hit earlier or more
3839 frequently than expected.
3840
3841 @node Continuing and Stepping
3842 @section Continuing and stepping
3843
3844 @cindex stepping
3845 @cindex continuing
3846 @cindex resuming execution
3847 @dfn{Continuing} means resuming program execution until your program
3848 completes normally. In contrast, @dfn{stepping} means executing just
3849 one more ``step'' of your program, where ``step'' may mean either one
3850 line of source code, or one machine instruction (depending on what
3851 particular command you use). Either when continuing or when stepping,
3852 your program may stop even sooner, due to a breakpoint or a signal. (If
3853 it stops due to a signal, you may want to use @code{handle}, or use
3854 @samp{signal 0} to resume execution. @xref{Signals, ,Signals}.)
3855
3856 @table @code
3857 @kindex continue
3858 @kindex c @r{(@code{continue})}
3859 @kindex fg @r{(resume foreground execution)}
3860 @item continue @r{[}@var{ignore-count}@r{]}
3861 @itemx c @r{[}@var{ignore-count}@r{]}
3862 @itemx fg @r{[}@var{ignore-count}@r{]}
3863 Resume program execution, at the address where your program last stopped;
3864 any breakpoints set at that address are bypassed. The optional argument
3865 @var{ignore-count} allows you to specify a further number of times to
3866 ignore a breakpoint at this location; its effect is like that of
3867 @code{ignore} (@pxref{Conditions, ,Break conditions}).
3868
3869 The argument @var{ignore-count} is meaningful only when your program
3870 stopped due to a breakpoint. At other times, the argument to
3871 @code{continue} is ignored.
3872
3873 The synonyms @code{c} and @code{fg} (for @dfn{foreground}, as the
3874 debugged program is deemed to be the foreground program) are provided
3875 purely for convenience, and have exactly the same behavior as
3876 @code{continue}.
3877 @end table
3878
3879 To resume execution at a different place, you can use @code{return}
3880 (@pxref{Returning, ,Returning from a function}) to go back to the
3881 calling function; or @code{jump} (@pxref{Jumping, ,Continuing at a
3882 different address}) to go to an arbitrary location in your program.
3883
3884 A typical technique for using stepping is to set a breakpoint
3885 (@pxref{Breakpoints, ,Breakpoints; watchpoints; and catchpoints}) at the
3886 beginning of the function or the section of your program where a problem
3887 is believed to lie, run your program until it stops at that breakpoint,
3888 and then step through the suspect area, examining the variables that are
3889 interesting, until you see the problem happen.
3890
3891 @table @code
3892 @kindex step
3893 @kindex s @r{(@code{step})}
3894 @item step
3895 Continue running your program until control reaches a different source
3896 line, then stop it and return control to @value{GDBN}. This command is
3897 abbreviated @code{s}.
3898
3899 @quotation
3900 @c "without debugging information" is imprecise; actually "without line
3901 @c numbers in the debugging information". (gcc -g1 has debugging info but
3902 @c not line numbers). But it seems complex to try to make that
3903 @c distinction here.
3904 @emph{Warning:} If you use the @code{step} command while control is
3905 within a function that was compiled without debugging information,
3906 execution proceeds until control reaches a function that does have
3907 debugging information. Likewise, it will not step into a function which
3908 is compiled without debugging information. To step through functions
3909 without debugging information, use the @code{stepi} command, described
3910 below.
3911 @end quotation
3912
3913 The @code{step} command only stops at the first instruction of a source
3914 line. This prevents the multiple stops that could otherwise occur in
3915 @code{switch} statements, @code{for} loops, etc. @code{step} continues
3916 to stop if a function that has debugging information is called within
3917 the line. In other words, @code{step} @emph{steps inside} any functions
3918 called within the line.
3919
3920 Also, the @code{step} command only enters a function if there is line
3921 number information for the function. Otherwise it acts like the
3922 @code{next} command. This avoids problems when using @code{cc -gl}
3923 on MIPS machines. Previously, @code{step} entered subroutines if there
3924 was any debugging information about the routine.
3925
3926 @item step @var{count}
3927 Continue running as in @code{step}, but do so @var{count} times. If a
3928 breakpoint is reached, or a signal not related to stepping occurs before
3929 @var{count} steps, stepping stops right away.
3930
3931 @kindex next
3932 @kindex n @r{(@code{next})}
3933 @item next @r{[}@var{count}@r{]}
3934 Continue to the next source line in the current (innermost) stack frame.
3935 This is similar to @code{step}, but function calls that appear within
3936 the line of code are executed without stopping. Execution stops when
3937 control reaches a different line of code at the original stack level
3938 that was executing when you gave the @code{next} command. This command
3939 is abbreviated @code{n}.
3940
3941 An argument @var{count} is a repeat count, as for @code{step}.
3942
3943
3944 @c FIX ME!! Do we delete this, or is there a way it fits in with
3945 @c the following paragraph? --- Vctoria
3946 @c
3947 @c @code{next} within a function that lacks debugging information acts like
3948 @c @code{step}, but any function calls appearing within the code of the
3949 @c function are executed without stopping.
3950
3951 The @code{next} command only stops at the first instruction of a
3952 source line. This prevents multiple stops that could otherwise occur in
3953 @code{switch} statements, @code{for} loops, etc.
3954
3955 @kindex set step-mode
3956 @item set step-mode
3957 @cindex functions without line info, and stepping
3958 @cindex stepping into functions with no line info
3959 @itemx set step-mode on
3960 The @code{set step-mode on} command causes the @code{step} command to
3961 stop at the first instruction of a function which contains no debug line
3962 information rather than stepping over it.
3963
3964 This is useful in cases where you may be interested in inspecting the
3965 machine instructions of a function which has no symbolic info and do not
3966 want @value{GDBN} to automatically skip over this function.
3967
3968 @item set step-mode off
3969 Causes the @code{step} command to step over any functions which contains no
3970 debug information. This is the default.
3971
3972 @item show step-mode
3973 Show whether @value{GDBN} will stop in or step over functions without
3974 source line debug information.
3975
3976 @kindex finish
3977 @item finish
3978 Continue running until just after function in the selected stack frame
3979 returns. Print the returned value (if any).
3980
3981 Contrast this with the @code{return} command (@pxref{Returning,
3982 ,Returning from a function}).
3983
3984 @kindex until
3985 @kindex u @r{(@code{until})}
3986 @cindex run until specified location
3987 @item until
3988 @itemx u
3989 Continue running until a source line past the current line, in the
3990 current stack frame, is reached. This command is used to avoid single
3991 stepping through a loop more than once. It is like the @code{next}
3992 command, except that when @code{until} encounters a jump, it
3993 automatically continues execution until the program counter is greater
3994 than the address of the jump.
3995
3996 This means that when you reach the end of a loop after single stepping
3997 though it, @code{until} makes your program continue execution until it
3998 exits the loop. In contrast, a @code{next} command at the end of a loop
3999 simply steps back to the beginning of the loop, which forces you to step
4000 through the next iteration.
4001
4002 @code{until} always stops your program if it attempts to exit the current
4003 stack frame.
4004
4005 @code{until} may produce somewhat counterintuitive results if the order
4006 of machine code does not match the order of the source lines. For
4007 example, in the following excerpt from a debugging session, the @code{f}
4008 (@code{frame}) command shows that execution is stopped at line
4009 @code{206}; yet when we use @code{until}, we get to line @code{195}:
4010
4011 @smallexample
4012 (@value{GDBP}) f
4013 #0 main (argc=4, argv=0xf7fffae8) at m4.c:206
4014 206 expand_input();
4015 (@value{GDBP}) until
4016 195 for ( ; argc > 0; NEXTARG) @{
4017 @end smallexample
4018
4019 This happened because, for execution efficiency, the compiler had
4020 generated code for the loop closure test at the end, rather than the
4021 start, of the loop---even though the test in a C @code{for}-loop is
4022 written before the body of the loop. The @code{until} command appeared
4023 to step back to the beginning of the loop when it advanced to this
4024 expression; however, it has not really gone to an earlier
4025 statement---not in terms of the actual machine code.
4026
4027 @code{until} with no argument works by means of single
4028 instruction stepping, and hence is slower than @code{until} with an
4029 argument.
4030
4031 @item until @var{location}
4032 @itemx u @var{location}
4033 Continue running your program until either the specified location is
4034 reached, or the current stack frame returns. @var{location} is any of
4035 the forms of argument acceptable to @code{break} (@pxref{Set Breaks,
4036 ,Setting breakpoints}). This form of the command uses breakpoints, and
4037 hence is quicker than @code{until} without an argument. The specified
4038 location is actually reached only if it is in the current frame. This
4039 implies that @code{until} can be used to skip over recursive function
4040 invocations. For instance in the code below, if the current location is
4041 line @code{96}, issuing @code{until 99} will execute the program up to
4042 line @code{99} in the same invocation of factorial, i.e. after the inner
4043 invocations have returned.
4044
4045 @smallexample
4046 94 int factorial (int value)
4047 95 @{
4048 96 if (value > 1) @{
4049 97 value *= factorial (value - 1);
4050 98 @}
4051 99 return (value);
4052 100 @}
4053 @end smallexample
4054
4055
4056 @kindex advance @var{location}
4057 @itemx advance @var{location}
4058 Continue running the program up to the given @var{location}. An argument is
4059 required, which should be of the same form as arguments for the @code{break}
4060 command. Execution will also stop upon exit from the current stack
4061 frame. This command is similar to @code{until}, but @code{advance} will
4062 not skip over recursive function calls, and the target location doesn't
4063 have to be in the same frame as the current one.
4064
4065
4066 @kindex stepi
4067 @kindex si @r{(@code{stepi})}
4068 @item stepi
4069 @itemx stepi @var{arg}
4070 @itemx si
4071 Execute one machine instruction, then stop and return to the debugger.
4072
4073 It is often useful to do @samp{display/i $pc} when stepping by machine
4074 instructions. This makes @value{GDBN} automatically display the next
4075 instruction to be executed, each time your program stops. @xref{Auto
4076 Display,, Automatic display}.
4077
4078 An argument is a repeat count, as in @code{step}.
4079
4080 @need 750
4081 @kindex nexti
4082 @kindex ni @r{(@code{nexti})}
4083 @item nexti
4084 @itemx nexti @var{arg}
4085 @itemx ni
4086 Execute one machine instruction, but if it is a function call,
4087 proceed until the function returns.
4088
4089 An argument is a repeat count, as in @code{next}.
4090 @end table
4091
4092 @node Signals
4093 @section Signals
4094 @cindex signals
4095
4096 A signal is an asynchronous event that can happen in a program. The
4097 operating system defines the possible kinds of signals, and gives each
4098 kind a name and a number. For example, in Unix @code{SIGINT} is the
4099 signal a program gets when you type an interrupt character (often @kbd{Ctrl-c});
4100 @code{SIGSEGV} is the signal a program gets from referencing a place in
4101 memory far away from all the areas in use; @code{SIGALRM} occurs when
4102 the alarm clock timer goes off (which happens only if your program has
4103 requested an alarm).
4104
4105 @cindex fatal signals
4106 Some signals, including @code{SIGALRM}, are a normal part of the
4107 functioning of your program. Others, such as @code{SIGSEGV}, indicate
4108 errors; these signals are @dfn{fatal} (they kill your program immediately) if the
4109 program has not specified in advance some other way to handle the signal.
4110 @code{SIGINT} does not indicate an error in your program, but it is normally
4111 fatal so it can carry out the purpose of the interrupt: to kill the program.
4112
4113 @value{GDBN} has the ability to detect any occurrence of a signal in your
4114 program. You can tell @value{GDBN} in advance what to do for each kind of
4115 signal.
4116
4117 @cindex handling signals
4118 Normally, @value{GDBN} is set up to let the non-erroneous signals like
4119 @code{SIGALRM} be silently passed to your program
4120 (so as not to interfere with their role in the program's functioning)
4121 but to stop your program immediately whenever an error signal happens.
4122 You can change these settings with the @code{handle} command.
4123
4124 @table @code
4125 @kindex info signals
4126 @kindex info handle
4127 @item info signals
4128 @itemx info handle
4129 Print a table of all the kinds of signals and how @value{GDBN} has been told to
4130 handle each one. You can use this to see the signal numbers of all
4131 the defined types of signals.
4132
4133 @code{info handle} is an alias for @code{info signals}.
4134
4135 @kindex handle
4136 @item handle @var{signal} @var{keywords}@dots{}
4137 Change the way @value{GDBN} handles signal @var{signal}. @var{signal}
4138 can be the number of a signal or its name (with or without the
4139 @samp{SIG} at the beginning); a list of signal numbers of the form
4140 @samp{@var{low}-@var{high}}; or the word @samp{all}, meaning all the
4141 known signals. The @var{keywords} say what change to make.
4142 @end table
4143
4144 @c @group
4145 The keywords allowed by the @code{handle} command can be abbreviated.
4146 Their full names are:
4147
4148 @table @code
4149 @item nostop
4150 @value{GDBN} should not stop your program when this signal happens. It may
4151 still print a message telling you that the signal has come in.
4152
4153 @item stop
4154 @value{GDBN} should stop your program when this signal happens. This implies
4155 the @code{print} keyword as well.
4156
4157 @item print
4158 @value{GDBN} should print a message when this signal happens.
4159
4160 @item noprint
4161 @value{GDBN} should not mention the occurrence of the signal at all. This
4162 implies the @code{nostop} keyword as well.
4163
4164 @item pass
4165 @itemx noignore
4166 @value{GDBN} should allow your program to see this signal; your program
4167 can handle the signal, or else it may terminate if the signal is fatal
4168 and not handled. @code{pass} and @code{noignore} are synonyms.
4169
4170 @item nopass
4171 @itemx ignore
4172 @value{GDBN} should not allow your program to see this signal.
4173 @code{nopass} and @code{ignore} are synonyms.
4174 @end table
4175 @c @end group
4176
4177 When a signal stops your program, the signal is not visible to the
4178 program until you
4179 continue. Your program sees the signal then, if @code{pass} is in
4180 effect for the signal in question @emph{at that time}. In other words,
4181 after @value{GDBN} reports a signal, you can use the @code{handle}
4182 command with @code{pass} or @code{nopass} to control whether your
4183 program sees that signal when you continue.
4184
4185 The default is set to @code{nostop}, @code{noprint}, @code{pass} for
4186 non-erroneous signals such as @code{SIGALRM}, @code{SIGWINCH} and
4187 @code{SIGCHLD}, and to @code{stop}, @code{print}, @code{pass} for the
4188 erroneous signals.
4189
4190 You can also use the @code{signal} command to prevent your program from
4191 seeing a signal, or cause it to see a signal it normally would not see,
4192 or to give it any signal at any time. For example, if your program stopped
4193 due to some sort of memory reference error, you might store correct
4194 values into the erroneous variables and continue, hoping to see more
4195 execution; but your program would probably terminate immediately as
4196 a result of the fatal signal once it saw the signal. To prevent this,
4197 you can continue with @samp{signal 0}. @xref{Signaling, ,Giving your
4198 program a signal}.
4199
4200 @node Thread Stops
4201 @section Stopping and starting multi-thread programs
4202
4203 When your program has multiple threads (@pxref{Threads,, Debugging
4204 programs with multiple threads}), you can choose whether to set
4205 breakpoints on all threads, or on a particular thread.
4206
4207 @table @code
4208 @cindex breakpoints and threads
4209 @cindex thread breakpoints
4210 @kindex break @dots{} thread @var{threadno}
4211 @item break @var{linespec} thread @var{threadno}
4212 @itemx break @var{linespec} thread @var{threadno} if @dots{}
4213 @var{linespec} specifies source lines; there are several ways of
4214 writing them, but the effect is always to specify some source line.
4215
4216 Use the qualifier @samp{thread @var{threadno}} with a breakpoint command
4217 to specify that you only want @value{GDBN} to stop the program when a
4218 particular thread reaches this breakpoint. @var{threadno} is one of the
4219 numeric thread identifiers assigned by @value{GDBN}, shown in the first
4220 column of the @samp{info threads} display.
4221
4222 If you do not specify @samp{thread @var{threadno}} when you set a
4223 breakpoint, the breakpoint applies to @emph{all} threads of your
4224 program.
4225
4226 You can use the @code{thread} qualifier on conditional breakpoints as
4227 well; in this case, place @samp{thread @var{threadno}} before the
4228 breakpoint condition, like this:
4229
4230 @smallexample
4231 (@value{GDBP}) break frik.c:13 thread 28 if bartab > lim
4232 @end smallexample
4233
4234 @end table
4235
4236 @cindex stopped threads
4237 @cindex threads, stopped
4238 Whenever your program stops under @value{GDBN} for any reason,
4239 @emph{all} threads of execution stop, not just the current thread. This
4240 allows you to examine the overall state of the program, including
4241 switching between threads, without worrying that things may change
4242 underfoot.
4243
4244 @cindex thread breakpoints and system calls
4245 @cindex system calls and thread breakpoints
4246 @cindex premature return from system calls
4247 There is an unfortunate side effect. If one thread stops for a
4248 breakpoint, or for some other reason, and another thread is blocked in a
4249 system call, then the system call may return prematurely. This is a
4250 consequence of the interaction between multiple threads and the signals
4251 that @value{GDBN} uses to implement breakpoints and other events that
4252 stop execution.
4253
4254 To handle this problem, your program should check the return value of
4255 each system call and react appropriately. This is good programming
4256 style anyways.
4257
4258 For example, do not write code like this:
4259
4260 @smallexample
4261 sleep (10);
4262 @end smallexample
4263
4264 The call to @code{sleep} will return early if a different thread stops
4265 at a breakpoint or for some other reason.
4266
4267 Instead, write this:
4268
4269 @smallexample
4270 int unslept = 10;
4271 while (unslept > 0)
4272 unslept = sleep (unslept);
4273 @end smallexample
4274
4275 A system call is allowed to return early, so the system is still
4276 conforming to its specification. But @value{GDBN} does cause your
4277 multi-threaded program to behave differently than it would without
4278 @value{GDBN}.
4279
4280 Also, @value{GDBN} uses internal breakpoints in the thread library to
4281 monitor certain events such as thread creation and thread destruction.
4282 When such an event happens, a system call in another thread may return
4283 prematurely, even though your program does not appear to stop.
4284
4285 @cindex continuing threads
4286 @cindex threads, continuing
4287 Conversely, whenever you restart the program, @emph{all} threads start
4288 executing. @emph{This is true even when single-stepping} with commands
4289 like @code{step} or @code{next}.
4290
4291 In particular, @value{GDBN} cannot single-step all threads in lockstep.
4292 Since thread scheduling is up to your debugging target's operating
4293 system (not controlled by @value{GDBN}), other threads may
4294 execute more than one statement while the current thread completes a
4295 single step. Moreover, in general other threads stop in the middle of a
4296 statement, rather than at a clean statement boundary, when the program
4297 stops.
4298
4299 You might even find your program stopped in another thread after
4300 continuing or even single-stepping. This happens whenever some other
4301 thread runs into a breakpoint, a signal, or an exception before the
4302 first thread completes whatever you requested.
4303
4304 On some OSes, you can lock the OS scheduler and thus allow only a single
4305 thread to run.
4306
4307 @table @code
4308 @item set scheduler-locking @var{mode}
4309 @cindex scheduler locking mode
4310 @cindex lock scheduler
4311 Set the scheduler locking mode. If it is @code{off}, then there is no
4312 locking and any thread may run at any time. If @code{on}, then only the
4313 current thread may run when the inferior is resumed. The @code{step}
4314 mode optimizes for single-stepping. It stops other threads from
4315 ``seizing the prompt'' by preempting the current thread while you are
4316 stepping. Other threads will only rarely (or never) get a chance to run
4317 when you step. They are more likely to run when you @samp{next} over a
4318 function call, and they are completely free to run when you use commands
4319 like @samp{continue}, @samp{until}, or @samp{finish}. However, unless another
4320 thread hits a breakpoint during its timeslice, they will never steal the
4321 @value{GDBN} prompt away from the thread that you are debugging.
4322
4323 @item show scheduler-locking
4324 Display the current scheduler locking mode.
4325 @end table
4326
4327
4328 @node Stack
4329 @chapter Examining the Stack
4330
4331 When your program has stopped, the first thing you need to know is where it
4332 stopped and how it got there.
4333
4334 @cindex call stack
4335 Each time your program performs a function call, information about the call
4336 is generated.
4337 That information includes the location of the call in your program,
4338 the arguments of the call,
4339 and the local variables of the function being called.
4340 The information is saved in a block of data called a @dfn{stack frame}.
4341 The stack frames are allocated in a region of memory called the @dfn{call
4342 stack}.
4343
4344 When your program stops, the @value{GDBN} commands for examining the
4345 stack allow you to see all of this information.
4346
4347 @cindex selected frame
4348 One of the stack frames is @dfn{selected} by @value{GDBN} and many
4349 @value{GDBN} commands refer implicitly to the selected frame. In
4350 particular, whenever you ask @value{GDBN} for the value of a variable in
4351 your program, the value is found in the selected frame. There are
4352 special @value{GDBN} commands to select whichever frame you are
4353 interested in. @xref{Selection, ,Selecting a frame}.
4354
4355 When your program stops, @value{GDBN} automatically selects the
4356 currently executing frame and describes it briefly, similar to the
4357 @code{frame} command (@pxref{Frame Info, ,Information about a frame}).
4358
4359 @menu
4360 * Frames:: Stack frames
4361 * Backtrace:: Backtraces
4362 * Selection:: Selecting a frame
4363 * Frame Info:: Information on a frame
4364
4365 @end menu
4366
4367 @node Frames
4368 @section Stack frames
4369
4370 @cindex frame, definition
4371 @cindex stack frame
4372 The call stack is divided up into contiguous pieces called @dfn{stack
4373 frames}, or @dfn{frames} for short; each frame is the data associated
4374 with one call to one function. The frame contains the arguments given
4375 to the function, the function's local variables, and the address at
4376 which the function is executing.
4377
4378 @cindex initial frame
4379 @cindex outermost frame
4380 @cindex innermost frame
4381 When your program is started, the stack has only one frame, that of the
4382 function @code{main}. This is called the @dfn{initial} frame or the
4383 @dfn{outermost} frame. Each time a function is called, a new frame is
4384 made. Each time a function returns, the frame for that function invocation
4385 is eliminated. If a function is recursive, there can be many frames for
4386 the same function. The frame for the function in which execution is
4387 actually occurring is called the @dfn{innermost} frame. This is the most
4388 recently created of all the stack frames that still exist.
4389
4390 @cindex frame pointer
4391 Inside your program, stack frames are identified by their addresses. A
4392 stack frame consists of many bytes, each of which has its own address; each
4393 kind of computer has a convention for choosing one byte whose
4394 address serves as the address of the frame. Usually this address is kept
4395 in a register called the @dfn{frame pointer register}
4396 (@pxref{Registers, $fp}) while execution is going on in that frame.
4397
4398 @cindex frame number
4399 @value{GDBN} assigns numbers to all existing stack frames, starting with
4400 zero for the innermost frame, one for the frame that called it,
4401 and so on upward. These numbers do not really exist in your program;
4402 they are assigned by @value{GDBN} to give you a way of designating stack
4403 frames in @value{GDBN} commands.
4404
4405 @c The -fomit-frame-pointer below perennially causes hbox overflow
4406 @c underflow problems.
4407 @cindex frameless execution
4408 Some compilers provide a way to compile functions so that they operate
4409 without stack frames. (For example, the @value{GCC} option
4410 @smallexample
4411 @samp{-fomit-frame-pointer}
4412 @end smallexample
4413 generates functions without a frame.)
4414 This is occasionally done with heavily used library functions to save
4415 the frame setup time. @value{GDBN} has limited facilities for dealing
4416 with these function invocations. If the innermost function invocation
4417 has no stack frame, @value{GDBN} nevertheless regards it as though
4418 it had a separate frame, which is numbered zero as usual, allowing
4419 correct tracing of the function call chain. However, @value{GDBN} has
4420 no provision for frameless functions elsewhere in the stack.
4421
4422 @table @code
4423 @kindex frame@r{, command}
4424 @cindex current stack frame
4425 @item frame @var{args}
4426 The @code{frame} command allows you to move from one stack frame to another,
4427 and to print the stack frame you select. @var{args} may be either the
4428 address of the frame or the stack frame number. Without an argument,
4429 @code{frame} prints the current stack frame.
4430
4431 @kindex select-frame
4432 @cindex selecting frame silently
4433 @item select-frame
4434 The @code{select-frame} command allows you to move from one stack frame
4435 to another without printing the frame. This is the silent version of
4436 @code{frame}.
4437 @end table
4438
4439 @node Backtrace
4440 @section Backtraces
4441
4442 @cindex traceback
4443 @cindex call stack traces
4444 A backtrace is a summary of how your program got where it is. It shows one
4445 line per frame, for many frames, starting with the currently executing
4446 frame (frame zero), followed by its caller (frame one), and on up the
4447 stack.
4448
4449 @table @code
4450 @kindex backtrace
4451 @kindex bt @r{(@code{backtrace})}
4452 @item backtrace
4453 @itemx bt
4454 Print a backtrace of the entire stack: one line per frame for all
4455 frames in the stack.
4456
4457 You can stop the backtrace at any time by typing the system interrupt
4458 character, normally @kbd{Ctrl-c}.
4459
4460 @item backtrace @var{n}
4461 @itemx bt @var{n}
4462 Similar, but print only the innermost @var{n} frames.
4463
4464 @item backtrace -@var{n}
4465 @itemx bt -@var{n}
4466 Similar, but print only the outermost @var{n} frames.
4467
4468 @item backtrace full
4469 @itemx bt full
4470 @itemx bt full @var{n}
4471 @itemx bt full -@var{n}
4472 Print the values of the local variables also. @var{n} specifies the
4473 number of frames to print, like described above.
4474 @end table
4475
4476 @kindex where
4477 @kindex info stack
4478 The names @code{where} and @code{info stack} (abbreviated @code{info s})
4479 are additional aliases for @code{backtrace}.
4480
4481 @cindex multiple threads, backtrace
4482 In a multi-threaded program, @value{GDBN} by default shows the
4483 backtrace only for the current thread. To display the backtrace for
4484 several or all of the threads, use the command @code{thread apply}
4485 (@pxref{Threads, thread apply}). For example, if you type @kbd{thread
4486 apply all backtrace}, @value{GDBN} will display the backtrace for all
4487 the threads; this is handy when you debug a core dump of a
4488 multi-threaded program.
4489
4490 Each line in the backtrace shows the frame number and the function name.
4491 The program counter value is also shown---unless you use @code{set
4492 print address off}. The backtrace also shows the source file name and
4493 line number, as well as the arguments to the function. The program
4494 counter value is omitted if it is at the beginning of the code for that
4495 line number.
4496
4497 Here is an example of a backtrace. It was made with the command
4498 @samp{bt 3}, so it shows the innermost three frames.
4499
4500 @smallexample
4501 @group
4502 #0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8)
4503 at builtin.c:993
4504 #1 0x6e38 in expand_macro (sym=0x2b600) at macro.c:242
4505 #2 0x6840 in expand_token (obs=0x0, t=177664, td=0xf7fffb08)
4506 at macro.c:71
4507 (More stack frames follow...)
4508 @end group
4509 @end smallexample
4510
4511 @noindent
4512 The display for frame zero does not begin with a program counter
4513 value, indicating that your program has stopped at the beginning of the
4514 code for line @code{993} of @code{builtin.c}.
4515
4516 @cindex value optimized out, in backtrace
4517 @cindex function call arguments, optimized out
4518 If your program was compiled with optimizations, some compilers will
4519 optimize away arguments passed to functions if those arguments are
4520 never used after the call. Such optimizations generate code that
4521 passes arguments through registers, but doesn't store those arguments
4522 in the stack frame. @value{GDBN} has no way of displaying such
4523 arguments in stack frames other than the innermost one. Here's what
4524 such a backtrace might look like:
4525
4526 @smallexample
4527 @group
4528 #0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8)
4529 at builtin.c:993
4530 #1 0x6e38 in expand_macro (sym=<value optimized out>) at macro.c:242
4531 #2 0x6840 in expand_token (obs=0x0, t=<value optimized out>, td=0xf7fffb08)
4532 at macro.c:71
4533 (More stack frames follow...)
4534 @end group
4535 @end smallexample
4536
4537 @noindent
4538 The values of arguments that were not saved in their stack frames are
4539 shown as @samp{<value optimized out>}.
4540
4541 If you need to display the values of such optimized-out arguments,
4542 either deduce that from other variables whose values depend on the one
4543 you are interested in, or recompile without optimizations.
4544
4545 @cindex backtrace beyond @code{main} function
4546 @cindex program entry point
4547 @cindex startup code, and backtrace
4548 Most programs have a standard user entry point---a place where system
4549 libraries and startup code transition into user code. For C this is
4550 @code{main}@footnote{
4551 Note that embedded programs (the so-called ``free-standing''
4552 environment) are not required to have a @code{main} function as the
4553 entry point. They could even have multiple entry points.}.
4554 When @value{GDBN} finds the entry function in a backtrace
4555 it will terminate the backtrace, to avoid tracing into highly
4556 system-specific (and generally uninteresting) code.
4557
4558 If you need to examine the startup code, or limit the number of levels
4559 in a backtrace, you can change this behavior:
4560
4561 @table @code
4562 @item set backtrace past-main
4563 @itemx set backtrace past-main on
4564 @kindex set backtrace
4565 Backtraces will continue past the user entry point.
4566
4567 @item set backtrace past-main off
4568 Backtraces will stop when they encounter the user entry point. This is the
4569 default.
4570
4571 @item show backtrace past-main
4572 @kindex show backtrace
4573 Display the current user entry point backtrace policy.
4574
4575 @item set backtrace past-entry
4576 @itemx set backtrace past-entry on
4577 Backtraces will continue past the internal entry point of an application.
4578 This entry point is encoded by the linker when the application is built,
4579 and is likely before the user entry point @code{main} (or equivalent) is called.
4580
4581 @item set backtrace past-entry off
4582 Backtraces will stop when they encouter the internal entry point of an
4583 application. This is the default.
4584
4585 @item show backtrace past-entry
4586 Display the current internal entry point backtrace policy.
4587
4588 @item set backtrace limit @var{n}
4589 @itemx set backtrace limit 0
4590 @cindex backtrace limit
4591 Limit the backtrace to @var{n} levels. A value of zero means
4592 unlimited.
4593
4594 @item show backtrace limit
4595 Display the current limit on backtrace levels.
4596 @end table
4597
4598 @node Selection
4599 @section Selecting a frame
4600
4601 Most commands for examining the stack and other data in your program work on
4602 whichever stack frame is selected at the moment. Here are the commands for
4603 selecting a stack frame; all of them finish by printing a brief description
4604 of the stack frame just selected.
4605
4606 @table @code
4607 @kindex frame@r{, selecting}
4608 @kindex f @r{(@code{frame})}
4609 @item frame @var{n}
4610 @itemx f @var{n}
4611 Select frame number @var{n}. Recall that frame zero is the innermost
4612 (currently executing) frame, frame one is the frame that called the
4613 innermost one, and so on. The highest-numbered frame is the one for
4614 @code{main}.
4615
4616 @item frame @var{addr}
4617 @itemx f @var{addr}
4618 Select the frame at address @var{addr}. This is useful mainly if the
4619 chaining of stack frames has been damaged by a bug, making it
4620 impossible for @value{GDBN} to assign numbers properly to all frames. In
4621 addition, this can be useful when your program has multiple stacks and
4622 switches between them.
4623
4624 On the SPARC architecture, @code{frame} needs two addresses to
4625 select an arbitrary frame: a frame pointer and a stack pointer.
4626
4627 On the MIPS and Alpha architecture, it needs two addresses: a stack
4628 pointer and a program counter.
4629
4630 On the 29k architecture, it needs three addresses: a register stack
4631 pointer, a program counter, and a memory stack pointer.
4632
4633 @kindex up
4634 @item up @var{n}
4635 Move @var{n} frames up the stack. For positive numbers @var{n}, this
4636 advances toward the outermost frame, to higher frame numbers, to frames
4637 that have existed longer. @var{n} defaults to one.
4638
4639 @kindex down
4640 @kindex do @r{(@code{down})}
4641 @item down @var{n}
4642 Move @var{n} frames down the stack. For positive numbers @var{n}, this
4643 advances toward the innermost frame, to lower frame numbers, to frames
4644 that were created more recently. @var{n} defaults to one. You may
4645 abbreviate @code{down} as @code{do}.
4646 @end table
4647
4648 All of these commands end by printing two lines of output describing the
4649 frame. The first line shows the frame number, the function name, the
4650 arguments, and the source file and line number of execution in that
4651 frame. The second line shows the text of that source line.
4652
4653 @need 1000
4654 For example:
4655
4656 @smallexample
4657 @group
4658 (@value{GDBP}) up
4659 #1 0x22f0 in main (argc=1, argv=0xf7fffbf4, env=0xf7fffbfc)
4660 at env.c:10
4661 10 read_input_file (argv[i]);
4662 @end group
4663 @end smallexample
4664
4665 After such a printout, the @code{list} command with no arguments
4666 prints ten lines centered on the point of execution in the frame.
4667 You can also edit the program at the point of execution with your favorite
4668 editing program by typing @code{edit}.
4669 @xref{List, ,Printing source lines},
4670 for details.
4671
4672 @table @code
4673 @kindex down-silently
4674 @kindex up-silently
4675 @item up-silently @var{n}
4676 @itemx down-silently @var{n}
4677 These two commands are variants of @code{up} and @code{down},
4678 respectively; they differ in that they do their work silently, without
4679 causing display of the new frame. They are intended primarily for use
4680 in @value{GDBN} command scripts, where the output might be unnecessary and
4681 distracting.
4682 @end table
4683
4684 @node Frame Info
4685 @section Information about a frame
4686
4687 There are several other commands to print information about the selected
4688 stack frame.
4689
4690 @table @code
4691 @item frame
4692 @itemx f
4693 When used without any argument, this command does not change which
4694 frame is selected, but prints a brief description of the currently
4695 selected stack frame. It can be abbreviated @code{f}. With an
4696 argument, this command is used to select a stack frame.
4697 @xref{Selection, ,Selecting a frame}.
4698
4699 @kindex info frame
4700 @kindex info f @r{(@code{info frame})}
4701 @item info frame
4702 @itemx info f
4703 This command prints a verbose description of the selected stack frame,
4704 including:
4705
4706 @itemize @bullet
4707 @item
4708 the address of the frame
4709 @item
4710 the address of the next frame down (called by this frame)
4711 @item
4712 the address of the next frame up (caller of this frame)
4713 @item
4714 the language in which the source code corresponding to this frame is written
4715 @item
4716 the address of the frame's arguments
4717 @item
4718 the address of the frame's local variables
4719 @item
4720 the program counter saved in it (the address of execution in the caller frame)
4721 @item
4722 which registers were saved in the frame
4723 @end itemize
4724
4725 @noindent The verbose description is useful when
4726 something has gone wrong that has made the stack format fail to fit
4727 the usual conventions.
4728
4729 @item info frame @var{addr}
4730 @itemx info f @var{addr}
4731 Print a verbose description of the frame at address @var{addr}, without
4732 selecting that frame. The selected frame remains unchanged by this
4733 command. This requires the same kind of address (more than one for some
4734 architectures) that you specify in the @code{frame} command.
4735 @xref{Selection, ,Selecting a frame}.
4736
4737 @kindex info args
4738 @item info args
4739 Print the arguments of the selected frame, each on a separate line.
4740
4741 @item info locals
4742 @kindex info locals
4743 Print the local variables of the selected frame, each on a separate
4744 line. These are all variables (declared either static or automatic)
4745 accessible at the point of execution of the selected frame.
4746
4747 @kindex info catch
4748 @cindex catch exceptions, list active handlers
4749 @cindex exception handlers, how to list
4750 @item info catch
4751 Print a list of all the exception handlers that are active in the
4752 current stack frame at the current point of execution. To see other
4753 exception handlers, visit the associated frame (using the @code{up},
4754 @code{down}, or @code{frame} commands); then type @code{info catch}.
4755 @xref{Set Catchpoints, , Setting catchpoints}.
4756
4757 @end table
4758
4759
4760 @node Source
4761 @chapter Examining Source Files
4762
4763 @value{GDBN} can print parts of your program's source, since the debugging
4764 information recorded in the program tells @value{GDBN} what source files were
4765 used to build it. When your program stops, @value{GDBN} spontaneously prints
4766 the line where it stopped. Likewise, when you select a stack frame
4767 (@pxref{Selection, ,Selecting a frame}), @value{GDBN} prints the line where
4768 execution in that frame has stopped. You can print other portions of
4769 source files by explicit command.
4770
4771 If you use @value{GDBN} through its @sc{gnu} Emacs interface, you may
4772 prefer to use Emacs facilities to view source; see @ref{Emacs, ,Using
4773 @value{GDBN} under @sc{gnu} Emacs}.
4774
4775 @menu
4776 * List:: Printing source lines
4777 * Edit:: Editing source files
4778 * Search:: Searching source files
4779 * Source Path:: Specifying source directories
4780 * Machine Code:: Source and machine code
4781 @end menu
4782
4783 @node List
4784 @section Printing source lines
4785
4786 @kindex list
4787 @kindex l @r{(@code{list})}
4788 To print lines from a source file, use the @code{list} command
4789 (abbreviated @code{l}). By default, ten lines are printed.
4790 There are several ways to specify what part of the file you want to print.
4791
4792 Here are the forms of the @code{list} command most commonly used:
4793
4794 @table @code
4795 @item list @var{linenum}
4796 Print lines centered around line number @var{linenum} in the
4797 current source file.
4798
4799 @item list @var{function}
4800 Print lines centered around the beginning of function
4801 @var{function}.
4802
4803 @item list
4804 Print more lines. If the last lines printed were printed with a
4805 @code{list} command, this prints lines following the last lines
4806 printed; however, if the last line printed was a solitary line printed
4807 as part of displaying a stack frame (@pxref{Stack, ,Examining the
4808 Stack}), this prints lines centered around that line.
4809
4810 @item list -
4811 Print lines just before the lines last printed.
4812 @end table
4813
4814 @cindex @code{list}, how many lines to display
4815 By default, @value{GDBN} prints ten source lines with any of these forms of
4816 the @code{list} command. You can change this using @code{set listsize}:
4817
4818 @table @code
4819 @kindex set listsize
4820 @item set listsize @var{count}
4821 Make the @code{list} command display @var{count} source lines (unless
4822 the @code{list} argument explicitly specifies some other number).
4823
4824 @kindex show listsize
4825 @item show listsize
4826 Display the number of lines that @code{list} prints.
4827 @end table
4828
4829 Repeating a @code{list} command with @key{RET} discards the argument,
4830 so it is equivalent to typing just @code{list}. This is more useful
4831 than listing the same lines again. An exception is made for an
4832 argument of @samp{-}; that argument is preserved in repetition so that
4833 each repetition moves up in the source file.
4834
4835 @cindex linespec
4836 In general, the @code{list} command expects you to supply zero, one or two
4837 @dfn{linespecs}. Linespecs specify source lines; there are several ways
4838 of writing them, but the effect is always to specify some source line.
4839 Here is a complete description of the possible arguments for @code{list}:
4840
4841 @table @code
4842 @item list @var{linespec}
4843 Print lines centered around the line specified by @var{linespec}.
4844
4845 @item list @var{first},@var{last}
4846 Print lines from @var{first} to @var{last}. Both arguments are
4847 linespecs.
4848
4849 @item list ,@var{last}
4850 Print lines ending with @var{last}.
4851
4852 @item list @var{first},
4853 Print lines starting with @var{first}.
4854
4855 @item list +
4856 Print lines just after the lines last printed.
4857
4858 @item list -
4859 Print lines just before the lines last printed.
4860
4861 @item list
4862 As described in the preceding table.
4863 @end table
4864
4865 Here are the ways of specifying a single source line---all the
4866 kinds of linespec.
4867
4868 @table @code
4869 @item @var{number}
4870 Specifies line @var{number} of the current source file.
4871 When a @code{list} command has two linespecs, this refers to
4872 the same source file as the first linespec.
4873
4874 @item +@var{offset}
4875 Specifies the line @var{offset} lines after the last line printed.
4876 When used as the second linespec in a @code{list} command that has
4877 two, this specifies the line @var{offset} lines down from the
4878 first linespec.
4879
4880 @item -@var{offset}
4881 Specifies the line @var{offset} lines before the last line printed.
4882
4883 @item @var{filename}:@var{number}
4884 Specifies line @var{number} in the source file @var{filename}.
4885
4886 @item @var{function}
4887 Specifies the line that begins the body of the function @var{function}.
4888 For example: in C, this is the line with the open brace.
4889
4890 @item @var{filename}:@var{function}
4891 Specifies the line of the open-brace that begins the body of the
4892 function @var{function} in the file @var{filename}. You only need the
4893 file name with a function name to avoid ambiguity when there are
4894 identically named functions in different source files.
4895
4896 @item *@var{address}
4897 Specifies the line containing the program address @var{address}.
4898 @var{address} may be any expression.
4899 @end table
4900
4901 @node Edit
4902 @section Editing source files
4903 @cindex editing source files
4904
4905 @kindex edit
4906 @kindex e @r{(@code{edit})}
4907 To edit the lines in a source file, use the @code{edit} command.
4908 The editing program of your choice
4909 is invoked with the current line set to
4910 the active line in the program.
4911 Alternatively, there are several ways to specify what part of the file you
4912 want to print if you want to see other parts of the program.
4913
4914 Here are the forms of the @code{edit} command most commonly used:
4915
4916 @table @code
4917 @item edit
4918 Edit the current source file at the active line number in the program.
4919
4920 @item edit @var{number}
4921 Edit the current source file with @var{number} as the active line number.
4922
4923 @item edit @var{function}
4924 Edit the file containing @var{function} at the beginning of its definition.
4925
4926 @item edit @var{filename}:@var{number}
4927 Specifies line @var{number} in the source file @var{filename}.
4928
4929 @item edit @var{filename}:@var{function}
4930 Specifies the line that begins the body of the
4931 function @var{function} in the file @var{filename}. You only need the
4932 file name with a function name to avoid ambiguity when there are
4933 identically named functions in different source files.
4934
4935 @item edit *@var{address}
4936 Specifies the line containing the program address @var{address}.
4937 @var{address} may be any expression.
4938 @end table
4939
4940 @subsection Choosing your editor
4941 You can customize @value{GDBN} to use any editor you want
4942 @footnote{
4943 The only restriction is that your editor (say @code{ex}), recognizes the
4944 following command-line syntax:
4945 @smallexample
4946 ex +@var{number} file
4947 @end smallexample
4948 The optional numeric value +@var{number} specifies the number of the line in
4949 the file where to start editing.}.
4950 By default, it is @file{@value{EDITOR}}, but you can change this
4951 by setting the environment variable @code{EDITOR} before using
4952 @value{GDBN}. For example, to configure @value{GDBN} to use the
4953 @code{vi} editor, you could use these commands with the @code{sh} shell:
4954 @smallexample
4955 EDITOR=/usr/bin/vi
4956 export EDITOR
4957 gdb @dots{}
4958 @end smallexample
4959 or in the @code{csh} shell,
4960 @smallexample
4961 setenv EDITOR /usr/bin/vi
4962 gdb @dots{}
4963 @end smallexample
4964
4965 @node Search
4966 @section Searching source files
4967 @cindex searching source files
4968
4969 There are two commands for searching through the current source file for a
4970 regular expression.
4971
4972 @table @code
4973 @kindex search
4974 @kindex forward-search
4975 @item forward-search @var{regexp}
4976 @itemx search @var{regexp}
4977 The command @samp{forward-search @var{regexp}} checks each line,
4978 starting with the one following the last line listed, for a match for
4979 @var{regexp}. It lists the line that is found. You can use the
4980 synonym @samp{search @var{regexp}} or abbreviate the command name as
4981 @code{fo}.
4982
4983 @kindex reverse-search
4984 @item reverse-search @var{regexp}
4985 The command @samp{reverse-search @var{regexp}} checks each line, starting
4986 with the one before the last line listed and going backward, for a match
4987 for @var{regexp}. It lists the line that is found. You can abbreviate
4988 this command as @code{rev}.
4989 @end table
4990
4991 @node Source Path
4992 @section Specifying source directories
4993
4994 @cindex source path
4995 @cindex directories for source files
4996 Executable programs sometimes do not record the directories of the source
4997 files from which they were compiled, just the names. Even when they do,
4998 the directories could be moved between the compilation and your debugging
4999 session. @value{GDBN} has a list of directories to search for source files;
5000 this is called the @dfn{source path}. Each time @value{GDBN} wants a source file,
5001 it tries all the directories in the list, in the order they are present
5002 in the list, until it finds a file with the desired name.
5003
5004 For example, suppose an executable references the file
5005 @file{/usr/src/foo-1.0/lib/foo.c}, and our source path is
5006 @file{/mnt/cross}. The file is first looked up literally; if this
5007 fails, @file{/mnt/cross/usr/src/foo-1.0/lib/foo.c} is tried; if this
5008 fails, @file{/mnt/cross/foo.c} is opened; if this fails, an error
5009 message is printed. @value{GDBN} does not look up the parts of the
5010 source file name, such as @file{/mnt/cross/src/foo-1.0/lib/foo.c}.
5011 Likewise, the subdirectories of the source path are not searched: if
5012 the source path is @file{/mnt/cross}, and the binary refers to
5013 @file{foo.c}, @value{GDBN} would not find it under
5014 @file{/mnt/cross/usr/src/foo-1.0/lib}.
5015
5016 Plain file names, relative file names with leading directories, file
5017 names containing dots, etc.@: are all treated as described above; for
5018 instance, if the source path is @file{/mnt/cross}, and the source file
5019 is recorded as @file{../lib/foo.c}, @value{GDBN} would first try
5020 @file{../lib/foo.c}, then @file{/mnt/cross/../lib/foo.c}, and after
5021 that---@file{/mnt/cross/foo.c}.
5022
5023 Note that the executable search path is @emph{not} used to locate the
5024 source files.
5025
5026 Whenever you reset or rearrange the source path, @value{GDBN} clears out
5027 any information it has cached about where source files are found and where
5028 each line is in the file.
5029
5030 @kindex directory
5031 @kindex dir
5032 When you start @value{GDBN}, its source path includes only @samp{cdir}
5033 and @samp{cwd}, in that order.
5034 To add other directories, use the @code{directory} command.
5035
5036 The search path is used to find both program source files and @value{GDBN}
5037 script files (read using the @samp{-command} option and @samp{source} command).
5038
5039 In addition to the source path, @value{GDBN} provides a set of commands
5040 that manage a list of source path substitution rules. A @dfn{substitution
5041 rule} specifies how to rewrite source directories stored in the program's
5042 debug information in case the sources were moved to a different
5043 directory between compilation and debugging. A rule is made of
5044 two strings, the first specifying what needs to be rewritten in
5045 the path, and the second specifying how it should be rewritten.
5046 In @ref{set substitute-path}, we name these two parts @var{from} and
5047 @var{to} respectively. @value{GDBN} does a simple string replacement
5048 of @var{from} with @var{to} at the start of the directory part of the
5049 source file name, and uses that result instead of the original file
5050 name to look up the sources.
5051
5052 Using the previous example, suppose the @file{foo-1.0} tree has been
5053 moved from @file{/usr/src} to @file{/mnt/cross}, then you can tell
5054 GDB to replace @file{/usr/src} in all source path names with
5055 @file{/mnt/cross}. The first lookup will then be
5056 @file{/mnt/cross/foo-1.0/lib/foo.c} in place of the original location
5057 of @file{/usr/src/foo-1.0/lib/foo.c}. To define a source path
5058 substitution rule, use the @code{set substitute-path} command
5059 (@pxref{set substitute-path}).
5060
5061 To avoid unexpected substitution results, a rule is applied only if the
5062 @var{from} part of the directory name ends at a directory separator.
5063 For instance, a rule substituting @file{/usr/source} into
5064 @file{/mnt/cross} will be applied to @file{/usr/source/foo-1.0} but
5065 not to @file{/usr/sourceware/foo-2.0}. And because the substitution
5066 is applied only at the begining of the directory name, this rule will
5067 not be applied to @file{/root/usr/source/baz.c} either.
5068
5069 In many cases, you can achieve the same result using the @code{directory}
5070 command. However, @code{set substitute-path} can be more efficient in
5071 the case where the sources are organized in a complex tree with multiple
5072 subdirectories. With the @code{directory} command, you need to add each
5073 subdirectory of your project. If you moved the entire tree while
5074 preserving its internal organization, then @code{set substitute-path}
5075 allows you to direct the debugger to all the sources with one single
5076 command.
5077
5078 @code{set substitute-path} is also more than just a shortcut command.
5079 The source path is only used if the file at the original location no
5080 longer exists. On the other hand, @code{set substitute-path} modifies
5081 the debugger behavior to look at the rewritten location instead. So, if
5082 for any reason a source file that is not relevant to your executable is
5083 located at the original location, a substitution rule is the only
5084 method available to point GDB at the new location.
5085
5086 @table @code
5087 @item directory @var{dirname} @dots{}
5088 @item dir @var{dirname} @dots{}
5089 Add directory @var{dirname} to the front of the source path. Several
5090 directory names may be given to this command, separated by @samp{:}
5091 (@samp{;} on MS-DOS and MS-Windows, where @samp{:} usually appears as
5092 part of absolute file names) or
5093 whitespace. You may specify a directory that is already in the source
5094 path; this moves it forward, so @value{GDBN} searches it sooner.
5095
5096 @kindex cdir
5097 @kindex cwd
5098 @vindex $cdir@r{, convenience variable}
5099 @vindex $cwdr@r{, convenience variable}
5100 @cindex compilation directory
5101 @cindex current directory
5102 @cindex working directory
5103 @cindex directory, current
5104 @cindex directory, compilation
5105 You can use the string @samp{$cdir} to refer to the compilation
5106 directory (if one is recorded), and @samp{$cwd} to refer to the current
5107 working directory. @samp{$cwd} is not the same as @samp{.}---the former
5108 tracks the current working directory as it changes during your @value{GDBN}
5109 session, while the latter is immediately expanded to the current
5110 directory at the time you add an entry to the source path.
5111
5112 @item directory
5113 Reset the source path to its default value (@samp{$cdir:$cwd} on Unix systems). This requires confirmation.
5114
5115 @c RET-repeat for @code{directory} is explicitly disabled, but since
5116 @c repeating it would be a no-op we do not say that. (thanks to RMS)
5117
5118 @item show directories
5119 @kindex show directories
5120 Print the source path: show which directories it contains.
5121
5122 @anchor{set substitute-path}
5123 @item set substitute-path @var{from} @var{to}
5124 @kindex set substitute-path
5125 Define a source path substitution rule, and add it at the end of the
5126 current list of existing substitution rules. If a rule with the same
5127 @var{from} was already defined, then the old rule is also deleted.
5128
5129 For example, if the file @file{/foo/bar/baz.c} was moved to
5130 @file{/mnt/cross/baz.c}, then the command
5131
5132 @smallexample
5133 (@value{GDBP}) set substitute-path /usr/src /mnt/cross
5134 @end smallexample
5135
5136 @noindent
5137 will tell @value{GDBN} to replace @samp{/usr/src} with
5138 @samp{/mnt/cross}, which will allow @value{GDBN} to find the file
5139 @file{baz.c} even though it was moved.
5140
5141 In the case when more than one substitution rule have been defined,
5142 the rules are evaluated one by one in the order where they have been
5143 defined. The first one matching, if any, is selected to perform
5144 the substitution.
5145
5146 For instance, if we had entered the following commands:
5147
5148 @smallexample
5149 (@value{GDBP}) set substitute-path /usr/src/include /mnt/include
5150 (@value{GDBP}) set substitute-path /usr/src /mnt/src
5151 @end smallexample
5152
5153 @noindent
5154 @value{GDBN} would then rewrite @file{/usr/src/include/defs.h} into
5155 @file{/mnt/include/defs.h} by using the first rule. However, it would
5156 use the second rule to rewrite @file{/usr/src/lib/foo.c} into
5157 @file{/mnt/src/lib/foo.c}.
5158
5159
5160 @item unset substitute-path [path]
5161 @kindex unset substitute-path
5162 If a path is specified, search the current list of substitution rules
5163 for a rule that would rewrite that path. Delete that rule if found.
5164 A warning is emitted by the debugger if no rule could be found.
5165
5166 If no path is specified, then all substitution rules are deleted.
5167
5168 @item show substitute-path [path]
5169 @kindex show substitute-path
5170 If a path is specified, then print the source path substitution rule
5171 which would rewrite that path, if any.
5172
5173 If no path is specified, then print all existing source path substitution
5174 rules.
5175
5176 @end table
5177
5178 If your source path is cluttered with directories that are no longer of
5179 interest, @value{GDBN} may sometimes cause confusion by finding the wrong
5180 versions of source. You can correct the situation as follows:
5181
5182 @enumerate
5183 @item
5184 Use @code{directory} with no argument to reset the source path to its default value.
5185
5186 @item
5187 Use @code{directory} with suitable arguments to reinstall the
5188 directories you want in the source path. You can add all the
5189 directories in one command.
5190 @end enumerate
5191
5192 @node Machine Code
5193 @section Source and machine code
5194 @cindex source line and its code address
5195
5196 You can use the command @code{info line} to map source lines to program
5197 addresses (and vice versa), and the command @code{disassemble} to display
5198 a range of addresses as machine instructions. When run under @sc{gnu} Emacs
5199 mode, the @code{info line} command causes the arrow to point to the
5200 line specified. Also, @code{info line} prints addresses in symbolic form as
5201 well as hex.
5202
5203 @table @code
5204 @kindex info line
5205 @item info line @var{linespec}
5206 Print the starting and ending addresses of the compiled code for
5207 source line @var{linespec}. You can specify source lines in any of
5208 the ways understood by the @code{list} command (@pxref{List, ,Printing
5209 source lines}).
5210 @end table
5211
5212 For example, we can use @code{info line} to discover the location of
5213 the object code for the first line of function
5214 @code{m4_changequote}:
5215
5216 @c FIXME: I think this example should also show the addresses in
5217 @c symbolic form, as they usually would be displayed.
5218 @smallexample
5219 (@value{GDBP}) info line m4_changequote
5220 Line 895 of "builtin.c" starts at pc 0x634c and ends at 0x6350.
5221 @end smallexample
5222
5223 @noindent
5224 @cindex code address and its source line
5225 We can also inquire (using @code{*@var{addr}} as the form for
5226 @var{linespec}) what source line covers a particular address:
5227 @smallexample
5228 (@value{GDBP}) info line *0x63ff
5229 Line 926 of "builtin.c" starts at pc 0x63e4 and ends at 0x6404.
5230 @end smallexample
5231
5232 @cindex @code{$_} and @code{info line}
5233 @cindex @code{x} command, default address
5234 @kindex x@r{(examine), and} info line
5235 After @code{info line}, the default address for the @code{x} command
5236 is changed to the starting address of the line, so that @samp{x/i} is
5237 sufficient to begin examining the machine code (@pxref{Memory,
5238 ,Examining memory}). Also, this address is saved as the value of the
5239 convenience variable @code{$_} (@pxref{Convenience Vars, ,Convenience
5240 variables}).
5241
5242 @table @code
5243 @kindex disassemble
5244 @cindex assembly instructions
5245 @cindex instructions, assembly
5246 @cindex machine instructions
5247 @cindex listing machine instructions
5248 @item disassemble
5249 This specialized command dumps a range of memory as machine
5250 instructions. The default memory range is the function surrounding the
5251 program counter of the selected frame. A single argument to this
5252 command is a program counter value; @value{GDBN} dumps the function
5253 surrounding this value. Two arguments specify a range of addresses
5254 (first inclusive, second exclusive) to dump.
5255 @end table
5256
5257 The following example shows the disassembly of a range of addresses of
5258 HP PA-RISC 2.0 code:
5259
5260 @smallexample
5261 (@value{GDBP}) disas 0x32c4 0x32e4
5262 Dump of assembler code from 0x32c4 to 0x32e4:
5263 0x32c4 <main+204>: addil 0,dp
5264 0x32c8 <main+208>: ldw 0x22c(sr0,r1),r26
5265 0x32cc <main+212>: ldil 0x3000,r31
5266 0x32d0 <main+216>: ble 0x3f8(sr4,r31)
5267 0x32d4 <main+220>: ldo 0(r31),rp
5268 0x32d8 <main+224>: addil -0x800,dp
5269 0x32dc <main+228>: ldo 0x588(r1),r26
5270 0x32e0 <main+232>: ldil 0x3000,r31
5271 End of assembler dump.
5272 @end smallexample
5273
5274 Some architectures have more than one commonly-used set of instruction
5275 mnemonics or other syntax.
5276
5277 For programs that were dynamically linked and use shared libraries,
5278 instructions that call functions or branch to locations in the shared
5279 libraries might show a seemingly bogus location---it's actually a
5280 location of the relocation table. On some architectures, @value{GDBN}
5281 might be able to resolve these to actual function names.
5282
5283 @table @code
5284 @kindex set disassembly-flavor
5285 @cindex Intel disassembly flavor
5286 @cindex AT&T disassembly flavor
5287 @item set disassembly-flavor @var{instruction-set}
5288 Select the instruction set to use when disassembling the
5289 program via the @code{disassemble} or @code{x/i} commands.
5290
5291 Currently this command is only defined for the Intel x86 family. You
5292 can set @var{instruction-set} to either @code{intel} or @code{att}.
5293 The default is @code{att}, the AT&T flavor used by default by Unix
5294 assemblers for x86-based targets.
5295
5296 @kindex show disassembly-flavor
5297 @item show disassembly-flavor
5298 Show the current setting of the disassembly flavor.
5299 @end table
5300
5301
5302 @node Data
5303 @chapter Examining Data
5304
5305 @cindex printing data
5306 @cindex examining data
5307 @kindex print
5308 @kindex inspect
5309 @c "inspect" is not quite a synonym if you are using Epoch, which we do not
5310 @c document because it is nonstandard... Under Epoch it displays in a
5311 @c different window or something like that.
5312 The usual way to examine data in your program is with the @code{print}
5313 command (abbreviated @code{p}), or its synonym @code{inspect}. It
5314 evaluates and prints the value of an expression of the language your
5315 program is written in (@pxref{Languages, ,Using @value{GDBN} with
5316 Different Languages}).
5317
5318 @table @code
5319 @item print @var{expr}
5320 @itemx print /@var{f} @var{expr}
5321 @var{expr} is an expression (in the source language). By default the
5322 value of @var{expr} is printed in a format appropriate to its data type;
5323 you can choose a different format by specifying @samp{/@var{f}}, where
5324 @var{f} is a letter specifying the format; see @ref{Output Formats,,Output
5325 formats}.
5326
5327 @item print
5328 @itemx print /@var{f}
5329 @cindex reprint the last value
5330 If you omit @var{expr}, @value{GDBN} displays the last value again (from the
5331 @dfn{value history}; @pxref{Value History, ,Value history}). This allows you to
5332 conveniently inspect the same value in an alternative format.
5333 @end table
5334
5335 A more low-level way of examining data is with the @code{x} command.
5336 It examines data in memory at a specified address and prints it in a
5337 specified format. @xref{Memory, ,Examining memory}.
5338
5339 If you are interested in information about types, or about how the
5340 fields of a struct or a class are declared, use the @code{ptype @var{exp}}
5341 command rather than @code{print}. @xref{Symbols, ,Examining the Symbol
5342 Table}.
5343
5344 @menu
5345 * Expressions:: Expressions
5346 * Variables:: Program variables
5347 * Arrays:: Artificial arrays
5348 * Output Formats:: Output formats
5349 * Memory:: Examining memory
5350 * Auto Display:: Automatic display
5351 * Print Settings:: Print settings
5352 * Value History:: Value history
5353 * Convenience Vars:: Convenience variables
5354 * Registers:: Registers
5355 * Floating Point Hardware:: Floating point hardware
5356 * Vector Unit:: Vector Unit
5357 * OS Information:: Auxiliary data provided by operating system
5358 * Memory Region Attributes:: Memory region attributes
5359 * Dump/Restore Files:: Copy between memory and a file
5360 * Core File Generation:: Cause a program dump its core
5361 * Character Sets:: Debugging programs that use a different
5362 character set than GDB does
5363 * Caching Remote Data:: Data caching for remote targets
5364 @end menu
5365
5366 @node Expressions
5367 @section Expressions
5368
5369 @cindex expressions
5370 @code{print} and many other @value{GDBN} commands accept an expression and
5371 compute its value. Any kind of constant, variable or operator defined
5372 by the programming language you are using is valid in an expression in
5373 @value{GDBN}. This includes conditional expressions, function calls,
5374 casts, and string constants. It also includes preprocessor macros, if
5375 you compiled your program to include this information; see
5376 @ref{Compilation}.
5377
5378 @cindex arrays in expressions
5379 @value{GDBN} supports array constants in expressions input by
5380 the user. The syntax is @{@var{element}, @var{element}@dots{}@}. For example,
5381 you can use the command @code{print @{1, 2, 3@}} to build up an array in
5382 memory that is @code{malloc}ed in the target program.
5383
5384 Because C is so widespread, most of the expressions shown in examples in
5385 this manual are in C. @xref{Languages, , Using @value{GDBN} with Different
5386 Languages}, for information on how to use expressions in other
5387 languages.
5388
5389 In this section, we discuss operators that you can use in @value{GDBN}
5390 expressions regardless of your programming language.
5391
5392 @cindex casts, in expressions
5393 Casts are supported in all languages, not just in C, because it is so
5394 useful to cast a number into a pointer in order to examine a structure
5395 at that address in memory.
5396 @c FIXME: casts supported---Mod2 true?
5397
5398 @value{GDBN} supports these operators, in addition to those common
5399 to programming languages:
5400
5401 @table @code
5402 @item @@
5403 @samp{@@} is a binary operator for treating parts of memory as arrays.
5404 @xref{Arrays, ,Artificial arrays}, for more information.
5405
5406 @item ::
5407 @samp{::} allows you to specify a variable in terms of the file or
5408 function where it is defined. @xref{Variables, ,Program variables}.
5409
5410 @cindex @{@var{type}@}
5411 @cindex type casting memory
5412 @cindex memory, viewing as typed object
5413 @cindex casts, to view memory
5414 @item @{@var{type}@} @var{addr}
5415 Refers to an object of type @var{type} stored at address @var{addr} in
5416 memory. @var{addr} may be any expression whose value is an integer or
5417 pointer (but parentheses are required around binary operators, just as in
5418 a cast). This construct is allowed regardless of what kind of data is
5419 normally supposed to reside at @var{addr}.
5420 @end table
5421
5422 @node Variables
5423 @section Program variables
5424
5425 The most common kind of expression to use is the name of a variable
5426 in your program.
5427
5428 Variables in expressions are understood in the selected stack frame
5429 (@pxref{Selection, ,Selecting a frame}); they must be either:
5430
5431 @itemize @bullet
5432 @item
5433 global (or file-static)
5434 @end itemize
5435
5436 @noindent or
5437
5438 @itemize @bullet
5439 @item
5440 visible according to the scope rules of the
5441 programming language from the point of execution in that frame
5442 @end itemize
5443
5444 @noindent This means that in the function
5445
5446 @smallexample
5447 foo (a)
5448 int a;
5449 @{
5450 bar (a);
5451 @{
5452 int b = test ();
5453 bar (b);
5454 @}
5455 @}
5456 @end smallexample
5457
5458 @noindent
5459 you can examine and use the variable @code{a} whenever your program is
5460 executing within the function @code{foo}, but you can only use or
5461 examine the variable @code{b} while your program is executing inside
5462 the block where @code{b} is declared.
5463
5464 @cindex variable name conflict
5465 There is an exception: you can refer to a variable or function whose
5466 scope is a single source file even if the current execution point is not
5467 in this file. But it is possible to have more than one such variable or
5468 function with the same name (in different source files). If that
5469 happens, referring to that name has unpredictable effects. If you wish,
5470 you can specify a static variable in a particular function or file,
5471 using the colon-colon (@code{::}) notation:
5472
5473 @cindex colon-colon, context for variables/functions
5474 @iftex
5475 @c info cannot cope with a :: index entry, but why deprive hard copy readers?
5476 @cindex @code{::}, context for variables/functions
5477 @end iftex
5478 @smallexample
5479 @var{file}::@var{variable}
5480 @var{function}::@var{variable}
5481 @end smallexample
5482
5483 @noindent
5484 Here @var{file} or @var{function} is the name of the context for the
5485 static @var{variable}. In the case of file names, you can use quotes to
5486 make sure @value{GDBN} parses the file name as a single word---for example,
5487 to print a global value of @code{x} defined in @file{f2.c}:
5488
5489 @smallexample
5490 (@value{GDBP}) p 'f2.c'::x
5491 @end smallexample
5492
5493 @cindex C@t{++} scope resolution
5494 This use of @samp{::} is very rarely in conflict with the very similar
5495 use of the same notation in C@t{++}. @value{GDBN} also supports use of the C@t{++}
5496 scope resolution operator in @value{GDBN} expressions.
5497 @c FIXME: Um, so what happens in one of those rare cases where it's in
5498 @c conflict?? --mew
5499
5500 @cindex wrong values
5501 @cindex variable values, wrong
5502 @cindex function entry/exit, wrong values of variables
5503 @cindex optimized code, wrong values of variables
5504 @quotation
5505 @emph{Warning:} Occasionally, a local variable may appear to have the
5506 wrong value at certain points in a function---just after entry to a new
5507 scope, and just before exit.
5508 @end quotation
5509 You may see this problem when you are stepping by machine instructions.
5510 This is because, on most machines, it takes more than one instruction to
5511 set up a stack frame (including local variable definitions); if you are
5512 stepping by machine instructions, variables may appear to have the wrong
5513 values until the stack frame is completely built. On exit, it usually
5514 also takes more than one machine instruction to destroy a stack frame;
5515 after you begin stepping through that group of instructions, local
5516 variable definitions may be gone.
5517
5518 This may also happen when the compiler does significant optimizations.
5519 To be sure of always seeing accurate values, turn off all optimization
5520 when compiling.
5521
5522 @cindex ``No symbol "foo" in current context''
5523 Another possible effect of compiler optimizations is to optimize
5524 unused variables out of existence, or assign variables to registers (as
5525 opposed to memory addresses). Depending on the support for such cases
5526 offered by the debug info format used by the compiler, @value{GDBN}
5527 might not be able to display values for such local variables. If that
5528 happens, @value{GDBN} will print a message like this:
5529
5530 @smallexample
5531 No symbol "foo" in current context.
5532 @end smallexample
5533
5534 To solve such problems, either recompile without optimizations, or use a
5535 different debug info format, if the compiler supports several such
5536 formats. For example, @value{NGCC}, the @sc{gnu} C/C@t{++} compiler,
5537 usually supports the @option{-gstabs+} option. @option{-gstabs+}
5538 produces debug info in a format that is superior to formats such as
5539 COFF. You may be able to use DWARF 2 (@option{-gdwarf-2}), which is also
5540 an effective form for debug info. @xref{Debugging Options,,Options
5541 for Debugging Your Program or @sc{gnu} CC, gcc.info, Using @sc{gnu} CC}.
5542 @xref{C, , Debugging C++}, for more info about debug info formats
5543 that are best suited to C@t{++} programs.
5544
5545 If you ask to print an object whose contents are unknown to
5546 @value{GDBN}, e.g., because its data type is not completely specified
5547 by the debug information, @value{GDBN} will say @samp{<incomplete
5548 type>}. @xref{Symbols, incomplete type}, for more about this.
5549
5550 @node Arrays
5551 @section Artificial arrays
5552
5553 @cindex artificial array
5554 @cindex arrays
5555 @kindex @@@r{, referencing memory as an array}
5556 It is often useful to print out several successive objects of the
5557 same type in memory; a section of an array, or an array of
5558 dynamically determined size for which only a pointer exists in the
5559 program.
5560
5561 You can do this by referring to a contiguous span of memory as an
5562 @dfn{artificial array}, using the binary operator @samp{@@}. The left
5563 operand of @samp{@@} should be the first element of the desired array
5564 and be an individual object. The right operand should be the desired length
5565 of the array. The result is an array value whose elements are all of
5566 the type of the left argument. The first element is actually the left
5567 argument; the second element comes from bytes of memory immediately
5568 following those that hold the first element, and so on. Here is an
5569 example. If a program says
5570
5571 @smallexample
5572 int *array = (int *) malloc (len * sizeof (int));
5573 @end smallexample
5574
5575 @noindent
5576 you can print the contents of @code{array} with
5577
5578 @smallexample
5579 p *array@@len
5580 @end smallexample
5581
5582 The left operand of @samp{@@} must reside in memory. Array values made
5583 with @samp{@@} in this way behave just like other arrays in terms of
5584 subscripting, and are coerced to pointers when used in expressions.
5585 Artificial arrays most often appear in expressions via the value history
5586 (@pxref{Value History, ,Value history}), after printing one out.
5587
5588 Another way to create an artificial array is to use a cast.
5589 This re-interprets a value as if it were an array.
5590 The value need not be in memory:
5591 @smallexample
5592 (@value{GDBP}) p/x (short[2])0x12345678
5593 $1 = @{0x1234, 0x5678@}
5594 @end smallexample
5595
5596 As a convenience, if you leave the array length out (as in
5597 @samp{(@var{type}[])@var{value}}) @value{GDBN} calculates the size to fill
5598 the value (as @samp{sizeof(@var{value})/sizeof(@var{type})}:
5599 @smallexample
5600 (@value{GDBP}) p/x (short[])0x12345678
5601 $2 = @{0x1234, 0x5678@}
5602 @end smallexample
5603
5604 Sometimes the artificial array mechanism is not quite enough; in
5605 moderately complex data structures, the elements of interest may not
5606 actually be adjacent---for example, if you are interested in the values
5607 of pointers in an array. One useful work-around in this situation is
5608 to use a convenience variable (@pxref{Convenience Vars, ,Convenience
5609 variables}) as a counter in an expression that prints the first
5610 interesting value, and then repeat that expression via @key{RET}. For
5611 instance, suppose you have an array @code{dtab} of pointers to
5612 structures, and you are interested in the values of a field @code{fv}
5613 in each structure. Here is an example of what you might type:
5614
5615 @smallexample
5616 set $i = 0
5617 p dtab[$i++]->fv
5618 @key{RET}
5619 @key{RET}
5620 @dots{}
5621 @end smallexample
5622
5623 @node Output Formats
5624 @section Output formats
5625
5626 @cindex formatted output
5627 @cindex output formats
5628 By default, @value{GDBN} prints a value according to its data type. Sometimes
5629 this is not what you want. For example, you might want to print a number
5630 in hex, or a pointer in decimal. Or you might want to view data in memory
5631 at a certain address as a character string or as an instruction. To do
5632 these things, specify an @dfn{output format} when you print a value.
5633
5634 The simplest use of output formats is to say how to print a value
5635 already computed. This is done by starting the arguments of the
5636 @code{print} command with a slash and a format letter. The format
5637 letters supported are:
5638
5639 @table @code
5640 @item x
5641 Regard the bits of the value as an integer, and print the integer in
5642 hexadecimal.
5643
5644 @item d
5645 Print as integer in signed decimal.
5646
5647 @item u
5648 Print as integer in unsigned decimal.
5649
5650 @item o
5651 Print as integer in octal.
5652
5653 @item t
5654 Print as integer in binary. The letter @samp{t} stands for ``two''.
5655 @footnote{@samp{b} cannot be used because these format letters are also
5656 used with the @code{x} command, where @samp{b} stands for ``byte'';
5657 see @ref{Memory,,Examining memory}.}
5658
5659 @item a
5660 @cindex unknown address, locating
5661 @cindex locate address
5662 Print as an address, both absolute in hexadecimal and as an offset from
5663 the nearest preceding symbol. You can use this format used to discover
5664 where (in what function) an unknown address is located:
5665
5666 @smallexample
5667 (@value{GDBP}) p/a 0x54320
5668 $3 = 0x54320 <_initialize_vx+396>
5669 @end smallexample
5670
5671 @noindent
5672 The command @code{info symbol 0x54320} yields similar results.
5673 @xref{Symbols, info symbol}.
5674
5675 @item c
5676 Regard as an integer and print it as a character constant. This
5677 prints both the numerical value and its character representation. The
5678 character representation is replaced with the octal escape @samp{\nnn}
5679 for characters outside the 7-bit @sc{ascii} range.
5680
5681 @item f
5682 Regard the bits of the value as a floating point number and print
5683 using typical floating point syntax.
5684 @end table
5685
5686 For example, to print the program counter in hex (@pxref{Registers}), type
5687
5688 @smallexample
5689 p/x $pc
5690 @end smallexample
5691
5692 @noindent
5693 Note that no space is required before the slash; this is because command
5694 names in @value{GDBN} cannot contain a slash.
5695
5696 To reprint the last value in the value history with a different format,
5697 you can use the @code{print} command with just a format and no
5698 expression. For example, @samp{p/x} reprints the last value in hex.
5699
5700 @node Memory
5701 @section Examining memory
5702
5703 You can use the command @code{x} (for ``examine'') to examine memory in
5704 any of several formats, independently of your program's data types.
5705
5706 @cindex examining memory
5707 @table @code
5708 @kindex x @r{(examine memory)}
5709 @item x/@var{nfu} @var{addr}
5710 @itemx x @var{addr}
5711 @itemx x
5712 Use the @code{x} command to examine memory.
5713 @end table
5714
5715 @var{n}, @var{f}, and @var{u} are all optional parameters that specify how
5716 much memory to display and how to format it; @var{addr} is an
5717 expression giving the address where you want to start displaying memory.
5718 If you use defaults for @var{nfu}, you need not type the slash @samp{/}.
5719 Several commands set convenient defaults for @var{addr}.
5720
5721 @table @r
5722 @item @var{n}, the repeat count
5723 The repeat count is a decimal integer; the default is 1. It specifies
5724 how much memory (counting by units @var{u}) to display.
5725 @c This really is **decimal**; unaffected by 'set radix' as of GDB
5726 @c 4.1.2.
5727
5728 @item @var{f}, the display format
5729 The display format is one of the formats used by @code{print}
5730 (@samp{x}, @samp{d}, @samp{u}, @samp{o}, @samp{t}, @samp{a}, @samp{c},
5731 @samp{f}), and in addition @samp{s} (for null-terminated strings) and
5732 @samp{i} (for machine instructions). The default is @samp{x}
5733 (hexadecimal) initially. The default changes each time you use either
5734 @code{x} or @code{print}.
5735
5736 @item @var{u}, the unit size
5737 The unit size is any of
5738
5739 @table @code
5740 @item b
5741 Bytes.
5742 @item h
5743 Halfwords (two bytes).
5744 @item w
5745 Words (four bytes). This is the initial default.
5746 @item g
5747 Giant words (eight bytes).
5748 @end table
5749
5750 Each time you specify a unit size with @code{x}, that size becomes the
5751 default unit the next time you use @code{x}. (For the @samp{s} and
5752 @samp{i} formats, the unit size is ignored and is normally not written.)
5753
5754 @item @var{addr}, starting display address
5755 @var{addr} is the address where you want @value{GDBN} to begin displaying
5756 memory. The expression need not have a pointer value (though it may);
5757 it is always interpreted as an integer address of a byte of memory.
5758 @xref{Expressions, ,Expressions}, for more information on expressions. The default for
5759 @var{addr} is usually just after the last address examined---but several
5760 other commands also set the default address: @code{info breakpoints} (to
5761 the address of the last breakpoint listed), @code{info line} (to the
5762 starting address of a line), and @code{print} (if you use it to display
5763 a value from memory).
5764 @end table
5765
5766 For example, @samp{x/3uh 0x54320} is a request to display three halfwords
5767 (@code{h}) of memory, formatted as unsigned decimal integers (@samp{u}),
5768 starting at address @code{0x54320}. @samp{x/4xw $sp} prints the four
5769 words (@samp{w}) of memory above the stack pointer (here, @samp{$sp};
5770 @pxref{Registers, ,Registers}) in hexadecimal (@samp{x}).
5771
5772 Since the letters indicating unit sizes are all distinct from the
5773 letters specifying output formats, you do not have to remember whether
5774 unit size or format comes first; either order works. The output
5775 specifications @samp{4xw} and @samp{4wx} mean exactly the same thing.
5776 (However, the count @var{n} must come first; @samp{wx4} does not work.)
5777
5778 Even though the unit size @var{u} is ignored for the formats @samp{s}
5779 and @samp{i}, you might still want to use a count @var{n}; for example,
5780 @samp{3i} specifies that you want to see three machine instructions,
5781 including any operands. The command @code{disassemble} gives an
5782 alternative way of inspecting machine instructions; see @ref{Machine
5783 Code,,Source and machine code}.
5784
5785 All the defaults for the arguments to @code{x} are designed to make it
5786 easy to continue scanning memory with minimal specifications each time
5787 you use @code{x}. For example, after you have inspected three machine
5788 instructions with @samp{x/3i @var{addr}}, you can inspect the next seven
5789 with just @samp{x/7}. If you use @key{RET} to repeat the @code{x} command,
5790 the repeat count @var{n} is used again; the other arguments default as
5791 for successive uses of @code{x}.
5792
5793 @cindex @code{$_}, @code{$__}, and value history
5794 The addresses and contents printed by the @code{x} command are not saved
5795 in the value history because there is often too much of them and they
5796 would get in the way. Instead, @value{GDBN} makes these values available for
5797 subsequent use in expressions as values of the convenience variables
5798 @code{$_} and @code{$__}. After an @code{x} command, the last address
5799 examined is available for use in expressions in the convenience variable
5800 @code{$_}. The contents of that address, as examined, are available in
5801 the convenience variable @code{$__}.
5802
5803 If the @code{x} command has a repeat count, the address and contents saved
5804 are from the last memory unit printed; this is not the same as the last
5805 address printed if several units were printed on the last line of output.
5806
5807 @cindex remote memory comparison
5808 @cindex verify remote memory image
5809 When you are debugging a program running on a remote target machine
5810 (@pxref{Remote}), you may wish to verify the program's image in the
5811 remote machine's memory against the executable file you downloaded to
5812 the target. The @code{compare-sections} command is provided for such
5813 situations.
5814
5815 @table @code
5816 @kindex compare-sections
5817 @item compare-sections @r{[}@var{section-name}@r{]}
5818 Compare the data of a loadable section @var{section-name} in the
5819 executable file of the program being debugged with the same section in
5820 the remote machine's memory, and report any mismatches. With no
5821 arguments, compares all loadable sections. This command's
5822 availability depends on the target's support for the @code{"qCRC"}
5823 remote request.
5824 @end table
5825
5826 @node Auto Display
5827 @section Automatic display
5828 @cindex automatic display
5829 @cindex display of expressions
5830
5831 If you find that you want to print the value of an expression frequently
5832 (to see how it changes), you might want to add it to the @dfn{automatic
5833 display list} so that @value{GDBN} prints its value each time your program stops.
5834 Each expression added to the list is given a number to identify it;
5835 to remove an expression from the list, you specify that number.
5836 The automatic display looks like this:
5837
5838 @smallexample
5839 2: foo = 38
5840 3: bar[5] = (struct hack *) 0x3804
5841 @end smallexample
5842
5843 @noindent
5844 This display shows item numbers, expressions and their current values. As with
5845 displays you request manually using @code{x} or @code{print}, you can
5846 specify the output format you prefer; in fact, @code{display} decides
5847 whether to use @code{print} or @code{x} depending on how elaborate your
5848 format specification is---it uses @code{x} if you specify a unit size,
5849 or one of the two formats (@samp{i} and @samp{s}) that are only
5850 supported by @code{x}; otherwise it uses @code{print}.
5851
5852 @table @code
5853 @kindex display
5854 @item display @var{expr}
5855 Add the expression @var{expr} to the list of expressions to display
5856 each time your program stops. @xref{Expressions, ,Expressions}.
5857
5858 @code{display} does not repeat if you press @key{RET} again after using it.
5859
5860 @item display/@var{fmt} @var{expr}
5861 For @var{fmt} specifying only a display format and not a size or
5862 count, add the expression @var{expr} to the auto-display list but
5863 arrange to display it each time in the specified format @var{fmt}.
5864 @xref{Output Formats,,Output formats}.
5865
5866 @item display/@var{fmt} @var{addr}
5867 For @var{fmt} @samp{i} or @samp{s}, or including a unit-size or a
5868 number of units, add the expression @var{addr} as a memory address to
5869 be examined each time your program stops. Examining means in effect
5870 doing @samp{x/@var{fmt} @var{addr}}. @xref{Memory, ,Examining memory}.
5871 @end table
5872
5873 For example, @samp{display/i $pc} can be helpful, to see the machine
5874 instruction about to be executed each time execution stops (@samp{$pc}
5875 is a common name for the program counter; @pxref{Registers, ,Registers}).
5876
5877 @table @code
5878 @kindex delete display
5879 @kindex undisplay
5880 @item undisplay @var{dnums}@dots{}
5881 @itemx delete display @var{dnums}@dots{}
5882 Remove item numbers @var{dnums} from the list of expressions to display.
5883
5884 @code{undisplay} does not repeat if you press @key{RET} after using it.
5885 (Otherwise you would just get the error @samp{No display number @dots{}}.)
5886
5887 @kindex disable display
5888 @item disable display @var{dnums}@dots{}
5889 Disable the display of item numbers @var{dnums}. A disabled display
5890 item is not printed automatically, but is not forgotten. It may be
5891 enabled again later.
5892
5893 @kindex enable display
5894 @item enable display @var{dnums}@dots{}
5895 Enable display of item numbers @var{dnums}. It becomes effective once
5896 again in auto display of its expression, until you specify otherwise.
5897
5898 @item display
5899 Display the current values of the expressions on the list, just as is
5900 done when your program stops.
5901
5902 @kindex info display
5903 @item info display
5904 Print the list of expressions previously set up to display
5905 automatically, each one with its item number, but without showing the
5906 values. This includes disabled expressions, which are marked as such.
5907 It also includes expressions which would not be displayed right now
5908 because they refer to automatic variables not currently available.
5909 @end table
5910
5911 @cindex display disabled out of scope
5912 If a display expression refers to local variables, then it does not make
5913 sense outside the lexical context for which it was set up. Such an
5914 expression is disabled when execution enters a context where one of its
5915 variables is not defined. For example, if you give the command
5916 @code{display last_char} while inside a function with an argument
5917 @code{last_char}, @value{GDBN} displays this argument while your program
5918 continues to stop inside that function. When it stops elsewhere---where
5919 there is no variable @code{last_char}---the display is disabled
5920 automatically. The next time your program stops where @code{last_char}
5921 is meaningful, you can enable the display expression once again.
5922
5923 @node Print Settings
5924 @section Print settings
5925
5926 @cindex format options
5927 @cindex print settings
5928 @value{GDBN} provides the following ways to control how arrays, structures,
5929 and symbols are printed.
5930
5931 @noindent
5932 These settings are useful for debugging programs in any language:
5933
5934 @table @code
5935 @kindex set print
5936 @item set print address
5937 @itemx set print address on
5938 @cindex print/don't print memory addresses
5939 @value{GDBN} prints memory addresses showing the location of stack
5940 traces, structure values, pointer values, breakpoints, and so forth,
5941 even when it also displays the contents of those addresses. The default
5942 is @code{on}. For example, this is what a stack frame display looks like with
5943 @code{set print address on}:
5944
5945 @smallexample
5946 @group
5947 (@value{GDBP}) f
5948 #0 set_quotes (lq=0x34c78 "<<", rq=0x34c88 ">>")
5949 at input.c:530
5950 530 if (lquote != def_lquote)
5951 @end group
5952 @end smallexample
5953
5954 @item set print address off
5955 Do not print addresses when displaying their contents. For example,
5956 this is the same stack frame displayed with @code{set print address off}:
5957
5958 @smallexample
5959 @group
5960 (@value{GDBP}) set print addr off
5961 (@value{GDBP}) f
5962 #0 set_quotes (lq="<<", rq=">>") at input.c:530
5963 530 if (lquote != def_lquote)
5964 @end group
5965 @end smallexample
5966
5967 You can use @samp{set print address off} to eliminate all machine
5968 dependent displays from the @value{GDBN} interface. For example, with
5969 @code{print address off}, you should get the same text for backtraces on
5970 all machines---whether or not they involve pointer arguments.
5971
5972 @kindex show print
5973 @item show print address
5974 Show whether or not addresses are to be printed.
5975 @end table
5976
5977 When @value{GDBN} prints a symbolic address, it normally prints the
5978 closest earlier symbol plus an offset. If that symbol does not uniquely
5979 identify the address (for example, it is a name whose scope is a single
5980 source file), you may need to clarify. One way to do this is with
5981 @code{info line}, for example @samp{info line *0x4537}. Alternately,
5982 you can set @value{GDBN} to print the source file and line number when
5983 it prints a symbolic address:
5984
5985 @table @code
5986 @item set print symbol-filename on
5987 @cindex source file and line of a symbol
5988 @cindex symbol, source file and line
5989 Tell @value{GDBN} to print the source file name and line number of a
5990 symbol in the symbolic form of an address.
5991
5992 @item set print symbol-filename off
5993 Do not print source file name and line number of a symbol. This is the
5994 default.
5995
5996 @item show print symbol-filename
5997 Show whether or not @value{GDBN} will print the source file name and
5998 line number of a symbol in the symbolic form of an address.
5999 @end table
6000
6001 Another situation where it is helpful to show symbol filenames and line
6002 numbers is when disassembling code; @value{GDBN} shows you the line
6003 number and source file that corresponds to each instruction.
6004
6005 Also, you may wish to see the symbolic form only if the address being
6006 printed is reasonably close to the closest earlier symbol:
6007
6008 @table @code
6009 @item set print max-symbolic-offset @var{max-offset}
6010 @cindex maximum value for offset of closest symbol
6011 Tell @value{GDBN} to only display the symbolic form of an address if the
6012 offset between the closest earlier symbol and the address is less than
6013 @var{max-offset}. The default is 0, which tells @value{GDBN}
6014 to always print the symbolic form of an address if any symbol precedes it.
6015
6016 @item show print max-symbolic-offset
6017 Ask how large the maximum offset is that @value{GDBN} prints in a
6018 symbolic address.
6019 @end table
6020
6021 @cindex wild pointer, interpreting
6022 @cindex pointer, finding referent
6023 If you have a pointer and you are not sure where it points, try
6024 @samp{set print symbol-filename on}. Then you can determine the name
6025 and source file location of the variable where it points, using
6026 @samp{p/a @var{pointer}}. This interprets the address in symbolic form.
6027 For example, here @value{GDBN} shows that a variable @code{ptt} points
6028 at another variable @code{t}, defined in @file{hi2.c}:
6029
6030 @smallexample
6031 (@value{GDBP}) set print symbol-filename on
6032 (@value{GDBP}) p/a ptt
6033 $4 = 0xe008 <t in hi2.c>
6034 @end smallexample
6035
6036 @quotation
6037 @emph{Warning:} For pointers that point to a local variable, @samp{p/a}
6038 does not show the symbol name and filename of the referent, even with
6039 the appropriate @code{set print} options turned on.
6040 @end quotation
6041
6042 Other settings control how different kinds of objects are printed:
6043
6044 @table @code
6045 @item set print array
6046 @itemx set print array on
6047 @cindex pretty print arrays
6048 Pretty print arrays. This format is more convenient to read,
6049 but uses more space. The default is off.
6050
6051 @item set print array off
6052 Return to compressed format for arrays.
6053
6054 @item show print array
6055 Show whether compressed or pretty format is selected for displaying
6056 arrays.
6057
6058 @cindex print array indexes
6059 @item set print array-indexes
6060 @itemx set print array-indexes on
6061 Print the index of each element when displaying arrays. May be more
6062 convenient to locate a given element in the array or quickly find the
6063 index of a given element in that printed array. The default is off.
6064
6065 @item set print array-indexes off
6066 Stop printing element indexes when displaying arrays.
6067
6068 @item show print array-indexes
6069 Show whether the index of each element is printed when displaying
6070 arrays.
6071
6072 @item set print elements @var{number-of-elements}
6073 @cindex number of array elements to print
6074 @cindex limit on number of printed array elements
6075 Set a limit on how many elements of an array @value{GDBN} will print.
6076 If @value{GDBN} is printing a large array, it stops printing after it has
6077 printed the number of elements set by the @code{set print elements} command.
6078 This limit also applies to the display of strings.
6079 When @value{GDBN} starts, this limit is set to 200.
6080 Setting @var{number-of-elements} to zero means that the printing is unlimited.
6081
6082 @item show print elements
6083 Display the number of elements of a large array that @value{GDBN} will print.
6084 If the number is 0, then the printing is unlimited.
6085
6086 @item set print repeats
6087 @cindex repeated array elements
6088 Set the threshold for suppressing display of repeated array
6089 elelments. When the number of consecutive identical elements of an
6090 array exceeds the threshold, @value{GDBN} prints the string
6091 @code{"<repeats @var{n} times>"}, where @var{n} is the number of
6092 identical repetitions, instead of displaying the identical elements
6093 themselves. Setting the threshold to zero will cause all elements to
6094 be individually printed. The default threshold is 10.
6095
6096 @item show print repeats
6097 Display the current threshold for printing repeated identical
6098 elements.
6099
6100 @item set print null-stop
6101 @cindex @sc{null} elements in arrays
6102 Cause @value{GDBN} to stop printing the characters of an array when the first
6103 @sc{null} is encountered. This is useful when large arrays actually
6104 contain only short strings.
6105 The default is off.
6106
6107 @item show print null-stop
6108 Show whether @value{GDBN} stops printing an array on the first
6109 @sc{null} character.
6110
6111 @item set print pretty on
6112 @cindex print structures in indented form
6113 @cindex indentation in structure display
6114 Cause @value{GDBN} to print structures in an indented format with one member
6115 per line, like this:
6116
6117 @smallexample
6118 @group
6119 $1 = @{
6120 next = 0x0,
6121 flags = @{
6122 sweet = 1,
6123 sour = 1
6124 @},
6125 meat = 0x54 "Pork"
6126 @}
6127 @end group
6128 @end smallexample
6129
6130 @item set print pretty off
6131 Cause @value{GDBN} to print structures in a compact format, like this:
6132
6133 @smallexample
6134 @group
6135 $1 = @{next = 0x0, flags = @{sweet = 1, sour = 1@}, \
6136 meat = 0x54 "Pork"@}
6137 @end group
6138 @end smallexample
6139
6140 @noindent
6141 This is the default format.
6142
6143 @item show print pretty
6144 Show which format @value{GDBN} is using to print structures.
6145
6146 @item set print sevenbit-strings on
6147 @cindex eight-bit characters in strings
6148 @cindex octal escapes in strings
6149 Print using only seven-bit characters; if this option is set,
6150 @value{GDBN} displays any eight-bit characters (in strings or
6151 character values) using the notation @code{\}@var{nnn}. This setting is
6152 best if you are working in English (@sc{ascii}) and you use the
6153 high-order bit of characters as a marker or ``meta'' bit.
6154
6155 @item set print sevenbit-strings off
6156 Print full eight-bit characters. This allows the use of more
6157 international character sets, and is the default.
6158
6159 @item show print sevenbit-strings
6160 Show whether or not @value{GDBN} is printing only seven-bit characters.
6161
6162 @item set print union on
6163 @cindex unions in structures, printing
6164 Tell @value{GDBN} to print unions which are contained in structures
6165 and other unions. This is the default setting.
6166
6167 @item set print union off
6168 Tell @value{GDBN} not to print unions which are contained in
6169 structures and other unions. @value{GDBN} will print @code{"@{...@}"}
6170 instead.
6171
6172 @item show print union
6173 Ask @value{GDBN} whether or not it will print unions which are contained in
6174 structures and other unions.
6175
6176 For example, given the declarations
6177
6178 @smallexample
6179 typedef enum @{Tree, Bug@} Species;
6180 typedef enum @{Big_tree, Acorn, Seedling@} Tree_forms;
6181 typedef enum @{Caterpillar, Cocoon, Butterfly@}
6182 Bug_forms;
6183
6184 struct thing @{
6185 Species it;
6186 union @{
6187 Tree_forms tree;
6188 Bug_forms bug;
6189 @} form;
6190 @};
6191
6192 struct thing foo = @{Tree, @{Acorn@}@};
6193 @end smallexample
6194
6195 @noindent
6196 with @code{set print union on} in effect @samp{p foo} would print
6197
6198 @smallexample
6199 $1 = @{it = Tree, form = @{tree = Acorn, bug = Cocoon@}@}
6200 @end smallexample
6201
6202 @noindent
6203 and with @code{set print union off} in effect it would print
6204
6205 @smallexample
6206 $1 = @{it = Tree, form = @{...@}@}
6207 @end smallexample
6208
6209 @noindent
6210 @code{set print union} affects programs written in C-like languages
6211 and in Pascal.
6212 @end table
6213
6214 @need 1000
6215 @noindent
6216 These settings are of interest when debugging C@t{++} programs:
6217
6218 @table @code
6219 @cindex demangling C@t{++} names
6220 @item set print demangle
6221 @itemx set print demangle on
6222 Print C@t{++} names in their source form rather than in the encoded
6223 (``mangled'') form passed to the assembler and linker for type-safe
6224 linkage. The default is on.
6225
6226 @item show print demangle
6227 Show whether C@t{++} names are printed in mangled or demangled form.
6228
6229 @item set print asm-demangle
6230 @itemx set print asm-demangle on
6231 Print C@t{++} names in their source form rather than their mangled form, even
6232 in assembler code printouts such as instruction disassemblies.
6233 The default is off.
6234
6235 @item show print asm-demangle
6236 Show whether C@t{++} names in assembly listings are printed in mangled
6237 or demangled form.
6238
6239 @cindex C@t{++} symbol decoding style
6240 @cindex symbol decoding style, C@t{++}
6241 @kindex set demangle-style
6242 @item set demangle-style @var{style}
6243 Choose among several encoding schemes used by different compilers to
6244 represent C@t{++} names. The choices for @var{style} are currently:
6245
6246 @table @code
6247 @item auto
6248 Allow @value{GDBN} to choose a decoding style by inspecting your program.
6249
6250 @item gnu
6251 Decode based on the @sc{gnu} C@t{++} compiler (@code{g++}) encoding algorithm.
6252 This is the default.
6253
6254 @item hp
6255 Decode based on the HP ANSI C@t{++} (@code{aCC}) encoding algorithm.
6256
6257 @item lucid
6258 Decode based on the Lucid C@t{++} compiler (@code{lcc}) encoding algorithm.
6259
6260 @item arm
6261 Decode using the algorithm in the @cite{C@t{++} Annotated Reference Manual}.
6262 @strong{Warning:} this setting alone is not sufficient to allow
6263 debugging @code{cfront}-generated executables. @value{GDBN} would
6264 require further enhancement to permit that.
6265
6266 @end table
6267 If you omit @var{style}, you will see a list of possible formats.
6268
6269 @item show demangle-style
6270 Display the encoding style currently in use for decoding C@t{++} symbols.
6271
6272 @item set print object
6273 @itemx set print object on
6274 @cindex derived type of an object, printing
6275 @cindex display derived types
6276 When displaying a pointer to an object, identify the @emph{actual}
6277 (derived) type of the object rather than the @emph{declared} type, using
6278 the virtual function table.
6279
6280 @item set print object off
6281 Display only the declared type of objects, without reference to the
6282 virtual function table. This is the default setting.
6283
6284 @item show print object
6285 Show whether actual, or declared, object types are displayed.
6286
6287 @item set print static-members
6288 @itemx set print static-members on
6289 @cindex static members of C@t{++} objects
6290 Print static members when displaying a C@t{++} object. The default is on.
6291
6292 @item set print static-members off
6293 Do not print static members when displaying a C@t{++} object.
6294
6295 @item show print static-members
6296 Show whether C@t{++} static members are printed or not.
6297
6298 @item set print pascal_static-members
6299 @itemx set print pascal_static-members on
6300 @cindex static members of Pacal objects
6301 @cindex Pacal objects, static members display
6302 Print static members when displaying a Pascal object. The default is on.
6303
6304 @item set print pascal_static-members off
6305 Do not print static members when displaying a Pascal object.
6306
6307 @item show print pascal_static-members
6308 Show whether Pascal static members are printed or not.
6309
6310 @c These don't work with HP ANSI C++ yet.
6311 @item set print vtbl
6312 @itemx set print vtbl on
6313 @cindex pretty print C@t{++} virtual function tables
6314 @cindex virtual functions (C@t{++}) display
6315 @cindex VTBL display
6316 Pretty print C@t{++} virtual function tables. The default is off.
6317 (The @code{vtbl} commands do not work on programs compiled with the HP
6318 ANSI C@t{++} compiler (@code{aCC}).)
6319
6320 @item set print vtbl off
6321 Do not pretty print C@t{++} virtual function tables.
6322
6323 @item show print vtbl
6324 Show whether C@t{++} virtual function tables are pretty printed, or not.
6325 @end table
6326
6327 @node Value History
6328 @section Value history
6329
6330 @cindex value history
6331 @cindex history of values printed by @value{GDBN}
6332 Values printed by the @code{print} command are saved in the @value{GDBN}
6333 @dfn{value history}. This allows you to refer to them in other expressions.
6334 Values are kept until the symbol table is re-read or discarded
6335 (for example with the @code{file} or @code{symbol-file} commands).
6336 When the symbol table changes, the value history is discarded,
6337 since the values may contain pointers back to the types defined in the
6338 symbol table.
6339
6340 @cindex @code{$}
6341 @cindex @code{$$}
6342 @cindex history number
6343 The values printed are given @dfn{history numbers} by which you can
6344 refer to them. These are successive integers starting with one.
6345 @code{print} shows you the history number assigned to a value by
6346 printing @samp{$@var{num} = } before the value; here @var{num} is the
6347 history number.
6348
6349 To refer to any previous value, use @samp{$} followed by the value's
6350 history number. The way @code{print} labels its output is designed to
6351 remind you of this. Just @code{$} refers to the most recent value in
6352 the history, and @code{$$} refers to the value before that.
6353 @code{$$@var{n}} refers to the @var{n}th value from the end; @code{$$2}
6354 is the value just prior to @code{$$}, @code{$$1} is equivalent to
6355 @code{$$}, and @code{$$0} is equivalent to @code{$}.
6356
6357 For example, suppose you have just printed a pointer to a structure and
6358 want to see the contents of the structure. It suffices to type
6359
6360 @smallexample
6361 p *$
6362 @end smallexample
6363
6364 If you have a chain of structures where the component @code{next} points
6365 to the next one, you can print the contents of the next one with this:
6366
6367 @smallexample
6368 p *$.next
6369 @end smallexample
6370
6371 @noindent
6372 You can print successive links in the chain by repeating this
6373 command---which you can do by just typing @key{RET}.
6374
6375 Note that the history records values, not expressions. If the value of
6376 @code{x} is 4 and you type these commands:
6377
6378 @smallexample
6379 print x
6380 set x=5
6381 @end smallexample
6382
6383 @noindent
6384 then the value recorded in the value history by the @code{print} command
6385 remains 4 even though the value of @code{x} has changed.
6386
6387 @table @code
6388 @kindex show values
6389 @item show values
6390 Print the last ten values in the value history, with their item numbers.
6391 This is like @samp{p@ $$9} repeated ten times, except that @code{show
6392 values} does not change the history.
6393
6394 @item show values @var{n}
6395 Print ten history values centered on history item number @var{n}.
6396
6397 @item show values +
6398 Print ten history values just after the values last printed. If no more
6399 values are available, @code{show values +} produces no display.
6400 @end table
6401
6402 Pressing @key{RET} to repeat @code{show values @var{n}} has exactly the
6403 same effect as @samp{show values +}.
6404
6405 @node Convenience Vars
6406 @section Convenience variables
6407
6408 @cindex convenience variables
6409 @cindex user-defined variables
6410 @value{GDBN} provides @dfn{convenience variables} that you can use within
6411 @value{GDBN} to hold on to a value and refer to it later. These variables
6412 exist entirely within @value{GDBN}; they are not part of your program, and
6413 setting a convenience variable has no direct effect on further execution
6414 of your program. That is why you can use them freely.
6415
6416 Convenience variables are prefixed with @samp{$}. Any name preceded by
6417 @samp{$} can be used for a convenience variable, unless it is one of
6418 the predefined machine-specific register names (@pxref{Registers, ,Registers}).
6419 (Value history references, in contrast, are @emph{numbers} preceded
6420 by @samp{$}. @xref{Value History, ,Value history}.)
6421
6422 You can save a value in a convenience variable with an assignment
6423 expression, just as you would set a variable in your program.
6424 For example:
6425
6426 @smallexample
6427 set $foo = *object_ptr
6428 @end smallexample
6429
6430 @noindent
6431 would save in @code{$foo} the value contained in the object pointed to by
6432 @code{object_ptr}.
6433
6434 Using a convenience variable for the first time creates it, but its
6435 value is @code{void} until you assign a new value. You can alter the
6436 value with another assignment at any time.
6437
6438 Convenience variables have no fixed types. You can assign a convenience
6439 variable any type of value, including structures and arrays, even if
6440 that variable already has a value of a different type. The convenience
6441 variable, when used as an expression, has the type of its current value.
6442
6443 @table @code
6444 @kindex show convenience
6445 @cindex show all user variables
6446 @item show convenience
6447 Print a list of convenience variables used so far, and their values.
6448 Abbreviated @code{show conv}.
6449
6450 @kindex init-if-undefined
6451 @cindex convenience variables, initializing
6452 @item init-if-undefined $@var{variable} = @var{expression}
6453 Set a convenience variable if it has not already been set. This is useful
6454 for user-defined commands that keep some state. It is similar, in concept,
6455 to using local static variables with initializers in C (except that
6456 convenience variables are global). It can also be used to allow users to
6457 override default values used in a command script.
6458
6459 If the variable is already defined then the expression is not evaluated so
6460 any side-effects do not occur.
6461 @end table
6462
6463 One of the ways to use a convenience variable is as a counter to be
6464 incremented or a pointer to be advanced. For example, to print
6465 a field from successive elements of an array of structures:
6466
6467 @smallexample
6468 set $i = 0
6469 print bar[$i++]->contents
6470 @end smallexample
6471
6472 @noindent
6473 Repeat that command by typing @key{RET}.
6474
6475 Some convenience variables are created automatically by @value{GDBN} and given
6476 values likely to be useful.
6477
6478 @table @code
6479 @vindex $_@r{, convenience variable}
6480 @item $_
6481 The variable @code{$_} is automatically set by the @code{x} command to
6482 the last address examined (@pxref{Memory, ,Examining memory}). Other
6483 commands which provide a default address for @code{x} to examine also
6484 set @code{$_} to that address; these commands include @code{info line}
6485 and @code{info breakpoint}. The type of @code{$_} is @code{void *}
6486 except when set by the @code{x} command, in which case it is a pointer
6487 to the type of @code{$__}.
6488
6489 @vindex $__@r{, convenience variable}
6490 @item $__
6491 The variable @code{$__} is automatically set by the @code{x} command
6492 to the value found in the last address examined. Its type is chosen
6493 to match the format in which the data was printed.
6494
6495 @item $_exitcode
6496 @vindex $_exitcode@r{, convenience variable}
6497 The variable @code{$_exitcode} is automatically set to the exit code when
6498 the program being debugged terminates.
6499 @end table
6500
6501 On HP-UX systems, if you refer to a function or variable name that
6502 begins with a dollar sign, @value{GDBN} searches for a user or system
6503 name first, before it searches for a convenience variable.
6504
6505 @node Registers
6506 @section Registers
6507
6508 @cindex registers
6509 You can refer to machine register contents, in expressions, as variables
6510 with names starting with @samp{$}. The names of registers are different
6511 for each machine; use @code{info registers} to see the names used on
6512 your machine.
6513
6514 @table @code
6515 @kindex info registers
6516 @item info registers
6517 Print the names and values of all registers except floating-point
6518 and vector registers (in the selected stack frame).
6519
6520 @kindex info all-registers
6521 @cindex floating point registers
6522 @item info all-registers
6523 Print the names and values of all registers, including floating-point
6524 and vector registers (in the selected stack frame).
6525
6526 @item info registers @var{regname} @dots{}
6527 Print the @dfn{relativized} value of each specified register @var{regname}.
6528 As discussed in detail below, register values are normally relative to
6529 the selected stack frame. @var{regname} may be any register name valid on
6530 the machine you are using, with or without the initial @samp{$}.
6531 @end table
6532
6533 @cindex stack pointer register
6534 @cindex program counter register
6535 @cindex process status register
6536 @cindex frame pointer register
6537 @cindex standard registers
6538 @value{GDBN} has four ``standard'' register names that are available (in
6539 expressions) on most machines---whenever they do not conflict with an
6540 architecture's canonical mnemonics for registers. The register names
6541 @code{$pc} and @code{$sp} are used for the program counter register and
6542 the stack pointer. @code{$fp} is used for a register that contains a
6543 pointer to the current stack frame, and @code{$ps} is used for a
6544 register that contains the processor status. For example,
6545 you could print the program counter in hex with
6546
6547 @smallexample
6548 p/x $pc
6549 @end smallexample
6550
6551 @noindent
6552 or print the instruction to be executed next with
6553
6554 @smallexample
6555 x/i $pc
6556 @end smallexample
6557
6558 @noindent
6559 or add four to the stack pointer@footnote{This is a way of removing
6560 one word from the stack, on machines where stacks grow downward in
6561 memory (most machines, nowadays). This assumes that the innermost
6562 stack frame is selected; setting @code{$sp} is not allowed when other
6563 stack frames are selected. To pop entire frames off the stack,
6564 regardless of machine architecture, use @code{return};
6565 see @ref{Returning, ,Returning from a function}.} with
6566
6567 @smallexample
6568 set $sp += 4
6569 @end smallexample
6570
6571 Whenever possible, these four standard register names are available on
6572 your machine even though the machine has different canonical mnemonics,
6573 so long as there is no conflict. The @code{info registers} command
6574 shows the canonical names. For example, on the SPARC, @code{info
6575 registers} displays the processor status register as @code{$psr} but you
6576 can also refer to it as @code{$ps}; and on x86-based machines @code{$ps}
6577 is an alias for the @sc{eflags} register.
6578
6579 @value{GDBN} always considers the contents of an ordinary register as an
6580 integer when the register is examined in this way. Some machines have
6581 special registers which can hold nothing but floating point; these
6582 registers are considered to have floating point values. There is no way
6583 to refer to the contents of an ordinary register as floating point value
6584 (although you can @emph{print} it as a floating point value with
6585 @samp{print/f $@var{regname}}).
6586
6587 Some registers have distinct ``raw'' and ``virtual'' data formats. This
6588 means that the data format in which the register contents are saved by
6589 the operating system is not the same one that your program normally
6590 sees. For example, the registers of the 68881 floating point
6591 coprocessor are always saved in ``extended'' (raw) format, but all C
6592 programs expect to work with ``double'' (virtual) format. In such
6593 cases, @value{GDBN} normally works with the virtual format only (the format
6594 that makes sense for your program), but the @code{info registers} command
6595 prints the data in both formats.
6596
6597 @cindex SSE registers (x86)
6598 @cindex MMX registers (x86)
6599 Some machines have special registers whose contents can be interpreted
6600 in several different ways. For example, modern x86-based machines
6601 have SSE and MMX registers that can hold several values packed
6602 together in several different formats. @value{GDBN} refers to such
6603 registers in @code{struct} notation:
6604
6605 @smallexample
6606 (@value{GDBP}) print $xmm1
6607 $1 = @{
6608 v4_float = @{0, 3.43859137e-038, 1.54142831e-044, 1.821688e-044@},
6609 v2_double = @{9.92129282474342e-303, 2.7585945287983262e-313@},
6610 v16_int8 = "\000\000\000\000\3706;\001\v\000\000\000\r\000\000",
6611 v8_int16 = @{0, 0, 14072, 315, 11, 0, 13, 0@},
6612 v4_int32 = @{0, 20657912, 11, 13@},
6613 v2_int64 = @{88725056443645952, 55834574859@},
6614 uint128 = 0x0000000d0000000b013b36f800000000
6615 @}
6616 @end smallexample
6617
6618 @noindent
6619 To set values of such registers, you need to tell @value{GDBN} which
6620 view of the register you wish to change, as if you were assigning
6621 value to a @code{struct} member:
6622
6623 @smallexample
6624 (@value{GDBP}) set $xmm1.uint128 = 0x000000000000000000000000FFFFFFFF
6625 @end smallexample
6626
6627 Normally, register values are relative to the selected stack frame
6628 (@pxref{Selection, ,Selecting a frame}). This means that you get the
6629 value that the register would contain if all stack frames farther in
6630 were exited and their saved registers restored. In order to see the
6631 true contents of hardware registers, you must select the innermost
6632 frame (with @samp{frame 0}).
6633
6634 However, @value{GDBN} must deduce where registers are saved, from the machine
6635 code generated by your compiler. If some registers are not saved, or if
6636 @value{GDBN} is unable to locate the saved registers, the selected stack
6637 frame makes no difference.
6638
6639 @node Floating Point Hardware
6640 @section Floating point hardware
6641 @cindex floating point
6642
6643 Depending on the configuration, @value{GDBN} may be able to give
6644 you more information about the status of the floating point hardware.
6645
6646 @table @code
6647 @kindex info float
6648 @item info float
6649 Display hardware-dependent information about the floating
6650 point unit. The exact contents and layout vary depending on the
6651 floating point chip. Currently, @samp{info float} is supported on
6652 the ARM and x86 machines.
6653 @end table
6654
6655 @node Vector Unit
6656 @section Vector Unit
6657 @cindex vector unit
6658
6659 Depending on the configuration, @value{GDBN} may be able to give you
6660 more information about the status of the vector unit.
6661
6662 @table @code
6663 @kindex info vector
6664 @item info vector
6665 Display information about the vector unit. The exact contents and
6666 layout vary depending on the hardware.
6667 @end table
6668
6669 @node OS Information
6670 @section Operating system auxiliary information
6671 @cindex OS information
6672
6673 @value{GDBN} provides interfaces to useful OS facilities that can help
6674 you debug your program.
6675
6676 @cindex @code{ptrace} system call
6677 @cindex @code{struct user} contents
6678 When @value{GDBN} runs on a @dfn{Posix system} (such as GNU or Unix
6679 machines), it interfaces with the inferior via the @code{ptrace}
6680 system call. The operating system creates a special sata structure,
6681 called @code{struct user}, for this interface. You can use the
6682 command @code{info udot} to display the contents of this data
6683 structure.
6684
6685 @table @code
6686 @item info udot
6687 @kindex info udot
6688 Display the contents of the @code{struct user} maintained by the OS
6689 kernel for the program being debugged. @value{GDBN} displays the
6690 contents of @code{struct user} as a list of hex numbers, similar to
6691 the @code{examine} command.
6692 @end table
6693
6694 @cindex auxiliary vector
6695 @cindex vector, auxiliary
6696 Some operating systems supply an @dfn{auxiliary vector} to programs at
6697 startup. This is akin to the arguments and environment that you
6698 specify for a program, but contains a system-dependent variety of
6699 binary values that tell system libraries important details about the
6700 hardware, operating system, and process. Each value's purpose is
6701 identified by an integer tag; the meanings are well-known but system-specific.
6702 Depending on the configuration and operating system facilities,
6703 @value{GDBN} may be able to show you this information. For remote
6704 targets, this functionality may further depend on the remote stub's
6705 support of the @samp{qXfer:auxv:read} packet, see @ref{Remote
6706 configuration, auxiliary vector}.
6707
6708 @table @code
6709 @kindex info auxv
6710 @item info auxv
6711 Display the auxiliary vector of the inferior, which can be either a
6712 live process or a core dump file. @value{GDBN} prints each tag value
6713 numerically, and also shows names and text descriptions for recognized
6714 tags. Some values in the vector are numbers, some bit masks, and some
6715 pointers to strings or other data. @value{GDBN} displays each value in the
6716 most appropriate form for a recognized tag, and in hexadecimal for
6717 an unrecognized tag.
6718 @end table
6719
6720
6721 @node Memory Region Attributes
6722 @section Memory region attributes
6723 @cindex memory region attributes
6724
6725 @dfn{Memory region attributes} allow you to describe special handling
6726 required by regions of your target's memory. @value{GDBN} uses
6727 attributes to determine whether to allow certain types of memory
6728 accesses; whether to use specific width accesses; and whether to cache
6729 target memory. By default the description of memory regions is
6730 fetched from the target (if the current target supports this), but the
6731 user can override the fetched regions.
6732
6733 Defined memory regions can be individually enabled and disabled. When a
6734 memory region is disabled, @value{GDBN} uses the default attributes when
6735 accessing memory in that region. Similarly, if no memory regions have
6736 been defined, @value{GDBN} uses the default attributes when accessing
6737 all memory.
6738
6739 When a memory region is defined, it is given a number to identify it;
6740 to enable, disable, or remove a memory region, you specify that number.
6741
6742 @table @code
6743 @kindex mem
6744 @item mem @var{lower} @var{upper} @var{attributes}@dots{}
6745 Define a memory region bounded by @var{lower} and @var{upper} with
6746 attributes @var{attributes}@dots{}, and add it to the list of regions
6747 monitored by @value{GDBN}. Note that @var{upper} == 0 is a special
6748 case: it is treated as the the target's maximum memory address.
6749 (0xffff on 16 bit targets, 0xffffffff on 32 bit targets, etc.)
6750
6751 @item mem auto
6752 Discard any user changes to the memory regions and use target-supplied
6753 regions, if available, or no regions if the target does not support.
6754
6755 @kindex delete mem
6756 @item delete mem @var{nums}@dots{}
6757 Remove memory regions @var{nums}@dots{} from the list of regions
6758 monitored by @value{GDBN}.
6759
6760 @kindex disable mem
6761 @item disable mem @var{nums}@dots{}
6762 Disable monitoring of memory regions @var{nums}@dots{}.
6763 A disabled memory region is not forgotten.
6764 It may be enabled again later.
6765
6766 @kindex enable mem
6767 @item enable mem @var{nums}@dots{}
6768 Enable monitoring of memory regions @var{nums}@dots{}.
6769
6770 @kindex info mem
6771 @item info mem
6772 Print a table of all defined memory regions, with the following columns
6773 for each region:
6774
6775 @table @emph
6776 @item Memory Region Number
6777 @item Enabled or Disabled.
6778 Enabled memory regions are marked with @samp{y}.
6779 Disabled memory regions are marked with @samp{n}.
6780
6781 @item Lo Address
6782 The address defining the inclusive lower bound of the memory region.
6783
6784 @item Hi Address
6785 The address defining the exclusive upper bound of the memory region.
6786
6787 @item Attributes
6788 The list of attributes set for this memory region.
6789 @end table
6790 @end table
6791
6792
6793 @subsection Attributes
6794
6795 @subsubsection Memory Access Mode
6796 The access mode attributes set whether @value{GDBN} may make read or
6797 write accesses to a memory region.
6798
6799 While these attributes prevent @value{GDBN} from performing invalid
6800 memory accesses, they do nothing to prevent the target system, I/O DMA,
6801 etc.@: from accessing memory.
6802
6803 @table @code
6804 @item ro
6805 Memory is read only.
6806 @item wo
6807 Memory is write only.
6808 @item rw
6809 Memory is read/write. This is the default.
6810 @end table
6811
6812 @subsubsection Memory Access Size
6813 The acccess size attributes tells @value{GDBN} to use specific sized
6814 accesses in the memory region. Often memory mapped device registers
6815 require specific sized accesses. If no access size attribute is
6816 specified, @value{GDBN} may use accesses of any size.
6817
6818 @table @code
6819 @item 8
6820 Use 8 bit memory accesses.
6821 @item 16
6822 Use 16 bit memory accesses.
6823 @item 32
6824 Use 32 bit memory accesses.
6825 @item 64
6826 Use 64 bit memory accesses.
6827 @end table
6828
6829 @c @subsubsection Hardware/Software Breakpoints
6830 @c The hardware/software breakpoint attributes set whether @value{GDBN}
6831 @c will use hardware or software breakpoints for the internal breakpoints
6832 @c used by the step, next, finish, until, etc. commands.
6833 @c
6834 @c @table @code
6835 @c @item hwbreak
6836 @c Always use hardware breakpoints
6837 @c @item swbreak (default)
6838 @c @end table
6839
6840 @subsubsection Data Cache
6841 The data cache attributes set whether @value{GDBN} will cache target
6842 memory. While this generally improves performance by reducing debug
6843 protocol overhead, it can lead to incorrect results because @value{GDBN}
6844 does not know about volatile variables or memory mapped device
6845 registers.
6846
6847 @table @code
6848 @item cache
6849 Enable @value{GDBN} to cache target memory.
6850 @item nocache
6851 Disable @value{GDBN} from caching target memory. This is the default.
6852 @end table
6853
6854 @c @subsubsection Memory Write Verification
6855 @c The memory write verification attributes set whether @value{GDBN}
6856 @c will re-reads data after each write to verify the write was successful.
6857 @c
6858 @c @table @code
6859 @c @item verify
6860 @c @item noverify (default)
6861 @c @end table
6862
6863 @node Dump/Restore Files
6864 @section Copy between memory and a file
6865 @cindex dump/restore files
6866 @cindex append data to a file
6867 @cindex dump data to a file
6868 @cindex restore data from a file
6869
6870 You can use the commands @code{dump}, @code{append}, and
6871 @code{restore} to copy data between target memory and a file. The
6872 @code{dump} and @code{append} commands write data to a file, and the
6873 @code{restore} command reads data from a file back into the inferior's
6874 memory. Files may be in binary, Motorola S-record, Intel hex, or
6875 Tektronix Hex format; however, @value{GDBN} can only append to binary
6876 files.
6877
6878 @table @code
6879
6880 @kindex dump
6881 @item dump @r{[}@var{format}@r{]} memory @var{filename} @var{start_addr} @var{end_addr}
6882 @itemx dump @r{[}@var{format}@r{]} value @var{filename} @var{expr}
6883 Dump the contents of memory from @var{start_addr} to @var{end_addr},
6884 or the value of @var{expr}, to @var{filename} in the given format.
6885
6886 The @var{format} parameter may be any one of:
6887 @table @code
6888 @item binary
6889 Raw binary form.
6890 @item ihex
6891 Intel hex format.
6892 @item srec
6893 Motorola S-record format.
6894 @item tekhex
6895 Tektronix Hex format.
6896 @end table
6897
6898 @value{GDBN} uses the same definitions of these formats as the
6899 @sc{gnu} binary utilities, like @samp{objdump} and @samp{objcopy}. If
6900 @var{format} is omitted, @value{GDBN} dumps the data in raw binary
6901 form.
6902
6903 @kindex append
6904 @item append @r{[}binary@r{]} memory @var{filename} @var{start_addr} @var{end_addr}
6905 @itemx append @r{[}binary@r{]} value @var{filename} @var{expr}
6906 Append the contents of memory from @var{start_addr} to @var{end_addr},
6907 or the value of @var{expr}, to the file @var{filename}, in raw binary form.
6908 (@value{GDBN} can only append data to files in raw binary form.)
6909
6910 @kindex restore
6911 @item restore @var{filename} @r{[}binary@r{]} @var{bias} @var{start} @var{end}
6912 Restore the contents of file @var{filename} into memory. The
6913 @code{restore} command can automatically recognize any known @sc{bfd}
6914 file format, except for raw binary. To restore a raw binary file you
6915 must specify the optional keyword @code{binary} after the filename.
6916
6917 If @var{bias} is non-zero, its value will be added to the addresses
6918 contained in the file. Binary files always start at address zero, so
6919 they will be restored at address @var{bias}. Other bfd files have
6920 a built-in location; they will be restored at offset @var{bias}
6921 from that location.
6922
6923 If @var{start} and/or @var{end} are non-zero, then only data between
6924 file offset @var{start} and file offset @var{end} will be restored.
6925 These offsets are relative to the addresses in the file, before
6926 the @var{bias} argument is applied.
6927
6928 @end table
6929
6930 @node Core File Generation
6931 @section How to Produce a Core File from Your Program
6932 @cindex dump core from inferior
6933
6934 A @dfn{core file} or @dfn{core dump} is a file that records the memory
6935 image of a running process and its process status (register values
6936 etc.). Its primary use is post-mortem debugging of a program that
6937 crashed while it ran outside a debugger. A program that crashes
6938 automatically produces a core file, unless this feature is disabled by
6939 the user. @xref{Files}, for information on invoking @value{GDBN} in
6940 the post-mortem debugging mode.
6941
6942 Occasionally, you may wish to produce a core file of the program you
6943 are debugging in order to preserve a snapshot of its state.
6944 @value{GDBN} has a special command for that.
6945
6946 @table @code
6947 @kindex gcore
6948 @kindex generate-core-file
6949 @item generate-core-file [@var{file}]
6950 @itemx gcore [@var{file}]
6951 Produce a core dump of the inferior process. The optional argument
6952 @var{file} specifies the file name where to put the core dump. If not
6953 specified, the file name defaults to @file{core.@var{pid}}, where
6954 @var{pid} is the inferior process ID.
6955
6956 Note that this command is implemented only for some systems (as of
6957 this writing, @sc{gnu}/Linux, FreeBSD, Solaris, Unixware, and S390).
6958 @end table
6959
6960 @node Character Sets
6961 @section Character Sets
6962 @cindex character sets
6963 @cindex charset
6964 @cindex translating between character sets
6965 @cindex host character set
6966 @cindex target character set
6967
6968 If the program you are debugging uses a different character set to
6969 represent characters and strings than the one @value{GDBN} uses itself,
6970 @value{GDBN} can automatically translate between the character sets for
6971 you. The character set @value{GDBN} uses we call the @dfn{host
6972 character set}; the one the inferior program uses we call the
6973 @dfn{target character set}.
6974
6975 For example, if you are running @value{GDBN} on a @sc{gnu}/Linux system, which
6976 uses the ISO Latin 1 character set, but you are using @value{GDBN}'s
6977 remote protocol (@pxref{Remote,Remote Debugging}) to debug a program
6978 running on an IBM mainframe, which uses the @sc{ebcdic} character set,
6979 then the host character set is Latin-1, and the target character set is
6980 @sc{ebcdic}. If you give @value{GDBN} the command @code{set
6981 target-charset EBCDIC-US}, then @value{GDBN} translates between
6982 @sc{ebcdic} and Latin 1 as you print character or string values, or use
6983 character and string literals in expressions.
6984
6985 @value{GDBN} has no way to automatically recognize which character set
6986 the inferior program uses; you must tell it, using the @code{set
6987 target-charset} command, described below.
6988
6989 Here are the commands for controlling @value{GDBN}'s character set
6990 support:
6991
6992 @table @code
6993 @item set target-charset @var{charset}
6994 @kindex set target-charset
6995 Set the current target character set to @var{charset}. We list the
6996 character set names @value{GDBN} recognizes below, but if you type
6997 @code{set target-charset} followed by @key{TAB}@key{TAB}, @value{GDBN} will
6998 list the target character sets it supports.
6999 @end table
7000
7001 @table @code
7002 @item set host-charset @var{charset}
7003 @kindex set host-charset
7004 Set the current host character set to @var{charset}.
7005
7006 By default, @value{GDBN} uses a host character set appropriate to the
7007 system it is running on; you can override that default using the
7008 @code{set host-charset} command.
7009
7010 @value{GDBN} can only use certain character sets as its host character
7011 set. We list the character set names @value{GDBN} recognizes below, and
7012 indicate which can be host character sets, but if you type
7013 @code{set target-charset} followed by @key{TAB}@key{TAB}, @value{GDBN} will
7014 list the host character sets it supports.
7015
7016 @item set charset @var{charset}
7017 @kindex set charset
7018 Set the current host and target character sets to @var{charset}. As
7019 above, if you type @code{set charset} followed by @key{TAB}@key{TAB},
7020 @value{GDBN} will list the name of the character sets that can be used
7021 for both host and target.
7022
7023
7024 @item show charset
7025 @kindex show charset
7026 Show the names of the current host and target charsets.
7027
7028 @itemx show host-charset
7029 @kindex show host-charset
7030 Show the name of the current host charset.
7031
7032 @itemx show target-charset
7033 @kindex show target-charset
7034 Show the name of the current target charset.
7035
7036 @end table
7037
7038 @value{GDBN} currently includes support for the following character
7039 sets:
7040
7041 @table @code
7042
7043 @item ASCII
7044 @cindex ASCII character set
7045 Seven-bit U.S. @sc{ascii}. @value{GDBN} can use this as its host
7046 character set.
7047
7048 @item ISO-8859-1
7049 @cindex ISO 8859-1 character set
7050 @cindex ISO Latin 1 character set
7051 The ISO Latin 1 character set. This extends @sc{ascii} with accented
7052 characters needed for French, German, and Spanish. @value{GDBN} can use
7053 this as its host character set.
7054
7055 @item EBCDIC-US
7056 @itemx IBM1047
7057 @cindex EBCDIC character set
7058 @cindex IBM1047 character set
7059 Variants of the @sc{ebcdic} character set, used on some of IBM's
7060 mainframe operating systems. (@sc{gnu}/Linux on the S/390 uses U.S. @sc{ascii}.)
7061 @value{GDBN} cannot use these as its host character set.
7062
7063 @end table
7064
7065 Note that these are all single-byte character sets. More work inside
7066 GDB is needed to support multi-byte or variable-width character
7067 encodings, like the UTF-8 and UCS-2 encodings of Unicode.
7068
7069 Here is an example of @value{GDBN}'s character set support in action.
7070 Assume that the following source code has been placed in the file
7071 @file{charset-test.c}:
7072
7073 @smallexample
7074 #include <stdio.h>
7075
7076 char ascii_hello[]
7077 = @{72, 101, 108, 108, 111, 44, 32, 119,
7078 111, 114, 108, 100, 33, 10, 0@};
7079 char ibm1047_hello[]
7080 = @{200, 133, 147, 147, 150, 107, 64, 166,
7081 150, 153, 147, 132, 90, 37, 0@};
7082
7083 main ()
7084 @{
7085 printf ("Hello, world!\n");
7086 @}
7087 @end smallexample
7088
7089 In this program, @code{ascii_hello} and @code{ibm1047_hello} are arrays
7090 containing the string @samp{Hello, world!} followed by a newline,
7091 encoded in the @sc{ascii} and @sc{ibm1047} character sets.
7092
7093 We compile the program, and invoke the debugger on it:
7094
7095 @smallexample
7096 $ gcc -g charset-test.c -o charset-test
7097 $ gdb -nw charset-test
7098 GNU gdb 2001-12-19-cvs
7099 Copyright 2001 Free Software Foundation, Inc.
7100 @dots{}
7101 (@value{GDBP})
7102 @end smallexample
7103
7104 We can use the @code{show charset} command to see what character sets
7105 @value{GDBN} is currently using to interpret and display characters and
7106 strings:
7107
7108 @smallexample
7109 (@value{GDBP}) show charset
7110 The current host and target character set is `ISO-8859-1'.
7111 (@value{GDBP})
7112 @end smallexample
7113
7114 For the sake of printing this manual, let's use @sc{ascii} as our
7115 initial character set:
7116 @smallexample
7117 (@value{GDBP}) set charset ASCII
7118 (@value{GDBP}) show charset
7119 The current host and target character set is `ASCII'.
7120 (@value{GDBP})
7121 @end smallexample
7122
7123 Let's assume that @sc{ascii} is indeed the correct character set for our
7124 host system --- in other words, let's assume that if @value{GDBN} prints
7125 characters using the @sc{ascii} character set, our terminal will display
7126 them properly. Since our current target character set is also
7127 @sc{ascii}, the contents of @code{ascii_hello} print legibly:
7128
7129 @smallexample
7130 (@value{GDBP}) print ascii_hello
7131 $1 = 0x401698 "Hello, world!\n"
7132 (@value{GDBP}) print ascii_hello[0]
7133 $2 = 72 'H'
7134 (@value{GDBP})
7135 @end smallexample
7136
7137 @value{GDBN} uses the target character set for character and string
7138 literals you use in expressions:
7139
7140 @smallexample
7141 (@value{GDBP}) print '+'
7142 $3 = 43 '+'
7143 (@value{GDBP})
7144 @end smallexample
7145
7146 The @sc{ascii} character set uses the number 43 to encode the @samp{+}
7147 character.
7148
7149 @value{GDBN} relies on the user to tell it which character set the
7150 target program uses. If we print @code{ibm1047_hello} while our target
7151 character set is still @sc{ascii}, we get jibberish:
7152
7153 @smallexample
7154 (@value{GDBP}) print ibm1047_hello
7155 $4 = 0x4016a8 "\310\205\223\223\226k@@\246\226\231\223\204Z%"
7156 (@value{GDBP}) print ibm1047_hello[0]
7157 $5 = 200 '\310'
7158 (@value{GDBP})
7159 @end smallexample
7160
7161 If we invoke the @code{set target-charset} followed by @key{TAB}@key{TAB},
7162 @value{GDBN} tells us the character sets it supports:
7163
7164 @smallexample
7165 (@value{GDBP}) set target-charset
7166 ASCII EBCDIC-US IBM1047 ISO-8859-1
7167 (@value{GDBP}) set target-charset
7168 @end smallexample
7169
7170 We can select @sc{ibm1047} as our target character set, and examine the
7171 program's strings again. Now the @sc{ascii} string is wrong, but
7172 @value{GDBN} translates the contents of @code{ibm1047_hello} from the
7173 target character set, @sc{ibm1047}, to the host character set,
7174 @sc{ascii}, and they display correctly:
7175
7176 @smallexample
7177 (@value{GDBP}) set target-charset IBM1047
7178 (@value{GDBP}) show charset
7179 The current host character set is `ASCII'.
7180 The current target character set is `IBM1047'.
7181 (@value{GDBP}) print ascii_hello
7182 $6 = 0x401698 "\110\145%%?\054\040\167?\162%\144\041\012"
7183 (@value{GDBP}) print ascii_hello[0]
7184 $7 = 72 '\110'
7185 (@value{GDBP}) print ibm1047_hello
7186 $8 = 0x4016a8 "Hello, world!\n"
7187 (@value{GDBP}) print ibm1047_hello[0]
7188 $9 = 200 'H'
7189 (@value{GDBP})
7190 @end smallexample
7191
7192 As above, @value{GDBN} uses the target character set for character and
7193 string literals you use in expressions:
7194
7195 @smallexample
7196 (@value{GDBP}) print '+'
7197 $10 = 78 '+'
7198 (@value{GDBP})
7199 @end smallexample
7200
7201 The @sc{ibm1047} character set uses the number 78 to encode the @samp{+}
7202 character.
7203
7204 @node Caching Remote Data
7205 @section Caching Data of Remote Targets
7206 @cindex caching data of remote targets
7207
7208 @value{GDBN} can cache data exchanged between the debugger and a
7209 remote target (@pxref{Remote}). Such caching generally improves
7210 performance, because it reduces the overhead of the remote protocol by
7211 bundling memory reads and writes into large chunks. Unfortunately,
7212 @value{GDBN} does not currently know anything about volatile
7213 registers, and thus data caching will produce incorrect results when
7214 volatile registers are in use.
7215
7216 @table @code
7217 @kindex set remotecache
7218 @item set remotecache on
7219 @itemx set remotecache off
7220 Set caching state for remote targets. When @code{ON}, use data
7221 caching. By default, this option is @code{OFF}.
7222
7223 @kindex show remotecache
7224 @item show remotecache
7225 Show the current state of data caching for remote targets.
7226
7227 @kindex info dcache
7228 @item info dcache
7229 Print the information about the data cache performance. The
7230 information displayed includes: the dcache width and depth; and for
7231 each cache line, how many times it was referenced, and its data and
7232 state (dirty, bad, ok, etc.). This command is useful for debugging
7233 the data cache operation.
7234 @end table
7235
7236
7237 @node Macros
7238 @chapter C Preprocessor Macros
7239
7240 Some languages, such as C and C@t{++}, provide a way to define and invoke
7241 ``preprocessor macros'' which expand into strings of tokens.
7242 @value{GDBN} can evaluate expressions containing macro invocations, show
7243 the result of macro expansion, and show a macro's definition, including
7244 where it was defined.
7245
7246 You may need to compile your program specially to provide @value{GDBN}
7247 with information about preprocessor macros. Most compilers do not
7248 include macros in their debugging information, even when you compile
7249 with the @option{-g} flag. @xref{Compilation}.
7250
7251 A program may define a macro at one point, remove that definition later,
7252 and then provide a different definition after that. Thus, at different
7253 points in the program, a macro may have different definitions, or have
7254 no definition at all. If there is a current stack frame, @value{GDBN}
7255 uses the macros in scope at that frame's source code line. Otherwise,
7256 @value{GDBN} uses the macros in scope at the current listing location;
7257 see @ref{List}.
7258
7259 At the moment, @value{GDBN} does not support the @code{##}
7260 token-splicing operator, the @code{#} stringification operator, or
7261 variable-arity macros.
7262
7263 Whenever @value{GDBN} evaluates an expression, it always expands any
7264 macro invocations present in the expression. @value{GDBN} also provides
7265 the following commands for working with macros explicitly.
7266
7267 @table @code
7268
7269 @kindex macro expand
7270 @cindex macro expansion, showing the results of preprocessor
7271 @cindex preprocessor macro expansion, showing the results of
7272 @cindex expanding preprocessor macros
7273 @item macro expand @var{expression}
7274 @itemx macro exp @var{expression}
7275 Show the results of expanding all preprocessor macro invocations in
7276 @var{expression}. Since @value{GDBN} simply expands macros, but does
7277 not parse the result, @var{expression} need not be a valid expression;
7278 it can be any string of tokens.
7279
7280 @kindex macro exp1
7281 @item macro expand-once @var{expression}
7282 @itemx macro exp1 @var{expression}
7283 @cindex expand macro once
7284 @i{(This command is not yet implemented.)} Show the results of
7285 expanding those preprocessor macro invocations that appear explicitly in
7286 @var{expression}. Macro invocations appearing in that expansion are
7287 left unchanged. This command allows you to see the effect of a
7288 particular macro more clearly, without being confused by further
7289 expansions. Since @value{GDBN} simply expands macros, but does not
7290 parse the result, @var{expression} need not be a valid expression; it
7291 can be any string of tokens.
7292
7293 @kindex info macro
7294 @cindex macro definition, showing
7295 @cindex definition, showing a macro's
7296 @item info macro @var{macro}
7297 Show the definition of the macro named @var{macro}, and describe the
7298 source location where that definition was established.
7299
7300 @kindex macro define
7301 @cindex user-defined macros
7302 @cindex defining macros interactively
7303 @cindex macros, user-defined
7304 @item macro define @var{macro} @var{replacement-list}
7305 @itemx macro define @var{macro}(@var{arglist}) @var{replacement-list}
7306 @i{(This command is not yet implemented.)} Introduce a definition for a
7307 preprocessor macro named @var{macro}, invocations of which are replaced
7308 by the tokens given in @var{replacement-list}. The first form of this
7309 command defines an ``object-like'' macro, which takes no arguments; the
7310 second form defines a ``function-like'' macro, which takes the arguments
7311 given in @var{arglist}.
7312
7313 A definition introduced by this command is in scope in every expression
7314 evaluated in @value{GDBN}, until it is removed with the @command{macro
7315 undef} command, described below. The definition overrides all
7316 definitions for @var{macro} present in the program being debugged, as
7317 well as any previous user-supplied definition.
7318
7319 @kindex macro undef
7320 @item macro undef @var{macro}
7321 @i{(This command is not yet implemented.)} Remove any user-supplied
7322 definition for the macro named @var{macro}. This command only affects
7323 definitions provided with the @command{macro define} command, described
7324 above; it cannot remove definitions present in the program being
7325 debugged.
7326
7327 @kindex macro list
7328 @item macro list
7329 @i{(This command is not yet implemented.)} List all the macros
7330 defined using the @code{macro define} command.
7331 @end table
7332
7333 @cindex macros, example of debugging with
7334 Here is a transcript showing the above commands in action. First, we
7335 show our source files:
7336
7337 @smallexample
7338 $ cat sample.c
7339 #include <stdio.h>
7340 #include "sample.h"
7341
7342 #define M 42
7343 #define ADD(x) (M + x)
7344
7345 main ()
7346 @{
7347 #define N 28
7348 printf ("Hello, world!\n");
7349 #undef N
7350 printf ("We're so creative.\n");
7351 #define N 1729
7352 printf ("Goodbye, world!\n");
7353 @}
7354 $ cat sample.h
7355 #define Q <
7356 $
7357 @end smallexample
7358
7359 Now, we compile the program using the @sc{gnu} C compiler, @value{NGCC}.
7360 We pass the @option{-gdwarf-2} and @option{-g3} flags to ensure the
7361 compiler includes information about preprocessor macros in the debugging
7362 information.
7363
7364 @smallexample
7365 $ gcc -gdwarf-2 -g3 sample.c -o sample
7366 $
7367 @end smallexample
7368
7369 Now, we start @value{GDBN} on our sample program:
7370
7371 @smallexample
7372 $ gdb -nw sample
7373 GNU gdb 2002-05-06-cvs
7374 Copyright 2002 Free Software Foundation, Inc.
7375 GDB is free software, @dots{}
7376 (@value{GDBP})
7377 @end smallexample
7378
7379 We can expand macros and examine their definitions, even when the
7380 program is not running. @value{GDBN} uses the current listing position
7381 to decide which macro definitions are in scope:
7382
7383 @smallexample
7384 (@value{GDBP}) list main
7385 3
7386 4 #define M 42
7387 5 #define ADD(x) (M + x)
7388 6
7389 7 main ()
7390 8 @{
7391 9 #define N 28
7392 10 printf ("Hello, world!\n");
7393 11 #undef N
7394 12 printf ("We're so creative.\n");
7395 (@value{GDBP}) info macro ADD
7396 Defined at /home/jimb/gdb/macros/play/sample.c:5
7397 #define ADD(x) (M + x)
7398 (@value{GDBP}) info macro Q
7399 Defined at /home/jimb/gdb/macros/play/sample.h:1
7400 included at /home/jimb/gdb/macros/play/sample.c:2
7401 #define Q <
7402 (@value{GDBP}) macro expand ADD(1)
7403 expands to: (42 + 1)
7404 (@value{GDBP}) macro expand-once ADD(1)
7405 expands to: once (M + 1)
7406 (@value{GDBP})
7407 @end smallexample
7408
7409 In the example above, note that @command{macro expand-once} expands only
7410 the macro invocation explicit in the original text --- the invocation of
7411 @code{ADD} --- but does not expand the invocation of the macro @code{M},
7412 which was introduced by @code{ADD}.
7413
7414 Once the program is running, GDB uses the macro definitions in force at
7415 the source line of the current stack frame:
7416
7417 @smallexample
7418 (@value{GDBP}) break main
7419 Breakpoint 1 at 0x8048370: file sample.c, line 10.
7420 (@value{GDBP}) run
7421 Starting program: /home/jimb/gdb/macros/play/sample
7422
7423 Breakpoint 1, main () at sample.c:10
7424 10 printf ("Hello, world!\n");
7425 (@value{GDBP})
7426 @end smallexample
7427
7428 At line 10, the definition of the macro @code{N} at line 9 is in force:
7429
7430 @smallexample
7431 (@value{GDBP}) info macro N
7432 Defined at /home/jimb/gdb/macros/play/sample.c:9
7433 #define N 28
7434 (@value{GDBP}) macro expand N Q M
7435 expands to: 28 < 42
7436 (@value{GDBP}) print N Q M
7437 $1 = 1
7438 (@value{GDBP})
7439 @end smallexample
7440
7441 As we step over directives that remove @code{N}'s definition, and then
7442 give it a new definition, @value{GDBN} finds the definition (or lack
7443 thereof) in force at each point:
7444
7445 @smallexample
7446 (@value{GDBP}) next
7447 Hello, world!
7448 12 printf ("We're so creative.\n");
7449 (@value{GDBP}) info macro N
7450 The symbol `N' has no definition as a C/C++ preprocessor macro
7451 at /home/jimb/gdb/macros/play/sample.c:12
7452 (@value{GDBP}) next
7453 We're so creative.
7454 14 printf ("Goodbye, world!\n");
7455 (@value{GDBP}) info macro N
7456 Defined at /home/jimb/gdb/macros/play/sample.c:13
7457 #define N 1729
7458 (@value{GDBP}) macro expand N Q M
7459 expands to: 1729 < 42
7460 (@value{GDBP}) print N Q M
7461 $2 = 0
7462 (@value{GDBP})
7463 @end smallexample
7464
7465
7466 @node Tracepoints
7467 @chapter Tracepoints
7468 @c This chapter is based on the documentation written by Michael
7469 @c Snyder, David Taylor, Jim Blandy, and Elena Zannoni.
7470
7471 @cindex tracepoints
7472 In some applications, it is not feasible for the debugger to interrupt
7473 the program's execution long enough for the developer to learn
7474 anything helpful about its behavior. If the program's correctness
7475 depends on its real-time behavior, delays introduced by a debugger
7476 might cause the program to change its behavior drastically, or perhaps
7477 fail, even when the code itself is correct. It is useful to be able
7478 to observe the program's behavior without interrupting it.
7479
7480 Using @value{GDBN}'s @code{trace} and @code{collect} commands, you can
7481 specify locations in the program, called @dfn{tracepoints}, and
7482 arbitrary expressions to evaluate when those tracepoints are reached.
7483 Later, using the @code{tfind} command, you can examine the values
7484 those expressions had when the program hit the tracepoints. The
7485 expressions may also denote objects in memory---structures or arrays,
7486 for example---whose values @value{GDBN} should record; while visiting
7487 a particular tracepoint, you may inspect those objects as if they were
7488 in memory at that moment. However, because @value{GDBN} records these
7489 values without interacting with you, it can do so quickly and
7490 unobtrusively, hopefully not disturbing the program's behavior.
7491
7492 The tracepoint facility is currently available only for remote
7493 targets. @xref{Targets}. In addition, your remote target must know
7494 how to collect trace data. This functionality is implemented in the
7495 remote stub; however, none of the stubs distributed with @value{GDBN}
7496 support tracepoints as of this writing. The format of the remote
7497 packets used to implement tracepoints are described in @ref{Tracepoint
7498 Packets}.
7499
7500 This chapter describes the tracepoint commands and features.
7501
7502 @menu
7503 * Set Tracepoints::
7504 * Analyze Collected Data::
7505 * Tracepoint Variables::
7506 @end menu
7507
7508 @node Set Tracepoints
7509 @section Commands to Set Tracepoints
7510
7511 Before running such a @dfn{trace experiment}, an arbitrary number of
7512 tracepoints can be set. Like a breakpoint (@pxref{Set Breaks}), a
7513 tracepoint has a number assigned to it by @value{GDBN}. Like with
7514 breakpoints, tracepoint numbers are successive integers starting from
7515 one. Many of the commands associated with tracepoints take the
7516 tracepoint number as their argument, to identify which tracepoint to
7517 work on.
7518
7519 For each tracepoint, you can specify, in advance, some arbitrary set
7520 of data that you want the target to collect in the trace buffer when
7521 it hits that tracepoint. The collected data can include registers,
7522 local variables, or global data. Later, you can use @value{GDBN}
7523 commands to examine the values these data had at the time the
7524 tracepoint was hit.
7525
7526 This section describes commands to set tracepoints and associated
7527 conditions and actions.
7528
7529 @menu
7530 * Create and Delete Tracepoints::
7531 * Enable and Disable Tracepoints::
7532 * Tracepoint Passcounts::
7533 * Tracepoint Actions::
7534 * Listing Tracepoints::
7535 * Starting and Stopping Trace Experiment::
7536 @end menu
7537
7538 @node Create and Delete Tracepoints
7539 @subsection Create and Delete Tracepoints
7540
7541 @table @code
7542 @cindex set tracepoint
7543 @kindex trace
7544 @item trace
7545 The @code{trace} command is very similar to the @code{break} command.
7546 Its argument can be a source line, a function name, or an address in
7547 the target program. @xref{Set Breaks}. The @code{trace} command
7548 defines a tracepoint, which is a point in the target program where the
7549 debugger will briefly stop, collect some data, and then allow the
7550 program to continue. Setting a tracepoint or changing its commands
7551 doesn't take effect until the next @code{tstart} command; thus, you
7552 cannot change the tracepoint attributes once a trace experiment is
7553 running.
7554
7555 Here are some examples of using the @code{trace} command:
7556
7557 @smallexample
7558 (@value{GDBP}) @b{trace foo.c:121} // a source file and line number
7559
7560 (@value{GDBP}) @b{trace +2} // 2 lines forward
7561
7562 (@value{GDBP}) @b{trace my_function} // first source line of function
7563
7564 (@value{GDBP}) @b{trace *my_function} // EXACT start address of function
7565
7566 (@value{GDBP}) @b{trace *0x2117c4} // an address
7567 @end smallexample
7568
7569 @noindent
7570 You can abbreviate @code{trace} as @code{tr}.
7571
7572 @vindex $tpnum
7573 @cindex last tracepoint number
7574 @cindex recent tracepoint number
7575 @cindex tracepoint number
7576 The convenience variable @code{$tpnum} records the tracepoint number
7577 of the most recently set tracepoint.
7578
7579 @kindex delete tracepoint
7580 @cindex tracepoint deletion
7581 @item delete tracepoint @r{[}@var{num}@r{]}
7582 Permanently delete one or more tracepoints. With no argument, the
7583 default is to delete all tracepoints.
7584
7585 Examples:
7586
7587 @smallexample
7588 (@value{GDBP}) @b{delete trace 1 2 3} // remove three tracepoints
7589
7590 (@value{GDBP}) @b{delete trace} // remove all tracepoints
7591 @end smallexample
7592
7593 @noindent
7594 You can abbreviate this command as @code{del tr}.
7595 @end table
7596
7597 @node Enable and Disable Tracepoints
7598 @subsection Enable and Disable Tracepoints
7599
7600 @table @code
7601 @kindex disable tracepoint
7602 @item disable tracepoint @r{[}@var{num}@r{]}
7603 Disable tracepoint @var{num}, or all tracepoints if no argument
7604 @var{num} is given. A disabled tracepoint will have no effect during
7605 the next trace experiment, but it is not forgotten. You can re-enable
7606 a disabled tracepoint using the @code{enable tracepoint} command.
7607
7608 @kindex enable tracepoint
7609 @item enable tracepoint @r{[}@var{num}@r{]}
7610 Enable tracepoint @var{num}, or all tracepoints. The enabled
7611 tracepoints will become effective the next time a trace experiment is
7612 run.
7613 @end table
7614
7615 @node Tracepoint Passcounts
7616 @subsection Tracepoint Passcounts
7617
7618 @table @code
7619 @kindex passcount
7620 @cindex tracepoint pass count
7621 @item passcount @r{[}@var{n} @r{[}@var{num}@r{]]}
7622 Set the @dfn{passcount} of a tracepoint. The passcount is a way to
7623 automatically stop a trace experiment. If a tracepoint's passcount is
7624 @var{n}, then the trace experiment will be automatically stopped on
7625 the @var{n}'th time that tracepoint is hit. If the tracepoint number
7626 @var{num} is not specified, the @code{passcount} command sets the
7627 passcount of the most recently defined tracepoint. If no passcount is
7628 given, the trace experiment will run until stopped explicitly by the
7629 user.
7630
7631 Examples:
7632
7633 @smallexample
7634 (@value{GDBP}) @b{passcount 5 2} // Stop on the 5th execution of
7635 @exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// tracepoint 2}
7636
7637 (@value{GDBP}) @b{passcount 12} // Stop on the 12th execution of the
7638 @exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// most recently defined tracepoint.}
7639 (@value{GDBP}) @b{trace foo}
7640 (@value{GDBP}) @b{pass 3}
7641 (@value{GDBP}) @b{trace bar}
7642 (@value{GDBP}) @b{pass 2}
7643 (@value{GDBP}) @b{trace baz}
7644 (@value{GDBP}) @b{pass 1} // Stop tracing when foo has been
7645 @exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// executed 3 times OR when bar has}
7646 @exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// been executed 2 times}
7647 @exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// OR when baz has been executed 1 time.}
7648 @end smallexample
7649 @end table
7650
7651 @node Tracepoint Actions
7652 @subsection Tracepoint Action Lists
7653
7654 @table @code
7655 @kindex actions
7656 @cindex tracepoint actions
7657 @item actions @r{[}@var{num}@r{]}
7658 This command will prompt for a list of actions to be taken when the
7659 tracepoint is hit. If the tracepoint number @var{num} is not
7660 specified, this command sets the actions for the one that was most
7661 recently defined (so that you can define a tracepoint and then say
7662 @code{actions} without bothering about its number). You specify the
7663 actions themselves on the following lines, one action at a time, and
7664 terminate the actions list with a line containing just @code{end}. So
7665 far, the only defined actions are @code{collect} and
7666 @code{while-stepping}.
7667
7668 @cindex remove actions from a tracepoint
7669 To remove all actions from a tracepoint, type @samp{actions @var{num}}
7670 and follow it immediately with @samp{end}.
7671
7672 @smallexample
7673 (@value{GDBP}) @b{collect @var{data}} // collect some data
7674
7675 (@value{GDBP}) @b{while-stepping 5} // single-step 5 times, collect data
7676
7677 (@value{GDBP}) @b{end} // signals the end of actions.
7678 @end smallexample
7679
7680 In the following example, the action list begins with @code{collect}
7681 commands indicating the things to be collected when the tracepoint is
7682 hit. Then, in order to single-step and collect additional data
7683 following the tracepoint, a @code{while-stepping} command is used,
7684 followed by the list of things to be collected while stepping. The
7685 @code{while-stepping} command is terminated by its own separate
7686 @code{end} command. Lastly, the action list is terminated by an
7687 @code{end} command.
7688
7689 @smallexample
7690 (@value{GDBP}) @b{trace foo}
7691 (@value{GDBP}) @b{actions}
7692 Enter actions for tracepoint 1, one per line:
7693 > collect bar,baz
7694 > collect $regs
7695 > while-stepping 12
7696 > collect $fp, $sp
7697 > end
7698 end
7699 @end smallexample
7700
7701 @kindex collect @r{(tracepoints)}
7702 @item collect @var{expr1}, @var{expr2}, @dots{}
7703 Collect values of the given expressions when the tracepoint is hit.
7704 This command accepts a comma-separated list of any valid expressions.
7705 In addition to global, static, or local variables, the following
7706 special arguments are supported:
7707
7708 @table @code
7709 @item $regs
7710 collect all registers
7711
7712 @item $args
7713 collect all function arguments
7714
7715 @item $locals
7716 collect all local variables.
7717 @end table
7718
7719 You can give several consecutive @code{collect} commands, each one
7720 with a single argument, or one @code{collect} command with several
7721 arguments separated by commas: the effect is the same.
7722
7723 The command @code{info scope} (@pxref{Symbols, info scope}) is
7724 particularly useful for figuring out what data to collect.
7725
7726 @kindex while-stepping @r{(tracepoints)}
7727 @item while-stepping @var{n}
7728 Perform @var{n} single-step traces after the tracepoint, collecting
7729 new data at each step. The @code{while-stepping} command is
7730 followed by the list of what to collect while stepping (followed by
7731 its own @code{end} command):
7732
7733 @smallexample
7734 > while-stepping 12
7735 > collect $regs, myglobal
7736 > end
7737 >
7738 @end smallexample
7739
7740 @noindent
7741 You may abbreviate @code{while-stepping} as @code{ws} or
7742 @code{stepping}.
7743 @end table
7744
7745 @node Listing Tracepoints
7746 @subsection Listing Tracepoints
7747
7748 @table @code
7749 @kindex info tracepoints
7750 @kindex info tp
7751 @cindex information about tracepoints
7752 @item info tracepoints @r{[}@var{num}@r{]}
7753 Display information about the tracepoint @var{num}. If you don't specify
7754 a tracepoint number, displays information about all the tracepoints
7755 defined so far. For each tracepoint, the following information is
7756 shown:
7757
7758 @itemize @bullet
7759 @item
7760 its number
7761 @item
7762 whether it is enabled or disabled
7763 @item
7764 its address
7765 @item
7766 its passcount as given by the @code{passcount @var{n}} command
7767 @item
7768 its step count as given by the @code{while-stepping @var{n}} command
7769 @item
7770 where in the source files is the tracepoint set
7771 @item
7772 its action list as given by the @code{actions} command
7773 @end itemize
7774
7775 @smallexample
7776 (@value{GDBP}) @b{info trace}
7777 Num Enb Address PassC StepC What
7778 1 y 0x002117c4 0 0 <gdb_asm>
7779 2 y 0x0020dc64 0 0 in g_test at g_test.c:1375
7780 3 y 0x0020b1f4 0 0 in get_data at ../foo.c:41
7781 (@value{GDBP})
7782 @end smallexample
7783
7784 @noindent
7785 This command can be abbreviated @code{info tp}.
7786 @end table
7787
7788 @node Starting and Stopping Trace Experiment
7789 @subsection Starting and Stopping Trace Experiment
7790
7791 @table @code
7792 @kindex tstart
7793 @cindex start a new trace experiment
7794 @cindex collected data discarded
7795 @item tstart
7796 This command takes no arguments. It starts the trace experiment, and
7797 begins collecting data. This has the side effect of discarding all
7798 the data collected in the trace buffer during the previous trace
7799 experiment.
7800
7801 @kindex tstop
7802 @cindex stop a running trace experiment
7803 @item tstop
7804 This command takes no arguments. It ends the trace experiment, and
7805 stops collecting data.
7806
7807 @strong{Note}: a trace experiment and data collection may stop
7808 automatically if any tracepoint's passcount is reached
7809 (@pxref{Tracepoint Passcounts}), or if the trace buffer becomes full.
7810
7811 @kindex tstatus
7812 @cindex status of trace data collection
7813 @cindex trace experiment, status of
7814 @item tstatus
7815 This command displays the status of the current trace data
7816 collection.
7817 @end table
7818
7819 Here is an example of the commands we described so far:
7820
7821 @smallexample
7822 (@value{GDBP}) @b{trace gdb_c_test}
7823 (@value{GDBP}) @b{actions}
7824 Enter actions for tracepoint #1, one per line.
7825 > collect $regs,$locals,$args
7826 > while-stepping 11
7827 > collect $regs
7828 > end
7829 > end
7830 (@value{GDBP}) @b{tstart}
7831 [time passes @dots{}]
7832 (@value{GDBP}) @b{tstop}
7833 @end smallexample
7834
7835
7836 @node Analyze Collected Data
7837 @section Using the collected data
7838
7839 After the tracepoint experiment ends, you use @value{GDBN} commands
7840 for examining the trace data. The basic idea is that each tracepoint
7841 collects a trace @dfn{snapshot} every time it is hit and another
7842 snapshot every time it single-steps. All these snapshots are
7843 consecutively numbered from zero and go into a buffer, and you can
7844 examine them later. The way you examine them is to @dfn{focus} on a
7845 specific trace snapshot. When the remote stub is focused on a trace
7846 snapshot, it will respond to all @value{GDBN} requests for memory and
7847 registers by reading from the buffer which belongs to that snapshot,
7848 rather than from @emph{real} memory or registers of the program being
7849 debugged. This means that @strong{all} @value{GDBN} commands
7850 (@code{print}, @code{info registers}, @code{backtrace}, etc.) will
7851 behave as if we were currently debugging the program state as it was
7852 when the tracepoint occurred. Any requests for data that are not in
7853 the buffer will fail.
7854
7855 @menu
7856 * tfind:: How to select a trace snapshot
7857 * tdump:: How to display all data for a snapshot
7858 * save-tracepoints:: How to save tracepoints for a future run
7859 @end menu
7860
7861 @node tfind
7862 @subsection @code{tfind @var{n}}
7863
7864 @kindex tfind
7865 @cindex select trace snapshot
7866 @cindex find trace snapshot
7867 The basic command for selecting a trace snapshot from the buffer is
7868 @code{tfind @var{n}}, which finds trace snapshot number @var{n},
7869 counting from zero. If no argument @var{n} is given, the next
7870 snapshot is selected.
7871
7872 Here are the various forms of using the @code{tfind} command.
7873
7874 @table @code
7875 @item tfind start
7876 Find the first snapshot in the buffer. This is a synonym for
7877 @code{tfind 0} (since 0 is the number of the first snapshot).
7878
7879 @item tfind none
7880 Stop debugging trace snapshots, resume @emph{live} debugging.
7881
7882 @item tfind end
7883 Same as @samp{tfind none}.
7884
7885 @item tfind
7886 No argument means find the next trace snapshot.
7887
7888 @item tfind -
7889 Find the previous trace snapshot before the current one. This permits
7890 retracing earlier steps.
7891
7892 @item tfind tracepoint @var{num}
7893 Find the next snapshot associated with tracepoint @var{num}. Search
7894 proceeds forward from the last examined trace snapshot. If no
7895 argument @var{num} is given, it means find the next snapshot collected
7896 for the same tracepoint as the current snapshot.
7897
7898 @item tfind pc @var{addr}
7899 Find the next snapshot associated with the value @var{addr} of the
7900 program counter. Search proceeds forward from the last examined trace
7901 snapshot. If no argument @var{addr} is given, it means find the next
7902 snapshot with the same value of PC as the current snapshot.
7903
7904 @item tfind outside @var{addr1}, @var{addr2}
7905 Find the next snapshot whose PC is outside the given range of
7906 addresses.
7907
7908 @item tfind range @var{addr1}, @var{addr2}
7909 Find the next snapshot whose PC is between @var{addr1} and
7910 @var{addr2}. @c FIXME: Is the range inclusive or exclusive?
7911
7912 @item tfind line @r{[}@var{file}:@r{]}@var{n}
7913 Find the next snapshot associated with the source line @var{n}. If
7914 the optional argument @var{file} is given, refer to line @var{n} in
7915 that source file. Search proceeds forward from the last examined
7916 trace snapshot. If no argument @var{n} is given, it means find the
7917 next line other than the one currently being examined; thus saying
7918 @code{tfind line} repeatedly can appear to have the same effect as
7919 stepping from line to line in a @emph{live} debugging session.
7920 @end table
7921
7922 The default arguments for the @code{tfind} commands are specifically
7923 designed to make it easy to scan through the trace buffer. For
7924 instance, @code{tfind} with no argument selects the next trace
7925 snapshot, and @code{tfind -} with no argument selects the previous
7926 trace snapshot. So, by giving one @code{tfind} command, and then
7927 simply hitting @key{RET} repeatedly you can examine all the trace
7928 snapshots in order. Or, by saying @code{tfind -} and then hitting
7929 @key{RET} repeatedly you can examine the snapshots in reverse order.
7930 The @code{tfind line} command with no argument selects the snapshot
7931 for the next source line executed. The @code{tfind pc} command with
7932 no argument selects the next snapshot with the same program counter
7933 (PC) as the current frame. The @code{tfind tracepoint} command with
7934 no argument selects the next trace snapshot collected by the same
7935 tracepoint as the current one.
7936
7937 In addition to letting you scan through the trace buffer manually,
7938 these commands make it easy to construct @value{GDBN} scripts that
7939 scan through the trace buffer and print out whatever collected data
7940 you are interested in. Thus, if we want to examine the PC, FP, and SP
7941 registers from each trace frame in the buffer, we can say this:
7942
7943 @smallexample
7944 (@value{GDBP}) @b{tfind start}
7945 (@value{GDBP}) @b{while ($trace_frame != -1)}
7946 > printf "Frame %d, PC = %08X, SP = %08X, FP = %08X\n", \
7947 $trace_frame, $pc, $sp, $fp
7948 > tfind
7949 > end
7950
7951 Frame 0, PC = 0020DC64, SP = 0030BF3C, FP = 0030BF44
7952 Frame 1, PC = 0020DC6C, SP = 0030BF38, FP = 0030BF44
7953 Frame 2, PC = 0020DC70, SP = 0030BF34, FP = 0030BF44
7954 Frame 3, PC = 0020DC74, SP = 0030BF30, FP = 0030BF44
7955 Frame 4, PC = 0020DC78, SP = 0030BF2C, FP = 0030BF44
7956 Frame 5, PC = 0020DC7C, SP = 0030BF28, FP = 0030BF44
7957 Frame 6, PC = 0020DC80, SP = 0030BF24, FP = 0030BF44
7958 Frame 7, PC = 0020DC84, SP = 0030BF20, FP = 0030BF44
7959 Frame 8, PC = 0020DC88, SP = 0030BF1C, FP = 0030BF44
7960 Frame 9, PC = 0020DC8E, SP = 0030BF18, FP = 0030BF44
7961 Frame 10, PC = 00203F6C, SP = 0030BE3C, FP = 0030BF14
7962 @end smallexample
7963
7964 Or, if we want to examine the variable @code{X} at each source line in
7965 the buffer:
7966
7967 @smallexample
7968 (@value{GDBP}) @b{tfind start}
7969 (@value{GDBP}) @b{while ($trace_frame != -1)}
7970 > printf "Frame %d, X == %d\n", $trace_frame, X
7971 > tfind line
7972 > end
7973
7974 Frame 0, X = 1
7975 Frame 7, X = 2
7976 Frame 13, X = 255
7977 @end smallexample
7978
7979 @node tdump
7980 @subsection @code{tdump}
7981 @kindex tdump
7982 @cindex dump all data collected at tracepoint
7983 @cindex tracepoint data, display
7984
7985 This command takes no arguments. It prints all the data collected at
7986 the current trace snapshot.
7987
7988 @smallexample
7989 (@value{GDBP}) @b{trace 444}
7990 (@value{GDBP}) @b{actions}
7991 Enter actions for tracepoint #2, one per line:
7992 > collect $regs, $locals, $args, gdb_long_test
7993 > end
7994
7995 (@value{GDBP}) @b{tstart}
7996
7997 (@value{GDBP}) @b{tfind line 444}
7998 #0 gdb_test (p1=0x11, p2=0x22, p3=0x33, p4=0x44, p5=0x55, p6=0x66)
7999 at gdb_test.c:444
8000 444 printp( "%s: arguments = 0x%X 0x%X 0x%X 0x%X 0x%X 0x%X\n", )
8001
8002 (@value{GDBP}) @b{tdump}
8003 Data collected at tracepoint 2, trace frame 1:
8004 d0 0xc4aa0085 -995491707
8005 d1 0x18 24
8006 d2 0x80 128
8007 d3 0x33 51
8008 d4 0x71aea3d 119204413
8009 d5 0x22 34
8010 d6 0xe0 224
8011 d7 0x380035 3670069
8012 a0 0x19e24a 1696330
8013 a1 0x3000668 50333288
8014 a2 0x100 256
8015 a3 0x322000 3284992
8016 a4 0x3000698 50333336
8017 a5 0x1ad3cc 1758156
8018 fp 0x30bf3c 0x30bf3c
8019 sp 0x30bf34 0x30bf34
8020 ps 0x0 0
8021 pc 0x20b2c8 0x20b2c8
8022 fpcontrol 0x0 0
8023 fpstatus 0x0 0
8024 fpiaddr 0x0 0
8025 p = 0x20e5b4 "gdb-test"
8026 p1 = (void *) 0x11
8027 p2 = (void *) 0x22
8028 p3 = (void *) 0x33
8029 p4 = (void *) 0x44
8030 p5 = (void *) 0x55
8031 p6 = (void *) 0x66
8032 gdb_long_test = 17 '\021'
8033
8034 (@value{GDBP})
8035 @end smallexample
8036
8037 @node save-tracepoints
8038 @subsection @code{save-tracepoints @var{filename}}
8039 @kindex save-tracepoints
8040 @cindex save tracepoints for future sessions
8041
8042 This command saves all current tracepoint definitions together with
8043 their actions and passcounts, into a file @file{@var{filename}}
8044 suitable for use in a later debugging session. To read the saved
8045 tracepoint definitions, use the @code{source} command (@pxref{Command
8046 Files}).
8047
8048 @node Tracepoint Variables
8049 @section Convenience Variables for Tracepoints
8050 @cindex tracepoint variables
8051 @cindex convenience variables for tracepoints
8052
8053 @table @code
8054 @vindex $trace_frame
8055 @item (int) $trace_frame
8056 The current trace snapshot (a.k.a.@: @dfn{frame}) number, or -1 if no
8057 snapshot is selected.
8058
8059 @vindex $tracepoint
8060 @item (int) $tracepoint
8061 The tracepoint for the current trace snapshot.
8062
8063 @vindex $trace_line
8064 @item (int) $trace_line
8065 The line number for the current trace snapshot.
8066
8067 @vindex $trace_file
8068 @item (char []) $trace_file
8069 The source file for the current trace snapshot.
8070
8071 @vindex $trace_func
8072 @item (char []) $trace_func
8073 The name of the function containing @code{$tracepoint}.
8074 @end table
8075
8076 Note: @code{$trace_file} is not suitable for use in @code{printf},
8077 use @code{output} instead.
8078
8079 Here's a simple example of using these convenience variables for
8080 stepping through all the trace snapshots and printing some of their
8081 data.
8082
8083 @smallexample
8084 (@value{GDBP}) @b{tfind start}
8085
8086 (@value{GDBP}) @b{while $trace_frame != -1}
8087 > output $trace_file
8088 > printf ", line %d (tracepoint #%d)\n", $trace_line, $tracepoint
8089 > tfind
8090 > end
8091 @end smallexample
8092
8093 @node Overlays
8094 @chapter Debugging Programs That Use Overlays
8095 @cindex overlays
8096
8097 If your program is too large to fit completely in your target system's
8098 memory, you can sometimes use @dfn{overlays} to work around this
8099 problem. @value{GDBN} provides some support for debugging programs that
8100 use overlays.
8101
8102 @menu
8103 * How Overlays Work:: A general explanation of overlays.
8104 * Overlay Commands:: Managing overlays in @value{GDBN}.
8105 * Automatic Overlay Debugging:: @value{GDBN} can find out which overlays are
8106 mapped by asking the inferior.
8107 * Overlay Sample Program:: A sample program using overlays.
8108 @end menu
8109
8110 @node How Overlays Work
8111 @section How Overlays Work
8112 @cindex mapped overlays
8113 @cindex unmapped overlays
8114 @cindex load address, overlay's
8115 @cindex mapped address
8116 @cindex overlay area
8117
8118 Suppose you have a computer whose instruction address space is only 64
8119 kilobytes long, but which has much more memory which can be accessed by
8120 other means: special instructions, segment registers, or memory
8121 management hardware, for example. Suppose further that you want to
8122 adapt a program which is larger than 64 kilobytes to run on this system.
8123
8124 One solution is to identify modules of your program which are relatively
8125 independent, and need not call each other directly; call these modules
8126 @dfn{overlays}. Separate the overlays from the main program, and place
8127 their machine code in the larger memory. Place your main program in
8128 instruction memory, but leave at least enough space there to hold the
8129 largest overlay as well.
8130
8131 Now, to call a function located in an overlay, you must first copy that
8132 overlay's machine code from the large memory into the space set aside
8133 for it in the instruction memory, and then jump to its entry point
8134 there.
8135
8136 @c NB: In the below the mapped area's size is greater or equal to the
8137 @c size of all overlays. This is intentional to remind the developer
8138 @c that overlays don't necessarily need to be the same size.
8139
8140 @smallexample
8141 @group
8142 Data Instruction Larger
8143 Address Space Address Space Address Space
8144 +-----------+ +-----------+ +-----------+
8145 | | | | | |
8146 +-----------+ +-----------+ +-----------+<-- overlay 1
8147 | program | | main | .----| overlay 1 | load address
8148 | variables | | program | | +-----------+
8149 | and heap | | | | | |
8150 +-----------+ | | | +-----------+<-- overlay 2
8151 | | +-----------+ | | | load address
8152 +-----------+ | | | .-| overlay 2 |
8153 | | | | | |
8154 mapped --->+-----------+ | | +-----------+
8155 address | | | | | |
8156 | overlay | <-' | | |
8157 | area | <---' +-----------+<-- overlay 3
8158 | | <---. | | load address
8159 +-----------+ `--| overlay 3 |
8160 | | | |
8161 +-----------+ | |
8162 +-----------+
8163 | |
8164 +-----------+
8165
8166 @anchor{A code overlay}A code overlay
8167 @end group
8168 @end smallexample
8169
8170 The diagram (@pxref{A code overlay}) shows a system with separate data
8171 and instruction address spaces. To map an overlay, the program copies
8172 its code from the larger address space to the instruction address space.
8173 Since the overlays shown here all use the same mapped address, only one
8174 may be mapped at a time. For a system with a single address space for
8175 data and instructions, the diagram would be similar, except that the
8176 program variables and heap would share an address space with the main
8177 program and the overlay area.
8178
8179 An overlay loaded into instruction memory and ready for use is called a
8180 @dfn{mapped} overlay; its @dfn{mapped address} is its address in the
8181 instruction memory. An overlay not present (or only partially present)
8182 in instruction memory is called @dfn{unmapped}; its @dfn{load address}
8183 is its address in the larger memory. The mapped address is also called
8184 the @dfn{virtual memory address}, or @dfn{VMA}; the load address is also
8185 called the @dfn{load memory address}, or @dfn{LMA}.
8186
8187 Unfortunately, overlays are not a completely transparent way to adapt a
8188 program to limited instruction memory. They introduce a new set of
8189 global constraints you must keep in mind as you design your program:
8190
8191 @itemize @bullet
8192
8193 @item
8194 Before calling or returning to a function in an overlay, your program
8195 must make sure that overlay is actually mapped. Otherwise, the call or
8196 return will transfer control to the right address, but in the wrong
8197 overlay, and your program will probably crash.
8198
8199 @item
8200 If the process of mapping an overlay is expensive on your system, you
8201 will need to choose your overlays carefully to minimize their effect on
8202 your program's performance.
8203
8204 @item
8205 The executable file you load onto your system must contain each
8206 overlay's instructions, appearing at the overlay's load address, not its
8207 mapped address. However, each overlay's instructions must be relocated
8208 and its symbols defined as if the overlay were at its mapped address.
8209 You can use GNU linker scripts to specify different load and relocation
8210 addresses for pieces of your program; see @ref{Overlay Description,,,
8211 ld.info, Using ld: the GNU linker}.
8212
8213 @item
8214 The procedure for loading executable files onto your system must be able
8215 to load their contents into the larger address space as well as the
8216 instruction and data spaces.
8217
8218 @end itemize
8219
8220 The overlay system described above is rather simple, and could be
8221 improved in many ways:
8222
8223 @itemize @bullet
8224
8225 @item
8226 If your system has suitable bank switch registers or memory management
8227 hardware, you could use those facilities to make an overlay's load area
8228 contents simply appear at their mapped address in instruction space.
8229 This would probably be faster than copying the overlay to its mapped
8230 area in the usual way.
8231
8232 @item
8233 If your overlays are small enough, you could set aside more than one
8234 overlay area, and have more than one overlay mapped at a time.
8235
8236 @item
8237 You can use overlays to manage data, as well as instructions. In
8238 general, data overlays are even less transparent to your design than
8239 code overlays: whereas code overlays only require care when you call or
8240 return to functions, data overlays require care every time you access
8241 the data. Also, if you change the contents of a data overlay, you
8242 must copy its contents back out to its load address before you can copy a
8243 different data overlay into the same mapped area.
8244
8245 @end itemize
8246
8247
8248 @node Overlay Commands
8249 @section Overlay Commands
8250
8251 To use @value{GDBN}'s overlay support, each overlay in your program must
8252 correspond to a separate section of the executable file. The section's
8253 virtual memory address and load memory address must be the overlay's
8254 mapped and load addresses. Identifying overlays with sections allows
8255 @value{GDBN} to determine the appropriate address of a function or
8256 variable, depending on whether the overlay is mapped or not.
8257
8258 @value{GDBN}'s overlay commands all start with the word @code{overlay};
8259 you can abbreviate this as @code{ov} or @code{ovly}. The commands are:
8260
8261 @table @code
8262 @item overlay off
8263 @kindex overlay
8264 Disable @value{GDBN}'s overlay support. When overlay support is
8265 disabled, @value{GDBN} assumes that all functions and variables are
8266 always present at their mapped addresses. By default, @value{GDBN}'s
8267 overlay support is disabled.
8268
8269 @item overlay manual
8270 @cindex manual overlay debugging
8271 Enable @dfn{manual} overlay debugging. In this mode, @value{GDBN}
8272 relies on you to tell it which overlays are mapped, and which are not,
8273 using the @code{overlay map-overlay} and @code{overlay unmap-overlay}
8274 commands described below.
8275
8276 @item overlay map-overlay @var{overlay}
8277 @itemx overlay map @var{overlay}
8278 @cindex map an overlay
8279 Tell @value{GDBN} that @var{overlay} is now mapped; @var{overlay} must
8280 be the name of the object file section containing the overlay. When an
8281 overlay is mapped, @value{GDBN} assumes it can find the overlay's
8282 functions and variables at their mapped addresses. @value{GDBN} assumes
8283 that any other overlays whose mapped ranges overlap that of
8284 @var{overlay} are now unmapped.
8285
8286 @item overlay unmap-overlay @var{overlay}
8287 @itemx overlay unmap @var{overlay}
8288 @cindex unmap an overlay
8289 Tell @value{GDBN} that @var{overlay} is no longer mapped; @var{overlay}
8290 must be the name of the object file section containing the overlay.
8291 When an overlay is unmapped, @value{GDBN} assumes it can find the
8292 overlay's functions and variables at their load addresses.
8293
8294 @item overlay auto
8295 Enable @dfn{automatic} overlay debugging. In this mode, @value{GDBN}
8296 consults a data structure the overlay manager maintains in the inferior
8297 to see which overlays are mapped. For details, see @ref{Automatic
8298 Overlay Debugging}.
8299
8300 @item overlay load-target
8301 @itemx overlay load
8302 @cindex reloading the overlay table
8303 Re-read the overlay table from the inferior. Normally, @value{GDBN}
8304 re-reads the table @value{GDBN} automatically each time the inferior
8305 stops, so this command should only be necessary if you have changed the
8306 overlay mapping yourself using @value{GDBN}. This command is only
8307 useful when using automatic overlay debugging.
8308
8309 @item overlay list-overlays
8310 @itemx overlay list
8311 @cindex listing mapped overlays
8312 Display a list of the overlays currently mapped, along with their mapped
8313 addresses, load addresses, and sizes.
8314
8315 @end table
8316
8317 Normally, when @value{GDBN} prints a code address, it includes the name
8318 of the function the address falls in:
8319
8320 @smallexample
8321 (@value{GDBP}) print main
8322 $3 = @{int ()@} 0x11a0 <main>
8323 @end smallexample
8324 @noindent
8325 When overlay debugging is enabled, @value{GDBN} recognizes code in
8326 unmapped overlays, and prints the names of unmapped functions with
8327 asterisks around them. For example, if @code{foo} is a function in an
8328 unmapped overlay, @value{GDBN} prints it this way:
8329
8330 @smallexample
8331 (@value{GDBP}) overlay list
8332 No sections are mapped.
8333 (@value{GDBP}) print foo
8334 $5 = @{int (int)@} 0x100000 <*foo*>
8335 @end smallexample
8336 @noindent
8337 When @code{foo}'s overlay is mapped, @value{GDBN} prints the function's
8338 name normally:
8339
8340 @smallexample
8341 (@value{GDBP}) overlay list
8342 Section .ov.foo.text, loaded at 0x100000 - 0x100034,
8343 mapped at 0x1016 - 0x104a
8344 (@value{GDBP}) print foo
8345 $6 = @{int (int)@} 0x1016 <foo>
8346 @end smallexample
8347
8348 When overlay debugging is enabled, @value{GDBN} can find the correct
8349 address for functions and variables in an overlay, whether or not the
8350 overlay is mapped. This allows most @value{GDBN} commands, like
8351 @code{break} and @code{disassemble}, to work normally, even on unmapped
8352 code. However, @value{GDBN}'s breakpoint support has some limitations:
8353
8354 @itemize @bullet
8355 @item
8356 @cindex breakpoints in overlays
8357 @cindex overlays, setting breakpoints in
8358 You can set breakpoints in functions in unmapped overlays, as long as
8359 @value{GDBN} can write to the overlay at its load address.
8360 @item
8361 @value{GDBN} can not set hardware or simulator-based breakpoints in
8362 unmapped overlays. However, if you set a breakpoint at the end of your
8363 overlay manager (and tell @value{GDBN} which overlays are now mapped, if
8364 you are using manual overlay management), @value{GDBN} will re-set its
8365 breakpoints properly.
8366 @end itemize
8367
8368
8369 @node Automatic Overlay Debugging
8370 @section Automatic Overlay Debugging
8371 @cindex automatic overlay debugging
8372
8373 @value{GDBN} can automatically track which overlays are mapped and which
8374 are not, given some simple co-operation from the overlay manager in the
8375 inferior. If you enable automatic overlay debugging with the
8376 @code{overlay auto} command (@pxref{Overlay Commands}), @value{GDBN}
8377 looks in the inferior's memory for certain variables describing the
8378 current state of the overlays.
8379
8380 Here are the variables your overlay manager must define to support
8381 @value{GDBN}'s automatic overlay debugging:
8382
8383 @table @asis
8384
8385 @item @code{_ovly_table}:
8386 This variable must be an array of the following structures:
8387
8388 @smallexample
8389 struct
8390 @{
8391 /* The overlay's mapped address. */
8392 unsigned long vma;
8393
8394 /* The size of the overlay, in bytes. */
8395 unsigned long size;
8396
8397 /* The overlay's load address. */
8398 unsigned long lma;
8399
8400 /* Non-zero if the overlay is currently mapped;
8401 zero otherwise. */
8402 unsigned long mapped;
8403 @}
8404 @end smallexample
8405
8406 @item @code{_novlys}:
8407 This variable must be a four-byte signed integer, holding the total
8408 number of elements in @code{_ovly_table}.
8409
8410 @end table
8411
8412 To decide whether a particular overlay is mapped or not, @value{GDBN}
8413 looks for an entry in @w{@code{_ovly_table}} whose @code{vma} and
8414 @code{lma} members equal the VMA and LMA of the overlay's section in the
8415 executable file. When @value{GDBN} finds a matching entry, it consults
8416 the entry's @code{mapped} member to determine whether the overlay is
8417 currently mapped.
8418
8419 In addition, your overlay manager may define a function called
8420 @code{_ovly_debug_event}. If this function is defined, @value{GDBN}
8421 will silently set a breakpoint there. If the overlay manager then
8422 calls this function whenever it has changed the overlay table, this
8423 will enable @value{GDBN} to accurately keep track of which overlays
8424 are in program memory, and update any breakpoints that may be set
8425 in overlays. This will allow breakpoints to work even if the
8426 overlays are kept in ROM or other non-writable memory while they
8427 are not being executed.
8428
8429 @node Overlay Sample Program
8430 @section Overlay Sample Program
8431 @cindex overlay example program
8432
8433 When linking a program which uses overlays, you must place the overlays
8434 at their load addresses, while relocating them to run at their mapped
8435 addresses. To do this, you must write a linker script (@pxref{Overlay
8436 Description,,, ld.info, Using ld: the GNU linker}). Unfortunately,
8437 since linker scripts are specific to a particular host system, target
8438 architecture, and target memory layout, this manual cannot provide
8439 portable sample code demonstrating @value{GDBN}'s overlay support.
8440
8441 However, the @value{GDBN} source distribution does contain an overlaid
8442 program, with linker scripts for a few systems, as part of its test
8443 suite. The program consists of the following files from
8444 @file{gdb/testsuite/gdb.base}:
8445
8446 @table @file
8447 @item overlays.c
8448 The main program file.
8449 @item ovlymgr.c
8450 A simple overlay manager, used by @file{overlays.c}.
8451 @item foo.c
8452 @itemx bar.c
8453 @itemx baz.c
8454 @itemx grbx.c
8455 Overlay modules, loaded and used by @file{overlays.c}.
8456 @item d10v.ld
8457 @itemx m32r.ld
8458 Linker scripts for linking the test program on the @code{d10v-elf}
8459 and @code{m32r-elf} targets.
8460 @end table
8461
8462 You can build the test program using the @code{d10v-elf} GCC
8463 cross-compiler like this:
8464
8465 @smallexample
8466 $ d10v-elf-gcc -g -c overlays.c
8467 $ d10v-elf-gcc -g -c ovlymgr.c
8468 $ d10v-elf-gcc -g -c foo.c
8469 $ d10v-elf-gcc -g -c bar.c
8470 $ d10v-elf-gcc -g -c baz.c
8471 $ d10v-elf-gcc -g -c grbx.c
8472 $ d10v-elf-gcc -g overlays.o ovlymgr.o foo.o bar.o \
8473 baz.o grbx.o -Wl,-Td10v.ld -o overlays
8474 @end smallexample
8475
8476 The build process is identical for any other architecture, except that
8477 you must substitute the appropriate compiler and linker script for the
8478 target system for @code{d10v-elf-gcc} and @code{d10v.ld}.
8479
8480
8481 @node Languages
8482 @chapter Using @value{GDBN} with Different Languages
8483 @cindex languages
8484
8485 Although programming languages generally have common aspects, they are
8486 rarely expressed in the same manner. For instance, in ANSI C,
8487 dereferencing a pointer @code{p} is accomplished by @code{*p}, but in
8488 Modula-2, it is accomplished by @code{p^}. Values can also be
8489 represented (and displayed) differently. Hex numbers in C appear as
8490 @samp{0x1ae}, while in Modula-2 they appear as @samp{1AEH}.
8491
8492 @cindex working language
8493 Language-specific information is built into @value{GDBN} for some languages,
8494 allowing you to express operations like the above in your program's
8495 native language, and allowing @value{GDBN} to output values in a manner
8496 consistent with the syntax of your program's native language. The
8497 language you use to build expressions is called the @dfn{working
8498 language}.
8499
8500 @menu
8501 * Setting:: Switching between source languages
8502 * Show:: Displaying the language
8503 * Checks:: Type and range checks
8504 * Supported languages:: Supported languages
8505 * Unsupported languages:: Unsupported languages
8506 @end menu
8507
8508 @node Setting
8509 @section Switching between source languages
8510
8511 There are two ways to control the working language---either have @value{GDBN}
8512 set it automatically, or select it manually yourself. You can use the
8513 @code{set language} command for either purpose. On startup, @value{GDBN}
8514 defaults to setting the language automatically. The working language is
8515 used to determine how expressions you type are interpreted, how values
8516 are printed, etc.
8517
8518 In addition to the working language, every source file that
8519 @value{GDBN} knows about has its own working language. For some object
8520 file formats, the compiler might indicate which language a particular
8521 source file is in. However, most of the time @value{GDBN} infers the
8522 language from the name of the file. The language of a source file
8523 controls whether C@t{++} names are demangled---this way @code{backtrace} can
8524 show each frame appropriately for its own language. There is no way to
8525 set the language of a source file from within @value{GDBN}, but you can
8526 set the language associated with a filename extension. @xref{Show, ,
8527 Displaying the language}.
8528
8529 This is most commonly a problem when you use a program, such
8530 as @code{cfront} or @code{f2c}, that generates C but is written in
8531 another language. In that case, make the
8532 program use @code{#line} directives in its C output; that way
8533 @value{GDBN} will know the correct language of the source code of the original
8534 program, and will display that source code, not the generated C code.
8535
8536 @menu
8537 * Filenames:: Filename extensions and languages.
8538 * Manually:: Setting the working language manually
8539 * Automatically:: Having @value{GDBN} infer the source language
8540 @end menu
8541
8542 @node Filenames
8543 @subsection List of filename extensions and languages
8544
8545 If a source file name ends in one of the following extensions, then
8546 @value{GDBN} infers that its language is the one indicated.
8547
8548 @table @file
8549 @item .ada
8550 @itemx .ads
8551 @itemx .adb
8552 @itemx .a
8553 Ada source file.
8554
8555 @item .c
8556 C source file
8557
8558 @item .C
8559 @itemx .cc
8560 @itemx .cp
8561 @itemx .cpp
8562 @itemx .cxx
8563 @itemx .c++
8564 C@t{++} source file
8565
8566 @item .m
8567 Objective-C source file
8568
8569 @item .f
8570 @itemx .F
8571 Fortran source file
8572
8573 @item .mod
8574 Modula-2 source file
8575
8576 @item .s
8577 @itemx .S
8578 Assembler source file. This actually behaves almost like C, but
8579 @value{GDBN} does not skip over function prologues when stepping.
8580 @end table
8581
8582 In addition, you may set the language associated with a filename
8583 extension. @xref{Show, , Displaying the language}.
8584
8585 @node Manually
8586 @subsection Setting the working language
8587
8588 If you allow @value{GDBN} to set the language automatically,
8589 expressions are interpreted the same way in your debugging session and
8590 your program.
8591
8592 @kindex set language
8593 If you wish, you may set the language manually. To do this, issue the
8594 command @samp{set language @var{lang}}, where @var{lang} is the name of
8595 a language, such as
8596 @code{c} or @code{modula-2}.
8597 For a list of the supported languages, type @samp{set language}.
8598
8599 Setting the language manually prevents @value{GDBN} from updating the working
8600 language automatically. This can lead to confusion if you try
8601 to debug a program when the working language is not the same as the
8602 source language, when an expression is acceptable to both
8603 languages---but means different things. For instance, if the current
8604 source file were written in C, and @value{GDBN} was parsing Modula-2, a
8605 command such as:
8606
8607 @smallexample
8608 print a = b + c
8609 @end smallexample
8610
8611 @noindent
8612 might not have the effect you intended. In C, this means to add
8613 @code{b} and @code{c} and place the result in @code{a}. The result
8614 printed would be the value of @code{a}. In Modula-2, this means to compare
8615 @code{a} to the result of @code{b+c}, yielding a @code{BOOLEAN} value.
8616
8617 @node Automatically
8618 @subsection Having @value{GDBN} infer the source language
8619
8620 To have @value{GDBN} set the working language automatically, use
8621 @samp{set language local} or @samp{set language auto}. @value{GDBN}
8622 then infers the working language. That is, when your program stops in a
8623 frame (usually by encountering a breakpoint), @value{GDBN} sets the
8624 working language to the language recorded for the function in that
8625 frame. If the language for a frame is unknown (that is, if the function
8626 or block corresponding to the frame was defined in a source file that
8627 does not have a recognized extension), the current working language is
8628 not changed, and @value{GDBN} issues a warning.
8629
8630 This may not seem necessary for most programs, which are written
8631 entirely in one source language. However, program modules and libraries
8632 written in one source language can be used by a main program written in
8633 a different source language. Using @samp{set language auto} in this
8634 case frees you from having to set the working language manually.
8635
8636 @node Show
8637 @section Displaying the language
8638
8639 The following commands help you find out which language is the
8640 working language, and also what language source files were written in.
8641
8642 @table @code
8643 @item show language
8644 @kindex show language
8645 Display the current working language. This is the
8646 language you can use with commands such as @code{print} to
8647 build and compute expressions that may involve variables in your program.
8648
8649 @item info frame
8650 @kindex info frame@r{, show the source language}
8651 Display the source language for this frame. This language becomes the
8652 working language if you use an identifier from this frame.
8653 @xref{Frame Info, ,Information about a frame}, to identify the other
8654 information listed here.
8655
8656 @item info source
8657 @kindex info source@r{, show the source language}
8658 Display the source language of this source file.
8659 @xref{Symbols, ,Examining the Symbol Table}, to identify the other
8660 information listed here.
8661 @end table
8662
8663 In unusual circumstances, you may have source files with extensions
8664 not in the standard list. You can then set the extension associated
8665 with a language explicitly:
8666
8667 @table @code
8668 @item set extension-language @var{ext} @var{language}
8669 @kindex set extension-language
8670 Tell @value{GDBN} that source files with extension @var{ext} are to be
8671 assumed as written in the source language @var{language}.
8672
8673 @item info extensions
8674 @kindex info extensions
8675 List all the filename extensions and the associated languages.
8676 @end table
8677
8678 @node Checks
8679 @section Type and range checking
8680
8681 @quotation
8682 @emph{Warning:} In this release, the @value{GDBN} commands for type and range
8683 checking are included, but they do not yet have any effect. This
8684 section documents the intended facilities.
8685 @end quotation
8686 @c FIXME remove warning when type/range code added
8687
8688 Some languages are designed to guard you against making seemingly common
8689 errors through a series of compile- and run-time checks. These include
8690 checking the type of arguments to functions and operators, and making
8691 sure mathematical overflows are caught at run time. Checks such as
8692 these help to ensure a program's correctness once it has been compiled
8693 by eliminating type mismatches, and providing active checks for range
8694 errors when your program is running.
8695
8696 @value{GDBN} can check for conditions like the above if you wish.
8697 Although @value{GDBN} does not check the statements in your program,
8698 it can check expressions entered directly into @value{GDBN} for
8699 evaluation via the @code{print} command, for example. As with the
8700 working language, @value{GDBN} can also decide whether or not to check
8701 automatically based on your program's source language.
8702 @xref{Supported languages, ,Supported languages}, for the default
8703 settings of supported languages.
8704
8705 @menu
8706 * Type Checking:: An overview of type checking
8707 * Range Checking:: An overview of range checking
8708 @end menu
8709
8710 @cindex type checking
8711 @cindex checks, type
8712 @node Type Checking
8713 @subsection An overview of type checking
8714
8715 Some languages, such as Modula-2, are strongly typed, meaning that the
8716 arguments to operators and functions have to be of the correct type,
8717 otherwise an error occurs. These checks prevent type mismatch
8718 errors from ever causing any run-time problems. For example,
8719
8720 @smallexample
8721 1 + 2 @result{} 3
8722 @exdent but
8723 @error{} 1 + 2.3
8724 @end smallexample
8725
8726 The second example fails because the @code{CARDINAL} 1 is not
8727 type-compatible with the @code{REAL} 2.3.
8728
8729 For the expressions you use in @value{GDBN} commands, you can tell the
8730 @value{GDBN} type checker to skip checking;
8731 to treat any mismatches as errors and abandon the expression;
8732 or to only issue warnings when type mismatches occur,
8733 but evaluate the expression anyway. When you choose the last of
8734 these, @value{GDBN} evaluates expressions like the second example above, but
8735 also issues a warning.
8736
8737 Even if you turn type checking off, there may be other reasons
8738 related to type that prevent @value{GDBN} from evaluating an expression.
8739 For instance, @value{GDBN} does not know how to add an @code{int} and
8740 a @code{struct foo}. These particular type errors have nothing to do
8741 with the language in use, and usually arise from expressions, such as
8742 the one described above, which make little sense to evaluate anyway.
8743
8744 Each language defines to what degree it is strict about type. For
8745 instance, both Modula-2 and C require the arguments to arithmetical
8746 operators to be numbers. In C, enumerated types and pointers can be
8747 represented as numbers, so that they are valid arguments to mathematical
8748 operators. @xref{Supported languages, ,Supported languages}, for further
8749 details on specific languages.
8750
8751 @value{GDBN} provides some additional commands for controlling the type checker:
8752
8753 @kindex set check type
8754 @kindex show check type
8755 @table @code
8756 @item set check type auto
8757 Set type checking on or off based on the current working language.
8758 @xref{Supported languages, ,Supported languages}, for the default settings for
8759 each language.
8760
8761 @item set check type on
8762 @itemx set check type off
8763 Set type checking on or off, overriding the default setting for the
8764 current working language. Issue a warning if the setting does not
8765 match the language default. If any type mismatches occur in
8766 evaluating an expression while type checking is on, @value{GDBN} prints a
8767 message and aborts evaluation of the expression.
8768
8769 @item set check type warn
8770 Cause the type checker to issue warnings, but to always attempt to
8771 evaluate the expression. Evaluating the expression may still
8772 be impossible for other reasons. For example, @value{GDBN} cannot add
8773 numbers and structures.
8774
8775 @item show type
8776 Show the current setting of the type checker, and whether or not @value{GDBN}
8777 is setting it automatically.
8778 @end table
8779
8780 @cindex range checking
8781 @cindex checks, range
8782 @node Range Checking
8783 @subsection An overview of range checking
8784
8785 In some languages (such as Modula-2), it is an error to exceed the
8786 bounds of a type; this is enforced with run-time checks. Such range
8787 checking is meant to ensure program correctness by making sure
8788 computations do not overflow, or indices on an array element access do
8789 not exceed the bounds of the array.
8790
8791 For expressions you use in @value{GDBN} commands, you can tell
8792 @value{GDBN} to treat range errors in one of three ways: ignore them,
8793 always treat them as errors and abandon the expression, or issue
8794 warnings but evaluate the expression anyway.
8795
8796 A range error can result from numerical overflow, from exceeding an
8797 array index bound, or when you type a constant that is not a member
8798 of any type. Some languages, however, do not treat overflows as an
8799 error. In many implementations of C, mathematical overflow causes the
8800 result to ``wrap around'' to lower values---for example, if @var{m} is
8801 the largest integer value, and @var{s} is the smallest, then
8802
8803 @smallexample
8804 @var{m} + 1 @result{} @var{s}
8805 @end smallexample
8806
8807 This, too, is specific to individual languages, and in some cases
8808 specific to individual compilers or machines. @xref{Supported languages, ,
8809 Supported languages}, for further details on specific languages.
8810
8811 @value{GDBN} provides some additional commands for controlling the range checker:
8812
8813 @kindex set check range
8814 @kindex show check range
8815 @table @code
8816 @item set check range auto
8817 Set range checking on or off based on the current working language.
8818 @xref{Supported languages, ,Supported languages}, for the default settings for
8819 each language.
8820
8821 @item set check range on
8822 @itemx set check range off
8823 Set range checking on or off, overriding the default setting for the
8824 current working language. A warning is issued if the setting does not
8825 match the language default. If a range error occurs and range checking is on,
8826 then a message is printed and evaluation of the expression is aborted.
8827
8828 @item set check range warn
8829 Output messages when the @value{GDBN} range checker detects a range error,
8830 but attempt to evaluate the expression anyway. Evaluating the
8831 expression may still be impossible for other reasons, such as accessing
8832 memory that the process does not own (a typical example from many Unix
8833 systems).
8834
8835 @item show range
8836 Show the current setting of the range checker, and whether or not it is
8837 being set automatically by @value{GDBN}.
8838 @end table
8839
8840 @node Supported languages
8841 @section Supported languages
8842
8843 @value{GDBN} supports C, C@t{++}, Objective-C, Fortran, Java, Pascal,
8844 assembly, Modula-2, and Ada.
8845 @c This is false ...
8846 Some @value{GDBN} features may be used in expressions regardless of the
8847 language you use: the @value{GDBN} @code{@@} and @code{::} operators,
8848 and the @samp{@{type@}addr} construct (@pxref{Expressions,
8849 ,Expressions}) can be used with the constructs of any supported
8850 language.
8851
8852 The following sections detail to what degree each source language is
8853 supported by @value{GDBN}. These sections are not meant to be language
8854 tutorials or references, but serve only as a reference guide to what the
8855 @value{GDBN} expression parser accepts, and what input and output
8856 formats should look like for different languages. There are many good
8857 books written on each of these languages; please look to these for a
8858 language reference or tutorial.
8859
8860 @menu
8861 * C:: C and C@t{++}
8862 * Objective-C:: Objective-C
8863 * Fortran:: Fortran
8864 * Pascal:: Pascal
8865 * Modula-2:: Modula-2
8866 * Ada:: Ada
8867 @end menu
8868
8869 @node C
8870 @subsection C and C@t{++}
8871
8872 @cindex C and C@t{++}
8873 @cindex expressions in C or C@t{++}
8874
8875 Since C and C@t{++} are so closely related, many features of @value{GDBN} apply
8876 to both languages. Whenever this is the case, we discuss those languages
8877 together.
8878
8879 @cindex C@t{++}
8880 @cindex @code{g++}, @sc{gnu} C@t{++} compiler
8881 @cindex @sc{gnu} C@t{++}
8882 The C@t{++} debugging facilities are jointly implemented by the C@t{++}
8883 compiler and @value{GDBN}. Therefore, to debug your C@t{++} code
8884 effectively, you must compile your C@t{++} programs with a supported
8885 C@t{++} compiler, such as @sc{gnu} @code{g++}, or the HP ANSI C@t{++}
8886 compiler (@code{aCC}).
8887
8888 For best results when using @sc{gnu} C@t{++}, use the DWARF 2 debugging
8889 format; if it doesn't work on your system, try the stabs+ debugging
8890 format. You can select those formats explicitly with the @code{g++}
8891 command-line options @option{-gdwarf-2} and @option{-gstabs+}.
8892 @xref{Debugging Options,,Options for Debugging Your Program or @sc{gnu}
8893 CC, gcc.info, Using @sc{gnu} CC}.
8894
8895 @menu
8896 * C Operators:: C and C@t{++} operators
8897 * C Constants:: C and C@t{++} constants
8898 * C plus plus expressions:: C@t{++} expressions
8899 * C Defaults:: Default settings for C and C@t{++}
8900 * C Checks:: C and C@t{++} type and range checks
8901 * Debugging C:: @value{GDBN} and C
8902 * Debugging C plus plus:: @value{GDBN} features for C@t{++}
8903 @end menu
8904
8905 @node C Operators
8906 @subsubsection C and C@t{++} operators
8907
8908 @cindex C and C@t{++} operators
8909
8910 Operators must be defined on values of specific types. For instance,
8911 @code{+} is defined on numbers, but not on structures. Operators are
8912 often defined on groups of types.
8913
8914 For the purposes of C and C@t{++}, the following definitions hold:
8915
8916 @itemize @bullet
8917
8918 @item
8919 @emph{Integral types} include @code{int} with any of its storage-class
8920 specifiers; @code{char}; @code{enum}; and, for C@t{++}, @code{bool}.
8921
8922 @item
8923 @emph{Floating-point types} include @code{float}, @code{double}, and
8924 @code{long double} (if supported by the target platform).
8925
8926 @item
8927 @emph{Pointer types} include all types defined as @code{(@var{type} *)}.
8928
8929 @item
8930 @emph{Scalar types} include all of the above.
8931
8932 @end itemize
8933
8934 @noindent
8935 The following operators are supported. They are listed here
8936 in order of increasing precedence:
8937
8938 @table @code
8939 @item ,
8940 The comma or sequencing operator. Expressions in a comma-separated list
8941 are evaluated from left to right, with the result of the entire
8942 expression being the last expression evaluated.
8943
8944 @item =
8945 Assignment. The value of an assignment expression is the value
8946 assigned. Defined on scalar types.
8947
8948 @item @var{op}=
8949 Used in an expression of the form @w{@code{@var{a} @var{op}= @var{b}}},
8950 and translated to @w{@code{@var{a} = @var{a op b}}}.
8951 @w{@code{@var{op}=}} and @code{=} have the same precedence.
8952 @var{op} is any one of the operators @code{|}, @code{^}, @code{&},
8953 @code{<<}, @code{>>}, @code{+}, @code{-}, @code{*}, @code{/}, @code{%}.
8954
8955 @item ?:
8956 The ternary operator. @code{@var{a} ? @var{b} : @var{c}} can be thought
8957 of as: if @var{a} then @var{b} else @var{c}. @var{a} should be of an
8958 integral type.
8959
8960 @item ||
8961 Logical @sc{or}. Defined on integral types.
8962
8963 @item &&
8964 Logical @sc{and}. Defined on integral types.
8965
8966 @item |
8967 Bitwise @sc{or}. Defined on integral types.
8968
8969 @item ^
8970 Bitwise exclusive-@sc{or}. Defined on integral types.
8971
8972 @item &
8973 Bitwise @sc{and}. Defined on integral types.
8974
8975 @item ==@r{, }!=
8976 Equality and inequality. Defined on scalar types. The value of these
8977 expressions is 0 for false and non-zero for true.
8978
8979 @item <@r{, }>@r{, }<=@r{, }>=
8980 Less than, greater than, less than or equal, greater than or equal.
8981 Defined on scalar types. The value of these expressions is 0 for false
8982 and non-zero for true.
8983
8984 @item <<@r{, }>>
8985 left shift, and right shift. Defined on integral types.
8986
8987 @item @@
8988 The @value{GDBN} ``artificial array'' operator (@pxref{Expressions, ,Expressions}).
8989
8990 @item +@r{, }-
8991 Addition and subtraction. Defined on integral types, floating-point types and
8992 pointer types.
8993
8994 @item *@r{, }/@r{, }%
8995 Multiplication, division, and modulus. Multiplication and division are
8996 defined on integral and floating-point types. Modulus is defined on
8997 integral types.
8998
8999 @item ++@r{, }--
9000 Increment and decrement. When appearing before a variable, the
9001 operation is performed before the variable is used in an expression;
9002 when appearing after it, the variable's value is used before the
9003 operation takes place.
9004
9005 @item *
9006 Pointer dereferencing. Defined on pointer types. Same precedence as
9007 @code{++}.
9008
9009 @item &
9010 Address operator. Defined on variables. Same precedence as @code{++}.
9011
9012 For debugging C@t{++}, @value{GDBN} implements a use of @samp{&} beyond what is
9013 allowed in the C@t{++} language itself: you can use @samp{&(&@var{ref})}
9014 (or, if you prefer, simply @samp{&&@var{ref}}) to examine the address
9015 where a C@t{++} reference variable (declared with @samp{&@var{ref}}) is
9016 stored.
9017
9018 @item -
9019 Negative. Defined on integral and floating-point types. Same
9020 precedence as @code{++}.
9021
9022 @item !
9023 Logical negation. Defined on integral types. Same precedence as
9024 @code{++}.
9025
9026 @item ~
9027 Bitwise complement operator. Defined on integral types. Same precedence as
9028 @code{++}.
9029
9030
9031 @item .@r{, }->
9032 Structure member, and pointer-to-structure member. For convenience,
9033 @value{GDBN} regards the two as equivalent, choosing whether to dereference a
9034 pointer based on the stored type information.
9035 Defined on @code{struct} and @code{union} data.
9036
9037 @item .*@r{, }->*
9038 Dereferences of pointers to members.
9039
9040 @item []
9041 Array indexing. @code{@var{a}[@var{i}]} is defined as
9042 @code{*(@var{a}+@var{i})}. Same precedence as @code{->}.
9043
9044 @item ()
9045 Function parameter list. Same precedence as @code{->}.
9046
9047 @item ::
9048 C@t{++} scope resolution operator. Defined on @code{struct}, @code{union},
9049 and @code{class} types.
9050
9051 @item ::
9052 Doubled colons also represent the @value{GDBN} scope operator
9053 (@pxref{Expressions, ,Expressions}). Same precedence as @code{::},
9054 above.
9055 @end table
9056
9057 If an operator is redefined in the user code, @value{GDBN} usually
9058 attempts to invoke the redefined version instead of using the operator's
9059 predefined meaning.
9060
9061 @menu
9062 * C Constants::
9063 @end menu
9064
9065 @node C Constants
9066 @subsubsection C and C@t{++} constants
9067
9068 @cindex C and C@t{++} constants
9069
9070 @value{GDBN} allows you to express the constants of C and C@t{++} in the
9071 following ways:
9072
9073 @itemize @bullet
9074 @item
9075 Integer constants are a sequence of digits. Octal constants are
9076 specified by a leading @samp{0} (i.e.@: zero), and hexadecimal constants
9077 by a leading @samp{0x} or @samp{0X}. Constants may also end with a letter
9078 @samp{l}, specifying that the constant should be treated as a
9079 @code{long} value.
9080
9081 @item
9082 Floating point constants are a sequence of digits, followed by a decimal
9083 point, followed by a sequence of digits, and optionally followed by an
9084 exponent. An exponent is of the form:
9085 @samp{@w{e@r{[[}+@r{]|}-@r{]}@var{nnn}}}, where @var{nnn} is another
9086 sequence of digits. The @samp{+} is optional for positive exponents.
9087 A floating-point constant may also end with a letter @samp{f} or
9088 @samp{F}, specifying that the constant should be treated as being of
9089 the @code{float} (as opposed to the default @code{double}) type; or with
9090 a letter @samp{l} or @samp{L}, which specifies a @code{long double}
9091 constant.
9092
9093 @item
9094 Enumerated constants consist of enumerated identifiers, or their
9095 integral equivalents.
9096
9097 @item
9098 Character constants are a single character surrounded by single quotes
9099 (@code{'}), or a number---the ordinal value of the corresponding character
9100 (usually its @sc{ascii} value). Within quotes, the single character may
9101 be represented by a letter or by @dfn{escape sequences}, which are of
9102 the form @samp{\@var{nnn}}, where @var{nnn} is the octal representation
9103 of the character's ordinal value; or of the form @samp{\@var{x}}, where
9104 @samp{@var{x}} is a predefined special character---for example,
9105 @samp{\n} for newline.
9106
9107 @item
9108 String constants are a sequence of character constants surrounded by
9109 double quotes (@code{"}). Any valid character constant (as described
9110 above) may appear. Double quotes within the string must be preceded by
9111 a backslash, so for instance @samp{"a\"b'c"} is a string of five
9112 characters.
9113
9114 @item
9115 Pointer constants are an integral value. You can also write pointers
9116 to constants using the C operator @samp{&}.
9117
9118 @item
9119 Array constants are comma-separated lists surrounded by braces @samp{@{}
9120 and @samp{@}}; for example, @samp{@{1,2,3@}} is a three-element array of
9121 integers, @samp{@{@{1,2@}, @{3,4@}, @{5,6@}@}} is a three-by-two array,
9122 and @samp{@{&"hi", &"there", &"fred"@}} is a three-element array of pointers.
9123 @end itemize
9124
9125 @menu
9126 * C plus plus expressions::
9127 * C Defaults::
9128 * C Checks::
9129
9130 * Debugging C::
9131 @end menu
9132
9133 @node C plus plus expressions
9134 @subsubsection C@t{++} expressions
9135
9136 @cindex expressions in C@t{++}
9137 @value{GDBN} expression handling can interpret most C@t{++} expressions.
9138
9139 @cindex debugging C@t{++} programs
9140 @cindex C@t{++} compilers
9141 @cindex debug formats and C@t{++}
9142 @cindex @value{NGCC} and C@t{++}
9143 @quotation
9144 @emph{Warning:} @value{GDBN} can only debug C@t{++} code if you use the
9145 proper compiler and the proper debug format. Currently, @value{GDBN}
9146 works best when debugging C@t{++} code that is compiled with
9147 @value{NGCC} 2.95.3 or with @value{NGCC} 3.1 or newer, using the options
9148 @option{-gdwarf-2} or @option{-gstabs+}. DWARF 2 is preferred over
9149 stabs+. Most configurations of @value{NGCC} emit either DWARF 2 or
9150 stabs+ as their default debug format, so you usually don't need to
9151 specify a debug format explicitly. Other compilers and/or debug formats
9152 are likely to work badly or not at all when using @value{GDBN} to debug
9153 C@t{++} code.
9154 @end quotation
9155
9156 @enumerate
9157
9158 @cindex member functions
9159 @item
9160 Member function calls are allowed; you can use expressions like
9161
9162 @smallexample
9163 count = aml->GetOriginal(x, y)
9164 @end smallexample
9165
9166 @vindex this@r{, inside C@t{++} member functions}
9167 @cindex namespace in C@t{++}
9168 @item
9169 While a member function is active (in the selected stack frame), your
9170 expressions have the same namespace available as the member function;
9171 that is, @value{GDBN} allows implicit references to the class instance
9172 pointer @code{this} following the same rules as C@t{++}.
9173
9174 @cindex call overloaded functions
9175 @cindex overloaded functions, calling
9176 @cindex type conversions in C@t{++}
9177 @item
9178 You can call overloaded functions; @value{GDBN} resolves the function
9179 call to the right definition, with some restrictions. @value{GDBN} does not
9180 perform overload resolution involving user-defined type conversions,
9181 calls to constructors, or instantiations of templates that do not exist
9182 in the program. It also cannot handle ellipsis argument lists or
9183 default arguments.
9184
9185 It does perform integral conversions and promotions, floating-point
9186 promotions, arithmetic conversions, pointer conversions, conversions of
9187 class objects to base classes, and standard conversions such as those of
9188 functions or arrays to pointers; it requires an exact match on the
9189 number of function arguments.
9190
9191 Overload resolution is always performed, unless you have specified
9192 @code{set overload-resolution off}. @xref{Debugging C plus plus,
9193 ,@value{GDBN} features for C@t{++}}.
9194
9195 You must specify @code{set overload-resolution off} in order to use an
9196 explicit function signature to call an overloaded function, as in
9197 @smallexample
9198 p 'foo(char,int)'('x', 13)
9199 @end smallexample
9200
9201 The @value{GDBN} command-completion facility can simplify this;
9202 see @ref{Completion, ,Command completion}.
9203
9204 @cindex reference declarations
9205 @item
9206 @value{GDBN} understands variables declared as C@t{++} references; you can use
9207 them in expressions just as you do in C@t{++} source---they are automatically
9208 dereferenced.
9209
9210 In the parameter list shown when @value{GDBN} displays a frame, the values of
9211 reference variables are not displayed (unlike other variables); this
9212 avoids clutter, since references are often used for large structures.
9213 The @emph{address} of a reference variable is always shown, unless
9214 you have specified @samp{set print address off}.
9215
9216 @item
9217 @value{GDBN} supports the C@t{++} name resolution operator @code{::}---your
9218 expressions can use it just as expressions in your program do. Since
9219 one scope may be defined in another, you can use @code{::} repeatedly if
9220 necessary, for example in an expression like
9221 @samp{@var{scope1}::@var{scope2}::@var{name}}. @value{GDBN} also allows
9222 resolving name scope by reference to source files, in both C and C@t{++}
9223 debugging (@pxref{Variables, ,Program variables}).
9224 @end enumerate
9225
9226 In addition, when used with HP's C@t{++} compiler, @value{GDBN} supports
9227 calling virtual functions correctly, printing out virtual bases of
9228 objects, calling functions in a base subobject, casting objects, and
9229 invoking user-defined operators.
9230
9231 @node C Defaults
9232 @subsubsection C and C@t{++} defaults
9233
9234 @cindex C and C@t{++} defaults
9235
9236 If you allow @value{GDBN} to set type and range checking automatically, they
9237 both default to @code{off} whenever the working language changes to
9238 C or C@t{++}. This happens regardless of whether you or @value{GDBN}
9239 selects the working language.
9240
9241 If you allow @value{GDBN} to set the language automatically, it
9242 recognizes source files whose names end with @file{.c}, @file{.C}, or
9243 @file{.cc}, etc, and when @value{GDBN} enters code compiled from one of
9244 these files, it sets the working language to C or C@t{++}.
9245 @xref{Automatically, ,Having @value{GDBN} infer the source language},
9246 for further details.
9247
9248 @c Type checking is (a) primarily motivated by Modula-2, and (b)
9249 @c unimplemented. If (b) changes, it might make sense to let this node
9250 @c appear even if Mod-2 does not, but meanwhile ignore it. roland 16jul93.
9251
9252 @node C Checks
9253 @subsubsection C and C@t{++} type and range checks
9254
9255 @cindex C and C@t{++} checks
9256
9257 By default, when @value{GDBN} parses C or C@t{++} expressions, type checking
9258 is not used. However, if you turn type checking on, @value{GDBN}
9259 considers two variables type equivalent if:
9260
9261 @itemize @bullet
9262 @item
9263 The two variables are structured and have the same structure, union, or
9264 enumerated tag.
9265
9266 @item
9267 The two variables have the same type name, or types that have been
9268 declared equivalent through @code{typedef}.
9269
9270 @ignore
9271 @c leaving this out because neither J Gilmore nor R Pesch understand it.
9272 @c FIXME--beers?
9273 @item
9274 The two @code{struct}, @code{union}, or @code{enum} variables are
9275 declared in the same declaration. (Note: this may not be true for all C
9276 compilers.)
9277 @end ignore
9278 @end itemize
9279
9280 Range checking, if turned on, is done on mathematical operations. Array
9281 indices are not checked, since they are often used to index a pointer
9282 that is not itself an array.
9283
9284 @node Debugging C
9285 @subsubsection @value{GDBN} and C
9286
9287 The @code{set print union} and @code{show print union} commands apply to
9288 the @code{union} type. When set to @samp{on}, any @code{union} that is
9289 inside a @code{struct} or @code{class} is also printed. Otherwise, it
9290 appears as @samp{@{...@}}.
9291
9292 The @code{@@} operator aids in the debugging of dynamic arrays, formed
9293 with pointers and a memory allocation function. @xref{Expressions,
9294 ,Expressions}.
9295
9296 @menu
9297 * Debugging C plus plus::
9298 @end menu
9299
9300 @node Debugging C plus plus
9301 @subsubsection @value{GDBN} features for C@t{++}
9302
9303 @cindex commands for C@t{++}
9304
9305 Some @value{GDBN} commands are particularly useful with C@t{++}, and some are
9306 designed specifically for use with C@t{++}. Here is a summary:
9307
9308 @table @code
9309 @cindex break in overloaded functions
9310 @item @r{breakpoint menus}
9311 When you want a breakpoint in a function whose name is overloaded,
9312 @value{GDBN} breakpoint menus help you specify which function definition
9313 you want. @xref{Breakpoint Menus,,Breakpoint menus}.
9314
9315 @cindex overloading in C@t{++}
9316 @item rbreak @var{regex}
9317 Setting breakpoints using regular expressions is helpful for setting
9318 breakpoints on overloaded functions that are not members of any special
9319 classes.
9320 @xref{Set Breaks, ,Setting breakpoints}.
9321
9322 @cindex C@t{++} exception handling
9323 @item catch throw
9324 @itemx catch catch
9325 Debug C@t{++} exception handling using these commands. @xref{Set
9326 Catchpoints, , Setting catchpoints}.
9327
9328 @cindex inheritance
9329 @item ptype @var{typename}
9330 Print inheritance relationships as well as other information for type
9331 @var{typename}.
9332 @xref{Symbols, ,Examining the Symbol Table}.
9333
9334 @cindex C@t{++} symbol display
9335 @item set print demangle
9336 @itemx show print demangle
9337 @itemx set print asm-demangle
9338 @itemx show print asm-demangle
9339 Control whether C@t{++} symbols display in their source form, both when
9340 displaying code as C@t{++} source and when displaying disassemblies.
9341 @xref{Print Settings, ,Print settings}.
9342
9343 @item set print object
9344 @itemx show print object
9345 Choose whether to print derived (actual) or declared types of objects.
9346 @xref{Print Settings, ,Print settings}.
9347
9348 @item set print vtbl
9349 @itemx show print vtbl
9350 Control the format for printing virtual function tables.
9351 @xref{Print Settings, ,Print settings}.
9352 (The @code{vtbl} commands do not work on programs compiled with the HP
9353 ANSI C@t{++} compiler (@code{aCC}).)
9354
9355 @kindex set overload-resolution
9356 @cindex overloaded functions, overload resolution
9357 @item set overload-resolution on
9358 Enable overload resolution for C@t{++} expression evaluation. The default
9359 is on. For overloaded functions, @value{GDBN} evaluates the arguments
9360 and searches for a function whose signature matches the argument types,
9361 using the standard C@t{++} conversion rules (see @ref{C plus plus expressions, ,C@t{++}
9362 expressions}, for details). If it cannot find a match, it emits a
9363 message.
9364
9365 @item set overload-resolution off
9366 Disable overload resolution for C@t{++} expression evaluation. For
9367 overloaded functions that are not class member functions, @value{GDBN}
9368 chooses the first function of the specified name that it finds in the
9369 symbol table, whether or not its arguments are of the correct type. For
9370 overloaded functions that are class member functions, @value{GDBN}
9371 searches for a function whose signature @emph{exactly} matches the
9372 argument types.
9373
9374 @kindex show overload-resolution
9375 @item show overload-resolution
9376 Show the current setting of overload resolution.
9377
9378 @item @r{Overloaded symbol names}
9379 You can specify a particular definition of an overloaded symbol, using
9380 the same notation that is used to declare such symbols in C@t{++}: type
9381 @code{@var{symbol}(@var{types})} rather than just @var{symbol}. You can
9382 also use the @value{GDBN} command-line word completion facilities to list the
9383 available choices, or to finish the type list for you.
9384 @xref{Completion,, Command completion}, for details on how to do this.
9385 @end table
9386
9387 @node Objective-C
9388 @subsection Objective-C
9389
9390 @cindex Objective-C
9391 This section provides information about some commands and command
9392 options that are useful for debugging Objective-C code. See also
9393 @ref{Symbols, info classes}, and @ref{Symbols, info selectors}, for a
9394 few more commands specific to Objective-C support.
9395
9396 @menu
9397 * Method Names in Commands::
9398 * The Print Command with Objective-C::
9399 @end menu
9400
9401 @node Method Names in Commands, The Print Command with Objective-C, Objective-C, Objective-C
9402 @subsubsection Method Names in Commands
9403
9404 The following commands have been extended to accept Objective-C method
9405 names as line specifications:
9406
9407 @kindex clear@r{, and Objective-C}
9408 @kindex break@r{, and Objective-C}
9409 @kindex info line@r{, and Objective-C}
9410 @kindex jump@r{, and Objective-C}
9411 @kindex list@r{, and Objective-C}
9412 @itemize
9413 @item @code{clear}
9414 @item @code{break}
9415 @item @code{info line}
9416 @item @code{jump}
9417 @item @code{list}
9418 @end itemize
9419
9420 A fully qualified Objective-C method name is specified as
9421
9422 @smallexample
9423 -[@var{Class} @var{methodName}]
9424 @end smallexample
9425
9426 where the minus sign is used to indicate an instance method and a
9427 plus sign (not shown) is used to indicate a class method. The class
9428 name @var{Class} and method name @var{methodName} are enclosed in
9429 brackets, similar to the way messages are specified in Objective-C
9430 source code. For example, to set a breakpoint at the @code{create}
9431 instance method of class @code{Fruit} in the program currently being
9432 debugged, enter:
9433
9434 @smallexample
9435 break -[Fruit create]
9436 @end smallexample
9437
9438 To list ten program lines around the @code{initialize} class method,
9439 enter:
9440
9441 @smallexample
9442 list +[NSText initialize]
9443 @end smallexample
9444
9445 In the current version of @value{GDBN}, the plus or minus sign is
9446 required. In future versions of @value{GDBN}, the plus or minus
9447 sign will be optional, but you can use it to narrow the search. It
9448 is also possible to specify just a method name:
9449
9450 @smallexample
9451 break create
9452 @end smallexample
9453
9454 You must specify the complete method name, including any colons. If
9455 your program's source files contain more than one @code{create} method,
9456 you'll be presented with a numbered list of classes that implement that
9457 method. Indicate your choice by number, or type @samp{0} to exit if
9458 none apply.
9459
9460 As another example, to clear a breakpoint established at the
9461 @code{makeKeyAndOrderFront:} method of the @code{NSWindow} class, enter:
9462
9463 @smallexample
9464 clear -[NSWindow makeKeyAndOrderFront:]
9465 @end smallexample
9466
9467 @node The Print Command with Objective-C
9468 @subsubsection The Print Command With Objective-C
9469 @cindex Objective-C, print objects
9470 @kindex print-object
9471 @kindex po @r{(@code{print-object})}
9472
9473 The print command has also been extended to accept methods. For example:
9474
9475 @smallexample
9476 print -[@var{object} hash]
9477 @end smallexample
9478
9479 @cindex print an Objective-C object description
9480 @cindex @code{_NSPrintForDebugger}, and printing Objective-C objects
9481 @noindent
9482 will tell @value{GDBN} to send the @code{hash} message to @var{object}
9483 and print the result. Also, an additional command has been added,
9484 @code{print-object} or @code{po} for short, which is meant to print
9485 the description of an object. However, this command may only work
9486 with certain Objective-C libraries that have a particular hook
9487 function, @code{_NSPrintForDebugger}, defined.
9488
9489 @node Fortran
9490 @subsection Fortran
9491 @cindex Fortran-specific support in @value{GDBN}
9492
9493 @value{GDBN} can be used to debug programs written in Fortran, but it
9494 currently supports only the features of Fortran 77 language.
9495
9496 @cindex trailing underscore, in Fortran symbols
9497 Some Fortran compilers (@sc{gnu} Fortran 77 and Fortran 95 compilers
9498 among them) append an underscore to the names of variables and
9499 functions. When you debug programs compiled by those compilers, you
9500 will need to refer to variables and functions with a trailing
9501 underscore.
9502
9503 @menu
9504 * Fortran Operators:: Fortran operators and expressions
9505 * Fortran Defaults:: Default settings for Fortran
9506 * Special Fortran commands:: Special @value{GDBN} commands for Fortran
9507 @end menu
9508
9509 @node Fortran Operators
9510 @subsubsection Fortran operators and expressions
9511
9512 @cindex Fortran operators and expressions
9513
9514 Operators must be defined on values of specific types. For instance,
9515 @code{+} is defined on numbers, but not on characters or other non-
9516 arithmetic types. Operators are often defined on groups of types.
9517
9518 @table @code
9519 @item **
9520 The exponentiation operator. It raises the first operand to the power
9521 of the second one.
9522
9523 @item :
9524 The range operator. Normally used in the form of array(low:high) to
9525 represent a section of array.
9526 @end table
9527
9528 @node Fortran Defaults
9529 @subsubsection Fortran Defaults
9530
9531 @cindex Fortran Defaults
9532
9533 Fortran symbols are usually case-insensitive, so @value{GDBN} by
9534 default uses case-insensitive matches for Fortran symbols. You can
9535 change that with the @samp{set case-insensitive} command, see
9536 @ref{Symbols}, for the details.
9537
9538 @node Special Fortran commands
9539 @subsubsection Special Fortran commands
9540
9541 @cindex Special Fortran commands
9542
9543 @value{GDBN} had some commands to support Fortran specific feature,
9544 such as common block displaying.
9545
9546 @table @code
9547 @cindex @code{COMMON} blocks, Fortran
9548 @kindex info common
9549 @item info common @r{[}@var{common-name}@r{]}
9550 This command prints the values contained in the Fortran @code{COMMON}
9551 block whose name is @var{common-name}. With no argument, the names of
9552 all @code{COMMON} blocks visible at current program location are
9553 printed.
9554 @end table
9555
9556 @node Pascal
9557 @subsection Pascal
9558
9559 @cindex Pascal support in @value{GDBN}, limitations
9560 Debugging Pascal programs which use sets, subranges, file variables, or
9561 nested functions does not currently work. @value{GDBN} does not support
9562 entering expressions, printing values, or similar features using Pascal
9563 syntax.
9564
9565 The Pascal-specific command @code{set print pascal_static-members}
9566 controls whether static members of Pascal objects are displayed.
9567 @xref{Print Settings, pascal_static-members}.
9568
9569 @node Modula-2
9570 @subsection Modula-2
9571
9572 @cindex Modula-2, @value{GDBN} support
9573
9574 The extensions made to @value{GDBN} to support Modula-2 only support
9575 output from the @sc{gnu} Modula-2 compiler (which is currently being
9576 developed). Other Modula-2 compilers are not currently supported, and
9577 attempting to debug executables produced by them is most likely
9578 to give an error as @value{GDBN} reads in the executable's symbol
9579 table.
9580
9581 @cindex expressions in Modula-2
9582 @menu
9583 * M2 Operators:: Built-in operators
9584 * Built-In Func/Proc:: Built-in functions and procedures
9585 * M2 Constants:: Modula-2 constants
9586 * M2 Types:: Modula-2 types
9587 * M2 Defaults:: Default settings for Modula-2
9588 * Deviations:: Deviations from standard Modula-2
9589 * M2 Checks:: Modula-2 type and range checks
9590 * M2 Scope:: The scope operators @code{::} and @code{.}
9591 * GDB/M2:: @value{GDBN} and Modula-2
9592 @end menu
9593
9594 @node M2 Operators
9595 @subsubsection Operators
9596 @cindex Modula-2 operators
9597
9598 Operators must be defined on values of specific types. For instance,
9599 @code{+} is defined on numbers, but not on structures. Operators are
9600 often defined on groups of types. For the purposes of Modula-2, the
9601 following definitions hold:
9602
9603 @itemize @bullet
9604
9605 @item
9606 @emph{Integral types} consist of @code{INTEGER}, @code{CARDINAL}, and
9607 their subranges.
9608
9609 @item
9610 @emph{Character types} consist of @code{CHAR} and its subranges.
9611
9612 @item
9613 @emph{Floating-point types} consist of @code{REAL}.
9614
9615 @item
9616 @emph{Pointer types} consist of anything declared as @code{POINTER TO
9617 @var{type}}.
9618
9619 @item
9620 @emph{Scalar types} consist of all of the above.
9621
9622 @item
9623 @emph{Set types} consist of @code{SET} and @code{BITSET} types.
9624
9625 @item
9626 @emph{Boolean types} consist of @code{BOOLEAN}.
9627 @end itemize
9628
9629 @noindent
9630 The following operators are supported, and appear in order of
9631 increasing precedence:
9632
9633 @table @code
9634 @item ,
9635 Function argument or array index separator.
9636
9637 @item :=
9638 Assignment. The value of @var{var} @code{:=} @var{value} is
9639 @var{value}.
9640
9641 @item <@r{, }>
9642 Less than, greater than on integral, floating-point, or enumerated
9643 types.
9644
9645 @item <=@r{, }>=
9646 Less than or equal to, greater than or equal to
9647 on integral, floating-point and enumerated types, or set inclusion on
9648 set types. Same precedence as @code{<}.
9649
9650 @item =@r{, }<>@r{, }#
9651 Equality and two ways of expressing inequality, valid on scalar types.
9652 Same precedence as @code{<}. In @value{GDBN} scripts, only @code{<>} is
9653 available for inequality, since @code{#} conflicts with the script
9654 comment character.
9655
9656 @item IN
9657 Set membership. Defined on set types and the types of their members.
9658 Same precedence as @code{<}.
9659
9660 @item OR
9661 Boolean disjunction. Defined on boolean types.
9662
9663 @item AND@r{, }&
9664 Boolean conjunction. Defined on boolean types.
9665
9666 @item @@
9667 The @value{GDBN} ``artificial array'' operator (@pxref{Expressions, ,Expressions}).
9668
9669 @item +@r{, }-
9670 Addition and subtraction on integral and floating-point types, or union
9671 and difference on set types.
9672
9673 @item *
9674 Multiplication on integral and floating-point types, or set intersection
9675 on set types.
9676
9677 @item /
9678 Division on floating-point types, or symmetric set difference on set
9679 types. Same precedence as @code{*}.
9680
9681 @item DIV@r{, }MOD
9682 Integer division and remainder. Defined on integral types. Same
9683 precedence as @code{*}.
9684
9685 @item -
9686 Negative. Defined on @code{INTEGER} and @code{REAL} data.
9687
9688 @item ^
9689 Pointer dereferencing. Defined on pointer types.
9690
9691 @item NOT
9692 Boolean negation. Defined on boolean types. Same precedence as
9693 @code{^}.
9694
9695 @item .
9696 @code{RECORD} field selector. Defined on @code{RECORD} data. Same
9697 precedence as @code{^}.
9698
9699 @item []
9700 Array indexing. Defined on @code{ARRAY} data. Same precedence as @code{^}.
9701
9702 @item ()
9703 Procedure argument list. Defined on @code{PROCEDURE} objects. Same precedence
9704 as @code{^}.
9705
9706 @item ::@r{, }.
9707 @value{GDBN} and Modula-2 scope operators.
9708 @end table
9709
9710 @quotation
9711 @emph{Warning:} Set expressions and their operations are not yet supported, so @value{GDBN}
9712 treats the use of the operator @code{IN}, or the use of operators
9713 @code{+}, @code{-}, @code{*}, @code{/}, @code{=}, , @code{<>}, @code{#},
9714 @code{<=}, and @code{>=} on sets as an error.
9715 @end quotation
9716
9717
9718 @node Built-In Func/Proc
9719 @subsubsection Built-in functions and procedures
9720 @cindex Modula-2 built-ins
9721
9722 Modula-2 also makes available several built-in procedures and functions.
9723 In describing these, the following metavariables are used:
9724
9725 @table @var
9726
9727 @item a
9728 represents an @code{ARRAY} variable.
9729
9730 @item c
9731 represents a @code{CHAR} constant or variable.
9732
9733 @item i
9734 represents a variable or constant of integral type.
9735
9736 @item m
9737 represents an identifier that belongs to a set. Generally used in the
9738 same function with the metavariable @var{s}. The type of @var{s} should
9739 be @code{SET OF @var{mtype}} (where @var{mtype} is the type of @var{m}).
9740
9741 @item n
9742 represents a variable or constant of integral or floating-point type.
9743
9744 @item r
9745 represents a variable or constant of floating-point type.
9746
9747 @item t
9748 represents a type.
9749
9750 @item v
9751 represents a variable.
9752
9753 @item x
9754 represents a variable or constant of one of many types. See the
9755 explanation of the function for details.
9756 @end table
9757
9758 All Modula-2 built-in procedures also return a result, described below.
9759
9760 @table @code
9761 @item ABS(@var{n})
9762 Returns the absolute value of @var{n}.
9763
9764 @item CAP(@var{c})
9765 If @var{c} is a lower case letter, it returns its upper case
9766 equivalent, otherwise it returns its argument.
9767
9768 @item CHR(@var{i})
9769 Returns the character whose ordinal value is @var{i}.
9770
9771 @item DEC(@var{v})
9772 Decrements the value in the variable @var{v} by one. Returns the new value.
9773
9774 @item DEC(@var{v},@var{i})
9775 Decrements the value in the variable @var{v} by @var{i}. Returns the
9776 new value.
9777
9778 @item EXCL(@var{m},@var{s})
9779 Removes the element @var{m} from the set @var{s}. Returns the new
9780 set.
9781
9782 @item FLOAT(@var{i})
9783 Returns the floating point equivalent of the integer @var{i}.
9784
9785 @item HIGH(@var{a})
9786 Returns the index of the last member of @var{a}.
9787
9788 @item INC(@var{v})
9789 Increments the value in the variable @var{v} by one. Returns the new value.
9790
9791 @item INC(@var{v},@var{i})
9792 Increments the value in the variable @var{v} by @var{i}. Returns the
9793 new value.
9794
9795 @item INCL(@var{m},@var{s})
9796 Adds the element @var{m} to the set @var{s} if it is not already
9797 there. Returns the new set.
9798
9799 @item MAX(@var{t})
9800 Returns the maximum value of the type @var{t}.
9801
9802 @item MIN(@var{t})
9803 Returns the minimum value of the type @var{t}.
9804
9805 @item ODD(@var{i})
9806 Returns boolean TRUE if @var{i} is an odd number.
9807
9808 @item ORD(@var{x})
9809 Returns the ordinal value of its argument. For example, the ordinal
9810 value of a character is its @sc{ascii} value (on machines supporting the
9811 @sc{ascii} character set). @var{x} must be of an ordered type, which include
9812 integral, character and enumerated types.
9813
9814 @item SIZE(@var{x})
9815 Returns the size of its argument. @var{x} can be a variable or a type.
9816
9817 @item TRUNC(@var{r})
9818 Returns the integral part of @var{r}.
9819
9820 @item VAL(@var{t},@var{i})
9821 Returns the member of the type @var{t} whose ordinal value is @var{i}.
9822 @end table
9823
9824 @quotation
9825 @emph{Warning:} Sets and their operations are not yet supported, so
9826 @value{GDBN} treats the use of procedures @code{INCL} and @code{EXCL} as
9827 an error.
9828 @end quotation
9829
9830 @cindex Modula-2 constants
9831 @node M2 Constants
9832 @subsubsection Constants
9833
9834 @value{GDBN} allows you to express the constants of Modula-2 in the following
9835 ways:
9836
9837 @itemize @bullet
9838
9839 @item
9840 Integer constants are simply a sequence of digits. When used in an
9841 expression, a constant is interpreted to be type-compatible with the
9842 rest of the expression. Hexadecimal integers are specified by a
9843 trailing @samp{H}, and octal integers by a trailing @samp{B}.
9844
9845 @item
9846 Floating point constants appear as a sequence of digits, followed by a
9847 decimal point and another sequence of digits. An optional exponent can
9848 then be specified, in the form @samp{E@r{[}+@r{|}-@r{]}@var{nnn}}, where
9849 @samp{@r{[}+@r{|}-@r{]}@var{nnn}} is the desired exponent. All of the
9850 digits of the floating point constant must be valid decimal (base 10)
9851 digits.
9852
9853 @item
9854 Character constants consist of a single character enclosed by a pair of
9855 like quotes, either single (@code{'}) or double (@code{"}). They may
9856 also be expressed by their ordinal value (their @sc{ascii} value, usually)
9857 followed by a @samp{C}.
9858
9859 @item
9860 String constants consist of a sequence of characters enclosed by a
9861 pair of like quotes, either single (@code{'}) or double (@code{"}).
9862 Escape sequences in the style of C are also allowed. @xref{C
9863 Constants, ,C and C@t{++} constants}, for a brief explanation of escape
9864 sequences.
9865
9866 @item
9867 Enumerated constants consist of an enumerated identifier.
9868
9869 @item
9870 Boolean constants consist of the identifiers @code{TRUE} and
9871 @code{FALSE}.
9872
9873 @item
9874 Pointer constants consist of integral values only.
9875
9876 @item
9877 Set constants are not yet supported.
9878 @end itemize
9879
9880 @node M2 Types
9881 @subsubsection Modula-2 Types
9882 @cindex Modula-2 types
9883
9884 Currently @value{GDBN} can print the following data types in Modula-2
9885 syntax: array types, record types, set types, pointer types, procedure
9886 types, enumerated types, subrange types and base types. You can also
9887 print the contents of variables declared using these type.
9888 This section gives a number of simple source code examples together with
9889 sample @value{GDBN} sessions.
9890
9891 The first example contains the following section of code:
9892
9893 @smallexample
9894 VAR
9895 s: SET OF CHAR ;
9896 r: [20..40] ;
9897 @end smallexample
9898
9899 @noindent
9900 and you can request @value{GDBN} to interrogate the type and value of
9901 @code{r} and @code{s}.
9902
9903 @smallexample
9904 (@value{GDBP}) print s
9905 @{'A'..'C', 'Z'@}
9906 (@value{GDBP}) ptype s
9907 SET OF CHAR
9908 (@value{GDBP}) print r
9909 21
9910 (@value{GDBP}) ptype r
9911 [20..40]
9912 @end smallexample
9913
9914 @noindent
9915 Likewise if your source code declares @code{s} as:
9916
9917 @smallexample
9918 VAR
9919 s: SET ['A'..'Z'] ;
9920 @end smallexample
9921
9922 @noindent
9923 then you may query the type of @code{s} by:
9924
9925 @smallexample
9926 (@value{GDBP}) ptype s
9927 type = SET ['A'..'Z']
9928 @end smallexample
9929
9930 @noindent
9931 Note that at present you cannot interactively manipulate set
9932 expressions using the debugger.
9933
9934 The following example shows how you might declare an array in Modula-2
9935 and how you can interact with @value{GDBN} to print its type and contents:
9936
9937 @smallexample
9938 VAR
9939 s: ARRAY [-10..10] OF CHAR ;
9940 @end smallexample
9941
9942 @smallexample
9943 (@value{GDBP}) ptype s
9944 ARRAY [-10..10] OF CHAR
9945 @end smallexample
9946
9947 Note that the array handling is not yet complete and although the type
9948 is printed correctly, expression handling still assumes that all
9949 arrays have a lower bound of zero and not @code{-10} as in the example
9950 above. Unbounded arrays are also not yet recognized in @value{GDBN}.
9951
9952 Here are some more type related Modula-2 examples:
9953
9954 @smallexample
9955 TYPE
9956 colour = (blue, red, yellow, green) ;
9957 t = [blue..yellow] ;
9958 VAR
9959 s: t ;
9960 BEGIN
9961 s := blue ;
9962 @end smallexample
9963
9964 @noindent
9965 The @value{GDBN} interaction shows how you can query the data type
9966 and value of a variable.
9967
9968 @smallexample
9969 (@value{GDBP}) print s
9970 $1 = blue
9971 (@value{GDBP}) ptype t
9972 type = [blue..yellow]
9973 @end smallexample
9974
9975 @noindent
9976 In this example a Modula-2 array is declared and its contents
9977 displayed. Observe that the contents are written in the same way as
9978 their @code{C} counterparts.
9979
9980 @smallexample
9981 VAR
9982 s: ARRAY [1..5] OF CARDINAL ;
9983 BEGIN
9984 s[1] := 1 ;
9985 @end smallexample
9986
9987 @smallexample
9988 (@value{GDBP}) print s
9989 $1 = @{1, 0, 0, 0, 0@}
9990 (@value{GDBP}) ptype s
9991 type = ARRAY [1..5] OF CARDINAL
9992 @end smallexample
9993
9994 The Modula-2 language interface to @value{GDBN} also understands
9995 pointer types as shown in this example:
9996
9997 @smallexample
9998 VAR
9999 s: POINTER TO ARRAY [1..5] OF CARDINAL ;
10000 BEGIN
10001 NEW(s) ;
10002 s^[1] := 1 ;
10003 @end smallexample
10004
10005 @noindent
10006 and you can request that @value{GDBN} describes the type of @code{s}.
10007
10008 @smallexample
10009 (@value{GDBP}) ptype s
10010 type = POINTER TO ARRAY [1..5] OF CARDINAL
10011 @end smallexample
10012
10013 @value{GDBN} handles compound types as we can see in this example.
10014 Here we combine array types, record types, pointer types and subrange
10015 types:
10016
10017 @smallexample
10018 TYPE
10019 foo = RECORD
10020 f1: CARDINAL ;
10021 f2: CHAR ;
10022 f3: myarray ;
10023 END ;
10024
10025 myarray = ARRAY myrange OF CARDINAL ;
10026 myrange = [-2..2] ;
10027 VAR
10028 s: POINTER TO ARRAY myrange OF foo ;
10029 @end smallexample
10030
10031 @noindent
10032 and you can ask @value{GDBN} to describe the type of @code{s} as shown
10033 below.
10034
10035 @smallexample
10036 (@value{GDBP}) ptype s
10037 type = POINTER TO ARRAY [-2..2] OF foo = RECORD
10038 f1 : CARDINAL;
10039 f2 : CHAR;
10040 f3 : ARRAY [-2..2] OF CARDINAL;
10041 END
10042 @end smallexample
10043
10044 @node M2 Defaults
10045 @subsubsection Modula-2 defaults
10046 @cindex Modula-2 defaults
10047
10048 If type and range checking are set automatically by @value{GDBN}, they
10049 both default to @code{on} whenever the working language changes to
10050 Modula-2. This happens regardless of whether you or @value{GDBN}
10051 selected the working language.
10052
10053 If you allow @value{GDBN} to set the language automatically, then entering
10054 code compiled from a file whose name ends with @file{.mod} sets the
10055 working language to Modula-2. @xref{Automatically, ,Having @value{GDBN} set
10056 the language automatically}, for further details.
10057
10058 @node Deviations
10059 @subsubsection Deviations from standard Modula-2
10060 @cindex Modula-2, deviations from
10061
10062 A few changes have been made to make Modula-2 programs easier to debug.
10063 This is done primarily via loosening its type strictness:
10064
10065 @itemize @bullet
10066 @item
10067 Unlike in standard Modula-2, pointer constants can be formed by
10068 integers. This allows you to modify pointer variables during
10069 debugging. (In standard Modula-2, the actual address contained in a
10070 pointer variable is hidden from you; it can only be modified
10071 through direct assignment to another pointer variable or expression that
10072 returned a pointer.)
10073
10074 @item
10075 C escape sequences can be used in strings and characters to represent
10076 non-printable characters. @value{GDBN} prints out strings with these
10077 escape sequences embedded. Single non-printable characters are
10078 printed using the @samp{CHR(@var{nnn})} format.
10079
10080 @item
10081 The assignment operator (@code{:=}) returns the value of its right-hand
10082 argument.
10083
10084 @item
10085 All built-in procedures both modify @emph{and} return their argument.
10086 @end itemize
10087
10088 @node M2 Checks
10089 @subsubsection Modula-2 type and range checks
10090 @cindex Modula-2 checks
10091
10092 @quotation
10093 @emph{Warning:} in this release, @value{GDBN} does not yet perform type or
10094 range checking.
10095 @end quotation
10096 @c FIXME remove warning when type/range checks added
10097
10098 @value{GDBN} considers two Modula-2 variables type equivalent if:
10099
10100 @itemize @bullet
10101 @item
10102 They are of types that have been declared equivalent via a @code{TYPE
10103 @var{t1} = @var{t2}} statement
10104
10105 @item
10106 They have been declared on the same line. (Note: This is true of the
10107 @sc{gnu} Modula-2 compiler, but it may not be true of other compilers.)
10108 @end itemize
10109
10110 As long as type checking is enabled, any attempt to combine variables
10111 whose types are not equivalent is an error.
10112
10113 Range checking is done on all mathematical operations, assignment, array
10114 index bounds, and all built-in functions and procedures.
10115
10116 @node M2 Scope
10117 @subsubsection The scope operators @code{::} and @code{.}
10118 @cindex scope
10119 @cindex @code{.}, Modula-2 scope operator
10120 @cindex colon, doubled as scope operator
10121 @ifinfo
10122 @vindex colon-colon@r{, in Modula-2}
10123 @c Info cannot handle :: but TeX can.
10124 @end ifinfo
10125 @iftex
10126 @vindex ::@r{, in Modula-2}
10127 @end iftex
10128
10129 There are a few subtle differences between the Modula-2 scope operator
10130 (@code{.}) and the @value{GDBN} scope operator (@code{::}). The two have
10131 similar syntax:
10132
10133 @smallexample
10134
10135 @var{module} . @var{id}
10136 @var{scope} :: @var{id}
10137 @end smallexample
10138
10139 @noindent
10140 where @var{scope} is the name of a module or a procedure,
10141 @var{module} the name of a module, and @var{id} is any declared
10142 identifier within your program, except another module.
10143
10144 Using the @code{::} operator makes @value{GDBN} search the scope
10145 specified by @var{scope} for the identifier @var{id}. If it is not
10146 found in the specified scope, then @value{GDBN} searches all scopes
10147 enclosing the one specified by @var{scope}.
10148
10149 Using the @code{.} operator makes @value{GDBN} search the current scope for
10150 the identifier specified by @var{id} that was imported from the
10151 definition module specified by @var{module}. With this operator, it is
10152 an error if the identifier @var{id} was not imported from definition
10153 module @var{module}, or if @var{id} is not an identifier in
10154 @var{module}.
10155
10156 @node GDB/M2
10157 @subsubsection @value{GDBN} and Modula-2
10158
10159 Some @value{GDBN} commands have little use when debugging Modula-2 programs.
10160 Five subcommands of @code{set print} and @code{show print} apply
10161 specifically to C and C@t{++}: @samp{vtbl}, @samp{demangle},
10162 @samp{asm-demangle}, @samp{object}, and @samp{union}. The first four
10163 apply to C@t{++}, and the last to the C @code{union} type, which has no direct
10164 analogue in Modula-2.
10165
10166 The @code{@@} operator (@pxref{Expressions, ,Expressions}), while available
10167 with any language, is not useful with Modula-2. Its
10168 intent is to aid the debugging of @dfn{dynamic arrays}, which cannot be
10169 created in Modula-2 as they can in C or C@t{++}. However, because an
10170 address can be specified by an integral constant, the construct
10171 @samp{@{@var{type}@}@var{adrexp}} is still useful.
10172
10173 @cindex @code{#} in Modula-2
10174 In @value{GDBN} scripts, the Modula-2 inequality operator @code{#} is
10175 interpreted as the beginning of a comment. Use @code{<>} instead.
10176
10177 @node Ada
10178 @subsection Ada
10179 @cindex Ada
10180
10181 The extensions made to @value{GDBN} for Ada only support
10182 output from the @sc{gnu} Ada (GNAT) compiler.
10183 Other Ada compilers are not currently supported, and
10184 attempting to debug executables produced by them is most likely
10185 to be difficult.
10186
10187
10188 @cindex expressions in Ada
10189 @menu
10190 * Ada Mode Intro:: General remarks on the Ada syntax
10191 and semantics supported by Ada mode
10192 in @value{GDBN}.
10193 * Omissions from Ada:: Restrictions on the Ada expression syntax.
10194 * Additions to Ada:: Extensions of the Ada expression syntax.
10195 * Stopping Before Main Program:: Debugging the program during elaboration.
10196 * Ada Glitches:: Known peculiarities of Ada mode.
10197 @end menu
10198
10199 @node Ada Mode Intro
10200 @subsubsection Introduction
10201 @cindex Ada mode, general
10202
10203 The Ada mode of @value{GDBN} supports a fairly large subset of Ada expression
10204 syntax, with some extensions.
10205 The philosophy behind the design of this subset is
10206
10207 @itemize @bullet
10208 @item
10209 That @value{GDBN} should provide basic literals and access to operations for
10210 arithmetic, dereferencing, field selection, indexing, and subprogram calls,
10211 leaving more sophisticated computations to subprograms written into the
10212 program (which therefore may be called from @value{GDBN}).
10213
10214 @item
10215 That type safety and strict adherence to Ada language restrictions
10216 are not particularly important to the @value{GDBN} user.
10217
10218 @item
10219 That brevity is important to the @value{GDBN} user.
10220 @end itemize
10221
10222 Thus, for brevity, the debugger acts as if there were
10223 implicit @code{with} and @code{use} clauses in effect for all user-written
10224 packages, making it unnecessary to fully qualify most names with
10225 their packages, regardless of context. Where this causes ambiguity,
10226 @value{GDBN} asks the user's intent.
10227
10228 The debugger will start in Ada mode if it detects an Ada main program.
10229 As for other languages, it will enter Ada mode when stopped in a program that
10230 was translated from an Ada source file.
10231
10232 While in Ada mode, you may use `@t{--}' for comments. This is useful
10233 mostly for documenting command files. The standard @value{GDBN} comment
10234 (@samp{#}) still works at the beginning of a line in Ada mode, but not in the
10235 middle (to allow based literals).
10236
10237 The debugger supports limited overloading. Given a subprogram call in which
10238 the function symbol has multiple definitions, it will use the number of
10239 actual parameters and some information about their types to attempt to narrow
10240 the set of definitions. It also makes very limited use of context, preferring
10241 procedures to functions in the context of the @code{call} command, and
10242 functions to procedures elsewhere.
10243
10244 @node Omissions from Ada
10245 @subsubsection Omissions from Ada
10246 @cindex Ada, omissions from
10247
10248 Here are the notable omissions from the subset:
10249
10250 @itemize @bullet
10251 @item
10252 Only a subset of the attributes are supported:
10253
10254 @itemize @minus
10255 @item
10256 @t{'First}, @t{'Last}, and @t{'Length}
10257 on array objects (not on types and subtypes).
10258
10259 @item
10260 @t{'Min} and @t{'Max}.
10261
10262 @item
10263 @t{'Pos} and @t{'Val}.
10264
10265 @item
10266 @t{'Tag}.
10267
10268 @item
10269 @t{'Range} on array objects (not subtypes), but only as the right
10270 operand of the membership (@code{in}) operator.
10271
10272 @item
10273 @t{'Access}, @t{'Unchecked_Access}, and
10274 @t{'Unrestricted_Access} (a GNAT extension).
10275
10276 @item
10277 @t{'Address}.
10278 @end itemize
10279
10280 @item
10281 The names in
10282 @code{Characters.Latin_1} are not available and
10283 concatenation is not implemented. Thus, escape characters in strings are
10284 not currently available.
10285
10286 @item
10287 Equality tests (@samp{=} and @samp{/=}) on arrays test for bitwise
10288 equality of representations. They will generally work correctly
10289 for strings and arrays whose elements have integer or enumeration types.
10290 They may not work correctly for arrays whose element
10291 types have user-defined equality, for arrays of real values
10292 (in particular, IEEE-conformant floating point, because of negative
10293 zeroes and NaNs), and for arrays whose elements contain unused bits with
10294 indeterminate values.
10295
10296 @item
10297 The other component-by-component array operations (@code{and}, @code{or},
10298 @code{xor}, @code{not}, and relational tests other than equality)
10299 are not implemented.
10300
10301 @item
10302 @cindex array aggregates (Ada)
10303 @cindex record aggregates (Ada)
10304 @cindex aggregates (Ada)
10305 There is limited support for array and record aggregates. They are
10306 permitted only on the right sides of assignments, as in these examples:
10307
10308 @smallexample
10309 set An_Array := (1, 2, 3, 4, 5, 6)
10310 set An_Array := (1, others => 0)
10311 set An_Array := (0|4 => 1, 1..3 => 2, 5 => 6)
10312 set A_2D_Array := ((1, 2, 3), (4, 5, 6), (7, 8, 9))
10313 set A_Record := (1, "Peter", True);
10314 set A_Record := (Name => "Peter", Id => 1, Alive => True)
10315 @end smallexample
10316
10317 Changing a
10318 discriminant's value by assigning an aggregate has an
10319 undefined effect if that discriminant is used within the record.
10320 However, you can first modify discriminants by directly assigning to
10321 them (which normally would not be allowed in Ada), and then performing an
10322 aggregate assignment. For example, given a variable @code{A_Rec}
10323 declared to have a type such as:
10324
10325 @smallexample
10326 type Rec (Len : Small_Integer := 0) is record
10327 Id : Integer;
10328 Vals : IntArray (1 .. Len);
10329 end record;
10330 @end smallexample
10331
10332 you can assign a value with a different size of @code{Vals} with two
10333 assignments:
10334
10335 @smallexample
10336 set A_Rec.Len := 4
10337 set A_Rec := (Id => 42, Vals => (1, 2, 3, 4))
10338 @end smallexample
10339
10340 As this example also illustrates, @value{GDBN} is very loose about the usual
10341 rules concerning aggregates. You may leave out some of the
10342 components of an array or record aggregate (such as the @code{Len}
10343 component in the assignment to @code{A_Rec} above); they will retain their
10344 original values upon assignment. You may freely use dynamic values as
10345 indices in component associations. You may even use overlapping or
10346 redundant component associations, although which component values are
10347 assigned in such cases is not defined.
10348
10349 @item
10350 Calls to dispatching subprograms are not implemented.
10351
10352 @item
10353 The overloading algorithm is much more limited (i.e., less selective)
10354 than that of real Ada. It makes only limited use of the context in which a subexpression
10355 appears to resolve its meaning, and it is much looser in its rules for allowing
10356 type matches. As a result, some function calls will be ambiguous, and the user
10357 will be asked to choose the proper resolution.
10358
10359 @item
10360 The @code{new} operator is not implemented.
10361
10362 @item
10363 Entry calls are not implemented.
10364
10365 @item
10366 Aside from printing, arithmetic operations on the native VAX floating-point
10367 formats are not supported.
10368
10369 @item
10370 It is not possible to slice a packed array.
10371 @end itemize
10372
10373 @node Additions to Ada
10374 @subsubsection Additions to Ada
10375 @cindex Ada, deviations from
10376
10377 As it does for other languages, @value{GDBN} makes certain generic
10378 extensions to Ada (@pxref{Expressions}):
10379
10380 @itemize @bullet
10381 @item
10382 If the expression @var{E} is a variable residing in memory
10383 (typically a local variable or array element) and @var{N} is
10384 a positive integer, then @code{@var{E}@@@var{N}} displays the values of
10385 @var{E} and the @var{N}-1 adjacent variables following it in memory as an array.
10386 In Ada, this operator is generally not necessary, since its prime use
10387 is in displaying parts of an array, and slicing will usually do this in Ada.
10388 However, there are occasional uses when debugging programs
10389 in which certain debugging information has been optimized away.
10390
10391 @item
10392 @code{@var{B}::@var{var}} means ``the variable named @var{var} that appears
10393 in function or file @var{B}.'' When @var{B} is a file name, you must typically
10394 surround it in single quotes.
10395
10396 @item
10397 The expression @code{@{@var{type}@} @var{addr}} means ``the variable of type
10398 @var{type} that appears at address @var{addr}.''
10399
10400 @item
10401 A name starting with @samp{$} is a convenience variable
10402 (@pxref{Convenience Vars}) or a machine register (@pxref{Registers}).
10403 @end itemize
10404
10405 In addition, @value{GDBN} provides a few other shortcuts and outright additions specific
10406 to Ada:
10407
10408 @itemize @bullet
10409 @item
10410 The assignment statement is allowed as an expression, returning
10411 its right-hand operand as its value. Thus, you may enter
10412
10413 @smallexample
10414 set x := y + 3
10415 print A(tmp := y + 1)
10416 @end smallexample
10417
10418 @item
10419 The semicolon is allowed as an ``operator,'' returning as its value
10420 the value of its right-hand operand.
10421 This allows, for example,
10422 complex conditional breaks:
10423
10424 @smallexample
10425 break f
10426 condition 1 (report(i); k += 1; A(k) > 100)
10427 @end smallexample
10428
10429 @item
10430 Rather than use catenation and symbolic character names to introduce special
10431 characters into strings, one may instead use a special bracket notation,
10432 which is also used to print strings. A sequence of characters of the form
10433 @samp{["@var{XX}"]} within a string or character literal denotes the
10434 (single) character whose numeric encoding is @var{XX} in hexadecimal. The
10435 sequence of characters @samp{["""]} also denotes a single quotation mark
10436 in strings. For example,
10437 @smallexample
10438 "One line.["0a"]Next line.["0a"]"
10439 @end smallexample
10440 @noindent
10441 contains an ASCII newline character (@code{Ada.Characters.Latin_1.LF}) after each
10442 period.
10443
10444 @item
10445 The subtype used as a prefix for the attributes @t{'Pos}, @t{'Min}, and
10446 @t{'Max} is optional (and is ignored in any case). For example, it is valid
10447 to write
10448
10449 @smallexample
10450 print 'max(x, y)
10451 @end smallexample
10452
10453 @item
10454 When printing arrays, @value{GDBN} uses positional notation when the
10455 array has a lower bound of 1, and uses a modified named notation otherwise.
10456 For example, a one-dimensional array of three integers with a lower bound of 3 might print as
10457
10458 @smallexample
10459 (3 => 10, 17, 1)
10460 @end smallexample
10461
10462 @noindent
10463 That is, in contrast to valid Ada, only the first component has a @code{=>}
10464 clause.
10465
10466 @item
10467 You may abbreviate attributes in expressions with any unique,
10468 multi-character subsequence of
10469 their names (an exact match gets preference).
10470 For example, you may use @t{a'len}, @t{a'gth}, or @t{a'lh}
10471 in place of @t{a'length}.
10472
10473 @item
10474 @cindex quoting Ada internal identifiers
10475 Since Ada is case-insensitive, the debugger normally maps identifiers you type
10476 to lower case. The GNAT compiler uses upper-case characters for
10477 some of its internal identifiers, which are normally of no interest to users.
10478 For the rare occasions when you actually have to look at them,
10479 enclose them in angle brackets to avoid the lower-case mapping.
10480 For example,
10481 @smallexample
10482 @value{GDBP} print <JMPBUF_SAVE>[0]
10483 @end smallexample
10484
10485 @item
10486 Printing an object of class-wide type or dereferencing an
10487 access-to-class-wide value will display all the components of the object's
10488 specific type (as indicated by its run-time tag). Likewise, component
10489 selection on such a value will operate on the specific type of the
10490 object.
10491
10492 @end itemize
10493
10494 @node Stopping Before Main Program
10495 @subsubsection Stopping at the Very Beginning
10496
10497 @cindex breakpointing Ada elaboration code
10498 It is sometimes necessary to debug the program during elaboration, and
10499 before reaching the main procedure.
10500 As defined in the Ada Reference
10501 Manual, the elaboration code is invoked from a procedure called
10502 @code{adainit}. To run your program up to the beginning of
10503 elaboration, simply use the following two commands:
10504 @code{tbreak adainit} and @code{run}.
10505
10506 @node Ada Glitches
10507 @subsubsection Known Peculiarities of Ada Mode
10508 @cindex Ada, problems
10509
10510 Besides the omissions listed previously (@pxref{Omissions from Ada}),
10511 we know of several problems with and limitations of Ada mode in
10512 @value{GDBN},
10513 some of which will be fixed with planned future releases of the debugger
10514 and the GNU Ada compiler.
10515
10516 @itemize @bullet
10517 @item
10518 Currently, the debugger
10519 has insufficient information to determine whether certain pointers represent
10520 pointers to objects or the objects themselves.
10521 Thus, the user may have to tack an extra @code{.all} after an expression
10522 to get it printed properly.
10523
10524 @item
10525 Static constants that the compiler chooses not to materialize as objects in
10526 storage are invisible to the debugger.
10527
10528 @item
10529 Named parameter associations in function argument lists are ignored (the
10530 argument lists are treated as positional).
10531
10532 @item
10533 Many useful library packages are currently invisible to the debugger.
10534
10535 @item
10536 Fixed-point arithmetic, conversions, input, and output is carried out using
10537 floating-point arithmetic, and may give results that only approximate those on
10538 the host machine.
10539
10540 @item
10541 The type of the @t{'Address} attribute may not be @code{System.Address}.
10542
10543 @item
10544 The GNAT compiler never generates the prefix @code{Standard} for any of
10545 the standard symbols defined by the Ada language. @value{GDBN} knows about
10546 this: it will strip the prefix from names when you use it, and will never
10547 look for a name you have so qualified among local symbols, nor match against
10548 symbols in other packages or subprograms. If you have
10549 defined entities anywhere in your program other than parameters and
10550 local variables whose simple names match names in @code{Standard},
10551 GNAT's lack of qualification here can cause confusion. When this happens,
10552 you can usually resolve the confusion
10553 by qualifying the problematic names with package
10554 @code{Standard} explicitly.
10555 @end itemize
10556
10557 @node Unsupported languages
10558 @section Unsupported languages
10559
10560 @cindex unsupported languages
10561 @cindex minimal language
10562 In addition to the other fully-supported programming languages,
10563 @value{GDBN} also provides a pseudo-language, called @code{minimal}.
10564 It does not represent a real programming language, but provides a set
10565 of capabilities close to what the C or assembly languages provide.
10566 This should allow most simple operations to be performed while debugging
10567 an application that uses a language currently not supported by @value{GDBN}.
10568
10569 If the language is set to @code{auto}, @value{GDBN} will automatically
10570 select this language if the current frame corresponds to an unsupported
10571 language.
10572
10573 @node Symbols
10574 @chapter Examining the Symbol Table
10575
10576 The commands described in this chapter allow you to inquire about the
10577 symbols (names of variables, functions and types) defined in your
10578 program. This information is inherent in the text of your program and
10579 does not change as your program executes. @value{GDBN} finds it in your
10580 program's symbol table, in the file indicated when you started @value{GDBN}
10581 (@pxref{File Options, ,Choosing files}), or by one of the
10582 file-management commands (@pxref{Files, ,Commands to specify files}).
10583
10584 @cindex symbol names
10585 @cindex names of symbols
10586 @cindex quoting names
10587 Occasionally, you may need to refer to symbols that contain unusual
10588 characters, which @value{GDBN} ordinarily treats as word delimiters. The
10589 most frequent case is in referring to static variables in other
10590 source files (@pxref{Variables,,Program variables}). File names
10591 are recorded in object files as debugging symbols, but @value{GDBN} would
10592 ordinarily parse a typical file name, like @file{foo.c}, as the three words
10593 @samp{foo} @samp{.} @samp{c}. To allow @value{GDBN} to recognize
10594 @samp{foo.c} as a single symbol, enclose it in single quotes; for example,
10595
10596 @smallexample
10597 p 'foo.c'::x
10598 @end smallexample
10599
10600 @noindent
10601 looks up the value of @code{x} in the scope of the file @file{foo.c}.
10602
10603 @table @code
10604 @cindex case-insensitive symbol names
10605 @cindex case sensitivity in symbol names
10606 @kindex set case-sensitive
10607 @item set case-sensitive on
10608 @itemx set case-sensitive off
10609 @itemx set case-sensitive auto
10610 Normally, when @value{GDBN} looks up symbols, it matches their names
10611 with case sensitivity determined by the current source language.
10612 Occasionally, you may wish to control that. The command @code{set
10613 case-sensitive} lets you do that by specifying @code{on} for
10614 case-sensitive matches or @code{off} for case-insensitive ones. If
10615 you specify @code{auto}, case sensitivity is reset to the default
10616 suitable for the source language. The default is case-sensitive
10617 matches for all languages except for Fortran, for which the default is
10618 case-insensitive matches.
10619
10620 @kindex show case-sensitive
10621 @item show case-sensitive
10622 This command shows the current setting of case sensitivity for symbols
10623 lookups.
10624
10625 @kindex info address
10626 @cindex address of a symbol
10627 @item info address @var{symbol}
10628 Describe where the data for @var{symbol} is stored. For a register
10629 variable, this says which register it is kept in. For a non-register
10630 local variable, this prints the stack-frame offset at which the variable
10631 is always stored.
10632
10633 Note the contrast with @samp{print &@var{symbol}}, which does not work
10634 at all for a register variable, and for a stack local variable prints
10635 the exact address of the current instantiation of the variable.
10636
10637 @kindex info symbol
10638 @cindex symbol from address
10639 @cindex closest symbol and offset for an address
10640 @item info symbol @var{addr}
10641 Print the name of a symbol which is stored at the address @var{addr}.
10642 If no symbol is stored exactly at @var{addr}, @value{GDBN} prints the
10643 nearest symbol and an offset from it:
10644
10645 @smallexample
10646 (@value{GDBP}) info symbol 0x54320
10647 _initialize_vx + 396 in section .text
10648 @end smallexample
10649
10650 @noindent
10651 This is the opposite of the @code{info address} command. You can use
10652 it to find out the name of a variable or a function given its address.
10653
10654 @kindex whatis
10655 @item whatis [@var{arg}]
10656 Print the data type of @var{arg}, which can be either an expression or
10657 a data type. With no argument, print the data type of @code{$}, the
10658 last value in the value history. If @var{arg} is an expression, it is
10659 not actually evaluated, and any side-effecting operations (such as
10660 assignments or function calls) inside it do not take place. If
10661 @var{arg} is a type name, it may be the name of a type or typedef, or
10662 for C code it may have the form @samp{class @var{class-name}},
10663 @samp{struct @var{struct-tag}}, @samp{union @var{union-tag}} or
10664 @samp{enum @var{enum-tag}}.
10665 @xref{Expressions, ,Expressions}.
10666
10667 @kindex ptype
10668 @item ptype [@var{arg}]
10669 @code{ptype} accepts the same arguments as @code{whatis}, but prints a
10670 detailed description of the type, instead of just the name of the type.
10671 @xref{Expressions, ,Expressions}.
10672
10673 For example, for this variable declaration:
10674
10675 @smallexample
10676 struct complex @{double real; double imag;@} v;
10677 @end smallexample
10678
10679 @noindent
10680 the two commands give this output:
10681
10682 @smallexample
10683 @group
10684 (@value{GDBP}) whatis v
10685 type = struct complex
10686 (@value{GDBP}) ptype v
10687 type = struct complex @{
10688 double real;
10689 double imag;
10690 @}
10691 @end group
10692 @end smallexample
10693
10694 @noindent
10695 As with @code{whatis}, using @code{ptype} without an argument refers to
10696 the type of @code{$}, the last value in the value history.
10697
10698 @cindex incomplete type
10699 Sometimes, programs use opaque data types or incomplete specifications
10700 of complex data structure. If the debug information included in the
10701 program does not allow @value{GDBN} to display a full declaration of
10702 the data type, it will say @samp{<incomplete type>}. For example,
10703 given these declarations:
10704
10705 @smallexample
10706 struct foo;
10707 struct foo *fooptr;
10708 @end smallexample
10709
10710 @noindent
10711 but no definition for @code{struct foo} itself, @value{GDBN} will say:
10712
10713 @smallexample
10714 (@value{GDBP}) ptype foo
10715 $1 = <incomplete type>
10716 @end smallexample
10717
10718 @noindent
10719 ``Incomplete type'' is C terminology for data types that are not
10720 completely specified.
10721
10722 @kindex info types
10723 @item info types @var{regexp}
10724 @itemx info types
10725 Print a brief description of all types whose names match the regular
10726 expression @var{regexp} (or all types in your program, if you supply
10727 no argument). Each complete typename is matched as though it were a
10728 complete line; thus, @samp{i type value} gives information on all
10729 types in your program whose names include the string @code{value}, but
10730 @samp{i type ^value$} gives information only on types whose complete
10731 name is @code{value}.
10732
10733 This command differs from @code{ptype} in two ways: first, like
10734 @code{whatis}, it does not print a detailed description; second, it
10735 lists all source files where a type is defined.
10736
10737 @kindex info scope
10738 @cindex local variables
10739 @item info scope @var{location}
10740 List all the variables local to a particular scope. This command
10741 accepts a @var{location} argument---a function name, a source line, or
10742 an address preceded by a @samp{*}, and prints all the variables local
10743 to the scope defined by that location. For example:
10744
10745 @smallexample
10746 (@value{GDBP}) @b{info scope command_line_handler}
10747 Scope for command_line_handler:
10748 Symbol rl is an argument at stack/frame offset 8, length 4.
10749 Symbol linebuffer is in static storage at address 0x150a18, length 4.
10750 Symbol linelength is in static storage at address 0x150a1c, length 4.
10751 Symbol p is a local variable in register $esi, length 4.
10752 Symbol p1 is a local variable in register $ebx, length 4.
10753 Symbol nline is a local variable in register $edx, length 4.
10754 Symbol repeat is a local variable at frame offset -8, length 4.
10755 @end smallexample
10756
10757 @noindent
10758 This command is especially useful for determining what data to collect
10759 during a @dfn{trace experiment}, see @ref{Tracepoint Actions,
10760 collect}.
10761
10762 @kindex info source
10763 @item info source
10764 Show information about the current source file---that is, the source file for
10765 the function containing the current point of execution:
10766 @itemize @bullet
10767 @item
10768 the name of the source file, and the directory containing it,
10769 @item
10770 the directory it was compiled in,
10771 @item
10772 its length, in lines,
10773 @item
10774 which programming language it is written in,
10775 @item
10776 whether the executable includes debugging information for that file, and
10777 if so, what format the information is in (e.g., STABS, Dwarf 2, etc.), and
10778 @item
10779 whether the debugging information includes information about
10780 preprocessor macros.
10781 @end itemize
10782
10783
10784 @kindex info sources
10785 @item info sources
10786 Print the names of all source files in your program for which there is
10787 debugging information, organized into two lists: files whose symbols
10788 have already been read, and files whose symbols will be read when needed.
10789
10790 @kindex info functions
10791 @item info functions
10792 Print the names and data types of all defined functions.
10793
10794 @item info functions @var{regexp}
10795 Print the names and data types of all defined functions
10796 whose names contain a match for regular expression @var{regexp}.
10797 Thus, @samp{info fun step} finds all functions whose names
10798 include @code{step}; @samp{info fun ^step} finds those whose names
10799 start with @code{step}. If a function name contains characters
10800 that conflict with the regular expression language (e.g.@:
10801 @samp{operator*()}), they may be quoted with a backslash.
10802
10803 @kindex info variables
10804 @item info variables
10805 Print the names and data types of all variables that are declared
10806 outside of functions (i.e.@: excluding local variables).
10807
10808 @item info variables @var{regexp}
10809 Print the names and data types of all variables (except for local
10810 variables) whose names contain a match for regular expression
10811 @var{regexp}.
10812
10813 @kindex info classes
10814 @cindex Objective-C, classes and selectors
10815 @item info classes
10816 @itemx info classes @var{regexp}
10817 Display all Objective-C classes in your program, or
10818 (with the @var{regexp} argument) all those matching a particular regular
10819 expression.
10820
10821 @kindex info selectors
10822 @item info selectors
10823 @itemx info selectors @var{regexp}
10824 Display all Objective-C selectors in your program, or
10825 (with the @var{regexp} argument) all those matching a particular regular
10826 expression.
10827
10828 @ignore
10829 This was never implemented.
10830 @kindex info methods
10831 @item info methods
10832 @itemx info methods @var{regexp}
10833 The @code{info methods} command permits the user to examine all defined
10834 methods within C@t{++} program, or (with the @var{regexp} argument) a
10835 specific set of methods found in the various C@t{++} classes. Many
10836 C@t{++} classes provide a large number of methods. Thus, the output
10837 from the @code{ptype} command can be overwhelming and hard to use. The
10838 @code{info-methods} command filters the methods, printing only those
10839 which match the regular-expression @var{regexp}.
10840 @end ignore
10841
10842 @cindex reloading symbols
10843 Some systems allow individual object files that make up your program to
10844 be replaced without stopping and restarting your program. For example,
10845 in VxWorks you can simply recompile a defective object file and keep on
10846 running. If you are running on one of these systems, you can allow
10847 @value{GDBN} to reload the symbols for automatically relinked modules:
10848
10849 @table @code
10850 @kindex set symbol-reloading
10851 @item set symbol-reloading on
10852 Replace symbol definitions for the corresponding source file when an
10853 object file with a particular name is seen again.
10854
10855 @item set symbol-reloading off
10856 Do not replace symbol definitions when encountering object files of the
10857 same name more than once. This is the default state; if you are not
10858 running on a system that permits automatic relinking of modules, you
10859 should leave @code{symbol-reloading} off, since otherwise @value{GDBN}
10860 may discard symbols when linking large programs, that may contain
10861 several modules (from different directories or libraries) with the same
10862 name.
10863
10864 @kindex show symbol-reloading
10865 @item show symbol-reloading
10866 Show the current @code{on} or @code{off} setting.
10867 @end table
10868
10869 @cindex opaque data types
10870 @kindex set opaque-type-resolution
10871 @item set opaque-type-resolution on
10872 Tell @value{GDBN} to resolve opaque types. An opaque type is a type
10873 declared as a pointer to a @code{struct}, @code{class}, or
10874 @code{union}---for example, @code{struct MyType *}---that is used in one
10875 source file although the full declaration of @code{struct MyType} is in
10876 another source file. The default is on.
10877
10878 A change in the setting of this subcommand will not take effect until
10879 the next time symbols for a file are loaded.
10880
10881 @item set opaque-type-resolution off
10882 Tell @value{GDBN} not to resolve opaque types. In this case, the type
10883 is printed as follows:
10884 @smallexample
10885 @{<no data fields>@}
10886 @end smallexample
10887
10888 @kindex show opaque-type-resolution
10889 @item show opaque-type-resolution
10890 Show whether opaque types are resolved or not.
10891
10892 @kindex maint print symbols
10893 @cindex symbol dump
10894 @kindex maint print psymbols
10895 @cindex partial symbol dump
10896 @item maint print symbols @var{filename}
10897 @itemx maint print psymbols @var{filename}
10898 @itemx maint print msymbols @var{filename}
10899 Write a dump of debugging symbol data into the file @var{filename}.
10900 These commands are used to debug the @value{GDBN} symbol-reading code. Only
10901 symbols with debugging data are included. If you use @samp{maint print
10902 symbols}, @value{GDBN} includes all the symbols for which it has already
10903 collected full details: that is, @var{filename} reflects symbols for
10904 only those files whose symbols @value{GDBN} has read. You can use the
10905 command @code{info sources} to find out which files these are. If you
10906 use @samp{maint print psymbols} instead, the dump shows information about
10907 symbols that @value{GDBN} only knows partially---that is, symbols defined in
10908 files that @value{GDBN} has skimmed, but not yet read completely. Finally,
10909 @samp{maint print msymbols} dumps just the minimal symbol information
10910 required for each object file from which @value{GDBN} has read some symbols.
10911 @xref{Files, ,Commands to specify files}, for a discussion of how
10912 @value{GDBN} reads symbols (in the description of @code{symbol-file}).
10913
10914 @kindex maint info symtabs
10915 @kindex maint info psymtabs
10916 @cindex listing @value{GDBN}'s internal symbol tables
10917 @cindex symbol tables, listing @value{GDBN}'s internal
10918 @cindex full symbol tables, listing @value{GDBN}'s internal
10919 @cindex partial symbol tables, listing @value{GDBN}'s internal
10920 @item maint info symtabs @r{[} @var{regexp} @r{]}
10921 @itemx maint info psymtabs @r{[} @var{regexp} @r{]}
10922
10923 List the @code{struct symtab} or @code{struct partial_symtab}
10924 structures whose names match @var{regexp}. If @var{regexp} is not
10925 given, list them all. The output includes expressions which you can
10926 copy into a @value{GDBN} debugging this one to examine a particular
10927 structure in more detail. For example:
10928
10929 @smallexample
10930 (@value{GDBP}) maint info psymtabs dwarf2read
10931 @{ objfile /home/gnu/build/gdb/gdb
10932 ((struct objfile *) 0x82e69d0)
10933 @{ psymtab /home/gnu/src/gdb/dwarf2read.c
10934 ((struct partial_symtab *) 0x8474b10)
10935 readin no
10936 fullname (null)
10937 text addresses 0x814d3c8 -- 0x8158074
10938 globals (* (struct partial_symbol **) 0x8507a08 @@ 9)
10939 statics (* (struct partial_symbol **) 0x40e95b78 @@ 2882)
10940 dependencies (none)
10941 @}
10942 @}
10943 (@value{GDBP}) maint info symtabs
10944 (@value{GDBP})
10945 @end smallexample
10946 @noindent
10947 We see that there is one partial symbol table whose filename contains
10948 the string @samp{dwarf2read}, belonging to the @samp{gdb} executable;
10949 and we see that @value{GDBN} has not read in any symtabs yet at all.
10950 If we set a breakpoint on a function, that will cause @value{GDBN} to
10951 read the symtab for the compilation unit containing that function:
10952
10953 @smallexample
10954 (@value{GDBP}) break dwarf2_psymtab_to_symtab
10955 Breakpoint 1 at 0x814e5da: file /home/gnu/src/gdb/dwarf2read.c,
10956 line 1574.
10957 (@value{GDBP}) maint info symtabs
10958 @{ objfile /home/gnu/build/gdb/gdb
10959 ((struct objfile *) 0x82e69d0)
10960 @{ symtab /home/gnu/src/gdb/dwarf2read.c
10961 ((struct symtab *) 0x86c1f38)
10962 dirname (null)
10963 fullname (null)
10964 blockvector ((struct blockvector *) 0x86c1bd0) (primary)
10965 debugformat DWARF 2
10966 @}
10967 @}
10968 (@value{GDBP})
10969 @end smallexample
10970 @end table
10971
10972
10973 @node Altering
10974 @chapter Altering Execution
10975
10976 Once you think you have found an error in your program, you might want to
10977 find out for certain whether correcting the apparent error would lead to
10978 correct results in the rest of the run. You can find the answer by
10979 experiment, using the @value{GDBN} features for altering execution of the
10980 program.
10981
10982 For example, you can store new values into variables or memory
10983 locations, give your program a signal, restart it at a different
10984 address, or even return prematurely from a function.
10985
10986 @menu
10987 * Assignment:: Assignment to variables
10988 * Jumping:: Continuing at a different address
10989 * Signaling:: Giving your program a signal
10990 * Returning:: Returning from a function
10991 * Calling:: Calling your program's functions
10992 * Patching:: Patching your program
10993 @end menu
10994
10995 @node Assignment
10996 @section Assignment to variables
10997
10998 @cindex assignment
10999 @cindex setting variables
11000 To alter the value of a variable, evaluate an assignment expression.
11001 @xref{Expressions, ,Expressions}. For example,
11002
11003 @smallexample
11004 print x=4
11005 @end smallexample
11006
11007 @noindent
11008 stores the value 4 into the variable @code{x}, and then prints the
11009 value of the assignment expression (which is 4).
11010 @xref{Languages, ,Using @value{GDBN} with Different Languages}, for more
11011 information on operators in supported languages.
11012
11013 @kindex set variable
11014 @cindex variables, setting
11015 If you are not interested in seeing the value of the assignment, use the
11016 @code{set} command instead of the @code{print} command. @code{set} is
11017 really the same as @code{print} except that the expression's value is
11018 not printed and is not put in the value history (@pxref{Value History,
11019 ,Value history}). The expression is evaluated only for its effects.
11020
11021 If the beginning of the argument string of the @code{set} command
11022 appears identical to a @code{set} subcommand, use the @code{set
11023 variable} command instead of just @code{set}. This command is identical
11024 to @code{set} except for its lack of subcommands. For example, if your
11025 program has a variable @code{width}, you get an error if you try to set
11026 a new value with just @samp{set width=13}, because @value{GDBN} has the
11027 command @code{set width}:
11028
11029 @smallexample
11030 (@value{GDBP}) whatis width
11031 type = double
11032 (@value{GDBP}) p width
11033 $4 = 13
11034 (@value{GDBP}) set width=47
11035 Invalid syntax in expression.
11036 @end smallexample
11037
11038 @noindent
11039 The invalid expression, of course, is @samp{=47}. In
11040 order to actually set the program's variable @code{width}, use
11041
11042 @smallexample
11043 (@value{GDBP}) set var width=47
11044 @end smallexample
11045
11046 Because the @code{set} command has many subcommands that can conflict
11047 with the names of program variables, it is a good idea to use the
11048 @code{set variable} command instead of just @code{set}. For example, if
11049 your program has a variable @code{g}, you run into problems if you try
11050 to set a new value with just @samp{set g=4}, because @value{GDBN} has
11051 the command @code{set gnutarget}, abbreviated @code{set g}:
11052
11053 @smallexample
11054 @group
11055 (@value{GDBP}) whatis g
11056 type = double
11057 (@value{GDBP}) p g
11058 $1 = 1
11059 (@value{GDBP}) set g=4
11060 (@value{GDBP}) p g
11061 $2 = 1
11062 (@value{GDBP}) r
11063 The program being debugged has been started already.
11064 Start it from the beginning? (y or n) y
11065 Starting program: /home/smith/cc_progs/a.out
11066 "/home/smith/cc_progs/a.out": can't open to read symbols:
11067 Invalid bfd target.
11068 (@value{GDBP}) show g
11069 The current BFD target is "=4".
11070 @end group
11071 @end smallexample
11072
11073 @noindent
11074 The program variable @code{g} did not change, and you silently set the
11075 @code{gnutarget} to an invalid value. In order to set the variable
11076 @code{g}, use
11077
11078 @smallexample
11079 (@value{GDBP}) set var g=4
11080 @end smallexample
11081
11082 @value{GDBN} allows more implicit conversions in assignments than C; you can
11083 freely store an integer value into a pointer variable or vice versa,
11084 and you can convert any structure to any other structure that is the
11085 same length or shorter.
11086 @comment FIXME: how do structs align/pad in these conversions?
11087 @comment /doc@cygnus.com 18dec1990
11088
11089 To store values into arbitrary places in memory, use the @samp{@{@dots{}@}}
11090 construct to generate a value of specified type at a specified address
11091 (@pxref{Expressions, ,Expressions}). For example, @code{@{int@}0x83040} refers
11092 to memory location @code{0x83040} as an integer (which implies a certain size
11093 and representation in memory), and
11094
11095 @smallexample
11096 set @{int@}0x83040 = 4
11097 @end smallexample
11098
11099 @noindent
11100 stores the value 4 into that memory location.
11101
11102 @node Jumping
11103 @section Continuing at a different address
11104
11105 Ordinarily, when you continue your program, you do so at the place where
11106 it stopped, with the @code{continue} command. You can instead continue at
11107 an address of your own choosing, with the following commands:
11108
11109 @table @code
11110 @kindex jump
11111 @item jump @var{linespec}
11112 Resume execution at line @var{linespec}. Execution stops again
11113 immediately if there is a breakpoint there. @xref{List, ,Printing
11114 source lines}, for a description of the different forms of
11115 @var{linespec}. It is common practice to use the @code{tbreak} command
11116 in conjunction with @code{jump}. @xref{Set Breaks, ,Setting
11117 breakpoints}.
11118
11119 The @code{jump} command does not change the current stack frame, or
11120 the stack pointer, or the contents of any memory location or any
11121 register other than the program counter. If line @var{linespec} is in
11122 a different function from the one currently executing, the results may
11123 be bizarre if the two functions expect different patterns of arguments or
11124 of local variables. For this reason, the @code{jump} command requests
11125 confirmation if the specified line is not in the function currently
11126 executing. However, even bizarre results are predictable if you are
11127 well acquainted with the machine-language code of your program.
11128
11129 @item jump *@var{address}
11130 Resume execution at the instruction at address @var{address}.
11131 @end table
11132
11133 @c Doesn't work on HP-UX; have to set $pcoqh and $pcoqt.
11134 On many systems, you can get much the same effect as the @code{jump}
11135 command by storing a new value into the register @code{$pc}. The
11136 difference is that this does not start your program running; it only
11137 changes the address of where it @emph{will} run when you continue. For
11138 example,
11139
11140 @smallexample
11141 set $pc = 0x485
11142 @end smallexample
11143
11144 @noindent
11145 makes the next @code{continue} command or stepping command execute at
11146 address @code{0x485}, rather than at the address where your program stopped.
11147 @xref{Continuing and Stepping, ,Continuing and stepping}.
11148
11149 The most common occasion to use the @code{jump} command is to back
11150 up---perhaps with more breakpoints set---over a portion of a program
11151 that has already executed, in order to examine its execution in more
11152 detail.
11153
11154 @c @group
11155 @node Signaling
11156 @section Giving your program a signal
11157 @cindex deliver a signal to a program
11158
11159 @table @code
11160 @kindex signal
11161 @item signal @var{signal}
11162 Resume execution where your program stopped, but immediately give it the
11163 signal @var{signal}. @var{signal} can be the name or the number of a
11164 signal. For example, on many systems @code{signal 2} and @code{signal
11165 SIGINT} are both ways of sending an interrupt signal.
11166
11167 Alternatively, if @var{signal} is zero, continue execution without
11168 giving a signal. This is useful when your program stopped on account of
11169 a signal and would ordinary see the signal when resumed with the
11170 @code{continue} command; @samp{signal 0} causes it to resume without a
11171 signal.
11172
11173 @code{signal} does not repeat when you press @key{RET} a second time
11174 after executing the command.
11175 @end table
11176 @c @end group
11177
11178 Invoking the @code{signal} command is not the same as invoking the
11179 @code{kill} utility from the shell. Sending a signal with @code{kill}
11180 causes @value{GDBN} to decide what to do with the signal depending on
11181 the signal handling tables (@pxref{Signals}). The @code{signal} command
11182 passes the signal directly to your program.
11183
11184
11185 @node Returning
11186 @section Returning from a function
11187
11188 @table @code
11189 @cindex returning from a function
11190 @kindex return
11191 @item return
11192 @itemx return @var{expression}
11193 You can cancel execution of a function call with the @code{return}
11194 command. If you give an
11195 @var{expression} argument, its value is used as the function's return
11196 value.
11197 @end table
11198
11199 When you use @code{return}, @value{GDBN} discards the selected stack frame
11200 (and all frames within it). You can think of this as making the
11201 discarded frame return prematurely. If you wish to specify a value to
11202 be returned, give that value as the argument to @code{return}.
11203
11204 This pops the selected stack frame (@pxref{Selection, ,Selecting a
11205 frame}), and any other frames inside of it, leaving its caller as the
11206 innermost remaining frame. That frame becomes selected. The
11207 specified value is stored in the registers used for returning values
11208 of functions.
11209
11210 The @code{return} command does not resume execution; it leaves the
11211 program stopped in the state that would exist if the function had just
11212 returned. In contrast, the @code{finish} command (@pxref{Continuing
11213 and Stepping, ,Continuing and stepping}) resumes execution until the
11214 selected stack frame returns naturally.
11215
11216 @node Calling
11217 @section Calling program functions
11218
11219 @table @code
11220 @cindex calling functions
11221 @cindex inferior functions, calling
11222 @item print @var{expr}
11223 Evaluate the expression @var{expr} and display the resuling value.
11224 @var{expr} may include calls to functions in the program being
11225 debugged.
11226
11227 @kindex call
11228 @item call @var{expr}
11229 Evaluate the expression @var{expr} without displaying @code{void}
11230 returned values.
11231
11232 You can use this variant of the @code{print} command if you want to
11233 execute a function from your program that does not return anything
11234 (a.k.a.@: @dfn{a void function}), but without cluttering the output
11235 with @code{void} returned values that @value{GDBN} will otherwise
11236 print. If the result is not void, it is printed and saved in the
11237 value history.
11238 @end table
11239
11240 It is possible for the function you call via the @code{print} or
11241 @code{call} command to generate a signal (e.g., if there's a bug in
11242 the function, or if you passed it incorrect arguments). What happens
11243 in that case is controlled by the @code{set unwindonsignal} command.
11244
11245 @table @code
11246 @item set unwindonsignal
11247 @kindex set unwindonsignal
11248 @cindex unwind stack in called functions
11249 @cindex call dummy stack unwinding
11250 Set unwinding of the stack if a signal is received while in a function
11251 that @value{GDBN} called in the program being debugged. If set to on,
11252 @value{GDBN} unwinds the stack it created for the call and restores
11253 the context to what it was before the call. If set to off (the
11254 default), @value{GDBN} stops in the frame where the signal was
11255 received.
11256
11257 @item show unwindonsignal
11258 @kindex show unwindonsignal
11259 Show the current setting of stack unwinding in the functions called by
11260 @value{GDBN}.
11261 @end table
11262
11263 @cindex weak alias functions
11264 Sometimes, a function you wish to call is actually a @dfn{weak alias}
11265 for another function. In such case, @value{GDBN} might not pick up
11266 the type information, including the types of the function arguments,
11267 which causes @value{GDBN} to call the inferior function incorrectly.
11268 As a result, the called function will function erroneously and may
11269 even crash. A solution to that is to use the name of the aliased
11270 function instead.
11271
11272 @node Patching
11273 @section Patching programs
11274
11275 @cindex patching binaries
11276 @cindex writing into executables
11277 @cindex writing into corefiles
11278
11279 By default, @value{GDBN} opens the file containing your program's
11280 executable code (or the corefile) read-only. This prevents accidental
11281 alterations to machine code; but it also prevents you from intentionally
11282 patching your program's binary.
11283
11284 If you'd like to be able to patch the binary, you can specify that
11285 explicitly with the @code{set write} command. For example, you might
11286 want to turn on internal debugging flags, or even to make emergency
11287 repairs.
11288
11289 @table @code
11290 @kindex set write
11291 @item set write on
11292 @itemx set write off
11293 If you specify @samp{set write on}, @value{GDBN} opens executable and
11294 core files for both reading and writing; if you specify @samp{set write
11295 off} (the default), @value{GDBN} opens them read-only.
11296
11297 If you have already loaded a file, you must load it again (using the
11298 @code{exec-file} or @code{core-file} command) after changing @code{set
11299 write}, for your new setting to take effect.
11300
11301 @item show write
11302 @kindex show write
11303 Display whether executable files and core files are opened for writing
11304 as well as reading.
11305 @end table
11306
11307 @node GDB Files
11308 @chapter @value{GDBN} Files
11309
11310 @value{GDBN} needs to know the file name of the program to be debugged,
11311 both in order to read its symbol table and in order to start your
11312 program. To debug a core dump of a previous run, you must also tell
11313 @value{GDBN} the name of the core dump file.
11314
11315 @menu
11316 * Files:: Commands to specify files
11317 * Separate Debug Files:: Debugging information in separate files
11318 * Symbol Errors:: Errors reading symbol files
11319 @end menu
11320
11321 @node Files
11322 @section Commands to specify files
11323
11324 @cindex symbol table
11325 @cindex core dump file
11326
11327 You may want to specify executable and core dump file names. The usual
11328 way to do this is at start-up time, using the arguments to
11329 @value{GDBN}'s start-up commands (@pxref{Invocation, , Getting In and
11330 Out of @value{GDBN}}).
11331
11332 Occasionally it is necessary to change to a different file during a
11333 @value{GDBN} session. Or you may run @value{GDBN} and forget to
11334 specify a file you want to use. Or you are debugging a remote target
11335 via @code{gdbserver} (@pxref{Server, file}). In these situations the
11336 @value{GDBN} commands to specify new files are useful.
11337
11338 @table @code
11339 @cindex executable file
11340 @kindex file
11341 @item file @var{filename}
11342 Use @var{filename} as the program to be debugged. It is read for its
11343 symbols and for the contents of pure memory. It is also the program
11344 executed when you use the @code{run} command. If you do not specify a
11345 directory and the file is not found in the @value{GDBN} working directory,
11346 @value{GDBN} uses the environment variable @code{PATH} as a list of
11347 directories to search, just as the shell does when looking for a program
11348 to run. You can change the value of this variable, for both @value{GDBN}
11349 and your program, using the @code{path} command.
11350
11351 @cindex unlinked object files
11352 @cindex patching object files
11353 You can load unlinked object @file{.o} files into @value{GDBN} using
11354 the @code{file} command. You will not be able to ``run'' an object
11355 file, but you can disassemble functions and inspect variables. Also,
11356 if the underlying BFD functionality supports it, you could use
11357 @kbd{gdb -write} to patch object files using this technique. Note
11358 that @value{GDBN} can neither interpret nor modify relocations in this
11359 case, so branches and some initialized variables will appear to go to
11360 the wrong place. But this feature is still handy from time to time.
11361
11362 @item file
11363 @code{file} with no argument makes @value{GDBN} discard any information it
11364 has on both executable file and the symbol table.
11365
11366 @kindex exec-file
11367 @item exec-file @r{[} @var{filename} @r{]}
11368 Specify that the program to be run (but not the symbol table) is found
11369 in @var{filename}. @value{GDBN} searches the environment variable @code{PATH}
11370 if necessary to locate your program. Omitting @var{filename} means to
11371 discard information on the executable file.
11372
11373 @kindex symbol-file
11374 @item symbol-file @r{[} @var{filename} @r{]}
11375 Read symbol table information from file @var{filename}. @code{PATH} is
11376 searched when necessary. Use the @code{file} command to get both symbol
11377 table and program to run from the same file.
11378
11379 @code{symbol-file} with no argument clears out @value{GDBN} information on your
11380 program's symbol table.
11381
11382 The @code{symbol-file} command causes @value{GDBN} to forget the contents of
11383 some breakpoints and auto-display expressions. This is because they may
11384 contain pointers to the internal data recording symbols and data types,
11385 which are part of the old symbol table data being discarded inside
11386 @value{GDBN}.
11387
11388 @code{symbol-file} does not repeat if you press @key{RET} again after
11389 executing it once.
11390
11391 When @value{GDBN} is configured for a particular environment, it
11392 understands debugging information in whatever format is the standard
11393 generated for that environment; you may use either a @sc{gnu} compiler, or
11394 other compilers that adhere to the local conventions.
11395 Best results are usually obtained from @sc{gnu} compilers; for example,
11396 using @code{@value{GCC}} you can generate debugging information for
11397 optimized code.
11398
11399 For most kinds of object files, with the exception of old SVR3 systems
11400 using COFF, the @code{symbol-file} command does not normally read the
11401 symbol table in full right away. Instead, it scans the symbol table
11402 quickly to find which source files and which symbols are present. The
11403 details are read later, one source file at a time, as they are needed.
11404
11405 The purpose of this two-stage reading strategy is to make @value{GDBN}
11406 start up faster. For the most part, it is invisible except for
11407 occasional pauses while the symbol table details for a particular source
11408 file are being read. (The @code{set verbose} command can turn these
11409 pauses into messages if desired. @xref{Messages/Warnings, ,Optional
11410 warnings and messages}.)
11411
11412 We have not implemented the two-stage strategy for COFF yet. When the
11413 symbol table is stored in COFF format, @code{symbol-file} reads the
11414 symbol table data in full right away. Note that ``stabs-in-COFF''
11415 still does the two-stage strategy, since the debug info is actually
11416 in stabs format.
11417
11418 @kindex readnow
11419 @cindex reading symbols immediately
11420 @cindex symbols, reading immediately
11421 @item symbol-file @var{filename} @r{[} -readnow @r{]}
11422 @itemx file @var{filename} @r{[} -readnow @r{]}
11423 You can override the @value{GDBN} two-stage strategy for reading symbol
11424 tables by using the @samp{-readnow} option with any of the commands that
11425 load symbol table information, if you want to be sure @value{GDBN} has the
11426 entire symbol table available.
11427
11428 @c FIXME: for now no mention of directories, since this seems to be in
11429 @c flux. 13mar1992 status is that in theory GDB would look either in
11430 @c current dir or in same dir as myprog; but issues like competing
11431 @c GDB's, or clutter in system dirs, mean that in practice right now
11432 @c only current dir is used. FFish says maybe a special GDB hierarchy
11433 @c (eg rooted in val of env var GDBSYMS) could exist for mappable symbol
11434 @c files.
11435
11436 @kindex core-file
11437 @item core-file @r{[}@var{filename}@r{]}
11438 @itemx core
11439 Specify the whereabouts of a core dump file to be used as the ``contents
11440 of memory''. Traditionally, core files contain only some parts of the
11441 address space of the process that generated them; @value{GDBN} can access the
11442 executable file itself for other parts.
11443
11444 @code{core-file} with no argument specifies that no core file is
11445 to be used.
11446
11447 Note that the core file is ignored when your program is actually running
11448 under @value{GDBN}. So, if you have been running your program and you
11449 wish to debug a core file instead, you must kill the subprocess in which
11450 the program is running. To do this, use the @code{kill} command
11451 (@pxref{Kill Process, ,Killing the child process}).
11452
11453 @kindex add-symbol-file
11454 @cindex dynamic linking
11455 @item add-symbol-file @var{filename} @var{address}
11456 @itemx add-symbol-file @var{filename} @var{address} @r{[} -readnow @r{]}
11457 @itemx add-symbol-file @var{filename} @r{-s}@var{section} @var{address} @dots{}
11458 The @code{add-symbol-file} command reads additional symbol table
11459 information from the file @var{filename}. You would use this command
11460 when @var{filename} has been dynamically loaded (by some other means)
11461 into the program that is running. @var{address} should be the memory
11462 address at which the file has been loaded; @value{GDBN} cannot figure
11463 this out for itself. You can additionally specify an arbitrary number
11464 of @samp{@r{-s}@var{section} @var{address}} pairs, to give an explicit
11465 section name and base address for that section. You can specify any
11466 @var{address} as an expression.
11467
11468 The symbol table of the file @var{filename} is added to the symbol table
11469 originally read with the @code{symbol-file} command. You can use the
11470 @code{add-symbol-file} command any number of times; the new symbol data
11471 thus read keeps adding to the old. To discard all old symbol data
11472 instead, use the @code{symbol-file} command without any arguments.
11473
11474 @cindex relocatable object files, reading symbols from
11475 @cindex object files, relocatable, reading symbols from
11476 @cindex reading symbols from relocatable object files
11477 @cindex symbols, reading from relocatable object files
11478 @cindex @file{.o} files, reading symbols from
11479 Although @var{filename} is typically a shared library file, an
11480 executable file, or some other object file which has been fully
11481 relocated for loading into a process, you can also load symbolic
11482 information from relocatable @file{.o} files, as long as:
11483
11484 @itemize @bullet
11485 @item
11486 the file's symbolic information refers only to linker symbols defined in
11487 that file, not to symbols defined by other object files,
11488 @item
11489 every section the file's symbolic information refers to has actually
11490 been loaded into the inferior, as it appears in the file, and
11491 @item
11492 you can determine the address at which every section was loaded, and
11493 provide these to the @code{add-symbol-file} command.
11494 @end itemize
11495
11496 @noindent
11497 Some embedded operating systems, like Sun Chorus and VxWorks, can load
11498 relocatable files into an already running program; such systems
11499 typically make the requirements above easy to meet. However, it's
11500 important to recognize that many native systems use complex link
11501 procedures (@code{.linkonce} section factoring and C@t{++} constructor table
11502 assembly, for example) that make the requirements difficult to meet. In
11503 general, one cannot assume that using @code{add-symbol-file} to read a
11504 relocatable object file's symbolic information will have the same effect
11505 as linking the relocatable object file into the program in the normal
11506 way.
11507
11508 @code{add-symbol-file} does not repeat if you press @key{RET} after using it.
11509
11510 @kindex add-symbol-file-from-memory
11511 @cindex @code{syscall DSO}
11512 @cindex load symbols from memory
11513 @item add-symbol-file-from-memory @var{address}
11514 Load symbols from the given @var{address} in a dynamically loaded
11515 object file whose image is mapped directly into the inferior's memory.
11516 For example, the Linux kernel maps a @code{syscall DSO} into each
11517 process's address space; this DSO provides kernel-specific code for
11518 some system calls. The argument can be any expression whose
11519 evaluation yields the address of the file's shared object file header.
11520 For this command to work, you must have used @code{symbol-file} or
11521 @code{exec-file} commands in advance.
11522
11523 @kindex add-shared-symbol-files
11524 @kindex assf
11525 @item add-shared-symbol-files @var{library-file}
11526 @itemx assf @var{library-file}
11527 The @code{add-shared-symbol-files} command can currently be used only
11528 in the Cygwin build of @value{GDBN} on MS-Windows OS, where it is an
11529 alias for the @code{dll-symbols} command (@pxref{Cygwin Native}).
11530 @value{GDBN} automatically looks for shared libraries, however if
11531 @value{GDBN} does not find yours, you can invoke
11532 @code{add-shared-symbol-files}. It takes one argument: the shared
11533 library's file name. @code{assf} is a shorthand alias for
11534 @code{add-shared-symbol-files}.
11535
11536 @kindex section
11537 @item section @var{section} @var{addr}
11538 The @code{section} command changes the base address of the named
11539 @var{section} of the exec file to @var{addr}. This can be used if the
11540 exec file does not contain section addresses, (such as in the
11541 @code{a.out} format), or when the addresses specified in the file
11542 itself are wrong. Each section must be changed separately. The
11543 @code{info files} command, described below, lists all the sections and
11544 their addresses.
11545
11546 @kindex info files
11547 @kindex info target
11548 @item info files
11549 @itemx info target
11550 @code{info files} and @code{info target} are synonymous; both print the
11551 current target (@pxref{Targets, ,Specifying a Debugging Target}),
11552 including the names of the executable and core dump files currently in
11553 use by @value{GDBN}, and the files from which symbols were loaded. The
11554 command @code{help target} lists all possible targets rather than
11555 current ones.
11556
11557 @kindex maint info sections
11558 @item maint info sections
11559 Another command that can give you extra information about program sections
11560 is @code{maint info sections}. In addition to the section information
11561 displayed by @code{info files}, this command displays the flags and file
11562 offset of each section in the executable and core dump files. In addition,
11563 @code{maint info sections} provides the following command options (which
11564 may be arbitrarily combined):
11565
11566 @table @code
11567 @item ALLOBJ
11568 Display sections for all loaded object files, including shared libraries.
11569 @item @var{sections}
11570 Display info only for named @var{sections}.
11571 @item @var{section-flags}
11572 Display info only for sections for which @var{section-flags} are true.
11573 The section flags that @value{GDBN} currently knows about are:
11574 @table @code
11575 @item ALLOC
11576 Section will have space allocated in the process when loaded.
11577 Set for all sections except those containing debug information.
11578 @item LOAD
11579 Section will be loaded from the file into the child process memory.
11580 Set for pre-initialized code and data, clear for @code{.bss} sections.
11581 @item RELOC
11582 Section needs to be relocated before loading.
11583 @item READONLY
11584 Section cannot be modified by the child process.
11585 @item CODE
11586 Section contains executable code only.
11587 @item DATA
11588 Section contains data only (no executable code).
11589 @item ROM
11590 Section will reside in ROM.
11591 @item CONSTRUCTOR
11592 Section contains data for constructor/destructor lists.
11593 @item HAS_CONTENTS
11594 Section is not empty.
11595 @item NEVER_LOAD
11596 An instruction to the linker to not output the section.
11597 @item COFF_SHARED_LIBRARY
11598 A notification to the linker that the section contains
11599 COFF shared library information.
11600 @item IS_COMMON
11601 Section contains common symbols.
11602 @end table
11603 @end table
11604 @kindex set trust-readonly-sections
11605 @cindex read-only sections
11606 @item set trust-readonly-sections on
11607 Tell @value{GDBN} that readonly sections in your object file
11608 really are read-only (i.e.@: that their contents will not change).
11609 In that case, @value{GDBN} can fetch values from these sections
11610 out of the object file, rather than from the target program.
11611 For some targets (notably embedded ones), this can be a significant
11612 enhancement to debugging performance.
11613
11614 The default is off.
11615
11616 @item set trust-readonly-sections off
11617 Tell @value{GDBN} not to trust readonly sections. This means that
11618 the contents of the section might change while the program is running,
11619 and must therefore be fetched from the target when needed.
11620
11621 @item show trust-readonly-sections
11622 Show the current setting of trusting readonly sections.
11623 @end table
11624
11625 All file-specifying commands allow both absolute and relative file names
11626 as arguments. @value{GDBN} always converts the file name to an absolute file
11627 name and remembers it that way.
11628
11629 @cindex shared libraries
11630 @value{GDBN} supports GNU/Linux, MS-Windows, HP-UX, SunOS, SVr4, Irix,
11631 and IBM RS/6000 AIX shared libraries.
11632
11633 @value{GDBN} automatically loads symbol definitions from shared libraries
11634 when you use the @code{run} command, or when you examine a core file.
11635 (Before you issue the @code{run} command, @value{GDBN} does not understand
11636 references to a function in a shared library, however---unless you are
11637 debugging a core file).
11638
11639 On HP-UX, if the program loads a library explicitly, @value{GDBN}
11640 automatically loads the symbols at the time of the @code{shl_load} call.
11641
11642 @c FIXME: some @value{GDBN} release may permit some refs to undef
11643 @c FIXME...symbols---eg in a break cmd---assuming they are from a shared
11644 @c FIXME...lib; check this from time to time when updating manual
11645
11646 There are times, however, when you may wish to not automatically load
11647 symbol definitions from shared libraries, such as when they are
11648 particularly large or there are many of them.
11649
11650 To control the automatic loading of shared library symbols, use the
11651 commands:
11652
11653 @table @code
11654 @kindex set auto-solib-add
11655 @item set auto-solib-add @var{mode}
11656 If @var{mode} is @code{on}, symbols from all shared object libraries
11657 will be loaded automatically when the inferior begins execution, you
11658 attach to an independently started inferior, or when the dynamic linker
11659 informs @value{GDBN} that a new library has been loaded. If @var{mode}
11660 is @code{off}, symbols must be loaded manually, using the
11661 @code{sharedlibrary} command. The default value is @code{on}.
11662
11663 @cindex memory used for symbol tables
11664 If your program uses lots of shared libraries with debug info that
11665 takes large amounts of memory, you can decrease the @value{GDBN}
11666 memory footprint by preventing it from automatically loading the
11667 symbols from shared libraries. To that end, type @kbd{set
11668 auto-solib-add off} before running the inferior, then load each
11669 library whose debug symbols you do need with @kbd{sharedlibrary
11670 @var{regexp}}, where @var{regexp} is a regular expresion that matches
11671 the libraries whose symbols you want to be loaded.
11672
11673 @kindex show auto-solib-add
11674 @item show auto-solib-add
11675 Display the current autoloading mode.
11676 @end table
11677
11678 @cindex load shared library
11679 To explicitly load shared library symbols, use the @code{sharedlibrary}
11680 command:
11681
11682 @table @code
11683 @kindex info sharedlibrary
11684 @kindex info share
11685 @item info share
11686 @itemx info sharedlibrary
11687 Print the names of the shared libraries which are currently loaded.
11688
11689 @kindex sharedlibrary
11690 @kindex share
11691 @item sharedlibrary @var{regex}
11692 @itemx share @var{regex}
11693 Load shared object library symbols for files matching a
11694 Unix regular expression.
11695 As with files loaded automatically, it only loads shared libraries
11696 required by your program for a core file or after typing @code{run}. If
11697 @var{regex} is omitted all shared libraries required by your program are
11698 loaded.
11699
11700 @item nosharedlibrary
11701 @kindex nosharedlibrary
11702 @cindex unload symbols from shared libraries
11703 Unload all shared object library symbols. This discards all symbols
11704 that have been loaded from all shared libraries. Symbols from shared
11705 libraries that were loaded by explicit user requests are not
11706 discarded.
11707 @end table
11708
11709 Sometimes you may wish that @value{GDBN} stops and gives you control
11710 when any of shared library events happen. Use the @code{set
11711 stop-on-solib-events} command for this:
11712
11713 @table @code
11714 @item set stop-on-solib-events
11715 @kindex set stop-on-solib-events
11716 This command controls whether @value{GDBN} should give you control
11717 when the dynamic linker notifies it about some shared library event.
11718 The most common event of interest is loading or unloading of a new
11719 shared library.
11720
11721 @item show stop-on-solib-events
11722 @kindex show stop-on-solib-events
11723 Show whether @value{GDBN} stops and gives you control when shared
11724 library events happen.
11725 @end table
11726
11727 Shared libraries are also supported in many cross or remote debugging
11728 configurations. A copy of the target's libraries need to be present on the
11729 host system; they need to be the same as the target libraries, although the
11730 copies on the target can be stripped as long as the copies on the host are
11731 not.
11732
11733 @cindex where to look for shared libraries
11734 For remote debugging, you need to tell @value{GDBN} where the target
11735 libraries are, so that it can load the correct copies---otherwise, it
11736 may try to load the host's libraries. @value{GDBN} has two variables
11737 to specify the search directories for target libraries.
11738
11739 @table @code
11740 @cindex prefix for shared library file names
11741 @kindex set solib-absolute-prefix
11742 @item set solib-absolute-prefix @var{path}
11743 If this variable is set, @var{path} will be used as a prefix for any
11744 absolute shared library paths; many runtime loaders store the absolute
11745 paths to the shared library in the target program's memory. If you use
11746 @samp{solib-absolute-prefix} to find shared libraries, they need to be laid
11747 out in the same way that they are on the target, with e.g.@: a
11748 @file{/usr/lib} hierarchy under @var{path}.
11749
11750 @cindex default value of @samp{solib-absolute-prefix}
11751 @cindex @samp{--with-sysroot}
11752 You can set the default value of @samp{solib-absolute-prefix} by using the
11753 configure-time @samp{--with-sysroot} option.
11754
11755 @kindex show solib-absolute-prefix
11756 @item show solib-absolute-prefix
11757 Display the current shared library prefix.
11758
11759 @kindex set solib-search-path
11760 @item set solib-search-path @var{path}
11761 If this variable is set, @var{path} is a colon-separated list of directories
11762 to search for shared libraries. @samp{solib-search-path} is used after
11763 @samp{solib-absolute-prefix} fails to locate the library, or if the path to
11764 the library is relative instead of absolute. If you want to use
11765 @samp{solib-search-path} instead of @samp{solib-absolute-prefix}, be sure to
11766 set @samp{solib-absolute-prefix} to a nonexistant directory to prevent
11767 @value{GDBN} from finding your host's libraries.
11768
11769 @kindex show solib-search-path
11770 @item show solib-search-path
11771 Display the current shared library search path.
11772 @end table
11773
11774
11775 @node Separate Debug Files
11776 @section Debugging Information in Separate Files
11777 @cindex separate debugging information files
11778 @cindex debugging information in separate files
11779 @cindex @file{.debug} subdirectories
11780 @cindex debugging information directory, global
11781 @cindex global debugging information directory
11782
11783 @value{GDBN} allows you to put a program's debugging information in a
11784 file separate from the executable itself, in a way that allows
11785 @value{GDBN} to find and load the debugging information automatically.
11786 Since debugging information can be very large --- sometimes larger
11787 than the executable code itself --- some systems distribute debugging
11788 information for their executables in separate files, which users can
11789 install only when they need to debug a problem.
11790
11791 If an executable's debugging information has been extracted to a
11792 separate file, the executable should contain a @dfn{debug link} giving
11793 the name of the debugging information file (with no directory
11794 components), and a checksum of its contents. (The exact form of a
11795 debug link is described below.) If the full name of the directory
11796 containing the executable is @var{execdir}, and the executable has a
11797 debug link that specifies the name @var{debugfile}, then @value{GDBN}
11798 will automatically search for the debugging information file in three
11799 places:
11800
11801 @itemize @bullet
11802 @item
11803 the directory containing the executable file (that is, it will look
11804 for a file named @file{@var{execdir}/@var{debugfile}},
11805 @item
11806 a subdirectory of that directory named @file{.debug} (that is, the
11807 file @file{@var{execdir}/.debug/@var{debugfile}}, and
11808 @item
11809 a subdirectory of the global debug file directory that includes the
11810 executable's full path, and the name from the link (that is, the file
11811 @file{@var{globaldebugdir}/@var{execdir}/@var{debugfile}}, where
11812 @var{globaldebugdir} is the global debug file directory, and
11813 @var{execdir} has been turned into a relative path).
11814 @end itemize
11815 @noindent
11816 @value{GDBN} checks under each of these names for a debugging
11817 information file whose checksum matches that given in the link, and
11818 reads the debugging information from the first one it finds.
11819
11820 So, for example, if you ask @value{GDBN} to debug @file{/usr/bin/ls},
11821 which has a link containing the name @file{ls.debug}, and the global
11822 debug directory is @file{/usr/lib/debug}, then @value{GDBN} will look
11823 for debug information in @file{/usr/bin/ls.debug},
11824 @file{/usr/bin/.debug/ls.debug}, and
11825 @file{/usr/lib/debug/usr/bin/ls.debug}.
11826
11827 You can set the global debugging info directory's name, and view the
11828 name @value{GDBN} is currently using.
11829
11830 @table @code
11831
11832 @kindex set debug-file-directory
11833 @item set debug-file-directory @var{directory}
11834 Set the directory which @value{GDBN} searches for separate debugging
11835 information files to @var{directory}.
11836
11837 @kindex show debug-file-directory
11838 @item show debug-file-directory
11839 Show the directory @value{GDBN} searches for separate debugging
11840 information files.
11841
11842 @end table
11843
11844 @cindex @code{.gnu_debuglink} sections
11845 @cindex debug links
11846 A debug link is a special section of the executable file named
11847 @code{.gnu_debuglink}. The section must contain:
11848
11849 @itemize
11850 @item
11851 A filename, with any leading directory components removed, followed by
11852 a zero byte,
11853 @item
11854 zero to three bytes of padding, as needed to reach the next four-byte
11855 boundary within the section, and
11856 @item
11857 a four-byte CRC checksum, stored in the same endianness used for the
11858 executable file itself. The checksum is computed on the debugging
11859 information file's full contents by the function given below, passing
11860 zero as the @var{crc} argument.
11861 @end itemize
11862
11863 Any executable file format can carry a debug link, as long as it can
11864 contain a section named @code{.gnu_debuglink} with the contents
11865 described above.
11866
11867 The debugging information file itself should be an ordinary
11868 executable, containing a full set of linker symbols, sections, and
11869 debugging information. The sections of the debugging information file
11870 should have the same names, addresses and sizes as the original file,
11871 but they need not contain any data --- much like a @code{.bss} section
11872 in an ordinary executable.
11873
11874 As of December 2002, there is no standard GNU utility to produce
11875 separated executable / debugging information file pairs. Ulrich
11876 Drepper's @file{elfutils} package, starting with version 0.53,
11877 contains a version of the @code{strip} command such that the command
11878 @kbd{strip foo -f foo.debug} removes the debugging information from
11879 the executable file @file{foo}, places it in the file
11880 @file{foo.debug}, and leaves behind a debug link in @file{foo}.
11881
11882 Since there are many different ways to compute CRC's (different
11883 polynomials, reversals, byte ordering, etc.), the simplest way to
11884 describe the CRC used in @code{.gnu_debuglink} sections is to give the
11885 complete code for a function that computes it:
11886
11887 @kindex gnu_debuglink_crc32
11888 @smallexample
11889 unsigned long
11890 gnu_debuglink_crc32 (unsigned long crc,
11891 unsigned char *buf, size_t len)
11892 @{
11893 static const unsigned long crc32_table[256] =
11894 @{
11895 0x00000000, 0x77073096, 0xee0e612c, 0x990951ba, 0x076dc419,
11896 0x706af48f, 0xe963a535, 0x9e6495a3, 0x0edb8832, 0x79dcb8a4,
11897 0xe0d5e91e, 0x97d2d988, 0x09b64c2b, 0x7eb17cbd, 0xe7b82d07,
11898 0x90bf1d91, 0x1db71064, 0x6ab020f2, 0xf3b97148, 0x84be41de,
11899 0x1adad47d, 0x6ddde4eb, 0xf4d4b551, 0x83d385c7, 0x136c9856,
11900 0x646ba8c0, 0xfd62f97a, 0x8a65c9ec, 0x14015c4f, 0x63066cd9,
11901 0xfa0f3d63, 0x8d080df5, 0x3b6e20c8, 0x4c69105e, 0xd56041e4,
11902 0xa2677172, 0x3c03e4d1, 0x4b04d447, 0xd20d85fd, 0xa50ab56b,
11903 0x35b5a8fa, 0x42b2986c, 0xdbbbc9d6, 0xacbcf940, 0x32d86ce3,
11904 0x45df5c75, 0xdcd60dcf, 0xabd13d59, 0x26d930ac, 0x51de003a,
11905 0xc8d75180, 0xbfd06116, 0x21b4f4b5, 0x56b3c423, 0xcfba9599,
11906 0xb8bda50f, 0x2802b89e, 0x5f058808, 0xc60cd9b2, 0xb10be924,
11907 0x2f6f7c87, 0x58684c11, 0xc1611dab, 0xb6662d3d, 0x76dc4190,
11908 0x01db7106, 0x98d220bc, 0xefd5102a, 0x71b18589, 0x06b6b51f,
11909 0x9fbfe4a5, 0xe8b8d433, 0x7807c9a2, 0x0f00f934, 0x9609a88e,
11910 0xe10e9818, 0x7f6a0dbb, 0x086d3d2d, 0x91646c97, 0xe6635c01,
11911 0x6b6b51f4, 0x1c6c6162, 0x856530d8, 0xf262004e, 0x6c0695ed,
11912 0x1b01a57b, 0x8208f4c1, 0xf50fc457, 0x65b0d9c6, 0x12b7e950,
11913 0x8bbeb8ea, 0xfcb9887c, 0x62dd1ddf, 0x15da2d49, 0x8cd37cf3,
11914 0xfbd44c65, 0x4db26158, 0x3ab551ce, 0xa3bc0074, 0xd4bb30e2,
11915 0x4adfa541, 0x3dd895d7, 0xa4d1c46d, 0xd3d6f4fb, 0x4369e96a,
11916 0x346ed9fc, 0xad678846, 0xda60b8d0, 0x44042d73, 0x33031de5,
11917 0xaa0a4c5f, 0xdd0d7cc9, 0x5005713c, 0x270241aa, 0xbe0b1010,
11918 0xc90c2086, 0x5768b525, 0x206f85b3, 0xb966d409, 0xce61e49f,
11919 0x5edef90e, 0x29d9c998, 0xb0d09822, 0xc7d7a8b4, 0x59b33d17,
11920 0x2eb40d81, 0xb7bd5c3b, 0xc0ba6cad, 0xedb88320, 0x9abfb3b6,
11921 0x03b6e20c, 0x74b1d29a, 0xead54739, 0x9dd277af, 0x04db2615,
11922 0x73dc1683, 0xe3630b12, 0x94643b84, 0x0d6d6a3e, 0x7a6a5aa8,
11923 0xe40ecf0b, 0x9309ff9d, 0x0a00ae27, 0x7d079eb1, 0xf00f9344,
11924 0x8708a3d2, 0x1e01f268, 0x6906c2fe, 0xf762575d, 0x806567cb,
11925 0x196c3671, 0x6e6b06e7, 0xfed41b76, 0x89d32be0, 0x10da7a5a,
11926 0x67dd4acc, 0xf9b9df6f, 0x8ebeeff9, 0x17b7be43, 0x60b08ed5,
11927 0xd6d6a3e8, 0xa1d1937e, 0x38d8c2c4, 0x4fdff252, 0xd1bb67f1,
11928 0xa6bc5767, 0x3fb506dd, 0x48b2364b, 0xd80d2bda, 0xaf0a1b4c,
11929 0x36034af6, 0x41047a60, 0xdf60efc3, 0xa867df55, 0x316e8eef,
11930 0x4669be79, 0xcb61b38c, 0xbc66831a, 0x256fd2a0, 0x5268e236,
11931 0xcc0c7795, 0xbb0b4703, 0x220216b9, 0x5505262f, 0xc5ba3bbe,
11932 0xb2bd0b28, 0x2bb45a92, 0x5cb36a04, 0xc2d7ffa7, 0xb5d0cf31,
11933 0x2cd99e8b, 0x5bdeae1d, 0x9b64c2b0, 0xec63f226, 0x756aa39c,
11934 0x026d930a, 0x9c0906a9, 0xeb0e363f, 0x72076785, 0x05005713,
11935 0x95bf4a82, 0xe2b87a14, 0x7bb12bae, 0x0cb61b38, 0x92d28e9b,
11936 0xe5d5be0d, 0x7cdcefb7, 0x0bdbdf21, 0x86d3d2d4, 0xf1d4e242,
11937 0x68ddb3f8, 0x1fda836e, 0x81be16cd, 0xf6b9265b, 0x6fb077e1,
11938 0x18b74777, 0x88085ae6, 0xff0f6a70, 0x66063bca, 0x11010b5c,
11939 0x8f659eff, 0xf862ae69, 0x616bffd3, 0x166ccf45, 0xa00ae278,
11940 0xd70dd2ee, 0x4e048354, 0x3903b3c2, 0xa7672661, 0xd06016f7,
11941 0x4969474d, 0x3e6e77db, 0xaed16a4a, 0xd9d65adc, 0x40df0b66,
11942 0x37d83bf0, 0xa9bcae53, 0xdebb9ec5, 0x47b2cf7f, 0x30b5ffe9,
11943 0xbdbdf21c, 0xcabac28a, 0x53b39330, 0x24b4a3a6, 0xbad03605,
11944 0xcdd70693, 0x54de5729, 0x23d967bf, 0xb3667a2e, 0xc4614ab8,
11945 0x5d681b02, 0x2a6f2b94, 0xb40bbe37, 0xc30c8ea1, 0x5a05df1b,
11946 0x2d02ef8d
11947 @};
11948 unsigned char *end;
11949
11950 crc = ~crc & 0xffffffff;
11951 for (end = buf + len; buf < end; ++buf)
11952 crc = crc32_table[(crc ^ *buf) & 0xff] ^ (crc >> 8);
11953 return ~crc & 0xffffffff;
11954 @}
11955 @end smallexample
11956
11957
11958 @node Symbol Errors
11959 @section Errors reading symbol files
11960
11961 While reading a symbol file, @value{GDBN} occasionally encounters problems,
11962 such as symbol types it does not recognize, or known bugs in compiler
11963 output. By default, @value{GDBN} does not notify you of such problems, since
11964 they are relatively common and primarily of interest to people
11965 debugging compilers. If you are interested in seeing information
11966 about ill-constructed symbol tables, you can either ask @value{GDBN} to print
11967 only one message about each such type of problem, no matter how many
11968 times the problem occurs; or you can ask @value{GDBN} to print more messages,
11969 to see how many times the problems occur, with the @code{set
11970 complaints} command (@pxref{Messages/Warnings, ,Optional warnings and
11971 messages}).
11972
11973 The messages currently printed, and their meanings, include:
11974
11975 @table @code
11976 @item inner block not inside outer block in @var{symbol}
11977
11978 The symbol information shows where symbol scopes begin and end
11979 (such as at the start of a function or a block of statements). This
11980 error indicates that an inner scope block is not fully contained
11981 in its outer scope blocks.
11982
11983 @value{GDBN} circumvents the problem by treating the inner block as if it had
11984 the same scope as the outer block. In the error message, @var{symbol}
11985 may be shown as ``@code{(don't know)}'' if the outer block is not a
11986 function.
11987
11988 @item block at @var{address} out of order
11989
11990 The symbol information for symbol scope blocks should occur in
11991 order of increasing addresses. This error indicates that it does not
11992 do so.
11993
11994 @value{GDBN} does not circumvent this problem, and has trouble
11995 locating symbols in the source file whose symbols it is reading. (You
11996 can often determine what source file is affected by specifying
11997 @code{set verbose on}. @xref{Messages/Warnings, ,Optional warnings and
11998 messages}.)
11999
12000 @item bad block start address patched
12001
12002 The symbol information for a symbol scope block has a start address
12003 smaller than the address of the preceding source line. This is known
12004 to occur in the SunOS 4.1.1 (and earlier) C compiler.
12005
12006 @value{GDBN} circumvents the problem by treating the symbol scope block as
12007 starting on the previous source line.
12008
12009 @item bad string table offset in symbol @var{n}
12010
12011 @cindex foo
12012 Symbol number @var{n} contains a pointer into the string table which is
12013 larger than the size of the string table.
12014
12015 @value{GDBN} circumvents the problem by considering the symbol to have the
12016 name @code{foo}, which may cause other problems if many symbols end up
12017 with this name.
12018
12019 @item unknown symbol type @code{0x@var{nn}}
12020
12021 The symbol information contains new data types that @value{GDBN} does
12022 not yet know how to read. @code{0x@var{nn}} is the symbol type of the
12023 uncomprehended information, in hexadecimal.
12024
12025 @value{GDBN} circumvents the error by ignoring this symbol information.
12026 This usually allows you to debug your program, though certain symbols
12027 are not accessible. If you encounter such a problem and feel like
12028 debugging it, you can debug @code{@value{GDBP}} with itself, breakpoint
12029 on @code{complain}, then go up to the function @code{read_dbx_symtab}
12030 and examine @code{*bufp} to see the symbol.
12031
12032 @item stub type has NULL name
12033
12034 @value{GDBN} could not find the full definition for a struct or class.
12035
12036 @item const/volatile indicator missing (ok if using g++ v1.x), got@dots{}
12037 The symbol information for a C@t{++} member function is missing some
12038 information that recent versions of the compiler should have output for
12039 it.
12040
12041 @item info mismatch between compiler and debugger
12042
12043 @value{GDBN} could not parse a type specification output by the compiler.
12044
12045 @end table
12046
12047 @node Targets
12048 @chapter Specifying a Debugging Target
12049
12050 @cindex debugging target
12051 A @dfn{target} is the execution environment occupied by your program.
12052
12053 Often, @value{GDBN} runs in the same host environment as your program;
12054 in that case, the debugging target is specified as a side effect when
12055 you use the @code{file} or @code{core} commands. When you need more
12056 flexibility---for example, running @value{GDBN} on a physically separate
12057 host, or controlling a standalone system over a serial port or a
12058 realtime system over a TCP/IP connection---you can use the @code{target}
12059 command to specify one of the target types configured for @value{GDBN}
12060 (@pxref{Target Commands, ,Commands for managing targets}).
12061
12062 @cindex target architecture
12063 It is possible to build @value{GDBN} for several different @dfn{target
12064 architectures}. When @value{GDBN} is built like that, you can choose
12065 one of the available architectures with the @kbd{set architecture}
12066 command.
12067
12068 @table @code
12069 @kindex set architecture
12070 @kindex show architecture
12071 @item set architecture @var{arch}
12072 This command sets the current target architecture to @var{arch}. The
12073 value of @var{arch} can be @code{"auto"}, in addition to one of the
12074 supported architectures.
12075
12076 @item show architecture
12077 Show the current target architecture.
12078
12079 @item set processor
12080 @itemx processor
12081 @kindex set processor
12082 @kindex show processor
12083 These are alias commands for, respectively, @code{set architecture}
12084 and @code{show architecture}.
12085 @end table
12086
12087 @menu
12088 * Active Targets:: Active targets
12089 * Target Commands:: Commands for managing targets
12090 * Byte Order:: Choosing target byte order
12091 * Remote:: Remote debugging
12092
12093 @end menu
12094
12095 @node Active Targets
12096 @section Active targets
12097
12098 @cindex stacking targets
12099 @cindex active targets
12100 @cindex multiple targets
12101
12102 There are three classes of targets: processes, core files, and
12103 executable files. @value{GDBN} can work concurrently on up to three
12104 active targets, one in each class. This allows you to (for example)
12105 start a process and inspect its activity without abandoning your work on
12106 a core file.
12107
12108 For example, if you execute @samp{gdb a.out}, then the executable file
12109 @code{a.out} is the only active target. If you designate a core file as
12110 well---presumably from a prior run that crashed and coredumped---then
12111 @value{GDBN} has two active targets and uses them in tandem, looking
12112 first in the corefile target, then in the executable file, to satisfy
12113 requests for memory addresses. (Typically, these two classes of target
12114 are complementary, since core files contain only a program's
12115 read-write memory---variables and so on---plus machine status, while
12116 executable files contain only the program text and initialized data.)
12117
12118 When you type @code{run}, your executable file becomes an active process
12119 target as well. When a process target is active, all @value{GDBN}
12120 commands requesting memory addresses refer to that target; addresses in
12121 an active core file or executable file target are obscured while the
12122 process target is active.
12123
12124 Use the @code{core-file} and @code{exec-file} commands to select a new
12125 core file or executable target (@pxref{Files, ,Commands to specify
12126 files}). To specify as a target a process that is already running, use
12127 the @code{attach} command (@pxref{Attach, ,Debugging an already-running
12128 process}).
12129
12130 @node Target Commands
12131 @section Commands for managing targets
12132
12133 @table @code
12134 @item target @var{type} @var{parameters}
12135 Connects the @value{GDBN} host environment to a target machine or
12136 process. A target is typically a protocol for talking to debugging
12137 facilities. You use the argument @var{type} to specify the type or
12138 protocol of the target machine.
12139
12140 Further @var{parameters} are interpreted by the target protocol, but
12141 typically include things like device names or host names to connect
12142 with, process numbers, and baud rates.
12143
12144 The @code{target} command does not repeat if you press @key{RET} again
12145 after executing the command.
12146
12147 @kindex help target
12148 @item help target
12149 Displays the names of all targets available. To display targets
12150 currently selected, use either @code{info target} or @code{info files}
12151 (@pxref{Files, ,Commands to specify files}).
12152
12153 @item help target @var{name}
12154 Describe a particular target, including any parameters necessary to
12155 select it.
12156
12157 @kindex set gnutarget
12158 @item set gnutarget @var{args}
12159 @value{GDBN} uses its own library BFD to read your files. @value{GDBN}
12160 knows whether it is reading an @dfn{executable},
12161 a @dfn{core}, or a @dfn{.o} file; however, you can specify the file format
12162 with the @code{set gnutarget} command. Unlike most @code{target} commands,
12163 with @code{gnutarget} the @code{target} refers to a program, not a machine.
12164
12165 @quotation
12166 @emph{Warning:} To specify a file format with @code{set gnutarget},
12167 you must know the actual BFD name.
12168 @end quotation
12169
12170 @noindent
12171 @xref{Files, , Commands to specify files}.
12172
12173 @kindex show gnutarget
12174 @item show gnutarget
12175 Use the @code{show gnutarget} command to display what file format
12176 @code{gnutarget} is set to read. If you have not set @code{gnutarget},
12177 @value{GDBN} will determine the file format for each file automatically,
12178 and @code{show gnutarget} displays @samp{The current BDF target is "auto"}.
12179 @end table
12180
12181 @cindex common targets
12182 Here are some common targets (available, or not, depending on the GDB
12183 configuration):
12184
12185 @table @code
12186 @kindex target
12187 @item target exec @var{program}
12188 @cindex executable file target
12189 An executable file. @samp{target exec @var{program}} is the same as
12190 @samp{exec-file @var{program}}.
12191
12192 @item target core @var{filename}
12193 @cindex core dump file target
12194 A core dump file. @samp{target core @var{filename}} is the same as
12195 @samp{core-file @var{filename}}.
12196
12197 @item target remote @var{medium}
12198 @cindex remote target
12199 A remote system connected to @value{GDBN} via a serial line or network
12200 connection. This command tells @value{GDBN} to use its own remote
12201 protocol over @var{medium} for debugging. @xref{Remote Debugging}.
12202
12203 For example, if you have a board connected to @file{/dev/ttya} on the
12204 machine running @value{GDBN}, you could say:
12205
12206 @smallexample
12207 target remote /dev/ttya
12208 @end smallexample
12209
12210 @code{target remote} supports the @code{load} command. This is only
12211 useful if you have some other way of getting the stub to the target
12212 system, and you can put it somewhere in memory where it won't get
12213 clobbered by the download.
12214
12215 @item target sim
12216 @cindex built-in simulator target
12217 Builtin CPU simulator. @value{GDBN} includes simulators for most architectures.
12218 In general,
12219 @smallexample
12220 target sim
12221 load
12222 run
12223 @end smallexample
12224 @noindent
12225 works; however, you cannot assume that a specific memory map, device
12226 drivers, or even basic I/O is available, although some simulators do
12227 provide these. For info about any processor-specific simulator details,
12228 see the appropriate section in @ref{Embedded Processors, ,Embedded
12229 Processors}.
12230
12231 @end table
12232
12233 Some configurations may include these targets as well:
12234
12235 @table @code
12236
12237 @item target nrom @var{dev}
12238 @cindex NetROM ROM emulator target
12239 NetROM ROM emulator. This target only supports downloading.
12240
12241 @end table
12242
12243 Different targets are available on different configurations of @value{GDBN};
12244 your configuration may have more or fewer targets.
12245
12246 Many remote targets require you to download the executable's code once
12247 you've successfully established a connection. You may wish to control
12248 various aspects of this process.
12249
12250 @table @code
12251
12252 @item set hash
12253 @kindex set hash@r{, for remote monitors}
12254 @cindex hash mark while downloading
12255 This command controls whether a hash mark @samp{#} is displayed while
12256 downloading a file to the remote monitor. If on, a hash mark is
12257 displayed after each S-record is successfully downloaded to the
12258 monitor.
12259
12260 @item show hash
12261 @kindex show hash@r{, for remote monitors}
12262 Show the current status of displaying the hash mark.
12263
12264 @item set debug monitor
12265 @kindex set debug monitor
12266 @cindex display remote monitor communications
12267 Enable or disable display of communications messages between
12268 @value{GDBN} and the remote monitor.
12269
12270 @item show debug monitor
12271 @kindex show debug monitor
12272 Show the current status of displaying communications between
12273 @value{GDBN} and the remote monitor.
12274 @end table
12275
12276 @table @code
12277
12278 @kindex load @var{filename}
12279 @item load @var{filename}
12280 Depending on what remote debugging facilities are configured into
12281 @value{GDBN}, the @code{load} command may be available. Where it exists, it
12282 is meant to make @var{filename} (an executable) available for debugging
12283 on the remote system---by downloading, or dynamic linking, for example.
12284 @code{load} also records the @var{filename} symbol table in @value{GDBN}, like
12285 the @code{add-symbol-file} command.
12286
12287 If your @value{GDBN} does not have a @code{load} command, attempting to
12288 execute it gets the error message ``@code{You can't do that when your
12289 target is @dots{}}''
12290
12291 The file is loaded at whatever address is specified in the executable.
12292 For some object file formats, you can specify the load address when you
12293 link the program; for other formats, like a.out, the object file format
12294 specifies a fixed address.
12295 @c FIXME! This would be a good place for an xref to the GNU linker doc.
12296
12297 Depending on the remote side capabilities, @value{GDBN} may be able to
12298 load programs into flash memory.
12299
12300 @code{load} does not repeat if you press @key{RET} again after using it.
12301 @end table
12302
12303 @node Byte Order
12304 @section Choosing target byte order
12305
12306 @cindex choosing target byte order
12307 @cindex target byte order
12308
12309 Some types of processors, such as the MIPS, PowerPC, and Renesas SH,
12310 offer the ability to run either big-endian or little-endian byte
12311 orders. Usually the executable or symbol will include a bit to
12312 designate the endian-ness, and you will not need to worry about
12313 which to use. However, you may still find it useful to adjust
12314 @value{GDBN}'s idea of processor endian-ness manually.
12315
12316 @table @code
12317 @kindex set endian
12318 @item set endian big
12319 Instruct @value{GDBN} to assume the target is big-endian.
12320
12321 @item set endian little
12322 Instruct @value{GDBN} to assume the target is little-endian.
12323
12324 @item set endian auto
12325 Instruct @value{GDBN} to use the byte order associated with the
12326 executable.
12327
12328 @item show endian
12329 Display @value{GDBN}'s current idea of the target byte order.
12330
12331 @end table
12332
12333 Note that these commands merely adjust interpretation of symbolic
12334 data on the host, and that they have absolutely no effect on the
12335 target system.
12336
12337 @node Remote
12338 @section Remote debugging
12339 @cindex remote debugging
12340
12341 If you are trying to debug a program running on a machine that cannot run
12342 @value{GDBN} in the usual way, it is often useful to use remote debugging.
12343 For example, you might use remote debugging on an operating system kernel,
12344 or on a small system which does not have a general purpose operating system
12345 powerful enough to run a full-featured debugger.
12346
12347 Some configurations of @value{GDBN} have special serial or TCP/IP interfaces
12348 to make this work with particular debugging targets. In addition,
12349 @value{GDBN} comes with a generic serial protocol (specific to @value{GDBN},
12350 but not specific to any particular target system) which you can use if you
12351 write the remote stubs---the code that runs on the remote system to
12352 communicate with @value{GDBN}.
12353
12354 Other remote targets may be available in your
12355 configuration of @value{GDBN}; use @code{help target} to list them.
12356
12357 Once you've connected to the remote target, @value{GDBN} allows you to
12358 send arbitrary commands to the remote monitor:
12359
12360 @table @code
12361 @item remote @var{command}
12362 @kindex remote@r{, a command}
12363 @cindex send command to remote monitor
12364 Send an arbitrary @var{command} string to the remote monitor.
12365 @end table
12366
12367
12368 @node Remote Debugging
12369 @chapter Debugging remote programs
12370
12371 @menu
12372 * Connecting:: Connecting to a remote target
12373 * Server:: Using the gdbserver program
12374 * Remote configuration:: Remote configuration
12375 * remote stub:: Implementing a remote stub
12376 @end menu
12377
12378 @node Connecting
12379 @section Connecting to a remote target
12380
12381 On the @value{GDBN} host machine, you will need an unstripped copy of
12382 your program, since @value{GDBN} needs symobl and debugging information.
12383 Start up @value{GDBN} as usual, using the name of the local copy of your
12384 program as the first argument.
12385
12386 @cindex @code{target remote}
12387 @value{GDBN} can communicate with the target over a serial line, or
12388 over an @acronym{IP} network using @acronym{TCP} or @acronym{UDP}. In
12389 each case, @value{GDBN} uses the same protocol for debugging your
12390 program; only the medium carrying the debugging packets varies. The
12391 @code{target remote} command establishes a connection to the target.
12392 Its arguments indicate which medium to use:
12393
12394 @table @code
12395
12396 @item target remote @var{serial-device}
12397 @cindex serial line, @code{target remote}
12398 Use @var{serial-device} to communicate with the target. For example,
12399 to use a serial line connected to the device named @file{/dev/ttyb}:
12400
12401 @smallexample
12402 target remote /dev/ttyb
12403 @end smallexample
12404
12405 If you're using a serial line, you may want to give @value{GDBN} the
12406 @w{@samp{--baud}} option, or use the @code{set remotebaud} command
12407 (@pxref{Remote configuration, set remotebaud}) before the
12408 @code{target} command.
12409
12410 @item target remote @code{@var{host}:@var{port}}
12411 @itemx target remote @code{tcp:@var{host}:@var{port}}
12412 @cindex @acronym{TCP} port, @code{target remote}
12413 Debug using a @acronym{TCP} connection to @var{port} on @var{host}.
12414 The @var{host} may be either a host name or a numeric @acronym{IP}
12415 address; @var{port} must be a decimal number. The @var{host} could be
12416 the target machine itself, if it is directly connected to the net, or
12417 it might be a terminal server which in turn has a serial line to the
12418 target.
12419
12420 For example, to connect to port 2828 on a terminal server named
12421 @code{manyfarms}:
12422
12423 @smallexample
12424 target remote manyfarms:2828
12425 @end smallexample
12426
12427 If your remote target is actually running on the same machine as your
12428 debugger session (e.g.@: a simulator for your target running on the
12429 same host), you can omit the hostname. For example, to connect to
12430 port 1234 on your local machine:
12431
12432 @smallexample
12433 target remote :1234
12434 @end smallexample
12435 @noindent
12436
12437 Note that the colon is still required here.
12438
12439 @item target remote @code{udp:@var{host}:@var{port}}
12440 @cindex @acronym{UDP} port, @code{target remote}
12441 Debug using @acronym{UDP} packets to @var{port} on @var{host}. For example, to
12442 connect to @acronym{UDP} port 2828 on a terminal server named @code{manyfarms}:
12443
12444 @smallexample
12445 target remote udp:manyfarms:2828
12446 @end smallexample
12447
12448 When using a @acronym{UDP} connection for remote debugging, you should
12449 keep in mind that the `U' stands for ``Unreliable''. @acronym{UDP}
12450 can silently drop packets on busy or unreliable networks, which will
12451 cause havoc with your debugging session.
12452
12453 @item target remote | @var{command}
12454 @cindex pipe, @code{target remote} to
12455 Run @var{command} in the background and communicate with it using a
12456 pipe. The @var{command} is a shell command, to be parsed and expanded
12457 by the system's command shell, @code{/bin/sh}; it should expect remote
12458 protocol packets on its standard input, and send replies on its
12459 standard output. You could use this to run a stand-alone simulator
12460 that speaks the remote debugging protocol, to make net connections
12461 using programs like @code{ssh}, or for other similar tricks.
12462
12463 If @var{command} closes its standard output (perhaps by exiting),
12464 @value{GDBN} will try to send it a @code{SIGTERM} signal. (If the
12465 program has already exited, this will have no effect.)
12466
12467 @end table
12468
12469 Once the connection has been established, you can use all the usual
12470 commands to examine and change data and to step and continue the
12471 remote program.
12472
12473 @cindex interrupting remote programs
12474 @cindex remote programs, interrupting
12475 Whenever @value{GDBN} is waiting for the remote program, if you type the
12476 interrupt character (often @kbd{Ctrl-c}), @value{GDBN} attempts to stop the
12477 program. This may or may not succeed, depending in part on the hardware
12478 and the serial drivers the remote system uses. If you type the
12479 interrupt character once again, @value{GDBN} displays this prompt:
12480
12481 @smallexample
12482 Interrupted while waiting for the program.
12483 Give up (and stop debugging it)? (y or n)
12484 @end smallexample
12485
12486 If you type @kbd{y}, @value{GDBN} abandons the remote debugging session.
12487 (If you decide you want to try again later, you can use @samp{target
12488 remote} again to connect once more.) If you type @kbd{n}, @value{GDBN}
12489 goes back to waiting.
12490
12491 @table @code
12492 @kindex detach (remote)
12493 @item detach
12494 When you have finished debugging the remote program, you can use the
12495 @code{detach} command to release it from @value{GDBN} control.
12496 Detaching from the target normally resumes its execution, but the results
12497 will depend on your particular remote stub. After the @code{detach}
12498 command, @value{GDBN} is free to connect to another target.
12499
12500 @kindex disconnect
12501 @item disconnect
12502 The @code{disconnect} command behaves like @code{detach}, except that
12503 the target is generally not resumed. It will wait for @value{GDBN}
12504 (this instance or another one) to connect and continue debugging. After
12505 the @code{disconnect} command, @value{GDBN} is again free to connect to
12506 another target.
12507
12508 @cindex send command to remote monitor
12509 @cindex extend @value{GDBN} for remote targets
12510 @cindex add new commands for external monitor
12511 @kindex monitor
12512 @item monitor @var{cmd}
12513 This command allows you to send arbitrary commands directly to the
12514 remote monitor. Since @value{GDBN} doesn't care about the commands it
12515 sends like this, this command is the way to extend @value{GDBN}---you
12516 can add new commands that only the external monitor will understand
12517 and implement.
12518 @end table
12519
12520 @node Server
12521 @section Using the @code{gdbserver} program
12522
12523 @kindex gdbserver
12524 @cindex remote connection without stubs
12525 @code{gdbserver} is a control program for Unix-like systems, which
12526 allows you to connect your program with a remote @value{GDBN} via
12527 @code{target remote}---but without linking in the usual debugging stub.
12528
12529 @code{gdbserver} is not a complete replacement for the debugging stubs,
12530 because it requires essentially the same operating-system facilities
12531 that @value{GDBN} itself does. In fact, a system that can run
12532 @code{gdbserver} to connect to a remote @value{GDBN} could also run
12533 @value{GDBN} locally! @code{gdbserver} is sometimes useful nevertheless,
12534 because it is a much smaller program than @value{GDBN} itself. It is
12535 also easier to port than all of @value{GDBN}, so you may be able to get
12536 started more quickly on a new system by using @code{gdbserver}.
12537 Finally, if you develop code for real-time systems, you may find that
12538 the tradeoffs involved in real-time operation make it more convenient to
12539 do as much development work as possible on another system, for example
12540 by cross-compiling. You can use @code{gdbserver} to make a similar
12541 choice for debugging.
12542
12543 @value{GDBN} and @code{gdbserver} communicate via either a serial line
12544 or a TCP connection, using the standard @value{GDBN} remote serial
12545 protocol.
12546
12547 @table @emph
12548 @item On the target machine,
12549 you need to have a copy of the program you want to debug.
12550 @code{gdbserver} does not need your program's symbol table, so you can
12551 strip the program if necessary to save space. @value{GDBN} on the host
12552 system does all the symbol handling.
12553
12554 To use the server, you must tell it how to communicate with @value{GDBN};
12555 the name of your program; and the arguments for your program. The usual
12556 syntax is:
12557
12558 @smallexample
12559 target> gdbserver @var{comm} @var{program} [ @var{args} @dots{} ]
12560 @end smallexample
12561
12562 @var{comm} is either a device name (to use a serial line) or a TCP
12563 hostname and portnumber. For example, to debug Emacs with the argument
12564 @samp{foo.txt} and communicate with @value{GDBN} over the serial port
12565 @file{/dev/com1}:
12566
12567 @smallexample
12568 target> gdbserver /dev/com1 emacs foo.txt
12569 @end smallexample
12570
12571 @code{gdbserver} waits passively for the host @value{GDBN} to communicate
12572 with it.
12573
12574 To use a TCP connection instead of a serial line:
12575
12576 @smallexample
12577 target> gdbserver host:2345 emacs foo.txt
12578 @end smallexample
12579
12580 The only difference from the previous example is the first argument,
12581 specifying that you are communicating with the host @value{GDBN} via
12582 TCP. The @samp{host:2345} argument means that @code{gdbserver} is to
12583 expect a TCP connection from machine @samp{host} to local TCP port 2345.
12584 (Currently, the @samp{host} part is ignored.) You can choose any number
12585 you want for the port number as long as it does not conflict with any
12586 TCP ports already in use on the target system (for example, @code{23} is
12587 reserved for @code{telnet}).@footnote{If you choose a port number that
12588 conflicts with another service, @code{gdbserver} prints an error message
12589 and exits.} You must use the same port number with the host @value{GDBN}
12590 @code{target remote} command.
12591
12592 On some targets, @code{gdbserver} can also attach to running programs.
12593 This is accomplished via the @code{--attach} argument. The syntax is:
12594
12595 @smallexample
12596 target> gdbserver @var{comm} --attach @var{pid}
12597 @end smallexample
12598
12599 @var{pid} is the process ID of a currently running process. It isn't necessary
12600 to point @code{gdbserver} at a binary for the running process.
12601
12602 @pindex pidof
12603 @cindex attach to a program by name
12604 You can debug processes by name instead of process ID if your target has the
12605 @code{pidof} utility:
12606
12607 @smallexample
12608 target> gdbserver @var{comm} --attach `pidof @var{PROGRAM}`
12609 @end smallexample
12610
12611 In case more than one copy of @var{PROGRAM} is running, or @var{PROGRAM}
12612 has multiple threads, most versions of @code{pidof} support the
12613 @code{-s} option to only return the first process ID.
12614
12615 @item On the host machine,
12616 connect to your target (@pxref{Connecting,,Connecting to a remote target}).
12617 For TCP connections, you must start up @code{gdbserver} prior to using
12618 the @code{target remote} command. Otherwise you may get an error whose
12619 text depends on the host system, but which usually looks something like
12620 @samp{Connection refused}. You don't need to use the @code{load}
12621 command in @value{GDBN} when using @code{gdbserver}, since the program is
12622 already on the target. However, if you want to load the symbols (as
12623 you normally would), do that with the @code{file} command, and issue
12624 it @emph{before} connecting to the server; otherwise, you will get an
12625 error message saying @code{"Program is already running"}, since the
12626 program is considered running after the connection.
12627
12628 @end table
12629
12630 @node Remote configuration
12631 @section Remote configuration
12632
12633 @kindex set remote
12634 @kindex show remote
12635 This section documents the configuration options available when
12636 debugging remote programs. For the options related to the File I/O
12637 extensions of the remote protocol, see @ref{system,
12638 system-call-allowed}.
12639
12640 @table @code
12641 @item set remoteaddresssize @var{bits}
12642 @cindex adress size for remote targets
12643 @cindex bits in remote address
12644 Set the maximum size of address in a memory packet to the specified
12645 number of bits. @value{GDBN} will mask off the address bits above
12646 that number, when it passes addresses to the remote target. The
12647 default value is the number of bits in the target's address.
12648
12649 @item show remoteaddresssize
12650 Show the current value of remote address size in bits.
12651
12652 @item set remotebaud @var{n}
12653 @cindex baud rate for remote targets
12654 Set the baud rate for the remote serial I/O to @var{n} baud. The
12655 value is used to set the speed of the serial port used for debugging
12656 remote targets.
12657
12658 @item show remotebaud
12659 Show the current speed of the remote connection.
12660
12661 @item set remotebreak
12662 @cindex interrupt remote programs
12663 @cindex BREAK signal instead of Ctrl-C
12664 @anchor{set remotebreak}
12665 If set to on, @value{GDBN} sends a @code{BREAK} signal to the remote
12666 when you type @kbd{Ctrl-c} to interrupt the program running
12667 on the remote. If set to off, @value{GDBN} sends the @samp{Ctrl-C}
12668 character instead. The default is off, since most remote systems
12669 expect to see @samp{Ctrl-C} as the interrupt signal.
12670
12671 @item show remotebreak
12672 Show whether @value{GDBN} sends @code{BREAK} or @samp{Ctrl-C} to
12673 interrupt the remote program.
12674
12675 @item set remotedevice @var{device}
12676 @cindex serial port name
12677 Set the name of the serial port through which to communicate to the
12678 remote target to @var{device}. This is the device used by
12679 @value{GDBN} to open the serial communications line to the remote
12680 target. There's no default, so you must set a valid port name for the
12681 remote serial communications to work. (Some varieties of the
12682 @code{target} command accept the port name as part of their
12683 arguments.)
12684
12685 @item show remotedevice
12686 Show the current name of the serial port.
12687
12688 @item set remotelogbase @var{base}
12689 Set the base (a.k.a.@: radix) of logging serial protocol
12690 communications to @var{base}. Supported values of @var{base} are:
12691 @code{ascii}, @code{octal}, and @code{hex}. The default is
12692 @code{ascii}.
12693
12694 @item show remotelogbase
12695 Show the current setting of the radix for logging remote serial
12696 protocol.
12697
12698 @item set remotelogfile @var{file}
12699 @cindex record serial communications on file
12700 Record remote serial communications on the named @var{file}. The
12701 default is not to record at all.
12702
12703 @item show remotelogfile.
12704 Show the current setting of the file name on which to record the
12705 serial communications.
12706
12707 @item set remotetimeout @var{num}
12708 @cindex timeout for serial communications
12709 @cindex remote timeout
12710 Set the timeout limit to wait for the remote target to respond to
12711 @var{num} seconds. The default is 2 seconds.
12712
12713 @item show remotetimeout
12714 Show the current number of seconds to wait for the remote target
12715 responses.
12716
12717 @cindex limit hardware breakpoints and watchpoints
12718 @cindex remote target, limit break- and watchpoints
12719 @anchor{set remote hardware-watchpoint-limit}
12720 @anchor{set remote hardware-breakpoint-limit}
12721 @item set remote hardware-watchpoint-limit @var{limit}
12722 @itemx set remote hardware-breakpoint-limit @var{limit}
12723 Restrict @value{GDBN} to using @var{limit} remote hardware breakpoint or
12724 watchpoints. A limit of -1, the default, is treated as unlimited.
12725
12726 @item set remote fetch-register-packet
12727 @itemx set remote set-register-packet
12728 @itemx set remote P-packet
12729 @itemx set remote p-packet
12730 @cindex P-packet
12731 @cindex fetch registers from remote targets
12732 @cindex set registers in remote targets
12733 Determine whether @value{GDBN} can set and fetch registers from the
12734 remote target using the @samp{P} packets. The default depends on the
12735 remote stub's support of the @samp{P} packets (@value{GDBN} queries
12736 the stub when this packet is first required).
12737
12738 @item show remote fetch-register-packet
12739 @itemx show remote set-register-packet
12740 @itemx show remote P-packet
12741 @itemx show remote p-packet
12742 Show the current setting of using the @samp{P} packets for setting and
12743 fetching registers from the remote target.
12744
12745 @cindex binary downloads
12746 @cindex X-packet
12747 @item set remote binary-download-packet
12748 @itemx set remote X-packet
12749 Determine whether @value{GDBN} sends downloads in binary mode using
12750 the @samp{X} packets. The default is on.
12751
12752 @item show remote binary-download-packet
12753 @itemx show remote X-packet
12754 Show the current setting of using the @samp{X} packets for binary
12755 downloads.
12756
12757 @item set remote read-aux-vector-packet
12758 @cindex auxiliary vector of remote target
12759 @cindex @code{auxv}, and remote targets
12760 Set the use of the remote protocol's @samp{qXfer:auxv:read} (target
12761 auxiliary vector) request. This request is used to fetch the
12762 remote target's @dfn{auxiliary vector}, see @ref{OS Information,
12763 Auxiliary Vector}. The default setting depends on the remote stub's
12764 support of this request (@value{GDBN} queries the stub when this
12765 request is first required). @xref{General Query Packets, qXfer}, for
12766 more information about this request.
12767
12768 @item show remote read-aux-vector-packet
12769 Show the current setting of use of the @samp{qXfer:auxv:read} request.
12770
12771 @item set remote symbol-lookup-packet
12772 @cindex remote symbol lookup request
12773 Set the use of the remote protocol's @samp{qSymbol} (target symbol
12774 lookup) request. This request is used to communicate symbol
12775 information to the remote target, e.g., whenever a new shared library
12776 is loaded by the remote (@pxref{Files, shared libraries}). The
12777 default setting depends on the remote stub's support of this request
12778 (@value{GDBN} queries the stub when this request is first required).
12779 @xref{General Query Packets, qSymbol}, for more information about this
12780 request.
12781
12782 @item show remote symbol-lookup-packet
12783 Show the current setting of use of the @samp{qSymbol} request.
12784
12785 @item set remote verbose-resume-packet
12786 @cindex resume remote target
12787 @cindex signal thread, and remote targets
12788 @cindex single-step thread, and remote targets
12789 @cindex thread-specific operations on remote targets
12790 Set the use of the remote protocol's @samp{vCont} (descriptive resume)
12791 request. This request is used to resume specific threads in the
12792 remote target, and to single-step or signal them. The default setting
12793 depends on the remote stub's support of this request (@value{GDBN}
12794 queries the stub when this request is first required). This setting
12795 affects debugging of multithreaded programs: if @samp{vCont} cannot be
12796 used, @value{GDBN} might be unable to single-step a specific thread,
12797 especially under @code{set scheduler-locking off}; it is also
12798 impossible to pause a specific thread. @xref{Packets, vCont}, for
12799 more details.
12800
12801 @item show remote verbose-resume-packet
12802 Show the current setting of use of the @samp{vCont} request
12803
12804 @item set remote software-breakpoint-packet
12805 @itemx set remote hardware-breakpoint-packet
12806 @itemx set remote write-watchpoint-packet
12807 @itemx set remote read-watchpoint-packet
12808 @itemx set remote access-watchpoint-packet
12809 @itemx set remote Z-packet
12810 @cindex Z-packet
12811 @cindex remote hardware breakpoints and watchpoints
12812 These commands enable or disable the use of @samp{Z} packets for
12813 setting breakpoints and watchpoints in the remote target. The default
12814 depends on the remote stub's support of the @samp{Z} packets
12815 (@value{GDBN} queries the stub when each packet is first required).
12816 The command @code{set remote Z-packet}, kept for back-compatibility,
12817 turns on or off all the features that require the use of @samp{Z}
12818 packets.
12819
12820 @item show remote software-breakpoint-packet
12821 @itemx show remote hardware-breakpoint-packet
12822 @itemx show remote write-watchpoint-packet
12823 @itemx show remote read-watchpoint-packet
12824 @itemx show remote access-watchpoint-packet
12825 @itemx show remote Z-packet
12826 Show the current setting of @samp{Z} packets usage.
12827
12828 @item set remote get-thread-local-storage-address
12829 @kindex set remote get-thread-local-storage-address
12830 @cindex thread local storage of remote targets
12831 This command enables or disables the use of the @samp{qGetTLSAddr}
12832 (Get Thread Local Storage Address) request packet. The default
12833 depends on whether the remote stub supports this request.
12834 @xref{General Query Packets, qGetTLSAddr}, for more details about this
12835 packet.
12836
12837 @item show remote get-thread-local-storage-address
12838 @kindex show remote get-thread-local-storage-address
12839 Show the current setting of @samp{qGetTLSAddr} packet usage.
12840
12841 @item set remote supported-packets
12842 @kindex set remote supported-packets
12843 @cindex query supported packets of remote targets
12844 This command enables or disables the use of the @samp{qSupported}
12845 request packet. @xref{General Query Packets, qSupported}, for more
12846 details about this packet. The default is to use @samp{qSupported}.
12847
12848 @item show remote supported-packets
12849 @kindex show remote supported-packets
12850 Show the current setting of @samp{qSupported} packet usage.
12851 @end table
12852
12853 @node remote stub
12854 @section Implementing a remote stub
12855
12856 @cindex debugging stub, example
12857 @cindex remote stub, example
12858 @cindex stub example, remote debugging
12859 The stub files provided with @value{GDBN} implement the target side of the
12860 communication protocol, and the @value{GDBN} side is implemented in the
12861 @value{GDBN} source file @file{remote.c}. Normally, you can simply allow
12862 these subroutines to communicate, and ignore the details. (If you're
12863 implementing your own stub file, you can still ignore the details: start
12864 with one of the existing stub files. @file{sparc-stub.c} is the best
12865 organized, and therefore the easiest to read.)
12866
12867 @cindex remote serial debugging, overview
12868 To debug a program running on another machine (the debugging
12869 @dfn{target} machine), you must first arrange for all the usual
12870 prerequisites for the program to run by itself. For example, for a C
12871 program, you need:
12872
12873 @enumerate
12874 @item
12875 A startup routine to set up the C runtime environment; these usually
12876 have a name like @file{crt0}. The startup routine may be supplied by
12877 your hardware supplier, or you may have to write your own.
12878
12879 @item
12880 A C subroutine library to support your program's
12881 subroutine calls, notably managing input and output.
12882
12883 @item
12884 A way of getting your program to the other machine---for example, a
12885 download program. These are often supplied by the hardware
12886 manufacturer, but you may have to write your own from hardware
12887 documentation.
12888 @end enumerate
12889
12890 The next step is to arrange for your program to use a serial port to
12891 communicate with the machine where @value{GDBN} is running (the @dfn{host}
12892 machine). In general terms, the scheme looks like this:
12893
12894 @table @emph
12895 @item On the host,
12896 @value{GDBN} already understands how to use this protocol; when everything
12897 else is set up, you can simply use the @samp{target remote} command
12898 (@pxref{Targets,,Specifying a Debugging Target}).
12899
12900 @item On the target,
12901 you must link with your program a few special-purpose subroutines that
12902 implement the @value{GDBN} remote serial protocol. The file containing these
12903 subroutines is called a @dfn{debugging stub}.
12904
12905 On certain remote targets, you can use an auxiliary program
12906 @code{gdbserver} instead of linking a stub into your program.
12907 @xref{Server,,Using the @code{gdbserver} program}, for details.
12908 @end table
12909
12910 The debugging stub is specific to the architecture of the remote
12911 machine; for example, use @file{sparc-stub.c} to debug programs on
12912 @sc{sparc} boards.
12913
12914 @cindex remote serial stub list
12915 These working remote stubs are distributed with @value{GDBN}:
12916
12917 @table @code
12918
12919 @item i386-stub.c
12920 @cindex @file{i386-stub.c}
12921 @cindex Intel
12922 @cindex i386
12923 For Intel 386 and compatible architectures.
12924
12925 @item m68k-stub.c
12926 @cindex @file{m68k-stub.c}
12927 @cindex Motorola 680x0
12928 @cindex m680x0
12929 For Motorola 680x0 architectures.
12930
12931 @item sh-stub.c
12932 @cindex @file{sh-stub.c}
12933 @cindex Renesas
12934 @cindex SH
12935 For Renesas SH architectures.
12936
12937 @item sparc-stub.c
12938 @cindex @file{sparc-stub.c}
12939 @cindex Sparc
12940 For @sc{sparc} architectures.
12941
12942 @item sparcl-stub.c
12943 @cindex @file{sparcl-stub.c}
12944 @cindex Fujitsu
12945 @cindex SparcLite
12946 For Fujitsu @sc{sparclite} architectures.
12947
12948 @end table
12949
12950 The @file{README} file in the @value{GDBN} distribution may list other
12951 recently added stubs.
12952
12953 @menu
12954 * Stub Contents:: What the stub can do for you
12955 * Bootstrapping:: What you must do for the stub
12956 * Debug Session:: Putting it all together
12957 @end menu
12958
12959 @node Stub Contents
12960 @subsection What the stub can do for you
12961
12962 @cindex remote serial stub
12963 The debugging stub for your architecture supplies these three
12964 subroutines:
12965
12966 @table @code
12967 @item set_debug_traps
12968 @findex set_debug_traps
12969 @cindex remote serial stub, initialization
12970 This routine arranges for @code{handle_exception} to run when your
12971 program stops. You must call this subroutine explicitly near the
12972 beginning of your program.
12973
12974 @item handle_exception
12975 @findex handle_exception
12976 @cindex remote serial stub, main routine
12977 This is the central workhorse, but your program never calls it
12978 explicitly---the setup code arranges for @code{handle_exception} to
12979 run when a trap is triggered.
12980
12981 @code{handle_exception} takes control when your program stops during
12982 execution (for example, on a breakpoint), and mediates communications
12983 with @value{GDBN} on the host machine. This is where the communications
12984 protocol is implemented; @code{handle_exception} acts as the @value{GDBN}
12985 representative on the target machine. It begins by sending summary
12986 information on the state of your program, then continues to execute,
12987 retrieving and transmitting any information @value{GDBN} needs, until you
12988 execute a @value{GDBN} command that makes your program resume; at that point,
12989 @code{handle_exception} returns control to your own code on the target
12990 machine.
12991
12992 @item breakpoint
12993 @cindex @code{breakpoint} subroutine, remote
12994 Use this auxiliary subroutine to make your program contain a
12995 breakpoint. Depending on the particular situation, this may be the only
12996 way for @value{GDBN} to get control. For instance, if your target
12997 machine has some sort of interrupt button, you won't need to call this;
12998 pressing the interrupt button transfers control to
12999 @code{handle_exception}---in effect, to @value{GDBN}. On some machines,
13000 simply receiving characters on the serial port may also trigger a trap;
13001 again, in that situation, you don't need to call @code{breakpoint} from
13002 your own program---simply running @samp{target remote} from the host
13003 @value{GDBN} session gets control.
13004
13005 Call @code{breakpoint} if none of these is true, or if you simply want
13006 to make certain your program stops at a predetermined point for the
13007 start of your debugging session.
13008 @end table
13009
13010 @node Bootstrapping
13011 @subsection What you must do for the stub
13012
13013 @cindex remote stub, support routines
13014 The debugging stubs that come with @value{GDBN} are set up for a particular
13015 chip architecture, but they have no information about the rest of your
13016 debugging target machine.
13017
13018 First of all you need to tell the stub how to communicate with the
13019 serial port.
13020
13021 @table @code
13022 @item int getDebugChar()
13023 @findex getDebugChar
13024 Write this subroutine to read a single character from the serial port.
13025 It may be identical to @code{getchar} for your target system; a
13026 different name is used to allow you to distinguish the two if you wish.
13027
13028 @item void putDebugChar(int)
13029 @findex putDebugChar
13030 Write this subroutine to write a single character to the serial port.
13031 It may be identical to @code{putchar} for your target system; a
13032 different name is used to allow you to distinguish the two if you wish.
13033 @end table
13034
13035 @cindex control C, and remote debugging
13036 @cindex interrupting remote targets
13037 If you want @value{GDBN} to be able to stop your program while it is
13038 running, you need to use an interrupt-driven serial driver, and arrange
13039 for it to stop when it receives a @code{^C} (@samp{\003}, the control-C
13040 character). That is the character which @value{GDBN} uses to tell the
13041 remote system to stop.
13042
13043 Getting the debugging target to return the proper status to @value{GDBN}
13044 probably requires changes to the standard stub; one quick and dirty way
13045 is to just execute a breakpoint instruction (the ``dirty'' part is that
13046 @value{GDBN} reports a @code{SIGTRAP} instead of a @code{SIGINT}).
13047
13048 Other routines you need to supply are:
13049
13050 @table @code
13051 @item void exceptionHandler (int @var{exception_number}, void *@var{exception_address})
13052 @findex exceptionHandler
13053 Write this function to install @var{exception_address} in the exception
13054 handling tables. You need to do this because the stub does not have any
13055 way of knowing what the exception handling tables on your target system
13056 are like (for example, the processor's table might be in @sc{rom},
13057 containing entries which point to a table in @sc{ram}).
13058 @var{exception_number} is the exception number which should be changed;
13059 its meaning is architecture-dependent (for example, different numbers
13060 might represent divide by zero, misaligned access, etc). When this
13061 exception occurs, control should be transferred directly to
13062 @var{exception_address}, and the processor state (stack, registers,
13063 and so on) should be just as it is when a processor exception occurs. So if
13064 you want to use a jump instruction to reach @var{exception_address}, it
13065 should be a simple jump, not a jump to subroutine.
13066
13067 For the 386, @var{exception_address} should be installed as an interrupt
13068 gate so that interrupts are masked while the handler runs. The gate
13069 should be at privilege level 0 (the most privileged level). The
13070 @sc{sparc} and 68k stubs are able to mask interrupts themselves without
13071 help from @code{exceptionHandler}.
13072
13073 @item void flush_i_cache()
13074 @findex flush_i_cache
13075 On @sc{sparc} and @sc{sparclite} only, write this subroutine to flush the
13076 instruction cache, if any, on your target machine. If there is no
13077 instruction cache, this subroutine may be a no-op.
13078
13079 On target machines that have instruction caches, @value{GDBN} requires this
13080 function to make certain that the state of your program is stable.
13081 @end table
13082
13083 @noindent
13084 You must also make sure this library routine is available:
13085
13086 @table @code
13087 @item void *memset(void *, int, int)
13088 @findex memset
13089 This is the standard library function @code{memset} that sets an area of
13090 memory to a known value. If you have one of the free versions of
13091 @code{libc.a}, @code{memset} can be found there; otherwise, you must
13092 either obtain it from your hardware manufacturer, or write your own.
13093 @end table
13094
13095 If you do not use the GNU C compiler, you may need other standard
13096 library subroutines as well; this varies from one stub to another,
13097 but in general the stubs are likely to use any of the common library
13098 subroutines which @code{@value{GCC}} generates as inline code.
13099
13100
13101 @node Debug Session
13102 @subsection Putting it all together
13103
13104 @cindex remote serial debugging summary
13105 In summary, when your program is ready to debug, you must follow these
13106 steps.
13107
13108 @enumerate
13109 @item
13110 Make sure you have defined the supporting low-level routines
13111 (@pxref{Bootstrapping,,What you must do for the stub}):
13112 @display
13113 @code{getDebugChar}, @code{putDebugChar},
13114 @code{flush_i_cache}, @code{memset}, @code{exceptionHandler}.
13115 @end display
13116
13117 @item
13118 Insert these lines near the top of your program:
13119
13120 @smallexample
13121 set_debug_traps();
13122 breakpoint();
13123 @end smallexample
13124
13125 @item
13126 For the 680x0 stub only, you need to provide a variable called
13127 @code{exceptionHook}. Normally you just use:
13128
13129 @smallexample
13130 void (*exceptionHook)() = 0;
13131 @end smallexample
13132
13133 @noindent
13134 but if before calling @code{set_debug_traps}, you set it to point to a
13135 function in your program, that function is called when
13136 @code{@value{GDBN}} continues after stopping on a trap (for example, bus
13137 error). The function indicated by @code{exceptionHook} is called with
13138 one parameter: an @code{int} which is the exception number.
13139
13140 @item
13141 Compile and link together: your program, the @value{GDBN} debugging stub for
13142 your target architecture, and the supporting subroutines.
13143
13144 @item
13145 Make sure you have a serial connection between your target machine and
13146 the @value{GDBN} host, and identify the serial port on the host.
13147
13148 @item
13149 @c The "remote" target now provides a `load' command, so we should
13150 @c document that. FIXME.
13151 Download your program to your target machine (or get it there by
13152 whatever means the manufacturer provides), and start it.
13153
13154 @item
13155 Start @value{GDBN} on the host, and connect to the target
13156 (@pxref{Connecting,,Connecting to a remote target}).
13157
13158 @end enumerate
13159
13160 @node Configurations
13161 @chapter Configuration-Specific Information
13162
13163 While nearly all @value{GDBN} commands are available for all native and
13164 cross versions of the debugger, there are some exceptions. This chapter
13165 describes things that are only available in certain configurations.
13166
13167 There are three major categories of configurations: native
13168 configurations, where the host and target are the same, embedded
13169 operating system configurations, which are usually the same for several
13170 different processor architectures, and bare embedded processors, which
13171 are quite different from each other.
13172
13173 @menu
13174 * Native::
13175 * Embedded OS::
13176 * Embedded Processors::
13177 * Architectures::
13178 @end menu
13179
13180 @node Native
13181 @section Native
13182
13183 This section describes details specific to particular native
13184 configurations.
13185
13186 @menu
13187 * HP-UX:: HP-UX
13188 * BSD libkvm Interface:: Debugging BSD kernel memory images
13189 * SVR4 Process Information:: SVR4 process information
13190 * DJGPP Native:: Features specific to the DJGPP port
13191 * Cygwin Native:: Features specific to the Cygwin port
13192 * Hurd Native:: Features specific to @sc{gnu} Hurd
13193 * Neutrino:: Features specific to QNX Neutrino
13194 @end menu
13195
13196 @node HP-UX
13197 @subsection HP-UX
13198
13199 On HP-UX systems, if you refer to a function or variable name that
13200 begins with a dollar sign, @value{GDBN} searches for a user or system
13201 name first, before it searches for a convenience variable.
13202
13203
13204 @node BSD libkvm Interface
13205 @subsection BSD libkvm Interface
13206
13207 @cindex libkvm
13208 @cindex kernel memory image
13209 @cindex kernel crash dump
13210
13211 BSD-derived systems (FreeBSD/NetBSD/OpenBSD) have a kernel memory
13212 interface that provides a uniform interface for accessing kernel virtual
13213 memory images, including live systems and crash dumps. @value{GDBN}
13214 uses this interface to allow you to debug live kernels and kernel crash
13215 dumps on many native BSD configurations. This is implemented as a
13216 special @code{kvm} debugging target. For debugging a live system, load
13217 the currently running kernel into @value{GDBN} and connect to the
13218 @code{kvm} target:
13219
13220 @smallexample
13221 (@value{GDBP}) @b{target kvm}
13222 @end smallexample
13223
13224 For debugging crash dumps, provide the file name of the crash dump as an
13225 argument:
13226
13227 @smallexample
13228 (@value{GDBP}) @b{target kvm /var/crash/bsd.0}
13229 @end smallexample
13230
13231 Once connected to the @code{kvm} target, the following commands are
13232 available:
13233
13234 @table @code
13235 @kindex kvm
13236 @item kvm pcb
13237 Set current context from the @dfn{Process Control Block} (PCB) address.
13238
13239 @item kvm proc
13240 Set current context from proc address. This command isn't available on
13241 modern FreeBSD systems.
13242 @end table
13243
13244 @node SVR4 Process Information
13245 @subsection SVR4 process information
13246 @cindex /proc
13247 @cindex examine process image
13248 @cindex process info via @file{/proc}
13249
13250 Many versions of SVR4 and compatible systems provide a facility called
13251 @samp{/proc} that can be used to examine the image of a running
13252 process using file-system subroutines. If @value{GDBN} is configured
13253 for an operating system with this facility, the command @code{info
13254 proc} is available to report information about the process running
13255 your program, or about any process running on your system. @code{info
13256 proc} works only on SVR4 systems that include the @code{procfs} code.
13257 This includes, as of this writing, @sc{gnu}/Linux, OSF/1 (Digital
13258 Unix), Solaris, Irix, and Unixware, but not HP-UX, for example.
13259
13260 @table @code
13261 @kindex info proc
13262 @cindex process ID
13263 @item info proc
13264 @itemx info proc @var{process-id}
13265 Summarize available information about any running process. If a
13266 process ID is specified by @var{process-id}, display information about
13267 that process; otherwise display information about the program being
13268 debugged. The summary includes the debugged process ID, the command
13269 line used to invoke it, its current working directory, and its
13270 executable file's absolute file name.
13271
13272 On some systems, @var{process-id} can be of the form
13273 @samp{[@var{pid}]/@var{tid}} which specifies a certain thread ID
13274 within a process. If the optional @var{pid} part is missing, it means
13275 a thread from the process being debugged (the leading @samp{/} still
13276 needs to be present, or else @value{GDBN} will interpret the number as
13277 a process ID rather than a thread ID).
13278
13279 @item info proc mappings
13280 @cindex memory address space mappings
13281 Report the memory address space ranges accessible in the program, with
13282 information on whether the process has read, write, or execute access
13283 rights to each range. On @sc{gnu}/Linux systems, each memory range
13284 includes the object file which is mapped to that range, instead of the
13285 memory access rights to that range.
13286
13287 @item info proc stat
13288 @itemx info proc status
13289 @cindex process detailed status information
13290 These subcommands are specific to @sc{gnu}/Linux systems. They show
13291 the process-related information, including the user ID and group ID;
13292 how many threads are there in the process; its virtual memory usage;
13293 the signals that are pending, blocked, and ignored; its TTY; its
13294 consumption of system and user time; its stack size; its @samp{nice}
13295 value; etc. For more information, see the @samp{proc} man page
13296 (type @kbd{man 5 proc} from your shell prompt).
13297
13298 @item info proc all
13299 Show all the information about the process described under all of the
13300 above @code{info proc} subcommands.
13301
13302 @ignore
13303 @comment These sub-options of 'info proc' were not included when
13304 @comment procfs.c was re-written. Keep their descriptions around
13305 @comment against the day when someone finds the time to put them back in.
13306 @kindex info proc times
13307 @item info proc times
13308 Starting time, user CPU time, and system CPU time for your program and
13309 its children.
13310
13311 @kindex info proc id
13312 @item info proc id
13313 Report on the process IDs related to your program: its own process ID,
13314 the ID of its parent, the process group ID, and the session ID.
13315 @end ignore
13316
13317 @item set procfs-trace
13318 @kindex set procfs-trace
13319 @cindex @code{procfs} API calls
13320 This command enables and disables tracing of @code{procfs} API calls.
13321
13322 @item show procfs-trace
13323 @kindex show procfs-trace
13324 Show the current state of @code{procfs} API call tracing.
13325
13326 @item set procfs-file @var{file}
13327 @kindex set procfs-file
13328 Tell @value{GDBN} to write @code{procfs} API trace to the named
13329 @var{file}. @value{GDBN} appends the trace info to the previous
13330 contents of the file. The default is to display the trace on the
13331 standard output.
13332
13333 @item show procfs-file
13334 @kindex show procfs-file
13335 Show the file to which @code{procfs} API trace is written.
13336
13337 @item proc-trace-entry
13338 @itemx proc-trace-exit
13339 @itemx proc-untrace-entry
13340 @itemx proc-untrace-exit
13341 @kindex proc-trace-entry
13342 @kindex proc-trace-exit
13343 @kindex proc-untrace-entry
13344 @kindex proc-untrace-exit
13345 These commands enable and disable tracing of entries into and exits
13346 from the @code{syscall} interface.
13347
13348 @item info pidlist
13349 @kindex info pidlist
13350 @cindex process list, QNX Neutrino
13351 For QNX Neutrino only, this command displays the list of all the
13352 processes and all the threads within each process.
13353
13354 @item info meminfo
13355 @kindex info meminfo
13356 @cindex mapinfo list, QNX Neutrino
13357 For QNX Neutrino only, this command displays the list of all mapinfos.
13358 @end table
13359
13360 @node DJGPP Native
13361 @subsection Features for Debugging @sc{djgpp} Programs
13362 @cindex @sc{djgpp} debugging
13363 @cindex native @sc{djgpp} debugging
13364 @cindex MS-DOS-specific commands
13365
13366 @cindex DPMI
13367 @sc{djgpp} is a port of the @sc{gnu} development tools to MS-DOS and
13368 MS-Windows. @sc{djgpp} programs are 32-bit protected-mode programs
13369 that use the @dfn{DPMI} (DOS Protected-Mode Interface) API to run on
13370 top of real-mode DOS systems and their emulations.
13371
13372 @value{GDBN} supports native debugging of @sc{djgpp} programs, and
13373 defines a few commands specific to the @sc{djgpp} port. This
13374 subsection describes those commands.
13375
13376 @table @code
13377 @kindex info dos
13378 @item info dos
13379 This is a prefix of @sc{djgpp}-specific commands which print
13380 information about the target system and important OS structures.
13381
13382 @kindex sysinfo
13383 @cindex MS-DOS system info
13384 @cindex free memory information (MS-DOS)
13385 @item info dos sysinfo
13386 This command displays assorted information about the underlying
13387 platform: the CPU type and features, the OS version and flavor, the
13388 DPMI version, and the available conventional and DPMI memory.
13389
13390 @cindex GDT
13391 @cindex LDT
13392 @cindex IDT
13393 @cindex segment descriptor tables
13394 @cindex descriptor tables display
13395 @item info dos gdt
13396 @itemx info dos ldt
13397 @itemx info dos idt
13398 These 3 commands display entries from, respectively, Global, Local,
13399 and Interrupt Descriptor Tables (GDT, LDT, and IDT). The descriptor
13400 tables are data structures which store a descriptor for each segment
13401 that is currently in use. The segment's selector is an index into a
13402 descriptor table; the table entry for that index holds the
13403 descriptor's base address and limit, and its attributes and access
13404 rights.
13405
13406 A typical @sc{djgpp} program uses 3 segments: a code segment, a data
13407 segment (used for both data and the stack), and a DOS segment (which
13408 allows access to DOS/BIOS data structures and absolute addresses in
13409 conventional memory). However, the DPMI host will usually define
13410 additional segments in order to support the DPMI environment.
13411
13412 @cindex garbled pointers
13413 These commands allow to display entries from the descriptor tables.
13414 Without an argument, all entries from the specified table are
13415 displayed. An argument, which should be an integer expression, means
13416 display a single entry whose index is given by the argument. For
13417 example, here's a convenient way to display information about the
13418 debugged program's data segment:
13419
13420 @smallexample
13421 @exdent @code{(@value{GDBP}) info dos ldt $ds}
13422 @exdent @code{0x13f: base=0x11970000 limit=0x0009ffff 32-Bit Data (Read/Write, Exp-up)}
13423 @end smallexample
13424
13425 @noindent
13426 This comes in handy when you want to see whether a pointer is outside
13427 the data segment's limit (i.e.@: @dfn{garbled}).
13428
13429 @cindex page tables display (MS-DOS)
13430 @item info dos pde
13431 @itemx info dos pte
13432 These two commands display entries from, respectively, the Page
13433 Directory and the Page Tables. Page Directories and Page Tables are
13434 data structures which control how virtual memory addresses are mapped
13435 into physical addresses. A Page Table includes an entry for every
13436 page of memory that is mapped into the program's address space; there
13437 may be several Page Tables, each one holding up to 4096 entries. A
13438 Page Directory has up to 4096 entries, one each for every Page Table
13439 that is currently in use.
13440
13441 Without an argument, @kbd{info dos pde} displays the entire Page
13442 Directory, and @kbd{info dos pte} displays all the entries in all of
13443 the Page Tables. An argument, an integer expression, given to the
13444 @kbd{info dos pde} command means display only that entry from the Page
13445 Directory table. An argument given to the @kbd{info dos pte} command
13446 means display entries from a single Page Table, the one pointed to by
13447 the specified entry in the Page Directory.
13448
13449 @cindex direct memory access (DMA) on MS-DOS
13450 These commands are useful when your program uses @dfn{DMA} (Direct
13451 Memory Access), which needs physical addresses to program the DMA
13452 controller.
13453
13454 These commands are supported only with some DPMI servers.
13455
13456 @cindex physical address from linear address
13457 @item info dos address-pte @var{addr}
13458 This command displays the Page Table entry for a specified linear
13459 address. The argument @var{addr} is a linear address which should
13460 already have the appropriate segment's base address added to it,
13461 because this command accepts addresses which may belong to @emph{any}
13462 segment. For example, here's how to display the Page Table entry for
13463 the page where a variable @code{i} is stored:
13464
13465 @smallexample
13466 @exdent @code{(@value{GDBP}) info dos address-pte __djgpp_base_address + (char *)&i}
13467 @exdent @code{Page Table entry for address 0x11a00d30:}
13468 @exdent @code{Base=0x02698000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0xd30}
13469 @end smallexample
13470
13471 @noindent
13472 This says that @code{i} is stored at offset @code{0xd30} from the page
13473 whose physical base address is @code{0x02698000}, and shows all the
13474 attributes of that page.
13475
13476 Note that you must cast the addresses of variables to a @code{char *},
13477 since otherwise the value of @code{__djgpp_base_address}, the base
13478 address of all variables and functions in a @sc{djgpp} program, will
13479 be added using the rules of C pointer arithmetics: if @code{i} is
13480 declared an @code{int}, @value{GDBN} will add 4 times the value of
13481 @code{__djgpp_base_address} to the address of @code{i}.
13482
13483 Here's another example, it displays the Page Table entry for the
13484 transfer buffer:
13485
13486 @smallexample
13487 @exdent @code{(@value{GDBP}) info dos address-pte *((unsigned *)&_go32_info_block + 3)}
13488 @exdent @code{Page Table entry for address 0x29110:}
13489 @exdent @code{Base=0x00029000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0x110}
13490 @end smallexample
13491
13492 @noindent
13493 (The @code{+ 3} offset is because the transfer buffer's address is the
13494 3rd member of the @code{_go32_info_block} structure.) The output
13495 clearly shows that this DPMI server maps the addresses in conventional
13496 memory 1:1, i.e.@: the physical (@code{0x00029000} + @code{0x110}) and
13497 linear (@code{0x29110}) addresses are identical.
13498
13499 This command is supported only with some DPMI servers.
13500 @end table
13501
13502 @cindex DOS serial data link, remote debugging
13503 In addition to native debugging, the DJGPP port supports remote
13504 debugging via a serial data link. The following commands are specific
13505 to remote serial debugging in the DJGPP port of @value{GDBN}.
13506
13507 @table @code
13508 @kindex set com1base
13509 @kindex set com1irq
13510 @kindex set com2base
13511 @kindex set com2irq
13512 @kindex set com3base
13513 @kindex set com3irq
13514 @kindex set com4base
13515 @kindex set com4irq
13516 @item set com1base @var{addr}
13517 This command sets the base I/O port address of the @file{COM1} serial
13518 port.
13519
13520 @item set com1irq @var{irq}
13521 This command sets the @dfn{Interrupt Request} (@code{IRQ}) line to use
13522 for the @file{COM1} serial port.
13523
13524 There are similar commands @samp{set com2base}, @samp{set com3irq},
13525 etc.@: for setting the port address and the @code{IRQ} lines for the
13526 other 3 COM ports.
13527
13528 @kindex show com1base
13529 @kindex show com1irq
13530 @kindex show com2base
13531 @kindex show com2irq
13532 @kindex show com3base
13533 @kindex show com3irq
13534 @kindex show com4base
13535 @kindex show com4irq
13536 The related commands @samp{show com1base}, @samp{show com1irq} etc.@:
13537 display the current settings of the base address and the @code{IRQ}
13538 lines used by the COM ports.
13539
13540 @item info serial
13541 @kindex info serial
13542 @cindex DOS serial port status
13543 This command prints the status of the 4 DOS serial ports. For each
13544 port, it prints whether it's active or not, its I/O base address and
13545 IRQ number, whether it uses a 16550-style FIFO, its baudrate, and the
13546 counts of various errors encountered so far.
13547 @end table
13548
13549
13550 @node Cygwin Native
13551 @subsection Features for Debugging MS Windows PE executables
13552 @cindex MS Windows debugging
13553 @cindex native Cygwin debugging
13554 @cindex Cygwin-specific commands
13555
13556 @value{GDBN} supports native debugging of MS Windows programs, including
13557 DLLs with and without symbolic debugging information. There are various
13558 additional Cygwin-specific commands, described in this subsection. The
13559 subsubsection @pxref{Non-debug DLL symbols} describes working with DLLs
13560 that have no debugging symbols.
13561
13562
13563 @table @code
13564 @kindex info w32
13565 @item info w32
13566 This is a prefix of MS Windows specific commands which print
13567 information about the target system and important OS structures.
13568
13569 @item info w32 selector
13570 This command displays information returned by
13571 the Win32 API @code{GetThreadSelectorEntry} function.
13572 It takes an optional argument that is evaluated to
13573 a long value to give the information about this given selector.
13574 Without argument, this command displays information
13575 about the the six segment registers.
13576
13577 @kindex info dll
13578 @item info dll
13579 This is a Cygwin specific alias of info shared.
13580
13581 @kindex dll-symbols
13582 @item dll-symbols
13583 This command loads symbols from a dll similarly to
13584 add-sym command but without the need to specify a base address.
13585
13586 @kindex set cygwin-exceptions
13587 @cindex debugging the Cygwin DLL
13588 @cindex Cygwin DLL, debugging
13589 @item set cygwin-exceptions @var{mode}
13590 If @var{mode} is @code{on}, @value{GDBN} will break on exceptions that
13591 happen inside the Cygwin DLL. If @var{mode} is @code{off},
13592 @value{GDBN} will delay recognition of exceptions, and may ignore some
13593 exceptions which seem to be caused by internal Cygwin DLL
13594 ``bookkeeping''. This option is meant primarily for debugging the
13595 Cygwin DLL itself; the default value is @code{off} to avoid annoying
13596 @value{GDBN} users with false @code{SIGSEGV} signals.
13597
13598 @kindex show cygwin-exceptions
13599 @item show cygwin-exceptions
13600 Displays whether @value{GDBN} will break on exceptions that happen
13601 inside the Cygwin DLL itself.
13602
13603 @kindex set new-console
13604 @item set new-console @var{mode}
13605 If @var{mode} is @code{on} the debuggee will
13606 be started in a new console on next start.
13607 If @var{mode} is @code{off}i, the debuggee will
13608 be started in the same console as the debugger.
13609
13610 @kindex show new-console
13611 @item show new-console
13612 Displays whether a new console is used
13613 when the debuggee is started.
13614
13615 @kindex set new-group
13616 @item set new-group @var{mode}
13617 This boolean value controls whether the debuggee should
13618 start a new group or stay in the same group as the debugger.
13619 This affects the way the Windows OS handles
13620 @samp{Ctrl-C}.
13621
13622 @kindex show new-group
13623 @item show new-group
13624 Displays current value of new-group boolean.
13625
13626 @kindex set debugevents
13627 @item set debugevents
13628 This boolean value adds debug output concerning kernel events related
13629 to the debuggee seen by the debugger. This includes events that
13630 signal thread and process creation and exit, DLL loading and
13631 unloading, console interrupts, and debugging messages produced by the
13632 Windows @code{OutputDebugString} API call.
13633
13634 @kindex set debugexec
13635 @item set debugexec
13636 This boolean value adds debug output concerning execute events
13637 (such as resume thread) seen by the debugger.
13638
13639 @kindex set debugexceptions
13640 @item set debugexceptions
13641 This boolean value adds debug output concerning exceptions in the
13642 debuggee seen by the debugger.
13643
13644 @kindex set debugmemory
13645 @item set debugmemory
13646 This boolean value adds debug output concerning debuggee memory reads
13647 and writes by the debugger.
13648
13649 @kindex set shell
13650 @item set shell
13651 This boolean values specifies whether the debuggee is called
13652 via a shell or directly (default value is on).
13653
13654 @kindex show shell
13655 @item show shell
13656 Displays if the debuggee will be started with a shell.
13657
13658 @end table
13659
13660 @menu
13661 * Non-debug DLL symbols:: Support for DLLs without debugging symbols
13662 @end menu
13663
13664 @node Non-debug DLL symbols
13665 @subsubsection Support for DLLs without debugging symbols
13666 @cindex DLLs with no debugging symbols
13667 @cindex Minimal symbols and DLLs
13668
13669 Very often on windows, some of the DLLs that your program relies on do
13670 not include symbolic debugging information (for example,
13671 @file{kernel32.dll}). When @value{GDBN} doesn't recognize any debugging
13672 symbols in a DLL, it relies on the minimal amount of symbolic
13673 information contained in the DLL's export table. This subsubsection
13674 describes working with such symbols, known internally to @value{GDBN} as
13675 ``minimal symbols''.
13676
13677 Note that before the debugged program has started execution, no DLLs
13678 will have been loaded. The easiest way around this problem is simply to
13679 start the program --- either by setting a breakpoint or letting the
13680 program run once to completion. It is also possible to force
13681 @value{GDBN} to load a particular DLL before starting the executable ---
13682 see the shared library information in @pxref{Files} or the
13683 @code{dll-symbols} command in @pxref{Cygwin Native}. Currently,
13684 explicitly loading symbols from a DLL with no debugging information will
13685 cause the symbol names to be duplicated in @value{GDBN}'s lookup table,
13686 which may adversely affect symbol lookup performance.
13687
13688 @subsubsection DLL name prefixes
13689
13690 In keeping with the naming conventions used by the Microsoft debugging
13691 tools, DLL export symbols are made available with a prefix based on the
13692 DLL name, for instance @code{KERNEL32!CreateFileA}. The plain name is
13693 also entered into the symbol table, so @code{CreateFileA} is often
13694 sufficient. In some cases there will be name clashes within a program
13695 (particularly if the executable itself includes full debugging symbols)
13696 necessitating the use of the fully qualified name when referring to the
13697 contents of the DLL. Use single-quotes around the name to avoid the
13698 exclamation mark (``!'') being interpreted as a language operator.
13699
13700 Note that the internal name of the DLL may be all upper-case, even
13701 though the file name of the DLL is lower-case, or vice-versa. Since
13702 symbols within @value{GDBN} are @emph{case-sensitive} this may cause
13703 some confusion. If in doubt, try the @code{info functions} and
13704 @code{info variables} commands or even @code{maint print msymbols} (see
13705 @pxref{Symbols}). Here's an example:
13706
13707 @smallexample
13708 (@value{GDBP}) info function CreateFileA
13709 All functions matching regular expression "CreateFileA":
13710
13711 Non-debugging symbols:
13712 0x77e885f4 CreateFileA
13713 0x77e885f4 KERNEL32!CreateFileA
13714 @end smallexample
13715
13716 @smallexample
13717 (@value{GDBP}) info function !
13718 All functions matching regular expression "!":
13719
13720 Non-debugging symbols:
13721 0x6100114c cygwin1!__assert
13722 0x61004034 cygwin1!_dll_crt0@@0
13723 0x61004240 cygwin1!dll_crt0(per_process *)
13724 [etc...]
13725 @end smallexample
13726
13727 @subsubsection Working with minimal symbols
13728
13729 Symbols extracted from a DLL's export table do not contain very much
13730 type information. All that @value{GDBN} can do is guess whether a symbol
13731 refers to a function or variable depending on the linker section that
13732 contains the symbol. Also note that the actual contents of the memory
13733 contained in a DLL are not available unless the program is running. This
13734 means that you cannot examine the contents of a variable or disassemble
13735 a function within a DLL without a running program.
13736
13737 Variables are generally treated as pointers and dereferenced
13738 automatically. For this reason, it is often necessary to prefix a
13739 variable name with the address-of operator (``&'') and provide explicit
13740 type information in the command. Here's an example of the type of
13741 problem:
13742
13743 @smallexample
13744 (@value{GDBP}) print 'cygwin1!__argv'
13745 $1 = 268572168
13746 @end smallexample
13747
13748 @smallexample
13749 (@value{GDBP}) x 'cygwin1!__argv'
13750 0x10021610: "\230y\""
13751 @end smallexample
13752
13753 And two possible solutions:
13754
13755 @smallexample
13756 (@value{GDBP}) print ((char **)'cygwin1!__argv')[0]
13757 $2 = 0x22fd98 "/cygdrive/c/mydirectory/myprogram"
13758 @end smallexample
13759
13760 @smallexample
13761 (@value{GDBP}) x/2x &'cygwin1!__argv'
13762 0x610c0aa8 <cygwin1!__argv>: 0x10021608 0x00000000
13763 (@value{GDBP}) x/x 0x10021608
13764 0x10021608: 0x0022fd98
13765 (@value{GDBP}) x/s 0x0022fd98
13766 0x22fd98: "/cygdrive/c/mydirectory/myprogram"
13767 @end smallexample
13768
13769 Setting a break point within a DLL is possible even before the program
13770 starts execution. However, under these circumstances, @value{GDBN} can't
13771 examine the initial instructions of the function in order to skip the
13772 function's frame set-up code. You can work around this by using ``*&''
13773 to set the breakpoint at a raw memory address:
13774
13775 @smallexample
13776 (@value{GDBP}) break *&'python22!PyOS_Readline'
13777 Breakpoint 1 at 0x1e04eff0
13778 @end smallexample
13779
13780 The author of these extensions is not entirely convinced that setting a
13781 break point within a shared DLL like @file{kernel32.dll} is completely
13782 safe.
13783
13784 @node Hurd Native
13785 @subsection Commands specific to @sc{gnu} Hurd systems
13786 @cindex @sc{gnu} Hurd debugging
13787
13788 This subsection describes @value{GDBN} commands specific to the
13789 @sc{gnu} Hurd native debugging.
13790
13791 @table @code
13792 @item set signals
13793 @itemx set sigs
13794 @kindex set signals@r{, Hurd command}
13795 @kindex set sigs@r{, Hurd command}
13796 This command toggles the state of inferior signal interception by
13797 @value{GDBN}. Mach exceptions, such as breakpoint traps, are not
13798 affected by this command. @code{sigs} is a shorthand alias for
13799 @code{signals}.
13800
13801 @item show signals
13802 @itemx show sigs
13803 @kindex show signals@r{, Hurd command}
13804 @kindex show sigs@r{, Hurd command}
13805 Show the current state of intercepting inferior's signals.
13806
13807 @item set signal-thread
13808 @itemx set sigthread
13809 @kindex set signal-thread
13810 @kindex set sigthread
13811 This command tells @value{GDBN} which thread is the @code{libc} signal
13812 thread. That thread is run when a signal is delivered to a running
13813 process. @code{set sigthread} is the shorthand alias of @code{set
13814 signal-thread}.
13815
13816 @item show signal-thread
13817 @itemx show sigthread
13818 @kindex show signal-thread
13819 @kindex show sigthread
13820 These two commands show which thread will run when the inferior is
13821 delivered a signal.
13822
13823 @item set stopped
13824 @kindex set stopped@r{, Hurd command}
13825 This commands tells @value{GDBN} that the inferior process is stopped,
13826 as with the @code{SIGSTOP} signal. The stopped process can be
13827 continued by delivering a signal to it.
13828
13829 @item show stopped
13830 @kindex show stopped@r{, Hurd command}
13831 This command shows whether @value{GDBN} thinks the debuggee is
13832 stopped.
13833
13834 @item set exceptions
13835 @kindex set exceptions@r{, Hurd command}
13836 Use this command to turn off trapping of exceptions in the inferior.
13837 When exception trapping is off, neither breakpoints nor
13838 single-stepping will work. To restore the default, set exception
13839 trapping on.
13840
13841 @item show exceptions
13842 @kindex show exceptions@r{, Hurd command}
13843 Show the current state of trapping exceptions in the inferior.
13844
13845 @item set task pause
13846 @kindex set task@r{, Hurd commands}
13847 @cindex task attributes (@sc{gnu} Hurd)
13848 @cindex pause current task (@sc{gnu} Hurd)
13849 This command toggles task suspension when @value{GDBN} has control.
13850 Setting it to on takes effect immediately, and the task is suspended
13851 whenever @value{GDBN} gets control. Setting it to off will take
13852 effect the next time the inferior is continued. If this option is set
13853 to off, you can use @code{set thread default pause on} or @code{set
13854 thread pause on} (see below) to pause individual threads.
13855
13856 @item show task pause
13857 @kindex show task@r{, Hurd commands}
13858 Show the current state of task suspension.
13859
13860 @item set task detach-suspend-count
13861 @cindex task suspend count
13862 @cindex detach from task, @sc{gnu} Hurd
13863 This command sets the suspend count the task will be left with when
13864 @value{GDBN} detaches from it.
13865
13866 @item show task detach-suspend-count
13867 Show the suspend count the task will be left with when detaching.
13868
13869 @item set task exception-port
13870 @itemx set task excp
13871 @cindex task exception port, @sc{gnu} Hurd
13872 This command sets the task exception port to which @value{GDBN} will
13873 forward exceptions. The argument should be the value of the @dfn{send
13874 rights} of the task. @code{set task excp} is a shorthand alias.
13875
13876 @item set noninvasive
13877 @cindex noninvasive task options
13878 This command switches @value{GDBN} to a mode that is the least
13879 invasive as far as interfering with the inferior is concerned. This
13880 is the same as using @code{set task pause}, @code{set exceptions}, and
13881 @code{set signals} to values opposite to the defaults.
13882
13883 @item info send-rights
13884 @itemx info receive-rights
13885 @itemx info port-rights
13886 @itemx info port-sets
13887 @itemx info dead-names
13888 @itemx info ports
13889 @itemx info psets
13890 @cindex send rights, @sc{gnu} Hurd
13891 @cindex receive rights, @sc{gnu} Hurd
13892 @cindex port rights, @sc{gnu} Hurd
13893 @cindex port sets, @sc{gnu} Hurd
13894 @cindex dead names, @sc{gnu} Hurd
13895 These commands display information about, respectively, send rights,
13896 receive rights, port rights, port sets, and dead names of a task.
13897 There are also shorthand aliases: @code{info ports} for @code{info
13898 port-rights} and @code{info psets} for @code{info port-sets}.
13899
13900 @item set thread pause
13901 @kindex set thread@r{, Hurd command}
13902 @cindex thread properties, @sc{gnu} Hurd
13903 @cindex pause current thread (@sc{gnu} Hurd)
13904 This command toggles current thread suspension when @value{GDBN} has
13905 control. Setting it to on takes effect immediately, and the current
13906 thread is suspended whenever @value{GDBN} gets control. Setting it to
13907 off will take effect the next time the inferior is continued.
13908 Normally, this command has no effect, since when @value{GDBN} has
13909 control, the whole task is suspended. However, if you used @code{set
13910 task pause off} (see above), this command comes in handy to suspend
13911 only the current thread.
13912
13913 @item show thread pause
13914 @kindex show thread@r{, Hurd command}
13915 This command shows the state of current thread suspension.
13916
13917 @item set thread run
13918 This comamnd sets whether the current thread is allowed to run.
13919
13920 @item show thread run
13921 Show whether the current thread is allowed to run.
13922
13923 @item set thread detach-suspend-count
13924 @cindex thread suspend count, @sc{gnu} Hurd
13925 @cindex detach from thread, @sc{gnu} Hurd
13926 This command sets the suspend count @value{GDBN} will leave on a
13927 thread when detaching. This number is relative to the suspend count
13928 found by @value{GDBN} when it notices the thread; use @code{set thread
13929 takeover-suspend-count} to force it to an absolute value.
13930
13931 @item show thread detach-suspend-count
13932 Show the suspend count @value{GDBN} will leave on the thread when
13933 detaching.
13934
13935 @item set thread exception-port
13936 @itemx set thread excp
13937 Set the thread exception port to which to forward exceptions. This
13938 overrides the port set by @code{set task exception-port} (see above).
13939 @code{set thread excp} is the shorthand alias.
13940
13941 @item set thread takeover-suspend-count
13942 Normally, @value{GDBN}'s thread suspend counts are relative to the
13943 value @value{GDBN} finds when it notices each thread. This command
13944 changes the suspend counts to be absolute instead.
13945
13946 @item set thread default
13947 @itemx show thread default
13948 @cindex thread default settings, @sc{gnu} Hurd
13949 Each of the above @code{set thread} commands has a @code{set thread
13950 default} counterpart (e.g., @code{set thread default pause}, @code{set
13951 thread default exception-port}, etc.). The @code{thread default}
13952 variety of commands sets the default thread properties for all
13953 threads; you can then change the properties of individual threads with
13954 the non-default commands.
13955 @end table
13956
13957
13958 @node Neutrino
13959 @subsection QNX Neutrino
13960 @cindex QNX Neutrino
13961
13962 @value{GDBN} provides the following commands specific to the QNX
13963 Neutrino target:
13964
13965 @table @code
13966 @item set debug nto-debug
13967 @kindex set debug nto-debug
13968 When set to on, enables debugging messages specific to the QNX
13969 Neutrino support.
13970
13971 @item show debug nto-debug
13972 @kindex show debug nto-debug
13973 Show the current state of QNX Neutrino messages.
13974 @end table
13975
13976
13977 @node Embedded OS
13978 @section Embedded Operating Systems
13979
13980 This section describes configurations involving the debugging of
13981 embedded operating systems that are available for several different
13982 architectures.
13983
13984 @menu
13985 * VxWorks:: Using @value{GDBN} with VxWorks
13986 @end menu
13987
13988 @value{GDBN} includes the ability to debug programs running on
13989 various real-time operating systems.
13990
13991 @node VxWorks
13992 @subsection Using @value{GDBN} with VxWorks
13993
13994 @cindex VxWorks
13995
13996 @table @code
13997
13998 @kindex target vxworks
13999 @item target vxworks @var{machinename}
14000 A VxWorks system, attached via TCP/IP. The argument @var{machinename}
14001 is the target system's machine name or IP address.
14002
14003 @end table
14004
14005 On VxWorks, @code{load} links @var{filename} dynamically on the
14006 current target system as well as adding its symbols in @value{GDBN}.
14007
14008 @value{GDBN} enables developers to spawn and debug tasks running on networked
14009 VxWorks targets from a Unix host. Already-running tasks spawned from
14010 the VxWorks shell can also be debugged. @value{GDBN} uses code that runs on
14011 both the Unix host and on the VxWorks target. The program
14012 @code{@value{GDBP}} is installed and executed on the Unix host. (It may be
14013 installed with the name @code{vxgdb}, to distinguish it from a
14014 @value{GDBN} for debugging programs on the host itself.)
14015
14016 @table @code
14017 @item VxWorks-timeout @var{args}
14018 @kindex vxworks-timeout
14019 All VxWorks-based targets now support the option @code{vxworks-timeout}.
14020 This option is set by the user, and @var{args} represents the number of
14021 seconds @value{GDBN} waits for responses to rpc's. You might use this if
14022 your VxWorks target is a slow software simulator or is on the far side
14023 of a thin network line.
14024 @end table
14025
14026 The following information on connecting to VxWorks was current when
14027 this manual was produced; newer releases of VxWorks may use revised
14028 procedures.
14029
14030 @findex INCLUDE_RDB
14031 To use @value{GDBN} with VxWorks, you must rebuild your VxWorks kernel
14032 to include the remote debugging interface routines in the VxWorks
14033 library @file{rdb.a}. To do this, define @code{INCLUDE_RDB} in the
14034 VxWorks configuration file @file{configAll.h} and rebuild your VxWorks
14035 kernel. The resulting kernel contains @file{rdb.a}, and spawns the
14036 source debugging task @code{tRdbTask} when VxWorks is booted. For more
14037 information on configuring and remaking VxWorks, see the manufacturer's
14038 manual.
14039 @c VxWorks, see the @cite{VxWorks Programmer's Guide}.
14040
14041 Once you have included @file{rdb.a} in your VxWorks system image and set
14042 your Unix execution search path to find @value{GDBN}, you are ready to
14043 run @value{GDBN}. From your Unix host, run @code{@value{GDBP}} (or
14044 @code{vxgdb}, depending on your installation).
14045
14046 @value{GDBN} comes up showing the prompt:
14047
14048 @smallexample
14049 (vxgdb)
14050 @end smallexample
14051
14052 @menu
14053 * VxWorks Connection:: Connecting to VxWorks
14054 * VxWorks Download:: VxWorks download
14055 * VxWorks Attach:: Running tasks
14056 @end menu
14057
14058 @node VxWorks Connection
14059 @subsubsection Connecting to VxWorks
14060
14061 The @value{GDBN} command @code{target} lets you connect to a VxWorks target on the
14062 network. To connect to a target whose host name is ``@code{tt}'', type:
14063
14064 @smallexample
14065 (vxgdb) target vxworks tt
14066 @end smallexample
14067
14068 @need 750
14069 @value{GDBN} displays messages like these:
14070
14071 @smallexample
14072 Attaching remote machine across net...
14073 Connected to tt.
14074 @end smallexample
14075
14076 @need 1000
14077 @value{GDBN} then attempts to read the symbol tables of any object modules
14078 loaded into the VxWorks target since it was last booted. @value{GDBN} locates
14079 these files by searching the directories listed in the command search
14080 path (@pxref{Environment, ,Your program's environment}); if it fails
14081 to find an object file, it displays a message such as:
14082
14083 @smallexample
14084 prog.o: No such file or directory.
14085 @end smallexample
14086
14087 When this happens, add the appropriate directory to the search path with
14088 the @value{GDBN} command @code{path}, and execute the @code{target}
14089 command again.
14090
14091 @node VxWorks Download
14092 @subsubsection VxWorks download
14093
14094 @cindex download to VxWorks
14095 If you have connected to the VxWorks target and you want to debug an
14096 object that has not yet been loaded, you can use the @value{GDBN}
14097 @code{load} command to download a file from Unix to VxWorks
14098 incrementally. The object file given as an argument to the @code{load}
14099 command is actually opened twice: first by the VxWorks target in order
14100 to download the code, then by @value{GDBN} in order to read the symbol
14101 table. This can lead to problems if the current working directories on
14102 the two systems differ. If both systems have NFS mounted the same
14103 filesystems, you can avoid these problems by using absolute paths.
14104 Otherwise, it is simplest to set the working directory on both systems
14105 to the directory in which the object file resides, and then to reference
14106 the file by its name, without any path. For instance, a program
14107 @file{prog.o} may reside in @file{@var{vxpath}/vw/demo/rdb} in VxWorks
14108 and in @file{@var{hostpath}/vw/demo/rdb} on the host. To load this
14109 program, type this on VxWorks:
14110
14111 @smallexample
14112 -> cd "@var{vxpath}/vw/demo/rdb"
14113 @end smallexample
14114
14115 @noindent
14116 Then, in @value{GDBN}, type:
14117
14118 @smallexample
14119 (vxgdb) cd @var{hostpath}/vw/demo/rdb
14120 (vxgdb) load prog.o
14121 @end smallexample
14122
14123 @value{GDBN} displays a response similar to this:
14124
14125 @smallexample
14126 Reading symbol data from wherever/vw/demo/rdb/prog.o... done.
14127 @end smallexample
14128
14129 You can also use the @code{load} command to reload an object module
14130 after editing and recompiling the corresponding source file. Note that
14131 this makes @value{GDBN} delete all currently-defined breakpoints,
14132 auto-displays, and convenience variables, and to clear the value
14133 history. (This is necessary in order to preserve the integrity of
14134 debugger's data structures that reference the target system's symbol
14135 table.)
14136
14137 @node VxWorks Attach
14138 @subsubsection Running tasks
14139
14140 @cindex running VxWorks tasks
14141 You can also attach to an existing task using the @code{attach} command as
14142 follows:
14143
14144 @smallexample
14145 (vxgdb) attach @var{task}
14146 @end smallexample
14147
14148 @noindent
14149 where @var{task} is the VxWorks hexadecimal task ID. The task can be running
14150 or suspended when you attach to it. Running tasks are suspended at
14151 the time of attachment.
14152
14153 @node Embedded Processors
14154 @section Embedded Processors
14155
14156 This section goes into details specific to particular embedded
14157 configurations.
14158
14159 @cindex send command to simulator
14160 Whenever a specific embedded processor has a simulator, @value{GDBN}
14161 allows to send an arbitrary command to the simulator.
14162
14163 @table @code
14164 @item sim @var{command}
14165 @kindex sim@r{, a command}
14166 Send an arbitrary @var{command} string to the simulator. Consult the
14167 documentation for the specific simulator in use for information about
14168 acceptable commands.
14169 @end table
14170
14171
14172 @menu
14173 * ARM:: ARM RDI
14174 * H8/300:: Renesas H8/300
14175 * H8/500:: Renesas H8/500
14176 * M32R/D:: Renesas M32R/D
14177 * M68K:: Motorola M68K
14178 * MIPS Embedded:: MIPS Embedded
14179 * OpenRISC 1000:: OpenRisc 1000
14180 * PA:: HP PA Embedded
14181 * PowerPC: PowerPC
14182 * SH:: Renesas SH
14183 * Sparclet:: Tsqware Sparclet
14184 * Sparclite:: Fujitsu Sparclite
14185 * ST2000:: Tandem ST2000
14186 * Z8000:: Zilog Z8000
14187 * AVR:: Atmel AVR
14188 * CRIS:: CRIS
14189 * Super-H:: Renesas Super-H
14190 * WinCE:: Windows CE child processes
14191 @end menu
14192
14193 @node ARM
14194 @subsection ARM
14195 @cindex ARM RDI
14196
14197 @table @code
14198 @kindex target rdi
14199 @item target rdi @var{dev}
14200 ARM Angel monitor, via RDI library interface to ADP protocol. You may
14201 use this target to communicate with both boards running the Angel
14202 monitor, or with the EmbeddedICE JTAG debug device.
14203
14204 @kindex target rdp
14205 @item target rdp @var{dev}
14206 ARM Demon monitor.
14207
14208 @end table
14209
14210 @value{GDBN} provides the following ARM-specific commands:
14211
14212 @table @code
14213 @item set arm disassembler
14214 @kindex set arm
14215 This commands selects from a list of disassembly styles. The
14216 @code{"std"} style is the standard style.
14217
14218 @item show arm disassembler
14219 @kindex show arm
14220 Show the current disassembly style.
14221
14222 @item set arm apcs32
14223 @cindex ARM 32-bit mode
14224 This command toggles ARM operation mode between 32-bit and 26-bit.
14225
14226 @item show arm apcs32
14227 Display the current usage of the ARM 32-bit mode.
14228
14229 @item set arm fpu @var{fputype}
14230 This command sets the ARM floating-point unit (FPU) type. The
14231 argument @var{fputype} can be one of these:
14232
14233 @table @code
14234 @item auto
14235 Determine the FPU type by querying the OS ABI.
14236 @item softfpa
14237 Software FPU, with mixed-endian doubles on little-endian ARM
14238 processors.
14239 @item fpa
14240 GCC-compiled FPA co-processor.
14241 @item softvfp
14242 Software FPU with pure-endian doubles.
14243 @item vfp
14244 VFP co-processor.
14245 @end table
14246
14247 @item show arm fpu
14248 Show the current type of the FPU.
14249
14250 @item set arm abi
14251 This command forces @value{GDBN} to use the specified ABI.
14252
14253 @item show arm abi
14254 Show the currently used ABI.
14255
14256 @item set debug arm
14257 Toggle whether to display ARM-specific debugging messages from the ARM
14258 target support subsystem.
14259
14260 @item show debug arm
14261 Show whether ARM-specific debugging messages are enabled.
14262 @end table
14263
14264 The following commands are available when an ARM target is debugged
14265 using the RDI interface:
14266
14267 @table @code
14268 @item rdilogfile @r{[}@var{file}@r{]}
14269 @kindex rdilogfile
14270 @cindex ADP (Angel Debugger Protocol) logging
14271 Set the filename for the ADP (Angel Debugger Protocol) packet log.
14272 With an argument, sets the log file to the specified @var{file}. With
14273 no argument, show the current log file name. The default log file is
14274 @file{rdi.log}.
14275
14276 @item rdilogenable @r{[}@var{arg}@r{]}
14277 @kindex rdilogenable
14278 Control logging of ADP packets. With an argument of 1 or @code{"yes"}
14279 enables logging, with an argument 0 or @code{"no"} disables it. With
14280 no arguments displays the current setting. When logging is enabled,
14281 ADP packets exchanged between @value{GDBN} and the RDI target device
14282 are logged to a file.
14283
14284 @item set rdiromatzero
14285 @kindex set rdiromatzero
14286 @cindex ROM at zero address, RDI
14287 Tell @value{GDBN} whether the target has ROM at address 0. If on,
14288 vector catching is disabled, so that zero address can be used. If off
14289 (the default), vector catching is enabled. For this command to take
14290 effect, it needs to be invoked prior to the @code{target rdi} command.
14291
14292 @item show rdiromatzero
14293 @kindex show rdiromatzero
14294 Show the current setting of ROM at zero address.
14295
14296 @item set rdiheartbeat
14297 @kindex set rdiheartbeat
14298 @cindex RDI heartbeat
14299 Enable or disable RDI heartbeat packets. It is not recommended to
14300 turn on this option, since it confuses ARM and EPI JTAG interface, as
14301 well as the Angel monitor.
14302
14303 @item show rdiheartbeat
14304 @kindex show rdiheartbeat
14305 Show the setting of RDI heartbeat packets.
14306 @end table
14307
14308
14309 @node H8/300
14310 @subsection Renesas H8/300
14311
14312 @table @code
14313
14314 @kindex target hms@r{, with H8/300}
14315 @item target hms @var{dev}
14316 A Renesas SH, H8/300, or H8/500 board, attached via serial line to your host.
14317 Use special commands @code{device} and @code{speed} to control the serial
14318 line and the communications speed used.
14319
14320 @kindex target e7000@r{, with H8/300}
14321 @item target e7000 @var{dev}
14322 E7000 emulator for Renesas H8 and SH.
14323
14324 @kindex target sh3@r{, with H8/300}
14325 @kindex target sh3e@r{, with H8/300}
14326 @item target sh3 @var{dev}
14327 @itemx target sh3e @var{dev}
14328 Renesas SH-3 and SH-3E target systems.
14329
14330 @end table
14331
14332 @cindex download to H8/300 or H8/500
14333 @cindex H8/300 or H8/500 download
14334 @cindex download to Renesas SH
14335 @cindex Renesas SH download
14336 When you select remote debugging to a Renesas SH, H8/300, or H8/500
14337 board, the @code{load} command downloads your program to the Renesas
14338 board and also opens it as the current executable target for
14339 @value{GDBN} on your host (like the @code{file} command).
14340
14341 @value{GDBN} needs to know these things to talk to your
14342 Renesas SH, H8/300, or H8/500:
14343
14344 @enumerate
14345 @item
14346 that you want to use @samp{target hms}, the remote debugging interface
14347 for Renesas microprocessors, or @samp{target e7000}, the in-circuit
14348 emulator for the Renesas SH and the Renesas 300H. (@samp{target hms} is
14349 the default when @value{GDBN} is configured specifically for the Renesas SH,
14350 H8/300, or H8/500.)
14351
14352 @item
14353 what serial device connects your host to your Renesas board (the first
14354 serial device available on your host is the default).
14355
14356 @item
14357 what speed to use over the serial device.
14358 @end enumerate
14359
14360 @menu
14361 * Renesas Boards:: Connecting to Renesas boards.
14362 * Renesas ICE:: Using the E7000 In-Circuit Emulator.
14363 * Renesas Special:: Special @value{GDBN} commands for Renesas micros.
14364 @end menu
14365
14366 @node Renesas Boards
14367 @subsubsection Connecting to Renesas boards
14368
14369 @c only for Unix hosts
14370 @kindex device
14371 @cindex serial device, Renesas micros
14372 Use the special @code{@value{GDBN}} command @samp{device @var{port}} if you
14373 need to explicitly set the serial device. The default @var{port} is the
14374 first available port on your host. This is only necessary on Unix
14375 hosts, where it is typically something like @file{/dev/ttya}.
14376
14377 @kindex speed
14378 @cindex serial line speed, Renesas micros
14379 @code{@value{GDBN}} has another special command to set the communications
14380 speed: @samp{speed @var{bps}}. This command also is only used from Unix
14381 hosts; on DOS hosts, set the line speed as usual from outside @value{GDBN} with
14382 the DOS @code{mode} command (for instance,
14383 @w{@kbd{mode com2:9600,n,8,1,p}} for a 9600@dmn{bps} connection).
14384
14385 The @samp{device} and @samp{speed} commands are available only when you
14386 use a Unix host to debug your Renesas microprocessor programs. If you
14387 use a DOS host,
14388 @value{GDBN} depends on an auxiliary terminate-and-stay-resident program
14389 called @code{asynctsr} to communicate with the development board
14390 through a PC serial port. You must also use the DOS @code{mode} command
14391 to set up the serial port on the DOS side.
14392
14393 The following sample session illustrates the steps needed to start a
14394 program under @value{GDBN} control on an H8/300. The example uses a
14395 sample H8/300 program called @file{t.x}. The procedure is the same for
14396 the Renesas SH and the H8/500.
14397
14398 First hook up your development board. In this example, we use a
14399 board attached to serial port @code{COM2}; if you use a different serial
14400 port, substitute its name in the argument of the @code{mode} command.
14401 When you call @code{asynctsr}, the auxiliary comms program used by the
14402 debugger, you give it just the numeric part of the serial port's name;
14403 for example, @samp{asyncstr 2} below runs @code{asyncstr} on
14404 @code{COM2}.
14405
14406 @smallexample
14407 C:\H8300\TEST> asynctsr 2
14408 C:\H8300\TEST> mode com2:9600,n,8,1,p
14409
14410 Resident portion of MODE loaded
14411
14412 COM2: 9600, n, 8, 1, p
14413
14414 @end smallexample
14415
14416 @quotation
14417 @emph{Warning:} We have noticed a bug in PC-NFS that conflicts with
14418 @code{asynctsr}. If you also run PC-NFS on your DOS host, you may need to
14419 disable it, or even boot without it, to use @code{asynctsr} to control
14420 your development board.
14421 @end quotation
14422
14423 @kindex target hms@r{, and serial protocol}
14424 Now that serial communications are set up, and the development board is
14425 connected, you can start up @value{GDBN}. Call @code{@value{GDBN}} with
14426 the name of your program as the argument. @code{@value{GDBN}} prompts
14427 you, as usual, with the prompt @samp{(@value{GDBP})}. Use two special
14428 commands to begin your debugging session: @samp{target hms} to specify
14429 cross-debugging to the Renesas board, and the @code{load} command to
14430 download your program to the board. @code{load} displays the names of
14431 the program's sections, and a @samp{*} for each 2K of data downloaded.
14432 (If you want to refresh @value{GDBN} data on symbols or on the
14433 executable file without downloading, use the @value{GDBN} commands
14434 @code{file} or @code{symbol-file}. These commands, and @code{load}
14435 itself, are described in @ref{Files,,Commands to specify files}.)
14436
14437 @smallexample
14438 (eg-C:\H8300\TEST) @value{GDBP} t.x
14439 @value{GDBN} is free software and you are welcome to distribute copies
14440 of it under certain conditions; type "show copying" to see
14441 the conditions.
14442 There is absolutely no warranty for @value{GDBN}; type "show warranty"
14443 for details.
14444 @value{GDBN} @value{GDBVN}, Copyright 1992 Free Software Foundation, Inc...
14445 (@value{GDBP}) target hms
14446 Connected to remote H8/300 HMS system.
14447 (@value{GDBP}) load t.x
14448 .text : 0x8000 .. 0xabde ***********
14449 .data : 0xabde .. 0xad30 *
14450 .stack : 0xf000 .. 0xf014 *
14451 @end smallexample
14452
14453 At this point, you're ready to run or debug your program. From here on,
14454 you can use all the usual @value{GDBN} commands. The @code{break} command
14455 sets breakpoints; the @code{run} command starts your program;
14456 @code{print} or @code{x} display data; the @code{continue} command
14457 resumes execution after stopping at a breakpoint. You can use the
14458 @code{help} command at any time to find out more about @value{GDBN} commands.
14459
14460 Remember, however, that @emph{operating system} facilities aren't
14461 available on your development board; for example, if your program hangs,
14462 you can't send an interrupt---but you can press the @sc{reset} switch!
14463
14464 Use the @sc{reset} button on the development board
14465 @itemize @bullet
14466 @item
14467 to interrupt your program (don't use @kbd{Ctrl-c} on the DOS host---it has
14468 no way to pass an interrupt signal to the development board); and
14469
14470 @item
14471 to return to the @value{GDBN} command prompt after your program finishes
14472 normally. The communications protocol provides no other way for @value{GDBN}
14473 to detect program completion.
14474 @end itemize
14475
14476 In either case, @value{GDBN} sees the effect of a @sc{reset} on the
14477 development board as a ``normal exit'' of your program.
14478
14479 @node Renesas ICE
14480 @subsubsection Using the E7000 in-circuit emulator
14481
14482 @kindex target e7000@r{, with Renesas ICE}
14483 You can use the E7000 in-circuit emulator to develop code for either the
14484 Renesas SH or the H8/300H. Use one of these forms of the @samp{target
14485 e7000} command to connect @value{GDBN} to your E7000:
14486
14487 @table @code
14488 @item target e7000 @var{port} @var{speed}
14489 Use this form if your E7000 is connected to a serial port. The
14490 @var{port} argument identifies what serial port to use (for example,
14491 @samp{com2}). The third argument is the line speed in bits per second
14492 (for example, @samp{9600}).
14493
14494 @item target e7000 @var{hostname}
14495 If your E7000 is installed as a host on a TCP/IP network, you can just
14496 specify its hostname; @value{GDBN} uses @code{telnet} to connect.
14497 @end table
14498
14499 The following special commands are available when debugging with the
14500 Renesas E7000 ICE:
14501
14502 @table @code
14503 @item e7000 @var{command}
14504 @kindex e7000
14505 @cindex send command to E7000 monitor
14506 This sends the specified @var{command} to the E7000 monitor.
14507
14508 @item ftplogin @var{machine} @var{username} @var{password} @var{dir}
14509 @kindex ftplogin@r{, E7000}
14510 This command records information for subsequent interface with the
14511 E7000 monitor via the FTP protocol: @value{GDBN} will log into the
14512 named @var{machine} using specified @var{username} and @var{password},
14513 and then chdir to the named directory @var{dir}.
14514
14515 @item ftpload @var{file}
14516 @kindex ftpload@r{, E7000}
14517 This command uses credentials recorded by @code{ftplogin} to fetch and
14518 load the named @var{file} from the E7000 monitor.
14519
14520 @item drain
14521 @kindex drain@r{, E7000}
14522 This command drains any pending text buffers stored on the E7000.
14523
14524 @item set usehardbreakpoints
14525 @itemx show usehardbreakpoints
14526 @kindex set usehardbreakpoints@r{, E7000}
14527 @kindex show usehardbreakpoints@r{, E7000}
14528 @cindex hardware breakpoints, and E7000
14529 These commands set and show the use of hardware breakpoints for all
14530 breakpoints. @xref{Set Breaks, hardware-assisted breakpoint}, for
14531 more information about using hardware breakpoints selectively.
14532 @end table
14533
14534 @node Renesas Special
14535 @subsubsection Special @value{GDBN} commands for Renesas micros
14536
14537 Some @value{GDBN} commands are available only for the H8/300:
14538
14539 @table @code
14540
14541 @kindex set machine
14542 @kindex show machine
14543 @item set machine h8300
14544 @itemx set machine h8300h
14545 Condition @value{GDBN} for one of the two variants of the H8/300
14546 architecture with @samp{set machine}. You can use @samp{show machine}
14547 to check which variant is currently in effect.
14548
14549 @end table
14550
14551 @node H8/500
14552 @subsection H8/500
14553
14554 @table @code
14555
14556 @kindex set memory @var{mod}
14557 @cindex memory models, H8/500
14558 @item set memory @var{mod}
14559 @itemx show memory
14560 Specify which H8/500 memory model (@var{mod}) you are using with
14561 @samp{set memory}; check which memory model is in effect with @samp{show
14562 memory}. The accepted values for @var{mod} are @code{small},
14563 @code{big}, @code{medium}, and @code{compact}.
14564
14565 @end table
14566
14567 @node M32R/D
14568 @subsection Renesas M32R/D and M32R/SDI
14569
14570 @table @code
14571 @kindex target m32r
14572 @item target m32r @var{dev}
14573 Renesas M32R/D ROM monitor.
14574
14575 @kindex target m32rsdi
14576 @item target m32rsdi @var{dev}
14577 Renesas M32R SDI server, connected via parallel port to the board.
14578 @end table
14579
14580 The following @value{GDBN} commands are specific to the M32R monitor:
14581
14582 @table @code
14583 @item set download-path @var{path}
14584 @kindex set download-path
14585 @cindex find downloadable @sc{srec} files (M32R)
14586 Set the default path for finding donwloadable @sc{srec} files.
14587
14588 @item show download-path
14589 @kindex show download-path
14590 Show the default path for downloadable @sc{srec} files.
14591
14592 @item set board-address @var{addr}
14593 @kindex set board-address
14594 @cindex M32-EVA target board address
14595 Set the IP address for the M32R-EVA target board.
14596
14597 @item show board-address
14598 @kindex show board-address
14599 Show the current IP address of the target board.
14600
14601 @item set server-address @var{addr}
14602 @kindex set server-address
14603 @cindex download server address (M32R)
14604 Set the IP address for the download server, which is the @value{GDBN}'s
14605 host machine.
14606
14607 @item show server-address
14608 @kindex show server-address
14609 Display the IP address of the download server.
14610
14611 @item upload @r{[}@var{file}@r{]}
14612 @kindex upload@r{, M32R}
14613 Upload the specified @sc{srec} @var{file} via the monitor's Ethernet
14614 upload capability. If no @var{file} argument is given, the current
14615 executable file is uploaded.
14616
14617 @item tload @r{[}@var{file}@r{]}
14618 @kindex tload@r{, M32R}
14619 Test the @code{upload} command.
14620 @end table
14621
14622 The following commands are available for M32R/SDI:
14623
14624 @table @code
14625 @item sdireset
14626 @kindex sdireset
14627 @cindex reset SDI connection, M32R
14628 This command resets the SDI connection.
14629
14630 @item sdistatus
14631 @kindex sdistatus
14632 This command shows the SDI connection status.
14633
14634 @item debug_chaos
14635 @kindex debug_chaos
14636 @cindex M32R/Chaos debugging
14637 Instructs the remote that M32R/Chaos debugging is to be used.
14638
14639 @item use_debug_dma
14640 @kindex use_debug_dma
14641 Instructs the remote to use the DEBUG_DMA method of accessing memory.
14642
14643 @item use_mon_code
14644 @kindex use_mon_code
14645 Instructs the remote to use the MON_CODE method of accessing memory.
14646
14647 @item use_ib_break
14648 @kindex use_ib_break
14649 Instructs the remote to set breakpoints by IB break.
14650
14651 @item use_dbt_break
14652 @kindex use_dbt_break
14653 Instructs the remote to set breakpoints by DBT.
14654 @end table
14655
14656 @node M68K
14657 @subsection M68k
14658
14659 The Motorola m68k configuration includes ColdFire support, and
14660 target command for the following ROM monitors.
14661
14662 @table @code
14663
14664 @kindex target abug
14665 @item target abug @var{dev}
14666 ABug ROM monitor for M68K.
14667
14668 @kindex target cpu32bug
14669 @item target cpu32bug @var{dev}
14670 CPU32BUG monitor, running on a CPU32 (M68K) board.
14671
14672 @kindex target dbug
14673 @item target dbug @var{dev}
14674 dBUG ROM monitor for Motorola ColdFire.
14675
14676 @kindex target est
14677 @item target est @var{dev}
14678 EST-300 ICE monitor, running on a CPU32 (M68K) board.
14679
14680 @kindex target rom68k
14681 @item target rom68k @var{dev}
14682 ROM 68K monitor, running on an M68K IDP board.
14683
14684 @end table
14685
14686 @table @code
14687
14688 @kindex target rombug
14689 @item target rombug @var{dev}
14690 ROMBUG ROM monitor for OS/9000.
14691
14692 @end table
14693
14694 @node MIPS Embedded
14695 @subsection MIPS Embedded
14696
14697 @cindex MIPS boards
14698 @value{GDBN} can use the MIPS remote debugging protocol to talk to a
14699 MIPS board attached to a serial line. This is available when
14700 you configure @value{GDBN} with @samp{--target=mips-idt-ecoff}.
14701
14702 @need 1000
14703 Use these @value{GDBN} commands to specify the connection to your target board:
14704
14705 @table @code
14706 @item target mips @var{port}
14707 @kindex target mips @var{port}
14708 To run a program on the board, start up @code{@value{GDBP}} with the
14709 name of your program as the argument. To connect to the board, use the
14710 command @samp{target mips @var{port}}, where @var{port} is the name of
14711 the serial port connected to the board. If the program has not already
14712 been downloaded to the board, you may use the @code{load} command to
14713 download it. You can then use all the usual @value{GDBN} commands.
14714
14715 For example, this sequence connects to the target board through a serial
14716 port, and loads and runs a program called @var{prog} through the
14717 debugger:
14718
14719 @smallexample
14720 host$ @value{GDBP} @var{prog}
14721 @value{GDBN} is free software and @dots{}
14722 (@value{GDBP}) target mips /dev/ttyb
14723 (@value{GDBP}) load @var{prog}
14724 (@value{GDBP}) run
14725 @end smallexample
14726
14727 @item target mips @var{hostname}:@var{portnumber}
14728 On some @value{GDBN} host configurations, you can specify a TCP
14729 connection (for instance, to a serial line managed by a terminal
14730 concentrator) instead of a serial port, using the syntax
14731 @samp{@var{hostname}:@var{portnumber}}.
14732
14733 @item target pmon @var{port}
14734 @kindex target pmon @var{port}
14735 PMON ROM monitor.
14736
14737 @item target ddb @var{port}
14738 @kindex target ddb @var{port}
14739 NEC's DDB variant of PMON for Vr4300.
14740
14741 @item target lsi @var{port}
14742 @kindex target lsi @var{port}
14743 LSI variant of PMON.
14744
14745 @kindex target r3900
14746 @item target r3900 @var{dev}
14747 Densan DVE-R3900 ROM monitor for Toshiba R3900 Mips.
14748
14749 @kindex target array
14750 @item target array @var{dev}
14751 Array Tech LSI33K RAID controller board.
14752
14753 @end table
14754
14755
14756 @noindent
14757 @value{GDBN} also supports these special commands for MIPS targets:
14758
14759 @table @code
14760 @item set mipsfpu double
14761 @itemx set mipsfpu single
14762 @itemx set mipsfpu none
14763 @itemx set mipsfpu auto
14764 @itemx show mipsfpu
14765 @kindex set mipsfpu
14766 @kindex show mipsfpu
14767 @cindex MIPS remote floating point
14768 @cindex floating point, MIPS remote
14769 If your target board does not support the MIPS floating point
14770 coprocessor, you should use the command @samp{set mipsfpu none} (if you
14771 need this, you may wish to put the command in your @value{GDBN} init
14772 file). This tells @value{GDBN} how to find the return value of
14773 functions which return floating point values. It also allows
14774 @value{GDBN} to avoid saving the floating point registers when calling
14775 functions on the board. If you are using a floating point coprocessor
14776 with only single precision floating point support, as on the @sc{r4650}
14777 processor, use the command @samp{set mipsfpu single}. The default
14778 double precision floating point coprocessor may be selected using
14779 @samp{set mipsfpu double}.
14780
14781 In previous versions the only choices were double precision or no
14782 floating point, so @samp{set mipsfpu on} will select double precision
14783 and @samp{set mipsfpu off} will select no floating point.
14784
14785 As usual, you can inquire about the @code{mipsfpu} variable with
14786 @samp{show mipsfpu}.
14787
14788 @item set timeout @var{seconds}
14789 @itemx set retransmit-timeout @var{seconds}
14790 @itemx show timeout
14791 @itemx show retransmit-timeout
14792 @cindex @code{timeout}, MIPS protocol
14793 @cindex @code{retransmit-timeout}, MIPS protocol
14794 @kindex set timeout
14795 @kindex show timeout
14796 @kindex set retransmit-timeout
14797 @kindex show retransmit-timeout
14798 You can control the timeout used while waiting for a packet, in the MIPS
14799 remote protocol, with the @code{set timeout @var{seconds}} command. The
14800 default is 5 seconds. Similarly, you can control the timeout used while
14801 waiting for an acknowledgement of a packet with the @code{set
14802 retransmit-timeout @var{seconds}} command. The default is 3 seconds.
14803 You can inspect both values with @code{show timeout} and @code{show
14804 retransmit-timeout}. (These commands are @emph{only} available when
14805 @value{GDBN} is configured for @samp{--target=mips-idt-ecoff}.)
14806
14807 The timeout set by @code{set timeout} does not apply when @value{GDBN}
14808 is waiting for your program to stop. In that case, @value{GDBN} waits
14809 forever because it has no way of knowing how long the program is going
14810 to run before stopping.
14811
14812 @item set syn-garbage-limit @var{num}
14813 @kindex set syn-garbage-limit@r{, MIPS remote}
14814 @cindex synchronize with remote MIPS target
14815 Limit the maximum number of characters @value{GDBN} should ignore when
14816 it tries to synchronize with the remote target. The default is 10
14817 characters. Setting the limit to -1 means there's no limit.
14818
14819 @item show syn-garbage-limit
14820 @kindex show syn-garbage-limit@r{, MIPS remote}
14821 Show the current limit on the number of characters to ignore when
14822 trying to synchronize with the remote system.
14823
14824 @item set monitor-prompt @var{prompt}
14825 @kindex set monitor-prompt@r{, MIPS remote}
14826 @cindex remote monitor prompt
14827 Tell @value{GDBN} to expect the specified @var{prompt} string from the
14828 remote monitor. The default depends on the target:
14829 @table @asis
14830 @item pmon target
14831 @samp{PMON}
14832 @item ddb target
14833 @samp{NEC010}
14834 @item lsi target
14835 @samp{PMON>}
14836 @end table
14837
14838 @item show monitor-prompt
14839 @kindex show monitor-prompt@r{, MIPS remote}
14840 Show the current strings @value{GDBN} expects as the prompt from the
14841 remote monitor.
14842
14843 @item set monitor-warnings
14844 @kindex set monitor-warnings@r{, MIPS remote}
14845 Enable or disable monitor warnings about hardware breakpoints. This
14846 has effect only for the @code{lsi} target. When on, @value{GDBN} will
14847 display warning messages whose codes are returned by the @code{lsi}
14848 PMON monitor for breakpoint commands.
14849
14850 @item show monitor-warnings
14851 @kindex show monitor-warnings@r{, MIPS remote}
14852 Show the current setting of printing monitor warnings.
14853
14854 @item pmon @var{command}
14855 @kindex pmon@r{, MIPS remote}
14856 @cindex send PMON command
14857 This command allows sending an arbitrary @var{command} string to the
14858 monitor. The monitor must be in debug mode for this to work.
14859 @end table
14860
14861 @node OpenRISC 1000
14862 @subsection OpenRISC 1000
14863 @cindex OpenRISC 1000
14864
14865 @cindex or1k boards
14866 See OR1k Architecture document (@uref{www.opencores.org}) for more information
14867 about platform and commands.
14868
14869 @table @code
14870
14871 @kindex target jtag
14872 @item target jtag jtag://@var{host}:@var{port}
14873
14874 Connects to remote JTAG server.
14875 JTAG remote server can be either an or1ksim or JTAG server,
14876 connected via parallel port to the board.
14877
14878 Example: @code{target jtag jtag://localhost:9999}
14879
14880 @kindex or1ksim
14881 @item or1ksim @var{command}
14882 If connected to @code{or1ksim} OpenRISC 1000 Architectural
14883 Simulator, proprietary commands can be executed.
14884
14885 @kindex info or1k spr
14886 @item info or1k spr
14887 Displays spr groups.
14888
14889 @item info or1k spr @var{group}
14890 @itemx info or1k spr @var{groupno}
14891 Displays register names in selected group.
14892
14893 @item info or1k spr @var{group} @var{register}
14894 @itemx info or1k spr @var{register}
14895 @itemx info or1k spr @var{groupno} @var{registerno}
14896 @itemx info or1k spr @var{registerno}
14897 Shows information about specified spr register.
14898
14899 @kindex spr
14900 @item spr @var{group} @var{register} @var{value}
14901 @itemx spr @var{register @var{value}}
14902 @itemx spr @var{groupno} @var{registerno @var{value}}
14903 @itemx spr @var{registerno @var{value}}
14904 Writes @var{value} to specified spr register.
14905 @end table
14906
14907 Some implementations of OpenRISC 1000 Architecture also have hardware trace.
14908 It is very similar to @value{GDBN} trace, except it does not interfere with normal
14909 program execution and is thus much faster. Hardware breakpoints/watchpoint
14910 triggers can be set using:
14911 @table @code
14912 @item $LEA/$LDATA
14913 Load effective address/data
14914 @item $SEA/$SDATA
14915 Store effective address/data
14916 @item $AEA/$ADATA
14917 Access effective address ($SEA or $LEA) or data ($SDATA/$LDATA)
14918 @item $FETCH
14919 Fetch data
14920 @end table
14921
14922 When triggered, it can capture low level data, like: @code{PC}, @code{LSEA},
14923 @code{LDATA}, @code{SDATA}, @code{READSPR}, @code{WRITESPR}, @code{INSTR}.
14924
14925 @code{htrace} commands:
14926 @cindex OpenRISC 1000 htrace
14927 @table @code
14928 @kindex hwatch
14929 @item hwatch @var{conditional}
14930 Set hardware watchpoint on combination of Load/Store Effecive Address(es)
14931 or Data. For example:
14932
14933 @code{hwatch ($LEA == my_var) && ($LDATA < 50) || ($SEA == my_var) && ($SDATA >= 50)}
14934
14935 @code{hwatch ($LEA == my_var) && ($LDATA < 50) || ($SEA == my_var) && ($SDATA >= 50)}
14936
14937 @kindex htrace
14938 @item htrace info
14939 Display information about current HW trace configuration.
14940
14941 @item htrace trigger @var{conditional}
14942 Set starting criteria for HW trace.
14943
14944 @item htrace qualifier @var{conditional}
14945 Set acquisition qualifier for HW trace.
14946
14947 @item htrace stop @var{conditional}
14948 Set HW trace stopping criteria.
14949
14950 @item htrace record [@var{data}]*
14951 Selects the data to be recorded, when qualifier is met and HW trace was
14952 triggered.
14953
14954 @item htrace enable
14955 @itemx htrace disable
14956 Enables/disables the HW trace.
14957
14958 @item htrace rewind [@var{filename}]
14959 Clears currently recorded trace data.
14960
14961 If filename is specified, new trace file is made and any newly collected data
14962 will be written there.
14963
14964 @item htrace print [@var{start} [@var{len}]]
14965 Prints trace buffer, using current record configuration.
14966
14967 @item htrace mode continuous
14968 Set continuous trace mode.
14969
14970 @item htrace mode suspend
14971 Set suspend trace mode.
14972
14973 @end table
14974
14975 @node PowerPC
14976 @subsection PowerPC
14977
14978 @table @code
14979 @kindex target dink32
14980 @item target dink32 @var{dev}
14981 DINK32 ROM monitor.
14982
14983 @kindex target ppcbug
14984 @item target ppcbug @var{dev}
14985 @kindex target ppcbug1
14986 @item target ppcbug1 @var{dev}
14987 PPCBUG ROM monitor for PowerPC.
14988
14989 @kindex target sds
14990 @item target sds @var{dev}
14991 SDS monitor, running on a PowerPC board (such as Motorola's ADS).
14992 @end table
14993
14994 @cindex SDS protocol
14995 The following commands specifi to the SDS protocol are supported
14996 by@value{GDBN}:
14997
14998 @table @code
14999 @item set sdstimeout @var{nsec}
15000 @kindex set sdstimeout
15001 Set the timeout for SDS protocol reads to be @var{nsec} seconds. The
15002 default is 2 seconds.
15003
15004 @item show sdstimeout
15005 @kindex show sdstimeout
15006 Show the current value of the SDS timeout.
15007
15008 @item sds @var{command}
15009 @kindex sds@r{, a command}
15010 Send the specified @var{command} string to the SDS monitor.
15011 @end table
15012
15013
15014 @node PA
15015 @subsection HP PA Embedded
15016
15017 @table @code
15018
15019 @kindex target op50n
15020 @item target op50n @var{dev}
15021 OP50N monitor, running on an OKI HPPA board.
15022
15023 @kindex target w89k
15024 @item target w89k @var{dev}
15025 W89K monitor, running on a Winbond HPPA board.
15026
15027 @end table
15028
15029 @node SH
15030 @subsection Renesas SH
15031
15032 @table @code
15033
15034 @kindex target hms@r{, with Renesas SH}
15035 @item target hms @var{dev}
15036 A Renesas SH board attached via serial line to your host. Use special
15037 commands @code{device} and @code{speed} to control the serial line and
15038 the communications speed used.
15039
15040 @kindex target e7000@r{, with Renesas SH}
15041 @item target e7000 @var{dev}
15042 E7000 emulator for Renesas SH.
15043
15044 @kindex target sh3@r{, with SH}
15045 @kindex target sh3e@r{, with SH}
15046 @item target sh3 @var{dev}
15047 @item target sh3e @var{dev}
15048 Renesas SH-3 and SH-3E target systems.
15049
15050 @end table
15051
15052 @node Sparclet
15053 @subsection Tsqware Sparclet
15054
15055 @cindex Sparclet
15056
15057 @value{GDBN} enables developers to debug tasks running on
15058 Sparclet targets from a Unix host.
15059 @value{GDBN} uses code that runs on
15060 both the Unix host and on the Sparclet target. The program
15061 @code{@value{GDBP}} is installed and executed on the Unix host.
15062
15063 @table @code
15064 @item remotetimeout @var{args}
15065 @kindex remotetimeout
15066 @value{GDBN} supports the option @code{remotetimeout}.
15067 This option is set by the user, and @var{args} represents the number of
15068 seconds @value{GDBN} waits for responses.
15069 @end table
15070
15071 @cindex compiling, on Sparclet
15072 When compiling for debugging, include the options @samp{-g} to get debug
15073 information and @samp{-Ttext} to relocate the program to where you wish to
15074 load it on the target. You may also want to add the options @samp{-n} or
15075 @samp{-N} in order to reduce the size of the sections. Example:
15076
15077 @smallexample
15078 sparclet-aout-gcc prog.c -Ttext 0x12010000 -g -o prog -N
15079 @end smallexample
15080
15081 You can use @code{objdump} to verify that the addresses are what you intended:
15082
15083 @smallexample
15084 sparclet-aout-objdump --headers --syms prog
15085 @end smallexample
15086
15087 @cindex running, on Sparclet
15088 Once you have set
15089 your Unix execution search path to find @value{GDBN}, you are ready to
15090 run @value{GDBN}. From your Unix host, run @code{@value{GDBP}}
15091 (or @code{sparclet-aout-gdb}, depending on your installation).
15092
15093 @value{GDBN} comes up showing the prompt:
15094
15095 @smallexample
15096 (gdbslet)
15097 @end smallexample
15098
15099 @menu
15100 * Sparclet File:: Setting the file to debug
15101 * Sparclet Connection:: Connecting to Sparclet
15102 * Sparclet Download:: Sparclet download
15103 * Sparclet Execution:: Running and debugging
15104 @end menu
15105
15106 @node Sparclet File
15107 @subsubsection Setting file to debug
15108
15109 The @value{GDBN} command @code{file} lets you choose with program to debug.
15110
15111 @smallexample
15112 (gdbslet) file prog
15113 @end smallexample
15114
15115 @need 1000
15116 @value{GDBN} then attempts to read the symbol table of @file{prog}.
15117 @value{GDBN} locates
15118 the file by searching the directories listed in the command search
15119 path.
15120 If the file was compiled with debug information (option "-g"), source
15121 files will be searched as well.
15122 @value{GDBN} locates
15123 the source files by searching the directories listed in the directory search
15124 path (@pxref{Environment, ,Your program's environment}).
15125 If it fails
15126 to find a file, it displays a message such as:
15127
15128 @smallexample
15129 prog: No such file or directory.
15130 @end smallexample
15131
15132 When this happens, add the appropriate directories to the search paths with
15133 the @value{GDBN} commands @code{path} and @code{dir}, and execute the
15134 @code{target} command again.
15135
15136 @node Sparclet Connection
15137 @subsubsection Connecting to Sparclet
15138
15139 The @value{GDBN} command @code{target} lets you connect to a Sparclet target.
15140 To connect to a target on serial port ``@code{ttya}'', type:
15141
15142 @smallexample
15143 (gdbslet) target sparclet /dev/ttya
15144 Remote target sparclet connected to /dev/ttya
15145 main () at ../prog.c:3
15146 @end smallexample
15147
15148 @need 750
15149 @value{GDBN} displays messages like these:
15150
15151 @smallexample
15152 Connected to ttya.
15153 @end smallexample
15154
15155 @node Sparclet Download
15156 @subsubsection Sparclet download
15157
15158 @cindex download to Sparclet
15159 Once connected to the Sparclet target,
15160 you can use the @value{GDBN}
15161 @code{load} command to download the file from the host to the target.
15162 The file name and load offset should be given as arguments to the @code{load}
15163 command.
15164 Since the file format is aout, the program must be loaded to the starting
15165 address. You can use @code{objdump} to find out what this value is. The load
15166 offset is an offset which is added to the VMA (virtual memory address)
15167 of each of the file's sections.
15168 For instance, if the program
15169 @file{prog} was linked to text address 0x1201000, with data at 0x12010160
15170 and bss at 0x12010170, in @value{GDBN}, type:
15171
15172 @smallexample
15173 (gdbslet) load prog 0x12010000
15174 Loading section .text, size 0xdb0 vma 0x12010000
15175 @end smallexample
15176
15177 If the code is loaded at a different address then what the program was linked
15178 to, you may need to use the @code{section} and @code{add-symbol-file} commands
15179 to tell @value{GDBN} where to map the symbol table.
15180
15181 @node Sparclet Execution
15182 @subsubsection Running and debugging
15183
15184 @cindex running and debugging Sparclet programs
15185 You can now begin debugging the task using @value{GDBN}'s execution control
15186 commands, @code{b}, @code{step}, @code{run}, etc. See the @value{GDBN}
15187 manual for the list of commands.
15188
15189 @smallexample
15190 (gdbslet) b main
15191 Breakpoint 1 at 0x12010000: file prog.c, line 3.
15192 (gdbslet) run
15193 Starting program: prog
15194 Breakpoint 1, main (argc=1, argv=0xeffff21c) at prog.c:3
15195 3 char *symarg = 0;
15196 (gdbslet) step
15197 4 char *execarg = "hello!";
15198 (gdbslet)
15199 @end smallexample
15200
15201 @node Sparclite
15202 @subsection Fujitsu Sparclite
15203
15204 @table @code
15205
15206 @kindex target sparclite
15207 @item target sparclite @var{dev}
15208 Fujitsu sparclite boards, used only for the purpose of loading.
15209 You must use an additional command to debug the program.
15210 For example: target remote @var{dev} using @value{GDBN} standard
15211 remote protocol.
15212
15213 @end table
15214
15215 @node ST2000
15216 @subsection Tandem ST2000
15217
15218 @value{GDBN} may be used with a Tandem ST2000 phone switch, running Tandem's
15219 STDBUG protocol.
15220
15221 To connect your ST2000 to the host system, see the manufacturer's
15222 manual. Once the ST2000 is physically attached, you can run:
15223
15224 @smallexample
15225 target st2000 @var{dev} @var{speed}
15226 @end smallexample
15227
15228 @noindent
15229 to establish it as your debugging environment. @var{dev} is normally
15230 the name of a serial device, such as @file{/dev/ttya}, connected to the
15231 ST2000 via a serial line. You can instead specify @var{dev} as a TCP
15232 connection (for example, to a serial line attached via a terminal
15233 concentrator) using the syntax @code{@var{hostname}:@var{portnumber}}.
15234
15235 The @code{load} and @code{attach} commands are @emph{not} defined for
15236 this target; you must load your program into the ST2000 as you normally
15237 would for standalone operation. @value{GDBN} reads debugging information
15238 (such as symbols) from a separate, debugging version of the program
15239 available on your host computer.
15240 @c FIXME!! This is terribly vague; what little content is here is
15241 @c basically hearsay.
15242
15243 @cindex ST2000 auxiliary commands
15244 These auxiliary @value{GDBN} commands are available to help you with the ST2000
15245 environment:
15246
15247 @table @code
15248 @item st2000 @var{command}
15249 @kindex st2000 @var{cmd}
15250 @cindex STDBUG commands (ST2000)
15251 @cindex commands to STDBUG (ST2000)
15252 Send a @var{command} to the STDBUG monitor. See the manufacturer's
15253 manual for available commands.
15254
15255 @item connect
15256 @cindex connect (to STDBUG)
15257 Connect the controlling terminal to the STDBUG command monitor. When
15258 you are done interacting with STDBUG, typing either of two character
15259 sequences gets you back to the @value{GDBN} command prompt:
15260 @kbd{@key{RET} ~ .} (Return, followed by tilde and period) or
15261 @kbd{@key{RET} ~ C-d} (Return, followed by tilde and control-D).
15262 @end table
15263
15264 @node Z8000
15265 @subsection Zilog Z8000
15266
15267 @cindex Z8000
15268 @cindex simulator, Z8000
15269 @cindex Zilog Z8000 simulator
15270
15271 When configured for debugging Zilog Z8000 targets, @value{GDBN} includes
15272 a Z8000 simulator.
15273
15274 For the Z8000 family, @samp{target sim} simulates either the Z8002 (the
15275 unsegmented variant of the Z8000 architecture) or the Z8001 (the
15276 segmented variant). The simulator recognizes which architecture is
15277 appropriate by inspecting the object code.
15278
15279 @table @code
15280 @item target sim @var{args}
15281 @kindex sim
15282 @kindex target sim@r{, with Z8000}
15283 Debug programs on a simulated CPU. If the simulator supports setup
15284 options, specify them via @var{args}.
15285 @end table
15286
15287 @noindent
15288 After specifying this target, you can debug programs for the simulated
15289 CPU in the same style as programs for your host computer; use the
15290 @code{file} command to load a new program image, the @code{run} command
15291 to run your program, and so on.
15292
15293 As well as making available all the usual machine registers
15294 (@pxref{Registers, ,Registers}), the Z8000 simulator provides three
15295 additional items of information as specially named registers:
15296
15297 @table @code
15298
15299 @item cycles
15300 Counts clock-ticks in the simulator.
15301
15302 @item insts
15303 Counts instructions run in the simulator.
15304
15305 @item time
15306 Execution time in 60ths of a second.
15307
15308 @end table
15309
15310 You can refer to these values in @value{GDBN} expressions with the usual
15311 conventions; for example, @w{@samp{b fputc if $cycles>5000}} sets a
15312 conditional breakpoint that suspends only after at least 5000
15313 simulated clock ticks.
15314
15315 @node AVR
15316 @subsection Atmel AVR
15317 @cindex AVR
15318
15319 When configured for debugging the Atmel AVR, @value{GDBN} supports the
15320 following AVR-specific commands:
15321
15322 @table @code
15323 @item info io_registers
15324 @kindex info io_registers@r{, AVR}
15325 @cindex I/O registers (Atmel AVR)
15326 This command displays information about the AVR I/O registers. For
15327 each register, @value{GDBN} prints its number and value.
15328 @end table
15329
15330 @node CRIS
15331 @subsection CRIS
15332 @cindex CRIS
15333
15334 When configured for debugging CRIS, @value{GDBN} provides the
15335 following CRIS-specific commands:
15336
15337 @table @code
15338 @item set cris-version @var{ver}
15339 @cindex CRIS version
15340 Set the current CRIS version to @var{ver}, either @samp{10} or @samp{32}.
15341 The CRIS version affects register names and sizes. This command is useful in
15342 case autodetection of the CRIS version fails.
15343
15344 @item show cris-version
15345 Show the current CRIS version.
15346
15347 @item set cris-dwarf2-cfi
15348 @cindex DWARF-2 CFI and CRIS
15349 Set the usage of DWARF-2 CFI for CRIS debugging. The default is @samp{on}.
15350 Change to @samp{off} when using @code{gcc-cris} whose version is below
15351 @code{R59}.
15352
15353 @item show cris-dwarf2-cfi
15354 Show the current state of using DWARF-2 CFI.
15355
15356 @item set cris-mode @var{mode}
15357 @cindex CRIS mode
15358 Set the current CRIS mode to @var{mode}. It should only be changed when
15359 debugging in guru mode, in which case it should be set to
15360 @samp{guru} (the default is @samp{normal}).
15361
15362 @item show cris-mode
15363 Show the current CRIS mode.
15364 @end table
15365
15366 @node Super-H
15367 @subsection Renesas Super-H
15368 @cindex Super-H
15369
15370 For the Renesas Super-H processor, @value{GDBN} provides these
15371 commands:
15372
15373 @table @code
15374 @item regs
15375 @kindex regs@r{, Super-H}
15376 Show the values of all Super-H registers.
15377 @end table
15378
15379 @node WinCE
15380 @subsection Windows CE
15381 @cindex Windows CE
15382
15383 The following commands are available for Windows CE:
15384
15385 @table @code
15386 @item set remotedirectory @var{dir}
15387 @kindex set remotedirectory
15388 Tell @value{GDBN} to upload files from the named directory @var{dir}.
15389 The default is @file{/gdb}, i.e.@: the root directory on the current
15390 drive.
15391
15392 @item show remotedirectory
15393 @kindex show remotedirectory
15394 Show the current value of the upload directory.
15395
15396 @item set remoteupload @var{method}
15397 @kindex set remoteupload
15398 Set the method used to upload files to remote device. Valid values
15399 for @var{method} are @samp{always}, @samp{newer}, and @samp{never}.
15400 The default is @samp{newer}.
15401
15402 @item show remoteupload
15403 @kindex show remoteupload
15404 Show the current setting of the upload method.
15405
15406 @item set remoteaddhost
15407 @kindex set remoteaddhost
15408 Tell @value{GDBN} whether to add this host to the remote stub's
15409 arguments when you debug over a network.
15410
15411 @item show remoteaddhost
15412 @kindex show remoteaddhost
15413 Show whether to add this host to remote stub's arguments when
15414 debugging over a network.
15415 @end table
15416
15417
15418 @node Architectures
15419 @section Architectures
15420
15421 This section describes characteristics of architectures that affect
15422 all uses of @value{GDBN} with the architecture, both native and cross.
15423
15424 @menu
15425 * i386::
15426 * A29K::
15427 * Alpha::
15428 * MIPS::
15429 * HPPA:: HP PA architecture
15430 @end menu
15431
15432 @node i386
15433 @subsection x86 Architecture-specific issues.
15434
15435 @table @code
15436 @item set struct-convention @var{mode}
15437 @kindex set struct-convention
15438 @cindex struct return convention
15439 @cindex struct/union returned in registers
15440 Set the convention used by the inferior to return @code{struct}s and
15441 @code{union}s from functions to @var{mode}. Possible values of
15442 @var{mode} are @code{"pcc"}, @code{"reg"}, and @code{"default"} (the
15443 default). @code{"default"} or @code{"pcc"} means that @code{struct}s
15444 are returned on the stack, while @code{"reg"} means that a
15445 @code{struct} or a @code{union} whose size is 1, 2, 4, or 8 bytes will
15446 be returned in a register.
15447
15448 @item show struct-convention
15449 @kindex show struct-convention
15450 Show the current setting of the convention to return @code{struct}s
15451 from functions.
15452 @end table
15453
15454 @node A29K
15455 @subsection A29K
15456
15457 @table @code
15458
15459 @kindex set rstack_high_address
15460 @cindex AMD 29K register stack
15461 @cindex register stack, AMD29K
15462 @item set rstack_high_address @var{address}
15463 On AMD 29000 family processors, registers are saved in a separate
15464 @dfn{register stack}. There is no way for @value{GDBN} to determine the
15465 extent of this stack. Normally, @value{GDBN} just assumes that the
15466 stack is ``large enough''. This may result in @value{GDBN} referencing
15467 memory locations that do not exist. If necessary, you can get around
15468 this problem by specifying the ending address of the register stack with
15469 the @code{set rstack_high_address} command. The argument should be an
15470 address, which you probably want to precede with @samp{0x} to specify in
15471 hexadecimal.
15472
15473 @kindex show rstack_high_address
15474 @item show rstack_high_address
15475 Display the current limit of the register stack, on AMD 29000 family
15476 processors.
15477
15478 @end table
15479
15480 @node Alpha
15481 @subsection Alpha
15482
15483 See the following section.
15484
15485 @node MIPS
15486 @subsection MIPS
15487
15488 @cindex stack on Alpha
15489 @cindex stack on MIPS
15490 @cindex Alpha stack
15491 @cindex MIPS stack
15492 Alpha- and MIPS-based computers use an unusual stack frame, which
15493 sometimes requires @value{GDBN} to search backward in the object code to
15494 find the beginning of a function.
15495
15496 @cindex response time, MIPS debugging
15497 To improve response time (especially for embedded applications, where
15498 @value{GDBN} may be restricted to a slow serial line for this search)
15499 you may want to limit the size of this search, using one of these
15500 commands:
15501
15502 @table @code
15503 @cindex @code{heuristic-fence-post} (Alpha, MIPS)
15504 @item set heuristic-fence-post @var{limit}
15505 Restrict @value{GDBN} to examining at most @var{limit} bytes in its
15506 search for the beginning of a function. A value of @var{0} (the
15507 default) means there is no limit. However, except for @var{0}, the
15508 larger the limit the more bytes @code{heuristic-fence-post} must search
15509 and therefore the longer it takes to run. You should only need to use
15510 this command when debugging a stripped executable.
15511
15512 @item show heuristic-fence-post
15513 Display the current limit.
15514 @end table
15515
15516 @noindent
15517 These commands are available @emph{only} when @value{GDBN} is configured
15518 for debugging programs on Alpha or MIPS processors.
15519
15520 Several MIPS-specific commands are available when debugging MIPS
15521 programs:
15522
15523 @table @code
15524 @item set mips saved-gpreg-size @var{size}
15525 @kindex set mips saved-gpreg-size
15526 @cindex MIPS GP register size on stack
15527 Set the size of MIPS general-purpose registers saved on the stack.
15528 The argument @var{size} can be one of the following:
15529
15530 @table @samp
15531 @item 32
15532 32-bit GP registers
15533 @item 64
15534 64-bit GP registers
15535 @item auto
15536 Use the target's default setting or autodetect the saved size from the
15537 information contained in the executable. This is the default
15538 @end table
15539
15540 @item show mips saved-gpreg-size
15541 @kindex show mips saved-gpreg-size
15542 Show the current size of MIPS GP registers on the stack.
15543
15544 @item set mips stack-arg-size @var{size}
15545 @kindex set mips stack-arg-size
15546 @cindex MIPS stack space for arguments
15547 Set the amount of stack space reserved for arguments to functions.
15548 The argument can be one of @code{"32"}, @code{"64"} or @code{"auto"}
15549 (the default).
15550
15551 @item set mips abi @var{arg}
15552 @kindex set mips abi
15553 @cindex set ABI for MIPS
15554 Tell @value{GDBN} which MIPS ABI is used by the inferior. Possible
15555 values of @var{arg} are:
15556
15557 @table @samp
15558 @item auto
15559 The default ABI associated with the current binary (this is the
15560 default).
15561 @item o32
15562 @item o64
15563 @item n32
15564 @item n64
15565 @item eabi32
15566 @item eabi64
15567 @item auto
15568 @end table
15569
15570 @item show mips abi
15571 @kindex show mips abi
15572 Show the MIPS ABI used by @value{GDBN} to debug the inferior.
15573
15574 @item set mipsfpu
15575 @itemx show mipsfpu
15576 @xref{MIPS Embedded, set mipsfpu}.
15577
15578 @item set mips mask-address @var{arg}
15579 @kindex set mips mask-address
15580 @cindex MIPS addresses, masking
15581 This command determines whether the most-significant 32 bits of 64-bit
15582 MIPS addresses are masked off. The argument @var{arg} can be
15583 @samp{on}, @samp{off}, or @samp{auto}. The latter is the default
15584 setting, which lets @value{GDBN} determine the correct value.
15585
15586 @item show mips mask-address
15587 @kindex show mips mask-address
15588 Show whether the upper 32 bits of MIPS addresses are masked off or
15589 not.
15590
15591 @item set remote-mips64-transfers-32bit-regs
15592 @kindex set remote-mips64-transfers-32bit-regs
15593 This command controls compatibility with 64-bit MIPS targets that
15594 transfer data in 32-bit quantities. If you have an old MIPS 64 target
15595 that transfers 32 bits for some registers, like @sc{sr} and @sc{fsr},
15596 and 64 bits for other registers, set this option to @samp{on}.
15597
15598 @item show remote-mips64-transfers-32bit-regs
15599 @kindex show remote-mips64-transfers-32bit-regs
15600 Show the current setting of compatibility with older MIPS 64 targets.
15601
15602 @item set debug mips
15603 @kindex set debug mips
15604 This command turns on and off debugging messages for the MIPS-specific
15605 target code in @value{GDBN}.
15606
15607 @item show debug mips
15608 @kindex show debug mips
15609 Show the current setting of MIPS debugging messages.
15610 @end table
15611
15612
15613 @node HPPA
15614 @subsection HPPA
15615 @cindex HPPA support
15616
15617 When @value{GDBN} is debugging te HP PA architecture, it provides the
15618 following special commands:
15619
15620 @table @code
15621 @item set debug hppa
15622 @kindex set debug hppa
15623 THis command determines whether HPPA architecture specific debugging
15624 messages are to be displayed.
15625
15626 @item show debug hppa
15627 Show whether HPPA debugging messages are displayed.
15628
15629 @item maint print unwind @var{address}
15630 @kindex maint print unwind@r{, HPPA}
15631 This command displays the contents of the unwind table entry at the
15632 given @var{address}.
15633
15634 @end table
15635
15636
15637 @node Controlling GDB
15638 @chapter Controlling @value{GDBN}
15639
15640 You can alter the way @value{GDBN} interacts with you by using the
15641 @code{set} command. For commands controlling how @value{GDBN} displays
15642 data, see @ref{Print Settings, ,Print settings}. Other settings are
15643 described here.
15644
15645 @menu
15646 * Prompt:: Prompt
15647 * Editing:: Command editing
15648 * Command History:: Command history
15649 * Screen Size:: Screen size
15650 * Numbers:: Numbers
15651 * ABI:: Configuring the current ABI
15652 * Messages/Warnings:: Optional warnings and messages
15653 * Debugging Output:: Optional messages about internal happenings
15654 @end menu
15655
15656 @node Prompt
15657 @section Prompt
15658
15659 @cindex prompt
15660
15661 @value{GDBN} indicates its readiness to read a command by printing a string
15662 called the @dfn{prompt}. This string is normally @samp{(@value{GDBP})}. You
15663 can change the prompt string with the @code{set prompt} command. For
15664 instance, when debugging @value{GDBN} with @value{GDBN}, it is useful to change
15665 the prompt in one of the @value{GDBN} sessions so that you can always tell
15666 which one you are talking to.
15667
15668 @emph{Note:} @code{set prompt} does not add a space for you after the
15669 prompt you set. This allows you to set a prompt which ends in a space
15670 or a prompt that does not.
15671
15672 @table @code
15673 @kindex set prompt
15674 @item set prompt @var{newprompt}
15675 Directs @value{GDBN} to use @var{newprompt} as its prompt string henceforth.
15676
15677 @kindex show prompt
15678 @item show prompt
15679 Prints a line of the form: @samp{Gdb's prompt is: @var{your-prompt}}
15680 @end table
15681
15682 @node Editing
15683 @section Command editing
15684 @cindex readline
15685 @cindex command line editing
15686
15687 @value{GDBN} reads its input commands via the @dfn{Readline} interface. This
15688 @sc{gnu} library provides consistent behavior for programs which provide a
15689 command line interface to the user. Advantages are @sc{gnu} Emacs-style
15690 or @dfn{vi}-style inline editing of commands, @code{csh}-like history
15691 substitution, and a storage and recall of command history across
15692 debugging sessions.
15693
15694 You may control the behavior of command line editing in @value{GDBN} with the
15695 command @code{set}.
15696
15697 @table @code
15698 @kindex set editing
15699 @cindex editing
15700 @item set editing
15701 @itemx set editing on
15702 Enable command line editing (enabled by default).
15703
15704 @item set editing off
15705 Disable command line editing.
15706
15707 @kindex show editing
15708 @item show editing
15709 Show whether command line editing is enabled.
15710 @end table
15711
15712 @xref{Command Line Editing}, for more details about the Readline
15713 interface. Users unfamiliar with @sc{gnu} Emacs or @code{vi} are
15714 encouraged to read that chapter.
15715
15716 @node Command History
15717 @section Command history
15718 @cindex command history
15719
15720 @value{GDBN} can keep track of the commands you type during your
15721 debugging sessions, so that you can be certain of precisely what
15722 happened. Use these commands to manage the @value{GDBN} command
15723 history facility.
15724
15725 @value{GDBN} uses the @sc{gnu} History library, a part of the Readline
15726 package, to provide the history facility. @xref{Using History
15727 Interactively}, for the detailed description of the History library.
15728
15729 To issue a command to @value{GDBN} without affecting certain aspects of
15730 the state which is seen by users, prefix it with @samp{server }. This
15731 means that this command will not affect the command history, nor will it
15732 affect @value{GDBN}'s notion of which command to repeat if @key{RET} is
15733 pressed on a line by itself.
15734
15735 @cindex @code{server}, command prefix
15736 The server prefix does not affect the recording of values into the value
15737 history; to print a value without recording it into the value history,
15738 use the @code{output} command instead of the @code{print} command.
15739
15740 Here is the description of @value{GDBN} commands related to command
15741 history.
15742
15743 @table @code
15744 @cindex history substitution
15745 @cindex history file
15746 @kindex set history filename
15747 @cindex @env{GDBHISTFILE}, environment variable
15748 @item set history filename @var{fname}
15749 Set the name of the @value{GDBN} command history file to @var{fname}.
15750 This is the file where @value{GDBN} reads an initial command history
15751 list, and where it writes the command history from this session when it
15752 exits. You can access this list through history expansion or through
15753 the history command editing characters listed below. This file defaults
15754 to the value of the environment variable @code{GDBHISTFILE}, or to
15755 @file{./.gdb_history} (@file{./_gdb_history} on MS-DOS) if this variable
15756 is not set.
15757
15758 @cindex save command history
15759 @kindex set history save
15760 @item set history save
15761 @itemx set history save on
15762 Record command history in a file, whose name may be specified with the
15763 @code{set history filename} command. By default, this option is disabled.
15764
15765 @item set history save off
15766 Stop recording command history in a file.
15767
15768 @cindex history size
15769 @kindex set history size
15770 @cindex @env{HISTSIZE}, environment variable
15771 @item set history size @var{size}
15772 Set the number of commands which @value{GDBN} keeps in its history list.
15773 This defaults to the value of the environment variable
15774 @code{HISTSIZE}, or to 256 if this variable is not set.
15775 @end table
15776
15777 History expansion assigns special meaning to the character @kbd{!}.
15778 @xref{Event Designators}, for more details.
15779
15780 @cindex history expansion, turn on/off
15781 Since @kbd{!} is also the logical not operator in C, history expansion
15782 is off by default. If you decide to enable history expansion with the
15783 @code{set history expansion on} command, you may sometimes need to
15784 follow @kbd{!} (when it is used as logical not, in an expression) with
15785 a space or a tab to prevent it from being expanded. The readline
15786 history facilities do not attempt substitution on the strings
15787 @kbd{!=} and @kbd{!(}, even when history expansion is enabled.
15788
15789 The commands to control history expansion are:
15790
15791 @table @code
15792 @item set history expansion on
15793 @itemx set history expansion
15794 @kindex set history expansion
15795 Enable history expansion. History expansion is off by default.
15796
15797 @item set history expansion off
15798 Disable history expansion.
15799
15800 @c @group
15801 @kindex show history
15802 @item show history
15803 @itemx show history filename
15804 @itemx show history save
15805 @itemx show history size
15806 @itemx show history expansion
15807 These commands display the state of the @value{GDBN} history parameters.
15808 @code{show history} by itself displays all four states.
15809 @c @end group
15810 @end table
15811
15812 @table @code
15813 @kindex show commands
15814 @cindex show last commands
15815 @cindex display command history
15816 @item show commands
15817 Display the last ten commands in the command history.
15818
15819 @item show commands @var{n}
15820 Print ten commands centered on command number @var{n}.
15821
15822 @item show commands +
15823 Print ten commands just after the commands last printed.
15824 @end table
15825
15826 @node Screen Size
15827 @section Screen size
15828 @cindex size of screen
15829 @cindex pauses in output
15830
15831 Certain commands to @value{GDBN} may produce large amounts of
15832 information output to the screen. To help you read all of it,
15833 @value{GDBN} pauses and asks you for input at the end of each page of
15834 output. Type @key{RET} when you want to continue the output, or @kbd{q}
15835 to discard the remaining output. Also, the screen width setting
15836 determines when to wrap lines of output. Depending on what is being
15837 printed, @value{GDBN} tries to break the line at a readable place,
15838 rather than simply letting it overflow onto the following line.
15839
15840 Normally @value{GDBN} knows the size of the screen from the terminal
15841 driver software. For example, on Unix @value{GDBN} uses the termcap data base
15842 together with the value of the @code{TERM} environment variable and the
15843 @code{stty rows} and @code{stty cols} settings. If this is not correct,
15844 you can override it with the @code{set height} and @code{set
15845 width} commands:
15846
15847 @table @code
15848 @kindex set height
15849 @kindex set width
15850 @kindex show width
15851 @kindex show height
15852 @item set height @var{lpp}
15853 @itemx show height
15854 @itemx set width @var{cpl}
15855 @itemx show width
15856 These @code{set} commands specify a screen height of @var{lpp} lines and
15857 a screen width of @var{cpl} characters. The associated @code{show}
15858 commands display the current settings.
15859
15860 If you specify a height of zero lines, @value{GDBN} does not pause during
15861 output no matter how long the output is. This is useful if output is to a
15862 file or to an editor buffer.
15863
15864 Likewise, you can specify @samp{set width 0} to prevent @value{GDBN}
15865 from wrapping its output.
15866
15867 @item set pagination on
15868 @itemx set pagination off
15869 @kindex set pagination
15870 Turn the output pagination on or off; the default is on. Turning
15871 pagination off is the alternative to @code{set height 0}.
15872
15873 @item show pagination
15874 @kindex show pagination
15875 Show the current pagination mode.
15876 @end table
15877
15878 @node Numbers
15879 @section Numbers
15880 @cindex number representation
15881 @cindex entering numbers
15882
15883 You can always enter numbers in octal, decimal, or hexadecimal in
15884 @value{GDBN} by the usual conventions: octal numbers begin with
15885 @samp{0}, decimal numbers end with @samp{.}, and hexadecimal numbers
15886 begin with @samp{0x}. Numbers that neither begin with @samp{0} or
15887 @samp{0x}, nor end with a @samp{.} are, by default, entered in base
15888 10; likewise, the default display for numbers---when no particular
15889 format is specified---is base 10. You can change the default base for
15890 both input and output with the commands described below.
15891
15892 @table @code
15893 @kindex set input-radix
15894 @item set input-radix @var{base}
15895 Set the default base for numeric input. Supported choices
15896 for @var{base} are decimal 8, 10, or 16. @var{base} must itself be
15897 specified either unambiguously or using the current input radix; for
15898 example, any of
15899
15900 @smallexample
15901 set input-radix 012
15902 set input-radix 10.
15903 set input-radix 0xa
15904 @end smallexample
15905
15906 @noindent
15907 sets the input base to decimal. On the other hand, @samp{set input-radix 10}
15908 leaves the input radix unchanged, no matter what it was, since
15909 @samp{10}, being without any leading or trailing signs of its base, is
15910 interpreted in the current radix. Thus, if the current radix is 16,
15911 @samp{10} is interpreted in hex, i.e.@: as 16 decimal, which doesn't
15912 change the radix.
15913
15914 @kindex set output-radix
15915 @item set output-radix @var{base}
15916 Set the default base for numeric display. Supported choices
15917 for @var{base} are decimal 8, 10, or 16. @var{base} must itself be
15918 specified either unambiguously or using the current input radix.
15919
15920 @kindex show input-radix
15921 @item show input-radix
15922 Display the current default base for numeric input.
15923
15924 @kindex show output-radix
15925 @item show output-radix
15926 Display the current default base for numeric display.
15927
15928 @item set radix @r{[}@var{base}@r{]}
15929 @itemx show radix
15930 @kindex set radix
15931 @kindex show radix
15932 These commands set and show the default base for both input and output
15933 of numbers. @code{set radix} sets the radix of input and output to
15934 the same base; without an argument, it resets the radix back to its
15935 default value of 10.
15936
15937 @end table
15938
15939 @node ABI
15940 @section Configuring the current ABI
15941
15942 @value{GDBN} can determine the @dfn{ABI} (Application Binary Interface) of your
15943 application automatically. However, sometimes you need to override its
15944 conclusions. Use these commands to manage @value{GDBN}'s view of the
15945 current ABI.
15946
15947 @cindex OS ABI
15948 @kindex set osabi
15949 @kindex show osabi
15950
15951 One @value{GDBN} configuration can debug binaries for multiple operating
15952 system targets, either via remote debugging or native emulation.
15953 @value{GDBN} will autodetect the @dfn{OS ABI} (Operating System ABI) in use,
15954 but you can override its conclusion using the @code{set osabi} command.
15955 One example where this is useful is in debugging of binaries which use
15956 an alternate C library (e.g.@: @sc{uClibc} for @sc{gnu}/Linux) which does
15957 not have the same identifying marks that the standard C library for your
15958 platform provides.
15959
15960 @table @code
15961 @item show osabi
15962 Show the OS ABI currently in use.
15963
15964 @item set osabi
15965 With no argument, show the list of registered available OS ABI's.
15966
15967 @item set osabi @var{abi}
15968 Set the current OS ABI to @var{abi}.
15969 @end table
15970
15971 @cindex float promotion
15972
15973 Generally, the way that an argument of type @code{float} is passed to a
15974 function depends on whether the function is prototyped. For a prototyped
15975 (i.e.@: ANSI/ISO style) function, @code{float} arguments are passed unchanged,
15976 according to the architecture's convention for @code{float}. For unprototyped
15977 (i.e.@: K&R style) functions, @code{float} arguments are first promoted to type
15978 @code{double} and then passed.
15979
15980 Unfortunately, some forms of debug information do not reliably indicate whether
15981 a function is prototyped. If @value{GDBN} calls a function that is not marked
15982 as prototyped, it consults @kbd{set coerce-float-to-double}.
15983
15984 @table @code
15985 @kindex set coerce-float-to-double
15986 @item set coerce-float-to-double
15987 @itemx set coerce-float-to-double on
15988 Arguments of type @code{float} will be promoted to @code{double} when passed
15989 to an unprototyped function. This is the default setting.
15990
15991 @item set coerce-float-to-double off
15992 Arguments of type @code{float} will be passed directly to unprototyped
15993 functions.
15994
15995 @kindex show coerce-float-to-double
15996 @item show coerce-float-to-double
15997 Show the current setting of promoting @code{float} to @code{double}.
15998 @end table
15999
16000 @kindex set cp-abi
16001 @kindex show cp-abi
16002 @value{GDBN} needs to know the ABI used for your program's C@t{++}
16003 objects. The correct C@t{++} ABI depends on which C@t{++} compiler was
16004 used to build your application. @value{GDBN} only fully supports
16005 programs with a single C@t{++} ABI; if your program contains code using
16006 multiple C@t{++} ABI's or if @value{GDBN} can not identify your
16007 program's ABI correctly, you can tell @value{GDBN} which ABI to use.
16008 Currently supported ABI's include ``gnu-v2'', for @code{g++} versions
16009 before 3.0, ``gnu-v3'', for @code{g++} versions 3.0 and later, and
16010 ``hpaCC'' for the HP ANSI C@t{++} compiler. Other C@t{++} compilers may
16011 use the ``gnu-v2'' or ``gnu-v3'' ABI's as well. The default setting is
16012 ``auto''.
16013
16014 @table @code
16015 @item show cp-abi
16016 Show the C@t{++} ABI currently in use.
16017
16018 @item set cp-abi
16019 With no argument, show the list of supported C@t{++} ABI's.
16020
16021 @item set cp-abi @var{abi}
16022 @itemx set cp-abi auto
16023 Set the current C@t{++} ABI to @var{abi}, or return to automatic detection.
16024 @end table
16025
16026 @node Messages/Warnings
16027 @section Optional warnings and messages
16028
16029 @cindex verbose operation
16030 @cindex optional warnings
16031 By default, @value{GDBN} is silent about its inner workings. If you are
16032 running on a slow machine, you may want to use the @code{set verbose}
16033 command. This makes @value{GDBN} tell you when it does a lengthy
16034 internal operation, so you will not think it has crashed.
16035
16036 Currently, the messages controlled by @code{set verbose} are those
16037 which announce that the symbol table for a source file is being read;
16038 see @code{symbol-file} in @ref{Files, ,Commands to specify files}.
16039
16040 @table @code
16041 @kindex set verbose
16042 @item set verbose on
16043 Enables @value{GDBN} output of certain informational messages.
16044
16045 @item set verbose off
16046 Disables @value{GDBN} output of certain informational messages.
16047
16048 @kindex show verbose
16049 @item show verbose
16050 Displays whether @code{set verbose} is on or off.
16051 @end table
16052
16053 By default, if @value{GDBN} encounters bugs in the symbol table of an
16054 object file, it is silent; but if you are debugging a compiler, you may
16055 find this information useful (@pxref{Symbol Errors, ,Errors reading
16056 symbol files}).
16057
16058 @table @code
16059
16060 @kindex set complaints
16061 @item set complaints @var{limit}
16062 Permits @value{GDBN} to output @var{limit} complaints about each type of
16063 unusual symbols before becoming silent about the problem. Set
16064 @var{limit} to zero to suppress all complaints; set it to a large number
16065 to prevent complaints from being suppressed.
16066
16067 @kindex show complaints
16068 @item show complaints
16069 Displays how many symbol complaints @value{GDBN} is permitted to produce.
16070
16071 @end table
16072
16073 By default, @value{GDBN} is cautious, and asks what sometimes seems to be a
16074 lot of stupid questions to confirm certain commands. For example, if
16075 you try to run a program which is already running:
16076
16077 @smallexample
16078 (@value{GDBP}) run
16079 The program being debugged has been started already.
16080 Start it from the beginning? (y or n)
16081 @end smallexample
16082
16083 If you are willing to unflinchingly face the consequences of your own
16084 commands, you can disable this ``feature'':
16085
16086 @table @code
16087
16088 @kindex set confirm
16089 @cindex flinching
16090 @cindex confirmation
16091 @cindex stupid questions
16092 @item set confirm off
16093 Disables confirmation requests.
16094
16095 @item set confirm on
16096 Enables confirmation requests (the default).
16097
16098 @kindex show confirm
16099 @item show confirm
16100 Displays state of confirmation requests.
16101
16102 @end table
16103
16104 @cindex command tracing
16105 If you need to debug user-defined commands or sourced files you may find it
16106 useful to enable @dfn{command tracing}. In this mode each command will be
16107 printed as it is executed, prefixed with one or more @samp{+} symbols, the
16108 quantity denoting the call depth of each command.
16109
16110 @table @code
16111 @kindex set trace-commands
16112 @cindex command scripts, debugging
16113 @item set trace-commands on
16114 Enable command tracing.
16115 @item set trace-commands off
16116 Disable command tracing.
16117 @item show trace-commands
16118 Display the current state of command tracing.
16119 @end table
16120
16121 @node Debugging Output
16122 @section Optional messages about internal happenings
16123 @cindex optional debugging messages
16124
16125 @value{GDBN} has commands that enable optional debugging messages from
16126 various @value{GDBN} subsystems; normally these commands are of
16127 interest to @value{GDBN} maintainers, or when reporting a bug. This
16128 section documents those commands.
16129
16130 @table @code
16131 @kindex set exec-done-display
16132 @item set exec-done-display
16133 Turns on or off the notification of asynchronous commands'
16134 completion. When on, @value{GDBN} will print a message when an
16135 asynchronous command finishes its execution. The default is off.
16136 @kindex show exec-done-display
16137 @item show exec-done-display
16138 Displays the current setting of asynchronous command completion
16139 notification.
16140 @kindex set debug
16141 @cindex gdbarch debugging info
16142 @cindex architecture debugging info
16143 @item set debug arch
16144 Turns on or off display of gdbarch debugging info. The default is off
16145 @kindex show debug
16146 @item show debug arch
16147 Displays the current state of displaying gdbarch debugging info.
16148 @item set debug aix-thread
16149 @cindex AIX threads
16150 Display debugging messages about inner workings of the AIX thread
16151 module.
16152 @item show debug aix-thread
16153 Show the current state of AIX thread debugging info display.
16154 @item set debug event
16155 @cindex event debugging info
16156 Turns on or off display of @value{GDBN} event debugging info. The
16157 default is off.
16158 @item show debug event
16159 Displays the current state of displaying @value{GDBN} event debugging
16160 info.
16161 @item set debug expression
16162 @cindex expression debugging info
16163 Turns on or off display of debugging info about @value{GDBN}
16164 expression parsing. The default is off.
16165 @item show debug expression
16166 Displays the current state of displaying debugging info about
16167 @value{GDBN} expression parsing.
16168 @item set debug frame
16169 @cindex frame debugging info
16170 Turns on or off display of @value{GDBN} frame debugging info. The
16171 default is off.
16172 @item show debug frame
16173 Displays the current state of displaying @value{GDBN} frame debugging
16174 info.
16175 @item set debug infrun
16176 @cindex inferior debugging info
16177 Turns on or off display of @value{GDBN} debugging info for running the inferior.
16178 The default is off. @file{infrun.c} contains GDB's runtime state machine used
16179 for implementing operations such as single-stepping the inferior.
16180 @item show debug infrun
16181 Displays the current state of @value{GDBN} inferior debugging.
16182 @item set debug lin-lwp
16183 @cindex @sc{gnu}/Linux LWP debug messages
16184 @cindex Linux lightweight processes
16185 Turns on or off debugging messages from the Linux LWP debug support.
16186 @item show debug lin-lwp
16187 Show the current state of Linux LWP debugging messages.
16188 @item set debug observer
16189 @cindex observer debugging info
16190 Turns on or off display of @value{GDBN} observer debugging. This
16191 includes info such as the notification of observable events.
16192 @item show debug observer
16193 Displays the current state of observer debugging.
16194 @item set debug overload
16195 @cindex C@t{++} overload debugging info
16196 Turns on or off display of @value{GDBN} C@t{++} overload debugging
16197 info. This includes info such as ranking of functions, etc. The default
16198 is off.
16199 @item show debug overload
16200 Displays the current state of displaying @value{GDBN} C@t{++} overload
16201 debugging info.
16202 @cindex packets, reporting on stdout
16203 @cindex serial connections, debugging
16204 @cindex debug remote protocol
16205 @cindex remote protocol debugging
16206 @cindex display remote packets
16207 @item set debug remote
16208 Turns on or off display of reports on all packets sent back and forth across
16209 the serial line to the remote machine. The info is printed on the
16210 @value{GDBN} standard output stream. The default is off.
16211 @item show debug remote
16212 Displays the state of display of remote packets.
16213 @item set debug serial
16214 Turns on or off display of @value{GDBN} serial debugging info. The
16215 default is off.
16216 @item show debug serial
16217 Displays the current state of displaying @value{GDBN} serial debugging
16218 info.
16219 @item set debug solib-frv
16220 @cindex FR-V shared-library debugging
16221 Turns on or off debugging messages for FR-V shared-library code.
16222 @item show debug solib-frv
16223 Display the current state of FR-V shared-library code debugging
16224 messages.
16225 @item set debug target
16226 @cindex target debugging info
16227 Turns on or off display of @value{GDBN} target debugging info. This info
16228 includes what is going on at the target level of GDB, as it happens. The
16229 default is 0. Set it to 1 to track events, and to 2 to also track the
16230 value of large memory transfers. Changes to this flag do not take effect
16231 until the next time you connect to a target or use the @code{run} command.
16232 @item show debug target
16233 Displays the current state of displaying @value{GDBN} target debugging
16234 info.
16235 @item set debugvarobj
16236 @cindex variable object debugging info
16237 Turns on or off display of @value{GDBN} variable object debugging
16238 info. The default is off.
16239 @item show debugvarobj
16240 Displays the current state of displaying @value{GDBN} variable object
16241 debugging info.
16242 @end table
16243
16244 @node Sequences
16245 @chapter Canned Sequences of Commands
16246
16247 Aside from breakpoint commands (@pxref{Break Commands, ,Breakpoint
16248 command lists}), @value{GDBN} provides two ways to store sequences of
16249 commands for execution as a unit: user-defined commands and command
16250 files.
16251
16252 @menu
16253 * Define:: How to define your own commands
16254 * Hooks:: Hooks for user-defined commands
16255 * Command Files:: How to write scripts of commands to be stored in a file
16256 * Output:: Commands for controlled output
16257 @end menu
16258
16259 @node Define
16260 @section User-defined commands
16261
16262 @cindex user-defined command
16263 @cindex arguments, to user-defined commands
16264 A @dfn{user-defined command} is a sequence of @value{GDBN} commands to
16265 which you assign a new name as a command. This is done with the
16266 @code{define} command. User commands may accept up to 10 arguments
16267 separated by whitespace. Arguments are accessed within the user command
16268 via @code{$arg0@dots{}$arg9}. A trivial example:
16269
16270 @smallexample
16271 define adder
16272 print $arg0 + $arg1 + $arg2
16273 end
16274 @end smallexample
16275
16276 @noindent
16277 To execute the command use:
16278
16279 @smallexample
16280 adder 1 2 3
16281 @end smallexample
16282
16283 @noindent
16284 This defines the command @code{adder}, which prints the sum of
16285 its three arguments. Note the arguments are text substitutions, so they may
16286 reference variables, use complex expressions, or even perform inferior
16287 functions calls.
16288
16289 @cindex argument count in user-defined commands
16290 @cindex how many arguments (user-defined commands)
16291 In addition, @code{$argc} may be used to find out how many arguments have
16292 been passed. This expands to a number in the range 0@dots{}10.
16293
16294 @smallexample
16295 define adder
16296 if $argc == 2
16297 print $arg0 + $arg1
16298 end
16299 if $argc == 3
16300 print $arg0 + $arg1 + $arg2
16301 end
16302 end
16303 @end smallexample
16304
16305 @table @code
16306
16307 @kindex define
16308 @item define @var{commandname}
16309 Define a command named @var{commandname}. If there is already a command
16310 by that name, you are asked to confirm that you want to redefine it.
16311
16312 The definition of the command is made up of other @value{GDBN} command lines,
16313 which are given following the @code{define} command. The end of these
16314 commands is marked by a line containing @code{end}.
16315
16316 @kindex document
16317 @kindex end@r{ (user-defined commands)}
16318 @item document @var{commandname}
16319 Document the user-defined command @var{commandname}, so that it can be
16320 accessed by @code{help}. The command @var{commandname} must already be
16321 defined. This command reads lines of documentation just as @code{define}
16322 reads the lines of the command definition, ending with @code{end}.
16323 After the @code{document} command is finished, @code{help} on command
16324 @var{commandname} displays the documentation you have written.
16325
16326 You may use the @code{document} command again to change the
16327 documentation of a command. Redefining the command with @code{define}
16328 does not change the documentation.
16329
16330 @kindex dont-repeat
16331 @cindex don't repeat command
16332 @item dont-repeat
16333 Used inside a user-defined command, this tells @value{GDBN} that this
16334 command should not be repeated when the user hits @key{RET}
16335 (@pxref{Command Syntax, repeat last command}).
16336
16337 @kindex help user-defined
16338 @item help user-defined
16339 List all user-defined commands, with the first line of the documentation
16340 (if any) for each.
16341
16342 @kindex show user
16343 @item show user
16344 @itemx show user @var{commandname}
16345 Display the @value{GDBN} commands used to define @var{commandname} (but
16346 not its documentation). If no @var{commandname} is given, display the
16347 definitions for all user-defined commands.
16348
16349 @cindex infinite recursion in user-defined commands
16350 @kindex show max-user-call-depth
16351 @kindex set max-user-call-depth
16352 @item show max-user-call-depth
16353 @itemx set max-user-call-depth
16354 The value of @code{max-user-call-depth} controls how many recursion
16355 levels are allowed in user-defined commands before GDB suspects an
16356 infinite recursion and aborts the command.
16357 @end table
16358
16359 In addition to the above commands, user-defined commands frequently
16360 use control flow commands, described in @ref{Command Files}.
16361
16362 When user-defined commands are executed, the
16363 commands of the definition are not printed. An error in any command
16364 stops execution of the user-defined command.
16365
16366 If used interactively, commands that would ask for confirmation proceed
16367 without asking when used inside a user-defined command. Many @value{GDBN}
16368 commands that normally print messages to say what they are doing omit the
16369 messages when used in a user-defined command.
16370
16371 @node Hooks
16372 @section User-defined command hooks
16373 @cindex command hooks
16374 @cindex hooks, for commands
16375 @cindex hooks, pre-command
16376
16377 @kindex hook
16378 You may define @dfn{hooks}, which are a special kind of user-defined
16379 command. Whenever you run the command @samp{foo}, if the user-defined
16380 command @samp{hook-foo} exists, it is executed (with no arguments)
16381 before that command.
16382
16383 @cindex hooks, post-command
16384 @kindex hookpost
16385 A hook may also be defined which is run after the command you executed.
16386 Whenever you run the command @samp{foo}, if the user-defined command
16387 @samp{hookpost-foo} exists, it is executed (with no arguments) after
16388 that command. Post-execution hooks may exist simultaneously with
16389 pre-execution hooks, for the same command.
16390
16391 It is valid for a hook to call the command which it hooks. If this
16392 occurs, the hook is not re-executed, thereby avoiding infinite recursion.
16393
16394 @c It would be nice if hookpost could be passed a parameter indicating
16395 @c if the command it hooks executed properly or not. FIXME!
16396
16397 @kindex stop@r{, a pseudo-command}
16398 In addition, a pseudo-command, @samp{stop} exists. Defining
16399 (@samp{hook-stop}) makes the associated commands execute every time
16400 execution stops in your program: before breakpoint commands are run,
16401 displays are printed, or the stack frame is printed.
16402
16403 For example, to ignore @code{SIGALRM} signals while
16404 single-stepping, but treat them normally during normal execution,
16405 you could define:
16406
16407 @smallexample
16408 define hook-stop
16409 handle SIGALRM nopass
16410 end
16411
16412 define hook-run
16413 handle SIGALRM pass
16414 end
16415
16416 define hook-continue
16417 handle SIGLARM pass
16418 end
16419 @end smallexample
16420
16421 As a further example, to hook at the begining and end of the @code{echo}
16422 command, and to add extra text to the beginning and end of the message,
16423 you could define:
16424
16425 @smallexample
16426 define hook-echo
16427 echo <<<---
16428 end
16429
16430 define hookpost-echo
16431 echo --->>>\n
16432 end
16433
16434 (@value{GDBP}) echo Hello World
16435 <<<---Hello World--->>>
16436 (@value{GDBP})
16437
16438 @end smallexample
16439
16440 You can define a hook for any single-word command in @value{GDBN}, but
16441 not for command aliases; you should define a hook for the basic command
16442 name, e.g.@: @code{backtrace} rather than @code{bt}.
16443 @c FIXME! So how does Joe User discover whether a command is an alias
16444 @c or not?
16445 If an error occurs during the execution of your hook, execution of
16446 @value{GDBN} commands stops and @value{GDBN} issues a prompt
16447 (before the command that you actually typed had a chance to run).
16448
16449 If you try to define a hook which does not match any known command, you
16450 get a warning from the @code{define} command.
16451
16452 @node Command Files
16453 @section Command files
16454
16455 @cindex command files
16456 @cindex scripting commands
16457 A command file for @value{GDBN} is a text file made of lines that are
16458 @value{GDBN} commands. Comments (lines starting with @kbd{#}) may
16459 also be included. An empty line in a command file does nothing; it
16460 does not mean to repeat the last command, as it would from the
16461 terminal.
16462
16463 You can request the execution of a command file with the @code{source}
16464 command:
16465
16466 @table @code
16467 @kindex source
16468 @cindex execute commands from a file
16469 @item source [@code{-v}] @var{filename}
16470 Execute the command file @var{filename}.
16471 @end table
16472
16473 The lines in a command file are generally executed sequentially,
16474 unless the order of execution is changed by one of the
16475 @emph{flow-control commands} described below. The commands are not
16476 printed as they are executed. An error in any command terminates
16477 execution of the command file and control is returned to the console.
16478
16479 @value{GDBN} searches for @var{filename} in the current directory and then
16480 on the search path (specified with the @samp{directory} command).
16481
16482 If @code{-v}, for verbose mode, is given then @value{GDBN} displays
16483 each command as it is executed. The option must be given before
16484 @var{filename}, and is interpreted as part of the filename anywhere else.
16485
16486 Commands that would ask for confirmation if used interactively proceed
16487 without asking when used in a command file. Many @value{GDBN} commands that
16488 normally print messages to say what they are doing omit the messages
16489 when called from command files.
16490
16491 @value{GDBN} also accepts command input from standard input. In this
16492 mode, normal output goes to standard output and error output goes to
16493 standard error. Errors in a command file supplied on standard input do
16494 not terminate execution of the command file---execution continues with
16495 the next command.
16496
16497 @smallexample
16498 gdb < cmds > log 2>&1
16499 @end smallexample
16500
16501 (The syntax above will vary depending on the shell used.) This example
16502 will execute commands from the file @file{cmds}. All output and errors
16503 would be directed to @file{log}.
16504
16505 Since commands stored on command files tend to be more general than
16506 commands typed interactively, they frequently need to deal with
16507 complicated situations, such as different or unexpected values of
16508 variables and symbols, changes in how the program being debugged is
16509 built, etc. @value{GDBN} provides a set of flow-control commands to
16510 deal with these complexities. Using these commands, you can write
16511 complex scripts that loop over data structures, execute commands
16512 conditionally, etc.
16513
16514 @table @code
16515 @kindex if
16516 @kindex else
16517 @item if
16518 @itemx else
16519 This command allows to include in your script conditionally executed
16520 commands. The @code{if} command takes a single argument, which is an
16521 expression to evaluate. It is followed by a series of commands that
16522 are executed only if the expression is true (its value is nonzero).
16523 There can then optionally be an @code{else} line, followed by a series
16524 of commands that are only executed if the expression was false. The
16525 end of the list is marked by a line containing @code{end}.
16526
16527 @kindex while
16528 @item while
16529 This command allows to write loops. Its syntax is similar to
16530 @code{if}: the command takes a single argument, which is an expression
16531 to evaluate, and must be followed by the commands to execute, one per
16532 line, terminated by an @code{end}. These commands are called the
16533 @dfn{body} of the loop. The commands in the body of @code{while} are
16534 executed repeatedly as long as the expression evaluates to true.
16535
16536 @kindex loop_break
16537 @item loop_break
16538 This command exits the @code{while} loop in whose body it is included.
16539 Execution of the script continues after that @code{while}s @code{end}
16540 line.
16541
16542 @kindex loop_continue
16543 @item loop_continue
16544 This command skips the execution of the rest of the body of commands
16545 in the @code{while} loop in whose body it is included. Execution
16546 branches to the beginning of the @code{while} loop, where it evaluates
16547 the controlling expression.
16548
16549 @kindex end@r{ (if/else/while commands)}
16550 @item end
16551 Terminate the block of commands that are the body of @code{if},
16552 @code{else}, or @code{while} flow-control commands.
16553 @end table
16554
16555
16556 @node Output
16557 @section Commands for controlled output
16558
16559 During the execution of a command file or a user-defined command, normal
16560 @value{GDBN} output is suppressed; the only output that appears is what is
16561 explicitly printed by the commands in the definition. This section
16562 describes three commands useful for generating exactly the output you
16563 want.
16564
16565 @table @code
16566 @kindex echo
16567 @item echo @var{text}
16568 @c I do not consider backslash-space a standard C escape sequence
16569 @c because it is not in ANSI.
16570 Print @var{text}. Nonprinting characters can be included in
16571 @var{text} using C escape sequences, such as @samp{\n} to print a
16572 newline. @strong{No newline is printed unless you specify one.}
16573 In addition to the standard C escape sequences, a backslash followed
16574 by a space stands for a space. This is useful for displaying a
16575 string with spaces at the beginning or the end, since leading and
16576 trailing spaces are otherwise trimmed from all arguments.
16577 To print @samp{@w{ }and foo =@w{ }}, use the command
16578 @samp{echo \@w{ }and foo = \@w{ }}.
16579
16580 A backslash at the end of @var{text} can be used, as in C, to continue
16581 the command onto subsequent lines. For example,
16582
16583 @smallexample
16584 echo This is some text\n\
16585 which is continued\n\
16586 onto several lines.\n
16587 @end smallexample
16588
16589 produces the same output as
16590
16591 @smallexample
16592 echo This is some text\n
16593 echo which is continued\n
16594 echo onto several lines.\n
16595 @end smallexample
16596
16597 @kindex output
16598 @item output @var{expression}
16599 Print the value of @var{expression} and nothing but that value: no
16600 newlines, no @samp{$@var{nn} = }. The value is not entered in the
16601 value history either. @xref{Expressions, ,Expressions}, for more information
16602 on expressions.
16603
16604 @item output/@var{fmt} @var{expression}
16605 Print the value of @var{expression} in format @var{fmt}. You can use
16606 the same formats as for @code{print}. @xref{Output Formats,,Output
16607 formats}, for more information.
16608
16609 @kindex printf
16610 @item printf @var{string}, @var{expressions}@dots{}
16611 Print the values of the @var{expressions} under the control of
16612 @var{string}. The @var{expressions} are separated by commas and may be
16613 either numbers or pointers. Their values are printed as specified by
16614 @var{string}, exactly as if your program were to execute the C
16615 subroutine
16616 @c FIXME: the above implies that at least all ANSI C formats are
16617 @c supported, but it isn't true: %E and %G don't work (or so it seems).
16618 @c Either this is a bug, or the manual should document what formats are
16619 @c supported.
16620
16621 @smallexample
16622 printf (@var{string}, @var{expressions}@dots{});
16623 @end smallexample
16624
16625 For example, you can print two values in hex like this:
16626
16627 @smallexample
16628 printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo
16629 @end smallexample
16630
16631 The only backslash-escape sequences that you can use in the format
16632 string are the simple ones that consist of backslash followed by a
16633 letter.
16634 @end table
16635
16636 @node Interpreters
16637 @chapter Command Interpreters
16638 @cindex command interpreters
16639
16640 @value{GDBN} supports multiple command interpreters, and some command
16641 infrastructure to allow users or user interface writers to switch
16642 between interpreters or run commands in other interpreters.
16643
16644 @value{GDBN} currently supports two command interpreters, the console
16645 interpreter (sometimes called the command-line interpreter or @sc{cli})
16646 and the machine interface interpreter (or @sc{gdb/mi}). This manual
16647 describes both of these interfaces in great detail.
16648
16649 By default, @value{GDBN} will start with the console interpreter.
16650 However, the user may choose to start @value{GDBN} with another
16651 interpreter by specifying the @option{-i} or @option{--interpreter}
16652 startup options. Defined interpreters include:
16653
16654 @table @code
16655 @item console
16656 @cindex console interpreter
16657 The traditional console or command-line interpreter. This is the most often
16658 used interpreter with @value{GDBN}. With no interpreter specified at runtime,
16659 @value{GDBN} will use this interpreter.
16660
16661 @item mi
16662 @cindex mi interpreter
16663 The newest @sc{gdb/mi} interface (currently @code{mi2}). Used primarily
16664 by programs wishing to use @value{GDBN} as a backend for a debugger GUI
16665 or an IDE. For more information, see @ref{GDB/MI, ,The @sc{gdb/mi}
16666 Interface}.
16667
16668 @item mi2
16669 @cindex mi2 interpreter
16670 The current @sc{gdb/mi} interface.
16671
16672 @item mi1
16673 @cindex mi1 interpreter
16674 The @sc{gdb/mi} interface included in @value{GDBN} 5.1, 5.2, and 5.3.
16675
16676 @end table
16677
16678 @cindex invoke another interpreter
16679 The interpreter being used by @value{GDBN} may not be dynamically
16680 switched at runtime. Although possible, this could lead to a very
16681 precarious situation. Consider an IDE using @sc{gdb/mi}. If a user
16682 enters the command "interpreter-set console" in a console view,
16683 @value{GDBN} would switch to using the console interpreter, rendering
16684 the IDE inoperable!
16685
16686 @kindex interpreter-exec
16687 Although you may only choose a single interpreter at startup, you may execute
16688 commands in any interpreter from the current interpreter using the appropriate
16689 command. If you are running the console interpreter, simply use the
16690 @code{interpreter-exec} command:
16691
16692 @smallexample
16693 interpreter-exec mi "-data-list-register-names"
16694 @end smallexample
16695
16696 @sc{gdb/mi} has a similar command, although it is only available in versions of
16697 @value{GDBN} which support @sc{gdb/mi} version 2 (or greater).
16698
16699 @node TUI
16700 @chapter @value{GDBN} Text User Interface
16701 @cindex TUI
16702 @cindex Text User Interface
16703
16704 @menu
16705 * TUI Overview:: TUI overview
16706 * TUI Keys:: TUI key bindings
16707 * TUI Single Key Mode:: TUI single key mode
16708 * TUI Commands:: TUI specific commands
16709 * TUI Configuration:: TUI configuration variables
16710 @end menu
16711
16712 The @value{GDBN} Text User Interface, TUI in short, is a terminal
16713 interface which uses the @code{curses} library to show the source
16714 file, the assembly output, the program registers and @value{GDBN}
16715 commands in separate text windows.
16716
16717 The TUI is enabled by invoking @value{GDBN} using either
16718 @pindex gdbtui
16719 @samp{gdbtui} or @samp{gdb -tui}.
16720
16721 @node TUI Overview
16722 @section TUI overview
16723
16724 The TUI has two display modes that can be switched while
16725 @value{GDBN} runs:
16726
16727 @itemize @bullet
16728 @item
16729 A curses (or TUI) mode in which it displays several text
16730 windows on the terminal.
16731
16732 @item
16733 A standard mode which corresponds to the @value{GDBN} configured without
16734 the TUI.
16735 @end itemize
16736
16737 In the TUI mode, @value{GDBN} can display several text window
16738 on the terminal:
16739
16740 @table @emph
16741 @item command
16742 This window is the @value{GDBN} command window with the @value{GDBN}
16743 prompt and the @value{GDBN} outputs. The @value{GDBN} input is still
16744 managed using readline but through the TUI. The @emph{command}
16745 window is always visible.
16746
16747 @item source
16748 The source window shows the source file of the program. The current
16749 line as well as active breakpoints are displayed in this window.
16750
16751 @item assembly
16752 The assembly window shows the disassembly output of the program.
16753
16754 @item register
16755 This window shows the processor registers. It detects when
16756 a register is changed and when this is the case, registers that have
16757 changed are highlighted.
16758
16759 @end table
16760
16761 The source and assembly windows show the current program position
16762 by highlighting the current line and marking them with the @samp{>} marker.
16763 Breakpoints are also indicated with two markers. A first one
16764 indicates the breakpoint type:
16765
16766 @table @code
16767 @item B
16768 Breakpoint which was hit at least once.
16769
16770 @item b
16771 Breakpoint which was never hit.
16772
16773 @item H
16774 Hardware breakpoint which was hit at least once.
16775
16776 @item h
16777 Hardware breakpoint which was never hit.
16778
16779 @end table
16780
16781 The second marker indicates whether the breakpoint is enabled or not:
16782
16783 @table @code
16784 @item +
16785 Breakpoint is enabled.
16786
16787 @item -
16788 Breakpoint is disabled.
16789
16790 @end table
16791
16792 The source, assembly and register windows are attached to the thread
16793 and the frame position. They are updated when the current thread
16794 changes, when the frame changes or when the program counter changes.
16795 These three windows are arranged by the TUI according to several
16796 layouts. The layout defines which of these three windows are visible.
16797 The following layouts are available:
16798
16799 @itemize @bullet
16800 @item
16801 source
16802
16803 @item
16804 assembly
16805
16806 @item
16807 source and assembly
16808
16809 @item
16810 source and registers
16811
16812 @item
16813 assembly and registers
16814
16815 @end itemize
16816
16817 On top of the command window a status line gives various information
16818 concerning the current process begin debugged. The status line is
16819 updated when the information it shows changes. The following fields
16820 are displayed:
16821
16822 @table @emph
16823 @item target
16824 Indicates the current gdb target
16825 (@pxref{Targets, ,Specifying a Debugging Target}).
16826
16827 @item process
16828 Gives information about the current process or thread number.
16829 When no process is being debugged, this field is set to @code{No process}.
16830
16831 @item function
16832 Gives the current function name for the selected frame.
16833 The name is demangled if demangling is turned on (@pxref{Print Settings}).
16834 When there is no symbol corresponding to the current program counter
16835 the string @code{??} is displayed.
16836
16837 @item line
16838 Indicates the current line number for the selected frame.
16839 When the current line number is not known the string @code{??} is displayed.
16840
16841 @item pc
16842 Indicates the current program counter address.
16843
16844 @end table
16845
16846 @node TUI Keys
16847 @section TUI Key Bindings
16848 @cindex TUI key bindings
16849
16850 The TUI installs several key bindings in the readline keymaps
16851 (@pxref{Command Line Editing}).
16852 They allow to leave or enter in the TUI mode or they operate
16853 directly on the TUI layout and windows. The TUI also provides
16854 a @emph{SingleKey} keymap which binds several keys directly to
16855 @value{GDBN} commands. The following key bindings
16856 are installed for both TUI mode and the @value{GDBN} standard mode.
16857
16858 @table @kbd
16859 @kindex C-x C-a
16860 @item C-x C-a
16861 @kindex C-x a
16862 @itemx C-x a
16863 @kindex C-x A
16864 @itemx C-x A
16865 Enter or leave the TUI mode. When the TUI mode is left,
16866 the curses window management is left and @value{GDBN} operates using
16867 its standard mode writing on the terminal directly. When the TUI
16868 mode is entered, the control is given back to the curses windows.
16869 The screen is then refreshed.
16870
16871 @kindex C-x 1
16872 @item C-x 1
16873 Use a TUI layout with only one window. The layout will
16874 either be @samp{source} or @samp{assembly}. When the TUI mode
16875 is not active, it will switch to the TUI mode.
16876
16877 Think of this key binding as the Emacs @kbd{C-x 1} binding.
16878
16879 @kindex C-x 2
16880 @item C-x 2
16881 Use a TUI layout with at least two windows. When the current
16882 layout shows already two windows, a next layout with two windows is used.
16883 When a new layout is chosen, one window will always be common to the
16884 previous layout and the new one.
16885
16886 Think of it as the Emacs @kbd{C-x 2} binding.
16887
16888 @kindex C-x o
16889 @item C-x o
16890 Change the active window. The TUI associates several key bindings
16891 (like scrolling and arrow keys) to the active window. This command
16892 gives the focus to the next TUI window.
16893
16894 Think of it as the Emacs @kbd{C-x o} binding.
16895
16896 @kindex C-x s
16897 @item C-x s
16898 Use the TUI @emph{SingleKey} keymap that binds single key to gdb commands
16899 (@pxref{TUI Single Key Mode}).
16900
16901 @end table
16902
16903 The following key bindings are handled only by the TUI mode:
16904
16905 @table @key
16906 @kindex PgUp
16907 @item PgUp
16908 Scroll the active window one page up.
16909
16910 @kindex PgDn
16911 @item PgDn
16912 Scroll the active window one page down.
16913
16914 @kindex Up
16915 @item Up
16916 Scroll the active window one line up.
16917
16918 @kindex Down
16919 @item Down
16920 Scroll the active window one line down.
16921
16922 @kindex Left
16923 @item Left
16924 Scroll the active window one column left.
16925
16926 @kindex Right
16927 @item Right
16928 Scroll the active window one column right.
16929
16930 @kindex C-L
16931 @item C-L
16932 Refresh the screen.
16933
16934 @end table
16935
16936 In the TUI mode, the arrow keys are used by the active window
16937 for scrolling. This means they are available for readline when the
16938 active window is the command window. When the command window
16939 does not have the focus, it is necessary to use other readline
16940 key bindings such as @kbd{C-p}, @kbd{C-n}, @kbd{C-b} and @kbd{C-f}.
16941
16942 @node TUI Single Key Mode
16943 @section TUI Single Key Mode
16944 @cindex TUI single key mode
16945
16946 The TUI provides a @emph{SingleKey} mode in which it installs a particular
16947 key binding in the readline keymaps to connect single keys to
16948 some gdb commands.
16949
16950 @table @kbd
16951 @kindex c @r{(SingleKey TUI key)}
16952 @item c
16953 continue
16954
16955 @kindex d @r{(SingleKey TUI key)}
16956 @item d
16957 down
16958
16959 @kindex f @r{(SingleKey TUI key)}
16960 @item f
16961 finish
16962
16963 @kindex n @r{(SingleKey TUI key)}
16964 @item n
16965 next
16966
16967 @kindex q @r{(SingleKey TUI key)}
16968 @item q
16969 exit the @emph{SingleKey} mode.
16970
16971 @kindex r @r{(SingleKey TUI key)}
16972 @item r
16973 run
16974
16975 @kindex s @r{(SingleKey TUI key)}
16976 @item s
16977 step
16978
16979 @kindex u @r{(SingleKey TUI key)}
16980 @item u
16981 up
16982
16983 @kindex v @r{(SingleKey TUI key)}
16984 @item v
16985 info locals
16986
16987 @kindex w @r{(SingleKey TUI key)}
16988 @item w
16989 where
16990
16991 @end table
16992
16993 Other keys temporarily switch to the @value{GDBN} command prompt.
16994 The key that was pressed is inserted in the editing buffer so that
16995 it is possible to type most @value{GDBN} commands without interaction
16996 with the TUI @emph{SingleKey} mode. Once the command is entered the TUI
16997 @emph{SingleKey} mode is restored. The only way to permanently leave
16998 this mode is by typing @kbd{q} or @kbd{C-x s}.
16999
17000
17001 @node TUI Commands
17002 @section TUI specific commands
17003 @cindex TUI commands
17004
17005 The TUI has specific commands to control the text windows.
17006 These commands are always available, that is they do not depend on
17007 the current terminal mode in which @value{GDBN} runs. When @value{GDBN}
17008 is in the standard mode, using these commands will automatically switch
17009 in the TUI mode.
17010
17011 @table @code
17012 @item info win
17013 @kindex info win
17014 List and give the size of all displayed windows.
17015
17016 @item layout next
17017 @kindex layout
17018 Display the next layout.
17019
17020 @item layout prev
17021 Display the previous layout.
17022
17023 @item layout src
17024 Display the source window only.
17025
17026 @item layout asm
17027 Display the assembly window only.
17028
17029 @item layout split
17030 Display the source and assembly window.
17031
17032 @item layout regs
17033 Display the register window together with the source or assembly window.
17034
17035 @item focus next | prev | src | asm | regs | split
17036 @kindex focus
17037 Set the focus to the named window.
17038 This command allows to change the active window so that scrolling keys
17039 can be affected to another window.
17040
17041 @item refresh
17042 @kindex refresh
17043 Refresh the screen. This is similar to typing @kbd{C-L}.
17044
17045 @item tui reg float
17046 @kindex tui reg
17047 Show the floating point registers in the register window.
17048
17049 @item tui reg general
17050 Show the general registers in the register window.
17051
17052 @item tui reg next
17053 Show the next register group. The list of register groups as well as
17054 their order is target specific. The predefined register groups are the
17055 following: @code{general}, @code{float}, @code{system}, @code{vector},
17056 @code{all}, @code{save}, @code{restore}.
17057
17058 @item tui reg system
17059 Show the system registers in the register window.
17060
17061 @item update
17062 @kindex update
17063 Update the source window and the current execution point.
17064
17065 @item winheight @var{name} +@var{count}
17066 @itemx winheight @var{name} -@var{count}
17067 @kindex winheight
17068 Change the height of the window @var{name} by @var{count}
17069 lines. Positive counts increase the height, while negative counts
17070 decrease it.
17071
17072 @item tabset
17073 @kindex tabset @var{nchars}
17074 Set the width of tab stops to be @var{nchars} characters.
17075
17076 @end table
17077
17078 @node TUI Configuration
17079 @section TUI configuration variables
17080 @cindex TUI configuration variables
17081
17082 The TUI has several configuration variables that control the
17083 appearance of windows on the terminal.
17084
17085 @table @code
17086 @item set tui border-kind @var{kind}
17087 @kindex set tui border-kind
17088 Select the border appearance for the source, assembly and register windows.
17089 The possible values are the following:
17090 @table @code
17091 @item space
17092 Use a space character to draw the border.
17093
17094 @item ascii
17095 Use ascii characters + - and | to draw the border.
17096
17097 @item acs
17098 Use the Alternate Character Set to draw the border. The border is
17099 drawn using character line graphics if the terminal supports them.
17100
17101 @end table
17102
17103 @item set tui active-border-mode @var{mode}
17104 @kindex set tui active-border-mode
17105 Select the attributes to display the border of the active window.
17106 The possible values are @code{normal}, @code{standout}, @code{reverse},
17107 @code{half}, @code{half-standout}, @code{bold} and @code{bold-standout}.
17108
17109 @item set tui border-mode @var{mode}
17110 @kindex set tui border-mode
17111 Select the attributes to display the border of other windows.
17112 The @var{mode} can be one of the following:
17113 @table @code
17114 @item normal
17115 Use normal attributes to display the border.
17116
17117 @item standout
17118 Use standout mode.
17119
17120 @item reverse
17121 Use reverse video mode.
17122
17123 @item half
17124 Use half bright mode.
17125
17126 @item half-standout
17127 Use half bright and standout mode.
17128
17129 @item bold
17130 Use extra bright or bold mode.
17131
17132 @item bold-standout
17133 Use extra bright or bold and standout mode.
17134
17135 @end table
17136
17137 @end table
17138
17139 @node Emacs
17140 @chapter Using @value{GDBN} under @sc{gnu} Emacs
17141
17142 @cindex Emacs
17143 @cindex @sc{gnu} Emacs
17144 A special interface allows you to use @sc{gnu} Emacs to view (and
17145 edit) the source files for the program you are debugging with
17146 @value{GDBN}.
17147
17148 To use this interface, use the command @kbd{M-x gdb} in Emacs. Give the
17149 executable file you want to debug as an argument. This command starts
17150 @value{GDBN} as a subprocess of Emacs, with input and output through a newly
17151 created Emacs buffer.
17152 @c (Do not use the @code{-tui} option to run @value{GDBN} from Emacs.)
17153
17154 Using @value{GDBN} under Emacs is just like using @value{GDBN} normally except for two
17155 things:
17156
17157 @itemize @bullet
17158 @item
17159 All ``terminal'' input and output goes through the Emacs buffer.
17160 @end itemize
17161
17162 This applies both to @value{GDBN} commands and their output, and to the input
17163 and output done by the program you are debugging.
17164
17165 This is useful because it means that you can copy the text of previous
17166 commands and input them again; you can even use parts of the output
17167 in this way.
17168
17169 All the facilities of Emacs' Shell mode are available for interacting
17170 with your program. In particular, you can send signals the usual
17171 way---for example, @kbd{C-c C-c} for an interrupt, @kbd{C-c C-z} for a
17172 stop.
17173
17174 @itemize @bullet
17175 @item
17176 @value{GDBN} displays source code through Emacs.
17177 @end itemize
17178
17179 Each time @value{GDBN} displays a stack frame, Emacs automatically finds the
17180 source file for that frame and puts an arrow (@samp{=>}) at the
17181 left margin of the current line. Emacs uses a separate buffer for
17182 source display, and splits the screen to show both your @value{GDBN} session
17183 and the source.
17184
17185 Explicit @value{GDBN} @code{list} or search commands still produce output as
17186 usual, but you probably have no reason to use them from Emacs.
17187
17188 If you specify an absolute file name when prompted for the @kbd{M-x
17189 gdb} argument, then Emacs sets your current working directory to where
17190 your program resides. If you only specify the file name, then Emacs
17191 sets your current working directory to to the directory associated
17192 with the previous buffer. In this case, @value{GDBN} may find your
17193 program by searching your environment's @code{PATH} variable, but on
17194 some operating systems it might not find the source. So, although the
17195 @value{GDBN} input and output session proceeds normally, the auxiliary
17196 buffer does not display the current source and line of execution.
17197
17198 The initial working directory of @value{GDBN} is printed on the top
17199 line of the @value{GDBN} I/O buffer and this serves as a default for
17200 the commands that specify files for @value{GDBN} to operate
17201 on. @xref{Files, ,Commands to specify files}.
17202
17203 By default, @kbd{M-x gdb} calls the program called @file{gdb}. If you
17204 need to call @value{GDBN} by a different name (for example, if you
17205 keep several configurations around, with different names) you can
17206 customize the Emacs variable @code{gud-gdb-command-name} to run the
17207 one you want.
17208
17209 In the @value{GDBN} I/O buffer, you can use these special Emacs commands in
17210 addition to the standard Shell mode commands:
17211
17212 @table @kbd
17213 @item C-h m
17214 Describe the features of Emacs' @value{GDBN} Mode.
17215
17216 @item C-c C-s
17217 Execute to another source line, like the @value{GDBN} @code{step} command; also
17218 update the display window to show the current file and location.
17219
17220 @item C-c C-n
17221 Execute to next source line in this function, skipping all function
17222 calls, like the @value{GDBN} @code{next} command. Then update the display window
17223 to show the current file and location.
17224
17225 @item C-c C-i
17226 Execute one instruction, like the @value{GDBN} @code{stepi} command; update
17227 display window accordingly.
17228
17229 @item C-c C-f
17230 Execute until exit from the selected stack frame, like the @value{GDBN}
17231 @code{finish} command.
17232
17233 @item C-c C-r
17234 Continue execution of your program, like the @value{GDBN} @code{continue}
17235 command.
17236
17237 @item C-c <
17238 Go up the number of frames indicated by the numeric argument
17239 (@pxref{Arguments, , Numeric Arguments, Emacs, The @sc{gnu} Emacs Manual}),
17240 like the @value{GDBN} @code{up} command.
17241
17242 @item C-c >
17243 Go down the number of frames indicated by the numeric argument, like the
17244 @value{GDBN} @code{down} command.
17245 @end table
17246
17247 In any source file, the Emacs command @kbd{C-x @key{SPC}} (@code{gud-break})
17248 tells @value{GDBN} to set a breakpoint on the source line point is on.
17249
17250 If you type @kbd{M-x speedbar}, then Emacs displays a separate frame which
17251 shows a backtrace when the @value{GDBN} I/O buffer is current. Move
17252 point to any frame in the stack and type @key{RET} to make it become the
17253 current frame and display the associated source in the source buffer.
17254 Alternatively, click @kbd{Mouse-2} to make the selected frame become the
17255 current one.
17256
17257 If you accidentally delete the source-display buffer, an easy way to get
17258 it back is to type the command @code{f} in the @value{GDBN} buffer, to
17259 request a frame display; when you run under Emacs, this recreates
17260 the source buffer if necessary to show you the context of the current
17261 frame.
17262
17263 The source files displayed in Emacs are in ordinary Emacs buffers
17264 which are visiting the source files in the usual way. You can edit
17265 the files with these buffers if you wish; but keep in mind that @value{GDBN}
17266 communicates with Emacs in terms of line numbers. If you add or
17267 delete lines from the text, the line numbers that @value{GDBN} knows cease
17268 to correspond properly with the code.
17269
17270 The description given here is for GNU Emacs version 21.3 and a more
17271 detailed description of its interaction with @value{GDBN} is given in
17272 the Emacs manual (@pxref{Debuggers,,, Emacs, The @sc{gnu} Emacs Manual}).
17273
17274 @c The following dropped because Epoch is nonstandard. Reactivate
17275 @c if/when v19 does something similar. ---doc@cygnus.com 19dec1990
17276 @ignore
17277 @kindex Emacs Epoch environment
17278 @kindex Epoch
17279 @kindex inspect
17280
17281 Version 18 of @sc{gnu} Emacs has a built-in window system
17282 called the @code{epoch}
17283 environment. Users of this environment can use a new command,
17284 @code{inspect} which performs identically to @code{print} except that
17285 each value is printed in its own window.
17286 @end ignore
17287
17288
17289 @node GDB/MI
17290 @chapter The @sc{gdb/mi} Interface
17291
17292 @unnumberedsec Function and Purpose
17293
17294 @cindex @sc{gdb/mi}, its purpose
17295 @sc{gdb/mi} is a line based machine oriented text interface to
17296 @value{GDBN} and is activated by specifying using the
17297 @option{--interpreter} command line option (@pxref{Mode Options}). It
17298 is specifically intended to support the development of systems which
17299 use the debugger as just one small component of a larger system.
17300
17301 This chapter is a specification of the @sc{gdb/mi} interface. It is written
17302 in the form of a reference manual.
17303
17304 Note that @sc{gdb/mi} is still under construction, so some of the
17305 features described below are incomplete and subject to change
17306 (@pxref{GDB/MI Development and Front Ends, , @sc{gdb/mi} Development and Front Ends}).
17307
17308 @unnumberedsec Notation and Terminology
17309
17310 @cindex notational conventions, for @sc{gdb/mi}
17311 This chapter uses the following notation:
17312
17313 @itemize @bullet
17314 @item
17315 @code{|} separates two alternatives.
17316
17317 @item
17318 @code{[ @var{something} ]} indicates that @var{something} is optional:
17319 it may or may not be given.
17320
17321 @item
17322 @code{( @var{group} )*} means that @var{group} inside the parentheses
17323 may repeat zero or more times.
17324
17325 @item
17326 @code{( @var{group} )+} means that @var{group} inside the parentheses
17327 may repeat one or more times.
17328
17329 @item
17330 @code{"@var{string}"} means a literal @var{string}.
17331 @end itemize
17332
17333 @ignore
17334 @heading Dependencies
17335 @end ignore
17336
17337 @menu
17338 * GDB/MI Command Syntax::
17339 * GDB/MI Compatibility with CLI::
17340 * GDB/MI Development and Front Ends::
17341 * GDB/MI Output Records::
17342 * GDB/MI Simple Examples::
17343 * GDB/MI Command Description Format::
17344 * GDB/MI Breakpoint Commands::
17345 * GDB/MI Program Context::
17346 * GDB/MI Thread Commands::
17347 * GDB/MI Program Execution::
17348 * GDB/MI Stack Manipulation::
17349 * GDB/MI Variable Objects::
17350 * GDB/MI Data Manipulation::
17351 * GDB/MI Tracepoint Commands::
17352 * GDB/MI Symbol Query::
17353 * GDB/MI File Commands::
17354 @ignore
17355 * GDB/MI Kod Commands::
17356 * GDB/MI Memory Overlay Commands::
17357 * GDB/MI Signal Handling Commands::
17358 @end ignore
17359 * GDB/MI Target Manipulation::
17360 * GDB/MI Miscellaneous Commands::
17361 @end menu
17362
17363 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
17364 @node GDB/MI Command Syntax
17365 @section @sc{gdb/mi} Command Syntax
17366
17367 @menu
17368 * GDB/MI Input Syntax::
17369 * GDB/MI Output Syntax::
17370 @end menu
17371
17372 @node GDB/MI Input Syntax
17373 @subsection @sc{gdb/mi} Input Syntax
17374
17375 @cindex input syntax for @sc{gdb/mi}
17376 @cindex @sc{gdb/mi}, input syntax
17377 @table @code
17378 @item @var{command} @expansion{}
17379 @code{@var{cli-command} | @var{mi-command}}
17380
17381 @item @var{cli-command} @expansion{}
17382 @code{[ @var{token} ] @var{cli-command} @var{nl}}, where
17383 @var{cli-command} is any existing @value{GDBN} CLI command.
17384
17385 @item @var{mi-command} @expansion{}
17386 @code{[ @var{token} ] "-" @var{operation} ( " " @var{option} )*
17387 @code{[} " --" @code{]} ( " " @var{parameter} )* @var{nl}}
17388
17389 @item @var{token} @expansion{}
17390 "any sequence of digits"
17391
17392 @item @var{option} @expansion{}
17393 @code{"-" @var{parameter} [ " " @var{parameter} ]}
17394
17395 @item @var{parameter} @expansion{}
17396 @code{@var{non-blank-sequence} | @var{c-string}}
17397
17398 @item @var{operation} @expansion{}
17399 @emph{any of the operations described in this chapter}
17400
17401 @item @var{non-blank-sequence} @expansion{}
17402 @emph{anything, provided it doesn't contain special characters such as
17403 "-", @var{nl}, """ and of course " "}
17404
17405 @item @var{c-string} @expansion{}
17406 @code{""" @var{seven-bit-iso-c-string-content} """}
17407
17408 @item @var{nl} @expansion{}
17409 @code{CR | CR-LF}
17410 @end table
17411
17412 @noindent
17413 Notes:
17414
17415 @itemize @bullet
17416 @item
17417 The CLI commands are still handled by the @sc{mi} interpreter; their
17418 output is described below.
17419
17420 @item
17421 The @code{@var{token}}, when present, is passed back when the command
17422 finishes.
17423
17424 @item
17425 Some @sc{mi} commands accept optional arguments as part of the parameter
17426 list. Each option is identified by a leading @samp{-} (dash) and may be
17427 followed by an optional argument parameter. Options occur first in the
17428 parameter list and can be delimited from normal parameters using
17429 @samp{--} (this is useful when some parameters begin with a dash).
17430 @end itemize
17431
17432 Pragmatics:
17433
17434 @itemize @bullet
17435 @item
17436 We want easy access to the existing CLI syntax (for debugging).
17437
17438 @item
17439 We want it to be easy to spot a @sc{mi} operation.
17440 @end itemize
17441
17442 @node GDB/MI Output Syntax
17443 @subsection @sc{gdb/mi} Output Syntax
17444
17445 @cindex output syntax of @sc{gdb/mi}
17446 @cindex @sc{gdb/mi}, output syntax
17447 The output from @sc{gdb/mi} consists of zero or more out-of-band records
17448 followed, optionally, by a single result record. This result record
17449 is for the most recent command. The sequence of output records is
17450 terminated by @samp{(gdb)}.
17451
17452 If an input command was prefixed with a @code{@var{token}} then the
17453 corresponding output for that command will also be prefixed by that same
17454 @var{token}.
17455
17456 @table @code
17457 @item @var{output} @expansion{}
17458 @code{( @var{out-of-band-record} )* [ @var{result-record} ] "(gdb)" @var{nl}}
17459
17460 @item @var{result-record} @expansion{}
17461 @code{ [ @var{token} ] "^" @var{result-class} ( "," @var{result} )* @var{nl}}
17462
17463 @item @var{out-of-band-record} @expansion{}
17464 @code{@var{async-record} | @var{stream-record}}
17465
17466 @item @var{async-record} @expansion{}
17467 @code{@var{exec-async-output} | @var{status-async-output} | @var{notify-async-output}}
17468
17469 @item @var{exec-async-output} @expansion{}
17470 @code{[ @var{token} ] "*" @var{async-output}}
17471
17472 @item @var{status-async-output} @expansion{}
17473 @code{[ @var{token} ] "+" @var{async-output}}
17474
17475 @item @var{notify-async-output} @expansion{}
17476 @code{[ @var{token} ] "=" @var{async-output}}
17477
17478 @item @var{async-output} @expansion{}
17479 @code{@var{async-class} ( "," @var{result} )* @var{nl}}
17480
17481 @item @var{result-class} @expansion{}
17482 @code{"done" | "running" | "connected" | "error" | "exit"}
17483
17484 @item @var{async-class} @expansion{}
17485 @code{"stopped" | @var{others}} (where @var{others} will be added
17486 depending on the needs---this is still in development).
17487
17488 @item @var{result} @expansion{}
17489 @code{ @var{variable} "=" @var{value}}
17490
17491 @item @var{variable} @expansion{}
17492 @code{ @var{string} }
17493
17494 @item @var{value} @expansion{}
17495 @code{ @var{const} | @var{tuple} | @var{list} }
17496
17497 @item @var{const} @expansion{}
17498 @code{@var{c-string}}
17499
17500 @item @var{tuple} @expansion{}
17501 @code{ "@{@}" | "@{" @var{result} ( "," @var{result} )* "@}" }
17502
17503 @item @var{list} @expansion{}
17504 @code{ "[]" | "[" @var{value} ( "," @var{value} )* "]" | "["
17505 @var{result} ( "," @var{result} )* "]" }
17506
17507 @item @var{stream-record} @expansion{}
17508 @code{@var{console-stream-output} | @var{target-stream-output} | @var{log-stream-output}}
17509
17510 @item @var{console-stream-output} @expansion{}
17511 @code{"~" @var{c-string}}
17512
17513 @item @var{target-stream-output} @expansion{}
17514 @code{"@@" @var{c-string}}
17515
17516 @item @var{log-stream-output} @expansion{}
17517 @code{"&" @var{c-string}}
17518
17519 @item @var{nl} @expansion{}
17520 @code{CR | CR-LF}
17521
17522 @item @var{token} @expansion{}
17523 @emph{any sequence of digits}.
17524 @end table
17525
17526 @noindent
17527 Notes:
17528
17529 @itemize @bullet
17530 @item
17531 All output sequences end in a single line containing a period.
17532
17533 @item
17534 The @code{@var{token}} is from the corresponding request. If an execution
17535 command is interrupted by the @samp{-exec-interrupt} command, the
17536 @var{token} associated with the @samp{*stopped} message is the one of the
17537 original execution command, not the one of the interrupt command.
17538
17539 @item
17540 @cindex status output in @sc{gdb/mi}
17541 @var{status-async-output} contains on-going status information about the
17542 progress of a slow operation. It can be discarded. All status output is
17543 prefixed by @samp{+}.
17544
17545 @item
17546 @cindex async output in @sc{gdb/mi}
17547 @var{exec-async-output} contains asynchronous state change on the target
17548 (stopped, started, disappeared). All async output is prefixed by
17549 @samp{*}.
17550
17551 @item
17552 @cindex notify output in @sc{gdb/mi}
17553 @var{notify-async-output} contains supplementary information that the
17554 client should handle (e.g., a new breakpoint information). All notify
17555 output is prefixed by @samp{=}.
17556
17557 @item
17558 @cindex console output in @sc{gdb/mi}
17559 @var{console-stream-output} is output that should be displayed as is in the
17560 console. It is the textual response to a CLI command. All the console
17561 output is prefixed by @samp{~}.
17562
17563 @item
17564 @cindex target output in @sc{gdb/mi}
17565 @var{target-stream-output} is the output produced by the target program.
17566 All the target output is prefixed by @samp{@@}.
17567
17568 @item
17569 @cindex log output in @sc{gdb/mi}
17570 @var{log-stream-output} is output text coming from @value{GDBN}'s internals, for
17571 instance messages that should be displayed as part of an error log. All
17572 the log output is prefixed by @samp{&}.
17573
17574 @item
17575 @cindex list output in @sc{gdb/mi}
17576 New @sc{gdb/mi} commands should only output @var{lists} containing
17577 @var{values}.
17578
17579
17580 @end itemize
17581
17582 @xref{GDB/MI Stream Records, , @sc{gdb/mi} Stream Records}, for more
17583 details about the various output records.
17584
17585 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
17586 @node GDB/MI Compatibility with CLI
17587 @section @sc{gdb/mi} Compatibility with CLI
17588
17589 @cindex compatibility, @sc{gdb/mi} and CLI
17590 @cindex @sc{gdb/mi}, compatibility with CLI
17591
17592 For the developers convenience CLI commands can be entered directly,
17593 but there may be some unexpected behaviour. For example, commands
17594 that query the user will behave as if the user replied yes, breakpoint
17595 command lists are not executed and some CLI commands, such as
17596 @code{if}, @code{when} and @code{define}, prompt for further input with
17597 @samp{>}, which is not valid MI output.
17598
17599 This feature may be removed at some stage in the future and it is
17600 recommended that front ends use the @code{-interpreter-exec} command
17601 (@pxref{-interpreter-exec}).
17602
17603 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
17604 @node GDB/MI Development and Front Ends
17605 @section @sc{gdb/mi} Development and Front Ends
17606 @cindex @sc{gdb/mi} development
17607
17608 The application which takes the MI output and presents the state of the
17609 program being debugged to the user is called a @dfn{front end}.
17610
17611 Although @sc{gdb/mi} is still incomplete, it is currently being used
17612 by a variety of front ends to @value{GDBN}. This makes it difficult
17613 to introduce new functionality without breaking existing usage. This
17614 section tries to minimize the problems by describing how the protocol
17615 might change.
17616
17617 Some changes in MI need not break a carefully designed front end, and
17618 for these the MI version will remain unchanged. The following is a
17619 list of changes that may occur within one level, so front ends should
17620 parse MI output in a way that can handle them:
17621
17622 @itemize @bullet
17623 @item
17624 New MI commands may be added.
17625
17626 @item
17627 New fields may be added to the output of any MI command.
17628
17629 @c The format of field's content e.g type prefix, may change so parse it
17630 @c at your own risk. Yes, in general?
17631
17632 @c The order of fields may change? Shouldn't really matter but it might
17633 @c resolve inconsistencies.
17634 @end itemize
17635
17636 If the changes are likely to break front ends, the MI version level
17637 will be increased by one. This will allow the front end to parse the
17638 output according to the MI version. Apart from mi0, new versions of
17639 @value{GDBN} will not support old versions of MI and it will be the
17640 responsibility of the front end to work with the new one.
17641
17642 @c Starting with mi3, add a new command -mi-version that prints the MI
17643 @c version?
17644
17645 The best way to avoid unexpected changes in MI that might break your front
17646 end is to make your project known to @value{GDBN} developers and
17647 follow development on @email{gdb@@sourceware.org} and
17648 @email{gdb-patches@@sourceware.org}. There is also the mailing list
17649 @email{dmi-discuss@@lists.freestandards.org}, hosted by the Free Standards
17650 Group, which has the aim of creating a a more general MI protocol
17651 called Debugger Machine Interface (DMI) that will become a standard
17652 for all debuggers, not just @value{GDBN}.
17653 @cindex mailing lists
17654
17655 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
17656 @node GDB/MI Output Records
17657 @section @sc{gdb/mi} Output Records
17658
17659 @menu
17660 * GDB/MI Result Records::
17661 * GDB/MI Stream Records::
17662 * GDB/MI Out-of-band Records::
17663 @end menu
17664
17665 @node GDB/MI Result Records
17666 @subsection @sc{gdb/mi} Result Records
17667
17668 @cindex result records in @sc{gdb/mi}
17669 @cindex @sc{gdb/mi}, result records
17670 In addition to a number of out-of-band notifications, the response to a
17671 @sc{gdb/mi} command includes one of the following result indications:
17672
17673 @table @code
17674 @findex ^done
17675 @item "^done" [ "," @var{results} ]
17676 The synchronous operation was successful, @code{@var{results}} are the return
17677 values.
17678
17679 @item "^running"
17680 @findex ^running
17681 @c Is this one correct? Should it be an out-of-band notification?
17682 The asynchronous operation was successfully started. The target is
17683 running.
17684
17685 @item "^connected"
17686 @findex ^connected
17687 GDB has connected to a remote target.
17688
17689 @item "^error" "," @var{c-string}
17690 @findex ^error
17691 The operation failed. The @code{@var{c-string}} contains the corresponding
17692 error message.
17693
17694 @item "^exit"
17695 @findex ^exit
17696 GDB has terminated.
17697
17698 @end table
17699
17700 @node GDB/MI Stream Records
17701 @subsection @sc{gdb/mi} Stream Records
17702
17703 @cindex @sc{gdb/mi}, stream records
17704 @cindex stream records in @sc{gdb/mi}
17705 @value{GDBN} internally maintains a number of output streams: the console, the
17706 target, and the log. The output intended for each of these streams is
17707 funneled through the @sc{gdb/mi} interface using @dfn{stream records}.
17708
17709 Each stream record begins with a unique @dfn{prefix character} which
17710 identifies its stream (@pxref{GDB/MI Output Syntax, , @sc{gdb/mi} Output
17711 Syntax}). In addition to the prefix, each stream record contains a
17712 @code{@var{string-output}}. This is either raw text (with an implicit new
17713 line) or a quoted C string (which does not contain an implicit newline).
17714
17715 @table @code
17716 @item "~" @var{string-output}
17717 The console output stream contains text that should be displayed in the
17718 CLI console window. It contains the textual responses to CLI commands.
17719
17720 @item "@@" @var{string-output}
17721 The target output stream contains any textual output from the running
17722 target. This is only present when GDB's event loop is truly
17723 asynchronous, which is currently only the case for remote targets.
17724
17725 @item "&" @var{string-output}
17726 The log stream contains debugging messages being produced by @value{GDBN}'s
17727 internals.
17728 @end table
17729
17730 @node GDB/MI Out-of-band Records
17731 @subsection @sc{gdb/mi} Out-of-band Records
17732
17733 @cindex out-of-band records in @sc{gdb/mi}
17734 @cindex @sc{gdb/mi}, out-of-band records
17735 @dfn{Out-of-band} records are used to notify the @sc{gdb/mi} client of
17736 additional changes that have occurred. Those changes can either be a
17737 consequence of @sc{gdb/mi} (e.g., a breakpoint modified) or a result of
17738 target activity (e.g., target stopped).
17739
17740 The following is a preliminary list of possible out-of-band records.
17741 In particular, the @var{exec-async-output} records.
17742
17743 @table @code
17744 @item *stopped,reason="@var{reason}"
17745 @end table
17746
17747 @var{reason} can be one of the following:
17748
17749 @table @code
17750 @item breakpoint-hit
17751 A breakpoint was reached.
17752 @item watchpoint-trigger
17753 A watchpoint was triggered.
17754 @item read-watchpoint-trigger
17755 A read watchpoint was triggered.
17756 @item access-watchpoint-trigger
17757 An access watchpoint was triggered.
17758 @item function-finished
17759 An -exec-finish or similar CLI command was accomplished.
17760 @item location-reached
17761 An -exec-until or similar CLI command was accomplished.
17762 @item watchpoint-scope
17763 A watchpoint has gone out of scope.
17764 @item end-stepping-range
17765 An -exec-next, -exec-next-instruction, -exec-step, -exec-step-instruction or
17766 similar CLI command was accomplished.
17767 @item exited-signalled
17768 The inferior exited because of a signal.
17769 @item exited
17770 The inferior exited.
17771 @item exited-normally
17772 The inferior exited normally.
17773 @item signal-received
17774 A signal was received by the inferior.
17775 @end table
17776
17777
17778 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
17779 @node GDB/MI Simple Examples
17780 @section Simple Examples of @sc{gdb/mi} Interaction
17781 @cindex @sc{gdb/mi}, simple examples
17782
17783 This subsection presents several simple examples of interaction using
17784 the @sc{gdb/mi} interface. In these examples, @samp{->} means that the
17785 following line is passed to @sc{gdb/mi} as input, while @samp{<-} means
17786 the output received from @sc{gdb/mi}.
17787
17788 Note the the line breaks shown in the examples are here only for
17789 readability, they don't appear in the real output.
17790
17791 @subheading Setting a breakpoint
17792
17793 Setting a breakpoint generates synchronous output which contains detailed
17794 information of the breakpoint.
17795
17796 @smallexample
17797 -> -break-insert main
17798 <- ^done,bkpt=@{number="1",type="breakpoint",disp="keep",
17799 enabled="y",addr="0x08048564",func="main",file="myprog.c",
17800 fullname="/home/nickrob/myprog.c",line="68",times="0"@}
17801 <- (gdb)
17802 @end smallexample
17803
17804 @subheading Program Execution
17805
17806 Program execution generates asynchronous records and MI gives the
17807 reason that execution stopped.
17808
17809 @smallexample
17810 -> -exec-run
17811 <- ^running
17812 <- (gdb)
17813 <- *stopped,reason="breakpoint-hit",bkptno="1",thread-id="0",
17814 frame=@{addr="0x08048564",func="main",
17815 args=[@{name="argc",value="1"@},@{name="argv",value="0xbfc4d4d4"@}],
17816 file="myprog.c",fullname="/home/nickrob/myprog.c",line="68"@}
17817 <- (gdb)
17818 -> -exec-continue
17819 <- ^running
17820 <- (gdb)
17821 <- *stopped,reason="exited-normally"
17822 <- (gdb)
17823 @end smallexample
17824
17825 @subheading Quitting GDB
17826
17827 Quitting GDB just prints the result class @samp{^exit}.
17828
17829 @smallexample
17830 -> (gdb)
17831 <- -gdb-exit
17832 <- ^exit
17833 @end smallexample
17834
17835 @subheading A Bad Command
17836
17837 Here's what happens if you pass a non-existent command:
17838
17839 @smallexample
17840 -> -rubbish
17841 <- ^error,msg="Undefined MI command: rubbish"
17842 <- (gdb)
17843 @end smallexample
17844
17845
17846 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
17847 @node GDB/MI Command Description Format
17848 @section @sc{gdb/mi} Command Description Format
17849
17850 The remaining sections describe blocks of commands. Each block of
17851 commands is laid out in a fashion similar to this section.
17852
17853 @subheading Motivation
17854
17855 The motivation for this collection of commands.
17856
17857 @subheading Introduction
17858
17859 A brief introduction to this collection of commands as a whole.
17860
17861 @subheading Commands
17862
17863 For each command in the block, the following is described:
17864
17865 @subsubheading Synopsis
17866
17867 @smallexample
17868 -command @var{args}@dots{}
17869 @end smallexample
17870
17871 @subsubheading Result
17872
17873 @subsubheading @value{GDBN} Command
17874
17875 The corresponding @value{GDBN} CLI command(s), if any.
17876
17877 @subsubheading Example
17878
17879 Example(s) formatted for readability. Some of the described commands have
17880 not been implemented yet and these are labeled N.A.@: (not available).
17881
17882
17883 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
17884 @node GDB/MI Breakpoint Commands
17885 @section @sc{gdb/mi} Breakpoint Commands
17886
17887 @cindex breakpoint commands for @sc{gdb/mi}
17888 @cindex @sc{gdb/mi}, breakpoint commands
17889 This section documents @sc{gdb/mi} commands for manipulating
17890 breakpoints.
17891
17892 @subheading The @code{-break-after} Command
17893 @findex -break-after
17894
17895 @subsubheading Synopsis
17896
17897 @smallexample
17898 -break-after @var{number} @var{count}
17899 @end smallexample
17900
17901 The breakpoint number @var{number} is not in effect until it has been
17902 hit @var{count} times. To see how this is reflected in the output of
17903 the @samp{-break-list} command, see the description of the
17904 @samp{-break-list} command below.
17905
17906 @subsubheading @value{GDBN} Command
17907
17908 The corresponding @value{GDBN} command is @samp{ignore}.
17909
17910 @subsubheading Example
17911
17912 @smallexample
17913 (gdb)
17914 -break-insert main
17915 ^done,bkpt=@{number="1",addr="0x000100d0",file="hello.c",
17916 fullname="/home/foo/hello.c",line="5",times="0"@}
17917 (gdb)
17918 -break-after 1 3
17919 ~
17920 ^done
17921 (gdb)
17922 -break-list
17923 ^done,BreakpointTable=@{nr_rows="1",nr_cols="6",
17924 hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
17925 @{width="14",alignment="-1",col_name="type",colhdr="Type"@},
17926 @{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
17927 @{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
17928 @{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
17929 @{width="40",alignment="2",col_name="what",colhdr="What"@}],
17930 body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
17931 addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
17932 line="5",times="0",ignore="3"@}]@}
17933 (gdb)
17934 @end smallexample
17935
17936 @ignore
17937 @subheading The @code{-break-catch} Command
17938 @findex -break-catch
17939
17940 @subheading The @code{-break-commands} Command
17941 @findex -break-commands
17942 @end ignore
17943
17944
17945 @subheading The @code{-break-condition} Command
17946 @findex -break-condition
17947
17948 @subsubheading Synopsis
17949
17950 @smallexample
17951 -break-condition @var{number} @var{expr}
17952 @end smallexample
17953
17954 Breakpoint @var{number} will stop the program only if the condition in
17955 @var{expr} is true. The condition becomes part of the
17956 @samp{-break-list} output (see the description of the @samp{-break-list}
17957 command below).
17958
17959 @subsubheading @value{GDBN} Command
17960
17961 The corresponding @value{GDBN} command is @samp{condition}.
17962
17963 @subsubheading Example
17964
17965 @smallexample
17966 (gdb)
17967 -break-condition 1 1
17968 ^done
17969 (gdb)
17970 -break-list
17971 ^done,BreakpointTable=@{nr_rows="1",nr_cols="6",
17972 hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
17973 @{width="14",alignment="-1",col_name="type",colhdr="Type"@},
17974 @{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
17975 @{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
17976 @{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
17977 @{width="40",alignment="2",col_name="what",colhdr="What"@}],
17978 body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
17979 addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
17980 line="5",cond="1",times="0",ignore="3"@}]@}
17981 (gdb)
17982 @end smallexample
17983
17984 @subheading The @code{-break-delete} Command
17985 @findex -break-delete
17986
17987 @subsubheading Synopsis
17988
17989 @smallexample
17990 -break-delete ( @var{breakpoint} )+
17991 @end smallexample
17992
17993 Delete the breakpoint(s) whose number(s) are specified in the argument
17994 list. This is obviously reflected in the breakpoint list.
17995
17996 @subsubheading @value{GDBN} command
17997
17998 The corresponding @value{GDBN} command is @samp{delete}.
17999
18000 @subsubheading Example
18001
18002 @smallexample
18003 (gdb)
18004 -break-delete 1
18005 ^done
18006 (gdb)
18007 -break-list
18008 ^done,BreakpointTable=@{nr_rows="0",nr_cols="6",
18009 hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
18010 @{width="14",alignment="-1",col_name="type",colhdr="Type"@},
18011 @{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
18012 @{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
18013 @{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
18014 @{width="40",alignment="2",col_name="what",colhdr="What"@}],
18015 body=[]@}
18016 (gdb)
18017 @end smallexample
18018
18019 @subheading The @code{-break-disable} Command
18020 @findex -break-disable
18021
18022 @subsubheading Synopsis
18023
18024 @smallexample
18025 -break-disable ( @var{breakpoint} )+
18026 @end smallexample
18027
18028 Disable the named @var{breakpoint}(s). The field @samp{enabled} in the
18029 break list is now set to @samp{n} for the named @var{breakpoint}(s).
18030
18031 @subsubheading @value{GDBN} Command
18032
18033 The corresponding @value{GDBN} command is @samp{disable}.
18034
18035 @subsubheading Example
18036
18037 @smallexample
18038 (gdb)
18039 -break-disable 2
18040 ^done
18041 (gdb)
18042 -break-list
18043 ^done,BreakpointTable=@{nr_rows="1",nr_cols="6",
18044 hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
18045 @{width="14",alignment="-1",col_name="type",colhdr="Type"@},
18046 @{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
18047 @{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
18048 @{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
18049 @{width="40",alignment="2",col_name="what",colhdr="What"@}],
18050 body=[bkpt=@{number="2",type="breakpoint",disp="keep",enabled="n",
18051 addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
18052 line="5",times="0"@}]@}
18053 (gdb)
18054 @end smallexample
18055
18056 @subheading The @code{-break-enable} Command
18057 @findex -break-enable
18058
18059 @subsubheading Synopsis
18060
18061 @smallexample
18062 -break-enable ( @var{breakpoint} )+
18063 @end smallexample
18064
18065 Enable (previously disabled) @var{breakpoint}(s).
18066
18067 @subsubheading @value{GDBN} Command
18068
18069 The corresponding @value{GDBN} command is @samp{enable}.
18070
18071 @subsubheading Example
18072
18073 @smallexample
18074 (gdb)
18075 -break-enable 2
18076 ^done
18077 (gdb)
18078 -break-list
18079 ^done,BreakpointTable=@{nr_rows="1",nr_cols="6",
18080 hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
18081 @{width="14",alignment="-1",col_name="type",colhdr="Type"@},
18082 @{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
18083 @{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
18084 @{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
18085 @{width="40",alignment="2",col_name="what",colhdr="What"@}],
18086 body=[bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y",
18087 addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c",
18088 line="5",times="0"@}]@}
18089 (gdb)
18090 @end smallexample
18091
18092 @subheading The @code{-break-info} Command
18093 @findex -break-info
18094
18095 @subsubheading Synopsis
18096
18097 @smallexample
18098 -break-info @var{breakpoint}
18099 @end smallexample
18100
18101 @c REDUNDANT???
18102 Get information about a single breakpoint.
18103
18104 @subsubheading @value{GDBN} command
18105
18106 The corresponding @value{GDBN} command is @samp{info break @var{breakpoint}}.
18107
18108 @subsubheading Example
18109 N.A.
18110
18111 @subheading The @code{-break-insert} Command
18112 @findex -break-insert
18113
18114 @subsubheading Synopsis
18115
18116 @smallexample
18117 -break-insert [ -t ] [ -h ] [ -r ]
18118 [ -c @var{condition} ] [ -i @var{ignore-count} ]
18119 [ -p @var{thread} ] [ @var{line} | @var{addr} ]
18120 @end smallexample
18121
18122 @noindent
18123 If specified, @var{line}, can be one of:
18124
18125 @itemize @bullet
18126 @item function
18127 @c @item +offset
18128 @c @item -offset
18129 @c @item linenum
18130 @item filename:linenum
18131 @item filename:function
18132 @item *address
18133 @end itemize
18134
18135 The possible optional parameters of this command are:
18136
18137 @table @samp
18138 @item -t
18139 Insert a temporary breakpoint.
18140 @item -h
18141 Insert a hardware breakpoint.
18142 @item -c @var{condition}
18143 Make the breakpoint conditional on @var{condition}.
18144 @item -i @var{ignore-count}
18145 Initialize the @var{ignore-count}.
18146 @item -r
18147 Insert a regular breakpoint in all the functions whose names match the
18148 given regular expression. Other flags are not applicable to regular
18149 expresson.
18150 @end table
18151
18152 @subsubheading Result
18153
18154 The result is in the form:
18155
18156 @smallexample
18157 ^done,bkpt=@{number="@var{number}",type="@var{type}",disp="del"|"keep",
18158 enabled="y"|"n",addr="@var{hex}",func="@var{funcname}",file="@var{filename}",
18159 fullname="@var{full_filename}",line="@var{lineno}",[thread="@var{threadno},]
18160 times="@var{times}"@}
18161 @end smallexample
18162
18163 @noindent
18164 where @var{number} is the @value{GDBN} number for this breakpoint,
18165 @var{funcname} is the name of the function where the breakpoint was
18166 inserted, @var{filename} is the name of the source file which contains
18167 this function, @var{lineno} is the source line number within that file
18168 and @var{times} the number of times that the breakpoint has been hit
18169 (always 0 for -break-insert but may be greater for -break-info or -break-list
18170 which use the same output).
18171
18172 Note: this format is open to change.
18173 @c An out-of-band breakpoint instead of part of the result?
18174
18175 @subsubheading @value{GDBN} Command
18176
18177 The corresponding @value{GDBN} commands are @samp{break}, @samp{tbreak},
18178 @samp{hbreak}, @samp{thbreak}, and @samp{rbreak}.
18179
18180 @subsubheading Example
18181
18182 @smallexample
18183 (gdb)
18184 -break-insert main
18185 ^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",
18186 fullname="/home/foo/recursive2.c,line="4",times="0"@}
18187 (gdb)
18188 -break-insert -t foo
18189 ^done,bkpt=@{number="2",addr="0x00010774",file="recursive2.c",
18190 fullname="/home/foo/recursive2.c,line="11",times="0"@}
18191 (gdb)
18192 -break-list
18193 ^done,BreakpointTable=@{nr_rows="2",nr_cols="6",
18194 hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
18195 @{width="14",alignment="-1",col_name="type",colhdr="Type"@},
18196 @{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
18197 @{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
18198 @{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
18199 @{width="40",alignment="2",col_name="what",colhdr="What"@}],
18200 body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
18201 addr="0x0001072c", func="main",file="recursive2.c",
18202 fullname="/home/foo/recursive2.c,"line="4",times="0"@},
18203 bkpt=@{number="2",type="breakpoint",disp="del",enabled="y",
18204 addr="0x00010774",func="foo",file="recursive2.c",
18205 fullname="/home/foo/recursive2.c",line="11",times="0"@}]@}
18206 (gdb)
18207 -break-insert -r foo.*
18208 ~int foo(int, int);
18209 ^done,bkpt=@{number="3",addr="0x00010774",file="recursive2.c,
18210 "fullname="/home/foo/recursive2.c",line="11",times="0"@}
18211 (gdb)
18212 @end smallexample
18213
18214 @subheading The @code{-break-list} Command
18215 @findex -break-list
18216
18217 @subsubheading Synopsis
18218
18219 @smallexample
18220 -break-list
18221 @end smallexample
18222
18223 Displays the list of inserted breakpoints, showing the following fields:
18224
18225 @table @samp
18226 @item Number
18227 number of the breakpoint
18228 @item Type
18229 type of the breakpoint: @samp{breakpoint} or @samp{watchpoint}
18230 @item Disposition
18231 should the breakpoint be deleted or disabled when it is hit: @samp{keep}
18232 or @samp{nokeep}
18233 @item Enabled
18234 is the breakpoint enabled or no: @samp{y} or @samp{n}
18235 @item Address
18236 memory location at which the breakpoint is set
18237 @item What
18238 logical location of the breakpoint, expressed by function name, file
18239 name, line number
18240 @item Times
18241 number of times the breakpoint has been hit
18242 @end table
18243
18244 If there are no breakpoints or watchpoints, the @code{BreakpointTable}
18245 @code{body} field is an empty list.
18246
18247 @subsubheading @value{GDBN} Command
18248
18249 The corresponding @value{GDBN} command is @samp{info break}.
18250
18251 @subsubheading Example
18252
18253 @smallexample
18254 (gdb)
18255 -break-list
18256 ^done,BreakpointTable=@{nr_rows="2",nr_cols="6",
18257 hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
18258 @{width="14",alignment="-1",col_name="type",colhdr="Type"@},
18259 @{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
18260 @{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
18261 @{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
18262 @{width="40",alignment="2",col_name="what",colhdr="What"@}],
18263 body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
18264 addr="0x000100d0",func="main",file="hello.c",line="5",times="0"@},
18265 bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y",
18266 addr="0x00010114",func="foo",file="hello.c",fullname="/home/foo/hello.c",
18267 line="13",times="0"@}]@}
18268 (gdb)
18269 @end smallexample
18270
18271 Here's an example of the result when there are no breakpoints:
18272
18273 @smallexample
18274 (gdb)
18275 -break-list
18276 ^done,BreakpointTable=@{nr_rows="0",nr_cols="6",
18277 hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
18278 @{width="14",alignment="-1",col_name="type",colhdr="Type"@},
18279 @{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
18280 @{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
18281 @{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
18282 @{width="40",alignment="2",col_name="what",colhdr="What"@}],
18283 body=[]@}
18284 (gdb)
18285 @end smallexample
18286
18287 @subheading The @code{-break-watch} Command
18288 @findex -break-watch
18289
18290 @subsubheading Synopsis
18291
18292 @smallexample
18293 -break-watch [ -a | -r ]
18294 @end smallexample
18295
18296 Create a watchpoint. With the @samp{-a} option it will create an
18297 @dfn{access} watchpoint, i.e. a watchpoint that triggers either on a
18298 read from or on a write to the memory location. With the @samp{-r}
18299 option, the watchpoint created is a @dfn{read} watchpoint, i.e. it will
18300 trigger only when the memory location is accessed for reading. Without
18301 either of the options, the watchpoint created is a regular watchpoint,
18302 i.e. it will trigger when the memory location is accessed for writing.
18303 @xref{Set Watchpoints, , Setting watchpoints}.
18304
18305 Note that @samp{-break-list} will report a single list of watchpoints and
18306 breakpoints inserted.
18307
18308 @subsubheading @value{GDBN} Command
18309
18310 The corresponding @value{GDBN} commands are @samp{watch}, @samp{awatch}, and
18311 @samp{rwatch}.
18312
18313 @subsubheading Example
18314
18315 Setting a watchpoint on a variable in the @code{main} function:
18316
18317 @smallexample
18318 (gdb)
18319 -break-watch x
18320 ^done,wpt=@{number="2",exp="x"@}
18321 (gdb)
18322 -exec-continue
18323 ^running
18324 ^done,reason="watchpoint-trigger",wpt=@{number="2",exp="x"@},
18325 value=@{old="-268439212",new="55"@},
18326 frame=@{func="main",args=[],file="recursive2.c",
18327 fullname="/home/foo/bar/recursive2.c",line="5"@}
18328 (gdb)
18329 @end smallexample
18330
18331 Setting a watchpoint on a variable local to a function. @value{GDBN} will stop
18332 the program execution twice: first for the variable changing value, then
18333 for the watchpoint going out of scope.
18334
18335 @smallexample
18336 (gdb)
18337 -break-watch C
18338 ^done,wpt=@{number="5",exp="C"@}
18339 (gdb)
18340 -exec-continue
18341 ^running
18342 ^done,reason="watchpoint-trigger",
18343 wpt=@{number="5",exp="C"@},value=@{old="-276895068",new="3"@},
18344 frame=@{func="callee4",args=[],
18345 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
18346 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13"@}
18347 (gdb)
18348 -exec-continue
18349 ^running
18350 ^done,reason="watchpoint-scope",wpnum="5",
18351 frame=@{func="callee3",args=[@{name="strarg",
18352 value="0x11940 \"A string argument.\""@}],
18353 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
18354 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
18355 (gdb)
18356 @end smallexample
18357
18358 Listing breakpoints and watchpoints, at different points in the program
18359 execution. Note that once the watchpoint goes out of scope, it is
18360 deleted.
18361
18362 @smallexample
18363 (gdb)
18364 -break-watch C
18365 ^done,wpt=@{number="2",exp="C"@}
18366 (gdb)
18367 -break-list
18368 ^done,BreakpointTable=@{nr_rows="2",nr_cols="6",
18369 hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
18370 @{width="14",alignment="-1",col_name="type",colhdr="Type"@},
18371 @{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
18372 @{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
18373 @{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
18374 @{width="40",alignment="2",col_name="what",colhdr="What"@}],
18375 body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
18376 addr="0x00010734",func="callee4",
18377 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
18378 fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c"line="8",times="1"@},
18379 bkpt=@{number="2",type="watchpoint",disp="keep",
18380 enabled="y",addr="",what="C",times="0"@}]@}
18381 (gdb)
18382 -exec-continue
18383 ^running
18384 ^done,reason="watchpoint-trigger",wpt=@{number="2",exp="C"@},
18385 value=@{old="-276895068",new="3"@},
18386 frame=@{func="callee4",args=[],
18387 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
18388 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13"@}
18389 (gdb)
18390 -break-list
18391 ^done,BreakpointTable=@{nr_rows="2",nr_cols="6",
18392 hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
18393 @{width="14",alignment="-1",col_name="type",colhdr="Type"@},
18394 @{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
18395 @{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
18396 @{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
18397 @{width="40",alignment="2",col_name="what",colhdr="What"@}],
18398 body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
18399 addr="0x00010734",func="callee4",
18400 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
18401 fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"@},
18402 bkpt=@{number="2",type="watchpoint",disp="keep",
18403 enabled="y",addr="",what="C",times="-5"@}]@}
18404 (gdb)
18405 -exec-continue
18406 ^running
18407 ^done,reason="watchpoint-scope",wpnum="2",
18408 frame=@{func="callee3",args=[@{name="strarg",
18409 value="0x11940 \"A string argument.\""@}],
18410 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
18411 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
18412 (gdb)
18413 -break-list
18414 ^done,BreakpointTable=@{nr_rows="1",nr_cols="6",
18415 hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@},
18416 @{width="14",alignment="-1",col_name="type",colhdr="Type"@},
18417 @{width="4",alignment="-1",col_name="disp",colhdr="Disp"@},
18418 @{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@},
18419 @{width="10",alignment="-1",col_name="addr",colhdr="Address"@},
18420 @{width="40",alignment="2",col_name="what",colhdr="What"@}],
18421 body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y",
18422 addr="0x00010734",func="callee4",
18423 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
18424 fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8",
18425 times="1"@}]@}
18426 (gdb)
18427 @end smallexample
18428
18429 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
18430 @node GDB/MI Program Context
18431 @section @sc{gdb/mi} Program Context
18432
18433 @subheading The @code{-exec-arguments} Command
18434 @findex -exec-arguments
18435
18436
18437 @subsubheading Synopsis
18438
18439 @smallexample
18440 -exec-arguments @var{args}
18441 @end smallexample
18442
18443 Set the inferior program arguments, to be used in the next
18444 @samp{-exec-run}.
18445
18446 @subsubheading @value{GDBN} Command
18447
18448 The corresponding @value{GDBN} command is @samp{set args}.
18449
18450 @subsubheading Example
18451
18452 @c FIXME!
18453 Don't have one around.
18454
18455
18456 @subheading The @code{-exec-show-arguments} Command
18457 @findex -exec-show-arguments
18458
18459 @subsubheading Synopsis
18460
18461 @smallexample
18462 -exec-show-arguments
18463 @end smallexample
18464
18465 Print the arguments of the program.
18466
18467 @subsubheading @value{GDBN} Command
18468
18469 The corresponding @value{GDBN} command is @samp{show args}.
18470
18471 @subsubheading Example
18472 N.A.
18473
18474
18475 @subheading The @code{-environment-cd} Command
18476 @findex -environment-cd
18477
18478 @subsubheading Synopsis
18479
18480 @smallexample
18481 -environment-cd @var{pathdir}
18482 @end smallexample
18483
18484 Set @value{GDBN}'s working directory.
18485
18486 @subsubheading @value{GDBN} Command
18487
18488 The corresponding @value{GDBN} command is @samp{cd}.
18489
18490 @subsubheading Example
18491
18492 @smallexample
18493 (gdb)
18494 -environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
18495 ^done
18496 (gdb)
18497 @end smallexample
18498
18499
18500 @subheading The @code{-environment-directory} Command
18501 @findex -environment-directory
18502
18503 @subsubheading Synopsis
18504
18505 @smallexample
18506 -environment-directory [ -r ] [ @var{pathdir} ]+
18507 @end smallexample
18508
18509 Add directories @var{pathdir} to beginning of search path for source files.
18510 If the @samp{-r} option is used, the search path is reset to the default
18511 search path. If directories @var{pathdir} are supplied in addition to the
18512 @samp{-r} option, the search path is first reset and then addition
18513 occurs as normal.
18514 Multiple directories may be specified, separated by blanks. Specifying
18515 multiple directories in a single command
18516 results in the directories added to the beginning of the
18517 search path in the same order they were presented in the command.
18518 If blanks are needed as
18519 part of a directory name, double-quotes should be used around
18520 the name. In the command output, the path will show up separated
18521 by the system directory-separator character. The directory-seperator
18522 character must not be used
18523 in any directory name.
18524 If no directories are specified, the current search path is displayed.
18525
18526 @subsubheading @value{GDBN} Command
18527
18528 The corresponding @value{GDBN} command is @samp{dir}.
18529
18530 @subsubheading Example
18531
18532 @smallexample
18533 (gdb)
18534 -environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb
18535 ^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd"
18536 (gdb)
18537 -environment-directory ""
18538 ^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd"
18539 (gdb)
18540 -environment-directory -r /home/jjohnstn/src/gdb /usr/src
18541 ^done,source-path="/home/jjohnstn/src/gdb:/usr/src:$cdir:$cwd"
18542 (gdb)
18543 -environment-directory -r
18544 ^done,source-path="$cdir:$cwd"
18545 (gdb)
18546 @end smallexample
18547
18548
18549 @subheading The @code{-environment-path} Command
18550 @findex -environment-path
18551
18552 @subsubheading Synopsis
18553
18554 @smallexample
18555 -environment-path [ -r ] [ @var{pathdir} ]+
18556 @end smallexample
18557
18558 Add directories @var{pathdir} to beginning of search path for object files.
18559 If the @samp{-r} option is used, the search path is reset to the original
18560 search path that existed at gdb start-up. If directories @var{pathdir} are
18561 supplied in addition to the
18562 @samp{-r} option, the search path is first reset and then addition
18563 occurs as normal.
18564 Multiple directories may be specified, separated by blanks. Specifying
18565 multiple directories in a single command
18566 results in the directories added to the beginning of the
18567 search path in the same order they were presented in the command.
18568 If blanks are needed as
18569 part of a directory name, double-quotes should be used around
18570 the name. In the command output, the path will show up separated
18571 by the system directory-separator character. The directory-seperator
18572 character must not be used
18573 in any directory name.
18574 If no directories are specified, the current path is displayed.
18575
18576
18577 @subsubheading @value{GDBN} Command
18578
18579 The corresponding @value{GDBN} command is @samp{path}.
18580
18581 @subsubheading Example
18582
18583 @smallexample
18584 (gdb)
18585 -environment-path
18586 ^done,path="/usr/bin"
18587 (gdb)
18588 -environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb /bin
18589 ^done,path="/kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb:/bin:/usr/bin"
18590 (gdb)
18591 -environment-path -r /usr/local/bin
18592 ^done,path="/usr/local/bin:/usr/bin"
18593 (gdb)
18594 @end smallexample
18595
18596
18597 @subheading The @code{-environment-pwd} Command
18598 @findex -environment-pwd
18599
18600 @subsubheading Synopsis
18601
18602 @smallexample
18603 -environment-pwd
18604 @end smallexample
18605
18606 Show the current working directory.
18607
18608 @subsubheading @value{GDBN} command
18609
18610 The corresponding @value{GDBN} command is @samp{pwd}.
18611
18612 @subsubheading Example
18613
18614 @smallexample
18615 (gdb)
18616 -environment-pwd
18617 ^done,cwd="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb"
18618 (gdb)
18619 @end smallexample
18620
18621 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
18622 @node GDB/MI Thread Commands
18623 @section @sc{gdb/mi} Thread Commands
18624
18625
18626 @subheading The @code{-thread-info} Command
18627 @findex -thread-info
18628
18629 @subsubheading Synopsis
18630
18631 @smallexample
18632 -thread-info
18633 @end smallexample
18634
18635 @subsubheading @value{GDBN} command
18636
18637 No equivalent.
18638
18639 @subsubheading Example
18640 N.A.
18641
18642
18643 @subheading The @code{-thread-list-all-threads} Command
18644 @findex -thread-list-all-threads
18645
18646 @subsubheading Synopsis
18647
18648 @smallexample
18649 -thread-list-all-threads
18650 @end smallexample
18651
18652 @subsubheading @value{GDBN} Command
18653
18654 The equivalent @value{GDBN} command is @samp{info threads}.
18655
18656 @subsubheading Example
18657 N.A.
18658
18659
18660 @subheading The @code{-thread-list-ids} Command
18661 @findex -thread-list-ids
18662
18663 @subsubheading Synopsis
18664
18665 @smallexample
18666 -thread-list-ids
18667 @end smallexample
18668
18669 Produces a list of the currently known @value{GDBN} thread ids. At the
18670 end of the list it also prints the total number of such threads.
18671
18672 @subsubheading @value{GDBN} Command
18673
18674 Part of @samp{info threads} supplies the same information.
18675
18676 @subsubheading Example
18677
18678 No threads present, besides the main process:
18679
18680 @smallexample
18681 (gdb)
18682 -thread-list-ids
18683 ^done,thread-ids=@{@},number-of-threads="0"
18684 (gdb)
18685 @end smallexample
18686
18687
18688 Several threads:
18689
18690 @smallexample
18691 (gdb)
18692 -thread-list-ids
18693 ^done,thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@},
18694 number-of-threads="3"
18695 (gdb)
18696 @end smallexample
18697
18698
18699 @subheading The @code{-thread-select} Command
18700 @findex -thread-select
18701
18702 @subsubheading Synopsis
18703
18704 @smallexample
18705 -thread-select @var{threadnum}
18706 @end smallexample
18707
18708 Make @var{threadnum} the current thread. It prints the number of the new
18709 current thread, and the topmost frame for that thread.
18710
18711 @subsubheading @value{GDBN} Command
18712
18713 The corresponding @value{GDBN} command is @samp{thread}.
18714
18715 @subsubheading Example
18716
18717 @smallexample
18718 (gdb)
18719 -exec-next
18720 ^running
18721 (gdb)
18722 *stopped,reason="end-stepping-range",thread-id="2",line="187",
18723 file="../../../devo/gdb/testsuite/gdb.threads/linux-dp.c"
18724 (gdb)
18725 -thread-list-ids
18726 ^done,
18727 thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@},
18728 number-of-threads="3"
18729 (gdb)
18730 -thread-select 3
18731 ^done,new-thread-id="3",
18732 frame=@{level="0",func="vprintf",
18733 args=[@{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""@},
18734 @{name="arg",value="0x2"@}],file="vprintf.c",line="31"@}
18735 (gdb)
18736 @end smallexample
18737
18738 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
18739 @node GDB/MI Program Execution
18740 @section @sc{gdb/mi} Program Execution
18741
18742 These are the asynchronous commands which generate the out-of-band
18743 record @samp{*stopped}. Currently GDB only really executes
18744 asynchronously with remote targets and this interaction is mimicked in
18745 other cases.
18746
18747 @subheading The @code{-exec-continue} Command
18748 @findex -exec-continue
18749
18750 @subsubheading Synopsis
18751
18752 @smallexample
18753 -exec-continue
18754 @end smallexample
18755
18756 Resumes the execution of the inferior program until a breakpoint is
18757 encountered, or until the inferior exits.
18758
18759 @subsubheading @value{GDBN} Command
18760
18761 The corresponding @value{GDBN} corresponding is @samp{continue}.
18762
18763 @subsubheading Example
18764
18765 @smallexample
18766 -exec-continue
18767 ^running
18768 (gdb)
18769 @@Hello world
18770 *stopped,reason="breakpoint-hit",bkptno="2",frame=@{func="foo",args=[],
18771 file="hello.c",fullname="/home/foo/bar/hello.c",line="13"@}
18772 (gdb)
18773 @end smallexample
18774
18775
18776 @subheading The @code{-exec-finish} Command
18777 @findex -exec-finish
18778
18779 @subsubheading Synopsis
18780
18781 @smallexample
18782 -exec-finish
18783 @end smallexample
18784
18785 Resumes the execution of the inferior program until the current
18786 function is exited. Displays the results returned by the function.
18787
18788 @subsubheading @value{GDBN} Command
18789
18790 The corresponding @value{GDBN} command is @samp{finish}.
18791
18792 @subsubheading Example
18793
18794 Function returning @code{void}.
18795
18796 @smallexample
18797 -exec-finish
18798 ^running
18799 (gdb)
18800 @@hello from foo
18801 *stopped,reason="function-finished",frame=@{func="main",args=[],
18802 file="hello.c",fullname="/home/foo/bar/hello.c",line="7"@}
18803 (gdb)
18804 @end smallexample
18805
18806 Function returning other than @code{void}. The name of the internal
18807 @value{GDBN} variable storing the result is printed, together with the
18808 value itself.
18809
18810 @smallexample
18811 -exec-finish
18812 ^running
18813 (gdb)
18814 *stopped,reason="function-finished",frame=@{addr="0x000107b0",func="foo",
18815 args=[@{name="a",value="1"],@{name="b",value="9"@}@},
18816 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
18817 gdb-result-var="$1",return-value="0"
18818 (gdb)
18819 @end smallexample
18820
18821
18822 @subheading The @code{-exec-interrupt} Command
18823 @findex -exec-interrupt
18824
18825 @subsubheading Synopsis
18826
18827 @smallexample
18828 -exec-interrupt
18829 @end smallexample
18830
18831 Interrupts the background execution of the target. Note how the token
18832 associated with the stop message is the one for the execution command
18833 that has been interrupted. The token for the interrupt itself only
18834 appears in the @samp{^done} output. If the user is trying to
18835 interrupt a non-running program, an error message will be printed.
18836
18837 @subsubheading @value{GDBN} Command
18838
18839 The corresponding @value{GDBN} command is @samp{interrupt}.
18840
18841 @subsubheading Example
18842
18843 @smallexample
18844 (gdb)
18845 111-exec-continue
18846 111^running
18847
18848 (gdb)
18849 222-exec-interrupt
18850 222^done
18851 (gdb)
18852 111*stopped,signal-name="SIGINT",signal-meaning="Interrupt",
18853 frame=@{addr="0x00010140",func="foo",args=[],file="try.c",
18854 fullname="/home/foo/bar/try.c",line="13"@}
18855 (gdb)
18856
18857 (gdb)
18858 -exec-interrupt
18859 ^error,msg="mi_cmd_exec_interrupt: Inferior not executing."
18860 (gdb)
18861 @end smallexample
18862
18863
18864 @subheading The @code{-exec-next} Command
18865 @findex -exec-next
18866
18867 @subsubheading Synopsis
18868
18869 @smallexample
18870 -exec-next
18871 @end smallexample
18872
18873 Resumes execution of the inferior program, stopping when the beginning
18874 of the next source line is reached.
18875
18876 @subsubheading @value{GDBN} Command
18877
18878 The corresponding @value{GDBN} command is @samp{next}.
18879
18880 @subsubheading Example
18881
18882 @smallexample
18883 -exec-next
18884 ^running
18885 (gdb)
18886 *stopped,reason="end-stepping-range",line="8",file="hello.c"
18887 (gdb)
18888 @end smallexample
18889
18890
18891 @subheading The @code{-exec-next-instruction} Command
18892 @findex -exec-next-instruction
18893
18894 @subsubheading Synopsis
18895
18896 @smallexample
18897 -exec-next-instruction
18898 @end smallexample
18899
18900 Executes one machine instruction. If the instruction is a function
18901 call, continues until the function returns. If the program stops at an
18902 instruction in the middle of a source line, the address will be
18903 printed as well.
18904
18905 @subsubheading @value{GDBN} Command
18906
18907 The corresponding @value{GDBN} command is @samp{nexti}.
18908
18909 @subsubheading Example
18910
18911 @smallexample
18912 (gdb)
18913 -exec-next-instruction
18914 ^running
18915
18916 (gdb)
18917 *stopped,reason="end-stepping-range",
18918 addr="0x000100d4",line="5",file="hello.c"
18919 (gdb)
18920 @end smallexample
18921
18922
18923 @subheading The @code{-exec-return} Command
18924 @findex -exec-return
18925
18926 @subsubheading Synopsis
18927
18928 @smallexample
18929 -exec-return
18930 @end smallexample
18931
18932 Makes current function return immediately. Doesn't execute the inferior.
18933 Displays the new current frame.
18934
18935 @subsubheading @value{GDBN} Command
18936
18937 The corresponding @value{GDBN} command is @samp{return}.
18938
18939 @subsubheading Example
18940
18941 @smallexample
18942 (gdb)
18943 200-break-insert callee4
18944 200^done,bkpt=@{number="1",addr="0x00010734",
18945 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@}
18946 (gdb)
18947 000-exec-run
18948 000^running
18949 (gdb)
18950 000*stopped,reason="breakpoint-hit",bkptno="1",
18951 frame=@{func="callee4",args=[],
18952 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
18953 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8"@}
18954 (gdb)
18955 205-break-delete
18956 205^done
18957 (gdb)
18958 111-exec-return
18959 111^done,frame=@{level="0",func="callee3",
18960 args=[@{name="strarg",
18961 value="0x11940 \"A string argument.\""@}],
18962 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
18963 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"@}
18964 (gdb)
18965 @end smallexample
18966
18967
18968 @subheading The @code{-exec-run} Command
18969 @findex -exec-run
18970
18971 @subsubheading Synopsis
18972
18973 @smallexample
18974 -exec-run
18975 @end smallexample
18976
18977 Starts execution of the inferior from the beginning. The inferior
18978 executes until either a breakpoint is encountered or the program
18979 exits. In the latter case the output will include an exit code, if
18980 the program has exited exceptionally.
18981
18982 @subsubheading @value{GDBN} Command
18983
18984 The corresponding @value{GDBN} command is @samp{run}.
18985
18986 @subsubheading Examples
18987
18988 @smallexample
18989 (gdb)
18990 -break-insert main
18991 ^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",line="4"@}
18992 (gdb)
18993 -exec-run
18994 ^running
18995 (gdb)
18996 *stopped,reason="breakpoint-hit",bkptno="1",
18997 frame=@{func="main",args=[],file="recursive2.c",
18998 fullname="/home/foo/bar/recursive2.c",line="4"@}
18999 (gdb)
19000 @end smallexample
19001
19002 @noindent
19003 Program exited normally:
19004
19005 @smallexample
19006 (gdb)
19007 -exec-run
19008 ^running
19009 (gdb)
19010 x = 55
19011 *stopped,reason="exited-normally"
19012 (gdb)
19013 @end smallexample
19014
19015 @noindent
19016 Program exited exceptionally:
19017
19018 @smallexample
19019 (gdb)
19020 -exec-run
19021 ^running
19022 (gdb)
19023 x = 55
19024 *stopped,reason="exited",exit-code="01"
19025 (gdb)
19026 @end smallexample
19027
19028 Another way the program can terminate is if it receives a signal such as
19029 @code{SIGINT}. In this case, @sc{gdb/mi} displays this:
19030
19031 @smallexample
19032 (gdb)
19033 *stopped,reason="exited-signalled",signal-name="SIGINT",
19034 signal-meaning="Interrupt"
19035 @end smallexample
19036
19037
19038 @c @subheading -exec-signal
19039
19040
19041 @subheading The @code{-exec-step} Command
19042 @findex -exec-step
19043
19044 @subsubheading Synopsis
19045
19046 @smallexample
19047 -exec-step
19048 @end smallexample
19049
19050 Resumes execution of the inferior program, stopping when the beginning
19051 of the next source line is reached, if the next source line is not a
19052 function call. If it is, stop at the first instruction of the called
19053 function.
19054
19055 @subsubheading @value{GDBN} Command
19056
19057 The corresponding @value{GDBN} command is @samp{step}.
19058
19059 @subsubheading Example
19060
19061 Stepping into a function:
19062
19063 @smallexample
19064 -exec-step
19065 ^running
19066 (gdb)
19067 *stopped,reason="end-stepping-range",
19068 frame=@{func="foo",args=[@{name="a",value="10"@},
19069 @{name="b",value="0"@}],file="recursive2.c",
19070 fullname="/home/foo/bar/recursive2.c",line="11"@}
19071 (gdb)
19072 @end smallexample
19073
19074 Regular stepping:
19075
19076 @smallexample
19077 -exec-step
19078 ^running
19079 (gdb)
19080 *stopped,reason="end-stepping-range",line="14",file="recursive2.c"
19081 (gdb)
19082 @end smallexample
19083
19084
19085 @subheading The @code{-exec-step-instruction} Command
19086 @findex -exec-step-instruction
19087
19088 @subsubheading Synopsis
19089
19090 @smallexample
19091 -exec-step-instruction
19092 @end smallexample
19093
19094 Resumes the inferior which executes one machine instruction. The
19095 output, once @value{GDBN} has stopped, will vary depending on whether
19096 we have stopped in the middle of a source line or not. In the former
19097 case, the address at which the program stopped will be printed as
19098 well.
19099
19100 @subsubheading @value{GDBN} Command
19101
19102 The corresponding @value{GDBN} command is @samp{stepi}.
19103
19104 @subsubheading Example
19105
19106 @smallexample
19107 (gdb)
19108 -exec-step-instruction
19109 ^running
19110
19111 (gdb)
19112 *stopped,reason="end-stepping-range",
19113 frame=@{func="foo",args=[],file="try.c",
19114 fullname="/home/foo/bar/try.c",line="10"@}
19115 (gdb)
19116 -exec-step-instruction
19117 ^running
19118
19119 (gdb)
19120 *stopped,reason="end-stepping-range",
19121 frame=@{addr="0x000100f4",func="foo",args=[],file="try.c",
19122 fullname="/home/foo/bar/try.c",line="10"@}
19123 (gdb)
19124 @end smallexample
19125
19126
19127 @subheading The @code{-exec-until} Command
19128 @findex -exec-until
19129
19130 @subsubheading Synopsis
19131
19132 @smallexample
19133 -exec-until [ @var{location} ]
19134 @end smallexample
19135
19136 Executes the inferior until the @var{location} specified in the
19137 argument is reached. If there is no argument, the inferior executes
19138 until a source line greater than the current one is reached. The
19139 reason for stopping in this case will be @samp{location-reached}.
19140
19141 @subsubheading @value{GDBN} Command
19142
19143 The corresponding @value{GDBN} command is @samp{until}.
19144
19145 @subsubheading Example
19146
19147 @smallexample
19148 (gdb)
19149 -exec-until recursive2.c:6
19150 ^running
19151 (gdb)
19152 x = 55
19153 *stopped,reason="location-reached",frame=@{func="main",args=[],
19154 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="6"@}
19155 (gdb)
19156 @end smallexample
19157
19158 @ignore
19159 @subheading -file-clear
19160 Is this going away????
19161 @end ignore
19162
19163 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
19164 @node GDB/MI Stack Manipulation
19165 @section @sc{gdb/mi} Stack Manipulation Commands
19166
19167
19168 @subheading The @code{-stack-info-frame} Command
19169 @findex -stack-info-frame
19170
19171 @subsubheading Synopsis
19172
19173 @smallexample
19174 -stack-info-frame
19175 @end smallexample
19176
19177 Get info on the selected frame.
19178
19179 @subsubheading @value{GDBN} Command
19180
19181 The corresponding @value{GDBN} command is @samp{info frame} or @samp{frame}
19182 (without arguments).
19183
19184 @subsubheading Example
19185
19186 @smallexample
19187 (gdb)
19188 -stack-info-frame
19189 ^done,frame=@{level="1",addr="0x0001076c",func="callee3",
19190 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
19191 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"@}
19192 (gdb)
19193 @end smallexample
19194
19195 @subheading The @code{-stack-info-depth} Command
19196 @findex -stack-info-depth
19197
19198 @subsubheading Synopsis
19199
19200 @smallexample
19201 -stack-info-depth [ @var{max-depth} ]
19202 @end smallexample
19203
19204 Return the depth of the stack. If the integer argument @var{max-depth}
19205 is specified, do not count beyond @var{max-depth} frames.
19206
19207 @subsubheading @value{GDBN} Command
19208
19209 There's no equivalent @value{GDBN} command.
19210
19211 @subsubheading Example
19212
19213 For a stack with frame levels 0 through 11:
19214
19215 @smallexample
19216 (gdb)
19217 -stack-info-depth
19218 ^done,depth="12"
19219 (gdb)
19220 -stack-info-depth 4
19221 ^done,depth="4"
19222 (gdb)
19223 -stack-info-depth 12
19224 ^done,depth="12"
19225 (gdb)
19226 -stack-info-depth 11
19227 ^done,depth="11"
19228 (gdb)
19229 -stack-info-depth 13
19230 ^done,depth="12"
19231 (gdb)
19232 @end smallexample
19233
19234 @subheading The @code{-stack-list-arguments} Command
19235 @findex -stack-list-arguments
19236
19237 @subsubheading Synopsis
19238
19239 @smallexample
19240 -stack-list-arguments @var{show-values}
19241 [ @var{low-frame} @var{high-frame} ]
19242 @end smallexample
19243
19244 Display a list of the arguments for the frames between @var{low-frame}
19245 and @var{high-frame} (inclusive). If @var{low-frame} and
19246 @var{high-frame} are not provided, list the arguments for the whole
19247 call stack. If the two arguments are equal, show the single frame
19248 at the corresponding level. It is an error if @var{low-frame} is
19249 larger than the actual number of frames. On the other hand,
19250 @var{high-frame} may be larger than the actual number of frames, in
19251 which case only existing frames will be returned.
19252
19253 The @var{show-values} argument must have a value of 0 or 1. A value of
19254 0 means that only the names of the arguments are listed, a value of 1
19255 means that both names and values of the arguments are printed.
19256
19257 @subsubheading @value{GDBN} Command
19258
19259 @value{GDBN} does not have an equivalent command. @code{gdbtk} has a
19260 @samp{gdb_get_args} command which partially overlaps with the
19261 functionality of @samp{-stack-list-arguments}.
19262
19263 @subsubheading Example
19264
19265 @smallexample
19266 (gdb)
19267 -stack-list-frames
19268 ^done,
19269 stack=[
19270 frame=@{level="0",addr="0x00010734",func="callee4",
19271 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
19272 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8"@},
19273 frame=@{level="1",addr="0x0001076c",func="callee3",
19274 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
19275 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"@},
19276 frame=@{level="2",addr="0x0001078c",func="callee2",
19277 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
19278 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="22"@},
19279 frame=@{level="3",addr="0x000107b4",func="callee1",
19280 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
19281 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="27"@},
19282 frame=@{level="4",addr="0x000107e0",func="main",
19283 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",
19284 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="32"@}]
19285 (gdb)
19286 -stack-list-arguments 0
19287 ^done,
19288 stack-args=[
19289 frame=@{level="0",args=[]@},
19290 frame=@{level="1",args=[name="strarg"]@},
19291 frame=@{level="2",args=[name="intarg",name="strarg"]@},
19292 frame=@{level="3",args=[name="intarg",name="strarg",name="fltarg"]@},
19293 frame=@{level="4",args=[]@}]
19294 (gdb)
19295 -stack-list-arguments 1
19296 ^done,
19297 stack-args=[
19298 frame=@{level="0",args=[]@},
19299 frame=@{level="1",
19300 args=[@{name="strarg",value="0x11940 \"A string argument.\""@}]@},
19301 frame=@{level="2",args=[
19302 @{name="intarg",value="2"@},
19303 @{name="strarg",value="0x11940 \"A string argument.\""@}]@},
19304 @{frame=@{level="3",args=[
19305 @{name="intarg",value="2"@},
19306 @{name="strarg",value="0x11940 \"A string argument.\""@},
19307 @{name="fltarg",value="3.5"@}]@},
19308 frame=@{level="4",args=[]@}]
19309 (gdb)
19310 -stack-list-arguments 0 2 2
19311 ^done,stack-args=[frame=@{level="2",args=[name="intarg",name="strarg"]@}]
19312 (gdb)
19313 -stack-list-arguments 1 2 2
19314 ^done,stack-args=[frame=@{level="2",
19315 args=[@{name="intarg",value="2"@},
19316 @{name="strarg",value="0x11940 \"A string argument.\""@}]@}]
19317 (gdb)
19318 @end smallexample
19319
19320 @c @subheading -stack-list-exception-handlers
19321
19322
19323 @subheading The @code{-stack-list-frames} Command
19324 @findex -stack-list-frames
19325
19326 @subsubheading Synopsis
19327
19328 @smallexample
19329 -stack-list-frames [ @var{low-frame} @var{high-frame} ]
19330 @end smallexample
19331
19332 List the frames currently on the stack. For each frame it displays the
19333 following info:
19334
19335 @table @samp
19336 @item @var{level}
19337 The frame number, 0 being the topmost frame, i.e. the innermost function.
19338 @item @var{addr}
19339 The @code{$pc} value for that frame.
19340 @item @var{func}
19341 Function name.
19342 @item @var{file}
19343 File name of the source file where the function lives.
19344 @item @var{line}
19345 Line number corresponding to the @code{$pc}.
19346 @end table
19347
19348 If invoked without arguments, this command prints a backtrace for the
19349 whole stack. If given two integer arguments, it shows the frames whose
19350 levels are between the two arguments (inclusive). If the two arguments
19351 are equal, it shows the single frame at the corresponding level. It is
19352 an error if @var{low-frame} is larger than the actual number of
19353 frames. On the other hand, @var{high-frame} may be larger than the
19354 actual number of frames, in which case only existing frames will be returned.
19355
19356 @subsubheading @value{GDBN} Command
19357
19358 The corresponding @value{GDBN} commands are @samp{backtrace} and @samp{where}.
19359
19360 @subsubheading Example
19361
19362 Full stack backtrace:
19363
19364 @smallexample
19365 (gdb)
19366 -stack-list-frames
19367 ^done,stack=
19368 [frame=@{level="0",addr="0x0001076c",func="foo",
19369 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="11"@},
19370 frame=@{level="1",addr="0x000107a4",func="foo",
19371 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
19372 frame=@{level="2",addr="0x000107a4",func="foo",
19373 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
19374 frame=@{level="3",addr="0x000107a4",func="foo",
19375 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
19376 frame=@{level="4",addr="0x000107a4",func="foo",
19377 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
19378 frame=@{level="5",addr="0x000107a4",func="foo",
19379 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
19380 frame=@{level="6",addr="0x000107a4",func="foo",
19381 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
19382 frame=@{level="7",addr="0x000107a4",func="foo",
19383 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
19384 frame=@{level="8",addr="0x000107a4",func="foo",
19385 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
19386 frame=@{level="9",addr="0x000107a4",func="foo",
19387 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
19388 frame=@{level="10",addr="0x000107a4",func="foo",
19389 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
19390 frame=@{level="11",addr="0x00010738",func="main",
19391 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="4"@}]
19392 (gdb)
19393 @end smallexample
19394
19395 Show frames between @var{low_frame} and @var{high_frame}:
19396
19397 @smallexample
19398 (gdb)
19399 -stack-list-frames 3 5
19400 ^done,stack=
19401 [frame=@{level="3",addr="0x000107a4",func="foo",
19402 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
19403 frame=@{level="4",addr="0x000107a4",func="foo",
19404 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@},
19405 frame=@{level="5",addr="0x000107a4",func="foo",
19406 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@}]
19407 (gdb)
19408 @end smallexample
19409
19410 Show a single frame:
19411
19412 @smallexample
19413 (gdb)
19414 -stack-list-frames 3 3
19415 ^done,stack=
19416 [frame=@{level="3",addr="0x000107a4",func="foo",
19417 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"@}]
19418 (gdb)
19419 @end smallexample
19420
19421
19422 @subheading The @code{-stack-list-locals} Command
19423 @findex -stack-list-locals
19424
19425 @subsubheading Synopsis
19426
19427 @smallexample
19428 -stack-list-locals @var{print-values}
19429 @end smallexample
19430
19431 Display the local variable names for the selected frame. If
19432 @var{print-values} is 0 or @code{--no-values}, print only the names of
19433 the variables; if it is 1 or @code{--all-values}, print also their
19434 values; and if it is 2 or @code{--simple-values}, print the name,
19435 type and value for simple data types and the name and type for arrays,
19436 structures and unions. In this last case, a frontend can immediately
19437 display the value of simple data types and create variable objects for
19438 other data types when the the user wishes to explore their values in
19439 more detail.
19440
19441 @subsubheading @value{GDBN} Command
19442
19443 @samp{info locals} in @value{GDBN}, @samp{gdb_get_locals} in @code{gdbtk}.
19444
19445 @subsubheading Example
19446
19447 @smallexample
19448 (gdb)
19449 -stack-list-locals 0
19450 ^done,locals=[name="A",name="B",name="C"]
19451 (gdb)
19452 -stack-list-locals --all-values
19453 ^done,locals=[@{name="A",value="1"@},@{name="B",value="2"@},
19454 @{name="C",value="@{1, 2, 3@}"@}]
19455 -stack-list-locals --simple-values
19456 ^done,locals=[@{name="A",type="int",value="1"@},
19457 @{name="B",type="int",value="2"@},@{name="C",type="int [3]"@}]
19458 (gdb)
19459 @end smallexample
19460
19461
19462 @subheading The @code{-stack-select-frame} Command
19463 @findex -stack-select-frame
19464
19465 @subsubheading Synopsis
19466
19467 @smallexample
19468 -stack-select-frame @var{framenum}
19469 @end smallexample
19470
19471 Change the selected frame. Select a different frame @var{framenum} on
19472 the stack.
19473
19474 @subsubheading @value{GDBN} Command
19475
19476 The corresponding @value{GDBN} commands are @samp{frame}, @samp{up},
19477 @samp{down}, @samp{select-frame}, @samp{up-silent}, and @samp{down-silent}.
19478
19479 @subsubheading Example
19480
19481 @smallexample
19482 (gdb)
19483 -stack-select-frame 2
19484 ^done
19485 (gdb)
19486 @end smallexample
19487
19488 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
19489 @node GDB/MI Variable Objects
19490 @section @sc{gdb/mi} Variable Objects
19491
19492
19493 @subheading Motivation for Variable Objects in @sc{gdb/mi}
19494
19495 For the implementation of a variable debugger window (locals, watched
19496 expressions, etc.), we are proposing the adaptation of the existing code
19497 used by @code{Insight}.
19498
19499 The two main reasons for that are:
19500
19501 @enumerate 1
19502 @item
19503 It has been proven in practice (it is already on its second generation).
19504
19505 @item
19506 It will shorten development time (needless to say how important it is
19507 now).
19508 @end enumerate
19509
19510 The original interface was designed to be used by Tcl code, so it was
19511 slightly changed so it could be used through @sc{gdb/mi}. This section
19512 describes the @sc{gdb/mi} operations that will be available and gives some
19513 hints about their use.
19514
19515 @emph{Note}: In addition to the set of operations described here, we
19516 expect the @sc{gui} implementation of a variable window to require, at
19517 least, the following operations:
19518
19519 @itemize @bullet
19520 @item @code{-gdb-show} @code{output-radix}
19521 @item @code{-stack-list-arguments}
19522 @item @code{-stack-list-locals}
19523 @item @code{-stack-select-frame}
19524 @end itemize
19525
19526 @subheading Introduction to Variable Objects in @sc{gdb/mi}
19527
19528 @cindex variable objects in @sc{gdb/mi}
19529 The basic idea behind variable objects is the creation of a named object
19530 to represent a variable, an expression, a memory location or even a CPU
19531 register. For each object created, a set of operations is available for
19532 examining or changing its properties.
19533
19534 Furthermore, complex data types, such as C structures, are represented
19535 in a tree format. For instance, the @code{struct} type variable is the
19536 root and the children will represent the struct members. If a child
19537 is itself of a complex type, it will also have children of its own.
19538 Appropriate language differences are handled for C, C@t{++} and Java.
19539
19540 When returning the actual values of the objects, this facility allows
19541 for the individual selection of the display format used in the result
19542 creation. It can be chosen among: binary, decimal, hexadecimal, octal
19543 and natural. Natural refers to a default format automatically
19544 chosen based on the variable type (like decimal for an @code{int}, hex
19545 for pointers, etc.).
19546
19547 The following is the complete set of @sc{gdb/mi} operations defined to
19548 access this functionality:
19549
19550 @multitable @columnfractions .4 .6
19551 @item @strong{Operation}
19552 @tab @strong{Description}
19553
19554 @item @code{-var-create}
19555 @tab create a variable object
19556 @item @code{-var-delete}
19557 @tab delete the variable object and its children
19558 @item @code{-var-set-format}
19559 @tab set the display format of this variable
19560 @item @code{-var-show-format}
19561 @tab show the display format of this variable
19562 @item @code{-var-info-num-children}
19563 @tab tells how many children this object has
19564 @item @code{-var-list-children}
19565 @tab return a list of the object's children
19566 @item @code{-var-info-type}
19567 @tab show the type of this variable object
19568 @item @code{-var-info-expression}
19569 @tab print what this variable object represents
19570 @item @code{-var-show-attributes}
19571 @tab is this variable editable? does it exist here?
19572 @item @code{-var-evaluate-expression}
19573 @tab get the value of this variable
19574 @item @code{-var-assign}
19575 @tab set the value of this variable
19576 @item @code{-var-update}
19577 @tab update the variable and its children
19578 @end multitable
19579
19580 In the next subsection we describe each operation in detail and suggest
19581 how it can be used.
19582
19583 @subheading Description And Use of Operations on Variable Objects
19584
19585 @subheading The @code{-var-create} Command
19586 @findex -var-create
19587
19588 @subsubheading Synopsis
19589
19590 @smallexample
19591 -var-create @{@var{name} | "-"@}
19592 @{@var{frame-addr} | "*"@} @var{expression}
19593 @end smallexample
19594
19595 This operation creates a variable object, which allows the monitoring of
19596 a variable, the result of an expression, a memory cell or a CPU
19597 register.
19598
19599 The @var{name} parameter is the string by which the object can be
19600 referenced. It must be unique. If @samp{-} is specified, the varobj
19601 system will generate a string ``varNNNNNN'' automatically. It will be
19602 unique provided that one does not specify @var{name} on that format.
19603 The command fails if a duplicate name is found.
19604
19605 The frame under which the expression should be evaluated can be
19606 specified by @var{frame-addr}. A @samp{*} indicates that the current
19607 frame should be used.
19608
19609 @var{expression} is any expression valid on the current language set (must not
19610 begin with a @samp{*}), or one of the following:
19611
19612 @itemize @bullet
19613 @item
19614 @samp{*@var{addr}}, where @var{addr} is the address of a memory cell
19615
19616 @item
19617 @samp{*@var{addr}-@var{addr}} --- a memory address range (TBD)
19618
19619 @item
19620 @samp{$@var{regname}} --- a CPU register name
19621 @end itemize
19622
19623 @subsubheading Result
19624
19625 This operation returns the name, number of children and the type of the
19626 object created. Type is returned as a string as the ones generated by
19627 the @value{GDBN} CLI:
19628
19629 @smallexample
19630 name="@var{name}",numchild="N",type="@var{type}"
19631 @end smallexample
19632
19633
19634 @subheading The @code{-var-delete} Command
19635 @findex -var-delete
19636
19637 @subsubheading Synopsis
19638
19639 @smallexample
19640 -var-delete @var{name}
19641 @end smallexample
19642
19643 Deletes a previously created variable object and all of its children.
19644
19645 Returns an error if the object @var{name} is not found.
19646
19647
19648 @subheading The @code{-var-set-format} Command
19649 @findex -var-set-format
19650
19651 @subsubheading Synopsis
19652
19653 @smallexample
19654 -var-set-format @var{name} @var{format-spec}
19655 @end smallexample
19656
19657 Sets the output format for the value of the object @var{name} to be
19658 @var{format-spec}.
19659
19660 The syntax for the @var{format-spec} is as follows:
19661
19662 @smallexample
19663 @var{format-spec} @expansion{}
19664 @{binary | decimal | hexadecimal | octal | natural@}
19665 @end smallexample
19666
19667
19668 @subheading The @code{-var-show-format} Command
19669 @findex -var-show-format
19670
19671 @subsubheading Synopsis
19672
19673 @smallexample
19674 -var-show-format @var{name}
19675 @end smallexample
19676
19677 Returns the format used to display the value of the object @var{name}.
19678
19679 @smallexample
19680 @var{format} @expansion{}
19681 @var{format-spec}
19682 @end smallexample
19683
19684
19685 @subheading The @code{-var-info-num-children} Command
19686 @findex -var-info-num-children
19687
19688 @subsubheading Synopsis
19689
19690 @smallexample
19691 -var-info-num-children @var{name}
19692 @end smallexample
19693
19694 Returns the number of children of a variable object @var{name}:
19695
19696 @smallexample
19697 numchild=@var{n}
19698 @end smallexample
19699
19700
19701 @subheading The @code{-var-list-children} Command
19702 @findex -var-list-children
19703
19704 @subsubheading Synopsis
19705
19706 @smallexample
19707 -var-list-children [@var{print-values}] @var{name}
19708 @end smallexample
19709 @anchor{-var-list-children}
19710
19711 Return a list of the children of the specified variable object and
19712 create variable objects for them, if they do not already exist. With
19713 a single argument or if @var{print-values} has a value for of 0 or
19714 @code{--no-values}, print only the names of the variables; if
19715 @var{print-values} is 1 or @code{--all-values}, also print their
19716 values; and if it is 2 or @code{--simple-values} print the name and
19717 value for simple data types and just the name for arrays, structures
19718 and unions.
19719
19720 @subsubheading Example
19721
19722 @smallexample
19723 (gdb)
19724 -var-list-children n
19725 ^done,numchild=@var{n},children=[@{name=@var{name},
19726 numchild=@var{n},type=@var{type}@},@r{(repeats N times)}]
19727 (gdb)
19728 -var-list-children --all-values n
19729 ^done,numchild=@var{n},children=[@{name=@var{name},
19730 numchild=@var{n},value=@var{value},type=@var{type}@},@r{(repeats N times)}]
19731 @end smallexample
19732
19733
19734 @subheading The @code{-var-info-type} Command
19735 @findex -var-info-type
19736
19737 @subsubheading Synopsis
19738
19739 @smallexample
19740 -var-info-type @var{name}
19741 @end smallexample
19742
19743 Returns the type of the specified variable @var{name}. The type is
19744 returned as a string in the same format as it is output by the
19745 @value{GDBN} CLI:
19746
19747 @smallexample
19748 type=@var{typename}
19749 @end smallexample
19750
19751
19752 @subheading The @code{-var-info-expression} Command
19753 @findex -var-info-expression
19754
19755 @subsubheading Synopsis
19756
19757 @smallexample
19758 -var-info-expression @var{name}
19759 @end smallexample
19760
19761 Returns what is represented by the variable object @var{name}:
19762
19763 @smallexample
19764 lang=@var{lang-spec},exp=@var{expression}
19765 @end smallexample
19766
19767 @noindent
19768 where @var{lang-spec} is @code{@{"C" | "C++" | "Java"@}}.
19769
19770 @subheading The @code{-var-show-attributes} Command
19771 @findex -var-show-attributes
19772
19773 @subsubheading Synopsis
19774
19775 @smallexample
19776 -var-show-attributes @var{name}
19777 @end smallexample
19778
19779 List attributes of the specified variable object @var{name}:
19780
19781 @smallexample
19782 status=@var{attr} [ ( ,@var{attr} )* ]
19783 @end smallexample
19784
19785 @noindent
19786 where @var{attr} is @code{@{ @{ editable | noneditable @} | TBD @}}.
19787
19788 @subheading The @code{-var-evaluate-expression} Command
19789 @findex -var-evaluate-expression
19790
19791 @subsubheading Synopsis
19792
19793 @smallexample
19794 -var-evaluate-expression @var{name}
19795 @end smallexample
19796
19797 Evaluates the expression that is represented by the specified variable
19798 object and returns its value as a string in the current format specified
19799 for the object:
19800
19801 @smallexample
19802 value=@var{value}
19803 @end smallexample
19804
19805 Note that one must invoke @code{-var-list-children} for a variable
19806 before the value of a child variable can be evaluated.
19807
19808 @subheading The @code{-var-assign} Command
19809 @findex -var-assign
19810
19811 @subsubheading Synopsis
19812
19813 @smallexample
19814 -var-assign @var{name} @var{expression}
19815 @end smallexample
19816
19817 Assigns the value of @var{expression} to the variable object specified
19818 by @var{name}. The object must be @samp{editable}. If the variable's
19819 value is altered by the assign, the variable will show up in any
19820 subsequent @code{-var-update} list.
19821
19822 @subsubheading Example
19823
19824 @smallexample
19825 (gdb)
19826 -var-assign var1 3
19827 ^done,value="3"
19828 (gdb)
19829 -var-update *
19830 ^done,changelist=[@{name="var1",in_scope="true",type_changed="false"@}]
19831 (gdb)
19832 @end smallexample
19833
19834 @subheading The @code{-var-update} Command
19835 @findex -var-update
19836
19837 @subsubheading Synopsis
19838
19839 @smallexample
19840 -var-update [@var{print-values}] @{@var{name} | "*"@}
19841 @end smallexample
19842
19843 Update the value of the variable object @var{name} by evaluating its
19844 expression after fetching all the new values from memory or registers.
19845 A @samp{*} causes all existing variable objects to be updated. The
19846 option @var{print-values} determines whether names both and values, or
19847 just names are printed in the manner described for
19848 @code{-var-list-children} (@pxref{-var-list-children}).
19849
19850 @subsubheading Example
19851
19852 @smallexample
19853 (gdb)
19854 -var-assign var1 3
19855 ^done,value="3"
19856 (gdb)
19857 -var-update --all-values var1
19858 ^done,changelist=[@{name="var1",value="3",in_scope="true",
19859 type_changed="false"@}]
19860 (gdb)
19861 @end smallexample
19862
19863 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
19864 @node GDB/MI Data Manipulation
19865 @section @sc{gdb/mi} Data Manipulation
19866
19867 @cindex data manipulation, in @sc{gdb/mi}
19868 @cindex @sc{gdb/mi}, data manipulation
19869 This section describes the @sc{gdb/mi} commands that manipulate data:
19870 examine memory and registers, evaluate expressions, etc.
19871
19872 @c REMOVED FROM THE INTERFACE.
19873 @c @subheading -data-assign
19874 @c Change the value of a program variable. Plenty of side effects.
19875 @c @subsubheading GDB command
19876 @c set variable
19877 @c @subsubheading Example
19878 @c N.A.
19879
19880 @subheading The @code{-data-disassemble} Command
19881 @findex -data-disassemble
19882
19883 @subsubheading Synopsis
19884
19885 @smallexample
19886 -data-disassemble
19887 [ -s @var{start-addr} -e @var{end-addr} ]
19888 | [ -f @var{filename} -l @var{linenum} [ -n @var{lines} ] ]
19889 -- @var{mode}
19890 @end smallexample
19891
19892 @noindent
19893 Where:
19894
19895 @table @samp
19896 @item @var{start-addr}
19897 is the beginning address (or @code{$pc})
19898 @item @var{end-addr}
19899 is the end address
19900 @item @var{filename}
19901 is the name of the file to disassemble
19902 @item @var{linenum}
19903 is the line number to disassemble around
19904 @item @var{lines}
19905 is the the number of disassembly lines to be produced. If it is -1,
19906 the whole function will be disassembled, in case no @var{end-addr} is
19907 specified. If @var{end-addr} is specified as a non-zero value, and
19908 @var{lines} is lower than the number of disassembly lines between
19909 @var{start-addr} and @var{end-addr}, only @var{lines} lines are
19910 displayed; if @var{lines} is higher than the number of lines between
19911 @var{start-addr} and @var{end-addr}, only the lines up to @var{end-addr}
19912 are displayed.
19913 @item @var{mode}
19914 is either 0 (meaning only disassembly) or 1 (meaning mixed source and
19915 disassembly).
19916 @end table
19917
19918 @subsubheading Result
19919
19920 The output for each instruction is composed of four fields:
19921
19922 @itemize @bullet
19923 @item Address
19924 @item Func-name
19925 @item Offset
19926 @item Instruction
19927 @end itemize
19928
19929 Note that whatever included in the instruction field, is not manipulated
19930 directely by @sc{gdb/mi}, i.e. it is not possible to adjust its format.
19931
19932 @subsubheading @value{GDBN} Command
19933
19934 There's no direct mapping from this command to the CLI.
19935
19936 @subsubheading Example
19937
19938 Disassemble from the current value of @code{$pc} to @code{$pc + 20}:
19939
19940 @smallexample
19941 (gdb)
19942 -data-disassemble -s $pc -e "$pc + 20" -- 0
19943 ^done,
19944 asm_insns=[
19945 @{address="0x000107c0",func-name="main",offset="4",
19946 inst="mov 2, %o0"@},
19947 @{address="0x000107c4",func-name="main",offset="8",
19948 inst="sethi %hi(0x11800), %o2"@},
19949 @{address="0x000107c8",func-name="main",offset="12",
19950 inst="or %o2, 0x140, %o1\t! 0x11940 <_lib_version+8>"@},
19951 @{address="0x000107cc",func-name="main",offset="16",
19952 inst="sethi %hi(0x11800), %o2"@},
19953 @{address="0x000107d0",func-name="main",offset="20",
19954 inst="or %o2, 0x168, %o4\t! 0x11968 <_lib_version+48>"@}]
19955 (gdb)
19956 @end smallexample
19957
19958 Disassemble the whole @code{main} function. Line 32 is part of
19959 @code{main}.
19960
19961 @smallexample
19962 -data-disassemble -f basics.c -l 32 -- 0
19963 ^done,asm_insns=[
19964 @{address="0x000107bc",func-name="main",offset="0",
19965 inst="save %sp, -112, %sp"@},
19966 @{address="0x000107c0",func-name="main",offset="4",
19967 inst="mov 2, %o0"@},
19968 @{address="0x000107c4",func-name="main",offset="8",
19969 inst="sethi %hi(0x11800), %o2"@},
19970 [@dots{}]
19971 @{address="0x0001081c",func-name="main",offset="96",inst="ret "@},
19972 @{address="0x00010820",func-name="main",offset="100",inst="restore "@}]
19973 (gdb)
19974 @end smallexample
19975
19976 Disassemble 3 instructions from the start of @code{main}:
19977
19978 @smallexample
19979 (gdb)
19980 -data-disassemble -f basics.c -l 32 -n 3 -- 0
19981 ^done,asm_insns=[
19982 @{address="0x000107bc",func-name="main",offset="0",
19983 inst="save %sp, -112, %sp"@},
19984 @{address="0x000107c0",func-name="main",offset="4",
19985 inst="mov 2, %o0"@},
19986 @{address="0x000107c4",func-name="main",offset="8",
19987 inst="sethi %hi(0x11800), %o2"@}]
19988 (gdb)
19989 @end smallexample
19990
19991 Disassemble 3 instructions from the start of @code{main} in mixed mode:
19992
19993 @smallexample
19994 (gdb)
19995 -data-disassemble -f basics.c -l 32 -n 3 -- 1
19996 ^done,asm_insns=[
19997 src_and_asm_line=@{line="31",
19998 file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \
19999 testsuite/gdb.mi/basics.c",line_asm_insn=[
20000 @{address="0x000107bc",func-name="main",offset="0",
20001 inst="save %sp, -112, %sp"@}]@},
20002 src_and_asm_line=@{line="32",
20003 file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \
20004 testsuite/gdb.mi/basics.c",line_asm_insn=[
20005 @{address="0x000107c0",func-name="main",offset="4",
20006 inst="mov 2, %o0"@},
20007 @{address="0x000107c4",func-name="main",offset="8",
20008 inst="sethi %hi(0x11800), %o2"@}]@}]
20009 (gdb)
20010 @end smallexample
20011
20012
20013 @subheading The @code{-data-evaluate-expression} Command
20014 @findex -data-evaluate-expression
20015
20016 @subsubheading Synopsis
20017
20018 @smallexample
20019 -data-evaluate-expression @var{expr}
20020 @end smallexample
20021
20022 Evaluate @var{expr} as an expression. The expression could contain an
20023 inferior function call. The function call will execute synchronously.
20024 If the expression contains spaces, it must be enclosed in double quotes.
20025
20026 @subsubheading @value{GDBN} Command
20027
20028 The corresponding @value{GDBN} commands are @samp{print}, @samp{output}, and
20029 @samp{call}. In @code{gdbtk} only, there's a corresponding
20030 @samp{gdb_eval} command.
20031
20032 @subsubheading Example
20033
20034 In the following example, the numbers that precede the commands are the
20035 @dfn{tokens} described in @ref{GDB/MI Command Syntax, ,@sc{gdb/mi}
20036 Command Syntax}. Notice how @sc{gdb/mi} returns the same tokens in its
20037 output.
20038
20039 @smallexample
20040 211-data-evaluate-expression A
20041 211^done,value="1"
20042 (gdb)
20043 311-data-evaluate-expression &A
20044 311^done,value="0xefffeb7c"
20045 (gdb)
20046 411-data-evaluate-expression A+3
20047 411^done,value="4"
20048 (gdb)
20049 511-data-evaluate-expression "A + 3"
20050 511^done,value="4"
20051 (gdb)
20052 @end smallexample
20053
20054
20055 @subheading The @code{-data-list-changed-registers} Command
20056 @findex -data-list-changed-registers
20057
20058 @subsubheading Synopsis
20059
20060 @smallexample
20061 -data-list-changed-registers
20062 @end smallexample
20063
20064 Display a list of the registers that have changed.
20065
20066 @subsubheading @value{GDBN} Command
20067
20068 @value{GDBN} doesn't have a direct analog for this command; @code{gdbtk}
20069 has the corresponding command @samp{gdb_changed_register_list}.
20070
20071 @subsubheading Example
20072
20073 On a PPC MBX board:
20074
20075 @smallexample
20076 (gdb)
20077 -exec-continue
20078 ^running
20079
20080 (gdb)
20081 *stopped,reason="breakpoint-hit",bkptno="1",frame=@{func="main",
20082 args=[],file="try.c",fullname="/home/foo/bar/try.c",line="5"@}
20083 (gdb)
20084 -data-list-changed-registers
20085 ^done,changed-registers=["0","1","2","4","5","6","7","8","9",
20086 "10","11","13","14","15","16","17","18","19","20","21","22","23",
20087 "24","25","26","27","28","30","31","64","65","66","67","69"]
20088 (gdb)
20089 @end smallexample
20090
20091
20092 @subheading The @code{-data-list-register-names} Command
20093 @findex -data-list-register-names
20094
20095 @subsubheading Synopsis
20096
20097 @smallexample
20098 -data-list-register-names [ ( @var{regno} )+ ]
20099 @end smallexample
20100
20101 Show a list of register names for the current target. If no arguments
20102 are given, it shows a list of the names of all the registers. If
20103 integer numbers are given as arguments, it will print a list of the
20104 names of the registers corresponding to the arguments. To ensure
20105 consistency between a register name and its number, the output list may
20106 include empty register names.
20107
20108 @subsubheading @value{GDBN} Command
20109
20110 @value{GDBN} does not have a command which corresponds to
20111 @samp{-data-list-register-names}. In @code{gdbtk} there is a
20112 corresponding command @samp{gdb_regnames}.
20113
20114 @subsubheading Example
20115
20116 For the PPC MBX board:
20117 @smallexample
20118 (gdb)
20119 -data-list-register-names
20120 ^done,register-names=["r0","r1","r2","r3","r4","r5","r6","r7",
20121 "r8","r9","r10","r11","r12","r13","r14","r15","r16","r17","r18",
20122 "r19","r20","r21","r22","r23","r24","r25","r26","r27","r28","r29",
20123 "r30","r31","f0","f1","f2","f3","f4","f5","f6","f7","f8","f9",
20124 "f10","f11","f12","f13","f14","f15","f16","f17","f18","f19","f20",
20125 "f21","f22","f23","f24","f25","f26","f27","f28","f29","f30","f31",
20126 "", "pc","ps","cr","lr","ctr","xer"]
20127 (gdb)
20128 -data-list-register-names 1 2 3
20129 ^done,register-names=["r1","r2","r3"]
20130 (gdb)
20131 @end smallexample
20132
20133 @subheading The @code{-data-list-register-values} Command
20134 @findex -data-list-register-values
20135
20136 @subsubheading Synopsis
20137
20138 @smallexample
20139 -data-list-register-values @var{fmt} [ ( @var{regno} )*]
20140 @end smallexample
20141
20142 Display the registers' contents. @var{fmt} is the format according to
20143 which the registers' contents are to be returned, followed by an optional
20144 list of numbers specifying the registers to display. A missing list of
20145 numbers indicates that the contents of all the registers must be returned.
20146
20147 Allowed formats for @var{fmt} are:
20148
20149 @table @code
20150 @item x
20151 Hexadecimal
20152 @item o
20153 Octal
20154 @item t
20155 Binary
20156 @item d
20157 Decimal
20158 @item r
20159 Raw
20160 @item N
20161 Natural
20162 @end table
20163
20164 @subsubheading @value{GDBN} Command
20165
20166 The corresponding @value{GDBN} commands are @samp{info reg}, @samp{info
20167 all-reg}, and (in @code{gdbtk}) @samp{gdb_fetch_registers}.
20168
20169 @subsubheading Example
20170
20171 For a PPC MBX board (note: line breaks are for readability only, they
20172 don't appear in the actual output):
20173
20174 @smallexample
20175 (gdb)
20176 -data-list-register-values r 64 65
20177 ^done,register-values=[@{number="64",value="0xfe00a300"@},
20178 @{number="65",value="0x00029002"@}]
20179 (gdb)
20180 -data-list-register-values x
20181 ^done,register-values=[@{number="0",value="0xfe0043c8"@},
20182 @{number="1",value="0x3fff88"@},@{number="2",value="0xfffffffe"@},
20183 @{number="3",value="0x0"@},@{number="4",value="0xa"@},
20184 @{number="5",value="0x3fff68"@},@{number="6",value="0x3fff58"@},
20185 @{number="7",value="0xfe011e98"@},@{number="8",value="0x2"@},
20186 @{number="9",value="0xfa202820"@},@{number="10",value="0xfa202808"@},
20187 @{number="11",value="0x1"@},@{number="12",value="0x0"@},
20188 @{number="13",value="0x4544"@},@{number="14",value="0xffdfffff"@},
20189 @{number="15",value="0xffffffff"@},@{number="16",value="0xfffffeff"@},
20190 @{number="17",value="0xefffffed"@},@{number="18",value="0xfffffffe"@},
20191 @{number="19",value="0xffffffff"@},@{number="20",value="0xffffffff"@},
20192 @{number="21",value="0xffffffff"@},@{number="22",value="0xfffffff7"@},
20193 @{number="23",value="0xffffffff"@},@{number="24",value="0xffffffff"@},
20194 @{number="25",value="0xffffffff"@},@{number="26",value="0xfffffffb"@},
20195 @{number="27",value="0xffffffff"@},@{number="28",value="0xf7bfffff"@},
20196 @{number="29",value="0x0"@},@{number="30",value="0xfe010000"@},
20197 @{number="31",value="0x0"@},@{number="32",value="0x0"@},
20198 @{number="33",value="0x0"@},@{number="34",value="0x0"@},
20199 @{number="35",value="0x0"@},@{number="36",value="0x0"@},
20200 @{number="37",value="0x0"@},@{number="38",value="0x0"@},
20201 @{number="39",value="0x0"@},@{number="40",value="0x0"@},
20202 @{number="41",value="0x0"@},@{number="42",value="0x0"@},
20203 @{number="43",value="0x0"@},@{number="44",value="0x0"@},
20204 @{number="45",value="0x0"@},@{number="46",value="0x0"@},
20205 @{number="47",value="0x0"@},@{number="48",value="0x0"@},
20206 @{number="49",value="0x0"@},@{number="50",value="0x0"@},
20207 @{number="51",value="0x0"@},@{number="52",value="0x0"@},
20208 @{number="53",value="0x0"@},@{number="54",value="0x0"@},
20209 @{number="55",value="0x0"@},@{number="56",value="0x0"@},
20210 @{number="57",value="0x0"@},@{number="58",value="0x0"@},
20211 @{number="59",value="0x0"@},@{number="60",value="0x0"@},
20212 @{number="61",value="0x0"@},@{number="62",value="0x0"@},
20213 @{number="63",value="0x0"@},@{number="64",value="0xfe00a300"@},
20214 @{number="65",value="0x29002"@},@{number="66",value="0x202f04b5"@},
20215 @{number="67",value="0xfe0043b0"@},@{number="68",value="0xfe00b3e4"@},
20216 @{number="69",value="0x20002b03"@}]
20217 (gdb)
20218 @end smallexample
20219
20220
20221 @subheading The @code{-data-read-memory} Command
20222 @findex -data-read-memory
20223
20224 @subsubheading Synopsis
20225
20226 @smallexample
20227 -data-read-memory [ -o @var{byte-offset} ]
20228 @var{address} @var{word-format} @var{word-size}
20229 @var{nr-rows} @var{nr-cols} [ @var{aschar} ]
20230 @end smallexample
20231
20232 @noindent
20233 where:
20234
20235 @table @samp
20236 @item @var{address}
20237 An expression specifying the address of the first memory word to be
20238 read. Complex expressions containing embedded white space should be
20239 quoted using the C convention.
20240
20241 @item @var{word-format}
20242 The format to be used to print the memory words. The notation is the
20243 same as for @value{GDBN}'s @code{print} command (@pxref{Output Formats,
20244 ,Output formats}).
20245
20246 @item @var{word-size}
20247 The size of each memory word in bytes.
20248
20249 @item @var{nr-rows}
20250 The number of rows in the output table.
20251
20252 @item @var{nr-cols}
20253 The number of columns in the output table.
20254
20255 @item @var{aschar}
20256 If present, indicates that each row should include an @sc{ascii} dump. The
20257 value of @var{aschar} is used as a padding character when a byte is not a
20258 member of the printable @sc{ascii} character set (printable @sc{ascii}
20259 characters are those whose code is between 32 and 126, inclusively).
20260
20261 @item @var{byte-offset}
20262 An offset to add to the @var{address} before fetching memory.
20263 @end table
20264
20265 This command displays memory contents as a table of @var{nr-rows} by
20266 @var{nr-cols} words, each word being @var{word-size} bytes. In total,
20267 @code{@var{nr-rows} * @var{nr-cols} * @var{word-size}} bytes are read
20268 (returned as @samp{total-bytes}). Should less than the requested number
20269 of bytes be returned by the target, the missing words are identified
20270 using @samp{N/A}. The number of bytes read from the target is returned
20271 in @samp{nr-bytes} and the starting address used to read memory in
20272 @samp{addr}.
20273
20274 The address of the next/previous row or page is available in
20275 @samp{next-row} and @samp{prev-row}, @samp{next-page} and
20276 @samp{prev-page}.
20277
20278 @subsubheading @value{GDBN} Command
20279
20280 The corresponding @value{GDBN} command is @samp{x}. @code{gdbtk} has
20281 @samp{gdb_get_mem} memory read command.
20282
20283 @subsubheading Example
20284
20285 Read six bytes of memory starting at @code{bytes+6} but then offset by
20286 @code{-6} bytes. Format as three rows of two columns. One byte per
20287 word. Display each word in hex.
20288
20289 @smallexample
20290 (gdb)
20291 9-data-read-memory -o -6 -- bytes+6 x 1 3 2
20292 9^done,addr="0x00001390",nr-bytes="6",total-bytes="6",
20293 next-row="0x00001396",prev-row="0x0000138e",next-page="0x00001396",
20294 prev-page="0x0000138a",memory=[
20295 @{addr="0x00001390",data=["0x00","0x01"]@},
20296 @{addr="0x00001392",data=["0x02","0x03"]@},
20297 @{addr="0x00001394",data=["0x04","0x05"]@}]
20298 (gdb)
20299 @end smallexample
20300
20301 Read two bytes of memory starting at address @code{shorts + 64} and
20302 display as a single word formatted in decimal.
20303
20304 @smallexample
20305 (gdb)
20306 5-data-read-memory shorts+64 d 2 1 1
20307 5^done,addr="0x00001510",nr-bytes="2",total-bytes="2",
20308 next-row="0x00001512",prev-row="0x0000150e",
20309 next-page="0x00001512",prev-page="0x0000150e",memory=[
20310 @{addr="0x00001510",data=["128"]@}]
20311 (gdb)
20312 @end smallexample
20313
20314 Read thirty two bytes of memory starting at @code{bytes+16} and format
20315 as eight rows of four columns. Include a string encoding with @samp{x}
20316 used as the non-printable character.
20317
20318 @smallexample
20319 (gdb)
20320 4-data-read-memory bytes+16 x 1 8 4 x
20321 4^done,addr="0x000013a0",nr-bytes="32",total-bytes="32",
20322 next-row="0x000013c0",prev-row="0x0000139c",
20323 next-page="0x000013c0",prev-page="0x00001380",memory=[
20324 @{addr="0x000013a0",data=["0x10","0x11","0x12","0x13"],ascii="xxxx"@},
20325 @{addr="0x000013a4",data=["0x14","0x15","0x16","0x17"],ascii="xxxx"@},
20326 @{addr="0x000013a8",data=["0x18","0x19","0x1a","0x1b"],ascii="xxxx"@},
20327 @{addr="0x000013ac",data=["0x1c","0x1d","0x1e","0x1f"],ascii="xxxx"@},
20328 @{addr="0x000013b0",data=["0x20","0x21","0x22","0x23"],ascii=" !\"#"@},
20329 @{addr="0x000013b4",data=["0x24","0x25","0x26","0x27"],ascii="$%&'"@},
20330 @{addr="0x000013b8",data=["0x28","0x29","0x2a","0x2b"],ascii="()*+"@},
20331 @{addr="0x000013bc",data=["0x2c","0x2d","0x2e","0x2f"],ascii=",-./"@}]
20332 (gdb)
20333 @end smallexample
20334
20335 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
20336 @node GDB/MI Tracepoint Commands
20337 @section @sc{gdb/mi} Tracepoint Commands
20338
20339 The tracepoint commands are not yet implemented.
20340
20341 @c @subheading -trace-actions
20342
20343 @c @subheading -trace-delete
20344
20345 @c @subheading -trace-disable
20346
20347 @c @subheading -trace-dump
20348
20349 @c @subheading -trace-enable
20350
20351 @c @subheading -trace-exists
20352
20353 @c @subheading -trace-find
20354
20355 @c @subheading -trace-frame-number
20356
20357 @c @subheading -trace-info
20358
20359 @c @subheading -trace-insert
20360
20361 @c @subheading -trace-list
20362
20363 @c @subheading -trace-pass-count
20364
20365 @c @subheading -trace-save
20366
20367 @c @subheading -trace-start
20368
20369 @c @subheading -trace-stop
20370
20371
20372 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
20373 @node GDB/MI Symbol Query
20374 @section @sc{gdb/mi} Symbol Query Commands
20375
20376
20377 @subheading The @code{-symbol-info-address} Command
20378 @findex -symbol-info-address
20379
20380 @subsubheading Synopsis
20381
20382 @smallexample
20383 -symbol-info-address @var{symbol}
20384 @end smallexample
20385
20386 Describe where @var{symbol} is stored.
20387
20388 @subsubheading @value{GDBN} Command
20389
20390 The corresponding @value{GDBN} command is @samp{info address}.
20391
20392 @subsubheading Example
20393 N.A.
20394
20395
20396 @subheading The @code{-symbol-info-file} Command
20397 @findex -symbol-info-file
20398
20399 @subsubheading Synopsis
20400
20401 @smallexample
20402 -symbol-info-file
20403 @end smallexample
20404
20405 Show the file for the symbol.
20406
20407 @subsubheading @value{GDBN} Command
20408
20409 There's no equivalent @value{GDBN} command. @code{gdbtk} has
20410 @samp{gdb_find_file}.
20411
20412 @subsubheading Example
20413 N.A.
20414
20415
20416 @subheading The @code{-symbol-info-function} Command
20417 @findex -symbol-info-function
20418
20419 @subsubheading Synopsis
20420
20421 @smallexample
20422 -symbol-info-function
20423 @end smallexample
20424
20425 Show which function the symbol lives in.
20426
20427 @subsubheading @value{GDBN} Command
20428
20429 @samp{gdb_get_function} in @code{gdbtk}.
20430
20431 @subsubheading Example
20432 N.A.
20433
20434
20435 @subheading The @code{-symbol-info-line} Command
20436 @findex -symbol-info-line
20437
20438 @subsubheading Synopsis
20439
20440 @smallexample
20441 -symbol-info-line
20442 @end smallexample
20443
20444 Show the core addresses of the code for a source line.
20445
20446 @subsubheading @value{GDBN} Command
20447
20448 The corresponding @value{GDBN} command is @samp{info line}.
20449 @code{gdbtk} has the @samp{gdb_get_line} and @samp{gdb_get_file} commands.
20450
20451 @subsubheading Example
20452 N.A.
20453
20454
20455 @subheading The @code{-symbol-info-symbol} Command
20456 @findex -symbol-info-symbol
20457
20458 @subsubheading Synopsis
20459
20460 @smallexample
20461 -symbol-info-symbol @var{addr}
20462 @end smallexample
20463
20464 Describe what symbol is at location @var{addr}.
20465
20466 @subsubheading @value{GDBN} Command
20467
20468 The corresponding @value{GDBN} command is @samp{info symbol}.
20469
20470 @subsubheading Example
20471 N.A.
20472
20473
20474 @subheading The @code{-symbol-list-functions} Command
20475 @findex -symbol-list-functions
20476
20477 @subsubheading Synopsis
20478
20479 @smallexample
20480 -symbol-list-functions
20481 @end smallexample
20482
20483 List the functions in the executable.
20484
20485 @subsubheading @value{GDBN} Command
20486
20487 @samp{info functions} in @value{GDBN}, @samp{gdb_listfunc} and
20488 @samp{gdb_search} in @code{gdbtk}.
20489
20490 @subsubheading Example
20491 N.A.
20492
20493
20494 @subheading The @code{-symbol-list-lines} Command
20495 @findex -symbol-list-lines
20496
20497 @subsubheading Synopsis
20498
20499 @smallexample
20500 -symbol-list-lines @var{filename}
20501 @end smallexample
20502
20503 Print the list of lines that contain code and their associated program
20504 addresses for the given source filename. The entries are sorted in
20505 ascending PC order.
20506
20507 @subsubheading @value{GDBN} Command
20508
20509 There is no corresponding @value{GDBN} command.
20510
20511 @subsubheading Example
20512 @smallexample
20513 (gdb)
20514 -symbol-list-lines basics.c
20515 ^done,lines=[@{pc="0x08048554",line="7"@},@{pc="0x0804855a",line="8"@}]
20516 (gdb)
20517 @end smallexample
20518
20519
20520 @subheading The @code{-symbol-list-types} Command
20521 @findex -symbol-list-types
20522
20523 @subsubheading Synopsis
20524
20525 @smallexample
20526 -symbol-list-types
20527 @end smallexample
20528
20529 List all the type names.
20530
20531 @subsubheading @value{GDBN} Command
20532
20533 The corresponding commands are @samp{info types} in @value{GDBN},
20534 @samp{gdb_search} in @code{gdbtk}.
20535
20536 @subsubheading Example
20537 N.A.
20538
20539
20540 @subheading The @code{-symbol-list-variables} Command
20541 @findex -symbol-list-variables
20542
20543 @subsubheading Synopsis
20544
20545 @smallexample
20546 -symbol-list-variables
20547 @end smallexample
20548
20549 List all the global and static variable names.
20550
20551 @subsubheading @value{GDBN} Command
20552
20553 @samp{info variables} in @value{GDBN}, @samp{gdb_search} in @code{gdbtk}.
20554
20555 @subsubheading Example
20556 N.A.
20557
20558
20559 @subheading The @code{-symbol-locate} Command
20560 @findex -symbol-locate
20561
20562 @subsubheading Synopsis
20563
20564 @smallexample
20565 -symbol-locate
20566 @end smallexample
20567
20568 @subsubheading @value{GDBN} Command
20569
20570 @samp{gdb_loc} in @code{gdbtk}.
20571
20572 @subsubheading Example
20573 N.A.
20574
20575
20576 @subheading The @code{-symbol-type} Command
20577 @findex -symbol-type
20578
20579 @subsubheading Synopsis
20580
20581 @smallexample
20582 -symbol-type @var{variable}
20583 @end smallexample
20584
20585 Show type of @var{variable}.
20586
20587 @subsubheading @value{GDBN} Command
20588
20589 The corresponding @value{GDBN} command is @samp{ptype}, @code{gdbtk} has
20590 @samp{gdb_obj_variable}.
20591
20592 @subsubheading Example
20593 N.A.
20594
20595
20596 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
20597 @node GDB/MI File Commands
20598 @section @sc{gdb/mi} File Commands
20599
20600 This section describes the GDB/MI commands to specify executable file names
20601 and to read in and obtain symbol table information.
20602
20603 @subheading The @code{-file-exec-and-symbols} Command
20604 @findex -file-exec-and-symbols
20605
20606 @subsubheading Synopsis
20607
20608 @smallexample
20609 -file-exec-and-symbols @var{file}
20610 @end smallexample
20611
20612 Specify the executable file to be debugged. This file is the one from
20613 which the symbol table is also read. If no file is specified, the
20614 command clears the executable and symbol information. If breakpoints
20615 are set when using this command with no arguments, @value{GDBN} will produce
20616 error messages. Otherwise, no output is produced, except a completion
20617 notification.
20618
20619 @subsubheading @value{GDBN} Command
20620
20621 The corresponding @value{GDBN} command is @samp{file}.
20622
20623 @subsubheading Example
20624
20625 @smallexample
20626 (gdb)
20627 -file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
20628 ^done
20629 (gdb)
20630 @end smallexample
20631
20632
20633 @subheading The @code{-file-exec-file} Command
20634 @findex -file-exec-file
20635
20636 @subsubheading Synopsis
20637
20638 @smallexample
20639 -file-exec-file @var{file}
20640 @end smallexample
20641
20642 Specify the executable file to be debugged. Unlike
20643 @samp{-file-exec-and-symbols}, the symbol table is @emph{not} read
20644 from this file. If used without argument, @value{GDBN} clears the information
20645 about the executable file. No output is produced, except a completion
20646 notification.
20647
20648 @subsubheading @value{GDBN} Command
20649
20650 The corresponding @value{GDBN} command is @samp{exec-file}.
20651
20652 @subsubheading Example
20653
20654 @smallexample
20655 (gdb)
20656 -file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
20657 ^done
20658 (gdb)
20659 @end smallexample
20660
20661
20662 @subheading The @code{-file-list-exec-sections} Command
20663 @findex -file-list-exec-sections
20664
20665 @subsubheading Synopsis
20666
20667 @smallexample
20668 -file-list-exec-sections
20669 @end smallexample
20670
20671 List the sections of the current executable file.
20672
20673 @subsubheading @value{GDBN} Command
20674
20675 The @value{GDBN} command @samp{info file} shows, among the rest, the same
20676 information as this command. @code{gdbtk} has a corresponding command
20677 @samp{gdb_load_info}.
20678
20679 @subsubheading Example
20680 N.A.
20681
20682
20683 @subheading The @code{-file-list-exec-source-file} Command
20684 @findex -file-list-exec-source-file
20685
20686 @subsubheading Synopsis
20687
20688 @smallexample
20689 -file-list-exec-source-file
20690 @end smallexample
20691
20692 List the line number, the current source file, and the absolute path
20693 to the current source file for the current executable.
20694
20695 @subsubheading @value{GDBN} Command
20696
20697 The @value{GDBN} equivalent is @samp{info source}
20698
20699 @subsubheading Example
20700
20701 @smallexample
20702 (gdb)
20703 123-file-list-exec-source-file
20704 123^done,line="1",file="foo.c",fullname="/home/bar/foo.c"
20705 (gdb)
20706 @end smallexample
20707
20708
20709 @subheading The @code{-file-list-exec-source-files} Command
20710 @findex -file-list-exec-source-files
20711
20712 @subsubheading Synopsis
20713
20714 @smallexample
20715 -file-list-exec-source-files
20716 @end smallexample
20717
20718 List the source files for the current executable.
20719
20720 It will always output the filename, but only when GDB can find the absolute
20721 file name of a source file, will it output the fullname.
20722
20723 @subsubheading @value{GDBN} Command
20724
20725 The @value{GDBN} equivalent is @samp{info sources}.
20726 @code{gdbtk} has an analogous command @samp{gdb_listfiles}.
20727
20728 @subsubheading Example
20729 @smallexample
20730 (gdb)
20731 -file-list-exec-source-files
20732 ^done,files=[
20733 @{file=foo.c,fullname=/home/foo.c@},
20734 @{file=/home/bar.c,fullname=/home/bar.c@},
20735 @{file=gdb_could_not_find_fullpath.c@}]
20736 (gdb)
20737 @end smallexample
20738
20739 @subheading The @code{-file-list-shared-libraries} Command
20740 @findex -file-list-shared-libraries
20741
20742 @subsubheading Synopsis
20743
20744 @smallexample
20745 -file-list-shared-libraries
20746 @end smallexample
20747
20748 List the shared libraries in the program.
20749
20750 @subsubheading @value{GDBN} Command
20751
20752 The corresponding @value{GDBN} command is @samp{info shared}.
20753
20754 @subsubheading Example
20755 N.A.
20756
20757
20758 @subheading The @code{-file-list-symbol-files} Command
20759 @findex -file-list-symbol-files
20760
20761 @subsubheading Synopsis
20762
20763 @smallexample
20764 -file-list-symbol-files
20765 @end smallexample
20766
20767 List symbol files.
20768
20769 @subsubheading @value{GDBN} Command
20770
20771 The corresponding @value{GDBN} command is @samp{info file} (part of it).
20772
20773 @subsubheading Example
20774 N.A.
20775
20776
20777 @subheading The @code{-file-symbol-file} Command
20778 @findex -file-symbol-file
20779
20780 @subsubheading Synopsis
20781
20782 @smallexample
20783 -file-symbol-file @var{file}
20784 @end smallexample
20785
20786 Read symbol table info from the specified @var{file} argument. When
20787 used without arguments, clears @value{GDBN}'s symbol table info. No output is
20788 produced, except for a completion notification.
20789
20790 @subsubheading @value{GDBN} Command
20791
20792 The corresponding @value{GDBN} command is @samp{symbol-file}.
20793
20794 @subsubheading Example
20795
20796 @smallexample
20797 (gdb)
20798 -file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx
20799 ^done
20800 (gdb)
20801 @end smallexample
20802
20803 @ignore
20804 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
20805 @node GDB/MI Memory Overlay Commands
20806 @section @sc{gdb/mi} Memory Overlay Commands
20807
20808 The memory overlay commands are not implemented.
20809
20810 @c @subheading -overlay-auto
20811
20812 @c @subheading -overlay-list-mapping-state
20813
20814 @c @subheading -overlay-list-overlays
20815
20816 @c @subheading -overlay-map
20817
20818 @c @subheading -overlay-off
20819
20820 @c @subheading -overlay-on
20821
20822 @c @subheading -overlay-unmap
20823
20824 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
20825 @node GDB/MI Signal Handling Commands
20826 @section @sc{gdb/mi} Signal Handling Commands
20827
20828 Signal handling commands are not implemented.
20829
20830 @c @subheading -signal-handle
20831
20832 @c @subheading -signal-list-handle-actions
20833
20834 @c @subheading -signal-list-signal-types
20835 @end ignore
20836
20837
20838 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
20839 @node GDB/MI Target Manipulation
20840 @section @sc{gdb/mi} Target Manipulation Commands
20841
20842
20843 @subheading The @code{-target-attach} Command
20844 @findex -target-attach
20845
20846 @subsubheading Synopsis
20847
20848 @smallexample
20849 -target-attach @var{pid} | @var{file}
20850 @end smallexample
20851
20852 Attach to a process @var{pid} or a file @var{file} outside of @value{GDBN}.
20853
20854 @subsubheading @value{GDBN} command
20855
20856 The corresponding @value{GDBN} command is @samp{attach}.
20857
20858 @subsubheading Example
20859 N.A.
20860
20861
20862 @subheading The @code{-target-compare-sections} Command
20863 @findex -target-compare-sections
20864
20865 @subsubheading Synopsis
20866
20867 @smallexample
20868 -target-compare-sections [ @var{section} ]
20869 @end smallexample
20870
20871 Compare data of section @var{section} on target to the exec file.
20872 Without the argument, all sections are compared.
20873
20874 @subsubheading @value{GDBN} Command
20875
20876 The @value{GDBN} equivalent is @samp{compare-sections}.
20877
20878 @subsubheading Example
20879 N.A.
20880
20881
20882 @subheading The @code{-target-detach} Command
20883 @findex -target-detach
20884
20885 @subsubheading Synopsis
20886
20887 @smallexample
20888 -target-detach
20889 @end smallexample
20890
20891 Detach from the remote target which normally resumes its execution.
20892 There's no output.
20893
20894 @subsubheading @value{GDBN} command
20895
20896 The corresponding @value{GDBN} command is @samp{detach}.
20897
20898 @subsubheading Example
20899
20900 @smallexample
20901 (gdb)
20902 -target-detach
20903 ^done
20904 (gdb)
20905 @end smallexample
20906
20907
20908 @subheading The @code{-target-disconnect} Command
20909 @findex -target-disconnect
20910
20911 @subsubheading Synopsis
20912
20913 @example
20914 -target-disconnect
20915 @end example
20916
20917 Disconnect from the remote target. There's no output and the target is
20918 generally not resumed.
20919
20920 @subsubheading @value{GDBN} command
20921
20922 The corresponding @value{GDBN} command is @samp{disconnect}.
20923
20924 @subsubheading Example
20925
20926 @smallexample
20927 (gdb)
20928 -target-disconnect
20929 ^done
20930 (gdb)
20931 @end smallexample
20932
20933
20934 @subheading The @code{-target-download} Command
20935 @findex -target-download
20936
20937 @subsubheading Synopsis
20938
20939 @smallexample
20940 -target-download
20941 @end smallexample
20942
20943 Loads the executable onto the remote target.
20944 It prints out an update message every half second, which includes the fields:
20945
20946 @table @samp
20947 @item section
20948 The name of the section.
20949 @item section-sent
20950 The size of what has been sent so far for that section.
20951 @item section-size
20952 The size of the section.
20953 @item total-sent
20954 The total size of what was sent so far (the current and the previous sections).
20955 @item total-size
20956 The size of the overall executable to download.
20957 @end table
20958
20959 @noindent
20960 Each message is sent as status record (@pxref{GDB/MI Output Syntax, ,
20961 @sc{gdb/mi} Output Syntax}).
20962
20963 In addition, it prints the name and size of the sections, as they are
20964 downloaded. These messages include the following fields:
20965
20966 @table @samp
20967 @item section
20968 The name of the section.
20969 @item section-size
20970 The size of the section.
20971 @item total-size
20972 The size of the overall executable to download.
20973 @end table
20974
20975 @noindent
20976 At the end, a summary is printed.
20977
20978 @subsubheading @value{GDBN} Command
20979
20980 The corresponding @value{GDBN} command is @samp{load}.
20981
20982 @subsubheading Example
20983
20984 Note: each status message appears on a single line. Here the messages
20985 have been broken down so that they can fit onto a page.
20986
20987 @smallexample
20988 (gdb)
20989 -target-download
20990 +download,@{section=".text",section-size="6668",total-size="9880"@}
20991 +download,@{section=".text",section-sent="512",section-size="6668",
20992 total-sent="512",total-size="9880"@}
20993 +download,@{section=".text",section-sent="1024",section-size="6668",
20994 total-sent="1024",total-size="9880"@}
20995 +download,@{section=".text",section-sent="1536",section-size="6668",
20996 total-sent="1536",total-size="9880"@}
20997 +download,@{section=".text",section-sent="2048",section-size="6668",
20998 total-sent="2048",total-size="9880"@}
20999 +download,@{section=".text",section-sent="2560",section-size="6668",
21000 total-sent="2560",total-size="9880"@}
21001 +download,@{section=".text",section-sent="3072",section-size="6668",
21002 total-sent="3072",total-size="9880"@}
21003 +download,@{section=".text",section-sent="3584",section-size="6668",
21004 total-sent="3584",total-size="9880"@}
21005 +download,@{section=".text",section-sent="4096",section-size="6668",
21006 total-sent="4096",total-size="9880"@}
21007 +download,@{section=".text",section-sent="4608",section-size="6668",
21008 total-sent="4608",total-size="9880"@}
21009 +download,@{section=".text",section-sent="5120",section-size="6668",
21010 total-sent="5120",total-size="9880"@}
21011 +download,@{section=".text",section-sent="5632",section-size="6668",
21012 total-sent="5632",total-size="9880"@}
21013 +download,@{section=".text",section-sent="6144",section-size="6668",
21014 total-sent="6144",total-size="9880"@}
21015 +download,@{section=".text",section-sent="6656",section-size="6668",
21016 total-sent="6656",total-size="9880"@}
21017 +download,@{section=".init",section-size="28",total-size="9880"@}
21018 +download,@{section=".fini",section-size="28",total-size="9880"@}
21019 +download,@{section=".data",section-size="3156",total-size="9880"@}
21020 +download,@{section=".data",section-sent="512",section-size="3156",
21021 total-sent="7236",total-size="9880"@}
21022 +download,@{section=".data",section-sent="1024",section-size="3156",
21023 total-sent="7748",total-size="9880"@}
21024 +download,@{section=".data",section-sent="1536",section-size="3156",
21025 total-sent="8260",total-size="9880"@}
21026 +download,@{section=".data",section-sent="2048",section-size="3156",
21027 total-sent="8772",total-size="9880"@}
21028 +download,@{section=".data",section-sent="2560",section-size="3156",
21029 total-sent="9284",total-size="9880"@}
21030 +download,@{section=".data",section-sent="3072",section-size="3156",
21031 total-sent="9796",total-size="9880"@}
21032 ^done,address="0x10004",load-size="9880",transfer-rate="6586",
21033 write-rate="429"
21034 (gdb)
21035 @end smallexample
21036
21037
21038 @subheading The @code{-target-exec-status} Command
21039 @findex -target-exec-status
21040
21041 @subsubheading Synopsis
21042
21043 @smallexample
21044 -target-exec-status
21045 @end smallexample
21046
21047 Provide information on the state of the target (whether it is running or
21048 not, for instance).
21049
21050 @subsubheading @value{GDBN} Command
21051
21052 There's no equivalent @value{GDBN} command.
21053
21054 @subsubheading Example
21055 N.A.
21056
21057
21058 @subheading The @code{-target-list-available-targets} Command
21059 @findex -target-list-available-targets
21060
21061 @subsubheading Synopsis
21062
21063 @smallexample
21064 -target-list-available-targets
21065 @end smallexample
21066
21067 List the possible targets to connect to.
21068
21069 @subsubheading @value{GDBN} Command
21070
21071 The corresponding @value{GDBN} command is @samp{help target}.
21072
21073 @subsubheading Example
21074 N.A.
21075
21076
21077 @subheading The @code{-target-list-current-targets} Command
21078 @findex -target-list-current-targets
21079
21080 @subsubheading Synopsis
21081
21082 @smallexample
21083 -target-list-current-targets
21084 @end smallexample
21085
21086 Describe the current target.
21087
21088 @subsubheading @value{GDBN} Command
21089
21090 The corresponding information is printed by @samp{info file} (among
21091 other things).
21092
21093 @subsubheading Example
21094 N.A.
21095
21096
21097 @subheading The @code{-target-list-parameters} Command
21098 @findex -target-list-parameters
21099
21100 @subsubheading Synopsis
21101
21102 @smallexample
21103 -target-list-parameters
21104 @end smallexample
21105
21106 @c ????
21107
21108 @subsubheading @value{GDBN} Command
21109
21110 No equivalent.
21111
21112 @subsubheading Example
21113 N.A.
21114
21115
21116 @subheading The @code{-target-select} Command
21117 @findex -target-select
21118
21119 @subsubheading Synopsis
21120
21121 @smallexample
21122 -target-select @var{type} @var{parameters @dots{}}
21123 @end smallexample
21124
21125 Connect @value{GDBN} to the remote target. This command takes two args:
21126
21127 @table @samp
21128 @item @var{type}
21129 The type of target, for instance @samp{async}, @samp{remote}, etc.
21130 @item @var{parameters}
21131 Device names, host names and the like. @xref{Target Commands, ,
21132 Commands for managing targets}, for more details.
21133 @end table
21134
21135 The output is a connection notification, followed by the address at
21136 which the target program is, in the following form:
21137
21138 @smallexample
21139 ^connected,addr="@var{address}",func="@var{function name}",
21140 args=[@var{arg list}]
21141 @end smallexample
21142
21143 @subsubheading @value{GDBN} Command
21144
21145 The corresponding @value{GDBN} command is @samp{target}.
21146
21147 @subsubheading Example
21148
21149 @smallexample
21150 (gdb)
21151 -target-select async /dev/ttya
21152 ^connected,addr="0xfe00a300",func="??",args=[]
21153 (gdb)
21154 @end smallexample
21155
21156 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
21157 @node GDB/MI Miscellaneous Commands
21158 @section Miscellaneous @sc{gdb/mi} Commands
21159
21160 @c @subheading -gdb-complete
21161
21162 @subheading The @code{-gdb-exit} Command
21163 @findex -gdb-exit
21164
21165 @subsubheading Synopsis
21166
21167 @smallexample
21168 -gdb-exit
21169 @end smallexample
21170
21171 Exit @value{GDBN} immediately.
21172
21173 @subsubheading @value{GDBN} Command
21174
21175 Approximately corresponds to @samp{quit}.
21176
21177 @subsubheading Example
21178
21179 @smallexample
21180 (gdb)
21181 -gdb-exit
21182 ^exit
21183 @end smallexample
21184
21185
21186 @subheading The @code{-exec-abort} Command
21187 @findex -exec-abort
21188
21189 @subsubheading Synopsis
21190
21191 @smallexample
21192 -exec-abort
21193 @end smallexample
21194
21195 Kill the inferior running program.
21196
21197 @subsubheading @value{GDBN} Command
21198
21199 The corresponding @value{GDBN} command is @samp{kill}.
21200
21201 @subsubheading Example
21202 N.A.
21203
21204
21205 @subheading The @code{-gdb-set} Command
21206 @findex -gdb-set
21207
21208 @subsubheading Synopsis
21209
21210 @smallexample
21211 -gdb-set
21212 @end smallexample
21213
21214 Set an internal @value{GDBN} variable.
21215 @c IS THIS A DOLLAR VARIABLE? OR SOMETHING LIKE ANNOTATE ?????
21216
21217 @subsubheading @value{GDBN} Command
21218
21219 The corresponding @value{GDBN} command is @samp{set}.
21220
21221 @subsubheading Example
21222
21223 @smallexample
21224 (gdb)
21225 -gdb-set $foo=3
21226 ^done
21227 (gdb)
21228 @end smallexample
21229
21230
21231 @subheading The @code{-gdb-show} Command
21232 @findex -gdb-show
21233
21234 @subsubheading Synopsis
21235
21236 @smallexample
21237 -gdb-show
21238 @end smallexample
21239
21240 Show the current value of a @value{GDBN} variable.
21241
21242 @subsubheading @value{GDBN} command
21243
21244 The corresponding @value{GDBN} command is @samp{show}.
21245
21246 @subsubheading Example
21247
21248 @smallexample
21249 (gdb)
21250 -gdb-show annotate
21251 ^done,value="0"
21252 (gdb)
21253 @end smallexample
21254
21255 @c @subheading -gdb-source
21256
21257
21258 @subheading The @code{-gdb-version} Command
21259 @findex -gdb-version
21260
21261 @subsubheading Synopsis
21262
21263 @smallexample
21264 -gdb-version
21265 @end smallexample
21266
21267 Show version information for @value{GDBN}. Used mostly in testing.
21268
21269 @subsubheading @value{GDBN} Command
21270
21271 The @value{GDBN} equivalent is @samp{show version}. @value{GDBN} by
21272 default shows this information when you start an interactive session.
21273
21274 @subsubheading Example
21275
21276 @c This example modifies the actual output from GDB to avoid overfull
21277 @c box in TeX.
21278 @smallexample
21279 (gdb)
21280 -gdb-version
21281 ~GNU gdb 5.2.1
21282 ~Copyright 2000 Free Software Foundation, Inc.
21283 ~GDB is free software, covered by the GNU General Public License, and
21284 ~you are welcome to change it and/or distribute copies of it under
21285 ~ certain conditions.
21286 ~Type "show copying" to see the conditions.
21287 ~There is absolutely no warranty for GDB. Type "show warranty" for
21288 ~ details.
21289 ~This GDB was configured as
21290 "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi".
21291 ^done
21292 (gdb)
21293 @end smallexample
21294
21295 @subheading The @code{-interpreter-exec} Command
21296 @findex -interpreter-exec
21297
21298 @subheading Synopsis
21299
21300 @smallexample
21301 -interpreter-exec @var{interpreter} @var{command}
21302 @end smallexample
21303 @anchor{-interpreter-exec}
21304
21305 Execute the specified @var{command} in the given @var{interpreter}.
21306
21307 @subheading @value{GDBN} Command
21308
21309 The corresponding @value{GDBN} command is @samp{interpreter-exec}.
21310
21311 @subheading Example
21312
21313 @smallexample
21314 (gdb)
21315 -interpreter-exec console "break main"
21316 &"During symbol reading, couldn't parse type; debugger out of date?.\n"
21317 &"During symbol reading, bad structure-type format.\n"
21318 ~"Breakpoint 1 at 0x8074fc6: file ../../src/gdb/main.c, line 743.\n"
21319 ^done
21320 (gdb)
21321 @end smallexample
21322
21323 @subheading The @code{-inferior-tty-set} Command
21324 @findex -inferior-tty-set
21325
21326 @subheading Synopsis
21327
21328 @smallexample
21329 -inferior-tty-set /dev/pts/1
21330 @end smallexample
21331
21332 Set terminal for future runs of the program being debugged.
21333
21334 @subheading @value{GDBN} Command
21335
21336 The corresponding @value{GDBN} command is @samp{set inferior-tty} /dev/pts/1.
21337
21338 @subheading Example
21339
21340 @smallexample
21341 (gdb)
21342 -inferior-tty-set /dev/pts/1
21343 ^done
21344 (gdb)
21345 @end smallexample
21346
21347 @subheading The @code{-inferior-tty-show} Command
21348 @findex -inferior-tty-show
21349
21350 @subheading Synopsis
21351
21352 @smallexample
21353 -inferior-tty-show
21354 @end smallexample
21355
21356 Show terminal for future runs of program being debugged.
21357
21358 @subheading @value{GDBN} Command
21359
21360 The corresponding @value{GDBN} command is @samp{show inferior-tty}.
21361
21362 @subheading Example
21363
21364 @smallexample
21365 (gdb)
21366 -inferior-tty-set /dev/pts/1
21367 ^done
21368 (gdb)
21369 -inferior-tty-show
21370 ^done,inferior_tty_terminal="/dev/pts/1"
21371 (gdb)
21372 @end smallexample
21373
21374 @node Annotations
21375 @chapter @value{GDBN} Annotations
21376
21377 This chapter describes annotations in @value{GDBN}. Annotations were
21378 designed to interface @value{GDBN} to graphical user interfaces or other
21379 similar programs which want to interact with @value{GDBN} at a
21380 relatively high level.
21381
21382 The annotation mechanism has largely been superseeded by @sc{gdb/mi}
21383 (@pxref{GDB/MI}).
21384
21385 @ignore
21386 This is Edition @value{EDITION}, @value{DATE}.
21387 @end ignore
21388
21389 @menu
21390 * Annotations Overview:: What annotations are; the general syntax.
21391 * Prompting:: Annotations marking @value{GDBN}'s need for input.
21392 * Errors:: Annotations for error messages.
21393 * Invalidation:: Some annotations describe things now invalid.
21394 * Annotations for Running::
21395 Whether the program is running, how it stopped, etc.
21396 * Source Annotations:: Annotations describing source code.
21397 @end menu
21398
21399 @node Annotations Overview
21400 @section What is an Annotation?
21401 @cindex annotations
21402
21403 Annotations start with a newline character, two @samp{control-z}
21404 characters, and the name of the annotation. If there is no additional
21405 information associated with this annotation, the name of the annotation
21406 is followed immediately by a newline. If there is additional
21407 information, the name of the annotation is followed by a space, the
21408 additional information, and a newline. The additional information
21409 cannot contain newline characters.
21410
21411 Any output not beginning with a newline and two @samp{control-z}
21412 characters denotes literal output from @value{GDBN}. Currently there is
21413 no need for @value{GDBN} to output a newline followed by two
21414 @samp{control-z} characters, but if there was such a need, the
21415 annotations could be extended with an @samp{escape} annotation which
21416 means those three characters as output.
21417
21418 The annotation @var{level}, which is specified using the
21419 @option{--annotate} command line option (@pxref{Mode Options}), controls
21420 how much information @value{GDBN} prints together with its prompt,
21421 values of expressions, source lines, and other types of output. Level 0
21422 is for no anntations, level 1 is for use when @value{GDBN} is run as a
21423 subprocess of @sc{gnu} Emacs, level 3 is the maximum annotation suitable
21424 for programs that control @value{GDBN}, and level 2 annotations have
21425 been made obsolete (@pxref{Limitations, , Limitations of the Annotation
21426 Interface, annotate, GDB's Obsolete Annotations}).
21427
21428 @table @code
21429 @kindex set annotate
21430 @item set annotate @var{level}
21431 The @value{GDBN} command @code{set annotate} sets the level of
21432 annotations to the specified @var{level}.
21433
21434 @item show annotate
21435 @kindex show annotate
21436 Show the current annotation level.
21437 @end table
21438
21439 This chapter describes level 3 annotations.
21440
21441 A simple example of starting up @value{GDBN} with annotations is:
21442
21443 @smallexample
21444 $ @kbd{gdb --annotate=3}
21445 GNU gdb 6.0
21446 Copyright 2003 Free Software Foundation, Inc.
21447 GDB is free software, covered by the GNU General Public License,
21448 and you are welcome to change it and/or distribute copies of it
21449 under certain conditions.
21450 Type "show copying" to see the conditions.
21451 There is absolutely no warranty for GDB. Type "show warranty"
21452 for details.
21453 This GDB was configured as "i386-pc-linux-gnu"
21454
21455 ^Z^Zpre-prompt
21456 (@value{GDBP})
21457 ^Z^Zprompt
21458 @kbd{quit}
21459
21460 ^Z^Zpost-prompt
21461 $
21462 @end smallexample
21463
21464 Here @samp{quit} is input to @value{GDBN}; the rest is output from
21465 @value{GDBN}. The three lines beginning @samp{^Z^Z} (where @samp{^Z}
21466 denotes a @samp{control-z} character) are annotations; the rest is
21467 output from @value{GDBN}.
21468
21469 @node Prompting
21470 @section Annotation for @value{GDBN} Input
21471
21472 @cindex annotations for prompts
21473 When @value{GDBN} prompts for input, it annotates this fact so it is possible
21474 to know when to send output, when the output from a given command is
21475 over, etc.
21476
21477 Different kinds of input each have a different @dfn{input type}. Each
21478 input type has three annotations: a @code{pre-} annotation, which
21479 denotes the beginning of any prompt which is being output, a plain
21480 annotation, which denotes the end of the prompt, and then a @code{post-}
21481 annotation which denotes the end of any echo which may (or may not) be
21482 associated with the input. For example, the @code{prompt} input type
21483 features the following annotations:
21484
21485 @smallexample
21486 ^Z^Zpre-prompt
21487 ^Z^Zprompt
21488 ^Z^Zpost-prompt
21489 @end smallexample
21490
21491 The input types are
21492
21493 @table @code
21494 @findex pre-prompt
21495 @findex prompt
21496 @findex post-prompt
21497 @item prompt
21498 When @value{GDBN} is prompting for a command (the main @value{GDBN} prompt).
21499
21500 @findex pre-commands
21501 @findex commands
21502 @findex post-commands
21503 @item commands
21504 When @value{GDBN} prompts for a set of commands, like in the @code{commands}
21505 command. The annotations are repeated for each command which is input.
21506
21507 @findex pre-overload-choice
21508 @findex overload-choice
21509 @findex post-overload-choice
21510 @item overload-choice
21511 When @value{GDBN} wants the user to select between various overloaded functions.
21512
21513 @findex pre-query
21514 @findex query
21515 @findex post-query
21516 @item query
21517 When @value{GDBN} wants the user to confirm a potentially dangerous operation.
21518
21519 @findex pre-prompt-for-continue
21520 @findex prompt-for-continue
21521 @findex post-prompt-for-continue
21522 @item prompt-for-continue
21523 When @value{GDBN} is asking the user to press return to continue. Note: Don't
21524 expect this to work well; instead use @code{set height 0} to disable
21525 prompting. This is because the counting of lines is buggy in the
21526 presence of annotations.
21527 @end table
21528
21529 @node Errors
21530 @section Errors
21531 @cindex annotations for errors, warnings and interrupts
21532
21533 @findex quit
21534 @smallexample
21535 ^Z^Zquit
21536 @end smallexample
21537
21538 This annotation occurs right before @value{GDBN} responds to an interrupt.
21539
21540 @findex error
21541 @smallexample
21542 ^Z^Zerror
21543 @end smallexample
21544
21545 This annotation occurs right before @value{GDBN} responds to an error.
21546
21547 Quit and error annotations indicate that any annotations which @value{GDBN} was
21548 in the middle of may end abruptly. For example, if a
21549 @code{value-history-begin} annotation is followed by a @code{error}, one
21550 cannot expect to receive the matching @code{value-history-end}. One
21551 cannot expect not to receive it either, however; an error annotation
21552 does not necessarily mean that @value{GDBN} is immediately returning all the way
21553 to the top level.
21554
21555 @findex error-begin
21556 A quit or error annotation may be preceded by
21557
21558 @smallexample
21559 ^Z^Zerror-begin
21560 @end smallexample
21561
21562 Any output between that and the quit or error annotation is the error
21563 message.
21564
21565 Warning messages are not yet annotated.
21566 @c If we want to change that, need to fix warning(), type_error(),
21567 @c range_error(), and possibly other places.
21568
21569 @node Invalidation
21570 @section Invalidation Notices
21571
21572 @cindex annotations for invalidation messages
21573 The following annotations say that certain pieces of state may have
21574 changed.
21575
21576 @table @code
21577 @findex frames-invalid
21578 @item ^Z^Zframes-invalid
21579
21580 The frames (for example, output from the @code{backtrace} command) may
21581 have changed.
21582
21583 @findex breakpoints-invalid
21584 @item ^Z^Zbreakpoints-invalid
21585
21586 The breakpoints may have changed. For example, the user just added or
21587 deleted a breakpoint.
21588 @end table
21589
21590 @node Annotations for Running
21591 @section Running the Program
21592 @cindex annotations for running programs
21593
21594 @findex starting
21595 @findex stopping
21596 When the program starts executing due to a @value{GDBN} command such as
21597 @code{step} or @code{continue},
21598
21599 @smallexample
21600 ^Z^Zstarting
21601 @end smallexample
21602
21603 is output. When the program stops,
21604
21605 @smallexample
21606 ^Z^Zstopped
21607 @end smallexample
21608
21609 is output. Before the @code{stopped} annotation, a variety of
21610 annotations describe how the program stopped.
21611
21612 @table @code
21613 @findex exited
21614 @item ^Z^Zexited @var{exit-status}
21615 The program exited, and @var{exit-status} is the exit status (zero for
21616 successful exit, otherwise nonzero).
21617
21618 @findex signalled
21619 @findex signal-name
21620 @findex signal-name-end
21621 @findex signal-string
21622 @findex signal-string-end
21623 @item ^Z^Zsignalled
21624 The program exited with a signal. After the @code{^Z^Zsignalled}, the
21625 annotation continues:
21626
21627 @smallexample
21628 @var{intro-text}
21629 ^Z^Zsignal-name
21630 @var{name}
21631 ^Z^Zsignal-name-end
21632 @var{middle-text}
21633 ^Z^Zsignal-string
21634 @var{string}
21635 ^Z^Zsignal-string-end
21636 @var{end-text}
21637 @end smallexample
21638
21639 @noindent
21640 where @var{name} is the name of the signal, such as @code{SIGILL} or
21641 @code{SIGSEGV}, and @var{string} is the explanation of the signal, such
21642 as @code{Illegal Instruction} or @code{Segmentation fault}.
21643 @var{intro-text}, @var{middle-text}, and @var{end-text} are for the
21644 user's benefit and have no particular format.
21645
21646 @findex signal
21647 @item ^Z^Zsignal
21648 The syntax of this annotation is just like @code{signalled}, but @value{GDBN} is
21649 just saying that the program received the signal, not that it was
21650 terminated with it.
21651
21652 @findex breakpoint
21653 @item ^Z^Zbreakpoint @var{number}
21654 The program hit breakpoint number @var{number}.
21655
21656 @findex watchpoint
21657 @item ^Z^Zwatchpoint @var{number}
21658 The program hit watchpoint number @var{number}.
21659 @end table
21660
21661 @node Source Annotations
21662 @section Displaying Source
21663 @cindex annotations for source display
21664
21665 @findex source
21666 The following annotation is used instead of displaying source code:
21667
21668 @smallexample
21669 ^Z^Zsource @var{filename}:@var{line}:@var{character}:@var{middle}:@var{addr}
21670 @end smallexample
21671
21672 where @var{filename} is an absolute file name indicating which source
21673 file, @var{line} is the line number within that file (where 1 is the
21674 first line in the file), @var{character} is the character position
21675 within the file (where 0 is the first character in the file) (for most
21676 debug formats this will necessarily point to the beginning of a line),
21677 @var{middle} is @samp{middle} if @var{addr} is in the middle of the
21678 line, or @samp{beg} if @var{addr} is at the beginning of the line, and
21679 @var{addr} is the address in the target program associated with the
21680 source which is being displayed. @var{addr} is in the form @samp{0x}
21681 followed by one or more lowercase hex digits (note that this does not
21682 depend on the language).
21683
21684 @node GDB Bugs
21685 @chapter Reporting Bugs in @value{GDBN}
21686 @cindex bugs in @value{GDBN}
21687 @cindex reporting bugs in @value{GDBN}
21688
21689 Your bug reports play an essential role in making @value{GDBN} reliable.
21690
21691 Reporting a bug may help you by bringing a solution to your problem, or it
21692 may not. But in any case the principal function of a bug report is to help
21693 the entire community by making the next version of @value{GDBN} work better. Bug
21694 reports are your contribution to the maintenance of @value{GDBN}.
21695
21696 In order for a bug report to serve its purpose, you must include the
21697 information that enables us to fix the bug.
21698
21699 @menu
21700 * Bug Criteria:: Have you found a bug?
21701 * Bug Reporting:: How to report bugs
21702 @end menu
21703
21704 @node Bug Criteria
21705 @section Have you found a bug?
21706 @cindex bug criteria
21707
21708 If you are not sure whether you have found a bug, here are some guidelines:
21709
21710 @itemize @bullet
21711 @cindex fatal signal
21712 @cindex debugger crash
21713 @cindex crash of debugger
21714 @item
21715 If the debugger gets a fatal signal, for any input whatever, that is a
21716 @value{GDBN} bug. Reliable debuggers never crash.
21717
21718 @cindex error on valid input
21719 @item
21720 If @value{GDBN} produces an error message for valid input, that is a
21721 bug. (Note that if you're cross debugging, the problem may also be
21722 somewhere in the connection to the target.)
21723
21724 @cindex invalid input
21725 @item
21726 If @value{GDBN} does not produce an error message for invalid input,
21727 that is a bug. However, you should note that your idea of
21728 ``invalid input'' might be our idea of ``an extension'' or ``support
21729 for traditional practice''.
21730
21731 @item
21732 If you are an experienced user of debugging tools, your suggestions
21733 for improvement of @value{GDBN} are welcome in any case.
21734 @end itemize
21735
21736 @node Bug Reporting
21737 @section How to report bugs
21738 @cindex bug reports
21739 @cindex @value{GDBN} bugs, reporting
21740
21741 A number of companies and individuals offer support for @sc{gnu} products.
21742 If you obtained @value{GDBN} from a support organization, we recommend you
21743 contact that organization first.
21744
21745 You can find contact information for many support companies and
21746 individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs
21747 distribution.
21748 @c should add a web page ref...
21749
21750 In any event, we also recommend that you submit bug reports for
21751 @value{GDBN}. The prefered method is to submit them directly using
21752 @uref{http://www.gnu.org/software/gdb/bugs/, @value{GDBN}'s Bugs web
21753 page}. Alternatively, the @email{bug-gdb@@gnu.org, e-mail gateway} can
21754 be used.
21755
21756 @strong{Do not send bug reports to @samp{info-gdb}, or to
21757 @samp{help-gdb}, or to any newsgroups.} Most users of @value{GDBN} do
21758 not want to receive bug reports. Those that do have arranged to receive
21759 @samp{bug-gdb}.
21760
21761 The mailing list @samp{bug-gdb} has a newsgroup @samp{gnu.gdb.bug} which
21762 serves as a repeater. The mailing list and the newsgroup carry exactly
21763 the same messages. Often people think of posting bug reports to the
21764 newsgroup instead of mailing them. This appears to work, but it has one
21765 problem which can be crucial: a newsgroup posting often lacks a mail
21766 path back to the sender. Thus, if we need to ask for more information,
21767 we may be unable to reach you. For this reason, it is better to send
21768 bug reports to the mailing list.
21769
21770 The fundamental principle of reporting bugs usefully is this:
21771 @strong{report all the facts}. If you are not sure whether to state a
21772 fact or leave it out, state it!
21773
21774 Often people omit facts because they think they know what causes the
21775 problem and assume that some details do not matter. Thus, you might
21776 assume that the name of the variable you use in an example does not matter.
21777 Well, probably it does not, but one cannot be sure. Perhaps the bug is a
21778 stray memory reference which happens to fetch from the location where that
21779 name is stored in memory; perhaps, if the name were different, the contents
21780 of that location would fool the debugger into doing the right thing despite
21781 the bug. Play it safe and give a specific, complete example. That is the
21782 easiest thing for you to do, and the most helpful.
21783
21784 Keep in mind that the purpose of a bug report is to enable us to fix the
21785 bug. It may be that the bug has been reported previously, but neither
21786 you nor we can know that unless your bug report is complete and
21787 self-contained.
21788
21789 Sometimes people give a few sketchy facts and ask, ``Does this ring a
21790 bell?'' Those bug reports are useless, and we urge everyone to
21791 @emph{refuse to respond to them} except to chide the sender to report
21792 bugs properly.
21793
21794 To enable us to fix the bug, you should include all these things:
21795
21796 @itemize @bullet
21797 @item
21798 The version of @value{GDBN}. @value{GDBN} announces it if you start
21799 with no arguments; you can also print it at any time using @code{show
21800 version}.
21801
21802 Without this, we will not know whether there is any point in looking for
21803 the bug in the current version of @value{GDBN}.
21804
21805 @item
21806 The type of machine you are using, and the operating system name and
21807 version number.
21808
21809 @item
21810 What compiler (and its version) was used to compile @value{GDBN}---e.g.@:
21811 ``@value{GCC}--2.8.1''.
21812
21813 @item
21814 What compiler (and its version) was used to compile the program you are
21815 debugging---e.g.@: ``@value{GCC}--2.8.1'', or ``HP92453-01 A.10.32.03 HP
21816 C Compiler''. For GCC, you can say @code{gcc --version} to get this
21817 information; for other compilers, see the documentation for those
21818 compilers.
21819
21820 @item
21821 The command arguments you gave the compiler to compile your example and
21822 observe the bug. For example, did you use @samp{-O}? To guarantee
21823 you will not omit something important, list them all. A copy of the
21824 Makefile (or the output from make) is sufficient.
21825
21826 If we were to try to guess the arguments, we would probably guess wrong
21827 and then we might not encounter the bug.
21828
21829 @item
21830 A complete input script, and all necessary source files, that will
21831 reproduce the bug.
21832
21833 @item
21834 A description of what behavior you observe that you believe is
21835 incorrect. For example, ``It gets a fatal signal.''
21836
21837 Of course, if the bug is that @value{GDBN} gets a fatal signal, then we
21838 will certainly notice it. But if the bug is incorrect output, we might
21839 not notice unless it is glaringly wrong. You might as well not give us
21840 a chance to make a mistake.
21841
21842 Even if the problem you experience is a fatal signal, you should still
21843 say so explicitly. Suppose something strange is going on, such as, your
21844 copy of @value{GDBN} is out of synch, or you have encountered a bug in
21845 the C library on your system. (This has happened!) Your copy might
21846 crash and ours would not. If you told us to expect a crash, then when
21847 ours fails to crash, we would know that the bug was not happening for
21848 us. If you had not told us to expect a crash, then we would not be able
21849 to draw any conclusion from our observations.
21850
21851 @pindex script
21852 @cindex recording a session script
21853 To collect all this information, you can use a session recording program
21854 such as @command{script}, which is available on many Unix systems.
21855 Just run your @value{GDBN} session inside @command{script} and then
21856 include the @file{typescript} file with your bug report.
21857
21858 Another way to record a @value{GDBN} session is to run @value{GDBN}
21859 inside Emacs and then save the entire buffer to a file.
21860
21861 @item
21862 If you wish to suggest changes to the @value{GDBN} source, send us context
21863 diffs. If you even discuss something in the @value{GDBN} source, refer to
21864 it by context, not by line number.
21865
21866 The line numbers in our development sources will not match those in your
21867 sources. Your line numbers would convey no useful information to us.
21868
21869 @end itemize
21870
21871 Here are some things that are not necessary:
21872
21873 @itemize @bullet
21874 @item
21875 A description of the envelope of the bug.
21876
21877 Often people who encounter a bug spend a lot of time investigating
21878 which changes to the input file will make the bug go away and which
21879 changes will not affect it.
21880
21881 This is often time consuming and not very useful, because the way we
21882 will find the bug is by running a single example under the debugger
21883 with breakpoints, not by pure deduction from a series of examples.
21884 We recommend that you save your time for something else.
21885
21886 Of course, if you can find a simpler example to report @emph{instead}
21887 of the original one, that is a convenience for us. Errors in the
21888 output will be easier to spot, running under the debugger will take
21889 less time, and so on.
21890
21891 However, simplification is not vital; if you do not want to do this,
21892 report the bug anyway and send us the entire test case you used.
21893
21894 @item
21895 A patch for the bug.
21896
21897 A patch for the bug does help us if it is a good one. But do not omit
21898 the necessary information, such as the test case, on the assumption that
21899 a patch is all we need. We might see problems with your patch and decide
21900 to fix the problem another way, or we might not understand it at all.
21901
21902 Sometimes with a program as complicated as @value{GDBN} it is very hard to
21903 construct an example that will make the program follow a certain path
21904 through the code. If you do not send us the example, we will not be able
21905 to construct one, so we will not be able to verify that the bug is fixed.
21906
21907 And if we cannot understand what bug you are trying to fix, or why your
21908 patch should be an improvement, we will not install it. A test case will
21909 help us to understand.
21910
21911 @item
21912 A guess about what the bug is or what it depends on.
21913
21914 Such guesses are usually wrong. Even we cannot guess right about such
21915 things without first using the debugger to find the facts.
21916 @end itemize
21917
21918 @c The readline documentation is distributed with the readline code
21919 @c and consists of the two following files:
21920 @c rluser.texinfo
21921 @c inc-hist.texinfo
21922 @c Use -I with makeinfo to point to the appropriate directory,
21923 @c environment var TEXINPUTS with TeX.
21924 @include rluser.texi
21925 @include inc-hist.texinfo
21926
21927
21928 @node Formatting Documentation
21929 @appendix Formatting Documentation
21930
21931 @cindex @value{GDBN} reference card
21932 @cindex reference card
21933 The @value{GDBN} 4 release includes an already-formatted reference card, ready
21934 for printing with PostScript or Ghostscript, in the @file{gdb}
21935 subdirectory of the main source directory@footnote{In
21936 @file{gdb-@value{GDBVN}/gdb/refcard.ps} of the version @value{GDBVN}
21937 release.}. If you can use PostScript or Ghostscript with your printer,
21938 you can print the reference card immediately with @file{refcard.ps}.
21939
21940 The release also includes the source for the reference card. You
21941 can format it, using @TeX{}, by typing:
21942
21943 @smallexample
21944 make refcard.dvi
21945 @end smallexample
21946
21947 The @value{GDBN} reference card is designed to print in @dfn{landscape}
21948 mode on US ``letter'' size paper;
21949 that is, on a sheet 11 inches wide by 8.5 inches
21950 high. You will need to specify this form of printing as an option to
21951 your @sc{dvi} output program.
21952
21953 @cindex documentation
21954
21955 All the documentation for @value{GDBN} comes as part of the machine-readable
21956 distribution. The documentation is written in Texinfo format, which is
21957 a documentation system that uses a single source file to produce both
21958 on-line information and a printed manual. You can use one of the Info
21959 formatting commands to create the on-line version of the documentation
21960 and @TeX{} (or @code{texi2roff}) to typeset the printed version.
21961
21962 @value{GDBN} includes an already formatted copy of the on-line Info
21963 version of this manual in the @file{gdb} subdirectory. The main Info
21964 file is @file{gdb-@value{GDBVN}/gdb/gdb.info}, and it refers to
21965 subordinate files matching @samp{gdb.info*} in the same directory. If
21966 necessary, you can print out these files, or read them with any editor;
21967 but they are easier to read using the @code{info} subsystem in @sc{gnu}
21968 Emacs or the standalone @code{info} program, available as part of the
21969 @sc{gnu} Texinfo distribution.
21970
21971 If you want to format these Info files yourself, you need one of the
21972 Info formatting programs, such as @code{texinfo-format-buffer} or
21973 @code{makeinfo}.
21974
21975 If you have @code{makeinfo} installed, and are in the top level
21976 @value{GDBN} source directory (@file{gdb-@value{GDBVN}}, in the case of
21977 version @value{GDBVN}), you can make the Info file by typing:
21978
21979 @smallexample
21980 cd gdb
21981 make gdb.info
21982 @end smallexample
21983
21984 If you want to typeset and print copies of this manual, you need @TeX{},
21985 a program to print its @sc{dvi} output files, and @file{texinfo.tex}, the
21986 Texinfo definitions file.
21987
21988 @TeX{} is a typesetting program; it does not print files directly, but
21989 produces output files called @sc{dvi} files. To print a typeset
21990 document, you need a program to print @sc{dvi} files. If your system
21991 has @TeX{} installed, chances are it has such a program. The precise
21992 command to use depends on your system; @kbd{lpr -d} is common; another
21993 (for PostScript devices) is @kbd{dvips}. The @sc{dvi} print command may
21994 require a file name without any extension or a @samp{.dvi} extension.
21995
21996 @TeX{} also requires a macro definitions file called
21997 @file{texinfo.tex}. This file tells @TeX{} how to typeset a document
21998 written in Texinfo format. On its own, @TeX{} cannot either read or
21999 typeset a Texinfo file. @file{texinfo.tex} is distributed with GDB
22000 and is located in the @file{gdb-@var{version-number}/texinfo}
22001 directory.
22002
22003 If you have @TeX{} and a @sc{dvi} printer program installed, you can
22004 typeset and print this manual. First switch to the the @file{gdb}
22005 subdirectory of the main source directory (for example, to
22006 @file{gdb-@value{GDBVN}/gdb}) and type:
22007
22008 @smallexample
22009 make gdb.dvi
22010 @end smallexample
22011
22012 Then give @file{gdb.dvi} to your @sc{dvi} printing program.
22013
22014 @node Installing GDB
22015 @appendix Installing @value{GDBN}
22016 @cindex installation
22017
22018 @menu
22019 * Requirements:: Requirements for building @value{GDBN}
22020 * Running Configure:: Invoking the @value{GDBN} @code{configure} script
22021 * Separate Objdir:: Compiling @value{GDBN} in another directory
22022 * Config Names:: Specifying names for hosts and targets
22023 * Configure Options:: Summary of options for configure
22024 @end menu
22025
22026 @node Requirements
22027 @section Requirements for building @value{GDBN}
22028 @cindex building @value{GDBN}, requirements for
22029
22030 Building @value{GDBN} requires various tools and packages to be available.
22031 Other packages will be used only if they are found.
22032
22033 @heading Tools/packages necessary for building @value{GDBN}
22034 @table @asis
22035 @item ISO C90 compiler
22036 @value{GDBN} is written in ISO C90. It should be buildable with any
22037 working C90 compiler, e.g.@: GCC.
22038
22039 @end table
22040
22041 @heading Tools/packages optional for building @value{GDBN}
22042 @table @asis
22043 @item Expat
22044 @value{GDBN} can use the Expat XML parsing library. This library may be
22045 included with your operating system distribution; if it is not, you
22046 can get the latest version from @url{http://expat.sourceforge.net}.
22047 The @code{configure} script will search for this library in several
22048 standard locations; if it is installed in an unusual path, you can
22049 use the @option{--with-libexpat-prefix} option to specify its location.
22050
22051 Expat is used currently only used to implement some remote-specific
22052 features.
22053
22054 @end table
22055
22056 @node Running Configure
22057 @section Invoking the @value{GDBN} @code{configure} script
22058 @cindex configuring @value{GDBN}
22059 @value{GDBN} comes with a @code{configure} script that automates the process
22060 of preparing @value{GDBN} for installation; you can then use @code{make} to
22061 build the @code{gdb} program.
22062 @iftex
22063 @c irrelevant in info file; it's as current as the code it lives with.
22064 @footnote{If you have a more recent version of @value{GDBN} than @value{GDBVN},
22065 look at the @file{README} file in the sources; we may have improved the
22066 installation procedures since publishing this manual.}
22067 @end iftex
22068
22069 The @value{GDBN} distribution includes all the source code you need for
22070 @value{GDBN} in a single directory, whose name is usually composed by
22071 appending the version number to @samp{gdb}.
22072
22073 For example, the @value{GDBN} version @value{GDBVN} distribution is in the
22074 @file{gdb-@value{GDBVN}} directory. That directory contains:
22075
22076 @table @code
22077 @item gdb-@value{GDBVN}/configure @r{(and supporting files)}
22078 script for configuring @value{GDBN} and all its supporting libraries
22079
22080 @item gdb-@value{GDBVN}/gdb
22081 the source specific to @value{GDBN} itself
22082
22083 @item gdb-@value{GDBVN}/bfd
22084 source for the Binary File Descriptor library
22085
22086 @item gdb-@value{GDBVN}/include
22087 @sc{gnu} include files
22088
22089 @item gdb-@value{GDBVN}/libiberty
22090 source for the @samp{-liberty} free software library
22091
22092 @item gdb-@value{GDBVN}/opcodes
22093 source for the library of opcode tables and disassemblers
22094
22095 @item gdb-@value{GDBVN}/readline
22096 source for the @sc{gnu} command-line interface
22097
22098 @item gdb-@value{GDBVN}/glob
22099 source for the @sc{gnu} filename pattern-matching subroutine
22100
22101 @item gdb-@value{GDBVN}/mmalloc
22102 source for the @sc{gnu} memory-mapped malloc package
22103 @end table
22104
22105 The simplest way to configure and build @value{GDBN} is to run @code{configure}
22106 from the @file{gdb-@var{version-number}} source directory, which in
22107 this example is the @file{gdb-@value{GDBVN}} directory.
22108
22109 First switch to the @file{gdb-@var{version-number}} source directory
22110 if you are not already in it; then run @code{configure}. Pass the
22111 identifier for the platform on which @value{GDBN} will run as an
22112 argument.
22113
22114 For example:
22115
22116 @smallexample
22117 cd gdb-@value{GDBVN}
22118 ./configure @var{host}
22119 make
22120 @end smallexample
22121
22122 @noindent
22123 where @var{host} is an identifier such as @samp{sun4} or
22124 @samp{decstation}, that identifies the platform where @value{GDBN} will run.
22125 (You can often leave off @var{host}; @code{configure} tries to guess the
22126 correct value by examining your system.)
22127
22128 Running @samp{configure @var{host}} and then running @code{make} builds the
22129 @file{bfd}, @file{readline}, @file{mmalloc}, and @file{libiberty}
22130 libraries, then @code{gdb} itself. The configured source files, and the
22131 binaries, are left in the corresponding source directories.
22132
22133 @need 750
22134 @code{configure} is a Bourne-shell (@code{/bin/sh}) script; if your
22135 system does not recognize this automatically when you run a different
22136 shell, you may need to run @code{sh} on it explicitly:
22137
22138 @smallexample
22139 sh configure @var{host}
22140 @end smallexample
22141
22142 If you run @code{configure} from a directory that contains source
22143 directories for multiple libraries or programs, such as the
22144 @file{gdb-@value{GDBVN}} source directory for version @value{GDBVN}, @code{configure}
22145 creates configuration files for every directory level underneath (unless
22146 you tell it not to, with the @samp{--norecursion} option).
22147
22148 You should run the @code{configure} script from the top directory in the
22149 source tree, the @file{gdb-@var{version-number}} directory. If you run
22150 @code{configure} from one of the subdirectories, you will configure only
22151 that subdirectory. That is usually not what you want. In particular,
22152 if you run the first @code{configure} from the @file{gdb} subdirectory
22153 of the @file{gdb-@var{version-number}} directory, you will omit the
22154 configuration of @file{bfd}, @file{readline}, and other sibling
22155 directories of the @file{gdb} subdirectory. This leads to build errors
22156 about missing include files such as @file{bfd/bfd.h}.
22157
22158 You can install @code{@value{GDBP}} anywhere; it has no hardwired paths.
22159 However, you should make sure that the shell on your path (named by
22160 the @samp{SHELL} environment variable) is publicly readable. Remember
22161 that @value{GDBN} uses the shell to start your program---some systems refuse to
22162 let @value{GDBN} debug child processes whose programs are not readable.
22163
22164 @node Separate Objdir
22165 @section Compiling @value{GDBN} in another directory
22166
22167 If you want to run @value{GDBN} versions for several host or target machines,
22168 you need a different @code{gdb} compiled for each combination of
22169 host and target. @code{configure} is designed to make this easy by
22170 allowing you to generate each configuration in a separate subdirectory,
22171 rather than in the source directory. If your @code{make} program
22172 handles the @samp{VPATH} feature (@sc{gnu} @code{make} does), running
22173 @code{make} in each of these directories builds the @code{gdb}
22174 program specified there.
22175
22176 To build @code{gdb} in a separate directory, run @code{configure}
22177 with the @samp{--srcdir} option to specify where to find the source.
22178 (You also need to specify a path to find @code{configure}
22179 itself from your working directory. If the path to @code{configure}
22180 would be the same as the argument to @samp{--srcdir}, you can leave out
22181 the @samp{--srcdir} option; it is assumed.)
22182
22183 For example, with version @value{GDBVN}, you can build @value{GDBN} in a
22184 separate directory for a Sun 4 like this:
22185
22186 @smallexample
22187 @group
22188 cd gdb-@value{GDBVN}
22189 mkdir ../gdb-sun4
22190 cd ../gdb-sun4
22191 ../gdb-@value{GDBVN}/configure sun4
22192 make
22193 @end group
22194 @end smallexample
22195
22196 When @code{configure} builds a configuration using a remote source
22197 directory, it creates a tree for the binaries with the same structure
22198 (and using the same names) as the tree under the source directory. In
22199 the example, you'd find the Sun 4 library @file{libiberty.a} in the
22200 directory @file{gdb-sun4/libiberty}, and @value{GDBN} itself in
22201 @file{gdb-sun4/gdb}.
22202
22203 Make sure that your path to the @file{configure} script has just one
22204 instance of @file{gdb} in it. If your path to @file{configure} looks
22205 like @file{../gdb-@value{GDBVN}/gdb/configure}, you are configuring only
22206 one subdirectory of @value{GDBN}, not the whole package. This leads to
22207 build errors about missing include files such as @file{bfd/bfd.h}.
22208
22209 One popular reason to build several @value{GDBN} configurations in separate
22210 directories is to configure @value{GDBN} for cross-compiling (where
22211 @value{GDBN} runs on one machine---the @dfn{host}---while debugging
22212 programs that run on another machine---the @dfn{target}).
22213 You specify a cross-debugging target by
22214 giving the @samp{--target=@var{target}} option to @code{configure}.
22215
22216 When you run @code{make} to build a program or library, you must run
22217 it in a configured directory---whatever directory you were in when you
22218 called @code{configure} (or one of its subdirectories).
22219
22220 The @code{Makefile} that @code{configure} generates in each source
22221 directory also runs recursively. If you type @code{make} in a source
22222 directory such as @file{gdb-@value{GDBVN}} (or in a separate configured
22223 directory configured with @samp{--srcdir=@var{dirname}/gdb-@value{GDBVN}}), you
22224 will build all the required libraries, and then build GDB.
22225
22226 When you have multiple hosts or targets configured in separate
22227 directories, you can run @code{make} on them in parallel (for example,
22228 if they are NFS-mounted on each of the hosts); they will not interfere
22229 with each other.
22230
22231 @node Config Names
22232 @section Specifying names for hosts and targets
22233
22234 The specifications used for hosts and targets in the @code{configure}
22235 script are based on a three-part naming scheme, but some short predefined
22236 aliases are also supported. The full naming scheme encodes three pieces
22237 of information in the following pattern:
22238
22239 @smallexample
22240 @var{architecture}-@var{vendor}-@var{os}
22241 @end smallexample
22242
22243 For example, you can use the alias @code{sun4} as a @var{host} argument,
22244 or as the value for @var{target} in a @code{--target=@var{target}}
22245 option. The equivalent full name is @samp{sparc-sun-sunos4}.
22246
22247 The @code{configure} script accompanying @value{GDBN} does not provide
22248 any query facility to list all supported host and target names or
22249 aliases. @code{configure} calls the Bourne shell script
22250 @code{config.sub} to map abbreviations to full names; you can read the
22251 script, if you wish, or you can use it to test your guesses on
22252 abbreviations---for example:
22253
22254 @smallexample
22255 % sh config.sub i386-linux
22256 i386-pc-linux-gnu
22257 % sh config.sub alpha-linux
22258 alpha-unknown-linux-gnu
22259 % sh config.sub hp9k700
22260 hppa1.1-hp-hpux
22261 % sh config.sub sun4
22262 sparc-sun-sunos4.1.1
22263 % sh config.sub sun3
22264 m68k-sun-sunos4.1.1
22265 % sh config.sub i986v
22266 Invalid configuration `i986v': machine `i986v' not recognized
22267 @end smallexample
22268
22269 @noindent
22270 @code{config.sub} is also distributed in the @value{GDBN} source
22271 directory (@file{gdb-@value{GDBVN}}, for version @value{GDBVN}).
22272
22273 @node Configure Options
22274 @section @code{configure} options
22275
22276 Here is a summary of the @code{configure} options and arguments that
22277 are most often useful for building @value{GDBN}. @code{configure} also has
22278 several other options not listed here. @inforef{What Configure
22279 Does,,configure.info}, for a full explanation of @code{configure}.
22280
22281 @smallexample
22282 configure @r{[}--help@r{]}
22283 @r{[}--prefix=@var{dir}@r{]}
22284 @r{[}--exec-prefix=@var{dir}@r{]}
22285 @r{[}--srcdir=@var{dirname}@r{]}
22286 @r{[}--norecursion@r{]} @r{[}--rm@r{]}
22287 @r{[}--target=@var{target}@r{]}
22288 @var{host}
22289 @end smallexample
22290
22291 @noindent
22292 You may introduce options with a single @samp{-} rather than
22293 @samp{--} if you prefer; but you may abbreviate option names if you use
22294 @samp{--}.
22295
22296 @table @code
22297 @item --help
22298 Display a quick summary of how to invoke @code{configure}.
22299
22300 @item --prefix=@var{dir}
22301 Configure the source to install programs and files under directory
22302 @file{@var{dir}}.
22303
22304 @item --exec-prefix=@var{dir}
22305 Configure the source to install programs under directory
22306 @file{@var{dir}}.
22307
22308 @c avoid splitting the warning from the explanation:
22309 @need 2000
22310 @item --srcdir=@var{dirname}
22311 @strong{Warning: using this option requires @sc{gnu} @code{make}, or another
22312 @code{make} that implements the @code{VPATH} feature.}@*
22313 Use this option to make configurations in directories separate from the
22314 @value{GDBN} source directories. Among other things, you can use this to
22315 build (or maintain) several configurations simultaneously, in separate
22316 directories. @code{configure} writes configuration specific files in
22317 the current directory, but arranges for them to use the source in the
22318 directory @var{dirname}. @code{configure} creates directories under
22319 the working directory in parallel to the source directories below
22320 @var{dirname}.
22321
22322 @item --norecursion
22323 Configure only the directory level where @code{configure} is executed; do not
22324 propagate configuration to subdirectories.
22325
22326 @item --target=@var{target}
22327 Configure @value{GDBN} for cross-debugging programs running on the specified
22328 @var{target}. Without this option, @value{GDBN} is configured to debug
22329 programs that run on the same machine (@var{host}) as @value{GDBN} itself.
22330
22331 There is no convenient way to generate a list of all available targets.
22332
22333 @item @var{host} @dots{}
22334 Configure @value{GDBN} to run on the specified @var{host}.
22335
22336 There is no convenient way to generate a list of all available hosts.
22337 @end table
22338
22339 There are many other options available as well, but they are generally
22340 needed for special purposes only.
22341
22342 @node Maintenance Commands
22343 @appendix Maintenance Commands
22344 @cindex maintenance commands
22345 @cindex internal commands
22346
22347 In addition to commands intended for @value{GDBN} users, @value{GDBN}
22348 includes a number of commands intended for @value{GDBN} developers,
22349 that are not documented elsewhere in this manual. These commands are
22350 provided here for reference. (For commands that turn on debugging
22351 messages, see @ref{Debugging Output}.)
22352
22353 @table @code
22354 @kindex maint agent
22355 @item maint agent @var{expression}
22356 Translate the given @var{expression} into remote agent bytecodes.
22357 This command is useful for debugging the Agent Expression mechanism
22358 (@pxref{Agent Expressions}).
22359
22360 @kindex maint info breakpoints
22361 @item @anchor{maint info breakpoints}maint info breakpoints
22362 Using the same format as @samp{info breakpoints}, display both the
22363 breakpoints you've set explicitly, and those @value{GDBN} is using for
22364 internal purposes. Internal breakpoints are shown with negative
22365 breakpoint numbers. The type column identifies what kind of breakpoint
22366 is shown:
22367
22368 @table @code
22369 @item breakpoint
22370 Normal, explicitly set breakpoint.
22371
22372 @item watchpoint
22373 Normal, explicitly set watchpoint.
22374
22375 @item longjmp
22376 Internal breakpoint, used to handle correctly stepping through
22377 @code{longjmp} calls.
22378
22379 @item longjmp resume
22380 Internal breakpoint at the target of a @code{longjmp}.
22381
22382 @item until
22383 Temporary internal breakpoint used by the @value{GDBN} @code{until} command.
22384
22385 @item finish
22386 Temporary internal breakpoint used by the @value{GDBN} @code{finish} command.
22387
22388 @item shlib events
22389 Shared library events.
22390
22391 @end table
22392
22393 @kindex maint check-symtabs
22394 @item maint check-symtabs
22395 Check the consistency of psymtabs and symtabs.
22396
22397 @kindex maint cplus first_component
22398 @item maint cplus first_component @var{name}
22399 Print the first C@t{++} class/namespace component of @var{name}.
22400
22401 @kindex maint cplus namespace
22402 @item maint cplus namespace
22403 Print the list of possible C@t{++} namespaces.
22404
22405 @kindex maint demangle
22406 @item maint demangle @var{name}
22407 Demangle a C@t{++} or Objective-C manled @var{name}.
22408
22409 @kindex maint deprecate
22410 @kindex maint undeprecate
22411 @cindex deprecated commands
22412 @item maint deprecate @var{command} @r{[}@var{replacement}@r{]}
22413 @itemx maint undeprecate @var{command}
22414 Deprecate or undeprecate the named @var{command}. Deprecated commands
22415 cause @value{GDBN} to issue a warning when you use them. The optional
22416 argument @var{replacement} says which newer command should be used in
22417 favor of the deprecated one; if it is given, @value{GDBN} will mention
22418 the replacement as part of the warning.
22419
22420 @kindex maint dump-me
22421 @item maint dump-me
22422 @cindex @code{SIGQUIT} signal, dump core of @value{GDBN}
22423 Cause a fatal signal in the debugger and force it to dump its core.
22424 This is supported only on systems which support aborting a program
22425 with the @code{SIGQUIT} signal.
22426
22427 @kindex maint internal-error
22428 @kindex maint internal-warning
22429 @item maint internal-error @r{[}@var{message-text}@r{]}
22430 @itemx maint internal-warning @r{[}@var{message-text}@r{]}
22431 Cause @value{GDBN} to call the internal function @code{internal_error}
22432 or @code{internal_warning} and hence behave as though an internal error
22433 or internal warning has been detected. In addition to reporting the
22434 internal problem, these functions give the user the opportunity to
22435 either quit @value{GDBN} or create a core file of the current
22436 @value{GDBN} session.
22437
22438 These commands take an optional parameter @var{message-text} that is
22439 used as the text of the error or warning message.
22440
22441 Here's an example of using @code{indernal-error}:
22442
22443 @smallexample
22444 (@value{GDBP}) @kbd{maint internal-error testing, 1, 2}
22445 @dots{}/maint.c:121: internal-error: testing, 1, 2
22446 A problem internal to GDB has been detected. Further
22447 debugging may prove unreliable.
22448 Quit this debugging session? (y or n) @kbd{n}
22449 Create a core file? (y or n) @kbd{n}
22450 (@value{GDBP})
22451 @end smallexample
22452
22453 @kindex maint packet
22454 @item maint packet @var{text}
22455 If @value{GDBN} is talking to an inferior via the serial protocol,
22456 then this command sends the string @var{text} to the inferior, and
22457 displays the response packet. @value{GDBN} supplies the initial
22458 @samp{$} character, the terminating @samp{#} character, and the
22459 checksum.
22460
22461 @kindex maint print architecture
22462 @item maint print architecture @r{[}@var{file}@r{]}
22463 Print the entire architecture configuration. The optional argument
22464 @var{file} names the file where the output goes.
22465
22466 @kindex maint print dummy-frames
22467 @item maint print dummy-frames
22468 Prints the contents of @value{GDBN}'s internal dummy-frame stack.
22469
22470 @smallexample
22471 (@value{GDBP}) @kbd{b add}
22472 @dots{}
22473 (@value{GDBP}) @kbd{print add(2,3)}
22474 Breakpoint 2, add (a=2, b=3) at @dots{}
22475 58 return (a + b);
22476 The program being debugged stopped while in a function called from GDB.
22477 @dots{}
22478 (@value{GDBP}) @kbd{maint print dummy-frames}
22479 0x1a57c80: pc=0x01014068 fp=0x0200bddc sp=0x0200bdd6
22480 top=0x0200bdd4 id=@{stack=0x200bddc,code=0x101405c@}
22481 call_lo=0x01014000 call_hi=0x01014001
22482 (@value{GDBP})
22483 @end smallexample
22484
22485 Takes an optional file parameter.
22486
22487 @kindex maint print registers
22488 @kindex maint print raw-registers
22489 @kindex maint print cooked-registers
22490 @kindex maint print register-groups
22491 @item maint print registers @r{[}@var{file}@r{]}
22492 @itemx maint print raw-registers @r{[}@var{file}@r{]}
22493 @itemx maint print cooked-registers @r{[}@var{file}@r{]}
22494 @itemx maint print register-groups @r{[}@var{file}@r{]}
22495 Print @value{GDBN}'s internal register data structures.
22496
22497 The command @code{maint print raw-registers} includes the contents of
22498 the raw register cache; the command @code{maint print cooked-registers}
22499 includes the (cooked) value of all registers; and the command
22500 @code{maint print register-groups} includes the groups that each
22501 register is a member of. @xref{Registers,, Registers, gdbint,
22502 @value{GDBN} Internals}.
22503
22504 These commands take an optional parameter, a file name to which to
22505 write the information.
22506
22507 @kindex maint print reggroups
22508 @item maint print reggroups @r{[}@var{file}@r{]}
22509 Print @value{GDBN}'s internal register group data structures. The
22510 optional argument @var{file} tells to what file to write the
22511 information.
22512
22513 The register groups info looks like this:
22514
22515 @smallexample
22516 (@value{GDBP}) @kbd{maint print reggroups}
22517 Group Type
22518 general user
22519 float user
22520 all user
22521 vector user
22522 system user
22523 save internal
22524 restore internal
22525 @end smallexample
22526
22527 @kindex flushregs
22528 @item flushregs
22529 This command forces @value{GDBN} to flush its internal register cache.
22530
22531 @kindex maint print objfiles
22532 @cindex info for known object files
22533 @item maint print objfiles
22534 Print a dump of all known object files. For each object file, this
22535 command prints its name, address in memory, and all of its psymtabs
22536 and symtabs.
22537
22538 @kindex maint print statistics
22539 @cindex bcache statistics
22540 @item maint print statistics
22541 This command prints, for each object file in the program, various data
22542 about that object file followed by the byte cache (@dfn{bcache})
22543 statistics for the object file. The objfile data includes the number
22544 of minimal, partical, full, and stabs symbols, the number of types
22545 defined by the objfile, the number of as yet unexpanded psym tables,
22546 the number of line tables and string tables, and the amount of memory
22547 used by the various tables. The bcache statistics include the counts,
22548 sizes, and counts of duplicates of all and unique objects, max,
22549 average, and median entry size, total memory used and its overhead and
22550 savings, and various measures of the hash table size and chain
22551 lengths.
22552
22553 @kindex maint print type
22554 @cindex type chain of a data type
22555 @item maint print type @var{expr}
22556 Print the type chain for a type specified by @var{expr}. The argument
22557 can be either a type name or a symbol. If it is a symbol, the type of
22558 that symbol is described. The type chain produced by this command is
22559 a recursive definition of the data type as stored in @value{GDBN}'s
22560 data structures, including its flags and contained types.
22561
22562 @kindex maint set dwarf2 max-cache-age
22563 @kindex maint show dwarf2 max-cache-age
22564 @item maint set dwarf2 max-cache-age
22565 @itemx maint show dwarf2 max-cache-age
22566 Control the DWARF 2 compilation unit cache.
22567
22568 @cindex DWARF 2 compilation units cache
22569 In object files with inter-compilation-unit references, such as those
22570 produced by the GCC option @samp{-feliminate-dwarf2-dups}, the DWARF 2
22571 reader needs to frequently refer to previously read compilation units.
22572 This setting controls how long a compilation unit will remain in the
22573 cache if it is not referenced. A higher limit means that cached
22574 compilation units will be stored in memory longer, and more total
22575 memory will be used. Setting it to zero disables caching, which will
22576 slow down @value{GDBN} startup, but reduce memory consumption.
22577
22578 @kindex maint set profile
22579 @kindex maint show profile
22580 @cindex profiling GDB
22581 @item maint set profile
22582 @itemx maint show profile
22583 Control profiling of @value{GDBN}.
22584
22585 Profiling will be disabled until you use the @samp{maint set profile}
22586 command to enable it. When you enable profiling, the system will begin
22587 collecting timing and execution count data; when you disable profiling or
22588 exit @value{GDBN}, the results will be written to a log file. Remember that
22589 if you use profiling, @value{GDBN} will overwrite the profiling log file
22590 (often called @file{gmon.out}). If you have a record of important profiling
22591 data in a @file{gmon.out} file, be sure to move it to a safe location.
22592
22593 Configuring with @samp{--enable-profiling} arranges for @value{GDBN} to be
22594 compiled with the @samp{-pg} compiler option.
22595
22596 @kindex maint show-debug-regs
22597 @cindex x86 hardware debug registers
22598 @item maint show-debug-regs
22599 Control whether to show variables that mirror the x86 hardware debug
22600 registers. Use @code{ON} to enable, @code{OFF} to disable. If
22601 enabled, the debug registers values are shown when GDB inserts or
22602 removes a hardware breakpoint or watchpoint, and when the inferior
22603 triggers a hardware-assisted breakpoint or watchpoint.
22604
22605 @kindex maint space
22606 @cindex memory used by commands
22607 @item maint space
22608 Control whether to display memory usage for each command. If set to a
22609 nonzero value, @value{GDBN} will display how much memory each command
22610 took, following the command's own output. This can also be requested
22611 by invoking @value{GDBN} with the @option{--statistics} command-line
22612 switch (@pxref{Mode Options}).
22613
22614 @kindex maint time
22615 @cindex time of command execution
22616 @item maint time
22617 Control whether to display the execution time for each command. If
22618 set to a nonzero value, @value{GDBN} will display how much time it
22619 took to execute each command, following the command's own output.
22620 This can also be requested by invoking @value{GDBN} with the
22621 @option{--statistics} command-line switch (@pxref{Mode Options}).
22622
22623 @kindex maint translate-address
22624 @item maint translate-address @r{[}@var{section}@r{]} @var{addr}
22625 Find the symbol stored at the location specified by the address
22626 @var{addr} and an optional section name @var{section}. If found,
22627 @value{GDBN} prints the name of the closest symbol and an offset from
22628 the symbol's location to the specified address. This is similar to
22629 the @code{info address} command (@pxref{Symbols}), except that this
22630 command also allows to find symbols in other sections.
22631
22632 @end table
22633
22634 The following command is useful for non-interactive invocations of
22635 @value{GDBN}, such as in the test suite.
22636
22637 @table @code
22638 @item set watchdog @var{nsec}
22639 @kindex set watchdog
22640 @cindex watchdog timer
22641 @cindex timeout for commands
22642 Set the maximum number of seconds @value{GDBN} will wait for the
22643 target operation to finish. If this time expires, @value{GDBN}
22644 reports and error and the command is aborted.
22645
22646 @item show watchdog
22647 Show the current setting of the target wait timeout.
22648 @end table
22649
22650 @node Remote Protocol
22651 @appendix @value{GDBN} Remote Serial Protocol
22652
22653 @menu
22654 * Overview::
22655 * Packets::
22656 * Stop Reply Packets::
22657 * General Query Packets::
22658 * Register Packet Format::
22659 * Tracepoint Packets::
22660 * Interrupts::
22661 * Examples::
22662 * File-I/O remote protocol extension::
22663 * Memory map format::
22664 @end menu
22665
22666 @node Overview
22667 @section Overview
22668
22669 There may be occasions when you need to know something about the
22670 protocol---for example, if there is only one serial port to your target
22671 machine, you might want your program to do something special if it
22672 recognizes a packet meant for @value{GDBN}.
22673
22674 In the examples below, @samp{->} and @samp{<-} are used to indicate
22675 transmitted and received data respectfully.
22676
22677 @cindex protocol, @value{GDBN} remote serial
22678 @cindex serial protocol, @value{GDBN} remote
22679 @cindex remote serial protocol
22680 All @value{GDBN} commands and responses (other than acknowledgments) are
22681 sent as a @var{packet}. A @var{packet} is introduced with the character
22682 @samp{$}, the actual @var{packet-data}, and the terminating character
22683 @samp{#} followed by a two-digit @var{checksum}:
22684
22685 @smallexample
22686 @code{$}@var{packet-data}@code{#}@var{checksum}
22687 @end smallexample
22688 @noindent
22689
22690 @cindex checksum, for @value{GDBN} remote
22691 @noindent
22692 The two-digit @var{checksum} is computed as the modulo 256 sum of all
22693 characters between the leading @samp{$} and the trailing @samp{#} (an
22694 eight bit unsigned checksum).
22695
22696 Implementors should note that prior to @value{GDBN} 5.0 the protocol
22697 specification also included an optional two-digit @var{sequence-id}:
22698
22699 @smallexample
22700 @code{$}@var{sequence-id}@code{:}@var{packet-data}@code{#}@var{checksum}
22701 @end smallexample
22702
22703 @cindex sequence-id, for @value{GDBN} remote
22704 @noindent
22705 That @var{sequence-id} was appended to the acknowledgment. @value{GDBN}
22706 has never output @var{sequence-id}s. Stubs that handle packets added
22707 since @value{GDBN} 5.0 must not accept @var{sequence-id}.
22708
22709 @cindex acknowledgment, for @value{GDBN} remote
22710 When either the host or the target machine receives a packet, the first
22711 response expected is an acknowledgment: either @samp{+} (to indicate
22712 the package was received correctly) or @samp{-} (to request
22713 retransmission):
22714
22715 @smallexample
22716 -> @code{$}@var{packet-data}@code{#}@var{checksum}
22717 <- @code{+}
22718 @end smallexample
22719 @noindent
22720
22721 The host (@value{GDBN}) sends @var{command}s, and the target (the
22722 debugging stub incorporated in your program) sends a @var{response}. In
22723 the case of step and continue @var{command}s, the response is only sent
22724 when the operation has completed (the target has again stopped).
22725
22726 @var{packet-data} consists of a sequence of characters with the
22727 exception of @samp{#} and @samp{$} (see @samp{X} packet for additional
22728 exceptions).
22729
22730 @cindex remote protocol, field separator
22731 Fields within the packet should be separated using @samp{,} @samp{;} or
22732 @samp{:}. Except where otherwise noted all numbers are represented in
22733 @sc{hex} with leading zeros suppressed.
22734
22735 Implementors should note that prior to @value{GDBN} 5.0, the character
22736 @samp{:} could not appear as the third character in a packet (as it
22737 would potentially conflict with the @var{sequence-id}).
22738
22739 @cindex remote protocol, binary data
22740 @anchor{Binary Data}
22741 Binary data in most packets is encoded either as two hexadecimal
22742 digits per byte of binary data. This allowed the traditional remote
22743 protocol to work over connections which were only seven-bit clean.
22744 Some packets designed more recently assume an eight-bit clean
22745 connection, and use a more efficient encoding to send and receive
22746 binary data.
22747
22748 The binary data representation uses @code{7d} (@sc{ascii} @samp{@}})
22749 as an escape character. Any escaped byte is transmitted as the escape
22750 character followed by the original character XORed with @code{0x20}.
22751 For example, the byte @code{0x7d} would be transmitted as the two
22752 bytes @code{0x7d 0x5d}. The bytes @code{0x23} (@sc{ascii} @samp{#}),
22753 @code{0x24} (@sc{ascii} @samp{$}), and @code{0x7d} (@sc{ascii}
22754 @samp{@}}) must always be escaped. Responses sent by the stub
22755 must also escape @code{0x2a} (@sc{ascii} @samp{*}), so that it
22756 is not interpreted as the start of a run-length encoded sequence
22757 (described next).
22758
22759 Response @var{data} can be run-length encoded to save space. A @samp{*}
22760 means that the next character is an @sc{ascii} encoding giving a repeat count
22761 which stands for that many repetitions of the character preceding the
22762 @samp{*}. The encoding is @code{n+29}, yielding a printable character
22763 where @code{n >=3} (which is where rle starts to win). The printable
22764 characters @samp{$}, @samp{#}, @samp{+} and @samp{-} or with a numeric
22765 value greater than 126 should not be used.
22766
22767 So:
22768 @smallexample
22769 "@code{0* }"
22770 @end smallexample
22771 @noindent
22772 means the same as "0000".
22773
22774 The error response returned for some packets includes a two character
22775 error number. That number is not well defined.
22776
22777 @cindex empty response, for unsupported packets
22778 For any @var{command} not supported by the stub, an empty response
22779 (@samp{$#00}) should be returned. That way it is possible to extend the
22780 protocol. A newer @value{GDBN} can tell if a packet is supported based
22781 on that response.
22782
22783 A stub is required to support the @samp{g}, @samp{G}, @samp{m}, @samp{M},
22784 @samp{c}, and @samp{s} @var{command}s. All other @var{command}s are
22785 optional.
22786
22787 @node Packets
22788 @section Packets
22789
22790 The following table provides a complete list of all currently defined
22791 @var{command}s and their corresponding response @var{data}.
22792 @xref{File-I/O remote protocol extension}, for details about the File
22793 I/O extension of the remote protocol.
22794
22795 Each packet's description has a template showing the packet's overall
22796 syntax, followed by an explanation of the packet's meaning. We
22797 include spaces in some of the templates for clarity; these are not
22798 part of the packet's syntax. No @value{GDBN} packet uses spaces to
22799 separate its components. For example, a template like @samp{foo
22800 @var{bar} @var{baz}} describes a packet beginning with the three ASCII
22801 bytes @samp{foo}, followed by a @var{bar}, followed directly by a
22802 @var{baz}. GDB does not transmit a space character between the
22803 @samp{foo} and the @var{bar}, or between the @var{bar} and the
22804 @var{baz}.
22805
22806 Note that all packet forms beginning with an upper- or lower-case
22807 letter, other than those described here, are reserved for future use.
22808
22809 Here are the packet descriptions.
22810
22811 @table @samp
22812
22813 @item !
22814 @cindex @samp{!} packet
22815 Enable extended mode. In extended mode, the remote server is made
22816 persistent. The @samp{R} packet is used to restart the program being
22817 debugged.
22818
22819 Reply:
22820 @table @samp
22821 @item OK
22822 The remote target both supports and has enabled extended mode.
22823 @end table
22824
22825 @item ?
22826 @cindex @samp{?} packet
22827 Indicate the reason the target halted. The reply is the same as for
22828 step and continue.
22829
22830 Reply:
22831 @xref{Stop Reply Packets}, for the reply specifications.
22832
22833 @item A @var{arglen},@var{argnum},@var{arg},@dots{}
22834 @cindex @samp{A} packet
22835 Initialized @code{argv[]} array passed into program. @var{arglen}
22836 specifies the number of bytes in the hex encoded byte stream
22837 @var{arg}. See @code{gdbserver} for more details.
22838
22839 Reply:
22840 @table @samp
22841 @item OK
22842 The arguments were set.
22843 @item E @var{NN}
22844 An error occurred.
22845 @end table
22846
22847 @item b @var{baud}
22848 @cindex @samp{b} packet
22849 (Don't use this packet; its behavior is not well-defined.)
22850 Change the serial line speed to @var{baud}.
22851
22852 JTC: @emph{When does the transport layer state change? When it's
22853 received, or after the ACK is transmitted. In either case, there are
22854 problems if the command or the acknowledgment packet is dropped.}
22855
22856 Stan: @emph{If people really wanted to add something like this, and get
22857 it working for the first time, they ought to modify ser-unix.c to send
22858 some kind of out-of-band message to a specially-setup stub and have the
22859 switch happen "in between" packets, so that from remote protocol's point
22860 of view, nothing actually happened.}
22861
22862 @item B @var{addr},@var{mode}
22863 @cindex @samp{B} packet
22864 Set (@var{mode} is @samp{S}) or clear (@var{mode} is @samp{C}) a
22865 breakpoint at @var{addr}.
22866
22867 Don't use this packet. Use the @samp{Z} and @samp{z} packets instead
22868 (@pxref{insert breakpoint or watchpoint packet}).
22869
22870 @item c @r{[}@var{addr}@r{]}
22871 @cindex @samp{c} packet
22872 Continue. @var{addr} is address to resume. If @var{addr} is omitted,
22873 resume at current address.
22874
22875 Reply:
22876 @xref{Stop Reply Packets}, for the reply specifications.
22877
22878 @item C @var{sig}@r{[};@var{addr}@r{]}
22879 @cindex @samp{C} packet
22880 Continue with signal @var{sig} (hex signal number). If
22881 @samp{;@var{addr}} is omitted, resume at same address.
22882
22883 Reply:
22884 @xref{Stop Reply Packets}, for the reply specifications.
22885
22886 @item d
22887 @cindex @samp{d} packet
22888 Toggle debug flag.
22889
22890 Don't use this packet; instead, define a general set packet
22891 (@pxref{General Query Packets}).
22892
22893 @item D
22894 @cindex @samp{D} packet
22895 Detach @value{GDBN} from the remote system. Sent to the remote target
22896 before @value{GDBN} disconnects via the @code{detach} command.
22897
22898 Reply:
22899 @table @samp
22900 @item OK
22901 for success
22902 @item E @var{NN}
22903 for an error
22904 @end table
22905
22906 @item F @var{RC},@var{EE},@var{CF};@var{XX}
22907 @cindex @samp{F} packet
22908 A reply from @value{GDBN} to an @samp{F} packet sent by the target.
22909 This is part of the File-I/O protocol extension. @xref{File-I/O
22910 remote protocol extension}, for the specification.
22911
22912 @item g
22913 @anchor{read registers packet}
22914 @cindex @samp{g} packet
22915 Read general registers.
22916
22917 Reply:
22918 @table @samp
22919 @item @var{XX@dots{}}
22920 Each byte of register data is described by two hex digits. The bytes
22921 with the register are transmitted in target byte order. The size of
22922 each register and their position within the @samp{g} packet are
22923 determined by the @value{GDBN} internal macros
22924 @code{DEPRECATED_REGISTER_RAW_SIZE} and @code{REGISTER_NAME} macros. The
22925 specification of several standard @samp{g} packets is specified below.
22926 @item E @var{NN}
22927 for an error.
22928 @end table
22929
22930 @item G @var{XX@dots{}}
22931 @cindex @samp{G} packet
22932 Write general registers. @xref{read registers packet}, for a
22933 description of the @var{XX@dots{}} data.
22934
22935 Reply:
22936 @table @samp
22937 @item OK
22938 for success
22939 @item E @var{NN}
22940 for an error
22941 @end table
22942
22943 @item H @var{c} @var{t}
22944 @cindex @samp{H} packet
22945 Set thread for subsequent operations (@samp{m}, @samp{M}, @samp{g},
22946 @samp{G}, et.al.). @var{c} depends on the operation to be performed: it
22947 should be @samp{c} for step and continue operations, @samp{g} for other
22948 operations. The thread designator @var{t} may be @samp{-1}, meaning all
22949 the threads, a thread number, or @samp{0} which means pick any thread.
22950
22951 Reply:
22952 @table @samp
22953 @item OK
22954 for success
22955 @item E @var{NN}
22956 for an error
22957 @end table
22958
22959 @c FIXME: JTC:
22960 @c 'H': How restrictive (or permissive) is the thread model. If a
22961 @c thread is selected and stopped, are other threads allowed
22962 @c to continue to execute? As I mentioned above, I think the
22963 @c semantics of each command when a thread is selected must be
22964 @c described. For example:
22965 @c
22966 @c 'g': If the stub supports threads and a specific thread is
22967 @c selected, returns the register block from that thread;
22968 @c otherwise returns current registers.
22969 @c
22970 @c 'G' If the stub supports threads and a specific thread is
22971 @c selected, sets the registers of the register block of
22972 @c that thread; otherwise sets current registers.
22973
22974 @item i @r{[}@var{addr}@r{[},@var{nnn}@r{]]}
22975 @anchor{cycle step packet}
22976 @cindex @samp{i} packet
22977 Step the remote target by a single clock cycle. If @samp{,@var{nnn}} is
22978 present, cycle step @var{nnn} cycles. If @var{addr} is present, cycle
22979 step starting at that address.
22980
22981 @item I
22982 @cindex @samp{I} packet
22983 Signal, then cycle step. @xref{step with signal packet}. @xref{cycle
22984 step packet}.
22985
22986 @item k
22987 @cindex @samp{k} packet
22988 Kill request.
22989
22990 FIXME: @emph{There is no description of how to operate when a specific
22991 thread context has been selected (i.e.@: does 'k' kill only that
22992 thread?)}.
22993
22994 @item m @var{addr},@var{length}
22995 @cindex @samp{m} packet
22996 Read @var{length} bytes of memory starting at address @var{addr}.
22997 Note that @var{addr} may not be aligned to any particular boundary.
22998
22999 The stub need not use any particular size or alignment when gathering
23000 data from memory for the response; even if @var{addr} is word-aligned
23001 and @var{length} is a multiple of the word size, the stub is free to
23002 use byte accesses, or not. For this reason, this packet may not be
23003 suitable for accessing memory-mapped I/O devices.
23004 @cindex alignment of remote memory accesses
23005 @cindex size of remote memory accesses
23006 @cindex memory, alignment and size of remote accesses
23007
23008 Reply:
23009 @table @samp
23010 @item @var{XX@dots{}}
23011 Memory contents; each byte is transmitted as a two-digit hexadecimal
23012 number. The reply may contain fewer bytes than requested if the
23013 server was able to read only part of the region of memory.
23014 @item E @var{NN}
23015 @var{NN} is errno
23016 @end table
23017
23018 @item M @var{addr},@var{length}:@var{XX@dots{}}
23019 @cindex @samp{M} packet
23020 Write @var{length} bytes of memory starting at address @var{addr}.
23021 @var{XX@dots{}} is the data; each byte is transmitted as a two-digit
23022 hexadecimal number.
23023
23024 Reply:
23025 @table @samp
23026 @item OK
23027 for success
23028 @item E @var{NN}
23029 for an error (this includes the case where only part of the data was
23030 written).
23031 @end table
23032
23033 @item p @var{n}
23034 @cindex @samp{p} packet
23035 Read the value of register @var{n}; @var{n} is in hex.
23036 @xref{read registers packet}, for a description of how the returned
23037 register value is encoded.
23038
23039 Reply:
23040 @table @samp
23041 @item @var{XX@dots{}}
23042 the register's value
23043 @item E @var{NN}
23044 for an error
23045 @item
23046 Indicating an unrecognized @var{query}.
23047 @end table
23048
23049 @item P @var{n@dots{}}=@var{r@dots{}}
23050 @anchor{write register packet}
23051 @cindex @samp{P} packet
23052 Write register @var{n@dots{}} with value @var{r@dots{}}. The register
23053 number @var{n} is in hexadecimal, and @var{r@dots{}} contains two hex
23054 digits for each byte in the register (target byte order).
23055
23056 Reply:
23057 @table @samp
23058 @item OK
23059 for success
23060 @item E @var{NN}
23061 for an error
23062 @end table
23063
23064 @item q @var{name} @var{params}@dots{}
23065 @itemx Q @var{name} @var{params}@dots{}
23066 @cindex @samp{q} packet
23067 @cindex @samp{Q} packet
23068 General query (@samp{q}) and set (@samp{Q}). These packets are
23069 described fully in @ref{General Query Packets}.
23070
23071 @item r
23072 @cindex @samp{r} packet
23073 Reset the entire system.
23074
23075 Don't use this packet; use the @samp{R} packet instead.
23076
23077 @item R @var{XX}
23078 @cindex @samp{R} packet
23079 Restart the program being debugged. @var{XX}, while needed, is ignored.
23080 This packet is only available in extended mode.
23081
23082 The @samp{R} packet has no reply.
23083
23084 @item s @r{[}@var{addr}@r{]}
23085 @cindex @samp{s} packet
23086 Single step. @var{addr} is the address at which to resume. If
23087 @var{addr} is omitted, resume at same address.
23088
23089 Reply:
23090 @xref{Stop Reply Packets}, for the reply specifications.
23091
23092 @item S @var{sig}@r{[};@var{addr}@r{]}
23093 @anchor{step with signal packet}
23094 @cindex @samp{S} packet
23095 Step with signal. This is analogous to the @samp{C} packet, but
23096 requests a single-step, rather than a normal resumption of execution.
23097
23098 Reply:
23099 @xref{Stop Reply Packets}, for the reply specifications.
23100
23101 @item t @var{addr}:@var{PP},@var{MM}
23102 @cindex @samp{t} packet
23103 Search backwards starting at address @var{addr} for a match with pattern
23104 @var{PP} and mask @var{MM}. @var{PP} and @var{MM} are 4 bytes.
23105 @var{addr} must be at least 3 digits.
23106
23107 @item T @var{XX}
23108 @cindex @samp{T} packet
23109 Find out if the thread XX is alive.
23110
23111 Reply:
23112 @table @samp
23113 @item OK
23114 thread is still alive
23115 @item E @var{NN}
23116 thread is dead
23117 @end table
23118
23119 @item v
23120 Packets starting with @samp{v} are identified by a multi-letter name,
23121 up to the first @samp{;} or @samp{?} (or the end of the packet).
23122
23123 @item vCont@r{[};@var{action}@r{[}:@var{tid}@r{]]}@dots{}
23124 @cindex @samp{vCont} packet
23125 Resume the inferior, specifying different actions for each thread.
23126 If an action is specified with no @var{tid}, then it is applied to any
23127 threads that don't have a specific action specified; if no default action is
23128 specified then other threads should remain stopped. Specifying multiple
23129 default actions is an error; specifying no actions is also an error.
23130 Thread IDs are specified in hexadecimal. Currently supported actions are:
23131
23132 @table @samp
23133 @item c
23134 Continue.
23135 @item C @var{sig}
23136 Continue with signal @var{sig}. @var{sig} should be two hex digits.
23137 @item s
23138 Step.
23139 @item S @var{sig}
23140 Step with signal @var{sig}. @var{sig} should be two hex digits.
23141 @end table
23142
23143 The optional @var{addr} argument normally associated with these packets is
23144 not supported in @samp{vCont}.
23145
23146 Reply:
23147 @xref{Stop Reply Packets}, for the reply specifications.
23148
23149 @item vCont?
23150 @cindex @samp{vCont?} packet
23151 Request a list of actions supporetd by the @samp{vCont} packet.
23152
23153 Reply:
23154 @table @samp
23155 @item vCont@r{[};@var{action}@dots{}@r{]}
23156 The @samp{vCont} packet is supported. Each @var{action} is a supported
23157 command in the @samp{vCont} packet.
23158 @item
23159 The @samp{vCont} packet is not supported.
23160 @end table
23161
23162 @item vFlashErase:@var{addr},@var{length}
23163 @cindex @samp{vFlashErase} packet
23164 Direct the stub to erase @var{length} bytes of flash starting at
23165 @var{addr}. The region may enclose any number of flash blocks, but
23166 its start and end must fall on block boundaries, as indicated by the
23167 flash block size appearing in the memory map (@pxref{Memory map
23168 format}). @value{GDBN} groups flash memory programming operations
23169 together, and sends a @samp{vFlashDone} request after each group; the
23170 stub is allowed to delay erase operation until the @samp{vFlashDone}
23171 packet is received.
23172
23173 Reply:
23174 @table @samp
23175 @item OK
23176 for success
23177 @item E @var{NN}
23178 for an error
23179 @end table
23180
23181 @item vFlashWrite:@var{addr}:@var{XX@dots{}}
23182 @cindex @samp{vFlashWrite} packet
23183 Direct the stub to write data to flash address @var{addr}. The data
23184 is passed in binary form using the same encoding as for the @samp{X}
23185 packet (@pxref{Binary Data}). The memory ranges specified by
23186 @samp{vFlashWrite} packets preceding a @samp{vFlashDone} packet must
23187 not overlap, and must appear in order of increasing addresses
23188 (although @samp{vFlashErase} packets for higher addresses may already
23189 have been received; the ordering is guaranteed only between
23190 @samp{vFlashWrite} packets). If a packet writes to an address that was
23191 neither erased by a preceding @samp{vFlashErase} packet nor by some other
23192 target-specific method, the results are unpredictable.
23193
23194
23195 Reply:
23196 @table @samp
23197 @item OK
23198 for success
23199 @item E.memtype
23200 for vFlashWrite addressing non-flash memory
23201 @item E @var{NN}
23202 for an error
23203 @end table
23204
23205 @item vFlashDone
23206 @cindex @samp{vFlashDone} packet
23207 Indicate to the stub that flash programming operation is finished.
23208 The stub is permitted to delay or batch the effects of a group of
23209 @samp{vFlashErase} and @samp{vFlashWrite} packets until a
23210 @samp{vFlashDone} packet is received. The contents of the affected
23211 regions of flash memory are unpredictable until the @samp{vFlashDone}
23212 request is completed.
23213
23214 @item X @var{addr},@var{length}:@var{XX@dots{}}
23215 @anchor{X packet}
23216 @cindex @samp{X} packet
23217 Write data to memory, where the data is transmitted in binary.
23218 @var{addr} is address, @var{length} is number of bytes,
23219 @samp{@var{XX}@dots{}} is binary data (@pxref{Binary Data}).
23220
23221 Reply:
23222 @table @samp
23223 @item OK
23224 for success
23225 @item E @var{NN}
23226 for an error
23227 @end table
23228
23229 @item z @var{type},@var{addr},@var{length}
23230 @itemx Z @var{type},@var{addr},@var{length}
23231 @anchor{insert breakpoint or watchpoint packet}
23232 @cindex @samp{z} packet
23233 @cindex @samp{Z} packets
23234 Insert (@samp{Z}) or remove (@samp{z}) a @var{type} breakpoint or
23235 watchpoint starting at address @var{address} and covering the next
23236 @var{length} bytes.
23237
23238 Each breakpoint and watchpoint packet @var{type} is documented
23239 separately.
23240
23241 @emph{Implementation notes: A remote target shall return an empty string
23242 for an unrecognized breakpoint or watchpoint packet @var{type}. A
23243 remote target shall support either both or neither of a given
23244 @samp{Z@var{type}@dots{}} and @samp{z@var{type}@dots{}} packet pair. To
23245 avoid potential problems with duplicate packets, the operations should
23246 be implemented in an idempotent way.}
23247
23248 @item z0,@var{addr},@var{length}
23249 @itemx Z0,@var{addr},@var{length}
23250 @cindex @samp{z0} packet
23251 @cindex @samp{Z0} packet
23252 Insert (@samp{Z0}) or remove (@samp{z0}) a memory breakpoint at address
23253 @var{addr} of size @var{length}.
23254
23255 A memory breakpoint is implemented by replacing the instruction at
23256 @var{addr} with a software breakpoint or trap instruction. The
23257 @var{length} is used by targets that indicates the size of the
23258 breakpoint (in bytes) that should be inserted (e.g., the @sc{arm} and
23259 @sc{mips} can insert either a 2 or 4 byte breakpoint).
23260
23261 @emph{Implementation note: It is possible for a target to copy or move
23262 code that contains memory breakpoints (e.g., when implementing
23263 overlays). The behavior of this packet, in the presence of such a
23264 target, is not defined.}
23265
23266 Reply:
23267 @table @samp
23268 @item OK
23269 success
23270 @item
23271 not supported
23272 @item E @var{NN}
23273 for an error
23274 @end table
23275
23276 @item z1,@var{addr},@var{length}
23277 @itemx Z1,@var{addr},@var{length}
23278 @cindex @samp{z1} packet
23279 @cindex @samp{Z1} packet
23280 Insert (@samp{Z1}) or remove (@samp{z1}) a hardware breakpoint at
23281 address @var{addr} of size @var{length}.
23282
23283 A hardware breakpoint is implemented using a mechanism that is not
23284 dependant on being able to modify the target's memory.
23285
23286 @emph{Implementation note: A hardware breakpoint is not affected by code
23287 movement.}
23288
23289 Reply:
23290 @table @samp
23291 @item OK
23292 success
23293 @item
23294 not supported
23295 @item E @var{NN}
23296 for an error
23297 @end table
23298
23299 @item z2,@var{addr},@var{length}
23300 @itemx Z2,@var{addr},@var{length}
23301 @cindex @samp{z2} packet
23302 @cindex @samp{Z2} packet
23303 Insert (@samp{Z2}) or remove (@samp{z2}) a write watchpoint.
23304
23305 Reply:
23306 @table @samp
23307 @item OK
23308 success
23309 @item
23310 not supported
23311 @item E @var{NN}
23312 for an error
23313 @end table
23314
23315 @item z3,@var{addr},@var{length}
23316 @itemx Z3,@var{addr},@var{length}
23317 @cindex @samp{z3} packet
23318 @cindex @samp{Z3} packet
23319 Insert (@samp{Z3}) or remove (@samp{z3}) a read watchpoint.
23320
23321 Reply:
23322 @table @samp
23323 @item OK
23324 success
23325 @item
23326 not supported
23327 @item E @var{NN}
23328 for an error
23329 @end table
23330
23331 @item z4,@var{addr},@var{length}
23332 @itemx Z4,@var{addr},@var{length}
23333 @cindex @samp{z4} packet
23334 @cindex @samp{Z4} packet
23335 Insert (@samp{Z4}) or remove (@samp{z4}) an access watchpoint.
23336
23337 Reply:
23338 @table @samp
23339 @item OK
23340 success
23341 @item
23342 not supported
23343 @item E @var{NN}
23344 for an error
23345 @end table
23346
23347 @end table
23348
23349 @node Stop Reply Packets
23350 @section Stop Reply Packets
23351 @cindex stop reply packets
23352
23353 The @samp{C}, @samp{c}, @samp{S}, @samp{s} and @samp{?} packets can
23354 receive any of the below as a reply. In the case of the @samp{C},
23355 @samp{c}, @samp{S} and @samp{s} packets, that reply is only returned
23356 when the target halts. In the below the exact meaning of @dfn{signal
23357 number} is poorly defined. In general one of the UNIX signal
23358 numbering conventions is used.
23359
23360 As in the description of request packets, we include spaces in the
23361 reply templates for clarity; these are not part of the reply packet's
23362 syntax. No @value{GDBN} stop reply packet uses spaces to separate its
23363 components.
23364
23365 @table @samp
23366
23367 @item S @var{AA}
23368 The program received signal number @var{AA} (a two-digit hexadecimal
23369 number). This is equivalent to a @samp{T} response with no
23370 @var{n}:@var{r} pairs.
23371
23372 @item T @var{AA} @var{n1}:@var{r1};@var{n2}:@var{r2};@dots{}
23373 @cindex @samp{T} packet reply
23374 The program received signal number @var{AA} (a two-digit hexadecimal
23375 number). This is equivalent to an @samp{S} response, except that the
23376 @samp{@var{n}:@var{r}} pairs can carry values of important registers
23377 and other information directly in the stop reply packet, reducing
23378 round-trip latency. Single-step and breakpoint traps are reported
23379 this way. Each @samp{@var{n}:@var{r}} pair is interpreted as follows:
23380 @enumerate
23381 @item
23382 If @var{n} is a hexadecimal number, it is a register number, and the
23383 corresponding @var{r} gives that register's value. @var{r} is a
23384 series of bytes in target byte order, with each byte given by a
23385 two-digit hex number.
23386 @item
23387 If @var{n} is @samp{thread}, then @var{r} is the thread process ID, in
23388 hex.
23389 @item
23390 If @var{n} is @samp{watch}, @samp{rwatch}, or @samp{awatch}, then the
23391 packet indicates a watchpoint hit, and @var{r} is the data address, in
23392 hex.
23393 @item
23394 Otherwise, @value{GDBN} should ignore this @samp{@var{n}:@var{r}} pair
23395 and go on to the next; this allows us to extend the protocol in the
23396 future.
23397 @end enumerate
23398
23399 @item W @var{AA}
23400 The process exited, and @var{AA} is the exit status. This is only
23401 applicable to certain targets.
23402
23403 @item X @var{AA}
23404 The process terminated with signal @var{AA}.
23405
23406 @item O @var{XX}@dots{}
23407 @samp{@var{XX}@dots{}} is hex encoding of @sc{ascii} data, to be
23408 written as the program's console output. This can happen at any time
23409 while the program is running and the debugger should continue to wait
23410 for @samp{W}, @samp{T}, etc.
23411
23412 @item F @var{call-id},@var{parameter}@dots{}
23413 @var{call-id} is the identifier which says which host system call should
23414 be called. This is just the name of the function. Translation into the
23415 correct system call is only applicable as it's defined in @value{GDBN}.
23416 @xref{File-I/O remote protocol extension}, for a list of implemented
23417 system calls.
23418
23419 @samp{@var{parameter}@dots{}} is a list of parameters as defined for
23420 this very system call.
23421
23422 The target replies with this packet when it expects @value{GDBN} to
23423 call a host system call on behalf of the target. @value{GDBN} replies
23424 with an appropriate @samp{F} packet and keeps up waiting for the next
23425 reply packet from the target. The latest @samp{C}, @samp{c}, @samp{S}
23426 or @samp{s} action is expected to be continued. @xref{File-I/O remote
23427 protocol extension}, for more details.
23428
23429 @end table
23430
23431 @node General Query Packets
23432 @section General Query Packets
23433 @cindex remote query requests
23434
23435 Packets starting with @samp{q} are @dfn{general query packets};
23436 packets starting with @samp{Q} are @dfn{general set packets}. General
23437 query and set packets are a semi-unified form for retrieving and
23438 sending information to and from the stub.
23439
23440 The initial letter of a query or set packet is followed by a name
23441 indicating what sort of thing the packet applies to. For example,
23442 @value{GDBN} may use a @samp{qSymbol} packet to exchange symbol
23443 definitions with the stub. These packet names follow some
23444 conventions:
23445
23446 @itemize @bullet
23447 @item
23448 The name must not contain commas, colons or semicolons.
23449 @item
23450 Most @value{GDBN} query and set packets have a leading upper case
23451 letter.
23452 @item
23453 The names of custom vendor packets should use a company prefix, in
23454 lower case, followed by a period. For example, packets designed at
23455 the Acme Corporation might begin with @samp{qacme.foo} (for querying
23456 foos) or @samp{Qacme.bar} (for setting bars).
23457 @end itemize
23458
23459 The name of a query or set packet should be separated from any
23460 parameters by a @samp{:}; the parameters themselves should be
23461 separated by @samp{,} or @samp{;}. Stubs must be careful to match the
23462 full packet name, and check for a separator or the end of the packet,
23463 in case two packet names share a common prefix. New packets should not begin
23464 with @samp{qC}, @samp{qP}, or @samp{qL}@footnote{The @samp{qP} and @samp{qL}
23465 packets predate these conventions, and have arguments without any terminator
23466 for the packet name; we suspect they are in widespread use in places that
23467 are difficult to upgrade. The @samp{qC} packet has no arguments, but some
23468 existing stubs (e.g.@: RedBoot) are known to not check for the end of the
23469 packet.}.
23470
23471 Like the descriptions of the other packets, each description here
23472 has a template showing the packet's overall syntax, followed by an
23473 explanation of the packet's meaning. We include spaces in some of the
23474 templates for clarity; these are not part of the packet's syntax. No
23475 @value{GDBN} packet uses spaces to separate its components.
23476
23477 Here are the currently defined query and set packets:
23478
23479 @table @samp
23480
23481 @item qC
23482 @cindex current thread, remote request
23483 @cindex @samp{qC} packet
23484 Return the current thread id.
23485
23486 Reply:
23487 @table @samp
23488 @item QC @var{pid}
23489 Where @var{pid} is an unsigned hexadecimal process id.
23490 @item @r{(anything else)}
23491 Any other reply implies the old pid.
23492 @end table
23493
23494 @item qCRC:@var{addr},@var{length}
23495 @cindex CRC of memory block, remote request
23496 @cindex @samp{qCRC} packet
23497 Compute the CRC checksum of a block of memory.
23498 Reply:
23499 @table @samp
23500 @item E @var{NN}
23501 An error (such as memory fault)
23502 @item C @var{crc32}
23503 The specified memory region's checksum is @var{crc32}.
23504 @end table
23505
23506 @item qfThreadInfo
23507 @itemx qsThreadInfo
23508 @cindex list active threads, remote request
23509 @cindex @samp{qfThreadInfo} packet
23510 @cindex @samp{qsThreadInfo} packet
23511 Obtain a list of all active thread ids from the target (OS). Since there
23512 may be too many active threads to fit into one reply packet, this query
23513 works iteratively: it may require more than one query/reply sequence to
23514 obtain the entire list of threads. The first query of the sequence will
23515 be the @samp{qfThreadInfo} query; subsequent queries in the
23516 sequence will be the @samp{qsThreadInfo} query.
23517
23518 NOTE: This packet replaces the @samp{qL} query (see below).
23519
23520 Reply:
23521 @table @samp
23522 @item m @var{id}
23523 A single thread id
23524 @item m @var{id},@var{id}@dots{}
23525 a comma-separated list of thread ids
23526 @item l
23527 (lower case letter @samp{L}) denotes end of list.
23528 @end table
23529
23530 In response to each query, the target will reply with a list of one or
23531 more thread ids, in big-endian unsigned hex, separated by commas.
23532 @value{GDBN} will respond to each reply with a request for more thread
23533 ids (using the @samp{qs} form of the query), until the target responds
23534 with @samp{l} (lower-case el, for @dfn{last}).
23535
23536 @item qGetTLSAddr:@var{thread-id},@var{offset},@var{lm}
23537 @cindex get thread-local storage address, remote request
23538 @cindex @samp{qGetTLSAddr} packet
23539 Fetch the address associated with thread local storage specified
23540 by @var{thread-id}, @var{offset}, and @var{lm}.
23541
23542 @var{thread-id} is the (big endian, hex encoded) thread id associated with the
23543 thread for which to fetch the TLS address.
23544
23545 @var{offset} is the (big endian, hex encoded) offset associated with the
23546 thread local variable. (This offset is obtained from the debug
23547 information associated with the variable.)
23548
23549 @var{lm} is the (big endian, hex encoded) OS/ABI specific encoding of the
23550 the load module associated with the thread local storage. For example,
23551 a @sc{gnu}/Linux system will pass the link map address of the shared
23552 object associated with the thread local storage under consideration.
23553 Other operating environments may choose to represent the load module
23554 differently, so the precise meaning of this parameter will vary.
23555
23556 Reply:
23557 @table @samp
23558 @item @var{XX}@dots{}
23559 Hex encoded (big endian) bytes representing the address of the thread
23560 local storage requested.
23561
23562 @item E @var{nn}
23563 An error occurred. @var{nn} are hex digits.
23564
23565 @item
23566 An empty reply indicates that @samp{qGetTLSAddr} is not supported by the stub.
23567 @end table
23568
23569 Use of this request packet is controlled by the @code{set remote
23570 get-thread-local-storage-address} command (@pxref{Remote
23571 configuration, set remote get-thread-local-storage-address}).
23572
23573 @item qL @var{startflag} @var{threadcount} @var{nextthread}
23574 Obtain thread information from RTOS. Where: @var{startflag} (one hex
23575 digit) is one to indicate the first query and zero to indicate a
23576 subsequent query; @var{threadcount} (two hex digits) is the maximum
23577 number of threads the response packet can contain; and @var{nextthread}
23578 (eight hex digits), for subsequent queries (@var{startflag} is zero), is
23579 returned in the response as @var{argthread}.
23580
23581 Don't use this packet; use the @samp{qfThreadInfo} query instead (see above).
23582
23583 Reply:
23584 @table @samp
23585 @item qM @var{count} @var{done} @var{argthread} @var{thread}@dots{}
23586 Where: @var{count} (two hex digits) is the number of threads being
23587 returned; @var{done} (one hex digit) is zero to indicate more threads
23588 and one indicates no further threads; @var{argthreadid} (eight hex
23589 digits) is @var{nextthread} from the request packet; @var{thread}@dots{}
23590 is a sequence of thread IDs from the target. @var{threadid} (eight hex
23591 digits). See @code{remote.c:parse_threadlist_response()}.
23592 @end table
23593
23594 @item qOffsets
23595 @cindex section offsets, remote request
23596 @cindex @samp{qOffsets} packet
23597 Get section offsets that the target used when re-locating the downloaded
23598 image. @emph{Note: while a @code{Bss} offset is included in the
23599 response, @value{GDBN} ignores this and instead applies the @code{Data}
23600 offset to the @code{Bss} section.}
23601
23602 Reply:
23603 @table @samp
23604 @item Text=@var{xxx};Data=@var{yyy};Bss=@var{zzz}
23605 @end table
23606
23607 @item qP @var{mode} @var{threadid}
23608 @cindex thread information, remote request
23609 @cindex @samp{qP} packet
23610 Returns information on @var{threadid}. Where: @var{mode} is a hex
23611 encoded 32 bit mode; @var{threadid} is a hex encoded 64 bit thread ID.
23612
23613 Don't use this packet; use the @samp{qThreadExtraInfo} query instead
23614 (see below).
23615
23616 Reply: see @code{remote.c:remote_unpack_thread_info_response()}.
23617
23618 @item qRcmd,@var{command}
23619 @cindex execute remote command, remote request
23620 @cindex @samp{qRcmd} packet
23621 @var{command} (hex encoded) is passed to the local interpreter for
23622 execution. Invalid commands should be reported using the output
23623 string. Before the final result packet, the target may also respond
23624 with a number of intermediate @samp{O@var{output}} console output
23625 packets. @emph{Implementors should note that providing access to a
23626 stubs's interpreter may have security implications}.
23627
23628 Reply:
23629 @table @samp
23630 @item OK
23631 A command response with no output.
23632 @item @var{OUTPUT}
23633 A command response with the hex encoded output string @var{OUTPUT}.
23634 @item E @var{NN}
23635 Indicate a badly formed request.
23636 @item
23637 An empty reply indicates that @samp{qRcmd} is not recognized.
23638 @end table
23639
23640 (Note that the @code{qRcmd} packet's name is separated from the
23641 command by a @samp{,}, not a @samp{:}, contrary to the naming
23642 conventions above. Please don't use this packet as a model for new
23643 packets.)
23644
23645 @item qSupported @r{[}:@var{gdbfeature} @r{[};@var{gdbfeature}@r{]}@dots{} @r{]}
23646 @cindex supported packets, remote query
23647 @cindex features of the remote protocol
23648 @cindex @samp{qSupported} packet
23649 @anchor{qSupported}
23650 Tell the remote stub about features supported by @value{GDBN}, and
23651 query the stub for features it supports. This packet allows
23652 @value{GDBN} and the remote stub to take advantage of each others'
23653 features. @samp{qSupported} also consolidates multiple feature probes
23654 at startup, to improve @value{GDBN} performance---a single larger
23655 packet performs better than multiple smaller probe packets on
23656 high-latency links. Some features may enable behavior which must not
23657 be on by default, e.g.@: because it would confuse older clients or
23658 stubs. Other features may describe packets which could be
23659 automatically probed for, but are not. These features must be
23660 reported before @value{GDBN} will use them. This ``default
23661 unsupported'' behavior is not appropriate for all packets, but it
23662 helps to keep the initial connection time under control with new
23663 versions of @value{GDBN} which support increasing numbers of packets.
23664
23665 Reply:
23666 @table @samp
23667 @item @var{stubfeature} @r{[};@var{stubfeature}@r{]}@dots{}
23668 The stub supports or does not support each returned @var{stubfeature},
23669 depending on the form of each @var{stubfeature} (see below for the
23670 possible forms).
23671 @item
23672 An empty reply indicates that @samp{qSupported} is not recognized,
23673 or that no features needed to be reported to @value{GDBN}.
23674 @end table
23675
23676 The allowed forms for each feature (either a @var{gdbfeature} in the
23677 @samp{qSupported} packet, or a @var{stubfeature} in the response)
23678 are:
23679
23680 @table @samp
23681 @item @var{name}=@var{value}
23682 The remote protocol feature @var{name} is supported, and associated
23683 with the specified @var{value}. The format of @var{value} depends
23684 on the feature, but it must not include a semicolon.
23685 @item @var{name}+
23686 The remote protocol feature @var{name} is supported, and does not
23687 need an associated value.
23688 @item @var{name}-
23689 The remote protocol feature @var{name} is not supported.
23690 @item @var{name}?
23691 The remote protocol feature @var{name} may be supported, and
23692 @value{GDBN} should auto-detect support in some other way when it is
23693 needed. This form will not be used for @var{gdbfeature} notifications,
23694 but may be used for @var{stubfeature} responses.
23695 @end table
23696
23697 Whenever the stub receives a @samp{qSupported} request, the
23698 supplied set of @value{GDBN} features should override any previous
23699 request. This allows @value{GDBN} to put the stub in a known
23700 state, even if the stub had previously been communicating with
23701 a different version of @value{GDBN}.
23702
23703 No values of @var{gdbfeature} (for the packet sent by @value{GDBN})
23704 are defined yet. Stubs should ignore any unknown values for
23705 @var{gdbfeature}. Any @value{GDBN} which sends a @samp{qSupported}
23706 packet supports receiving packets of unlimited length (earlier
23707 versions of @value{GDBN} may reject overly long responses). Values
23708 for @var{gdbfeature} may be defined in the future to let the stub take
23709 advantage of new features in @value{GDBN}, e.g.@: incompatible
23710 improvements in the remote protocol---support for unlimited length
23711 responses would be a @var{gdbfeature} example, if it were not implied by
23712 the @samp{qSupported} query. The stub's reply should be independent
23713 of the @var{gdbfeature} entries sent by @value{GDBN}; first @value{GDBN}
23714 describes all the features it supports, and then the stub replies with
23715 all the features it supports.
23716
23717 Similarly, @value{GDBN} will silently ignore unrecognized stub feature
23718 responses, as long as each response uses one of the standard forms.
23719
23720 Some features are flags. A stub which supports a flag feature
23721 should respond with a @samp{+} form response. Other features
23722 require values, and the stub should respond with an @samp{=}
23723 form response.
23724
23725 Each feature has a default value, which @value{GDBN} will use if
23726 @samp{qSupported} is not available or if the feature is not mentioned
23727 in the @samp{qSupported} response. The default values are fixed; a
23728 stub is free to omit any feature responses that match the defaults.
23729
23730 Not all features can be probed, but for those which can, the probing
23731 mechanism is useful: in some cases, a stub's internal
23732 architecture may not allow the protocol layer to know some information
23733 about the underlying target in advance. This is especially common in
23734 stubs which may be configured for multiple targets.
23735
23736 These are the currently defined stub features and their properties:
23737
23738 @multitable @columnfractions 0.25 0.2 0.2 0.2
23739 @c NOTE: The first row should be @headitem, but we do not yet require
23740 @c a new enough version of Texinfo (4.7) to use @headitem.
23741 @item Feature Name
23742 @tab Value Required
23743 @tab Default
23744 @tab Probe Allowed
23745
23746 @item @samp{PacketSize}
23747 @tab Yes
23748 @tab @samp{-}
23749 @tab No
23750
23751 @item @samp{qXfer:auxv:read}
23752 @tab No
23753 @tab @samp{-}
23754 @tab Yes
23755
23756 @item @samp{qXfer:memory-map:read}
23757 @tab No
23758 @tab @samp{-}
23759 @tab Yes
23760
23761 @end multitable
23762
23763 These are the currently defined stub features, in more detail:
23764
23765 @table @samp
23766 @cindex packet size, remote protocol
23767 @item PacketSize=@var{bytes}
23768 The remote stub can accept packets up to at least @var{bytes} in
23769 length. @value{GDBN} will send packets up to this size for bulk
23770 transfers, and will never send larger packets. This is a limit on the
23771 data characters in the packet, including the frame and checksum.
23772 There is no trailing NUL byte in a remote protocol packet; if the stub
23773 stores packets in a NUL-terminated format, it should allow an extra
23774 byte in its buffer for the NUL. If this stub feature is not supported,
23775 @value{GDBN} guesses based on the size of the @samp{g} packet response.
23776
23777 @item qXfer:auxv:read
23778 The remote stub understands the @samp{qXfer:auxv:read} packet
23779 (@pxref{qXfer auxiliary vector read}).
23780
23781 @end table
23782
23783 @item qSymbol::
23784 @cindex symbol lookup, remote request
23785 @cindex @samp{qSymbol} packet
23786 Notify the target that @value{GDBN} is prepared to serve symbol lookup
23787 requests. Accept requests from the target for the values of symbols.
23788
23789 Reply:
23790 @table @samp
23791 @item OK
23792 The target does not need to look up any (more) symbols.
23793 @item qSymbol:@var{sym_name}
23794 The target requests the value of symbol @var{sym_name} (hex encoded).
23795 @value{GDBN} may provide the value by using the
23796 @samp{qSymbol:@var{sym_value}:@var{sym_name}} message, described
23797 below.
23798 @end table
23799
23800 @item qSymbol:@var{sym_value}:@var{sym_name}
23801 Set the value of @var{sym_name} to @var{sym_value}.
23802
23803 @var{sym_name} (hex encoded) is the name of a symbol whose value the
23804 target has previously requested.
23805
23806 @var{sym_value} (hex) is the value for symbol @var{sym_name}. If
23807 @value{GDBN} cannot supply a value for @var{sym_name}, then this field
23808 will be empty.
23809
23810 Reply:
23811 @table @samp
23812 @item OK
23813 The target does not need to look up any (more) symbols.
23814 @item qSymbol:@var{sym_name}
23815 The target requests the value of a new symbol @var{sym_name} (hex
23816 encoded). @value{GDBN} will continue to supply the values of symbols
23817 (if available), until the target ceases to request them.
23818 @end table
23819
23820 @item QTDP
23821 @itemx QTFrame
23822 @xref{Tracepoint Packets}.
23823
23824 @item qThreadExtraInfo,@var{id}
23825 @cindex thread attributes info, remote request
23826 @cindex @samp{qThreadExtraInfo} packet
23827 Obtain a printable string description of a thread's attributes from
23828 the target OS. @var{id} is a thread-id in big-endian hex. This
23829 string may contain anything that the target OS thinks is interesting
23830 for @value{GDBN} to tell the user about the thread. The string is
23831 displayed in @value{GDBN}'s @code{info threads} display. Some
23832 examples of possible thread extra info strings are @samp{Runnable}, or
23833 @samp{Blocked on Mutex}.
23834
23835 Reply:
23836 @table @samp
23837 @item @var{XX}@dots{}
23838 Where @samp{@var{XX}@dots{}} is a hex encoding of @sc{ascii} data,
23839 comprising the printable string containing the extra information about
23840 the thread's attributes.
23841 @end table
23842
23843 (Note that the @code{qThreadExtraInfo} packet's name is separated from
23844 the command by a @samp{,}, not a @samp{:}, contrary to the naming
23845 conventions above. Please don't use this packet as a model for new
23846 packets.)
23847
23848 @item QTStart
23849 @itemx QTStop
23850 @itemx QTinit
23851 @itemx QTro
23852 @itemx qTStatus
23853 @xref{Tracepoint Packets}.
23854
23855 @item qXfer:@var{object}:read:@var{annex}:@var{offset},@var{length}
23856 @cindex read special object, remote request
23857 @cindex @samp{qXfer} packet
23858 @anchor{qXfer read}
23859 Read uninterpreted bytes from the target's special data area
23860 identified by the keyword @var{object}. Request @var{length} bytes
23861 starting at @var{offset} bytes into the data. The content and
23862 encoding of @var{annex} is specific to the object; it can supply
23863 additional details about what data to access.
23864
23865 Here are the specific requests of this form defined so far. All
23866 @samp{qXfer:@var{object}:read:@dots{}} requests use the same reply
23867 formats, listed below.
23868
23869 @table @samp
23870 @item qXfer:auxv:read::@var{offset},@var{length}
23871 @anchor{qXfer auxiliary vector read}
23872 Access the target's @dfn{auxiliary vector}. @xref{OS Information,
23873 auxiliary vector}, and @ref{Remote configuration,
23874 read-aux-vector-packet}. Note @var{annex} must be empty.
23875
23876 This packet is not probed by default; the remote stub must request it,
23877 by suppling an appropriate @samp{qSupported} response (@pxref{qSupported}).
23878 @end table
23879
23880 @table @samp
23881 @item qXfer:memory-map:read::@var{offset},@var{length}
23882 @anchor{qXfer memory map read}
23883 Access the target's @dfn{memory-map}. @xref{Memory map format}. The
23884 annex part of the generic @samp{qXfer} packet must be empty
23885 (@pxref{qXfer read}).
23886
23887 This packet is not probed by default; the remote stub must request it,
23888 by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}).
23889 @end table
23890
23891 Reply:
23892 @table @samp
23893 @item m @var{data}
23894 Data @var{data} (@pxref{Binary Data}) has been read from the
23895 target. There may be more data at a higher address (although
23896 it is permitted to return @samp{m} even for the last valid
23897 block of data, as long as at least one byte of data was read).
23898 @var{data} may have fewer bytes than the @var{length} in the
23899 request.
23900
23901 @item l @var{data}
23902 Data @var{data} (@pxref{Binary Data}) has been read from the target.
23903 There is no more data to be read. @var{data} may have fewer bytes
23904 than the @var{length} in the request.
23905
23906 @item l
23907 The @var{offset} in the request is at the end of the data.
23908 There is no more data to be read.
23909
23910 @item E00
23911 The request was malformed, or @var{annex} was invalid.
23912
23913 @item E @var{nn}
23914 The offset was invalid, or there was an error encountered reading the data.
23915 @var{nn} is a hex-encoded @code{errno} value.
23916
23917 @item
23918 An empty reply indicates the @var{object} string was not recognized by
23919 the stub, or that the object does not support reading.
23920 @end table
23921
23922 @item qXfer:@var{object}:write:@var{annex}:@var{offset}:@var{data}@dots{}
23923 @cindex write data into object, remote request
23924 Write uninterpreted bytes into the target's special data area
23925 identified by the keyword @var{object}, starting at @var{offset} bytes
23926 into the data. @samp{@var{data}@dots{}} is the binary-encoded data
23927 (@pxref{Binary Data}) to be written. The content and encoding of @var{annex}
23928 is specific to the object; it can supply additional details about what data
23929 to access.
23930
23931 No requests of this form are presently in use. This specification
23932 serves as a placeholder to document the common format that new
23933 specific request specifications ought to use.
23934
23935 Reply:
23936 @table @samp
23937 @item @var{nn}
23938 @var{nn} (hex encoded) is the number of bytes written.
23939 This may be fewer bytes than supplied in the request.
23940
23941 @item E00
23942 The request was malformed, or @var{annex} was invalid.
23943
23944 @item E @var{nn}
23945 The offset was invalid, or there was an error encountered writing the data.
23946 @var{nn} is a hex-encoded @code{errno} value.
23947
23948 @item
23949 An empty reply indicates the @var{object} string was not
23950 recognized by the stub, or that the object does not support writing.
23951 @end table
23952
23953 @item qXfer:@var{object}:@var{operation}:@dots{}
23954 Requests of this form may be added in the future. When a stub does
23955 not recognize the @var{object} keyword, or its support for
23956 @var{object} does not recognize the @var{operation} keyword, the stub
23957 must respond with an empty packet.
23958
23959 @end table
23960
23961 @node Register Packet Format
23962 @section Register Packet Format
23963
23964 The following @code{g}/@code{G} packets have previously been defined.
23965 In the below, some thirty-two bit registers are transferred as
23966 sixty-four bits. Those registers should be zero/sign extended (which?)
23967 to fill the space allocated. Register bytes are transferred in target
23968 byte order. The two nibbles within a register byte are transferred
23969 most-significant - least-significant.
23970
23971 @table @r
23972
23973 @item MIPS32
23974
23975 All registers are transferred as thirty-two bit quantities in the order:
23976 32 general-purpose; sr; lo; hi; bad; cause; pc; 32 floating-point
23977 registers; fsr; fir; fp.
23978
23979 @item MIPS64
23980
23981 All registers are transferred as sixty-four bit quantities (including
23982 thirty-two bit registers such as @code{sr}). The ordering is the same
23983 as @code{MIPS32}.
23984
23985 @end table
23986
23987 @node Tracepoint Packets
23988 @section Tracepoint Packets
23989 @cindex tracepoint packets
23990 @cindex packets, tracepoint
23991
23992 Here we describe the packets @value{GDBN} uses to implement
23993 tracepoints (@pxref{Tracepoints}).
23994
23995 @table @samp
23996
23997 @item QTDP:@var{n}:@var{addr}:@var{ena}:@var{step}:@var{pass}@r{[}-@r{]}
23998 Create a new tracepoint, number @var{n}, at @var{addr}. If @var{ena}
23999 is @samp{E}, then the tracepoint is enabled; if it is @samp{D}, then
24000 the tracepoint is disabled. @var{step} is the tracepoint's step
24001 count, and @var{pass} is its pass count. If the trailing @samp{-} is
24002 present, further @samp{QTDP} packets will follow to specify this
24003 tracepoint's actions.
24004
24005 Replies:
24006 @table @samp
24007 @item OK
24008 The packet was understood and carried out.
24009 @item
24010 The packet was not recognized.
24011 @end table
24012
24013 @item QTDP:-@var{n}:@var{addr}:@r{[}S@r{]}@var{action}@dots{}@r{[}-@r{]}
24014 Define actions to be taken when a tracepoint is hit. @var{n} and
24015 @var{addr} must be the same as in the initial @samp{QTDP} packet for
24016 this tracepoint. This packet may only be sent immediately after
24017 another @samp{QTDP} packet that ended with a @samp{-}. If the
24018 trailing @samp{-} is present, further @samp{QTDP} packets will follow,
24019 specifying more actions for this tracepoint.
24020
24021 In the series of action packets for a given tracepoint, at most one
24022 can have an @samp{S} before its first @var{action}. If such a packet
24023 is sent, it and the following packets define ``while-stepping''
24024 actions. Any prior packets define ordinary actions --- that is, those
24025 taken when the tracepoint is first hit. If no action packet has an
24026 @samp{S}, then all the packets in the series specify ordinary
24027 tracepoint actions.
24028
24029 The @samp{@var{action}@dots{}} portion of the packet is a series of
24030 actions, concatenated without separators. Each action has one of the
24031 following forms:
24032
24033 @table @samp
24034
24035 @item R @var{mask}
24036 Collect the registers whose bits are set in @var{mask}. @var{mask} is
24037 a hexadecimal number whose @var{i}'th bit is set if register number
24038 @var{i} should be collected. (The least significant bit is numbered
24039 zero.) Note that @var{mask} may be any number of digits long; it may
24040 not fit in a 32-bit word.
24041
24042 @item M @var{basereg},@var{offset},@var{len}
24043 Collect @var{len} bytes of memory starting at the address in register
24044 number @var{basereg}, plus @var{offset}. If @var{basereg} is
24045 @samp{-1}, then the range has a fixed address: @var{offset} is the
24046 address of the lowest byte to collect. The @var{basereg},
24047 @var{offset}, and @var{len} parameters are all unsigned hexadecimal
24048 values (the @samp{-1} value for @var{basereg} is a special case).
24049
24050 @item X @var{len},@var{expr}
24051 Evaluate @var{expr}, whose length is @var{len}, and collect memory as
24052 it directs. @var{expr} is an agent expression, as described in
24053 @ref{Agent Expressions}. Each byte of the expression is encoded as a
24054 two-digit hex number in the packet; @var{len} is the number of bytes
24055 in the expression (and thus one-half the number of hex digits in the
24056 packet).
24057
24058 @end table
24059
24060 Any number of actions may be packed together in a single @samp{QTDP}
24061 packet, as long as the packet does not exceed the maximum packet
24062 length (400 bytes, for many stubs). There may be only one @samp{R}
24063 action per tracepoint, and it must precede any @samp{M} or @samp{X}
24064 actions. Any registers referred to by @samp{M} and @samp{X} actions
24065 must be collected by a preceding @samp{R} action. (The
24066 ``while-stepping'' actions are treated as if they were attached to a
24067 separate tracepoint, as far as these restrictions are concerned.)
24068
24069 Replies:
24070 @table @samp
24071 @item OK
24072 The packet was understood and carried out.
24073 @item
24074 The packet was not recognized.
24075 @end table
24076
24077 @item QTFrame:@var{n}
24078 Select the @var{n}'th tracepoint frame from the buffer, and use the
24079 register and memory contents recorded there to answer subsequent
24080 request packets from @value{GDBN}.
24081
24082 A successful reply from the stub indicates that the stub has found the
24083 requested frame. The response is a series of parts, concatenated
24084 without separators, describing the frame we selected. Each part has
24085 one of the following forms:
24086
24087 @table @samp
24088 @item F @var{f}
24089 The selected frame is number @var{n} in the trace frame buffer;
24090 @var{f} is a hexadecimal number. If @var{f} is @samp{-1}, then there
24091 was no frame matching the criteria in the request packet.
24092
24093 @item T @var{t}
24094 The selected trace frame records a hit of tracepoint number @var{t};
24095 @var{t} is a hexadecimal number.
24096
24097 @end table
24098
24099 @item QTFrame:pc:@var{addr}
24100 Like @samp{QTFrame:@var{n}}, but select the first tracepoint frame after the
24101 currently selected frame whose PC is @var{addr};
24102 @var{addr} is a hexadecimal number.
24103
24104 @item QTFrame:tdp:@var{t}
24105 Like @samp{QTFrame:@var{n}}, but select the first tracepoint frame after the
24106 currently selected frame that is a hit of tracepoint @var{t}; @var{t}
24107 is a hexadecimal number.
24108
24109 @item QTFrame:range:@var{start}:@var{end}
24110 Like @samp{QTFrame:@var{n}}, but select the first tracepoint frame after the
24111 currently selected frame whose PC is between @var{start} (inclusive)
24112 and @var{end} (exclusive); @var{start} and @var{end} are hexadecimal
24113 numbers.
24114
24115 @item QTFrame:outside:@var{start}:@var{end}
24116 Like @samp{QTFrame:range:@var{start}:@var{end}}, but select the first
24117 frame @emph{outside} the given range of addresses.
24118
24119 @item QTStart
24120 Begin the tracepoint experiment. Begin collecting data from tracepoint
24121 hits in the trace frame buffer.
24122
24123 @item QTStop
24124 End the tracepoint experiment. Stop collecting trace frames.
24125
24126 @item QTinit
24127 Clear the table of tracepoints, and empty the trace frame buffer.
24128
24129 @item QTro:@var{start1},@var{end1}:@var{start2},@var{end2}:@dots{}
24130 Establish the given ranges of memory as ``transparent''. The stub
24131 will answer requests for these ranges from memory's current contents,
24132 if they were not collected as part of the tracepoint hit.
24133
24134 @value{GDBN} uses this to mark read-only regions of memory, like those
24135 containing program code. Since these areas never change, they should
24136 still have the same contents they did when the tracepoint was hit, so
24137 there's no reason for the stub to refuse to provide their contents.
24138
24139 @item qTStatus
24140 Ask the stub if there is a trace experiment running right now.
24141
24142 Replies:
24143 @table @samp
24144 @item T0
24145 There is no trace experiment running.
24146 @item T1
24147 There is a trace experiment running.
24148 @end table
24149
24150 @end table
24151
24152
24153 @node Interrupts
24154 @section Interrupts
24155 @cindex interrupts (remote protocol)
24156
24157 When a program on the remote target is running, @value{GDBN} may
24158 attempt to interrupt it by sending a @samp{Ctrl-C} or a @code{BREAK},
24159 control of which is specified via @value{GDBN}'s @samp{remotebreak}
24160 setting (@pxref{set remotebreak}).
24161
24162 The precise meaning of @code{BREAK} is defined by the transport
24163 mechanism and may, in fact, be undefined. @value{GDBN} does
24164 not currently define a @code{BREAK} mechanism for any of the network
24165 interfaces.
24166
24167 @samp{Ctrl-C}, on the other hand, is defined and implemented for all
24168 transport mechanisms. It is represented by sending the single byte
24169 @code{0x03} without any of the usual packet overhead described in
24170 the Overview section (@pxref{Overview}). When a @code{0x03} byte is
24171 transmitted as part of a packet, it is considered to be packet data
24172 and does @emph{not} represent an interrupt. E.g., an @samp{X} packet
24173 (@pxref{X packet}), used for binary downloads, may include an unescaped
24174 @code{0x03} as part of its packet.
24175
24176 Stubs are not required to recognize these interrupt mechanisms and the
24177 precise meaning associated with receipt of the interrupt is
24178 implementation defined. If the stub is successful at interrupting the
24179 running program, it is expected that it will send one of the Stop
24180 Reply Packets (@pxref{Stop Reply Packets}) to @value{GDBN} as a result
24181 of successfully stopping the program. Interrupts received while the
24182 program is stopped will be discarded.
24183
24184 @node Examples
24185 @section Examples
24186
24187 Example sequence of a target being re-started. Notice how the restart
24188 does not get any direct output:
24189
24190 @smallexample
24191 -> @code{R00}
24192 <- @code{+}
24193 @emph{target restarts}
24194 -> @code{?}
24195 <- @code{+}
24196 <- @code{T001:1234123412341234}
24197 -> @code{+}
24198 @end smallexample
24199
24200 Example sequence of a target being stepped by a single instruction:
24201
24202 @smallexample
24203 -> @code{G1445@dots{}}
24204 <- @code{+}
24205 -> @code{s}
24206 <- @code{+}
24207 @emph{time passes}
24208 <- @code{T001:1234123412341234}
24209 -> @code{+}
24210 -> @code{g}
24211 <- @code{+}
24212 <- @code{1455@dots{}}
24213 -> @code{+}
24214 @end smallexample
24215
24216 @node File-I/O remote protocol extension
24217 @section File-I/O remote protocol extension
24218 @cindex File-I/O remote protocol extension
24219
24220 @menu
24221 * File-I/O Overview::
24222 * Protocol basics::
24223 * The F request packet::
24224 * The F reply packet::
24225 * The Ctrl-C message::
24226 * Console I/O::
24227 * List of supported calls::
24228 * Protocol specific representation of datatypes::
24229 * Constants::
24230 * File-I/O Examples::
24231 @end menu
24232
24233 @node File-I/O Overview
24234 @subsection File-I/O Overview
24235 @cindex file-i/o overview
24236
24237 The @dfn{File I/O remote protocol extension} (short: File-I/O) allows the
24238 target to use the host's file system and console I/O to perform various
24239 system calls. System calls on the target system are translated into a
24240 remote protocol packet to the host system, which then performs the needed
24241 actions and returns a response packet to the target system.
24242 This simulates file system operations even on targets that lack file systems.
24243
24244 The protocol is defined to be independent of both the host and target systems.
24245 It uses its own internal representation of datatypes and values. Both
24246 @value{GDBN} and the target's @value{GDBN} stub are responsible for
24247 translating the system-dependent value representations into the internal
24248 protocol representations when data is transmitted.
24249
24250 The communication is synchronous. A system call is possible only when
24251 @value{GDBN} is waiting for a response from the @samp{C}, @samp{c}, @samp{S}
24252 or @samp{s} packets. While @value{GDBN} handles the request for a system call,
24253 the target is stopped to allow deterministic access to the target's
24254 memory. Therefore File-I/O is not interruptible by target signals. On
24255 the other hand, it is possible to interrupt File-I/O by a user interrupt
24256 (@samp{Ctrl-C}) within @value{GDBN}.
24257
24258 The target's request to perform a host system call does not finish
24259 the latest @samp{C}, @samp{c}, @samp{S} or @samp{s} action. That means,
24260 after finishing the system call, the target returns to continuing the
24261 previous activity (continue, step). No additional continue or step
24262 request from @value{GDBN} is required.
24263
24264 @smallexample
24265 (@value{GDBP}) continue
24266 <- target requests 'system call X'
24267 target is stopped, @value{GDBN} executes system call
24268 -> GDB returns result
24269 ... target continues, GDB returns to wait for the target
24270 <- target hits breakpoint and sends a Txx packet
24271 @end smallexample
24272
24273 The protocol only supports I/O on the console and to regular files on
24274 the host file system. Character or block special devices, pipes,
24275 named pipes, sockets or any other communication method on the host
24276 system are not supported by this protocol.
24277
24278 @node Protocol basics
24279 @subsection Protocol basics
24280 @cindex protocol basics, file-i/o
24281
24282 The File-I/O protocol uses the @code{F} packet as the request as well
24283 as reply packet. Since a File-I/O system call can only occur when
24284 @value{GDBN} is waiting for a response from the continuing or stepping target,
24285 the File-I/O request is a reply that @value{GDBN} has to expect as a result
24286 of a previous @samp{C}, @samp{c}, @samp{S} or @samp{s} packet.
24287 This @code{F} packet contains all information needed to allow @value{GDBN}
24288 to call the appropriate host system call:
24289
24290 @itemize @bullet
24291 @item
24292 A unique identifier for the requested system call.
24293
24294 @item
24295 All parameters to the system call. Pointers are given as addresses
24296 in the target memory address space. Pointers to strings are given as
24297 pointer/length pair. Numerical values are given as they are.
24298 Numerical control flags are given in a protocol specific representation.
24299
24300 @end itemize
24301
24302 At this point, @value{GDBN} has to perform the following actions.
24303
24304 @itemize @bullet
24305 @item
24306 If the parameters include pointer values to data needed as input to a
24307 system call, @value{GDBN} requests this data from the target with a
24308 standard @code{m} packet request. This additional communication has to be
24309 expected by the target implementation and is handled as any other @code{m}
24310 packet.
24311
24312 @item
24313 @value{GDBN} translates all value from protocol representation to host
24314 representation as needed. Datatypes are coerced into the host types.
24315
24316 @item
24317 @value{GDBN} calls the system call.
24318
24319 @item
24320 It then coerces datatypes back to protocol representation.
24321
24322 @item
24323 If the system call is expected to return data in buffer space specified
24324 by pointer parameters to the call, the data is transmitted to the
24325 target using a @code{M} or @code{X} packet. This packet has to be expected
24326 by the target implementation and is handled as any other @code{M} or @code{X}
24327 packet.
24328
24329 @end itemize
24330
24331 Eventually @value{GDBN} replies with another @code{F} packet which contains all
24332 necessary information for the target to continue. This at least contains
24333
24334 @itemize @bullet
24335 @item
24336 Return value.
24337
24338 @item
24339 @code{errno}, if has been changed by the system call.
24340
24341 @item
24342 ``Ctrl-C'' flag.
24343
24344 @end itemize
24345
24346 After having done the needed type and value coercion, the target continues
24347 the latest continue or step action.
24348
24349 @node The F request packet
24350 @subsection The @code{F} request packet
24351 @cindex file-i/o request packet
24352 @cindex @code{F} request packet
24353
24354 The @code{F} request packet has the following format:
24355
24356 @table @samp
24357 @item F@var{call-id},@var{parameter@dots{}}
24358
24359 @var{call-id} is the identifier to indicate the host system call to be called.
24360 This is just the name of the function.
24361
24362 @var{parameter@dots{}} are the parameters to the system call.
24363 Parameters are hexadecimal integer values, either the actual values in case
24364 of scalar datatypes, pointers to target buffer space in case of compound
24365 datatypes and unspecified memory areas, or pointer/length pairs in case
24366 of string parameters. These are appended to the @var{call-id} as a
24367 comma-delimited list. All values are transmitted in ASCII
24368 string representation, pointer/length pairs separated by a slash.
24369
24370 @end table
24371
24372
24373
24374 @node The F reply packet
24375 @subsection The @code{F} reply packet
24376 @cindex file-i/o reply packet
24377 @cindex @code{F} reply packet
24378
24379 The @code{F} reply packet has the following format:
24380
24381 @table @samp
24382
24383 @item F@var{retcode},@var{errno},@var{Ctrl-C flag};@var{call specific attachment}
24384
24385 @var{retcode} is the return code of the system call as hexadecimal value.
24386
24387 @var{errno} is the @code{errno} set by the call, in protocol specific representation.
24388 This parameter can be omitted if the call was successful.
24389
24390 @var{Ctrl-C flag} is only sent if the user requested a break. In this
24391 case, @var{errno} must be sent as well, even if the call was successful.
24392 The @var{Ctrl-C flag} itself consists of the character @samp{C}:
24393
24394 @smallexample
24395 F0,0,C
24396 @end smallexample
24397
24398 @noindent
24399 or, if the call was interrupted before the host call has been performed:
24400
24401 @smallexample
24402 F-1,4,C
24403 @end smallexample
24404
24405 @noindent
24406 assuming 4 is the protocol specific representation of @code{EINTR}.
24407
24408 @end table
24409
24410
24411 @node The Ctrl-C message
24412 @subsection The @samp{Ctrl-C} message
24413 @cindex ctrl-c message, in file-i/o protocol
24414
24415 If the @samp{Ctrl-C} flag is set in the @value{GDBN}
24416 reply packet (@pxref{The F reply packet}),
24417 the target should behave as if it had
24418 gotten a break message. The meaning for the target is ``system call
24419 interrupted by @code{SIGINT}''. Consequentially, the target should actually stop
24420 (as with a break message) and return to @value{GDBN} with a @code{T02}
24421 packet.
24422
24423 It's important for the target to know in which
24424 state the system call was interrupted. There are two possible cases:
24425
24426 @itemize @bullet
24427 @item
24428 The system call hasn't been performed on the host yet.
24429
24430 @item
24431 The system call on the host has been finished.
24432
24433 @end itemize
24434
24435 These two states can be distinguished by the target by the value of the
24436 returned @code{errno}. If it's the protocol representation of @code{EINTR}, the system
24437 call hasn't been performed. This is equivalent to the @code{EINTR} handling
24438 on POSIX systems. In any other case, the target may presume that the
24439 system call has been finished --- successfully or not --- and should behave
24440 as if the break message arrived right after the system call.
24441
24442 @value{GDBN} must behave reliably. If the system call has not been called
24443 yet, @value{GDBN} may send the @code{F} reply immediately, setting @code{EINTR} as
24444 @code{errno} in the packet. If the system call on the host has been finished
24445 before the user requests a break, the full action must be finished by
24446 @value{GDBN}. This requires sending @code{M} or @code{X} packets as necessary.
24447 The @code{F} packet may only be sent when either nothing has happened
24448 or the full action has been completed.
24449
24450 @node Console I/O
24451 @subsection Console I/O
24452 @cindex console i/o as part of file-i/o
24453
24454 By default and if not explicitely closed by the target system, the file
24455 descriptors 0, 1 and 2 are connected to the @value{GDBN} console. Output
24456 on the @value{GDBN} console is handled as any other file output operation
24457 (@code{write(1, @dots{})} or @code{write(2, @dots{})}). Console input is handled
24458 by @value{GDBN} so that after the target read request from file descriptor
24459 0 all following typing is buffered until either one of the following
24460 conditions is met:
24461
24462 @itemize @bullet
24463 @item
24464 The user types @kbd{Ctrl-c}. The behaviour is as explained above, and the
24465 @code{read}
24466 system call is treated as finished.
24467
24468 @item
24469 The user presses @key{RET}. This is treated as end of input with a trailing
24470 newline.
24471
24472 @item
24473 The user types @kbd{Ctrl-d}. This is treated as end of input. No trailing
24474 character (neither newline nor @samp{Ctrl-D}) is appended to the input.
24475
24476 @end itemize
24477
24478 If the user has typed more characters than fit in the buffer given to
24479 the @code{read} call, the trailing characters are buffered in @value{GDBN} until
24480 either another @code{read(0, @dots{})} is requested by the target, or debugging
24481 is stopped at the user's request.
24482
24483
24484 @node List of supported calls
24485 @subsection List of supported calls
24486 @cindex list of supported file-i/o calls
24487
24488 @menu
24489 * open::
24490 * close::
24491 * read::
24492 * write::
24493 * lseek::
24494 * rename::
24495 * unlink::
24496 * stat/fstat::
24497 * gettimeofday::
24498 * isatty::
24499 * system::
24500 @end menu
24501
24502 @node open
24503 @unnumberedsubsubsec open
24504 @cindex open, file-i/o system call
24505
24506 @table @asis
24507 @item Synopsis:
24508 @smallexample
24509 int open(const char *pathname, int flags);
24510 int open(const char *pathname, int flags, mode_t mode);
24511 @end smallexample
24512
24513 @item Request:
24514 @samp{Fopen,@var{pathptr}/@var{len},@var{flags},@var{mode}}
24515
24516 @noindent
24517 @var{flags} is the bitwise @code{OR} of the following values:
24518
24519 @table @code
24520 @item O_CREAT
24521 If the file does not exist it will be created. The host
24522 rules apply as far as file ownership and time stamps
24523 are concerned.
24524
24525 @item O_EXCL
24526 When used with @code{O_CREAT}, if the file already exists it is
24527 an error and open() fails.
24528
24529 @item O_TRUNC
24530 If the file already exists and the open mode allows
24531 writing (@code{O_RDWR} or @code{O_WRONLY} is given) it will be
24532 truncated to zero length.
24533
24534 @item O_APPEND
24535 The file is opened in append mode.
24536
24537 @item O_RDONLY
24538 The file is opened for reading only.
24539
24540 @item O_WRONLY
24541 The file is opened for writing only.
24542
24543 @item O_RDWR
24544 The file is opened for reading and writing.
24545 @end table
24546
24547 @noindent
24548 Other bits are silently ignored.
24549
24550
24551 @noindent
24552 @var{mode} is the bitwise @code{OR} of the following values:
24553
24554 @table @code
24555 @item S_IRUSR
24556 User has read permission.
24557
24558 @item S_IWUSR
24559 User has write permission.
24560
24561 @item S_IRGRP
24562 Group has read permission.
24563
24564 @item S_IWGRP
24565 Group has write permission.
24566
24567 @item S_IROTH
24568 Others have read permission.
24569
24570 @item S_IWOTH
24571 Others have write permission.
24572 @end table
24573
24574 @noindent
24575 Other bits are silently ignored.
24576
24577
24578 @item Return value:
24579 @code{open} returns the new file descriptor or -1 if an error
24580 occurred.
24581
24582 @item Errors:
24583
24584 @table @code
24585 @item EEXIST
24586 @var{pathname} already exists and @code{O_CREAT} and @code{O_EXCL} were used.
24587
24588 @item EISDIR
24589 @var{pathname} refers to a directory.
24590
24591 @item EACCES
24592 The requested access is not allowed.
24593
24594 @item ENAMETOOLONG
24595 @var{pathname} was too long.
24596
24597 @item ENOENT
24598 A directory component in @var{pathname} does not exist.
24599
24600 @item ENODEV
24601 @var{pathname} refers to a device, pipe, named pipe or socket.
24602
24603 @item EROFS
24604 @var{pathname} refers to a file on a read-only filesystem and
24605 write access was requested.
24606
24607 @item EFAULT
24608 @var{pathname} is an invalid pointer value.
24609
24610 @item ENOSPC
24611 No space on device to create the file.
24612
24613 @item EMFILE
24614 The process already has the maximum number of files open.
24615
24616 @item ENFILE
24617 The limit on the total number of files open on the system
24618 has been reached.
24619
24620 @item EINTR
24621 The call was interrupted by the user.
24622 @end table
24623
24624 @end table
24625
24626 @node close
24627 @unnumberedsubsubsec close
24628 @cindex close, file-i/o system call
24629
24630 @table @asis
24631 @item Synopsis:
24632 @smallexample
24633 int close(int fd);
24634 @end smallexample
24635
24636 @item Request:
24637 @samp{Fclose,@var{fd}}
24638
24639 @item Return value:
24640 @code{close} returns zero on success, or -1 if an error occurred.
24641
24642 @item Errors:
24643
24644 @table @code
24645 @item EBADF
24646 @var{fd} isn't a valid open file descriptor.
24647
24648 @item EINTR
24649 The call was interrupted by the user.
24650 @end table
24651
24652 @end table
24653
24654 @node read
24655 @unnumberedsubsubsec read
24656 @cindex read, file-i/o system call
24657
24658 @table @asis
24659 @item Synopsis:
24660 @smallexample
24661 int read(int fd, void *buf, unsigned int count);
24662 @end smallexample
24663
24664 @item Request:
24665 @samp{Fread,@var{fd},@var{bufptr},@var{count}}
24666
24667 @item Return value:
24668 On success, the number of bytes read is returned.
24669 Zero indicates end of file. If count is zero, read
24670 returns zero as well. On error, -1 is returned.
24671
24672 @item Errors:
24673
24674 @table @code
24675 @item EBADF
24676 @var{fd} is not a valid file descriptor or is not open for
24677 reading.
24678
24679 @item EFAULT
24680 @var{bufptr} is an invalid pointer value.
24681
24682 @item EINTR
24683 The call was interrupted by the user.
24684 @end table
24685
24686 @end table
24687
24688 @node write
24689 @unnumberedsubsubsec write
24690 @cindex write, file-i/o system call
24691
24692 @table @asis
24693 @item Synopsis:
24694 @smallexample
24695 int write(int fd, const void *buf, unsigned int count);
24696 @end smallexample
24697
24698 @item Request:
24699 @samp{Fwrite,@var{fd},@var{bufptr},@var{count}}
24700
24701 @item Return value:
24702 On success, the number of bytes written are returned.
24703 Zero indicates nothing was written. On error, -1
24704 is returned.
24705
24706 @item Errors:
24707
24708 @table @code
24709 @item EBADF
24710 @var{fd} is not a valid file descriptor or is not open for
24711 writing.
24712
24713 @item EFAULT
24714 @var{bufptr} is an invalid pointer value.
24715
24716 @item EFBIG
24717 An attempt was made to write a file that exceeds the
24718 host specific maximum file size allowed.
24719
24720 @item ENOSPC
24721 No space on device to write the data.
24722
24723 @item EINTR
24724 The call was interrupted by the user.
24725 @end table
24726
24727 @end table
24728
24729 @node lseek
24730 @unnumberedsubsubsec lseek
24731 @cindex lseek, file-i/o system call
24732
24733 @table @asis
24734 @item Synopsis:
24735 @smallexample
24736 long lseek (int fd, long offset, int flag);
24737 @end smallexample
24738
24739 @item Request:
24740 @samp{Flseek,@var{fd},@var{offset},@var{flag}}
24741
24742 @var{flag} is one of:
24743
24744 @table @code
24745 @item SEEK_SET
24746 The offset is set to @var{offset} bytes.
24747
24748 @item SEEK_CUR
24749 The offset is set to its current location plus @var{offset}
24750 bytes.
24751
24752 @item SEEK_END
24753 The offset is set to the size of the file plus @var{offset}
24754 bytes.
24755 @end table
24756
24757 @item Return value:
24758 On success, the resulting unsigned offset in bytes from
24759 the beginning of the file is returned. Otherwise, a
24760 value of -1 is returned.
24761
24762 @item Errors:
24763
24764 @table @code
24765 @item EBADF
24766 @var{fd} is not a valid open file descriptor.
24767
24768 @item ESPIPE
24769 @var{fd} is associated with the @value{GDBN} console.
24770
24771 @item EINVAL
24772 @var{flag} is not a proper value.
24773
24774 @item EINTR
24775 The call was interrupted by the user.
24776 @end table
24777
24778 @end table
24779
24780 @node rename
24781 @unnumberedsubsubsec rename
24782 @cindex rename, file-i/o system call
24783
24784 @table @asis
24785 @item Synopsis:
24786 @smallexample
24787 int rename(const char *oldpath, const char *newpath);
24788 @end smallexample
24789
24790 @item Request:
24791 @samp{Frename,@var{oldpathptr}/@var{len},@var{newpathptr}/@var{len}}
24792
24793 @item Return value:
24794 On success, zero is returned. On error, -1 is returned.
24795
24796 @item Errors:
24797
24798 @table @code
24799 @item EISDIR
24800 @var{newpath} is an existing directory, but @var{oldpath} is not a
24801 directory.
24802
24803 @item EEXIST
24804 @var{newpath} is a non-empty directory.
24805
24806 @item EBUSY
24807 @var{oldpath} or @var{newpath} is a directory that is in use by some
24808 process.
24809
24810 @item EINVAL
24811 An attempt was made to make a directory a subdirectory
24812 of itself.
24813
24814 @item ENOTDIR
24815 A component used as a directory in @var{oldpath} or new
24816 path is not a directory. Or @var{oldpath} is a directory
24817 and @var{newpath} exists but is not a directory.
24818
24819 @item EFAULT
24820 @var{oldpathptr} or @var{newpathptr} are invalid pointer values.
24821
24822 @item EACCES
24823 No access to the file or the path of the file.
24824
24825 @item ENAMETOOLONG
24826
24827 @var{oldpath} or @var{newpath} was too long.
24828
24829 @item ENOENT
24830 A directory component in @var{oldpath} or @var{newpath} does not exist.
24831
24832 @item EROFS
24833 The file is on a read-only filesystem.
24834
24835 @item ENOSPC
24836 The device containing the file has no room for the new
24837 directory entry.
24838
24839 @item EINTR
24840 The call was interrupted by the user.
24841 @end table
24842
24843 @end table
24844
24845 @node unlink
24846 @unnumberedsubsubsec unlink
24847 @cindex unlink, file-i/o system call
24848
24849 @table @asis
24850 @item Synopsis:
24851 @smallexample
24852 int unlink(const char *pathname);
24853 @end smallexample
24854
24855 @item Request:
24856 @samp{Funlink,@var{pathnameptr}/@var{len}}
24857
24858 @item Return value:
24859 On success, zero is returned. On error, -1 is returned.
24860
24861 @item Errors:
24862
24863 @table @code
24864 @item EACCES
24865 No access to the file or the path of the file.
24866
24867 @item EPERM
24868 The system does not allow unlinking of directories.
24869
24870 @item EBUSY
24871 The file @var{pathname} cannot be unlinked because it's
24872 being used by another process.
24873
24874 @item EFAULT
24875 @var{pathnameptr} is an invalid pointer value.
24876
24877 @item ENAMETOOLONG
24878 @var{pathname} was too long.
24879
24880 @item ENOENT
24881 A directory component in @var{pathname} does not exist.
24882
24883 @item ENOTDIR
24884 A component of the path is not a directory.
24885
24886 @item EROFS
24887 The file is on a read-only filesystem.
24888
24889 @item EINTR
24890 The call was interrupted by the user.
24891 @end table
24892
24893 @end table
24894
24895 @node stat/fstat
24896 @unnumberedsubsubsec stat/fstat
24897 @cindex fstat, file-i/o system call
24898 @cindex stat, file-i/o system call
24899
24900 @table @asis
24901 @item Synopsis:
24902 @smallexample
24903 int stat(const char *pathname, struct stat *buf);
24904 int fstat(int fd, struct stat *buf);
24905 @end smallexample
24906
24907 @item Request:
24908 @samp{Fstat,@var{pathnameptr}/@var{len},@var{bufptr}}@*
24909 @samp{Ffstat,@var{fd},@var{bufptr}}
24910
24911 @item Return value:
24912 On success, zero is returned. On error, -1 is returned.
24913
24914 @item Errors:
24915
24916 @table @code
24917 @item EBADF
24918 @var{fd} is not a valid open file.
24919
24920 @item ENOENT
24921 A directory component in @var{pathname} does not exist or the
24922 path is an empty string.
24923
24924 @item ENOTDIR
24925 A component of the path is not a directory.
24926
24927 @item EFAULT
24928 @var{pathnameptr} is an invalid pointer value.
24929
24930 @item EACCES
24931 No access to the file or the path of the file.
24932
24933 @item ENAMETOOLONG
24934 @var{pathname} was too long.
24935
24936 @item EINTR
24937 The call was interrupted by the user.
24938 @end table
24939
24940 @end table
24941
24942 @node gettimeofday
24943 @unnumberedsubsubsec gettimeofday
24944 @cindex gettimeofday, file-i/o system call
24945
24946 @table @asis
24947 @item Synopsis:
24948 @smallexample
24949 int gettimeofday(struct timeval *tv, void *tz);
24950 @end smallexample
24951
24952 @item Request:
24953 @samp{Fgettimeofday,@var{tvptr},@var{tzptr}}
24954
24955 @item Return value:
24956 On success, 0 is returned, -1 otherwise.
24957
24958 @item Errors:
24959
24960 @table @code
24961 @item EINVAL
24962 @var{tz} is a non-NULL pointer.
24963
24964 @item EFAULT
24965 @var{tvptr} and/or @var{tzptr} is an invalid pointer value.
24966 @end table
24967
24968 @end table
24969
24970 @node isatty
24971 @unnumberedsubsubsec isatty
24972 @cindex isatty, file-i/o system call
24973
24974 @table @asis
24975 @item Synopsis:
24976 @smallexample
24977 int isatty(int fd);
24978 @end smallexample
24979
24980 @item Request:
24981 @samp{Fisatty,@var{fd}}
24982
24983 @item Return value:
24984 Returns 1 if @var{fd} refers to the @value{GDBN} console, 0 otherwise.
24985
24986 @item Errors:
24987
24988 @table @code
24989 @item EINTR
24990 The call was interrupted by the user.
24991 @end table
24992
24993 @end table
24994
24995 Note that the @code{isatty} call is treated as a special case: it returns
24996 1 to the target if the file descriptor is attached
24997 to the @value{GDBN} console, 0 otherwise. Implementing through system calls
24998 would require implementing @code{ioctl} and would be more complex than
24999 needed.
25000
25001
25002 @node system
25003 @unnumberedsubsubsec system
25004 @cindex system, file-i/o system call
25005
25006 @table @asis
25007 @item Synopsis:
25008 @smallexample
25009 int system(const char *command);
25010 @end smallexample
25011
25012 @item Request:
25013 @samp{Fsystem,@var{commandptr}/@var{len}}
25014
25015 @item Return value:
25016 If @var{len} is zero, the return value indicates whether a shell is
25017 available. A zero return value indicates a shell is not available.
25018 For non-zero @var{len}, the value returned is -1 on error and the
25019 return status of the command otherwise. Only the exit status of the
25020 command is returned, which is extracted from the host's @code{system}
25021 return value by calling @code{WEXITSTATUS(retval)}. In case
25022 @file{/bin/sh} could not be executed, 127 is returned.
25023
25024 @item Errors:
25025
25026 @table @code
25027 @item EINTR
25028 The call was interrupted by the user.
25029 @end table
25030
25031 @end table
25032
25033 @value{GDBN} takes over the full task of calling the necessary host calls
25034 to perform the @code{system} call. The return value of @code{system} on
25035 the host is simplified before it's returned
25036 to the target. Any termination signal information from the child process
25037 is discarded, and the return value consists
25038 entirely of the exit status of the called command.
25039
25040 Due to security concerns, the @code{system} call is by default refused
25041 by @value{GDBN}. The user has to allow this call explicitly with the
25042 @code{set remote system-call-allowed 1} command.
25043
25044 @table @code
25045 @item set remote system-call-allowed
25046 @kindex set remote system-call-allowed
25047 Control whether to allow the @code{system} calls in the File I/O
25048 protocol for the remote target. The default is zero (disabled).
25049
25050 @item show remote system-call-allowed
25051 @kindex show remote system-call-allowed
25052 Show whether the @code{system} calls are allowed in the File I/O
25053 protocol.
25054 @end table
25055
25056 @node Protocol specific representation of datatypes
25057 @subsection Protocol specific representation of datatypes
25058 @cindex protocol specific representation of datatypes, in file-i/o protocol
25059
25060 @menu
25061 * Integral datatypes::
25062 * Pointer values::
25063 * Memory transfer::
25064 * struct stat::
25065 * struct timeval::
25066 @end menu
25067
25068 @node Integral datatypes
25069 @unnumberedsubsubsec Integral datatypes
25070 @cindex integral datatypes, in file-i/o protocol
25071
25072 The integral datatypes used in the system calls are @code{int},
25073 @code{unsigned int}, @code{long}, @code{unsigned long},
25074 @code{mode_t}, and @code{time_t}.
25075
25076 @code{int}, @code{unsigned int}, @code{mode_t} and @code{time_t} are
25077 implemented as 32 bit values in this protocol.
25078
25079 @code{long} and @code{unsigned long} are implemented as 64 bit types.
25080
25081 @xref{Limits}, for corresponding MIN and MAX values (similar to those
25082 in @file{limits.h}) to allow range checking on host and target.
25083
25084 @code{time_t} datatypes are defined as seconds since the Epoch.
25085
25086 All integral datatypes transferred as part of a memory read or write of a
25087 structured datatype e.g.@: a @code{struct stat} have to be given in big endian
25088 byte order.
25089
25090 @node Pointer values
25091 @unnumberedsubsubsec Pointer values
25092 @cindex pointer values, in file-i/o protocol
25093
25094 Pointers to target data are transmitted as they are. An exception
25095 is made for pointers to buffers for which the length isn't
25096 transmitted as part of the function call, namely strings. Strings
25097 are transmitted as a pointer/length pair, both as hex values, e.g.@:
25098
25099 @smallexample
25100 @code{1aaf/12}
25101 @end smallexample
25102
25103 @noindent
25104 which is a pointer to data of length 18 bytes at position 0x1aaf.
25105 The length is defined as the full string length in bytes, including
25106 the trailing null byte. For example, the string @code{"hello world"}
25107 at address 0x123456 is transmitted as
25108
25109 @smallexample
25110 @code{123456/d}
25111 @end smallexample
25112
25113 @node Memory transfer
25114 @unnumberedsubsubsec Memory transfer
25115 @cindex memory transfer, in file-i/o protocol
25116
25117 Structured data which is transferred using a memory read or write (for
25118 example, a @code{struct stat}) is expected to be in a protocol specific format
25119 with all scalar multibyte datatypes being big endian. Translation to
25120 this representation needs to be done both by the target before the @code{F}
25121 packet is sent, and by @value{GDBN} before
25122 it transfers memory to the target. Transferred pointers to structured
25123 data should point to the already-coerced data at any time.
25124
25125
25126 @node struct stat
25127 @unnumberedsubsubsec struct stat
25128 @cindex struct stat, in file-i/o protocol
25129
25130 The buffer of type @code{struct stat} used by the target and @value{GDBN}
25131 is defined as follows:
25132
25133 @smallexample
25134 struct stat @{
25135 unsigned int st_dev; /* device */
25136 unsigned int st_ino; /* inode */
25137 mode_t st_mode; /* protection */
25138 unsigned int st_nlink; /* number of hard links */
25139 unsigned int st_uid; /* user ID of owner */
25140 unsigned int st_gid; /* group ID of owner */
25141 unsigned int st_rdev; /* device type (if inode device) */
25142 unsigned long st_size; /* total size, in bytes */
25143 unsigned long st_blksize; /* blocksize for filesystem I/O */
25144 unsigned long st_blocks; /* number of blocks allocated */
25145 time_t st_atime; /* time of last access */
25146 time_t st_mtime; /* time of last modification */
25147 time_t st_ctime; /* time of last change */
25148 @};
25149 @end smallexample
25150
25151 The integral datatypes conform to the definitions given in the
25152 appropriate section (see @ref{Integral datatypes}, for details) so this
25153 structure is of size 64 bytes.
25154
25155 The values of several fields have a restricted meaning and/or
25156 range of values.
25157
25158 @table @code
25159
25160 @item st_dev
25161 A value of 0 represents a file, 1 the console.
25162
25163 @item st_ino
25164 No valid meaning for the target. Transmitted unchanged.
25165
25166 @item st_mode
25167 Valid mode bits are described in @ref{Constants}. Any other
25168 bits have currently no meaning for the target.
25169
25170 @item st_uid
25171 @itemx st_gid
25172 @itemx st_rdev
25173 No valid meaning for the target. Transmitted unchanged.
25174
25175 @item st_atime
25176 @itemx st_mtime
25177 @itemx st_ctime
25178 These values have a host and file system dependent
25179 accuracy. Especially on Windows hosts, the file system may not
25180 support exact timing values.
25181 @end table
25182
25183 The target gets a @code{struct stat} of the above representation and is
25184 responsible for coercing it to the target representation before
25185 continuing.
25186
25187 Note that due to size differences between the host, target, and protocol
25188 representations of @code{struct stat} members, these members could eventually
25189 get truncated on the target.
25190
25191 @node struct timeval
25192 @unnumberedsubsubsec struct timeval
25193 @cindex struct timeval, in file-i/o protocol
25194
25195 The buffer of type @code{struct timeval} used by the File-I/O protocol
25196 is defined as follows:
25197
25198 @smallexample
25199 struct timeval @{
25200 time_t tv_sec; /* second */
25201 long tv_usec; /* microsecond */
25202 @};
25203 @end smallexample
25204
25205 The integral datatypes conform to the definitions given in the
25206 appropriate section (see @ref{Integral datatypes}, for details) so this
25207 structure is of size 8 bytes.
25208
25209 @node Constants
25210 @subsection Constants
25211 @cindex constants, in file-i/o protocol
25212
25213 The following values are used for the constants inside of the
25214 protocol. @value{GDBN} and target are responsible for translating these
25215 values before and after the call as needed.
25216
25217 @menu
25218 * Open flags::
25219 * mode_t values::
25220 * Errno values::
25221 * Lseek flags::
25222 * Limits::
25223 @end menu
25224
25225 @node Open flags
25226 @unnumberedsubsubsec Open flags
25227 @cindex open flags, in file-i/o protocol
25228
25229 All values are given in hexadecimal representation.
25230
25231 @smallexample
25232 O_RDONLY 0x0
25233 O_WRONLY 0x1
25234 O_RDWR 0x2
25235 O_APPEND 0x8
25236 O_CREAT 0x200
25237 O_TRUNC 0x400
25238 O_EXCL 0x800
25239 @end smallexample
25240
25241 @node mode_t values
25242 @unnumberedsubsubsec mode_t values
25243 @cindex mode_t values, in file-i/o protocol
25244
25245 All values are given in octal representation.
25246
25247 @smallexample
25248 S_IFREG 0100000
25249 S_IFDIR 040000
25250 S_IRUSR 0400
25251 S_IWUSR 0200
25252 S_IXUSR 0100
25253 S_IRGRP 040
25254 S_IWGRP 020
25255 S_IXGRP 010
25256 S_IROTH 04
25257 S_IWOTH 02
25258 S_IXOTH 01
25259 @end smallexample
25260
25261 @node Errno values
25262 @unnumberedsubsubsec Errno values
25263 @cindex errno values, in file-i/o protocol
25264
25265 All values are given in decimal representation.
25266
25267 @smallexample
25268 EPERM 1
25269 ENOENT 2
25270 EINTR 4
25271 EBADF 9
25272 EACCES 13
25273 EFAULT 14
25274 EBUSY 16
25275 EEXIST 17
25276 ENODEV 19
25277 ENOTDIR 20
25278 EISDIR 21
25279 EINVAL 22
25280 ENFILE 23
25281 EMFILE 24
25282 EFBIG 27
25283 ENOSPC 28
25284 ESPIPE 29
25285 EROFS 30
25286 ENAMETOOLONG 91
25287 EUNKNOWN 9999
25288 @end smallexample
25289
25290 @code{EUNKNOWN} is used as a fallback error value if a host system returns
25291 any error value not in the list of supported error numbers.
25292
25293 @node Lseek flags
25294 @unnumberedsubsubsec Lseek flags
25295 @cindex lseek flags, in file-i/o protocol
25296
25297 @smallexample
25298 SEEK_SET 0
25299 SEEK_CUR 1
25300 SEEK_END 2
25301 @end smallexample
25302
25303 @node Limits
25304 @unnumberedsubsubsec Limits
25305 @cindex limits, in file-i/o protocol
25306
25307 All values are given in decimal representation.
25308
25309 @smallexample
25310 INT_MIN -2147483648
25311 INT_MAX 2147483647
25312 UINT_MAX 4294967295
25313 LONG_MIN -9223372036854775808
25314 LONG_MAX 9223372036854775807
25315 ULONG_MAX 18446744073709551615
25316 @end smallexample
25317
25318 @node File-I/O Examples
25319 @subsection File-I/O Examples
25320 @cindex file-i/o examples
25321
25322 Example sequence of a write call, file descriptor 3, buffer is at target
25323 address 0x1234, 6 bytes should be written:
25324
25325 @smallexample
25326 <- @code{Fwrite,3,1234,6}
25327 @emph{request memory read from target}
25328 -> @code{m1234,6}
25329 <- XXXXXX
25330 @emph{return "6 bytes written"}
25331 -> @code{F6}
25332 @end smallexample
25333
25334 Example sequence of a read call, file descriptor 3, buffer is at target
25335 address 0x1234, 6 bytes should be read:
25336
25337 @smallexample
25338 <- @code{Fread,3,1234,6}
25339 @emph{request memory write to target}
25340 -> @code{X1234,6:XXXXXX}
25341 @emph{return "6 bytes read"}
25342 -> @code{F6}
25343 @end smallexample
25344
25345 Example sequence of a read call, call fails on the host due to invalid
25346 file descriptor (@code{EBADF}):
25347
25348 @smallexample
25349 <- @code{Fread,3,1234,6}
25350 -> @code{F-1,9}
25351 @end smallexample
25352
25353 Example sequence of a read call, user presses @kbd{Ctrl-c} before syscall on
25354 host is called:
25355
25356 @smallexample
25357 <- @code{Fread,3,1234,6}
25358 -> @code{F-1,4,C}
25359 <- @code{T02}
25360 @end smallexample
25361
25362 Example sequence of a read call, user presses @kbd{Ctrl-c} after syscall on
25363 host is called:
25364
25365 @smallexample
25366 <- @code{Fread,3,1234,6}
25367 -> @code{X1234,6:XXXXXX}
25368 <- @code{T02}
25369 @end smallexample
25370
25371 @node Memory map format
25372 @section Memory map format
25373 @cindex memory map format
25374
25375 To be able to write into flash memory, @value{GDBN} needs to obtain a
25376 memory map from the target. This section describes the format of the
25377 memory map.
25378
25379 The memory map is obtained using the @samp{qXfer:memory-map:read}
25380 (@pxref{qXfer memory map read}) packet and is an XML document that
25381 lists memory regions. The top-level structure of the document is shown below:
25382
25383 @smallexample
25384 <?xml version="1.0"?>
25385 <!DOCTYPE memory-map
25386 PUBLIC "+//IDN gnu.org//DTD GDB Memory Map V1.0//EN"
25387 "http://sourceware.org/gdb/gdb-memory-map.dtd">
25388 <memory-map>
25389 region...
25390 </memory-map>
25391 @end smallexample
25392
25393 Each region can be either:
25394
25395 @itemize
25396
25397 @item
25398 A region of RAM starting at @var{addr} and extending for @var{length}
25399 bytes from there:
25400
25401 @smallexample
25402 <memory type="ram" start="@var{addr}" length="@var{length}"/>
25403 @end smallexample
25404
25405
25406 @item
25407 A region of read-only memory:
25408
25409 @smallexample
25410 <memory type="rom" start="@var{addr}" length="@var{length}"/>
25411 @end smallexample
25412
25413
25414 @item
25415 A region of flash memory, with erasure blocks @var{blocksize}
25416 bytes in length:
25417
25418 @smallexample
25419 <memory type="flash" start="@var{addr}" length="@var{length}">
25420 <property name="blocksize">@var{blocksize}</property>
25421 </memory>
25422 @end smallexample
25423
25424 @end itemize
25425
25426 Regions must not overlap. @value{GDBN} assumes that areas of memory not covered
25427 by the memory map are RAM, and uses the ordinary @samp{M} and @samp{X}
25428 packets to write to addresses in such ranges.
25429
25430 The formal DTD for memory map format is given below:
25431
25432 @smallexample
25433 <!-- ................................................... -->
25434 <!-- Memory Map XML DTD ................................ -->
25435 <!-- File: memory-map.dtd .............................. -->
25436 <!-- .................................... .............. -->
25437 <!-- memory-map.dtd -->
25438 <!-- memory-map: Root element with versioning -->
25439 <!ELEMENT memory-map (memory | property)>
25440 <!ATTLIST memory-map version CDATA #FIXED "1.0.0">
25441 <!ELEMENT memory (property)>
25442 <!-- memory: Specifies a memory region,
25443 and its type, or device. -->
25444 <!ATTLIST memory type CDATA #REQUIRED
25445 start CDATA #REQUIRED
25446 length CDATA #REQUIRED
25447 device CDATA #IMPLIED>
25448 <!-- property: Generic attribute tag -->
25449 <!ELEMENT property (#PCDATA | property)*>
25450 <!ATTLIST property name CDATA #REQUIRED>
25451 @end smallexample
25452
25453 @include agentexpr.texi
25454
25455 @include gpl.texi
25456
25457 @raisesections
25458 @include fdl.texi
25459 @lowersections
25460
25461 @node Index
25462 @unnumbered Index
25463
25464 @printindex cp
25465
25466 @tex
25467 % I think something like @colophon should be in texinfo. In the
25468 % meantime:
25469 \long\def\colophon{\hbox to0pt{}\vfill
25470 \centerline{The body of this manual is set in}
25471 \centerline{\fontname\tenrm,}
25472 \centerline{with headings in {\bf\fontname\tenbf}}
25473 \centerline{and examples in {\tt\fontname\tentt}.}
25474 \centerline{{\it\fontname\tenit\/},}
25475 \centerline{{\bf\fontname\tenbf}, and}
25476 \centerline{{\sl\fontname\tensl\/}}
25477 \centerline{are used for emphasis.}\vfill}
25478 \page\colophon
25479 % Blame: doc@cygnus.com, 1991.
25480 @end tex
25481
25482 @bye
This page took 0.948152 seconds and 5 git commands to generate.